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

• Compaq Tru64 Unix
• DOS
• Microsoft Windows
• Microsoft Windows 95
• Microsoft Windows NT
• Compaq OpenVMS VAX
• Compaq OpenVMS Alpha
• SCO UNIX

Similar to the Compaq ACMS Service Interface (SI) routines provided on the Compaq 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 Compaq 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:

• ACMSDI_WORKSPACE
• ACMSDI_WORKSPACE_OPT
• ACMSDI_WORKSPACE_BIND
• ACMSDI_FORM_RECORD_BIND

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:

• ACMSDI_FORM_RECORD_BIND structure for the control text must be the first one in the array of such structures passed on the call.
• After the call completes, the record length field (rec_len) contains the send control text count or the receive control text count instead of the length of the record.

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.

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.

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.