COZZI - Copy Spool File (CPYPRTF)

Where allowed to run: All environments (*ALL)
Threadsafe: No
Parameters
Examples
Error messages

The COZZI - Copy Spool File (CPYPRTF) command duplicates a SPOOL file and places it on another Output Queue or converts it to PDF and stores it on the IFS. The original SPOOL file is not modified by this command. The new SPOOL file may be created with alternate SPOOL file attributes, overriding those from the original SPOOL file before creating the copy. Attributes including but not limited to FORMS, COPIES, SPLFNAME SPLFOWNER, USRDTA, HOLD, and SAVE may be overriden.

Restrictions:

This command uses the IBM QSPCRTSP API which is shipped (typically) with PUBLIC *EXCLUDE authority. To allow users to use the CPYPRTF command *USE authority to QSPCRTSP API is required.

Top

Parameters

Keyword Description Choices Notes
SPLFNAME SPOOL file name Name, *LAST Required, Positional 1
JOB Job name Single values: *, *CURRENT
Other values: Qualified job name
Optional, Positional 2
Qualifier 1: Job name Name
Qualifier 2: User Name
Qualifier 3: Number 000000-999999
SPLNBR SPOOL file number 0-999999, *ONLY, *LAST, *ANY Optional, Positional 3
NEWSPLF New SPOOL file name Name, *SPLFNAME, *CRTPGM, *SAME Optional
OUTQ Copy to Output queue Single values: *SAME
Other values (up to 300 repetitions): Qualified object name
Optional
Qualifier 1: Copy to Output queue Name, *PDF, *TEXT
Qualifier 2: Library Name, *LIBL
STMF Stream file location Path name, *NONE, *HOME, *HOMEPDF, *USRPRF Optional
STMFNAME Stream file name or *STMF Path name, *STMF, *SPLF, *SPLFNAME, *OUTQ, *SRLNBR, *USRDTA, *DATE, *FULL, *FULLSYS Optional
STMFOPT Create or Replace Stream file *REPLACE, *CREATE Optional
STMFDIROPT Create Stream file folder *CREATE, *YES, *NONE, *NO Optional
STMFCCSID CCSID for IFS file 1-65535, *ASCII, *PCASCII, *APPLE, *BINARY, *JOB, *NONE, *UTF8, *UTF16 Optional
FORMTYPE New Form type Character value, *SAME Optional
USRDTA New User-Data Character value, *SAME, *CRTPGM Optional
HOLD Hold *SAME, *YES, *NO Optional
SAVE Save after printing *SAME, *YES, *NO Optional
COPIES Copies 1-255, *SAME Optional
SPLFOWN New SPOOL file owner Name, *SAME Optional
EXPDATE Expiration date Date, *SAME, *NONE, *DAYS Optional
DAYS Days until SPOOL file expires Integer, *SAME Optional
PAGERANGE Page range to print Element list Optional
Element 1: Starting page Integer, *SAME, *ENDPAGE, *FIRST
Element 2: Ending page Integer, *SAME, *END, *PAGES
Element 3: Number of pages to print Integer, *RANGE
WAIT Wait for open SPLF to close *YES, *NO Optional
Top

SPOOL file name (SPLFNAME)

Specify the name of the SPOOL file to be copied.

This is a required parameter.

name
Specify the name of the existing SPOOL file to be duplicated.
*LAST
Use this special value to indicate that the last SPOOL file created in the job is copied, regardless of its SPOOL File Name (SPLFNAME).
Top

Job name (JOB)

Specifies the job that created the spooled file whose data shall be copied.

Single values

* or *CURRENT
The current running job (the job running the CPYPRTF command) created the SPOOL file. Use *CURRENT when end-users are enter this information and they need a more clearly recognizable value.
Top

SPOOL file number (SPLNBR)

Specifies the number of the spooled file whose data is to be copied, from the job specified on the JOB parameter. If SPLFNAME(*LAST) is specified, this parameter is ignored.

*ONLY
There is only one SPOOL file with the name specified on the SPLFNAME parameter.
*LAST
The highest SPOOL file number with the same name as the SPLFNAME is used as the SPLNBR.
*ANY
*ANY means the SPLNBR is not used to find the SPOOL file. Future enahancements to the CPYPRTF command shall use this option.
Top

New SPOOL file name (NEWSPLF)

Specify the name for the new SPOOL file.

*SPLF
The SPOOL file name along with the file suffix of 'PDF' or 'TXT' is used as the stream file name. The entire name is prefixed with the JOBNBR and SPLNBR as follows: 100238_000001_QPRINT.PDF
*SPLFNAME
The new SPOOL file has the same name as the original SPOOL file.
*SAME
The new SPOOL file has the same name as the original SPOOL file. This is the same as specifying NEWSPLF(*SPLFNAME)
*CRTPGM
If the SPOOL File being copied was created by a user-written program and the program name is stored in the SPOOL File description, then the SPOOL File name of the copy will be the same as the creating program name. If no creation program is saved with the SPOOL file, the current name is used as the new SPOOL file name.
Top

To Output queue (OUTQ)

Specify the name of the output queue where the copy of the SPOOL file is placed.

Single values

*SAME
The new SPOOL file is created in the same output queue as the original.

Other values (up to 300 outq names)

name
Specify one more qualified output queue names for the new SPOOL file. A new SPOOL file is created for each outq specified for this parameter.
*PDF
The selected SPOOL files are copied to the IFS (the STMF parameter is required) after being converted to PDF format.
Top

Stream File Folder Location (STMF)

Identifies the IFS directory (folder) where the PDF or Text file(s) are written. The directory must exist unless STMFDIROPT(*YES) is specified. You may specify a full-qualified IFS file name (including the file name) with this parameter when STMFNAME(*STMF) is specified. For example this:

STMF('/home/cozzi/pdf/wrkactjob.pdf') STMFNAME(*STMF)

is the equivalent of this:

STMF('/home/cozzi/pdf') STMFNAME('WRKACTJOB.PDF')

*HOME
The PDF file is written to the /home/%u directory. Where %u is replaced with the user profile of the user running the command.
*None
No PDF output is produced. If OUTQ(*PDF) and STMF(*NONE) are specified an error is issued.
*HOMEPDF
The directory is /home/%u/pdf meaning a subdirectory named PDF is used within the classic default /HOME/USER directory. If the user running the command has user profile of COZZI, then /home/cozzi/pdf is the folder location.
*USRPRF
The HOME directory associated with the User Profile is retrieved and used as the folder location. While this is oftent the same as specifying *HOME for this parameter, some configuations use altnerative locations. Whatever directory name is stored with the user profile is used when *USRPRF is specified.
directory
Specify any directory on the IFS were the PDF document are written. You may embed any of the following special values to be used as substitution arguments in the path name (STMF) parameter:
%h
Home Directory for the user running the command.
%sf or %f
SPOOL File Name
%sn or %n
SPOOL File Number
%su
SPOOL File job User Profile.
%so or %ow
SPOOL File Owner.
%s
System name on which the SPOOL file was created (NOTE: This is actually the system serial number although it is documented, internally as the System Name, it is not.)
%ud
SPOOL File User Data
%u
Current User Profile (of user running the command)
%o or &oq
Current Output Queue where the SPOOL file exists.
%l or ol
Output Queue Library name
%cd or d
SPOOL File Create Date
%j
Job information of the job that created the SPOOL file. As 999999_user_jobname
%jb or &jo or &jj
Job (name) that created the SPOOL file.
%ju
User profile of user whose job created the SPOOL file.
%jn
Job number of the job that created the SPOOL file.
Top

Stream File Name (STMFNAME)

Specifies the name for the PDF or text file to be created.

*SPLFNAME
The SPOOL file name along with the file suffix of 'PDF' or 'TXT' is used as the stream file name.
*STMF
Specifies that this parameter (STMFNAME) is ignored by the command. The file name is specified on the STMF parameter, including the folder/path where the PDF or text file is creatd, along with the file name where it is stored.
*OUTQ
The SPOOL File's output queue name and SPOOL File name are used to produce the PDF file name. The format shall be: OUTQ_SPLFNAME.PDF where OUTQ is the OUTPUT QUEUE name and SPOOL is the SPOOL file name.
*USRDTA
The SPOOL File's user data AND SPOOL File name are used to produce the PDF file name. The format shall be: USRDDTA_SPLFNAME.PDF where USRDTA is the user data and SPOOL is the SPOOL file name. Any embedded blanks in the USRDTA are replaced with the underscore symbol. For example, if a SPOOL file named QPRINT has USRDTA('IBM IRD') then the generated PDF file name shall be: IBM_IRD_QPRINT.PDF
*SRLNBR
The serial number of the system on which the SPOOL file was created is used as part of the PDF file name: SRLNBR_SPLFNAME.PDF
*DATE
The PDF file name is generated with a 3-part name: Creation Date, output queue and SPOOL file name, as follows: CRTDATE_OUTQ_SPLFNAME.PDF
*FULL
The PDF file name is generated with a 4-part name: Creation Date, serial number, output queue and SPOOL file name, as follows: CRTDATE_SRLNBR_OUTQ_SPLFNAME.PDF
*FULLSYS
The PDF file name is generated similar to *FULL except the creation date and serial number are reversed. SRLNBR_CRTDATE_OUTQ_SPLFNAME.PDF
name
Specify the file name for the PDF file. If one of the previous special values does not give you what you want you may specify a valid name along with any of the following embedded symbols. These symbols are replaced in the name with their corresponding value.
%n
Name of the SPOOL File (SPLFNAME)
%s
System name on which the SPOOL file was created (NOTE: This is actually the system serial number although it is documented, internally as the System Name, it is not.)
%ud
User Data
%u
SPOOL File Owner (User Profile that created the SPOOL file)
%o
Output Queue (OUTQ) name
%l
Output Queue Library name
%d
SPOOL File Create DATE
Top

PDF File Option (STMFOPT)

Specify if the PDF file should be created or replaced in the target STMF folder. CPYPRTF does not support a "mbropt(*ADD)" style function. Target IFS Stream Files are either created or replaced, never added-to.

*REPLACE
If the PDF file already exists, it is cleared and replaced.
*CREATE
The PDF file is created. If the file already exists, the CPYPRTF operation will fail and no PDF file shall be created or replaced.
Top

Stream File Directory Option (STMFDIROPT)

Specify if the directory structure where the stream file is being stored should be created by the CPYPRTF command (if it does not already exist).

*CREATE or *YES
If the IFS folder already exists, nothing happens. If the IFS folder structure does NOT exist, it is created, including any subfolders. For example if the base user folder exists, /home/cozzi and STMF('/home/cozzi/pdf/pickles') is specified for the folder location, when STMFDIROPT(*CREATE) is specified, the PDF subfolder is created, and then the PICKLES subfolder is created within the PDF folder.
*NONE
The folder is not created. If it does not exist, the CPYPRTF command will fail.
Top

CCSID for IFS Stream file (STMFCCSID)

Specifies the CCSID of the PDF or TEXT file created by the command. If the file already exists and STMFOPT(*REPLACE) is specified, the existing file is deleted and a new file with the STMFCCSID is created in its place.

*PCASCII
The file is created and data is converted to CCSID 819 (PC ASCII)
*DFT
CCSID 65535 (no ccsid) is assigned to the IFS stream file.
*JOB
The CCSID of the current job is assigned to the IFS stream file.
*UTF8
The CCSID for UTF-8 (1208) is assigned to the IFS stream file.
*UTF16
The CCSID for UTF-16 (1200) is assigned to the IFS stream file.
1-65535
Specify the valid CCSID for the CSV file being generated.
Top

New Form type (FORMTYPE)

Specify the FORMS Type for the new SPOOL file. NOTE: If multiple OUTQ names are specified all SPOOL files created shall have the same FORMS type.

*SAME
The FORMS Type is the same as the original SPOOL file.
Top

New User-Data (USRDTA)

Specify the User Data assigned to the new SPOOL file.

*SAME
The User Data is the same as the original SPOOL file.
*CRTPGM
If the SPOOL File being copied was created by a user-written program and the program name is stored in the SPOOL File description, then the User Data associated with the new SPOOL file (the copy) shall be set to the name of the program that created the original SPOOL file.
character-value
Specify the user data for the new SPOOL file(s).
Top

Hold (HOLD)

Specify whether or not the new SPOOL file is placed on Hold in the output queue.

*SAME
The HOLD attribute is the same as the original SPOOL file.
*YES
The new SPOOL file is held on the output queue.
*NO
The new SPOOL file is not held on the output queue.
Top

Save after printing (SAVE)

Specify whether or not the new SPOOL file is saved after it is printed.

*SAME
The new SPOOL file SAVE attribute is the same as the original SPOOL file.
*YES
The new SPOOL file is saved after it is printed.
*NO
The new SPOOL file is not saved after it is printed. The SPOOL file will be deleted after it is printed.
Top

Copies (COPIES)

Specifiy the number of copies for the new SPOOL file.

*SAME
The new SPOOL file has the same number of copies as the original SPOOL file.
1-255
Specify the number of copies for the new SPOOL file. The valid range of copies is 1 to 255.
Top

New SPOOL file owner (SPLFOWN)

Specify the owner of the new SPOOL file.

*SAME
The new SPOOL file is owned by the same owner as the original SPOOL file.
name
Specify a user profile that becomes the owner of the new SPOOL file.
Top

Expiration date (EXPDATE)

Specifiy the date the new SPOOL file becomes eligible to be deleted by the Delete Expired Spooled Files (DLTEXPSPLF) command. The DLTEXPSPLF command does NOT include a USER (user profile) parameter, so running it means deleting all eligible SPOOL files.

*SAME
The new SPOOL file has the same expiration date as the original SPOOL file.
*NONE
The new SPOOL file has no expiration date.
*DAYS
The expiration date for the new SPOOL file is calculated based on the today's date plus the value specified on the DAYS parameter.
date
Specify the date that the new SPOOL file becomes eligible to be deleted.
Top

Days until SPOOL file expires (DAYS)

When EXPDATE(*DAYS) is specified, this parameter indicates the number of days until the new SPOOL file is eligible to be deleted by the Delete Expired Spooled Files (DLTEXPSPLF) command.

*SAME
The DAYS until expire are based on the EXPDATE. If EXPDATE(*DAYS) is specified, and DAYS(*SAME) is specified, the expiration date is the same as the original SPOOL file.
1-366
Specify the number of days after which the SPOOL file becomes eligible for removal from the system by the Delete Expired Spooled Files (DLTEXPSPLF) command. The actual expiration date applied to the spooled file is calculated by adding the number of days specified here, to the date this command is executed.
Top

Page range to print (PAGERANGE)

Specify the printable page range for the new SPOOL file. Use this parameter to copy a segment of an existing SPOOL file. While the entire SPOOL file is copied, the page range to be printed for the new SPOOL file is adjusted to the values specified for this parameter.

Element 1: Starting page

*SAME
The starting page is the same as the original SPOOL file.
*ENDPAGE
The first page to be printed is identified on the ENDPAGE element of this parameter.
*FIRST
The first page to be printed is the first page in the document.
integer
Specify the specific page number as the first page to be printed.

Element 2: Ending page

*SAME
The ending page is the same as that of the original SPOOL file.
*END
The last page to be printed is the "end page"--last page in the new SPOOL file.
*PAGES
The last page to print is calculated by the RANGE element. When *PAGES is specified, you must specify the number of pages to print element of this parameter.
integer
Specify the specific ending page to be printed.

Element 3: Number of pages to print

*RANGE
The page range is used to calculate the number of pages to print.
integer
Specify the number of pages to print. This parameter is ignored expect when *PAGES is specified for the ending page number.
Top

Wait for open SPLF to close (WAIT)

Specifies if the CPYPRTF command should wait for SPOOL files that are currently NOT in a RDY (ready) state to become RDY.

*YES
If CPYPRTF encounters a SPOOL file that is not yet in the RDY (ready) state, it will wait for the SPOOL file to become RDY.
*NO
If CPYPRTF encounters a SPOOL file that is not in the RDY (ready) state it skips the SPOOL file and does not copy it.
Top

Examples for CPYPRTF

Example 1: Simple Command Example

CPYPRTF  SPLFNAME(AGING) SAVE(*YES) OUTQ(QUSRSYS/ARCHIVE)

This command copies the SPOOL file named AGING and places the copy on the ARCHIVE output queue in library QUSRSYS. The SPOOL file attribute to Save After Printing is changed to *YES.

Example 2: Copy to multiple target OUTQ's

CPYPRTF  SPLFNAME(BUDGET) OUTQ(BOBC CAROLEJ JOHNC ALANC)

This makes 4 copies of the SPOOL file named EMAIL and places one on each of the OUTQ's specified.

Top

Error messages

Unknown
Top