# Compaq TP Desktop Connector
for ACMS
Client Services Reference Manual

Previous | Contents | Index

# 2.6 acmsdi_call_task

TP Desktop Connector client programs call this service to execute a task in a ACMS application.

## Format

> acmsdi_call_task (submitter_id,
> [call_options],
> task _name,
> application _name,
> selection _string,
> status _message,
> workspace _count,
> [workspaces],
> [call_id],
> [completion_status],
> [completion_routine], 1
> [call_context])

## Parameters

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: read
> Mechanism: by reference
> The submitter_id returned by the acmsdi_sign_in service.

> ### call_options

> Type: ACMSDI_CALL_OPTION
> Access: read
> Mechanism: by reference
> An array of ACMSDI_CALL_OPTION elements that either enables unidirectional workspace optimization or defines presentation procedure addresses. The include file ACMSDI.H contains the definition for the ACMSDI_CALL_OPTION type. If you use the options array to enable unidirectional workspaces, use the ACMSDI_WORKSPACE_OPT type in the workspace list. See Section 2.4.2 and Section 2.5 for more information.

> ### task_name

> Type: char *
> Access: read
> Mechanism: by reference
> The name of the task to execute. Maximum length is 31.

> ### application_name

> Type: char *
> Access: read
> Mechanism: by reference
> The specification of a ACMS application in which the task resides. The application name must be a valid application specification on the submitter node. It can take the form NODE::APPLICATION, or can be specified using a logical name that is translated by the ACMS Central Controller (ACC) on the submitter node. Maximum length is 80.

> ### selection_string

> Type: char *
> Access: read
> Mechanism: by reference
> Used by the desktop client program to pass additional information to the task. Maximum length is 256.

> ### status_message

> Type: char *
> Access: write
> Mechanism: by reference
> A buffer to receive the message text associated with the task completion status. The message text returned is either the text associated with a TP Desktop Connector error or the message text returned from a ACMS application. Required length is 80.

> Caution

> If the full space is not allocated, the TP Desktop Connector client services write past the end of the allocated string and can cause the application to fail. Ensure that the desktop client program allocates the required length of space.

### workspace_count

Type: long int
Access: read
Mechanism: by value
The decimal number of workspaces being passed to the task.

### workspaces

Type: ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OPT array
Access: read/write
Mechanism: by reference
One or more optional workspaces to be passed to the task. You need to typecast your array to void *. The workspaces must be specified in the same order as they are declared in the task definition, and must match the number specified in the workspace_count parameter. If you use the ACMSDI_WORKSPACE_OPT type, you must set the call_options parameter to allow unidirectional workspaces.

### call_id

Type: ACMSDI_CALL_ID
Access: write
Mechanism: by reference
A structure defined in the ACMSDI.H include file into which the acmsdi_call_task service writes a newly created call identification, a handle used by the TP Desktop Connector client services to identify an active call for a submitter.

### completion_status

Type: int
Access: write
Mechanism: by reference
The final status of the TP Desktop Connector client service. In the blocking environment, the completion_status parameter is set to zero when the service starts successfully.

When the service completes, the completion_status parameter contains the final status. See Table 2-2 for the list of return status values.

When a task is canceled, the TP Desktop Connector gateway reports a specific error, where possible. If the gateway cannot convert a ACMS error to a specific TP Desktop Connector status, it returns ACMSDI_TASK_FAILED to the desktop client program.

### completion_routine

Type: function address1
Access: read
Mechanism: by value
Address of a function to be called when the service completes. The completion_routine is called by the acmsdi_dispatch_message service when the "End of Task" message is received from the TP Desktop Connector gateway.

### call_context

Type: void *
Access: read
Mechanism: by value
Optional parameter passed to presentation procedures and completion routines to identify the call. Use this parameter to supply an application-specific context for the call.

## Return Status

> The status values returned by the acmsdi_call_task service are listed in Table 2-2.

> Table 2-2 acmsdi_call_task Return Status Values
> Status | Description
> --- | ---
> ACMSDI_APPLDEAD | Application stopped unexpectedly.
> ACMSDI_CALLACTV | Call is already active.
> ACMSDI_INSUFPRM | Insufficient parameters.
> ACMSDI_INTERNAL | Internal TP Desktop Connector error.
> ACMSDI_INVOPTION | Invalid item in options list.
> ACMSDI_INVSUBID | Invalid or obsolete submitter identification.
> ACMSDI_MIXEDMODE | All calls on a connection must be either blocking or nonblocking.
> ACMSDI_NOMEMORY | Insufficient memory to complete requests.
> ACMSDI_NORMAL | Normal successful completion.
> ACMSDI_NOSUCH_APPL | Application not found.
> ACMSDI_NOSUCH_TASK | Task not found.
> ACMSDI_OPR_CANCELLED | Operator canceled task.
> ACMSDI_PENDING | Successful operation pending nonblocking completion. The final status is in the completion status parameter.
> ACMSDI_SECCHK | Task security check failed.
> ACMSDI_SIGNINACTV | Request is invalid while the sign-in is active.
> ACMSDI_SIGNOUTACTV | Request is invalid while the sign-out is active.
> ACMSDI_SRVDEAD | Node name is invalid, or TP Desktop Connector gateway is not running on the specified node, or the network link terminated.
> ACMSDI_TASK_ABORT | Task completed abnormally.
> ACMSDI_TASK_CANCELLED | Task was canceled.
> ACMSDI_TASK_FAILED | Task failed during execution.
> ACMSDI_TASK_SP_DIED | Task was canceled when TP Desktop Connector gateway process died.

Note #### 1 For nonblocking only, see Section 2.3. #### 1 For nonblocking only, see Section 2.3. Not applicable to forced nonblocking and will cause an error if supplied.

# 2.7 acmsdi_cancel

TP Desktop Connector client programs call this service in a nonblocking or forced nonblocking environment to cancel a currently active ACMS task. Use the acmsdi_cancel service only if you invoke a task using nonblocking services. Do not use the acmsdi_cancel service from a presentation procedure or from an asynchronous completion routine.

## Format

> acmsdi_cancel (submitter id,
> call _id,
> [cancel_reason],
> reserved,
> [completion_status],
> completion _routine, 1
> [call_context])

## Parameters

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: read
> Mechanism: by reference
> The submitter_id for the session associated with the task that is being canceled.

> ### call_id

> Type: ACMSDI_CALL_ID
> Access: read
> Mechanism: by reference
> The call_id for the task that is being canceled, which was passed back on the acmsdi_call_task service.

> ### cancel_reason

> Type: long int
> Access: read
> Mechanism: by value
> Optional parameter containing the status value of the reason code for the cancel request. This value is passed to the Application Execution Controller (EXC) by the TP Desktop Connector gateway. The default is ACMSDI_CALL_CANCELED, "the task was canceled by the task submitter".

> ### reserved

> Type:
> Access:
> Mechanism:
> This parameter is reserved for future use. Specify as NULL.

> ### completion_status

> Type: long int
> Access: write
> Mechanism: by reference
> Optional parameter to contain the final completion status of the service. The completion_status is set to ACMSDI_PENDING when the service starts successfully. When the service is successful, completion_status is set to 0.

> ### completion_routine

> Type: function address1
> Access: read
> Mechanism: by value
> Address of a function to be called when the service completes. The completion_routine is called by the ACMSDI_DISPATCH_MESSAGE service when the appropriate reply is received from the TP Desktop Connector gateway on the OpenVMS system.

> ### call_context

> Type: void*
> Access: read
> Mechanism: by value
> Optional parameter that is passed to the completion_routine to identify the call. You can use this to supply application-specific context for the call that is being canceled.

## Return Status

> The status values returned by the acmsdi_cancel service are listed in Table 2-3.

> Table 2-3 acmsdi_cancel Return Status Values
> Status | Description
> --- | ---
> ACMSDI_CANCELACTV | Cancel already in progress.
> ACMSDI_EXCHACTV | Service cannot be called from presentation procedure.
> ACMSDI_INSUFPRM | Insufficient parameters.
> ACMSDI_INTERNAL | Internal ACMS error.
> ACMSDI_INVCALLID | Invalid or obsolete call identification.
> ACMSDI_INVSUBID | Invalid or obsolete submitter identification.
> ACMSDI_NOMEMORY | Insufficient memory to complete requests.
> ACMSDI_NORMAL | Normal successful completion.
> ACMSDI_PENDING | Successful operation pending nonblocking completion. The final status is in the completion status parameter.
> ACMSDISIGNINACTV | Request is invalid while the sign-in is active.
> ACMSDISIGNOUTACTV | Request is invalid while sign-out is active.
> ACMSDI_SRVDEAD | Node name is invalid, or the TP Desktop Connector gateway is not running on the specified node.

Note #### 1 For nonblocking only, see Section 2.3. #### 1 For nonblocking only, see Section 2.3. Not applicable to forced nonblocking and will cause an error if supplied.

# 2.8 acmsdi_complete_pp

TP Desktop Connector client programs call this nonblocking service to complete exchange step processing for a submitter. An application must call this service to complete an outstanding presentation procedure request from the TP Desktop Connector gateway in a nonblocking or forced nonblocking environment (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

## Format

> acmsdi_complete_pp (call_id,
> pp _status)

## Parameters

> ### call_id

> Type: ACMSDI_CALL_ID
> Access: read
> Mechanism: by reference
> The call_id parameter is passed back on the acmsdi_call_task service.

> ### pp_status

> Type: long int
> Access: read
> Mechanism: by value
> The completion status of the presentation procedure. The pp_status parameter is returned to the ACMS task as the completion status for the current exchange step. A valid OpenVMS status value is returned to the task.

## Return Status

> The status values returned by the acmsdi_complete_pp service are listed in Table 2-4.

> Table 2-4 acmsdi_complete_pp Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INSUFPRM | Insufficient parameters.
> ACMSDI_INTERNAL | Internal TP Desktop Connector error.
> ACMSDI_INVCALLID | Invalid or obsolete call identification.
> ACMSDI_INVSUBID | Invalid or obsolete submitter identification.
> ACMSDI_NOMEMORY | Insufficient memory to complete requests.
> ACMSDI_NOPPACTV | No presentation procedure active for this call.
> ACMSDI_NORMAL | Normal successful completion.
> ACMSDI_SRVDEAD | Node name is invalid, or the TP Desktop Connector gateway is not running on the specified node, or the network link terminated.

# 2.9 acmsdi_dispatch_message

TP Desktop Connector client programs call this nonblocking service to check for and process messages sent from a TP Desktop Connector gateway to an active submitter in the desktop application. The application must periodically call this service in a nonblocking environment to check for completion of outstanding acmsdi_sign_in, acmsdi_call_task, and acmsdi_sign_out requests. If no TP Desktop Connector messages are received, the service returns immediately. If a TP Desktop Connector message is received, the service calls the appropriate completion routine or presentation procedure and then returns (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

Note that this call is not used in the forced nonblocking environment. See Section 4.13.

## Format

> acmsdi_dispatch_message ()

## Parameters

> ###

> No parameters are specified.

## Return Status

> The status values returned by the acmsdi_dispatch_message service are listed in Table 2-5.

> Table 2-5 acmsdi_dispatch_message Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INTERNAL | Internal TP Desktop Connector error.
> ACMSDI_NOMEMORY | Insufficient memory.
> ACMSDI_NORMAL | Normal successful completion.
> ACMSDI_SRVDEAD | Node name is invalid, or TP Desktop Connector gateway is not running on the specified node, or the network link terminated.

# 2.10 acmsdi_return_pointer

TP Desktop Connector client programs written in Visual Basic use the ACMSDI_RETURN_POINTER service to create the workspace array for the ACMSDI_CALL_TASK routine. When passing a workspace, the ACMSDI_CALL_TASK service expects a data structure with the size and address of each workspace. The ACMSDI_RETURN_POINTER service assigns the address of a workspace argument to the contents of a pointer address argument. This service may be used in the forced nonblocking environment to obtain reference pointers to structures such as call_id.

## Format

> acmsdi_return_pointer (structure)

## Parameters

> ### structure

> Type: long int
> Access: read
> Mechanism: by reference
> The workspace or other structure for which a pointer is to be obtained.

## Return Status

> The return status value for acmsdi_return_pointer is the address of the structure passed as the parameter in the call.

# 2.11 acmsdi_sign_in

TP Desktop Connector client programs call this service to sign a user in to a ACMS system.

## Format

> acmsdi_sign_in (submitter_node,
> username,
> password,
> [options],
> submitter _id,
> [completion_status],
> [completion_routine], 1
> [call_context])

## Parameters

> ### submitter_node

> Type: char *
> Access: read
> Mechanism: by reference
> The node name of the ACMS system where the user is to be signed in. Maximum length is 80.

> ### username

> Type: char *
> Access: read
> Mechanism: by reference
> The name of the OpenVMS account of the user to be signed in. Maximum length is 80.

> ### password

> Type: char *
> Access: read
> Mechanism: by reference
> The password of the user to be signed in. Maximum length is 80.

> ### options

> Type: ACMSDI_OPTION array
> Access: read
> Mechanism: by reference
> Union containing multiple structures and an option variable, the value of which defines the type of option being selected (see Section 2.5.1).

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: write
> Mechanism: by reference
> A structure into which the acmsdi_sign_in service writes a newly created submitter identification. Other services use the submitter identification as a handle to identify an active submitter. The ACMSDI_SUBMITTER_ID structure is defined in the ACMSDI.H include file.

> ### completion_status

> Type: int
> Access: write
> Mechanism: by reference
> The final status of the service. In the blocking environment, the completion_status parameter is set to zero when the service starts successfully.

> When the service completes, completion_status contains the final status. See Table 2-6 for a list of return status values.

> ### completion_routine

> Type: function address1
> Access: read
> Mechanism: by value
> Address of a function to be called when the nonblocking service completes. The completion routine is called by the acmsdi_dispatch_message service when the reply is received from the TP Desktop Connector gateway.

> ### call_context

> Type: void *
> Access: read
> Mechanism: by value
> Optional parameter passed to presentation procedures and completion routines to identify the call. Use this parameter to supply application-specific context for the call.

## Return Status

> The status values returned by the acmsdi_sign_in service are listed in Table 2-6.

> Table 2-6 acmsdi_sign_in Return Status Values
> Status | Description
> --- | ---
> ACMSDI_CALLACTV | Call is active.
> ACMSDI_INSUFPRM | Insufficient parameters.
> ACMSDI_INTERNAL | Internal TP Desktop Connector error.
> ACMSDI_INVLOGIN | Invalid login attempt.
> ACMSDI_INVOPTION | Invalid item in options list.
> ACMSDI_INVPROTOCOL | Mismatch in versions of TP Desktop Connector client and gateway software.
> ACMSDI_MIXEDMODE | All calls on a connection must be either blocking or nonblocking.
> ACMSDI_NOACMS | ACMS system not available.
> ACMSDI_NOCOMPRESS | Gateway does not allow compression.
> ACMSDI_NOMEMORY | Insufficient memory to complete requests.
> ACMSDI_NORMAL | Normal successful completion.
> ACMSDI_PENDING | Successful operation pending nonblocking completion. The final status is in the completion_status parameter.
> ACMSDI_PWDEXPIRED | Password has expired.
> ACMSDI_PWDEXPIRING | Password expiring in the number of hours specified in options array.
> ACMSDI_SIGNINACTV | Sign-in active.
> ACMSDI_SIGNOUTACTV | Sign-out active.
> ACMSDI_SRVDEAD | Node name is invalid, or TP Desktop Connector gateway is not running on the specified node, or the network link terminated.

Note #### 1 For nonblocking only, see Section 2.3. #### 1 For nonblocking only, see Section 2.3. Not applicable to forced nonblocking and will cause an error if supplied.

Previous | Next | Contents | Index