PrintQueue.mesa
Copyright (C) Xerox Corporation 1981, 1982, 1983, 1984, 1985, 1986. All rights reserved.
Last edited by Jacks: 14-Oct-85 9:56:16
Tim Diebert: December 22, 1986 1:11:01 pm PST
<<Print Server's internal queue interface for Spooled PrintObjects.
This queue package serves both the network interface and the internal stages of printing.
The queue consists of a fixed number of QueueObjects and a number of predefined QueueStages (or individual queues).
A single QueueObject may exist on only one of the QueueStages.
Two QueueStages have special significance: inactive is used to recycle QueueObjects, they begin life there and are returned there after a complete life cycle; tpInactive holds the (usually one) QueueObjects reserved for test pattern use (so that a test pattern can be queued even if inactive is empty).
Requeue moves QueueObject from QueueStage to QueueStage.
Next allows sequential access to QueueObjects on a given QueueStage.
Empty indicates whether a given queue is empty or not.
QueueObjects moved onto the inactive queue will have their fc, localFileName and the localFileName STRING deleted if QueueObject.deleteInactiveFile=TRUE.
QueueObjects aquired from the inactive queue will have all their fields set to default values.>>
DIRECTORY
BasicTime USING [GMT, nullGMT],
FS USING [OpenFile, nullOpenFile],
NSString USING [nullString, String],
PaperTypes USING [Paper],
PrintingTypes USING [Option],
System USING [nullID, UniversalID],
TargetPSStatus USING [Communication],
XNS USING [Address, unknownAddress];
PrintQueue: CEDAR DEFINITIONS = BEGIN
TYPES
QueueStage: TYPE = { spooling, spooledLow, spooledNormal, spooledHigh, decomposing, decomposed, marking, marked, merging, merged, forwarding, forwarded, temp, bannerOnly, retrySpooled, retryDecomposed, retransmit, hold, aborted, errors, tpSpooled, tpDecomposed, tpMerged, tpInactive, inactive};
Defines the current subdivisions of the print queue; indicates the current status of a print job; the 'inactive' queue stage is where queue objects get recycled, i.e. completed jobs are put there and the oldest one is recycled when a new job is received.
QueueObject: TYPE = MACHINE DEPENDENT RECORD [
fileID(0): FS.OpenFile ← FS.nullOpenFile, --for PrintObject
fileName(2): NSString.String ← NSString.nullString,
user defined name of object ← [bytes:@fileNameBody]
localFileName(4): NSString.String ← NSString.nullString,
of PrintObject ←[bytes:@localFileNameBody]
sender(6): NSString.String ← NSString.nullString,
client who sent object ←[bytes:@senderBody]
recipient(8): NSString.String ← NSString.nullString,
designated by sender ←[bytes:@recipientBody]
operatorMsg(10): NSString.String ← NSString.nullString,
designated by sender; used for FAX phone nos in 8.0/NSPrint 3.0 ←[bytes:@operatorMsgBody]
errorMsg(12): NSString.String ← NSString.nullString, -- ←[bytes:@errorMsgBody]
uid(14): System.UniversalID ← System.nullID, --equivalent to requestID in NSPrint
fileSize(19): LONG CARDINAL ← 0, --size in bytes of object
fileTypeHint(21): PrintFileType ← unknown,
numberCopies(22): CARDINAL ← 1,
firstPageToPrint(23): CARDINAL ← 1,
lastPageToPrint(24): CARDINAL ← LAST[CARDINAL],
paper(25): PaperTypes.Paper ← [],
twoSided(28): BOOLEAN ← FALSE,
staple(29): BOOLEAN ← FALSE,
priority(30): Priority ← normal,
releaseKey(31): CARDINAL ← LAST[CARDINAL],
fileCreateDate(32): BasicTime.GMT ← BasicTime.nullGMT, --date and time of creation of interpress file
fileQueuedDate(34): BasicTime.GMT ← BasicTime.nullGMT, --date and time file is queued on print service
startDecomposeDate(36): BasicTime.GMT ← BasicTime.nullGMT, --date and time when decomposition of file began
decomposeTime(38): LONG CARDINAL ← 0, --elapsed time in seconds for file in decomposer
markTime(40): LONG CARDINAL ← 0, --elapsed time in seconds for file in marker (or merger for feps9700)
completionDate(42): BasicTime.GMT ← BasicTime.nullGMT, --date and time processing completed on file
sourceSystemElement(44): XNS.Address ← XNS.unknownAddress, --sent from
printObjectHandle(50): PrintObjectHandle ← nilPrintObjectHandle, --for Decompose.Handle
platesDecomposed(52): CARDINAL ← 0,
currentStatus(53): ObjectStatus ← null,
priorStatus(54): ObjectStatus ← null, --for retries and banner only
bannerOnly(55): BOOLEAN ← FALSE, --TRUE for banner only jobs
deleteInactiveFile(56): BOOLEAN ← TRUE, --FALSE for Test Pattern files, which should not be deleted
fileNameBody(57): PACKED ARRAY StringBody OF CHAR ← ALL[blank],
localFileNameBody(107): PACKED ARRAY StringBody OF CHAR ← ALL[blank],
senderBody(157): PACKED ARRAY StringBody OF CHAR ← ALL[blank],
recipientBody(207): PACKED ARRAY StringBody OF CHAR ← ALL[blank],
operatorMsgBody(257): PACKED ARRAY StringBody OF CHAR ← ALL[blank],
errorMsgBody(307): PACKED ARRAY StringBody OF CHAR ← ALL[blank],
optionVariant(357): SELECT option(357): PrintingTypes.Option FROM
fax495 => [
localPrintStatus(358): FaxLocalPrintStatus ← null,
localPrintCompletionDate(359): BasicTime.GMT ← BasicTime.nullGMT,
phoneNoCount(361): [0..maxFaxPhoneNos] ← 0,
number of phone numbers provided
transmitData(362): ARRAY [0..maxFaxPhoneNos) OF FaxMitData ← ALL[]
status of each transmission attempt
],
feps9700 => [
ivFileID(358): FS.OpenFile ← FS.nullOpenFile,
interleaved Interpress file to be forwarded
targetRequestID(360): System.UniversalID ← System.nullID,
request ID returned by target PS when document is forwarded
forwardingStatus(365): TargetPSStatus.Communication ← okay
status of document forwarding (if we are at or past that stage)
],
bansheeDl, d1, fax295, fx3500, raven, unknown => [],
ENDCASE
];
QueueObjectHandle: TYPE = REF QueueObject;
NewObjectQueuedProc: TYPE = PROCEDURE; --for notification purposes (see QueueWatcher).
PrintObjectHandle: TYPE = REF ANY;
Errortype: TYPE = {invalidQueueObject, malformedQueue, nullQueueObject, multipleWatchers, unspecified};
PrintFileType: TYPE = {unknown, xeroxEncoding1, interpress10};
Priority: TYPE = {low, normal, high};
ObjectStatus: TYPE = {
restart, spooling, spooled,
decomposing, decomposed, marking, printed,
merging, merged, forwarding, forwarded,
canceledInDecomposer, canceledInMarker,
canceledInMerger, canceledInForwarder, canceledInQueue,
spoolFailure, decomposeFailure, markFailure,
mergeFailure, forwardFailure,
--for startup:-- sysRestartInSpooler, sysRestartInDecomposer,
sysRestartInMarker, sysRestartInMerger,
sysRestartInForwarder, sysRestartInQueue,
faxInProgress, faxCompleted, faxCanceled, faxAborted,
held, null};
FaxMitStatus: TYPE = {
queued, transmitting, transmitted, canceled, busy, noAnswer, transmitError, invalidPhoneNumber, localFaxFailure, purgedAtSysRestart, null};
Indicates the status of a transmit request to a specific phone number; 'queued' indicates the document has not reached the marking phase (it may be decomposing); 'null' indicates there is no transmit request; 'transmitError' means unexpected response or other retriable error.
FaxLocalPrintStatus: TYPE = {
queued, marking, printed, canceled, localFaxFailure, purgedAtSysRestart, null};
Indicates the status of local fax printing; 'queued' indicates the document has not reached the marking phase (it may be decomposing); 'null' indicates there is no local print request.
FaxMitData: TYPE = RECORD [
phoneNumber: NSString.String ← NSString.nullString, -- ←[bytes:@phoneNumberBody]
status: FaxMitStatus ← null,
retryCount: CARDINAL ← 0, --number of retries so far
queuedForRetry: BOOLEAN ← FALSE,
completionDate: BasicTime.GMT ← BasicTime.nullGMT, --date and time of successful transmit or transmit failure.
elapsedTime: LONG CARDINAL ← 0, --duration of phone call(s) in seconds.
errorCode: NSString.String ← NSString.nullString, --valid if status is transmitError or localFaxFailure
phoneNumberBody: PACKED ARRAY [0..maxPhoneNoLength) OF CHAR ← ALL[blank],
errorCodeBody: PACKED ARRAY [0..4) OF CHAR ← ALL[blank]
];
RelativePosition: TYPE = {front, back};
ObjectStringField: TYPE = {fileName, localFileName, sender, recipient, operatorMsg, errorMsg};
StatsRecord: TYPE = RECORD [
statsFrom: BasicTime.GMT ← BasicTime.nullGMT,
inconsistantAtInit: CARDINAL,
activity: QueueActivity ← ALL[0]];
StringBody: TYPE = [0..maxStringBytes);
QueueActivity: TYPE = ARRAY QueueStage OF LONG CARDINAL;
CONSTANTS
maxQueueStage: CARDINAL = 14;
maxStringBytes: CARDINAL = 100;
maxPhoneNoLength: CARDINAL = 34;
maxFaxPhoneNos: CARDINAL = 10;
nilQueueObjectHandle: QueueObjectHandle = NIL;
nilPrintObjectHandle: PrintObjectHandle = NIL;
blank: CHAR = ' ;
ERRORS
Error: ERROR [errortype: Errortype];
Queue PROCEDURES
Requeue: PROCEDURE [qOH: QueueObjectHandle ← nilQueueObjectHandle,
fromQueue: QueueStage, toQueue: QueueStage, position: RelativePosition ← back]
RETURNS [QueueObjectHandle];
If Empty then return nilQueueObjectHandle else next QueueObjectHandle (i.e., from front of fromQueue) position specifies the relative positon of the toQueue;
Errors:
Next: PROCEDURE [qOH: QueueObjectHandle ← nilQueueObjectHandle,
fromQueue: QueueStage] RETURNS [QueueObjectHandle];
If qOH=nilQueueObjectHandle then return the QueueObjectHandle at the front of the fromQueue (i.e. the oldest entry on the queue)
Else if there's a newer QueueObject on the queue than the specified QueueObject then return it's QueueObjectHandle
Else return nilQueueObjectHandle;
Queue entries are not removed from the queue and are not displaced in any way.
Errors:
Previous: PROCEDURE [qOH: QueueObjectHandle ← nilQueueObjectHandle,
fromQueue: QueueStage] RETURNS [QueueObjectHandle];
If qOH=nilQueueObjectHandle then return the QueueObjectHandle at the back of the fromQueue (i.e. the newest entry on the queue)
Else if there's an older QueueObject on the queue than the specified QueueObject then return it's QueueObjectHandle
Else return nilQueueObjectHandle;
Queue entries are not removed from the queue and are not displaced in any way.
Errors:
GetQueueObject: PROCEDURE [] RETURNS [qOH: PrintQueue.QueueObjectHandle];
Allocates space for queue object from z. The queue object is allocated as the largest variant of PrintQueue.QueueObject. Thus, the client may set the record to any of the other variants. Client in responsible for freeing the queue object.
Empty: PROCEDURE [queueStage: QueueStage] RETURNS [BOOLEAN];
Tells whether queue is empty or not.
ReserveForTestPattern: PROCEDURE [qOH: QueueObjectHandle ← nilQueueObjectHandle,
fromQueue: QueueStage ← inactive, toQueue: QueueStage ← tpInactive]
RETURNS [QueueObjectHandle];
Marks qOH (specified or returned) as a TestPattern object and Requeues it on toQueue.
Subsequent Requeues to inactive will queue it on tpInactive instead.
ReleaseAsTestPattern: PROCEDURE [qOH: QueueObjectHandle,
fromQueue: QueueStage ← tpInactive, toQueue: QueueStage ← inactive];
Removes marked qOH as a TestPattern object and Requeues it on toQueue.
Associated file is deleted.
QueueWatcher: PROCEDURE [proc: NewObjectQueuedProc, queueStage: QueueStage];
proc is called when a new QueueObject shows up on the specified queue.
Raises Error[multipleWatchers].
LocateHandle: PROCEDURE [fileSent: System.UniversalID]
RETURNS [qOH: QueueObjectHandle, queueStage: QueueStage];
If not found, return nilQueueObjectHandle.
WhereIs: PROCEDURE [qOH: QueueObjectHandle]
RETURNS [valid: BOOLEAN, queueStage: QueueStage];
If not a valid QueueObjectHandle, returns valid=FALSE else returns QueueStage.
CopyStringIn: PROCEDURE [qOH: QueueObjectHandle, fromString: NSString.String,
toField: ObjectStringField];
Utility for copying strings into QueueObject.
CopyQueueObject: PROCEDURE [fromQOH: QueueObjectHandle, toQOH: QueueObjectHandle];
Utility for copying QueueObject so that data from it can be retrieved without the QueueObject being recycled in the middle.
Initialize: PROCEDURE [directory: REF TEXT, queueEntries: CARDINAL,
currentOption: PrintingTypes.Option] RETURNS [queueSize: CARDINAL];
Called once at start time. queueEntries may change the size of the queue, if possible. Directory is on the default volume (user volume) which is set up at start time. CurrentOption tells how to initialize QueueObject variant records.
Backup: PROCEDURE[]; --Backup the print queue to the backing file.
Cleanup: PROCEDURE[];
Called when the print service is being permanently removed from a server.
Proc should release any storage allocated.
Stats: PROCEDURE RETURNS[stats: StatsRecord];
ResetStats: PROCEDURE;
END.
LOG when/who/what
****EARLIER LOG ENTRIES DELETED. See archived version from 8.0.
18-Sep-84 13:25:29 - Jacks - QueueStage: added forwarding and forwarded; QueueObject: added twoSided, staple, and new engine variants, removed paperTray variant for raven and fx3500 and PaperTray type; added Backup proc; made QueueObject MACHINE DEPENDENT; ObjectStatus: added feps9700 statuses and faxCanceled.
14-Nov-84 12:10:20 - Jacks - Second round of changes for 9.0: added targetRequestID and forwardingStatus to QueueObject; added tpMerged to QueueStage; made transmitData [0..maxFaxPhoneNos) instead of [1..maxFaxPhoneNos].
17-Jun-85 15:43:26 - Jacks - Added copyright notice; updated to PS Euclid interfaces.
25-Jun-85 13:35:56 - Jacks - Added d1 variant to QueueObject.
1-Jul-85 13:06:44 - Jacks - Added faxAborted to ObjectStatus; added queuedForRetry to QueueObject.
14-Oct-85 9:56:05 - Jacks - Added errorCode to FaxMitData.