Communicate on a 2260 or 2265 display station.
CONVERSE (2260)
>>-CONVERSE--FROM(data-area)--+-FROMLENGTH(data-value)--+------->
'-FROMFLENGTH(data-value)-'
>--+-INTO(data-area)-+--+-TOLENGTH(data-area)--+---------------->
'-SET(ptr-ref)----' '-TOFLENGTH(data-area)-'
>--+------------------------+--+------------+------------------->
+-MAXLENGTH(data-value)--+ '-NOTRUNCATE-'
'-MAXFLENGTH(data-value)-'
>--+---------------------+--+----------------------+------------>
'-CTLCHAR(data-value)-' '-LINEADDR(data-value)-'
>--+---------+-------------------------------------------------><
'-LEAVEKB-'
Condition: LENGERR
Description
CONVERSE communicates on a
2260 or 2265 display station.
Options
- CTLCHAR(data-value)
- specifies a 1-byte write control
character (WCC) that controls the CONVERSE command. (The WCC is documented
in the IBM® 3270 Data Stream
Programmer's Reference manual.) A COBOL user must specify a
data area containing this character. If the option is omitted, all
modified data tags are reset to zero and the keyboard is restored.
- 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.
- LEAVEKB
- specifies that the keyboard
is to remain locked at the completion of the data transfer.
- LINEADDR(data-value)
- specifies that the writing
is to begin on a specific line of a 2260/2265 screen. The data value
is a halfword binary value in the range 1 through 12 for a 2260, or
1 through 15 for a 2265.
- 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.
- 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.
- 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
- 22 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.