Today, we'll extend our API suite using the List Jobs System API.

In the last API Corner article, "Determining Whether Jobs Are Currently Active," we created the service program (*SRVPGM) JOBCHKS. The *SRVPGM exported the function JobActive, which defined one input parameter and returned an indicator. The input parameter could be a simple job name such as DAYEND, a generic job name such as DAYEND*, or a special value such as *CURRENT. If one or more jobs with the specified job name was active, JobActive returned an indicator value of '1'; otherwise, it returned a value of '0'. In this article, we will extend JOBCHKS with another API of our own creation. This API, named JobsActive, will return the number of active jobs with the specified job name and optionally return one or more of the fully qualified job names matching the specified job name.

As we did for JobActive, we'll provide the prototype for JobsActive in source member JobChksPR of QRPGLESRC. The updated source for JobChksPR is this:

/if not defined(JobChks_Prototypes)                    

d JobActive       pr              n                    

d  JobName                      10a   const                  

d JobsActive      pr            10i 0                   

d  JobName                      10a   const                  

d  JobLst                        1a   options(*nopass :*varsize)

d  SizJobLst                    10i 0 const options(*nopass)    

 /define JobChks_Prototypes                          

 /endif               

JobsActive defines one required parameter, JobName; two optional parameters, JobLst and SizJobLst, respectively; and a signed integer return value representing the number of active jobs matching the value of JobName. The JobName parameter, as with the JobName parameter of the JobActive function, can be a simple job name, a generic job name, or one of three special values (*, *CURRENT, or *ALL). JobLst is an optional parameter that is defined as being variable length and can be used to have JobsActive return a list of jobs that are active and match the JobName parameter criteria. SizJobLst is also an optional parameter and represents the size of the JobLst parameter passed to JobsActive. If the SizJobLst parameter is not provided when calling JobsActive, then the JobLst parameter will not be used even if passed.

The JobLst parameter is defined as a data structure of variable length. The first element of the data structure is a 4-byte integer representing the number of qualified job names actually returned in the JobLst parameter. Immediately following this 4-byte integer is an array of qualified job names with each qualified job name being defined as a 10-byte simple job name, a 10-byte user name, and a 6-byte job number. The allocated size of the array, as opposed to the dimensions of the array, is determined by the SizJobLst parameter value less four bytes for the number of qualified job names being returned. The caller of JobsActive can, for instance, allocate the following JobInfo data structure and pass this data structure as the JobLst parameter (along with %size(JobInfo) as the SizJobLst parameter) if they want up to 10 active job names to be returned.

d JobInfo         ds                                        

d  JobsRtnd                     10i 0                       

d  Job                          26a   dim(10)              

d   JobNam                      10a   overlay(Job :1)       

d   JobUsr                      10a   overlay(Job :11)      

d   JobNbr                       6a   overlay(Job :21)      

If the caller wants up to 100 active job names, then they can simply change the dim(10) specification for subfield Job to dim(100) and recompile the calling application program. Using %size(JobInfo) for the SizJobLst parameter when calling JobsActive will then inform the JobsActive function that there is sufficient room in JobLst for up to 100 job entries.

With that introduction to JobsActive out of the way, let's see what needs to be changed relative to the JOBCHKS *SRVPGM. First, we need to define JobsActive as an export of JOBCHKS, so here is the updated source member JOBCHKS of source file QSRVSRC.

StrPgmExp  PgmLvl(*Current) Signature('JOBCHKS')    

  Export     Symbol("JOBACTIVE")                    

  Export     Symbol("JOBSACTIVE")                    

EndPgmExp           

Second, we need to actually implement JobsActive, so here is the updated QRPGLESRC source for JOBCHKS itself.

h nomain                                                                  

d GetJobList      pr                                                      

d  JobName                      10a   const                               

d  Status                       10a   const                                

 /copy qrpglesrc,JobChksPR                                                

 *************************************************************            

d CrtUsrSpc       pr                  extpgm('QUSCRTUS')                  

d  QualUsrSpcN                  20a   const                               

d  XAttr                        10a   const                               

d  IntSize                      10i 0 const                               

d  IntValue                      1a   const                                

d  PubAut                       10a   const                               

d  TxtDesc                      50a   const                               

d  ReplaceOpt                   10a   const options(*nopass)              

d  ErrCde                             likeds(QUSEC) options(*nopass)      

d  Domain                       10a   const options(*nopass)           

d  TfrSize                      10i 0 const options(*nopass)           

d  OptSpcAlgn                    1a   const options(*nopass)           

d LstJobs         pr                  extpgm('QUSLJOB')                

d  QualUsrSpcN                  20a   const                            

d  Format                        8a   const                            

d  QualJobName                  26a   const                            

d  Status                       10a   const                            

d  ErrCde                             likeds(QUSEC) options(*nopass)   

d  JobType                       1a   const options(*nopass)           

d  NbrFldsRtn                   10i 0 const options(*nopass)           

d  FldKeys                      10i 0 const options(*nopass)           

d  CntHandle                    48a   const options(*nopass)           

d RtvUsrSpcPtr    pr                  extpgm('QUSPTRUS')               

d  QualUsrSpcN                  20a   const                            

d  UsrSpcPtr                      *                                    

d  ErrCde                             likeds(QUSEC) options(*nopass)   

 ***********************************************************      

d JobHdrPtr       s               *                               

d LJobHdr         ds                  likeds(QUSH0100)            

d                                     based(JobHdrPtr)            

d JobDtaPtr       s               *                               

d LJobDta         ds                  likeds(QUSL010002)          

d                                     based(JobDtaPtr)            

d                sds                                               

d curJobName            244    269                                

d ErrCde          ds                  qualified                   

d  Hdr                                likeds(QUSEC)               

d  MsgDta                      256a                               

 /copy qsysinc/qrpglesrc,qusec                                    

 /copy qsysinc/qrpglesrc,qusgen                                   

 /copy qsysinc/qrpglesrc,qusljob                                  

 ***********************************************************      

p JobActive       b                   export                      

d JobActive       pi              n                               

d  JobName                      10a   const                       

 /free                                                            

  QUSBPrv = 0;                                                     

  ErrCde.Hdr.QUSBPrv = %size(ErrCde);                             

  if %subst(JobName :1 :1) = '*';                                 

     return *on;                                                  

  endif;                                                          

  GetJobList(JobName :'*ACTIVE');                                  

  return (LJobHdr.QUSNbrLE <> 0);                                 

 /end-free                                                           

p JobActive       e                                                 

 ***********************************************************        

p JobsActive      b                   export                        

d JobsActive      pi            10i 0                               

d  JobName                      10a   const                         

d  JobInfo                       1a   options(*nopass :*varsize)    

d  SizJobInfo                   10i 0 const options(*nopass)        

d JobInfHdrPtr    s               *                                 

d JobsRtnd        s             10i 0 based(JobInfHdrPtr)           

d JobInfDtaPtr    s               *                                 

d JobInf          ds                  based(JobInfDtaPtr)           

d  JobNam                       10a                                  

d  JobUsr                       10a                                 

d  JobNbr                        6a                                 

d SizRcvVar       s             10i 0                

 /free                                               

  QUSBPrv = 0;                                       

  ErrCde.Hdr.QUSBPrv = %size(ErrCde);                 

  if %parms() >= 3;                                  

     SizRcvVar = SizJobInfo;                         

  else;                                              

     SizRcvVar = 0;                                   

  endif;                                             

  if JobName = '*';                                  

     if SizRcvVar >= %size(JobsRtnd);                

        JobInfHdrPtr = %addr(JobInfo);               

        SizRcvVar -= %size(JobsRtnd);                

        if SizRcvVar >= %size(JobInf);               

           JobInfDtaPtr = %addr(JobInfo) + %size(JobsRtnd);     

           JobInf = curJobName;                                 

           JobsRtnd = 1;                                        

        else;                                                   

           JobsRtnd = 0;                                         

        endif;                                                  

     endif;                                                     

     return 1;                                                   

  endif;                                                        

  GetJobList(JobName :'*ACTIVE');                               

  if SizRcvVar >= %size(JobsRtnd);                              

     JobInfHdrPtr = %addr(JobInfo);                             

     JobsRtnd = 0;                                              

     SizRcvVar -= %size(JobsRtnd);                              

     dow ((SizRcvVar >= %size(JobInf)) and                       

          (JobsRtnd < LJobHdr.QUSNbrLE));                        

         if JobsRtnd = 0;                                        

            JobDtaPtr = JobHdrPtr + LJobHdr.QUSOLD;              

            JobInfDtaPtr = %addr(JobInfo) + %size(JobsRtnd);     

         else;                                                   

            JobDtaPtr += LJobHdr.QUSSEE;                         

            JobInfDtaPtr += %size(JobInf);                        

         endif;                                                  

         JobNam = LJobDta.QUSJNU;                                

         JobUsr = LJobDta.QUSUNU;                                 

         JobNbr = LJobDta.QUSJNbrU;                              

         JobsRtnd += 1;                                          

         SizRcvVar -= %size(JobInf);                             

     enddo;                                                      

  endif;                                                         

  return LJobHdr.QUSNbrLE;                                       

 /end-free                                                      

p JobsActive      e                                             

 ***********************************************************    

p GetJobList      b                                             

d GetJobList      pi                                            

d  JobName                      10a   const                     

d  Status                       10a   const                      

 /free                                                          

  // Get addressability to Job List *USRSPC                     

  RtvUsrSpcPtr('JOBLIST   QTEMP' :JobHdrPtr :ErrCde);           

  if ErrCde.Hdr.QUSBAvl = 0;                                    

     // All is OK                                               

  else;                                                               

     // Assume UsrSpc not found, so create it                        

     CrtUsrSpc('JOBLIST   QTEMP' :'JobList' :4096                    

               :x'00' :'*ALL' :'Used by JobChks'                     

               :'*YES' :QUSEC :'*DEFAULT' :0 :'1');                  

     RtvUsrSpcPtr('JOBLIST   QTEMP' :JobHdrPtr :QUSEC);               

  endif;                                                             

  LstJobs('JOBLIST   QTEMP' :'JOBL0100'                              

          :(JobName + '*ALL      ' + '*ALL  ')                       

          :Status :QUSEC);                                           

 /end-free                                                           

p GetJobList      e                                                  

There are a few additions to the global definitions of the JOBCHKS module:

1. 1.Defining the pointer variable JobDtaPtr and the data structure LJobDta, which is based on JobDtaPtr. In the previous article, we utilized the List Job (QUSLJOB) API in procedure GetJobList but never actually examined the list of jobs returned. In this article, we will (in some code paths) be using this list, and the variables JobDtaPtr and LJobDta are used to point to a list entry and define the contents of a list entry, respectively. LJobDta is defined like the QSYSINC/QRPGLESRC, QUSLJOB IBM-provided data structure QUSL010002. QUSL010002 provides the definition of QUSLJOB's format JOBL0100, which is what is requested in the GetJobList procedure
2. 2.Inclusion of the program status data structure (PSDS) with the subfield curJobName to provide easy access to the qualified job name of the current job. The PSDS will be used when the '*' special value is passed by the caller for the JobName parameter of JobsActive.
3. 3.Copying of the IBM-provided QSYSINC/QRPGLESRC,QUSLJOB API definitions. This is done in support of point 1 above.

The next set of changes in JOBCHKS is the exported procedure JobsActive itself.

The local definitions for JobsActive are these:

1. 1.The pointer variable JobInfHdrPtr and the integer variable JobsRtnd, which is based on JobInfHdrPtr. When the caller of JobsActive passes a JobInfo parameter that is 4 bytes or larger in size, JobRtnd is used to return the number of qualified job names that are returned in the JobInfo parameter.
2. 2.The pointer variable JobInfDtaPtr and the data structure JobInf, which is based on JobInfDtaPtr. When the caller of JobsActive passes a JobInfo parameter that is 30 bytes or larger in size, JobInf is used to return the qualified job names in the JobInfo parameter.
3. 3.The integer variable SizRcvVar, which is used to track the size of available storage in the JobInfo parameter to return qualified job name information in.

Moving on to the actual processing of JobsActive, we start (as we did in the previous JobActive procedure) by setting the two instances of the API error code structure, QUSEC and ErrCde, to appropriate values for sending escapes and not sending escapes, respectively.

Following this, JobsActive checks to see if the SizJobInfo parameter was passed by the caller. If the parameter was passed, then SizRcvVar is set to the value of SizJobInfo; otherwise, SizRcvVar is set to zero.

A check is then made for a JobName special value of '*', indicating that a check for only the current job is needed. In the previous JobActive procedure, any of the supported special values resulted in JobActive returning a value of '1' to indicate that yes, at least one job is currently active on the system, and for performance reasons, we could bypass the actual calling of the QUSLJOB API. In the case of JobsActive, which returns the number of jobs active on the system for the given JobName, we can only bypass calling QUSLJOB in the case of the '*' special value. With an input value of '*', we know only one "current" job is active, while the special values '*CURRENT' and '*ALL' are quite likely (and guaranteed in the case of '*ALL') to have multiple currently active jobs on the system.

If JobName is '*', JobsActive determines if there is sufficient available storage in the JobInfo parameter to return the number of active jobs returned (that is, SizRcvVar is greater than or equal to the size of JobsRtnd). If there is not sufficient storage, then JobsActive simply ends with no additional processing, returning an active job count of 1.

If there is sufficient storage, JobsActive sets JobInfHdrPtr to the address (location) of the JobInfo parameter, decrements the amount of available storage in JobInfo by the size of the number of jobs returned, and determines if there is sufficient remaining storage in the JobInfo parameter to return the qualified job name of the current job (SizRcvVar is greater than or equal to the size of the JobInf data structure). If there is not sufficient storage, JobsActive sets the number of jobs returned (JobsRtnd) to 0 and ends, returning an active job count of 1. If there is sufficient storage, JobsActive sets JobInfDtaPtr to the address of where to return the qualified job name, sets JobInf to the current job name using the job name found in the PSDS, sets the number of jobs returned to 1, and returns an active job count of 1.

If JobName is not the special value '*', JobsActive calls the GetJobList procedure of the previous article to get a list of jobs (using the QUSLJOB API) that are currently active with the specified JobName. There are no changes this month in the processing of the GetJobList procedure, but, unlike JobActive, which simply examined the number of jobs returned by the QUSLJOB API, JobsActive may process the returned job entries.

After calling GetJobList, JobsActive determines, using the same method of how the special JobName value of '*' was handled, if there is sufficient available storage in the JobInfo parameter to return the number of active jobs returned. If there is not sufficient storage, then JobsActive ends, returning the number of active jobs returned by the QUSLJOB API (LJobHdr.QUSNbrLE). Please note that relative to this return value there is a "qualifier" at the end of the article related to the accuracy of this returned active job count.

If there is sufficient storage, JobsActive sets JobInfHdrPtr to the address (location) of the JobInfo parameter, sets the number of jobs returned to 0, decrements the amount of available storage in JobInfo by the size of the number of jobs returned, and enters into a DOW, which will return those active qualified job names that will fit in the remaining storage of the JobInfo parameter.

The DOW is run while two conditions remain true. The conditions are that there is sufficient available storage in JobInfo to return another qualified job name (SizRcvVar is greater than or equal to the size of the JobInf data structure) and that there are additional active jobs to be returned (that is, the number of jobs currently being returned in JobInfo, JobsRtnd, is less than the number of active jobs returned by the QUSLJOB API, LJobHdr.QUSNbrLE). While these two conditions are true, JobsActive sets the pointer JobDtaPtr to the address of the next QUSLJOB active job entry to be processed, sets the pointer JobInfDtaPtr to the address of where to return the next qualified job name within JobInfo, sets the qualified job name within JobInfo (JobNam, JobUsr, and JobNbr) from the QUSLJOB entry, increments the number of active jobs returned in JobInfo (JobsRtnd) by one, and decrements the amount of available storage within JobInfo (SizRcvVar) by the size of JobInf. The DOW condition for SizRcvVar being greater than or equal to the size of the JobInf data structure is what prevents JobsActive from returning partial qualified job names.

Within this DOW, there is processing conditioned by whether or not JobsActive is working with the first active job to be returned or with a subsequent active job that is to be returned. In the case of returning the first active job, the pointer variable JobDtaPtr, used to access the QUSLJOB active job entry, is set by taking the address of the start of the user space containing the QUSLJOB API list (JobHdrPtr) and adding the offset to the first API returned job entry (LJobHdr.QUSOLD) while the pointer variable JobInfDtaPtr, used to return the next qualified job name within JobInfo, is set by taking the address of the start of the JobInfo parameter and adding the size of JobsRtnd (which precedes the returned list within the JobInfo parameter). When returning an active job that is not the first job returned in JobInfo, the pointer variable JobDtaPtr is incremented by the size of each QUSLJOB API returned entry (LJobHdr.QUSSEE) while the pointer variable JobInfDtaPtr is incremented by the size of each qualified job name return in the JobInfo parameter (%size(JobInf)).

When the DOW is exited, JobsActive ends, returning the number of active jobs returned by the QUSLJOB API.

Assuming that the above source is stored in member JOBCHKS of source file QRPGLESRC, you can create the JOBCHKS *MODULE and *SRVPGM using these two commands:

CRTRPGMOD MODULE(JOBCHKS)

CRTSRVPGM SRVPGM(JOBCHKS)

We're now ready to start using the JobsActive function within our application code. The updated source for our test program UseJobChks is shown below.

h dftactgrp(*no) bnddir('SOMETOOLS')                        

d UseJobChks      pr                                        

d  JobName                      10a   const                 

d UseJobChks      pi                                        

d  JobName                      10a   const                 

 /copy qrpglesrc,JobChksPR                                  

d JobInfo         ds                                        

d  JobsRtnd                     10i 0                       

d  Job                          26a   dim(100)              

d   JobNam                      10a   overlay(Job :1)       

d   JobUsr                      10a   overlay(Job :11)      

d   JobNbr                       6a   overlay(Job :21)      

d X               s             10i 0                       

 /free                                                       

  if JobActive(JobName);                                    

     dsply 'It is active';                                  

  else;                                                      

     dsply 'Not active right now';                          

  endif;                                                    

  dsply (%char(JobsActive(JobName)) + ' active jobs');      

  JobsActive(JobName :JobInfo :%size(JobInfo));             

  for X = 1 to JobsRtnd;                                    

      dsply (%trimr(JobNam(X)) + '/' +                      

             %trimr(JobUsr(X)) + '/' +                      

             JobNbr(X));                                    

  endfor;                                                   

  *inlr = *on;                                              

  return;                                                   

 /end-free    

These are the updates:

1. 1.The definition of a JobInfo data structure. This data structure defines the subfield JobsRtnd to know how many active qualified job names are returned in JobInfo and the array Job. Job is defined as an array of 100 elements, each element representing a qualified job name.
2. 2.The definition of a signed integer variable X. This variable will be used to index the Job array of JobInfo.
3. 3.A dsply of the number of active jobs. This demonstrates calling JobsActive with only one parameter, the job name.
4. 4.A dsply of the active qualified job names. This demonstrates calling JobsActive with all three parameters and then processing the returned list of active jobs.

To compile our sample program you can use this command:

CRTBNDRPG PGM(USEJOBCHKS)

To test the UseJobChks program with a job name of 'Q*', you can use this:

CALL PGM(USEJOBCHKS) PARM(Q*)  

Assuming there are jobs on the system starting with the letter 'Q', this should result in messages similar to the following:

CALL PGM(USEJOBCHKS) PARM(Q*)     

DSPLY  It is active               

DSPLY  2314 active jobs           

DSPLY  QSYSARB/QSYS/541096        

DSPLY  QSYSARB2/QSYS/541097       

DSPLY  QSYSARB3/QSYS/541098       

DSPLY  QSYSARB4/QSYS/541099       

DSPLY  QSYSARB5/QSYS/541100   

DSPLY  QLUS/QSYS/541101       

DSPLY  QDBSRV01/QSYS/541104   

DSPLY  QDBSRV02/QSYS/541105   

DSPLY  QDBSRV03/QSYS/541106    

In this article, we've seen how to access the first entry of a list of entries returned by a list API such as QUSLJOB and then how to access subsequent entries within the list. With the number of list APIs on the system, this knowledge can be quite useful.

We've also seen how to provide our own API wrapper, JobsActive, around a system API such as QUSLJOB. One benefit of this wrapper approach is that we can provide customized system-level information (such as the Job array of UseJobChks) to application developers without the application developers needing to know how to call system APIs directly.

A second benefit of the wrapper is that we might better understand a fairly common warning found in the documentation of many system APIs. This warning is related to APIs that return data in output parameters (like the JobLst parameter of JobsActive) and have a "Length of" parameter where you provide the size of the output parameter (like the SizJobLst parameter of JobsActive). The warning itself is "If the length is larger than the size of the receiver variable, the results may not be predictable," and this warning certainly applies to JobsActive.

You may or may not have noticed that while the sample program UseJobChks defines the array Job to process the returned active jobs, JobsActive has no such array. JobsActive uses based storage to return active job information to its caller and has no clue as to how its caller, UseJobChks in our case, has defined this storage. The caller may have defined the storage related to JobLst qualified job names using:

1. 1.an array approach such as UseJobChks (with whatever array dimensions you might want—10, 100, 500, etc.)
2. 2.one big character variable that will be accessed using operators such as %subst
3. 3.a data structure with specific subfields such as JobName1, JobUser1, JobNbr1, JobName2, JobUser2, JobNbr2, etc.
4. 4.a variety of other approaches

All of these approaches will work just fine as the only thing JobsActive (and system APIs) care about is the size of the receiver variable where information is to be returned, not how you have elected to define your use of this storage. In UseJobChks, we use %size(JobInfo) to have the RPG compiler determine the correct SizJobLst value to pass to JobsActive.

A "rookie" mistake would be to hardcode the SizJobLst value. Let's say our rookie determined the size of JobLst as 2604 by multiplying the number of Job dimensions (100) by the size of one Job entry (26) plus 4 for JobsRtnd. If the developer then codes JobsActive('Q*' :JobInfo :2604); no harm is done. But if they make a typo and code the third parameter as 3604 rather than 2604, then problems could occur. If there are only 50 active jobs, then they'll get back the qualified job names of the 50 jobs. If there are 200 active jobs, then they'll get back the qualified job names of 138 jobs (what will fit in 3604 bytes). As Job is only allocated for 100 jobs, where do the other 38 qualified job names go? This is where "the results may not be predictable" warning comes into play.

We can safely say the 988 bytes associated with the 38 qualified job names will go immediately after the first 100 qualified job names that are returned. The question is, what was previously in those 988 bytes and has now been overwritten? It might have been a variable in UseJobChks that was used before calling JobsActive and isn't used after the call, it might have been a variable in UseJobChks that now has a "strange" value that will be used after the call, it might have been an RPG run-time control area so rather strange RPG errors might start showing up in the program (like files "closed" when you know they're "open"), it might have been a variable in another program (that will "blow up" much later for no apparent reason), it might have been an RPG run-time control area in another program, it might have been storage beyond the end of the current activation group, or it might have been any combination of the above (and the combination can change based on your programs being recompiled and/or different programs being called in the current job). This is not a good situation to be in, and this is why we want to make sure the specified length of the receiver variable parameter is not larger than the allocated size of the receiver variable when calling an API. Using a built-in such as %size for length parameters is definitely the way to go. A variation of this, and one that I have seen more than once, is when the user of the API correctly hardcoded the length of the receiver variable (let's say 2604 for 100 returned entries as in our UseJobChks example), but a year later the UseJobChks source was copied for another project, and it was determined that this new project only needed 10 returned entries, so the dim(100) was changed to dim(10) without changing the 2604 value. Care to guess what will happen at some point in the future? There are other reasons for using %size beyond this concern for unpredictable results, but this is the major one.

Before closing, two other points need to be discussed.

The first point is relative to the accuracy of the number of active jobs value returned by JobsActive. What is being returned is the number of list entries returned by the QUSLJOB API, and this value may or may not represent all active jobs with the specified JobName. The QUSLJOB API returns the active job list in a user space and the maximum size of a user space is roughly 16MB. This size is more than sufficient to return in excess of 250,000 job entries, but what if there are 450,000 active jobs? Note that I have no idea if anyone is running this number of active jobs in 2014, but the documented maximum of all jobs on the system (active, on a *JOBQ, or ended with spooled output) is 485,000 jobs, and this number of jobs will not fit in one user space. With the current coding of JobsActive, I've taken the simplistic approach of just returning a big number representing the number of active jobs that are returned by the first call to QUSLJOB and not caring if the actual number of active jobs might be higher.

If I did care, then the following changes could be made:

1. 1.After processing all entries returned by the QUSLJOB API, check the value of the Information Status field in the List API Generic Header (LJobHdr.QUSIS).
2. 2.If the information status value is 'C' (complete), then all job entries have been returned and LJobHdr.QUSNbrLE is accurate, so JobsActive can end, returning LJobHdr.QUSNbrLE.
3. 3.If the information status value is 'P' (partial), then there are more job entries that could be returned. In this case, JobsActive could:
   1. a.Store the value of LJobHdr.QUSNbrLE.
   2. b.Call the QUSLJOB API again asking for the next set of entries following the initial set of entries (that is, another 250,000+ active jobs). To get this next set of entries, this subsequent call to QUSLJOB would utilize the Continuation handle parameter, setting the parameter to the continuation handle value provided in the API specific Header Section.
   3. c.Process the returned entries (if there's still available storage in JobInfo).
   4. d.Add the LJobHdr.QUSNbrLE value of this API call to the previously stored value of previous API calls.
   5. e.Go back to step 1 and replace the step 2 returning of LJobHdr.QUSNbrLE with the returning of the stored value of all accumulated LJobHdr.QUSNbrLE values.

Using this continuation handle approach, we can process list API output (like that of QUSLJOB) even though the number of entries exceeds the capacity of a single user space. This use of continuation handles may not apply to many of you in the case of listing jobs in an active status, as done with our calls to GetJobList where the second parameter is '*ACTIVE', but QUSLJOB does support other status values, such as '*ALL', and I've certainly been on systems where the number of all jobs on the system would exceed the number of entries that can be returned in one user space—requiring the use of the continuation handle parameter.

The second point I would like to make is that I somewhat short-changed the reader in terms of how JobsActive implements support for the JobName special value '*'. I used the RPG PSDS to obtain the qualified job name of the current job, but, as this is The API Corner, I might have demonstrated the use of an API to access the current job's qualified job name. If you know that you're interested in a specific job (like the current job), rather than a list of jobs, then there are several system APIs available to directly return this job information through a receiver variable. As an exercise, can you find at least one API to directly return the qualified job name of the current job? I found four rather quickly, though I anticipate most readers finding one particular API first. If you are not able to find an API to retrieve the current job's qualified name, you might want to refer to the 7.1 Information Center and search on the words "Retrieve Job Information." I want to avoid providing the API name in this article, but you should find a link to this API in the result list of your search.

As usual, if you have any 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.

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale

Also Read

The API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?