COZZI - Copy OUTQ to OUTQ (CPYOUTQ)

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

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:

Top

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
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, *SRLNBR, *USRDTA, *DATE, *FULL, *FULLSYS 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.
Top

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Top

Error messages

Unknown
Top