CONVERSE (terminal)
Communicates with a terminal.
Syntax
Description
CONVERSE communicates either with a terminal, or on an advanced program-to-program communications (APPC) mapped conversation. The form of CONVERSE command that is described here is used for communicating with a terminal. For details of the CONVERSE command that is for use on APPC mapped conversations, see CONVERSE (APPC). (An APPC conversation allows a program to send data to, and receive data from, a program that is running in a remote system. Programming that uses APPC conversations is called Distributed Transaction Programming (DTP). For guidance information about DTP, see Distributed transaction processing (DTP).)
Options
- CTLCHAR(data-value)
- Specifies a one-byte Write Control Character (WCC) that controls the CONVERSE command. A COBOL user must specify a data area that contains this character. If this option is omitted from the CONVERSE command, all modified data tags are reset to zero, and the keyboard is restored.
- ERASE
- Specifies that the screen is to be erased and the cursor returned to the upper left corner of the screen before writing occurs. Normally, ERASE is specified in the first output command of a transaction. This clears the screen ready for the new output data.
- FROM(data-area)
- Specifies the data that is to be written to the terminal.
- FROMFLENGTH(data-value)
- Specifies a 32-bit alternative to FROMLENGTH(data-value).
- FROMLENGTH(data-value)
- Specifies, as a 16-bit binary value, the length of the data that is to be written.
- INTO(data-area)
- Specifies the receiving field for the data that is read from the terminal. For more information about using this option, see INTO and SET.
- MAXFLENGTH(data-value)
- A 32-bit alternative to MAXLENGTH(data-value).
- MAXLENGTH(data-value)
- Specifies,
as a 16-bit binary value, the maximum amount of data that CICS® can return
to the application on the CONVERSE command. This value must be zero through
32767.
If the NOTRUNCATE option is specified and the data that is received is longer than the maximum that is specified in MAXLENGTH, CICS returns the data up to the maximum length and sets EIBCOMPL=EIBFALSE to indicate that more data is to follow. The remaining data can be received by using one or more of the RECEIVE commands.
If the NOTRUNCATE option is not specified and the data that is received is longer than the maximum that is specified in MAXLENGTH, CICS returns the data up to the maximum length and returns the LENGERR condition. The remaining data is discarded by CICS and cannot be received by the application. If MAXLENGTH is not coded on the CONVERSE command, CICS uses, as the maximum length, the value that is passed in the TOLENGTH argument.
- NOTRUNCATE
- Specifies that, when the data that is available exceeds the length that is requested, the remaining data is not to be discarded but is to be retained for retrieval by subsequent RECEIVE commands.
- SET(ptr-ref)
- Specifies a pointer reference that is to be set to the address of the data that is read from the terminal. This pointer reference is valid until the next terminal control or APPC command, or the end of task. For more information about using this option, see INTO and SET.
- TOFLENGTH(data-area)
- A 32-bit alternative to TOLENGTH(data-area).
- TOLENGTH(data-area)
- Specifies
a 16-bit binary value that CICS uses to return the amount of data received. If
the NOTRUNCATE option is specified, the TOLENGTH option contains the amount
of contains the amount of data to be passed back to the application. If the
NOTRUNCATE option is not specified, the TOLENGTH option contains the amount
of data that was received by CICS before any truncation occurred.
If MAXLENGTH is not specified, the TOLENGTH option is also used to specify the maximum amount of data that CICS can return to the application on the CONVERSE call. If TOLENGTH is used to pass the maximum value, it must be set up before each call to CONVERSE because its value might have been changed by the previous CONVERSE command. If the value of TOLENGTH passed is less that zero, CICS assumes zero.
Conditions
- INVREQ
- Occurs
for the following conditions, depending on the options that are specified
on the CONVERSE command:
- Any of the terminal-related CONVERSE options (ERASE or CTLCHAR) has been specified, but the principal facility for the task is not a terminal (that is, it is an APPC conversation).
- An attempt is made to issue a CONVERSE command with terminal-related options from a remotely linked-to program.
- A remotely linked-to program attempted to execute a CONVERSE command that refers to the principal facility.
Default action: Terminates the task abnormally.
- LENGERR
- Occurs
for the following conditions:
- Received data was truncated because the length exceeded the maximum that is allowed by the program, and the NOTRUNCATE option was not specified. Refer to the option descriptions for information about maximum lengths.
- An out-of-range value is supplied in the FROMLENGTH, MAXLENGTH, or TOLENGTH option, or in one of the alternative 32-bit length options.
Default action: Terminates the task abnormally.
- NOTALLOC
- Occurs
if this command is issued in a task that is not associated with a terminal.
Default action: Terminates the task abnormally.
- TERMERR
- Occurs
if a terminal-related error occurs.
Default action: Terminate the task abnormally (with abend code ATNI).