DIGITAL TP Desktop Connector
for ACMS
Client Services Reference Manual
Previous Contents Index

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

2.12 acmsdi_sign_out

TP Desktop Connector client programs call this service to terminate an active session with a ACMS system. To insure that all network links are properly shut down, the desktop client program calls the acmsdi_sign_out service before terminating.

Format

acmsdi_sign_out (submitter_id,
[completion_status],
[completion_routine], 1
[call_context])

Parameters

submitter_id

Type: ACMSDI_SUBMITTER_ID
Access: read
Mechanism: by reference
The submitter identification returned by the acmsdi_sign_in service.

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-7 for a list of the 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_out service are listed in Table 2-7.

Table 2-7 acmsdi_sign_out Return Status Values
Status Description
ACMSDI_CALLACTV Request is invalid while task call is active.
ACMSDI_INSUFPRM Insufficient parameters.
ACMSDI_INTERNAL Internal TP Desktop Connector error.
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_PENDING Successful operation pending nonblocking completion. The final status is in the completion_status parameter.
ACMSDI_SIGNINACTV Request is invalid while sign-in is active.
ACMSDI_SIGNOUTACTV Request is invalid while 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.

Note

1 For nonblocking only, see Section 2.3.

Previous Next Contents Index