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 on the Windows and Linux platforms supported by Pervasive PSQL v11 SP3.

On Windows, the executable program is bcfg.bat and is installed, by default, in the Program Files 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 6

Requirements for Running bcfg on Linux

Requirement

Discussion

Java Runtime Environment (JRE)

The JRE components required to run bcfg are installed as part of Pervasive PSQL. Bcfg uses the “local” version of the JRE installed as part of Pervasive PSQL.

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 and Client for Linux in Getting Started With Pervasive PSQL.

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 7

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.

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

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

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

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

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

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

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]

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

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

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.

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

The help search option for a keyword (that is, help for a keyword). The utility searches for configuration settings that contain keyword and returns the ID and setting name, or returns “no matches found.” See also next row in this table.

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 to server. 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 administrator 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.