Get Job List

Summary

The following are the RPG/LE fully free-form definitions and instructions needed for using the Get Job List service procedure. This service procedure simply allows the caller to get a list of active jobs on the system.

By Dave Clark

Service Prototype

Place the following in a separate copybook for inclusion in both the caller and the service program source members.

**free

//******************************************************************************
// Uses IBM APIs to create a user space and get a list of active jobs on the
// system.  The (generic) job name, maximum number of jobs expected, and the
// name of the list are required input paramaters.  The job count found and a
// pointer to the user space are returned.  When the current job list is no
// longer needed, a job name of *RESET must be used to release the user space.
//******************************************************************************
dcl-pr GenUtl_GetJobList     int(10);
  JobName                    char(10) const;
  MaxJobs                    int(10)  const;
  ListName                   char(10);
  ListPtr                    pointer;
end-pr;

// data structures to map the job list user space
dcl-ds GenUtl_JobL_Gen_DS    likeds(QUSH0100)    // generic header
                             based(GenUtl_JobL_Gen_Ptr);
dcl-ds GenUtl_JobL_Inp_DS    likeds(QUSLI)       // input parms
                             based(GenUtl_JobL_Inp_Ptr);
dcl-ds GenUtl_JobL_Hdr_DS    likeds(QUSLH)       // API header
                             based(GenUtl_JobL_Hdr_Ptr);
dcl-ds GenUtl_JobL_Lst_DS    qualified           // list section
                             based(GenUtl_JobL_Lst_Ptr);
  JobL_Entry                 likeds(QUSL010002) dim(999);
   JobL_QJobNam              char(26)  overlay(JobL_Entry: 1);
   JobL_JobName              char(10)  overlay(JobL_Entry: 1);
   JobL_UserName             char(10)  overlay(JobL_Entry: 11);
   JobL_JobNumb              char(6)   overlay(JobL_Entry: 21);
end-ds;

Service Procedure

Place the following in a service program source member.

**free
ctl-opt NoMain AlwNull(*UsrCtl) Debug Option(*SrcStmt:*NoDebugIo)
        DatFmt(*ISO) TimFmt(*ISO);

//******************************************************************************
// Uses IBM APIs to create a user space and get a list of active jobs on the
// system.  The (generic) job name, maximum number of jobs expected, and the
// name of the list are required input paramaters.  The job count found and a
// pointer to the user space are returned.  When the current job list is no
// longer needed, a job name of *RESET must be used to release the user space.
//******************************************************************************
dcl-proc GenUtl_GetJobList   export;
  dcl-pi *n                  int(10);
    JobName                  char(10) const;
    MaxJobs                  int(10)  const;
    ListName                 char(10);
    ListPtr                  pointer;
  end-pi;

  dcl-s UserSpaceName        char(20);
  dcl-s UserSpaceSize        int(10);
  dcl-s iObjType             char(10)  inz('*USRSPC');
  dcl-s iLibrary             char(10)  inz('QTEMP');

  if ListName <= *blanks;              // if not supplied
    ListName = 'JOBLIST';              // use default
  else;                                // else make sure is uppercase
    ListName = %xlate(GenUtl_lower:GenUtl_UPPER:ListName);
  endif;
  UserSpaceName = ListName + 'QTEMP';  // place user space in QTEMP

  if JobName = '*RESET'                // request to delete user space?
  or GenUtl_ObjectExists(ListName: iObjType: iLibrary);
    callp IBMAPI_DltUsrSpace( UserSpaceName: ApiErrC);
    ListPtr = *null;                   // clear pointer
    if JobName = '*RESET';             // if specifically requested
      return *zero;                    // exit immediately
    endif;
  endif;
                                       // create user space
  UserSpaceSize = %size(QUSH0100) + %size(QUSLI) + %size(QUSLH)
                + (%size(QUSL010002) * (MaxJobs + 1));
  callp IBMAPI_CreateUserSpace( UserSpaceName: 'JOBLIST'
                              : UserSpaceSize: x'00': '*EXCLUDE'
                              : 'List of Active Jobs on the System'
                              : '*YES': ApiErrC);
  if ApiErrC.BytAvail > *zero;
    GenUtl_Escape(*omit : 'Message ' + ApiErrC.MsgId + ' occurred in '
                        + %trim(PROC_NAME)
                        + ' while creating a user space in QTEMP.');
  endif;
                                       // fill it with list of active jobs
  callp IBMAPI_ListUserJobs( UserSpaceName: 'JOBL0100'
                           : JobName + '*ALL      *ALL'
                           : '*ACTIVE': ApiErrC);
  if ApiErrC.BytAvail > *zero;
    GenUtl_Escape(*omit : 'Message ' + ApiErrC.MsgId + ' occurred in '
                        + %trim(PROC_NAME)
                        + ' while retrieving a list of '
                        + %trim(JobName) + ' jobs.');
  endif;
                                       // get pointer to user space
  callp IBMAPI_RtvPtrUsrSpace( UserSpaceName: ListPtr: ApiErrC);
  if ApiErrC.BytAvail > *zero;
    GenUtl_Escape(*omit : 'Message ' + ApiErrC.MsgId + ' occurred in '
                        + %trim(PROC_NAME)
                        + ' while retrieving a user space pointer.');
  endif;

  GenUtl_JobL_Gen_Ptr = ListPtr + 0;   // map list header areas
  GenUtl_JobL_Inp_Ptr = ListPtr + GenUtl_JobL_Gen_DS.QUSOIP;
  GenUtl_JobL_Hdr_Ptr = ListPtr + GenUtl_JobL_Gen_DS.QUSOHS;
  GenUtl_JobL_Lst_Ptr = ListPtr + GenUtl_JobL_Gen_DS.QUSOLD;

  return GenUtl_JobL_Gen_DS.QUSNBRLE;  // return number of list entries
end-proc;

Example

See the Job Is Active service procedure.

References

• API Error Code Structure (ApiErrC)
• Object Exists service procedure
• IBMAPI_CreateUserSpace API
• IBMAPI_DltUsrSpace API
• IBMAPI_ListUserJobs API
• IBMAPI_RtvPtrUsrSpace API