Route a BMS message. This command is only available on
full 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 Route list format 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 Message identification for
the format of the title option.
Conditions
- 39 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 (**).
- 37 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.
- 41 INVLDC
- occurs
if the specified LDC mnemonic is not included in the LDC list for
the logical unit.
Default action: terminate the task abnormally.
- 16 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.
- 33 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.
- 34 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.