Writing a power-handling program

 

You should activate the power-handling program at each initial program load (IPL) and keep it active at all times. It should be accounted for in the activity level available in work management subsystem specifications.

The message queue that is specified in QUPSMSGQ is used for uninterruptible power supply message processing. The program normally allocates the queue by specifying the command:

ALCOBJ OBJ(xxx/yyy *MSGQ *EXCL)

When a message arrives, there are some critical messages to process:

• CPF1816: System utility power failed at &1 (this message applies to the battery feature and full power supply)

• CPF1817: System power restored at &1 (this message applies to the battery feature and full power supply)

• CPI0963: System on auxiliary power (this message applies if system power fails during the IPL)

• CPI0994: System power is restored (this message applies to the limited uninterruptible power supply)

You can choose to ignore the other messages.

Your program can handle a brief power interruption without doing any unique processing. For example, when the CPF1816 message arrives, you can set a switch in your program that indicates that the message occurred. The program might then perform a RCVMSG with WAIT(10) to cause a time-out in 10 seconds. If the CPF1817 message is received before the time-out occurs, you can reset the switch and perform no other action.

Your program can prepare for a normal shut down if power is not restored after a brief time period. For example, if you have remote workstations that are still active, you may want to send them a message requesting they sign off quickly. You may want to issue ENDSBS OPTION(*CNTRLD) to prevent new workstations from signing on or new batch work from beginning. If you have batch jobs running, you may want to end them with the following command:

ENDJOB OPTION(*CNTRLD)

This sets an indicator to end the job. Some high-level languages and the control language enable you to test within a program to see if a controlled end job was specified. If the program does not end itself, the default on the ENDJOB command (30 seconds) is used.

You can set a second timer in your program, such as RCVMSG WAIT(120). If utility power has not been restored, you can issue the PWRDWNSYS OPTION(*IMMED) command. The wait time should be specified based on your battery time and the time that is required for a power-down.

If you name a message queue for the QUPSMSGQ system value and *NOMAX for QUPSDLYTIM, the following conditions apply:

• The message queue you specify must be allocated by a program when the CPF1816 message occurs.

• If the message queue you specify is a workstation message queue, it must be in a break or notify mode.

If not, the system assumes that no power handling program exists, and the system will be turned off.

When the system has been placed in a restricted state (for example, ENDSBS *ALL), your uninterruptible power supply handling program will no longer be active. For this reason, it is necessary to prepare an alternate method of dealing with your uninterruptible power supply and any possible power interruptions that may occur while your system is in a restricted state.

For example, when performing a save system (using the SAVSYS command) or reclaim storage (using the RCLSTG command), your uninterruptible power supply program is no longer be active after all subsystems have been ended. Only a single workstation job is active. You can perform one of the following actions as an alternative:

1. After all subsystems have been ended, from the command line change the mode for the message queue specified in system value QUPSMSGQ to *BREAK. This causes all uninterruptible power supply messages to be sent as break messages to the user that is signed on to that workstation. This method enables you to manually decide what to do if a power failure occurs.

2. Change the system value QUPSDLYTIM to some value other than *NOMAX (for example, the number of minutes you want the uninterruptible power supply to ride out the power failure). This method will prevent the system from performing an immediate quick shut down. However, if a power failure occurs, a quick shut down will be performed if the power failure lasts longer than the value specified for the system value QUPSDLYTIM.

3. Change your existing uninterruptible power supply handling program for use as a BREAK HANDLING program which may be used while the system is in a restricted state. This can be done by creating a second version of your uninterruptible power supply program that does not allocate the message queue specified in system value QUPSMSGQ. (In other words, do not use the ALCOBJ command.) To utilize this program while in a restricted state, before starting a dedicated function such as SAVSYS, enter the command:

   CHGMSGQ MSGQ(LIB/MSGQ) DLVRY(*BREAK)
   PGM(LIB/PGM)

   where (LIB/MSGQ) is the name the message queue specified in system value QUPSMSGQ, and (LIB/PGM) is the name of your modified uninterruptible power supply handling program. Now, should a power failure occur, the power failure message is handled by the break handling program, even while a function such as the SAVSYS command is running. To deactivate the break-handling program, either have the user sign off or enter the following command:

   CHGMSGQ MSGQ(LIB/MSGQ) DLVRY(*HOLD)
   PGM(*DSPMSG)

   After you have deactivated the break-handling program, you should immediately start your subsystems and your normal uninterruptible-power-supply handling program.

• Example: Power-handling CL program
  The sample power-handling CL program can help you build your own program according to your specific system requirements.

• Example: Testing a power-handling CL program
  After a power-handling program has been created, you can test it by creating a simple CL program that uses the Send Program Message (SNDPGMMSG) command and the Delay Job (DLYJOB) command.

 

Parent topic:

Enabling a power-handling program to control system activity during a power interruption