Page 3 - Contents; Preface; vii; Service Format; iii
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii 1 Service Format 1.1 Routine Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–1 1.2 Format . . . . . . . . . . . . . . . . . . . . . . . ....
Page 4 - iv
2.11 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 . . ...
Page 7 - Intended Audience; This manual has the following structure:; Chapter; Chapter 1; Related Documents
Preface This manual provides reference information for the TP Desktop Connectorclient services, formerly known as the ACMS Desktop Portable API. Intended Audience This guide is intended for application programmers, application designers, andsystem managers. Manual Structure This manual has the follo...
Page 8 - Using DECset; viii
• Compaq TP Desktop Connector for ACMS Installation Guide Provides the steps needed to install a TP Desktop Connector gateway on anOpenVMS system and the TP Desktop Connector software on the desktopclient system. • Compaq TP Desktop Connector for ACMS Gateway Management Guide Contains information ab...
Page 9 - Conventions; This guide uses the following conventions and symbols:; TP Desktop Connector; User Input; In examples, user input is highlighted with bold type.; WORD
Conventions This guide uses the following conventions and symbols: TP Desktop Connector Refers to the Compaq TP Desktop Connector for ACMSsoftware. 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...
Page 11 - Service Format; Table 1–1 Services Description Parameters; Name
1 Service Format This chapter describes the format and elements of the service descriptionsprovided in following chapters. This chapter also provides a list of the servicesand the appropriate session environments in which each service may be used. 1.1 Routine Names The TP Desktop Connector service n...
Page 12 - Table 1–2 Parameter Data Types; Data Type
1.3.1 Type Entry Table 1–2 lists the C-language data types used in the TP Desktop Connectorservices. Table 1–2 Parameter Data Types Data Type Description ACMSDI_CALL_ID Identification returned by the acmsdi_call_taskservice ACMSDI_FORM_RECORD Structure defined in the ACMSDI.H include file (seeSectio...
Page 13 - Table 1–3 Called Routine Access Methods; Access Method
Table 1–2 (Cont.) Parameter Data Types Data Type 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 describ...
Page 14 - Table 1–4 Parameter-Passing Mechanisms; Each service returns a status value defined as follows:; Session Environments
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 bythe routine. The parameter is a pointer to the data. Because Csupports only call by valu...
Page 15 - Table 1–5 Matrix of Services and Environments; Service
In a forced nonblocking environment, service routines provide a method ofpolling that is used to determine the type of message sent from the back-endserver. This message type may then be used to determine the appropriateaction (for example, process the call completion or exchange step). The forcedno...
Page 17 - Service Format 1–7
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 - yes - acmsdi_write_msg See description in Section 3.11 - yes - acmsdi_check_version See description in S...
Page 19 - Microsoft Windows; Summary of Portable API Client Services; Table 2–1 Summary of Portable API Client Services
2 TP Desktop Connector Portable API Client Services This chapter describes the Compaq TP Desktop Connector portable API clientservices available on the following desktop systems: • Microsoft Windows • Compaq OpenVMS • Compaq Tru64 UNIX 2.1 Summary of Portable API Client Services Similar to the Compa...
Page 20 - Parameter Memory Allocation; –2 TP Desktop Connector Portable API Client Services
Table 2–1 (Cont.) Summary of Portable API Client Services Service Description acmsdi_complete_pp Used by nonblocking environments only. Sends a responsefrom a presentation procedure request to the TP DesktopConnector gateway. acmsdi_dispatch_message Used by nonblocking environments only. Checks for ...
Page 21 - Nonblocking and Blocking Restriction; Parameters; TP Desktop Connector Portable API Client Services 2–3
client service returns the ACMSDI_PENDING status. If a status other thanACMSDI_PENDING is returned, the completion routine is not called. If nonblocking calls are active, use the acmsdi_dispatch_message service topoll for responses from the TP Desktop Connector gateway. When a responseis received, a...
Page 22 - Return Status; Workspace Data Structures; This section describes the following workspace data structures:; –4 TP Desktop Connector Portable API Client Services
call_context Type: void *Access: readMechanism: by valueSupplies application-specific context to the completion routine. If specified onacmsdi_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 thecompletion ...
Page 23 - TP Desktop Connector Portable API Client Services 2–5
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...
Page 24 - –6 TP Desktop Connector Portable API Client Services
2.4.2 ACMSDI_WORKSPACE_OPT Structure The ACMSDI.H file contains the definition of the ACMSDI_WORKSPACE_OPTtype 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_OPTI...
Page 25 - void; TP Desktop Connector Portable API Client Services 2–7
Example 2–4 (Cont.) Passing Two Workspaces 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_WORKS...
Page 26 - –8 TP Desktop Connector Portable API Client Services
You can use the ACMSDI_FORM_RECORD_BIND structure to locate sendcontrol text and receive control text buffers. Both acmsdi_bind_send_args andacmsdi_bind_receive_args services contain arguments to specify whether or notto transfer control text. If you specify to transfer control text, the followingru...
Page 28 - Caution; Constant; Enables version checking; –10 TP Desktop Connector Portable API Client Services
Caution Use the ACMSDI_CALL_OPT_OPTIMIZE_WKSPS option and theACMSDI_WORKSPACE_OPT type definition together to optimizeunidirectional workspace traffic. Do not use one without the other.The acmsdi_call_task client service uses the presence or absence ofthe workspace optimization option to decide whic...
Page 29 - Declare an array of at least two elements of the type ACMSDI_OPTION.; Example 2–5 Initializing an Options List; This option is usable with forced nonblocking calls only.; TP Desktop Connector Portable API Client Services 2–11
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 optionvariable in the last array element. Example 2–5 initializes an ...
Page 30 - Example 2–6 Dynamically Specifying a TCP/IP Port Identifier; –12 TP Desktop Connector Portable API Client Services
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", /...
Page 31 - TP Desktop Connector Portable API Client Services 2–13
acmsdi_call_task 2.6 acmsdi_call_task TP Desktop Connector client programs call this service to execute a task in aACMS application. Format acmsdi_call_task (submitter_id, [call_options],task_name,application_name,selection_string,status_message,workspace_count,[workspaces],[call_id],[completion_sta...
Page 32 - –14 TP Desktop Connector Portable API Client Services
acmsdi_call_task task_name Type: char *Access: readMechanism: by referenceThe name of the task to execute. Maximum length is 31. application_name Type: char *Access: readMechanism: by referenceThe specification of a ACMS application in which the task resides. Theapplication name must be a valid appl...
Page 33 - workspaces; TP Desktop Connector Portable API Client Services 2–15
acmsdi_call_task workspace_count Type: long intAccess: readMechanism: by valueThe decimal number of workspaces being passed to the task. workspaces Type: ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OPT arrayAccess: read/writeMechanism: by referenceOne or more optional workspaces to be passed to the task. Y...
Page 34 - Table 2–2 acmsdi_call_task Return Status Values; Status
acmsdi_call_task completion_routine Type: function address 1 Access: readMechanism: by valueAddress 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 ...
Page 36 - –18 TP Desktop Connector Portable API Client Services
acmsdi_cancel 2.7 acmsdi_cancel TP Desktop Connector client programs call this service in a nonblocking orforced nonblocking environment to cancel a currently active ACMS task. Usethe acmsdi_cancel service only if you invoke a task using nonblocking services.Do not use the acmsdi_cancel service from...
Page 37 - TP Desktop Connector Portable API Client Services 2–19
acmsdi_cancel reserved Type:Access:Mechanism:This parameter is reserved for future use. Specify as NULL. completion_status Type: long intAccess: writeMechanism: by referenceOptional parameter to contain the final completion status of the service.The completion_status is set to ACMSDI_PENDING when th...
Page 38 - Table 2–3 acmsdi_cancel Return Status Values
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 presentationprocedure. ACMSDI_INSUFPRM Insufficient parameters. ACMSDI_INTERNAL Internal ACMS error. ACMSDI_INVCALLID Invalid or o...
Page 39 - TP Desktop Connector Portable API Client Services 2–21
acmsdi_complete_pp 2.8 acmsdi_complete_pp TP Desktop Connector client programs call this nonblocking service to completeexchange step processing for a submitter. An application must call thisservice to complete an outstanding presentation procedure request fromthe TP Desktop Connector gateway in a n...
Page 40 - Table 2–4 acmsdi_complete_pp Return Status Values
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...
Page 41 - No parameters are specified.; Table 2–5 acmsdi_dispatch_message Return Status Values; Internal TP Desktop Connector error.; TP Desktop Connector Portable API Client Services 2–23
acmsdi_dispatch_message 2.9 acmsdi_dispatch_message TP Desktop Connector client programs call this nonblocking service to checkfor and process messages sent from a TP Desktop Connector gateway to anactive submitter in the desktop application. The application must periodicallycall this service in a n...
Page 42 - Normal successful completion.; –24 TP Desktop Connector Portable API Client Services
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 DesktopConnector gateway is not running onthe specified node, or the network linkterminated. 2–24 TP Deskto...
Page 43 - structure; TP Desktop Connector Portable API Client Services 2–25
acmsdi_return_pointer 2.10 acmsdi_return_pointer TP Desktop Connector client programs written in Visual Basic use theACMSDI_RETURN_POINTER service to create the workspace array for theACMSDI_CALL_TASK routine. When passing a workspace, the ACMSDI_CALL_TASK service expects a data structure with the s...
Page 44 - username; –26 TP Desktop Connector Portable API Client Services
acmsdi_sign_in 2.11 acmsdi_sign_in TP Desktop Connector client programs call this service to sign a user in to aACMS system. Format acmsdi_sign_in (submitter_node, username,password,[options],submitter_id,[completion_status],[completion_routine], 1 [call_context]) Parameters submitter_node Type: cha...
Page 45 - TP Desktop Connector Portable API Client Services 2–27
acmsdi_sign_in options Type: ACMSDI_OPTION arrayAccess: readMechanism: by referenceUnion containing multiple structures and an option variable, the value ofwhich defines the type of option being selected (see Section 2.5.1). submitter_id Type: ACMSDI_SUBMITTER_IDAccess: writeMechanism: by referenceA...
Page 46 - Table 2–6 acmsdi_sign_in Return Status Values
acmsdi_sign_in Return Status The status values returned by the acmsdi_sign_in service are listed inTable 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....
Page 47 - Type: function address; TP Desktop Connector Portable API Client Services 2–29
acmsdi_sign_out 2.12 acmsdi_sign_out TP Desktop Connector client programs call this service to terminate an activesession with a ACMS system. To insure that all network links are properlyshut down, the desktop client program calls the acmsdi_sign_out service beforeterminating. Format acmsdi_sign_out...
Page 48 - Table 2–7 acmsdi_sign_out Return Status Values; Insufficient parameters.; –30 TP Desktop Connector Portable API Client Services
acmsdi_sign_out call_context Type: void *Access: readMechanism: by valueOptional parameter passed to presentation procedures and completion routinesto identify the call. Use this parameter to supply application-specific contextfor the call. Return Status The status values returned by the acmsdi_sign...
Page 51 - Portable API Presentation Procedures; Summary of Portable API Presentation Procedures; Table 3–1 Summary of Portable API Presentation Procedures; Customer-Supplied Procedure
3 Portable API Presentation Procedures This chapter describes the interface between the TP Desktop Connectorgateway and customer-written presentation procedures. It also describes theinterfaces on portable clients for customer-written action routines to performversion checking. 3.1 Summary of Portab...
Page 52 - Table 3–1 (Cont.) Summary of Portable API Presentation Procedures; Return Status Values Expected from Presentation Procedures; –2 Portable API Presentation Procedures
Table 3–1 (Cont.) Summary of Portable API Presentation Procedures Customer-Supplied Procedure Description acmsdi_request Services a TDMS Request exchange, which displaysa form and transfers data between a form and theapplication program. acmsdi_send Services a DECforms send request, which sendsdata ...
Page 53 - Example 3–1 Form Record Definition and Initialization Macro; int; Prototypes and Code for Presentation Procedures and Version; Parameter Memory Allocation; Portable API Presentation Procedures 3–3
3.1.2 ACMSDI_FORM_RECORD Structure and Macro Call Defined in the ACMSDI.H file, the ACMSDI_FORM_RECORD type declaresform records and shadow records passed to and from presentation procedures.The code in Example 3–1 defines the ACMSDI_FORM_RECORD type and amacro ACMSDI_INIT_FORM_RECORD to initialize ...
Page 54 - Blocking and Nonblocking Usage; Presentation Procedures in a Nonblocking Environment; –4 Portable API Presentation Procedures
3.3 Blocking and Nonblocking Usage Like the portable TP Desktop Connector client services, presentationprocedures can be either blocking or nonblocking. If the desktop clientprogram supplies the completion_routine parameter in the acmsdi_call_taskcall, the service behaves in the nonblocking environm...
Page 55 - Portable API Presentation Procedures 3–5
acmsdi_disable 3.4 acmsdi_disable TP Desktop Connector services call this procedure for each active forms sessionfor a desktop submitter whenever the TP Desktop Connector client programcalls acmsdi_sign_out to sign the submitter out of the ACMS system. Format acmsdi_disable (forms_session, call_id,c...
Page 56 - –6 Portable API Presentation Procedures
acmsdi_enable 3.5 acmsdi_enable TP Desktop Connector client services call this presentation procedure whenevera DECforms ENABLE request is received from the TP Desktop Connectorgateway on the OpenVMS system. Format acmsdi_enable (submitter_id, forms_session,file_specification,form_specification,form...
Page 57 - Portable API Presentation Procedures 3–7
acmsdi_enable file_specification Type: char *Access: readMechanism: by referenceThe form file specification from the ACMS task group definition. Refer toCompaq TP Desktop Connector for ACMS Client Application ProgrammingGuide for guidelines on specifying the form file specification. form_specificati...
Page 58 - –8 Portable API Presentation Procedures
acmsdi_enable Return Status The status values returned by the acmsdi_enable procedure are described inSection 3.1.1. 3–8 Portable API Presentation Procedures
Page 59 - Portable API Presentation Procedures 3–9
acmsdi_read_msg 3.6 acmsdi_read_msg TP Desktop Connector client services call this presentation procedure whena TDMS Read exchange is received from the TP Desktop Connector gatewayon the host OpenVMS system. Its function is to display the prompt (if any)sent from the ACMS task and then to acquire th...
Page 60 - –10 Portable API Presentation Procedures
acmsdi_read_msg call_id Type: ACMSDI_CALL_IDAccess: readMechanism: by referenceThe call identification returned by the acmsdi_call_task service which initiatedthe ACMS task associated with this exchange. call_context Type: void *Access: readMechanism: by valueApplication-specific context for the cal...
Page 61 - Portable API Presentation Procedures 3–11
acmsdi_receive 3.7 acmsdi_receive The TP Desktop Connector client services call this presentation procedurewhenever a DECforms RECEIVE request is received from the TP DesktopConnector gateway on the OpenVMS system. Format acmsdi_receive (forms_session, receive_record_identifier,receive_record_count,...
Page 62 - timeout; –12 Portable API Presentation Procedures
acmsdi_receive receive_control_text Type: char *Access: writeMechanism: by referenceA 25-character string that the customer-supplied request can use to returnreceive control text. receive_control_text_count Type: long intAccess: writeMechanism: by referenceThe number of receive control text items th...
Page 63 - Portable API Presentation Procedures 3–13
acmsdi_receive receive_record Type: ACMSDI_FORM_RECORD arrayAccess: writeMechanism: by referenceAn array of ACMSDI_FORM_RECORD structures pointing to buffers thatstore application data and shadow records from the request (see Section 3.1.2). Return Status The status values returned by the acmsdi_rec...
Page 64 - –14 Portable API Presentation Procedures
acmsdi_request 3.8 acmsdi_request TP Desktop Connector client services call this presentation procedure whenevera TDMS Request exchange is received from the TP Desktop Connector gatewayon the OpenVMS system. Format acmsdi_request (submitter_id, request_name,workspace_count,workspaces,call_id,call_co...
Page 65 - Portable API Presentation Procedures 3–15
acmsdi_request workspaces Type: ACMSDI_WORKSPACE arrayAccess: read/writeMechanism: by referenceThe workspace data sent from the ACMS task. One or more optionalworkspace arguments can be sent from the task (see Section 2.4). call_id Type: ACMSDI_CALL_IDAccess: readMechanism: by referenceThe call iden...
Page 66 - –16 Portable API Presentation Procedures
acmsdi_send 3.9 acmsdi_send TP Desktop Connector client services call this presentation procedure whenevera DECforms SEND request is received from the TP Desktop Connector gatewayon the OpenVMS system. Format acmsdi_send (forms_session, send_record_identifier,send_record_count,receive_control_text,r...
Page 67 - Portable API Presentation Procedures 3–17
acmsdi_send receive_control_text Type: char *Access: writeMechanism: by referenceA 25-character string that the customer-supplied request can use to returnreceive control text. receive_control_text_count Type: long intAccess: writeMechanism: by referenceThe number of receive control text items that ...
Page 68 - –18 Portable API Presentation Procedures
acmsdi_send send_record Type: ACMSDI_FORM_RECORD arrayAccess: readMechanism: by referenceAn array of ACMSDI_FORM_RECORD structures pointing to bufferscontaining 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...
Page 69 - Portable API Presentation Procedures 3–19
acmsdi_transceive 3.10 acmsdi_transceive TP Desktop Connector client services call this presentation procedure whenevera DECforms TRANSCEIVE request is received from the TP Desktop Connectorgateway on the OpenVMS system. Format acmsdi_transceive (forms_session, send_record_identifier,send_record_cou...
Page 70 - –20 Portable API Presentation Procedures
acmsdi_transceive send_record_count Type: long intAccess: readMechanism: by valueThe number of send record items sent from the ACMS task. receive_record_identifier Type: char *Access: readMechanism: by referenceThe form record name or record list name specified in the RECEIVE request inthe ACMS task...
Page 71 - Portable API Presentation Procedures 3–21
acmsdi_transceive send_control_text_count Type: long intAccess: readMechanism: by valueThe number of send control text items sent from the ACMS task. timeout Type: short intAccess: readMechanism: by valueA timeout value for user input processing, sent from the ACMS task. call_id Type: ACMSDI_CALL_ID...
Page 72 - –22 Portable API Presentation Procedures
acmsdi_transceive Return Status The status values returned by the acmsdi_transceive procedure are describedin Section 3.1.1. 3–22 Portable API Presentation Procedures
Page 73 - Portable API Presentation Procedures 3–23
acmsdi_write_msg 3.11 acmsdi_write_msg TP Desktop Connector client services call this presentation procedure whena TDMS Write exchange is received from the TP Desktop Connector gatewayon the host OpenVMS system. Its function is to display the message text sentfrom the ACMS task in the form’s Message...
Page 74 - –24 Portable API Presentation Procedures
acmsdi_write_msg call_id Type: ACMSDI_CALL_IDAccess: readMechanism: by referenceThe call identification returned by the acmsdi_call_task service which initiatedthe ACMS task associated with this exchange. call_context Type: void *Access: readMechanism: by valueApplication-specific context for the ca...
Page 75 - version; Portable API Presentation Procedures 3–25
acmsdi_check_version 3.12 Version-Checking Routines The following sections describe the version-checking routines. Version checkingis supported on systems using FORM I/O tasks (see Compaq TP DesktopConnector for ACMS Client Application Programming Guide). 3.12.1 acmsdi_check_version TP Desktop Conne...
Page 76 - –26 Portable API Presentation Procedures
acmsdi_check_version Return Status The TP Desktop Connector service checks the status value returned andexpects a valid OpenVMS status. If a failure status is returned, the TPDesktop Connector run-time system terminates the ENABLE request. If the version-checking routine determines that software is ...
Page 77 - Always returns SUCCESS status.; Portable API Presentation Procedures 3–27
acmsdi_get_version 3.12.2 acmsdi_get_version The TP Desktop Connector gateway calls this routine on the OpenVMS systemwhenever it receives an ENABLE request from the EXC. The action routinecan return a version string that is then passed to the desktop client program,allowing a version comparison at ...
Page 79 - Forced Nonblocking Client Services; Summary of Forced Nonblocking Procedures; Table 4–1 Summary of Forced Nonblocking Procedures
4 Forced Nonblocking Client Services This chapter describes the forced nonblocking interface between the TPDesktop Connector gateway and customer-written procedures. 4.1 Summary of Forced Nonblocking Procedures Forced nonblocking client services extend the Portable API to supportdevelopment tools th...
Page 81 - Example 4–1 Form Record Definition; unsigned int; Example 4–2 Workspace Structure Definition; Forced Nonblocking Client Services 4–3
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 *...
Page 82 - –4 Forced Nonblocking Client Services
acmsdi_complete_call 4.2 acmsdi_complete_call The acmsdi_complete_call service is a required call that obtains completionarguments for acsmdi_call_task, acsmdi_sign_in, acmsdi_sign_out, andacmsdi_cancel services. When acmsdi_poll detects completion,acmsdi_complete_call can obtain the completion stat...
Page 83 - Forced Nonblocking Client Services 4–5
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 theTP Desktop Connector client services to identify an active call for a submitter.This parameter is required when completing an ...
Page 84 - Table 4–2 acmsdi_complete_call Return Status Values
acmsdi_complete_call Return Status The status values returned by the acmsdi_complete_call procedure aredescribed in Table 4–2. Table 4–2 acmsdi_complete_call Return Status Values Status Description ACMSDI_EXCHACTV Request is invalid while exchange stepprocessing is active. ACMSDI_INSUFPRM Insufficie...
Page 85 - Forced Nonblocking Client Services 4–7
acmsdi_bind_enable_args 4.3 acmsdi_bind_enable_args The client application can call this service whenever acmsdi_poll returnsACMSDI_ENABLE_EXCH from the TP Desktop Connector gateway on theOpenVMS system. This service retrieves the write-only arguments passed fromthe TP Desktop Connector client servi...
Page 86 - –8 Forced Nonblocking Client Services
acmsdi_bind_enable_args form_version Type: char *Access: writeMechanism: by referenceTwenty-four bytes containing the version number or date supplied by theacmsdi_get_version routine on the OpenVMS system. The argument providesfor version checking by the client application. (The acmsdi_check_version...
Page 87 - Forced Nonblocking Client Services 4–9
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. ACMS...
Page 88 - Format; direction; –10 Forced Nonblocking Client Services
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 onthe host OpenVMS system. It performs one of the following f...
Page 89 - Forced Nonblocking Client Services 4–11
acmsdi_bind_msg from ACMS. A value of 0 indicates that the message text for a TDMS Readexchange is being copied to ACMS from the application’s memory. length Type: short intAccess: readMechanism: by valueThe length of the text being sent or the length of the buffer to receive the text;specifically o...
Page 90 - Table 4–4 acmsdi_bind_msg Return Status Values; –12 Forced Nonblocking Client Services
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_BI...
Page 91 - Forced Nonblocking Client Services 4–13
acmsdi_bind_receive_args 4.5 acmsdi_bind_receive_args The client application can call this service whenever an acmsdi_poll returnsACMSDI_RECV_EXCH from the TP Desktop Connector gateway on theOpenVMS system. This service retrieves the write-only arguments passed fromthe TP Desktop Connector client se...
Page 92 - –14 Forced Nonblocking Client Services
acmsdi_bind_receive_args receive_record_count Type: long intAccess: writeMechanism: by referenceThe number of receive record items sent from the ACMS task. The TP DesktopConnector writes the receive_record_count into this location. timeout Type: short intAccess: writeMechanism: by referenceA timeout...
Page 93 - Forced Nonblocking Client Services 4–15
acmsdi_bind_receive_recs 4.6 acmsdi_bind_receive_recs The client application calls this service to send the client application’s receiveforms record data to the TP Desktop Connector gateway on the OpenVMSsystem. Use this service after you have retrieved the exchange step argumentsthat identify the f...
Page 94 - –16 Forced Nonblocking Client Services
acmsdi_bind_receive_recs Return Status The status values returned by the acmsdi_bind_receive_recs service aredescribed 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 ident...
Page 95 - Forced Nonblocking Client Services 4–17
acmsdi_bind_request_args 4.7 acmsdi_bind_request_args The client application can call this service whenever acmsdi_poll returnsACMSDI_REQUEST_EXCH (a TDMS exchange step) from the TP DesktopConnector gateway on the OpenVMS system. This service retrieves the write-only arguments passed from the TP Des...
Page 96 - –18 Forced Nonblocking Client Services
acmsdi_bind_request_args call_id Type: ACMSDI_CALL_ID *Access: writeMechanism: by referenceThe call identification returned by the acmsdi_call_task service. To identifythe original task call, compare this pointer with a reference pointer to the callidentifier obtained by acmsdi_return_pointer. Retur...
Page 97 - Forced Nonblocking Client Services 4–19
acmsdi_bind_request_wksps 4.8 acmsdi_bind_request_wksps The client application calls this service to copy request workspace databetween the client application and the ACMS during a TDMS exchange.Use the acmsdi_bind_request_wksps call to copy request workspace datafrom TP Desktop Connector gateway to...
Page 98 - –20 Forced Nonblocking Client Services
acmsdi_bind_request_wksps Return Status The status values returned by the acmsdi_bind_request_wksps service aredescribed 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 id...
Page 99 - Forced Nonblocking Client Services 4–21
acmsdi_bind_send_args 4.9 acmsdi_bind_send_args The client application can call this service whenever an acmsdi_poll returnsACMSDI_SEND_EXCH from the TP Desktop Connector gateway on theOpenVMS system. This service retrieves the write-only arguments passed fromthe TP Desktop Connector client services...
Page 100 - –22 Forced Nonblocking Client Services
acmsdi_bind_send_args send_record_count Type: long intAccess: writeMechanism: by referenceThe number of send record items sent from the ACMS task. TP DesktopConnector writes the send_record_count into this location. timeout Type: short intAccess: writeMechanism: by referenceA timeout value for user ...
Page 101 - Forced Nonblocking Client Services 4–23
acmsdi_bind_send_recs 4.10 acmsdi_bind_send_recs The client application calls this service to retrieve send forms record data fromthe TP Desktop Connector gateway on the OpenVMS system. Use this serviceafter you have retrieved the exchange step arguments that identify the formsrecords required from ...
Page 102 - –24 Forced Nonblocking Client Services
acmsdi_bind_send_recs Return Status The status values returned by the acmsdi_bind_send_recs service are describedin 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 identificati...
Page 103 - Forced Nonblocking Client Services 4–25
acmsdi_bind_session_id 4.11 acmsdi_bind_session_id You can issue the acmsdi_bind_session_id service to send the forms session IDargument 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_...
Page 104 - –26 Forced Nonblocking Client Services
acmsdi_bind_session_id Return Status The status values returned by the acmsdi_bind_session_id procedure aredescribed 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 identif...
Page 105 - Forced Nonblocking Client Services 4–27
acmsdi_bind_transceive_args 4.12 acmsdi_bind_transceive_args The client application can call this service whenever an acmsdi_poll returnsACMSDI_TRCV_EXCH from the TP Desktop Connector gateway on theOpenVMS system. This service retrieves the write-only arguments passed fromthe TP Desktop Connector cl...
Page 106 - –28 Forced Nonblocking Client Services
acmsdi_bind_transceive_args send_record_identifier Type: char *Access: writeMechanism: by referenceThe form record name or record list name specified in the SEND request inthe ACMS task. Refer to Compaq TP Desktop Connector for ACMS ClientApplication Programming Guide for guidelines on specifying th...
Page 107 - Forced Nonblocking Client Services 4–29
acmsdi_bind_transceive_args Return Status The status values returned by the acmsdi_bind_transceive_args service aredescribed 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 subm...
Page 108 - –30 Forced Nonblocking Client Services
acmsdi_poll 4.13 acmsdi_poll TP Desktop Connector client programs call this nonblocking service to checkfor and process messages sent from a TP Desktop Connector gateway to anactive submitter in the desktop application. The application must periodicallycall this service in a forced nonblocking envir...
Page 109 - Table 4–13 acmsdi_poll Return Status Values
acmsdi_poll For example, if an acmsdi_call_task completion message is sent from the backend, 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 asa 32-bit integer. To determine the structure being referenc...
Page 110 - TDMS Read exchange has arrived; –32 Forced Nonblocking Client Services
acmsdi_poll Table 4–13 (Cont.) acmsdi_poll Return Status Values Status Description ACMSDI_SRVDEAD TP Desktop Connector gateway is notrunning on the server node, or thenetwork link has been terminated. ACMSDI_TDMS_READ_EXCH TDMS Read exchange has arrived ACMSDI_TDMS_WRITE_EXCH TDMS Write exchange has...
Page 111 - System Management Service on OpenVMS; System Management Service on OpenVMS 5–1
5 System Management Service on OpenVMS This chapter describes the system management service available onsystems running the TP Desktop Connector gateway. The ACMSDI$GET_SUBMITTER_INFO service returns information about the status of TPDesktop Connector gateway processing on the submitter node. System...
Page 112 - Note; –2 System Management Service on OpenVMS
ACMSDI$GET_SUBMITTER_INFO 5.1 ACMSDI$GET_SUBMITTER_INFO This service returns information regarding desktop users signed in to theCompaq ACMS system. The service reports only those users signed in to theTP Desktop Connector gateway running on the same node as the programcalling the ACMSDI$GET_SUBMITT...
Page 113 - itmlst; Figure 5–1 shows the item descriptor format.; Figure 5–1 Submitter Item Descriptor Format; The valid item codes are described in Table 5–1.; Table 5–1 Submitter Information Item Codes; Code Name
ACMSDI$GET_SUBMITTER_INFO ACMSDI$GET_SUBMITTER_INFO calls, if the service returns the statusACMSDI$_NORMAL, the program does not modify the variable value. itmlst Type: longword (unsigned)Access: readMechanism: by referenceItem list describing the information to be reported. Itmlst is the addressof ...
Page 115 - Returns the ACMS submitter_ID of the desktop submitter.; System Management Service on OpenVMS 5–5
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 addressin which the ACMSDI$GET_SUBMITTER_INFO servicewrites...
Page 116 - No matching submitter. No submitter matches; –6 System Management Service on OpenVMS
ACMSDI$GET_SUBMITTER_INFO target_username Type: character string descriptorAccess: readMechanism: by descriptorThe user name on which to report. Return Status The status values returned by the ACMSDI$GET_SUBMITTER_INFO serviceare listed in Table 5–2. Table 5–2 ACMSDI$GET_SUBMITTER_INFO Return Status...
Page 117 - Data Compression Monitor Commands; Data Compression Monitor Commands 6–1
6 Data Compression Monitor Commands This chapter provides a description of the Data Compression Monitorcommands that you can use to monitor compression activity. You can shortenall commands and keywords to the smallest unambiguous abbreviation, whichis at most three characters. See Compaq TP Desktop...
Page 118 - EXIT; –2 Data Compression Monitor Commands
EXIT 6.1 EXIT This command exits the Compression Monitor Activity reporting program. Format EXIT 6–2 Data Compression Monitor Commands
Page 119 - HELP; Data Compression Monitor Commands 6–3
HELP 6.2 HELP Displays the help file, SYS$HLP:ACMSDI$DCM_REPORTER_HLP.TXT. Format HELP Data Compression Monitor Commands 6–3
Page 120 - LIST; –4 Data Compression Monitor Commands
LIST 6.3 LIST This command generates a report, which you can display on the screen or writeto 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 applicati...
Page 121 - Data Compression Monitor Commands 6–5
LIST /NODE=(node-identifier[,...]) Selects detailed records associated with task calls originating from the clientnode(s) specified. The node-identifier can be a DECnet node name, TCP/IPaddress, or a list of same. If you specify a list, separate the identifiers withcommas and enclose the list within...
Page 122 - Examples; Selects records for application LARRY.; –6 Data Compression Monitor Commands
LIST all tasks are selected. If tasks specified are part of more than one ACMSapplication, matching task details for all applications are selected, unless younarrow the selection further with the /APPLICATION qualifier. /USER=user-identifier Selects detailed records associated with ACMS task calls e...
Page 123 - Selects all records for task calls from node ALPHA1.; Data Compression Monitor Commands 6–7
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 PANTHR. 10. /NODE=*CPQ* Selects all records for task calls from nodes that contain CPQ in theirnames. 11. /OUTPUT=DAILY_COMPRESSION.RE...
Page 124 - –8 Data Compression Monitor Commands
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 es...
Page 125 - RENEW; Data Compression Monitor Commands 6–9
RENEW 6.4 RENEW This command closes the current log file and opens a new one. The new log fileis a new version of ACMSDI$COMPRESSION.LOG. Format RENEW Data Compression Monitor Commands 6–9
Page 126 - SELECT; file; Qualifiers; –10 Data Compression Monitor Commands
SELECT 6.5 SELECT This command selects records from the log file and writes them to a file fromwhich you can generate customized reports. If you do not specify a qualifier, allrecords are selected. Format SELECT file [/qualifier] Parameters file Is a required parameter that specifies the name of the...
Page 127 - Data Compression Monitor Commands 6–11
SELECT a default input file using the SET command. To override a default input filesetting, use /INPUT=* on the LIST command. /NODE=(node-identifier[,...]) Selects detailed records associated with task calls originating from the clientnode(s) specified. The node-identifier can be a DECnet node name,...
Page 128 - –12 Data Compression Monitor Commands
SELECT identifier(s) have been selected with the SET command. Specifying /USERwith the SELECT command overrides any default user identifiers that mayhave been set. Specifying /USER=* with the SELECT command specifies thatrecords for all user sessions are selected, overriding any defaults that mayhav...
Page 129 - SET; Data Compression Monitor Commands 6–13
SET 6.6 SET This command sets default values for the LIST and SELECT commands. Allqualifiers, except /BEFORE and /SINCE, can have a default value. You canuse the SHOW command to display the current default settings. When you seta default, it applies to all reports you request with the LIST command a...
Page 130 - –14 Data Compression Monitor Commands
SET /OUTPUT=file Directs the report to a file. The file specification must be a valid OpenVMSfile specification. Displaying the report on the screen is the default, unless youspecify the /OUTPUT qualifier with the SET command. Specifying /OUTPUT=*with the LIST command, displays any reports on the sc...
Page 131 - SHOW; Data Compression Monitor Commands 6–15
SHOW 6.7 SHOW This command displays the default values for qualifiers of the LIST andSELECT commands, which you have set with the SET command. All commandqualifiers, except /BEFORE and /SINCE, can have a default value. SpecifyingSHOW without any qualifiers displays all defaults. Format SHOW [/qualif...
Page 133 - Compaq ACMS System Status Values; Table A–1 ACMS System Status Values; Symbol
A Compaq ACMS System Status Values Table A–1 lists the ACMS system status values and their correspondingnumeric values as defined in ACMSDI.H and returned in the err2 parameter,with corresponding symbols. Table A–1 ACMS System Status Values Symbol Value Text ACMSDI_NORMAL 0 Normal completion ACMSDI_...
Page 135 - Compaq ACMS System Status Values A–3
Descriptions of client messages and server messages are provided in thefollowing files: • SYS$HELP:ACMSDI$CLIENT_MESSAGES.TXT • SYS$HELP:ACMSDI$SERVER_MESSAGES.TXT Compaq ACMS System Status Values A–3
Page 137 - Index; Index–1
Index A Access in documentation format, 1–3parameter, 1–1 ACMS$DESKTOP_ID submitter description, 5–5 ACMSDI$GET_SUBMITTER_INFO service description, 5–2sample program using, 5–2 acmsdi_bind_enable_args routine description of interface, 4–7 acmsdi_bind_msg routine, 4–10acmsdi_bind_receive_args routine...
Page 138 - Index–2
ACMSDI_INIT_WORKSPACE data type definition, 2–4 ACMSDI_OPTION array using, 2–11 ACMSDI_OPTION data type structure, 1–2 ACMSDI_OPT_CHECK_VERSION option defined, 2–10example, 2–27 ACMSDI_OPT_COMMID option defined, 2–10example, 2–11 ACMSDI_OPT_END_LIST option defined, 2–10 ACMSDI_OPT_FREE_ROUTINE optio...
Page 139 - See Gateway; Index–3
F Forced nonblocking services described, 4–1specifying, 2–3summary, 4–1 Form record initialization macro, 3–3type 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–1param...
Page 140 - Index–4
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–5desktop gateway, 5–4 program for infor...