RECEIVE MAP
(
Receive screen input data from a terminal.
name
)
MAPSET (
name
) INTO
SET (
(
data-area ptr-ref
)
)
TERMINAL
ASIS
FROM (
data-area
)
LENGTH (
data-value
)
Conditions:
INVMPSZ, INVREQ, MAPFAIL, NOTAUTH
Description
The RECEIVE MAP command receives (maps) screen input data from a terminal into a data area in an application program. Data can also be received (mapped) from a data area of a program into which it has previously been read by the
RECEIVE command.
Following a RECEIVE MAP command, the inbound cursor position is placed in
EIBCPOSN, and the terminal attention identifier (AID) is placed in EIBAID.
If the map name is coded as a literal, the INTO and SET options can be omitted and RECEIVE MAP defaults to using INTO(‘mapnameI’), where ‘mapnameI’ is the map name suffixed with an “I”, meaning Input.
For further information about RECEIVE MAP, see “Receiving data from a display”
on page 160. See Appendix D, “BMS macro summary,” on page 553 for the map
definition macros.
Options
ASIS
specifies that lowercase characters in the 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 MAP command of a transaction.
It also has no effect if the screen contains data before a transaction is 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.
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
operand of the DFHMSD BMS map definition macro (see page 560).
INTO(
data-area
)
specifies the data area into which the mapped data is to be written. If the map
Chapter 32. Application programming commands - reference
415
name is coded as a literal, and INTO is not specified, the name of the data area defaults to the name of the map suffixed with an “I”. The data mapped into the specified area includes the 12-byte prefix generated by TIOAPFX.
LENGTH(
data-value
)
specifies as a halfword binary value the length of the data to be formatted. It must not exceed the length of the FROM data area. This should include the length of the 12-byte prefix generated by the TIOAPFX=YES operand of the
DFHMSD BMS map definition macro (see page 560).
For a description of a safe upper limit, see “LENGTH options” on page 312.
MAP(
name
)
specifies the name of the map to be used. The name can be up to 7 characters long.
MAPSET(
name
)
specifies either an unsuffixed or a suffixed name of the map set. An unsuffixed map set name can be up to 7 characters long, and a suffixed map set name can be from 2 through 8 characters long. The map set must reside in the library defined in the PPT. If *LIBL is used for the library of the map set, the map set must reside in the library list of the control region where the map is being used. If the MAPSET option is not specified, the name given in the MAP option is assumed to be that of the map set.
SET(
ptr-ref
)
specifies a pointer reference to be set to the address of the 12-byte prefix to the mapped data.
TERMINAL
specifies that input data is to be read from the terminal that originated the transaction.
Exception Conditions
Some of the following exception conditions may occur in combination with others.
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.
INVMPSZ
occurs if the specified map is too wide or too long for the terminal.
Default action: Terminate the task abnormally.
INVREQ
RESP2 values: v
200
A RECEIVE MAP command is issued in a nonterminal task; these tasks do not have a TIOA or a TCTTE.
The command is issued in a DPL server program.
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. 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 of the
RECEIVE MAP command. The input map is not set to nulls.
416
CICS for iSeries Application Programming Guide V5
