DIGITAL TP Desktop Connector
for ACMS
Gateway Management Guide


Previous Contents Index

2.2.3 Authorizing Desktop Systems Terminals

All TP Desktop Connector users are signed in to DIGITAL ACMS using the NL: device specification. If you do not have the $ALL or NL: device authorized, run the DIGITAL 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 DIGITAL ACMS application is running on the submitter node, and when the DIGITAL 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:

The user name specified in the access control list entry is the name under which the desktop user signs in to the DIGITAL 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.

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, see DIGITAL ACMS for OpenVMS Managing Applications.

2.3 Controlling the TP Desktop Connector System

The following sections 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. See DIGITAL 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:

  1. Enter the ACMS/SHOW command with the ACMSDI$GET_SUBMITTER_INFO service to identify desktop users and tasks.
  2. Enter the ACMS/CANCEL USER command to specify a desktop user to cancel.
  3. 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 sections discuss starting and stopping the gateway and specifying gateway process quotas.

2.4.1 Starting the Gateway

To start the TP Desktop Connector software, DECnet for OpenVMS software must be running. Run the Network Control Program to check that DECnet software is running:


NCP>  SHOW EXECUTOR

If the state is on, DECnet software is running.

To start the gateway, 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 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 (see the logical name information for sample application code in the DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide) 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. To alter the quotas, follow the guidelines given in Section 2.5.3.

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

If a TP Desktop Connector application cannot sign in to ACMS, 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 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 following command:


$ 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 gateway name. The default object name is the DECnet node name of the gateway.
APPLETALK_TYPE Specifies the gateway type. 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

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:

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


INTEGRITY_CHECK=YES 

The default is NO (off).

Once 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 or environmental 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:


$ @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 sections describe tuning the TP Desktop Connector system by setting TP Desktop Connector system parameters, overriding quotas, and setting a maximum buffer size.

2.5.1 Setting DIGITAL ACMS System Parameters

The ACMSPARAM.COM command procedure performs the following operations:

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 DIGITAL ACMS system parameters, see DIGITAL ACMS for OpenVMS Managing Applications.

Consider the variables shown in Table 2-3 when setting DIGITAL 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 DIGITAL 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


Previous Next Contents Index