ERROR PROCESSING PACKAGE This document describes the usage of the error processing package available in the RSX-11M system macro and object libraries. These macros simplify error checking, provide a valuable aid in debugging and help give some standardization to error reporting. The package consists of two components: a set of macros to check for errors and call the error processing routines when an error is detected. The macros are divided in four classes - three error type specific and one general. For each class, two macro calls are provided. The ???WRN form reports the error and returns. The ???ERR form exits the task after the error messages are printed. The eight macros are listed below: 1. I/O Status Errors 1. QIOWRN 2. QIOERR 2. FCS Status Errors 1. FCSWRN 2. FCSERR 3. Directive Status Errors 1. DIRWRN 2. DIRERR 4. Program Errors 1. PRGWRN 2. PRGERR The user need only define the macro name in an .MCALL statement before using. All associated object modules referenced by the macros are contained in SYSLIB, therefore no additional task-build commands are needed. The following pages detail the macro arguments and give examples on using the macros and their results. ERROR PROCESSING PACKAGE PAGE 2 General Notes The following notes apply the error processing package: 1. The package is most conviently used by placing the macros in RSXMAC.SML and the error processing routines in SYSLIB.OLB. 2. The logical unit numbers needed by the package are obtained using the special Task Builder symbols .MOLUN and .TRLUN. No luns need to be allocated for use by the package. 3. The error messages are retrieved from the file LB:[1,2]QIOSYM.MSG. The file is accessed directly and no FCS I/O is performed. 4. The package was orginally designed to aid debugging of programs. After debugging is complete and the additional size of the error processing routines is undesirable, the error routines can be eliminated by defining conditional assembly symbols. The macros will generate trap instructions in place of the error call. Each class can be selectively disabled using the following symbols: Q$$MSG for QIO??? macors, D$$MSG for DIR??? macros, and F$$MSG for FCS??? macros. Program error message cannot be turned off using this mechanism. 5. The error macros allow selective specification of certain errors to be handled by the program. For example, a program searching for a file would expect the FCS "No Such File" error. Such list are called conditional list and consist of sets of error, address pairs. Each pair is enclosed in angle brackets and the entire list must also be enclosed in angle brackets (even if there is only one entry). 6. Arguments are used in MOV and CMP instructions. For example, if TSTLUN was a symbol defining the lun number and IOSTAT was the label for the I/O status block, the QIOERR macro would be called with "#TSTLUN" as the lun argument and "IOSTAT" as the I/O status argument. The exception are error codes in conditional lists. The "#" sign is supplied here. In order to effective use the package, besides reading this document, also read the macro definitions. ERROR PROCESSING PACKAGE PAGE 3 I/O Status Errors -- QIOWRN MACRO FORM: QIOWRN IOS,LUN [,CNDLST,CONTIN] WHERE IOS = ADDRESS OF I/O STATUS WORD LUN = I/O LOGICAL UNIT NUMBER CNDLST = OPTIONAL EXCEPTIONS WITH BRANCH LOCATIONS CONTIN = OPTIONAL CONTINUATION BRANCH LOCATION FUNCTION: This macro is used to test for errors occurring from a QIO operation. If an exception is listed and it occurs, no error message is reported and control is transferred to the associated branch location. Multiple exceptions may be listed. If an error has occurred and is not listed in the exceptions list, an error message is displayed and control is transferred to the continuation location. The error message is displayed on the TI: device. If no errors are found, control is transferred to the location following the macro. EXAMPLE: .MCALL QIOWRN QIOWRN IOSTAT,LUN,<,>,ERRHER In this example, two exceptions are listed. Note that the extra set of angle brackets is required because the exceptions list is passed on to another macro for processing. If the first exception listed, IE.IES, occurs, control is passed to location GOHERE. If the second exception, IE.PES, occurs, control is transferred to location NOHERE. If any other errors are found, a message of the following format is displayed on the TI: device. Variable portions of the message are displayed in parentheses. (tsknam) -- QIO ERROR (nn) (error message from QIOSYM) LUN: (lun) DEV: (dev) AT PC (nnnnnn) Control is then transferred to location ERRHER. If no errors are detected, the statement following the macro is executed. ERROR PROCESSING PACKAGE PAGE 4 I/O Status Errors -- QIOERR MACRO FORM: QIOERR IOS,LUN [,CNDLST] WHERE IOS = ADDRESS OF I/O STATUS WORD LUN = I/O LOGICAL UNIT NUMBER CNDLST = OPTIONAL EXCEPTIONS WITH BRANCH LOCATIONS FUNCTION: This macro is used to test for errors occurring from a QIO operation. If an exception is listed and it occurs, no error message is reported and control is transferred to the associated branch location. Multiple exceptions may be listed. If an error has occurred and is not listed in the exceptions list, an error message is displayed and the task is exited. The error message is displayed on the TI: device. If no errors are found, control is transferred to the location following the macro. EXAMPLE: .MCALL QIOERR QIOERR IOSTAT,LUN,<,> In this example, two exceptions are listed. Note that the extra set of angle brackets is required because the exceptions list is passed on to another macro for processing. If the first exception listed, IE.IES, occurs, control is passed to location GOHERE. If the second exception, IE.PES, occurs, control is transferred to location NOHERE. If any other errors are found, a message of the following format is displayed on the TI: device. Variable portions of the message are displayed in parentheses. (tsknam) -- EXITING DUE TO QIO ERROR (nn) (error message from QIOSYM) LUN: (lun) DEV: (dev) AT PC (nnnnnn) The task is then exited by means of an EXIT$S directive. If no errors are detected, the statement following the macro is executed. ERROR PROCESSING PACKAGE PAGE 5 FCS Status Errors -- FCSWRN MACRO FORM: FCSWRN [CNDLST,CONTIN] WHERE CNDLST = OPTIONAL EXCEPTIONS WITH BRANCH LOCATIONS CONTIN = OPTIONAL CONTINUATION BRANCH LOCATION FUNCTION: This macro is used to test for errors occurring from a FCS operation. If an exception is listed and it occurs, no error message is reported and control is transferred to the associated branch location. Multiple exceptions may be listed. If an error has occurred and is not listed in the exceptions list, an error message is displayed and control is transferred to the continuation location. The error message is displayed on the TI: device. If no errors are found, control is transferred to the location following the macro. EXAMPLE: .MCALL FCSWRN FCSWRN <,>,ERRHER In this example, two exceptions are listed. Note that the extra set of angle brackets is required because the exceptions list is passed on to another macro for processing. If the first exception listed, IE.FOP, occurs, control is passed to location GOHERE. If the second exception, IE.WAC, occurs, control is transferred to location NOHERE. If any other errors are found, a message of the following format is displayed on the TI: device. Variable portions of the message are displayed in parentheses. (tsknam) -- FCS ERROR (nn) (FCS error message from QIOSYM) LUN: (lun) DEV: (dev) FILE: (filnam) AT PC (nnnnnn) Control is then transferred to location ERRHER. If no errors are detected, the statement following the macro is executed. ERROR PROCESSING PACKAGE PAGE 6 FCS Status Errors -- FCSERR MACRO FORM: FCSERR [CNDLST] WHERE CNDLST = OPTIONAL EXCEPTIONS WITH BRANCH LOCATIONS CONTIN = OPTIONAL CONTINUATION BRANCH LOCATION FUNCTION: This macro is used to test for errors occurring from a FCS operation. If an exception is listed and it occurs, no error message is reported and control is transferred to the associated branch location. Multiple exceptions may be listed. If an error has occurred and is not listed in the exceptions list, an error message is displayed and the task is exited via an EXIT$S directive. The error message is displayed on the TI: device. If no errors are found, control is transferred to the location following the macro. EXAMPLE: .MCALL FCSERR FCSERR <,> In this example, two exceptions are listed. Note that the extra set of angle brackets is required because the exceptions list is passed on to another macro for processing. If the first exception listed, IE.FOP, occurs, control is passed to location GOHERE. If the second exception, IE.WAC, occurs, control is transferred to location NOHERE. If any other errors are found, a message of the following format is displayed on the TI: device. Variable portions of the message are displayed in parentheses. (tsknam) -- EXITING DUE TO FCS ERROR (nn) (FCS error message from QIOSYM) LUN: (lun) DEV: (dev) FILE: (filnam) AT PC (nnnnnn) The task is then terminated. If no errors are detected, the statement following the macro is executed. ERROR PROCESSING PACKAGE PAGE 7 DIRECTIVE Status Errors -- DIRWRN MACRO FORM: DIRWRN [CNDLST,CONTIN] WHERE CNDLST = OPTIONAL EXCEPTIONS WITH BRANCH LOCATIONS CONTIN = OPTIONAL CONTINUATION BRANCH LOCATION FUNCTION: This macro is used to test for errors occurring from a DIR operation. If an exception is listed and it occurs, no error message is reported and control is transferred to the associated branch location. Multiple exceptions may be listed. If an error has occurred and is not listed in the exceptions list, an error message is displayed and control is transferred to the continuation location. The error message is displayed on the TI: device. If no errors are found, control is transferred to the location following the macro. EXAMPLE: .MCALL DIRWRN DIRWRN <,>,ERRHER In this example, two exceptions are listed. Note that the extra set of angle brackets is required because the exceptions list is passed on to another macro for processing. If the first exception listed, IE.HWR, occurs, control is passed to location GOHERE. If the second exception, IE.PRI, occurs, control is transferred to location NOHERE. If any other errors are found, a message of the following format is displayed on the TI: device. Variable portions of the message are displayed in parentheses. (tsknam) -- DIR ERROR (nn) (directive error message from QIOSYM) AT PC (nnnnnn) Control is then transferred to location ERRHER. If no errors are detected, the statement following the macro is executed. ERROR PROCESSING PACKAGE PAGE 8 DIRECTIVE Status Errors -- DIRERR MACRO FORM: DIRERR [CNDLST] WHERE CNDLST = OPTIONAL EXCEPTIONS WITH BRANCH LOCATIONS FUNCTION: This macro is used to test for errors occurring from a DIR operation. If an exception is listed and it occurs, no error message is reported and control is transferred to the associated branch location. Multiple exceptions may be listed. If an error has occurred and is not listed in the exceptions list, an error message is displayed and the task is terminated via an EXIT$S directive. The error message is displayed on the TI: device. If no errors are found, control is transferred to the location following the macro. EXAMPLE: .MCALL DIRERR DIRERR <,> In this example, two exceptions are listed. Note that the extra set of angle brackets is required because the exceptions list is passed on to another macro for processing. If the first exception listed, IE.HWR, occurs, control is passed to location GOHERE. If the second exception, IE.PRI, occurs, control is transferred to location NOHERE. If any other errors are found, a message of the following format is displayed on the TI: device. Variable portions of the message are displayed in parentheses. (tsknam) -- DIR ERROR (nn) (directive error message from QIOSYM) AT PC (nnnnnn) The task is then exited. If no errors are detected, the statement following the macro is executed. ERROR PROCESSING PACKAGE PAGE 9 Program Errors -- PRGWRN MACRO FORM: PRGWRN MSGADR [,CONTIN] WHERE MSGADR = ADDRESS OF ERROR MESSAGE TERMINATED BY A ZERO (ASCIZ) CONTIN = OPTIONAL CONTINUATION BRANCH LOCATION FUNCTION: This macro is used to output an error message and continue task execution. The only restriction on the error message is that the maximum number of characters is 230. The error message is displayed on the TI: device. After the error message has been displayed, control is transferred to the continuation location. EXAMPLE: .MCALL PRGWRN PRGWRN INVALD,20$ In this example, the message INVALD is output. Then control is transferred to location 20$. The error message is displayed in the following format on the TI: device. Variable portions of the message are shown in parentheses. (tsknam) -- PROGRAM ERROR (error message from task) ERROR PROCESSING PACKAGE PAGE 10 Progra m Errors -- PRGERR MACRO FORM: PRGERR MSGADR WHERE MSGADR = ADDRESS OF ERROR MESSAGE TERMINATED BY A ZERO (ASCIZ) FUNCTION: This macro is used to output an error message and stop task execution. The only restriction on the error message is that the maximum number of characters is 230. The error message is displayed on the TI: device. After the error message has been displayed, the task is terminated via an EXIT$S directive. EXAMPLE: .MCALL PRGERR PRGERR INVALD In this example, the message INVALD is output after which the task is terminated. The error message is displayed in the following format on the TI: device. Variable portions of the message are shown in parentheses. (tsknam) -- PROGRAM ERROR (error message from task)