Summary of Contents for Compaq TP Desktop Connector AA–PVNFG–TE
Page 1
Compaq TP Desktop Connector for ACMS Client Services Reference Manual Order Number: AA–PVNFG–TE May 2002 This manual describes the services and commands needed to create and maintain TP Desktop Connector client programs that use the portable API. Revision Update Information: This is a revised manual.
Page 2
Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license. Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice.
OpenVMS based system management service. Chapter 6 Lists the data compression monitor commands. Appendix A Lists the Compaq ACMS system status values that can be returned in the err2 parameter. Related Documents For information on developing Compaq ACMS applications, refer to the following manuals: •...
Page 8
Provides a high-level discussion and examples of the activities to develop, install, and run a complete application. If you are new to programming with ACMS software, Compaq recommends reading the following books before using the Compaq TP Desktop Connector for ACMS product: •...
Page 9
Conventions This guide uses the following conventions and symbols: TP Desktop Connector Refers to the Compaq TP Desktop Connector for ACMS software. In examples, user input is highlighted with bold type. User Input The dollar sign indicates a generic command line prompt.
Page 10
italics Italics are used for emphasis and for parameters in text. Titles of manuals are also italicized. In format descriptions, square brackets surround a choice of options; select none, one, several, or all of the choices. A vertical ellipsis in an example means that information not directly related to the example has been omitted.
Service Format This chapter describes the format and elements of the service descriptions provided in following chapters. This chapter also provides a list of the services and the appropriate session environments in which each service may be used. 1.1 Routine Names The TP Desktop Connector service names and OpenVMS action routines are shown in C-language format.
1.3.1 Type Entry Table 1–2 lists the C-language data types used in the TP Desktop Connector services. Table 1–2 Parameter Data Types Data Type Description ACMSDI_CALL_ID Identification returned by the acmsdi_call_task service ACMSDI_FORM_RECORD Structure defined in the ACMSDI.H include file (see Section 3.1.2) ACMSDI_FORM_RECORD_ Structure defined in the ACMSDI.H and...
Table 1–2 (Cont.) Parameter Data Types Data Type Description longword 32-bit unsigned integer Longword pointer to data buffer short Synonym for short int short int 16-bit signed integer unsigned long int 32-bit unsigned integer void * Pointer to object of unknown type 1.3.2 Access Access describes the way in which the called routine accesses the data specified by the parameter.
Table 1–4 Parameter-Passing Mechanisms Mechanism Description By value The parameter contains a copy of the data to be used by the routine. By reference The parameter contains the address of the data to be used by the routine. The parameter is a pointer to the data. Because C supports only call by value, write parameters other than arrays and structures must be passed as pointers.
These session environments are explained in more depth in Chapter 2 and in Compaq TP Desktop Connector for ACMS Client Application Programming Guide. Table 1–5 lists the services and indicates the session environments in which you can use each call.
Page 16
Table 1–5 (Cont.) Matrix of Services and Environments Service Availability within Environment Blocking Nonblocking Forced Nonblocking acmsdi_bind_receive_args See description in Section 4.5 acmsdi_bind_transceive_args See description in Section 4.12 acmsdi_bind_msg See description in Section 4.4 acmsdi_bind_request_args See description in Section 4.7 acmsdi_bind_session_id See description in Section 4.11 acmsdi_bind_send_recs...
Page 17
Table 1–5 (Cont.) Matrix of Services and Environments Service Availability within Environment Blocking Nonblocking Forced Nonblocking Callbacks acmsdi_transceive See description in Section 3.10 acmsdi_write_msg See description in Section 3.11 acmsdi_check_version See description in Section 3.12.1 acmsdi_get_version(back end) See description in Section 3.12.2 Service Format 1–7...
Compaq Tru64 UNIX 2.1 Summary of Portable API Client Services 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 (Cont.) Summary of Portable API Client Services Service Description acmsdi_complete_pp Used by nonblocking environments only. Sends a response from a presentation procedure request to the TP Desktop Connector gateway. acmsdi_dispatch_ Used by nonblocking environments only. Checks for and message processes messages from the TP Desktop Connector gateway.
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...
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.
Page 23
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.
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.
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: •...
Page 27
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...
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.
Page 29
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.
Page 30
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 */...
acmsdi_call_task 2.6 acmsdi_call_task TP Desktop Connector client programs call this service to execute a task in a ACMS application. Format acmsdi_call_task (submitter_id, [call_options], task_name, application_name, selection_string, status_message, workspace_count, [workspaces], [call_id], [completion_status], [completion_routine], [call_context]) Parameters submitter_id Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The submitter_id returned by the acmsdi_sign_in service.
Page 32
acmsdi_call_task task_name Type: char * Access: read Mechanism: by reference The name of the task to execute. Maximum length is 31. application_name Type: char * Access: read Mechanism: by reference The specification of a ACMS application in which the task resides. The application name must be a valid application specification on the submitter node.
Page 33
acmsdi_call_task workspace_count Type: long int Access: read Mechanism: by value The decimal number of workspaces being passed to the task. workspaces Type: ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OPT array Access: read/write Mechanism: by reference One or more optional workspaces to be passed to the task. You need to typecast your array to void *.
acmsdi_call_task completion_routine Type: function address Access: read Mechanism: by value Address of a function to be called when the service completes. The completion_ routine is called by the acmsdi_dispatch_message service when the End of " Task message is received from the TP Desktop Connector gateway. "...
Page 35
acmsdi_call_task Table 2–2 (Cont.) acmsdi_call_task Return Status Values Status Description ACMSDI_NOSUCH_TASK Task not found. ACMSDI_OPR_CANCELLED Operator canceled task. ACMSDI_PENDING Successful operation pending nonblocking completion. The final status is in the completion status parameter. ACMSDI_SECCHK Task security check failed. ACMSDI_SIGNINACTV Request is invalid while the sign-in is active. ACMSDI_SIGNOUTACTV Request is invalid while the sign-out is active.
acmsdi_cancel 2.7 acmsdi_cancel TP Desktop Connector client programs call this service in a nonblocking or forced nonblocking environment to cancel a currently active ACMS task. Use the acmsdi_cancel service only if you invoke a task using nonblocking services. Do not use the acmsdi_cancel service from a presentation procedure or from an asynchronous completion routine.
Page 37
acmsdi_cancel reserved Type: Access: Mechanism: This parameter is reserved for future use. Specify as NULL. completion_status Type: long int Access: write Mechanism: by reference Optional parameter to contain the final completion status of the service. The completion_status is set to ACMSDI_PENDING when the service starts successfully.
acmsdi_cancel Table 2–3 acmsdi_cancel Return Status Values Status Description ACMSDI_CANCELACTV Cancel already in progress. ACMSDI_EXCHACTV Service cannot be called from presentation procedure. ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INTERNAL Internal ACMS error. ACMSDI_INVCALLID Invalid or obsolete call identification. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_NOMEMORY Insufficient memory to complete requests.
An application must call this service to complete an outstanding presentation procedure request from the TP Desktop Connector gateway in a nonblocking or forced nonblocking environment (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide. Format...
acmsdi_complete_pp Table 2–4 acmsdi_complete_pp Return Status Values Status Description 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_NOMEMORY Insufficient memory to complete requests. ACMSDI_NOPPACTV No presentation procedure active for this call. ACMSDI_NORMAL Normal successful completion.
If a TP Desktop Connector message is received, the service calls the appropriate completion routine or presentation procedure and then returns (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide. Note that this call is not used in the forced nonblocking environment. See Section 4.13.
Page 42
acmsdi_dispatch_message Table 2–5 (Cont.) acmsdi_dispatch_message Return Status Values Status Description ACMSDI_NORMAL Normal successful completion. ACMSDI_SRVDEAD Node name is invalid, or TP Desktop Connector gateway is not running on the specified node, or the network link terminated. 2–24 TP Desktop Connector Portable API Client Services...
acmsdi_return_pointer 2.10 acmsdi_return_pointer TP Desktop Connector client programs written in Visual Basic use the ACMSDI_RETURN_POINTER service to create the workspace array for the ACMSDI_CALL_TASK routine. When passing a workspace, the ACMSDI_ CALL_TASK service expects a data structure with the size and address of each workspace.
acmsdi_sign_in 2.11 acmsdi_sign_in TP Desktop Connector client programs call this service to sign a user in to a ACMS system. Format acmsdi_sign_in (submitter_node, username, password, [options], submitter_id, [completion_status], [completion_routine], [call_context]) Parameters submitter_node Type: char * Access: read Mechanism: by reference The node name of the ACMS system where the user is to be signed in.
Page 45
acmsdi_sign_in options Type: ACMSDI_OPTION array Access: read Mechanism: by reference Union containing multiple structures and an option variable, the value of which defines the type of option being selected (see Section 2.5.1). submitter_id Type: ACMSDI_SUBMITTER_ID Access: write Mechanism: by reference A structure into which the acmsdi_sign_in service writes a newly created submitter identification.
acmsdi_sign_in Return Status The status values returned by the acmsdi_sign_in service are listed in Table 2–6. Table 2–6 acmsdi_sign_in Return Status Values Status Description ACMSDI_CALLACTV Call is active. ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INTERNAL Internal TP Desktop Connector error. ACMSDI_INVLOGIN Invalid login attempt. ACMSDI_INVOPTION Invalid item in options list.
acmsdi_sign_out 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],...
acmsdi_sign_out 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.
Page 49
acmsdi_sign_out Table 2–7 (Cont.) acmsdi_sign_out Return Status Values Status Description 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. TP Desktop Connector Portable API Client Services 2–31...
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...
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 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.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.
acmsdi_disable 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...
Page 56
acmsdi_enable 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...
Page 57
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 *...
acmsdi_enable Return Status The status values returned by the acmsdi_enable procedure are described in Section 3.1.1. 3–8 Portable API Presentation Procedures...
acmsdi_read_msg 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.
Page 60
acmsdi_read_msg 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.
Page 61
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...
Page 62
acmsdi_receive 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.
acmsdi_receive 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.
acmsdi_request 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).
Page 65
acmsdi_request 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.
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...
Page 67
acmsdi_send 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.
Page 68
acmsdi_send 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.
Page 69
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. Portable API Presentation Procedures 3–19...
Page 70
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...
Page 71
acmsdi_transceive 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...
acmsdi_transceive Return Status The status values returned by the acmsdi_transceive procedure are described in Section 3.1.1. 3–22 Portable API Presentation Procedures...
acmsdi_write_msg 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,...
Page 74
acmsdi_write_msg 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.
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.
acmsdi_check_version 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: •...
acmsdi_get_version 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.
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 (Cont.) Summary of Forced Nonblocking Procedures Customer-Supplied Procedure Description 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.
Page 81
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;...
acmsdi_complete_call 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.
Page 83
acmsdi_complete_call 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...
acmsdi_complete_call 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.
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. Forced Nonblocking Client Services 4–7...
Page 86
acmsdi_bind_enable_args 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 *...
acmsdi_bind_enable_args 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. Forced Nonblocking Client Services 4–9...
acmsdi_bind_msg 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 Connector gateway on the host OpenVMS system. It performs one of the following functions: •...
Page 89
acmsdi_bind_msg 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: •...
acmsdi_bind_msg 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–12 Forced Nonblocking Client Services...
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. Forced Nonblocking Client Services 4–13...
acmsdi_bind_receive_args 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.
An array of ACMSDI_FORM_RECORD_BIND structures pointing to buffers that store application data and shadow records to be sent to the ACMS task, (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide). If the send_control_text_flag contains a value of 1, the first ACMSDI_FORM_RECORD_BIND structure in the array must point to the...
acmsdi_bind_receive_recs Return Status The status values returned by the acmsdi_bind_receive_recs service are described in Table 4–6. Table 4–6 acmsdi_bind_receive_recs 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_bind_request_args 4.7 acmsdi_bind_request_args The client application can call this service whenever acmsdi_poll returns ACMSDI_REQUEST_EXCH (a TDMS exchange step) from the TP Desktop Connector gateway on the OpenVMS system. This service retrieves the write- only arguments passed from the TP Desktop Connector client services. This provides the client application with the request name and and identifies the set of workspaces to be received from and then sent back to ACMS.
acmsdi_bind_request_args call_id Type: ACMSDI_CALL_ID * Access: write Mechanism: by reference 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. Return Status The status values returned by the acmsdi_bind_request_args service are described in Table 4–7.
Mechanism: by reference The workspace data sent from the ACMS task. One or more workspace arguments can be sent from and returned to the task (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide). Forced Nonblocking Client Services 4–19...
acmsdi_bind_request_wksps Return Status The status values returned by the acmsdi_bind_request_wksps service are described in Table 4–8. Table 4–8 acmsdi_bind_request_wksps 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.
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. Forced Nonblocking Client Services 4–21...
acmsdi_bind_send_args send_record_count Type: long int Access: write Mechanism: by reference The number of send record items sent from the ACMS task. TP Desktop Connector writes the send_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.
An array of ACMSDI_FORM_RECORD_BIND structures pointing to buffers containing application data and shadow records sent from the ACMS task (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide). If the send_control_text_flag contains a value of 1, the first ACMSDI_ FORM_RECORD_BIND structure in the array must point to the send control text buffer.
acmsdi_bind_send_recs Return Status The status values returned by the acmsdi_bind_send_recs service are described in Table 4–10. Table 4–10 acmsdi_bind_send_recs 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_bind_session_id 4.11 acmsdi_bind_session_id You can issue the acmsdi_bind_session_id service to send the forms session ID argument to ACMS during an enable exchange step. This is an optional call. Format acmsdi_bind_session_id (submitter_id, forms_session) 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).
acmsdi_bind_session_id Return Status The status values returned by the acmsdi_bind_session_id procedure are described in Table 4–11. Table 4–11 acmsdi_bind_session_id 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_bind_transceive_args 4.12 acmsdi_bind_transceive_args The client application can call this service whenever an acmsdi_poll returns ACMSDI_TRCV_EXCH from the TP Desktop Connector gateway on the OpenVMS system. This service retrieves the write-only arguments passed from the TP Desktop Connector client services. This provides the client application with the send and receive record identifiers and identifies the set of forms records to be received from and sent to ACMS.
Page 106
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...
acmsdi_bind_transceive_args Return Status The status values returned by the acmsdi_bind_transceive_args service are described in Table 4–12. Table 4–12 acmsdi_bind_transceive_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.
The acmsdi_poll call also checks for the arrival of an exchange step from the back end. (For more information, see Compaq TP Desktop Connector for ACMS Client Application Programming Guide). The acmsdi_poll service returns a pointer to the call context acquired from the user application when the just-completed call was issued.
acmsdi_poll For example, if an acmsdi_call_task completion message is sent from the back end, this is a pointer to the context supplied on the acmsdi_call_task call. This pointer to a structure in the client application’s memory is treated as a 32-bit integer. To determine the structure being referenced, the client application compares this value with the values returned by the acmsdi_ return_pointer service.
Page 110
acmsdi_poll Table 4–13 (Cont.) acmsdi_poll Return Status Values Status Description ACMSDI_SRVDEAD TP Desktop Connector gateway is not running on the server node, or the network link has been terminated. ACMSDI_TDMS_READ_EXCH TDMS Read exchange has arrived ACMSDI_TDMS_WRITE_EXCH TDMS Write exchange has arrived ACMSDI_TRCV_EXCH Transceive exchange step has arrived.
System Management Service on OpenVMS This chapter describes the system management service available on systems running the TP Desktop Connector gateway. The ACMSDI$GET_ SUBMITTER_INFO service returns information about the status of TP Desktop Connector gateway processing on the submitter node. System Management Service on OpenVMS 5–1...
Page 112
5.1 ACMSDI$GET_SUBMITTER_INFO This service returns information regarding desktop users signed in to the Compaq ACMS system. The service reports only those users signed in to the TP Desktop Connector gateway running on the same node as the program calling the ACMSDI$GET_SUBMITTER_INFO routine. See Compaq TP Desktop Connector for ACMS Client Application Programming Guide for coding and building guidelines.
ACMSDI$GET_SUBMITTER_INFO ACMSDI$GET_SUBMITTER_INFO calls, if the service returns the status ACMSDI$_NORMAL, the program does not modify the variable value. itmlst Type: longword (unsigned) Access: read Mechanism: by reference Item list describing the information to be reported. Itmlst is the address of a list of item descriptors, each of which specifies or controls an item of information to be returned.
Page 114
ACMSDI$GET_SUBMITTER_INFO Table 5–1 (Cont.) Submitter Information Item Codes Code Name ACMSDI$K_DESKTOP_ID Action: Returns the desktop gateway submitter identification assigned internally by the TP Desktop Connector gateway. Description: The buffer address field in the item descriptor is the address of a two-longword structure. ACMSDI$GET_SUBMITTER_ INFO writes the desktop gateway submitter number into the first field in the target_desktop_ID array, and the instance into the second field.
Page 115
ACMSDI$GET_SUBMITTER_INFO Table 5–1 (Cont.) Submitter Information Item Codes Code Name ACMSDI$K_SUBMITTER_ID Action: Returns the ACMS submitter_ID of the desktop submitter. Description: The buffer address field in the item descriptor is the address in which the ACMSDI$GET_SUBMITTER_INFO service writes the submitter_ID. ACMSDI$K_TRANSPORT Action: Returns an enumerated longword value corresponding to the...
ACMSDI$GET_SUBMITTER_INFO target_username Type: character string descriptor Access: read Mechanism: by descriptor The user name on which to report. Return Status The status values returned by the ACMSDI$GET_SUBMITTER_INFO service are listed in Table 5–2. Table 5–2 ACMSDI$GET_SUBMITTER_INFO Return Status Values Status Description ACMSDI$_ILLITEMCODE An illegal item code appears in the item list.
You can shorten all commands and keywords to the smallest unambiguous abbreviation, which is at most three characters. See Compaq TP Desktop Connector for ACMS Client Application Programming Guide for more information on using the Data Compression Monitor.
LIST 6.3 LIST This command generates a report, which you can display on the screen or write to a file. Format LIST [/qualifier] Qualifiers /APPLICATION=application Allows you to select detailed records associated with the application(s) specified. The application specification can be an ACMS application name or a list of application names.
Page 121
LIST /NODE=(node-identifier[,...]) Selects detailed records associated with task calls originating from the client node(s) specified. The node-identifier can be a DECnet node name, TCP/IP address, or a list of same. If you specify a list, separate the identifiers with commas and enclose the list within parentheses. If you specify a single identifier, you do not need the comma and parentheses.
Page 122
LIST all tasks are selected. If tasks specified are part of more than one ACMS application, matching task details for all applications are selected, unless you narrow the selection further with the /APPLICATION qualifier. /USER=user-identifier Selects detailed records associated with ACMS task calls executed for the signed-in user session(s) specified.
Page 123
LIST /NODE=ALPHA1 Selects all records for task calls from node ALPHA1. /NODE=(LION,TIGER,PANTHR) Selects all records for task calls from nodes LION, TIGER, and PANTHR. /NODE=*CPQ* Selects all records for task calls from nodes that contain CPQ in their names. /OUTPUT=DAILY_COMPRESSION.REP Directs the report to a file named DAILY_COMPRESSION.REP in the current directory.
Page 124
LIST /USER=MAIN-PLANT Selects all records for sessions established for user identifier MAIN-PLANT. /USER=(SCHMIDT,MASELLA,RAJIV,SWEENEY) Selects all records for sessions established for user identifiers SCHMIDT, MASELLA, RAJIV, and SWEENEY. /USER=SITE3* Selects all records for sessions established for user identifiers that begin with SITE3. 6–8 Data Compression Monitor Commands...
RENEW 6.4 RENEW This command closes the current log file and opens a new one. The new log file is a new version of ACMSDI$COMPRESSION.LOG. Format RENEW Data Compression Monitor Commands 6–9...
SELECT 6.5 SELECT This command selects records from the log file and writes them to a file from which you can generate customized reports. If you do not specify a qualifier, all records are selected. Format SELECT file [/qualifier] Parameters file Is a required parameter that specifies the name of the file to which the selected records are written.
Page 127
SELECT a default input file using the SET command. To override a default input file setting, use /INPUT=* on the LIST command. /NODE=(node-identifier[,...]) Selects detailed records associated with task calls originating from the client node(s) specified. The node-identifier can be a DECnet node name, TCP/IP address, or a list of same.
Page 128
SELECT identifier(s) have been selected with the SET command. Specifying /USER with the SELECT command overrides any default user identifiers that may have been set. Specifying /USER=* with the SELECT command specifies that records for all user sessions are selected, overriding any defaults that may have been set.
6.6 SET This command sets default values for the LIST and SELECT commands. All qualifiers, except /BEFORE and /SINCE, can have a default value. You can use the SHOW command to display the current default settings. When you set a default, it applies to all reports you request with the LIST command and to all records you select with the SELECT command.
Page 130
/OUTPUT=file Directs the report to a file. The file specification must be a valid OpenVMS file specification. Displaying the report on the screen is the default, unless you specify the /OUTPUT qualifier with the SET command. Specifying /OUTPUT=* with the LIST command, displays any reports on the screen, overriding any defaults that may be set.
SHOW 6.7 SHOW This command displays the default values for qualifiers of the LIST and SELECT commands, which you have set with the SET command. All command qualifiers, except /BEFORE and /SINCE, can have a default value. Specifying SHOW without any qualifiers displays all defaults. Format SHOW [/qualifier] Qualifiers...
ACMS not active ACMSDI_NOMEMORY –3011 Low memory resource ACMSDI_NOPPACTV –3012 No active presentation procedure ACMSDI_NOSUCH_APPL –3013 ACMS application not found ACMSDI_NOSUCH_TASK –3014 Invalid task code ACMSDI_OPR_CANCELLED –3015 Operator canceled ACMS user (continued on next page) Compaq ACMS System Status Values A–1...
Page 134
ACMSDI_DISPATCH_ MESSAGE call in process ACMSDI_UNSUPPORTED –3031 Unsupported option requested on acmsdi_sign_in or acmsdi_ call_task ACMSDI_PWDEXPIRING –3100 Number of hours returned until password expires ACMSDI_CALL_CANCELED –3101 The task was canceled by the task submitter A–2 Compaq ACMS System Status Values...
Page 135
Descriptions of client messages and server messages are provided in the following files: • SYS$HELP:ACMSDI$CLIENT_MESSAGES.TXT • SYS$HELP:ACMSDI$SERVER_MESSAGES.TXT Compaq ACMS System Status Values A–3...
Page 137
Index acmsdi_call_task service description, 2–13 acmsdi_cancel service Access description, 2–18 in documentation format, 1–3 acmsdi_check_version routine parameter, 1–1 interface description, 3–25 ACMS$DESKTOP_ID submitter acmsdi_complete_call routine description, 5–5 description of interface, 4–4 ACMSDI$GET_SUBMITTER_INFO service acmsdi_complete_pp service description, 5–2 description, 2–21 sample program using, 5–2 acmsdi_disable routine acmsdi_bind_enable_args routine description of interface, 3–5...
Page 138
ACMSDI_INIT_WORKSPACE data type acmsdi_transceive routine definition, 2–4 description of interface, 3–19 ACMSDI_OPTION array ACMSDI_WORKSPACE data type using, 2–11 definition, 2–4 ACMSDI_OPTION data type structure array, 1–2 structure, 1–2 ACMSDI_WORKSPACE_BIND data type ACMSDI_OPT_CHECK_VERSION option definition, 4–3 defined, 2–10 structure, 1–2 example, 2–27 acmsdi_write_msg routine, 3–23 ACMSDI_OPT_COMMID option defined, 2–10...
Page 139
Forced nonblocking services OpenVMS system described, 4–1 management service, 5–1 specifying, 2–3 Options summary, 4–1 specifying sign-in, 2–27 Form record initialization macro, 3–3 type definition, 3–3, 4–2 Parameter allocating memory, 3–3 data type, 1–2 Gateway passing mechanism, 1–3 task cancellation status, 2–15, 4–4 Portable API client services, 2–1 Portable API presentation procedure summary, 3–1...
Page 140
Session Environments ID, 5–5 description, 1–4 Target submitter SET command ID, 5–5 description, 6–13 Task SHOW command cancellation status, 2–15, 4–4 description, 6–15 TCP/IP port number, 2–11 SHOW_DESKTOP_USERS program Type location, 5–2 in documentation format, 1–2 Sign-in parameter, 1–1 service description, 2–26 Square brackets use in format, 1–1 Version checking...
Need help?
Do you have a question about the TP Desktop Connector AA–PVNFG–TE and is the answer not in the manual?
Questions and answers