Compaq TP Desktop Connector
for ACMS
Gateway Management Guide

2.2.2 Authorizing ACMS Users

The user of the application must be an authorized ACMS user on the submitter node. Run the ACMS User Definition Utility on the submitter node and add the user account names. For example:

$ SET DEFAULT SYS$SYSTEM $ RUN ACMSUDU UDU> ADD RODRIGUEZ UDU>

ACMS menus and other user attributes (except for forms-print-file and forms-language) defined in ACMSUDU are not applicable to desktop users.

Authorize as an agent the account under which the gateway runs:

UDU> ADD SYSTEM/AGENT UDU>

If you use the system startup procedure to start the gateway, the OpenVMS account SYSTEM runs the gateway.

2.2.3 Authorizing Desktop Systems Terminals

All TP Desktop Connector users are signed in to ACMS using the NL: device specification. If you do not have the $ALL or NL: device authorized, run the ACMS Device Definition Utility. For example:

$ SET DEFAULT SYS$SYSTEM $ RUN ACMSDDU DDU> ADD NL DDU> SHOW NL . . . DDU> EXIT $

The device name NL authorizes all desktop devices.

2.2.4 Authorizing Task Access on the Application Node

Task authorization applies both when the user's ACMS application is running on the submitter node, and when the ACMS application is distributed.

2.2.4.1 Task Authorization on Submitter Nodes

On the submitter node, set the task access control for users in the application definition TASK ATTRIBUTES clause in one of the following ways:

For each task, in the TASK CONTROL DEFAULTS clause
For all tasks, in the TASK DEFAULTS clause

The user name specified in the access control list entry is the name under which the desktop user signs in to the ACMS system.

2.2.4.2 Task Authorization on Distributed Applications

The desktop client program as submitter needs authorization to allow it access to the task. The submitter must have a proxy account on the application node. On each application node, use either of the following methods to establish proxy.

Change ACMS system parameters:

$ RUN ACMSGEN ACMSGEN> SET NODE_NAME node ACMSGEN> SET USERNAME_DEFAULT proxy_username ACMSGEN> WRITE CURRENT ACMSGEN>

To effect the change, stop and restart the ACMS system.

Run the OpenVMS Authorize Utility. Do one of the following actions:
- To authorize all users:
  UAF> ADD/PROXY node::* */DEFAULT UAF>
  All users from the specified submitter node have proxy access on the application node.
- To authorize individual users:
  UAF> ADD/PROXY nodename::username_1 username_2 UAF>
  The user running the account specified by username_1 from the submitter node has individual proxy under username_2.

When the remote submitter node selects a task on the application node, the task's access control list (ACL) is searched to determine task access. For more information on task ACLs, refer to Compaq ACMS for OpenVMS Managing Applications.

2.3 Controlling the TP Desktop Connector System

The Sections 2.3.1 through 2.3.3 describe common operations involving control of the TP Desktop Connector system.

2.3.1 Starting the System and Applications

If all ACMS users are on desktop systems, the terminal subsystem is not required. Use the /NOTERMINALS option on startup:

$ ACMS/START SYSTEM/NOTERMINALS $

This option saves process and memory usage, because the Terminal Subsystem Controller (TSC) process and the CP are not started.

2.3.2 Displaying System Information

TP Desktop Connector provides the ACMSDI$GET_SUBMITTER_INFO service to supplement ACMS/SHOW USERS and ACMS/SHOW TASKS commands. Refer to Compaq TP Desktop Connector for ACMS Client Services Reference Manual for a description of the information returned by the service and the location of a sample program using the service.

2.3.3 Canceling Desktop Users and Tasks

To cancel TP Desktop Connector users, follow these steps:

Enter the ACMS/SHOW command with the ACMSDI$GET_SUBMITTER_INFO service to identify desktop users and tasks.
Enter the ACMS/CANCEL USER command to specify a desktop user to cancel.
Enter the ACMS/CANCEL TASK command to specify a task to cancel.

The command procedure ACMS$CANCEL.COM is not supported for desktop users. Because desktops appear to be inactive, the procedure cancels them at the specified interval. You can use ACMSDI$CANCEL.COM to cancel inactive TP Desktop Connector users.

2.4 Controlling the Gateway

The following topics are discussed in this section:

Starting the gateway process (see Section 2.4.1).
Specifying a startup parameter file (see Section 2.4.2).
Specifying network transports (see Section 2.4.3).
Specifying the TCP/IP port number on the gateway (see Section 2.4.4).
Enabling password expiration (see Section 2.4.5).
Using cyclic redundancy checking (see Section 2.4.6).
Stopping the gateway process (see Section 2.4.7).

2.4.1 Starting the Gateway

To start the TP Desktop Connector gateway for ACMS software, DECnet for OpenVMS software must be running. To check that DECnet software is running, run the Network Control Program. For example:

NCP> SHOW EXECUTOR

If the state is on, DECnet software is running.

To start the gateway process, use the command procedure found in the system startup directory to run under the SYSTEM user name.

The TP Desktop Connector startup command procedure executes from the SYSTEM user name. If you add the TP Desktop Connector startup as part of your system startup, this occurs automatically. If you need to start the TP Desktop Connector software on OpenVMS systems at times other than OpenVMS restart, try to run the procedure from the SYSTEM user name. You can accomplish this by either logging in to the OpenVMS system under that user name, or from a privileged account, setting your process privilege to CMKRNL and using the following command to restart the gateway:

$ @SYS$STARTUP:ACMSDI$SHUTDOWN . . . $ SUBMIT/USERNAME=SYSTEM/NOLOG ACMSDI$STARTUP.COM

The following example shows the interactive startup method:

$ @SYS$STARTUP:ACMSDI$STARTUP %RUN-S-PROC_ID, identification of created process is 42600450 $

The following example shows the batch startup method:

$ SUBMIT/USER=SYSTEM/NOLOG SYS$STARTUP:ACMSDI$STARTUP Job ACMSDI$STARTUP (queue SYS$BATCH, entry 1208) started on SYS$BATCH $

This command procedure defines some logical names and issues a RUN command to start the gateway in a detached process with the correct privileges and a default set of qualifiers specifying the process quotas. (Refer to the logical name information for sample application code in Compaq TP Desktop Connector for ACMS Client Application Programming Guide.) To alter the quotas, follow the guidelines given in Section 2.5.3.

If the ACMS system is stopped, users attempting to sign in on that submitter node are refused until the ACMS system is available. The ACMSDI$SERVER process continues running. It detects when the ACMS system restarts and connects new users.

If a TP Desktop Connector application cannot sign in to the ACMS system, verify that the ACMSDI$SERVER process is running under user name SYSTEM and that SYSTEM has been added to ACMSUDU.DAT as an agent. If the ACMSDI$SERVER process is running under a user name other than SYSTEM, shut down TP Desktop Connector and restart it.

2.4.2 Gateway Startup Parameter File

TP Desktop Connector software provides the ACMSDI$STARTUP command procedure for starting up the gateway. This command procedure can read an optional parameter file that you supply, containing customized settings such as user name quotas, designated transports to be initialized, integrity checking, in addition to OpenVMS parameters.

The parameter file defines logical names from keywords that determine the gateway characteristics. The logical names are defined in the process logical name table, for the process that invokes ACMSDI$STARTUP.COM. If the keywords are not specified or are specified as null, the process logical names are not defined. For those keywords that take a value, use an equal sign (=) with or without spaces between the keyword and the value. Enclose multiple values in parentheses.

Example 2-1 is a sample parameter file.

Example 2-1 Gateway Startup Parameter File

! ! What transports to start up ! TRANSPORT = (DECNET,APPLETALK,TCPIP,NETWARE,SERIAL) ! ! To select the Port numbers and gateway host ! TCPIP_PORT = 1023 NETWARE_PORT = 33658 NETWARE_NAME = ACMSDISERVER-ON-MYSYSTEM SERIAL_GATEWAY_USERNAME = ACMSDISERIAL_GATENAME ! ! For Multiple Gateways for Debugging purposes ! SERVER_NAME = DBG1 DECNET_OBJECT = "TASK=DBG1" ! To turn on integrity checking INTEGRITY_CHECK = YES ! ! To get warning messages ! PASSWORD_EXP = 7 ! ! OpenVMS Parameters ! AST_LIMIT = 100 BUFFER_LIMIT = 65535 ENQUEUE_LIMIT = 200 EXTENT = 2000 FILE_LIMIT = 100 IO_BUFFERED = 300 IO_DIRECT = 100 MAXIMUM_WORKING_SET = 750 PAGE_FILE = 100000 PRIORITY = 4 QUEUE_LIMIT = 20 WORKING_SET = 150

To specify the parameter file, use the DCL command in the following format:

SUBMIT SYS$STARTUP:ACMSDI$STARTUP /PARAM=SYS$STARTUP:filename

where:

filename is the name of the parameter file.

Table 2-1 contains the list of parameters that you can include in this file.

Table 2-1 Gateway Keywords
Keyword Meaning

APPLETALK_OBJECT Specifies the object part of the Appletalk gateway name. The default object name is the DECnet node name of the gateway.

APPLETALK_TYPE Specifies the gateway type for AppleTalk. This name can include spaces. The default AppleTalk gateway name is "Desktop ACMS server."

DECNET_OBJECT Defines the object number to be used by the gateway for its DECnet object. The default is 87.

INTEGRITY_CHECK Determines whether integrity checking is turned on. Specify either YES or NO. NO is the default.

NETWARE_NAME Defines the name to be used by the gateway for its NetWare port. The default is ACMS on node-name.

NETWARE_PORT Defines the number to be used by the gateway for its NetWare port. The default is 1023.

PASSWORD_EXP Defines the value (in days) to which a sign-in that detects an expiring password must be equal to or less than.

SERIAL_GATEWAY_USERNAME Defines the user name for the serial gateway process. The default is SYSTEM.

SERVER_NAME Defines a gateway-name extension to distinguish between multiple gateways on the same node. The value is a name of up to 5 characters appended to ACMSDI$SRV to create the process name.

TCPIP_PORT Defines the number to be used by the gateway for its TCP/IP port. The default is 1023.

TRANSPORT Defines transports to be enabled when the gateway starts. Valid values are:

APPLETALK
DECNET
NETWARE
SERIAL
TCPIP
The default is DECNET.

**Table 2-1 Gateway Keywords**
Keyword	Meaning
APPLETALK_OBJECT	Specifies the object part of the Appletalk gateway name. The default object name is the DECnet node name of the gateway.
APPLETALK_TYPE	Specifies the gateway type for AppleTalk. This name can include spaces. The default AppleTalk gateway name is "Desktop ACMS server."
DECNET_OBJECT	Defines the object number to be used by the gateway for its DECnet object. The default is 87.
INTEGRITY_CHECK	Determines whether integrity checking is turned on. Specify either YES or NO. NO is the default.
NETWARE_NAME	Defines the name to be used by the gateway for its NetWare port. The default is ACMS on node-name.
NETWARE_PORT	Defines the number to be used by the gateway for its NetWare port. The default is 1023.
PASSWORD_EXP	Defines the value (in days) to which a sign-in that detects an expiring password must be equal to or less than.
SERIAL_GATEWAY_USERNAME	Defines the user name for the serial gateway process. The default is SYSTEM.
SERVER_NAME	Defines a gateway-name extension to distinguish between multiple gateways on the same node. The value is a name of up to 5 characters appended to ACMSDI$SRV to create the process name.
TCPIP_PORT	Defines the number to be used by the gateway for its TCP/IP port. The default is 1023.
TRANSPORT	Defines transports to be enabled when the gateway starts. Valid values are: APPLETALK DECNET NETWARE SERIAL TCPIP The default is DECNET.

2.4.3 Specifying Network Transports

The gateway supports all five methods of transports used by TP Desktop Connector clients: AppleTalk, DECnet, NetWare, TCP/IP, and serial communications. To specify which transports to activate, add the parameter TRANSPORT to the ACMSDI startup parameter file.

The following example activates both DECnet and TCP/IP transports:

TRANSPORT=(DECNET,TCPIP)

Note

DECnet object numbers and NetWare node numbers are assigned by TP Desktop Connector. Do not change them.

See Chapter 3 for information on setting up the transport for your application.

2.4.4 Specifying the TCP/IP Port Number on the Gateway

TCP/IP uses numeric port numbers as endpoints of communication. The default port number is 1023, the highest unassigned privileged port number. Table 2-2 lists the three categories of port numbers.

Table 2-2 Port Numbers
Category Port Numbers

Reserved privileged ports 0---255

Privileged ports 256---1023

Nonprivileged ports 1024---65 535

**Table 2-2 Port Numbers**
Category	Port Numbers
Reserved privileged ports	0---255
Privileged ports	256---1023
Nonprivileged ports	1024---65 535

When using TCP/IP as the network transport, specify a numeric port number as the object to which the gateway connects. To assign a TCP/IP port number to the gateway, specify the TCPIP_PORT_NUMBER in the startup parameter file, which is optionally passed to the ACMSDI startup command file. The following example assigns the port number 32 767:

TCPIP_PORT_NUMBER=32767

2.4.5 Enabling Password Expiration

For further security checks, you can enable password expiration-checking by adding a new item, PASSWORD_EXP, to the ACMSDI$STARTUP.COM command file. This item defines the value (in days) to which a sign-in that detects an expiring password must be equal to or less than for the user to receive the status message ACMSDI_PWDEXPIRED. For example, if the value of PASSWORD_EXP is 7 and the sign-in detects that a password expires in 10 days, the sign-in call returns a normal success status. The gateway always checks the password expiration, regardless of whether the client uses the ACMS_PWDEXPIRED option. The default if you do not specify ACMSDI_PWDEXPIRED is 7 days.

For portable API desktop systems, the gateway checks the password expiration date only if the ACMSDI_OPT_PWD_EXPIRING flag is set in the sign-in options array. If you set the ACMSDI_OPT_PWD_EXPIRING flag, include a buffer address in the options array into which the client services can write the number of hours to expiration.

For the Macintosh, the password expiration is always checked (no flag on DBInit). The number of days to expiration is returned in DBGetErr. ACMSDI_PWDEXPIRED is returned in err2. The value for hours to expiration is returned as alphanumeric text following the ACMSDI_PWDEXPIRED message in the item2 parameter.

2.4.6 Cyclic Redundancy Checking

To help detect network transmission errors and some client application errors, you can turn on cyclic redundancy checking (CRC) on each message sent between the TP Desktop Connector client services and the gateway. CRC performs application data integrity checks that can prevent a gateway crash due to data corruption over the network.

In addition to preventing the gateway from crashing, CRC provides the following benefits:

Prevents intentional modification of transaction data (for example, dollar fields or account fields)
Provides confidence that the execution of critical transactions is correct in a client/server environment
Provides better detection of message corruption than the network transport can provide

You turn on CRC on the gateway side by adding a parameter in the gateway startup parameter file:

INTEGRITY_CHECK=YES

The default is NO (off).

iF you turn on CRC on the gateway side, CRC is performed for all clients sending messages to the gateway.

Note

Be aware that CRC is a CPU-intensive activity. Take this into consideration when deciding whether to turn integrity checking on.

If some client remote sites are more stable than others, you can be selective about which ones receive checking. To do this, leave CRC turned off by either not specifying it in the parameter file, or setting INTEGRITY_CHECK=NO.

On the desktop client side, define the logical name or environment variable ACMSDI_INTEGRITY_CHECK = "YES". This activity turns CRC on only for the sessions coming from this particular desktop client system.

For example:

C> set acmsdi_integrity_check="yes"

Note

When deciding whether to turn CRC on, take into account that CRC is a CPU-intensive activity.

For Macintosh clients, you activate CRC on a session-by-session basis by specifying "IntegrityCheck" on the connection string passed by the DBInit call.

2.4.7 Stopping the Gateway Process

To stop the gateway process, use the DCL command procedure provided. For example:

$ @SYS$STARTUP:ACMSDI$SHUTDOWN $

Any active desktop systems are disconnected and their work is aborted.

2.5 Tuning the TP Desktop Connector System

The following topics are described in this section.

Tuning the TP Desktop Connector system by setting ACMS system parameters (see Section 2.5.1).
Tuning the gateway process in relation to other processes on the TP Desktop Connector system (see Section 2.5.2).
Overriding default process quotas (see Section 2.5.3).
Setting a maximum buffer size for the client program (see Section 2.5.4).
Running applications simultaneously (see Section 2.5.5).

2.5.1 Setting ACMS System Parameters

Used to tune the ACMS system, the ACMSPARAM.COM command procedure performs the following operations:

Generates default values for all environment variables that are used to calculate ACMS system parameters (if values do not already exist).
Calculates values for OpenVMS system parameters that are affected by ACMS.
Calculates ACMS system parameters.
Calculates quotas for the user names under which the ACMS Command Process (CP) executes. Also adds accounts and assigns privileges for these user names in the SYS$SYSTEMLSYSUAF.DAT file.
Writes the OpenVMS system parameters that need modification to a file.

The variable that specifies the number of desktop systems that submits to ACMSDI depends on where the gateway resides. If the gateway is on the local node, then AGENT_SUB_CNT indicates the number of desktop systems. If the gateway is on the remote node, then REMOTE_SUB_CNT indicates the number of desktop systems.

If the defaults given for these variables do not accurately reflect your system, edit ACMVARINI.DAT with corrected values and rerun ACMSPARAM.COM. For more information on variables and their effects on OpenVMS and ACMS system parameters, refer to Compaq ACMS for OpenVMS Managing Applications.

Consider the variables shown in Table 2-3 when setting ACMS system parameters for TP Desktop Connector usage.

Table 2-3 Variables Required for ACMSPARAM.COM
Variable

AGENT_CNT

Description: Include in the number of agent processes one for the gateway.

Default: 2

Affects: ACMSGEN parameter MSS_MAXOBJ

AGENT_SUB_CNT

Description: Include in the number of users selecting tasks in ACMS agent processes one per desktop user sign-in.

Default: 10

Affects: ACMSGEN parameter MSS_MAXOBJ

REMOTE_NODE_CNT

Description: Include the number of remote ACMS users connecting to the local ACC. If the gateway is on the local node, and there are no other remote ACMS systems, then REMOTE_NODE_CNT = 0.

Default: 5

Affects: ACMSGEN parameter MSS_MAXOBJ. This number is used to calculate the ACC's process quotas.

REMOTE_SUB_CNT

Description: Include submitters from REMOTE_NODE_CNT. If the gateway is on the local node, then REMOTE_SUB_CNT = 0.

Defaults: 20 * REMOTE_NODE_CNT

Affects: ACMSGEN parameter MSS_MAXOBJ

**Table 2-3 Variables Required for ACMSPARAM.COM**
Variable
AGENT_CNT
	Description:	Include in the number of agent processes one for the gateway.
	Default:	2
	Affects:	ACMSGEN parameter MSS_MAXOBJ

AGENT_SUB_CNT
	Description:	Include in the number of users selecting tasks in ACMS agent processes one per desktop user sign-in.
	Default:	10
	Affects:	ACMSGEN parameter MSS_MAXOBJ

REMOTE_NODE_CNT
	Description:	Include the number of remote ACMS users connecting to the local ACC. If the gateway is on the local node, and there are no other remote ACMS systems, then REMOTE_NODE_CNT = 0.
	Default:	5
	Affects:	ACMSGEN parameter MSS_MAXOBJ. This number is used to calculate the ACC's process quotas.

REMOTE_SUB_CNT
	Description:	Include submitters from REMOTE_NODE_CNT. If the gateway is on the local node, then REMOTE_SUB_CNT = 0.
	Defaults:	20 * REMOTE_NODE_CNT
	Affects:	ACMSGEN parameter MSS_MAXOBJ

Contents

Index

Compaq TP Desktop Connector for ACMSGateway Management Guide

2.2.2 Authorizing ACMS Users

2.4.1 Starting the Gateway

2.5.1 Setting ACMS System Parameters

Compaq TP Desktop Connector
for ACMS
Gateway Management Guide