QRemote Control allows registered users to execute programs on the IBM i remotely. To execute a program, the user sends a text message (SMS) with a specific command to QRemote Control. The command specifies an exit program. An exit program in QRemote Control and QMessage Monitor is a standard IBM i program that has been registered with QMessage Monitor.
Despite the name, exit programs in this context are not related to exit point processing.
This facility requires:
- QMessage Monitor
- QRemote Control (licensed for all systems on which exit programs are to be executed)
- A GSM terminal. CCSS can advise you on GSM terminal hardware. Only supported hardware should be used.
Workflow
The basic workflow for use of exit programs is:
| Preparation |
- Identify functionality.
- Code the program.
- Compile the program.
- Distribute the program.
- Determine who should be authorized.
- Configure authorities.
- Register the program as an exit program.
|
| Use |
- Run the exit program
|
Identifying Functionality
Start by identifying the functionality you would like to be made available through text messages. Some examples are:
- Restart a known subsystem.
- End a known job.
- Enable a user profile.
As part of exit program execution, information can be sent back to the mobile phone user through text messages, lending itself to functions such as:
- Receiving a list of held job queues.
- Receiving a list of jobs in (Inquiry) Message Wait.
- Checking if a particular batch job is active.
- Get information from the STOCKS file.
Coding the Program
Code an IBM i program in the high-level language of your choice, for example, C, CL or RPG. Use the following information.
Program input
The exit program receives the following information:
| Parameter | Meaning | Data Type |
|---|
| 1 |
Name of the escalation user who sent the command. |
CHAR *10 |
| 2-6 |
Arguments provided by the user in the SMS. |
CHAR *10 (each) |
Between 0 and five parameters can be specified by the user in the text message in addition to the command itself.
Program output
The program can create output in the same manner as any IBM i program. To send information back to the user via text message, one of the following mechanisms can be employed (depending on the capabilities of the programming language used):
Using the SNDPGMMSG command. Any messages sent by the top level program will be joined together into one or more SMS messages, which are sent back to the sender. To mark a message as private, send the message *PRIVATE first.
Using the PGSMS command. You can use the PGSMS command in a CL program to send messages to the user (or to another user). Messages will be sent immediately, and the usual confirmation options are available. You can also specify private messages using this method. Private messages will not have their text displayed by the status and history functions.
Using the LDA. Set the first four bytes of the LDA to *SMS or *SMP. The remaining 560 bytes will be turned into a message (or messages) and sent back to the requesting user. *SMP is used to specify a private message.
Sample source code shipped with QMessage Monitor
File MMSRC is shipped with the QMessage Monitor product. Amongst others, this file contains a number of sample programs that can be used as a QRC exit program. It resides in the QMessage Monitor product library on the host system.
Compiling the Program
Exit programs are compiled in the same manner as any other IBM i programs.
We suggest that you compile programs to library MMUSR on the QMessage Monitor host system.
Distributing the Program
The next step is to get these newly created programs onto the other systems/partitions in the QMessage Monitor configuration. This can be achieved using the MMSNDUSR command, which will ship the contents of library MMUSR on the host to all other systems in the QMM configuration.
Determining which Escalation Users Should Be Authorized
Determine which persons you would like to be able to use these commands. If they have not been set up as escalation users in QMessage Monitor, add them now with their mobile phone numbers.
Configuring Authorities for Escalation Users
Setting Authority List membership
In the Maintenance module, in the Main section, create an authority list that will be used to control use of the exit program. Add the users determined in the preceding step, and give them “Allow Execute” authority.
Setting Escalation User authorities
In the Maintenance module, in the Main section, for each user, set the authority to a value other than “Not Authorised to submit requests”.
Registering Program as an Exit Program
The programs now need to be added as exit programs to the QMessage Monitor configuration. This can be achieved in the Maintenance module, by adding an Exit Program in the Exit Program view in. (Note: We will use the PC module Maintenance here, but you could also use the green-screen commands available from the QMM menu.)
In this example, program MY_LIB/MY_PGM is being registered as exit program EXIT_01. The Default System is system HOST. The exit program can only be executed by members of authority List MY_LIST.
Running the Program
From the mobile phone send a text message to the QRC server number as follows:
EX MY_SYSTEM EXIT_01 QBATCH
Where:
- EX is the QRemote Control command for running an exit program.
- MY_SYSTEM is the name of the system on which you want to run the exit program.
- EXIT_01 is the External Name of the exit program.
- QBATCH is the first (and in this case only) parameter that is passed to the exit program.
This calls the program associated with the External Name, with the parameter QBATCH.
The program could then, for instance, return a list of jobs currently running in the QBATCH subsystem.
Security
As with any communications, the use of exit programs has to be evaluated from a security perspective.
The use of exit programs is controlled through the following security features:
| Feature | How it works |
|---|
| Sender number verification |
As with any command sent to QRemote Control, the sender’s phone number is compared against the numbers that have been configured in QMessage Monitor as escalation user phone numbers. Only if the numbers of the sender matches one of the numbers for an escalation user, processing of the command is performed. |
| Authority Lists |
An authority list can be associated with an exit program. An authority list is a named list of escalation users. The authority list controls which escalation users, identified through the senders’ phone numbers, can execute a particular exit program. |
| Prepared commands |
Exit programs function similar to “prepared statements” in SQL. They allow to which functionality is made available to users. This reduces the security exposure in comparison to unlimited access to IBM i commands. |
These security features mitigate the risk associated with any communication. Nonetheless, it is up to you to determine if these features match your organization’s requirements.
