The COZZI - Copy OUTQ (CPYOUTQ) command copies spool files from one or more Output Queues to another output queue, several Output Queues, PDF files on the IFS, or to a remote output queue. The SPOOL files are not moved, they are copied--leaving the original SPOOL file image in place. If FROMOUTQ(*ALL) is specified, all output queues are searched for the SPOOL files to be copied. However the default for the JOB parameter is JOB(*) and this restricts the command to those SPOOL files created by the job running the CPYOUTQ command. Therefore, running CPYOUTQ FROMOUTQ(*ALL) TOOUTQ(QUSRSYS/MYOUTQ) will copy all SPOOL files created by "this" job (that still exist) to the target MYOUTQ output queue. If TOOUTQ(*PDF) is specified, the command copies the SPOOL files to the IFS after converting them to PDF format.

If the RMTSYS parameter is used, the TOOUTQ must exist on the remote system. The SPOOL files are sent to the Remote System and placed in the target output queue. In this case the CPYOUTQ acts as a front-end to the SENDSPLF command.

Restrictions:

• You must have *SPLCTL and other special authorities to copy certain spool files.
• This command is conditionally threadsafe.

Parameters

Keyword	Description	Choices	Notes
FROMOUTQ	Copy from output queue(s)	Single values: *ALL Other values (up to 300 repetitions): Qualified object name	Required, Positional 1
	Qualifier 1: Copy from output queue(s)	Name
	Qualifier 2: OUTQ Library	Name, *LIBL
TOOUTQ	Copy to output queue	Single values: *PDF, *TEXT Other values (up to 300 repetitions): Qualified object name	Required, Positional 2
	Qualifier 1: Copy to output queue	Name
	Qualifier 2: OUTQ Library	Name, *LIBL
STMF	Stream file location	Path name, *NONE, *HOME, *HOMEPDF, *USRPRF	Optional, Positional 14
STMFNAME	Stream file name or *STMF	Path name, *STMF, *SPLF, *SPLFNAME, *OUTQ, *SYSNAME, *USRDTA, *SYSDATE, *DATE, *FULL, *FULLSYS, *FULLUSRDTA, *SYSUSR, *USRSYS	Optional, Positional 15
STMFOPT	Create or Replace Stream file	*REPLACE, *CREATE	Optional, Positional 16
STMFDIROPT	Create Stream file folder	*CREATE, *YES, *NONE, *NO	Optional, Positional 17
STMFCCSID	CCSID for IFS file	1-65535, *PCASCII, *JOB, *NONE, *UTF8, *UTF16	Optional, Positional 18
RMTSYS	Copy to system	Character value, *LOCAL	Optional, Positional 3
JOB	Job name (dft is current job)	Single values: *ALL, *, *CURRENT Other values: Qualified job name	Optional, Positional 4
	Qualifier 1: Job name (dft is current job)	Name
	Qualifier 2: User	Name
	Qualifier 3: Number	000000-999999
USER	User profile filter	Single values: *ALL Other values (up to 300 repetitions): Name, *CURRENT	Optional, Positional 5
USRDTA	User data filter	Character value, *ALL, *BLANK	Optional, Positional 6
FORMTYPE	Forms type filter	Character value, *ALL, *STD	Optional, Positional 7
CRTDATE	SPOOL File Create-Time Filter	Single values: *ALL Other values: Element list	Optional, Positional 8
	Element 1: Earliest Date to include	Date, *CURRENT, *AVAIL
	Element 2: Earliest Time to include	Time, *AVAIL, *BEGIN
	Element 3: Ending Date to include	Date, *CURRENT, *AVAIL
	Element 4: Ending Time to include	Time, *AVAIL, *END, *CURRENT
SYSNAME	System name filter	Name, *ALL, *CURRENT	Optional, Positional 9
HOLD	Hold	*SAME, *YES, *NO	Optional, Positional 10
SAVE	Save after printing	*SAME, *YES, *NO	Optional, Positional 11
SPLFOWN	New SPOOL file owner	Name, *SAME	Optional, Positional 12
LOG	Log Copy Commands	*YES, *NO, *STATUS, *BOTH	Optional, Positional 13

Top

Copy from output queue(s) (FROMOUTQ)

Specify up to 300 output queue names whose SPOOL files shall be copied to the OUTQ specified on the TOOUTQ parameter. Be sure to specify the proper value for the JOB parameter to insure all the SPOOL files you want to copy are actually copied. Often times it is necessary to specify JOB(*ALL) instead of the default JOB(*).

NOTE: Since the list of SPOOL files is produced at the start of the CPYOUTQ command, SPOOL files created after the CPYOUTQ command has started are NOT included in the operation.

This is a required parameter.

Single values

*ALL

SPOOL files from all output queues in the designated library for the JOB identified on the JOB parameter, are copied.

Other values (up to 300 repetitions)

Output Queue

name

Specify up to 300 output queue name whose SPOOL files are to be copied.

Copy to output queue (TOOUTQ)

Specify target output queue to which the SPOOL files are copied. If the TOOUTQ is on another IBM i, then also specify the RMTSYS parameter.

This is a required parameter.

target-output queue

Specify the output queue where the copied SPOOL files should be stored.

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

*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 SPOOL file name along with the file suffix of 'PDF' or 'TXT' is used as the stream file name. If copying multiple SPOOL files with duplicate names, a subsequent output to the same name replaces the original .PDF or TXT file on the IFS. It is recommended that *SPLF be used instead of *SPLFNAME.

*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

*FULLUSRDTA

The PDF file name is the same as *FULLSYS except the USRDTA (User Data) is included if it exists. SRLNBR_CRTDATE_OUTQ_USRDTA_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

PDF File Option (STMFOPT)

Specify if the PDF file should be created or replaced in the target STMF folder. CPYOUTQ 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 CPYOUTQ operation will fail and no PDF file shall be created or replaced.

Stream File Directory Option (STMFDIROPT)

Specify if the directory structure where the stream file is being stored should be created by the CPYOUTQ 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 CPYOUTQ 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.

Copy to system (RMTSYS)

Specify the IP address or HOST table name entry where the TOOUTQ parameter exists. This allows you to copy the SPOOL files to an outq on another IBM i system (remote OUTQ). The TOOUTQ must exist on the remote location identified on this parameter.

*LOCAL

The TOOUTQ is on the local IBM i system--it is a local output queue.

remote IP or system name

Specify the IP address or system name as it appears in your DNS or in the HOST table on your system (See the IBM i CFGTCP command's option 10.)

Job name (JOB) Filter

Specify the job name to include in the copy procedures. Only SPOOL files created by the job specified here are copied. Often when copying an OUTQ, you may want to specify JOB(*ALL) instead of the default value, which is current job JOB(*).

Single values

*ALL

SPOOL files created by any (all) jobs are copied.

*

When * or *CURRENT is used, SPOOL files created during the current job only are copied.

User profile filter (USER)

Specifies User profiles whose SPOOL files are included in the copy.

Single values

*ALL

SPOOL files from ALL users are copied.

Other values (up to 300 user profile names)

*CURRENT

The current job's user is used to filter the SPOOL files.

name

Specify up to 300 User Profiles whose SPOOL files are included in the copy. Remember, only those SPOOL files that exist on the OUTQ(s) specified on the FROMOUTQ parameter are copied.

User data filter (USRDTA)

Specify user data to filter the SPOOL files being copied.

*ALL

User data is not used to filter the SPOOL files.

*BLANK

This special value indicates that SPOOL files with blank (empty) user data are included.

user-data

Specify any valid user data. Be sure to enclose it in quotes as this is a case-sensitive value, and can contain embedded blanks.

Forms type filter (FORMTYPE)

Specifies the type of FORMS used to filter the SPOOL files.

*ALL

FORMTYPE is not used to filter the SPOOL files being copied.

*STD

The FORM(*STD) SPOOL files are included in the copy.

forms-type

Only SPOOL files whose FORM match this parameter are included in the copy.

SPOOL File Create-Time Filter (CRTDATE)

Specifies the SPOOL file creation date range to be selected.

Single value

*ALL

All SPOOL files, regardless of creation date/time are selected.

Element 1: Earliest Date to include

*CURRENT

SPOOL files created on the curret job date are selected.

*AVAIL

Use *AVAIL with the Ending Date/Time to indicate that all SPOOL files created prior to the Earliest Date/Time are selected (regardless of how old those SPOOL file are).

date

Specify the earliest creation date of SPOOL files selected for copy.

Element 2: Earliest Time to include

*AVAIL

All SPOOL files created on the Earliest Date element are selected, regardless of the time they were selected.

*BEGIN

Same as *AVAIL, used for compatibility with WRKSPLF.

time

Specify the time. SPOOL file created after this time are selected.

Element 3: Ending Date to include

*CURRENT

SPOOL files included in the copy must have a creation date no later than the current job date.

*AVAIL

SPOOL files created on or after the Earliest Cration Date value are selected for copy.

date

Specify the latest creation date for SPOOL files to be selected for copy.

Element 4: Ending Time to include

*AVAIL

The creation time is ignored--only the ending date is used to select SPOOL files for copy.

*END

Same as *AVAIL, used for compatibility with WRKSPLF.

*CURRENT

The current time is used--SPOOL files created after the time the CPYOUTQ command begins running are not included.

time

Specify the latest time on the Ending Creation Date, for SPOOL files to be selected for copy.

System name filter (SYSNAME)

Specifies name of the System on which the SPOOL files to be included in the copy, are created. The system name is available by running the DSPNETA CL command.

*ALL

SPOOL Files with any system name may be selected for copy.

*CURRENT

SPOOL Files with the system name that matches the system name of the system on which the CPYOUTQ command is being run, are selected for copy.

name

Specify any system name to select only SPOOL files created on that specific system in the copy.

Hold (HOLD)

Specify whether or not the new SPOOL files are placed on Hold in the target 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.

Save after printing (SAVE)

Specify whether or not the new SPOOL files are saved after they are 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.

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.

Log Internal Copy Commands (LOG)

Controls whether to write the internal CL commands performing the copy operation to the joblog.

*YES

The CPYPRTF or SNDTCPSPLF command is written to the joblog for each SPOOL file that is copied.

*NO

No internal commands are written to the joblog. This is the default.

*STATUS

The CPYPRTF or SNDTCPSPLF commands are written to the *EXT message queue as *STATUS messages.

*BOTH

*STATUS causes both LOG(*YES) and LOG(*STATUS) to be used.

Examples for CPYOUTQ

Simple Command Example

CPYOUTQ  FROMOUTQ(*ALL) TOOUTQ(QUSRSYS/ARCHIVE)

This command copies all the SPOOL files created durring the current job (regardles of which OUTQ they are in) to the ARCHIVE outq queue in library QUSRSYS. The default for the JOB parameter is JOB(*) which limits the command to copying only SPOOL files for the current job, unless the JOB parameter is changed.

More Complex Command Example

CPYOUTQ  FROMOUTQ(SALES) TOOUTQ(QUSRSYS/SALES) JOB(*ALL)

This command copies all SPOOL file entries on the SALES outq (on the local system) to the SALES outq in library QUSRSYS. NOTE: The JOB parameter is JOB(*ALL) to include all SPOOL files on the SALES output queue rather than only those created in "this" job.

Copy All SPOOL files for a User

CPYOUTQ  FROMOUTQ(*ALL) TOOUTQ(QUSRSYS/BOB) RMTSYS(CHICAGO)
           USER(COZZI) JOB(*ALL)

This command copies all SPOOL file entries that exist on all output queues on the library for user COZZI to the output queue named BOB in QUSRSYS on the remote system named CHICAGO. NOTE: Since the list of SPOOL files is produced at the start of the CPYOUTQ command, SPOOL files created after the CPYOUTQ command has started are NOT included in the operation.

Error messages

Unknown