| Previous | Contents | Index |
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:
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 |
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:
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:
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:
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:
> SET ACMSDI_DECNET_OBJECT_ACMTST 187 |
> 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:
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 187 |
"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:
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. |
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.
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:
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
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.
| 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 |