# Compaq TP Desktop Connector
for ACMS
Client Application Programming Guide

Previous | Contents | Index

# 3.5 Getting Desktop Submitter Information

To gather TP Desktop Connector runtime information, you can provide a utility program to run on the same system as the gateway. Compaq TP Desktop Connector for ACMS Client Services Reference Manual describes the system management service to use.

A sample image (SHOW_DESKTOP_USERS.EXE), a source file (.C), a linker options file (.OPT), and a build command procedure (.COM) are stored in the ACMSDI$EXAMPLES directory to provide guidelines in coding and building the utility.

## 3.5.1 Coding the Routine

The caller can request all current desktop submitters or can select desktop submitters by user name, ACMS submitter identification, or desktop gateway submitter identification. The following identifications apply to a submitter:

- Desktop gateway submitter identification
  The gateway uses this value internally.

- ACMS submitter identification
  This is the value shown in the output of the ACMS/SHOW commands.
- TP Desktop Connector submitter identification
  This identification is supplied on the desktop system when the desktop client program signs the user in to the ACMS system. It never leaves the desktop and several desktop systems may have desktop client programs running with the same identification value. This identification is neither accepted by nor returned by the ACMSDI$GET_SUBMITTER_INFO service.

To filter which desktop submitters are reported, the ACMSDI$GET_SUBMITTER_INFO service applies all selection values provided on the call. If no selection values are provided, all submitters are reported.

To call the ACMSDI$GET_SUBMITTER_INFO routine, the software must perform these steps:

1. Initialize the user_context parameter to zero.
2. Enter a program loop that invokes ACMSDI$GET_SUBMITTER_INFO.
   To limit the number of submitters reported, specify one or more of the target_submitter_ID, target_desktop_ID, or target_username parameters. To have all submitters reported, specify none of the target parameters.
   Independent of the selection criteria, build the item list to specify what information you want reported about each submitter that matches the criteria. The service reuses the buffers you provide for the output information for each matching submitter. Have the program copy the reported information from the buffer to other program-managed storage.
3. Continue looping until ACMSDI$GET_SUBMITTER_INFO returns a status indicating that no more submitters match the selection criteria.

Because ACMSDI$GET_SUBMITTER_INFO takes a snapshot at the time of the first call, submitters can sign in to or out of the TP Desktop Connector system while the program loop calls the service repeatedly. The service always reports on a consistent set of submitters, the set that is signed in at the time of the first call. But the return status from the final call indicates whether the information reported from the snapshot is still valid as of the final call, or whether the set of submitters changed during the repeated calls.

## 3.5.2 Building the Shareable Image

The C-language prototype for the ACMSDI$GET_SUBMITTER_INFO routine and definitions for the item codes are included in the file ACMSDI.H in the ACMSDI$COMMON directory. Include this file in your C source file to obtain those definitions.

To link your program after you compile it, specify ACMSDI$VMS:ACMSDI$CLIENT_OBJLIB.OLB as an input object library, and SYS$SHARE:VAXCRTL.EXE as an input shareable image library. One way to do this is to create a linker options file (for example, EXAMPLE.OPT) containing these lines:

    ACMSDI$VMS:ACMSDI$CLIENT_OBJLIB/LIB
    SYS$SHARE:VAXCRTL/SHARE

Specify the linker options file on the link command:

    $ LINK your-program.OBJ, EXAMPLE.OPT/OPT

Store the program in a protected directory.

After you install TP Desktop Connector software, the ACMSDI$EXAMPLES directory contains an example program SHOW_DESKTOP_USERS.EXE that uses the ACMSDI$GET_SUBMITTER_INFO service. SHOW_DESKTOP_USERS.C and .OPT are the C-language source and the linker options files. The command procedure BUILD_SHOW_DESKTOP_USERS.COM includes the link command to build the image.

To modify the sample, copy the files to your own directory:

    $  COPY ACMSDI$EXAMPLES:*SHOW_DESKTOP_USERS*.* *.*

Compile the program using the following command:

    $  CC /INCLUDE=ACMSDI$COMMON: SHOW_DESKTOP_USERS.C

Link the resulting object into an image using this command:

    $  @BUILD_SHOW_DESKTOP_USERS

This creates SHOW_DESKTOP_USERS.EXE in your directory. Run the image using this command:

    $  RUN SHOW_DESKTOP_USERS
     TP Desktop Connector            Desktop Node Local           Sign-in Time
    Submitter     Submitter           Transport Username         Latest Message Time
      2790021    F8360;BD                 63571 SMITH         8-FEB-1993 11:19:32.30
                                         DECnet               8-FEB-1993 11:19:32.30

# 3.6 Debugging TP Desktop Connector Solutions

Several approaches are available for you to debug your TP Desktop Connector solution. You can debug:

- Desktop client program only
- NO I/O tasks
- Tasks called from desktop client programs
- Procedure server code

## 3.6.1 Debugging the Desktop Client Program Only

During your software development, it is useful to run your desktop client program independently of the ACMS application. To be able to run the desktop client program independently, write stub routines that emulate the processing expected on a call to the ACMS application, and link your desktop client program with these routines rather than the TP Desktop Connector client services. After you debug the desktop client program, relink it with the TP Desktop Connector client services. Part 2 describes debugging for each type of desktop system.

## 3.6.2 Debugging NO I/O Tasks

With ACMS applications that use NO I/O tasks, you can debug both the tasks and the step procedures without using the desktop system or the gateway. Use the ACMS Task Debugger to completely simulate the behavior of both the desktop system and the gateway for the desktop system. This technique works only for tasks having BLOCK WORK WITH NO I/O declared.

Although the ACMS Task Debugger is not a source-level debugger, it works with the OpenVMS Debugger so the procedure server (written in any OpenVMS third-generation language) is accessed by means of the OpenVMS Debugger. When the procedure server returns to the ACMS task, the ACMS Task Debugger regains control and allows step, breakpoint, deposit, examine, and other basic Debugger functions on the ADU task definition code.

To emulate a submitter, make a command file containing deposit statements that write reasonable test case values into the workspaces used in the call to the procedure server. When the task is finally activated, arguments to the task are expressed in workspace data passed to the task. To emulate the submitting desktop system, load workspace arguments as the desktop client program does when it calls the task. The ACMS Task Debugger supports command files that are executed (@filename syntax) at the ACMSDBG prompt. All ACMS Task Debugger commands can be executed from a command file (including other command files).

After making the command file, debug by following these steps:

1. Start the procedure server with the START SERVER command (before the task is selected).
2. Set OpenVMS Debugger breakpoints in the procedure server.
   Set a breakpoint at TASK-NAME\STEP-LABEL\$BEGIN> for the task and processing step that calls the procedure server process.
3. Select the task and step to the breakpoint.
4. Execute the command file that sets up the workspace records for the test case.
5. Examine the workspaces to confirm that they are as needed.
6. Step through the procedure server.
   If you compiled and linked the procedure server with /DEBUG options, the procedure server can be debugged exactly as any third-generation code under OpenVMS. The ACMS Task Debugger steps into the procedure server under OpenVMS Debugger control.
   If the procedure server was not compiled and built with /DEBUG options, the OpenVMS Debugger steps through it.
7. Confirm that the results are as expected by examining the data passed out of the procedure server call.

When the tasks and procedure servers are behaving as expected using this technique, you can then call the NO I/O tasks from your desktop client program, using the technique described in Section 3.6.3.

## 3.6.3 Debugging Tasks Called from Desktop Client Programs

To debug tasks, use the ACMS Task Debugger. The debugging steps are similar to those described for debugging tasks called from a user-written agent in Compaq ACMS for OpenVMS Writing Server Procedures.

TP Desktop Connector allows you to bring up multiple copies of the gateway on a single CPU, and to route a client connection explicitly to one of these copies of the gateway. This facility, provided only for debugging purposes, allows multiple developers at the same time and on the same OpenVMS system to debug tasks called from TP Desktop Connector client programs.

Note Using multiple gateways on a single CPU is not supported for production purposes.

To use the multiple gateway capability to debug tasks called from client programs, follow these steps:

1. Define the ACMS$DEBUG_AGENT_TASK logical name in one of the logical name tables for the user name under which you will be starting a copy of the gateway. The following example assumes that you are signed in to an ACMSDI_TEST account:

       $ DEFINE/GROUP ACMS$DEBUG_AGENT_TASK "Y"

   If your ACMS system and a gateway are currently running, you must stop and restart them. The ACMS$DEBUG_AGENT_TASK logical name is recognized only by agent processes in the group for which the logical name has been defined, and which are started after you have made this assignment.
2. Create or edit your gateway startup parameter file to define values for the SERVER_NAME and DECNET_OBJECT keywords. The names can be no longer than 5 characters.
   For example:
   - DECnet

         SERVER_NAME=SMITH
         DECNET_OBJECT=187

   - NetWare

         SERVER_NAME=SMITH
         NETWARE_PORT=33659

   - TCP/IP

         SERVER_NAME=SMITH
         TCPIP_PORT=1022

   - All three: DECnet, NetWare, TCP/IP

         SERVER_NAME=SMITH
         DECNET_OBJECT=187
         NETWARE_PORT=33659
         TCPIP_PORT=1022

   See Section 3.6.3.8 for information on using transports other than DECnet.
3. Run the ACMSDI$STARTUP.COM command procedure to start the TP Desktop Connector Gateway for ACMS, specifying the gateway startup parameter file containing your keyword definitions. For example:

       $ SUBMIT/USER=ACMSDI_TEST/NOLOG SYS$STARTUP:ACMSDI$STARTUP -
       _$ /PARAM= SYS$STARTUP:SMITH.PRM

   Assuming that the keyword declarations shown in the previous example are defined in a user-created SMITH.PRM file in SYS$STARTUP, this command starts a gateway with the process name ACMSDI$SRVSMITH connected to DECnet object 187. By specifying a user name, you associate a group logical name table with this gateway that is different from the logical name table associated with a production version of the gateway.
   The ACMSDI_TEST account must have NETMBX, TMPMBX, SYSNAM, SYSPRV, SYSLCK, and CMKRNL privileges. The process issuing this command must have NETMBX and CMKRNL privileges.
   This command can be incorporated into an ACMS task, using a DCL process server, so that users starting and stopping the server do not need to have system privileges. See Section 3.6.3.11.
4. Start an ACMS task debugger session, specifying the /AGENT_HANDLE qualifier. Set breakpoints, and then type ACCEPT to enable the task debugger session to receive task calls through your TP Desktop Connector gateway.
   For example:

       $ SET PROCESS/PRIV=SHARE
       $ ACMS/DEBUG/AGENT_HANDLE=SMITH_TEST PERS_GROUP.TDB/WORKSPACE
       ACMSDBG> SET BREAK PERS_UPDATE_TASK
       ACMSDBG> START PERS_SERVER
       DBG> SET BREAK PERS_GET_RECORD
       DBG> GO
       ACMSDBG> ACCEPT/CONTINUOUS

   Using an agent handle like SMITH_TEST (rather than PERS_GROUP) enables multiple users to work on the same task group in different task debugger sessions, at the same time. It is not necessary to create multiple versions of the task group, only to specify a unique agent handle.
   You can use a logical name to associate the agent handle with the application name used by a client program. See Section 3.6.3.2 for this information.
5. On the desktop client, set the environmental variable (or logical name, for OpenVMS clients) ACMSDI_DECNET_OBJECT_node to the object number you specified in starting the gateway. The node is the DECnet node name you will be specifying as the submitter-node parameter in ACMSDI_SIGN_IN. For example, if you are going to connect to ACMTST (in this case, using DECnet from a DOS client):

       > SET ACMSDI_DECNET_OBJECT_ACMTST 187

   Run tasks from your client program, specifying SMITH_TEST as the application name in the ACMSDI_CALL_TASK service or the DBSend call which initializes the application name on the Macintosh. The following notice appears on the terminal at which you are running the task debugger process:

       ACMSDBG>
       Terminal is in SERVER SMITH_TEST

   See Section 3.6.3.8 for information on using transports other than DECnet.
6. When you are finished with the debugging session, exit from the task debugger and stop your gateway process:

       ACMSDBG> EXIT
       $ @SYS$STARTUP:ACMSDI$SHUTDOWN SMITH

   You can also deassign the ACMSDI$DEBUG_AGENT_TASK logical. Or you can start another task debugger session to debug other tasks in the same or another group. Note that you must stop your gateway in order to run another task debugger session, even if you want to bring up the same task group that you were just debugging.

These steps, and additional options you have in using the multiple server feature, are explained more fully in the sections that follow.

### 3.6.3.1 Defining the Gateway Process and Network Names

Multiple gateways on a single OpenVMS system are distinguished from each other both by their process names and by the network name or object number they are associated with. These values, as well as resource utilization and other aspects of the gateway, are determined at gateway startup.

The default name for the gateway is ACMSDI$SERVER. If you start additional gateways on the node, TP Desktop Connector assigns them process names of the form ACMSDI$SRV(extension). The (extension) is a user-supplied suffix of up to 5 characters. This suffix distinguishes one gateway from another, and forms an OpenVMS process name, which is limited to 15 characters.

The command file SYS$STARTUP:ACMSDI$STARTUP.COM has been extended to handle the starting of multiple gateways. The naming of the gateway and whether or not it is considered the primary gateway is determined by keywords that you can add to a user-created parameter file. The keywords are SERVER_NAME, DECNET_OBJECT, TCPIP_PORT, and NETWARE_PORT.

When invoking ACMSDI$STARTUP.COM, the optional parameter file is used to define logical names from the keywords. The logical names are defined in the process logical name table, for the process which invokes ACMSDI$STARTUP.COM. If the keywords are not specified or are specified as null, the process logical names are not defined. The keywords that control gateway communication are listed in Table 3-1 with their associated logical names.

Table 3-1 Gateway Communication Keywords
Parameter File | Logical Name | Default | Sample
--- | --- | --- | ---
SERVER_NAME | ACMSDI$SERVER_NAME | Uses decnet_object | DBG1
DECNET_OBJECT | ACMSDI$DECNET_OBJECT | 87 | "TASK=DBG1"
TCPIP_PORT | ACMSDI$TCPIP_PORT | 1023 | 1022

For example, you can include the following declarations in a gateway startup parameter file:

    SERVER_NAME=DBG1
    DECNET_OBJECT="TASK=DBG1"

This startup file starts a gateway with process name ACMSDI$SRVDBG1, accessible for clients that specify DBG1 as the DECnet objectname with which to connect. The object number is assigned by DECnet. The name or number specified by the DECNET_OBJECT keyword is used to select the DECnet object that a gateway uses to listen for client connections when the DECnet transport is active. The DECNET_OBJECT can name a numbered DECnet object (DECNET_OBJECT = 187) or a named DECnet object (DECNET_OBJECT = "TASK=DBG1"). If additional gateways using DECnet are started, DECNET_OBJECT must be defined to be a unique object identifier. The object name is a suffix of up to 5 characters.

Similarly, the number specified by the TCPIP_PORT keyword specifies the TCP/IP port number used for client connections. For forced nonblocking calls, you also have the ability to specify your gateway node TCP/IP port number dynamically without having to define the environmental variable. See Compaq TP Desktop Connector for ACMS Gateway Management Guide for more information on setting values for this keyword and specifying the port number dynamically.

The name specified by the SERVER_NAME keyword is used to distinguish between multiple gateways on the same node by providing a gateway naming extension. The value is a name suffix of up to five characters, which is appended to ACMSDI$SRV to create the process name; for example, if SERVER_NAME is specified as DBG1, the gateway process name is ACMSDI$SRVDBG1.

If SERVER_NAME is not specified, then the DECNET_OBJECT, or TCPIP_PORT name is also used to distinguish between gateways. In this case, the DECNET_OBJECT name, for example, is used as a gateway name suffix (not including "TASK="). If neither SERVER_NAME nor DECNET_OBJECT is defined, then the default process name of ACMSDI$SERVER and DECnet object 87 is used.

Note A single client process can start multiple sessions to the same gateway on one node or multiple sessions to individual gateways on different nodes. However, a single client process cannot start second session to an alternate gateway on a node to which it already has a gateway connection established. That is because the client services cannot distinguish the difference between different gateways on the same node and multiplex subsequent sessions over the one connection to the initial gateway. However, you can have multiple client programs active at the same time on a desktop system and connected to different gateways on a single node.

### 3.6.3.2 Defining Logical Names

Before starting the gateway, you must define the logical name, ACMS$DEBUG_AGENT_TASK, in a logical name table associated with that process. For example, if you are in the same group as the user name under which the gateway will be started, you can use this command:

    $ DEFINE/PROC ACMS$DEBUG_AGENT_TASK "TRUE"

The ACMS$DEBUG_AGENT_TASK logical name instructs ACMS to direct task selection requests to task debugger processes rather than to ACMS EXC processes. If this logical name has been set for a gateway or another ACMS agent, any task selection handled by that gateway or agent which specifies an application name for which there is no corresponding task debugger session fails with the "application not found" message.

This logical name affects only those gateways or agents for which it has been defined. You can, therefore, have both production and debug systems on the same OpenVMS node, as long as the ACMS$DEBUG_AGENT_TASK logical has not been defined for the ACMSDI$SERVER process.

The relationship between the application name specified by the client program and the task debugger process which will receive the task calls can be established in either of two ways:

- The application name specified in task call is the same as the string specified in the /AGENT_HANDLE qualifier for the ACMS/DEBUG command.
- The application name specified in task call is the same as a logical name in one of the gateway's logical name tables, whose equivalence name is the string specified in the /AGENT_HANDLE qualifier for ACMS/DEBUG.

For example, if the current process is in the same group as the name under which your gateway is started, you can use this command to set up a logical name for the application:

    $ DEFINE/GROUP PERS_APPL SMITH_TEST

In this example, the client program calls tasks in an application named PERS_APPL. The task debugger session, however, is started with the agent handle set to SMITH_TEST, as shown in Figure 3-1.

Figure 3-1 Task Debugger Session

With this approach, the application names in the client program need not change to identify unique task debugger sessions for different users.

The logical name relationship between the application name and the agent handle can be set up by TP Desktop Connector for your gateway process if you include the DEBUG_APPLICATION_NAME and DEBUG_AGENT_HANDLE keywords in your startup parameter file. For example:

    DEBUG_APPLICATION_NAME = PERS_APPL
    DEBUG_AGENT_HANDLE     = SMITH_TEST

The equated value of the DEBUG_APPLICATION_NAME keyword is used as the logical name. The equated value of the DEBUG_AGENT HANDLE keyword is used as the equivalence name. In addition, if you use these keywords, TP Desktop Connector also sets the ACMS$DEBUG_AGENT_TASK logical to "TRUE". In this way, you do not need to have GROUP or other privileges to define these logical names.

Previous | Next | Contents | Index