Starting and Configuring Dimensions Server Pooling

The dmlsnr and refreshpoolconfig tools must normally (unless mentioned otherwise) be run by the following user accounts:

- dmlsnr: User root on UNIX and user dmsys on Windows.

- dmlsnr: User root on UNIX and user dmsys on Windows.

- refreshpoolconfig: User root or dmsys on UNIX and user dmsys on Windows.

Dimensions server pooling (and the License Manager) is automatically invoked upon Dimensions startup. These processes are also automatically stopped upon Dimensions shuts down. The server pooling is invoked with various default parameters in the file listener.dat in the dfs sub-directory of the Dimensions installation directory; in many circumstances, these default parameters will be perfectly adequate for most users.

NOTE In Dimensions CM for z/OS, a certificate mechanism is used to connect back to Dimensions CM from the mainframe. These certificates are also managed in memory by the pooling feature on the server machine. Timeouts for these certificates
(-cert_timeout and -cert_purge_timeout) can be set up in the listener.dat file as described later in this section).

On a Dimensions UNIX server, automatic server pooling is started and stopped as part of the standard running of the Dimensions server startup and shutdown scripts introduced at Dimensions release 2009 R1:

$DM_ROOT/prog/dm_control cm_start

$DM_ROOT/prog/dm_control cm_stop

or by the legacy scripts:

$DM_ROOT/prog/dmstartup

$DM_ROOT/prog/dmshutdown

On a Dimensions Windows server, the automatic server pooling is started and stopped by starting and stopping the following Dimensions Windows service:

Dimensions CM Listener Service

To manually start/stop server pooling or dynamically reconfigure the parameters with which it is run, you need to invoke the dmlsnr or refreshpoolconfig tools:

- dmlsnr enables a number of Dimensions application servers to be pre-started prior to Dimensions clients connecting to a Dimensions server. This enables faster connection time for clients as the application servers are already initialized and connected to the Dimensions database. The pool manager server will also create extra application servers, if necessary, up to a configured maximum after which client requests will be refused. The pool will also be shrunk by destroying unallocated application servers as clients disconnect, depending on the configuration of the pool as determined by the listener.dat file.

An application server that is serving an idle client is de-allocated from that client after a configurable length of time and is returned back to the pool ready for allocation to other clients. Inactive clients are seamlessly reconnected when they try to access Dimensions.

Once a clientmaintained by the Dimensions pool manager server for a period of time. If they remain inactive during this time, their state is discarded and when they are reconnected they will start with a new session.

- refreshpooconfig enables the pool configuration to be updated while Dimensions is still running, by dynamically updating the listener.dat file.

For details on how to manually invoke the dmlsnr or refreshpoolconfig commands, see the Administration Guide. To recap, the specific commands are:

dmlsnr -param $DM_ROOT/dfs/listener.dat

and

refreshpoolconfig -host machine:port

If you are not using the default TCP port of 671 for the Dimensions CM Listener Service, you must specify the appropriate port number.

NOTE If you want to display server pooling statistics, this can be done using either the getpoolstats command or the Administration Console, see Displaying Connection Pooling Statistics for details.

The listener.dat file is a text file containing a series of lines of the following format:

-<param><white-space><param-value>

The parameters supported are as follow:

Parameter | Description
-service | Default pcms_sdp Specifies the port to listen to for client connections. You may, therefore, run more than one pool manage using different ports.
-user | Specifies the operating system account name that will own every application process in the pool. For the Serena-Supplied Runtime RDBMS or Oracle Enterprise, this can be any arbitrary valid operating system account; whereas, for Microsoft SQL Server Enterprise, it must be the operating system account of the database owner. NOTE See the -restricted parameter concerning area/remote node authentication credentials with respect to running a server or agent in restricted mode.
-dsn | Default intermediate@dmudb Specifies the Dimensions base database name and the ODBC data source name (DSN) to use when starting up the initial applications servers at the time of pool manager startup.
-min | Default 5 Minimum number of application servers that the pool will shrink to.
-max | Default 120 Maximum number of application servers that the pool will expand to.
-initial | Default 5 Initial number of application servers that will be created in the pool at startup time. These will use the database connection parameter -dsn for identifying the base database to connect to.
-free | Default 20 The maximum number of application servers that may be left idle. Once this limit is reached, the pool will start shrinking as necessary by destroying idle application servers.
-idle_timeout | Default 300 at installation Minimum: none, but 60 is recommended The amount of time, in seconds, that a client can be idle before it is disconnected.
-session_timeout | Default 86400 (24 hours) at installation Minimum 3600 (1 hour) The amount of time, in seconds, that a clientis maintained by the pool manager before being discarded. The application server and the Dimensions license token are then returned to the pool. NOTE This value overrides the session-timeout parameter used in web-inf\web.xml files.
-cert_timeout | Default 3600 seconds at installation. Maximum: none. In Dimensions CM for z/OS, a certificate mechanism is used to connect back to Dimensions CM from the mainframe. This parameter specifies the interval that must pass before the certificate expires.
-cert_purge_timeout | Default 3600 seconds at installation. Maximum: 3600 (i hour) In Dimensions CM for z/OS, a certificate mechanism is used to connect back to Dimensions CM from the mainframe. This parameter specifies how often the pool removes expired certificates.
-max_auth_attempts | Default 3 Minimum 0. Specifying zero disables the functioning of this parameter, allowing an unlimited number of attempts to be made to pass an authentication point. To assist customers working in an environment where verification of a userprocess, Dimensions offers authentication facilities for "sensitive" changes to an objectattributes, improved audit trail generation, and new reporting facilities. The -max_auth_attempts parameter specifies the maximum number of attempts that can be made to pass an authentication point. Once the limit is reached, the usersession will be terminated and they will have to log in to the client again.
-dont_use_proxy | External executables called from event triggers run as the Dimensions CM proxy user unless you specify -dont_use_proxy in the dmlsnr configuration file or the dmlsnr command line. Specifying -dont_use_proxy causes dmappsrv processes to run as the authenticated user instead of the Dimensions CM proxy user. External executables then run as the authenticated user. However, the dmappsrv is locked to the user session, which disables dmappsrv pooling.
-restricted_mode | Used if you want to start a Dimensions server or agent in restricted mode, that is, as a user other than the default UNIX user root or a Windows local administrator (for example dmsys). If you want to do this, you will also have to set the -user parameter to the appropriate user. NOTE When running a server or agent in restricted mode, area/remote node authentication credentials are not used— that is, in restricted mode files in a remote area are owned by the user running the dmpool process (by default dmsys), regardless of which user-id is set for the area or userid specified in Remote Node Authentication. NOTE LDAP authentication is required for UNIX servers. NOTE You must additionally ensure that the service that is specified by -service (which is pcms_sdp by default) utilizes a port number of 1025 or higher rather than the default of 671. You do this as follows: On Windows systems: Edit the symbol DM_SERVICE_PCMS_SDP_TCP to specify the port number to be used. Note, that this port number must also be used on the server node. For detail On UNIX systems: Edit the /etc/services file to specify the port number to be used (for example, pcms_sdp<tab>1025/tcp Delete the "local connect pipe" (typically /tmp/dimensions_local_connectautomatically recreated when the listener is restarted. Change the ownership and/or permissions on $DM_ROOT/prog/dmstartup and $DM_ROOT/prog/dmshutdown so that they are executable by the user specified by the -user flag.
-ssl -ssl_password | Used for Secure Sockets Layer (SSL) connections.
-trace -tracedir | Commented out by default. There may be occasions when it is necessary to diagnose possible issues with the Dimensions CM Listener. Dimensions provides two special initialization parameters that you can use to start the listener in a mode that will trace internal progress and status information to a log file for debugging purposes. To enable tracing, uncomment and edit appropriately the following lines in the listener.dat file: -trace -tracedir <directory_name> where <directory_name> is the name of a directory where the trace files are to be created.