Compaq AAPVNFGTE manual

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. Operating System: Compaq OpenVMS V AX Compaq[...]

© 2002 Compaq Information T echnologies Group, L.P . Compaq, the Compaq logo, ACMS, ACMS Desktop, ACMSxp, DECnet, the DIGIT AL logo, OpenVMS, and VMScluster are trademarks of Compaq Information T echnologies Group, L.P . in the U.S. and/or other countries. Microsoft, W indows, Windows NT , and V isual C++ are trademarks of Microsoft Corporation in[...]

Contents Preface ..................................................... vii 1 Service Format 1.1 Routine Names . . . ................................... 1–1 1.2 Format . . ........................................... 1–1 1.3 Parameters ......................................... 1–1 1.3.1 T ype Entry ....................................... 1–2 [...]

2.1 1 acmsdi_sign_in ....................................... 2–26 2.12 acmsdi_sign_out ...................................... 2–29 3 Portable API Presentation Procedures 3.1 Summary of Portable API Presentation Procedures ........... 3–1 3.1.1 Return Status V alues Expected from Presentation Procedures ....................................... [...]

4.13 acmsdi_poll ......................................... 4–30 5 System Management Service on OpenVMS 5.1 ACMSDI$GET_SUBMITTER_INFO . . . ................... 5–2 6 Data Compression Monitor Commands 6.1 EXIT . . . ........................................... 6–2 6.2 HELP . . . ........................................... 6–3 6.3 LIST ........[...]

Figures 5–1 Submitter Item Descriptor Format .................... 5–3 T ables 1–1 Services Description Parameters ...................... 1–1 1–2 Parameter Data T ypes .............................. 1–2 1–3 Called Routine Access Methods ....................... 1–3 1–4 Parameter-Passing Mechanisms ...................... 1–4 1–5 [...]

Preface This manual provides reference information for the TP Desktop Connector client services, formerly known as the ACMS Desktop Portable API. Intended Audience This guide is intended for application programmers, application designers, and system managers. Manual Structure This manual has the following structure: Chapter Description Chapter 1 Ex[...]

• Compaq TP Desktop Connector for ACMS Installation Guide Provides the steps needed to install a TP Desktop Connector gateway on an OpenVMS system and the TP Desktop Connector software on the desktop client system. • Compaq TP Desktop Connector for ACMS Gateway Management Guide Contains information about the system management and administration[...]

Conventions This guide uses the following conventions and symbols: TP Desktop Connector Refers to the Compaq TP Desktop Connector for ACMS software. User Input In examples, user input is highlighted with bold type. $ The dollar sign indicates a generic command line prompt. This prompt may be different on your system. Return A key name in a box indi[...]

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. W in[...]

1 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-[...]

1.3.1 T ype Entry T able 1–2 lists the C-language data types used in the TP Desktop Connector services. T able 1–2 Parameter Data T ypes Data T ype 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_ BIND S[...]

T able 1–2 (Cont.) Parameter Data T ypes Data T ype Description longword 32-bit unsigned integer ptr 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 access[...]

T able 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 str[...]

In a forced nonblocking environment, service routines provide a method of polling that is used to determine the type of message sent from the back-end server . This message type may then be used to determine the appropriate action (for example, process the call completion or exchange step). The forced nonblocking software provides additional routin[...]

T able 1–5 (Cont.) Matrix of Services and Environments Service A vailability within Environment Blocking Nonblocking Forced Nonblocking acmsdi_bind_receive_args See description in Section 4.5 - - yes acmsdi_bind_transceive_args See description in Section 4.12 - - yes acmsdi_bind_msg See description in Section 4.4 - - yes acmsdi_bind_request_args [...]

T able 1–5 (Cont.) Matrix of Services and Environments Service A vailability within Environment Blocking Nonblocking Forced Nonblocking Callbacks acmsdi_transceive See description in Section 3.10 - yes - acmsdi_write_msg See description in Section 3.1 1 - yes - acmsdi_check_version See description in Section 3.12.1 - yes - acmsdi_get_version(back[...]

[...]

2 TP Desktop Connector Portable API Client Services This chapter describes the Compaq TP Desktop Connector portable API client services available on the following desktop systems: • Microsoft W indows • Compaq OpenVMS • Compaq T ru64 UNIX 2.1 Summary of Portable API Client Services Similar to the Compaq ACMS Service Interface (SI) routines pr[...]

T able 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_ message Used by nonblocking environments only . Checks for and processes messages from the TP Deskto[...]

client service returns the ACMSDI_PENDING status. If a status other than ACMSDI_PENDING is returned, the completion routine is not called. If nonblocking calls are active, use the acmsdi_dispatch_message service to poll for responses from the TP Desktop Connector gateway . When a response is received, acmsdi_dispatch_message calls the appropriate c[...]

call_context T ype: 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-suppl[...]

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); } T o pass more than one workspace to a proced[...]

2.4.2 ACMSDI_WORKSP ACE_OPT Structure The ACMSDI.H file contains the definition of the ACMSDI_WORKSP ACE_OPT type you use to declare workspaces passed to tasks using the ACMSDI_CALL_ T ASK service. Y ou can use ACMSDI_WORKSP ACE_OPT instead of ACMSDI_ WORKSP ACE. Only task calls that use the ACMSDI_T ASK_OPTIONS flag to indicate unidirectional w[...]

Example 2–4 (Cont.) Passing T wo W orkspaces struct { int id_number; char first_name[15]; char last_name[25]; } employee_record; ACMSDI_INIT_WORKSPACE_OPT (wksp_array[0], control_wksp, ACMSDI_ACCESS_READ); ACMSDI_INIT_WORKSPACE_OPT (wksp_array[1], employee_record, ACMSDI_ACCESS_WRITE); 2.4.3 ACMSDI_WORKSP ACE_BIND Structure The ACMSDI_WORKSP ACE_[...]

Y ou 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: • ACMSDI_FORM_RECORD_BIND struct[...]

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[...]

Caution Use the ACMSDI_CALL_OPT_OPTIMIZE_WKSPS option and the ACMSDI_WORKSP ACE_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 workspa[...]

T o 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. Example 2–5 initializes an options list to enable version checking, user-[...]

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 */ "HA[...]

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], 1 [call_conte[...]

acmsdi_call_task task_name T ype: char * Access: read Mechanism: by reference The name of the task to execute. Maximum length is 31. application_name T ype: 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 [...]

acmsdi_call_task workspace_count T ype: long int Access: read Mechanism: by value The decimal number of workspaces being passed to the task. workspaces T ype: ACMSDI_WORKSP ACE or ACMSDI_WORKSP ACE_OPT array Access: read/write Mechanism: by reference One or more optional workspaces to be passed to the task. Y ou need to typecast your array to void [...]

acmsdi_call_task completion_routine T ype: function address 1 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 T ask " message is received from the TP Desktop Connector gateway . call_context T ype: voi[...]

acmsdi_call_task T able 2–2 (Cont.) acmsdi_call_task Return Status V alues Status Description ACMSDI_NOSUCH_T ASK T ask 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 T ask security check failed. ACM[...]

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 asynchrono[...]

acmsdi_cancel reserved T ype: Access: Mechanism: This parameter is reserved for future use. Specify as NULL. completion_status T ype: 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 . When the[...]

acmsdi_cancel T able 2–3 acmsdi_cancel Return Status V alues 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_INVSUB[...]

acmsdi_complete_pp 2.8 acmsdi_complete_pp TP Desktop Connector client programs call this nonblocking service to complete exchange step processing for a submitter . 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 ([...]

acmsdi_complete_pp T able 2–4 acmsdi_complete_pp Return Status V alues 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_NOMEMOR Y Insufficient memory to[...]

acmsdi_dispatch_message 2.9 acmsdi_dispatch_message TP Desktop Connector client programs call this nonblocking service to check for and process messages sent from a TP Desktop Connector gateway to an active submitter in the desktop application. The application must periodically call this service in a nonblocking environment to check for completion [...]

acmsdi_dispatch_message T able 2–5 (Cont.) acmsdi_dispatch_message Return Status V alues Status Description ACMSDI_NORMAL Normal successful completion. ACMSDI_SR VDEAD 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 Service[...]

acmsdi_return_pointer 2.10 acmsdi_return_pointer TP Desktop Connector client programs written in V isual Basic use the ACMSDI_RETURN_POINTER service to create the workspace array for the ACMSDI_CALL_T ASK routine. When passing a workspace, the ACMSDI_ CALL_T ASK service expects a data structure with the size and address of each workspace. The ACMSD[...]

acmsdi_sign_in 2.1 1 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], 1 [call_context]) Parameters submitter_node T ype: char * Access: read Mechanism: by reference T[...]

acmsdi_sign_in options T ype: 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 T ype: ACMSDI_SUBMITTER_ID Access: write Mechanism: by reference A structure into which the acmsdi_sign_in[...]

acmsdi_sign_in Return Status The status values returned by the acmsdi_sign_in service are listed in T able 2–6. T able 2–6 acmsdi_sign_in Return Status V alues Status Description ACMSDI_CALLACTV Call is active. ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INTERNAL Internal TP Desktop Connector error . ACMSDI_INVLOGIN Invalid login attempt. [...]

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. T o 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], [completi[...]

acmsdi_sign_out call_context T ype: 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 T able 2–7. T [...]

acmsdi_sign_out T able 2–7 (Cont.) acmsdi_sign_out Return Status V alues Status Description ACMSDI_SIGNOUT ACTV Request is invalid while sign-out is active. ACMSDI_SR VDEAD 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 [...]

[...]

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 pro[...]

T able 3–1 (Cont.) Summary of Portable API Presentation Procedures Customer-Supplied Procedure Description 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. ac[...]

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 F[...]

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 environ[...]

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 forms_session T ype: AC[...]

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, ca[...]

acmsdi_enable file_specification T ype: 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 T ype: char * Access: read Mechan[...]

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 r[...]

acmsdi_read_msg call_id T ype: 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 T ype: void * Access: read Mechanism: by value Application-specific context for the call. This is the same context that was pa[...]

acmsdi_receive 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_c[...]

acmsdi_receive receive_control_text T ype: 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 T ype: long int Access: write Mechanism: by reference The number of receive control text items that the customer-supplied request returns.[...]

acmsdi_receive receive_record T ype: 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 T ype: ACMSDI[...]

acmsdi_request workspaces T ype: ACMSDI_WORKSP ACE 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 T ype: ACMSDI_CALL_ID Access: read Mechanism: by reference The call identification returned by the acmsdi_call_[...]

acmsdi_send 3.9 acmsdi_send TP Desktop Connector client services call this presentation procedure whenever a DECforms SEND request is received from the TP Desktop Connector gateway on the OpenVMS system. Format acmsdi_send (forms_session, send_record_identifier , send_record_count, receive_control_text, receive_control_text_count, send_control_tex[...]

acmsdi_send receive_control_text T ype: 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 T ype: long int Access: write Mechanism: by reference The number of receive control text items that the customer-supplied request returns. se[...]

acmsdi_send send_record T ype: ACMSDI_FORM_RECORD array Access: read Mechanism: by reference An array of ACMSDI_FORM_RECORD structures pointing to buffers containing application data and shadow records sent from the ACMS task (see Section 3.1.2). Return Status The status values returned by the acmsdi_send procedure are described in Section 3.1.1. 3[...]

acmsdi_transceive 3.10 acmsdi_transceive TP Desktop Connector client services call this presentation procedure whenever a DECforms TRANSCEIVE request is received from the TP Desktop Connector gateway on the OpenVMS system. Format acmsdi_transceive (forms_session, send_record_identifier , send_record_count, receive_record_identifier , receive_reco[...]

acmsdi_transceive send_record_count T ype: long int Access: read Mechanism: by value The number of send record items sent from the ACMS task. receive_record_identifier T ype: 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 [...]

acmsdi_transceive send_control_text_count T ype: long int Access: read Mechanism: by value The number of send control text items sent from the ACMS task. timeout T ype: short int Access: read Mechanism: by value A timeout value for user input processing, sent from the ACMS task. call_id T ype: ACMSDI_CALL_ID Access: read Mechanism: by reference The[...]

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.1 1 acmsdi_write_msg TP Desktop Connector client services call this presentation procedure when a TDMS W rite 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[...]

acmsdi_write_msg call_id T ype: 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 T ype: void * Access: read Mechanism: by value Application-specific context for the call. This is the same context that was p[...]

acmsdi_check_version 3.12 V ersion-Checking Routines The following sections describe the version-checking routines. V ersion 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 whenev[...]

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. This service can also be us[...]

[...]

4 Forced Nonblocking Client Services This chapter describes the forced nonblocking interface between the TP Desktop Connector gateway and customer-written procedures. 4.1 Summary of Forced Nonblocking Procedures Forced nonblocking client services extend the Portable API to support development tools that do not provide for callbacks, data pointers o[...]

T able 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 th[...]

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 le[...]

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[...]

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 T [...]

acmsdi_complete_call Return Status The status values returned by the acmsdi_complete_call procedure are described in T able 4–2. T able 4–2 acmsdi_complete_call Return Status V alues Status Description ACMSDI_EXCHACTV Request is invalid while exchange step processing is active. ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INTERNAL Internal [...]

acmsdi_bind_enable_args 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 Connector client services. This is an optional call. Format acmsdi_bi[...]

acmsdi_bind_enable_args form_version T ype: char * Access: write Mechanism: by reference T wenty-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 s[...]

acmsdi_bind_enable_args T able 4–3 acmsdi_bind_enable_args Return Status V alues 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 T rying to bind arguments for [...]

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 W rite exchange) from the TP Desktop Connector gateway on the host OpenVMS system. It performs one of the following functions: • acquires the prompt text, if any[...]

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 T ype: 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 [...]

acmsdi_bind_msg T able 4–4 acmsdi_bind_msg Return Status V alues 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 T rying to bind arguments for an exchange[...]

acmsdi_bind_receive_args 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 Connector client services. This provides the client application wi[...]

acmsdi_bind_receive_args receive_record_count T ype: 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 T ype: short int Access: write Mechanism: by reference A timeout value for user input processing sent fro[...]

acmsdi_bind_receive_recs 4.6 acmsdi_bind_receive_recs The client application calls this service to send the client application’ s receive forms record data to the TP Desktop Connector gateway on the OpenVMS system. Use this service after you have retrieved the exchange step arguments that identify the forms records to be sent to the TP Desktop Co[...]

acmsdi_bind_receive_recs Return Status The status values returned by the acmsdi_bind_receive_recs service are described in T able 4–6. T able 4–6 acmsdi_bind_receive_recs Return Status V alues Status Description ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_MIXEDMODE Not a forced[...]

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 t[...]

acmsdi_bind_request_args call_id T ype: ACMSDI_CALL_ID * Access: write Mechanism: by reference The call identification returned by the acmsdi_call_task service. T o 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 t[...]

acmsdi_bind_request_wksps 4.8 acmsdi_bind_request_wksps The client application calls this service to copy request workspace data between the client application and the ACMS during a TDMS exchange. Use the acmsdi_bind_request_wksps call to copy request workspace data from TP Desktop Connector gateway to the client application memory . After modific[...]

acmsdi_bind_request_wksps Return Status The status values returned by the acmsdi_bind_request_wksps service are described in T able 4–8. T able 4–8 acmsdi_bind_request_wksps Return Status V alues Status Description ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_MIXEDMODE Not a for[...]

acmsdi_bind_send_args 4.9 acmsdi_bind_send_args The client application can call this service whenever an acmsdi_poll returns ACMSDI_SEND_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[...]

acmsdi_bind_send_args send_record_count T ype: 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 T ype: short int Access: write Mechanism: by reference A timeout value for user input processing, sent from the ACMS task[...]

acmsdi_bind_send_recs 4.10 acmsdi_bind_send_recs The client application calls this service to retrieve send forms record data from the TP Desktop Connector gateway on the OpenVMS system. Use this service after you have retrieved the exchange step arguments that identify the forms records required from the TP Desktop Connector gateway . This service[...]

acmsdi_bind_send_recs Return Status The status values returned by the acmsdi_bind_send_recs service are described in T able 4–10. T able 4–10 acmsdi_bind_send_recs Return Status V alues Status Description ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_MIXEDMODE Not a forced nonblo[...]

acmsdi_bind_session_id 4.1 1 acmsdi_bind_session_id Y ou 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 T ype: ACMSDI_SUBMITTER_ID Access: read Mechanism: by refere[...]

acmsdi_bind_session_id Return Status The status values returned by the acmsdi_bind_session_id procedure are described in T able 4–1 1. T able 4–1 1 acmsdi_bind_session_id Return Status V alues Status Description ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_MIXEDMODE Not a forced[...]

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 applica[...]

acmsdi_bind_transceive_args send_record_identifier T ype: char * Access: write 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 T ype: long[...]

acmsdi_bind_transceive_args Return Status The status values returned by the acmsdi_bind_transceive_args service are described in T able 4–12. T able 4–12 acmsdi_bind_transceive_args Return Status V alues Status Description ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identification. ACMSDI_MIXEDMODE N[...]

acmsdi_poll 4.13 acmsdi_poll TP Desktop Connector client programs call this nonblocking service to check for and process messages sent from a TP Desktop Connector gateway to an active submitter in the desktop application. The application must periodically call this service in a forced nonblocking environment to check for completion of outstanding a[...]

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 . T o determine the structure being referenced, the client application compares this va[...]

acmsdi_poll T able 4–13 (Cont.) acmsdi_poll Return Status V alues Status Description ACMSDI_SR VDEAD 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 W rite exchange has arrived ACMSDI_TRCV_EXCH T ransceive exch[...]

5 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[...]

ACMSDI$GET_SUBMITTER_INFO 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 Connecto[...]

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 T ype: 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 sp[...]

ACMSDI$GET_SUBMITTER_INFO T able 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_SUB[...]

ACMSDI$GET_SUBMITTER_INFO T able 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 Actio[...]

ACMSDI$GET_SUBMITTER_INFO target_username T ype: 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 T able 5–2. T able 5–2 ACMSDI$GET_SUBMITTER_INFO Return Status V alues Status Description ACMSDI$_ILL[...]

6 Data Compression Monitor Commands This chapter provides a description of the Data Compression Monitor commands that you can use to monitor compression activity . Y ou 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 Progra[...]

EXIT 6.1 EXIT This command exits the Compression Monitor Activity reporting program. Format EXIT 6–2 Data Compression Monitor Commands[...]

HELP 6.2 HELP Displays the help file, SYS$HLP:ACMSDI$DCM_REPORTER_HLP .TXT . Format HELP Data Compression Monitor Commands 6–3[...]

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 /APPLICA TION=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. If[...]

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 ident[...]

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 /APPLICA TION qualifier . /USER=user-identifier Selects detailed records associated with ACMS task calls executed for the signed-in user session(s) s[...]

LIST 8. /NODE=ALPHA1 Selects all records for task calls from node ALPHA1. 9. /NODE=(LION,TIGER,PANTHR) Selects all records for task calls from nodes LION, TIGER, and P ANTHR. 10. /NODE=*CPQ* Selects all records for task calls from nodes that contain CPQ in their names. 11 . /OUTPUT=DAILY_COMPRESSION.REP Directs the report to a file named DAIL Y_CO[...]

LIST 19. /USER=MAIN-PLANT Selects all records for sessions established for user identifier MAIN-PLANT . 20. /USER=(SCHMIDT,MASELLA,RAJIV,SWEENEY) Selects all records for sessions established for user identifiers SCHMIDT , MASELLA, RAJIV , and SWEENEY . 21. /USER=SITE3* Selects all records for sessions established for user identifiers that begin [...]

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[...]

SELECT a default input file using the SET command. T o 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. If you[...]

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–12 Data Compression Monitor[...]

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. Y ou 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 [...]

SET /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 b[...]

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 /APPLICA TION Displays the[...]

[...]

A Compaq ACMS System Status V alues T able A–1 lists the ACMS system status values and their corresponding numeric values as defined in ACMSDI.H and returned in the err2 parameter , with corresponding symbols. T able A–1 ACMS System Status V alues Symbol V alue T ext ACMSDI_NORMAL 0 Normal completion ACMSDI_APPLDEAD –3001 ACMS application no[...]

T able A–1 (Cont.) ACMS System Status V alues Symbol V alue T ext ACMSDI_PENDING –3016 Operation started ACMSDI_SECCHK –3017 ACMS task ACL failure ACMSDI_SIGNINACTV –3018 Sign-in in process ACMSDI_SIGNOUT ACTV –3019 Sign-out in process ACMSDI_SR VDEAD –3020 TP Desktop Connector server has died ACMSDI_T ASK_ABORT –3021 T ask has aborte[...]

Descriptions of client messages and server messages are provided in the following files: • SYS$HELP:ACMSDI$CLIENT_MESSAGES.TXT • SYS$HELP:ACMSDI$SER VER_MESSAGES.TXT Compaq ACMS System Status V alues A–3[...]

[...]

Index A Access in documentation format, 1–3 parameter, 1–1 ACMS$DESKTOP_ID submitter description, 5–5 ACMSDI$GET_SUBMITTER_INFO service description, 5–2 sample program using, 5–2 acmsdi_bind_enable_args routine description of interface, 4–7 acmsdi_bind_msg routine, 4–10 acmsdi_bind_receive_args routine description of interface, 4–13[...]

ACMSDI_INIT_WORKSP ACE data type definition, 2–4 ACMSDI_OPTION array using, 2–1 1 ACMSDI_OPTION data type structure, 1–2 ACMSDI_OPT_CHECK_VERSION option defined, 2–10 example, 2–27 ACMSDI_OPT_COMMID option defined, 2–10 example, 2–1 1 ACMSDI_OPT_END_LIST option defined, 2–10 ACMSDI_OPT_FREE_ROUTINE option defined, 2–10 ACMSDI[...]

F Forced nonblocking services described, 4–1 specifying, 2–3 summary, 4–1 Form record initialization macro, 3–3 type definition, 3–3, 4–2 G Gateway task cancellation status, 2–15, 4–4 H HELP command description, 6–3 L LIST command description, 6–4 M Management service, 5–1 Mechanism parameter, 1–1 parameter passing, 1–3 M[...]

Session Environments description, 1–4 SET command description, 6–13 SHOW command description, 6–15 SHOW_DESKTOP_USERS program location, 5–2 Sign-in service description, 2–26 Square brackets use in format, 1–1 Status return, 1–4 Submitter identification ACMS, 5–5 desktop gateway, 5–4 program for information, 5–2 Submitter_id des[...]