DRAIN UR (Unit Record Device)

Authorization

Privilege Class: D

Purpose

Use DRAIN (unit record device) to stop spooling operations on specified real unit record devices.

Note: Spooling operations stop when the current file finishes processing.

Operands

UR: tells CP you want to drain a real unit record device.
ALL: drains all spooled unit record devices in the system. ALL is the default.
Printer
PRT
PUnch
PCH
Reader
RDR: drains all printers, punches, or readers.
rdev: is a real device number or list of real device numbers of the real spooled devices that you want drained. Each rdev must be a hexadecimal device address between X'0000' and X'FFFF'.
prtid: indicates that the entire command is to be passed for processing to the print server virtual machine designated by prtid. The value of prtid is provided by the print server virtual machine that will enter the DRAIN command to an AFP. The value is one to eight alphanumeric characters long. If you specify a value of four or fewer characters, prtid cannot contain only hexadecimal characters because CP then interprets prtid as rdev.

Usage Notes

Use the DRAIN command to bring the spooling system or a specified device to a controlled halt. You would normally drain all unit record devices before a system shutdown, and drain a printer before you change the contents of the UCS printer buffer.
A device is drained immediately if it is not active when the DRAIN command is issued; otherwise, it is drained when processing of the current file has completed. You can restart a drained device by issuing the START command. If you enter a START command to a device before draining has been completed, the device does not enter drained status, and it continues processing.
If you specify more than one real device number, execution of the DRAIN command terminates upon encountering an invalid real device number. None of the remaining devices are drained.
For a printer ID, the virtual machine associated with the printer ID processes the DRAIN command. Therefore, the options given on the DRAIN command must be valid for the virtual machine that is doing the processing.
When you enter the DRAIN, DRAIN PRINTER, DRAIN ALL, DRAIN UR, DRAIN UR PRINTER, or DRAIN UR ALL commands, all printers associated with all prtids are drained.

Responses

The following section lists the printer, punch, and reader responses that occur when drained status has been attained. An explanation of the various options that appear in the responses follows the last response.

Inactive Printer Responses:

For every inactive printer that attains the drained status, the first line of the response is the same. The second line varies based upon printer type.

PRT rdev DRAINED userid   CLASS  c …
 
PRT rdev FORM form {AUTO  } {SEP  } {NO3800 } [DEFFCB]  LIMIT [NONE]
                   {MANUAL} {NOSEP} {BEG3800} [FILEFCB]       [nnnnnnnnnn ]
                   {SETUP }         {ANY3800}

For 3800 printers the third line is:

PRT rdev FLASH name IMAGE imagelib CHARS name FCB {name} {HOLD } LPP nnn
                                                  {  6 } {PURGE}
                                                  {  8 }
                                                  { 10 }
                                                  { 12 }

For impact printers the third line is:

PRT rdev {NOFOLD} IMAGE imagelib CHARS chars [FCB name] [INDEX nn] LPP nnn
         {FOLD  }

The fourth line of the response for all printers is:

PRT rdev DEST {dest1} DEST {dest2   } DEST {dest3   } DEST {dest4   }
              {OFF  }      {- NONE -}      {- NONE -}      {- NONE -}

The last line of the response for 3800 printers is:

PRT rdev {AFP  } {MARK }
         {NOAFP} {NOMARK}

The last line of the response for impact printers is:

PRT rdev {AFP  }
         {NOAFP}

Inactive Punch Responses:

The following response occurs for each punch that attains the drained status:

PUN rdev DRAINED userid  CLASS c …
 
PUN rdev FORM form {AUTO  } {SEP  }  LIMIT [NONE]  (Con't)
                   {MANUAL} {NOSEP}        [nnnnnnnnnn ]
                   {SETUP }
 
Continued:
 
PUN rdev DEST {dest1} DEST {dest2  } DEST {dest3   } DEST {dest4   }
              {OFF  }      {-NONE -}      {- NONE -}      {- NONE -}

Inactive Reader Response:

RDR rdev DRAINED SYSTEM

Active Printer Responses:

For every active printer that attains the drained status, the first line of the response is the same. The second line varies according to printer type.

PRT rdev DRAINING userid   CLASS  c …
 
PRT rdev FORM form {AUTO  } {SEP  } {NO3800 } [DEFFCB]  LIMIT [NONE]
                   {MANUAL} {NOSEP} {BEG3800} [FILEBCB]       [nnnnnnnnnn ]
                   {SETUP }         {ANY3800}

For 3800 printers the third line is:

PRT rdev FLASH name IMAGE imagelib CHARS name FCB {name} {HOLD } LPP nnn
                                                  {  6 } {PURGE}
                                                  {  8 }
                                                  { 10 }
                                                  { 12 }

For impact printers the third line is:

PRT rdev {NOFOLD} IMAGE imagelib CHARS chars [FCB name] [INDEX nn] LPP nnn
         {FOLD  }

The fourth line of the response for all printers is:

PRT rdev DEST {dest1} DEST {dest2   } DEST {dest3   } DEST {dest4   }
              {OFF  }      {- NONE -}      {- NONE -}      {- NONE -}

The next line of the response for 3800 printers is:

PRT rdev {AFP  } {MARK }
         {NOAFP} {NOMARK}

The next line of the response for impact printers is:

PRT rdev {AFP  }
         {NOAFP}

The last line of the response for all printers is:

PRT rdev PRINTING userid FILE spoolid RECS {nnnn} COPY [*]nnn SEQ sss
                                           {nnnK}
                                           {nnnM}
 
Continued:
 
CL c typ

You receive a message when the system begins processing a spool file that has been sent to the real device with the MSG attribute specified with the SPOOL command.

Note: CP itself does not provide a response for prtids. The virtual machine associated with prtid provides the response.

Active Punch Responses:

The following response occurs for each punch that attains the drained status:

PUN rdev DRAINING userid CLASS c …
 
PUN rdev FORM form {AUTO  } {SEP  } LIMIT [NONE] (Con't)
                   {MANUAL} {NOSEP}       [nnnnnnnnnn ]
                   {SETUP }
 
Continued:
 
PUN rdev DEST {dest1} DEST {dest2  } DEST {dest3   } DEST {dest4   } (Con't)
              {OFF  }      {-NONE -}      {- NONE -}      {- NONE -}
 
Continued:
 
PUN rdev PUNCHING userid FILE spoolid RECS {nnnn} COPY [*]nnn SEQ sss
                                           {nnnK}
                                           {nnnM}
 
Continued:
 
CL c typ

Active Reader Response:

RDR rdev DRAINING SYSTEM

Explanation of Responses:

All the various options used in the preceding response section are detailed below.

PRT
PUN
RDR: is the device that you drained or are draining.
rdev: is the real device number of the drained or draining device.
CLASS c: are those output classes that the drained or draining device was servicing. One to eight classes are displayed for each printer or punch device that was drained or is draining.
FORM form: changes the form name of a spool file. form is one to eight characters long.
AUTO: indicates that the operator wants CP to schedule forms output. The currently active form is processed first. When all files with the current form have been printed or punched, CP automatically selects a new form for the device. The operator receives a message to change forms, and the output device is idle. The operator can then put in the new form and press the START button (or enter the START command) to print files with the new form.
MANUAL: indicates that the operator schedules output forms. Only spool files with the form currently active on the device are processed. When the last spool file with the current form is printed or punched, the output device stops. The operator can then schedule a new form by issuing a START command with the FORM option.
SETUP: indicates that the operator wants CP to print a page so that forms alignment can be verified. (This option is valid only for impact printers.) The operator gets a message indicating that the form should be set up. When the form has been set up, the operator should press the STOP button, then the START button. An alignment page is then printed. It is the first page of the file, with letters replaced with Xs and the numbers replaced with 9s. Each time the operator presses the STOP or START buttons after a full alignment page is printed, another alignment page is printed. When the forms are aligned, you should enter the START command for the device. The printer then returns to its previous mode (AUTO or MANUAL), and the file prints in its entirety.

If neither MANUAL, AUTO, nor SETUP is specified and the printer is currently in SETUP mode, it returns to the previous mode, AUTO or MANUAL. If no START command has been issued with the MANUAL, AUTO, or SETUP options since a system cold start, the default is MANUAL.

SEP
NOSEP: indicates the current separator status.
LIMIT NONE
LIMIT nnnnnnnnnn: indicates the current value for LIMIT, which was set by the CP START command or the system configuration file.
NO3800
BEG3800
ANY3800: specifies the restrictions on the 3800 load CCWs in effect after the device is started again.
DEFFCB
FILEFCB: specifies the FCB that is currently in use. DEFFCB means that the default that was loaded in the printer is used. FILEFCB means that file FCBs are sent to the real printer.
rdev: is the real 3800 printer or list of 3800 printer numbers that you want drained.
FLASH name: signifies that a form overlay contained in the 3800 printer is to be superimposed (or flashed) onto the specified number of copies of the output. The name, to be one to four characters long, identifies the forms overlay to be used in the projection.
IMAGE imagelib: specifies the name of the system image library file that contains the load images (character sets), FCBs, graphic character modifications, or copy modifications that are to be used for printing files and separators. imagelib may be from one to eight characters long, and must be an existing image library file.
FCB name: is the name of the forms control buffer (FCB) module to be used by the printer in the vertical formatting of a page.
Note: This does not appear for 1403-type printers.
CHARS name: specifies the name of the default character set used when spool files are being printed that do not specify a character set.
HOLD: prevents the printing of a file by placing it in a user hold status.
PURGE: closes and purges the spool file on the specified 3800 printer, regardless of the cont, keep, and hold setting for the device.

LPP nnn: indicates the lines per page that the printer is using for the generation of separator pages. The LPP value is determined from the FCB loaded on the printer.
If no FCB has been loaded to the printer, the LPP will appear as zero. Since the FCB is actually loaded when a file is printed, it is possible that the LPP will appear as zero or the LPP value for the prior FCB after the START command with the FCB operand is issued.

Note: If the number of lines per page derived from the FCB data is less than 30 or greater than 255, the LPP for that printer will be set to a default value of 66 for impact printers, or 60 for 3800 printers.
NOFOLD
FOLD: indicates whether lowercase characters are being translated (folded) into uppercase for printing.
CHARS chars: indicates the character set being used by the printer.
INDEX nn: indicates the character position on the page at which to begin printing.

PRT

PUN

indicates the type of device on which the file is being processed.

rdev

is the real device number.

DEST dest

is the destination value. dest is a one- to eight-character value. OFF is the default destination for the device for the first of four destination values. The designation - NONE - is shown for other destination values that have not been set.

AFP

NOAFP

specifies whether the printer is to process files with advanced function printer (AFP) characteristics.

MARK

NOMARK

indicates whether 3800 separator trailer pages are being marked with separator bars.

userid

is the name of the spool file owner.

FILE spoolid

is the spool file number.

RECS nnnn

RECS nnnK

RECS nnnM

is the number of logical records in the spool file. If the number is greater than 9999, the number is shown as nnnK, where K represents the number of lines rounded to the nearest 1000 records. If the number is greater than 999499, the number is shown as nnnM, where M represents the number of lines rounded to the nearest million.

COPY nnn

COPY * nnn

specifies the number of file copies you want printed or punched when the file is produced.

When the optional asterisk (*) is specified, the 3800 printer prints each page from the spooled output files nnn times before going on to the next page.

If a file is not spooled to the 3800 printer, the function performed by specifying the asterisk (*) is ignored, and duplication occurs normally.

SEQ sss

is the sequence number for the file on the printer or punch.

CL c

is the spool file class.

typ

shows the device type that originally produced the spool file. The type can be RDR, PRT, PUN, CON, DMP, or SYS.

Messages

HCP003E Invalid option - {option|command contains extra option(s) starting with option}
HCP007E Invalid userid - userid
HCP020E Userid missing or invalid
HCP021E A real device number was not supplied or it is invalid.
HCP031E Buffer missing or invalid; [FCB too long|extended FCB not supported]
HCP036E Index missing or invalid
HCP040E Device {rdev|vdev|ldev} does not exist
HCP043E Buffer buffer does not exist
HCP046E type rdev offline
HCP140E type {rdev|ldev} attached to userid
HCP148E Printer rdev buffer load name failed
HCP413E Command processing cannot complete due to a spool paging error.
HCP418E {rdev|vdev} is not a spooled device.
HCP422E The same option was specified twice.
HCP423E The function requested is incompatible with a previously specified operand.
HCP475I Fatal I/O error trying to read directory from volid [for user userid]
HCP1001E An operand is missing for option.
HCP1013E An invalid operand was supplied for option - operand
HCP1552E More than {4|8} operands were specified for the {CHARS|CLASS} option.
HCP2500E Image library libname could not be found [for printer rdev].
HCP2501E A spool paging I/O error occurred while reading image [library] imagename on printer rdev
HCP6005E Option option is not supported by z/VM®.
HCP6525E Authorization request failed.