Sends mapped output data to a terminal.
Syntax
SEND MAP >>-SEND MAP(name)--+--------------+-----------------------------> '-MAPSET(name)-' >--+-------------------------------------------------------+----> '-FROM(data-area)--+--------------------+--+----------+-' '-LENGTH(data-value)-' +-DATAONLY-+ '-MAPONLY--' >--+--------------------------+--+----------+--+----------+-----> '-CURSOR--+--------------+-' '-FORMFEED-' +-ERASE----+ '-(data-value)-' '-ERASEAUP-' >--+-------+--+--------+--+-------+--+-------+----------------->< '-PRINT-' '-FREEKB-' '-ALARM-' '-FRSET-'
Conditions: INVREQ, INVMPSZ, LENGERR
Description
SEND MAP sends mapped output data to a terminal.
- The user calls EXEC CICS RELEASE API to unload that map.
- No tasks are referencing the map and the Task Shared Pool threshold has been exceeded.
Use of the ALARM, FREEKB, FRSET, or PRINT options overrides all the CTRL options that are specified in the DFHMSD and DFHMDI macros that are used to define the map. Refer to the CTRL option description in DFHMDI.
For further information about Basic Mapping Support (BMS), see Using Basic Mapping Support (BMS) in CICS.
For the map definition macros, see Supported BMS definition macros.
Options
- ALARM
- Specifies that the alarm feature is to be activated.
- CURSOR(data-value)
- Specifies,
as a 16-bit binary value, the position to which the cursor is to be returned
on completion of a SEND MAP command.
The supplied value gives the cursor position relative to zero; the range of possible values depends on the size of the screen that is being used. If no value is supplied, symbolic cursor positioning is assumed.
For more information about symbolic cursor positioning, see TXSeries for Multiplatforms Application Programming Guide.
This option overrides any IC value of the ATTRB operand of the DFHMDF macro.
The value that is specified in the CURSOR option must be positive. A negative value causes the cursor to be positioned at the upper left corner of the screen (that is, at position zero).
- DATAONLY
- Specifies that only application program data is to be written. The attribute characters must be specified for each field that is in the supplied data. If the attribute characters in the user-supplied data are all set to X'00', the attribute byte that is on the screen is unchanged. Any default data or attributes from the map are ignored.
- ERASE
- Specifies that the screen or printer buffer is to be erased and the cursor returned to the upper left corner of the screen before the map is displayed. The first output operation in any transaction, or in a series of pseudoconversational transactions, should always specify ERASE.
- ERASEAUP
- Specifies that before this map is displayed, all unprotected character locations on the whole screen are to be erased.
- FORMFEED
- Specifies that a new page is required. The FORMFEED character is positioned at the start of the buffer. The application program must therefore ensure that this buffer position is not overwritten by map or text data.
- FREEKB
- Specifies that the keyboard is to be unlocked after the data is written.
- FROM(data-area)
- Specifies
the data area that contains the data that is to be processed. If this field
is not specified, the name defaults, for COBOL, to the name of the map that
is suffixed with an O; for C or C++, the name defaults
to:
&mapname.mapnameowhere mapname is the name of the map.
- FRSET
- Specifies
that the Modified Data Tags (MDTs) of all fields that are currently in the
terminal buffer are to be reset to the not-modified condition before the map
data is written to the buffer. If this option is omitted, MDTs that are turned
on by a previous operation remain on until overwritten by a subsequent SEND
command.
This allows the ATTRB operand of the DFHMDF macro for the requested map to control the final status of fields that are written or rewritten in response to a BMS command.
- LENGTH(data-value)
- Specifies,
as a 16-bit binary value, the length of the data that is to be formatted.
If the data area that is sending the map is longer than the data that is to be mapped, LENGTH should be specified.
- MAP(name)
- Specifies
the name of the map that is to be used. The map name can be up to seven characters
long.
If a map name is not a literal, FROM is required. This is because, if FROM is not specified, the FROM data-area is defaulted from the map name. For more information about using this option, see LENGTH.
- MAPONLY
- Specifies that only default data from the map is to be written. If this option is specified, the FROM option must not be specified.
- MAPSET(name)
- Specifies the name of the map set that is to be used. The map set name can be up to seven characters long. The map set must reside in a CICS® maps. directory, and must have an entry in the Program Definitions (PD) with the ProgType attribute set to map. If the MAPSET option is not specified, the name that is given in the MAP option is assumed to be that of the map set.
- Specifies that a print operation is to be started at a printer. If this option is omitted, the data is sent to the printer buffer but is not printed.
Conditions
- INVMPSZ
- Occurs
if the specified map is too wide or too long for the terminal.
Default action: Terminates the task abnormally.
- INVREQ
- Occurs
for the following condiions, depending on the options that are specified on
the SEND MAP command:
- The DATAONLY option is being used and the value of the LENGTH option is twelve or less.
- An attempt is made to issue a SEND MAP command from a remotely linked-to program.
- A remotely linked-to program attempted to execute a SEND MAP command that refers to the principal facility.
Default action: Terminates the task abnormally.
- LENGERR
- Occurs
when the LENGTH option is zero or negative.
Default action: Terminates the task abnormally.