CMSG command reference

Options for CMSG message switching

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:

Date form	Description
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 system 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 system date is assumed to be the year for delivery of the message.

Note: 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.

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. If you want to specify an absolute date with the year in a 4-digit format, then use the FULLDATE parameter.

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 system time is 2330 - 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 option SEND. The effects of TIME= and DATE= together are as follows:

• If you specify neither a time nor a date, the message is transmitted as soon as the receiving terminal is free.
• If you specify a time but no date, the message is transmitted at the specified time today. For example, if the time now is 09.00 and you specify TIME=0930, or TIME=+30, the message is transmitted at 09.30 today.
• If you specify a date but no time, the message is transmitted at the current system time on the specified date. For example, if the time now is 10.30 and you specify DATE=+2, the message is transmitted at 10.30 in two days' time.
• If you specify both a date and a time, the message is transmitted at the specified time on the specified date. For example, if you specify DATE=07/29/98 and TIME=1130, the message is transmitted at 11.30 on 07/29/98.

Note:

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 today's 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 system 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 like 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 system 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 system 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 system time is 2330 - 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 option SEND. The effects of TIME= and FULLDATE= together are as follows:

• If you specify neither a time nor a date, the message is transmitted as soon as the receiving terminal is free.
• If you specify a time but no date, the message is transmitted at the specified time today. For example, if the time now is 09.00 and you specify TIME=0930, or TIME=+30, the message is transmitted at 09.30 today.
• If you specify a date but no time, the message is transmitted at the current system time on the specified date. For example, if the time now is 10.30 and you specify FULLDATE=+2, the message is transmitted at 10.30 in two days' time.
• If you specify both a date and a time, the message is transmitted at the specified time on the specified date. For example, if you specify FULLDATE=07/29/1998 and TIME=1130, the message is transmitted at 11.30 on 07/29/1998.

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 system 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 required at the start 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).

For each prefix specified in the PROTECT option, you must define the temporary storage model to CICS as recoverable, 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 uses the most restrictive page size of them all.

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:

Invalid character	Description	Invalid character	Description
/	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

Specifies 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:

Invalid character	Description
,	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 many 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 Reducing storage stress.

.termlist

Specifies 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 can 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) cannot 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.

Examples of 3600 and 3770 batch destinations