6.1.2 Server configuration variables
The server configuration file is named a_srvcfg. On UNIX servers, it is located in /etc by default. On Windows NT (Intel) servers, it is located in \etc on the disk device that AcuServer is installed on. If the file is given another name, or located in another directory, the full location and name of the file must be specified with the "-c" option when you start AcuServer. See the "-start" option in section 7.1.
There are several server configuration variables. They are:
Name Default value
?-VERSION* 0
ACCESS-FILE /etc/AcuAccess
DEFAULT-USER undefined
FILE-TRACE-FLUSH 0
LOCK-ALL-FILES 0
LOCKS-PER-FILE* 10
MAX-ERROR-LINES* 0
MAX-FILES* 32
MAX-LOCKS* 32
NAME_EXT_DATA_FMT* decimal extensions
NAME_EXT_INDEX_FMT* decimal extensions
PASSWORD-ATTEMPTS 3
SERVER-IP undefined
SERVER-NAME undefined
SERVER-NUMBER* 1
SERVER-PORT -1
SERVER-START-<server #> -l -e acuserve.log
[Windows NT (Intel) servers only]
V-BUFFER-DATA* on ("1")
V-BUFFERS* 32
V-READ-AHEAD* on ("1")
V-SEG-SIZE* 2147482623
V-VERSION* 0
Variables marked with an asterisk ("*") can appear in both the runtime ("cblconfig") and server ("a_srvcfg") configuration files. These variables are fully described in Chapter H, "Configuration File Entries," of the ACUCOBOL-85 and ACUCOBOL-GT Appendices book. Note that values assigned to variables contained in the server configuration file are applied solely to operations performed by AcuServer.
In both "a_srvcfg" and "cblconfig," V-BUFFERS, V-BUFFER-DATA, V-READ-AHEAD, V-VERSION, ?-VERSION, V-SEG-SIZE, NAME_EXT_DATA_FMT, NAME_EXT_INDEX_FMT should be given values as recommended in the Runtime Manual. Note that when file access is made through AcuServer, the values assigned to these variables in the runtime configuration file are ignored.
ACCESS-FILE
The variable ACCESS-FILE, as well as the variables DEFAULT-USER and PASSWORD-ATTEMPTS, affects system security.
ACCESS-FILE must hold the full path and file name of the server access file, if it is other than the default ("/etc/AcuAccess" on UNIX systems; "\etc\AcuAccess" on Windows NT for Intel).
DEFAULT-USER
The variable DEFAULT-USER, as well as the variables ACCESS-FILE and PASSWORD-ATTEMPTS, affects system security.
DEFAULT-USER holds the default user name given to AcuServer requesters who are not specifically mapped to a local user name in the server access file (as when the Local Username field of the access record is empty, or the value of the field is an invalid user name). Definition of DEFAULT-USER is optional. DEFAULT-USER cannot be defined as "root." For a description of when AcuServer assigns DEFAULT-USER to a requester, see Chapter 8, section 8.4.
FILE-TRACE-FLUSH
Setting FILE-TRACE-FLUSH to "1" (on) causes AcuServer to flush the error trace buffer to disk after every WRITE operation. This ensures that in the event that the acuserve daemon terminates abnormally, all file trace information, up to the last WRITE operation, is captured in the log file. If this configuration variable is not used (set to "0" or "off) and AcuServer aborts unexpectedly, an undefined amount of file trace information will be lost. FILE-TRACE-FLUSH is set to "0" by default. Note that you can also enable file trace flushing when you start the acuserve daemon by including the "-t5", "-t6", or "-t7" commnad line switch in the start command (see section 7.1 for more information).
LOCK-ALL-FILES
If the variable LOCK-ALL-FILES is set to "1," it causes AcuServer to lock all files that it opens. Access to locked files is faster than access to files that are not locked. As a result, LOCK-ALL-FILES can improve data access speed.
This variable is especially helpful for servers running in conjunction with the Network File System (NFS) network protocol. At NFS installations, file access time can be degraded by slow network lock daemons. Setting LOCK-ALL-FILES to "1" locks all of the files internally, thus bypassing the slower network lock daemons.
Runtimes that do not use acuserve may be locked out if this variable is set to "1". So if the site uses this option, then all runtimes must use acuserve to access the files (set USE-LOCAL-SERVER to "1").
When LOCK-ALL-FILES is set to "0", files are no longer automatically locked, and access times are increased.
LOCKS-PER-FILE, MAX-FILES, and MAX-LOCKS
The values of LOCKS-PER-FILE, MAX-FILES and MAX-LOCKS are applied to the corresponding executable of each configuration file. That is, the values of the variables defined in the runtime configuration file are applied to the executing client program, and the values defined in the server configuration file are applied to the acuserve process. Remote file access is restricted by the smaller of the two values. For example:
If we have the following configuration values:
runtime (cblconfig) MAX-FILES 64
server (a_srvcfg) MAX-FILES 32
the runtime is able to open 64 files with a limit of 32 remote files.
Alternatively, if the configuration values are:
runtime (cblconfig) MAX-FILES 32
server (a_srvcfg) MAX-FILES 64
the runtime will be able to open, at most, 32 remote files.
Determine values for LOCKS-PER-FILE, MAX-FILES and MAX-LOCKS by noting the values set in cblconfig and then multiplying the value of each variable by the number of runtimes likely to access the server simultaneously. The resultant values will be sufficient to support the case where all runtimes have the maximum number of files open with the maximum number of locks applied. We recommended that the values assigned these variables in "a_srvcfg" not be smaller than the values assigned in "cblconfig."
For example, if you anticipate having four runtimes accessing the server simultaneously, and the settings of your runtime configuration variables are:
LOCKS-PER-FILE 10
MAX-FILES 30
MAX-LOCKS 40
the corresponding variables in a_srvcfg might be:
LOCKS-PER-FILE 40
MAX-FILES 120
MAX-LOCKS 160
The value of LOCKS-PER-FILE and MAX-FILES in the server configuration file cannot exceed 32767 for Vision files. The value of MAX-LOCKS cannot exceed 8191 for Vision files. To conserve system resources and improve runtime and server performance, set these variables to the smallest value that still meets your requirements.
PASSWORD-ATTEMPTS
The variable PASSWORD-ATTEMPTS, as well as the variables DEFAULT-USER and ACCESS-FILE, affects system security.
PASSWORD-ATTEMPTS holds a positive integer value specifying the total number of password validation attempts a requester is allowed before a connection attempt is terminated. The default value is three. If a value of less than one is given, the value one (1) is used. If a non-integer value is given, the default value (3) is used.
SERVER-IP and SERVER-NAME
The variables SERVER-IP and SERVER-NAME allow you to assign a specific IP address to an individual instance of the acuserve daemon. Use these variables when the server has two or more network addresses and you want to associate a particular network address with a given instance of the acuserve daemon.
To specify an IP address, include an entry for SERVER-IP in the configuration file and assign it the value of the desired IP address on the host. For example:
SERVER-IP = 192.215.170.107
To specify a hostname, make an entry for SERVER-NAME in the configuration file and assign it the value of a valid hostname on the server. For example:
SERVER-NAME = bigserve
where bigserve is the hostname for IP address 192.215.170.107.
If both variables are defined in the configuration file, acuserve uses the value of the first valid entry in the file.
By defining different values for these variables in separate server configuration files on the host and then specifying a particular configuration file when you start the acuserve daemon, you can associate a specific IP address/hostname with each instance of acuserve.
SERVER-NUMBER
The variable SERVER-NUMBER is used mainly by those sites that have licensed a multiple-use version of AcuServer. A multiple-use license entitles the site to spawn multiple instances of the acuserve daemon on the same host machine. This capability can be used to distribute the client load on large networks among multiple copies of the daemon, and thus can improve throughput.
A SERVER-NUMBER can be associated with the acuserve program and with any client program that accesses acuserve. Valid server numbers range from 1 to 32767.
The acuserve program is assigned a SERVER-NUMBER in the server configuration file ("a_srvcfg") or on the command line when it is started. Any value set for this variable in the server configuration file is overridden by any server number assigned on the command line (via the "-n" option) at start-up.
The client program is assigned a SERVER-NUMBER in the runtime configuration file ("cblconfig"). Assigning a SERVER-NUMBER to a runtime simply assigns that runtime to a particular instance of the acuserve daemon. For example, suppose host machine A is running three instances of the acuserve program, which you have assigned the server-numbers 1, 2, and 3. Then if twelve client programs are accessing these daemons on host machine A, you might assign the first four client programs to SERVER-NUMBER 1 (via the runtime configuration file). The next four clients might be assigned to SERVER-NUMBER 2, and the last four to SERVER-NUMBER 3. Each runtime will use only the daemon to which it has been assigned. This can help to balance the load on the server daemons, and thus can help optimize network performance.
If the remote name notation for a particular runtime specifies more than one host machine, then you may have a server running on each host for the specified server-number.
For example, suppose you have two runtimes, one assigned to SERVER-NUMBER 1 and one to SERVER-NUMBER 2. If there are two servers running on host A and two on host B, then:
runtimes with SERVER-NUMBER=1 and
FILE-PREFIX=@A:/data @B:/data
could use the daemon on host A with SERVER-NUMBER=1
and the daemon on host B with SERVER-NUMBER=1
runtimes with SERVER-NUMBER=2 and
FILE-PREFIX=@A:/data @B:/data
could use the daemon on host A with SERVER-NUMBER=2
and the daemon on host B with SERVER-NUMBER=2
Note: sites that use the FILE-PREFIX variable to set up paths for multiple directories or multiple servers (either multiple server host machines or multiple instances of the acuserve program on a single host) can improve performance significantly by using name aliasing instead of FILE-PREFIX. This is because a substantial number of RPC calls may be needed to search for a file whose path has been defined with FILE-PREFIX. This is especially true when using Windows NT servers and share names (a share name is the name assigned when the directory is set up for sharing under Windows NT). This is because Windows NT uses a very inefficient algorithm to resolve share names. For more information about name aliases, see section 2.3.5.
Multiple instances of acuserve may use the same SERVER-PORT as long as each daemon is assigned a different SERVER-NUMBER. However, to distribute the load on the server port, it is better to have each instance of the acuserve daemon use a different port.
Under UNIX, to identify the server daemons that you have running, you can use the command "rpcinfo -p". Each daemon will have a program number of 300300 + SERVER-NUMBER. (Sun Microsystems has assigned the RPC program number 300301 to AcuServer.) For example:
rpcinfo -p
program vers proto port 100000 2 tcp 111 portmapper 100000 2 udp 111 portmapper 300301 1 tcp 8222
The program number 300301 means that you have a server daemon running with SERVER-NUMBER set to 1 (300301 minus 300300 = 1).
To make this report even more helpful, you may want to assign a name to the program number. To do this you must modify the "/etc/rpc" file and add a line or two similar to the following:
acuserve1 300301
acuserve2 300302
Then after you start acuserve and use the command "rpcinfo -p" you will see a report similar to this:
Program vers proto port 100000 2 tcp 111 portmapper 100000 2 udp 111 portmapper 300301 1 tcp 8111 acuserve1 300302 1 tcp 8222 acuserve2
AcuServer for Windows NT (Intel) does not include an rpcinfo utility.
SERVER-PORT
The variable SERVER-PORT specifies a particular port number to be used for accessing acuserve on the server host machine. This is especially helpful when the server host machine has a security firewall, because firewalls generally allow access only to specific ports. With this variable, the site can ensure that firewall restrictions are satisfied.
The acuserve daemon can work with privileged port numbers (from 0 to 1023), and with non-privileged port numbers (1024 and higher, up to 32767).
Under UNIX, to identify the port in use by your acuserve daemon, you can use the command "rpcinfo -p" and look for a program number of 300301 or greater. For example:
rpcinfo -p
program vers proto port 100000 2 tcp 111 portmapper 100000 2 udp 111 portmapper 300301 1 tcp 8222
The last line shows program number 300301, which is an AcuServer daemon. This host has an AcuServer daemon running using port number 8222.
If SERVER-PORT is set to "-1" (the default value), then Acuserver will use an arbitrary port number. If the variable is set to any other number, AcuServer will attempt to use that port number. If the port cannot be used for some reason, then AcuServer will use an arbitrary port.
The value of this variable is overridden by any port number assigned on the command line (via the "-p" option) when the daemon is started.
AcuServer for Windows NT (Intel) does not include an rpcinfo utility.
SERVER-START-<server #>
SERVER-START-<server #> is used only on Windows NT (Intel) servers. It is used to override the default options used to start the service for acuserve. It should be followed by the options that you want to start acuserve with. These may be any options that can be specified after the "acuserve -start" command:
acuserve -start [-c config_file] [-e error_file] [-l] [-t#] [-f]
[-n num] [-p port]
The "-f" and "-n" options are ignored; the service cannot run in the foreground, and its server number is already specified.
The runtime looks for the server configuration file (a_srvcfg) in the directory:
<system-drive>\etc
or, if it is not found there, in
<AcuServer-drive>\etc
where system-drive is the system disk on which Windows NT resides and AcuServer-drive is the drive on which AcuServer resides. If the server configuration file is not found, or if this variable is not set, the acuserve service is started with the following options:
-l -e acuserve.log
Any options that require a filename should provide a full pathname. Otherwise the runtime assumes they are located in <SystemRoot>\system 32, where SystemRoot is a system environment variable defined by Windows NT. You can display its value by using this command:
echo %SystemRoot%
V-SEG-SIZE
V-SEG-SIZE sets the maximum size of a Vision file segment. Vision Version 4 allows for very large logical files by creating additional physical files (called file segments) as needed.
The default value is 2 GB - 1 KB -1 (which is 2,147,482,623 or hexadecimal 7FFFFBFF). The default is also the maximum value allowed. For best performance, set this value as high as possible, to minimize the number of files created.
V-VERSION
This variable specifies the version number of new Vision data files that are created by AcuServer. The default value is "4", which produces Vision files in the latest format (Version 4). Version 4 files are generated in a dual file format, with data records stored in one segment and overhead key information stored in another. The value "3" produces Version 3 files, in which data and keys are stored in a single file. The value "2" produces Version 2 files.
It is possible to have several instances of AcuServer executing simultaneously. These instances can create different versions of Vision files. The following paragraphs explain how to set this up.
?-VERSION
This variable sets the file format on a file-by-file basis. The "?" is replaced by the base name of the file (the file name minus directory and extension). The meaning of the variable is the same as for "V-VERSION". This variable is useful if you want to have all your files in one format, with a few exceptions. For example, you might want to maintain most of your files in Version 3 format to conserve file handles, but have a few files in Version 4 format to take advantage of the larger file size. Note that this variable only affects the file format when it is created. You can always rebuild the file in another format later.
This variable (and the "V-VERSION" variable) is most helpful when you are using transaction management. The transaction system does not record the format of the created file if an OPEN OUTPUT is done during a transaction, because the transaction system is not tied to any particular file system. If you need to recover a transaction, then the system will recreate the OPEN OUTPUT files using the settings of the "VERSION" variables.
UNIX servers
On a UNIX server, suppose you wanted to have two instances of the acuserve daemon executing, with one instance creating Vision Version 4 files, and the other creating Vision Version 3 files. The general strategy is to use two server configuration files.
By default, AcuServer creates Vision Version 4 files, so no entry is required in the server configuration file ("a_srvcfg") to make this happen. Any instance of the acuserve daemon that uses the default setting will create Vision Version 4 files.
To start an instance of the acuserve daemon that builds Vision Version 3 files, simply set up a second server configuration file (such as "b_srvcfg") and include the line "V-VERSION 3" in that file. Then point to the second configuration file at startup time. For example, you might use this command line to start the second instance of the acuserve daemon:
acuserve -start -n 2 -c b_srvcfg
Windows NT (Intel) servers
On a Windows NT server, suppose you have started server number 3 and server number 4 from the command line:
acuserve -start -n 3
acuserve -start -n 4
Suppose you would like them to produce different versions of Vision files.
By default, AcuServer looks for the server configuration file "\etc\a_srvcfg". In that file, you can use the variable SERVER-START-n (described later in this chapter) to override the default options used to start the service for acuserve.
Place these two entries in the file:
SERVER-START-3 -c \etc\config3 (other options as needed)
SERVER-START-4 -c \etc\config4 (other options as needed)
This causes each instance of the acuserve service to start up with a customized configuration file. In each customized file, place the appropriate entry (either V-VERSION 3 or V-VERSION 4).
Caution: Although ACUCOBOL-GT runtimes (from Version 3.2 on) are capable of using keys with more than six segments, Vision Version 3 files are not. If an ACUCOBOL-GT application is accessing Vision Version 3 files, it should not make use of more than six key segments.