[Cyan]<CedarPS>PSCommand>PSCommand.mesa!4

PSCommand.mesa

Last edited by Jacks 14-Oct-85 9:58:13

Tim Diebert: December 15, 1986 9:08:07 am PST

<<This interface is intended to be the focal point for client interaction with the Print Service. The initialization procedure is contained in another interface, since it is subject to change more often that PSCommand.>>

DIRECTORY

BasicTime USING [GMT, nullGMT],

BulkDataP0V1 USING [Source],

CHNameP2V0 USING [Name],

IO USING [STREAM],

NSString USING [String],

PaperHandling USING [

Banner, PaperFeed, PaperStacking, PaperSupply, PrintOrder, Registration],

PaperTypes USING [Paper, PaperSize],

PrintingP4V3 USING [InterpressMasterStatus],

PrintingTypes USING [Option],

PSAsyncMsg USING [Proc],

PSState USING [CurrentActivity, StateHandle, TraceLevel],

System USING [nullID, UniversalID],

TargetPSStatus USING [Communication, Current, Properties],

XNS USING [Address, unknownAddress];

PSCommand: CEDAR DEFINITIONS = BEGIN

OPEN CHName: CHNameP2V0, NSDataStream: BulkDataP0V1;

DECLARATIONS FOR QUEUE/DOCUMENT OPERATIONS:

Priority: TYPE = {low, normal, high};

<<DocumentParameterRecord contains all the items found in NSPrint PrintAttributes and PrintOptions and must be included with a document when it is queued:>>

DocumentParameters: TYPE = REF DocumentParameterRecord;

DocumentParameterRecord: TYPE = RECORD [

name: NSString.String ← NIL,

createDate: BasicTime.GMT ← BasicTime.nullGMT,

size: LONG CARDINAL ← 0, --document size in bytes

senderName: NSString.String ← NIL,

recipientName: NSString.String ← NIL,

message: NSString.String ← NIL,

copyCount: CARDINAL ← 1,

firstPageToPrint: CARDINAL ← 1,

lastPageToPrint: CARDINAL ← LAST[CARDINAL],

paper: PaperTypes.Paper ← [],

staple: BOOLEAN ← FALSE,

twoSided: BOOLEAN ← FALSE,

priority: Priority ← normal,

releaseKey: CARDINAL ← LAST[CARDINAL]

];

<<DocumentID uniquely identifies all documents submitted to the print service.>>

DocumentID: TYPE = System.UniversalID;

nullDocumentID: DocumentID = System.nullID;

<<DocumentStatus provides two levels of status information:

(1) the simple PrintingP4V3 status and

(2) the more specific internal print queue status. >>

DocumentStatus: TYPE = RECORD [

var: SELECT simple: SimpleDocStatus FROM

pending => [specific: SpecificDocStatus],

inProgress => [specific: SpecificDocStatus],

completed => [specific: SpecificDocStatus],

completedWithWarning => [specific: SpecificDocStatus],

unknown => [],

rejected => [specific: SpecificDocStatus],

aborted => [specific: SpecificDocStatus],

canceled => [specific: SpecificDocStatus],

held => [],

ENDCASE

];

<<SimpleDocStatus defines the high level document status:>>

SimpleDocStatus: TYPE = PrintingP4V3.InterpressMasterStatus;

pending(0), inProgress(1), completed(2), completedWithWarning(3), unknown(4), rejected(5), aborted(6), canceled(7), held(8) };

<<SpecificDocStatus defines the more specific document status:>>

SpecificDocStatus: TYPE = { --Equivalent to PrintQueue.ObjectStatus.

Normal statuses:

spooling, spooled, --being received; received and queued for decomposer

restart, --requeued for decomposer (at system restart or StopPrinting call)

decomposing, --being decomposed

decomposed, --decomposed and queued for marker

marking, printed, --being marked; already printed

forwarding, --being forwarded to target PS****REMOTE9700 STATUS ONLY!

forwarded, --already forwarded to target PS****REMOTE9700 STATUS ONLY!

Canceled at specified point (by calling CancelDocument):

canceledInDecomposer, --canceled with status = decomposing

canceledInMarker, --canceled with status = marking

canceledInForwarder, --canceled with status = forwarding****REMOTE9700 ONLY!

canceledInQueue, --canceled with status = spooled, restart, decomposed, or merged

Document aborted at specified point due to system error or limitation or other problem:

spoolFailure, --could not be received

decomposeFailure, --could not be decomposed

markFailure, --could not be marked

forwardFailure, --could not be forwarded****REMOTE9700 STATUS ONLY!

Document found at specified point in processing at system restart and was aborted:

sysRestartInSpooler,--found with status = spooling

sysRestartInDecomposer,--found with status = decomposing

sysRestartInMarker, --found with status = marking

sysRestartInForwarder,--found with status = forwarding****REMOTE9700 STATUS ONLY!

sysRestartInQueue, --found with status = decomposed or merged

Document was sent to a Fax495 Print Service:

faxStatus, --Document is currently in progress or completed; specific document status is contained in the optionDependent field of the DocumentAttrRecord****FAX495 STATUS ONLY!

null};

<<FaxTransmitStatus indicates the status of a transmit request to a specific fax phone number;

'queued' indicates the document is not yet ready to be transmitted. (Equivalent to fax transmit status maintained by print queue.)>>

FaxTransmitStatus: TYPE = {queued, transmitting, transmitted, canceled, busy, noAnswer, transmitError, invalidPhoneNumber, localFaxFailure, purgedAtSysRestart, null};

<<FaxLocalPrintStatus indicates the status of a local fax print request;

'queued' indicates the document is not yet ready to print;

'null' indicates there was no local print request for the document.

(Equivalent to fax local print status maintained by print queue.)>>

FaxLocalPrintStatus: TYPE = {queued, marking, printed, canceled, localFaxFailure, purgedAtSysRestart, null};

FaxTransmitData: TYPE = RECORD [

phoneNumber: NSString.String ← NIL,

transmit: FaxTransmitStatus ← null,

retryCount: CARDINAL ← 0, --number of retries so far

willRetry: BOOLEAN ← FALSE, --TRUE if we'll retry again

completionDate: BasicTime.GMT ← BasicTime.nullGMT,

phoneCallElapsedTime: LONG CARDINAL ← 0, --in seconds

errorCode: NSString.String ← NIL --valid if FaxTransmitStatus is transmitError or localFaxFailure

];

Fax495DocumentStatus: TYPE = RECORD [

localPrint: FaxLocalPrintStatus ← null,

localPrintCompletionDate: BasicTime.GMT ← BasicTime.nullGMT,

phoneNumberCount: CARDINAL ← 0,

transmitData: LONG DESCRIPTOR FOR ARRAY OF FaxTransmitData ← DESCRIPTOR[NIL, 0] --there's an array entry for every phone number

];

<<A DocumentFilter is passed to ListDocuments indicating the type of documents to list (any combination of id/name/sender/status).>>

DocumentFilter: TYPE = RECORD [

id: DocumentID ← nullDocumentID,

name: NSString.String ← NIL,

sender: NSString.String ← NIL,

status: PACKED ARRAY SimpleDocStatus OF BOOLEAN ← ALL[TRUE]

];

noDocuments: DocumentFilter = [nullDocumentID, NIL, NIL, ALL[FALSE]];

allDocuments: DocumentFilter = [nullDocumentID, NIL, NIL, ALL[TRUE]];

<<DocumentAttrRecord defines the information returned when a document is listed.>>

DocumentAttributes: TYPE = REF DocumentAttrRecord;

DocumentAttrRecord: TYPE = RECORD [

id: DocumentID ← nullDocumentID,

name, sender, recipient, errorMessage: NSString.String ← NIL,

status: DocumentStatus ← [unknown[]],

priority: Priority ← normal,

sourceSystemElement: XNS.Address ← XNS.unknownAddress,

sizeInBytes: LONG CARDINAL ← 0,

pagesDecomposed: CARDINAL ← 0,

numberOfCopies: CARDINAL ← 1,

dateReceived: BasicTime.GMT ← BasicTime.nullGMT,

secondsInFormatter: LONG CARDINAL ← 0,

completionDate: BasicTime.GMT ← BasicTime.nullGMT,

optionDependent: SELECT printingOption: PrintingTypes.Option FROM

fax495 => [faxStatus: Fax495DocumentStatus ← []],

bansheeDl, d1, fax295, feps9700, fx3500, raven, unknown => [],

ENDCASE

];

<<DocumentProc is an enumeration procedure which the client provides to ListDocuments.>>

DocumentProc: TYPE = PROCEDURE [document: DocumentAttributes]
RETURNS [continue: BOOLEAN ← TRUE];

DECLARATIONS FOR FONT OPERATIONS:

FontType: TYPE = {cdFont, any};

<<FontProc is an enumeration procedure which the client provides to ListFonts.>>

FontProc: TYPE = PROCEDURE [type: FontType, packageName: NSString.String,
sizeInBytes: LONG CARDINAL, createDate: BasicTime.GMT]
RETURNS [continue: BOOLEAN ← TRUE];

<<FontFilter allows clients of ListFonts to specify the type of fonts and/or name of fonts to list. Two wildcard characters are defined for the packageName: * (asterisk) and # (pound sign). The * character matches zero or more characters; # matches any single character. Wildcard characters meant to be interpreted literally within the pattern must be escaped by quoting them with ' (apostrophe).>>

FontFilter: TYPE = RECORD [type: FontType ← any, packageName: NSString.String ← NIL];

allFontPackages: FontFilter = [any, NIL];

DECLARATIONS FOR FILE OPERATIONS:

FileType: TYPE = {testPattern, any};

<<FileProc is an enumeration procedure which the client provides to ListFiles.>>

FileProc: TYPE = PROCEDURE [type: FileType, name: NSString.String,
sizeInBytes: LONG CARDINAL, createDate: BasicTime.GMT]
RETURNS [continue: BOOLEAN ← TRUE];

<<FileFilter allows clients of ListFiles to specify the type of files and/or name of files to list. Two wildcard characters are defined for the packageName: * (asterisk) and # (pound sign). The * character matches zero or more characters; # matches any single character. Wildcard characters meant to be interpreted literally within the pattern must be escaped by quoting them with ' (apostrophe).>>

FileFilter: TYPE = RECORD [type: FileType ← any, name: NSString.String ← NIL];

allFiles: FileFilter = [any, NIL];

<<Declarations concerning options for printing a file:>>

PaperTray: TYPE = {bottom, top, default};

maxPhoneNoLength: CARDINAL = 34;

PrintFileOptions: TYPE = RECORD [var: SELECT printingOption: PrintingTypes.Option FROM

fax295 => [paperSize: PaperTypes.PaperSize],

fax495 => [localPrint: BOOLEAN ← TRUE,

transmit: BOOLEAN ← FALSE,

phoneNumber: NSString.String ← NIL,

paperSize: PaperTypes.PaperSize],

fx3500 => [tray: PaperTray ← default],

raven => [tray: PaperTray ← default, stacking: PaperHandling.PaperStacking ← aligned],

bansheeDl, d1, feps9700, unknown => [],

ENDCASE

];

DECLARATIONS FOR SET PARAMETER OPERATIONS:

FaxTransmissionRetryReason: TYPE = {noConnectionMade, transmitError, always};

<<TraceParameters specifies the level of tracing for each major function of the Print Service.>>

TraceParameters: TYPE = RECORD [spooler: PSState.TraceLevel, decomposer: PSState.TraceLevel,
marker: PSState.TraceLevel];

ERRORS:

<<The client should make sure a command is valid before calling a procedure in the PSCommand interface, otherwise an Error is raised.>>

ErrorType: TYPE = {

abortedByClient, --aborted; operation may or may not have completed

disallowedInCurrentMode, --disallowed because the PS is not in normal operation mode (e.g. PS is in repair mode or font loading mode)

documentNotFound, --operation on a document which doesn't exist at PS

documentInProgress, --disallowed because a document is in progress

engineBusy, --operation depends on engine being idle

enqueue, --spooling error raised by Enqueue

fileNotFound, --operation on a file which doesn't exist at PS

incompatiblePrintingOption, --operation not valid with current printing option

insufficientSpace, --insufficient resources for operation

invalidPhoneNumber, --syntax of phone number is invalid

invalidParameters, --bad or unknown parameters supplied to operation

parameterOptionNotAvailable, --parameter option invalid for current printing option

systemError, --bug in implementation

targetPS, --problem communicating with target print service

targetPSNotSet, --target print service must be specified prior to operation

undefined --some undefined problem (and implementation-dependent) occurred

};

EnqueueError: TYPE = {busySpooling, masterTooLarge, mediumUnavailable, spoolingDisabled, spoolingQueueFull, tooManyClients, other};

UndefinedError: TYPE = CARDINAL;

Error: ERROR [problem: ErrorRecord];

ErrorRecord: TYPE = RECORD [

SELECT errorType: ErrorType FROM

abortedByClient, disallowedInCurrentMode,

documentNotFound, documentInProgress, engineBusy => [],

enqueue => [what: EnqueueError],

fileNotFound, incompatiblePrintingOption,

insufficientSpace, invalidPhoneNumber,

invalidParameters, parameterOptionNotAvailable,

systemError => [],

targetPS => [what: TargetPSStatus.Communication],

targetPSNotSet => [],

undefined => [what: UndefinedError],

ENDCASE

];

************************

PROCEDURES:

************************

PRINT SERVICE CONTROL OPERATIONS:

Start: PROCEDURE;

<<Export remote courier program; allow Print Service to queue and process documents.>>

Stop: PROCEDURE;

<<Unexport remote courier program; don't allow Print Service to queue or process documents.>>

StartPrinting: PROCEDURE [user: CHName.Name];

<<Allow processing of documents; no effect on queuing.>>

StopPrinting: PROCEDURE [user: CHName.Name, reason: NSString.String ← NIL];

<<Disallow processing of documents; documents in progress are requeued; no effect of queuing.>>

StartQueuing: PROCEDURE [user: CHName.Name];

<<Allow queuing of documents; on effect on printing.>>

StopQueuing: PROCEDURE [user: CHName.Name, reason: NSString.String ← NIL];

<<Disallow queuing of documents; no effect on printing.>>

ResetStatistics: PROCEDURE;

<<Reset the Print Service statistics counters to zero.>>

PRINT SERVICE STATUS:

GetPrintServiceStatus: PROCEDURE RETURNS [PSState.StateHandle];

<<Returns a readonly handle to the Print Service state record, which contains relatively static information retained across system restarts.>>

GetPrintServiceActivity: PROCEDURE RETURNS [PSState.CurrentActivity];

<<Returns a record of information detailing the current activity at the Print Service (this information changes constantly).>>

GetTargetPSStatus: PROCEDURE RETURNS [activity: TargetPSStatus.Current,
properties: TargetPSStatus.Properties];

<<Remote9700 ONLY: makes remote procedure calls to the Target Print Service and returns information about current target activity and properties.

Errors: PSCommand.Error[incompatiblePrintingOption, targetPSNotSet, targetPS]>>

QUEUE/DOCUMENT OPERATIONS:

Enqueue: PROCEDURE [document: NSDataStream.Source, parameters: DocumentParameters]
RETURNS [documentID: PSCommand.DocumentID];

<<Enqueue places a document on the spooled queue.

Errors: PSCommand.Error[enqueue, insufficientSpace, invalidParameters]

ListDocuments: PROCEDURE [proc: DocumentProc, filter: DocumentFilter ← allDocuments];

<<ListDocuments calls the proc for every document which qualifies using the specified filter (may filter on id, name, sender and/or status).

It passes the document attributes. If proc returns FALSE listing is aborted. Default is to list all documents in the queue.>>

CancelDocument: PROCEDURE [documentID: DocumentID] RETURNS [status: DocumentStatus];

<<CancelDocument cancels the specified document and returns its current status.

Errors: PSCommand.Error[documentNotFound]>>

FONT OPERATIONS:

ListFonts: PROCEDURE [proc: FontProc, filter: FontFilter ← allFontPackages];

<<ListFonts calls the proc for every font package specified by the filter (may filter on font type and/or package name). If proc returns FALSE listing is aborted. Default is to list all fonts.>>

InstallFont: PROCEDURE [type: FontType, packageName: NSString.String,
createDate: BasicTime.GMT, data: IO.STREAM,
packageSizeHintInBytes: LONG CARDINAL ← 0];

<<InstallFont creates or overwrites the specified font package with data from datastream. "packageSizeHintInBytes", if specified, gives the package size so space for the font can be allocated more efficiently.

Errors: PSCommand.Error[disallowedInCurrentMode, abortedByClient,insufficientSpace, invalidParameters, systemError]>>

DeleteFont: PROCEDURE [packageName: NSString.String];

<<DeleteFont deletes the named font package.

Errors: PSCommand.Error[disallowedInCurrentMode, fileNotFound, invalidParameters]>>

FILE OPERATIONS (for test patterns, etc.):

ListFiles: PROCEDURE [proc: FileProc, filter: FileFilter ← allFiles];

<<ListFiles calls the proc for every file specified by the filter (may filter on file type and/or file name). If proc returns FALSE listing is aborted. Default is to list all files.>>

InstallFile: PROCEDURE [type: FileType, name: NSString.String, createDate: BasicTime.GMT, data: IO.STREAM, fileSizeHintInBytes: LONG CARDINAL ← 0];

<<InstallFile creates or overwrites the named file with data from datastream. "fileSizeHintInBytes", if specified, gives the file size so space can be allocated more efficiently.

Errors: PSCommand.Error[disallowedInCurrentMode, abortedByClient,insufficientSpace, invalidParameters, systemError]>>

DeleteFile: PROCEDURE [name: NSString.String];

<<DeleteFile deletes the named file.

Errors: PSCommand.Error[disallowedInCurrentMode, fileNotFound, invalidParameters]>>

PrintFile: PROCEDURE [fileName, senderName: NSString.String, copies: CARDINAL,
options: PrintFileOptions];

<<PrintFile queues the named file for printing.

Errors: PSCommand.Error[incompatiblePrintingOption, fileNotFound, optionNotAvailable, invalidPhoneNumber, systemError]>>

SET PARAMETER OPERATIONS:

Apply to all printing options supported:

SetBanner: PROCEDURE [banner: PaperHandling.Banner];

<<Errors: PSCommand.Error[incompatiblePrintingOption]>>

SetPrintOrder: PROCEDURE [printOrder: PaperHandling.PrintOrder];

Apply to certain printing options supported:

SetMultipleCopies: PROCEDURE [multLocalCopiesAllowed, multRemoteCopiesAllowed: BOOL];

<<Fax495 only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

SetPaperFeed: PROCEDURE [paperFeed: PaperHandling.PaperFeed];

<<Raven and FX3500 only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

SetPaperStacking: PROCEDURE [paperStacking: PaperHandling.PaperStacking];

<<Raven only

Errors: PSCommand.Error[incompatiblePrintingOption, optionNotAvailable]>>

SetPaperSupply: PROCEDURE [paperSupply: PaperHandling.PaperSupply];

<<Raven, Fax495 and Fax295 only

Errors: PSCommand.Error[incompatiblePrintingOption, optionNotAvailable]>>

SetRegistration: PROCEDURE [registration: PaperHandling.Registration];

<<D1, Raven and FX3500 only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

SetTargetPrintService: PROCEDURE [address: XNS.Address, name: NSString.String ← NIL]; --Remote9700 only; address required, name is optional

<<Errors: PSCommand.Error[incompatiblePrintingOption]>>

SetTransmissionResolution: PROCEDURE [fineResolutionSupported: BOOLEAN];

<<Fax495 only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

SetTransmissionRetries: PROCEDURE [retries: CARDINAL, delayInSeconds: LONG CARDINAL, reason: FaxTransmissionRetryReason ← always];

<<Fax495 only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

ENGINE SPECIFIC OPERATIONS:

StartDiagnosticMode: PROCEDURE;

<<Raven, D1, FX3500 and Banshee only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

StartRepairMode: PROCEDURE;

<<Raven, D1, FX3500 and Banshee only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

PutPrinterDisplay: PROCEDURE [leftChar, rightChar: CHARACTER ← 0C];

<<FX3500 only: displays valid chars on printer display

Errors: PSCommand.Error[incompatiblePrintingOption, disallowedInCurrentMode]>>

GetPrinterDisplay: PROCEDURE RETURNS [leftChar, rightChar: CHARACTER ← 0C];

<<FX3500 only: gets chars from printer display

Errors: PSCommand.Error[incompatiblePrintingOption, disallowedInCurrentMode]>>

ShutDownEngine: PROCEDURE;

<<Raven B2 versions only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

WakeUpEngine: PROCEDURE;

<<Raven B2 versions only

Errors: PSCommand.Error[incompatiblePrintingOption]>>

ASYNCHRONOUS MESSAGE HANDLING OPERATIONS:

RegisterAsyncMessageProc: PROCEDURE [proc: PSAsyncMsg.Proc];

<<Official asynchronous messages (i.e. messages in message file) will be passed to all registered aynchronous message procs.>>

SetTrace: PROCEDURE [traceParms: TraceParameters];

<<Controls asynchronous display of low-level status and event information; no multi-national support provided as messages are not in message file.>>

END. --PSCommand

LOG

25-Aug-83 9:34:58 - Jacks - Created as part of PSCommand rework; this is the public interface to the print service commands.

22-Sep-83 13:39:47 - Jacks - Changed PSState.EngineType to PrinterTypes.Engine.

25-Oct-83 11:27:15 - Jacks - Added abortedByClient error type.

11-Nov-83 10:15:46 - Jacks - Changed references to PSState for paper handling defs to PaperHandling def; removed PaperSupply and PaperFeed definitions and put them in PaperHandling.

18-Nov-83 14:47:10 - Jacks - Added return var 'status' to CancelDocument.

28-Nov-83 15:05:39 - Jacks - Added insufficientSpace error type.

6-Dec-83 10:16:38 - Jacks - Added RegisterAsyncMessageProc.

14-Dec-83 14:55:40 - Jacks - Added SetFaxMultipleCopies and SetFaxRetries; added activity parm to GetPrintServiceStatus.

20-Dec-83 8:11:36 - Jacks - Added PrintFileOptions for other engines; made GetPrintServiceActivity a separate proc.

24-Jan-84 8:48:18 - Jacks - Converted to 8.0 SCS; added GetNSExecStatus and ExpungePrintService; added fax status types and more fields to DocumentAttrRecord; made minor changes.

22-Feb-84 15:56:59 - Jacks - To accomodate fax, removed restrictions on intStatus withing DocumentStatus; added intStatus to completed and completedWithWarnings; added willRetry to FaxTransmitData; added ResetStatistics, GetPrinterDisplay, PutPrinterDisplay; added parameters to Start/Stop Queuing/Printing.

19-Sep-84 14:58:07 - Jacks - Removed Initialize (currently in PSCommandExtra--will be in new PSInit interface); renamed Expunge; added SetFax495TransmissionResolution and SetFEPSTargetPS; changed "user" in Queuing/Printing control operations from NSString.String to NSName.Name; added feps9700 specific statuses to InternalDocStatus; renamed many types and parameter procedures; added variants where necessary for feps9700, banshee and fax295; removed aps5 variants.

15-Nov-84 11:19:51 - Jacks - Second round of changes for 9.0: Changed parameters to SetTargetPrintService; defined ErrorRecord and changed ErrorType somewhat; defined SimpleDocStatus and renamed InternalDocStatus to SpecificDocStatus; changes to DocumentAttrRecord: priority and sourceSystemElement not defined in NSPrint types anymore; removed secondsInMarker.

18-Jun-85 15:09:16 - Jacks - Added copyright notice; updated to PS Euclid interfaces; folded in changes from PSCommandExtras.

26-Jun-85 10:13:44 - Jacks - Added d1 variants.

1-Jul-85 13:11:51 - Jacks - Added retryCount to FaxTransmitData.

17-Jul-85 9:40:32 - Jacks - Removed AsyncMessageProc in favor of using PSAsyncMsg.Proc; added senderName parm to PrintFile.

24-Sep-85 11:11:17 - Jacks - Made DocumentFilter status a packed array; added documentInProgress to ErrorType; renamed DocumentParameterRecord.paperSize to paper.

14-Oct-85 9:57:41 - Jacks - Added errorCode to FaxTransmitData and removed obsolete Expunge proc.