# Compaq ACMS for OpenVMS
Writing Applications

Previous | Contents | Index

# 9.11 Procedure Parameter Notation for Programming Services

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.

Table 9-5 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.

# ACMS$DEQUEUE_TASK

> 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).

## Format

> 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])

## Parameters

> ### 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-adt2

> In 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.

### ret_workspace_count

The total number of workspaces for this queued task element.

### ret_element_priority

The priority of this queued task element [0 through 255].

### ret_username

The user name of the process that enqueued the queued task element, or, if the enqueuing process had CMKRNL privilege, this could be the user name specified with the user name parameter on the ACMS$QUEUE_TASK call.

### ret_element_id

The queued task element ID for this queued task element.

### ret_error_count

The number of times (if any) that the QTI component attempted a task invocation which failed for this queued task element.

### ret_last_error

The error message code (if any) returned to the QTI due to a task invocation error. If the QTI retries a task invocation and the retry also fails, then this parameter contains the most recent failure status. If the queued task element has never failed on a task invocation, then the error code is ACMS$_NORMAL.

### ret_last_error_adt

The absolute date and time of the most recent error message returned to QTI due to a task invocation error. If the queued task element has never failed on a task invocation, then the absolute date and time is zero.

## Return Status

> 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.

## Note

> 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.

# ACMS$QUEUE_TASK

> Stores the queued task element in an on-disk queued task file.

## Format

> 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])

## Parameters

> ### 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

### flags

Flags specifying options for the ACMS$QUEUE_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_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.

### element_priority

The relative priority of the queue element: higher priority elements are dequeued before lower priority elements. Valid values are 0 through 255.

The default value is 10.

### username

The user name under which the task runs. To specify this parameter, you must have the OpenVMS CMKRNL privilege. If you specify the parameter without this privilege, the ACMS$QUEUE_TASK service fails and returns ACMS$_INSUFPRIV.

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).

### element_id

A returned queued task element ID (in binary format) for this queued task element. See the ACMS$DEQUEUE_TASK service for a description of the binary and display formats of the element ID.

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.

## Return Status

> 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.

## Note

> 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