COZZI - Copy Spool File (CPYPRTF)

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.

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, TXT, *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, SYSNAME, USRDTA, SYSDATE, DATE, FULL, FULLSYS, FULLUSRDTA, SYSUSR, *USRSYS	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 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.

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.

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.

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.

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

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.

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.

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).

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.

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.

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.

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.