UM - Message Switching / Printout Spooling Utility

The online utility program UM is can be used by all Com-plete users. Some UM functions are especially designed for the application-oriented users, while others are designed for the system programmer. This means that you can issue some UM functions only if you have control status. These functions are marked as such in this section.

By default, the usage of the "TID=" argument is restricted to control users. This facility can be made available to all users by specifying APPLYMOD=7 in the Com-plete startup sysparms. A full description of the APPLYMOD sysparm can be found in the Com-plete System Programming documentation.

Note that throughout this section, all references to messages or message switching should be interpreted to mean both message switching and printout spooling, unless otherwise specified.

The UM system functions are:

• Send messages to any terminal in the Com-plete terminal network;

• Retrieve, purge, delete, reroute, repeat, hold and release messages;

• Change the sending authorization class codes for any given terminal (control user);

• Change the receiving authorization class codes for any given terminal (control user)

  These functions are described in the sections Menu Operation and Direct Command Operation.

This document covers the following topics:

• Destination Codes

• Class Codes

• Message Queue

• Message Delivery and Receipt

• Message Interruption and Recovery

• Message Text

• Message Routing

• Alternate Terminals

• Disabled Terminals

• Inoperative Terminals

• Menu Operation

• Direct Command Operation

Destination Codes

When you send a message, you must include information indicating where the message is to be received. You can select the terminal(s) that are to receive the message by specifying one or more destination codes. A destination code can be either:

• A Terminal Identification number (TID);

• A destination code that represents one or more TIDs.

  Destination codes allow an installation to form convenient groupings of TIDs. Each installation can also define procedures for changing and adding destination codes. When you use a destination code in a message switching terminal operator command, Com-plete first converts it into TID numbers and then sends the message(s) to the appropriate terminals.
  

Class Codes

A class code designates security restrictions and other information about a message. There are two categories of class codes:

1. Security class codes (numbered 1 through 4);

2. Other class codes (numbered 8 through 16).

For a successful message request, you must assign at least one security class code to each message you send.

Each terminal in the Com-plete network has two sets of security class codes assigned to it; one that defines which message classes it can send, and another that defines which message classes it can receive. Class codes are assigned through your user ID definition. Of you have not logged on to Com-plete or for printer devices, class codes are assigned through the terminal definition table.

Note that messages must have security class codes assigned. Com-plete checks to determine whether a sending terminal is authorized to send a specific message by verifying that the class code(s) assigned to that message is among the sending class codes assigned to the sending terminal. Com-plete also verifies that the assigned class codes(s) are included in the list of the receiving class codes of the terminal(s) to which the message is sent. If the class codes are not compatible, the message is not sent, and in some cases, a security violation is logged to the Com-plete logging device.

Several class codes (numbered 1 through 4) cause certain special operations to be performed as a message is sent. These operations and their class codes are explained in the following table.

Class codes 12 through 16 cause special services to be performed as a message is sent.

Message Queue

When a message is sent to a terminal, it is by default copied onto a disk file containing queues of messages for each terminal. The order of the messages queued to a specific terminal depends on the priority rating of the sending terminal. Note that you can recall messages from this file for redisplay at any time as long as they have not been successfully delivered. To accomplish this, use the UM time command options (*UM D or *UM number) described later in this section.

Message Delivery and Receipt

Messages sent to hard copy terminals are printed automatically if the terminal is in ready status and no other messages are queued to the terminal.

Messages sent to display devices require operator acknowledgment following display. To acknowledge a message, simply press ENTER.

A message sent to you may be longer than the buffer size for your receiving terminal. This is indicated by an asterisk (*) as the last character displayed. To display the remaining portion of the message, press ENTER.

There are three common situations in which messages sent to a terminal arenot automatically displayed:

1. If the terminal is MESSAGE DISABLED. Normally, when messages are sent to a terminal, they may interrupt and destroy whatever data is being entered at the time. To prevent this, set the terminal to disabled status for receipt of messages.

   Note:
   MESSAGE DISABLED status does not prevent class 2 messages from being received.

2. If a conversational program is executing at the terminal. If an active program is currently in use at the receiving terminal, messages will be placed in a special message queue for that terminal. The messages will be received when the application program terminates.

   Note:
   This feature does not apply to messages sent with class codes 2 or 3 assigned.

3. If the previous message was not acknowledged. If a previously sent message has not been acknowledged, additional messages will be queued.

   Note:
   This condition can occur only with CRT devices.

   When a terminal is enabled for receipt of messages, (e.g., a conversational program is ended, or the MESSAGE DISABLED status is removed), any messages that have been placed in the message queue will be available for display. On CRT terminals, as you acknowledge each message queued to your terminal, the next message will be displayed until all have been displayed and acknowledged.
   

Message Interruption and Recovery

The message switching facility of Com-plete provides automatic message restart in the event that terminal output is interrupted. Message restart is performed on a checkpoint basis. Each message sent to a terminal is initially queued to the message switching file queue residing on disk. Messages residing on the message file queue are sent or written to the destination terminal on an availability basis. As messages are written, a core queue checkpoint is taken to indicate the status of the output being written (for large messages, this checkpoint is taken at the completion of every full page of output). If output is interrupted (for example, by pressing STOP), output resumes at the last checkpoint when the terminal is made ready again (for example, by pressing START).

If a system failure occurs, all message core queue checkpoint records are destroyed. When Com-plete is again initialized, various message restart options are available, the default being recovery of message output from the beginning of the output message. For more details on the message recovery options available at your installation following a system failure, consult the system programmer responsible for Com-plete maintenance.

Message Text

The text of any given message can contain any character combination except:

• A left parenthesis "(" must not be the first character of a message;

• The phrase "TID=" must not be the first phrase of a message;

• An asterisk (*) must not be the last character of a message.

Com-plete treats all messages, regardless of content, as text when they are displayed at the receiving terminal: they are printed or displayed using the maximum line length of the receiving device. A word that will not fit at the end of a line is moved to the beginning of the next line. All blanks at the end of a message are ignored.

Message Routing

Note that, except for class 13 messages, each message received has a standard header containing the following:

• The message identification number;

• The date;

• The time the message was written;

• Terminal Identification number of the sending terminal.

The following illustrates a typical message header:

MSG ID:    133, SENT 10/17/97 AT 1106, FROM TID 17
SAMPLE MESSAGE HEADER DISPLAY

Note that if you do not want this header to appear, you must assign class code 13 to your message.

Alternate Terminals

Alternate terminals are those designated to receive message output for terminals that are either inoperative, currently in conversation with an online program, or disabled for message receipt. If a terminal has an alternate terminal assigned and cannot immediately receive a message, any message sent to it (except class 2 messages) is automatically displayed or written to the alternate terminal. Class 2 messages ignore an alternate terminal assignment and are received at the destination terminal unless it is inoperative.

You can assign alternate terminals in one of three ways:

1. Through the Terminal Definition Table (TIBTAB);

2. By using the ALT command of the UM facility.

Note that an alternate terminal assignment made via TIBTAB is a permanent assignment, whereas the setting made via the ALT command is only valid for the duration of the Com-plete session.

Disabled Terminals

When a message is sent to your terminal, it may interrupt and/or destroy whatever data you may have entered at the time the message is sent. The DISABLE terminal function prevents this by enabling you to temporarily suspend message receipt for a terminal.

If your terminal has been disabled, all messages sent to it (except those assigned message class 2) will be either routed to the alternate terminal, if assigned, or placed in the message file disk queue. Class 2 messages override a disabled status and are displayed immediately.

Inoperative Terminals

Inoperative terminals are those that are either:

• Powered off;

• Malfunctioning;

• Write-inhibited via a switch.

Com-plete handles inoperative terminals in a manner similar to its handling of disabled terminals. Messages sent to these terminals are either rerouted to a designated alternate terminal, if assigned. If no alternate terminal is assigned, the message is placed in the message queue for the inoperative terminal.

Messages sent to an inoperative terminal, if not rerouted to an alternate terminal, are automatically displayed when the terminal is once again able to receive messages.

Menu Operation

Message switching can be performed using direct commands or by selecting options from the UM menu. The following subsections describe the menu mode of work. For a description of direct command mode, see the section Direct Command Operation.

You can invoke the UM main menu with the command *UM. This displays the UM Message Switching Menu on the screen of your terminal:

COMMSG0001 (8) Please enter function.
 09:59:23        TID     9           COM-5.1.          User SAGAWW       05/23/97
                          ---  Message switching  ---                       UM00
                         Function. . . . . . Fc Parm(s)
                         ------------------- -- -------
           Send msg to.: Users, TIDs ....... SM 1,2,3
                         All active users .. SA 1,3
                         Users (from menu) . SS 1,3
                         Accounting Groups . SG 1,3
                         TIB Group(s) ...... ST 1,3



                         Select Function ...
 (1) Message:
                                                                         <More
 (2) Users, TIDs:
 (3) Class Codes: 1                                                  0 Receivers
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Mode  End         Send

You perform UM functions by selecting the appropriate option from this menu and specifying values in the other input fields as described in the following subsections.

Function SM - Send Message to User(s) or TID(s)

If you already know the individual user IDs or TID numbers that you wish to receive the message, enter up to seven destinations in the Users, TIDsfield and press PF5 to send the message specified in theMessagefield.

If you want to send the message to more than seven destinations, press ENTER instead of PF5. Repeat this procedure until your destination list is complete, then press PF5 to send the message.

Press PF2 to display the destinations you have already selected., for example:

11:31:09        TID     9           COM-5.1.          User SAGAWW       05/24/97
 Func: SM                 ---  Message switching  ---                       UM01
 Destination      Destination      Destination      Destination      Destination
 -----------      -----------      -----------      -----------      -----------
 U=MBE            U=NG             U=SAGAWW










 (1) Message: TEST
                                                                         <More
 (2) Users, TIDs:
 (3) Class Codes: 1                                                  3 Receivers
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Mode  End         Send        bwd   fwd

Function SA - Send Message to all Logged on Users

You can select option SA to send the message to all users currently logged on to Com-plete. These messages are not saved and are lost when Com-plete terminates.

Function SS - Send Message to User(s) (from Menu):

If you select function SS and press ENTER after specifying the message text, a list of all users currently logged on to the Com-plete system is displayed. The following figure shows an example of such a display:

COMMSG0017 (8) Press 'PF5' to execute function.
 16:30:15        TID     9           COM-5.1.         User SAGAWW       05/24/97
                          ---  Message switching  ---                       UM20
 M   Userid..    M   Userid..    M   Userid..    M   Userid..    M   Userid..
     NG              TIMERM          SAGAWW














 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                   End                           fwd                     Quit

You select users by entering any character into the M column left to the user ID. press PF8 to scroll to the next page. When your selection is complete, press PF5 to send the message.

Function SG - Send Message to Accounting Groups:

If you select function SG and press ENTER after specifying the message text, a screen displaying Accounting Groups of currently logged on users appears, for example:

COMMSG0017 (8) Press 'PF5' to execute function.
 10:43:12        TID     7           COM-5.1.         User SAGAWW       05/27/97
                          ---  Message switching  ---                       UM20
 M Acct.Group..  M Acct.Group..  M Acct.Group..  M Acct.Group..  M Acct.Group..
   WIEN            EBERSTADT       MR. COMPLETE    GROUP           COMPLETE














 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                   End                           fwd                     Quit

You select accounting groups by entering any character into the "M" column left of the accounting group name. Press PF8 to scroll the list forward to the next page. Once you have selected all desired groups, press PF5 to send the message.

Function ST - Send Message to TIB Groups:

If you select function ST and press ENTER after specifying the message text, a list of the defined TIB Groups is displayed, for example:

COMMSG0017 (8) Press 'PF5' to execute function.
 10:51:22        TID     7           COM-5.1.         User SAGAWW       05/27/97
                          ---  Message switching  ---                       UM20
 M   Tibgroup    M   Tibgroup    M   Tibgroup    M   Tibgroup    M   Tibgroup
     WIEN















 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                   End                           fwd                     Quit

Select the desired group(s) by entering any character into the "M" column left to the "Tibgroup" column. Press PF8 to scroll the list to the next page. Press PF5 to send the message to all selected groups when your selection is complete.

Direct Command Operation

Initial access to UM is gained by entering the call request:

*UM command 

where command represents the desired command.

If you omit the command parameter under COM-PASS, The UM Message Switching Menu is displayed (see the section Menu Operation above).

The available UM commands are summarized in the following table and described in more detail in the subsequent subsections.

*UM RCLASS=    (c1=YES|NO,c2=YES|NO,...,
 cn=YES-|NO).TID=xxx

*UM CLASS= (c1=YES|NO,c2=YES|NO,...,
 cn=YES|NO).TID=xxx

* Available only if you have control status.

Class codes are assigned to specific terminals by use of the terminal definition table (TIBTAB). They are also assigned to specific terminal users through the user ID, thus overriding any assignments made in TIBTAB. The class codes assigned to a specific user ID can be overridden by a control user while the user ID is in use, however, by using the RCLASS and SCLASS commands.

Send to Terminal(s):

This command enables you to send a message to one or more terminals or a set of terminals identified by a destination code. In addition, all class codes to be assigned to the message have to be given at that time.

The command format is:

*UM d1<,d2,...,dn><.(c1,c2,...,cn)>.message

The arguments are:

Message Segmentation

Messages are formed in segments. Each segment, including all characters in the message command itself, may not exceed 1,000 bytes in length. (This is the equivalent of 12.5 lines of message text on a 3277 Model 2 terminal.) Note that there is no limit to the number of message segments that make up a given message; however, the size of the message queue file itself is a limiting factor. Before a segmented message is written to the receiving terminal device, the segments are linked together by Com-plete and the message is sent as a single unit.

To end a message segment, enter an asterisk as the last character of the message text. To attach subsequent text segments to the initial message text, simply enter an asterisk as the last character of each segment. Consequently, an asterisk cannot be the last character in a given message. Note that you need to invoke UM only once via the initial call. The asterisk, which is used only as a segment delimiter, does not appear in the message when it is received.

Display Message Status

Messages sent to a terminal that are waiting to be displayed are queued in the message queue. It is often desirable to be able to obtain status information about pending messages in order to decide which UM functions you want to perform on specific messages (for example, reroute or delete a specific message).

The message status display function enables you to display status information about all pending messages, including:

• The TID of the terminal that generated the status display;

• The TID of an alternate terminal, if any (see the section Alternate Terminals above);

• The sending and receiving class codes;

• The terminal status (for example, Message Disabled or not. See the section Disabled Terminals above);

• The message number, status, and other information for all messages sent to the terminal that have not been written.

The command format is:

*UM D<.TID=tid>

with the optional argument tid as described above. If you omit the TID number, the status display is given for the terminal at which you enter the request.

Display a Message

You can selectively display messages from the message queue. You must know the number of a specific message in order to obtain a selective display.

The command format is:

*UM message

where message is a message number, which will cause that message to be displayed;

Delete a Message

You can selectively delete messages pending output to a terminal from the message queue in order to prevent completion of their output.

The command format is:

*UM DELETE.n

where n is the number of the message to be deleted.

Note that you can only delete messages pending output, and only those sent to the terminal you are currently using.

Hold a Message

This function enables you to hold specific messages destined for the terminal you are using.

The command format is:

*UM HOLD.n

where n is the number of the message to be held.

Release a Message

You must release a message in hold status before you can display it.

The command format is:

*UM RELEASE.n

where n is the number of the message to be released from hold.

Purge all Messages

Use this function to eliminate message output to a terminal regardless of the type or number of messages being sent.

The command format is:

*UM PURGE

Enable Terminal

This function allows you to remove the disabled message status from your terminal.

The command format is:

*UM ENABLE

After you invoke this function, the following message is displayed at your terminal:

UMS0022 - REQUESTED OPERATION COMPLETE

Any messages waiting in the message queue for display at your terminal are presented immediately.

Disable Terminal

This function allows you to temporarily suspend message receipt from your terminal.

The command format is:

*UM DISABLE

After you invoke this function, the following message is displayed at your terminal:

 UMS0022 - REQUESTED OPERATION COMPLETE

Any messages waiting in the message queue for display at your terminal are presented immediately after you remove the disabled status with the ENABLE command.

Reset Terminal I/O

Use this function to restart output to a terminal that has stopped because of permanent terminal I/O errors. This function enables you to cause messages destined for your terminal to be requeued to the message queue.

The command format is:

*UM RESET

Set Alternate Terminal

Use this function to temporarily route messages to an alternate instead of your terminal.

The command format is:

*UM ALT=tid

where tid is the Terminal Identification number (TID) of the terminal designated as the alternate.

Remove Alternate Terminal

Use this command to remove an alternate terminal assigned to your terminal.

The command format is:

*UM ALT=REMOVE.TID=ORIGINALTID

When you invoke the Remove Alternate function, all messages sent to the designated original destination terminal are either received immediately or queued in the message queue.

Change Receiving Class Codes (Control User)

The command format used to modify the receiving authorization class codes for a given terminal is:

*UM RCLASS=(c1=YES|NO,c2=YES|NO, .........cn=YES|NO).TID=yyy 

This command is used to temporarily change the receiving authorization class code specifications for the terminal designated by yyy; it may be issued only from the control terminal with TID=1.

The arguments are:

Note that class code modification is temporary only; class codes remain the same until changed with another RCLASS command or until Com-plete is reinitialized.

Example

Terminal 66 currently can receive messages with class codes 1 and 2. To disable receipt of class 2 messages and enable receipt of class 3 messages, issue the following command:

*UM RCLASS=(2=NO,3=YES).TID=66 

Change Sending Class Codes (Control User)

The format of the command used to modify the sending authorization class codes for a given terminal is:

*UM SCLASS=(c1=YES|NO,c2=YES|NO, ......... cn=YES|NO).TID=yyy 

This command is used to temporarily change the sending authorization class code specifications for the terminal designated by yyy.

The arguments are:

Class code modification is temporary only; class codes remain the same until changed with another SCLASS command or until Com-plete is reinitialized.

Example

Terminal 66 currently may send messages with class codes 1 and 2. To disable sending class 2 messages and enable sending class 3 messages, issue the following command:

*UM SCLASS=(2=NO,3=YES).TID=66