Move Job (QSPMOVJB) API

Required Parameter Group:

Function information

Input

Char(*)

Length of function information

Input

Binary(4)

Function information format

Input

Char(8)

Error code

I/O

Char(*)

Default Public Authority: *USE

Threadsafe: No

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 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 table, see Field Descriptions.

Offset

Type

Field

Dec

Hex

CHAR(10)

Source job name

CHAR(10)

Source job user name

CHAR(6)

Source job number

CHAR(16)

Source internal job identifier

CHAR(10)

Target job queue name

CHAR(10)

Target job queue library name

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

Offset

Type

Field

Dec

Hex

CHAR(10)

Source job name

CHAR(10)

Source job user name

CHAR(6)

Source job number

CHAR(16)

Source internal job identifier

CHAR(10)

Target job name

CHAR(10)

Target job user name

CHAR(6)

Target job number

CHAR(16)

Target internal job identifier

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:

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:

*INT

The job to be moved is identified by the internal job identifier.

Name

The name of the job to be moved.

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:

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:

*INT

The target job is identified by the internal job identifier.

Name

The name of the job after which the source job is to be moved.

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:

*LIBL

The library list is used to locate the job queue.

*CURLIB

The current library is used to locate the job queue. If no library is specified as the current library for the job, QGPL is used.

Name

The library name.

Blanks

No library name is given when the job queue name is *SAME.

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

*SAME

The job will move to the top of the job queue on which it currently resides.

Name

The name of the job queue to which the job is to move to the top of.

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.

Qualified Job Name

Internal Job Identifier

Job Queue

Job Name

User Name

Job Number

Name

Number

Blanks

Name

Blanks

Name

Blanks

Number

Blanks

Name

Blanks

Name

*INT

Blanks

Internal job identifier

Name

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.

Source
Qualified Job Name

Source
Internal Job Identifier

Target
Qualified Job Name

Target
Internal Job Identifier

Qualified job name

Blanks

Qualified job name

Blanks

Qualified job name

Blanks

*INT

Internal Job identifier

*INT

Internal Job identifier

Qualified job name

Blanks

*INT

Internal Job identifier

*INT

Internal job identifier

Error Messages

Message ID

Error Message Text

CPF24B4 E

Severe error while addressing parameter list.

CPF33C1 E

Job &3/&2/&1 not on job queue. Job not moved.

CPF3CF1 E

Error code parameter not valid.

CPF3C1D E

Length specified in parameter &1 not valid.

CPF3C21 E

Format name &1 is not valid.

CPF3C42 E

User name or job number is not blank.

CPF3C43 E

Internal job identifier is not valid.

CPF3C52 E

Internal job identifier no longer valid.

CPF3C53 E

Job &3/&2/&1 not found.

CPF3C58 E

Job name specified is not valid.

CPF3C90 E

Literal value cannot be changed.

CPF33BA E

Job queue &1 in library &2 is not valid.

CPF33B3 E

Not authorized to job queue &1.

CPF33B4 E

Not authorized to job &3/&2/&1. Job not moved.

CPF33B5 E

Job &3/&2/&1 is not available for moving.

CPF33B6 E

Job &3/&2/&1 held by HLDJOB command. Job not moved.

CPF33B7 E

Job &3/&2/&1 specified more than once. Job not moved.

CPF33B8 E

Priority required to move job &3/&2/&1 exceeds limit of user &9.

CPF33B9 E

Priority required to move job &3/&2/&1 exceeds limit of user &9.

CPF3330 E

Necessary resource not available.

CPF3343 E

Duplicate job names found.

CPF8121 E

&8 damage on job queue &4 in library &9.

CPF8122 E

&8 damage on library &4.

CPF9801 E

Object &2 in library &3 not found.

CPF9810 E

Library &1 not found.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V3R1

[ Back to top | Work Management APIs | APIs by category ]