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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.