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:

• Print lines that are all blank are not copied.
• Graphics data is lost.
• Bar code data is lost.

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

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.

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:

• Line 3 assigned to channel 1
• Line 15 assigned to channel 4

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.