WRITE LOG (COBOL)

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 that is specified in the message definition. Typical destinations are the operator console and the DC system log file. If the operator 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.
idmscu
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 that is specified in the message definition. Typical destinations are the operator console and the DC system log file. If the operator 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.
For more information about global messages, see the MESSAGE statement.
The message ID that is specified in the WRITE LOG statement is a seven-digit number. The first six (most significant) digits make up the actual message ID that is 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 with the message text to indicate the action to take after the message is written to the log:
Severity Level
CA IDMS Action
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.
If a WRITE LOG statement specifies a message ID that is not in the data dictionary, CA IDMS uses a prototype message and performs the action that is associated with the severity code in the WRITE LOG request.
Messages that are stored in the data dictionary can contain symbolic parameters. Symbolic parameters are identified by an ampersand (&). and are followed by a two-digit numeric identifier. Symbolic parameters 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 two-digit numeric identifier in the message text. For example, the first value that is specified corresponds to &01., the second to &02., and so forth.
Syntax
►►─── WRITE LOG MESSAGE ID 
message-id
 ────────────────────────────────────────►  ►─┬───────────────────────────────────────────────────────────────────────┬──►    │         ┌───────────────────────────────────────────────────────────┐ │    └─ PARMS ─▼─ FROM 
parameter-location
 ─┬─ TO 
end-parameter-location
 ─┬─┴─┘                                          └─ LENGTH 
parameter-length
 ───┘  ►─┬───────────────────────────────────────────────────────────────┬──────────►    └─ REPLY INTO 
reply-location
 ─┬─ TO 
end-reply-location
 ───────┬─┘                                  └─ MAX LENGTH 
reply-max-length
 ─┘    ►─┬────────────────────────────┬─────────────────────────────────────────────►    └─ MESSAGE PREFIX is 'DC' ───┘  ►─┬──────────────────────────────────────────────────────────────────────────►─    └─ TEXT INTO 
text-return-location
 ─┬─ TO 
end-text-return-location
 ─┬───────                                       └─ MAX LENGTH 
text-max-length
 ──┘  ─►───────────────────────────────────────────────┬─ . ───────────────────────►◄   ───┬──────────────────────────────────────────┬─┘      ├─ MESSAGE PREFIX is ─┬─ YES ◄ ──────────┬─┤      │                     ├─ NO ─────────────┤ │      │                     └─ 
message-prefix
 ─┘ │      │                                          │      └─ TEXT is ONLY ───────────────────────────┘
Parameters
  • WRITE LOG MESSAGE ID 
    message-id
     
    Specifies the message ID. The first six digits specify the message ID. The seventh digit specifies the message severity code. Specify the symbolic name of a user-defined PIC S9(8) COMP (fullword) 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 CA IDMS. The WRITE LOG statement can specify any number in the range 900001 through 999999. 
     The message length must be seven digits. The system always interprets the last digit as the severity level. If you request message 987659 and you 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 terminate with a 3996 abend code.
    When messages are added to the data dictionary for use with the WRITE LOG statement, they are assigned an eight-character identification number. The first two characters are DC. A request for message 987654 retrieves DC987654.
  • PARMS FROM 
    parameter-location
    Supplies replacement values for one or more symbolic parameters that are stored with the message text. Specify the symbolic name of a user-defined field that contains the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the replacement parameter. This field must begin with a 1-byte field into which the system places the length of the adjacent field. The value in the length does not include the length byte.
  • TO 
    end-parameter-location
    Specifies the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that contains the replacement parameter. Specify the symbolic name of a user-defined dummy byte field or a field containing a data item that is not associated with the replacement parameter.
  • LENGTH 
    parameter-length
    Specifies the length of the replacement parameter in bytes. Specify the symbolic name of a user-defined field that contains the length, or the length itself expressed as a numeric constant.
  • REPLY INTO 
    reply-location
    Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the area that is reserved for a reply to the message that the WRITE LOG request issues. Specify the symbolic name of a user-defined field. This field must begin with a 1-byte field into which the system places the length of the adjacent field. The value in the length does not include the length byte.
  • TO 
    end-reply-location
    Specifies the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that is reserved for the reply. Specify the symbolic name of a user-defined dummy byte field or a field containing a data item that is not associated with the reply.
  • MAX LENGTH 
    reply-max-length
    Specifies the maximum length, in bytes, of the area that is reserved for the reply. Specify the symbolic name of a user-defined field that contains the length, or the length itself expressed as a numeric constant.
  • MESSAGE PREFIX IS 'DC'
    Specifies the two characters that precede the numeric position of a message. The default is 'DC'.
  • TEXT INTO 
    text-return-location
    Writes the contents of the named message and any replacement parameters to the issuing program. Specify the symbolic name of a user-defined 1 through 132 character alphanumeric field that contains the WORKING-STORAGE SECTION or LINKAGE SECTION entry to which the message text is to be returned. This field must begin with a 1-byte field into which the system places the length of the adjacent field. The value in the length does not include the length byte.
  • TO 
    end-text-return-location
    Specifies the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that is reserved for the text. Specify the symbolic name of a user-defined dummy byte field or a field containing a data item that is not associated with the returned text.
  • MAX LENGTH 
    text-max-length
    Specifies the maximum length, in bytes, of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that is reserved for the returned message text. Specify the symbolic name of a user-defined field that contains the text length, or the length itself expressed as a numeric constant.
  • MESSAGE PREFIX is
    Specifies the format of the message prefix. To override the default DC prefix, specify any one or two characters for 
    message-prefix
    . To suppress a prefix, specify blanks.
    • YES 
      Indicates that the message text is preceded by:
      IDMS
       ppnnnnnnn
       V
      ssssss
       REPLY
      nn
      • pp
         is the prefix that is specified in the MESSAGE PREFIX parameter.
      • nnnnnnn
         is the message number.
      • Vssssss
         is the system number.
      • REPLY
        nn
         is the system-supplied reply number for the message (present only if the REPLY parameter is used).
      This value is the default.
    • NO 
      Indicates that the message text is preceded by:
      ppnnnnnnn
      • pp
         is the prefix that is specified in the MESSAGE PREFIX parameter.
      • nnnnnnn
         is the message number.
  • TEXT is ONLY
    Indicates that the message text is output with no prefix.
Example
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. which are stored with the message text. The message is sent to its destination, which is the logical terminal that is associated with the issuing task.
In this figure, a WRITE LOG STATEMENT supplies three replacement parameters. Task A issues a WRITE LOG request for message 900121, specifying values to replace three symbolic parameters that are stored with the message text. The message is sent to its destination, which is the logical terminal that is associated with the issuing task.
Status Codes
After completion of the WRITE LOG function, the ERROR-STATUS field of the IDMS DC communications block indicates the outcome:
Status code
Meaning
0000
The request has been serviced successfully.
3623
No storage or resource control element (RCE) can be allocated for the specified reply area.
3624
The maximum number of outstanding replies has been exceeded. A maximum of 98 messages can await a reply at a given time.
3625
The maximum number of replacement parameters has been exceeded. A maximum of 8 replacement parameters can be used when the "Message Prefix" option is not used. If the"Message Prefix" option is used, the maximum number of replacement parameters is limited to 7.
3631
The parameter list is invalid.