RECEIVE MAP MAPPINGDEV

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.