The #WTL (write to log) statement performs the following functions:
Messages are stored in the message area of the dictionary. Each message in the dictionary consists of the message text and the message destination. Typical destinations are the operator console and the DC/UCF log file. Messages are defined in the dictionary by using the IDD DDDL compiler.
Note: For more information about the IDD DDDL compiler, see the IDD DDDL Reference.
The message text can be dynamically changed by your program using symbolic parameters. You can also optionally request the system not to retrieve the message but to send only the message ID and symbolic parameter replacement values to the selected destinations.
The message ID specified in a #WTL statement is a 7-digit number. The first six digits contain the message identifier used to retrieve the message from the dictionary. The seventh digit is a severity code. When the program requests that the system retrieve the message from the dictionary (MSGDICT=YES), a predefined severity code is retrieved along with the message text.
When the dictionary lookup is bypassed (MSGDICT=NO), the system uses the severity code specified in the program. The severity level determines the action the system takes after the message is written to the log.
The dictionary severity may be overridden by using the OVRIDES parameter.
The possible severity codes and their resulting DC/UCF system responses are listed below:
|
Severity code |
DC/UCF system action |
|---|---|
|
0 |
Returns control to the issuing program and continues processing |
|
1 |
Snaps all task resources to the log and returns control to the issuing program |
|
2 |
Snaps all system areas to the log and returns control to the issuing program |
|
3 |
Snaps all task resources and abends the task with a task abend code of D002 |
|
4 |
Snaps all system areas and abends the task with a task abend code of D002 |
|
5 |
Abends the task with a task abend code of D002 |
|
6 |
Undefined |
|
7 |
Undefined |
|
8 |
Snaps all system areas and abends the system with a system abend code of 3996 |
|
9 |
Terminates the system with a system abend code of 3996 |
If a #WTL statement specifies a message ID that is not in the message dictionary, the system issues a prototype message with severity level 0. Messages should be defined in the message dictionary before they are issued by an executing program.
The message text can be dynamically altered by using symbolic parameters. Messages stored in the message dictionary can contain symbolic parameters, identified by an ampersand (&). followed by a 2-digit numeric identifier. Symbolic parameters can appear in any order in the message.
The #WTL statement can specify replacement values for one or more symbolic parameters by using the PARMS operand. The position of replacement values in the #WTL 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 &02., and the third &03., as shown in the example below.
The stored message text reads:
THIS IS TEXT &01. AND &03. OR &02.
The PARMS clause reads: PARMS=('A','B','C'). The resulting text would read:
THIS IS TEXT A AND C OR B
If the message destination is the operator console, the #WTL can optionally request a reply. An event control block (ECB) can be defined that will permit control to be returned immediately to the issuing task without waiting for the reply. The ECB will be posted by the system when the reply is sent. If no ECB is defined, control is not returned to the issuing task until the reply has been received.
Syntax
►►─┬─────────┬─ #WTL MSGID=message-id-pointer ────────────────────────────────► └─ label ─┘ ►─┬─────────────────────────────────────────┬────────────────────────────────► └─ ,MSGPREF= ─┬─ 'DC' ◄ ─────────────────┬┘ └─ message-prefix-pointer ─┘ ►─┬────────────────────────────────────────┬─────────────────────────────────► └─ ,PLIST= ─┬─ SYSPLIST ◄ ─────────────┬─┘ └─ parameter-list-pointer ─┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ ,MSGDICT= ─┬─ YES ◄ ─┬┘ └─ NO ────┘ ►─┬────────────────────────────────────────────┬─────────────────────────────► └─ ,PARMS= ─┬─── NO ◄ ─────────────────────┬┘ │ ┌──────────────────────┐ │ └─(──▼─ parameter-register ─┴─)─┘ ►─┬─────────────────────────────────────────────────────────────────┬────────► └─ ,REPLY= ─┬─ NO ◄ ────────────────────────────────────────────┬─┘ ├─ (YES,reply-location ─┬─────────────────────┬─ ) ─┤ │ └─ ,reply-max-length ─┘ │ └─ (CANCEL,reply-location) ─────────────────────────┘ ►─┬─────────────────────────────────┬────────────────────────────────────────► └─ , ─┬─ ECB=ecb-pointer ───────┬─┘ └─ ECBID=ecb-id-register ─┘ ►─┬───────────────────────────────────────────────────────────────────────┬──► └─,RTNTEXT=return-text-location ─┬─────────────────────────────────────┬┘ └─,RTNLEN=return-text-length-pointer ─┘ ►─┬─────────────────────────────────────┬────────────────────────────────────►◄ └─ ,OVRIDES=override-address-pointer ─┘
Parameters
Specifies the 7-digit message ID that is stored in the message dictionary. Message-id can be specified as follows:
A message ID must be a 4-byte packed decimal field (PL4), formatted as nnnnnnS, where nnnnnn is the 6-digit ID and S is the severity code. Message-id can specify any number in the range 900001 through 999999; id numbers 000001 through 900000 are reserved for use by the system.
Specifies a 2-character alphanumeric prefix to the message ID. The default message prefix is 'DC'.
Note: It is important when using the MSGPREF option that you keep the message ID within the user range of 900001 through 999999. The system uses message prefixes which could cause a conflict with user message prefixes unless this restriction is observed.
A register that points to the prefix, the symbolic name of a user-defined field containing the prefix, or the prefix literal enclosed in quotation marks.
Specifies the area in which the system builds the #WTL parameter list.
(Default); is the symbolic name of the storage area in which the system builds the #WTL parameter list.
A register that points to the area or the symbolic name of the area in which the system builds the #WTL parameter list.
If MSGID is the only operand specified on the #WTL request, you do not need to specify PLIST. If any additional operands are included, the following rules determine the size of the PLIST:
1 + P + X
where the following conditions are met:
Specifies whether to retrieve the message from the message area of the dictionary.
(Default); requests that the system locate the predefined message, apply substitution values, and send the message to the designated destinations.
Requests that the system bypass the dictionary. The system writes a message to the console operator and log file that contains only the message ID and any replacement values specified in the PARMS parameter.
Override the default destination and/or severity code values.
A register that points to the address of the override values or the symbolic name of the field containing the override values.
Override values must be defined in the following manner:
|
Bytes |
Contents |
|---|---|
|
0 |
X'80'—Destination is the DC log X'40'—Destination is the console operator X'20'—Destination is the terminal operator X'10'—Destination is the ID of any terminal X'08'—Override the severity with severity passed in message ID X'01'—Null override |
|
1 - 2 |
Overrides for MVS description in the format 00N0, where N is a valid MVS descriptor code. |
|
3 - 4 |
Overrides for MVS route code in the format 00N0, where N is a valid MVS route code. |
Specifies replacement values for one or more symbolic parameters stored with the message text.
Note: If the text parameters contain any binary zeroes (x'00'),CA IDMS/DC automatically changes them to blanks (x'40') after copying the parameters to an internal work area.
(Default); specifies that there are no symbolic parameters to be replaced, or requests that the system not replace any of the symbolic parameters.
Requests that the system replace the specified parameters. Parameter-register is a register that points to the replacement field, the symbolic name of a user-defined replacement field, or the replacement value literal enclosed in quotation marks.
When parameter-register is a register or user-defined field, each parameter field must begin with a 1-byte field from which the system obtains the length of the adjacent replacement field. The value in the length does not include the length byte.
Performs one of the following functions:
The REPLY and RTNTEXT options are mutually exclusive; do not specify both options on a single #WTL request. The following options can be specified for the REPLY parameter:
(Default); specifies that no reply is expected.
Specifies that a reply is expected and should be returned to the area defined by reply-location and, optionally, reply-max-length.
Specifies the location of the area reserved for a reply to the message issued by a #WTL request. Reply-location is either a register that points to the area or the symbolic name of that area.
Specifies the maximum length, in bytes, of the area reserved for the reply. Reply-max-length is an absolute expression of the area length. If the maximum length is not specified by using the REPLY option, you must indicate the maximum length in the second halfword of the reply location.
Note: If YES is specified, the ECB or the ECBID parameters must be included to identify the ECB to be posted.
When the reply is sent, the reply area will be formatted by the system, as shown below:
|
Bytes |
Contents |
|---|---|
|
0 - 1 |
Reserved for system use |
|
2 - 3 |
Length of the reply text expressed as a halfword binary value. If the maximum reply length is not specified, you must set this maximum length before issuing the #WTL request. On completion of the #WTL request, this field will contain the actual length of the text. |
|
4 - n |
Reply text |
Cancels a request for a reply to a previously issued #WTL request. Reply-location specifies the area reserved for a reply to the message. Reply-location is either a register that points to the area or the symbolic name of the area.
(#WTL requests with REPLY=YES only); identifies the ECB to be posted when the reply has been sent to its destination. Naming an ECB allows control to return immediately to the issuing task without waiting for a reply. The system will post the ECB when the reply is sent. If no ECB is defined, the system does not return control to the issuing task until the reply is received.
Identifies the ECB that is posted when the reply is sent.
Either a register that points to the fullword ECB or the symbolic name of the ECB.
Identifies the 4-character symbolic ECB that is posted when the reply is sent.
Either a register that contains the ECB ID, the symbolic name of a fullword field that contains the ECB ID, or the ID literal enclosed in quotation marks.
Specifies the location into which the system places the retrieved message text identified by message-id. Any replacement values specified in the PARMS parameter are included in the retrieved text.
If the length of the retrieved message text (RTNLEN) is not specified, the first byte of the return text receiving field must specify the length, in hexadecimal notation, of the returned string.
Either a register that points to the storage area reserved for the message text or the symbolic name of a user-defined field reserved for the message text.
Note: The RTNTEXT and REPLY options are mutually exclusive; only one of these operands can be specified in a single #WTL request.
Indicates the length of the return text receiving field.
A register that points to the length of the field, a halfword or fullword field containing the length of the field, or an absolute expression of the length of the field enclosed in quotation marks.
If this parameter is included, the first byte of the RTNTEXT receiving field does not have to be a length indicator. If the length specified is not large enough to accommodate the entire message, register 1 will contain the number of lines that could not be sent.
Example
The following figure illustrates a #WTL statement that supplies three replacement parameters and requests a reply. Program A issues a #WTL request for message 990100 with a prefix DC. The message text and severity are stored in the message area of the dictionary. Symbolic parameters are within the message text. The program specifies values to replace the symbolic parameters &01., &02., and &03. stored in the message area of the dictionary along with the message text. The system sends the message to terminal A, which is the logical terminal associated with the issuing task, and waits for a reply. The reply is returned to the area specified by REPLY; the length of the reply can be up to 20 bytes.
Status Codes
The system returns the following values to register 15 during processing of a #WTL request. Any value greater than zero indicates that the request was not serviced, and no #WTL was performed. Register 15 values are as follows:
The request has been serviced successfully.
An invalid parameter or combination of parameters has been specified.
A resource necessary for the processing of the request, for example, a resource control element, is not available.
The maximum number of outstanding replies was exceeded.
The length of the return text area is not large enough to contain the entire message text.
|
Copyright © 2014 CA.
All rights reserved.
|
|