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

3.9 acmsdi_send

 TP Desktop Connector client services call this presentation procedure whenever a DECforms SEND request is received from the TP Desktop Connector gateway on the OpenVMS system.

Format

acmsdi_send (forms_session,
send _record_identifier,
send _record_count,
receive _control_text,
receive _control_text_count,
send _control_text,
send _control_text_count,
timeout,
call _id,
call _context,
send _record)

Parameters

forms_session

Type: ACMSDI_FORMS_SESSION_ID
Access: read
Mechanism: by reference
An identification that associates the session with the form specified in the acmsdi_enable request (see Section 3.5).

send_record_identifier

Type: char *
Access: read
Mechanism: by reference
The form record name or record list name specified in the SEND request in the ACMS task. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form name.

send_record_count

Type: long int
Access: read
Mechanism: by value
The number of send record items sent from the ACMS task.

receive_control_text

Type: char *
Access: write
Mechanism: by reference
A 25-character string that the customer-supplied request can use to return receive control text.

receive_control_text_count

Type: long int
Access: write
Mechanism: by reference
The number of receive control text items that the customer-supplied request returns.

send_control_text

Type: char *
Access: read
Mechanism: by reference
Send control text sent from the ACMS task.

send_control_text_count

Type: long int
Access: read
Mechanism: by value
The number of send control text items sent from the ACMS task.

timeout

Type: short int
Access: read
Mechanism: by value
A timeout value for user input processing, sent from the ACMS task.

call_id

Type: ACMSDI_CALL_ID
Access: read
Mechanism: by reference
The call identification returned by the acmsdi_call_task service.

call_context

Type: void *
Access: read
Mechanism: by value
Application-specific context for the call. This is the same context that was passed by the application to the acmsdi_call_task() call.

send_record

Type: ACMSDI_FORM_RECORD array
Access: read
Mechanism: by reference
An array of ACMSDI_FORM_RECORD structures pointing to buffers containing application data and shadow records sent from the ACMS task (see Section 3.1.2).

Return Status

The status values returned by the acmsdi_send procedure are described in Section 3.1.1.

3.10 acmsdi_transceive

TP Desktop Connector client services call this presentation procedure whenever a DECforms TRANSCEIVE request is received from the TP Desktop Connector gateway on the OpenVMS system.

Format

acmsdi_transceive (forms_session,
send _record_identifier,
send _record_count,
receive _record_identifier,
receive _record_count,
receive _control_text,
receive _control_text_count,
send _control_text,
send _control_text_count,
timeout,
call _id,
call _context,
send _record,
receive _record)

Parameters

forms_session

Type: ACMSDI_FORMS_SESSION_ID
Access: read
Mechanism: by reference
An identification that associates the session with the form specified in the acmsdi_enable request (see Section 3.5).

send_record_identifier

Type: char *
Access: read
Mechanism: by reference
The form record name or record list name specified in the SEND request in the ACMS task. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form name.

send_record_count

Type: long int
Access: read
Mechanism: by value
The number of send record items sent from the ACMS task.

receive_record_identifier

Type: char *
Access: read
Mechanism: by reference
The form record name or record list name specified in the RECEIVE request in the ACMS task. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form name.

receive_record_count

Type: long int
Access: read
Mechanism: by value
The number of receive record items sent from the ACMS task.

receive_control_text

Type: char *
Access: write
Mechanism: by reference
A 25-character string that the customer-supplied request can use to return receive control text.

receive_control_text_count

Type: long int
Access: write
Mechanism: by reference
The number of receive control text items that the customer-supplied request returns.

send_control_text

Type: char *
Access: read
Mechanism: by reference
Send control text sent from the ACMS task.

send_control_text_count

Type: long int
Access: read
Mechanism: by value
The number of send control text items sent from the ACMS task.

timeout

Type: short int
Access: read
Mechanism: by value
A timeout value for user input processing, sent from the ACMS task.

call_id

Type: ACMSDI_CALL_ID
Access: read
Mechanism: by reference
The call identification returned by the acmsdi_call_task service.

call_context

Type: void *
Access: read
Mechanism: by value
Application-specific context for the call. This is the same context that was passed by the application to the acmsdi_call_task() call.

send_record

Type: ACMSDI_FORM_RECORD array
Access: read
Mechanism: by reference
An array of ACMSDI_FORM_RECORD structures pointing to buffers containing application data and shadow records sent from the ACMS task (see Section 3.1.2).

receive_record

Type: ACMSDI_FORM_RECORD array
Access: write
Mechanism: by reference
An array of ACMSDI_FORM_RECORD structures pointing to buffers to receive application data and shadow records from the request (see Section 3.1.2).

Return Status

The status values returned by the acmsdi_transceive procedure are described in Section 3.1.1.

3.11 acmsdi_write_msg

TP Desktop Connector client services call this presentation procedure when a TDMS Write exchange is received from the TP Desktop Connector gateway on the host OpenVMS system. Its function is to display the message text sent from the ACMS task in the form's Message Field.

Format

acmsdi_write_msg (submitter_id,
msg _text,
call _id,
call _context)

Parameters

submitter_id

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

msg_text

Type: char
Access: read
Mechanism: by reference
Text to be displayed in the form's Message Field. This is a C-style null-terminated string with a maximum length of 132 plus one for the null terminator.

call_id

Type: ACMSDI_CALL_ID
Access: read
Mechanism: by reference
The call identification returned by the acmsdi_call_task service which initiated the ACMS task associated with this exchange.

call_context

Type: void *
Access: read
Mechanism: by value
Application-specific context for the call. This is the same context that was passed by the application to the acmsdi_call_task service which initiated the ACMS task associated with this exchange.

Return Status

This function returns a ps32, defined in ACMSDI.H to be equivalent to a signed 32-bit integer. The value must be a valid TDMS status code. Valid TDMS statuses are defined in TDMS.H.

3.12 Version-Checking Routines

The following sections describe the version-checking routines. Version checking is supported on systems using FORM I/O tasks (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide).

3.12.1 acmsdi_check_version

 TP Desktop Connector client services call this routine whenever they receive an ENABLE request from the TP Desktop Connector gateway. The action routine can check the version string passed from the acmsdi_get_version routine on the submitter node and notify the desktop user of any inconsistency.

You request version checking during a sign-in (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide).

Format

acmsdi_check_version (form_file,
version )

Parameters

form_file

Type: char *
Access: read
Mechanism: by reference
Specification of a form file or a request library from the ACMS task group definition.

version

Type: char *
Access: read
Mechanism: by reference
Twenty-four bytes containing the version number or date supplied by the acmsdi_get_version routine on the OpenVMS system.

Return Status

The TP Desktop Connector service checks the status value returned and expects a valid OpenVMS status. If a failure status is returned, the TP Desktop Connector run-time system terminates the ENABLE request.

If the version-checking routine determines that software is not synchronized, it does one of the following:

3.12.2 acmsdi_get_version

The TP Desktop Connector gateway calls this routine on the OpenVMS system whenever it receives an ENABLE request from the EXC. The action routine can return a version string that is then passed to the desktop client program, allowing a version comparison at the desktop system.

This service can also be used in a forced nonblocking environment, see Section 4.3. On a PC, version checking occurs during enable processing.

Format

acmsdi_get_version (form_file,
version )

Parameters

form_file

Type: char *
Access: read
Mechanism: by reference
Form file or request library specification from the ACMS task group definition.

version

Type: char *
Access: write
Mechanism: by reference
Twenty-four bytes in which the routine writes the version number or date associated with the specified form file. The version parameter is passed to the desktop client program to be checked in the acmsdi_check_version routine.

Return Status

Always returns SUCCESS status.

Chapter 4
Forced Nonblocking Client Services

This chapter describes the forced nonblocking interface between the TP Desktop Connector gateway and customer-written procedures.

4.1 Summary of Forced Nonblocking Procedures

Forced nonblocking client services extend the Portable API to support development tools that do not provide for callbacks, data pointers or consistent memory locations for data. (Such tools include Visual Basic and others.) You create a forced nonblocking session when you specify the ACMSDI_OPTION, ACMSDI_OPT_NONBLK, with the acmsdi_sign_in service and do not supply a completion address. In this session, all calls are nonblocking. Table 4-1 summarizes the forced nonblocking calls to the TP Desktop Connector API. For more information on forced nonblocking calls, refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

Table 4-1 Summary of Forced Nonblocking Procedures
Customer-Supplied Procedure Description
acmsdi_complete_call Returns the completion status. Can also provide the ACMS status message and task argument workspaces.
acmsdi_bind_enable_args Retrieves write-only arguments in an enable exchange step request.
acmsdi_bind_enable_args Retrieves write-only arguments in an enable exchange step request.
acmsdi_bind_msg Sends or acquires the message text in TDMS Read or Write exchanges, respectively, or acquires the prompt text of a TDMS Read exchange.
acmsdi_bind_receive_recs Services receive and transceive exchange steps, which send data from the desktop client to the TP Desktop Connector gateway.
acmsdi_bind_request_args Provides the client application with the request name and identifies the set of workspaces in a TDMS request exchange step.
acmsdi_bind_request_wksps Services a TDMS exchange step, which transfers data between a desktop client and the TP Desktop Connector gateway.
acmsdi_bind_send_args Provides the client application with the send record identifier and identifies the records to be received in a send exchange step.
acmsdi_bind_send_recs Services send and transceive exchange steps, which send data from the TP Desktop Connector gateway to the desktop client.
acmsdi_bind_session_id Sends the forms session identifier to the TP Desktop Connector gateway during an enable exchange step.
acmsdi_bind_transceive_args Provides the client application with the send and receive record identifiers and identifies the records to be passed in a transceive exchange step.
acmsdi_poll Returns the message type of a message from the back end and a pointer to the call context from the client application.

4.1.1 ACMSDI_FORM_RECORD_BIND Structure

Defined in the ACMSDI.H and ACMSDI.BAS files, the ACMSDI_FORM_RECORD type declares form records and shadow records transferred. The code in Example 4-1 defines the ACMSDI_FORM_RECORD_BIND type for the C language.

Example 4-1 Form Record Definition 

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;                 /** pointer to data record **/ 
   unsigned int   shadow_buffer_len;  /** length of callers shadow buffer  **/ 
   unsigned int   shadow_rec_len;     /** actual length of shadow record **/ 
   void *shadow_record;               /** pointer to shadow record **/ 
} ACMSDI_FORM_RECORD_BIND;

4.1.2 ACMSDI_WORKSPACE_BIND Structure

Defined in the ACMSDI.H file, the ACMSDI_WORKSPACE_BIND 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 4-2 defines the ACMSDI_WORKSPACE_BIND type structure.

Example 4-2 Workspace Structure Definition 

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

4.2 acmsdi_complete_call

The acmsdi_complete_call service is a required call that obtains completion arguments for acsmdi_call_task, acsmdi_sign_in, acmsdi_sign_out, and acmsdi_cancel services. When acmsdi_poll detects completion, acmsdi_complete_call can obtain the completion status for these services. The acmsdi_complete_call can also obtain the ACMS status message and task argument workspaces sent from the back end for the acmsdi_call_task service.

Format

acmsdi_complete_call (submitter_id,
completion _status,
[call_id],
[status_message],
[workspaces])

Parameters

submitter_id

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

completion_status

Type: int
Access: write
Mechanism: by reference
The final status of the TP Desktop Connector client service. When the service completes, the completion_status parameter contains the final status. For the list of return status values, see Table 4-2.

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.

call_id

Type: ACMSDI_CALL_ID *
Access: read
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. This parameter is required when completing an acmsdi_call_task service.

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. You use this parameter only for the acmsdi_call_task service completion.

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.

workspaces

Type: ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OPT array
Access: write
Mechanism: by reference
One or more optional workspaces passed to the application from the back end. 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.

Because buffers may have been relocated by memory management, workspace pointers in the structures must be renewed using the acmsdi_return_pointer call just prior to issuing acmsdi_complete_call.

You use this parameter only for the acmsdi_call_task service completion.

Return Status

The status values returned by the acmsdi_complete_call procedure are described in Table 4-2.

Table 4-2 acmsdi_complete_call Return Status Values
Status Description
ACMSDI_EXCHACTV Request is invalid while exchange step processing is active.
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_MIXEDMODE Not a forced nonblocking session.
ACMSDI_NORMAL Normal successful completion.
ACMSDI_WRONG_STATE Session is in the wrong state for this call.

Previous Next Contents Index