Change Spooled File Attributes (CHGSPLFA)

The Change Spooled File Attributes (CHGSPLFA) command allows you to change attributes of a spooled file while it is on an output queue. These changes affect only the current processing of the file. The next time the job runs and the file is produced, the file attributes are derived from the device file description, the program, and any override commands.

If the file is currently being produced on an output device, the only parameters that can be changed are COPIES, RESTART, and SAVE. An attempt to change any other parameter results in an error, and no file attributes are changed. However, if the file is being held on an output queue because of spooling attribute errors, this command can be used to change the attributes, and a spooling writer can then be started to produce the file.

See the Information Center for more information about changing spooled file attributes.

You can change the following attributes:

Parameters

Keyword Description Choices Notes
FILE Spooled file Name, *SELECT Required, Key, Positional 1
JOB Job name Single values: *
Other values: Qualified job name		 Optional, Key, Positional 2
Qualifier 1: Job name Name
Qualifier 2: User Name
Qualifier 3: Number 000000-999999
SPLNBR Spooled file number 1-999999, *ONLY, *LAST, *ANY Optional, Key, Positional 3
JOBSYSNAME Job system name Name, *ONLY, *CURRENT, *ANY Optional, Key
CRTDATE Spooled file created Single values: *ONLY, *LAST
Other values: Element list		 Optional, Key
Element 1: Creation date Date
Element 2: Creation time Time, *ONLY, *LAST
SELECT Select files for Element list Optional
Element 1: User Name, *CURRENT, *ALL
Element 2: Print device Name, *ALL, *OUTQ
Element 3: Form type Character value, *ALL, *STD
Element 4: User data Character value, *ALL
Element 5: ASP 1-32, *ALL, *ASPDEV
ASPDEV ASP device Name, *, *SYSBAS, *CURASPGRP Optional
DEV Printer Name, *SAME, *OUTQ Optional
PRTSEQ Print sequence *SAME, *NEXT Optional
FORMTYPE Form type Character value, *SAME, *STD Optional
COPIES Copies 1-255, *SAME Optional
RESTART Restart printing Integer, *SAME, *STRPAGE, *ENDPAGE, *NEXT Optional
VOL Volume Single values: *SAME, *NONE
Other values (up to 50 repetitions): Character value		 Optional
LABEL Diskette label Character value, *SAME Optional
OUTQ Output queue Single values: *SAME, *DEV
Other values: Qualified object name		 Optional
Qualifier 1: Output queue Name
Qualifier 2: Library Name, *LIBL, *CURLIB
FILESEP File separators 0-9, *SAME Optional
PAGERANGE Page range to print Element list Optional
Element 1: Starting page Integer, *SAME, *ENDPAGE
Element 2: Ending page Integer, *SAME, *END
SCHEDULE File becomes available *SAME, *JOBEND, *FILEEND, *IMMED Optional
SAVE Save file *SAME, *NO, *YES, *IMMED Optional
EXPDATE Expiration date for file Date, *SAME, *NONE, *DAYS Optional
DAYS Days until file expires 1-366 Optional
OUTPTY Output priority 1-9, *SAME, *JOB Optional
USRDTA User data Character value, *SAME Optional
ALIGN Align page *SAME, *NO, *YES Optional
PRTQLTY Print quality *SAME, *STD, *DEVD, *DRAFT, *NLQ, *FASTDRAFT Optional
FORMFEED Form feed *SAME, *DEVD, *CONT, *CUT, *AUTOCUT, *CONT2 Optional
DRAWER Source drawer 1-255, *SAME, *E1, *FORMDF Optional
FIDELITY Print fidelity *SAME, *ABSOLUTE, *CONTENT Optional
DUPLEX Print on both sides *SAME, *NO, *YES, *TUMBLE, *FORMDF Optional
MULTIUP Pages per side 1-4, *SAME Optional
PAGDFN Page definition Single values: *SAME, *NONE
Other values: Qualified object name		 Optional
Qualifier 1: Page definition Name
Qualifier 2: Library Name, *LIBL, *CURLIB
FORMDF Form definition Single values: *SAME, *NONE, *DEVD, *INLINE, *INLINED
Other values: Qualified object name		 Optional
Qualifier 1: Form definition Name
Qualifier 2: Library Name, *LIBL, *CURLIB
AFPCHARS AFP Characters Single values: *SAME, *NONE
Other values (up to 4 repetitions): Character value		 Optional
FRONTOVL Front side overlay Single values: *NONE
Other values: Element list		 Optional
Element 1: Overlay Single values: *SAME
Other values: Qualified object name
Qualifier 1: Overlay Name
Qualifier 2: Library Name, *LIBL, *CURLIB
Element 2: Offset down 0.0-57.79, *SAME
Element 3: Offset across 0.0-57.79, *SAME
BACKOVL Back side overlay Single values: *FRONTOVL, *NONE
Other values: Element list		 Optional
Element 1: Overlay Single values: *SAME
Other values: Qualified object name
Qualifier 1: Overlay Name
Qualifier 2: Library Name, *LIBL, *CURLIB
Element 2: Offset down 0.0-57.79, *SAME
Element 3: Offset across 0.0-57.79, *SAME
Element 4: Constant back *SAME, *NOCONSTANT, *CONSTANT
USRDFNOPT User defined option Single values: *SAME, *NONE
Other values (up to 4 repetitions): Character value		 Optional
USRDFNDTA User Defined Data Character value, *SAME, *NONE Optional
USRDFNOBJ User defined object Single values: *NONE, *SAME
Other values: Element list		 Optional
Element 1: Object Qualified object name
Qualifier 1: Object Name
Qualifier 2: Library Name, *LIBL, *CURLIB
Element 2: Object type *DTAARA, *DTAQ, *FILE, *PSFCFG, *USRIDX, *USRQ, *USRSPC
IPDSPASTHR IPDS pass through *SAME, *DEVD, *NO, *YES Optional
FNTRSL Font resolution for formatting *SAME, *DEVD, *SEARCH, 240, 300 Optional
EXCHTYPE Diskette file exchange type *SAME, *STD, *BASIC, *H, *I Optional
CODE Code *SAME, *EBCDIC, *ASCII Optional

Spooled file (FILE)

Specifies the spooled file that is having its attributes changed.

This is a required parameter.

*SELECT
All spooled files that meet the selection values specified on the Select files for (SELECT) parameter are changed. This value is mutually exclusive with a value specified on the Job name (JOB) parameter, Spooled file number (SPLNBR) parameter, Job system name (JOBSYSNAME) parameter, or Spooled file created (CRTDATE) parameter.
name
Specify the name of the spooled file.

Job name (JOB)

Specifies the job that created the spooled file.

Single values

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

Qualifier 1: Job name

name
Specify the name of the job that contains 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 unique number of the spooled file in the job whose attributes are being changed.

*ONLY
Only one spooled file in the job has the specified file name; therefore, the number of the spooled file is not necessary.
*LAST
If there is more than one spooled file with the specified file name the one with the highest number is the file whose attributes are changed.
*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 that matches the file name whose attributes you wish to change.

Job system name (JOBSYSNAME)

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

Select files for (SELECT)

Specifies which files have their attributes changed. This parameter allows you to process more than one file at a time. Positional values can be specified to select the files: the user that created the file, the device that the file is queued for, the form type specified, the user data tag associated with the file, or the auxiliary storage pool the file is in. Only files that meet each of the values are selected.

Element 1: User

*CURRENT
Only files created by the user running this command are selected.
*ALL
Files created by all users are selected.
name
Specify a user name. Only files created by that user name are selected.

Element 2: Print device

*ALL
Files on any device-created or user-created output queue are selected.
*OUTQ
All files on any user-created output queue are selected. A user-created output queue is any output queue that is not automatically created by a device. A user-created output queue does not generally have the same name as a device, but if it does, it does not reside in library QUSRSYS.
name
Specify a device name. Only files on the device created output queue for that device are selected. A device created output queue is one that has the same name as a device and resides in the QUSRSYS library. Unless it already exists, it will automatically be created by the system when the device is created. A device created output queue cannot be deleted.

Element 3: Form type

*ALL
Files for all form types are selected.
*STD
Only files that specify the standard form type are selected.
form-type
Specify the form type to select the file.

Element 4: User data

*ALL
Files with any user data tag specified are selected.
user-data
Specify the user data tag to select the file.

Element 5: ASP

*ALL
All files as specified in the Auxiliary Storage Pool Device (ASPDEV) parameter are selected.
*ASPDEV
Files specified in the Auxiliary Storage Pool Device (ASPDEV) parameter are selected.
1-32
Specify the auxiliary storage pool (ASP) of the files being selected.

ASP device (ASPDEV)

Specifies the auxiliary storage pool device from which spooled files are to be selected. This parameter is only valid if the ASP number (ASP) element of the SELECT parameter is *ALL or *ASPDEV.

*
Files which are found in the ASPs that are currently part of the thread's library name space are selected. This includes the system ASP (ASP 1), all defined basic user ASPs (ASPs 2-32), and if the thread has an ASP group, the primary and secondary ASPs in the thread's ASP group.
*SYSBAS
Files which are found in the system ASP (ASP 1) and all defined basic user ASPs (ASPs 2-32) are selected.
*CURASPGRP
Files which are found in the primary and secondary ASPs in the thread's ASP group are selected. If no ASP group is associated with the thread, an error will be issued.
name
Specify the name of the auxiliary storage pool device description. Files which are found in the specified primary or secondary ASP are selected. Only primary or secondary ASPs which are in the thread's ASP group may be specified. If no ASP group is associated with the thread, an error will be issued.

Printer (DEV)

Specifies the printer that is used to print the file.

*SAME
The current value does not change.
*OUTQ
The file is not assigned to a specific printer. Instead, it is placed on the output queue specified on the Output queue (OUTQ) parameter.
name
Specify the name of the printer that will print this file.

Print sequence (PRTSEQ)

Specifies whether the file is the next file on the output queue to be printed.

A value here is mutually exclusive with a value on the File becomes available (SCHEDULE) parameter or Output priority (OUTPTY) parameter.

*SAME
The file is not explicitly moved to the top. Changes to the SCHEDULE parameter or OUTPTY parameter may cause the position of the file on the output queue to change.
*NEXT
The attributes of the file (or files) are changed so that they are moved to the top of the output queue. If PRTSEQ(*NEXT) is specified when the SELECT parameter is specified, files with selection values are moved ahead of the files that do not meet the requirements. Two files that are both moved may change their relative positions on the output queue.

Form type (FORMTYPE)

Specifies the type of forms used in the printer.

*SAME
The type of forms does not change.
*STD
The standard form used at your computer system is used to produce this spooled file.
form-type
Specify the type of form you wish to use to print the output of this spooled file. If the name of the form type includes embedded blanks, you must enclose it in apostrophes.

Copies (COPIES)

Specifies, for spooled output only, the number of copies of the output being printed.

Note: If you specify a value while a file is being printed the number of copies you specify are printed in addition to the number of copies that have already been printed.

*SAME
The number of copies remains unchanged.
1-255
Specify the number of identical copies to print.

Restart printing (RESTART)

Specifies the page on which you wish to restart printing. Specifying a value while a file is being printed causes the writer to stop printing the file and restart on the specified page. If a file is not being printed, this change takes effect when the first copy is printed. After the writer repositions to the page specified by this parameter, the value for this parameter is reset to *STRPAGE.

*SAME
The page on which to restart printing does not change.
*STRPAGE
The first page specified on the Page range to print (PAGERANGE) parameter is the page on which to restart printing.
*ENDPAGE
The starting page to print is the ending page to print. Only the end page is printed.
*NEXT
The page following the last page printed is the page on which to restart printing. If printing has not been interrupted, the starting page will be used.

Note: You can determine the last page printed by using the Work with Spooled File Attributes (WRKSPLFA) command. This value will be accurate when the writer has been ended *PAGEEND or the file has been held *PAGEEND. This value may not be accurate if the writer has been ended *IMMED or the spooled file has been held *IMMED.

restart-page
Specify the page on which to restart printing.

Volume (VOL)

Specifies, for diskette output files only, one or more volume identifiers of the diskettes on which this spooled file will be written. The diskettes (volumes) must be put into the device in the same order as the identifiers are specified here; a message is sent to the system operator if the order is different.

*SAME
The volume identifiers associated with the spooled file are not changed.
*NONE
No diskette volume identifiers are specified. This file is written on the first available diskette, based on the diskette writer's current position. No volume identifier checking is performed.
volume-identifier
Specify the identifier of one or more volumes in the order in which they are inserted and used for this file. Each volume identifier contains a maximum of six characters. A blank is used as the separator character when listing multiple identifiers.

If less than ten identifiers were initially specified for the diskette unit file, a maximum of ten can be specified here. If more than ten volume names were specified when the file was first opened, only that number of volumes can be entered on the change command. The maximum number of volumes allowed in the list is 50. You can always specify at least 10 volumes.

File label (LABEL)

Specifies, for diskette output files only, the data file identifier of the data file written on diskette from this spooled file. The data file identifier is stored in a label in the volume label area of the diskette.

*SAME
The data file identifier associated with the spooled file remains the same.
data-file-identifier
Specify the identifier (8 characters maximum) to be assigned to the data file that will be written on the diskette.

Output queue (OUTQ)

Specifies the output queue to which the spooled file is moved. This parameter is used only when the specified file is moved from one output queue to another.

Note: If the spooled file is currently on an output queue for which DSPDTA(*OWNER) is specified, you must own the file or have *SPLCTL authority to move it.

Single values

*SAME
The file remains on the same output queue.
*DEV
The output queue associated with the printer device for the spooled file is used.

Qualifier 1: Output queue

name
Specify the name of the output queue to which the spooled file is moved.

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 output queue. If no current library entry exists in the library list, QGPL is used.
name
Specify the name of the library in which the output queue is located.

File separators (FILESEP)

Specifies the number of separator pages to produce at the beginning of each file so you can separate this file from the other files being printed. The identifying information included on each file separator is the file name, file number, the name of the job and number, and the user's name.

*SAME
The number of separator pages does not change.
0-9
Specify the number of pages that are used as file separators.

Page range to print (PAGERANGE)

Specifies the page range to print for each copy of the file.

Restriction This parameter will be ignored by diskette writers when printer spooled files are redirected.

Element 1: Starting page

*SAME
The starting page does not change.
*ENDPAGE
The starting page to print is the ending page to print. Only the ending page is printed.
integer
Specify the starting page to printed.

Element 2: Ending page

*SAME
The ending page does not change.
*END
The last page of the file is the ending page to print.
integer
Specify the ending page to print.

File becomes available (SCHEDULE)

Specifies when the spooled file is made available to the writer.

*SAME
The schedule attribute of the spooled file does not change.
*JOBEND
The spooled file is made available to the writer only after the entire job is completed.
*FILEEND
The spooled file is made available to the writer as soon as the file has been closed in the program.
*IMMED
The spooled output file is made available to the writer as soon as the file is opened in the program.

Save file (SAVE)

Specifies whether the spooled file is saved after it has been written to an output device.

*SAME
The save attribute of the spooled file does not change.
*NO
The spooled file data is not held on the output queue after it has been produced.
*YES
The spooled file data is held on the output queue until the file is deleted. After the file is produced, the number of copies is set to 1, and the status of the file is changed from WTR to SAV. Refer to the Release Spooled File (RLSSPLF) command for information on how to produce the spooled file again.
*IMMED
The spooled file status is changed to SAV immediately, without being produced. The spooled file data is held on the output queue until the file is deleted. If the file is currently being produced on an output device or *NEXT is specified on the Print sequence (PRTSEQ) parameter, SAVE(*YES) will be used. Refer to the Release Spooled File (RLSSPLF) command for information on how to produce the spooled file again.

Expiration date for file (EXPDATE)

Specifies the expiration date for the spooled file. The spooled file will expire at 23:59:59, system local time on the date specified.

*SAME
The expiration date does not change.
*NONE
No expiration date is specified.
*DAYS
The expiration date is to be calculated using the value specified for the Days until file expires (DAYS) parameter.
date
Specify the date after which the spooled file will be eligible for removal from the system by the Delete Expired Spooled Files (DLTEXPSPLF) command. The date must be enclosed in apostrophes if date separator characters are used in the value.

Days until file expires (DAYS)

Specifies the number of days to keep the spooled file.

Note: A value must be specified for this parameter if the Expiration date for file (EXPDATE) parameter has a value of *DAYS. If the EXPDATE parameter has a value other than *DAYS, no value is allowed for this parameter.

1-366
Specify an interval in days after which the spooled file will be 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 to the date this command is executed.

Output priority (OUTPTY)

Specifies the output priority for spooled output files that are produced by this job. The highest priority is 1 and the lowest priority is 9.

*SAME
The current value does not change.
*JOB
The output priority associated with the job that created the spooled file is used.
1-9
Specify the output priority assigned. Valid values range from 1 (highest) to 9 (lowest).

User data (USRDTA)

Specifies, for spooled output, user-specified data that identifies the file.

*SAME
The current value does not change.
character-value
Specify up to 10 characters of data assigned to the spooled file.

Align page (ALIGN)

Specifies whether to verify forms alignment on this file. This parameter is only used by printer writers which were started with *FILE specified on the Align page (ALIGN) parameter.

*SAME
The current value for forms alignment verification does not change.
*NO
The forms alignment is not verified.
*YES
The forms alignment is verified.

Print quality (PRTQLTY)

Specifies the quality of the print to be produced. Not all printers support this parameter. Refer to the Create Printer File (CRTPRTF) command to determine which printers are supported.

*SAME
The print quality associated with the spooled file remains the same.
*STD
The output is printed with standard quality.
*DRAFT
The output is printed with draft print quality.
*NLQ
The output is printed with near letter quality.
*DEVD
The output is printed with the default print quality for the printer.
*FASTDRAFT
The output is printed at a higher speed and with lower quality than it would be if you specified *DRAFT.

Form feed (FORMFEED)

Specifies the form feed attachment used for this spooled file. This parameter determines how forms are fed into the printer. Not all printers support this parameter. Refer to the Create Printer File (CRTPRTF) command to determine if this parameter is supported.

*SAME
The value does not change.
*DEVD
The forms are fed into the printer in the manner specified in the device description for that printer.
*CONT
Continuous forms are used by the printer (the tractor feed attachment must be present).
*CONT2
Continuous forms are used by the printer. The form is fed from the secondary tractor feed attachment. The secondary tractor feed attachment must be on the printer device.
*CUT
Single-cut sheets are used by the printer. Each sheet must be manually loaded. For cut sheets, the forms alignment message is not issued.
*AUTOCUT
Single-cut sheets are automatically fed into the printer (the sheet-feed attachment must be attached). For cut sheets, the forms alignment message is not issued.

Source drawer (DRAWER)

Specifies the source drawer used when single-cut sheets are fed into the printer (specified by FORMFEED(*AUTOCUT)).

*SAME
The value does not change.
*E1
The envelopes are fed from the envelope drawer on the sheet-feed paper handler.
*FORMDF
The form definition specifies the drawer from which the paper is fed.
1-255
Specify the drawer from which the paper is fed.

Print fidelity (FIDELITY)

Specifies the print fidelity that will be maintained for this file.

*SAME
The print fidelity does not change.
*ABSOLUTE
The file is printed exactly as intended. Printing is stopped if an error is encountered in the data stream.
*CONTENT
Errors in the data stream are overridden, if possible, and printing is continued.

Print on both sides (DUPLEX)

Specifies whether output is printed on one side or two sides of the paper.

*SAME
The duplex value does not change.
*NO
The output is printed on one side of the paper.
*YES
The output is printed on both sides of the paper, with the top of each printed page at the same end of the sheet of paper.
*TUMBLE
The output is printed on both sides of the paper, with the top of one printed page at the opposite end from the top of the other printed page. This is usually used for output that will be bound at the top.
*FORMDF
The duplex value specified in the form definition is used. This value is valid only with printer device types of *AFPDS, *AFPDSLINE, or *LINE.

Pages per side (MULTIUP)

Specifies, for spooled files, whether or not multiple pages of output are printed on each physical page. This parameter is used only when the printer device type is *SCS, *IPDS, or *AFPDS and the spooled file was created on an IBM i.

Note: This parameter cannot change when the value for Reduce output (REDUCE) is *NONE. You can determine the value of Reduce output by using the Work with Spooled File Attributes (WRKSPLFA) command.

*SAME
The number of pages of output printed per physical page does not change.
1
One page of output is printed for every physical page.
2
Two pages of output are printed for every physical page.
4
Four pages of output are printed for every physical page.

Page definition (PAGDFN)

Specifies the page definition to be used to format line data.

Single values

*SAME
The value does not change.
*NONE
No page definition is specified.

Because PSF requires a page definition when *LINE or *AFPDSLINE is specified, an inline page definition is built from the print file parameters and passed to PSF when *NONE is specified.

Qualifier 1: Page definition

name
Specify the name of the page definition that must exist in the library specified. Valid values range from 1 to 8 characters. Device type *AFPDSLINE, *LINE, or *USERASCII must be specified when using a page definition.

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 thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.
name
Specify the name of the library to be searched.

Form definition (FORMDF)

Specifies the form definition to use when printing the file. A form definition is a resource object that defines the characteristics of the form, including overlays, position of page data on the form, and number of copies of pages and modifications to pages. The form definition is located inline with the file being printed, or in a library.

Single values

*SAME
The value does not change.
*NONE
No form definition is used.

Because PSF requires a form definition, an inline form definition is built from the print file parameters and passed to PSF when *NONE is specified.

*DEVD
The name of the form definition is specified in the printer device description.
*INLINE
The form definition is searched for inline. If no inline form definition exists, the file will not print.
*INLINED
The form definition is searched for inline. If none exists, the *DEVD form definition is used.

Qualifier 1: Form definition

name
Specify the name of the form definition that must exist in the library specified. Valid values range from 1 to 8 characters.

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 thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.
name
Specify the name of the library to be searched.

AFP Characters (AFPCHARS)

Specifies one or more AFP characters (coded fonts) to be used with line data and a page definition.

Single values

*SAME
The value does not change.
*NONE
No AFP characters (coded fonts) specified.

Other values (up to 4 repetitions)

character-value
Specify up to four 4-byte names of coded fonts to be specified with the line data and a page definition. The 4-byte names are concatenated to X0 to identify up to four coded fonts which are to be used when TBLREFCHR is being used within the data.

Front side overlay (FRONTOVL)

Specifies the overlay object to be printed on the front side of the page, and where on the page to place the overlay.

Single values

*NONE
No overlay is to be used.

Element 1: Overlay

Single values

*SAME
The front overlay value does not change.

Qualifier 1: Overlay

name
Specify the name of the overlay.

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 overlay. If no library is specified as the current library for the job, QGPL is used.
name
Specify the name of the library where the overlay is located.

Element 2: Offset down

*SAME
The offset down does not change.
0.0-57.79
Specify the point where the overlay is placed. The offset down value specifies the vertical position. Valid values range from 0 through 57.79 if the unit of measure is centimeters, or 0 through 22.75 if the unit of measure is inches. If no value is specified, the system sets the offset to 0.

Element 3: Offset across

*SAME
The offset across does not change.
0.0-57.79
Specify the point where the overlay is placed. The offset across value specifies the horizontal position. Valid values range from 0 through 57.79 if the unit of measure is centimeters, or 0 through 22.75 if the unit of measure is inches. If no value is specified, the system sets the offset to 0.

Back side overlay (BACKOVL)

Specifies the qualified name of the object that contains both the the overlay to be printed on the back side of the page and the offset, down and across, form the point of origin used when the overlay is printed. This parameter is used only when the printer device is *SCS or *IPDS.

Single values

*FRONTOVL
The value specified for the Front side overlay (FRONTOVL) parameter is used.
*NONE
No overlay is used.

Element 1: Overlay

Single values

*SAME
The back overlay value does not change.

Qualifier 1: Overlay

name
Specify the name of the overlay.

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 overlay. If no library is specified as the current library for the job, QGPL is used.
name
Specify the name of the library where the overlay is located.

Element 2: Offset down

*SAME
The offset down does not change.
0.0-57.79
Specify the offset down from the point of origin at which to begin printing. If UOM(*CM) was specified on the CRTPRTF command when this file was created, valid values range from 0 through 57.79 and if UOM(*INCHES) was specified, valid values range from 0 through 22.57.

Element 3: Offset across

*SAME
The offset across does not change.
0.0-57.79
Specify the offset across from the point of origin at which to begin printing the overlay. If UOM(*CM) was specified on the CRTPRTF command when this file was created, valid values range from 0 through 57.79 and if UOM(*INCHES) was specified, valid values range from 0 through 22.57.

Element 4: Constant back

The constant back function allows you to print overlays on blank pages without adding blank pages to the print application. Specifying the constant back function would cause blank pages to be generated onto which the specified back overlay could be printed. The generated blank pages are called constant forms because no variable data from the user's print application is printed on the pages. This value is not changeable if MULTIUP is not 1. The constant back function is only supported for duplex printing. It is ignored when DUPLEX(*NO) is specified on the printer file.

Note: The offset down and offset across values are ignored when *CONSTANT is specified for constant back. An offset of 0.0 is assumed for these values.

*SAME
The value does not change.
*NOCONSTANT
The constant back function is not performed.
*CONSTANT
The constant back function is performed.

User Defined Option (USRDFNOPT)

Specifies, for spooled output only, one or more user-defined options to be used by user applications or user-specified programs that process spooled files. A maximum of four user-defined options can be specified.

Single values

*SAME
The value does not change.
*NONE
No user-defined options specified.

Other values (up to 4 repetitions)

character-value
Specify a user-defined option to be used by user applications or user-specified programs that process spooled files. All characters are acceptable.

User Defined Data (USRDFNDTA)

Specifies, for spooled output only, the user-defined data to be used by user applications or user-specified programs that process spooled files.

*SAME
The value does not change.
*NONE
No user-defined data is specified.
character-value
Specify user-defined data to be used by user applications or user-specified programs that process spooled files. All characters are acceptable.

User Defined Object (USRDFNOBJ)

Specifies, for spooled output only, the user-defined object to be used by user applications or user-specified programs that process spooled files.

Single values

*SAME
The value does not change.
*NONE
No user-defined object specified.

Element 1: Object

Qualifier 1: Object

name
Specify the user-defined object to be used by user applications or user-specified programs that process spooled files.

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 thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.
name
Specify the name of the library to be searched.

Element 2: Object type

object-type
The user object type can be one of the following:
*DTAARA
Data Area
*DTAQ
Data Queue
*FILE
File
*PSFCFG
PSF Configuration Object
*USRIDX
User Index
*USRQ
User Queue
*USRSPC
User Space

IPDS pass through (IPDSPASTHR)

Specifies whether IPDS (Intelligent Printer Data Stream) pass-through is done for the spooled file.

*SAME
The value does not change.
*DEVD
The value specified for IPDSPASTHR in the PSF configuration object specified for a printer device description is used. If no PSF configuration object is specified for the device, a value of *NO is used.
*NO
No IPDS pass-through is done.
*YES
Specifies that IPDS pass-through is to be done if the spooled file is eligible for IPDS pass-through.

Note: Not all SCS or IPDS spooled files are eligible for IPDS pass-through. They may contain special functions that require transform to AFPDS for correct printing. Specifying IPDS pass-through on the printer file allows only those spooled files eligible for IPDS pass-through to bypass the extra transforms. Those spooled files not eligible for IPDS pass-through will still undergo the transforms to AFPDS and back to IPDS. IPDS pass-through will not be valid for all PSF supported printers. Any printer (or attachment) that does not support resident fonts can not support IPDS pass-through. This is because the resident font references in the data stream must be mapped to host fonts which are downloaded to the printer. All IBM IPDS printers, except for the following, can be supported with IPDS pass-through: 3820, 3825, 3827, 3828, 3829, 3831, 3835, 3900-001 and any printer attached using Print Services Facility for OS/2's Distributed Print Function.

For V3R7, V4R1 and V4R2, IPDSPASTHR can be specified with the USRDFNDTA parameter in a printer file. You may continue using this support with existing printer files and PSF configuration objects by specifying IPDSPASTHR(*DEVD) in the printer file. If you specify a value of anything other than *DEVD for the IPDSPASTHR parameter, any IPDS pass-through value in the USRDFNDTA parameter is ignored.

Font resolution for formatting (FNTRSL)

Specifies the resolution PSF should use to print the spooled file when printing to a multiple resolution printer and the spooled file does not specify the font metrics and resolution with which to print the spooled file or the font is not available at that resolution.

For more information regarding the algorithm used for searching a library list for a font resource, see the Printing category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ in the section entitled "User and Device Resource Library Lists" in the chapter called "Working With PSF Configuration Objects".

*SAME
The value does not change.
*DEVD
The value specified in the FNTRSL parameter of the PSF configuration object for the device is used. If no PSF configuration object is specified for the device, a value of *SEARCH is used.
*SEARCH
Specifies to search the library list for the first occurrence of a host font with a name match. The resolution of that font is used to print the spool file. Message PQT3546 is sent to specify the resolution of the font that was selected.
240
The font resolution is 240 pels per inch.
300
The font resolution is 300 pels per inch.

Diskette file exchange type (EXCHTYPE)

Specifies, for diskette output files only, the exchange type used to write the spooled file. This parameter determines the format and record length of the data being written to diskette. If you are going to read this diskette on another type of system, make sure this format is compatible with the other system.

*SAME
The current value does not change.
*STD
The BASIC exchange format is used for a type 1 or a type 2 diskette. The H exchange type is used for a type 2D diskette.
*BASIC
The BASIC exchange type is used.
*H
The H exchange type is used.
*I
The I exchange type is used.

Code (CODE)

Specifies, for diskette output files only, the type of character code used when this spooled file is written to diskette.

*SAME
The type of character code associated with the spooled file remains the same.
*EBCDIC
The EBCDIC character code is used with this spooled file.
*ASCII
The ASCII character code is used.

Examples

Example 1: Moving a File to Another Queue 

CHGSPLFA   FILE(SALES)  JOB(000147/JONES/BILLING)  OUTQ(QPRINT2)
           FORMTYPE('1140-6')

This command moves the file named SALES (of the BILLING job numbered 000147) from the present queue to the QPRINT2 queue. It also changes the forms identifier to 1140-6, which means that this form type is used in the printer.

Example 2: Changing Number of Output Copies 

CHGSPLFA   FILE(DEPT511)  COPIES(2)  FILESEP(5)

This command changes the attributes of the spooled file DEPT511 that is produced by the submitter's job. It changes the number of output copies to 2 and specifies that five separator pages precede each copy.

Example 3: Changing Starting and Ending Pages to Print 

CHGSPLFA   FILE(DEPT481)  PAGERANGE(99 100)

This command changes the attributes of the spooled file, DEPT481. It changes the starting and ending pages that are to be printed. Now, only pages 99 and 100 of each copy of the file is printed.

Example 4: Starting on a Specific Page 

CHGSPLFA   FILE(DEPT481)  RESTART(5)

This command restarts printing spooled file DEPT481 on page 5. All of the copies that follow are printed from the specified starting page to ending page. If the file is in WTR status, the writer stops printing the current copy and restarts printing on page 5. The page specified on the RESTART parameter must be within the range specified on the PAGERANGE parameter.

Example 5: Restarting on the Next Page 

CHGSPLFA   FILE(DEPT481)  RESTART(*NEXT)

This command restarts the printing job on the page following the last page printed when the job was interrupted. All of the copies that follow are printed from the specified starting page to ending page. The file must not be in WTR status. If the file is in WTR status, this command is rejected and a message is sent to the user. RESTART(*NEXT) is not valid when a file is being processed by a writer.

Error messages

*ESCAPE Messages

CPF337E
ASP device &1 not in current ASP group for thread.
CPF337F
ASP device &1 not allowed with ASP number &2.
CPF339F
Expiration date must be today or a date in the future.
CPF2207
Not authorized to use object &1 in library &3 type *&2.
CPF33AD
Target spooled file &1 not last spooled file in ready status. Source spooled file not moved.
CPF33A6
Spooled file &1 selected by writer. Spooled file not moved.
CPF33A7
Spooled file &1 number &8 in job &5/&4/&3 not moved.
CPF33A8
Spooled file &1 specified more than once. Spooled file not moved.
CPF33A9
Target spooled file &1 changed output queue. Source spooled file not moved.
CPF33C2
Moving spooled files to the top allowed only for output queues with SEQ(*FIFO).
CPF33C3
Priority required to move spooled file exceeds user's limit.
CPF33C4
Spooled file &1 held by HLDJOB command. Spooled file not moved.
CPF33C5
Target spooled file &1 selected by writer. Source spooled file not moved.
CPF33C6
Priority required to move file exceeds user's limit.
CPF33C7
Cannot move file ahead of other users' files.
CPF33D0
Printer &1 does not exist.
CPF33D1
User &1 does not exist.
CPF33F0
Not authorized to move spooled file.
CPF3303
File &1 not found in job &5/&4/&3.
CPF3309
No files named &1 are active.
CPF3330
Necessary resource not available.
CPF3335
File &1 number &8 attributes not changed.
CPF334A
Specified user defined object &1 not valid. See previous messages.
CPF3340
More than one file with specified name found in job &5/&4/&3.
CPF3341
File &1 number &8 attributes not changed.
CPF3342
Job &5/&4/&3 not found.
CPF3343
Duplicate job names found.
CPF3344
File &1 number &8 no longer in the system.
CPF3401
Cannot change COPIES for files in PRT or SND status.
CPF3464
Not authorized to output queue &1 in library &2.
CPF3492
Not authorized to spooled file.
CPF9825
Not authorized to device &1.
CPF9833
*CURASPGRP or *ASPGRPPRI specified and thread has no ASP group.
CPFB8ED
Device description &1 not correct for operation.