The WRITE LOG statement retrieves a predefined message from the message area of the data dictionary and optionally writes the message to a specified location in program variable storage. Retrieved messages are sent to the destination specified in the message definition; typical destinations are the operator's console and the system log file. If the operator's console has been defined as the message destination, the WRITE LOG statement can request a reply. When a reply is requested, control is not returned to the issuing task until the reply is received.
Message ID and Severity Code
The message ID specified in the WRITE LOG statement is a 7-digit number. The first six (most significant) digits make up the actual message ID used to retrieve the message from the data dictionary; the seventh digit is a severity code. This severity code is predefined in the dictionary and is retrieved along with the message text to indicate the action to be taken after the message is written to the log. The following table shows severity codes and corresponding system actions.
|
Severity code |
Corresponding action by the system |
|---|---|
|
0 |
Return control to the issuing program and continue processing. |
|
1 |
Snap all task resources and return control to the issuing program. |
|
2 |
Snap all system areas and return control to the issuing program. |
|
3 |
Snap all task resources and abend the task with a task abend code of D002. |
|
4 |
Snap all system areas and abend the task with a task abend code of D002. |
|
5 |
Terminate the task with a task abend code of D002. |
|
6 |
Undefined. |
|
7 |
Undefined. |
|
8 |
Snap all system areas and abend the system with a system abend code of 3996. |
|
9 |
Terminate the system with a system abend code of 3996. |
Message IDs That Are Not in the Dictionary
If a WRITE LOG statement specifies a message ID that is not in the dictionary, the system will use a prototype message but will perform the action associated with the severity code specified in the WRITE LOG request.
Messages Containing Symbolic Parameters
Messages stored in the data dictionary can contain symbolic Parameters. Symbolic Parameters, identified by an ampersand (&). followed by a 2-digit numeric identifier, can appear in any order within the message. The WRITE LOG statement can specify replacement values for one or more symbolic Parameters; however, the position of replacement values within the WRITE LOG request must correspond exactly with the 2-digit numeric identifier in the message text. For Example, the first value specified corresponds to &01., the second to &02., and so forth.
►►─── WRITE LOG MESSAGE ID (message-id) ──────────────────────────────────────► ►─┬─────────────────────────────────────────────────────────────────┬────────► │ ┌─────────────────────────────────────────────────────┐ │ └─ PARMS ─▼─ FROM (parm-location) ─┬─ TO (end-parm-location) ─┬─┴─┘ └─ LENGTH (parm-length) ───┘ ►─┬───────────────────────────────────────────────────────────────────┬──────► └─ REPLY INTO (reply-location) ─┬─ TO (end-reply-location) ───────┬─┘ └─ MAX LENGTH (reply-max-length) ─┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─ TEXT INTO (text-return-location) ─┬─ TO (end-text-return-location) ─┬─── └─ MAX LENGTH (text-max-length) ──┘ ─►──────────────────────────────────────────────────────┬─ ; ─────────────────►◄ ───┬──────────────────────────────┬──┬─────────────┬──┘ └─ MESSAGE_PREFIX ─┬─ YES ◄ ─┬─┘ └─ TEXT ONLY ─┘ └─ NO ────┘
Specifies the 7-digit message ID. The first six digits specify the ID of the message; the seventh digit specifies the message's severity code. Message-id is either the symbolic name of a user-defined FIXED BINARY(31) field that contains the message ID, or the ID itself expressed as a numeric constant. Message IDs 000001 through 900000 are reserved for use by the system; the WRITE LOG statement can specify any number in the range 900001 through 999999.
Note: The message length must be seven digits. The system will always interpret the last digit as the severity level. If you request message 987659 and do not code a severity level of zero (that is, 9876590) you are actually requesting that message 098765 be written to the log and that the system should be terminated with a 3996 abend code.
Note: When messages are added to the data dictionary for use with the WRITE LOG statement, they are assigned an 8-character identification number; the first two characters are DC. A request for message 987654 retrieves DC987654.
Supplies replacement values for one or more symbolic parameters stored with the message text. Parm-location is the symbolic name of a user-defined field that contains the program variable-storage entry of the replacement parameter.
Indicates the end of the program variable-storage entry that contains the replacement parameter and is specified following the last data item in parm-location. End-parm-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the replacement parameter.
Defines the length, in bytes, of the replacement parameter. Parm-location is either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
The following WRITE LOG statement replaces a symbolic parameter with the contents of the FLT_NO field:
WRITE LOG MESSAGE ID (9000160) PARMS FROM (FLT_NO) TO (END_FLT_NO);
Each replacement parameter must begin with a 1-byte field from which the system obtains the length (in hexadecimal) of the parameter. This 1-byte field cannot be displayed.
Consider the following Example:
03 FLT_NO,
05 FILLER CHAR (1),
05 FLT_PARM CHAR (6) INIT ('AAA201'),
05 END_FLT_NO CHAR (1);
Specifies the program variable-storage entry of the area reserved for a reply to the message issued by the WRITE LOG request. Reply-location is the symbolic name of a user-defined field. The length of the reply area is determined by one of the following specifications:
Indicates the end of the program variable-storage entry reserved for the reply and is specified following the last field in reply-location. End-reply-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the reply.
Defines the maximum length, in bytes, of the area reserved for the reply. Reply-max-length is either the symbolic name of a user-defined field that contains the length, or the length itself expressed as a numeric constant.
Specifies that the contents of the named message, along with any replacement parameters, are to be written to the issuing program. Text-return-location is the symbolic name of a user-defined 1- to 132-character alphanumeric field that contains the program variable-storage entry to which the message text is to be returned. The length of the returned text is determined by one of the following specifications:
Indicates the end of the program variable-storage entry reserved for the text and is specified following the last data item in text-return-location. End-text-return-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the returned text.
Defines the maximum length, in bytes, of the program variable-storage entry reserved for the returned message text. Text-max-length is either the symbolic name of a user-defined field that contains the text length, or the length itself expressed as a numeric constant.
Specifies the format of the message prefix.
Indicates that the message text is preceded by:
IDMS DCnnnnnnn Vssssss REPLYnn
DCnnnnnnn is the message number, Vssssss is the system number, and REPLYnn is the message's system-supplied reply number (present only if the REPLY parameter is used). YES is the default.
Indicates that the message text is preceded by:
DCnnnnnnn
DCnnnnnnn is the message number.
Indicates that the message text is output with no prefix.
The following figure illustrates a WRITE LOG statement that supplies three replacement parameters.
Task A issues a WRITE LOG request for message 900121, specifying values to replace symbolic parameters &01., &02., and &03. stored with the message text. The system sends the message to its destination, which has been defined as the logical terminal associated with the issuing task.
Upon completion of the WRITE LOG function, the ERROR_STATUS field of the IDMS DC communications block indicates the outcome of the operation:
The request has been serviced successfully.
No storage or resource control element (RCE) can be allocated for the specified reply area.
The maximum number of outstanding replies has been exceeded; a maximum of 98 messages can be awaiting reply at a given time.
The parameter list is invalid.
|
Copyright © 2014 CA.
All rights reserved.
|
|