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?"

I think this is an excellent idea! In this article, we'll look at how to use the List Job (QUSLJOB) API to monitor batch jobs and, if any job is found to be waiting on a message, to then send a generic message to a *DTAQ, identifying the job that is waiting for a reply. Though not shown in this article, a second program could monitor this *DTAQ and then perform operations such as sending a break message to the operator, paging the operator, setting off an alarm, sending a text message to someone's phone, sending an email, and so on.

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:

  Default Public Authority: *USE

  Threadsafe: Conditional

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 Program

When 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 This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.