Copy Spooled File (CPYSPLF)

The Copy Spooled File (CPYSPLF) command copies the data records in the specified spooled file either to a user-defined physical database file or to a stream file. This allows the use of spooled files in applications using microfiche, data communications, or data processing.

When copying a spooled file to a stream file, the spooled file can optionally be converted using a workstation customizing object. This allows the spooled file to be converted to other formats such as Portable Document Format (PDF). In order to convert a spooled file using the Workstation customizing object (WSCST) parameter, the device type (DEVTYPE) of the spooled file must be *SCS or *AFPDS.

When you copy a spooled file to a physical file or you copy it to a stream file without conversion, certain information is lost or changed. For example:

When you copy a spooled file to a stream file with conversion, the information retained and the format of the output is dependent on the workstation customizing obejct specified.

Parameters

Keyword Description Choices Notes
FILE Spooled file Name Required, Positional 1
TOFILE To data base file Single values: *TOSTMF
Other values: Qualified object name
Required, Positional 2
Qualifier 1: To data base file Name
Qualifier 2: Library Name, *LIBL, *CURLIB
JOB Job name Single values: *
Other values: Qualified job name
Optional
Qualifier 1: Job name Name
Qualifier 2: User Name
Qualifier 3: Number 000000-999999
SPLNBR Spooled file number 1-999999, *ONLY, *LAST, *ANY Optional
JOBSYSNAME Job system name Name, *ONLY, *CURRENT, *ANY Optional
CRTDATE Spooled file created Single values: *ONLY, *LAST
Other values: Element list
Optional
Element 1: Creation date Date
Element 2: Creation time Time, *ONLY, *LAST
TOMBR To member Name, *FIRST Optional
MBROPT Replace or add records *REPLACE, *ADD Optional
CTLCHAR Control character *NONE, *FCFC, *PRTCTL, *S36FMT Optional
CHLVAL Channel values Single values: *NORMAL
Other values (up to 12 repetitions): Element list
Optional
Element 1: Channel 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Element 2: Line 1-255
TOSTMF To stream file Path name, *NONE Optional
WSCST Workstation customizing object Single values: *NONE, *PDF
Other values: Qualified object name
Optional
Qualifier 1: Workstation customizing object Name
Qualifier 2: Library Name, *LIBL, *CURLIB
STMFOPT Stream file option *NONE, *REPLACE Optional
Start of changeOPNSPLFend of change Copy open spooled file *NO, *YES Optional

Spooled file (FILE)

Specifies the spooled file that is to be copied to a database file or stream file.

This is a required parameter.

name
Specify the file name of the spooled file.

To data base file (TOFILE)

Specifies whether the spooled file's records will be copied to a user-defined physical database file or a stream file. If the user specifies the name of a database file and the file does not exist at the time of the copy, the copy will fail.

This is a required parameter.

Single values

*TOSTMF
The spooled file will be converted based on the workstation customizing object specified in the Workstation customizing object (WSCST) parameter and the output placed in the stream file specified in the To stream file (TOSTMF) parameter.

Qualifier 1: To data base file

name
Specify the file name of the physical file to receive the copy.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the file. If no current library entry exists in the library list, QGPL is used.
name
Specify the name of the library where the file is located.

Job name (JOB)

Specifies the job that created the spooled file whose data records are to be copied.

Single values

*
The job that issued this command is the job that created the spooled file.

Qualifier 1: Job name

name
Specify the name of the job that created the spooled file.

Qualifier 2: User

name
Specify the user name that identifies the user profile under which the job is run.

Qualifier 3: Number

000000-999999
Specify the system-assigned job number.

Spooled file number (SPLNBR)

Specifies the number of the spooled file, from the job whose data records are to be copied.

*ONLY
Only one spooled file in the job has the specified file name; therefore, the number of the spooled file is not necessary.
*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 create date and time parameter is to take precedence over the spooled file number when selecting a spooled file.
1-999999
Specify the number of the spooled file whose data records are to be copied.

Job system name (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 create 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 create 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 create date and time parameter is to take precedence over the job system name when selecting a spooled file.
name
Specify the name of the system where the job that created the spooled file ran.

Spooled file created (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.

Single values

*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 create 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: Creation date

date
Specify the date the spooled file was created.

Element 2: Creation time

*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 create date.
*LAST
The spooled file with the latest create time of the specified job name, user name, job number, spooled file name, spooled file number, job system name, and spooled file create date is used.
time
Specify the time the spooled file was created.

To member (TOMBR)

Specifies the name of the file member that receives the copied records.

*FIRST
The first member of the specified file is used.
name
Specify the name of the member of the physical file. If this member does not exist, a member is created and the copy continues.

Replace or add records (MBROPT)

Specifies whether the new records replace or are added to the existing records.

*REPLACE
The system clears the existing member and adds the new records.
*ADD
The system adds the new records to the end of the existing records.

Control character (CTLCHAR)

Specifies which print control characters (if any) are to replace the spooled file's internal print control characters. This parameter is ignored if the Workstation customizing object (WSCST) parameter is specified and is not *NONE.

*NONE
No print control characters are created.
*FCFC
Specifies that the first character of every record contains one of the ANSI forms control codes. This option may be useful for microfiche production. For more information regarding the ANSI forms control codes, see the Basic printing topic collection in the Printing category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
*PRTCTL
Specifies that the first four characters of every record contains skip- and space-before values useful in high-level language programs. This code can be viewed as SSSL, where SSS is the skip-before line value and L is the space-before value.
*S36FMT
Specifies that the format of the records to be copied to a database file is the same as that created on the IBM System/36 for COPYPRT. This value is not allowed for spooled files which exist on primary or secondary auxiliary storage pools.

Channel values (CHLVAL)

Specifies a list of channel numbers with their assigned line numbers. Specify this parameter only if *FCFC is specified on the Control character (CTLCHAR) parameter). Channel number refers to a method of determining skipping for reports. Each assigned channel must have a corresponding line number to provide the correct positioning on a report.

Single values

*NORMAL
Indicates channel 1 is the only assigned channel number. The assigned line number for channel 1 is line 1.

Other values (up to 12 repetitions)

Element 1: Channel

channel-number
Specify which channels are used to control skipping on a report. The only valid values for this parameter are 1 through 12. Each channel number can be specified only once per Copy Spooled File (CPYSPLF) command.

Element 2: Line

1-255
The line number assigned for the channel number in the same list. The range of valid line numbers is 1 through 255. Each line number can be specified only once per Copy Spooled File (CPYSPLF) command.

To stream file (TOSTMF)

Specifies the stream file where the output data is to be written. All directories in the path name must exist. New directories are not created. This parameter must specify a value other than *NONE if the To data base file (TOFILE) parameter is *TOSTMF.

*NONE
The output is written to a user-defined physical file. This value is only valid if the To data base file (TOFILE) parameter specifies a user-defined physical database file.
path-name
Specify the path name for the stream file where the output data is to be written. This value is only valid if the To data base file (TOFILE) parameter specifies *TOSTMF.

Note: If the stream file exists, the CCSID associated with the stream file will not be changed.

For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.

Workstation customizing object (WSCST)

Specifies the workstation customizing object to use to transform the spooled file output to final form before writing it to a stream file. If the To data base file (TOFILE) parameter specifies a physical database file, the WSCST parameter is ignored.

Single values

*NONE
Specifies that no workstation customizing object is to be used.

If the To data base file (TOFILE) parameter specifies *TOSTMF and the device type of the spooled file is *AFPDS or *USERASCII, the spooled file data will be copied directly to the stream file. If the stream file does not exist, the associated CCSID of the stream file will be set to 65535.

For other types of spooled files, the spooled file data will be copied to the stream file using the Control character (CTLCHAR) parameter to format the data. Lines will be ended with carriage return and line feed controls to indicate record boundaries. If the stream file does not exist, a CCSID obtained from the spooled file attributes will be associated with the stream file. If the spooled file has a CHRID attribute other than *DEVD, the CHRID attribute will be used to select the CCSID to be associated with the stream file. If the spooled file has a CHRID attribute of *DEVD, the CCSID of the job which created the spooled file will be used.

*PDF
The output is transformed to Portable Document Format (PDF) before it is written into a stream file. If the stream file does not exist, the CCSID associated with the stream file will be set to 65535.

Qualifier 1: Workstation customizing object

name
Specify the name of the customizing object. When a named customizing object is used and the stream file does not exist, the CCSID associated with the stream file will be set to 65535.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the customizing object. If no current library entry exists in the library list, QGPL is used.
name
Specify the name of the library where the customizing object is located.

Stream file option (STMFOPT)

Specifies whether the copy operation replaces or fails to copy the records to the stream file if a stream file with the specified name already exists. If the stream file does not exist, it is created.

*NONE
No records are copied and the operation will fail.
*REPLACE
The records replace the existing stream file records. Start of change

Copy open spooled file (OPNSPLF)

Specifies whether or not the copy operation is allowed to proceed if the spooled file specified in the FILE parameter is still open.

*NO
No records are copied if the spooled file is open, and the copy will fail.
*YES
A diagnostic message is issued if the spooled file is open, and the records are copied.End of change

Examples

Example 1: Replacing Data

CPYSPLF   FILE(QPRINT)  JOB(PAYROLL01)  SPLNBR(4)
          TOFILE(MYFILE)  TOMBR(MYMBR)  CTLCHAR(*PRTCTL)

In this example, file QPRINT (which is the fourth file produced by job PAYROLL01) is copied to member MYMBR of physical file MYFILE (which resides in a library found by searching the library list). The newly copied data replaces all old data in the member because all old records have been cleared. The 4-byte print control code is created.

Example 2: Adding Data

CPYSPLF   FILE(QPRINT)  TOFILE(MYLIB/MYFILE)  JOB(PAYROLL02)
          MBROPT(*ADD)  CTLCHAR(*FCFC)  CHLVAL((1 3) (4 15))

In this example, file QPRINT (the only file of that name left in job PAYROLL02) is copied to the first member of the physical file found in library MYLIB. The newly copied data is added to data existing in the member. The FCFC 1-byte print control character is used and takes advantage of the assigned channel values in formatting the output. The assigned channel values as specified on the command are as follows:

Example 3: Converting to PDF

CPYSPLF   FILE(EMAIL)  JOB(123456/BARON/EMAIL01)  SPLNBR(1)
          TOFILE(*TOSTMF)  TOSTMF('/emailpdfs/email01.pdf')
          WSCST(*PDF) STMFOPT(*REPLACE)

In this example, spooled file EMAIL (which is the first spooled file produced by job 123456/BARON/EMAIL01) is converted to a PDF and stored in directory '/emailpdfs' with the name email01.pdf where it can be used by another application. If the stream file already exists, the data in the stream file will be replaced.

Example 4: Copying an AFPDS Spooled File to a Stream File

CPYSPLF   FILE(MYDOC)  JOB(*)  SPLNBR(*LAST)  TOFILE(*TOSTMF)
          TOSTMF(mydoc.afp)  WSCST(*NONE)  STMFOPT(*NONE)

In this example, the last spooled file named MYDOC produced by the current job is copied without conversion to a stream file named 'mydoc.afp' in the current working directory. The spooled file has a DEVTYPE of *AFPDS. If the stream file already exists, the CPYSPLF command will fail.

Example 5: Converting an SCS Spooled File to an ASCII Text Stream File

CPYSPLF   FILE(MYDOC)  JOB(*)  SPLNBR(*LAST)  TOFILE(*TOSTMF)
          TOSTMF(/textfiles/mydoc.txt)  WSCST(QSYS/QWPDEFAULT)

In this example, the last spooled file named MYDOC produced by the current job is converted to ASCII text and placed in the directory '/textfiles' with the file name 'mydoc.txt'. The spooled file has a DEVTYPE of *SCS. If the stream file already exists, the CPYSPLF command will fail.

Error messages

*ESCAPE Messages

CPF2207
Not authorized to use object &1 in library &3 type *&2.
CPF3CF2
Error(s) occurred during running of &1 API.
CPF3207
Member not added. Errors occurred.
CPF3303
File &1 not found in job &5/&4/&3.
CPF3309
No files named &1 are active.
CPF3311
Copy request failed for file &6 in &7.
CPF3330
Necessary resource not available.
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 &8 no longer in the system.
CPF338A
Control character *S36FMT not allowed.
CPF3394
Cannot convert spooled file data.
CPF3429
File &1 number &7 cannot be displayed, copied, or sent.
CPF3482
Copy request failed. Spool file &1 is open.
CPF3483
Copy request failed for file &6 in &7.
CPF3486
CHLVAL parameter value not valid.
CPF3492
Not authorized to spooled file.
CPF3493
CTLCHAR parameter not correct for file &1.
CPF3499
Records in file &1 preceded all assigned channel values.
CPF5812
Member &3 already exists in file &1 in library &2.
CPF6DF2
AFP data stream in user space &1 not valid.
CPF6DF4
Object &2 in library &3 contains unrecognizable data.
CPF6DF8
Data cannot be transformed.
CPF6DFB
Error occurred while transforming data.
CPF9801
Object &2 in library &3 not found.
CPF9802
Not authorized to object &2 in &3.
CPF9803
Cannot allocate object &2 in library &3.
CPF9804
Object &2 in library &3 damaged.
CPF9812
File &1 in library &2 not found.
CPF9820
Not authorized to use library &1.
CPF9837
Attempt made to override file &1 to MBR(*ALL).
CPF9845
Error occurred while opening file &1.
CPF9846
Error while processing file &1 in library &2.
CPF9872
Program or service program &1 in library &2 ended. Reason code &3.
CPFA09C
Not authorized to object. Object is &1.
CPFA0A0
Object already exists. Object is &1.
CPFA0A1
An input or output error occurred.
CPFA0A9
Object not found. Object is &1.
CPFCE01
Required product option not available.
CPFCE02
Unable to access the required transform service.
CPFCE03
A data stream error was detected.
CPFCE05
Transformation task cancelled due to a print fidelity error.
CPFCE06
Error occurred while transforming print data.
CPFCE07
The transform service job terminated due to a critical error.
CPFCE09
SCS data stream is not valid.