APIs by Example: Retrieve Job Description Information API

By:

Job descriptions play a very important role in work management on the i5. Whenever an interactive, batch, autostart, or prestart job begins its life, a number of significant job attributes are retrieved from the job description assigned to that job. As a consequence, job descriptions need to be carefully created, managed, and assigned, or unexpected and serious problems might be the outcome.

As programmers, we can help avoid these problems by writing utilities that make the system administrator's job easier. To write utilities that work with job descriptions, understanding the Retrieve Job Description Information (QWDRJOBD) API is helpful.

For example, if a library contained in the initial library list of a job description is deleted, and that job description is assigned to a user profile, the user profile in question can no longer sign on to the system but instead receives the error message "CPF1113 Library in initial library list not found." To help avoid such situations, and provide a working example of the QWDRJOBD API, I've written the Work with Referenced Job Descriptions (WRKREFJOBD) command.

The WRKREFJOBD lets you find and list all job descriptions referenced by specific objects on your system, before deleting or renaming these objects. From the resulting list panel, you then have various options to perform against the selected job descriptions, such as change, display, or delete the job description.

The WRKREFJOBD utility also provides yet another opportunity to demonstrate how powerful it is to combine list and retrieve APIs. In this example, I use the Open List of Objects (QGYOLOBJ) API to create a list of job descriptions and subsequently, for each returned qualified job description name, I use the QWDRJOBD API to retrieve the attributes of the job description. Using this information, I then evaluate the specified selection criteria and decide whether the job description should be included in the Work with list panel.

Let me introduce the WRKREFJOBD command prompt:


             Work with Ref Job Descriptions (WRKREFJOBD)            
 Type choices, press Enter.                                               
 Job description  . . . . . .   *ALL        Name, generic*, *ALL    
   Library  . . . . . . . . .     *LIBL     Name, *LIBL, *CURLIB... 
 List order . . . . . . . . .   *JOBD       *JOBD, *LIB
 Criteria relationship  . . .   *OR         *OR, *AND
 User profile . . . . . . . .   *NOCHK      Name, *NOCHK, *ANY 
 Printer device . . . . . . .   *NOCHK      Name, *NOCHK
 Library  . . . . . . . . . .   *NOCHK      Name, *NOCHK
 Job queue  . . . . . . . . .   *NOCHK      Name, *NOCHK
   Library  . . . . . . . . .     *NOCHK    Name, *NOCHK 
 Output queue . . . . . . . .   *NOCHK      Name, *NOCHK
   Library  . . . . . . . . .     *NOCHK    Name, *NOCHK 
 Request data string  . . . .   *NOCHK                 
 Output . . . . . . . . . . .   *           *, *PRINT

You can specify all combinations of job description and library special values to narrow your search to specific or generic job descriptions in various libraries. To list all job descriptions in library QSYS that have a user profile specified, run the following command:

WRKREFJOBD JOBD(QSYS/*ALL) USRPRF(*ANY)

You also have an option to define the relationship between multiple selection criteria. If you specify an OR relationship, all job descriptions meeting just one of the criteria are included in the list. Specifying an AND relationship includes only the job descriptions meeting all the specified criteria.

The preceding command leads to the display of the following list panel (optionally, you can have the list printed instead):


           Work with Referenced Job Descriptions          WYNDHAMW
                                               26-08-06  17:17:02
 Job description  . . . . . :   *ALL
   Library  . . . . . . . . :     QSYS
 Type options, press Enter.
   2=Change   3=Copy   4=Delete   5=Display   6=Print   7=Rename
      Job                                  Print        Initial       
 Opt  Description  Library     User        Device       Libl.
      QCSTJOBD     QSYS        QSYS        *USRPRF      *YES 
      QCSTSRCD     QSYS        QSYS        *USRPRF      *YES
      QDIRSRV      QSYS        QDIRSRV     *USRPRF      *YES
      QESAUTON     QSYS        QSRV        *USRPRF      *YES
      QFSIOPWK     QSYS        QPGMR       *USRPRF      *YES
      QGLDPUBA     QSYS        QDIRSRV     *USRPRF      *YES
      QGLDPUBE     QSYS        QDIRSRV     *USRPRF      *YES
      QLPINSTALL   QSYS        QLPINSTALL  *USRPRF      *YES
 More...
 Parameters or command                                      
 ==>                   
 F3=Exit   F4=Prompt  F5=Refresh  F6=Create job desc.  F9=Retrieve
 F11=Display queues   F12=Cancel  F17=Top   F18=Bottom

The list panel offers three alternate views, all in all displaying each job description's user, print device, initial library list flag, partial request data, job and output queue as well as text description. Cursor-sensitive help text is provided for the list panel and the command to explain all details.

In case you are wondering how job descriptions are assigned to the different job types that I've mentioned, here's a brief overview:

Interactive jobs pick up the job description from the work station entry that they are signing on through. By the default special value *USRPRF, the work station entry points to the signing-on user profile's job description, as you can see on the partial command prompt of the Add Workstation Entry (ADDWSE) command:


                   Add Work Station Entry (ADDWSE)
 Type choices, press Enter.
 Subsystem description  . .               Name
   Library  . . . . . . . .     *LIBL     Name, *LIBL, *CURLIB
 Work station name  . . . .               Name, generic*
 Work station type  . . . .               *ALL, 3179, 3180, 3196...   
 Job description  . . . . .   *USRPRF     Name, *USRPRF, *SBSD
   Library  . . . . . . . .               Name, *LIBL, *CURLIB

To inspect how your system is set up, run the Display Subsystem Description (DSPSBSD) command against your interactive subsystem and select option 4 (Work station name entries) and 5 (Work station type entries). From each resulting panel, you can specify option 5 for the entry that you want to display.

Batch jobs rely on the Submit Job (SBMJOB) command's job description (JOBD) parameter to locate the job description under which the job should run. By default, this parameter also points to the special value *USRPRF. In this context, *USRPRF refers to the user profile specified on the SBMJOB command's user (USER) parameter, which by the default value *CURRENT points to the user profile running the SBMJOB command. So if the default values are used for these two parameters, the submitting user profile is the origin of the job description for the submitted batch job.

For prestart jobs and autostart jobs, the job description is named directly on the Add Prestart Job Entry (ADDPJE) and Add Autostart Job Entry (ADDAJE) commands, respectively. In both cases, special values can also be used to define the job description parameter. Diving deeper into i5/OS work management is beyond this article's scope, but I have collected a number of links providing useful information for learning more about this topic:

Work management concepts general documentation:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/rzaks/rzaks1.htm [2]

Information about job descriptions and a link to a comprehensive discussion of this object type and its role in i5/OS work management:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/rzaks/rzaksjobdescription.htm [3]

An overview documenting the structure and work management of your system:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/rzaks/rzakssystemstructure.htm [4]

IBM's Work Management Job Attributes Experience Report includes a job attribute reference table as well as information about APIs and CL commands recommended to access and manage these:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/experience/jobatt53.pdf [5]

This APIs by Example includes the following sources:

CBX161   -- Work with Referenced Job Descriptions - CCP       
CBX161E  -- Work with Referenced Job Descriptions - UIM Exit  
CBX161H  -- Work with Referenced Job Descriptions - Help            
CBX161P  -- Work with Referenced Job Descriptions - Panel Group 
CBX161X  -- Work with Referenced Job Descriptions   

CBX161M  -- Work with Referenced Job Descriptions - Build Command

To create all these objects, compile and run CBX161M. Compilation instructions are in the source headers, as usual.

This article demonstrates the following APIs:

Retrieve Job Description Information (QWDRJOBD) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qwdrjobd.htm [6]

Open List of Objects (QGYOLOBJ) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qgyolobj.htm [7]

Get List Entries (QGYGTLE) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qgygtle.htm [8]

Close List (QGYCLST) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qgyclst.htm [9]

Open Display Application (QUIOPNDA) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/quiopnda.htm [10]

Open Print Application (QUIOPNPA) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/quiopnpa.htm [11]

Close Application (QUICLOA) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/quicloa.htm [12]

Display Panel (QUIDSPP) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/quidspp.htm [13]

Print Panel (QUIPRTP) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/quiprtp.htm [14]

Put Dialog Variable (QUIPUTV) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/quiputv.htm [15]