AS/400-iSeries Starter Kit

Sooner or later, you will want to use messages on the AS/400. For instance, you might need to have a program communicate to a user or workstation to request input, report a problem, or simply update the user or system operator on the status of the program (e.g., "Processing today's invoices"). Another time, your application might need to communicate with another program. Program-to-program messages can include informational, notification, status, diagnostic, escape, and request messages, each of which aids in developing program function, problem determination, or application auditing. "File YOURLIB/YOUROBJ not found" is an example of a diagnostic program-to-program message.

You or your users can also send messages to one or more users or workstations on the spur of the moment. Sometimes called impromptu messages, user-to-user messages are not predefined in a message file to system users. They might simply convey information, or they might require a response (e.g., "Joe, aliens have just landed and taken the programming manager hostage. What should we do???"). User-to-user messages can serve as a good introduction to AS/400 messaging.

Sending Messages 101

To send user-to-user messages, you use one of three commands: SNDMSG (Send Message), SNDBRKMSG (Send Break Message), or SNDNETMSG (Send Network Message). SNDMSG is the most commonly used (you can use it even if LMTCPB(*YES) is specified on your user profile) and the easiest to learn. The SNDMSG prompt screen is shown in Figure 7.1. To access the SNDMSG command, you can

• key SNDMSG on a command line,

• select option 5 on the System Request menu,

• select option 3 on the User Task menu, or

• select option 4 on the Operational Assistant menu. (This option may be best for end users because Operational Assistant provides the most user-friendly interface to the SNDMSG command.)

The message string you enter in the MSG parameter can be up to 512 characters long. To specify the message destination, you can enter a user profile name in the TOUSR parameter. TOUSR can have any of the following values:

• *SYSOPR -- to request that the message be sent to the system operator's message queue (QSYS/QSYSOPR).

• *REQUESTER -- to request that the message be sent to the interactive user's external message queue or to the system operator's message queue when the command is executed from within a program.

• *ALLACT -- to request that the message be sent to the message queue of every user currently signed on to the system. (*ALLACT is not valid when MSGTYPE(*INQ) is also specified.)

• User_profile_name -- to request that the message be sent to the user's message queue (which may or may not have the same name as the user profile).

For example, if you simply want to inform John, a co-worker, of a meeting, you could enter

SNDMSG MSG('John - Our meeting today will  +

            be at 4:00. Jim')              +

       TOUSR(JSMITH)

Another way to specify the message destination is to enter up to 50 message queue names in the TOMSGQ parameter. The specified message queue can be any external message queue on your system, including the workstation, user profile, or system history log (QHST) message queue (for more about sending messages to QHST, see "Sending Messages into History,").

Specifying more than one message queue is valid only for informational messages. The MSGTYPE parameter lets you specify whether the message you are sending is an *INFO (informational, the default) or *INQ (inquiry) message. Like the informational message, an inquiry message appears on the destination message queue as text. However, an inquiry message supplies a response line and waits for a reply. If you want to schedule a meeting with John and be sure he receives your message, you could enter

SNDMSG MSG('John - Will 4:00 be a good time for our  + 
            meeting today? Jim')                     +

       TOUSR(JSMITH) MSGTYPE(*INQ)

The RPYMSGQ parameter on the SNDMSG command specifies which message queue should receive the response to the inquiry message. Because the default for RPYMSGQ is *WRKSTN, John's reply will return to your (the sender's) workstation message queue.

As you can see, the SNDMSG command provides a simple way to send a message or inquiry to someone else on the local system. However, it has one quirk. Although SNDMSG can send a message to a message queue, it is the message queue attributes that define how that message will be received. If the message queue delivery mode is *BREAK and no break-handling program is specified, the message is presented as soon as the message queue receives it. A delivery mode of *NOTIFY causes a workstation alarm to sound and illuminates the "message wait" block on the screen. A delivery mode of *HOLD does not notify the user or workstation about a message received.

I Break for Messages

The SNDBRKMSG command offers a solution for messages that must get through regardless of the message queue's delivery mode or break-handling program or the message's severity. Although SNDBRKMSG provides the same function as the SNDMSG command, the message queue receiving the command handles messages in break mode, regardless of the message queue's delivery mode. Figure 7.2 shows the SNDBRKMSG prompt screen.

There are two other differences between the SNDBRKMSG command and the SNDMSG command. First, the SNDBRKMSG command has only the TOMSGQ parameter on which to specify a destination (i.e., only workstation message queues can be named as destinations). Second, the SNDBRKMSG command lets you specify the value *ALLWS (all workstations) in the TOMSGQ parameter to send a message to all workstation message queues.

The following is a sample message intended for all workstations on the system:

SNDBRKMSG MSG('Please sign off the system  +

               immediately. The system  +

               will be unavailable  +

               for the next 30 minutes.')  +

          TOMSGQ(*ALLWS)

This message will go immediately to all workstation message queues and be displayed on all active workstations. If a workstation is not active, the message simply will be added to the queue and displayed when the workstation becomes active and the message queue is allocated.

Casting Network Messages

The third command you can use to send a message to another user is SNDNETMSG (Figure 7.3). As with SNDMSG and SNDBRKMSG, you can type an impromptu message up to 512 characters long in the MSG parameter. The distinguishing feature of the SNDNETMSG command is the destination parameter, TOUSRID. The value you specify must be either a valid network user ID or a valid distribution list name (i.e., a list of network user IDs). If necessary, you can add network user IDs to the system network directory using the WRKDIR (Work with Directory) command. Each network user ID is associated with a user profile on a local or remote system in the network.

There are two situations for which the SNDNETMSG command is more appropriate than SNDMSG or SNDBRKMSG. First, you might need this command if your system is in a network because SNDMSG and SNDBRKMSG can't send messages to a remote system. Second, you can use SNDNETMSG to send messages to groups of users on a network -- including users on your local system -- using a distribution list. You can create a distribution list using the CRTDSTL (Create Distribution List) command and add the appropriate network user IDs to the list using the ADDDSTLE (Add Distribution List Entry) command.

When you specify a distribution list as the message destination, the message is distributed to the message queue of each network user on the list. For example, if distribution list PGMRS consists of network user IDs for Bob, Sue, Jim, and Linda, you could send the same message to each of them (and give them reason to remember you on Bosses' Day) by executing the following command:

SNDNETMSG MSG('Thanks for your hard work  +

               on the order entry project.  +

               Go home early today and  +

               enjoy a little time off.')   +

          TOUSRID(PGMRS)

The only requirements for this method are that user profiles have valid network user IDs on the network directory and that System Network Architecture Distribution Services (SNADS) be active. (You can start SNADS by starting the QSNADS subsystem.)

As you can see, you have more than one option when sending user-to-user messages on the AS/400. Now you're ready to move on to program-to-user and program-to-program messages, but these are topics for another day. This introduction to messages should get you started and whet your appetite for learning more.