Admin Alert: The Better Way to Send Break Messages to Active Users in i5/OS

Published: March 14, 2007

by Joe Hertvik

Note: This article has associated code, which you can download here.

In a recent column, I described how to create a custom program that selectively sends break messages to signed-on users. After publication, several readers informed me that i5/OS already covers that same ground with standard menu options and APIs. This week, I'll update my earlier solution by reviewing how to accomplish the same goals by using native i5/OS functionality instead of custom programming.

Going for the Goals

In my target scenario, I want to send a message to all signed-on interactive 5250 users, asking them to perform a specific function (i.e., get off the system, exit a program, etc). The requirement to only send to signed on users occurs because some i5/OS functions, such as the Send Break Message command (SNDBRKMSG), will deliver the message to every system workstation message queue even if there is no signed on user accessing that device. Delivering messages to all terminal message queues can cause confusion when users sign on to an unused terminal at a later time and find an old message that is no longer relevant to the system. The goal is to avoid confusion by only sending break messages to currently signed-on users.

The message must also be delivered as an immediate message which each user will receive in break mode (where the message will automatically display on the user's screen, regardless of what the user is doing). This is required so that the user will see the message as soon as it is received. IBM offers the following two ways to accomplish this task in i5/OS.

• By Menu: The OS/400 Operational Assistance Menu (GO ASSIST) provides a Send Message option to send messages to individual users, to all users enrolled in the system, or to all active users.
• By API: i5/OS includes the Send Message (QEZSNDMSG) API, which allows you to embed a program call within another program or a command, so that the message can automatically be sent without manual input.

Let's look at each technique and see what it brings to the table.

Ordering Messaging from the Menu

The easiest way to send a message to all active users is to use option 4 from the OS/400 Operational Assistance Menu (Send Message), which can be reached by typing in 'GO ASSIST' from a command line. When you select option 4, you can fill out the Send a Message screen as it appears here to deliver the message to all active users.

Send a Message
                                           
 Type information below, then press F10 to send. 
                                            
   Message needs reply  . . . . . .  N            Y=Yes, N=No 
                                                             
   Interrupt user . . . . . . . . .  Y            Y=Yes, N=No 
                                                             
   Message text . . . . . . . . . .  Type your message here
     
   Send to  . . . . . . . . . . . .  *ALLACT      Name, F4 for list 
                                                                                
F1=Help   F3=Exit   F10=Send   F12=Cancel  

To send a message to your active users only, you would type the message in the Message text field and then enter the '*ALLACT' literal in the Send to field. If you want the message to break on the user's terminal screen, you need to remember to change the Interrupt user field to 'Y' (its default is 'N'). After filling out your parameters, press F10 and the message will be sent out as a break message, and it will only be delivered to the workstation message queues that your active 5250 users are attached to.

You can also use GO ASSIST option 4 to send messages to individual users (by entering each user's name in the Send to list on the screen) or to the System Operator message queue (by entering *SYSOPR as a Send to list entry). There is also an option to require users to reply to a break message before they continue, which can come in handy when you want to ensure that a user will see the message. You can require message replies by entering a 'Y' in the Message needs reply field ('N' is the default). However, you may want to use this feature sparingly to avoid irritating your users when they are working on the system.

An interesting take on using the Send Message function came from reader Mohamed Hussain. Mohamed suggested that when sending break messages to individual users, it might be easier to select the users who will receive your message from the Work with User Jobs command (WRKUSRJOB). You can use WRKUSRJOB to select active users to receive messages by entering the command like this.

WRKUSRJOB USER(*ALL) STATUS(*ACTIVE) JOBTYPE(*INTERACT) ASTLVL(*BASIC)

Running WRKUSRJOB this way provides you with a list of signed-on users for your i5 partition. From this list, you can pick out an individual user or a group of users and enter '3=Send message' in front of each user that you want to send a message to. Once your users are selected, press ENTER and the WRKUSRJOB command will direct you to the Send a Message screen, and it will also fill in the names of all your selected users in the screen's Send to field list. From there you can enter your message and parameters and press the F10 key to send a message specifically to these users. This is a nice way to create a list of users to send messages to without having to type in each user name individually.

Sending Messages from an API

In addition to sending messages interactively from the Send Message function (option 4 on the GO ASSIST menu), IBM also provides an API called QEZSNDMG which allows you to send a message to one or more users and (optionally) allows you to pop up the Send a Message screen from within another program. To illustrate how this works for sending messages to all active users, I wrote the following CL utility called SNDACTMSG, which uses QEZSNDMG to send a message up to 494 characters long to all the active users currently using the system. Here's the program code that makes it happen.

Click here to see the program code.

Calling the program is easy. To send a message that is less than 494 characters long to all the active users on your system, you simply execute this call statement:

CALL SNDACTMSG PARM('Message text')

The SNDACTMSG code is more concise than it looks, because the majority of the coding lies in defining the parameters correctly. Here what each section of code does.

(Line 1) Input parameters: SNDACTMSG allows you to pass in a message to be sent to all active users. The message can be no more than 494 characters, the maximum message length for the QEZSNDMG API.

(Lines 3.00 through 48.00) Defining QEZSNDMG variables: The API requires twelve different parameters to run, and this section defines all program variables. To help you understand what each variable does, comments are included with each declare statement.

(Lines 49.00 through 57.00) Defining work variables: These variables are used to clean-up the incoming text message for transmission.

(Lines 60.00 through 70.00) Cleaning up the incoming message: According to IBM, unpredictable results can occur whenever you pass in character variables that are more than 32 characters long. I5/OS also may neglect to right-fill the incoming 494-character variable with spaces, so this code replaces any null values found in the message text with spaces.

(Line 71.00 through 76.00) Calling the API: This section calls the API using the parameters that I set up in the program. The end result is that QEZSNDMG uses the Send Message function to deliver the incoming message in break mode to all active users.

This program is a much simpler procedure for automatically sending text messages than the home-grown procedure that I created in my earlier article. The advantage to using the APIs over a home-grown solution is that the API solution relies on IBM's own native functions. APIs will usually retain system compatibility after PTFs are applied or after an upgrade is performed. With a home-grown solution, you may have to rewrite code to adjust to changed system parameters. It's also easier to use APIs because (in most cases) IBM has done a lot of the heavy lifting for you; you just fill in the parameters and go.

The other nice thing about SNDACTMSG is that it can be used as a template for creating other programs that use IBM's QEZSNDMG API. To that end, you may want to study up and learn how QEZSNDMSG works by reading about it at IBM's iSeries Information Center QEZSNDMG Web page.

About Our Testing Environment

All configurations described in this article were tested on an i5 box running i5/OS V5R3. However, most of these commands and features are also available on i5/OS V5R4 and most earlier versions of OS/400 V4R5 and below running on AS/400 and iSeries machines.

Special thanks go out to the following readers who sent me information that I used in this article: Carl Pitcher, Chip Cleveland, Krister Karlsson, Mohamed Hussain, Roger Engel, and Walker.

RELATED STORIES

iSeries Information Center QEZSNDMG Web page, Selectively Sending Break Messages to Active Users

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot