| Previous | Contents | Index |
This chapter describes the interface between the TP Desktop Connector
Gateway for ACMS 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 for ACMS 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 DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide.
| Customer-Supplied Procedure | Description |
|---|---|
| acmsdi_disable | Services a DIGITAL 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 DIGITAL 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 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;\
}\
|
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 DIGITAL 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 for ACMS 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 for ACMS 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 Gateway for ACMSs, 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.
acmsdi_disable (forms_session,
call _id,
call _context)
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.
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 for ACMS on the OpenVMS system.
acmsdi_enable (submitter_id,
forms _session,
file _specification,
form _specification,
forms _print_file,
forms _language,
call _id,
call _context)
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 DIGITAL 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 DIGITAL 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.
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 for ACMS 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.
acmsdi_read_msg (submitter_id,
msg _text,
prompt _text,
call _id,
call _context)
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.
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 for ACMS on the OpenVMS system.
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)
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 DIGITAL 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).
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 for ACMS on the OpenVMS system.
acmsdi_request (submitter_id,
request _name,
workspace _count,
workspaces,
call _id,
call _context)
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.
The status values returned by the acmsdi_request procedure are described in Section 3.1.1.
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.
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)
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 DIGITAL 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).
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 for ACMS on the OpenVMS system.
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)
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 DIGITAL 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 DIGITAL 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).
The status values returned by the acmsdi_transceive procedure are described in Section 3.1.1.
| Previous | Next | Contents | Index |