Power Down System Exit Programs
Required Parameters: None
Exit Point Name: QIBM_QWC_PWRDWNSYS
Exit Point Format Name: PWRD0100
Required Parameter Group:
| 1 | Exit information | Input/Output | Char(*) |
| 2 | Format of exit information | Input | Char(8) |
| 3 | Action | Input | Char(1) |
| 4 | Delay time | Input | Binary(4) |
QSYSINC Member Name: EWCPWRD
Exit Point Name: QIBM_QWC_PWRDWNSYS
Exit Point Format Name: PWRD0200
For format PWRD0100, the Power Down System exit program is called when the Power Down System (PWRDWNSYS) or End System (ENDSYS) command is used. There are no input or output parameters for this format. See PWRD0100 Format Usage Notes for more information.
For format PWRD0200, the Power Down System exit programs are called only when the Power Down System (PWRDWNSYS) command is used. See Format PWRD0200 Required Parameter Group for parameter information or PWRD0200 Format Usage Notes for usage information.
Authorities and Locks
- A user must have all object (*ALLOBJ) and security administrator (*SECADM) special authorities to add or remove exit programs to/from an exit point.
- If a user exit program is defined to the Pre power down system exit point (QIBM_QWC_PWRDWNSYS) for format PWRD0100, then the PWRDWNSYS command issuer must have use (*USE) authority to the user exit program and execute (*EXECUTE) authority to the library that contains that program. If not, then this user exit program will not be called and the system will continue to power down.
Format PWRD0100 Required Parameter
None.
Format PWRD0200 Required Parameter Group
- Exit information
- INPUT/OUTPUT CHAR(*)
The exit information used to communicate with the exit program.
- Format of the exit information.
- INPUT; CHAR(8)
The format of the exit program information. The following formats may be passed to the exit program:
PDPF0100 Pre powered down state format if the Action parameter specifies a Check action request. For details, see PDPF0100 Format. PDPF0200 Pre powered down state format if the Action parameter specifies an Execute or Cancel action request. For details, see PDPF0200 Format.
- Action
- INPUT; CHAR(1)
The type of exit program call being made. The following actions may be requested:
1 Check The exit program should determine if a powered down state can be reached. The exit program should set the Status flag and Wait time values appropriately. 2 Execute The exit program should start the process of preparing for a powered down state. 3 Cancel The exit program should reset any preliminary actions it may have taken while handling a previous Check action request. See PWRD0200 Format Usage Notes for all possible reasons that the user exit programs will be called for Cancel action processing.
- Delay time
- INPUT; BINARY(4)
The time specified for the delay when jobs are ended. This value represents the values passed in for the How to end (OPTION) and Controlled end delay time (DELAY) parameters on the Power Down System (PWRDWNSYS) command. The possible values are:
-1 The jobs are ended in an immediate manner because the PWRDWNSYS command had parameter OPTION(*IMMED). -2 The jobs are ended in a controlled manner because the PWRDWNSYS command had parameters OPTION(*CNTRLD) and DELAY(*NOLIMIT). delay time The delay time entered on the PWRDWNSYS command for a controlled end. The jobs are ended in a controlled manner because the PWRDWNSYS command had parameters OPTION(*CNTRLD) and DELAY(delay time). This value can range from 1 to 99999 seconds.
PDPF0100 Format
The following table describes the information that is located in the Exit information parameter for the PDPF0100 format. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Exit information length |
| 4 | 4 | BINARY(4) | Status flag |
| 8 | 8 | BINARY(4) | Wait time |
Field Descriptions
Exit information length The length of the exit information. This is set to 12.
Status flag A value that should be set by each exit program to indicate whether a powered down state can be reached or not. The possible values are as follows:
| 0 | No, a powered down state cannot be reached at this time. The exit program should set this value if it determines that the power down should not be performed. All prior exit programs that have been called with a Check action request will be called again with a Cancel action request to reset any preliminary actions taken while handling the Check action request. |
| 1 | Yes, a powered down state can be reached. |
Wait time The number of seconds that the system should wait for the exit program to complete the Execute action request. The exit programs can set this to a value between 1 and 3600 seconds. An attempt is made to run each exit program asynchronously via a batch job (asynchronous batch job method). If the batch job method fails for some reason, such as due to being in restricted state, or the subsystem is ending controlled, then another attempt will be made to execute the exit program synchronously via a direct call (synchronous direct call method). As you can see, there could be a mixture of asynchronous and synchronous methods used to run all the exit programs for the power down. Thus, both method's considerations described below must be accounted for when setting this value.
Both method's considerations are met if the sum of all the Wait times returned by the exit programs are less than 3600 seconds and if all exit programs finish Execute action processing in less time than their specified Wait time.
Asynchronous batch job method considerations:
For the Execute action processing, each exit program will be run in a separate job to allow multiple exit programs to be run at the same time. When setting the Wait time, the following needs to be considered:
- The largest value within this range that is set and returned by any exit program will be used as the maximum wait time.
- If none of the exit programs return a value, then a value of 30 seconds is used as the maximum wait time.
- If a value greater than 3600 is returned by any exit program, then 3600 will be used as the maximum wait time.
- For an immediate power down, the system will continue to power down after the maximum wait time has passed, and any exit programs that have not finished processing will be ended. For a controlled power down, the exit programs will be allowed to process longer than the maximum wait time depending on the value of the Delay time parameter.
Synchronous direct call method considerations:
For the Execute action processing, each exit program will be run sequentially in the same job where the PWRDWNSYS command was invoked. Each exit program will be called one after the other, but only after the prior exit program completes (serial) and only if there is time left to process. When setting the Wait time, the following needs to be considered:
- 3600 seconds is the maximum wait time for all the exit programs to complete. The value set by the user exit program will be used to determine how long to wait for the completion of that program. If the program goes over the specified time, then the program will be terminated and a CPF18C8 diagnostic message will result. If the exit program finishes under the time specified, then only the actual time used will be subtracted from the maximum time allowed (3600 seconds).
- For each exit program that didn't return a value, a value of 30 seconds will be used for that exit program.
- If a value greater than 3600 is returned by a exit program, then 3600 will be used for that exit program.
- For an immediate or controlled power down, the system will continue to power down after the maximum wait time has passed (3600 seconds), and any exit program that has not finished processing will be ended. Any exit programs that were in line to be called after this ended exit program will not be called to run.
PDPF0200 Format
The following table describes the information that is located in the Exit information parameter for the PDPF0200 format. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Exit information length |
| 4 | 4 | BINARY(4) | Execute wait time |
Field Descriptions
Execute wait time The number of seconds that the system will wait for this exit program to complete the Execute action request. This value is passed into the exit program as input and is essentially the same Wait time value that was determined during the Check action request. For the asynchronous method, this value will be set to the maximum wait time determined during the Check action request (value passed into each exit program will be the same). For synchronous method, this value will be set to the lesser of the Wait time returned by the exit program and the time left to process out of a maximum of 3600 seconds (value passed into each exit program may vary). This value does not apply to Cancel action requests.
Exit information length The length of the exit information. This is set to 8.
PWRD0100 Format Usage Notes
When a user issues the PWRDWNSYS or ENDSYS command, the operating system calls the user-written exit program that was added through the registration facility. The user-written exit program is not called for the following:
- If the system is already in restricted state.
- If the system is being powered down immediately while on auxiliary power. See the system value Uninterruptible power supply message queue (QUPSMSGQ) for this situation.
- If the system is ending because the storage lower limit is reached and the system value Auxiliary storage lower limit action (QSTGLOWACN) has a value of *ENDSYS or *PWRDWNSYS.
- If the system is ending because of an auditing error and the system value Auditing end action (QAUDENDACN) is set with *PWRDWNSYS.
- If the system is a secondary partition and is powering down because the primary partition is powering down.
- If the system is powering down because of a critical hardware detected situation.
- If shut-down was initiated from outside the partition, such as from the control panel or HMC.
This exit point supports one exit program. For information about adding an exit program to an exit point, see Registration Facility APIs.
The Power Down System exit point ignores any return codes or error messages that are sent from the exit program.
It is recommended that the Power Down System exit program exist in a library in the system auxiliary storage pool (ASP) or in a basic user ASP. It might not be found if it exists in a library in an independent ASP.
PWRD0200 Format Usage Notes
When a user issues the PWRDWNSYS command, the operating system calls the user-written exit programs that were added to the exit point through the registration facility. The user-written exit programs are not called for the following:
- If the system is being powered down immediately while on auxiliary power and this state is identified before Check action processing. See the system value Uninterruptible power supply message queue (QUPSMSGQ) for this situation.
- If the system is being powered down immediately and the system goes to auxiliary power after Check action processing has begun but before Execute action processing has begun. For this case, the Execute action phase will be skipped and the user exit programs will not be called for Cancel processing. The system will continue to power down.
- If the system is ending because the storage lower limit is reached and the system value Auxiliary storage lower limit action (QSTGLOWACN) has a value of *PWRDWNSYS.
- If the system is ending because of an auditing error and the system value Auditing end action (QAUDENDACN) is set with *PWRDWNSYS.
- If the system is a secondary partition and is powering down because the primary partition is powering down.
- If the system is powering down because of a critical hardware detected situation.
- If shut-down was initiated from outside the partition, such as from the control panel or HMC.
Unlike the exit program associated with format PWRD0100, the exit programs associated with PWRD0200 will be called if the system is powered down immediately or in a controlled manner from restricted state.
This exit point supports more than one exit program (no maximum). For information about adding an exit program to an exit point, see Registration Facility APIs.
If there are exit programs specified for both formats (PWRD0100 and PWRD0200) then both format exit program(s) will be called. This can occur for a normal controlled or immediate power down. When this occurs, the PWRD0200 exit programs will be called first followed by the PWRD0100 exit program.
Format PWRD0200 provides a method for the system to determine if a powered down state can be reached. The Action field will have values which will be used to determine what the exit program should do. Each exit program will be called multiple times from the PWRDWNSYS command processing program. Each exit program will be called first with a Check action request to determine if the powered down state can be safely reached and how much time might be required. If an exit program determines that a powered down state cannot be reached at this time (0 Status flag is returned), or if the PWRDWNSYS command is canceled during this Check processing, or if a confirmation panel is displayed after this Check processing and the user elects to not continue the power down, then all prior exit programs that have been called with a Check action request will be called again with a Cancel action request. Each exit program should reset any preliminary actions it may have made.
If all exit programs return a Yes (1 Status flag is returned) during the Check action phase, then each exit program will be called again with an Execute action. An Execute action will be used to instruct the exit program to perform it's pre powered down state work. These jobs will run under the user profile who issued the PWRDWNSYS command. Once the exit program is called with an Execute action, it will either be allowed to complete it's task or it will be terminated if the calculated Wait time is exceeded. Note that once the PWRDWNSYS command reaches the Execute action phase, the command can no longer be canceled.
If the PWRDWNSYS command is run again while the exit programs are processing the Execute action, then the exit programs will have to handle this situation where the Execute action processing may have already occurred and is currently being run in another job. The exit programs will also have to handle any necessary serialization.
Errors detected by the PWRDWNSYS command processing program (unable to call exit program, invalid status flag, and so on) will be treated as if a powered down state can be reached (same as status flag value of 1 being returned).
It is recommended that the Power Down System exit programs exist in a library in the system auxiliary storage pool (ASP number 1) or in a basic user ASP (ASP numbers 2-32). It might not be found if it exists in a library in an independent ASP.
Exit program introduced: V4R2