CMSG command

Read syntax diagramSkip visual syntax diagramCMSG
 
>>-CMSG--+------+--'message'------------------------------------>
         '-MSG=-'
 
>--+-------------------------------------------------+---------->
   |            .---------------.                    |
   |            V               |                    |
   '-,ROUTE=--+---Termid--/opid-+------------------+-'
              +-ALL--------------------------------+
              | .-----------.  .-----------------. |
              | V           |  V                 | |
              '---.termlist-+----,±termid--/opid-+-'
 
   .----------------.
   V                |
>----+------------+-+--+-------------+--+-----------------+----->
     '-,OPCLASS=n-'    '-,TIME=value-'  +-,DATE=value-----+
                                        '-,FULLDATE=value-'
 
>--+----------------------+--+-------------+-------------------->
   '-,ERRTERM=-+-Termid-+-'  '-,ID=(title)-'
               '-ORIG---'
 
>--+-------------------+--+----------------------+-------------->
   '-,HEADING=-+-YES-+-'  '-,PROTECT=-+-YES----+-'
               '-NO--'                +-NO-----+
                                      '-Prefix-'
 
>--+-,SEND---+-------------------------------------------------><
   '-,CANCEL-'
 

CMSG command options

The message-switching options are listed below. Except for CANCEL, you can specify the first letter of each option instead of the entire option.

CANCEL
specifies that the current input is to be ignored and institutes a non-conversational status between the terminal and the message-switching transaction. CANCEL must be the last 6 characters of the input. CANCEL is also effective within a message.
DATE=value
The date on which you want your message to be delivered. It can be specified in any of the following forms:
yy.ddd
year (00-99) and day (001-366).
mm/dd/yy
month (01-12), day (01-31), and year (00-99).
mm/dd
month (01-12) and day (01-31).
+d
number of days (0-4).

The first three of these forms provide ways of specifying absolute dates, with the year (where used) in a 2-digit format. For example, if the current system3 date is in the year 1997, January 31 1997 could be specified as 97.031, 01/31/97, or 01/31. In this last case, the year of the current system3 date is assumed to be the year for delivery of the message.

If DATFORM=DDMMYY was specified in the CICS system initialization parameters, enter the second and third of these as dd/mm/yy or dd/mm.

The fourth form allows you to specify a number of days from today. For example, a value of DATE=+3 (or D=+3) means that the message is to be transmitted 3 days from today. The number must be in the range 0-4. DATE=+d entries are not accepted when the system3 time is between 2330 and 0030, (to avoid confusion at or near midnight). If you use this form of the command within 30 minutes of midnight, the following error message is issued:

   +DATE INVLD FROM 2330 to 0030

You can also specify a time for message delivery using the TIME= option, which is described in topic  CMSG command options, SEND. The effects of TIME= and DATE= together are as follows:

Notes:
  1. In all cases, the delivery time that you request must be less than 100 hours from the beginning of the current day. This means that the delivery time can never be later than 03.59 on the fourth day from the current day.
  2. When processing date options entered in the form yy.ddd, mm/dd/yy and dd/mm/yy, CMSG operates a 'sliding 50 year window' to establish whether the year is in this century, the previous century or the next century. The two digit year is initially assumed to be in the same century as the current date. If this assumed year is more than 50 years in the past or more than 50 years ahead, it is adjusted accordingly. For example, if todays date is the 31st December 1997, the following DATE options are handled as follows:
    • DATE=99.001 is initially assumed to be the year 1999. Since it is within 50 years of the system3 year, the year 1999 is determined to be the delivery date for the message.
    • DATE=00.001 is initially assumed to be the year 1900. Since this year is more than 50 years ago, the delivery date is established as the year 2000.
    In both of these examples above, the delivery date is not accepted and the message 'DATE TOO FAR IN FUTURE' is displayed.

    Note that the FULLDATE operand allows a four digit year to be specified, and removes any possible ambiguity when using the DATE operand.

ERRTERM
"termid" is the identifier of the terminal to which notification is to be sent if the message is purged because it is undeliverable.

ORIG is a way of specifying the identifier of the originating terminal.

Note:
A message is considered undeliverable to a destination if it cannot be delivered within a specified interval after the requested delivery time. This interval is specified by the system programmer. If no interval is specified, no action is taken for undelivered messages, and the ERRTERM option has no effect.

If PRGDLAY is specified in the system initialization table (DFHSIT), the transient data destination CSMT is notified of the number of undeliverable messages purged for a terminal. In addition, if ERRTERM is entered, the specified terminal is notified of the message number, title identifier, and destination of the message.

FULLDATE=value
The FULLDATE option is similar to the DATE option, but it requires a four-digit year to be entered. It specifies the date on which you want your message to be delivered. It can be specified in any of the following forms:
yyyy.ddd
year (0000-9999) and day (001-366).
mm/dd/yyyy
month (01-12), day (01-31), and year (0000-9999).
mm/dd
month (01-12) and day (01-31).
+d
number of days (0-4).

The first three of these forms provide ways of specifying absolute dates, with the year (where used) in a 4-digit format. For example, if the current system4 date is in the year 1997, December 31 1997 could be specified as 1997.365, 12/31/1997 or 12/31. In this last case, the year of the current system4 date is assumed to be the year for delivery of the message.

(If DATFORM=DDMMYY was specified in the CICS system initialization parameters, enter the second and third of these as dd/mm/yyyy or dd/mm).

The fourth form allows you to specify a number of days from today. For example, a value of FULLDATE=+3 (or F=+3) means that the message is to be transmitted 3 days from today. The number must be in the range 0-4. FULLDATE=+d entries are not accepted when the system4 time is between 2330 and 0030, (to avoid confusion at or near midnight). If you use this form of the command within 30 minutes of midnight, the following error message is issued:

   +DATE INVLD FROM 2330 to 0030

You can also specify a time for message delivery using the TIME= option, which is described in topic  CMSG command options, SEND. The effects of TIME= and FULLDATE= together are as follows:

Note:
In all cases, the delivery time that you request must be less than 100 hours from the beginning of the current day. This means that the delivery time can never be later than 03.59 on the fourth day from the current system4 date.
HEADING
specifies heading information. You can use H or HEADING in place of HEADING=YES.
YES
Specifies that the current time, date, and identifier of the originating terminal is to precede the message text.
NO
causes a previous heading request to be ignored.
ID=(title)
title specifies the title (maximum length 62 characters) to be associated with the message.

See CSPG--page retrieval for commands to request a display of the titles of all messages queued for immediate delivery to that terminal.

MSG=message
"message" is the text of the message to be sent. The keyword MSG and the equal sign are optional. You must enclose the text within single quotation marks. A single quotation mark to be included as part of the message must be represented by a pair of single quotation marks. The message may be continued across multiple consecutive inputs.

If the ending single quotation mark is omitted, the entire input is treated as part of the message and a request to continue the message is sent to the terminal. The entire transaction may be canceled, or alternatively, options previously entered for this transaction may be saved by entering a single quotation mark followed by a comma to terminate the MSG option. The correct message can then be reentered; the previous incorrect message being ignored.

A single quotation mark at the end of data in a MSG option means either the end of the MSG option, or the first of a pair of single quotation marks indicating that a single quotation mark is to be included as part of the message.

In this situation, the response to the terminal is:

  CONTINUE INPUT OR MSG

If the first character of the next input is a single quotation mark, it is treated as the second of a pair of single quotation marks and the message is continued. Any character other than a single quotation mark causes the message to be complete, and that character is treated as the first character of a new option.

New-line (NL) characters within the message are kept. (If the first character is a new-line character, it is deleted.) This allows the operator to enter M=' and then carriage return (CR) or the equivalent of CR, to begin entering the message text at the left margin. The first CR is deleted. Additional CRs may be entered if blank lines are desired at the top of the transmitted message.

Note:
If the HEADING option is specified, these blank lines appear between the heading (time, date, and originator’s terminal identifier) and the message.

With NL processing, the delivered message is positioned at the left margin. If an unformatted message, or a line within a formatted message, exceeds the line width defined for the receiving terminal, sentences are split between words for any line exceeded.

OPCLASS
One or more numbers, each of which can be in the range 1-24, that define the operator classes that must be signed on before a message can be delivered. If more than one number is specified, the list must be enclosed within parentheses. For example, OPCLASS=(8,2) causes the message to be sent to all terminals that currently have an operator of class 8 or 2 signed on, and to all terminals that have that operator security value specified in their installed definitions. If OPCLASS=1 is specified, the message is routed to all terminals that are in service, regardless of whether an operator is signed on or not.

If ROUTE is specified as well, the message is routed to all requested destinations, but is not eligible for delivery to a terminal unless the class of the operator signed on matches one of the numbers specified by OPCLASS. However, if a ROUTE destination is qualified by an operator identifier, OPCLASS is ignored for that destination. For more information about how ROUTE= and OPCLASS= are used together, see the description of the ROUTE option.

PROTECT
specifies message recovery for a CICS emergency restart. You can use P or PROTECT in place of PROTECT=YES.
YES
Specifies that $$ is to be prefixed to the temporary storage data identifier of the stored message.
NO
Specifies that a previous protect request is to be ignored. This is done by using the default prefix of **. The same method is used to omit the option altogether.
prefix
Specifies a 1-or 2-character prefix to be used for the temporary-storage data identifier of the stored message. If a single character only is specified, a $ is provided as the second character. (For example, PROTECT=T causes a prefix of T$.)

If this option is omitted, a default prefix of ** is used. ** is also the default for user application programs issuing BMS message requests where no protection is specified (REQID option omitted).

A temporary-storage table (TST) entry is needed for each prefix specified in the PROTECT option so that message recovery is effective for that prefix.

ROUTE
specifies the destinations to receive the message. For routing messages to 3600, 3770 (batch), or 3790 (batch) terminals, see Examples of 3600 and 3770 batch destinations.
Termid
is the identifier or identifiers of the terminals to which the message is to be routed. For example, ROUTE=(LA04,OL,SF2) routes the message to the three terminals with the identifiers LA04, OL, and SF2. If routing is performed to several terminals of the same device and map suffixes, CICS processes the message identically for all of them and the most restricting page size prevailing is used.

The length of the terminal identifier specified in a message-switching transaction must be in the range 1-4 characters, and must not contain any of the following characters:

/
slash
,
comma
)
right parenthesis
(
left parenthesis
+
plus sign
-
minus sign
*
asterisk
 
blank.
Note:
A single message can be delivered more than once to the same terminal. For example, the instruction ROUTE=(T001,T001) causes two transmissions of a single message to terminal T001. If the destination terminal is in TRANSCEIVE status, the message appears consecutively at the terminal. If the terminal is in TRANSACTION status, the operator must request delivery of the message.
/opid
is a 1-to 3-character operator identifier preceded by a slash. The message is routed to the first terminal at which an operator with that identifier is currently signed on. For example, ROUTE=/PJ routes the message to the first terminal found (and only the first) with the operator identifier PJ currently signed on. If no such terminal is found, the sending operator is notified. The operator identifier that you specify must not contain any of the following characters:
,
comma
)
right parenthesis
 
space.
Termid/opid
is a terminal identifier qualified by an operator identifier to restrict the message delivery to the specified operator at the terminal location. For example, ROUTE=(LA04,OL/LBS,SF2) routes the message to terminals LA04 and SF2. The message is routed to terminal OL only if the operator whose identifier is LBS is signed on at that terminal.

ROUTE=(T001,T001/OP1,/OP1) causes the same message to be delivered three times to the same destination if the operator OP1 is signed on at T001.

ALL
causes the message to be broadcast to all terminals.

There is a variable limit on the number of terminals to which a message can be sent. This limit depends on a combination of factors. Significant factors are the types of terminal in use, the number of each type, and the length of message sent. The CMSG transaction is abended with an abend code of ABMC if the limit is exceeded.

Note:
If a CMSG ROUTE=ALL is issued to a large number of terminals, a task for each terminal is initiated up to the MAXTASK value. Because the tasks are single threaded, they are suspended and can give rise to an SOS condition. For guidance about avoiding this, see the CICS® Performance Guide.
.termlist
is a 1-or 2-character terminal list table (TLT) suffix preceded by a period. For example, .H3 identifies the terminal list table DFHTLTH3. A maximum of 10 terminal lists can be specified, and the terminal lists that you specify are merged together. The entries in the terminal lists contain terminal identifiers, or operator identifiers, or both. Duplicate entries within a single TLT are kept, though entries that are duplicated among the lists are deleted. (Entries are considered duplicate if each has the same terminal identifier and operator identifier.)

Here are two examples that show the effects of merging TLTs that contain duplicate entries. For these examples, assume that terminal list table DFHTLTL1 contains T001 twice, and that DFHTLTL2 contains T001 and T001/OP1.

  • If you specify ROUTE=(.L1,.L2), all entries from DFHTLTL1 are included as destinations. Duplicate entries within DFHTLTL1 are kept. All entries from DFHTLTL2 are checked for duplicates against the entries in the previously specified DFHTLTL1 and, if a duplicate is found, it is not repeated.

    The resulting destination list is T001, T001, T001/OP1.

  • The order in which you specify the TLTs is significant. If you specify R=(.L2,.L1), the DFHTLTL2 entries T001 and T001/OP1 are included in the destination list. However, the two entries for T001 in DFHTLTL1 are not included because T001 is already in DFHTLT2. In this case, the resulting destination list is T001, T001/OP1.
(±termid/opid,...)
A +termid/opid adds the specified destination (if not a duplicate) to the destinations contained in the requested TLT. A -termid/opid deletes the specified destination from the requested TLT. A -termid, without an opid, deletes all destinations of that terminal (with or without operator identifier) resulting from the requested TLT. + or -termid/opid parameters affect only those entries that result from requested TLTs, and have no effect on other + or - termid/opid parameters in the same request. All TLT suffixes must be entered before any + or - parameters.

Here are some examples that show the effects of specifying both TLTs that contain duplicate entries and ± entries. For these examples, assume that terminal list table DFHTLTL1 contains T001 twice, and that DFHTLTL2 contains T001 and T001/OP1.

  • ROUTE=(.L1,.L2,+T001) has the same effect as R=(.L1,.L2). The entry +T001 is not added, because it is a duplicate of an entry from DFHTLTL1. The resulting destination is T001, T001, T001/OP1.
  • ROUTE=(.L1,.L2,+T001/OP1,-T001) does not add +T001/OP1 because it is a duplicate of an entry in DFHTLTL2. The -T001 causes all entries from TLTs that refer to T001 (regardless of whether they are qualified by an operator identifier) to be deleted. The message ALL ROUTE ENTRIES DELETED is issued.

    If DFHTLTL2 did not contain the entry T001/OP1, the +T001/OP1 instruction would cause that entry to be added to the destination list. The -T001 instruction would not then delete the T001/OP1 entry from the list, because the effects of the + and - instructions are not cumulative: they act in isolation on the original concatenated TLTs.

  • ROUTE=(.L1,.L2,-T001,+T001/OP1); the -T001 causes all entries from the TLTs that refer to T001 (including the T001/OP1 entry in DFHTLTL2) to be deleted. The +T001/OP1 entry is then added and becomes the only resulting destination. There is no duplicate because it has just been deleted.

A ROUTE option may be divided across multiple consecutive inputs. However, if it refers to a TLT, it must be completed in the same input in which it was started. An individual ROUTE parameter (termid/opid) may not be split across two inputs.

When both ROUTE and OPCLASS are specified together, OPCLASS further restricts the message transmission. For example, ROUTE=(LA04/PJL,/MGK,OL), OPCLASS=4 routes the message to terminal LA04 if the operator whose identifier is PJL is signed on. The message is also sent to the first terminal with the operator whose identifier is MGK signed on. An operator whose class is 4 must be signed on to OL before the message can be routed there. Note that the OPCLASS value is acted on only when no operator identifier is specified.

SEND
specifies that all of the options have been entered and that the message is to be routed. SEND is the final option and must be followed by a space or an end-of-data.
TIME=value
"value" is the time at which you want the message to be delivered. You can specify the time in one of the following four ways:
hhmm
where "hhmm" is an absolute time in the range 0001-2400. For example, TIME=1145 causes the message to be transmitted at 11.45 am. The minutes value must be less than 60.
+hhmm
where "hhmm" is the number of hours and minutes from the current time. The minutes value must be less than 60. For example, TIME=+0720 means that the message is to be transmitted in 7 hours and 20 minutes from now. A value of TIME=+2400 means the same as DATE=+1.
+mm
where "mm" is the number of minutes from the current time. This value must be in the range 0-99. So, for example, a value of TIME=+75 causes the message to be transmitted 1 hour and 15 minutes from now. The values TIME=+90 and TIME=+0130 both cause the message to be transmitted in 90 minutes time.
+m
where "m" is the number of minutes from the current time. This value must be in the range 0-9. So, for example, a value of TIME=+5 causes the message to be transmitted 5 minutes from now.

If you specify a delivery time on the current day that falls within the past hour, it is interpreted as a request for immediate delivery. An earlier time than that is considered already passed and is treated as an error. The following message is issued:

TIME ALREADY PASSED

Note that, if the current time is 00.15, T=2345 is interpreted as 23.45 today because there has been a change of date. The message is not therefore transmitted immediately.

Logical unit destinations

This section describes the use of the CMSG transaction to send messages to logical units. For details of message handling within CICS subsystems, and of the use of the message-switching transaction at subsystem terminals, see the appropriate CICS/OS/VS subsystem guide.

Each logical unit in a CICS-SNA network is identified by a single terminal identifier and, if the logical unit is capable of receiving message text, messages may be routed to it in the same way as they are routed to non-SNA terminals. Routing by operator identifier may also be employed if the logical unit supports operator signon, and SNA and non-SNA destinations may be specified in the same ROUTE option.

The destination for a message sent to a logical unit can be a display or printer device, or it can be a data set or an application program in a subsystem controller. To the message sender, the destination behaves like a "terminal", and any necessary formatting is performed by the CMSG transaction or within the subsystem controller itself.

Logical device codes

Some types of logical unit (LU) can be used to get access to more than one resource within a subsystem. For example, data sent to a 3601 LU may be intended for an IBM 3604 Keyboard Display, an IBM 3618 Administrative Line Printer, or some other element of the IBM 3600 Finance Communication System. The facility provided by CICS to permit destination selection within LUs of this type is the logical device code (LDC).

The LUs that support destination selection by LDC are:

For the user of the message-switching transaction, the LDC is a 2-character mnemonic code whose meaning is defined by the CICS installation. It may be used to qualify an LU destination by including it in the ROUTE option in the syntax diagram that follows:

Read syntax diagramSkip visual syntax diagramROUTE
 
>>-ROUTE=------------------------------------------------------->
 
     .---------------------.
     V                     |
>--+---Termid--*ldc--/opid-+----------------------------+------><
   +-ALL--*ldc------------------------------------------+
   | .-----------------.  .---------------------------. |
   | V                 |  V                           | |
   '---.termlist--*ldc-+----+-----------------------+-+-'
                            '-,±termid--*ldc--/opid-'
 

where:

*ldc
is a 2-character LDC mnemonic preceded by an asterisk (*) that qualifies the destinations. The *ldc parameter may qualify an LU identifier (termid), a general broadcast (ALL), or a terminal list table specification (.termlist). The *ldc parameter applies only to LUs, not to any start-stop or BSC terminals.

Different LDC mnemonics may be included in one ROUTE option specification; however, all destinations for one message must indicate the same device type.

Termid*ldc
associates an LDC mnemonic with an LU identification.
ALL*ldc
is a general broadcast to all terminals with the same LDC mnemonic qualifying all LUs.
Termlist*ldc
.termlist*ldc
qualifies all entries in this terminal list table with the specified LDC mnemonic. This overrides any LDC specified within the terminal list table. This LDC specification does not apply to start-stop or BSC terminals.
Note:
This qualification of a TLT occurs before any succeeding TLTs or +/- entries are processed, see example 9 in Examples of 3600 and 3770 batch destinations.
+termid*ldc/opid
adds a destination, if not a complete duplicate to any contained in the requested TLTs.
-termid*ldc/opid
deletes duplicate destinations resulting from the requested TLTs. A -termid*ldc, without an opid, deletes all destinations of that termid*ldc (with or without operator identifiers) resulting from the requested TLTs. A -termid/opid, without an LDC mnemonic, deletes all destinations of that termid/opid (with or without LDC mnemonics) resulting from the requested TLTs.

If a destination is specified by /opid without termid, it becomes termid/opid, in which termid is the identifier of the first terminal or LU to which an operator with that identifier is currently signed on. If no such terminal or LU is found, the destination is not valid and the operator is notified.

Examples of 3600 and 3770 batch destinations

These examples assume the following:

1. R=T361*DS
Route message to terminal identifier T361 qualified by LDC mnemonic DS.
2. R=(T361*DS,T362*DS/OP1,T363,T371*P1, T372*P1/OP1,T373,T40)
Route message to:

T362 and T372 require that an operator with identification OP1 be signed on before the message can be sent.

Note:
The default LDC mnemonic for T363 must indicate the same device type as LDC mnemonic DS.
3. R=ALL*LP
Route message to all terminals (3600, 3770 batch and interactive logical units, start-stop, and BSC) with all 3600 destinations qualified by mnemonic LP. LP is ignored for start-stop and BSC destinations.
4. R=.L3
Use the terminal list table DFHTLTL3 for message destinations. (This is the same as example 2, plus T362*DS/OP2 and T372*P1/OP2.)
5. R=(.L3,-T362*DS/OP2,-T372*P1/OP2)
This is the same as example 4, but deletes T362*DS/OP2 and T372*P1/OP2, so is the same result as example 2.
6. R=(.L3,-T362*DS)
This is the same as example 4, but deletes all entries for T362*DS (with or without opids). The result is T361*DS, T363, all T37n terminals, and T40.
7. R=(.L3,-T362)
This is the same as example 6. -T362 deletes all entries for T362.
8. R=.L4*LP
LDC mnemonic LP qualifies (overrides) all entries in DFHTLTL4. Resulting destinations are:
T361*LP  T362*LP/OP1  T362*LP/OP2  T363*LP  T40*LP
Note:
The LP mnemonic has no effect on the start-stop or BSC terminal T40.
9. R=(.L4*LP,-T362*DS)
The -T362*DS causes no action, because the TLT destinations are qualified by LDC mnemonic LP before the additions or deletes are processed, thus causing no matching entry to delete.
10. R=(.L4,+T363*LP)
Cause error message ‘INVALID LDC AT T363*LP’ to be generated. LDC mnemonic LP has a different device type from LDC mnemonic DS (first 3600 destination encountered is T361*DS). All 3600 destinations for one message must indicate the same device type. All 3770 batch logical unit destinations for one message must indicate the same device type.
11. R=/OP2
Route message to the first terminal or logical unit found in the CICS terminal definition with operator identifier OP2 currently signed on. If OP2 is signed on to T362, the resulting destination is T362/OP2 with the default LDC mnemonic for logical unit T362. The default is DS because it is the first LDC mnemonic defined for T362. The resulting destination is T362*DS/OP2.

Related tasks
Using CICS supplied transactions
CMSG--message switching
Sending a message
Subsystems and terminal systems
CMSG examples

3.
References to "system date", "system time", "system year" and so on mean the date time or year as would be returned by EXEC CICS ASKTIME.
4.
References to "system date", "system time", "system year" and so on mean the date time or year as would be returned by EXEC CICS ASKTIME.

[[ Contents Previous Page | Next Page Index ]]