Application-Wide Parameters

This chapter tells about some of the application-wide parameters of the configuration file that are not covered in the chapters that follow.

When the general design of a BEA TUXEDO System/T application has been decided, the problem a BEA TUXEDO System/T administrator must address is how to begin to define the application to the system. The most basic parts of this task were covered in "Introduction to System/T Administration". The configuration parameters described in this chapter are specified in the RESOURCES section. They are parameters that:

say who can use the application
set the environment for using unsolicited messages and authentication
give the characteristics of the application
control the size of bulletin board tables
control the operation of DBBL and BBL administrative processes

Who Can Use the Application

The parameters in this group establish the ownership of the application and the permissions applying to its use. There are default values for these parameters, but you should consider whether the default really serves the needs of your application.

Section Parameter Meaning

*RESOURCES UID
GID The user-id and group-id to be associated with the bulletin board structures. This should be the UID and GID of the System/T administrator. The valid range is from 0 to 65535. Default: Takes the effective uid and gid of the one who invokes tmloadcf

PERM An octal number that specifies the permissions for the bulletin board structures. Default: If PERM is not specified, it defaults to 0666. Would 0660 be more appropriate for your application?

Section	Parameter	Meaning
*RESOURCES	UID GID	The user-id and group-id to be associated with the bulletin board structures. This should be the UID and GID of the System/T administrator. The valid range is from 0 to 65535. Default: Takes the effective `uid` and `gid` of the one who invokes `tmloadcf`
PERM	An octal number that specifies the permissions for the bulletin board structures. Default: If PERM is not specified, it defaults to 0666. Would 0660 be more appropriate for your application?

Unsolicited Notification

These configuration file entries are concerned with the method in which unsolicited messages to client processes are to be detected.

Parameter	Meaning	Default
NOTIFY	This parameter specifies the default method for detecting unsolicited messages. It can be set to `SIGNAL`, for the process to receive a signal, `DIPIN`, to get messages when the application makes (dips into) ATMI calls, or `IGNORE`. The value you set here can be overridden by a client in a call to tpinit(). For the value `SIGNAL` to work, the client process must be running with the same `uid` as the System/T configuration owner on that machine and must be on a system capable of receiving operating system signals. If these conditions are not met, `SIGNAL` is defaulted by the system to `DIPIN`. `IGNORE` might be a reasonable setting for an application where the detection method is always requested by clients in their call to `tpinit()`. The method of detecting unsolicited messages should be agreed upon between the administrator specifying these values in the configuration file and the programmers specifying flags in client process `tpinit()` calls.	DIPIN
SIGNAL	This parameter specifies the signal to be used in the event that SIGNAL is the value for NOTIFY. The legal values are SIGUSR1 and SIGUSR2 (defined in `<signal.h>`). If your application determines that SIGUSR1 is to be the preferred signal, it is recommended that you specify it here even if you do not specify SIGNAL.	SIGUSR2

Authentication

Setting the UID, GID and PERM parameters provides one level of security. Additional security levels are provided by these two parameters in the RESOURCES section to control the level of security and client authentication for the application.

Parameter Meaning Default

SECURITY Specifying SECURITY APP_PW for the application enables both second and third level security. If this value is specified, tmloadcf(1) prompts the administrator for a password when the configuration file is loaded to a binary file. The password selected by the administrator is stored in encrypted form by tmloadcf. Current versions of system clients such as mio(1) or ud(1) prompt the user for the application password. Application client processes for releases that support password protection need to be coded so as to prompt for the password and place it in the TPINIT buffer before calling tpinit(). The requirement of an application password implements second level System/T security and must be in effect before third level security can be implemented. None

AUTHSVC The value to be provided with this parameter is the name of a service that authenticates individual users as they attempt to join the application through application clients. There is a System/T-provided server called AUTHSVR(5) that offers a service called AUTHSVC. If you specify this value, enclose it in double quotes so it is not interpreted as a reserved word. The System/T server validates users against a password file. The authentication of individual users is System/T third level security. It requires that second level security be in effect. None

Parameter	Meaning	Default
SECURITY	Specifying `SECURITY APP_PW` for the application enables both second and third level security. If this value is specified, tmloadcf(1) prompts the administrator for a password when the configuration file is loaded to a binary file. The password selected by the administrator is stored in encrypted form by `tmloadcf`. Current versions of system clients such as mio(1) or ud(1) prompt the user for the application password. Application client processes for releases that support password protection need to be coded so as to prompt for the password and place it in the `TPINIT` buffer before calling tpinit(). The requirement of an application password implements second level System/T security and must be in effect before third level security can be implemented.	None
AUTHSVC	The value to be provided with this parameter is the name of a service that authenticates individual users as they attempt to join the application through application clients. There is a System/T-provided server called AUTHSVR(5) that offers a service called `AUTHSVC`. If you specify this value, enclose it in double quotes so it is not interpreted as a reserved word. The System/T server validates users against a password file. The authentication of individual users is System/T third level security. It requires that second level security be in effect.	None

Specifying the Characteristics of the Application

This group of parameters from the *RESOURCES section begins to describe the basic characteristics of your application.

Parameter Meaning Default

MODEL Choose between SHM and MP. SHM specifies a single uniprocessor machine; MP specifies either a multiprocessor or multiple uniprocessors. None

OPTIONS Valid options are LAN or MIGRATE. LAN indicates a networked application (MODEL must be MP). MIGRATE enables server relocation to alternate processors. LAN and MIGRATE can be specified together in a comma-separated list. No options

SECURITY This keyword specifies that security provisions are to be enforced. See ``Authentication'' above.

SYSTEM_ACCESS Choose between PROTECTED or FASTPATH. PROTECTED specifies that the shared memory for System/T internal tables is not accessible from code outside of the System/T libraries. You can also specify NO_OVERRIDE (separated by a comma from the first parameter) to prevent the parameter from being changed in the SERVERS section. FASTPATH

CMTRET Controls the initial setting of the TP_COMMIT_CONTROL characteristic for clients or servers of the application. The choice is between LOGGED or COMPLETE. COMPLETE

LDBAL Y or N Indicates whether load balancing should or should not be performed. You may elect to turn load balancing off if all servers of your application are in MSSQ sets (Multiple Server, Single Queue), or if each application service is available in one and only one server. In those two cases load balancing is automatic by virtue of the configuration and turning the option off saves having to call the load balancing routine. If the software has a choice of where to enqueue an incoming service request (that is, if some application services are available in dissimilar servers), load balancing improves throughput by selecting the queue of the server with the least cumulative processing load. For information on load balancing across a System/T network, see the discussion of TMNETLOAD in Chapter 4, System/T Networks. Y

Parameter	Meaning	Default
MODEL	Choose between SHM and MP. SHM specifies a single uniprocessor machine; MP specifies either a multiprocessor or multiple uniprocessors.	None
OPTIONS	Valid options are LAN or MIGRATE. LAN indicates a networked application (MODEL must be MP). MIGRATE enables server relocation to alternate processors. LAN and MIGRATE can be specified together in a comma-separated list.	No options
SECURITY	This keyword specifies that security provisions are to be enforced. See ``Authentication'' above.
SYSTEM_ACCESS	Choose between PROTECTED or FASTPATH. PROTECTED specifies that the shared memory for System/T internal tables is not accessible from code outside of the System/T libraries. You can also specify NO_OVERRIDE (separated by a comma from the first parameter) to prevent the parameter from being changed in the SERVERS section.	FASTPATH
CMTRET	Controls the initial setting of the TP_COMMIT_CONTROL characteristic for clients or servers of the application. The choice is between LOGGED or COMPLETE.	COMPLETE
LDBAL	Y or N Indicates whether load balancing should or should not be performed. You may elect to turn load balancing off if all servers of your application are in MSSQ sets (Multiple Server, Single Queue), or if each application service is available in one and only one server. In those two cases load balancing is automatic by virtue of the configuration and turning the option off saves having to call the load balancing routine. If the software has a choice of where to enqueue an incoming service request (that is, if some application services are available in dissimilar servers), load balancing improves throughput by selecting the queue of the server with the least cumulative processing load. For information on load balancing across a System/T network, see the discussion of `TMNETLOAD` in Chapter 4, System/T Networks.	Y

Controlling the Size of Bulletin Board Tables

This group of parameters is used less to keep the size of the bulletin board low (the default size is only about 200 pages) than to make sure enough space is allocated so that tmloadcf can complete successfully. In planning how to size your bulletin board, you should keep in mind the possibility that you may later want to add more resources to the application dynamically without shutting down the system and editing the ACSII configuration file.

Parameter Meaning Default

MAXACCESSERS The number of processes that can have access to a bulletin board at any one time. Count clients and servers, but don't count administrative servers or tmadmin. Must be greater than 0 and less than 32,768. 50

MAXSERVERS The number of server table entries in the bulletin board. Must be greater than 0 and less than 32,768. 50

MAXSERVICES The number of service table entries in the bulletin board. Must be greater than 0 and less than 32,768. 100

MAXGTT The number of simultaneous global transactions in which any machine in the configuration can be involved. Must be greater than or equal to 0 and less than 2048. 100

MAXCONV The number of simultaneous conversations in which processes on one machine can be involved. The range is from 1 to 32,767 but the default is much lower than the maximum. If no conversational servers are defined in the *SERVERS section, the default is 1; if any conversational servers are defined in the *SERVERS section, the default is 10. MAXCONV applies to all conversational processes on a machine. For a single process, the maximum number of simultaneous outgoing connections is 10 (plus one incoming connection, if the process is a conversational server). That limit is not configurable through UBBCONFIG. 10

MAXDRT The maximum number of data dependent routing criteria entries. The range is from 0 to 32,767. The default is based on the configured *ROUTING entries at boot time. Config

MAXRFT The maximum number of data dependent routing range field table entries. The range is from 0 to 32,767. The default is based on the configured *ROUTING entries at boot time. Config

MAXRTDATA The maximum amount of characters in strings in the data dependent routing criteria entries. The range is from 0 to 32,761. The default is based on the configured *ROUTING entries at boot time. Config

Parameter	Meaning	Default
MAXACCESSERS	The number of processes that can have access to a bulletin board at any one time. Count clients and servers, but don't count administrative servers or `tmadmin`. Must be greater than 0 and less than 32,768.	50
MAXSERVERS	The number of server table entries in the bulletin board. Must be greater than 0 and less than 32,768.	50
MAXSERVICES	The number of service table entries in the bulletin board. Must be greater than 0 and less than 32,768.	100
MAXGTT	The number of simultaneous global transactions in which any machine in the configuration can be involved. Must be greater than or equal to 0 and less than 2048.	100
MAXCONV	The number of simultaneous conversations in which processes on one machine can be involved. The range is from 1 to 32,767 but the default is much lower than the maximum. If no conversational servers are defined in the SERVERS section, the default is 1; if any conversational servers are defined in the SERVERS section, the default is 10. MAXCONV applies to all conversational processes on a machine. For a single process, the maximum number of simultaneous outgoing connections is 10 (plus one incoming connection, if the process is a conversational server). That limit is not configurable through UBBCONFIG.	10
MAXDRT	The maximum number of data dependent routing criteria entries. The range is from 0 to 32,767. The default is based on the configured *ROUTING entries at boot time.	Config
MAXRFT	The maximum number of data dependent routing range field table entries. The range is from 0 to 32,767. The default is based on the configured *ROUTING entries at boot time.	Config
MAXRTDATA	The maximum amount of characters in strings in the data dependent routing criteria entries. The range is from 0 to 32,761. The default is based on the configured *ROUTING entries at boot time.	Config

The size of the bulletin board is controlled by the default sizes of the tables used by each section. If the five parameters above are specified only in the *RESOURCES section, the bulletin board on each machine of the configuration is that size. However, MAXACCESSERS, MAXGTT and MAXCONV can all appear in entries in the *MACHINES section. (Remember, the format of the parameter changes to MAXsomething = value when used in the *MACHINES section.) When used in the *MACHINES section, the parameters override the value specified (or defaulted to) in the *RESOURCES section for the specific machine.

Controlling DBBL and BBL Operations

This group of parameters can best be regarded as tunables. The recommendation is that you begin by accepting the default values. When your application is far enough along in its development for you to begin to get a feeling about performance you might want to see how performance is affected by changes in these parameters. You might, for example, lengthen the time between status checks so that cycles are not taken up for reporting status more frequently than necessary. If you are recording what seems like a high number of blocking time-outs (a very subjective measurement), you might want to increase BLOCKTIME by small increments.

Parameter Meaning Default

SCANUNIT Time in seconds between scans by the BBL to look for old transactions and timed-out blocking calls. Must be greater than 0, less than or equal to 60 and a multiple of 5. 10

SANITYSCAN A multiplier of SCANUNIT that sets time for a sanity check of the application. At this interval each BBL reports to the DBBL on its viability with an ``I'm OK'' message. Set so that (SCANUNIT * SANITYSCAN) is approximately 120 seconds.

DBBLWAIT A multiplier of SCANUNIT for maximum wall time the DBBL should wait for a response before timing-out a BBL. Set so that (SCANUNIT * DBBLWAIT) is at least 20 seconds.

BBLQUERY A multiplier of SCANUNIT that sets frequency of status verification by the DBBL. The DBBL sends a message to any BBL that has not filed an ``I'm OK'' message within the period. If no response is received, the node represented by the non-responding BBL is partitioned. Must be greater than or equal to (SCANUNIT * SANITYSCAN) Set so that (SCANUNIT * BBLQUERY) is approximately 300 seconds.

BLOCKTIME A multiplier of SCANUNIT for timing-out a blocking call. (SCANUNIT * BLOCKTIME) must be greater than or equal to SCANUNIT and less than or equal to 300 seconds. Set so that (SCANUNIT * BLOCKTIME) is approximately 60 seconds.

Parameter	Meaning	Default
SCANUNIT	Time in seconds between scans by the BBL to look for old transactions and timed-out blocking calls. Must be greater than 0, less than or equal to 60 and a multiple of 5.	10
SANITYSCAN	A multiplier of SCANUNIT that sets time for a sanity check of the application. At this interval each BBL reports to the DBBL on its viability with an ``I'm OK'' message.	Set so that (SCANUNIT * SANITYSCAN) is approximately 120 seconds.
DBBLWAIT	A multiplier of SCANUNIT for maximum wall time the DBBL should wait for a response before timing-out a BBL.	Set so that (SCANUNIT * DBBLWAIT) is at least 20 seconds.
BBLQUERY	A multiplier of SCANUNIT that sets frequency of status verification by the DBBL. The DBBL sends a message to any BBL that has not filed an ``I'm OK'' message within the period. If no response is received, the node represented by the non-responding BBL is partitioned. Must be greater than or equal to (SCANUNIT * SANITYSCAN)	Set so that (SCANUNIT * BBLQUERY) is approximately 300 seconds.
BLOCKTIME	A multiplier of SCANUNIT for timing-out a blocking call. (SCANUNIT * BLOCKTIME) must be greater than or equal to SCANUNIT and less than or equal to 300 seconds.	Set so that (SCANUNIT * BLOCKTIME) is approximately 60 seconds.

Example

The *RESOURCES section of the bankapp application is shown below:

*RESOURCES Section, bankapp, MP Mode

*RESOURCES
# PARAMETER	VALUE
# ---------	-----
		# Substitute values appropriate for your application
		# for items enclosed in angle brackets  < >
#
IPCKEY		80952
UID		<user id>
GID		<group id>
PERM		0660
MAXACCESSERS	40
MAXSERVERS	35
MAXSERVICES	75
MAXGTT		20
MAXCONV		10
MASTER		SITE1,SITE2
SCANUNIT	10
SANITYSCAN	12
BBLQUERY	30
BLOCKTIME	30
DBBLWAIT	6
OPTIONS		LAN,MIGRATE
MODEL		MP
LDBAL		Y
#

The configuration file shown here requires editing of the UID and GID parameters before it can be used.