The CP-6 system provides comprehensive error reporting, which is available to report monitor service errors, shared processor errors, or errors in a user program. The error
reporting faci lity is not I imited to error messages; it can be used to output messages that conform to the requirements explained here.
In the case of monitor service errors, the monitor service passes an error code to the user, typically in the ALTRET frame of the TCB. The user cal Is the M$ERRMSG service specifying as parameters the error code stored in the ALTRET frame and a user buffer.
The following discussion presents the ful I information needed by users who are reporting errors on monitor service calls. For users who intend to define their own error codes and error message fi Ie, additional information is given under later headings.
ERROR CODE
The 1-word code specified as a parameter for M$ERRMSG must conform to this format:
CE74-00 M$ERRMSG - Error Message Reporting 4-25
Field
Functional Code Group
Module 10
Monitor Flag Error Number Severity Level
Content
VALUE-BIT(12), that is, 2 characters composed of the low-order 6 bits of the ASCII code
VALUE-BIT(6), that is, 1 character composed of the low-order 6 bits of the ASCII code
VALUE-BIT(l) VALUE-OEC(0-16383) VALUE-DEC (0-7)
User's reporting monitor service errors do not alter the error code. However a
processor or user can supply an error message fi Ie and manipulate the severity level to provide increasingly informative messages in response to requests from a time-sharing user. The processor or user displays one of several messages associated with the same error number but with an increasingly higher severity code (0-7) at each cal I to M$ERRMSG. (The HELP foci I ity is provided through use of a message file with multiple messages associated with each error condition.)
ERROR DISPLAY
The format of the error display resulting from the M$ERRMSG service is shown below. The text is always displayed (if found); other fields are optional. If the text is not found, the error code is displayed. The full form of the display is as follows:
•••• fff-Mnnnn-s text where
•••• indicates the seriousness of the error
fff-Mnnnn-s
by 0 to 4 asterisks. Asterisks may be omitted;
however, by convention the asterisks are used as fol lows:
• - information only
•• warning message
••• serious error
•••• fatal error
The FLAGLEV parameter determines the number of asterisks output by MSERRMSG.
represents the error code passed
to the M$ERRMSG service as explained above. fff represents the functional code group (FCG) and Module ID (MID) codes. The letter M precedes the error number (nnnnn) for monitor service errors.
The severity code(s) follows the error number.
The INCLCOOE parameter determines whether this code is part of the message output by MSERRMSG.
text is the message obtained from the message
4-26
fi Ie identified by the FILENAME parameter. The text may include:
o Text characters.
o Substitution names represented by XFN, XAC,
MSERRMSG - Error Message Reporting CE74-00
M$ERRMSG
~DC, ~U1, etc.
o Conditional fields framed by ~ symbols and containing the substitution character strings.
The M$ERRMSG service obtains an error message based on the error code supplied as a parameter, and stores the message in the user buffer. M$ERRMSG al lows phrase and
message substitution, al lows override of vertical format control, and al lows suppression of portions of the error display. The output of the M$ERRMSG service is returned in RESULTS area.
The M$ERRMSG service sends the error display through one or two DCBs specified for output. Correspondence checking is performed to determine if the DCB assignments are identical. Errors encountered in writing through the OUTDCBs are indicated in the RESULTS area. If no output DCBs are specified, the M$ERRMSG service simply stores the message in the buffer and returns.
The form of the call for this service is as fol lows:
CALL M$ERRMSG (FPT_ERRMSG) [ALTRET(label)];
The required parameters for the service are CODE and BUF. AI I other parameters are optional.
~LTCODE
=
VARIABLE specifies the 1-word area in memory containing the error code identifying the alternate message to be read from the file. It is used to form the key to read the fi Ie if no message can be found for CODE. To generate the structure for the error code, use the VLP_ERRCODE macro described in this section; or, for monitor service errors, the B$ALT m~cro discussed in Section 6. The default is NIL.BUF = VARIABLE specifies the buffer used when reading the fi Ie. BUF must have a minimum size of 120 bytes, the maximum size of any record in the fi Ie. Because some error messages may consist of multiple records in the fi Ie, a 120-byte buffer wi I I not always be large enough to hold the whole message. The caller may alleviate this condition by specifying a larger buffer.
Records from the fi Ie are read into the buffer at 120-byte offsets until the buffer is ful I or the message is complete. Status is returned to the caller indicating how many records are in the buffer, and whether or not the message is complete. If the buffer is not large enough to hold all of the records of the message, then the contents of the buffer wil I vary depending on whether the caller suppl ied OUTDCBs through which to output the messages. Given a buffer with enough space for n records, if no OUTOCBs have been specified, the buffer will contain the first n records of the message. If OUTOCBs have been specified, then the buffer wil I contain the first n-1 records in the first n-1 slots, and the last record of the message in the nth slot.
Example:
Suppose the user passes a 360-byte buffer and tries to read varying size error messages.
1. 2-record error message
1
121 241
Record 1
Record 2 120 240 360
On a normal return, the RESULTS area indicates that the buffer contains the complete message and it is two records.
2. 4-record error message - no OUTOCBs specified.
CE74-00 MSERRMSG - Error Message Reporting 4-27
1 obtain variable information which is substituted into the error message for special strings ~FN, ~C, ~TA, ~UF, ~DC and ~SN. If an error message contains these special
INCLCOOE - 'VESINOI indicates whether or not the error code should be output before the error message. The default is VES.
L6_ALTCOOE - IVESINOI specifies. if VESt that the code specified by the ALTCODE parameter is in unpacked LCP-6 error code format. Default = NO.
L6_CODE - IVESINOI specifies. if VESt that the code specified by the CODE parameter is in unpacked LCP-6 error code format. Default
=
NO.LANG = VALUE-CHAR(1) specifies the character that is to be assumed to be the native language when selecting the error message fi Ie.
MY_LANG
=
IVESINOI specifies. if VESt that the default native language key is that of the user making the ~$ERRMSG request. NO specifies that the character specified via the LANG option is to be used in selecting the error message fi Ie. The default is VES.NREAD
=
IVESINOI specifies. if VESt that the buffer contents should be output as passed, without reading the error message fi Ie but with substitution. The default is NO.OUTDCB1
=
DCBNAME specifies the first DCB through which to output the error message.The default is NIL.
OUTDCB2 - DCBNAME specifies the second DCB through which to output the error message.
The default is NIL.
POINTER = VALUE-DEC(0-LENGTHC(BUF» specifies. if non-zero, that a pointer ( ) should be output on a I ine before the error message and in which character position it should be placed. If POINTER is zero, or greater than LENGTHC(BUF). no pointer is output. If the requested message cannot be found. the pointer is output and ~$ERR~SG wi I I ALTRETURN after printing the pointer. Note that this option wi I I not work with NREAD - VES. The default is 0.
RESULTS = VARIABLE specifies an area in the user's data where any status information about a cal I to ~$ERR~SG is returned to the caller. The information returned consists of bits indicating unusual conditions encountered in the processing of the CALL, and a field containing the count of records from the message fi Ie returned in the user's buffer. The VLR_ERR~SG macro described later in this section can be invoked to generate this area. The default is NIL.
SOURCE = I PASS I TRAP IALTRETI specifies where ~$ERR~SG should look for the error code and DCB to report on. PASS. the default, indicates that the error code will be passed in CODE. TRAP indicates that ~$ER~G should look in B$EXCFR.ERR for the error code.
ALTRET tel Is ~ERR~SG to look in B$ALT.ERR for the error code and DCB.
The fully qualified name of this field is FPT_ERR~SG.V.SOURCE'. Acceptable EQUs are SOURCE_PASS'. SOURCE_TRAP'. and SOURCE_ALTRET'.
SUBAC
=
IVESINOI specifies. if VESt that %AC in the error message is to be considered a candidate for substitution. %AC (account) is obtained from the data control block specified by the DCB parameter. If SUBAC=NO. the ~~C is blanked out or the conditional phrase that contains ~~C is eliminated. The default is VES.SUBDC = IVESINOI specifies. if VES, that ~~C in the error message is to be considered a candidate for substitution. ~DC (DCB name) is obtained from the DCB parameter. If SUBDe-NO, the ~C is blanked out or the conditional phrase that contains ~C is el iminated. The default is VES.
SUBFILE
=
IVESINOI specifies, if VES, to use the default system error message fi Ie if the file passed by the user does not contain a message for the code passed in this cal I.The default is VES.
SUBFN - IVESINOI specifies, if VES, that ~FN in the error message is to be considered a candidate for substitution. ~FN (file name) is obtained from the data control block specified by the DCB parameter. If SUBFN-NO, the ~FN is blanked out or the conditional phrase that contains ~FN is eliminated. The default is VES.
CE74-00 ~$ER~G - Error ~essage Reporting 4-29
SUB LANG - IYESINOI. Specifies, if YES, that a message wi I I be in the default language if the user's native language is not avai lable. The default is YES.
SUBMESS - iYESjNOI specifies, if YES. to use a substitute message. (i .e., one with less severity) or the default message, if the error message fi Ie contains no message
corresponding to the CODE specified. The default is YES. If NO substitute message is avai lable, the text of the error code is used (See INCLCOOE).
SUBSN
=
IYESINOI specifies, if YES, that ~SN in the error message is to be considered a candidate for substitution. ~SN (serial number or set name) is obtained from the DCB parameter. If SUBSN=NO, ~SN is blanked out or the conditional phrase that contains ~SNis el iminated. The default is YES.
TYC
=
JYESINOI specifies, if YES, the TYC (type of completion) information from the specified DCB should be output after the error message. TYC is meaningful only if DCB was specified. The default is NO.VFC = VALUE-CHAR(l) may be specified when writing the error message. This code is used when writing the message through either or both OUTDCBs. The default is zero meaning
that the user's default VFC wi I I be used.