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

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.

Chapter 3
Portable API Presentation Procedures

This chapter describes the interface between the TP Desktop Connector gateway and customer-written presentation procedures. It also describes the interfaces on portable clients for customer-written action routines to perform version checking.

3.1 Summary of Portable API Presentation Procedures

Presentation procedures are customer-written routines that the TP Desktop Connector gateway calls when an exchange step occurs in a ACMS task with either the FORM I/O or REQUEST I/O attribute. Table 3-1 summarizes the presentation procedures available in a nonblocking session. These are not applicable to a forced nonblocking session. For more information on presentation procedures, refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

Table 3-1 Summary of Portable API Presentation Procedures
Customer-Supplied Procedure Description
acmsdi_disable Services a Compaq DECforms disable request, which disables a form.
acmsdi_enable Services a DECforms enable request, which enables a form.
acmsdi_read_msg Services a TDMS Read exchange, which displays the prompt, if any, sent from the ACMS task, and acquires the text from the form's message field.
acmsdi_receive Services a DECforms receive request, which sends data from the form to the application program.
acmsdi_request Services a TDMS Request exchange, which displays a form and transfers data between a form and the application program.
acmsdi_send Services a DECforms send request, which sends data from the application program to the form.
acmsdi_transceive Services a DECforms transceive request, which combines the actions of a send and a receive.
acmsdi_write_msg Services a TDMS Write exchange, which displays the text sent from the form's message field or the ACMS task.

See Compaq TP Desktop Connector for ACMS Client Application Programming Guide for a description of sample client presentation procedures.

3.1.1 Return Status Values Expected from Presentation Procedures

The presentation procedure routines must return a long integer containing any valid OpenVMS status value, including DECforms, TDMS, and application-defined values. Return status values for nonblocking presentation procedures are returned using the acmsdi_complete_pp routine. The status value is passed to the ACMS Application Execution Controller (EXC) as the completion status for the exchange step. The EXC attempts to interpret the value as a standard OpenVMS status value. Unless the task definition for the exchange step specifies CONTINUE ON FAILURE, the EXC cancels the task for an error status returned.

The Compaq TP Desktop Connector kit provides include files that specify the return status values for DECforms and TDMS: FORMS.H and TDMS.H. If the return status values change, you can regenerate the include files with the command procedures, MAKE_FORMS_H.COM and MAKE_TDMS_H.COM, in the ACMSDI$EXAMPLES directory.

To handle errors, specify the exception-handler syntax in the task definition. To have a single ACMS application support both DECforms terminals and graphical desktop systems, code the task definition to check for a DECforms error status value.

3.1.2 ACMSDI_FORM_RECORD Structure and Macro Call

Defined in the ACMSDI.H file, the ACMSDI_FORM_RECORD type declares form records and shadow records passed to and from presentation procedures. The code in Example 3-1 defines the ACMSDI_FORM_RECORD type and a macro ACMSDI_INIT_FORM_RECORD to initialize the form record structure.

Example 3-1 Form Record Definition and Initialization Macro 

typedef struct { 
    int   data_length;          /** length of data record **/ 
    void *data_record;          /** pointer to data record **/ 
    int   shadow_length;        /** length of shadow record **/ 
    void *shadow_record;        /** pointer to shadow record **/ 
} ACMSDI_FORM_RECORD; 
 
#define ACMSDI_INIT_FORM_RECORD (record, data, shadow)\
{\
    record.data_length = sizeof(data);\
    record.data_record = &data;\
    record.shadow_length = sizeof(shadow);\
    record.shadow_record = &shadow;\
}\

3.1.3 Prototypes and Code for Presentation Procedures and Version Routines

The ACMSDI.H file contains function prototypes for the presentation procedures and action routines that your code supplies. The file PPSTUBS.C contains stub modules you can use for linking your application (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

3.2 Parameter Memory Allocation

The caller of a TP Desktop Connector service or 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 the presentation procedures, the desktop client program can expect that TP Desktop Connector software allocates memory for all the parameters passed in and for all workspaces before it calls these procedures.

3.3 Blocking and Nonblocking Usage

Like the portable TP Desktop Connector client services, presentation procedures can be either blocking or nonblocking. If the desktop client program supplies the completion_routine parameter in the acmsdi_call_task call, the service behaves in the nonblocking environment (see Section 2.3). In a nonblocking environment, presentation procedures must behave in a way consistent with nonblocking services.

3.3.1 Presentation Procedures in a Nonblocking Environment

When nonblocking services are in use, presentation procedures are written in two parts:

The TP Desktop Connector client services return exchange step data and status to the TP Desktop Connector gateway when the desktop client program calls the acmsdi_complete_pp service.

3.3.2 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 client/server pair. 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 gateway and nonblocking calls to interact with the other gateway.

3.4 acmsdi_disable

TP Desktop Connector services call this procedure for each active forms session for a desktop submitter whenever the TP Desktop Connector client program calls acmsdi_sign_out to sign the submitter out of the ACMS system.

Format

acmsdi_disable (forms_session,
call _id,
call _context)

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

call_id

Type: ACMSDI_CALL_ID
Access: read
Mechanism: by reference
The call identification used to complete the disable call when using nonblocking services. See the description of acmsdi_complete_pp ( Section 2.8).

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_sign_out() call.

Return Status

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

3.5 acmsdi_enable

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

Format

acmsdi_enable (submitter_id,
forms _session,
file _specification,
form _specification,
forms _print_file,
forms _language,
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 (see Section 2.11).

forms_session

Type: ACMSDI_FORMS_SESSION_ID
Access: write
Mechanism: by reference
An identification that associates the session with the submitter identification. This is a write parameter that customer-supplied presentation procedures can fill. Presentation procedures (acmsdi_send, acmsdi_receive, acmsdi_transceive, and acmsdi_disable) can use the forms_session parameter to associate the session with the form specified in the enable request. The TP Desktop Connector run-time system passes this parameter to subsequent requests to specify which form to use.

file_specification

Type: char *
Access: read
Mechanism: by reference
The form file specification from the ACMS task group definition. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide. for guidelines on specifying the form file specification.

form_specification

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

forms_print_file

Type: char *
Access: read
Mechanism: by reference
The DECforms specification for the user in ACMSUDF.DAT.

forms_language

Type: char *
Access: read
Mechanism: by reference
The DECforms specification for the user in ACMSUDF.DAT.

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.

Return Status

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

3.6 acmsdi_read_msg

TP Desktop Connector client services call this presentation procedure when a TDMS Read exchange is received from the TP Desktop Connector gateway on the host OpenVMS system. Its function is to display the prompt (if any) sent from the ACMS task and then to acquire the text from the form's Message Field to be returned to ACMS.

Format

acmsdi_read_msg (submitter_id,
msg _text,
prompt _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: write
Mechanism: by reference
A buffer into which the presentation procedure will write the text from the form's Message Field to be returned to the ACMS task. This is a C-style null-terminated string with a maximum length of 132 plus one for the null terminator.

prompt_text

Type: char
Access: read
Mechanism: by reference
Text to be displayed as a prompt to the terminal operator. This is a C-style null-terminated string with a maximum length of 132 plus one for the null terminator. There may be no prompt text to display in which case the length will be 0; that is, the null terminator will be in the first position.

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

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

Format

acmsdi_receive (forms_session,
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,
receive _record)

Parameters

forms_session

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

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.

receive_record

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

Return Status

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

3.8 acmsdi_request

TP Desktop Connector client services call this presentation procedure whenever a TDMS Request exchange is received from the TP Desktop Connector gateway on the OpenVMS system.

Format

acmsdi_request (submitter_id,
request _name,
workspace _count,
workspaces,
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 (see Section 2.11).

request_name

Type: char *
Access: read
Mechanism: by reference
The name of the TDMS request specified in the ACMS task.

workspace_count

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

workspaces

Type: ACMSDI_WORKSPACE array
Access: read/write
Mechanism: by reference
The workspace data sent from the ACMS task. One or more optional workspace arguments can be sent from the task (see Section 2.4).

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.

Return Status

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

Previous Next Contents Index