Route a BMS message. (This command is only available on full
BMS. The CICS® Application
Programming Guide has further information about BMS.)

ROUTE
.-INTERVAL(0)------------------------.
>>-ROUTE--+------------------------------------+---------------->
+-INTERVAL(hhmmss)-------------------+
+-TIME(hhmmss)-----------------------+
| .-------------------------. |
| V | |
+-AFTER----+-HOURS(data-value)---+-+-+
| +-MINUTES(data-value)-+ |
| '-SECONDS(data-value)-' |
| .-------------------------. |
| V | |
'-AT----+-HOURS(data-value)---+-+----'
+-MINUTES(data-value)-+
'-SECONDS(data-value)-'
>--+------------------------+--+------------------+------------->
'-ERRTERM-+------------+-' '-TITLE(data-area)-'
'-(--name--)-'
>--+-----------------+--+--------------------+------------------>
'-LIST(data-area)-' '-OPCLASS(data-area)-'
>--+-------------+--+-----------+--+-------+-------------------><
'-REQID(name)-' '-LDC(name)-' '-NLEOM-'
Conditions: IGREQID, INVERRTERM, INVLDC, INVREQ, RTEFAIL, RTESOME
Description
ROUTE routes a BMS logical message
to one or more terminals or terminal operators.
The default is INTERVAL(0),
but for C the default is AFTER HOURS(0) MINUTES(0) SECONDS(0).
Options
- AFTER
- specifies
the amount of time to elapse before the route.
There are two ways to
enter the time under AFTER and AT.
- A combination of at least two of HOURS(0–99), MINUTES(0–59), and SECONDS(0–59).
HOURS(1) SECONDS(3) would mean one hour and three seconds (the minutes default
to zero).
- As one of HOURS(0–99), MINUTES(0–5999), or SECONDS(0–359 999). HOURS(1)
means one hour. MINUTES(62) means one hour and two minutes. SECONDS(3723)
means one hour, two minutes, and three seconds.
- AT
- specifies
the time of the route. For the ways to enter the time, see the AFTER option.
- ERRTERM(name)
- specifies
the name of the terminal to be notified if the message is deleted because
it is undeliverable. The message number, title identification, and destination
are indicated. If no name is specified, the originating terminal is assumed.
This option is effective only if PRGDLAY has been specified in the system
initialization parameters.
- HOURS(data-value)
- specifies
a fullword binary value in the range 0–99. This is a suboption of the AFTER
and AT options. For its use and meaning, see the AFTER option.
- INTERVAL(hhmmss)
- specifies
the interval of time after which the data is to be transmitted to the terminals
specified in the ROUTE command. The mm and ss are in the range
0–59.
When using the C language, you are recommended to use the AFTER/AT
HOURS, MINUTES, and SECONDS options as C does not provide a packed decimal
data type. You may use INTERVAL, but if the value specified is not an
integer constant, the application is responsible for ensuring that the value
passed to CICS is
in packed decimal format.
- LDC(name) — logical units only
- specifies
a 2-character mnemonic to be used to determine the logical device code (LDC)
to be transmitted in the FMH to the logical unit. The mnemonic identifies
an LDC entry defined by the DFHTCT TYPE=LDC macro.
When an LDC is specified,
BMS uses the device type, the page size, and the page status associated with
the LDC mnemonic to format the message. These values are taken from the extended
local LDC table for the LU, if it has one. If the LU has only a local (unextended)
LDC table, the values are taken from the system LDC table. The numeric value
of the LDC is obtained from the local LDC table, unless this is an unextended
table and the value is not specified, in which case it is taken from the system
table.
If the LDC option is omitted, the LDC mnemonic specified in
DFHMSD is used; see
DFHMSD for
further details. If the LDC option has also been omitted from DFHMSD, the
action depends on the type of logical unit, as follows:
- 3601 LU
- The first entry in the local or extended local LDC table is used, if there
is one. If a default cannot be obtained in this way, a null LDC numeric value
(X'00') is used. The page size used is the value that is specified
by the RDO TYPETERM options PAGESIZE or ALTPAGE, or (1,40) if such a value
is not specified.
- LUTYPE4 LU, batch LU, or batch data interchange LU
- The local LDC table is not used to supply a default LDC; instead, the
message is directed to the LU console. (Here, LU console means any medium
on which the LU elects to receive such messages. For a batch data interchange
LU, this does not imply sending an LDC in an FMH). The page size is obtained
in the manner described for the 3601 LU.
For message routing, the LDC option of the ROUTE command
takes precedence over all other sources. If this option is omitted and a route
list is specified (LIST option), the LDC mnemonic in the route list is used;
if the route list contains no LDC mnemonic, or no route list is specified,
a default LDC is chosen as described above.
- LIST(data-area)
- specifies
the data area that contains a list of terminals and operators to which data
is to be directed. If this option is omitted, all terminals supported by BMS
receive the data (unless the OPCLASS option is in effect). See the CICS Application Programming Guide for
the format of the route list.
- MINUTES(data-value)
- specifies
a fullword binary value in the range 0–59, when HOURS or SECONDS are also
specified, or 0–5999 when MINUTES is the only option specified. This is a
suboption of the AFTER and AT options. For its use and meaning, see the AFTER
option.
- NLEOM
- specifies
that data for a 3270 printer or a 3275 display with the printer adapter feature
should be built with blanks and new-line (NL) characters, and that an end-of-message
(EM) character should be placed at the end of the data. As the data is printed,
each NL character causes printing to continue on the next line, and the EM
character terminates printing.
The option is ignored if the device receiving
the message (direct or routed) is not one of those mentioned above.
If
this option is used, buffer updating and attribute modification of fields
previously written into the buffer are not allowed. CICS includes the ERASE
option with every write to the terminal.
The NL character occupies
a buffer position. A number of buffer positions, equivalent to the value of
the RDO options PAGESIZE or ALTPAGE for that terminal, are unavailable for
data. This may cause data to wrap around in the buffer; if this occurs, the
PAGESIZE or ALTPAGE value must be reduced.
- OPCLASS(data-area)
- specifies
the data area that contains a list of operator classes to which the data is
to be routed. The classes are supplied in a 3-byte field, each bit position
corresponding to one of the codes in the range 1 through 24 but in reverse
order, that is, the first byte corresponds to codes 24 through 17, the second
byte to codes 16 through 9, and the third byte to codes 8 through 1.
- REQID(name)
- specifies
a prefix (2–character field) to be used 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 **.
BMS message recovery is provided for
a logical message only if the PAGING option is specified in the BMS SEND commands,
and if the syncpoint has been reached.
- SECONDS(data-value)
- specifies
a fullword binary value in the range 0–59, when HOURS or MINUTES are also
specified, or 0–359 999 when SECONDS is the only option specified. This is
a suboption of the AFTER and AT options. For its use and meaning, see the
AFTER option.
- TIME(hhmmss)
- specifies
the time of day at which data is to be transmitted to the terminals specified
in the ROUTE command.
When using the C language, you are recommended
to use the AFTER/AT HOURS, MINUTES, and SECONDS options as C does not provide
a packed decimal data type. You may use TIME, but if the value specified is not an
integer constant, the application is responsible for ensuring that the value
passed to CICS is in packed decimal format.
- TITLE(data-area)
- specifies
the data area that contains the title to be used with a routing logical message.
This title appears as part of the response to a page query command. See the CICS Application Programming Guide for
the format of the title option.
Conditions
- IGREQID
- occurs
if the prefix specified in the REQID option is different from that established
by a previous REQID option, or by default for this logical message—REQID (**).
- INVERRTERM
- occurs
if the terminal identifier specified in the ERRTERM option is not valid or
is assigned to a type of terminal not supported by BMS.
Default action:
terminate the task abnormally.
- INVLDC
- occurs
if the specified LDC mnemonic is not included in the LDC list for the logical
unit.
Default action: terminate the task abnormally.
- INVREQ
- RESP2
values:
- 4
- Hours out of range
- 5
- Minutes out of range
- 6
- Seconds out of range
- 200
- BMS commands are not supported for distributed program link.
also occurs (RESP2 not set) in the following situations:
- Bytes 10 through 15 of a route list entry do not contain blanks.
Default action: terminate the task abnormally.
- RTEFAIL
- occurs
in any of the following situations:
- A ROUTE command would result in the message being sent only to. the terminal
that initiated the transaction.
- A ROUTE command is issued against a remote. shippable terminal that is
not yet installed in the application-owning region.
Default action: return control to the application program at the
point immediately following the ROUTE command.
- RTESOME
- occurs
if any of the terminals specified by the ROUTE command options do not receive
the message.
Default action: return control to the application program
at the point immediately following the ROUTE command.