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
  1. Identify functionality.
  2. Code the program.
  3. Compile the program.
  4. Distribute the program.
  5. Determine who should be authorized.
  6. Configure authorities.
  7. Register the program as an exit program.
Use
  1. 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:

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

FeatureHow 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.

 


Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: January 11, 2018