| Previous | Contents | Index |
To gather TP Desktop Connector runtime information, you can provide a utility program to run on the same system as the gateway. DIGITAL 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, DIGITAL ACMS submitter identification, or desktop gateway submitter identification. The following identifications apply to a submitter:
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:
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 DIGITAL 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
|
Several approaches are available for you to debug your TP Desktop Connector solution. You can debug:
During your software development, it is useful to run your desktop
client program independently of the DIGITAL 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
DIGITAL 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 DIGITAL 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 DIGITAL 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 DIGITAL 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 DIGITAL ACMS task, the DIGITAL 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 DIGITAL ACMS Task Debugger supports command files that are executed (@filename syntax) at the ACMSDBG prompt. All DIGITAL 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:
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 DIGITAL 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.
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:
$ DEFINE/GROUP ACMS$DEBUG_AGENT_TASK "Y" |
SERVER_NAME=SMITH DECNET_OBJECT=187 |
SERVER_NAME=SMITH NETWARE_PORT=33659 |
SERVER_NAME=SMITH TCPIP_PORT=1022 |
SERVER_NAME=SMITH DECNET_OBJECT=187 NETWARE_PORT=33659 TCPIP_PORT=1022 |
$ SUBMIT/USER=ACMSDI_TEST/NOLOG SYS$STARTUP:ACMSDI$STARTUP - _$ /PARAM= SYS$STARTUP:SMITH.PRM |
$ 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 |
> SET ACMSDI_DECNET_OBJECT_ACMTST 187 |
ACMSDBG> Terminal is in SERVER SMITH_TEST |
ACMSDBG> EXIT $ @SYS$STARTUP:ACMSDI$SHUTDOWN SMITH |
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.
| 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 DIGITAL 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.
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. |
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:
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 |