$image\bbj40.gif$ Configuring BBj Services via the Enterprise Manager

Description

BBj Services consists of several different servers, each with its own specific purpose. Configuration of each is done using the Enterprise Manager. A number of options require a restart of BBj Services and are marked with an asterisk (*) or a message at the bottom of the dialog (if all fields on the dialog require a restart). Configuration of port numbers should typically be done only in the case where the default port of one of the servers conflicts with another server running on that machine. For BBj Services login and password information, refer to Getting Started in BBj Services.

After launching BBj Enterprise Manager, configure BBj Services as follows:

Right click the tree node for the server to configure.
Select Connect.
Log on to the server as described in Logging On To A Machine That Is Running BBj Services For Administration.
Expand the tree node.
Select the node that describes the configuration information to be modified. Please refer to each specific section below for details about each type of options that can be configured.

NOTE: It is possible to configure the local machine even if connection to the server is not possible (i.e. the server could not be started due to a port conflict). This can be accomplished by selecting the "Configure Local Machine" option from the "Tools" menu. The image below shows this dialog:

$image\em-configurelocal.gif$

IMPORTANT NOTE: Most changes made to the configuration of BBj Services do not take effect until the server is stopped and restarted.

Journaled Filesystem

$image\em-journaledfs.gif$

The "Journaled Filesystem" option allows the configuration of the BBj Journaled Filesystem. The Journaled Filesystem requires two settings, a "Base Directory" and a list of "Log File Locations".

The "Base Directory" is where all Journaled files will be stored. This must be a directory that contains nothing but Journaled Filesystem files. This means that nothing else can be in this directory, including subdirectories.

The list of "Log File Locations" is a list of directories where Journaled Filesystem logs will be stored. These files are a minimum of 80 MB in size and can grow quite large. These log files can be on any mounted/mapped drive, or on the local machine. This directory must NOT be in the Base Directory or a sub directory of the Base Directory.

The final configuration option is the "Lock Table Size" which specifies the size of an internal cache. Decreasing this number will be a performance detriment, while increasing it will use more memory. Using the default setting is recommended.

Logging

$image\em-logging.gif$

The "Logging" option allows the user to specify the location of log files that contain information written to stdout and stderr by BBj Services. The location of the log files used by the various components of the BBj Services can be specified. These log files can be useful for troubleshooting.

For each log file, a maximum size in MB can be set. If the log file is blank, or set to 0, then it will grow indefinitely. If a log file reaches its maximum size, a new log file will be created and subsequent logging will be written to the new file.

Each day, a new log file will be created. The number of days to keep log files can be specified by entering the number of days in the "Keep…Log (Days)" fields. After the specified number of days is reached, the oldest log file(s) will be removed automatically when the new log file is created for the next day.

The user can set logging levels to be used by BASIS Technical Support for diagnosing certain kinds of problems. Please note that the logging levels go back to their default settings when BBj Services is restarted.

BBj Services Setup

After selecting BBj Services, the following Services Information dialog box appears:

$image\bbjservicesinfo.gif$

The BBj Services Information table contains the following data:

Server Type	Displays the type of server (described below). A second or subsequent server is displayed as a "blank" entry under its primary server a seen in the Thin Client Server above.
	Administration	Manages the BBj Services via the Enterprise Manager.
	Bridge	Provides access to the Java BBjBridge which enables a Java program to call a BBj program.
	Filesystem	Provides access to the file system from a BBj Interpreter
	Interpreter	Provides access to a fat client BBj Interpreter session on the local machine
	Port Request	Interacts as a local server with the Proxy Manager Server to provide port information about the various servers to a BBj session when it starts.
	PRO/5 5.0 DS	Enables clients running (V)PRO/5 5.0 and above access to files through the BBj file system using normal data server syntax. BBx and BBj clients can coexist without running a PRO/5 Data Server as long as the BBx clients use Data Server syntax to open files. Since all file access is taking place through the BBj file system, no file locking conflicts will occur.
	Proxy Manager	Maintains a list of currently active ThinClientProxyServers running on the local machine and interacts with the Port Request Server to insure a Thin Client BBj session connects correctly.
	SQL Engine	Provides SQL capabilities to the BBj Interpreter/ODBC/JDBC.
	Status	Returns an error when two or more BBjServices are running and provides various types of debugging status information.
	Terminal	Provides a TermConsole BBj Interpreter session under UNIX. Also provides IO interpreter session under UNIX and Windows.
	Thin Client Proxy	Provides access to Thin Client Servers from a local BBj executable Thin Client Server to local and remote clients.
	Thin Client	Provides an SSL-secured Thin Client BBj Interpreter session to local and remote clients.
Run	Marks an "x" if that server is running
Port	Shows the port number
Interface	Indicates if it is open to all (0.0.0.0) or only the local machine (i.e. 127.0.0.1)
SSL	Marks an "x" if SSL is enable on that server

To configure a server, right click on BBj Services and select Set Configuration. The following BBj Services Setup dialog appears as an interface for managing all of the individual servers that make up BBj Services.

$image\bbjservicessetup.gif$

The User Name and Password options are only visible when the Enterprise Manager is configuring a local machine on a Windows NT/2000/XP machine or when the remote server is a Windows NT/2000/XP machine. These fields allow the user to configure which account BBj Services will use to log on. The user must specify a valid user account and password in the tab. BASIS recommends that this user account is part of the Administrator’s group. BBj Services logs on and runs as this user account, which means that it has the same privileges, environment, and access to shared devices (such as printers, drive mappings, and ODBC User DSNs) as the specified user. BBj Services also executes processes as that user on the thin client’s behalf.

Standard Configuration Settings

To modify the settings for a particular server, click on the appropriate server from the left hand tree control. If there can be multiple servers of a particular type running at one time, expand the node first to see a list of servers of that type that are currently available for configuration.

All servers listed above* require the same standard 4 settings as the Bridge Server sample shown below.

*Exception: Status Server only requires the Port

$image\bbjservicessetup+bridgesvr.gif$

Port	Identifies the port on which the server listens for connections.
Bind Address	Sets the IP address of the only machine able to connect to the server. An address of 0.0.0.0 accepts connections from any IP address. A bind address of 127.0.0.1 (localhost) allows server access from that machine only. Consider setting the Filesystem Server bind address 127.0.0.1 to restrict access when the machine is outside of a firewall and network accessibility is not required.
Maximum Clients	Sets the maximum number of client connections sustained simultaneously.
Run Server	Enables the server when BBj Services is running.

Under normal circumstances, the default settings are acceptable. Some instances when these settings require modification include:

A requirement for Secure Sockets Layer (SSL)
A port conflict with one of the servers
A server needs to be disabled
A bind address needs setting (see below)
One type of multiple servers need to run

To add another server of a particular type, right click on the node corresponding to the type of server to be created and select the Add Server option from the menu.

Additional PRO/5 DS Configuration Settings

In addition to the standard settings, the PRO/5 DS Server requires additional settings pictured below.

$image\bbjservices-pro5dssvr.gif$

The additional PRO/5 DS Server settings are:

SSL	Enables Secure Sockets Layer (SSL) for encrypting the data passed to and from the server.
Prefixes	Provides a list of directories when a requesting a file open. Refer to Using The PREFIX Verb for complete details on the meaning of each prefix. Each item in the list of prefixes is a separate prefix to be examined. To add a new prefix to the list, right click on the list and select Add Prefix. To remove a prefix from the list, right click on the prefix and select the Remove Prefix.
DISKSYN	Lists DSKSYN values for each item equivalent to a single drive specified in the config.bbx file. For more information about the meaning of each entry, refer to PRO/5 Disk Configuration in the documentation. To add a new value, enter the values in the empty line at the bottom of the DISKSYN table. To remove a value, right click on the value and select Remove.
Umask	Sets the UNIX UMASK (file-creating mode mask) of the user and determines the permissions placed on the file when it is reinitialized.
Advisory Locking	Accesses data files using advisory locking.
Mkeyed FID Always 6	Forces the file system to return a type of 6 for all MKEYED derivative files. This setting is used when an application is dependant on the type information about a file returning a type of 6 (original MKEYED type) on data files, but it is using newer MKEYED types such as highly recoverable, 64-bit, etc.
Create Recoverable Files	Creates new files as highly recoverable by default.
Create 64-bit Files	Creates new files as 64-bit files.
Scan All Roots	Applies only to Microsoft Windows machines. If no drive letter is specified, and this option is checked, the file system checks each valid drive (subject to DSKSYN settings) as well as the current drive. For example, if OPEN(1) "/temp/hello.dat" is called, the file system first examines C:/temp/hello.dat, then if unsuccessful it tries A:/temp/hello.dat, then D:/temp/hello.dat, etc.

BBj Environment

$image\em-bbjenv.gif$

Web User	The user that should be used by the Web application that is communicating with this server.
Secure NT DS Encrypter	The encryption class to use when establishing a connection to the Secure NT Data server (PRO/5 series)
Program Cache Size	Sets the number of programs kept in memory in a Most Recently Used (MRU) cache. The default is 300.
Resource Cache Size	Sets the number of resources kept in memory in an MRU cache. The default is 32.
User Authentication	If this is selected, users will be prompted to enter a user name and password when a BBj Thin Client or Term Console session is launched. See BBj User Authentication.
Release Immediately On Lost Connection	Controls whether the Interpreter session should be terminated immediately if the client side of a thin client connection dies unexpectedly.
Notify User On Internal Error	Displays a message when the user encounters an internal BBj error. For more information, see BBjConfig::notifyUserOnInternalError.
Use Shared File Access	Enables when the BBj file system uses traditional BBx file locking to access files. Typically, BBj locks files from the outside world when it opens a file. This means that only the BBj Services that is currently accessing the file can access the file until it is finished with the file. Enabling shared file access means that PRO/5 and Visual PRO/5 applications can still access the data files opened in BBj directly. NOTE: Negative impact on performance occurs when enabling this feature.
Use Ident Verification	If this is selected, BBj Services will use IDENTD in conjunction with RHOSTS for authentication. This option is only valid when User Authentication is not selected.
Thread Pool Size	Maximum number of simultaneous threads used by the thread pool shared by the SQL engine, Filesystem, and administrative servers. Normally, users do not need to change this setting.
Thin Client JVM Wait Time	Specifies the number of seconds that the JVM continues to run after the last thin client session starts.
Unpin All Programs Button	Unpins all currently pinned programs. See "Pinning Programs" below for more information.
Clear Program Cache Button	Instructs BBj Services to clear its program cache.
Clear Resource Cache Button	Instructs BBj Services to clear its resource cache.
Dump JVM Threads	Performs a thread dump of the JVM’s currently running threads to standard err. This does not affect the running of applications. BASIS Technical Support uses this information for debugging purposes.

Pinning Programs

When BBj encounters the command "CALL filename", "LOAD filename", "RUN filename", or "START filename" it executes an algorithm to find and load the correct program file. BBj traverses the disks and directories defined by PREFIX and DSKSYN statements in the current configuration. After finding the correct file, BBj checks the program cache to determine whether the program file is already in memory. If the file is in memory, BBj then examines the file on disk to determine whether it has been modified since the file in memory was loaded. In most cases, and especially if the PREFIX list is long, BBj is required to make a number of calls to the filesystem.

This algorithm ensures that the next time the command "CALL filename" with the same filename is encountered:

BBj will reload the modified file if some other process has modified the filename.
BBj will load a new file if another process has created a new file with the filename that appears ‘earlier’ in the PREFIX/DSKSYN search path.

If BBj Services is configured to pin previously loaded programs, the standard search algorithm will not be executed. Instead, BBj will continue to use the same file each time it encounters "CALL filename", "RUN filename", "LOAD filename" or "START filename," unless the process has executed CHDIR or SETDRIVE. If either CHDIR or SETDRIVE has been executed, then BBj will re-execute the standard search algorithm the next time it encounters "CALL filename."

It is common practice for BBx developers to create a new file on disk or to modify an existing file anticipating that programs will immediately begin to use the new/modified file. If programs are pinned, then they will not use the new/modified file when the file can be obtained from the program cache.

To make all programs load a new/modified file, use the Enterprise Manager if program pinning is enabled. The Environment Tab in the Enterprise Manager contains an "Unpin All Programs" button. This button is only available when 'logged' into BBj Services. Clicking this button causes BBj to execute the standard search algorithm to find the file "filename" the next time BBj encounters the command "CALL filename." After the program is reloaded, it becomes repinned and the standard search algorithm will not be executed in subsequent CALLs to the same program name.

Skin Info

$image\em-skin.gif$

None: Select this option if no skin is to be applied.
Theme Pack: Select this option if a theme pack will be specified as the skin to be used by BBj applications. The theme pack file must also be specified if this option is selected.
Individual Files: Select this option if the skin definition is contained in individual files. The location of the files must also be specified in the appropriate text field for the type of these skin files.

Java Settings

$image\em-javasettings.gif$

CLASSPATH

The CLASSPATH tab allows the specification of the location(s) of any additional Java resources that will be available to BBj applications. These resources can include third party libraries, JDBC drivers, etc. Using a JDBC driver other than the BBj driver or the Sun JDBC-ODBC Bridge driver requires adding the path to the driver’s JAR file on this tab.

Items can be added or removed from the CLASSPATH as desired by simply clicking the Add or Remove buttons. When adding a new item, a file browse dialog will appear which will allow the selection of the directory or JAR file that is being added to the CLASSPATH.

JVM (Java Virtual Machine)

The JVM tab allows the specification of the JVM used for the BBj Services server. On UNIX operating systems, the user specifies the directory that contains the Java executable. On Microsoft Windows operating systems, the user specifies the jvm.dll file used for each of the applications displayed in the list box. On both types of operating systems, the user can also specify any command line arguments necessary such as stack size.

To set the jvm.dll or Java executable file and any command line arguments for an application, click the "Properties" button. To reset them to the default setting, click on the "All To Default" button.

When changing the JVM settings, BASIS suggests making most changes to the default settings to affect all applications currently set to use the default settings. This makes future administration much easier. Then make individual changes to the settings of applications only when that application requires settings that differ from the default.

Memory Allocation

Providing command line parameters to Java can influence the amount of memory that the operating system allocates to Java; a portion of which is then made available to BBj.

For more information, see the Advantage magazine article about BBj memory management at www.basis.com.

To obtain a detailed listing of Java command line parameters supported by your JVM, run the following command:

java -?

Additionally, the –X options provide users with advanced configuration selections, but they are non-standard and subject to change.

For example, the following options define an initial (-Xms) memory allocation of 192 MB and maximum (-Xmx) memory allocation of 256 MB:

-Xms192m -Xmx256m

For additional information, visit the Sun Java Web site at http://java.sun.com.

Memory Management

Below is a graph of optimally-tuned memory settings for Java running BBj. For more information, refer to the Advantage article New Language Features Give Programmers More Choices, under the heading Java Memory Management.

$image\em-memorymgr.gif$

Performance

$image\em-performance.gif$

The "Performance" dialog provides a way to limit the amount of message acknowledgement traffic that goes back and forth between the thin client and the server. Settings are labeled "Production" and "Development." If an application is completely in production and working as expected, all of the options under the Production column should be selected. During development, it may be helpful or necessary to select one or more of the options in the Development column in order to better track messages.

The following table describes each of the settings:

Production Settings

UI Ack Back	Equivalent to executing BBjConfig.suppressUIAckBack(1), which controls whether the Interpreter waits for a response from UI before processing the next program statement.
Printer Ack Back	Equivalent to executing BBjConfig.suppressPrinterAckBack(1), which controls whether the Interpreter waits for a response from UI before processing the next program statement.
Send Message Responses	Equivalent to executing BBjConfig.requireAllSendMsgResponses(0), which controls whether the Interpreter waits for a response from UI before processing the next program statement.
Pin Previously Loaded Programs	Causes all programs to be pinned. See Pinning Programs below for more information. Pinning should be disabled in Development mode and enabled in Production mode.