ZCPR33 PROGRAMMING NOTES ======================== Note Number: 001 Author: Jay Sage Date: June 6, 1987 The Command Status Flag and the Library Routine QERROR Background ---------- The command status flag is a control flag stored at offset 3 (i.e., the fourth byte) in the message buffer. In ZCPR30, only two bits of this flag are defined and used. Bit 0, the least significant bit, is the shell bit. When the command processor loads a program as a shell, it sets this bit so that the program knows that it has been invoked as a shell by the command processor and not by the user. When the user invokes the shell, it should simply install itself on the shell stack. When the command processor invokes it, it should perform its shell function. Bit 1 is the error bit. When the command processor runs the error handling command line, it sets this bit, so that the program knows that it has been invoked by the command processor to process an error and not by the user. When the user invokes the error handler, it should install itself in the error handling command line. When the command processor invokes it, it should perform its error handling function. Changes in ZCPR33 ----------------- Bits 0 and 1 retain the identical functions in ZCPR33. In addition, two more bits in the command status flag are defined and used. Bit 2 is the extended command processor bit. When the command processor loads a program as the extended command processor, it sets this bit so that the program knows it was invoked by the command processor and not by the user. The program may not care, of course, but if it does, it can test this bit. When control is returned to the command processor with both the ECP bit and the error bit set, the command processor interprets this to mean that an error has occurred and that the error handling command line should be run. This is the mechanism that allows extended command processors and error handlers to function together in ZCPR33. It also provides a vehicle by which any program can chain to the error handler. This will be covered in detail in another programming note. Bit 3 is the external program flag bit. When program code outside the command processor (either resident code in the FCP or RCP or a transient program) wants to make use of command processor services, it sets this bit so that the command processor code can respond in an appropriate way. There are two kinds of service that a program might request. One is error handling. As noted above, if a program returns to the command processor with the ECP and error bits set, then error handling will be invoked. If the program wishes to set an error code into the command error flag at offset 0 in the message buffer, then the external program bit must be set. Otherwise, an internal command processor error code will be loaded into that flag. The second command processor service that a program might use is the entry point provided to the REPARSE or SCAN routines for parsing file specifications. When the command processor uses these routines for its own purposes, entry of incorrect passwords causes an immediate vector to the error handling command. This would not, in general, be acceptable during the operation of a transient program. If the external program bit is set, the parsing code, instead of vectoring to the error handler, will simply set the file-specification-error flag in the file control block that it builds (this is covered in another programming application note) and return to the calling program. When control returns to the command processor for processing of the next command in a multiple command line, the external program flag is not reset. It is only reset when the command line becomes empty. Thus the bit should never be left set on return to the command processor unless error handling is being invoked. Moreover, error handlers must reset the bit before they terminate or subsequent parsing operations by the command processor may be performed incorrectly. The version of Z33ERROR (0.7) included with the release version of ZCPR33 does not do this, and non-ZCPR33 error handlers obviously do not. Thus, the coding in ZCPR33 is less than ideal (go ahead, call it a bug), and in the next release the external program bit will be cleared automatically. Only one extra line of code is required [RES 3,(HL) just before the NEXTCMD1 label]. Mistake in the QERROR Routine in Z3LIB -------------------------------------- The QERROR routine in the Z3LIB relocatable library is supposed to return zero if the error bit is set and nonzero otherwise. However, the routine makes the assumption that when the error bit is set it will be the only bit that is set. In ZCPR30 this was generally the case, but in ZCPR33 it will often not be the case. There are two solutions to this problem. The library Z33LIB of routines that support ZCPR33 extended functions contains a replacement version of QERROR that has been corrected. Alternative, the GETCST routine in Z3LIB can be used to get the value of the command status flag, and the bits can be tested directly in the user's code.