Used to receive the screen input entered by the user into application program data area. It 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.

Syntax -

If require receiving the data, either the INTO or the SET option must have specified. If a RECEIVE is issued purely to detect an attention identifier (AID), both the INTO and the SET options can be omitted.

The cursor position will be placed in EIBCPOSN and terminal attention identifier information stored in EIBAID immediately after RECEIVE MAP command.

Parameters -

MAP (map-name) -

Specifies the map name that used to receive the data. Map name can be up to 7 characters long. Map should be defined under CICS table definitions. Map should be residing under CICS maps directory. Map name is an optional entry in RECEIVE MAP.

If the Map name is not a literal, SET or INTO is required. If SET or INTO is not specified, it will try to place the received information to the map data area.

MAPSET(mapset-name) -

Specifies the mapset name where the map is part of. Mapset name can be 7-character long which is a combination of alphabets and numbers. Mapset should be defined under CICS table definitions.

Mapset should be resides under CICS maps directory. Mapset information is optional in RECEIVE MAP. If the Mapset information is not provided, CICS assumes that MAP name as a MAPSET name.

INTO(data-area) -

Specifies the data area where the received data needs to be written. If INTO field is not specified, the name defaults to the name of the map suffixed with an I.

If INTO is not coded, then CICS automatically finds the symbolic map area for the MAP and places the data to the corresponding input fields. The field values can be read in the program by referring to fieldname+I.

SET(Ptr-ref) -

Sets the pointer reference to the map data area stored in the memory location. Pointer concept mostly used in distributed environment where the transaction needs to run on the remote system.

Pointer reference valid until next receive command or the control moved out of the program or end of the task. Specifies the pointer to be set to the address of the 12-byte prefix to the mapped data.

The 12-byte prefix is generated by the TIOAPFX=YES option on the DFHMDI and DFHMSD BMS map definitions. If TIOAPFX=YES is specified in map definition, the pointer contains the address of the TIOA prefix and user data starts at offset X'0C' from the start of the TIOA prefix.

TERMINAL -

Specifies from where the data needs to read from the terminal that initiated the transaction. If FROM and LENGTH specified, it takes from the corresponding group data items. TERMINAL is mandatory if FROM and LENGTH is not specified.

FROM(data-area) -

Specifies the data area to be mapped by a RECEIVE MAP command. The data-area includes the 12-byte prefix generated by the TIOAPFX=YES option on the DFHMDI and DFHMSD BMS map definitions.

LENGTH(data-value) -

Specifies the data length to be formatted as a halfword binary value. data-value must not exceed the length of the FROM data area. The data-value includes the 12-byte prefix generated by the TIOAPFX=YES option on the DFHMDI and DFHMSD BMS map definitions.

ASIS -

Specifies the data entered to the screen will not be converted to uppercase. This allows the current task to receive a message containing both uppercase and lowercase data from the map. ASIS option has no impact on first RECEIVE MAP command of a transaction or if the screen contains data before a transaction being initiated.

Error Conditions -

Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.