Move Spooled File (QSPMOVSP) API

The Move Spooled File (QSPMOVSP) API can:

• Move a spooled file to the top of an output queue
• Move a spooled file after another spooled file

The spooled files can be identified by:

• The internal job and spooled file identifiers
• The specific job name, spooled file name, and spooled file number

See Spooled File Identifying Fields for these combinations for spooled file identifiers.

Using this API, a spooled file can:

• Change output queues

  The output queue of the spooled file is changed when it is moved to the top of another output queue.

  The source spooled file moves to the output queue of the target spooled file.

• Change priority

  The priority of the spooled file is changed to the requester's highest scheduled priority if the spooled file is moved to the top of an output queue. For example:

  Requester's priority limit = 2
  
                              file         priority
  
  New priority = 2 when moved here ------->
                                A             3
                                B             3
  

  The priority of the spooled file is changed to the priority of the target spooled file if the requester's highest schedule priority is equal to or less than that of the spooled file it is moving after. For example:

   Requester's priority limit = 2
  
                              file         priority
  
                                A             3
    new priority = 3 when moved here ------->
                                B             5
                                C             5
  

  The priority of the spooled file is changed to the requester's highest schedule priority if:

  • The requester's priority is greater (lower) than the target spooled file and
  • The requester's limit is less (higher) than or equal to the spooled files it is moving ahead of. For example:

  Requester's priority limit = 4
  
                              file         priority
  
                                C             3
  new priority = 4 when moved here ------->
                                B             5
                                D             5
  

  
  

  Requester's priority limit = 4
  
                              file         priority
  
                                E             3
  new priority = 4 when moved here ------->
                                F             4
    In this case, the requester must own spooled
    file F or have special authorities.
  

• Be held

  A spooled file in ready, open, closed, or deferred status is held when it is moved after a spooled file that is held or saved.

• Be released and made ready

  A spooled file in held, open, closed, or saved status is made ready when it is moved to the top of an output queue.

  A spooled file in held, open, closed, or saved status is made ready when it is moved after a spooled file that is in ready status.

Restrictions for Movement of Spooled Files

Situations exist in which the QSPMOVSP API does not allow a spooled file to be moved.

These situations are:

• A spooled file with deferred (DFR) status can move after a spooled file with ready (RDY) status on the same output queue. This can occur when the target spooled file is the last spooled file in RDY status on that output queue.
• The spooled file being moved cannot be held as a result of a Hold Job (HLDJOB SPLFILE(*YES)) command.
• A spooled file selected by a writer cannot be moved.
• A spooled file cannot be moved after a spooled file that is in open status.
• A spooled file cannot be moved after a spooled file that is in closed status, unless both spooled files are part of the same job.
• The destination output queue must have the order of spooled files on the queue defined as *FIFO.

  Spooled files cannot be moved to the top of an output queue with the order of spooled files on the output queue defined as *JOBNBR. When a spooled file is requested to be moved after a spooled file and the target spooled file resides on a job number sequenced output queue, the move will occur. However, the spooled file is positioned by the job number sequence. In this situation, CPI33E2 is written to the job log to indicate the action taken.

• A spooled file cannot be moved after a spooled file that has been selected by a writer (PND, WTR, PRT, SND, or MSGW status) unless the target spooled file is the last spooled file selected by the writer.
• A spooled file cannot be moved after a spooled file in deferred status unless both spooled files have the same status.
• A spooled file cannot be moved from an output queue in an independent disk pool to an output queue in *SYSBAS if that same spooled file resides in an output queue of another independent disk pool.

Note: If a spooled file is being moved using format MSPF0200 after a file which is on an output queue in a library that is in the process of being renamed, the spooled file could end up in some other position than directly after the spooled file specified.

Authorities and Locks

Output Queue of Spooled File Being Moved

*EXCLRD

New Output Queue of File Being Moved

*EXCLRD

Output Queue Library Authority

*EXECUTE

Output Queue Authorities

When the source spooled file moves to a different output queue and the source output queue is defined with DSPDATA(*OWNER), the requester must be the owner of the source spooled file or have *SPLCTL authority.

One or more of the following conditions must be met to move a spooled file on the destination output queue. The destination queue can be either the source output queue or a different output queue.

• The requester has *SPLCTL authority.
• The requester has *JOBCTL authority, and the destination output queue is specified as OPRCTL(*YES).
• The requester has *READ authority to the output queue.

Spooled File Authorities

The requester is authorized to the source spooled file if one or more of the following conditions are met:

• The requester is the owner of the spooled file.
• The requester has *SPLCTL authority.
• The requester has *JOBCTL authority, and the source output queue is specified as OPRCTL(*YES).
• The source output queue is defined as AUTCHK(*OWNER) and the requester has ownership rights to the output queue.
• The source output queue is defined as AUTCHK(*DTAAUT) and the requester has data rights (read, add, and delete) to the output queue.

User Profile Highest Schedule Priority

When the requester has no other special authorities, the following are also in effect:

• When moving a spooled file to the top of an output queue and one of the following is true, the priority is set to 1:
  • The requester has *SPLCTL authority.
  • The requester has *JOBCTL authority, and the destination output queue is specified as OPRCTL(*YES).
  • The destination output queue is defined as AUTCHK(*OWNER) and the requester has ownership rights to the output queue.
  • The destination output queue is defined as AUTCHK(*DTAAUT) and the requester has data rights (read, add, and delete) to the output queue.
• If a spooled file is moved ahead of a spooled file owned by someone else and both spooled files have the same priority, the requester must have a priority limit of one less than the priority of the spooled file.
• If the requester's priority limit is the same as the spooled files it is to be moved ahead of, all spooled files at that priority level must be owned by the requester.

Special authorities of *JOBCTL (job control) and *SPLCTL (spool control) allow the requester to move a spooled file anywhere on an output queue.

Required Parameter Group

Function information

INPUT; CHAR(*)

The information that is associated with the spooled file to be moved and the output queue to which it is 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 valid length for format MSPF0100 is 92 bytes or 114 bytes; the valid length for format MSPF0200 is 144 bytes or 188 bytes. If a valid length is not specified, message CPF3C1D will be issued.

Function information format name

INPUT; CHAR(8)

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

The formats are:

MSPF0100	Format for the function of *NEXT, which is a move of the source spooled file ahead of all other ready spooled files on the target output queue.
MSPF0200	Format for the function of *AFTER, which is a move of the source spooled file after the target spooled file.

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

MSPF0100 Format

The following table shows the information provided for the MSPF0100 format. For more details about the fields in the following table, see Field Descriptions.

MSPF0200 Format

The following table shows the information provided for the MSPF0200 format. For more details about the fields in the following table, see Field Descriptions.

Field Descriptions

Source internal job identifier. The internal identifier for the job that owns the spooled file to be moved. Only IBM^® i APIs use this identifier; no other interface on the system does.

Note: 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 the source job name is given.

Use one of the following APIs to make the identifier available:

• List Spooled Files (QUSLSPL) API
• Retrieve Spooled File Attributes (QUSRSPLA) API

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

Source internal spooled file identifier. The internal identifier for the spooled file to be moved. Only the IBM i APIs use this identifier; no other interface on the system does.

Note: The identifier is not valid following an initial program load (IPL) or if the spooled file has been moved between auxiliary storage pools (ASPs). If you attempt to use an invalid internal spooled file identifier, an exception occurs.

This field must be blank when a source spooled file name is given.

Use one of the following APIs to make the identifier available:

• List Spooled Files (QUSLSPL) API
• Retrieve Spooled File Attributes (QUSRSPLA) API

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

Source job name. The name of the job that owns the spooled file to be moved.

The possible values are:

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

Source job system name. The name of the system where the job that created the source spooled file ran or blank when the source spooled file name is *INT. This field is considered after the source job name, source user name, source job number, source spooled file name, and source spooled file number field requirements have been met.

The possible values are:

When the Length of function information parameter is less than 114 with format MSPF0100 or less than 188 with format MSPF0200, the API assumes blanks when the source spooled file name is *INT. When source spooled file name is not *INT, the API assumes *ONLY.

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

Source spooled file create date. The date, based on local job time, that the source spooled file was created on the system or blank when the spooled file name is *INT. This field is considered after the source job name, source job user name, source job number, source spooled file name, source spooled file number, and source job system name field requirements have been met. The date must be in the CYYMMDD format or one of the following special values:

When the Length of function information parameter is less than 114 with format MSPF0100 or less than 188 with format MSPF0200, the API assumes blanks when the spooled file name is *INT. When spooled file name is not *INT, the API assumes *ONLY.

Source spooled file create time. The time, in local job time, that the source spooled file was created on the system or blank when the source spooled file name is *INT. This field must be set to blanks when special values *LAST or *ONLY are used for field source spooled file create date. This field must have a value set if a date is specified for field source spooled file create date. This field is considered after the source job name, source job user name, source job number, source spooled file name, source spooled file number, source job system name, and source spooled file create date field requirements have been met. The time must be in the HHMMSS format or one of the following special values:

When the Length of function information parameter is less than 114 with format MSPF0100 or less than 188 with format MSPF0200, the API assumes blanks for this field.

Source spooled file name. The name of the spooled file to be moved.

The possible values are:

Source spooled file number. The unique number of the spooled file to be moved. The valid range is -1 through 999999 and must be specified as such even if the value for the spooled file name field is *INT.

The following special values are supported for this field:

Target internal job identifier. The internal identifier for the job of the spooled file after which the source spooled file is to be moved. Only the IBM i APIs use this identifier; no other interface on the system does.

Note: 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 job name is given.

Use one of the following APIs to make the identifier available:

• List Spooled Files (QUSLSPL) API
• Retrieve Spooled File Attributes (QUSRSPLA) API

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

Target internal spooled file identifier. The internal identifier for the spooled file after which the source spooled file is to be moved. Only the IBM i APIs use this identifier; no other interface on the system does.

Note: The identifier is not valid following an initial program load (IPL) or if the spooled file has been moved between auxiliary storage pools (ASPs). If you attempt to use an invalid internal spooled file identifier, an exception occurs.

This field must be blank when a target spooled file name is given.

Use one of the following APIs to make the identifier available:

• List Spooled Files (QUSLSPL) API
• Retrieve Spooled File Attributes (QUSRSPLA) API

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

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

The possible values are:

Target job number. The number of the target job. This is the number of the job that owns the spooled file after which the source spooled file is to be moved. It can optionally be blank when a target job name or target job user name is specified. This field must be blank when the target job name is specified as *INT or *.

Target job system name. The name of the system where the job that created the target spooled file ran or blank when the target spooled file name is *INT. This field is considered after the target job name, target job user name, target job number, target spooled file name, and target spooled file number field requirements have been met.

The possible values are:

When the Length of function information parameter is less than 188, the API assumes blanks when the spooled file name is *INT. When spooled file name is not *INT, the API assumes *ONLY.

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 or *.

Target output queue library name. The name of the library that contains the output queue.

The possible values are:

Target output queue name. The name of the output queue to which the source spooled file is to move to the top of.

The possible values are:

Target spooled file create date. The date, based on local job time, that the target spooled file was created on the system or blank when the target spooled file name is *INT. This field is considered after the target job name, target job user name, target job number, target spooled file name, target spooled file number, and target job system name field requirements have been met. The date must be in the CYYMMDD format or one of the following special values:

When the Length of function information parameter is less than 188, the API assumes blanks when the target spooled file name is *INT. When target spooled file name is not *INT, the API assumes *ONLY.

Target spooled file create time. The time, in local job time, that the target spooled file was created on the system or blank when the target spooled file name is *INT. This field must be set to blanks when special values *LAST or *ONLY are used for field target spooled file create date. This field must have a value set if a date is specified for field target spooled file create date. This field is considered after the target job name, target job user name, target job number, target spooled file name, target spooled file number, target job system name, and target spooled file create date field requirements have been met. The time must be in the HHMMSS format or one of the following special values:

When the Length of function information parameter is less than 188, the API assumes blanks for this field.

Target spooled file name. The name of the spooled file after which the source spooled file is to be moved.

The possible values are:

Target spooled file number. The unique number of the spooled file after which the source spooled file is to be moved. The valid range is -1 through 999999 and must be specified as such even if the value for the spooled file name field is *INT. The following special values are supported for this field:

How to Specify Spooled File Identifying Fields

This table illustrates the valid field combinations of qualified job name, internal job identifier, internal spooled file identifier, spooled file name, spooled file number, job system name, spooled file create date, and spooled file create time. The combinations of these fields identify the spooled file to be moved and the spooled file it is to be moved after. For example, when the qualified job name field value is *, the internal job identifier must be blank, the internal spooled file identifier must be blank, the actual name of the spooled file must be given, and a valid spooled file number must be given.

Spooled File Identifying Fields

Notes: This parameter combination is not valid when a job has been detached from its spooled files or for a spooled file on an independent disk pool. Use of this combination will result in message CPF3C43.

Error Messages

[ Back to top | Print APIs | APIs by category ]