Common options used on the RECEIVE command (z/OS® Communications Server).
Options
- ASIS
- specifies that lowercase characters
in the 3270 input data stream are not translated to uppercase; this
allows the current task to receive a message containing both uppercase
and lowercase data.
This option has no effect on the first RECEIVE
command of a transaction, because terminal control performs a READ
INITIAL and uses the terminal defaults to translate the operation
data.
This option has no effect if the screen contains data
before a transaction being initiated. This data is read and translated
in preparation for the next task and the first RECEIVE command in
that task retrieves the translated 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.
- BUFFER
- specifies that the contents
of the 3270 buffer are to be read, beginning at buffer location 1
and continuing until all contents of the buffer have been read. All
character and attribute sequences (including nulls) appear in the
input data stream in the same order as they appear in the 3270 buffer.
- 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 this option is omitted, the
principal facility is assumed.
- FLENGTH(data-area)
- An alternative to LENGTH. For
architectural reasons, this option is limited to a maximum of 32K
for all terminal-related RECEIVE commands.
- INTO(data-area)
- specifies the receiving field
for the data read from the logical unit or terminal, 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.
- LENGTH(data-area)
- specifies the length, as a
halfword binary value, of the data received.
If you specify the
INTO option, but omit the MAXLENGTH option, the argument must be a
data area that specifies the maximum length that the program accepts.
If the value specified is less than zero, zero is assumed.
If
you specify the SET option, the argument must be a data area. When
the data has been received, the data area is set to the length of
the data.
- MAXFLENGTH(data-value)
- A fullword alternative to MAXLENGTH.
- MAXLENGTH(data-value)
- specifies the maximum amount
(halfword binary value) of data that CICS® is
to recover. If INTO is specified, MAXLENGTH overrides the use of LENGTH
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 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 LENGTH 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 LENGTH option is set to the length
of data returned.
If this option is omitted, the value indicated
in the LENGTH option is assumed.
- 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 this option is omitted, the principal facility
for the task is used.
- SET(ptr-ref)
- specifies the pointer reference that
is to be set to the address of the data read from the logical unit
or terminal, or the partner transaction. The pointer reference
is valid until the next receive 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
Conditions
Some of the following conditions may occur in
combination with others. CICS checks
for these conditions in the following order:
- EODS
- 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.
- 06 EOC
- occurs when a request/response
unit (RU) is received with end-of-chain-indicator set. Field EIBEOC
also indicates this condition.
Default action: ignore the condition.
- 05 EODS (interpreter logical unit only)
- occurs when an end-of-data-set
indicator is received.
Default action: terminate the task abnormally.
- 07 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.
- 16 INVREQ
- RESP2 values:
- 200
- A distributed program link server application specified the function-shipping
session (its principal facility) on the CONVID option.
also occurs (RESP2 not set) in any of the following
situations:
- The command is used on an APPC conversation that is not using
the EXEC CICS interface or
that is not a mapped conversation.
Default action: terminate the task abnormally.
- 22 LENGERR
- occurs if data is discarded
by CICS because its length
exceeds the maximum the program accepts and the NOTRUNCATE option
is not specified.
Default action: terminate the task abnormally.
- 61 NOTALLOC
- occurs if the RECEIVE command
is issued by a transaction that has been started as a nonterminal
task by the START command, or if the CONVID value or facility specified
in the command 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 partner transaction.
EIBSIG is always set when an inbound signal is received.
Default
action: ignore the condition.
- 81 TERMERR
- occurs for a session-related
or terminal-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.