Receive screen input into an application data area, without
reference to the principal facility, if any. Terminal characteristics
are obtained from the MAPPINGDEV parameter.
RECEIVE MAP MAPPINGDEV
>>-RECEIVE MAP(name)--MAPPINGDEV(data-value)--FROM(data-area)--->
>--+--------------------+--+--------------+--------------------->
'-LENGTH(data-value)-' '-MAPSET(name)-'
>--+-----------------+-----------------------------------------><
+-INTO(data-area)-+
'-SET(ptr-ref)----'
Conditions: INVMPSZ, INVREQ, MAPFAIL,
Description
RECEIVE MAP MAPPINGDEV allows
the mapping of input data from a 3270 terminal that is not necessarily
the principal facility of the transaction.
MAPPINGDEV specifies
the name of a 3270 terminal whose BMS characteristics were used to
create the input data stream. This might be a terminal from which
the data was originally received using a RECEIVE command.
Options
- AID(data-value)
- Specifies
the one-byte data area containing the value of the 3270 attention
identifier (AID) to be used when performing the mapping operation.
Usually this will be the value contained in EIBAID following the RECEIVE
operation that originally received the datastream from the terminal.
The value specified is moved into field EIBAID in the EXEC interface
block on completion of the operation. No check is made that the AID
value specified is valid.
If AID(data-value) is not specified,
then the AID value defaults to X'7D' (the Enter key).
If the
AID byte (either explicitly, or by default) indicates an operation
other than CLEAR, PA1, PA2, or PA3, and CURSLOC=YES is specified for
the map, then the field containing the cursor is flagged by setting
the X'02' bit in its flag byte.
If the AID (whether specified
explicitly, or by default) is the subject of a HANDLE AID command,
the specified branch will be taken in the usual way.
- CURSOR(data-value)
- Specifies
an unsigned halfword binary field containing the cursor position (relative
to zero) to be used. Usually this will be the value contained in EIBCPOSN
following the RECEIVE operation that originally received the datastream
from the terminal.
The value specified is moved into EIBCPOSN
in the EXEC interface block on completion of the operation. No check
is made that the CURSOR value specified is valid.
If CURSOR(data-value)
is not specified, then the cursor value defaults to X'0000'.
- FROM(data-area)
- Specifies
the data area containing the data to be mapped. This must be in the
format of a TIOA and must contain a 12-byte prefix.
- 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.
- MAPPINGDEV(data-value)
- Specifies the name of a 3270 terminal
whose characteristics match those of the terminal from which the data
was originally received using a RECEIVE command.
- 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 or RECEIVE MAP command, or until the end of the transaction,
unless the application releases it by using a FREEMAIN request.
If
TASKDATALOC(ANY) is specified for the running task, the data returned
may be above or below the 16MB line.
If TASKDATALOC(BELOW)
is specified for the running task,the data returned is below the 16MB
line.
If TASKDATAKEY(USER) is specified for the running task,
and storage protection is active, the data returned is in user-key.
If TASKDATAKEY(CICS) is specified and storage protection is active,
the data returned is in CICS-key.
Conditions
Some of the following conditions
may occur in combination. If more than one occurs, only the first
is passed to the application program.
- 38 INVMPSZ
- occurs if the specified map is too
wide or too long for the terminal.
Default action: terminate the
task abnormally.
- 16 INVREQ
- occurs
if the terminal specified by MAPPINGDEV does not exist, does not support
BMS, or is not a 3270 printer or display.
Default action: terminate
the task abnormally.
- 36 MAPFAIL
- occurs if the data to be mapped has
a length of zero or does not contain a set-buffer-address (SBA) sequence.
Default action: terminate the task abnormally.