Communicate on an APPC mapped conversation
CONVERSE (APPC)
>>-CONVERSE--+--------------+--FROM(data-area)------------------>
'-CONVID(name)-'
>--+-FROMLENGTH(data-value)--+--+-INTO(data-area)-+------------->
'-FROMFLENGTH(data-value)-' '-SET(ptr-ref)----'
>--+-TOLENGTH(data-area)--+--+------------------------+--------->
'-TOFLENGTH(data-area)-' +-MAXLENGTH(data-value)--+
'-MAXFLENGTH(data-value)-'
>--+------------+--+-------------+-----------------------------><
'-NOTRUNCATE-' '-STATE(cvda)-'
Conditions: EOC, INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR
Description
CONVERSE sends, then receives,
data on an APPC mapped conversation.
Options
- 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).
For compatibility with
earlier releases, SESSION is accepted as a synonym for CONVID. New
programs should use CONVID.
If the option is omitted, the
principal facility for the task is used by default.
- 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. For a description of a safe upper
limit, see LENGTH options in CICS commands.
- 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 (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 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 is to be retained for retrieval by subsequent
RECEIVE commands.
- INTO(data-area)
- 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 connected to the other end of the current conversation.
- SET(ptr-ref)
- 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 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 current conversation. The cvda values returned by CICS are:
- ALLOCATED
- CONFFREE
- CONFRECEIVE
- CONFSEND
- FREE
- PENDFREE
- PENDRECEIVE
- RECEIVE
- ROLLBACK
- SEND
- SYNCFREE
- SYNCRECEIVE
- SYNCSEND
- TOFLENGTH(data-area)
- is a fullword alternative to
TOLENGTH.
- TOLENGTH(data-area)
- 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 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
- 06 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.
- 16 INVREQ
- RESP2 values:
- 200
- A distributed program link server application specified the function
shipping session (its principal facility)
also occurs (RESP2 not set) in any of the following
situations:
- The command is used on a conversation that is in use by CPI Communications,
or that is an APPC basic conversation. In the latter case, the application
should have issued a GDS SEND INVITE followed by a GDS RECEIVE.
Default action: terminate the task abnormally.
- 22 LENGERR
- occurs in any of the following
situations:
- Data 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.
- 61 NOTALLOC
- occurs if the facility specified
in the command is not owned by the application, or does not relate
to a conversation owned by the application.
Default action: terminate
the task abnormally.
- 24 SIGNAL
- 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
- 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) 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.