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

Chapter 2
TP Desktop Connector Portable API Client Services

This chapter describes the DIGITAL TP Desktop Connector portable API client services available on the following desktop systems:

2.1 Summary of Portable API Client Services

Similar to the DIGITAL ACMS Service Interface (SI) routines provided on the DIGITAL OpenVMS host, the TP Desktop Connector portable API client services allow you to write a desktop client program on desktop systems without extensive knowledge of network communications. Table 2-1 summarizes the TP Desktop Connector portable API client services.

Table 2-1 Summary of Portable API Client Services
Service Description
acmsdi_call_task Sends a request to the TP Desktop Connector gateway to start a task in a ACMS application. The TP Desktop Connector client service is either blocking or nonblocking. Exchange step processing during the task is handled by the TP Desktop Connector gateway calling customer-written generic presentation procedures in the desktop client program.
acmsdi_cancel Used by nonblocking services only. Called by a desktop application to cancel a currently active ACMS task.
acmsdi_complete_pp Used by nonblocking environments only. Sends a response from a presentation procedure request to the TP Desktop Connector gateway.
acmsdi_dispatch_message Used by nonblocking environments only. Checks for and processes messages from the TP Desktop Connector gateway. If no messages have been received from the gateway, acmsdi_dispatch_message returns immediately.
acmsdi_return_pointer Used by client programs written in Microsoft Visual Basic to create the workspace array for ACMS_CALL_TASK. Also used in the forced nonblocking environment to obtain reference pointers.
acmsdi_sign_in Requests the TP Desktop Connector gateway to sign a user running a desktop client program in to a ACMS system.
acmsdi_sign_out Requests the TP Desktop Connector gateway to sign a desktop client program out of a ACMS system.

These calls use the C-language argument-passing standards. Character strings are NULL-terminated and passed by reference. Workspaces are passed as structures composed of a length and a pointer field.

2.2 Parameter Memory Allocation

The caller of a TP Desktop Connector client service or a presentation procedure is responsible for allocating the memory for the parameters of that routine. For calls to the TP Desktop Connector client services, the desktop client program must allocate the memory for all parameters passed in, for example, submitter_id and call_context. For calls to the presentation procedures, the TP Desktop Connector client services allocate memory for all the parameters passed and for all workspaces.

2.3 Nonblocking Service Usage

The acmsdi_sign_in, acmsdi_call_task, and acmsdi_sign_out services can be either blocking, nonblocking, or forced nonblocking. If the desktop client program supplies the completion_routine parameter to the TP Desktop Connector client service, the service behaves in the nonblocking fashion. The TP Desktop Connector client service returns control to the desktop client program as soon as a request is sent to the TP Desktop Connector gateway. If the request is sent to the gateway successfully, the TP Desktop Connector client service returns the ACMSDI_PENDING status. If a status other than ACMSDI_PENDING is returned, the completion routine is not called.

If nonblocking calls are active, use the acmsdi_dispatch_message service to poll for responses from the TP Desktop Connector gateway. When a response is received, acmsdi_dispatch_message calls the appropriate customer-supplied completion routine. If the desktop client program supplies the completion_status parameter on the initial TP Desktop Connector client service call, the TP Desktop Connector client services set the completion_status to the final completion status for the service and immediately call the completion routine. See DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide for descriptions and examples.

The forced nonblocking services extend the portable API to support both exchange steps and nonblocking execution of task calls for development tools that do not support pointer data types or whose memory management routines relocate data. You can specify a forced nonblocking session with the acmsdi_sign_in service by using the ACMSDI_OPTION, ACMSDI_OPT_NONBLK. Do not specify a completion routine in a forced nonblocking session as this will result in an error. See Chapter 4 for more information.

2.3.1 Nonblocking and Blocking Restriction

All calls using the same desktop client program and TP Desktop Connector gateway connection must be either blocking, nonblocking, or forced nonblocking. These types of service calls cannot be mixed for a desktop client program and TP Desktop Connector gateway pair. See Table 1-5 for the list of service calls available for each type of session. If a desktop client program connects to two different TP Desktop Connector gateways, it can mix service call types, using blocking calls to interact with one TP Desktop Connector gateway and nonblocking calls to interact with the other TP Desktop Connector gateway.

2.3.2 Completion Routine Format

For nonblocking service requests, the acmsdi_dispatch_message service calls the customer-supplied completion routine when a response is received from the TP Desktop Connector gateway. The completion routine has the following format:

void completion_routine (call_context)

Parameters

call_context

Type: void *
Access: read
Mechanism: by value
Supplies application-specific context to the completion routine. If specified on acmsdi_call_task, acmsdi_sign_in, acmsdi_cancel, or acmsdi_sign_out service, the call_context is passed by the TP Desktop Connector client services to the completion routine.

Return Status

The customer-supplied completion routine does not return a status value.

2.4 Workspace Data Structures

This section describes the following workspace data structures:

2.4.1 ACMSDI_WORKSPACE Structure and Initialization Macro

Defined in the ACMSDI.H file, the ACMSDI_WORKSPACE type declares workspaces passed to tasks using the acmsdi_call_task service and workspaces passed from tasks to acmsdi_request presentation procedures.

The code in Example 2-1 defines the ACMSDI_WORKSPACE type and an ACMSDI_INIT_WORKSPACE macro used to initialize the workspace structure.

Example 2-1 Workspace Structure Definition and Initialization 

typedef struct { 
    unsigned int length;        /** length of workspace **/ 
    void *data;                 /** pointer to workspace **/ 
} ACMSDI_WORKSPACE; 
   .
   .
   .
#define ACMSDI_INIT_WORKSPACE(_wksp, _rec)\
{\
    _wksp.length = sizeof(_rec);\
    _wksp.record = &(_rec);\
}

To pass more than one workspace to a procedure, use an array of the ACMSDI_WORKSPACE structures. Example 2-2 passes two workspaces.

Example 2-2 Passing Workspaces to a Procedure 

ACMSDI_WORKSPACE  wksp_array[2]; 
 
struct { 
    char ctrl_key[5]; 
    char error_message[80]; 
} control_wksp; 
 
struct { 
    int id_number; 
    char first_name[15]; 
    char last_name[25]; 
} employee_record; 
 
    ACMSDI_INIT_WORKSPACE (wksp_array[0], control_wksp); 
    ACMSDI_INIT_WORKSPACE (wksp_array[1], employee_record);

The array wksp_array is defined with two elements of type ACMSDI_WORKSPACE. The structure definitions control_wksp and employee_record define the elements of the array. The two macro ACMSDI_INIT_WORKSPACE calls initialize the array of structures.

2.4.2 ACMSDI_WORKSPACE_OPT Structure

The ACMSDI.H file contains the definition of the ACMSDI_WORKSPACE_OPT type you use to declare workspaces passed to tasks using the ACMSDI_CALL_TASK service. You can use ACMSDI_WORKSPACE_OPT instead of ACMSDI_WORKSPACE. Only task calls that use the ACMSDI_TASK_OPTIONS flag to indicate unidirectional workspaces can use this structure. Example 2-3 shows the ACMSDI_WORKSPACE_OPT type definition and the definition of a macro to initialize the workspace structure.

Example 2-3 ACMSDI_WORKSPACE_OPT Type Definition 

#define ACMSDI_ACCESS_READ   '1'     /* read-only access */ 
#define ACMSDI_ACCESS_WRITE  '2'    /* write-only access */ 
#define ACMSDI_ACCESS_MODIFY '3'   /* modify (read and write) */ 
   .
   .
   .
typedef char ACMSDI_ACCESS_TYPE; 
typedef struct { 
    unsigned int length; 
    ACMSDI_ACCESS_TYPE access; 
    void *data; 
} ACMSDI_WORKSPACE_OPT; 
   .
   .
   .
#define ACMSDI_INIT_WORKSPACE_OPT(_wksp, _rec, _access)\
{\
   _wksp.length  = sizeof(_rec);\
   _wksp.access  = _access;\
   _wksp.data    = &(_rec);\
}

To pass more than one workspace to a procedure, use an array of the type ACMSDI_WORKSPACE_OPT. Example 2-4 passes two workspaces.

Example 2-4 Passing Two Workspaces 

ACMSDI_WORKSPACE_OPT wksp_array[2]; 
 
struct { 
    char ctrl_key[5]; 
    char error_message[80]; 
} control_wksp; 
struct { 
    int id_number; 
    char first_name[15]; 
    char last_name[25]; 
} employee_record; 
 
    ACMSDI_INIT_WORKSPACE_OPT (wksp_array[0], control_wksp, ACMSDI_ACCESS_READ); 
    ACMSDI_INIT_WORKSPACE_OPT (wksp_array[1], employee_record, ACMSDI_ACCESS_WRITE);

2.4.3 ACMSDI_WORKSPACE_BIND Structure

The ACMSDI_WORKSPACE_BIND structure locates workspace buffers and specifies the sizes of workspaces during acmsdi_bind_request_wksps operations. Like the ACMSDI_FORM_RECORD_BIND structure, the ACMSDI_WORKSPACE_BIND structure contains a field where the length of the TDMS exchange step workspace is returned. If the length differs from the buffer length, TP Desktop Connector truncates the resultant workspaces or buffers are not completely filled.

The following example shows the C language definition of this structure as it appears in the acmsdi.h file: 


 typedef struct { 
   unsigned int buffer_len;            /* length of caller's buffer */ 
   unsigned int wksp_len;              /* actual length of the workspace */ 
   void          *data; 
 } ACMSDI_WORKSPACE_BIND;

2.4.4 ACMSDI_FORM_RECORD_BIND Structure

The ACMSDI_FORM_RECORD_BIND structure locates form record buffers and specifies their sizes during acmsdi_bind_send_recs and acmsdi_bind_receive_recs operations. ACMSDI_FORM_RECORD_BIND serves the same purpose as ACMSDI_FORM_RECORD with one additional feature. It contains an additional field, rec_len, with which the TP Desktop Connector client services return the actual length of the form record as it is returned from the back-end application. You can compare this length against the client application buffer length to see if the buffer is large enough, too large, or exactly the right size to contain the form record. If the buffer size is too small, the form record is truncated to fit the buffer. If the buffer size is too large, the buffer is not completely filled.

You can use the ACMSDI_FORM_RECORD_BIND structure to locate send control text and receive control text buffers. Both acmsdi_bind_send_args and acmsdi_bind_receive_args services contain arguments to specify whether or not to transfer control text. If you specify to transfer control text, the following rules apply:

The following example shows the C language definition of this structure as it appears in the acmsdi.h file: 


 typedef struct { 
    unsigned int buffer_len;           /* length of caller's record buffer */ 
    unsigned int rec_len;              /* actual length of the form record */ 
    void          *data_record;        
    unsigned int shadow_buffer_len;    /* length of caller's shadow buffer */ 
    unsigned int shadow_rec_len;       /* actual length of shadow record */ 
    void          *shadow_record; 
 } ACMSDI_FORM_RECORD_BIND;

2.5 ACMSDI_CALL_OPTION Union Structure

ACMSDI_CALL_OPTION union is a parameter that is passed to the ACMSDI_CALL_TASK service to enable TP Desktop Connector functions, such as optimizing unidirectional workspace traffic on the call to the acmsdi_call_task client service. The include file ACMSDI.H contains the definition for the ACMSDI_CALL_OPTION union.

ACMSDI_CALL_OPTION contains several structures with the option variables, whose values determine the type of option being selected. Specify the values for the option variable using the following constants defined in the ACMSDI.H include file:
Option Description
ACMSDI_CALL_OPT_END_LIST Ends options list
ACMSDI_CALL_OPT_OPTIMIZE_WKSPS Enables unidirectional workspace optimization
ACMSDI_CALL_OPT_ENABLE Pointer to enable function
ACMSDI_CALL_OPT_DISABLE Pointer to disable function
ACMSDI_CALL_OPT_SEND Pointer to send function
ACMSDI_CALL_OPT_RECEIVE Pointer to receive function
ACMSDI_CALL_OPT_TDMS_READ Pointer to TDMS read function
ACMSDI_CALL_OPT_TDMS_WRITE Pointer to TDMS write function
ACMSDI_CALL_OPT_TRANSCEIVE Pointer to transceive function
ACMSDI_CALL_OPT_REQUEST Pointer to TDMS request function
ACMSDI_CALL_OPT_CHECK_VERSION Version checking routine
ACMSDI_CALL_OPT_PASS_TID TID of distributed transaction
ACMSDI_CALL_OPT_COMPRESS_WKSPS Activate workspace compression

To select options:

  1. Declare an array of at least two elements of the type ACMSDI_CALL_OPTION.
  2. Specify in the option variable the name for the structure being used.
  3. Specify the address for the malloc routine or password expiring buffer, if these options are being used.
  4. End an options list by assigning ACMSDI_CALL_OPT_END_LIST to the option variable in the last array element.

The following example shows the initialization of an options list used to enable unidirectional workspace handling: 


ACMSDI_CALL_OPTION call_options[2]; 
 
    call_options[0].option = ACMSDI_CALL_OPT_OPTIMIZE_WKSPS; 
    call_options[1].option = ACMSDI_CALL_OPT_END_LIST;

Caution

Use the ACMSDI_CALL_OPT_OPTIMIZE_WKSPS option and the ACMSDI_WORKSPACE_OPT type definition together to optimize unidirectional workspace traffic. Do not use one without the other. The acmsdi_call_task client service uses the presence or absence of the workspace optimization option to decide which data type has been passed in the workspaces argument. Using either one without the other produces unpredictable results.

2.5.1 ACMSDI_OPTION Array

ACMSDI_OPTION array is a parameter that is passed to the ACMSDI_SIGN_IN service to enable TP Desktop Connector functions, such as enabling password expiration checking on the call to acmsdi_call_task client service. The include file ACMSDI.H contains the definition for the ACMSDI_OPTION array.

The ACMSDI_OPTION array is a union containing multiple structures and an option variable, the value of which defines the type of option being selected. Specify the values for the option variable using the following constants defined in the include file ACMSDI.H:
Constant Description
ACMSDI_OPT_CHECK_VERSION Enables version checking
ACMSDI_OPT_COMMID Supplies communications device id or TCP/IP comm port
ACMSDI_OPT_END_LIST Ends options list
ACMSDI_OPT_FREE_ROUTINE Enables user-defined memory deallocation
ACMSDI_OPT_MALLOC_ROUTINE Enables user-defined memory allocation
ACMSDI_OPT_NONBLK Enables a forced nonblocking session
ACMSDI_OPT_PWD_EXPIRING Enables checking for passwords that are about to expire

To select options:

  1. Declare an array of at least two elements of the type ACMSDI_OPTION.
  2. Specify in the option variable the name tag for the structure being used.
  3. End an options list by assigning ACMSDI_OPT_END_LIST to the option variable in the last array element.

Example 2-5 initializes an options list to enable version checking, user-defined memory allocation, and password expiration checking.

Example 2-5 Initializing an Options List 

void *my_malloc_routine(int size); 
long pwd_exp_buffer; 
void my_free_routine(void *ptr); 
ACMSDI_OPTION options[5]; 
 
    options[0].option = ACMSDI_OPT_CHECK_VERSION; 
    options[1].option = ACMSDI_OPT_MALLOC_ROUTINE; 
    options[1].malloc_routine.address = my_malloc_routine; 
    options[2].option = ACMSDI_OPT_FREE_ROUTINE; 
    options[2].free_routine.address = my_free_routine; 
    options[3].option = ACMSDI_OPT_PWD_EXPIRING; 
    options[3].pwd_expiring_hrs.address = &pwd_exp_buffer; 
    options[4].option = ACMSDI_OPT_END_LIST;

You can provide the TCP/IP port number during sign-in by using the ACMSDI_OPT_COMMID option. Example 2-6 shows how to do this in C.

Note
This option is usable with forced nonblocking calls only.

Example 2-6 Dynamically Specifying a TCP/IP Port Identifier 

int status; 
ACMSDI_SUBMITTER_ID subm_id; 
long tcpip_port = 1000; 
ACMSDI_OPTION options[2]; 
options[0].option = ACMSDI_OPT_COMMID; 
options[0].CommID = tcpip_port; 
options[1].option = ACMSDI_OPT_END_LIST; 
 
status = acmsdi_sign_in ("N2001", /* ACMS Desktop Gateway node */ 
                         "HAL", /* username */ 
                         "HELLO_DAVE", /* password */ 
                          options, /* sign in options */ 
                          &subm_id, /* submitter id */ 
                          0, 0, 0);

If the environmental variable ACMSDI_TCPIP_PORT_host_node is defined, the option specified on the acmsdi_sign_in call takes precedence. If neither the environmental variable nor the sign-in option is specified, the default TCP/IP port number, 1023, is used.

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.

Previous Next Contents Index