HLDSPLF (Hold Spooled File)

HLDSPLF Command syntax diagram

 

Purpose

The Hold Spooled File (HLDSPLF) command stops the specified spooled file from additional processing by a spooling writer. If the file is being produced on an output device, the writer stops processing that file and gets the next file to be processed. When the file is released and again selected for output, it is again processed starting at the beginning. If several copies are being produced for the file when it is held, the incomplete copy is again produced from the beginning along with the remaining copies that follow it.

If the specified file is still receiving records from a program that is running when the file is held, the program that is running is unaware that the file is on hold. Also, if the held file is part of a job that produces other spooled files, they can be processed before the held file is released. The held file remains on the output queue and it appears to be the only file produced by the job.

The file is held until one of the following commands is entered: the RLSSPLF (Release Spooled File), the DLTSPLF (Delete Spooled File), the ENDJOB (End Job) with keyword SPLFILE(*YES) specified, or the CLROUTQ (Clear Output Queue) command. If the file is released before the writer begins producing it, the file is produced in its normal order within the group of files for the job. Production of a job's output is not delayed because some of its files are being held.

 

Required Parameters

FILE

Specifies the name of the spooled file to be held.

*SELECT: All spooled files that meet the selection requirements specified in the SELECT keyword are held. This value is mutually exclusive with the

JOB, SPLNBR, JOBSYNAME, and CRTDATE parameters. Specifying *SELECT causes the JOB, SPLNBR, JOBSYNAME, and CRTDATE parameters to be ignored.

spooled-file-name: Specify the name of the spooled file to be held.

 

Optional Parameters

JOB

Specifies the name of the job that created the file being held. If no job qualifier is given, all of the jobs currently in the system are searched for the simple job name.

A job identifier is a special value or a qualified name with up to three elements. For example:

job-name
*
user-name/job-name
job-number/user-name/job-name

More information on this parameter is in commonly used parameters.

*: The job that issued this HLDSPLF command is the job that produced the file being held.

job-name: Specify the name of the job that created the file being held.

user-name: Specify the name of the user of the job that created the file being held.

job-number: Specify the number of the job that created the file being held.

SPLNBR

Specifies the number of the spooled file to be held that was created by the specified job. More information on this parameter is in commonly used parameters.

*ONLY: One spooled file from the job has the specified file name. The number of the spooled file is not necessary. If *ONLY is specified and more than one spooled file has the specified file name, a message is sent.

*LAST: The spooled file with the highest number and the specified file name is used.

*ANY: The spooled file number is not used to determine which spooled file is used. Use this value when the job system name parameter or the spooled file creation date and time parameter is to take precedence over the spooled file number when selecting a spooled file.>

spooled-file-number: Specify the number of the spooled file that has the specified file name to be held.

JOBSYSNAME

Specifies the name of the system where the job that created the spooled file (JOB parameter) ran. This parameter is considered after the job name, user name, job number, spooled file name, and spooled file number parameter requirements have been met.

*ONLY: There is one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, and spooled file creation date and time.

*CURRENT: The spooled file created on the current system with the specified job name, user name, job number, spooled file name, spooled file number, and creation date and time is used.

*ANY: The job system name is not used to determine which spooled file is used. Use this value when the spooled file creation date and time parameter is to take precedence over the job system name when selecting a spooled file.

system name: Specify the name of the system where the job that created the spooled file ran.

CRTDATE

Specifies the date and time the spooled file was created. This parameter is considered after the job name, user name, job number, spooled file name, spooled file number, and job system name parameter requirements have been met.

*ONLY: There is one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, and job system name.

*LAST: The spooled file with the latest creation date and time of the specified job name, user name, job number, spooled file name, spooled file number, and job system name is used.

Element 1: Date spooled file was created

date: Specify the date the spooled file was created.

Element 2: Time spooled file was created

*ONLY: There is one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, job system name, and spooled file creation date.

*LAST: The spooled file with the latest creation time of the specified job name, user name, job number, spooled file name, spooled file number, job system name, and spooled file creation date is used.

time: Specify the time the spooled file was created.

SELECT

Specifies which group of files are selected to be held. Files can be selected based on user, device, form type, and user data. Only files that meet each of the requirements are selected.

Element 1: User Values

*CURRENT: Only files created by the user running this command are held.

*ALL: Files created by all users are held.

user-name: Specify the names of files to be held that were created by the specified user.

Element 2: Device Values

*ALL: Files queued for any device or on any object queue are held.

*OUTQ: All files that are not queued for a device are held. These files are on output queues that are not associated with printers.

device-name: Specify the names of files to be held that are queued for the specified device.

Element 3: Form Type Values

*ALL: Files for all form types are held.

*STD: Only files that specify the standard form type are selected.

form-type: Specify the form type of the files to be held.

Element 4: User Data Values

*ALL: Files with any user data tag specified are held.

user-data: Specify the user data tags of files to be held.

OPTION

Specifies which option to use when holding a spooled file. This parameter allows the user to choose when to hold a spooled file. If the spooled file being held is not currently being processed by a spool writer, this parameter is not valid. If the spooled file is being processed by a printer writer, then printing stops and a form feed is done to prepare the printer for the next spooled file to be printed.

*IMMED: The spooled file is held immediately.

*PAGEEND: The spooled file is held at a page boundary.

Examples for HLDSPLF

Example 1: Holding a File Created by Another Job

HLDSPLF  FILE(SHIPITEMS)  JOB(00009/JONES/ORDER)

This command withholds the spooled file SHIPITEMS, created by the job ORDER, from additional processing.

Example 2: Holding a File at a Page Boundary

HLDSPLF  FILE(QPJOBLOG)  OPTION(*PAGEEND)

This command holds the spooled file QPJOBLOG at a page boundary.

Example 3: Holding a File Immediately

HLDSPLF  FILE(QPJOBLOG)  OPTION(*IMMED)

This command holds the spooled file QPJOBLOG immediately. Holding a spooled file by specifying this option causes the CHGSPLFA command RESTART(*NEXT) to be inaccurate if the spooled file is currently being processed by a spool writer.

Error messages for HLDSPLF

*ESCAPE Messages

CPF33D0

Printer &1 does not exist.

CPF33D1

User &1 does not exist.

CPF3303

File &1 not found in job &5/&4/&3.

CPF3309

No files named &1 are active.

CPF3330

Necessary resource not available.

CPF3337

File &1 number &2 already held or saved.

CPF3340

More than one file with specified name found in job &5/&4/&3.

CPF3342

Job &5/&4/&3 not found.

CPF3343

Duplicate job names found.

CPF3344

File &1 number &2 no longer in the system.

CPF3357

Output queue &1 in library &2 not found.

CPF34A4

File &1 number &2 not held or deleted.

CPF3492

Not authorized to spooled file.