home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / zcpr33 / z3-33 / z33pnote.0z1 / Z33PNOTE.001
Text File  |  1987-06-10  |  5KB  |  101 lines
  1.                           ZCPR33 PROGRAMMING NOTES
  2.                           ========================
  3.  
  4. Note Number:    001
  5. Author:        Jay Sage
  6. Date:        June 6, 1987
  7.  
  8.  
  9.            The Command Status Flag and the Library Routine QERROR
  10.  
  11.  
  12. Background
  13. ----------
  14.  
  15.      The command status flag is a control flag stored at offset 3 (i.e., the
  16. fourth byte) in the message buffer.  In ZCPR30, only two bits of this flag
  17. are defined and used.
  18.  
  19.      Bit 0, the least significant bit, is the shell bit.  When the command
  20. processor loads a program as a shell, it sets this bit so that the program
  21. knows that it has been invoked as a shell by the command processor and not
  22. by the user.  When the user invokes the shell, it should simply install
  23. itself on the shell stack.  When the command processor invokes it, it should
  24. perform its shell function.
  25.  
  26.      Bit 1 is the error bit.  When the command processor runs the error
  27. handling command line, it sets this bit, so that the program knows that it
  28. has been invoked by the command processor to process an error and not by the
  29. user.  When the user invokes the error handler, it should install itself in
  30. the error handling command line.  When the command processor invokes it, it
  31. should perform its error handling function.
  32.  
  33.  
  34. Changes in ZCPR33
  35. -----------------
  36.  
  37.      Bits 0 and 1 retain the identical functions in ZCPR33.  In addition,
  38. two more bits in the command status flag are defined and used.
  39.  
  40.      Bit 2 is the extended command processor bit.  When the command
  41. processor loads a program as the extended command processor, it sets this
  42. bit so that the program knows it was invoked by the command processor and
  43. not by the user.  The program may not care, of course, but if it does, it
  44. can test this bit.  When control is returned to the command processor with
  45. both the ECP bit and the error bit set, the command processor interprets
  46. this to mean that an error has occurred and that the error handling command
  47. line should be run.  This is the mechanism that allows extended command
  48. processors and error handlers to function together in ZCPR33.  It also
  49. provides a vehicle by which any program can chain to the error handler. 
  50. This will be covered in detail in another programming note.
  51.  
  52.      Bit 3 is the external program flag bit.  When program code outside the
  53. command processor (either resident code in the FCP or RCP or a transient
  54. program) wants to make use of command processor services, it sets this bit
  55. so that the command processor code can respond in an appropriate way.  There
  56. are two kinds of service that a program might request.  One is error
  57. handling.  As noted above, if a program returns to the command processor
  58. with the ECP and error bits set, then error handling will be invoked.  If
  59. the program wishes to set an error code into the command error flag at
  60. offset 0 in the message buffer, then the external program bit must be set. 
  61. Otherwise, an internal command processor error code will be loaded into that
  62. flag.
  63.  
  64.      The second command processor service that a program might use is the
  65. entry point provided to the REPARSE or SCAN routines for parsing file
  66. specifications.  When the command processor uses these routines for its own
  67. purposes, entry of incorrect passwords causes an immediate vector to the
  68. error handling command.  This would not, in general, be acceptable during
  69. the operation of a transient program.  If the external program bit is set,
  70. the parsing code, instead of vectoring to the error handler, will simply set
  71. the file-specification-error flag in the file control block that it builds
  72. (this is covered in another programming application note) and return to the
  73. calling program.
  74.  
  75.      When control returns to the command processor for processing of the
  76. next command in a multiple command line, the external program flag is not
  77. reset.  It is only reset when the command line becomes empty.  Thus the bit
  78. should never be left set on return to the command processor unless error
  79. handling is being invoked.  Moreover, error handlers must reset the bit
  80. before they terminate or subsequent parsing operations by the command
  81. processor may be performed incorrectly.  The version of Z33ERROR (0.7)
  82. included with the release version of ZCPR33 does not do this, and non-ZCPR33
  83. error handlers obviously do not.  Thus, the coding in ZCPR33 is less than
  84. ideal (go ahead, call it a bug), and in the next release the external
  85. program bit will be cleared automatically.  Only one extra line of code is
  86. required [RES 3,(HL) just before the NEXTCMD1 label].
  87.  
  88.  
  89. Mistake in the QERROR Routine in Z3LIB
  90. --------------------------------------
  91.  
  92.      The QERROR routine in the Z3LIB relocatable library is supposed to
  93. return zero if the error bit is set and nonzero otherwise.  However, the
  94. routine makes the assumption that when the error bit is set it will be the
  95. only bit that is set.  In ZCPR30 this was generally the case, but in ZCPR33
  96. it will often not be the case.  There are two solutions to this problem. 
  97. The library Z33LIB of routines that support ZCPR33 extended functions
  98. contains a replacement version of QERROR that has been corrected. 
  99. Alternative, the GETCST routine in Z3LIB can be used to get the value of the
  100. command status flag, and the bits can be tested directly in the user's code.
  101.