SEND MAP


SEND MAP used to send the output data to a terminal. SEND MAP used to send data to the terminal through application program. Before executing the SEND command, the application program should prepare the data in the symbolic map area layout.

If FROM is not coded, then CICS automatically finds the symbolic map area (mapnameO) for the corresponding MAP and send it to the terminal. The symbolic map area not filled automatically, and the garbage values may send to the screen if the symbolic map area not initialized.

Syntax -


SEND MAP Syntax

Parameters -


MAP(map-name) -

Specifies the map name that used to display on the terminal. Map name can be up to 7 characters long. Map name is an optional entry in SEND MAP. If the Map information is not provided, CICS assumes that Mapset name as a Map name.

Map should be defined under CICS table definitions. Map should be residing under CICS maps directory. If the map name is not a literal, FROM is required. If FROM is not specified, system try to get the data from the symbolic map area corresponding to map name.

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. Providing Mapset information is optional in SEND MAP.If the Mapset information is not provided, CICS assumes that MAP name as a MAPSET name.

FROM(input-data-area) -

Specifies the data area containing the data to be processed. FROM(input-data-area) is optional and not required to specify. If the FROM option is not specified, map displays with the map symbolic map area.

This includes the 12-byte prefix generated by the TIOAPFX=YES option on the DFHMDI and DFHMSD BMS map definitions. If the FROM option is not specified in COBOL, it defaults to the map name suffixed with O.

LENGTH(input-data-value) -

Specifies the length of the data to be formatted as a halfword binary value. If the data area sending to the map is longer than the data to be mapped, LENGTH should be specified.

The sending data area should not exceed the length of the mapped data area. This should include the length of the 12-byte prefix generated by the TIOAPFX=YES option on the DFHMDI and DFHMSD BMS map definitions.Length is a 16-bit binary value.

DATAONLY -

Specifies only application program data to be written. This is an optional entry in SEND MAP. The modification can be identified by using attribute byte.

Attribute byte will be individually associated with each field defined on the MAP. If the attribute byte in the user-supplied data is set to X'00', the attribute byte on the screen is unchanged.

Any default data or attributes from the map are ignored. If the attribute byte value is other than X’00’, then field data modified.

MAPONLY -

Specifies only default MAP data to be written to the screen. This is an optional entry in SEND MAP. It won’t add any data from application program to data area of screen if MAPONLY option specified.

If the MAPONLY option is specified, FROM option is not required. If MAPONLY coded along with FROM, FROM option gets ignored.

CURSOR(data-value) -

Specifies the cursor position in the map while sending the map. This is an optional entry in SEND MAP. Data-value is a 16-bit binary field which contains the cursor relative value. data-value starts from 0 and maximum value is depending on the size of the screen.

If no value specified, then the cursor will be positioned at the first unprotected field of the MAP which is a symbolic position. This value overrides the IC value of ATRRIB of DFHMDF macro.

The value specified in the cursor option, the value must be positive and should be greater than zero. If the negative value specified, then the cursor will be placed at the top left most corner of the MAP which is of position zero.

FORMFEED -

Specifies about the need of new page while sending a MAP to screen. This is an optional entry in SEND MAP. FORMFEED character is positioned at the start of the buffer for 3270 printers and displays.

Application program is responsible to ensure this buffer position is not overwritten by map or text data. FORMFEED is ignored if the target terminal does not support it.

ERASE -

This is an optional entry in SEND MAP. Erase option responsible for the below three tasks -

  • Erases the screen buffer or partition before sending the map to the screen.
  • Erases the screen print buffer before sending the map to the screen.
  • Places the cursor to the upper left corner of the MAP before sending the map to screen.

The first output operation in any transaction should always have the ERASE option to clear the screen before the map is displayed on the screen. Otherwise, the new map will be overwritten on the existing screen without clearing it.

In a similar way, first output operation in series of pseudo conversations should have ERASE option coded to clear the screen before output operation performed.

ERASEUP -

ERASEUP erases all unprotected character locations or fields on the screen before sending the map to the screen. This is an optional entry in SEND MAP. ERASEUP performs the task as a is part of ERASE option.

PRINT -

PRINT Specifies the map printing needs to be started at printer. This is an optional entry in SEND MAP. If the PRINT option is not specified, the data sent to print buffer but not printed.

FREEKB -

Specifies that the keyboard should be unlocked after the data written. This is an optional entry in SEND MAP. If the FREEKB option not specified, the keyboard remains locked.

ALARM -

Specifies that the 3270 audible alarm feature is to be activated. This is an optional entry in SEND MAP. ALARM instructs BMS to set the alarm flag in the FMH (Function Management Headers).

FRSET -

Specifies the modified data tags (MDTs) of all fields are to be reset to the unmodified condition before any map data is written to the buffer. This is an optional entry in SEND MAP. The reset process will be completed before written the data to terminal buffer.

If the FRSET option is not specified, the MDT of previous transactions may have overwritten the current SEND and might provide irrelevant results.

FRSET allows the ATTRB operand of DFHMDF for the requested map to control the final status of fields written or rewritten in response to a BMS command if no other attribute information has been written in the symbolic map.

NLEOM -

Specifies data for the printer should be built with blanks, new-line characters (NL) and an end-of-message character (EOM) should be placed at the end of the data.

Each NL character causes printing to continue on the next line and the EM character terminates printing. NLEOM option must be specified in the first SEND MAP command used to build a logical message.

The option is ignored if the device receiving the message is not with blank, new-line character or end-of-message. The NL character occupies a buffer position. The NLEOM option overrides the ALARM option if the latter is present.

ACCUM -

Used to build a logical message. The logical message is completed by a SEND PAGE command or deleted by a PURGE MESSAGE command.

SET(ptr-ref) -

Specifies the pointer to be set to the address of the input or output data. The SET option specifies that completed pages are to be returned to the application program.

The pointer is set to the address of completed pages list. The application program regains control immediately after the SEND MAP command.

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.

PAGING -

Specifies the output data is not to be sent immediately to the terminal. The output data is to be placed in temporary storage and displayed in response to paging commands entered by the terminal operator.If PAGING is specified with a REQID prefix that is used for recoverable temporary storage queues.

TERMINAL -

Specifies the output data is to be sent to the terminal that originated the transaction.

WAIT -

Specifies the control should not be returned to the application program until the output operation has been completed. If WAIT is not specified, control returns to the application program when the output operation has started. A subsequent input or output command causes the application program to wait until the previous command has been completed.

LAST -

Specifies this is the last output operation for a transaction. This option applies to logical units only.

REQID(name) -

Specifies a 2-character prefix to be as part of a temporary storage identifier for CICS message recovery. Only one prefix can be specified for each logical message. The default prefix is **.

NOFLUSH -

Specifies the CICS does not clear pages on completion but returns control to the program.

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.

Error ConditionRESP2, Description & SolutionSystem Action
16 INVREQ
200 - Command not allowed for a distributed program link server program.
Solution - Remove the command from the distributed link server program as it is not allowed. Code the program with SEND MAP and call it if want to receive the input from the terminal.
RESP2 not set
  • Text data is output to the same partition while a BMS logical message is active.
    Solution - Both serving the same purpose. Debug the application program and remove any one of them.
  • A separate SEND MAP command with the ACCUM option is issued to the terminal that initiated the transaction while a routed logical message is being built.
    Solution - In this case, both serving the same purpose. Either remove the ACCUM in SEND MAP command or remove the transaction initiation.
  • A SEND MAP command is issued for a map without field specifications by specifying the FROM option and without the DATAONLY option.
    Solution - Specify DATAONLY along with FROM option.
  • A SEND MAP command with the DATAONLY option is issued with a data area that resides above the 16MB line.
    Solution - Reduce the data area size and resend it.
Task abnormally terminated
32 RETPAGE
Occurs if the SET option is specified and a completed page is ready for return to the application program.
Solution - Modify the application program not to complete the page before SEND MAP when SET option is specified.
Return control to the application program at the point immediately after the BMS SEND MAP command.
35 TSIOERR
Occurs if there is an irrecoverable temporary storage input/output error.
Solution - Nothing required from application programmer end. Inform the error to storage support team and try after some time.
Task abnormally terminated
38 INVMPSZ
Occurs if the specified map is too wide for the terminal. Also occurs if a HANDLE CONDITION OVERFLOW command is active and the specified map is too long for the terminal.
Solution - Change the map width if the terminal width is global or change the terminal if the map width is global.
Task abnormally terminated
39 IGREQID
Occurs if the prefix specified in the REQID option is different from previous REQID option.
Solution - Debug the application program and find the previous REQID. Make sure the REQID should be same as previous REQID.
Task abnormally terminated
40 OVERFLOW
Occurs if the mapped data does not fit on the current page. This condition is only raised if a HANDLE CONDITION OVERFLOW command is active.
Solution - Reduce the mapped data size to fit the current page or remove the OVERFLOW condition if you don’t want to abend even though overflow occurs.
Ignore the condition