Service Engine Configuration

The BIS Service Engine runs as a UNIX daemon process and one or more service processes which the daemon creates, as needed. There are always one or more idle service processes waiting for the Request Handler (the Apache part) to process a StartService tag.

Because the Service Engine runs as daemon, it normally starts when the operating starts, without any direct user interaction. It gets all of its options from a configuration file, its command line and its environment. The configuration file is usually named /etc/xbis.conf, but this can be changed by the ‑f command-line option. Each line in the configuration file is either a blank line, comment line or an option line. A comment line is a line in which the first nonblank character is a # character. On an option line, the line begins with a keyword, which is followed by one or more spaces or tabs and then by the option value. A # character may follow the option value to introduce an in-line comment.

The configuration file option keywords are:

BinDir Specifies the name of the directory where the BIS binary executable files are located.

There is no reason for a user to alter this parameter after installation.

LibDir Specifies a colon separated list of directory names that will be placed into the standard search path environment variable for the UNIX platform when the Service Engine is started. Usually the environment variable is LD_LIBRARY_PATH, but it is LIBPATH for AIX, SHLIB_PATH for 32-bit HP-UX, and LD_LIBRARY_PATH_64 for 64-bit Solaris. The value of this option is prepended to the current value of the library search environment variable. There is no reason for a user to alter this parameter after installation.
LogDir Specifies the name of the directory where the BIS log files are placed.
MaxChildren Specifies the maximum number of service (child) processes.

This is normally set to 250.

MaxSessions Specifies the maximum number of BIS sessions. It defaults to twice the MaxChildren value.
PageSize Specifies the amount of space allocated in the Sessions file for each session. This holds the information about a session between requests. It must be a power of two and it must be at least 512 but no more than 16384. It defaults to 2048, which should be sufficient unless your stencils define unusually long paths or a large number of environment variables.
SaveFiles If specified, copies of all request and response files are saved in the temporary directory.

This is a debugging tool, typically used during development of a web site.

ServiceTimeout Default service timeout, in seconds.

This is the preferred way to set the default service timeout. If BIS_SERVICE_TIMEOUT is set in the Apache configuration file for BIS (bis.conf), the Request Handler uses that value to override the value of the -T option. Doing so delays the start of each service program slightly.

SharedMemory If present, specifies the shared memory key that the Service Engine is to use. This directive should only be used when it is desired to run multiple Service Engine daemons on the same UNIX server. The value is an 8-hex digit value that must be matched by the value BISSesDaemonKey directive in use by the Request Handler. Only specify this keyword option when directed by Micro Focus Technical Support.
Socket Specifies the name of the socket used by the Request Handler to communicate with the Service Engine daemon.

There is no reason for a user to alter this parameter after installation.

TempDir Specifies the name of the directory where temporary files are created.
UserName Specifies the UNIX user name used by each service (child) processes. Although the Service Engine daemon process runs as root, each of the child service processes runs as the user specified by this option. This determines the files that a service process can read and write, as well as the home directory of each service process.

Options on the Service Engine daemon's command line may modify the configuration as determined by the configuration file and the built-in defaults. The command-line options are in a string that is assigned to an environment variable named OPTIONS. All of the Service Engine's environment variables, including OPTIONS, are set in a file named /etc/sysconfig/xbis. This file is created during the install of BIS.

The command-line options are:

-f file Specifies the name of the Service Engine configuration file.

If this option is present, it must be the first option on the command line. If omitted, the configuration file name defaults to /etc/xbis.conf.

-c count Specifies the maximum number of service (child) processes.

This is normally set to 9999 to indicate that the number of service processes is limited only by the license, but it may be set to a smaller value as a throttle.

-i count Specifies the number of idle service (child) processes.

This is normally set to 1 but a small increase in this may improve response time on a server which receives many requests in rapid succession.

-T timeout Default service timeout, in seconds.

This is the preferred way to set the default service timeout. If BIS_SERVICE_TIMEOUT is set in the Apache configuration file for BIS (bis.conf), the Request Handler uses that value to override the value of the -T option. Doing so delays the start of each service program slightly.

-u user Specifies the UNIX user name used by each service (child) processes.

Although the Service Engine daemon process runs as root, each of the child service processes runs as the user specified by this option. This determines the files that a service process can read and write, as well as the home directory of each service process.

-t dir Specifies the name of the directory where temporary files are created.
-r If specified, copies of all request and response files are saved in the temporary directory.

This is a debugging tool, typically used during development of a web site.

-L file Specifies the name of the Service Engine event log file.

The Service Engine records certain important events in this file. This is a debugging tool.

-s file Specifies the name of the socket used by the Request Handler to communicate with the Service Engine daemon.

There is no reason for a user to alter this parameter after installation.

-U file Specifies the name of a file used by the Service Engine daemon to communicate with the Request Handler.

There is no reason for a user to alter this parameter after installation.

If the BIS Service Engine options need to be changed, the configuration file ( /etc/xbis.conf) may be edited or (on systems other than AIX) the file /etc/sysconfig/xbis may be edited. If the configuration file is changed, the Service Engine can be instructed to reread it by using a kill command to send the Service Engine daemon a SIGHUP signal. However, the Service Engine does not read /etc/sysconfig/xbis directly. Instead, the shell script which starts the Service Engine reads this file. For any changes to take effect, the Service Engine must be restarted, either by restarting the operating system, by changing the runlevel, or by executing the shell script which starts the Service Engine ( /etc/init.d/xbisengd). This script accepts one parameter, which must be one of the following:

Start Starts the BIS Service Engine.
Stop Stops the BIS Service Engine.
Restart Stops the BIS Service Engine, and then starts it again.
Condrestart If the Service Engine is running, stop it, and then start it again. Otherwise, do nothing.
Status Displays the status of the Service Engine.

Note that stopping the Service Engine stops all of the service processes immediately, terminating any running service programs. This should not be used when users are connected to the server.