| Previous | Contents | Index |
acmsdi_write_msg (submitter_id,
msg _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: 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.
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
DIGITAL 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 DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide).
acmsdi_check_version (form_file,
version )
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.
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:
- Returns an OpenVMS failure status that cancels the ENABLE request.
- Sets a flag that causes the acmsdi_enable routine to terminate with a failure status.
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.
acmsdi_get_version (form_file,
version )
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.
Always returns SUCCESS status.
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 DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide.
| 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 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. |
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;
|
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.
acmsdi_complete_call (submitter_id,
completion _status,
[call_id],
[status_message],
[workspaces])
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.
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.
4.3 acmsdi_bind_enable_args
The client application can call this service whenever acmsdi_poll
returns ACMSDI_ENABLE_EXCH from the TP Desktop Connector gateway on the
OpenVMS system. This service retrieves the write-only arguments passed
from the TP Desktop client services. This is an optional call.
acmsdi_bind_enable_args (submitter_id,
file _specification,
form _specification,
form _version,
forms _print_file,
forms _language,
call _id)
submitter_id
Type: ACMSDI_SUBMITTER_ID
Access: read
Mechanism: by reference
The value returned by the acmsdi_sign_in service (see Section 2.11).file_specification
Type: char *
Access: write
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: write
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.form_version
Type: char *
Access: write
Mechanism: by reference
Twenty-four bytes containing the version number or date supplied by the acmsdi_get_version routine on the OpenVMS system. The argument provides for version checking by the client application. (The acmsdi_check_version is not available in a forced nonblocking session.)forms_print_file
Type: char *
Access: write
Mechanism: by reference
The DECforms specification for the user in ACMSUDF.DAT.forms_language
Type: char *
Access: write
Mechanism: by reference
The DECforms specification for the user in ACMSUDF.DAT.call_id
Type: ACMSDI_CALL_ID *
Access: write
Mechanism: by reference
A pointer to the call identification returned by the acmsdi_call_task service. To identify the original task call, compare this pointer with a reference pointer to the call identifier obtained by acmsdi_return_pointer.
The status values returned by the acmsdi_bind_enable_args procedure are described in Table 4-3.
Table 4-3 acmsdi_bind_enable_args Return Status Values Status Description ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_MIXEDMODE Not a forced nonblocking session. ACMSDI_NORMAL Normal successful completion. ACMSDI_WRONG_BIND Trying to bind arguments for an exchange that is not in progress.
4.4 acmsdi_bind_msg
The client application can call this service when acmsdi_poll returns
ACMSDI_TDMS_READ_EXCH (a TDMS Read exchange) or ACMSDI_TDMS_WRITE_EXCH
(a TDMS Write exchange) from the TP Desktop Gateway for ACMS on the
host OpenVMS system. It performs one of the following functions:
If the prompt or message text is being acquired, the text is truncated when the buffer supplied is not large enough to hold the entire text. If the buffer is larger than the text being acquired, the text is left-justified in the buffer and right-filled with blank characters.
This is an optional call, that is, you are not required to issue this call. However, if you do not issue this call you will not be able to process arguments received from the server or to send arguments back to the server.
acmsdi_bind_msg (submitter_id,
direction,
length,
text,
call _id)
submitter_id
Type: ACMSDI_SUBMITTER_ID
Access: read
Mechanism: by reference
The value returned by the acmsdi_sign_in service.direction
Type: short int
Access: read
Mechanism: by value
The value indicates which direction the text is being sent. A value of 1 indicates that the prompt text from a TDMS Read exchange or the message text from a TDMS Write exchange is being copied into the application's memory from ACMS. A value of 0 indicates that the message text for a TDMS Read exchange is being copied to ACMS from the application's memory.length
Type: short int
Access: read
Mechanism: by value
The length of the text being sent or the length of the buffer to receive the text; specifically one of the following:
- the length of the buffer in the application's memory which is to receive the prompt text for a TDMS Read exchange.
- the length of the message text being sent to ACMS for a TDMS Read exchange.
- the length of the buffer in the application's memory which is to receive the message text for a TDMS Write exchange.
text
Type: char
Access: read/write
Mechanism: by reference
The text string being sent to ACMS or the buffer which is to hold the text string being acquired from ACMS.call_id
Type: ACMSDI_CALL_ID *
Access: write
Mechanism: by reference
Pointer to the call identification returned by the acmsdi_call_task service. To identify the original task call, compare this pointer with a reference pointer to the call identifier obtained by acmsdi_return_pointer.
This function returns an int, which may be a 16-bit or 32-bit integer depending on the operating system. The value will be a valid TP Desktop Connector status code as defined in ACMSDI.H and described in Table 4-4
Table 4-4 acmsdi_bind_msg Return Status Values Status Description ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_MIXEDMODE Not a forced nonblocking session call. ACMSDI_NORMAL Normal successful completion. ACMSDI_WRONG_BIND Trying to bind arguments for an exchange that is not in progress.
4.5 acmsdi_bind_receive_args
The client application can call this service whenever an acmsdi_poll
returns ACMSDI_RECV_EXCH from the TP Desktop Connector gateway on the
OpenVMS system. This service retrieves the write-only arguments passed
from the TP Desktop client services. This provides the client
application with the receive record identifier and identifies the
appropriate set of forms records to send back to ACMS. See also
Section 4.6 for information on calls for receive forms records and
receive control text. This is an optional call.
acmsdi_bind_receive_args (submitter_id,
forms _session,
receive _record_identifier,
receive _record_count,
timeout,
call _id)
submitter_id
Type: ACMSDI_SUBMITTER_ID
Access: read
Mechanism: by reference
The submitter_id returned by the acmsdi_sign_in service.forms_session
Type: ACMSDI_FORMS_SESSION_ID
Access: write
Mechanism: by reference
An identification to associate the session with the form specified in the acmsdi_enable request (see Section 4.11).receive_record_identifier
Type: char *
Access: write
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: write
Mechanism: by reference
The number of receive record items sent from the ACMS task. The TP Desktop Connector writes the receive_record_count into this location.timeout
Type: short int
Access: write
Mechanism: by reference
A timeout value for user input processing sent from the ACMS task. TP Desktop Connector writes the timeout value into this location.call_id
Type: ACMSDI_CALL_ID *
Access: write
Mechanism: by reference
A pointer to the call identification returned by the acmsdi_call_task service. To identify the original task call, compare this pointer with a reference pointer to the call identifier obtained by acmsdi_return_pointer.
The status values returned by the acmsdi_bind_receive_args procedure are described in Table 4-5
Table 4-5 acmsdi_bind_receive_args Return Status Values Status Description ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_MIXEDMODE Not a forced nonblocking session call. ACMSDI_NORMAL Normal successful completion. ACMSDI_WRONG_BIND Trying to bind arguments for an exchange that is not in progress.
| Previous | Next | Contents | Index |