SEND MAP MAPPINGDEV

Create mapped output data to be sent to a terminal described by MAPPINGDEV at some later time. For further information about BMS, see the CICS® Application Programming Guide.

Minimum BMS:
Read syntax diagramSkip visual syntax diagram
SEND MAP MAPPINGDEV

>>-SEND MAP(name)--MAPPINGDEV(data-value)--SET(ptr-ref)--------->

>--+--------------+--------------------------------------------->
   '-MAPSET(name)-'   

>--+-+-----------------+--+----------+--+--------------------+-+-->
   | '-FROM(data-area)-'  '-DATAONLY-'  '-LENGTH(data-value)-' |   
   '-MAPONLY---------------------------------------------------'   

>--+-----------------------------+--+----------+---------------->
   '-CURSOR-+------------------+-'  '-FORMFEED-'   
            '-(--data-value--)-'                   

>--+----------+--+-------+--+--------+--+-------+--+-------+---><
   +-ERASE----+  '-PRINT-'  '-FREEKB-'  '-ALARM-'  '-FRSET-'   
   '-ERASEAUP-'                                                

Conditions: INVMPSZ, INVREQ

 

Description

SEND MAP MAPPINGDEV creates mapped output data to be sent to a terminal that is not the principal facility of the transaction. The terminal characteristics to be used are defined by MAPPINGDEV.

The mapped data is not transmitted but is returned to the application in a buffer defined by the SET option.

Options

ALARM
specifies that the 3270 audible alarm feature is to be activated. For logical units supporting FMHs (except interactive and batch logical units), ALARM instructs BMS to set the alarm flag in the FMH.

When using the ALARM option, refer to DFHMDI options, CTRL for a description of the option priority.

CURSOR(data-value)
specifies the location to which the 3270 cursor is to be returned upon completion of a SEND MAP MAPPINGDEV command.

The data value must be a halfword binary value that specifies the cursor position relative to zero; the range of values that can be specified depends on the size of the screen being used. If no data value is specified, symbolic cursor positioning is assumed. See the section about minimum BMS in the CICS Application Programming Guide for more information about symbolic cursor positioning.

This option overrides any IC option of the ATTRB operand of DFHMDF.

The value specified in the CURSOR option must be positive. A negative value leads to unpredictable results.

DATAONLY
specifies that only application program data is to be written. The attribute characters (3270 only) must be specified for each field in the supplied data. 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.
ERASE
specifies that the screen printer buffer is to be erased and the cursor returned to the upper left corner of the screen. (This option applies only to the 3270, or 8775)

The first output operation in any transaction, or in a series of pseudoconversational transactions, should always specify ERASE. For transactions attached to 3270 screens or printers, this also ensures that the correct screen size is selected, as defined for the transaction by the SCRNSIZE option in the RDO PROFILE definition.

ERASEAUP
specifies that before this page of output is displayed, all unprotected character locations in the entire screen are to be erased. (This option applies only to the 3270 and 8775.)
FORMFEED
specifies that a new page is required. For 3270 printers and displays, the FORMFEED character is positioned at the start of the buffer. The application program must thus ensure that this buffer position is not overwritten by map or text data. It is ignored if the target terminal does not support FORMFEED (that is, the RDO TYPETERM option FORMFEED was not used, or the terminal control table TYPE=TERMINAL does not specify FF=YES).
FREEKB
specifies that the 3270 keyboard should be unlocked after the data is written. If FREEKB is omitted, the keyboard remains locked.

When using the FREEKB option, refer to CTRL DFHMDI options, CTRL for a description of the option priority.

FROM(data-area)
specifies the data area containing the data to be processed. If this field is not specified, the name defaults to the name of the map suffixed with an O. This includes 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).
FRSET
specifies that the modified data tags (MDTs) of all fields currently in the 3270 buffer are to be reset to the unmodified condition (that is, field reset) before any map data is written to the buffer.

This 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.

When using the FRSET option refer to DFHMDI options, CTRL for a description of the option priority.

LENGTH(data-value)
specifies the length of the data to be formatted as a halfword binary value.

If the data area sending the map is longer than the data to be mapped, LENGTH should be specified. 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 BMS characteristics match those of the terminal to which the data will eventually be sent using a SEND TEXT MAPPED command or a terminal control SEND or CONVERSE.
MAPONLY
specifies that only default data from the map is to be written.
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.

The number of maps per mapset is limited to a maximum of 9 998.

PRINT
specifies that a print operation is to be started at a 3270 printer or at a 3275 with the printer adapter feature, or that data on an LUTYPE2 (3274/76 or 3790) is to be printed on a printer allocated by the controller. If this option is omitted, the data is sent to the printer buffer but is not printed.

When using the PRINT option, refer to DFHMDI options, CTRL for a description of the option priority.

SET(ptr-ref)
specifies the pointer to be set to the address of the mapped data.

The storage area containing the mapped data has the same format as the page buffer returned when using the SET option in the full BMS SEND command. See the description of the MAPPINGDEV facility in the CICS Application Programming Guide for more guidance about using the SET option.

Conditions

Some of the following conditions may occur in combination. If more than one occurs, only the first is passed to the application program.

INVMPSZ
occurs if the specified map is too wide for the terminal specified by MAPPINGDEV or if a HANDLE CONDITION OVERFLOW command is active and the specified map is too long for the terminal specified by MAPPINGDEV.

Default action: terminate the task abnormally.

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.