CONVERSE (3600-3601)

Communicate on a 3600 (3601) logical unit.

CONVERSE (3600-3601)

Conditions: EOC, EODS, INBFMH, LENGERR, SIGNAL, TERMERR

Description

CONVERSE communicates on a 3600 logical unit. This form of the CONVERSE command also applies to the 4700 and the 3630 plant communication system.

A logical device code (LDC) is a code that can be included in an outbound Function Management Header (FMH) to specify the disposition of the data (for example, to which subsystem terminal it should be sent). Each code can be represented by a unique LDC mnemonic.

The installation can specify up to 256 2-character mnemonics for each TCTTE, and two or more TCTTEs can share a list of these mnemonics. A numeric value (0 through 255) corresponds to each LDC mnemonic for each TCTTE.

A 3600 device and a logical page size are also associated with an LDC. LDC or LDC value is used in this information to refer to the code specified by the user; LDC mnemonic refers to the 2-character symbol that represents the LDC numeric value.

When the LDC option is specified in the CONVERSE command, the numeric value associated with the mnemonic for the particular TCTTE is inserted in the FMH. This value is chosen by the installation, and is interpreted by the 3601 application program.

On output, the FMH can be built by the application program or by CICS®. If your program supplies the FMH, you place it at the front of your output data and specify the FMH option on your CONVERSE command. If you omit the FMH option, CICS will provide an FMH but you must reserve the first three bytes of the message for CICS to complete.

Options

DEFRESP

This option indicates that a definite response is required when the output operation is completed.

FMH

This option specifies that a function management header is included in the data to be written. If the ATTACHID option is specified as well, the concatenated FMH flag is set in the attach FMH.

The use of FMH is optional and is not supported for all terminal types. If not supplied, CICS takes no action, except for 3600/4700 terminals, where an FMH is mandatory. In this case, if FMH is not specified, CICS supplies one and places it in the first 3 bytes of the message, which you must reserve for this purpose.

FROM(data-area)

This option specifies the data to be written to the terminal or logical unit, or sent to the partner transaction. This option can, when relevant, be omitted if ATTACHID is specified.

FROMFLENGTH(data-value)

This option is a fullword alternative to FROMLENGTH.

FROMLENGTH(data-value)

This option specifies the length, as a halfword binary value, of the data. For a description of a safe upper limit, see LENGTH options in CICS commands.

INTO(data-area)

This option specifies the receiving field for the data read from the terminal or logical unit, or the application target data area into which data is to be received from the application program that is connected to the other end of the current conversation.

LDC(name)

This option specifies the 2-character mnemonic that is used to determine the appropriate logical device code (LDC) numeric value. The mnemonic identifies an LDCentry that is defined by a DFHTCT TYPE=LDC macro.

MAXFLENGTH(data-value)

This option is a fullword alternative to MAXLENGTH.

MAXLENGTH(data-value)

This option specifies the maximum amount (halfword binary value) of data that CICS is to recover in response to a CONVERSE (default) command. If INTO is specified, MAXLENGTH overrides the use of TOLENGTH as an input to CICS. If SET is specified, MAXLENGTH provides a way for the program to limit the amount of data it receives at one time.

If the value specified is less than zero, zero is assumed.

If the length of data exceeds the value that is specified and the NOTRUNCATE option is not present, the data is truncated to that value and the LENGERR condition occurs. The data area that is specified in the TOLENGTH option is set to the original length of data.

If the length of data exceeds the value that is specified and the NOTRUNCATE option is present, CICS retains the remaining data and uses it to satisfy subsequent RECEIVE commands. The data area that is specified in the TOLENGTH option is set to the length of data returned.

If no argument is coded for MAXLENGTH, CICS defaults to TOLENGTH.

NOTRUNCATE

This option specifies that, when the data 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)

This option specifies the pointer reference to be set to the address of the data read from the terminal. pointer reference, unless changed by other commands or statements, is valid until the next CONVERSE (default) command or the end of task.

If DATALOCATION(ANY) is associated with the application program, the address of the data can be above or below the 16 MB line.

If DATALOCATION(BELOW) is associated with the application program, and the data resides above the 16 MB line, the data is copied below the 16 MB line, and the address of this copy is returned.

If TASKDATAKEY(USER) is specified for the running task, and storage protection is active, the data that is returned is in a user-key. If TASKDATAKEY(CICS) is specified and storage protection is active, the data that is returned is in a CICS-key.

TOFLENGTH(data-area)

This option is a fullword alternative to TOLENGTH.

TOLENGTH(data-area)

This option specifies the length (halfword binary value) of the data to be received. If you specify INTO, but omit MAXLENGTH, “data-area” specifies the maximum length that the program accepts. If the value is less than zero, zero is assumed.

If the length of the data exceeds the value that is specified, but NOTRUNCATE is omitted, the data is truncated to that value, and the LENGERR condition occurs. When the data is received, the data area is set to the length of the data.

For a description of a safe upper limit, see LENGTH options in CICS commands.

Conditions

Some of the following conditions can occur in combination with others. CICS checks for these conditions in the following order:

EODS
INBFMH
EOC

If more than one occurs, only the first is passed to the application program. However, eIBRCODE is set to indicate all the conditions that occurred.

06 EOC

This condition occurs when a request/response unit (RU) is received with the end-of-chain indicator set. Field EIBEOC also contains this indicator.

Default action: ignore the condition.

05 EODS

This condition occurs when an end-of-data-set indicator is received.

Default action: terminate the task abnormally.

07 INBFMH

This condition occurs if a request/response unit (RU) contains a function management header (FMH). Field EIBFMH contains this indicator and it must be used in preference to INBFMH. The IGNORE CONDITION command can be used to ignore the condition.

Default action: terminate the task abnormally.

22 LENGERR

This condition occurs in any of the following situations:

Data that is received is discarded by CICS because its length exceeds the maximum that the program accepts (see TOLENGTH and MAXLENGTH options), and the NOTRUNCATE option is not specified.
An out-of-range value is supplied in one of the options, FROMLENGTH, FROMFLENGTH, MAXLENGTH, MAXFLENGTH, TOLENGTH, or TOFLENGTH.

Default action: terminate the task abnormally.

24 SIGNAL

This condition occurs when an inbound SIGNAL data flow control command is received from a logical unit or session, or the partner transaction. EIBSIG is always set when an inbound signal is received.

Default action: ignore the condition.

81 TERMERR

This condition occurs for a terminal or session-related error. Any action on that conversation other than a FREE causes an ATCV abend.

A CANCEL TASK request by a user node error program (NEP) can cause this condition if the task has an outstanding terminal control request active when the node abnormal condition program handles the session error.

Default action: terminate the task abnormally with abend code ATNI.