| Previous | Contents | Index |
ACMS$DEQUEUE_TASK and ACMS$QUEUE_TASK contain reference material for the ACMS$DEQUEUE_TASK and ACMS$QUEUE_TASK programming services. The format descriptions for the services use OpenVMS procedure parameter notation. Each parameter can have four characteristics, represented by two groups of symbols following the parameter. The characteristics definable for each parameter are:
<name>.<access type><data type>.<pass mech><parameter form> |
The characteristics are always listed in this order. A period (.) separates access and data types from passing mechanism and parameter form. For example:
comp_status.wq.r |
Table 9-5 defines the symbols used for procedure parameter notation.
| Notation | Symbol | Meaning |
|---|---|---|
| Access Type | m | Modify access |
| r | Read access only | |
| s | Call without stack unwinding | |
| w | Write and read access | |
| Data Type | adt | Absolute date and time |
| bu | Byte logical (unsigned) | |
| l | Longword integer (signed) | |
| lc | Longword return status | |
| lu | Longword logical (unsigned) | |
| q | Quadword integer (signed) | |
| qu | Quadword integer (unsigned) | |
| r | Record | |
| t | Character-coded text string | |
| w | Word integer (signed) | |
| x | Data type by descriptor | |
| z | Unspecified | |
| zem | Procedure entry mask | |
| Passing Mechanism | d | By descriptor |
| r | By reference | |
| v | By immediate value | |
| Parameter Form | none | Scalar (also called atomic data type) |
| x | Class type by descriptor |
For a complete explanation of all the OpenVMS data structures, data types, access mechanisms and passing mechanisms, see Guide to Creating OpenVMS Modular Procedures.
Removes or reads a queued task element from the queued task file and returns information about the task. This service does not dequeue or read queued task elements that are on hold unless you include the element ID in the parameter list. ACMS$DEQUEUE_TASK deletes a queue element immediately upon removing it from the queue (unless READ ONLY is specified).
ACMS$DEQUEUE_TASK (queue_name.rt.dx,
[element_id.rr.r],
[flags.rlu.r],
[ret_task.wt.dx],
[ret_application.wt.dx],
[ret_workspace_list.wz.r],
[ret_workspace_count.wl.r],
[ret_element_priority.wl.r],
[ret_username.wt.dx],
[ret_element_id.wr.r],
[ret_error_count.wlu.r],
[ret_last_error.wlu.r],
[ret_last_error_adt.wadt.r])
queue_name
The name of the queue from which to dequeue the task. The name is subject to logical name translation in the calling process. The logical translation is performed only the first time that the queue is accessed by the calling process. Any queue names resulting from logical translation can have a maximum length of 39 characters. Logical search lists are not supported.The queue name parameter is case-sensitive, so this parameter must be uppercase in order to match the queue name created with ACMSQUEMGR. (The ACMSQUEMGR uppercases all queue names unless you explicitly enclose the queue name in quotes when using the CREATE QUEUE command.)
The queue name cannot contain any trailing spaces. For example, if the queue name is "UPDATE_QUEUE" then the descriptor must have a length of 12.
Always create the queue before using this service. Create a task queue by using the ACMS Queue Management Utility (ACMSQUEMGR).
Dequeue tasks in one of three access modes:
- By highest element priority (first-in-first-out, FIFO, within priority). This is the default mode for this service.
- By element ID. By supplying the element_ID parameter, you can directly access a queued task element. When you enqueue a task, the ACMS$QUEUE_TASK service returns the element ID.
- Sequentially, by specifying the ACMS$M_QUE_GETNEXT flag.
element_id
The queued task element ID in binary format. The parameter allows direct access to a queued task element. The ACMS$QUEUE_TASK service returns the element ID (also in binary format). When you specify the element ID, the queued task element is dequeued regardless of whether or not it is on hold.The binary queued task element ID is 32 bytes long and has the following format:
Field Name Length Process ID (PID) Longword Sequence number Longword Enqueue absolute date/time Quadword Node name length Byte Node name 15 bytes When the ACMSQUEMGR utility displays or accepts the queued task element ID, it uses the following display format:
node_name::pid-seq_no-adt1-adt2In this format:
- node_name is the node name.
- PID is the process ID formatted as 8 hex characters.
- seq_no is the sequence number formatted as 8 hex characters.
- adt1 is the low order longword of the enqueue absolute date/time formatted as 8 hex characters.
- adt2 is the high-order longword of the enqueue absolute date/time formatted as 8 hex characters.
flags
Flags specifying options for the ACMS$DEQUEUE_TASK operation. The flags argument is a longword bit mask that is the logical OR of each bit set, where each bit corresponds to an option.
- ACMS$M_QUE_READONLY
When this bit is set, the ACMS$DEQUEUE_TASK service reads a queued task element but does not delete the queue element from the task queue file. The service performs the read operation regardless of whether or not dequeues have been suspended for the queue.
If the ACMS$M_QUE_READONLY bit is set and you use the default access mode (FIFO within priority), the ACMS$DEQUEUE_TASK service returns the same queued task element each time you call the service (assuming a static queue file).
By default this bit is clear.- ACMS$M_QUE_NOWAIT
When this bit is set, the ACMS$DEQUEUE_TASK service does not wait for a queued task element before returning. If there are no elements and this bit is set, then the error ACMS$_QUEEMPTY is returned.
When this bit is not set, the ACMS$DEQUEUE_TASK service waits for a queue element if no elements are currently queued.
By default this bit is clear.- ACMS$M_QUE_GETNEXT
When this bit is set, the ACMS$DEQUEUE_TASK service operates in sequential mode.
Before you set this bit, you can establish a position in the queue file by using a prior ACMS$DEQUEUE_TASK service call in either of the other two access modes. If you have not established a position in the queue file by using a prior ACMS$DEQUEUE_TASK service call, then by default you are positioned to the top of the queue file.
If you set the ACMS$M_QUE_GETNEXT bit after initially calling the ACMS$DEQUEUE_TASK service in the default access mode, position the internal file pointer to the highest priority element. Then the queue file will be read sequentially on successive calls to the ACMS$DEQUEUE_TASK service.
Because of the queue file organization, this sequential access returns queued task elements in the same order that they would be returned if you were using the default access mode without setting the ACMS$M_QUE_READONLY bit (assuming a static queue file). The ordering of the queue file is by highest priority, and FIFO within priority.
By default, this bit is clear.ret_task
The task name for this queued task element.ret_application
The application specification for this queued task element.ret_workspace_list
The list of workspaces for this queued task element. This is a varying length argument list of workspaces passed by descriptor, as shown in Figure 9-3.Figure 9-3 List of Workspaces Passed by ACMS$DEQUEUE_TASK
If the queued task element has more workspaces than are passed in
ret_workspace_list, then the warning error message ACMS$_TOOFEWWSPS is
returned and the element is deleted. In all cases, the actual number of
workspaces contained in the queued task element is returned in the
ret_workspace_count parameter.
The error messages that can be returned by the ACMS$DEQUEUE_TASK service include:
Status Severity Level Description ACMS$_NORMAL Success Normal successful completion ACMS$_TOOFEWWSPS Warning The workspace list parameter had fewer workspaces than the queued task ACMS$_ERROPNAQF Error Error opening the ACMS Queue Definition File ACMS$_ERROPNPAR Error Error opening the ACMS parameter file ACMS$_ERROPNQUE Error Error opening queue ACMS$_ERRQUEINIT Error Error initializing the queue services ACMS$_INSUFPRIV Error Insufficient privilege for attempted operation ACMS$_INVNUMWSP Error Invalid number of workspaces ACMS$_INVQUENAM Error Invalid queue name ACMS$_LNE Error Logical name translation count exceeded ACMS$_QUEDEQSUS Error Dequeue operations are suspended ACMS$_QUEEMPTY Error Queue is empty ACMS$_QUENOTFND Error Queue does not exist SS$_ACCVIO Fatal Access violation; an argument that you passed was not accessible Errors from the RMS services SYS$OPEN, SYS$CONNECT, SYS$GET, and the RTL service LIB$SCOPY.dx.dx can also be returned.
You can include the ACMS$DEQUEUE_TASK call within a distributed transaction. When ACMS calls the DECdtm to start the distributed transaction, DECdtm returns a unique transaction identifier (TID). ACMS$DEQUEUE_TASK uses this default TID.
Stores the queued task element in an on-disk queued task file.
ACMS$QUEUE_TASK (queue_name.rt.dx,
task.rt.dx,
application.rt.dx,
[workspace_list.rz.r],
[flags.rlu.r],
[element_priority.rl.r],
[username.rt.dx],
[element_id.wr.r])
queue_name
The name of the queue in which you want to store this task. The name is subject to logical name translation in the calling process. The logical is performed only the first time that the queue is accessed by the calling process. The queue_name and any queue names resulting from logical translation can have a maximum length of 39 characters. Using logical names for queue names allows the actual queue name to change without recoding programs. Logical search lists are not supported.The queue name parameter is case-sensitive, so this parameter must be uppercase in order to match the queue name created with ACMSQUEMGR. The ACMSQUEMGR uppercases all queue names unless you explicitly enclose the queue-name in quotes when using the CREATE QUEUE command.
The queue name cannot contain any trailing spaces. For example, if the queue name is "UPDATE_QUEUE" then the descriptor must have a length of 12.
Always create the queue before using this service. Create a task queue by using the ACMS Queue Management Utility (ACMSQUEMGR).
task
The name of the task queued. The task name must be in capital letters.application
The name of the application in which the task is to be run. The application name must be in capital letters. This parameter names an application specification. The semantics associated with application specifications (for example, logical translation, search lists, failover) occur as the task is invoked by the QTI. (See Compaq ACMS for OpenVMS Managing Applications for more information on application specifications.)workspace_list
A list of workspaces to pass to the task. This is a variable length argument list of workspaces passed by descriptor, as shown in Figure 9-4.Figure 9-4 List of Workspaces Passed by ACMS$QUEUE_TASK Service
ACMS$M_QUE_HOLD
Setting the bit puts the queued task element in the hold state. Queued task elements that are in the hold state are not available for dequeuing by either the QTI or the ACMS$DEQUEUE_TASK service. Once a task is queued, you can use the ACMSQUEMGR utility to modify its state.
By default, this bit is clear.
The default value is 10.
If you do not use this parameter, the user name of the enqueuing process is stored as the user name under which the task runs.
The QTI uses the enqueuer user name as the submitter user name for the task selection (provided the process user name of the QTI has the ACMS agent privilege).
You can use the element ID from the ACMSQUEMGR Utility and in the ACMS$DEQUEUE_TASK service to directly access this queued task element for element operations.
The error messages returned by the ACMS$QUEUE_TASK service include:
Status Severity Level Description ACMS$_NORMAL Success Normal successful completion ACMS$_ERROPNAQF Error Error opening the ACMS Queue Definition File ACMS$_ERROPNPAR Error Error opening the ACMS parameter file ACMS$_ERROPNQUE Error Error opening queue ACMS$_ERRQUEINIT Error Error initializing the queue services ACMS$_INSUFPRIV Error Insufficient privilege for attempted operation ACMS$_INVAPPLE Error The application specification or its descriptor was invalid ACMS$_INVNUMWSP Error Invalid number of workspaces ACMS$_INVPRIO Error Invalid priority for element ACMS$_INVQUENAM Error Invalid queue name ACMS$_INVSIZWSP Error Total size of workspaces exceeds the size defined in the ACMS Queue Definition File ACMS$_INVTASK Error The task name or its descriptor was invalid ACMS$_INVUSER Error The user name was invalid ACMS$_LNE Error Logical name translation count exceeded ACMS$_QUEENQSUS Error Enqueue operations are suspended ACMS$_QUENOTFND Error Queue does not exist SS$_ACCVIO Fatal Access violation; an argument that you passed was not accessible Errors from the RMS services SYS$OPEN, SYS$CONNECT, and SYS$PUT can also be returned.
You can include the ACMS$QUEUE_TASK call within a distributed transaction. When ACMS calls the DECdtm to start the distributed transaction, DECdtm returns a unique transaction identifier (TID). ACMS$QUEUE_TASK uses this default TID.
| Previous | Next | Contents | Index |