# Compaq TP Desktop Connector
for ACMS
Client Application Programming Guide

Previous | Contents | Index

### 3.6.3.3 Required Privileges

Several privileges are required for the user name under which a gateway is started, regardless of whether named or numbered DECnet objects are used. These privileges are:

- NETMBX
- TMPMBX
- SYSNAM
- SYSPRV
- SYSLCK
- CMKRNL

When starting the gateway, you can either invoke SYS$STARTUP:ACMSDI$STARTUP.COM directly, or you can use the SUBMIT command to start the gateway under a user name other than your own.

To invoke ACMSDI$STARTUP.COM directly, the process invoking the command procedure must have all six privileges in addition to the DETACH and OPER privileges.

To invoke ACMSDI$STARTUP.COM with the SUBMIT/USER command, the process issuing the SUBMIT command must have NETMBX and CMKRNL privileges. It does not have to have the other privileges listed in this section. However, the user name specified in the /USER qualifier must have all six privileges.

### 3.6.3.4 Installing the TP Desktop Connector Gateway for ACMS Images

If you have many users who are starting gateways, you can install the gateway images to reduce the image activation and memory utilization costs for running the gateway. Create a command file (for example, SYS$STARTUP:ACMSDI$INSTALL.COM), which you invoke from your system startup file, containing the following commands:

    $ INSTALL ADD/OPEN/SHARE SYS$SYSTEM:ACMSDI$SERVER
    $ INSTALL ADD/OPEN/SHARE SYS$SHARE:ACMSDI$SERVER_SHR

### 3.6.3.5 Troubleshooting Problems in Starting Multiple Gateways

If you receive an error in starting the gateway, check the Software Event Log for additional information on why the gateway could not be started. Conditions that can cause the gateway startup to fail include:

- Another gateway of the same name or with the same DECnet name or object number is already started.
- Insufficient system resources exist to start the gateway.
- User name quota values are insufficient to start the gateway.
- The process that is starting the gateway or the user name under which the gateway is being started do not have sufficient privileges.

### 3.6.3.6 Starting the TP Desktop Connector Gateway for ACMS from an ACMS Task

To minimize the privileges assigned to the individuals who may need to stop and start the gateway, create an ACMS task that users can invoke to start the gateway. For example:

      REPLACE TASK START_SVR_TASK
      BLOCK
        PROCESSING IS
          DCL COMMAND "SUBMIT/USER='P1 @SYS$STARTUP:ACMSDI$STARTUP.COM 'P2"
            IN START_SVR_SERVER;
      END BLOCK;
      END DEFINITION;

Define ACMSDI_START_SERVER in the task group as a DCL PROCESS server. In the application, assign to the gateway a user name that has NETMBX and CMKRNL privileges so that it can issue the SUBMIT/USER command; define the ACL for this task to allow access by any appropriate users. The users can then use the SELECT command from any ACMS menu to invoke this function:

    Selection: SELECT start_svr_appl start_svr_task acmsdi_test test:smith.prm

In this example, acmsdi_test is the user name under which the gateway is started. SMITH.PRM is the name of the parameter file in the directory pointed to by the logical name TEST.

### 3.6.3.7 Running the Task Debugger Session

A process running the ACMS Task Debugger (ACMSDBG) is dedicated to debugging a single ACMS task group. Users use the ACMS/DEBUG to invoke the ACMSDBG.EXE image in their process. The procedure servers that the ACMS Task Debugger starts are run in subprocesses associated with the user process.

To debug a task, the task group definition must be built with the /DEBUG qualifier:

    ADU> BUILD GROUP/DEBUG dbg_task_group

If the task group is not built with /DEBUG, you can start the task group in the task debugger, set breakpoints, and run tasks. However, you cannot examine or deposit workspace values.

Compile and link the step procedures with the /DEBUG qualifier. Otherwise, you cannot set breakpoints, or examine and deposit variables.

Before starting the task debugger, define any logical names you need for your procedure servers. These include any names you would normally include in the application definition SERVER LOGICALS clause, or that you would define in logical name tables accessible to the procedure servers.

To start the ACMS Task Debugger, use ACMS/DEBUG:

- Include the name of the .TDB task group database file containing the tasks to be run. Only one task group can be debugged at a time.
- Use the /AGENT_HANDLE qualifier to provide the ACMS Task Debugger with a unique handle to the agent that will be submitting the tasks.
- Use the /WORKSPACE qualifier to enable examining and depositing in workspaces.

For example:

    $ ACMS/DEBUG/WORK/AGENT_HANDLE=SMITH_TEST PERS_GROUP
    ACMSDBG> SET BREAK PERS_UPDATE_TASK
    ACMSDBG> ACCEPT/CONTINUOUS

SMITH_TEST is the agent handle assigned for this task debugger process. PERS_GROUP.TDB is the name of the task definition file that you are debugging. SET BREAK establishes a breakpoint at the start of PERS_UPDATE_TASK. ACCEPT/CONTINUOUS prepares the task debugger process to receive task calls from the gateway. At this point, your process waits to receive either a task call, Ctrl/C, or Ctrl/Y.

Make sure that the gateway from which you will be accepting task calls is on the same OpenVMS system as your task debugger process. With the task debugger, you cannot use the application routing capability that is available when you are calling tasks in the normal ACMS runtime system.

The following restrictions apply when running a task debugger session with /AGENT_HANDLE specified:

- To run tasks in this debugger session, you must invoke them from a client program through the gateway, or from another ACMS agent. Do not select tasks from within the task debugger (that is, by using the SELECT command).
- If you want to end a task, do so from the client program rather than by using the CANCEL command in the task debugger.
- Make sure that you run only one task at a time in the task debugger session. If you need to test several tasks at one time (in multiple sign-ins) from the client program, set up a task debugger session for each of the sign-ins that you are going to create.

As you complete a task, you can start another task without leaving the task debugger. You can stop and start procedure servers within that task debugger session. However, once you exit from that task debugger session, you must also stop the gateway associated with that session. If you are going to do further debugging, restart your gateway, then restart your task debugger session. If you are not going to do any further debugging, also deassign the ACMS$DEBUG_AGENT_TASK and debug application logical name (if any) associated with your task debugger session.

### 3.6.3.8 Selecting a Gateway from a Portable API Client Program

To establish a connection between a client program and a gateway other than ACMSDI$SERVER (object 87), you must use the logical names (on OpenVMS) or the environmental variable (on DOS or SCO UNIX) ACMSDI_DECNET_OBJECT_node to define the gateway you want to invoke. The node in this case is the DECnet node name of the system to which you want to connect.

You can define one of two equivalence values for the ACMSDI_DECNET_OBJECT_node logical name or environmental variable:

- object_number
  Specifies a DECnet object number, in the range 128 to 255. For example:

      > SET ACMSDI_DECNET_OBJECT_ACMTST 187

- "task-name"
  Specifies the DECnet object name, up to 5 characters. For example:

      > SET ACMSDI_DECNET_OBJECT_ACMTST "SMITH"

Similarly, for transports other than DECnet, you define logical names or environmental variables that specify the port to which you want to connect. For TCP/IP, define ACMSDI_TCPIP_PORT_host to the same number that you assigned to the TCPIP_PORT keyword in the gateway startup parameter file. For example (for UNIX):

    # setenv ACMSDI_TCPIP_PORT_host 1023

If the environmental variable ACMSDI_NETWARE_SOCKET_yournode is set to the socket number (for example, 33659) then the client attempts to connect to the gateway that is using the socket with a port number of 33659:

    > SET ACMSDI_NETWARE_SOCKET_yournode=33659

where:

- yournode is the OpenVMS node name on which the ACMSDI$SERVER is running.
- 33659 is the port number assigned in the gateway startup parameter file set on the OpenVMS system, by using the keyword NETWARE_PORT=33659.

You can start multiple sessions from a single client program. However, to run a task in more than one of those sessions at one time, you must have a separate task debugger session started for each of the tasks you want to run simultaneously.

### 3.6.3.9 Selecting a Gateway from a Macintosh Client

To establish a connection between a Macintosh client program and a gateway other than ACMSDI$SERVER (object 87), you must use the keyword Object or RemoteTCPPort in the connection string parameter for DBInit. For example:

    short status;
    long sessid;
    char username[255]
    char password [255]
    #define ddev  "\ACMSDI"
    #define node  "\pBOSTON"
    #define connstring "\p\"DECnet Tool\"Object 187\""

        status = get_access( &username, &passwod );
        if (status != noErr)
            my_exit (status, 0, "Could not get username and password")

        status = DBInit (&sessid,
                         ddev,
                         node,
                         username,
                         password,
                         connstring,
                         NULL)
        if (status != noErr)
            my_exit (status, 0, "DBInit Failed");

Multiple gateways can also be used with the AppleTalk/DECnet Gateway. Specify the Object keyword in the connection string, along with the AppleTalk-DECnet Tool string, gateway name, and zonename (if any).

You can assign one of two values for the Object keyword:

- object_number
  Specifies a DECnet object number in the range from 128 to 255. For example:

      Object 187

- "task-name"
  Specifies the DECnet object name up to 5 characters. For example:

      "Object SMITH"

Similarly, for TCP/IP, you can use the keyword RemoteTCPPort rather than Object, in the connection string. Set RemoteTCPPort to the same number as you assigned to the TCPIP_PORT keyword in the gateway startup parameter file.

You can start multiple sessions from a single client program. However, to run a task in more than one of those sessions at one time, you must have a separate task debugger session started for each of the tasks that you want to run simultaneously.

### 3.6.3.10 Managing TP Desktop Connector Gateways Used for Debugging Purposes

All gateway capabilities, such as ACMSDI$GET_SUBMITTER_INFO, SHOW_DESKTOP_USERS, and Oracle Trace support, are available with multiple gateways.

To use ACMSDI$GET_SUBMITTER_INFO, you must define ACMSDI_DECNET_OBJECT_node on the OpenVMS node on which you are issuing the ACMSDI$GET_SUBMITTER_INFO service. For example:

    $ DEFINE/GROUP ACMSDI_DECNET_OBJECT_0 187

Use 0 rather than the DECnet node name when defining this logical name. The definition must be in a logical name table visible to the gateway whose number or name you specify as the equivalence name. Only the information from that gateway is returned.

### 3.6.3.11 Stopping a TP Desktop Connector Gateway for ACMS

The command procedure SYS$STARTUP:ACMSDI$SHUTDOWN takes an optional parameter value to specify a particular gateway process to stop. Use the process name as the parameter value. For example:

    $ @SYS$STARTUP:ACMSDI$SHUTDOWN DBG1

If you do not specify the parameter when invoking ACMSDI$SHUTDOWN.COM, ACMSDI$SERVER is stopped.

### 3.6.3.12 Restrictions on Using Multiple Gateways

The following restrictions apply when using the multiple gateway feature:

- Multiple gateways are supported for use in debugging only. For production systems, there must be only one gateway per OpenVMS system; that gateway must run under the default ACMSDI$SERVER user name, using the DECnet object 87 that Compaq has assigned for the gateway.
- NetWare and TCP/IP have guaranteed port numbers. For NetWare, the port number is hexadecimal 837A, or decimal 33658. For TCP/IP, the port number is decimal 1023.

  Note Check that the numbers you choose for DECnet object numbers and NetWare and TCP/IP port numbers are not taken by another application on your system.

- The ACMSDI gateway must be running on the same node as the ACMS task debugger process that will be invoked by it on a task call.
- Only a single submitter can use an ACMSDI gateway started with ACMS$DEBUG_AGENT_TASK enabled. When the ACMSDI$SERVER image is started with ACMS$DEBUG_AGENT_TASK, it is identified as an agent to be used with an ACMS task debugger process. When the gateway submits a task in an application whose translated name matches a unique agent handle, that gateway become associated with that particular ACMSDBG.EXE; the gateway is not accessible to any other task debugger process.
- After the ACMSDBG debugging session has been terminated, the ACMSDI gateway associated with that session cannot be used for other users. Nor can it be used for another task debugger session started by the same user. The ACMSDI gateway associated with the terminated ACMSDBG debugging session must be stopped; a gateway using the same name can then be restarted for another debugging session by the same or a different user.
- An ACMSDBG debugging session is restricted to a single task group. If the tasks called by a client program are normally in one application (.ADB file), but that application contains several task groups (.TDB file), then the task debugger session and TP Desktop Connector gateway must be stopped and restarted for each of the task groups.

## 3.6.4 Debugging Procedure Server Code

An online server debugging technique provided on the ACMS system lets you place procedure servers running on line (that is, outside the ACMS Task Debugger context and in the ACMS production context) into the OpenVMS Debugger. However, this technique has no ACMS task-level debugging. The OpenVMS Debugger is invoked when the procedure server actually starts. See the ACMS documentation for information on online server debugging.

# Part 2
Portable API and Macintosh Client Development

Part 2 describes procedures to develop desktop client programs using the TP Desktop Connector portable API or the TP Desktop Connector Macintosh API. General design and development issues are discussed in Part 1. Refer to Compaq TP Desktop Connector for ACMS Client Services Reference Manual for reference information about each desktop system.

# Chapter 4
Developing Portable API Client Programs

This chapter provides guidelines for developing desktop client programs for the portable application programming interface (API). Examples in this chapter use DOS code to illustrate the use of the blocking form of the TP Desktop Connector client services.

For information on configuring network transports for any of the client platforms, refer to Compaq TP Desktop Connector for ACMS Gateway Management Guide.

# 4.1 Guideline Summary

The following sections summarize the guidelines for developing desktop programs using the portable API client services.

## 4.1.1 Managing Code on the Desktop Client System

To effectively manage the relationship between elements of the desktop client program and the Compaq ACMS application for I/O tasks, create and use a library of application-specific presentation procedures that equate one-to-one to exchange steps. (This is the approach used in the DOS sample application in Section 4.4.)

## 4.1.2 Structuring Exchange Steps in the Presentation Code

If you are using I/O tasks in your solution, your desktop client program includes the following components:

- Main program
  Contains procedures for signing the user in to the ACMS system, handling menus and task selections, and signing the user out of the ACMS system.

- Presentation procedures
  Contain presentation code for handling interactions with a user to display and gather data during exchange step execution in an I/O task.

To handle the terminal I/O in an exchange step, a ACMS application typically calls DECforms or TDMS services. However, when using the TP Desktop Connector software, those calls are made to the desktop client program. Linked into the desktop client program, customer-written routines provide the logic to perform the exchange step processing on the desktop system.

TP Desktop software defines the interface for presentation procedures, but the application developer writes the actual code for the presentation procedures. Customer-written presentation procedures are called by TP Desktop Connector client services to handle ACMS exchange steps.

The desktop client program can use any appropriate forms-processing or presentation tool to interact with the user. Because procedures to handle task selection can also gather data from the user for input to the task, the distinction between the desktop client program and presentation procedures is somewhat arbitrary. However, it is a significant distinction.

Presentation procedures run on behalf of exchange steps in the task on the ACMS application node. The main part of the desktop client program requests a task that the TP Desktop Connector Gateway for ACMS handles. When the task executes an exchange step, the TP Desktop Connector Gateway for ACMS calls the desktop client program using the same network link. The TP Desktop Connector client services on the desktop system call the presentation procedure in the desktop client program. The appropriate customer-written presentation procedure in the desktop client program executes.

If the TP Desktop Connector software cannot invoke the presentation procedure, it returns a fatal status to the desktop gateway. The fatal status is returned to EXC, which decides whether to cancel the task based on the task definition.

Figure 4-1 shows the execution flow to process presentation procedures.

Figure 4-1 Processing of Presentation Procedures

## 4.1.3 Data Conversion

Because TP Desktop Connector software does not manipulate workspace contents, it does not constrain what data types are used on the desktop system or in the ACMS application. However, TP Desktop Connector software does not automatically handle data conversion between the Compaq OpenVMS and desktop systems. DOS data types are readily mapped to OpenVMS data types, and OpenVMS to DOS.

ACMS applications are constrained in their workspace definitions by the data types supported by Oracle CDD software. Table 4-1 shows Microsoft C and Microsoft COBOL equivalents for some of the more commonly used Oracle CDD data types.

Table 4-1 Language and Oracle CDD Data-Type Equivalents
Oracle CDD | Microsoft C | Microsoft COBOL
--- | --- | ---
DATE |  |
NUMERIC SIZE n |  | 9( n)
SIGNED BYTE | signed char |
SIGNED LONGWORD | signed long | S9(9) COMP-5
SIGNED LONGWORD SCALE -2 |  | S9(7)V9(2) COMP-5
SIGNED QUADWORD |  | S9(18) COMP-5
SIGNED QUADWORD SCALE -2 |  | S9(16)V9(2) COMP-5
SIGNED WORD | signed short | S9(4) COMP-5
SIGNED WORD SCALE -2 |  | S9(2)V9(2) COMP-5
TEXT SIZE n | char[ n] | X( n)
UNSIGNED BYTE | unsigned char |
UNSIGNED LONGWORD | unsigned long | 9(9) COMP-5
UNSIGNED QUADWORD |  | 9(18) COMP-5
UNSIGNED WORD | unsigned short | 9(4) COMP-5

Note that certain Oracle CDD data types have no direct equivalents for some languages. For example, SIGNED WORD SCALE --2 has no direct equivalent in the Microsoft C language. However, the Oracle CDD data type can be supported indirectly; for example, SIGNED WORD SCALE --2 can be supported in Microsoft C software by using a signed short and dividing it by 100 before it is displayed to the user.

The DATE data type has no direct equivalent in desktop languages. You can allocate the correct length storage for the DATE data type by using a quadword equivalent in the desktop language. However, routines for converting the DATE data type from binary to display format are not available on desktop systems. Therefore, convert a date field to a text field for the workspace using the 10-character international date format (YYYY MM DD) that DECforms and Oracle Rdb software support.

Refer to Oracle CDD User's Guide and the reference manual for the desktop language you are using for more information on data-type compatibility.

Previous | Next | Contents | Index