Configuration Through CLI Utility

The command line interface (CLI) version of configuration provides the same configuration functionality as the property dialogs in Pervasive PSQL Control Center. The CLI Configuration runs only on the Windows and Linux platforms supported by Pervasive PSQL v9 Service Pack 2.

On Windows, the executable program name is bcfg.bat and is located, by default, in the PVSW\bin directory.

On Linux, the executable program name is bcfg and is located, by default, in the /usr/local/psql/bin directory. The following requirements must be met to run bcfg on Linux.

Table 4-1 Requirements for Running bcfg on Linux
Requirement	Discussion
Java Runtime Environment (JRE)	The Standard Edition of the JRE is required to run bcfg. You can download the version from java.sun.com. Some Linux distributions include gcj, a GNU compiler for the Java programming language. If your Linux distribution includes the gcj compiler, check your PATH environment variable. Ensure that the path to the Standard Edition JRE appears before the path to the gcj. Rather than change your PATH variable, you could edit the bcfg script and set the correct path in the script. Note: The server or client installation informs you if the JRE is required. To determine if the Standard Edition JRE is installed or if it is in your PATH variable, enter the following command at a terminal window: `java -version` A return message of "command not found" means that you need either to install a JRE Standard Edition or add the JRE path to the PATH environment variable. You can download the JRE from java.sun.com. Add the PATH using an EXPORT command similar to the following (assuming your JRE is installed to /usr/local/java): `export PATH=/usr/local/java/bin:$PATH`
Pervasive PSQL server or client	A compatible Pervasive PSQL server or client must already be installed on the same machine. See Installing Pervasive PSQL Server for Linux and Installing Pervasive PSQL Client for Linux in Getting Started With Pervasive PSQL (Server edition).

If you have met the requirements to run bcfg on Linux and still are having difficulty running the utility, refer to the following troubleshooting guide.

Table 4-2 Troubleshooting Guide for Running bcfg on Linux
Troubleshooting Condition	Discussion
You receive the error "java.lang.UnsatisfiedLinkError."	This error typically occurs if you try to start bcfg by double-clicking on the script file using a file browser application. Start bcfg from a command prompt. This error can result if the LD_LIBRARY_PATH variable is not set. If you run bcfg as user "psql," this variable is set in the profile for psql. You may also explicitly set the variable with the following command: `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/psql/lib`
You receive the following error message: "Unable to connect to database engine. Make sure the target machine is accessible and an engine is running on the target machine."	The context of this error occurs if you attempt to administer the local server. To administer the local server, you must be a member of the pvsw group or be the root user. See also Pervasive PSQL Account Management on Linux in Getting Started With Pervasive PSQL (Server edition).

Setting a Configuration

You can configure settings one at a time from the command line or by providing one or more settings in an input file.

Tip
A convenient way to create an input file is first to create an output file. You can then edit the output file and use the edited version as an input file. See Editing an Input File for the types of edits permissible.

Restarting the Engines

If you use an input file, bcfg prompts you to restart the database engines after the utility processes the file. The restart applies regardless of the settings in the input file. Stopping then starting the engines ensures that the configuration settings take effect.

If you configure a setting from the command line, bcfg prompts you to restart the database engines only if the setting requires a restart.

See Ensuring Configuration Changes Take Effect for how to restart the engines.

Example Scenario: Configuring a Single Setting from the Command Line

Suppose that you want to turn on a configuration setting having to do with reconnecting a client to the server in the event of a network outage. You are not certain about the name of the configuration setting. Complete the following steps.

At a command prompt, type bcfg -H reconnect then press Enter.

The utility reports all settings that contain the string "reconnect":

ID Setting Name ----------------------------- 29 Enable Auto Reconnect 148 Enable Auto Reconnect 149 Auto Reconnect Timeout

Two of the settings, 29 and 148, look like what you want, but which is which?

Type bcfg 29 then press Enter.

The utility reports the following for setting ID 29:

=====================

ENABLE AUTO RECONNECT

=====================

ID: 29

Value: Off

Options: On Off

Default Value: Off

Description: <Client setting> Specifies if the Client will attempt to reconnect to the Server in the event of a network outage. The reconnected Client will continue processing as if no errors were encountered.

The description tells your that this setting applies to a client and that the setting is currently "off."

Type bcfg 29 on then press Enter.

The utility informs you that system setting 29 has been updated.

If you want to verify that the setting is now "on," type bcfg 29 then press Enter.

The utility reports the following for setting ID 29:

=====================

ENABLE AUTO RECONNECT

=====================

ID: 29

Value: On

Options: On Off

Default Value: Off

Note that the value is now set to "on."

Editing an Input File

An input file must contain at least one complete record for one setting. If you create an input file from an output file and want to remove configuration settings, ensure that the remaining settings are complete records.

At a minimum, a complete record encompasses and ID and Value pair. However, to ensure clarity, it is recommended that you include the top line of the setting header through the setting's description. For example, here is a suggested minimal record for Enable Auto Reconnect:

=====================

ENABLE AUTO RECONNECT

=====================

ID: 29

Value: On

Options: On Off

Default Value: Off

Other than limiting which setting records are included in the input file, the only other change allowed is to the Value assignments. The assignment can be whatever is specified by Options or by Range.

Command Syntax

bcfg -I inputfile [-S server] [-U username] 
[-P password] [-E] 
 
or

bcfg -O outputfile [-S server] [-U username] 
[-P password] [-E] 
 
or

bcfg ID [value] [-S server] [-U username] 
[-P password] 
 
or

bcfg -H <keyword | ''keyword with spaces''> [-S server]
[-U username] [-P password]

Options


-I	Required parameter if you provide an input file to the utility.
inputfile	A text file that contains one or more configuration setting records for a specified server and the value assigned to each setting. A convenient way to create an input file is first to create an output file. You can then edit the setting values as required and use the edited version as an input file. See Editing an Input File for the types of edits permissible.
-O	Required parameter if you want the output results of running the utility sent to a text file.
outputfile	A text file that contains the current configuration settings for a specified server as a result of running the utility.
ID	A two or three digit integer that uniquely identifies the configuration setting. Some configuration settings require that you restart the database engines for the setting to take effect. Bcfg prompts you if a restart is required. See Restarting the Engines .
value	A value assigned to the configuration setting. The valid values are specified in a setting record in Options or Range. If Value is omitted, the utility returns the current setting. If Value is included, the utility changes the setting based on the value assignment. See Example Scenario: Configuring a Single Setting from the Command Line .
-H	Required parameter if you provide a keyword. This parameter displays help for a keyword by listing the ID and name for the setting.
keyword	The name of the configuration setting, such as ALLOW CLIENT-STORED CREDENTIALS or SUPPORTED PROTOCOLS. Note that keyword is case insensitive. However, if the keyword contains one or more spaces, you must double quote the string. The utility can provide help based on partial keywords. For example, if you specify -H client, the utility returns all setting with the word "client" as part of the setting name. If you specify -H a, the utility returns all settings with an "a" in the name.
-S	Required parameter if the configuration settings apply to a remote server (a server other than the local one).
server	The name or IP address of the remote server that contains the database engine.
-U	Required parameter if a user name is required to access server.
username	User name with which you will connect toserver. See also Pervasive PSQL Security . If server is a local machine, the username and password are not required if: You are logged in to the local machine as an admistrator or as a member of the Pervasive_Admin group The local machine is not running Terminal Services.
-P	Required parameter if a password is required to access server.
password	Password used with username to connect to the server. See username. See also Pervasive PSQL Security .
-E	Ignore errors when reading inputfile or writing to outputfile.