Move Job (QSPMOVJB) API

The Move Job (QSPMOVJB) API performs one of two functions. They are to:

• Move one job at a time to the top of a job queue
• Move a job after another job

The jobs are identified by the internal job identifier or by the qualified job name. See How to Specify Job Identifying Fields for the valid combinations of identifying jobs.

As a result of using this API, a job could:

• Change job queues

  The job changes job queues when it is moved to the top of another job queue.

  The job being moved resides on the job queue of the target job.

• Change priority

  The job priority is changed to the requester's highest schedule priority if the job is moved to the top of a job queue.

   Requester's priority = 2
  
                                Job          Priority
   New priority = 2 when moved here-------------->
                                  A             3
                                  B             5
  

  The job priority will be changed to the priority of the target job if the requester's highest schedule priority is equal to or less than the target job.

   Requester's priority = 2
  
                               Job          Priority
  
                                 C             3
   New priority = 3 when moved here------------->
                                 D             5
  
  

  The job priority is changed to the requester's highest schedule priority if:

  • The requester's priority is greater than the target job and
  • The requester's priority is greater or equal to the jobs it is moving ahead of.

   Requester's priority = 4
  
                               Job          Priority
  
                                 C             3
   New priority = 4 when moved here------------->
                                 D             5
  
  

   Requester's priority = 4
  
                               Job          Priority
  
                                 E             3
   New priority = 4 when moved here------------->
                                 F             4
  
   The owner of the job moving must also be
   the owner of job F.
  

• Be held

  A job in ready status is held when it is moved after a job that is held.

• Be released

  A job in held status is released when it is moved to the top of a job queue.

  A job in held status is released when it is moved after a job that is released.

Restrictions for Movement of Jobs

The Move Job API has restrictions that determine whether a job can be moved.

• Scheduled jobs cannot be referenced as the source job or the target job.
• The job to be moved must exist, be a batch job, and be on a job queue.
• The job queue must exist.
• If a job is held with hold spooled files specified, and the job is to be moved to the top of a queue, no spooled file must exist for the job.

Authorities and Locks

Job Authorities:  The requester is authorized to the job if one or more of the following conditions are met.

• The requester is the owner of the job to be moved.
• The requester has *JOBCTL authority.

Job Queue Authority

Authority to the target job queue

*READ

Authority to the target job queue library

*EXECUTE

Job queue lock on which the source job resides

*EXCLRD

Job queue lock on which the target job resides

*EXCLRD

User Profile Highest Schedule Priority

• The requester must have a priority limit of at least x-1 (x being the priority of the job that will follow after this job).
• If the requester has equal priority to a job that it is moving ahead of, the requester must own all of the jobs it is moving ahead of at that priority level or have *JOBCTL authority.

Required Parameter Group

Function information

INPUT; CHAR(*)

The information that is associated with the job or jobs to be moved and the job queue to which the jobs are to be moved. See the Format of the Function Information for the format of this parameter.

Length of function information

INPUT; BINARY(4)

The length of the function information in the function information parameter. The length depends on the function format. Each format has a different (but fixed) length as shown in the specific format tables. The minimum length for format MJOB0100 is 62 bytes; the minimum length for format MJOB0200 is 84 bytes.

Function information format

INPUT; CHAR(8)

The format of the function information that is being provided. The information is provided in the function information parameter. They are:

MJOB0100	Format for the function of *NEXT, which is moving one job at a time to the top of a job queue.
MJOB0200	Format for the function of *AFTER, which is moving a job after another job.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of the Function Information

MJOB0100 Format:  The following table shows the information for the MJOB0100 format. For more details about the fields in the following tables see, Field Descriptions.

MJOB0200 Format:   The following table shows the information for the MJOB0200 format. For more details about the fields in the following tables see, Field Descriptions.

Field Descriptions

Source internal job identifier. The internal identifier for the job to be moved. The identifier is not valid following an initial program load (IPL). If you attempt to use it after an IPL, an exception occurs. This field must be blank when a source job name is given. Use one of the following APIs to make the identifier available:

List Job (QUSLJOB) API

Retrieve Job Information (QUSRJOBI) API

There may be a performance advantage when identifying the source job by its internal identifier.

Source job name. The name of the job to be moved. The possible values are:

Source job number. The number of the job to be moved. It can optionally be blank when a source job name or a source job user name or both are specified. This field must be blank when the source job name is specified as *INT.

Source job user name. The user name of the job to be moved. It can optionally be blank when a source job name is specified. This field must be blank when the source job name is specified as *INT.

Target internal job identifier. The internal identifier for the job after which the source job is to be moved. The identifier is not valid following an initial program load (IPL). If you attempt to use it after an IPL, an exception occurs. This field must be blank when a target job name is given. Use one of the following APIs to make the identifier available:

List Job (QUSLJOB) API

Retrieve Job Information (QUSRJOBI) API

There may be a performance advantage when identifying the target job by its internal identifier.

Target job name. The name of the job after which the source job is to be moved. The possible values are:

Target job number. The number of the target job. It can optionally be blank when a target job name or target job user name or both are specified. This field must be blank when the target job name is specified as *INT.

Target job queue library name. The name of the library that contains the job queue. This must be specified when a target job queue name is given. The possible values are:

Target job queue name. The name of the job queue to which the job is to move. The possible values are:

Target job user name. The user name of the target job. It can optionally be blank when a target job name is specified. This field must be blank when the target job name is specified as *INT.

How to Specify Job Identifying Fields

This table illustrates the valid combinations of values for format MJOB0100.

This table illustrates the valid combinations of values for format MJOB0200.

The qualified job name can use the same combinations of the qualified job name specified in format MJOB0100.

Error Messages