NetWare QMS
Articles and Tips: article
Developer Support Engineer
Developer Support
01 Apr 1996
NetWare's Queue Management Services (QMS) are Directory Services/bindery based in NetWare 4.0 and greater, while being exclusively bindery based in NetWare 3.12 and older versions. This article looks at QMS from a bindery perspective. A queue is simply a directory on the NetWare server where files can be stored and manipulated on a temporary basis. Queue administration and access control is organized around queue bindery objects. NetWare Queue Services provide full console-type control over the operation of the queue. NetWare servers provide QMS that allow jobs to be placed in a queue and serviced in a logical order. There are a wealth of APIs available for both client and NLM programmers. This article discusses those APIs and how they relate to managing and servicing queues.
- Introduction
- Queue Objects
- The Queue Job Record
- Managing Queues
- Servicing Queues
- Queue Job Functions
- Queue Job Management Functions
- Queue Management Functions
- Queue Server Functions
- Conclusion
Introduction
NetWare's Queue Management Services (QMS) are Directory Services/bindery based in NetWare 4.0 and greater, while being exclusively bindery based in NetWare 3.12 and older versions. This article looks at QMS from a bindery perspective.
NetWare's queue management system provides applications with a generic queuing mechanism for managing services on the network. A queue is simply a directory on the NetWare server where queue files can be stored and manipulated on a temporary basis. Novell states that each queue can hold up to 250 job files, although from a server standpoint, this maximum is 8190 (8 kilobytes -2).
The reason the 250 file maximum is promoted is because all of the NetWare utilities that create or manipulate queue and available APIs only support the 250 maximum. Developers would have to write their own management system to deal with the larger limit.
The server operating system numbers jobs from 1 to 999.
Objects accessing the queue can be users, operators, or servers. Users can submit jobs and monitor their progress. An operator controls the queue's status and has access to any jobs currently in the queue. A server removes jobs from the queue and performs whatever specialized service the developer has in mind.
When job is submitted to a queue, the job is copied into the queue directory, on the network server. Queue jobs are processed in the order in which they are submitted. Each file is given a number that identifies its place relative to the other jobs in the queue. A hidden file in the same directory keeps track of the sequence in which the jobs will be processed.
A job server checks each assigned queue at a specified interval, taking care of jobs on a first-in, first-out basis. As many as 25 job servers can be attached to a queue at the same time. Once a job is processed, its associated file is deleted from the queue directory.
Queue Objects
Queue administration and access control is organized around queue bindery objects. Like other bindery objects, a queue has the following:
name
type ID
object flag
security flag
additional properties
For example, a print queue might have the following object data:
|
Object name: |
PRINTER |
(user-supplied queue name) |
|
Object type: |
0x0300 |
(print queue) |
|
Object ID: |
9F00002A |
(assigned by NetWare) |
|
Object flag: |
0x00 |
(static) |
|
Object security: |
0x31 |
(write = supervisor; read = logged) |
Queue attributes consist of Q_DIRECTORY, Q_OPERATOR, Q_SERVERS, and Q_USERS. The following table shows the configuration of these properties.
|
Property Name
|
Property Flag
|
Property Security
|
Description
|
|
Q_DIRECTORY |
0x00 (item / static) |
0x33 |
Holdsthe directory path of the queue directory(for example, SYS:SYSTEM/9F00002A). The queueobject ID is used to name the subdirectorywhere the queue is found. |
|
Q_OPERATOR |
0x02 (set / static) |
0x31 |
Holdsthe object IDs of all bindery objects thatare assigned as queue operators. |
|
Q_SERVERS |
0x02 (set / static) |
0x31 |
Holdsthe object IDs of all servers that can access the queue. |
|
Q_USERS (optional) |
0x02 (set / static) |
0x31 |
Holdsthe object ID of all users who can access the queue. |
Note: Property security is based on the bindery access control scheme in which the upper nibble indicates write access and the lower nibble indicates read access. A value of 3 represents any supervisor-only access and a 1 represents any logged-in object. For example, the Q_USERS property security is 0x31, which means that only the supervisor can modify this property but any logged-in user can read its value.
The Queue Job Record
Inside of the queue, each job has a queue job record that holds information for processing the job. The information identifies the client, the target server, and the actual server.
The following information is contained in the QueueJobStruct:
Client station number
Client task
Client ID
Target server ID
Target execution time
Job entry time
Job number
Job type
Job position
Job control flags
Job file name
Job file handle
Servicing server station
Servicing server ID
Job description
Client record area
Job Control Flags
The job control flags affect the way the queue server processes a queue job. The flags define the following bits:
Note: Bits 0, 1, and 2 must be 0.
First Byte: Bit: 0 - must be 0 1 - must be 0 2 - must be 0 3 - service auto-start 4 - service restart 5 - entry open 6 - user hold 7 - operator hold
The service auto-start flag indicates how to handle the job should the client station lose its connection before submitting the job. If this flag is set, the job will be marked for processing if the client station loses its connection to the queue. If this flag isn't set, the job is removed from the queue.
The service restart flag indicates how to handle the job if the queue server fails during processing. If the flag is set, the job will be left in the queue for re-servicing.
The entry open flag indicates whether the job is ready to be processed. When the job entry is first created, this flag is set to indicate the job hasn't been submitted yet. When the client submits this job, this flag is cleared.
The user hold flag indicates whether the job may be processed. If the flag is set, the job will not be processed until the flag is clear, but the job continues to advance toward the front of the queue. An operator or the client who submitted the job can modify this flag.
The operator hold flag indicates whether the job may be processed. If the flag is set, the job will not be processed until the flag is clear, but the job continues to advance toward the front of the queue. Only operators can modify this flag.
Client Record Area
The client record area is a 152-byte field that can contain supplementary information exchanged between the queue client and the queue server. The format for this information is defined by the application. For example, NetWare printing uses this field to store print job parameters like tab size, number of copies, and banner name.
Creating and Managing Queue Jobs
Call NWQCreateJob, server, or NWCreateQueueFile2, client, to create a queue job. This function sets up a queue job record and opens a queue job file. You pass this function the destination queue and, optionally, the target server, target execution time, job type, and job control flags. A text description can also be included. The client record area can be used to store additional information required by the application. Creating the queue job returns a job file handle to the queue file. Use this handle to write data to the file.
Call NWQMarkJobForService, server, or NWCloseFileAndStartQueueJob2, client, to close the queue job file and make the job available for processing. If for some reason the job isn't to be processed, call NWRemoveJob, server, or NWRemoveJobFromQueue2, client, to cancel the job and remove it from the queue. Once in the queue, a job is identified by its queue job number. This number is part of the information returned in the queue job record when you submit the job. Use this number to read a queue job record and to find the current size of the job file. You can modify the following information in the queue job record:
Target server ID number
Target execution time
Job type
User hold flag
Server restart flag
Server auto-start flag
Text job description in the client record area
Operator hold flag
In addition you can change the job's position in the queue or remove the job from the queue. To modify the operator hold flag, an application must have operator status. Operators can also receive a list of all jobs currently in the queue.
Managing Queues
NetWare Queue Services provide full console-type control over the operation of the queue. You can create and delete objects and read and set queue status information for a queue.
Creating Queues
To create a queue, call NWQCreate, server, or NWCreateQueue, client. This function creates the queue object and assigns it a queue type, name, and directory path. The following queue types are defined by Novell:
OT_PRINT_QUEUE 0x0300 OT_JOB_QUEUE 0x0A00
An 8-character, hexadecimal representation of the queue's object ID is added to the directory path, and the resulting path is assigned to the queue's Q_DIRECTORY property. Typically, the directory SYS:SYSTEM is used as the directory path, although you can locate the queue somewhere else.
To delete a queue, call NWQDestroy, server, or NWDestroyQueue, client. Deleting a queue deletes all associated data, including all jobs currently in the queue. Any active jobs associated with the queue are aborted. The following events occur when calling this function:
All active jobs are aborted.
All job servers are detached from the queue.
All job entries are removed from the queue.
All files associated with the queue (job files and the queue file) are deleted.
The queue object and its associated properties are removed from the Directory or the bindery.
The queue's subdirectory is deleted.
Only the Supervisor or an object that is security equivalent to the Supervisor can destroy a queue.
Queue Status Information
A pair of functions access the queue status flags. Use NWQGetStatus, server, or NWReadQueueCurrentStatus2, client, to read the flags. Use NWQSetStatus, server, or NWSetQueueCurrentStatus2, client, to modify the flags.
Queue status flags indicate a queue's current operational status. Below are the values associated with these flags.
|
Value
|
Flag
|
Description
|
|
Bit 0x1 |
QS_CANT_ADD_JOBS |
Setif the operator has disallowed additional servers attaching to the queue to serviceit. |
|
Bit 0x2 |
QS_SERVERS_CANT_ATTACH |
Setif the operator has disallowed additional servers attaching to the queue to serviceit. |
|
Bit 0x3 |
QS_CANT_SERVICE_JOBS |
Setif the operator has disallowed servers servicing current jobs in the queue. |
You must have Operator privileges to call the above mentioned functions.
Servicing Queues
The server application is the third component in the queue service architecture. While the queue management system controls access to the queue and keeps the jobs in order, a queue server is responsible for removing jobs from the queue and processing them. Queue Services make few assumptions about the kind of services provided by a queue server.
Attaching to a Queue
To service a queue, a queue server application logs in to the NetWare server and calls NWQAttachServer, server, or NWAttachQueueServerToQueue, client. To attach to the queue successfully, a queue server must be listed in the queue's Q_SERVERS property. After attaching, a queue server calls NWQServiceJob, server, or NWServiceQueueJob2, client. This function can include a job type identifying the type of job the server will accept. (A value of -1 includes all job types.)
Processing Jobs
After receiving the request to service a job, the queue management system searches the queue for a job that is appropriate for the queue server. The following conditions apply:
The job's target server ID number must match the queue server or be set to -1L.
The target execution time must have expired or be set to FFh.
The job's type must match the type specified by the server.
The operator hold, user hold, and entry open flags must all be clear, and the server ID number must be 0, indicating that the job isn't being serviced.
When an eligible job is found, the job's server station, server task, and server ID number are set to that of the queue server. The job file is opened for read/write access, and the updated queue job record is returned to the queue server.
A queue server uses the job file handle to access the application-specific data associated with the job. When it has finished processing the job, a queue server calls NWQEndJobService, server, or NWFinishServicingQueueJob2, client. This is the queue management system's signal that the job has been processed.
If a queue server needs to interrupt processing a job, it calls NWQAbortJobService, server, or NWRestoreQueueServerRights, client. This function allows the queue management system to handle the unfinished job according to the values of the job's control flags.
Changing to Client Rights
While processing a job, a queue server can call NWQChangeToClientRights, server, or NWChangeToClientRights2, client, to assume the access rights of the user who submitted the job. This step is important if the job requires access to other files or bindery objects.
By assuming the client's rights, a queue server can be sure the user is permitted to access the specified files. After the job is complete, a queue server calls NWQRestoreServerRights, server, or NWRestoreQueueServerRights, client, to have its rights restored.
Accessing the Queue Status Record
The queue management system maintains a 64-byte status record for each queue that a queue server is attached to. This field is available for your application-the queue management system doesn't use it. Any object listed in either the queue's Q_USERS or Q_OPERATORS properties can read or modify this information. A pair of functions provide this service.
On the server call:
NWQGetServerStatus
NWQSetServerStatus
On the client call:
NWReadQueueServerCurrentStatus
NWSetQueueServerCurrentStatus
Queue Job Functions
These functions let you create, abort and close queue job files.
On the server:
NWQAbortJob - Removes a job from a queue and closes the associated file.
NWQMarkJobForService - Closes the job's associated file and marks the job ready for service.
NWQCreateJob - Places a new job into a queue.
On the client:
NWCloseFileAndAbortQueueJob2 - Closes a queue file and destroys it.
NWCloseFileAndStartQueueJob2 - Closes a queue file and marks the job ready for processing.
NWCreateQueueFile2 - Creates a queue file and returns a handle to it.
Queue Job Management Functions
These functions let you manage queue jobs after they are submitted to the queue.
On the server:
NWQChangeJobEntry - Changes information in a job entry record.
NWQChangeJobPosition - Changes a job's position in the queue.
NWQGetJobFileSize - Finds the size of the job's associated file in a queue.
NWQScanJobNums - Returns a list of jobs contained in the specified queue.
NWQGetJobEntry - Retrieves information about a specified job in a queue and places it in a NWQJobRec_t structure.
NWQRemoveJob - Removes a job from a queue.
On the client:
NWChangeQueueJobEntry2 - Changes the queue job information for the specified job.
NWChangeQueueJobPosition2 - Changes the position of the job in the specified queue.
NWGetQueueJobFileSize2 - Returns the size ofthe job file associated with a queue job.
NWGetQueueJobList2 - Returns a list of all entries in the specified queue.
NWReadQueueJobEntry2 - Reads the queue job information for the specified job.
NWRemoveJobFromQueue2 - Removes a job from the specified queue.
Queue Management Functions
These functions let you create and delete queue, and manage queue status.
On the server:
NWQCreate - Creates a queue object with the specified type and name in the bindery, and in the file system of a server.(This is a bindery-specific function. To create a queue for DirectoryServices use NWDSAddObject.)
NWQDestroy - Destroys the specified queue.
NWQGetStatus - Returns the current status of a queue. The queue status byte indicates the overall status of the queue.
NWQSetStatus - Allows an operator to control the addition of jobs and servers to a queue, or prevent current jobs from being serviced, by setting or clearing bits in the queue Status.
On the client:
NWCreateQueue - Creates a queue object in the bindery along with its associated queue properties.
NWDestroyQueue - Deletes a queue object fromthe bindery and removes its queue directory. All entries and associated jobfiles are also deleted.
NWGetPrinterQueueID - Returns the object ID of the queue servicing the specified printer.
NWReadQueueCurrentStatus2 - Returns the current status of the specified queue.
NWSetQueueCurrentStatus2 - Allows the operator to modify a queue's queue status property.
Queue Server Functions
These functions let queue servers attach to queues, open queue jobs, and assume client ID rights. They also provide access to the queue server status records associated with a queue.
On the server:
NWQAbortJobService - Allows a job server to inform the queue manager that the job server cannot complete servicing of a job it previously accepted. The function closes the job file and resets the calling server's access rights to their original (login) values.
NWQAttachServer - Attaches a job server to a specific queue.
NWQBeginJobService - Allows a job server to select a new job for servicing.
NWQChangeJobQueue - Moves a job from one queue to another.
NWQChangeToClientRights - Allows a job server to assume the login identity and rights of the client that placed the job in the queue.
NWQDetachServer - Removes the requesting job server from the queue's list of active job servers.
NWQEndJobService - Allows a job server to signal QMS that the calling job server has successfully completed servicing a job.
NWQGetServers - Returns the object IDs of the servers currently servicing the queue as well as the queue server's client connection numbers.
NWQGetServerStatus - Reads the current status of a job server.
NWQRestoreServerRights - Restores a job server's own login identity and rights after it has assumed a client's login identity and rights.
NWQServiceJob - Allows a job server to select a new job for servicing.
NWQSetServerStatus - Updates QMS's copy of a job server's status record.
On the client:
NWAbortServicingQueueJob2 - Signals the queue management services that the server has discontinued servicing the specified job.
NWAttachQueueServerTo Queue - Attaches the local workstation as a queue server to the specified queue.
NWChangeToClientRights2 - Allows a queue server to change its current login identity to match the identity of the client whose job is being serviced.
NWDetachQueueServerFromQueue - Removes the local workstation from the specified queue's list of active queue servers.
NWFinishServicingQueueJob2 - Signals the queue management services that the service has successfully serviced the job.
NWReadQueueServerCurrentStatus2 - Reads status information for a queue server. The information pertaining to the queue server status is specific to the application.
NWRestoreQueueServerRights - Restores the queue server ID to a queue server. This function typically is called after NWChangeToClientRights2 has changed the server's identity to the client.
NWServiceQueueJob2 - Returns the next available job in the specified queue.
NWSetQueueServerCurrentStatus - Modifies the status information for a queue server.
Conclusion
NetWare servers provide QMS that allow jobs to be placed in a queue and serviced in a logical order. There are a wealth of APIs available for both client and NLM programmers. NetWare's QMS consists of three roles--user, operator, and server, which are associated with applications submitting jobs to a queue, managing and deleting jobs, and removing jobs from the queue for processing. NetWare's QMS programming interface is straightforward and easy to implement. QMS provides applications with a generic queuing mechanism for managing services on the network.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.