| Keep Those Batch Jobs Running (Or How to Enjoy Your Off Time) |
 |
 |
 |
| Programming - APIs | |||||||||||||||||||||||||||||||||||||||||
| Written by Bruce Vining | |||||||||||||||||||||||||||||||||||||||||
| Tuesday, 02 September 2008 19:00 | |||||||||||||||||||||||||||||||||||||||||
|
With the QUSLJOB API and my MONBCH program working for you, you can relax when you're away from the office.
My recent series of articles prompted the following note from reader Jerry G.:
"I enjoy reading your articles as a learning exercise.... Would you consider demonstrating an API example to monitor jobs [in order to] notify [someone of] a troubled state like MSGW?"
In a subsequent article, we'll look at a V6R1 enhancement that allows us to easily send the text of the message to the *DTAQ (in addition to the job information, which is available on earlier releases). This enhancement allows the operator to know not only the specific message that needs to be responded to, but also the replies available. From here, it would not be a large leap to enable the operator to respond to the message using a handheld device. So if you haven't ordered V6R1, now is the time to do it!
The program we will use, Monitor Batch (MONBCH), is shown below.
h dftactgrp(*no)
dMonBch pr extpgm('MONBCH') dMonBch pi
dSetup pr * dDelay pr dProcessMsgW pr
dListJob pr extpgm('QSYS/QUSLJOB') d SpcName 20 const d Format 8 const d JobName 26 const d Status 10 const d QUSEC likeds(QUSEC) options(*nopass) d JobType 1 const options(*nopass) d NbrKeyFlds 10i 0 const options(*nopass) d KeyFlds likeds(KeyFlds) options(*nopass) d ContinHdl 48 const options(*nopass)
dSndDtaQMsg pr extpgm('QSYS/QSNDDTAQ') d DtaQName 10 const d DtaQLib 10 const d DataLen 5 0 const d Data 65535 const options(*varsize) d KeyLen 3 0 const options(*nopass) d KeyValue 65535 const options(*varsize :*nopass) d Asynch 10 const options(*nopass) d JrnEntry 10 const options(*nopass)
/copy qsysinc/qrpglesrc,qusgen /copy qsysinc/qrpglesrc,qusljob /copy qsysinc/qrpglesrc,qusec
dGenHdr ds likeds(QUSH0100) d based(GenHdrPtr)
dLstEntry ds likeds(QUSL020001) d based(LstPtr)
dAttrEntry ds likeds(QUSLKF) d based(AttrPtr)
dKeyFlds ds d KeyValues 10i 0 dim(25)
dUsrSpcName ds d Name 10 inz('MONBCHLJOB') d Library 10 inz('QTEMP')
dJobsToList ds d JobName 10 inz('*ALL') d JobUser 10 inz('*ALL') d JobNbr 6 inz('*ALL')
dPSDS sds 429 qualified d Line 21 28 d MsgID 40 46 d ExcpDta 91 170 d JobName 244 253
dDtaQMsg s 256 dLstCount s 10i 0 dAttrCount s 10i 0 dAttrValue s 100 based(AtrValPtr) dNbrKeyFlds s 10i 0 dContinue s n inz(*on) dMonBchCtl s 1 dtaara('VINING/MONBCHCTL')
dDtaQName c 'MESSAGES' dDtaQLib c 'VINING'
/free
monitor;
GenHdrPtr = Setup();
dow Continue; ListJob( UsrSpcName :'JOBL0200' :JobsToList :'*ACTIVE' :QUSEC :'B' :NbrKeyFlds :KeyFlds :*blanks);
// Check to see if the list is complete if (GenHdr.QUSIS = 'C') or (GenHdr.QUSIS = 'P');
// Get to the first list entry and process the list LstPtr = GenHdrPtr + GenHdr.QUSOLD;
for LstCount = 1 to GenHdr.QUSNBRLE; // Get first attribute and process all returned if LstEntry.QUSJIS = ' '; AttrPtr = LstPtr + %size(QUSL020001); for AttrCount = 1 to LstEntry.QUSNBRFR; AtrValPtr = AttrPtr + %size(QUSLKF); select; when AttrEntry.QUSKF = 0101; if %subst(AttrValue :1 :AttrEntry.QUSLD00) = 'MSGW'; ProcessMsgW(); endif; endsl; AttrPtr += AttrEntry.QUSLFIR; endfor; endif; LstPtr += GenHdr.QUSSEE; endfor; Delay(); else; dsply 'MONBCH is unable to access batch job information.'; *inlr = *on; return; endif; enddo;
*inlr = *on; return;
on-error; DtaQMsg = 'Job ' + %trimr(PSDS.JobName) + ' failed at statement ' + PSDS.Line + ' with message ' + PSDS.MsgID + ': ' + PSDS.ExcpDta; SndDtaQMsg( DtaQName :DtaQLib :%len(%trimr(DtaQMsg)) :DtaQMsg);
return;
endmon;
/end-free
*****************************************************************
pProcessMsgW b
dProcessMsgW pr dProcessMsgW pi
/free
DtaQMsg = 'Job ' + %trimr(LstEntry.QUSJNU00) + ' is waiting on a message.'; SndDtaQMsg( DtaQName :DtaQLib :%len(%trimr(DtaQMsg)) :DtaQMsg);
return;
/end-free
pProcessMsgW e
*****************************************************************
pDelay b
dDelay pr dDelay pi
dSleep pr 10u 0 extproc('sleep') d Seconds 10u 0 value
dTimeToEnd c 'E' dSecsPerMin c 60 dMinsToDly c 15
/free
in MonBchCtl; if MonBchCtl = TimeToEnd; Continue = *off; return; endif;
Sleep(SecsPerMin * MinsToDly);
in MonBchCtl; if MonBchCtl = TimeToEnd; Continue = *off; endif;
return;
/end-free
pDelay e
*****************************************************************
pSetup b
dSetup pr * dSetup pi *
dCrtUsrSpc pr extpgm('QSYS/QUSCRTUS') d SpcName 20 const d SpcAttr 10 const d SpcSiz 10i 0 const d SpcVal 1 const d SpcAut 10 const d SpcTxt 50 const d SpcRpl 10 const options(*nopass) d QUSEC likeds(QUSEC) options(*nopass) d SpcDmn 10 const options(*nopass) d SpcTfrSiz 10i 0 const options(*nopass) d SpcOptAln 1 const options(*nopass)
dRtvSpcPtr pr extpgm('QSYS/QUSPTRUS') d UsrSpcName 20 d UsrSpcPtr * d QUSEC likeds(QUSEC) options(*nopass)
dUsrSpcPtr s *
/free
// Set API error code structure to return exception messages QUSBPRV = 0;
// Set the job attribute key values KeyValues(1) = 0101; // Active job status NbrKeyFlds = 1;
// Create a *USRSPC to hold the list of jobs CrtUsrSpc(UsrSpcName :' ' :1 :x'00' :'*EXCLUDE' :' ' :'*YES' :QUSEC);
// Retrieve a pointer to the *USRSPC RtvSpcPtr(UsrSpcName :UsrSpcPtr :QUSEC);
// Return the pointer to the *USRSPC return UsrSpcPtr;
/end-free
pSetup e
To compile MONBCH is a simple CRTBNDRPG MONBCH. In order to run MONBCH, you will need to create two objects into the library VINING (or some more suitable library name, but don't forget to change VINING references in the MONBCH program source to your new name). The two objects are the data area MONBCHCTL and the data queue MESSAGES. These are the commands to create these objects:
CRTDTAARA DTAARA(VINING/MONBCHCTL) TYPE(*CHAR) LEN(1) CRTDTAQ DTAQ(VINING/MESSAGES) MAXLEN(256)
The MONBCHCTL data area is used to control when MONBCH ends. This is done by setting the data area to a value of E. The MESSAGES data queue is where MONBCH sends messages related to batch jobs being in a message wait state or a failure being detected within the MONBCH program itself.
The main processing within MONBCH is centered around the List Job (QUSLJOB) API. The QUSLJOB API generates a list of all or some jobs on the system. When generating a subset list, you can select jobs that meet particular requirements, such as all jobs on a job queue, all active jobs that are interactive, or, as is the case with MONBCH, all active batch jobs. The API takes up to nine parameters (shown below), four of which are required. The List Job (QUSLJOB) API
Required Parameter Group:
Optional Parameter Group 1:
Optional Parameter Group 2:
Optional Parameter Group 3:
The first parameter, Qualified user space name, is the name of the *USRSPC the API is to return information into. We will be creating this *USRSPC in the Setup procedure of MONBCH.
The second parameter, Format name, describes the type of information we want returned. The QUSLJOB API supports two formats. Format JOBL0100 returns basic job-related information such as the job name, job status, and job type. Format JOBL0200 returns this basic information, but you can also specify additional information about the job that you want returned. This additional information can be as simple as the user profile currently being used by the job or as complex as low-level details, such as the temporary storage currently in use by the job. The full list of available information can be found with the API documentation here. MONBCH will be using format JOBL0200 and requesting one piece of additional information: the active job status. The active job status field can be set to one of several values--for instance, HLD for held jobs, LCKW when the job is waiting for a lock, or MSGW for a job waiting for a reply to a message. MONBCH will be looking specifically for active batch jobs with an active job status of MSGW.
The third parameter, Qualified job name, defines by name what jobs you are interested in. The API defines three subfields for the Qualified job name parameter. The first ten bytes are the job name, the next ten bytes are the user name, and the last six bytes are the job number. The API supports specific job and user names, generic job and user names, and special values such as *CURRENT and *ALL. The MONBCH program will be using the special value *ALL for the job name, user name, and job number components of the Qualified job name.
The fourth parameter, Status, can be used to specify that you want only jobs of a specific status to be returned in the generated list. The supported status values are *ACTIVE, *JOBQ, *OUTQ, or *ALL. MONBCH will use this parameter to specify that only *ACTIVE jobs should be returned by the QUSLJOB API.
The fifth parameter, Error code, is the standard error code structure found with most system APIs.
The sixth parameter, Job type, can be used to specify that you want only certain types of jobs to be returned in the generated list. The Job type parameter supports values such as * for all types, A for autostart jobs, I for interactive jobs, etc. MONBCH will be using the value B to indicate that only batch jobs are to be returned. When this parameter is used in conjunction with the Status parameter value of *ACTIVE, the QUSLJOB API will return only active batch jobs in the user space. MONBCH will not see the other jobs (interactive, spool writers, etc.) that might be on your system.
The seventh and eighth parameters, Number of fields to return and Key of fields to return, respectively, can be used with format JOBL0200 to specify what additional job-related information is wanted. The eighth parameter is an array of 4-byte integer key values identifying the information desired. The seventh parameter is the number of key values that are to be found in this array. With QUSLJOB, each field of additional information is assigned a numeric key value. A value of 305, for instance, indicates that you want the user profile currently in effect for the job to be returned. MONBCH will be using a value of 101: active job status. You can ask for as many additional fields of information as your application needs. In the case of MONBCH, we need only the one additional field, though the array used (KeyValues) is defined as having 25 elements. This "keyed" approach to requesting specific information can be found in other system APIs--and not just List APIs either. For example, both the Retrieve Library Description (QLIRLIBD) API, documented here, and the Change Object Description (QLICOBJD) API, documented here, support a keyed approach to identifying data. Keys are useful when there is a potentially large amount of information that might be retrieved and/or changed and you don't want to have to be concerned with information that the current application doesn't really care about.
The ninth parameter, Continuation handle, is used when there are more jobs in the returned list than can fit in one user space. The continuation handle can be used to have the QUSLJOB API resume writing list entries to the user space after you have processed all of the initial job entries that were returned. We're not going to pay much attention to this parameter today as a user space can hold approximately 16MB of data and each job returned by the QUSLJOB API to our MONBCH program will use less than 100 bytes (based on returning only the basic job information and the active job status). A quick calculation shows that the user space can then hold greater than 160,000 active batch jobs--and I don't imagine that very many of you are running over 160,000 active batch jobs on your system. This continuation handle capability may be very useful for other applications but not for MONBCH.
With that brief introduction to the QUSLJOB API out of the way, let's now look at what the MONBCH program does. The MONBCH ProgramWhen MONBCH is first called, the Setup procedure is run. Setup creates the environment for MONBCH to run in. The system API error code bytes provided field is set to 0, the array KeyValues (used as the eighth parameter when calling QUSLJOB) is set to request active job status information, the user space MONBCHLJOB is created in QTEMP, and a pointer to the first byte of this user space is returned to the caller of Setup. If you have questions on the use of the error code, creating a user space, or obtaining a pointer to a user space, you may want to refer to an earlier article of mine, "The API Corner: Finding Modules in a *SRVPGM," where I provide additional information, or the book IBM System i APIs at Work, Second Edition.
When Setup returns the pointer variable, GenHdrPtr addresses the first byte of the user space. MONBCH then enters into a DoWhile loop conditioned by the variable Continue. Continue is defined as an indicator variable and is initialized to a value of *on. Within the DoWhile loop, MONBCH calls the QUSLJOB API, requesting that a list of all active batch jobs on the system be returned to the user space QTEMP/MONBCHLJOB. By specifying a format of JOBL0200, a KeyValues array containing the key value 101, and a NbrKeyFlds value of 1, MONBCH is also requesting that active job status information be returned for each active batch job.
MONBCH then processes the list using an approach that hopefully you are all familiar with by now. You check the list status (GenHdr.QUSIS) to verify that the list is either complete or partially complete, set the LstPtr pointer variable to address the first entry returned in the list (GenHdrPtr + GenHdr.QUSOLD), and then process all of the entries returned in the list (GenHdr.QUSNBRLE), stepping through the list by adding the size of each list entry (GenHdr.QUSSEE) to the LstPtr pointer variable value.
The actual processing of the list we'll cover in a bit more detail.
Format JOBL0200 of QUSLJOB defines a fixed set of information for each list entry returned. This standard information is provided at the start of each list entry, and the QSYSINC-provided include for this fixed set of information is this:
DQUSL020001 DS D* Qus JOBL0200 D QUSJNU00 1 10 D* Job Name Used D QUSUNU00 11 20 D* User Name Used D QUSJNBRU00 21 26 D* Job Number Used D QUSIJI00 27 42 D* Internal Job Id D QUSTATUS01 43 52 D* Status D QUSJT01 53 53 D* Job Type D QUSJS00 54 54 D* Job Subtype D QUSERVED18 55 56 D* Reserved D QUSJIS 57 57 D* Job Info Status D QUSRSV205 58 60 D* Reserved2 D QUSNBRFR 61 64B 0 D* Number Fields Rtnd D*QUSKFI 18 DIM(00001)
Several of the fields shown above are what you might expect: job name, user name, job type, etc., and several of these will be used later. Three fields, however, need some discussion right now. The first field, QUSJIS (or Job information status), tells you whether or not job-related information was returned. This field should be checked first, as MONBCH does with LstEntry.QUSJIS, where LstEntry is a Based structure defined likeds(QUSL020001), to verify that a blank was returned for the job described by the current list entry. A non-blank value indicates that the job information was not returned and that the entry should not be processed. In the case of MONBCH, we simply skip over the job list entry. The API documentation provides information on what the various non-blank values indicate. If the job information was successfully returned, MONBCH then accesses the additional information returned by QUSLJOB to determine if the job is in a message wait condition. The second field, QUSNBRFR, tells you how many additional fields have been returned for the current job entry. The third field, QUSKFI, is commented out with an array definition of one element. This commented field, QUSKFI, is where the additional information to be returned starts, with QUSNBRFR occurrences of additional information.
Similar to how QUSLJOB returns header information at the start of each job entry, so too does QUSLJOB return header information about each additional field that is returned. This is the QSYSINC include for this field level header information:
DQUSLKF DS D* Qus Ljob Key Fields D QUSLFIR 1 4B 0 D* Length Field Info Rtnd D QUSKF 5 8B 0 D* Key Field D QUSTOD 9 9 D* Type Of Data D QUSERVED17 10 12 D* Reserved D QUSLD00 13 16B 0 D* Length Data D*QUSDATA06 17 17
The first field, QUSLFIR, provides the length of the current field entry returned. This value is used to step to the next additional field entry for the current job entry. QUSKF tells you the key value that you are processing. Note that you should not assume that QUSLJOB will return the additional information fields in the same sequence as you requested it. Always verify the key field value before processing the related data. QUSTOD is the type of data returned (character or binary). QUSLD00 is the length of the data returned, and QUSDATA06 is a commented field of where you can find the returned data starting. As an example, MONBCH is asking for active job status, so for a specific job, QUSLFIR might be anything (which is why you need to use it!), USKF will be 101 (as that is the only key MONBCH asked for), QUSTOD will be C for character, QUSLD00 will most likely be 4, and the data found at QUSDATA06 might be MSGW for message wait, LCKW for lock wait, or any of several other possible values. We can anticipate these values for QUSTOD, QUSLD00, and QUSDATA06 based on the QUSLJOB API documentation.
With that explanation, MONBCH then processes each additional field information entry. Similar to how you process list entries using the List generic header fields information status (QUSIS), Offset to list data (QUSOLD), Number of list entries (QUSNBRLE), and Size of each entry (QUSSEE), you process the job information using the fields Job information status (QUSJIS), Number of fields returned (QUSNBRFR), and Length of field information returned (QUSLFIR). In MONBCH, only one key is requested, but I recommend still coding the program in anticipation of more keys being added at some point in the future (as has been done here). You may, for instance, only want to monitor for jobs in a message wait condition that are running in a specific subsystem. Key 1906--the qualified subsystem description name--would enable such an enhancement. For those interested, an example of using multiple keys and one possible processing flow to follow can be found in the book IBM System i APIs at Work, Second Edition in chapter 5, Object APIs. The example in the book uses QLIRLIBD to retrieve the size of a library in addition to the number of objects in the library.
When a job entry is found that is in a message wait condition, the ProcessMsgW procedure is called. ProcessMsgW doesn't do a whole lot right now, yet the whole purpose of the program is in this procedure. It simply sends a message to the data queue MESSAGES in library VINING, identifying the simple job name for the job that is waiting on a message (LstEntry.QUSJNU00). From this data queue message, another program that is monitoring the MESSAGES data queue could do most any operation that would be appropriate for the situation: page the night operator, set off an alarm, forward the message to a central help desk, etc. In a subsequent article, we will add to the ProcessMsgW procedure. We will see how to use the Retrieve Job Information (QUSRJOBI) API to locate the message the job is waiting on and a Message Handler API to send the actual message that the job is waiting on to the data queue.
After processing all of the job list entries returned by QUSLJOB, MONBCH then runs the Delay procedure. Delay provides two functions in the MONBCH program. First, it reads the data area MONBCHCTL in library VINING. If a value of E (the constant TimeToEnd) is found, indicating that the program should end, Delay turns off the Continue indicator and returns to the initial DoWhile loop. With Continue set *off, MONBCH will exit the DoWhile and end. The second function performed is to delay the next running of the QUSLJOB API for a predetermined amount of time. In the case of MONBCH, the delay will be 15 minutes. Delay does this by using the sleep system API. As its name suggests, sleep simply causes the program to suspend running, or sleep, for a period of time. The sleep API takes one parameter, an unsigned integer representing the number of seconds to sleep. As coded, the Delay procedure calls sleep, asking to be awakened after 15 minutes. During this time, MONBCH will simply be put into a wait state and consume no CPU. After 15 minutes, control is returned by sleep to Delay, Delay checks again if MONBCH should end, and then control returns to the main DoWhile loop to again either call QUSLJOB or to end the program. The sleep API is documented here. If you need more granular control of the delay time than seconds, there is also the usleep API. This API allows you to specify the sleep time in microseconds. There are certain conditions under which the sleep (and usleep) API may return control to Delay before the full 15 minutes are up, but unless you are working with the signal APIs, this should not be a concern.
There's one last part of MONBCH we haven't discussed. Around MONBCH there is a global Monitor group defined. This monitor enables MONBCH to also send a message (or at least try to send a message, depending on the actual failure) to the MESSAGES data queue in case a failure is encountered within MONBCH. It's decidedly a poor design if the job that's monitoring other jobs fails without warning or notification. For that reason, a message is sent to the data queue, indicating that MONBCH has failed. The message in this case includes the statement number where the failure occurred, the message that was received, and the text of the message. Much more extensive information could be captured using additional system APIs, but the message currently being sent will most likely be sufficient to determine what has gone wrong in the MONBCH program. One design point to keep in mind when writing a monitoring function such as MONBCH: don't add unnecessary code as it simply increases the likelihood of an error. If a given function can be done in a separate job, such as actually informing the night operator of a message wait condition, then move that function to that separate job.
That covers the MONBCH program in its entirety and hopefully fulfills the original request: "Would you consider demonstrating an API example to monitor jobs [to] notify [someone of] a troubled state like MSGW?" And along the way, you may have picked up a few more tips and techniques related to the use of system APIs. Next time, we'll look at how to access the actual message that the job is waiting on.
Meanwhile, if you have other API questions, send them to me at bvining@brucevining.com. I'll see what I can do about answering your burning questions in future columns.
| |||||||||||||||||||||||||||||||||||||||||
View all articles by this author
|
|||||||||||||||||||||||||||||||||||||||||
| Last Updated on Tuesday, 02 September 2008 09:26 | |||||||||||||||||||||||||||||||||||||||||
