230 lines
14 KiB
HTML
230 lines
14 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html lang="en-us" xml:lang="en-us">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="security" content="public" />
|
|
<meta name="Robots" content="index,follow" />
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
|
<meta name="DC.Type" content="task" />
|
|
<meta name="DC.Title" content="Example: Power-handling CL program" />
|
|
<meta name="abstract" content="You can use the sample program with a full uninterruptible power supply." />
|
|
<meta name="description" content="You can use the sample program with a full uninterruptible power supply." />
|
|
<meta name="DC.Relation" scheme="URI" content="rzahrwrtpgmco.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="rzahrimpgmpi.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="rzahrtstpgmrx.htm" />
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
|
<meta name="DC.Format" content="XHTML" />
|
|
<meta name="DC.Identifier" content="rzahrxmppgmrx" />
|
|
<meta name="DC.Language" content="en-us" />
|
|
<!-- 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. -->
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
|
<title>Example: Power-handling CL program</title>
|
|
</head>
|
|
<body id="rzahrxmppgmrx"><a name="rzahrxmppgmrx"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Example: Power-handling CL program</h1>
|
|
<div><p>You can use the sample program with a full uninterruptible power
|
|
supply.</p>
|
|
<div class="section"> <p>Although this sample CL program will work correctly as written,
|
|
you should tailor it to your specific system requirements. For example, add
|
|
additional recovery to the program by monitoring for error conditions specific
|
|
to your system. You will also need to supply a user-written program that
|
|
performs the steps necessary to prepare for a normal shutdown of the system.
|
|
These steps may include holding job queues, sending messages, and ending subsystems.
|
|
The program should restart normal operations should the power outage end before
|
|
the system is powered down.</p>
|
|
<div class="note"><span class="notetitle">Note:</span> By using the code examples, you agree
|
|
to the terms of the <a href="codedisclaimer.htm">Code license and disclaimer information</a>.</div>
|
|
<p>The
|
|
program performs the following:</p>
|
|
</div>
|
|
<ol><li class="stepexpand"><span>The power-handling program retrieves the system value QUPSMSGQ
|
|
into the variables &LIB and &MSGQ. Although this is not absolutely
|
|
necessary, it does help to ensure that the correct message queue is allocated
|
|
each time the program is started. The program then deletes the message queue
|
|
(if it already exists) and then creates it again. This step helps eliminate
|
|
clearing the message queue or any problems that might occur if the message
|
|
queue is damaged.</span></li>
|
|
<li class="stepexpand"><span>After the message queue has been created, the program must allocate
|
|
(ALCOBJ command) the message queue exclusively.</span> <div class="note"><span class="notetitle">Note:</span> When the
|
|
system value QUPSDLYTIM is set to *NOMAX, use one of the following methods
|
|
to allocate the message queue that is specified for system value QUPSMSGQ: <ul><li>Use the command <samp class="codeph">CHGMSGQ MSGQ(UPSLIB/UPSMSGQ) MODE(*BREAK)</samp></li>
|
|
<li>Include the ALCOBJ command within the power-handling program</li>
|
|
</ul>
|
|
<p>You may only use one of the methods that are listed.</p>
|
|
</div>
|
|
<p>If
|
|
a user or a program has not allocated the message queue, and a power outage
|
|
occurs, the system performs an immediate quick shut down.</p>
|
|
</li>
|
|
<li class="stepexpand"><span>At label <samp class="codeph">A</samp> in the example power handling program,
|
|
the Receive Message (RCVMSG) command is used to determine what message has
|
|
been sent to the message queue. The RCVMSG command is also used to determine
|
|
the amount of wait time (WAIT parameter) throughout the program.</span> <p>On
|
|
line <samp class="codeph">27.00</samp> of the example power-handling program, the value
|
|
of the WAIT parameter on the RCVMSG command causes the program to wait 600
|
|
seconds (ten minutes). After ten minutes, the program checks to see if a controlled
|
|
end to the job has occurred (using the ENDSBS or ENDJOB command). This prevents
|
|
the program from delaying the ENDJOB or ENDSBS command.</p>
|
|
<p>If you use ENDSBS
|
|
*IMMED or ENDJOB *IMMED, then this part of the program can be removed. You
|
|
can change the value for the WAIT parameter on the RCVMSG command to *MAX.
|
|
The RCVMSG command runs immediately if the system sends a message to the message
|
|
queue that is specified on the RCVMSG command. This occurs regardless of the
|
|
value that is specified for the WAIT parameter.</p>
|
|
</li>
|
|
<li class="stepexpand"><span>If the message that is received by the RCVMSG command is CPF1816
|
|
(system utility power failed), the program checks to see if this is a short
|
|
power failure. The program runs a second RCVMSG command with a value of ten
|
|
seconds for the WAIT parameter (you must decide how many seconds is adequate
|
|
for your site).</span> <p>If the message that is received by the RCVMSG
|
|
command within the specified ten seconds is CPF1817 (system utility power
|
|
restored), then power was restored. The program returns to label <samp class="codeph">A</samp> and
|
|
starts the cycle again.</p>
|
|
<div class="p">If the ten second limit is reached and no message
|
|
is received, then the power failure is longer than ten seconds and additional
|
|
steps are necessary. At this point, you can call a user-written program that
|
|
performs the following actions: <ul><li>The program uses the HLDJOBQ command to hold certain long running batch
|
|
jobs</li>
|
|
<li>The program notifies unaffected remote users</li>
|
|
<li>The program begins ending jobs and subsystems in an orderly manner</li>
|
|
</ul>
|
|
</div>
|
|
</li>
|
|
<li class="stepexpand"><span>At label <samp class="codeph">B</samp>, in the example power-handling program,
|
|
the program attempts to wait-out the power failure. The program retrieves
|
|
the present time and places this information into a CL variable that is named &START.
|
|
The present time is used to determine how much uninterruptible power supply
|
|
time is left.</span> <p>A third RCVMSG command runs, and a CL variable
|
|
that is named &WAIT (that was changed earlier in the program) determines
|
|
the value for the WAIT parameter. The CL variable &WAIT is the amount
|
|
of reserve power the uninterruptible power supply can provide. The value for
|
|
the &WAIT variable at label A should be adjusted to the amount of reserve
|
|
power that the uninterruptible power supply can provide. (The amount of reserve
|
|
power is measured in seconds.)</p>
|
|
<p>In the example program, the value of
|
|
the &WAIT variable is set to 1200 seconds (20 minutes). If message CPF1817
|
|
(System utility power restored) is received during that time, then power <em>has</em> been
|
|
restored, and another program can be called to restart normal system operations.
|
|
The program then returns to label A and starts the cycle again. If message
|
|
CPF1817 is not sent after 1200 seconds, then RCVMSG returns a blank message
|
|
ID (not equal to CPF1817). This indicates that power has <em>not</em> been restored
|
|
and an immediate system shut down is started. If a message other than CPF1817
|
|
is received during this 1200 second wait, the following actions occur:</p>
|
|
<ol type="a"><li>The program retrieves the present time, and calculates how much of the
|
|
1200 second wait period has elapsed.</li>
|
|
<li>The program subtracts the difference, and changes the CL variable &WAIT
|
|
to reflect that amount.</li>
|
|
<li>The program returns to label B to use the remaining power that is provided
|
|
by the uninterruptible power supply.</li>
|
|
</ol>
|
|
<p>This part of the program checks to see if a date change occurs, which
|
|
is necessary should the power outage occur on a different date.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="section"> <div class="fignone"><pre>SEQNBR*...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...
|
|
1.00 PGM
|
|
2.00 DCL VAR(&UPSMSGQ) TYPE(*CHAR) LEN(20)
|
|
3.00 DCL VAR(&LIB) TYPE(*CHAR) LEN(20)
|
|
4.00 DCL VAR(&MSGQ) TYPE(*CHAR) LEN(20)
|
|
5.00 DCL VAR(&MSGID) TYPE(*CHAR) LEN(7)
|
|
6.00 DCL VAR(&ENDSTS) TYPE(*CHAR) LEN(1)
|
|
7.00 DCL VAR(&WAIT) TYPE(*DEC) LEN(6)
|
|
8.00 DCL VAR(&HOUR) TYPE(*DEC) LEN(6)
|
|
9.00 DCL VAR(&MIN) TYPE(*DEC) LEN(6)
|
|
10.00 DCL VAR(&SEC) TYPE(*DEC) LEN(6)
|
|
11.00 DCL VAR(&TIME) TYPE(*CHAR) LEN(6)
|
|
12.00 DCL VAR(&START) TYPE(*DEC) LEN(6)
|
|
13.00 DCL VAR(&END) TYPE(*DEC) LEN(6)
|
|
14.00 DCL VAR(&RESULT) TYPE(*DEC) LEN(6)
|
|
15.00
|
|
16.00 RTVSYSVAL SYSVAL(QUPSMSGQ) RTNVAR(&UPSMSGQ)
|
|
17.00 CHGVAR VAR(&MSGQ) VALUE(%SST(&UPSMSGQ 1 10))
|
|
18.00 CHGVAR VAR(&LIB) VALUE(%SST(&UPSMSGQ 11 10))
|
|
19.00 DLTMSGQ MSGQ(&LIB/&MSGQ)
|
|
20.00 MONMSG MSGID(CPF2105) /* Message queue not found. */
|
|
21.00 CRTMSGQ MSGQ(&LIB/&MSGQ) TEXT('UPS Power handling +
|
|
22.00 program message queue') AUT(*EXCLUDE)
|
|
23.00 ALCOBJ OBJ((&LIB/&MSGQ *MSGQ *EXCL))
|
|
24.00
|
|
25.00 A: RCVMSG MSGQ(&LIB/&MSGQ) WAIT(600) RMV(*YES) +
|
|
26.00 MSGID(&MSGID)
|
|
27.00 IF COND(&MSGID *NE CPF1816) THEN(DO)
|
|
28.00 RTVJOBA ENDSTS(&ENDSTS)
|
|
29.00 IF COND(&ENDSTS *EQ '1') THEN(GOTO CMDLBL(ENDPGM))
|
|
30.00 GOTO CMDLBL(A)
|
|
31.00 ENDDO
|
|
32.00
|
|
33.00 /* Check to see if this is a short power outage. */
|
|
34.00 IF COND(&MSGID *EQ CPF1816) THEN(DO)
|
|
35.00 RCVMSG MSGQ(&LIB/&MSGQ); WAIT(10) RMV(*YES) +
|
|
36.00 MSGID(&MSGID); /* Wait ten seconds)
|
|
37.00 IF COND(&MSGID *EQ CPF1817) THEN(GOTO CMDLBL(A))
|
|
38.00 ENDDO
|
|
39.00
|
|
40.00 /* Power outage was longer than 10 seconds. */
|
|
41.00 CALL PGM(LIB/PGM) /* User program that prepares +
|
|
42.00 system for possible shutdown. */
|
|
43.00</pre>
|
|
</div>
|
|
<div class="fignone"><pre>44.00 /* Check to see if this is a long power outage. */
|
|
45.00 CHGVAR VAR(&WAIT); VALUE(01200) /* 20 minutes. */
|
|
46.00 B: RTVSYSVAL SYSVAL(QTIME) RTNVAR(&TIME);
|
|
47.00 CHGVAR VAR(&HOUR); VALUE(%SST(&TIME 1 2))
|
|
48.00 CHGVAR VAR(&MIN); VALUE(%SST(&TIME 3 2))
|
|
49.00 CHGVAR VAR(&SEC); VALUE(%SST(&TIME 5 2))
|
|
50.00 CHGVAR VAR(&START); VALUE((&SEC); + (&MIN * 60) + +
|
|
51.00 (&HOUR * 3600))
|
|
52.00 RCVMSG MSGQ(&LIB/&MSGQ); WAIT(&WAIT); RMV(*YES) +
|
|
53.00 MSGID(&MSGID);
|
|
54.00 IF COND(&MSGID *EQ CPF1817) THEN(DO)
|
|
55.00 CALL PGM(LIB/PGM) /* User program that restarts +
|
|
56.00 system operations. */
|
|
57.00 GOTO CMDLBL(A)
|
|
58.00 ENDDO
|
|
59.00
|
|
60.00 IF COND(&MSGID *NE CPF1817) THEN(DO)
|
|
61.00 RTVSYSVAL SYSVAL(QTIME) RTNVAR(&TIME)
|
|
62.00 CHGVAR VAR(&HOUR) VALUE(%SST(&TIME 1 2))
|
|
63.00 CHGVAR VAR(&MIN) VALUE(%SST(&TIME 3 2))
|
|
64.00 CHGVAR VAR(&SEC) VALUE(%SST(&TIME 5 2))
|
|
65.00 CHGVAR VAR(&END) VALUE((&SEC) + (&MIN * 60) + +
|
|
66.00 (&HOUR * 3600))
|
|
67.00 CHGVAR VAR(&RESULT); VALUE(&END - &START)
|
|
68.00 IF COND(&RESULT < 0) THEN(CHGVAR VAR(&RESULT) +
|
|
69.00 VALUE(86400 + &RESULT)) /* Check for +
|
|
70.00 change of day. 86400 = 24 hours. */
|
|
71.00 IF COND(&RESULT *GE &WAIT) THEN(PWRDWNSYS +
|
|
72.00 OPTION(*IMMED) /* uninterruptible power supply
|
|
battery reserve has expired. */
|
|
74.00
|
|
75.00 CHGVAR VAR(&WAIT) VALUE(&WAIT - &RESULT) /* UPS +
|
|
76.00 battery reserve has not expired. */
|
|
77.00 GOTO CMDLBL(B)
|
|
78.00 ENDDO
|
|
79.00
|
|
80.00 ENDPGM: DLCOBJ OBJ((&LIB/&MSGQ *MSGQ *EXCL))
|
|
81.00 ENDPGM</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzahrwrtpgmco.htm" title="A power-handling program should be activated at each IPL and remain active at all times. It should be accounted for in the activity level available in work management subsystem specifications.">Writing a power-handling program</a></div>
|
|
</div>
|
|
<div class="reltasks"><strong>Related tasks</strong><br />
|
|
<div><a href="rzahrimpgmpi.htm" title="This topic highlights what you need to do to use a power-handling program for a system when a full uninterruptible power supply is attached.">Implementing a power-handling program</a></div>
|
|
</div>
|
|
<div class="relref"><strong>Related reference</strong><br />
|
|
<div><a href="rzahrtstpgmrx.htm" title="Once 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. Set the DLY parameter value on the DLYJOB command to meet your testing needs.">Example: Testing a power-handling CL program</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |