- ALTERNATE
- sets
the terminal to use the ALTERNATE screen size.
- ASIS
- indicates
that output is to be sent in transparent mode (with no recognition of control
characters and accepting any of the 256 possible combinations of eight bits
as valid transmittable data).
Note: If you are using a katakana
terminal, you might see some messages containing mixed English and katakana
characters. That is because katakana terminals cannot display mixed-case output.
Uppercase characters in the data stream appear as uppercase English characters,
but lowercase characters appear as katakana characters. If this happens, ask
your system programmer to specify MSGCASE=UPPER in the system initialization
parameters so that messages contain uppercase characters only. This
note applies to any command that is used to receive katakana characters, not
just to CONVERSE commands.
- 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).
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.
- CTLCHAR(data-value)
- specifies
a 1-byte write control character (WCC) that controls the CONVERSE command.
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.
- DEFAULT
- sets
the terminal to use the DEFAULT screen size.
- DEFRESP
- indicates
that a definite response is required when the output operation has been completed.
- ERASE
- specifies
that the screen printer buffer or partition is to be erased and the cursor
returned to the upper left corner of the screen. (This option applies only
to the 3270, or 8775, and to the 3604 Keyboard Display.)
The first output
operation in any transaction, or in a series of pseudoconversational transactions,
should always specify ERASE. For transactions attached to 3270 screens or
printers, unless explicitly overridden by the DEFAULT or ALTERNATE option,
this also ensures that the correct screen size is selected, as defined for
the transaction by the SCRNSIZE option in the RDO PROFILE definition.
- 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.
The use of FMH is optional and is not supported
for all terminal types. If not supplied, CICS takes no action, except for
3600/4700 terminals, where an FMH is mandatory. In this case, if FMH is not
specified, CICS supplies one and places it in the first 3 bytes of the message,
which you must reserve for this purpose.
- 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.
- 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.
- LDC(name)
- specifies
the 2-character mnemonic used to determine the appropriate logical device
code (LDC) numeric value. The mnemonic identifies an LDC entry defined by
a DFHTCT TYPE=LDC macro.
- 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.
- 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
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
- STRFIELD
- specifies
that the data area specified in the FROM option contains structured fields.
If this option is specified, the contents of all structured fields must be
handled by the application program. The CONVERSE command must be used if the
data area contains a read partition structured field. (Structured fields are
described in the CICS 3270 Data Stream Device Guide.)
CTLCHAR
and ERASE are mutually exclusive with STRFIELD, and their use with STRFIELD
generates an error message.
- 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.