CONVERSE (MRO)

Communicate on an MRO session.

CONVERSE (MRO)

Conditions: CBIDERR, EOC, INBFMH, LENGERR, NOTALLOC, TERMERR

Description

CONVERSE communicates on an MRO session. For more information about MRO and IRC, see Introduction to CICS intercommunication.

Options

ATTACHID(name)

This option specifies that an attach header (created by a BUILD ATTACH command) is to precede, and be concatenated with, the user data supplied in the FROM option. “name” (1–8 characters) identifies the attach header control block to be used in the local task.

CONVID(name)

This option identifies the conversation to which the command relates. The 4-character name identifies either the token that is returned by a previously executed ALLOCATE command in EIBRSRCE in the EIB, or the token that represents the principal session (returned by a previously executed ASSIGN command).

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.

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 to be written. If you use this option, you must also specify FROM. 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 logical unit or terminal.

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 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 retained for retrieval by subsequent RECEIVE commands.

SESSION(name)

This option specifies the symbolic identifier (1–4 characters) of a session TCTTE. This option specifies the alternate facility to be used. If both this option and CONVID are omitted, the principal facility for the task is used.

SET(ptr-ref)

This option specifies a pointer reference to be set to the address of data that is received from the conversation partner in an MRO conversation. The pointer reference, unless changed by other commands or statements, is valid until the next CONVERSE (MRO) 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 16MB line, the data is copied below the 16MB 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 returned is in a user-key. If TASKDATAKEY(CICS) is specified and storage protection is active, the data returned is in a CICS-key.

STATE(cvda)

This option gets the state of the transaction program. The cvda values returned by CICS are:

ALLOCATED
FREE
PENDFREE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

TOFLENGTH(data-area)

This option is a fullword alternative to TOLENGTH.

TOLENGTH(data-area)

This option specifies the length, as a 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 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:

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.

62 CBIDERR

This condition occurs if the requested attach header control block that is named in ATTACHID cannot be found.

Default action: terminate the task abnormally.

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.

07 INBFMH

This condition occurs if a request/response unit (RU) contains a function management header (FMH). Field EIBFMH contains this indicator and it should 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 is discarded by CICS because its length exceeds the maximum that the program accepts and the NOTRUNCATE option is not specified.
An out-of-range value is supplied in the FROMLENGTH option.

Default action: terminate the task abnormally.

61 NOTALLOC

This condition occurs if the facility specified in the command is not owned by the application.

Default action: terminate the task abnormally.

81 TERMERR

This condition occurs for a session-related error.

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.