Receive screen input into an application data area. For
further information about BMS, see the CICS® Application
Programming Guide.

RECEIVE MAP
>>-RECEIVE MAP(name)--+--------------+--+-----------------+----->
'-MAPSET(name)-' +-INTO(data-area)-+
'-SET(ptr-ref)----'
.-TERMINAL--------------------------------.
>--+-----------------------------------------+-----------------><
+-FROM(data-area)--+--------------------+-+
| '-LENGTH(data-value)-' |
'-TERMINAL--+------+--+---------------+---'
'-ASIS-' '-INPARTN(name)-'
Conditions: EOC, EODS, INVMPSZ, INVPARTN, INVREQ, MAPFAIL, PARTNFAIL,
RDATT, UNEXPIN
Note: INPARTN is supported by Standard and full BMS
Description
RECEIVE MAP maps input data from a
terminal into a data area in an application program.
Data from certain
logical units is not mapped, but is left unaltered. Refer to the appropriate CICS subsystem
guide to see if this is true for a particular logical unit.
Following
a RECEIVE MAP command, the inbound cursor position is placed in EIBCPOSN,
and the terminal attention identifier (AID) placed in EIBAID.
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.
This 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.
- FROM(data-area)
- specifies
the data area containing the data to be mapped by a RECEIVE MAP command. This
includes the 12-byte prefix generated by the TIOAPFX=YES option on the DFHMDI
and DFHMSD BMS map definitions (see DFHMDI
operands, TERM and specifying
NODDS in the BMS operand).
- INPARTN(name)
- specifies
the name (1–2 characters) of the partition in which the terminal operator
is expected to enter data. If the terminal operator enters data in some other
partition, the INPARTN partition is activated, the keyboard is unlocked for
the partition, and an error message is output to any error message partition.
This option is ignored if the terminal does not support partitions, or if
there is no application partition set.
- INTO(data-area)
- specifies
the data area into which the mapped data is to be written. If this field is
not specified, the name defaults to the name of the map suffixed with an I.
- LENGTH(data-value)
- specifies
the length of the data to be formatted as a halfword binary value. It must
not exceed the length of the FROM data area, but this should include the length
of the 12-byte prefix generated by the TIOAPFX=YES option on the DFHMDI and
DFHMSD BMS map definitions (see DFHMDI
operands, TERM and specifying
NODDS in the BMS operand).
For a description of a safe upper limit,
see LENGTH options in CICS commands.
- MAP(name)
- specifies
the name (1–7 characters) of the map to be used.
- MAPSET(name)
- specifies
the unsuffixed name (1–7 characters) of the mapset to be used. The mapset
must reside in the CICS program library. The mapset can be defined either
by using RDO or by program autoinstall when the mapset is first used. If this
option is not specified, the name given in the MAP option is assumed to be
that of the mapset.
- 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.
- TERMINAL
- specifies
that input data is to be read from the terminal that originated the transaction.
Conditions
Some of the following conditions can
occur in combination. 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.
- 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.
- INVMPSZ
- occurs
if the specified map is too wide or too long for the terminal.
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 MAP command is issued in a nonterminal task; these tasks do not
have a TIOA or a TCTTE.
Default action: terminate the task abnormally.
- MAPFAIL
- occurs
if the data to be mapped has a length of zero or does not contain a set-buffer-address
(SBA) sequence. It applies only to 3270 devices. The receiving data area contains
the unmapped input data stream. The amount of unmapped data moved to the user's
area is limited to the length specified in the LENGTH option. The input map
is not set to nulls.
This condition also arises if a program issues a
RECEIVE MAP command to which the terminal operator responds by pressing a
CLEAR or PA key, or by pressing ENTER or a PF key without entering data.
Default
action: terminate the task abnormally.
- PARTNFAIL
- occurs
if the terminal operator attempts to enter data more than three times in a
partition other than that specified by the INPARTN option.
Default action:
terminate the task abnormally.
- RDATT
- occurs
if a RECEIVE MAP command is terminated by the operator using the ATTN key
rather than the RETURN key. It applies only to the 2741 Communications Terminal,
and only if 2741 read attention support has been generated for CICS.
Default
action: ignore the condition.
- UNEXPIN
- occurs
when unexpected or unrecognized data is received. This only applies to batch
data interchange terminals.
Default action: terminate the task abnormally.