Move Spooled File (QSPMOVSP) API


  Required Parameter Group:


  Default Public Authority: *USE

  Threadsafe: No

The Move Spooled File (QSPMOVSP) API can:

The spooled files can be identified by:

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

Using this API, a spooled file can:


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:

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.


Spooled File Authorities

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


User Profile Highest Schedule Priority

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

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:


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:

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:

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:

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:

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



API introduced: V3R1

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