Receive data from an 8775 terminal partition. This
command is only available on standard and full BMS. For further information
about BMS, see the CICS® Application
Programming Guide.

RECEIVE PARTN
>>-RECEIVE PARTN(data-area)------------------------------------><
Standard and full BMS:

RECEIVE PARTN
>>-+-INTO(data-area)-+--LENGTH(data-value)--+------+-----------><
'-SET(ptr-ref)----' '-ASIS-'
Conditions: EOC, EODS, INVPARTN, INVREQ, LENGERR
Description
RECEIVE PARTN reads data from a partition
on an 8775 terminal. It indicates which partition the data came from, and
puts the data into the INTO or the SET data area. You can then treat the data
as though it had originated from a terminal in base (unpartitioned) state.
Following
a RECEIVE PARTN command, the inbound cursor position is placed in EIBCPOSN,
and the terminal attention identifier (AID) placed in EIBAID. EIBAID and
EIBCPOSN are also updated at task initiation for non-ATI tasks as well as
after each terminal control and BMS input.
See BMS macros for
map definitions.
If data is to be received, you must specify either
the INTO or the SET option. If a RECEIVE is issued purely to detect an attention
identifier (AID), you can omit both the INTO and the SET options.
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.
The ASIS option has no effect on the
first RECEIVE command of a transaction, or if the screen contains data prior
to a transaction being initiated. For example, if a transaction is initiated
by another transaction, and begins by receiving data originally output by
that transaction, it cannot suppress uppercase translation on the data. 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.
- INTO(data-area)
- specifies
the area into which the input data stripped of partition controls is to be
written. The length of this area must be specified by the LENGTH option. If
the area is not large enough to hold the input data, the input data is truncated,
and the LENGERR condition raised. The length option data area is set to the
length of data received, prior to any truncation.
- LENGTH(data-value)
- specifies
the length of the data to be formatted as a halfword binary value. It must
be set to the length of any INTO area prior to the command. After the command,
BMS sets the LENGTH option to the length of data received prior to any truncation
if the INTO area is too small.
For a description of a safe upper limit,
see LENGTH options in CICS commands.
- PARTN(data-area)
- is
set to the name (1–2 characters) of the input partition. The partition can
be defined either by using RDO or by program autoinstall when the partition
is first used.
- SET(ptr-ref)
- specifies
the pointer that is to be set to the address of the 12-byte prefix to the
mapped data. 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 may 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.
Conditions
Some of the following conditions can
occur in combination. If more than one occurs, only the first one is passed
to the application program.
- EOC
- occurs
if the request/response unit (RU) is received with the end-of-chain (EOC)
indicator set. It applies only to logical units.
Default action: ignore
the condition.
- EODS
- occurs
if no data is received (only an FMH). It applies only to 3770 batch LUs and
to 3770 and 3790 batch data interchange LUs.
Default action: terminate
the task abnormally.
- INVPARTN
- occurs
if the specified partition is not defined in the partition set associated
with the application program.
Default action: terminate the task abnormally.
- INVREQ
- occurs
if a RECEIVE PARTN command is issued in a nonterminal task; these tasks do
not have a TIOA or a TCTTE.
Default action: terminate the task abnormally.
- LENGERR
- occurs
if the INTO area of a RECEIVE PARTN command is not large enough to hold the
input data.
Default action: truncate the data to fit within the INTO area.