 |
» |
|
|
|
Allows a qualified user to alter, print, or delete output spool file(s). (Native Mode) Syntax | |
SPOOLF has three possible execution branches. Which branch you choose depends upon whether your objective is to alter, print, ;delete. Branch 1 (;ALTER)
SPOOLF {[IDNAME=]{spoolid
(spoolid[,spoolid]. . .)}
[;ALTER][;SELEQ= {[select-eq]
^indirect_file}]
[;DEV={ldev
devclass
devname}]
[;PRI=outpri][;COPIES= numcopies]
[;SPSAVE] [;DEFER
;UNDEFER] [;SHOW] }
|
Branch 2 (;PRINT)
SPOOLF {[IDNAME=]{fileset
(fileset[,fileset]...)}
;PRINT[;DEV= {ldev
devclass
devname}]
[;PRI=outpri] [;COPIES= numcopies]
[;SPSAVE] [;DEFER
;UNDEFER] [;SHOW] }
|
Branch 3 (;DELETE)
SPOOLF {[IDNAME=]{spoolid
(spoolid[,spoolid]...)}
;DELETE[;SELEQ= {select-eq
^indirect_file}]
[;SHOW] }
|
The ;ALTER keyword is optional. It is also the default for all three SPOOLF execution branches. If you do not specify ;ALTER, ;PRINT, or ;DELETE, SPOOLF accepts only those parameters and keywords associated with the first (;ALTER) branch. Permitting ;ALTER to default has consequences: any attempt to specify parameters not belonging to the first execution branch fails. If your objective is to alter, use the first execution branch and any of its parameters. If your objective is to print, use the second execution branch and any of its parameters. If your objective is to delete, use the third execution branch and any of its parameters. Parameters | |
- spoolid
One or more spool file IDs: #Innn for input spool files or #Onnn for output spool files. These IDs are assigned by the spooling subsystem at spool file creation time. The # is optional. So is the O if you are displaying output spool files; that is, if you specify neither [#]O nor [#]I, [#]Onnn is assumed. Do not attempt to specify a qualified file name. You must enter spoolid. There is no default. The symbol @ may be used to specify all spool files. The symbol O@ may be used to specify all output spool files. The symbol I@ may be used to specify all input spool files. If @, O@, or I@ is specified, it must be the only value supplied. @, O@, and I@ are mutually exclusive.
| | | |  | NOTE: If you specify duplicate spoolids, a warning message is displayed. | | | | |
A console user or a user with SM or OP capability who specifies O@ acts on all output spool files on the system. A user with AM capability who specifies O@ acts on all output spool files created by users in the same account. All other users are limited to files they have created. - fileset
Specifies the set of files to be printed. There is no default. This positional parameter has this form:
filename[/lockword[.groupname[.accountname]]]
|
You may use wildcards. Files that are not spool files are ignored. An error is returned for each input spool file in the file set. If the file name or set is not fully qualified, the default is the user's current logon group and account. In batch mode, if any file in the set has a lockword, it must be supplied with the command; therefore, the file cannot be part of a set that contains wildcards. This restriction does not apply in interactive mode because the system prompts the user for each required lockword. In any case, if the lockword is not correctly provided, the print option on that file fails with a warning message, and the command continues on the rest of the files, if any. - select-eq
The selection equation is used as a filter on the set of spool files selected. Only spool files whose attributes satisfy all filter requirements are listed. For example, you use the following command to delete all of the output spool files to which you have access and that have less than 100 pages from user.acct:
SPOOLF O@;DELETE;SELEQ=[(OWNER=user.acct)AND(PAGES<100)]
|
Selection equations have the following format. In this display, when the expression is expanded, interpret the symbol ::= as "can be replaced by." Begin and end a selection equation with square brackets ([ and ]).
equation ::= {parm{ >
>=
<
<=
<>
= } value
(equation)
NOT equation
equation {AND
OR} equation }
|
value ::= Appropriate values per data type. parm ::= The parameter (parm) may be one of several attributes of the spool file to be altered or deleted, such as the dev parm, the FILEDES parm, and so on. The parm choices are described below. | | | | | NOTE: For string types other than DATE, such as user name, only the relational operators "=" and "<>" apply. Using any others results in an error. | | | | |
parm ::= DEV: LDEV number, device name, or device class name. You may use wildcards for device name and device class name. parm ::= FILEDES: Formal or actual file designator for the spool file. For example, if you enter the file equation below and print to it, EPOCLONG is the spool file's FILEDES.
FILE EPOCLONG;DEV=EPOC;ENV=LPLONG.ENV.SYS
PRINT MYFILE,*EPOCLONG
|
You may use wildcards. This keyword supports selection on the null string by entering FILEDES= "" (you may also use single quotes). You must include such a construct if you specifically want to select on such an attribute. Note that "" is not the same as " ". The blank is significant. parm ::= SPOOLID: Spool File identifier number in the format #Onnn or #Innn. The # is optional; but if it is used, an O or I must also be used. If it is not used, the O is also optional for output spool files; that is 123 is the same as #O123. The valid range of spoolids is 1 ≤ nnn ≤ 9,999,999. (The commas are for clarity; do not enter any commas in the actual equation.) parm ::= FORMID: Form name. You may use wildcards. (The formid is an ASCII string up to 8 characters, the first of which must be a letter.). Refer to the note accompanying the FILEDES and pages description. parm ::= STATE: READY, ACTIVE, OPEN, CREATE, PRINT, PROBLM, DELPND, SPSAVE, DEFER, XFER. parm ::= JOBNAME: Job or session name under which the spool file was created. The job name can consist of up to 8 alphanumeric characters, the first of which must be a letter. For a job input spool file, the JOBNAME shown is allocated to that job, not the job or session that streamed it. You may use wildcards. parm ::= DISP: Disposition can be SPSAVE or PURGE. Refer to the NOTE accompanying the PAGES description. parm ::=COPIES: Number of copies. Minimum is 1, maximum is 65,535. (The comma in 65,535 is for clarity; do not enter commas in the actual equation.) parm ::= PRI: Output priority. Minimum is 0, maximum is 14. Refer to the note accompanying the PAGES description. parm ::= JOBNUM: Job or session number under which the spool file was created, for example: #S257, #J329, or Jn (the "#" is optional). 1 ≤ n ≤ 16,383. (The commas are for clarity; do not enter any commas in the actual equation.) For a job input spool file, the JOBNUM shown is allocated to the job, not the job or session that streamed it. You may use some wildcards; J@ accepts all jobs, S@ accepts all sessions. J'@ and S'@ are also allowed, The apostrophe (') indicates an imported spool file or a spool file recovered during START NORECOVERY. parm ::= RECS: Number of records in the spool file. A positive integer is expected. parm ::= OWNER: The user under which the spool file was created. The format of the owner is user.account. If the account is not specified, the user's current account is assumed. You may use wildcards. For a job input spool file, the OWNER is the user logon for the job, not the job or session that streamed it. parm ::= JOBABORT: Select based on whether this is the $STDLIST of a job that aborted when an error was encountered when no CONTINUE was in effect. Valid values are TRUE and FALSE. Only "=" and "<>|" are allowed as relational operators. Refer to the note accompanying the PAGES description. parm ::= DATE: Creation date in the format mm/dd/yy or mm/dd/year. Note that the year can be in the form of yy, as in 10/10/88, or in the form of year, as in 10/10/1988; both are legal syntax for the date parameter.
- indirect_file
Specifies the name of a file containing the selection equation. It must be preceded by a caret (^). The selection equation contained in the file may not exceed 277 characters in length, including the brackets in which it must reside. There is no restriction on the indirect file code. If the record size exceeds 277, only 277 characters per record are read and a warning is issued. Backreferencing to a formal file designator is also allowed for an indirect_file name; that is, ^*filename is also allowed. Any file is accepted as an indirect_file, unless the file system returns an error from FOPEN or FREAD. There is no limit to the number of records in the indirect_file, only the total character count. Records are processed as follows: Leading and trailing blanks are stripped. If the last nonblank character is an ampersand (&), it is also stripped; otherwise, one blank is added back to the end of the record as a delimiter. The character count of the record is added to that of the records processed previously. If the total character count exceeds 277, an error is returned. If the total is less than 277, the current record is appended to previous records. This process repeats until either 277 characters have been counted or the end-of-file is detected. Records terminating with or without ampersands may be mixed as desired in the indirect file. If the resulting string is ≤277 characters, it is parsed. If the parser detects a syntax error, or if any nonblank character follows the closing bracket (]) of the select-eq, an error is returned and the select-eq is not processed.
- ALTER
The ALTER option alters the characteristics of specified output spool files. Private output spool files may be altered in a limited fashion; only the keywords PRI, DEFER, and UNDEFER are allowed. A system manager (SM) user may also specify DEV=. You cannot alter the attributes of spool files in the SPSAVE state. Because of the large amount of data buffered in the file system and the device, an output device may continue to print, making it appear as if the DEFER or DEV keyword has not had any effect. In reality, the spooler stops sending data to the device when the command is received but must wait until all buffered data has been printed before releasing the spool file. Depending on both the content of the data and the amount of buffering, this may require a significant part of a page or even several pages. - PRINT
The PRINT option copies the specified file sets to the HPSPOOL account and links the new output spool files into the spool queues for printing. It is especially useful for generating more copies of a spool file in the SPSAVE state. If the target device or class information exists in the file label extension, that device or class is used as the default. The DEV= option may be used to override this default. If there is no target device in the file label extension or the device specified is not valid, the DEV= parameter must be specified or an error message results. The default values of PRI (8) and COPIES (1) may also be overridden by user-specified parameters. You may specify ;DEFER or ;UNDEFER or ;SHOW for the target spool file that you are creating. Any changes that you apply through ;PRINT apply only to the new copy of the spool file(s) that you are creating. The changes do not apply to your original spool file(s). | | | | | NOTE: The user of the SPOOLF...;PRINT command must have nonshareable device (ND) capability. Private files cannot be printed using the PRINT option. | | | | |
- DELETE
The DELETE option purges all specified private or nonprivate spool files to which the user has access from the system. If a spool file is not in use (opened by a user, or being printed or stored), it is purged immediately. If it is in use, it is placed in DELPND state. Any spooler process printing it is notified, and printing stops at that point. Each of these files is deleted when its last user closes it, except in the case of STORE, as described below. The following command returns the spool file to its previous state from the DELPND state, if the command is issued before the file is actually deleted: SPOOLF nnn;ALTER Interruptions to the spooling process are different, depending on whether the spool file was opened by a spooler or by a user process. Spool File opened by a spooler If a spooler is printing the spool file and has not yet closed the file, entering the command SPOOLF nnn;ALTER returns the file to the PRINT state. The spooler has already been interrupted and is in the process of cleaning up by printing all data and closing the file. The cleanup process is not interrupted nor is it reversed due to the SPOOLF nnn;ALTER command. Because the spooler has been interrupted while printing a spool file, it marks the spool file as incompletely printed when it closes it. The spool file is put into the READY state, where it can be selected for printing once again. Spool File opened by a user process A user process that has opened a spool file is not interrupted by the SPOOLF nnn;DELETE command nor by the subsequent SPOOLF nnn;ALTER command. When the user process eventually closes the spool file, the file disposition used during the close determines the fate of the spool file. The spool file returns to the state it was in before the user opened it, if it continues to exist.
STORE introduces a unique situation. If a spool file is being stored when anyone (including the output spooler upon completing the last copy of the file) requests that the file be deleted, the file is placed in DELPND, as described above, but it cannot be purged by closing the file because it is still in use by STORE. Even so, the STORE command does not purge the file when it finishes with it (unless STORE's user has specified the PURGE option), because it accesses the file at a level lower than that known by the NMS file management routines. Such a file remains in the DELPND state until one of the following occurs: Someone opens it and closes it (with PURGE, SPOOLF;DELETE, FCOPY, PRINT, or an editor). STORE completes and the PURGE option was selected. It is made ready by raising the number of copies such that after the SPOOLF...;ALTER completes, the number of copies to be printed exceeds the number already printed.
The DELETE option works on either DATA input spool files in the READY state, or all output spool files in the READY, PRINT, DEFER, SPSAVE, or PROBLM state. It does not work on job $STDIN files; use the ABORTJOB command for these files. - ldev
Specifies the logical device number of the spool file's new destination device. If the spool file is in the PRINT state, it is returned to the READY state. It may immediately enter the PRINT state on ldev if all requirements are met. | | | | | NOTE: Printing of a spool file is interrupted only if the newly specified target ldev, devclass, or devname is different from the previous target ldev, devclass, or devname. | | | | |
- devclass
Specifies the new destination device class name for the spool file. If the spool file is in the PRINT state, it is returned to the READY state. It may immediately enter the PRINT state on a device in devclass if all requirements are met. The devclass parameter must begin with a letter and consist of eight or fewer alphanumeric characters. Note that MPE/iX does not allow the same name to be configured as a device class name and a device name. efer to the note accompanying ldev. - devname
Specifies the device name of the spool file's new destination device. If the spool file is in the PRINT state, it is returned to the READY state. It may immediately enter the PRINT state on devname if all requirements are met. Note that this occurs even if devname is the same as the device currently printing the file. The devname parameter must begin with a letter and consist of eight or fewer alphanumeric characters. Note that MPE/iX does not allow the same name to be configured as a device class name and a device name. Refer to the NOTE accompanying ldev. - outpri
Specifies the output priority of the designated spool files, where 0 is the lowest and 14 is the highest. Only an OP user or the console can specify an outpri of 14; other users are limited to 13. The default is 8 with the PRINT option and no change for the ALTER option. - numcopies
Specifies the number of copies of the designated spool files to be printed. The allowable range is 1 through 65,535. (The commas are for clarity; do not enter any commas in the actual command.) The default is 1 for the PRINT option and no change for the ALTER option. - SPSAVE
The SPSAVE option specifies that the selected spool files are not to be deleted after their last copy has printed. Instead they are retained in the HPSPOOL account in the SPSAVE state until deleted manually. Among other advantages, this option allows documents to be copied to user file space, to be reprinted without being reformatted, and so on. Private spool files may not be saved. | | | | | NOTE: When a file enters the SPSAVE state, its priority is set to 8 and its number of copies is set to 1. This is so that it will have the proper defaults should it be printed later. | | | | |
- DEFER
The DEFER option changes the spool file's state to DEFER. If it is currently in the PRINT state, its spooler is notified and printing stops at that point. (See the note about buffer retention under the DELETE option.) The spool file's priority remains unchanged. If this option is used with the PRINT option, the spool file is copied to OUT.HPSPOOL and linked to the spooling system, but the state of the spool file is DEFER. The spool file is not printed until a subsequent SPOOLF...;UNDEFER is entered. | | | | | NOTE: If the DEFER option is used on any file in the CREATE state (opened for original creation), the spool file only enters the DEFER state after it is completed (closed for the last time). | | | | |
- UNDEFER
The UNDEFER option changes a spool file's state from DEFER to READY and causes a spooler to start printing it if the spool file is qualified for an idle printer to print. The spool file's priority remains unchanged.
- SHOW
The SHOW option allows a user to display the results of the SPOOLF command. All other parameters are processed before the SHOW. Here is an example:
SPOOLF O@;SELEQ=[DEV=16];ALTER;PRI=8;SHOW
SPOOLID JOBNUM FILEDES PRI COPIES DEV STATE RSPFN OWNER
#O414 J5 $STDLIST 8 1 00000016 READY ALIX.MKT
#O416 J7 HOTSTUFF 8 2 00000016 READY JACK.SALES
|
Operation notes | |
Input spool file attributes cannot be altered, but input spooled DATA files can be deleted. Private spool files may be altered in a limited fashion; only the keywords PRI, DEFER, UNDEFER, and DELETE are allowed. If the user has system manager capability, DEV= is also allowed. The SPOOLF...;ALTER command can be used on problem state spool files to alter the device attribute so that the spool file becomes ready again. Most of the time, the spool file is in the problem state because the target device of the spool file is invalid. You may wish to select for printing only those spool files that do require special forms, or only those that do not require special forms. One way to do this is to use the ;FORMID parameter. Use a file equation with ;FORMID to designate one device that requires special forms and use another file equation without the parameter to designate a printer that does not require special forms. You may select files with no FORMID by specifying a null string (SELEQ=[FORMID=""]). The following example uses the LISTSPF command, but ;SELEQ works equally well with the SPOOLF command. File equations such as the ones here are used to create the designations:
FILE NOFORMID;DEV=LP,2
FILE FORMID1;DEV=LP,2;FORMID=FORMID1;FORMS=Forms Message 1.
FILE FORMID2;DEV=LP,2;FORMID=FORMID2;FORMS=Forms Message 2.
|
The priorities are set low, to defer printing. This gives you time to use the LISTSPF command to examine the state of your output spool files. Create two output files using each file equation.
listspf
SPOOLID JOBNUM FILEDES PRI COPIES DEV STATE RSPFN OWNER
#O620 S327 NOFORMID 2 1 LP READY USER.ACCT
#O621 S327 NOFORMID 2 1 LP READY USER.ACCT
#O622 S327 FORMID1 2 1 LP READY USER.ACCT
#O623 S327 FORMID1 2 1 LP READY USER.ACCT
#O624 S327 FORMID2 2 1 LP READY USER.ACCT
#O625 S327 FORMID2 2 1 LP READY USER.ACCT
INPUT SPOOL FILES OUTPUT SPOOL FILES
ACTIVE = 0; CREATE = 0; READY = 6;
OPEN = 0; DEFER = 0; SELECTED = 0;
READY = 0; DELPND = 0; SPSAVE = 0;
PRINT = 0; XFER = 0;
PROBLM = 0;
TOTAL IN FILES = 0; TOTAL OUT FILES = 6;
IN SECTORS = 0; OUT SECTORS = 96;
OUTFENCE = 6
:
|
Qualify the LISTSPF command:
listspf;seleq=[formid=formid1]
SPOOLID JOBNUM FILEDES PRI COPIES DEV STATE RSPFN OWNER
#O622 S327 FORMID1 2 1 LP READY USER.ACCT
#O623 S327 FORMID1 2 1 LP READY USER.ACCT
INPUT SPOOL FILES OUTPUT SPOOL FILES
ACTIVE = 0; CREATE = 0; READY = 2;
OPEN = 0; DEFER = 0; SELECTED = 0;
READY = 0; DELPND = 0; SPSAVE = 0;
PRINT = 0; XFER = 0;
PROBLM = 0;
TOTAL IN FILES = 0; TOTAL OUT FILES = 2;
IN SECTORS = 0; OUT SECTORS = 32;
OUTFENCE = 6
|
listspf;seleq=[formid=formid2]
SPOOLID JOBNUM FILEDES PRI COPIES DEV STATE RSPFN OWNER
#O624 S327 FORMID2 2 1 LP READY USER.ACCT
#O625 S327 FORMID2 2 1 LP READY USER.ACCT
INPUT SPOOL FILES OUTPUT SPOOL FILES
ACTIVE = 0; CREATE = 0; READY = 2;
OPEN = 0; DEFER = 0; SELECTED = 0;
READY = 0; DELPND = 0; SPSAVE = 0;
PRINT = 0; XFER = 0;
PROBLM = 0;
TOTAL IN FILES = 0; TOTAL OUT FILES = 2;
IN SECTORS = 0; OUT SECTORS = 32;
OUTFENCE = 6
listspf;seleq=[formid=""]
SPOOLID JOBNUM FILEDES PRI COPIES DEV STATE RSPFN OWNER
#O620 S327 NOFORMID 2 1 LP READY USER.ACCT
#O621 S327 NOFORMID 2 1 LP READY USER.ACCT
INPUT SPOOL FILES OUTPUT SPOOL FILES
ACTIVE = 0; CREATE = 0; READY = 2;
OPEN = 0; DEFER = 0; SELECTED = 0;
READY = 0; DELPND = 0; SPSAVE = 0;
PRINT = 0; XFER = 0;
TOTAL IN FILES = 0; TOTAL OUT FILES = 2;
IN SECTORS = 0; OUT SECTORS = 32;
OUTFENCE = 6
:
|
To print out one of the spool files that do not require special forms, do this: To print one of the spool files that do require special forms, do this: Use | |
This command may be issued from a session, a job, a program, or in Break, . The SPOOLF ...;SHOW command is breakable. The actions, however, cannot be stopped by Break. It may be executed by any user. What files the user can access with the command depends on the user's capabilities. If your need is only to list spool files, use the LISTSPF command. SPOOLF O@;SHOW, for example, must retrieve each SPFDIR entry and write it back. It locks the SPFDIR and JMAT tables for the duration of the command execution. On a system that has several thousand spool files, this can take tens of minutes. During table locking, any of a number of vital user-initiated actions are prohibited, depending upon the status of the SPFDIR and JMAT tables. Among those that may be prohibited are:
output spool file activity spooler processes attempting to obtain files to print
As the number of spool files on the system increases, this locking period may become lengthy. In extreme cases, locking may continue for tens of minutes. In addition, this use of SPOOLF defaults to ;ALTER and changes any spool file in the DELPND state back to its previous state, usually to READY or sometimes to PRINT. LISTSPF also performs table-locking, but the duration of the locking is brief (less than one minute on a system that has several thousand spoolfiles) and does not become excessive. Nor does LISTSPF produce any subtle side-effects. Finally, it generates the same display as SPOOLF O@;SHOW. Related information | |
- Commands
SPOOLER, LISTSPF, LISTFILE, ALTSPOOLFILE, DELETESPOOLFILE - Manuals
MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-60115)
|
