SPOOLF


SPOOLF

     Allows a qualified user to alter output spoolfile  characteristics.

SYNTAX

     SPOOLF  {[[IDNAME=] {spoolid                  } ]
{(spoolid[,spoolid ]. . .)}

[;DEV= {ldev } ]
{devclass}
{devname }

[;PRI= outpri ]
[;COPIES=numcopies ]

[[;SELEQ=]select_eq]
{^indirect_file}
[;ALTER]
[;SPSAVE]
[{;DEFER }]
{;UNDEFER}
} |

{[IDNAME=] {fileset }
{(fileset[,fileset ]. . .)}

;PRINT [;DEV= {ldev }]
{devclass}
{devname }

[;PRI= outpri ]
[;COPIES= numcopies ]

[;SPSAVE]
[{;DEFER } ]
{;UNDEFER}
} |

{[ [IDNAME=] {spoolid } ]
{(spoolid[,spoolid ]. . .)}

;DELETE [;SELEQ=select-eq]
{^indirect_file}
}

[;SHOW]


PARAMETERS


spoolid One or more spoolfile IDs: "#Innn" for input
spoolfiles or "#Onnn" for output spoolfiles.
These IDs are assigned by the spooling
subsystem at spoolfile creation time. The
"#" is optional. So is the "O" if you are
displaying output spoolfiles; that is, if you
specify neither [#]O nor [#]I, [#]O is assumed.

o If you specify multiple spoolfiles, you
must separate them with commas and enclose
them in parentheses. For example:

SPOOLF (277,278,282);PRI=8

o The symbol "@" may be used to specify all
spoolfiles.

o The symbol "O@" may be used to specify all
output spoolfiles.

o The symbol "I@" may be used to specify all
input spoolfiles.

o If "@", "O@", or "I@" is specified, it must
be the only value supplied. "@", "O@", and
"I@" are mutually exclusive.

The default is all the spoolfiles created by
the current .. The default
SPOOLID for the console user is all the
spoolfiles on the system.

If you specify duplicate spoolids, a warning
message is displayed.

fileset Specifies the set of files to be modified.
This positional parameter has this form:

filename[/lockword[.groupname[.accountname]]]


Wildcarding is supported; however, all files
in the fileset must be output spoolfiles. If
a file is not an output spoolfile, the print
option on that file fails and the command
continues on the rest of the files, if any.

If the file name or set is not fully
qualified, the default is the user's current
logon group and account. If any file in the
set has a lockword, it must be supplied with
the command in batch mode; therefore, the
file cannot be part of a wildcarded set.
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.
There is no default.

select-eq The selection equation is used as a filter
on the set of spoolfiles selected. Only
spoolfiles whose attributes satisfy all
filter requirements will be listed.

For example, you use the following command to
print all the output spool files from
user.account that have less than 100 pages:

SPOOLF O@;SELEQ=[(OWNER=user.acct)AND (PAGES,100)]

If you are not an SM, OP, AM or console user,
the following command prints all the output
files in your default group with a priority
greater than 2 that were created before
September 30, 1994:

SPOOLF O@;SELEQ[(PRI>2) AND(DATE<09/30/94)]

You must begin and end a selection equation
with square brackets ([ and ]), and enclose
parameters and their values in parentheses. The
format of selection equations is shown below.
Read the ::= symbol as "can be replaced by".

<select-eq> ::= [<equation>]

<equation> ::= {(<equation>) }
{(NOT <equation>) }
{<equation><AND><equation> }
{<equation><OR><equation> }
{ }
{ {> } }
{ {>+} }
{ {< } }
{parm {<+} value }
{ {<>} }
{ {+ } }

AND takes precedence over OR.

The parameter (parm) may be one of the following
attributes of the spoolfile to be altered/deleted.

DEV Ldev number, device name, or device class
name. Wildcarding is supported for device
name and device class name.

FILEDES Formal file designator for the spoolfile.
For example, if you enter the file equation
below and print to it, "EPOCLONG" becomes the
spoolfile's FILEDES.

FILE EPOCLONG;DEV=EPOC;ENV=LPLONG.ENV.SYS

PRINT MYFILE,*EPOCLONG

Wildcarding is supported.

NOTE: 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 such an attribute. Note that "" is
not the same as " ". The blank is significant.

SPOOLID Spoolfile identifier number in the format
#Onnnn or #Innnn.

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
spoolfiles; that is 123 = #O123. The valid
range of spoolids is from 1 to 9999999.

PAGES Number of pages in spoolfile (if known).
A positive integer number is expected.

NOTE: This attribute does not apply to input spoolfiles

FORMID Form name. Wildcarding is supported.
(The FORMID is an ASCII string up to 8
characters, the first of which must be a
letter.) See the NOTES accompanying the
FILEDES and PAGES description.

STATE READY, ACTIVE, OPEN, CREATE, PRINT, PROBLM,
DELPND, SPSAVE, DEFER, XFER.

JOBNAME Job or session name under which the spoolfile
was created. The job name can consist of up
to 8 alphanumeric characters, the first of
which must be a letter. You may use wildcards.

For job input spoolfiles, the JOBNAME and
JOBNUM shown are those allocated to that job,
NOT those of the job or session which streamed it.

The JOBNAME=@ parameter is a different use of the
@ symbol in that it wildcards an optional field
and the omission of this optional parameter
indicates that all entries are displayed whether
or not a job name exists.

DISP Disposition, SPSAVE or PURGE. See the NOTE
accompanying the PAGES description.

COPIES Number of copies. Minimum is 1, maximum is
65535. See the NOTE accompanying the PAGES description.

PRI Output priority (minimum is 0, maximum is 14),
or input priority (minimum is 1, maximum is
14). See the NOTE accompanying the PAGES description.

JOBNUM Job or session number under which the spoolfile
was created, for example: #S257 or #J329 (the
"#" is optional). The limits are 1 and 16,383.

Limited wildcarding is supported; J@ accepts
all jobs, S@ all sessions.

RECS Number of records in the spoolfile. A positive
integer is expected.

OWNER The user under which the spoolfile was created.
The format of the OWNER is ..
If the account is not specified, the user's
current account is assumed. Wildcarding is supported.

JOBABORT Select based on whether this is the $STDLIST of a
job which aborted when an error was
encountered but no "CONTINUE" was in effect.

Valid values are "TRUE" and "FALSE". Only
"=" and "<>" are allowed as relational
operators. See the NOTE accompanying the
PAGES description.

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 509 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 509, only 509 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 non-blank 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 509, an error is returned. If the total is
less than 509, the current record is appended to
previous records. This process repeats until either
509 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 <= 509 characters, it is
parsed. If the parser detects a syntax error, or if
any non-blank character follows the closing bracket
(]) of the SELEQ, an error is returned and the SELEQ
is not processed.

ALTER The ALTER option alters the characteristics
of specified output spoolfiles. Private
output spoolfiles 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 spoolfiles in
the SPSAVE state.

PRINT The PRINT option copies the specified
filesets to the HPSPOOL account and links the
copies into the spool queues for printing.

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

The user of the SPOOLF...; PRINT command must
have ND capability. Private files cannot be
printed using the PRINT command.

DELETE The DELETE option purges all specified
private or non-private spoolfiles to which
the user has access from the system.

If a spoolfile 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 (except STORE) closes it.

The DELETE option works on either DATA input
spoolfiles in the READY state, or all output
spoolfiles 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 spoolfile's new destination device.

If the spoolfile is in the PRINT state, it is
returned to the READY state. It may
immediately enter the PRINT state on
if all requirements are met. Note that this
occurs even if LDEV is the same as the device
currently printing the file.

devclass Specifies the new destination device class name
for the spoolfile. If the spoolfile 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. Note that this occurs
even if the result is no change in output device.

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

devname Specifies the device name of the spoolfile's new
destination device. If the spoolfile 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.

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

outpri Specifies the output priority of the designated
spoolfiles, 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
spoolfiles to be printed. The allowable
range is 1 through 65535. The default is 1
for the ;PRINT option, and no change for the
;ALTER option.

SPSAVE The SPSAVE option specifies that the selected
spoolfiles are not be 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 filespace, be reprinted
without being reformatted, etc. PRIVATE
spoolfiles may not be saved.

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 spoolfile's state
to DEFER. If it is currently in the PRINT
state, its spooler is notified and printing
stops at that point. The spoolfile's
priority remains unchanged. If this option
is used with the PRINT option, the spoolfile
is copied to OUT.HPSPOOL and linked to the
spooling system, but the state of the
spoolfile is DEFER. The spoolfile is not
printed until a subsequent SPOOLF...;UNDEFER
is entered.

If the DEFER option is used on any file in the
CREATE state (opened for original creation), the
spoolfile only enters the DEFER state after it is
completed (closed for the last time).

UNDEFER The UNDEFER option changes a spoolfile's state
from DEFER to READY and causes a spooler to
start printing it if the spoolfile is
qualified for an idle printer to print. The
spoolfile'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.


OPERATION

     Input spoolfile attributes cannot be altered, but input spooled
DATA files can be deleted. Private spoolfiles 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 spoolfiles
to alter the device attribute so that the spoolfile becomes ready
again. Most of the time, the spoolfile is in the problem state
because the target device of the spoolfile is invalid.

This command may be issued from a session, job, in BREAK, or from
a program. It is not breakable. It may be executed by a user with
OP capability or by any other user meeting the capability
requirements.


EXAMPLE(S)

:SPOOLF 2;SELEQ=[DEV=16];SHOW

SPOOLID JOBNUM FILEDES PRI COPIES DEV STATE RSPFN OWNER
#414 J5 $STDLIST 8 1 16 READY ALIX.MKT
#416 J7 HOTSTUFF 8 2 16 READY JACK.SALES

ADDITIONAL INFORMATION

Commands:   SPOOLER, LISTSPF