Write a message on the system console.
WRITE OPERATOR >>-WRITE OPERATOR--TEXT(data-value)-----------------------------> >--+------------------------+-----------------------------------> '-TEXTLENGTH(data-value)-' >--+-----------------------------------------------+------------> '-ROUTECODES(data-value)--NUMROUTES(data-value)-' .-EVENTUAL-------------------------------------------------------------------------------------. >--+----------------------------------------------------------------------------------------------+->< +-ACTION(cvda)---------------------------------------------------------------------------------+ +-CRITICAL-------------------------------------------------------------------------------------+ +-IMMEDIATE------------------------------------------------------------------------------------+ '-REPLY(data-area)--MAXLENGTH(data-value)--+------------------------+--+---------------------+-' '-REPLYLENGTH(data-area)-' '-TIMEOUT(data-value)-'
Conditions: EXPIRED, INVREQ, LENGERR
Description
WRITE OPERATOR enables an application to write a message to one or more system consoles and, if required, wait for a reply. The command can specify route codes, which is of particular use to application packages that have to issue their own operator messages.
As a result of a change in the way CICS® handles messages sent to the console, text lengths of greater than 113 characters are split into two lines. None of the variables below can be defined as PL/I variable character strings.
The action code is identical with the descriptor code to be associated with the message. Only one of the descriptor codes 2, 3, or 11 may be specified for this parameter.
- 2
- Immediate action
- 3
- Eventual action
- 11
- Critical eventual action.
The CRITICAL option is equivalent to a specification of ACTION(11). The EVENTUAL option is equivalent to a specification of ACTION(3). The IMMEDIATE option is equivalent to a specification of ACTION(2).
Retained messages can be handled by the console operator in a variety of ways (see z/OS MVS System Commands). Refer to your system programmer for information about how this command affects the appearance of the console screen to the operator.
Options
- ACTION(cvda)
- Specifies
an action code that is associated with this message. CVDA values are:
- CRITICAL
- Specifies that the message requires eventual action by the operator and has enough critical importance to remain on the console screen. The message remains on the screen until it is deleted by the operator.
- EVENTUAL
- Specifies that the operator should take action when there is time. The message is rolled off when other messages fill up the screen, but is still retained by the operating system until the operator explicitly deletes it.
- IMMEDIATE
- Specifies that the operator should take action immediately. The message remains on the console screen until it is deleted by the operator.
- MAXLENGTH(data-value)
- Specifies a fullword binary field that contains the length of the reply area (in the range 1–119 bytes). You must specify MAXLENGTH if you specify REPLY.
- NUMROUTES(data-value)
- Specifies a fullword binary field that defines the number of routing codes.
- REPLY(data-area)
- Specifies a data area for receiving the operator's reply. If you specify this option, your application pauses until either a reply is received or the TIMEOUT period expires.
- REPLYLENGTH(data-area)
- Specifies the actual length (fullword binary value) of the operator's reply.
- ROUTECODES(data-value)
- Specifies a variable-length field. Each code is one byte and contains a binary number in the range 1–28. The default is a single code, set to 2. In COBOL programs only, you must use a data-area that contains the 1-byte values rather than a data-value.
- TEXT(data-value)
- Specifies
a data value containing the text to be sent.
If the data value begins with DFHnnnn or DFHaannnn, the message is treated as a CICS message and is reformatted accordingly.
If you are using the COBOL2 translator option, you must use a data-area that contains the text to be sent to the operator, and not a data-value.
- TEXTLENGTH(data-value)
- Specifies
the length, as a fullword binary value, of the text. This option is
required only for C and C++ programs.
- If the REPLY option is specified, the length is in the range 0–121 bytes.
- If the REPLY option is not specified, the length is in the range 0–690 bytes.
If the length of the text is greater than 113, CICS formats the message in a multiline write to operator (WTO); each line has 69 bytes with a maximum of ten lines.
The output is edited in such a way that each line is broken, if possible, at a space character, The next line starts with a non-space character. If there is no room to reformat the data within the overall limit of 690 bytes of ten lines of 69 bytes, the output is not reformatted.
- TIMEOUT(data-value)
- Specifies a fullword binary field that contains the maximum time (in seconds) that CICS waits for a reply before returning control to this transaction. This must be in the range 0–86 400 (24 hours). The system default value is specified by the OPERTIM system initialization parameter. You can only specify TIMEOUT if you have also specified REPLY.
Conditions
- 31 EXPIRED
- RESP2
values:
- 7
- TIMEOUT has occurred before the operator's reply was received.
Default action: return the exception condition to the application.
- 16 INVREQ
- RESP2 values:
- 1
- The TEXTLENGTH value is not valid.
- 2
- The NUMROUTES value is not valid.
- 3
- The ROUTECODES value is not valid.
- 4
- The MAXLENGTH value is not valid.
- 5
- The TIMEOUT value is not valid.
- 6
- The ACTION value is not valid.
Default action: terminate the task abnormally.
- 22 LENGERR
- RESP2
values:
- 8
- The reply was longer than MAXLENGTH, and has been truncated.
Default action: terminate the task abnormally.
