image\bbj40.jpgConfiguring 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.

To configure BBj Services options:

1.  Expand the tree node for the server to configure

2.  Log on to the server as described in Logging On To A Machine That Is Running BBj Services For Administration.

3.  Double-click on 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.jpg

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.jpg

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.jpg

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 Startup

image\em-bbjservices.jpg

The "User Name" and "Password" options should only be visible when the Enterprise Manager is configuring a local machine on a Windows NT/2000/XP machine or the remote server is a Windows NT/2000/XP machine. This tab allows 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. It is recommended that this user account be a part of the Administrator’s group. BBj Services will log on and run as this user account, which means that it will have the same privileges, environment and access to shared devices (such as printers, drive mappings, and ODBC User DSNs) as the specified user. It will also act as that user when executing processes on a thin client’s behalf.

The table of server information provides a way to configure the various servers that run within BBj Services. Under normal circumstances, these settings should not need to be modified. However, if there is a port conflict, the offending server should be changed to run on a different port.

·  Run: If this box is checked, the server will be run when BBj Services is running.

·  Port: The port on which the server will listen for connections.

·  Bind Address: The IP address of the only machine that can connect to the server. If it is 0.0.0.0, then connections will be accepted from any IP address. If the bind address is set to 127.0.0.1 (localhost), then that server will only be accessible from that machine. It may be desirable to modify the bind address of the Filesystem Server to 127.0.0.1 to restrict access if the machine is outside of a firewall and network accessibility is not required.

·  Max Clients: The maximum number of client connections that can be simultaneously sustained.

BBj Environment

image\em-bbjenv.jpg

·  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 File: The name of the file to store the program cache.

·  Resource Cache File: The name of the file to store the resource cache.

·  Program Cache Size: Sets the number of programs kept in memory in a Most Recently Used (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.

·  Resource Cache Size: Sets the number of resources kept in memory in an MRU cache. The default is 32.

·  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.

·  Disallow Thin Client Console: Turning this option on disallows any connected clients from entering console mode. This has the additional benefits of increased security and reduced bandwidth usage because the server does not send any program listings to the client.

·  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.

·  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.

·  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.

·  Notify User On Internal Error: Displays a message when the user encounters an internal BBj error.

·  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.jpg

·  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.jpg

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 the JVM that will be used for the BBj Services server.

On UNIX operating systems, the user will specify the directory that contains the Java executable, and any command line arguments that are necessary.

On Microsoft Windows operating systems, the user will specify the jvm.dll file that will to be used for each of the applications that are listed in the list box. To set the jvm.dll file and any command line arguments for an application, click the "Properties" button. To reset all of them to the default setting, click on the "All To Default" button.

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.

Performance

image\em-performance.jpg

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

Setting

Description

UI Ack Back

Equivalent to executing the method 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 the method 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 the method 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.