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