ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/xpwrdwn.htm

529 lines
21 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Power Down System Exit Programs</title>
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Begin Header Records ========================================= -->
<!-- WM SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- File cleanup completed Nov 2001 by v2cdijab -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Power Down System Exit Programs</h2>
<div class="box" style="width: 75%;">
<br>
&nbsp;&nbsp;Required Parameters: None<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Name: QIBM_QWC_PWRDWNSYS&nbsp;&nbsp;<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Format Name: PWRD0100<br>
<!-- iddvc RMBR -->
<br>
</div>
<img src="delta.gif" alt="Start of change">
<div class="box" style="width: 75%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Exit information</td>
<td align="left" valign="top" width="20%">Input/Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">2</td>
<td align="left" valign="top" width="50%">Format of exit information</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">3</td>
<td align="left" valign="top" width="50%">Action</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">4</td>
<td align="left" valign="top" width="50%">Delay time</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;QSYSINC Member Name: EWCPWRD<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Name: QIBM_QWC_PWRDWNSYS<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Format Name: PWRD0200<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>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 <a href="#HDRUSAGE1">PWRD0100 Format Usage Notes</a> for more information.</p>
<p>For format PWRD0200, the Power Down System exit programs are called only when the Power Down System
(PWRDWNSYS) command is used. See <a href="#HDRPARMS2">Format PWRD0200 Required Parameter Group</a>
for parameter information or <a href="#HDRUSAGE2">PWRD0200 Format Usage Notes</a> for usage information.<img src="deltaend.gif" alt="End of change"></p>
<br>
<h3>Authorities and Locks</h3>
<ul>
<li>A user must have all object (*ALLOBJ) and security administrator (*SECADM)
special authorities to add or remove exit programs to/from an exit point.
</li>
<li>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.
</li>
</ul>
<br>
<h3>Format PWRD0100 Required Parameter</h3>
<dl>
<dd>None.</dd>
</dl>
<h3><img src="delta.gif" alt="Start of change"><a name="HDRPARMS2">Format PWRD0200 Required Parameter Group</a></h3>
<dl>
<dt><strong>Exit information</strong></dt>
<dd>INPUT/OUTPUT CHAR(*)
<p>The exit information used to communicate with the exit program.</p>
</dd>
<dt><strong>Format of the exit information.</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the exit program information. The following
formats may be passed to the exit program:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>PDPF0100</em></td>
<td align="left" valign="top">Pre powered down state format if the Action
parameter specifies a Check action request. For details, see the
<a href="#HDPDPF0100">PDPF0100</a> format.</td>
</tr>
<tr>
<td align="left" valign="top"><em>PDPF0200</em></td>
<td align="left" valign="top">Pre powered down state format if the Action
parameter specifies an Execute or Cancel action request. For details,
see the
<a href="#HDPDPF0200">PDPF0200</a> format.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Action</strong></dt>
<dd>INPUT; CHAR(1)
<p>The type of exit program call being made. The following actions may be
requested:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>1 Check</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>2 Execute</em></td>
<td align="left" valign="top">The exit program should start the process of
preparing for a powered down state.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3 Cancel</em></td>
<td align="left" valign="top">The exit program should reset any preliminary actions it may have taken
while handling a previous Check action request.
See <a href="#HDRUSAGE2">PWRD0200 Format Usage Notes</a> for all possible
reasons that the user exit programs will be called for Cancel action processing.
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Delay time</strong></dt>
<dd>INPUT; BINARY(4)
<p>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:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>-1 </em></td>
<td align="left" valign="top">The jobs are ended in an immediate manner because the PWRDWNSYS
command had parameter OPTION(*IMMED).</td>
</tr>
<tr>
<td align="left" valign="top"><em>-2 </em></td>
<td align="left" valign="top">The jobs are ended in a controlled manner because the PWRDWNSYS
command had parameters OPTION(*CNTRLD) and DELAY(*NOLIMIT).</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em><i>delay time</i></em></td>
<td align="left" valign="top">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.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3><a name="HDPDPF0100">PDPF0100 Format</a></h3>
<p>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 <a href="#HDRCHKDDE">Field Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Exit information length</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Status flag</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Wait time</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRCHKDDE">Field Descriptions</a></h3>
<p><strong>Exit information length</strong> The length of the exit information.
This is set to 12.</p>
<p><strong>Status flag</strong> 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:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">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.
</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Yes, a powered down state can be reached.</td>
</tr>
</table>
<p><strong>Wait time</strong>
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.
<p>
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.
</p>
<p>
<strong>Asynchronous batch job method considerations:</strong>
<p>
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:
</p>
<ul>
<li>
The largest value within this range that is set and returned by any exit program will be used
as the maximum wait time.
</li>
<li>
If none of the exit programs return a value, then a value of 30 seconds is used as the
maximum wait time.
</li>
<li>
If a value greater than 3600 is returned by any exit program, then 3600 will be used
as the maximum wait time.
</li>
<li>
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.
</li>
</ul>
<p>
<strong>Synchronous direct call method considerations:</strong>
<p>
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:
</p>
<ul>
<li>
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).
</li>
<li>
For each exit program that didn't return a value, a value of 30 seconds will be used
for that exit program.
</li>
<li>
If a value greater than 3600 is returned by a exit program, then 3600 will be used for that
exit program.
</li>
<li>
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.
</li>
</ul>
<br>
<br>
<h3><a name="HDPDPF0200">PDPF0200 Format</a></h3>
<p>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 <a href="#HDREXECFD">Field Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Exit information length</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">4</td>
<td align="center" valign="top" width="10%">4</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Execute wait time</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDREXECFD">Field Descriptions</a></h3>
<p><strong>Execute wait time</strong> 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.
</p>
<p><strong>Exit information length</strong> The length of the exit information.
This is set to 8.</p>
<br>
<h3><a name="HDRUSAGE1">PWRD0100 Format Usage Notes</a></h3>
<p>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:
<ul>
<li>If the system is already in restricted state.</li>
<li>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.
</li>
<li>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.
</li>
<li>If the system is ending because of an auditing error and the
system value Auditing end action (QAUDENDACN) is set with *PWRDWNSYS.</li>
<li>If the system is a secondary partition and is powering down
because the primary partition is powering down.</li>
<li>
If the system is powering down because of a
critical hardware detected situation.
</li>
</ul>
<p>This exit point supports one exit program. For information about adding an
exit program to an exit point, see the <a href="reg1.htm">Registration Facility
APIs</a>.</p>
<p>The Power Down System exit point ignores any return codes or error messages
that are sent from the exit program.</p>
<p>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.</p>
<h3><a name="HDRUSAGE2">PWRD0200 Format Usage Notes</a></h3>
<p>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:
<ul>
<li>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.
</li>
<li>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.
</li>
<li>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.
</li>
<li>If the system is ending because of an auditing error and the
system value Auditing end action (QAUDENDACN) is set with *PWRDWNSYS.</li>
<li>If the system is a secondary partition and is powering down
because the primary partition is powering down.</li>
<li>
If the system is powering down because of a
critical hardware detected situation.
</li>
</ul>
<p>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.
</p>
<p>This exit point supports more than one exit program (no maximum).
For information about adding an exit program to an exit point,
see the <a href="reg1.htm">Registration Facility APIs</a>.</p>
<p>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.</p>
<p>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.
</p>
<p>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.</p>
<p>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.</p>
<p>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).</p>
<p>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.
</p><img src="deltaend.gif" alt="End of change">
<hr>
Exit program introduced: V4R2
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center">
<a href="#Top_Of_Page">Top</a> |
<a href="wm1.htm">Work Management APIs</a> |
<a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>