Communicate on an MRO session.

CONVERSE (MRO)
>>-CONVERSE--+---------------+--+----------------+-------------->
+-CONVID(name)--+ '-ATTACHID(name)-'
'-SESSION(name)-'
>--+-------------------------------------------------------+---->
'-FROM(data-area)--+-FROMLENGTH(data-value)--+--+-----+-'
'-FROMFLENGTH(data-value)-' '-FMH-'
>--+-INTO(data-area)-+--+-TOLENGTH(data-area)--+---------------->
'-SET(ptr-ref)----' '-TOFLENGTH(data-area)-'
>--+------------------------+--+------------+--+---------+------>
+-MAXLENGTH(data-value)--+ '-NOTRUNCATE-' '-DEFRESP-'
'-MAXFLENGTH(data-value)-'
>--+-------------+---------------------------------------------><
'-STATE(cvda)-'
Conditions: CBIDERR, EOC, INBFMH, LENGERR, NOTALLOC, TERMERR
Options
- ATTACHID(name)
- 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)
- identifies
the conversation to which the command relates. The 4-character name identifies
either the token returned by a previously executed ALLOCATE command in EIBRSRCE
in the EIB, or the token representing the principal session (returned by a
previously executed ASSIGN command).
- DEFRESP
- indicates
that a definite response is required when the output operation has been completed.
- FMH
- specifies
that a function management header has been 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)
- specifies
the data to be written to the terminal or logical unit, or sent to the partner
transaction. This option may, when relevant, be omitted if ATTACHID is specified.
- FROMFLENGTH(data-value)
- is
a fullword alternative to FROMLENGTH.
- FROMLENGTH(data-value)
- 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)
- specifies
the receiving field for the data read from the logical unit or terminal.
- MAXFLENGTH(data-value)
- is
a fullword alternative to MAXLENGTH.
- MAXLENGTH(data-value)
- 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 specified and the NOTRUNCATE option is
not present, the data is truncated to that value and the LENGERR condition
occurs. The data area specified in the TOLENGTH option is set to the original
length of data.
If the length of data exceeds the value specified
and the NOTRUNCATE option is present, CICS retains the remaining data and
uses it to satisfy subsequent RECEIVE commands. The data area 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
- specifies
that, when the data available exceeds the length requested, the remaining
data is not to be discarded but retained for retrieval by subsequent RECEIVE
commands.
- SESSION(name)
- 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)
- specifies
a pointer reference to be set to the address of data 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 16MB 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)
- 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)
- is
a fullword alternative to TOLENGTH.
- TOLENGTH(data-area)
- 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. EIBRCODE, however, is set to indicate all the conditions that occurred.
- CBIDERR
- occurs
if the requested attach header control block named in ATTACHID cannot be found.
Default action: terminate the task abnormally.
- EOC
- 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.
- INBFMH
- 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.
- LENGERR
- 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.
- NOTALLOC
- occurs
if the facility specified in the command is not owned by the application.
Default action: terminate the task abnormally.
- TERMERR
- occurs
for a session-related error.
A CANCEL TASK request by a user node error
program (NEP) may 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.