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:

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:

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.

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