General Reference > User's Guide > Command Line Interface Utilities
Command Line Interface Utilities
This following topics discuss Zen command line interface (CLI) utilities:
CLI Utilities Overview
In addition to providing GUI utilities, Zen provides a number of command line interface (CLI) utilities that you can use. In most cases, these utilities duplicate functionality you can perform with GUI utilities.
For default locations of Zen files, see Where are the files installed? in Getting Started with Zen.
Platforms that Include CLI Utilities
These utilities are provided in the following installations:
• Windows – Enterprise Server, Cloud Server, Workgroup, and a limited set on Client
• Linux and Raspbian – Enterprise Server, Cloud Server, and a limited set on Client
The following summary of utilities notes which ones are present in a particular installation.
Where to Find CLI Utilities
Please note the location based on your platform.
Windows
In Windows, the utilities are installed to the bin directory of your Zen installation. If you installed to the default installation location, C:\Program Files (x86)\Actian\Zen\bin\. Since the Zen installation places your installation directory in the Path environment variable, these utilities should be available from any command prompt.
Linux and Raspbian
On Linux, utilities are installed to /usr/local/actianzen/bin. The user zen-svc has the necessary environment variables to use the utilities. If you wish to use utilities from accounts other than zen-svc, follow the instructions in Zen Account Management on Linux and Raspbian.
Utilities by Platform and Engine Type
The following tables outlines the command line tools, the platform where they are available, as well as whether the tool also has a graphical user interface.
Tool
Description
GUI Available
Windows
Linux
Server
Client
Server
Client
bcfg
Configures Zen components
Zen Control Center (see Configuration Reference in Advanced Operations Guide)
Yes
Yes
Yes
Yes
bdu
Imports data into a database
No
Yes
No
Yes
No
bmon
Monitors Zen activity
Monitor tool (see Monitoring in Advanced Operations Guide)
Yes
 
Yes
 
btadmin
Creates and administers database usernames and passwords
No
No
No
Yes
No
butil
Repairs and manipulates data files
Maintenance tool (see Manipulating Btrieve Data Files with the Maintenance Tool in Advanced Operations Guide)
Yes
Yes
Yes
Yes
clilcadm
w64clilcadm (Windows 64-bit)
clilcadm64 (Linux 64-bit)
Applies and administers user licenses.
License Administrator (see License Administration)
Yes
No
Yes
No
clipaadm
w64clipaadm (Windows 64-bit)
clipaadm64 (Linux 64-bit)
Phone authorization tool used to authorize product keys when an internet connection is unavailable.
(Phone authorization only)
Phone Authorization Wizard opened by running guipaadm at a command prompt
Yes
Yes
Yes
Yes
dbdefrag
Finds and corrects data fragmentation, rebuilds indexes, removes unused space.
Defragmenter (see Monitoring Data File Fragmentation in Advanced Operations Guide)
Yes
No
Yes
No
dbmaint
Creates and administers named databases
No
No
No
Yes
No
deu
Exports delimited data to a text file based on a SELECT statement
ZenCC (see Creating, Importing, and Exporting Data)
Yes
Yes
Yes
Yes
dsnadd
Creates and administers Engine DSNs on the server
No
No
No
Yes
Yes
easysync
Automates replication of records between databases
No
Yes
No
Yes
No
isql
isql64 (Linux 64-bit)
Allows you to run SQL statements interactively and test connectivity to a DSN.
No
No
No
Yes
Yes
licgetauth
w64licgetauth (Windows 64-bit)
licgetauth64 (Linux 64-bit)
Transmits authorization request data and retrieves authorization key data.
(Offline authorization only)
No
Yes
Yes
Yes
Yes
Notification Viewer
Provides two interfaces: Notification area icons and a graphical user interface. Although not strictly a CLI tool, it is mentioned here for reference.
See Notification Viewer in Advanced Operations Guide.
Yes
No
Yes
No
psc
Manipulates Zen services
No
Yes
Yes
No
No
psregedit
Configures Zen components by editing the Zen registry
No
No
No
Yes
Yes
psregsvr
Register Zen components
No
No
No
Yes
Yes
pvdbpass
Specifies usernames and passwords for secure databases
Zen Control Center (see Zen Security in Advanced Operations Guide)
Yes
Yes
Yes
Yes
pvddl
Processes SQL statements in a command file
Zen Control Center (see SQL Editor)
Yes
Yes
Yes
Yes
pvnetpass
Specifies usernames and passwords for remote servers
No
Yes
Yes
Yes
Yes
rbldcli
Rebuilds MicroKernel data files.
Rebuild wizard (see Rebuild Tool GUI Reference in Advanced Operations Guide)
Yes
Yes
Yes
Yes
rbldcli_offline
Rebuilds MicroKernel data files. Same as rbldcli, but for use on systems where Zen is not installed.
No
N/A
N/A
N/A
N/A
Command Line Interface Tool Reference
This section provides a reference for the following command line interface utilities:
• bcfg
• bdu
• bmon
• butil
w64clilcadm
clilcadm64
w64clipaadm
clipaadm64
• dsnadd
• isql
isql64
w64licgetauth
licgetauth64
• psc
• pvddl
bcfg
The bcfg tool is documented in Advanced Operations Guide. See Configuration Using Bcfg.
bdu
Description
The Bulk Data Utility (BDU) is a command line tool that allows you to load data from a delimited text file into a table. The table and database must already exist.
The BDU, the table, the database, and the Zen database engine must all be located on the same machine. The delimited text file must be locally accessible by the database engine server through a local drive, mapped drive, mounted folder, or shared folder.
You may use a default delimiter or a user-specified delimiter. The delimiting character must not be contained in the data itself. The following tables list the permissible delimiters.
Column Delimiter
Indicated By
Tab
\t (default)
Any single printable character (control characters are not printable, except null, tab, new line, and carriage return)
(*, A, t, l, and so forth)
Note:  Zen does not support use of NULL terminator (\0) or double quote (") as column delimiters.
Row Delimiter
Indicated By
New line character
\n (default)
Carriage return
\r
Carriage return line feed (CR LF)
\r\n
The BDU supports only single quote (') and double quote (") characters as text qualifiers. The data file may contain column values enclosed by single quotes or by double quotes. For example, the following column values are enclosed by double quotes and delimited by the tab character:
"Fred"\t"22"\t"2459"\t"Sales"\t
The BDU treats consecutive column delimiters as NULL values. If the tool finds consecutive column delimiters, it inserts a NULL value into the column, provided the column is nullable.
No qualifiers are allowed for a NULL value. The following column data inserts a NULL value in the second column. Note that qualifiers are not included for that column:
"Fred"\t\t"2459"\t"Sales"\t
Synopsis
bdu {database_name} {table_name} {data_file}
[-<e|E> max_errors]
[-<r|R> reject_file]
[-<f|F> first_row]
[-<l|L> last_row]
[-<t|T> field_term]
[-<n|N> row_term]
[-<o|O> output_file]
[{-<u|U> login_id} {-<p|P> password}]
[-<c|C> encoding]
[-<h|H>]
Note:  When loading data with BDU into a secured database for which the Btrieve Security policy is set to Mixed, the supplied credentials (username and password) must match those of a Zen database user account and an operating system user account.
Parameters
Parameter
Mandatory/Optional
Default Value
Description
database_name
Mandatory
 
Database name to connect to the local engine
table_name
Mandatory
 
Name of the table to be populated
data_file
Mandatory
 
Name and location of the delimited text file
-<e|E> max_errors
Optional
0 (zero)
The BDU exits when the first error is encountered.
The maximum number of errors that the BDU ignores before exiting
-<r|R> reject_file
Optional
stderr
Name of the file to which to write the rows that failed load. The specified directory must exist. However, if the file does not exist in the specified directory, it will be created.
-<f|F> first_row
Optional
Row 1
The first row in the delimited text file with which the load begins. This parameter allows you to skip a header row. For example, if your header row is row 1, set first_row to 2.
-<l|L> last_row
Optional
End of the source file
Last row in source file (row will be included in load). The load will stop after the end row has been loaded
-<t|T> field_term
Optional
A character, such as a comma or tab character
Column delimiter in the source file
-<n|N> row_term
Optional
A new line character
Row delimiter in the source file
-<o|O> output_file
Optional
stderr
Name of the file to which to write the information and error messages during load. The specified directory must exist. However, if the file does not exist in the specified directory, it will be created.
-<u|U> login_id
Optional
 
Username to connect to the Relational Engine
-<p|P> password
Optional
 
Password to connect to the Relational Engine
-<c|C> encoding
Optional
The system code page or "ASCII" if the system code page cannot be determined
The valid values for encoding are:
• ASCII
• UTF-8
• UTF-16LE
• UTF-16BE
The encoding parameter is not case sensitive and does not require quotes. See Examples.
Note: If a data file contains a byte order mark (BOM), BDU uses the encoding specified by the BOM. That is, if a data file uses a BOM to indicate an encoding of UTF-8, UTF-16LE, or UTF-16BE, BDU uses that encoding regardless of what value you specify for the encoding parameter on the command line.
If you provide an invalid value for encoding, the message returned is "Invalid value for command line argument 'file_encoding.'"
-<h|H>
Optional
 
Displays the version of BDU and the usage help
Notes
Configuration Settings
You are not required to change any Zen configuration settings to use BDU.
BDU loads data into a table using the accelerated mode. During the load of data, the MicroKernel does not perform transaction logging.
If you use archival logging, back up your data files again.
Error Logging
By default, BDU logs all information and error messages to the standard error stream (stderr). You may specify a log file to which the tool writes the information or error messages.
Two types of errors are not logged: critical and recoverable. With critical errors, BDU exits, since it cannot perform error recovery. For example, a missing delimited data file is a critical error.
With recoverable errors, BDU skips the error and continues processing. The tool keeps a count of such skipped errors and exits when it reaches a user-specified threshold. By default, the threshold is set to zero.
Constraints
The following constraints apply to loading data with BDU.
Constraint
Discussion
Any Referential Integrity (RI) error is considered an RI violation
Row is rejected
Any unique or primary key violations
Row is rejected
No value specified for a non-NULL column1
Row is rejected regardless of column's default value
No value specified for a nullable column1
NULL inserted regardless of column's default value
Table contains CLOB or BLOB columns (relational data types LONGVARCHAR, NLONGVARCHAR, or LONGVARBINARY)
BDU does not attempt to load data into the table and returns the message "The target table contains longvarchar, nlongvarchar, or longvarbinary data types. These data types are not supported."
Order of rows
BDU treats the delimited data file as unordered. The original order of rows may not be preserved.
Date fields
The only supported format is yyyy-mm-dd
Time fields
The only supported format is HH:MM:SS
Time stamp fields
The only supported format is yyyy-mm-dd HH:MM:SS.MS
White space and column delimiters
No white space must exist between the column delimiters and the data values, even if the data values are enclosed in quotes.
1 BDU is not aware of default values for a column defined during table creation or update
Best Practices
If possible, run BDU when the database load is minimal or when no concurrent sessions exist on the table being loaded.
If the table being loaded contains any indexes, drop the indexes before using BDU. Recreate the indexes after the load is complete.
If the table being loaded contains any columns with check constraints, drop the check constraints before using BDU. Respecify the constraints after the load is complete.
Sample Source File
The following content may be used to create a sample delimited text file. You may use the file to verify the usage examples. The examples refer to the sample file as data_file.txt. Note that because the following content is comma-delimited, you must specify the -t parameter (-t ,) with BDU. The -t parameter is required for any delimiter except the tab character.
zenBDUsample_1,12345,zen,101,18446744073709551615
zenBDUsample_2,12346,zen,102,18446744073709551614
zenBDUsample_3,12347,zen,103,18446744073709551613
zenBDUsample_4,12348,zen,104,18446744073709551612
zenBDUsample_5,12349,zen,105,18446744073709551611
zenBDUsample_6,12350,zen,106,18446744073709551610
zenBDUsample_7,12351,zen,107,18446744073709551609
zenBDUsample_8,12352,zen,108,18446744073709551608
zenBDUsample_9,12353,zen,109,18446744073709551607
zenBDUsample10,12354,zen,110,18446744073709551606
Note that in any data file being used as source input, no white space must exist between the column delimiters and the data values, even if the data values are enclosed in quotes.
Examples
The following examples assume that a table named BDU_Table is part of the Demodata sample database. To add such a table to Demodata, use the following query:
CREATE TABLE BDU_Table (Name CHAR(20) NOT NULL CASE, PhoneNo INTEGER,BuildingName CHAR(25) NOT NULL CASE, RoomNo UINT NOT NULL,HeadOfDept UBIGINT NOT NULL)
To run BDU with the default options:
bdu demodata BDU_Table D:\data_file.txt
Note:  The input data must be tab-delimited to use default options. If the input data is not tab-delimited, you must specify the delimiter with the -t parameter. For example, to use the data from these examples, which is comma-delimited, run BDU as follows:
bdu demodata BDU_Table D:\data_file.txt -t ,
============ 
To run BDU for the Billing table in the sample database Demodata and load tab-delimited data from a file that uses UTF-16LE encoding:
bdu demodata Billing D:\billing_data_import.txt -c UTF-16LE
============ 
To run the BDU for a database that requires username and password:
bdu demodata BDU_Table D:\data_file.txt -u <username> -p <password>
============ 
To run the BDU with max errors option:
bdu demodata BDU_Table D:\data_file.txt -e <no of errors user wants to allow>
For instance, for loading to continue until 100 errors have occurred:
bdu demodata BDU_Table D:\data_file.txt -e 100
============ 
To run the BDU with a specific column delimiter option:
bdu demodata BDU_Table D:\data_file.txt -t <column delimiter>
For instance, when the source file contains text in which each row is separated by ,
bdu demodata BDU_Table D:\data_file.txt -t ,
============ 
To run the BDU with a specific row delimiter option:
bdu demodata BDU_Table D:\data_file.txt -n <row delimiter>
For instance, when the source file contains text in which each row is separated by \n:
bdu demodata BDU_Table D:\data_file.txt -n \n
============ 
To run the BDU with a specific start row option:
bdu demodata BDU_Table D:\data_file.txt -f <line no. from which user wants loading to begin>
============ 
To run the BDU with a specific end row option:
bdu demodata BDU_Table D:\data_file.txt -l <line no. at which user wants loading to end>
============ 
You may combine parameters. To load the first 15 rows from the source file containing data that is separated by | and is enclosed in ':
bdu demodata BDU_Table D:\data_file.txt -f 1 -l 15 -t |
bmon
The bmon tool is documented in Advanced Operations Guide. See Command Line Interface Monitor.
btadmin
Description
The btadmin tool is used to create and update the flat file btpasswd, which stores usernames and passwords for authentication of Zen users. Users given administrator rights can monitor engine status and configure the engine remotely.
Synopsis
btadmin [ -p password] [a+] [a-] [-r] username
Options
-p
Specify the password. If this option is not specified, you will be prompted to enter the password.
a+
Gives administrator rights for this user.
a-
Removes administrator rights for this user.
-r
Remove username from btpasswd file.
username
Creates or updates the username in the btpasswd file. If username does not exist in this file, an entry is added. If it does exist, the password is changed.
See Also
Notes
To administer the engine from a remote workstation, you must supply a username and password. Upon initial installation of Zen, the supplied default is admin with an empty password.
Use btadmin to add more administrators:
% btadmin [-p password] [a+] username
This tool creates a record in the file btpasswd for user username with password password (if the option -p is not used, then you are asked to enter a password). If a user already exists, then the password is changed as specified.
By default a user is created without administration permissions. You can use the a+ option to give administration rights to the user. You can remove this right by using a-.
To remove a user record from the password file, enter:
% btadmin -r username
Every time the btpasswd file is changed, the previous version is backed up to btpasswd-.
butil
Description
The Btrieve utility butil is used at a command prompt for manipulation and administration of Btrieve files and their data. You can use butil to perform the following actions:
• Starts and stops continuous operations for use in performing server backups.
• Recovers changes made to a file between the time of the last backup and a system failure.
• Imports and exports ASCII, unformatted, and SDF sequential data.
• Copies data between files.
• Preloads or flushes the file page cache.
• Returns MicroKernel Engine version information.
Continuous operation is a MicroKernel Engine feature that enables you to back up files while they are in use by Zen-based applications. Two maintenance commands, startbu and endbu, begin and end continuous operation on a file or set of files.
Synopsis
butil
-cache <sourceFile | @listFile>
-clone outputFile sourceFile [/O<owner> | /PROMPT] [/pagecompresson | /pagecompressoff] [/recordcompresson | /recordcompressoff] [/UIDuname /PWDpword [/DBdbname]]
-close [sourceFile | @listFile] [/Sserver]
-clrowner sourceFile /O<owner | /PROMPT> [/UIDuname /PWDpword [/DBdbname]]
@commandFile [commandOutputFile]
-copy sourceFile outputFile
[/O< owner1 | /PROMPT> [/O<owner2 | /PROMPT>]] [/UIDuname /PWDpword [/DBdbname]]
-create outputFile descriptionFile [< Y | N >] [/UIDuname /PWDpword [/DBdbname]]
-drop sourceFile < keyNumber | SYSKEY >
[/O<owner> | /PROMPT] [/UIDuname /PWDpword [/DBdbname]]
-endbu < /A | sourceFile | @listFile > [/UIDuname /PWDpword [/DBdbname]]
-index sourceFile indexFile descriptionFile
[ /O<owner | /PROMPT>] [/UIDuname /PWDpword [/DBdbname]]
-load unformattedFile outputFile [/O<owner> | /PROMPT] [/UIDuname /PWDpword [/DBdbname]]
-purge <sourceFile | @listFile>
-RECOVER sourceFile unformattedFile [/O<owner |/PROMPT>] [/UIDuname /PWDpword [/DBdbname]]
-rollfwd <sourceFile | volume | drive | @listFile>
[</L[dumpFile] | /W[dumpFile]> [/T<dataLength>]
[/E<keyLength>] [/H] [/V] [/O<ownerList | owner> | /PROMPT]]
[/A] [/UIDuname /PWDpword [/DBdbname]]
-save sourceFile unformattedFile
[Y indexFile | N <keyNumber | -1>] [/O<owner1 | /PROMPT>
[/O<owner2 | /PROMPT>]] [/UIDuname /PWDpword [/DBdbname]]
-setowner sourceFile /O<owner | /PROMPT> level [/L][/UIDuname /PWDpword [/DBdbname]]
-sindex sourceFile <descriptionFile | SYSKEY> [keyNumber] [/O<owner> | /PROMPT] [/UIDuname /PWDpword [/DBdbname]]
-startbu <sourceFile | @listFile> [/UIDuname /PWDpword [/DBdbname]]
-stat <sourceFile> [/O<owner> | /PROMPT] [/UIDuname /PWDpword [/DBdbname]]
-ver
Note:  On Linux distributions, all slash options use a hyphen instead of a slash. For example, the /O options for butil -copy is -O, as in butil -copy -O. Also, if you specify /PROMPT instead of an owner name, upon execution the command generates an interactive prompt for the owner name.
Options
Maintenance tool command options are not case sensitive unless the option is a file name.
If you run butil without specifying a command option or with an invalid command option, a usage message is printed. The usage message indicates that there is an optional /S command line argument to butil. This argument is ignored on Linux or Raspbian.
When copying a file requires an owner name for both the original file and the copied file, the -copy option specifies both owner names, as shown in this example:
butil -copy originalFile copiedFile /Od3ltagamm@ /OV3rs10nXIII
The first owner name d3ltagamm@ is required to open originalFile. The second owner name V3rs10nXIII is used to create copiedFile.
If the owner names are provided interactively, the command resembles the following example:
butil -copy originalFile copiedFile /PROMPT /PROMPT
Upon execution, the user is first prompted to enter the owner name to access originalFile. Once that file is open, the user is prompted for the owner name to assign to copiedFile.
Butil also offers an option to execute command files.
For a complete discussion of butil commands, options, and examples, see Btrieve Command Line Maintenance Tool (Butil) in Advanced Operations Guide.
See Also
• syslogd in Linux man pages
• Btrieve API Guide, which describes the API for the MicroKernel Engine.
clilcadm
Description
The command line version of the License Administrator tool manages the user count licenses on your engine. The Windows and Linux 32-bit command line tool is clilcadm. The Windows the 64-bit tool is w64clilcadm, and the Linux 64-bit version of this tool is clilcadm64. For backward compatibility on 64-bit systems, use of clilcadm calls clilcadm64.
Note:  On Linux and Raspbian this tool can be run only by user accounts belonging to group zen-data. See Zen Account Management on Linux and Raspbian in Getting Started with Zen.
Synopsis
clilcadm -a <key> | -c [key] [force] | -d <key> | -g <key> <filename> |
-h | -i [key] | -k [key] | -n [key] | -s <servername> | -t | -u <username> | -p <password>
w64clilcadm -a <key> | -c [key] [force] | -d <key> | -g <key> <filename> | -h | -i [key] | -k [key] | -n [key] | -s <servername> | -t | -u <username> | -p <password>
clilcadm64 -a <key> | -c [key] [force] | -d <key> | -g <key> <filename> |
-h | -i [key] | -k [key] | -n [key] | -s <servername> | -t | -u <username> | -p <password>
Options
For a complete discussion of the command line options, see the License Administrator topic CLI Syntax.
See Also
licgetauth
License Administration documents license keys and their associated utilities in detail.
clipaadm
Description
The clipaadm tool allows you to authorize Zen via telephone in the event that it is not possible to authorize keys online, remotely, or offline. The name clipaadm stands for CLI phone authorization administration. Use the steps described here with the version of the tool for your platform:
• clipaadm.exe (Windows 32-bit)
• w64clipaadm.exe (Windows 64-bit)
• clipaadm (Linux and Raspbian)
For Workgroup engine authorization, you must be logged in with administrator rights before opening a command prompt.
Synopsis
You can use clipaadm either without parameters or with parameters entered in two steps.
Without Parameters
You can run clipaadm without parameters in environments that handle stdin. Executed in this way, clipaadm enters interactive mode and displays the steps to authorize the product key.
1. At a command prompt, run clipaadm.
2. When the prompt asks you to enter the product key, enter it and press Enter.
3. When the prompt returns an authorization request code, contact technical support and provide the code to a support representative, who will provide you with an authorization key for the next step.
If your vendor or OEM provided the product key, contact their support services. If Actian Corporation provided your product key, contact Actian support services. If you obtained your product key from Actian, call 1-800-287-4383 (U. S. toll-free) or 00800.1212.3434 (Europe toll-free).
4. When the prompt asks for the authorization key, enter it and press Enter.
5. When the prompt informs you that authorization is successful, you may close the prompt window.
With Parameters in Two Steps
In environments that do not support stdin, such as remote PowerShell sessions, you can perform authorization by using clipaadm with the parameters described in the following two steps:
1. At a command prompt, run clipaadm with the product key string:
clipaadm <product key>
2. When the prompt returns an authorization request code, contact technical support and provide the code to a support representative, who will provide you with an authorization key for the next step.
If Actian Corporation provided your product key, contact Actian support services. If your vendor or OEM provided the product key, contact their support services.
3. At a command prompt, run clipaadm again with the product key followed by the authorization key:
clipaadm <product key> <authorization key>
4. When the prompt informs you that authorization is successful, you may close the prompt window.
See Also
License Administration provides additional detail on the management of license keys.
dbdefrag
The dbdefrag tool is documented in Advanced Operations Guide. See Monitoring Data File Fragmentation.
dbmaint
Description
The dbmaint tool manages named databases.
Note:  This tool can be run only by user accounts belonging to group zen-data. See for information on Zen Linux or Raspbian utilities and user accounts.
Synopsis
dbmaint a | d | l | m [-nDbname][-a][-b][-c][-i][-e][-v][-ldictpath][-ddatapath][-ssecuritymode]
 
Add new database name
a -nDbname [-b] [-i] [-e] [-ldictpath] [-ddatapath]
Delete database name
d -nDbname
List database names
ldictpath [-a]
Modify database security policy
m -nDbname -ssecuritymode
Modify database code page
m -nDbname -c=codepage
Options
Commands
add, a
Add database name
del, d
Delete database name
list, l
List all database names
modify, m
Modify database name, security mode, or code page
Options
-a
Show full details about dbnames in database list when you use the -l option
-b
Create bound database
-c=codepage
Set the database code page. Zero specifies the server default (-c=0).
-ddatapath
Set data path
-e
Do not create dictionary files for database
-h
Show help
-i
Enforce relational integrity on the database
-ldictpath
Set dictionary path
-nDBName
Set database name
-ssecuritymode
Set Btrieve security policy for database. Valid choices are Classic, Mixed, Database.
-v
Create a database using long metadata (V2 metadata)
Examples
To create a database named TEST with relational integrity:
% dbmaint a -i -nTEST
Note:  Unless a data path is specified, the new database will be in the default location, $ACTIANZEN_ROOT/data. Likewise, if a dictionary path is not specified, the dictionary will be created in the default location.
To delete the same database:
% dbmaint d -nTEST
To create a database named mydbase with a database code page of CP932:
% dbmaint a -nmydbase -c=CP932
For the same database, to set the code page to the default operating system code page:
% dbmaint m -nmydbase -c=0
To see a list of valid code pages (specify an invalid code page and dbmaint returns a list of valid ones):
% dbmaint m -nmydbase -c=xzy
Dbmaint returns something similar to the following:
Bad code page "xyz" should be: ASCII, ISO8859_1, CP437, CP1252, UTF-8, CP1250, CP1251, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, CP737, CP775, CP850, CP852, CP855, CP857, CP858, CP862, CP866, CP932, or EUCJP
To list all database names with full information:
% dbmaint l -a
To modify the security policy of the DefaultDB database to Mixed:
% dbmaint m -nDefaultDB -sMixed
See Also
dsnadd, butil(1), btadmin(1), syslogd(1), smb.conf(5)
Database Code Page and Client Encoding in Advanced Operations Guide.
deu
Description
The deu data export utility exports the results of a SQL SELECT statement to a delimited text file.
Note:  This utility is agnostic to the rendering or use of binary data by any application. When it exports binary data, it writes it in binary format, such as 0x123abc.
Synopsis
deu database selectfile resultsfile [options]
[-c ] [-e fileencoding] [-f fielddelimiter] [-h] [-l logfile] [-n portnumber]
[-s servername] [-o] [-u loginid] [-p password]
Options
database
Database against which the SQL statement in selectfile is to be executed. It can be a database name or a server DSN.
selectfile
Text file that contains the SQL statement to run against database. The file is read from the current directory or from a location using a path provided with the file name.
Note: Unicode characters are not supported. If you use Unicode in the SELECT file, deu returns the error message: "Cannot connect to the designated server."
resultsfile
Text file that contains the results of the SQL SELECT command. The file can be overwritten if it exists. By default, the user is prompted to overwrite unless the -o option is used.
-c
Write column names in the first row of output, preceded by a hash character (#). Without this option, the default is no column names.
-d fileencoding
Read the source file in the specified character encoding. Without this option, the default is the current operating system encoding. The code page name is not case sensitive. See Code Pages for Data Source.
-e fileencoding
Write the results file in the specified character encoding. Without this option, the default is Windows-1252. The code page name is not case sensitive. See Code Pages for SELECT Results.
-f fielddelimiter
Field delimiter character for SELECT results. Without this option, the default is a comma.
-h
Show help.
-l logfile
Write log messages to a file as well as standard output. Logfile is the name of the file to which message entries are logged. The file is written to the current directory or to a location using a path provided with the file name.
-n portnumber
TCP port number where the database engine running on servername is listening. Without this option, port 1583 is the default used for the Relational Engine.
-o
Without prompting, overwrite resultsfile if it exists.
-s servername
Name of the server where the database is defined. Without this option, the local machine is the default. You may use an IP address.
-u loginid
Name of a user defined for a database with security enabled.
-p password
Password for the user identified by loginid.
Code Pages for Data Source
The following values represent code pages available to use with the -d option. Without this option, the default is the current operating system encoding. The values are not case sensitive.
• ANSI: CP1250, CP1251, CP1252 (Windows default), CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, CP932, CP936, CP949, CP950
• OEM: CP720, CP737, CP775, CP850, CP852, CP855, CP857, CP858, CP862, CP866, EUCJP
• Unicode: UTF-8, UTF-16LE
Code Pages for SELECT Results
The following values represent code pages available to use with the -e option Without this option, the default is CP1252. The values are not case sensitive.
• ANSI: CP1250, CP1251, CP1252 (Windows default), CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, CP932, CP936, CP949, CP950
• OEM: CP720, CP737, CP775, CP850, CP852, CP855, CP857, CP858, CP862, CP866, EUCJP
• Unicode: UTF-8, UTF-8-BOM, UTF-16BE, UTF-16BE-BOM, UTF-16LE, UTF-16LE-BOM
Other Exported Formats
The following list shows how deu handles the exporting of selected data types:
• BIT – 0 or 1
• BFLOAT4, REAL – Scientific notation, precision 7
• BFLOAT8, DOUBLE, FLOAT – Scientific notation, precision 16
• DATETIME, TIMESTAMP – year-month-day hour:minute:second.nanoseconds
• DATE – year-month-day
• TIME – hour:minute:seconds
• UNIQUEIDENTIFIER – GUID (e.g., 11111111-2222-3333-4444-111111111111)
Examples
The following example is included in the -h help on the deu command line:
deu demodata select.sql datafile.dat -c -l log.txt
In this case, the select.sql and datafile.dat files are expected to reside in the current directory. The following example uses a directory called Data on drive D:
C:\>deu demodata D:\Data\select.sql D:\Data\datafile.dat -c -l D:\Data\log.txt
Deu is designed to accept a SELECT statement in selectfile that results in a single record set. A file that includes more than one SELECT statement, separated by semicolons, returns no error, but deu executes only the first SELECT statement.
In selectfile you can combine multiple SELECT statements using UNION, as shown in the following example:
SELECT * FROM Class WHERE max_size >= 100
UNION
SELECT * FROM Class where max_size <= 25
This query results in one record set.
dsnadd
Description
Dsnadd simplifies the setup of a new ODBC data source to connect to a Zen database. It modifies the odbc.ini file by providing the appropriate properties for the new data source.
Zen follows the UNIXODBC standard by using the odbcinst.ini file in /usr/local/actianzen/etc to specify a 32-bit and a 64-bit ODBC driver. DSNs that reference the Pervasive ODBC Interface driver description point to the odbcinst.ini information from the odbc.ini file. A single DSN can be used by both a 32- and a 64-bit application. See also Notes.
Optionally, dsnadd provides options that let you create legacy-style DSNs that specify a 32-bit driver name in odbc.ini rather than pointing to odbcinst.ini. However, such DSNs are not accessible to 64-bit applications.
Synopsis
• To create a DSN on the server that connects to a named database:
dsnadd -dsn=myDSN -db=DBname
This creates a DSN with the description Pervasive ODBC Interface that can be used by both a 32- and a 64-bit application on the server. The DSN is not visible as an engine DSN in ODBC Administrator running on a Windows client.
• To add a DSN on a client that connects to a named database on a server:
dsnadd -dsn=myDSN -db=DBname -host=zenhost
This creates a DSN with the description Pervasive ODBC Interface that can be used by both a 32-bit application and a 64-bit application on the client.
• To add a deprecated, legacy-style Client DSN with the description Pervasive ODBC Client Interface, execute the following command:
dsnadd -dsn=myDSN -sdsn=engineDSN -host=zenhost -clntdsn
Note that the DSN is accessible only to 32-bit applications.
• To add a deprecated, legacy-style engine DSN on the server with the description Pervasive ODBC Engine Interface:
dsnadd -dsn=myDSN -db=DBname -engdsn
Note that the DSN is accessible only to 32-bit applications.
• To list existing DSNs:
dsnadd -l
Where:
myDSN is a name you want to assign to the new data source.
DBname is the name of the named database on the Zen host.
zenhost is the name of the host where your Zen Enterprise Server or Cloud Server is installed.
engineDSN is the name of the engine DSN on the Zen host.
Options
The following options are the most commonly used:
-db=
Name of the database (local or remote) to which the DSN is associated
-dsn-name= | -dsn=
The data source name
-help
Display syntax and options help for the dsnadd tool
-l
List existing DSNs
openmode=<0|1|-1|-4> | -omode=<-0|1|-1|-4>
Specify the default file open mode for files opened with the current connection. The default is 0, or Normal. Can be used only with local connections, not remote client connections. For more information on file open modes, see DSN Open Mode in ODBC Guide.
-srv-host= | -host=
Server host name
-srv-port= | -port=
Server port number. The default is 1583. (See also Changing the Default Communication Ports in Getting Started with Zen.)
-translate=< none | auto >
Encoding translation to use for character data. The default is none, meaning that no character data is translated between the client and server on the assumption that the client and server use the same operating system encoding.
See Automatic in ODBC Guide.
The following options are used to create deprecated, legacy-style DSNs:
-clntdsn
Create a deprecated, legacy-style Client DSN with the driver description Pervasive ODBC Client Interface.
Rather than using Client DSNs, new applications or revised 32-bit applications should create a DSN that connects to a named database using -db=.
-engdsn
Create a deprecated, legacy-style Engine DSN with the driver description Pervasive ODBC Engine Interface.
Rather than using Engine DSNs, new applications or revised 32-bit applications should create a DSN that connects to a named database using -db=.
-sdsn=
For use with deprecated, legacy-style Client DSNs. Name of an Engine DSN on the server.
The following options are typically used only for application development and testing:
-drv-desc=
dsnadd handles the driver descriptions based on the absence or presence of the -db, -clntdsn and -engdsn options. If specified, must be one of the following:
• Pervasive ODBC Interface
• Pervasive ODBC Client Interface
• Pervasive ODBC Engine Interface
-drv-path= | -drv=
The location of the driver libraries. The default is /usr/local/actianzen/lib:$HOME/lib.
-dsn-desc= | -desc=
dsnadd provides a default DNS description in odbc.ini. If you want to override the default description, use this option to specify a descriptive string of your choosing. If the descriptive string contains the space character, you must quote the entire string with double quotes.
-odbc-ini= | -ini=
ODBC.ini file name (for example, /usr/local/actianzen/etc/odbc.ini)
Examples
The following example creates a server-side DSN named acctingdb that connects to a local database named region1accting.
dsnadd -dsn=acctingdb -db=region1accting
The following example creates a client-side DSN named USInvoices that connects to a database named DomesticOrders on a remote server named USInventory:
dsnadd -dsn=USInvoices -db=DomesticOrders -host=USInventory
The following example creates a deprecated, legacy-style Client DSN named bkorderclnt that references an engine DSN named backordersrv on a machine named JapanSvr2 and uses automatic encoding.
dsnadd -dsn=bkorderclnt -sdsn=backordersrv -host=JapanSvr2 -translate=auto -clntdsn
The following example creates a deprecated, legacy-style engine DSN named partsctlg that connects to a database named partscatalog.
dsnadd -dsn=partsctlg -db=partscatalog -engdsn
Notes
On Linux distributions, individual ODBC drivers are loaded through the driver manager UNIXODBC. The driver manager maintains a mapping from data source names (DSNs) to the specific Zen ODBC drivers.
The installation of Zen Enterprise Server or Cloud Server 64-bit or Client 64-bit leaves user-defined, preexisting 32-bit DSNs as is, meaning they are not immediately accessible from a 64-bit application. For new DSNs, the installation of both products assigns a 32-bit and a 64-bit ODBC driver in odbcinst.ini. This assignment allows a single DSN to be used by both a 32- and a 64-bit application.
If you want preexisting 32-bit DSNs to be accessible to both 32- and 64-bit applications, you must recreate them as DSNs that connect to a named database.
ODBC and Data Source Names (DSNs)
The application bitness does not have to match the bitness of the Zen product. For example, the 64-bit ODBC driver or the 32-bit ODBC driver can be used to connect to either a 64-or 32-bit Zen server.
For client installations, however, the application bitness does have to match that of Zen Client on the client machine. If you want to use a 64-bit application on the client, the 64-bit Zen Client must be installed.
Zen ODBC Driver Descriptions for Linux or Raspbian
Zen allows DSNs to specify three different ODBC driver descriptions, as explained in the following table.
ODBC Driver Description in INI Files
Driver Library Installed With
Behavior for All Products Installed With
Pervasive ODBC Engine Interface
Server 64-bit
Server 32-bit (Linux only)
• Installation assigns an ODBC driver in odbc.ini for compatibility with preexisting Engine DSNs
• Connects to a local named database
• No longer created by default with dsnadd (the -engdsn option must be specified)
• Visible when viewing Engine DSNs in ODBC Administrator running on a Windows client
• For use by 32-bit applications that are already coded to use Engine DSNs
• 32-bit Engine DSNs are deprecated on Linux.
Pervasive ODBC Client Interface
Server 64-bit
Server 32-bit (Linux only)
Client 32-bit (Linux only)
• Installation assigns an ODBC driver in odbc.ini for compatibility with preexisting Client DSNs
• Connects to a local or remote named database or an Engine DSN
• For use only by 32-bit applications that are already coded to use Client DSNs
• No longer created by default when -host is specified with dsnadd (the -clntdsn option must be specified)
• 32-bit Client DSNs are deprecated on Linux.
Pervasive ODBC Interface
Server 64-bit
Client 64-bit
• Installation assigns ODBC drivers in odbcinst.ini for use by new 32-bit and 64-bit DSNs
• Connects to a local or remote named database
• The recommended driver description to use for 32-bit and 64-bit applications
• Created by default with dsnadd
• Not visible as Engine DSNs in ODBC Administrator running on a Windows client.
Frequently Asked Questions About ODBC and DSN Support for Linux or Raspbian
The following table answers some frequently asked questions about ODBC and DSN support for Linux or Raspbian.
Question
Answer
What do I need to do about DSNs if I port my 32-bit application to 64-bit?
If the application uses DSN-less connections that connect using Pervasive ODBC Client Interface, change the ODBC driver description to Pervasive ODBC Interface.
If the application uses DSNs, you must create new DSNs that connect to a named database.
What is a DSN-less connection?
A DSN-less connection is one that connects to a named database using the ODBC driver Pervasive ODBC Client Interface (for preexisting 32-bit applications) or the Pervasive ODBC Interface driver (for 32-bit or 64-bit applications).
Can I still create deprecated, legacy-style Engine DSNs and Client DSNs?
Yes, but you must specify the -engdsn or -clntdsn option with dsnadd. DSNs created with either option support only 32-bit applications.
If I am using ODBC Administrator on a Windows client, why do I not see my DSNs?
On 64-bit Windows operating systems, 64-bit system DSNs are distinct from 32-bit system DSNs because of the registry design. If you are using the 64-bit ODBC Administrator, you will not see the 32-bit system DSNs, and vice versa.
What if my application uses DTI to manage DSNs?
The DTI functions for DSNs manage only 32-bit Engine DSNs. Therefore, the DTI functions for DSNs are deprecated along with the 32-bit Engine Interface ODBC driver.
An alternative to using DTI to manage DSNs is to use SQL and ODBC statements. For example, you could use CREATE DATABASE to create a named database and SQLConfigDatasource to configure the DSNs.
Going forward, is there a recommended strategy for ODBC connections?
Yes. New applications or revised 32-bit applications, local or remote, should connect to a named database.
ODBC Header Files
The sql.h, sqltypes.h, and sqlext.h header files for ODBC contain differences for the compilation of 32-bit and 64-bit applications. Refer to the ODBC documentation on the UNIXODBC website for a discussion of 64-bit ODBC. For example, you may find the following information useful: http://www.unixodbc.org/doc/ODBC64.html.
See Also
btadmin, dbmaint, isql
easysync
Description
Easysync is a data synchronization utility that enables you to for automating the replication of newly created or updated records from one Zen database to another. The two databases can be on different servers or on the same one. Frequency of syncing can be near real-time or on a longer schedule. It includes a logging feature to enable general monitoring, detection of errors, and troubleshooting of unexpected results. When using easysync, keep in mind the following things:
• Files to be synchronized must use the 13.0 or 16.0 format.
• The files must have system data v2 enabled.
• Both source and destination files must have a user-defined unique key.
• A logged error entry identifies the source or destination file, Btrieve error, and the update sysdata2 time stamp of the failed record in the source file when applicable.
• Only insert and update operations can be synchronized. Delete operations are not tracked.
• Easysync makes no second attempts after failed synchronization of insert or update records.
• Easysync does not attempt to synchronize additional changes in a file once an error occurs. It stores the time value of the last successfully synchronized record and attempts to synchronize from that point the next time that easysync runs the configuration file.
• Easysync relies on a unique user-defined key to perform synchronization of updates. We recommend as a best practice that this key be not modifiable to avoid conflicts in updating the records, but this is not required. If the unique key of a record is modified, the outcome is typically an additional record at the destination with the new unique key, along with the record with the original key.
• Another good practice involves the scenario where multiple clients synchronize changes to a single source. You can avoid key collisions by using segmented keys where one of the segments is a unique identifier to that client, such as the device name. The other segments can use autoincrement/identity segments where they are unique in combination with the device/client name segment.
Synopsis
easysync [-e] [-o] config_file
easysync [-s]
easysync [-h]
Options
Parameter
Optional?
Description
config_file
No
Path name of the JSON configuration file to be executed.
-e
Yes
Encrypt owner names, usernames, and passwords in the configuration file.
-o
Yes
Run the configuration file only once instead of repeating until canceled.
-s
Yes
Print a sample configuration file with usage information.
-h
Yes
Command line help.
Configuration File
The configuration file is in JSON format. It consists of a version number, settings, and list of data files to synchronize. You can omit elements not used, such as source and destination owner name and password. Any omitted element that is required uses the default value shown in the table found after the following template sample.
The following template configuration file can be copied to create a new configuration file. This example has entries for two source files and their destinations.
{
"version": 1,
"settings": {
"log_file": "c:/path_to_logfile/easysync.log",
"log_level": "verbose",
"polling_interval_sec": 10,
"resume_on_error": true
},
"files": [{
"source_file": "btrv://server1/easysync?dbfile=src1.mkd",
"source_owner_name": "",
"source_username": "",
"source_password": "",
"destination_file": "btrv://server2/easysync?dbfile=des1.mkd",
"destination_owner_name": "",
"destination_username": "",
"destination_password": "",
"unique_key": 0,
"create_destination": true,
"_last_copied_record_timestamp": "0000000000000000",
"_last_existing_transaction_time": "0000000000000000",
"_last_file_timestamp": "0000000000000000"
}, {
"source_file": "btrv://server1/easysync?dbfile=src2.mkd",
"source_owner_name": "",
"source_username": "",
"source_password": "",
"destination_file": "btrv://server2/easysync?dbfile=des2.mkd",
"destination_owner_name": "",
"destination_username": "",
"destination_password": "",
"unique_key": 0,
"create_destination": true,
"_last_copied_record_timestamp": "08DC6AB81253D4D6",
"_last_existing_transaction_time": "0000000000000000",
"_last_file_timestamp": "08DC6AB81253D4D6"
}]
}
The following table lists the elements in the configuration file, their default value if any, and a description. Element names are case-sensitive.
Element
Default
Description
version
1
For future backward compatibility
polling_interval_sec
30
Frequency of checking a file for new data, in seconds
log_file
./easysync.log
Path and file name of log file
resume_on_error
true
Determines whether to continue synchronizing files after an error
source_file
—
Required. Source file absolute path or BTRV URI
source_owner_name
—
Owner name, if used
source_username
—
Username, if used
source_password
—
Password, if username is used
destination_file
—
Required. Destination file absolute path or BTRV URI
destination_owner_name
—
Owner name, if used
destination_username
—
Username, if used
destination_password
—
Password, if username is used
unique_key
—
Required. Unique key number existing in both source and destination files to use to find the destination file record to update based on a source file update
create_destination
false
If true, creates file if it does not exist
_last_copied_record_timestamp
0
Maintained by easysync. Time stamp of the last record copied from the source file, based on the update sysdata2 time stamp. Can be manually set to initiate synchronizing at a chosen time. If not specified, a zero time stamp is assumed, and every record in the source file is copied to the destination file.
_last_existing_transaction_time
—
Maintained by easysync. A time value to help determine whether an older existing transaction is causing failed synchronizations
_last_file_timestamp
—
Maintained by easysync. A time value to help determine whether new data exists in a file but synchronization is failing.
isql
Description
You can use the an interactive ODBC test tool isql to test your DSNs for their connectivity to databases and to execute SQL statements once you are connected to a database. The 32-bit tool is installed with Zen Enterprise Server 32-bit, Zen Client 32-bit, and Zen Enterprise Server 64-bit. The 64-bit tool is named isql64 and is installed with both Enterprise Server 64-bit and Client 64-bit.
The only difference between the two utilities is the type of DSN to which they can connect. By default, dsnadd creates DSNs that are accessible to both 32-bit and 64-bit applications (the DSNs specify the driver description Pervasive ODBC Interface). You can test connectivity of such DSNs with isql or isql64. See Zen ODBC Driver Descriptions for Linux or Raspbian.
Deprecated, legacy-style DSNs are accessible only to 32-bit applications. Therefore, you can test connectivity of such DSNs only with isql. See Frequently Asked Questions About ODBC and DSN Support for Linux or Raspbian.
For example, to connect to the Demodata sample database included with Zen, run isql (or isql64) with the DSN as the first parameter: isql demodata or isql64 demodata. The DSN for Demodata specifies the driver description Pervasive ODBC Interface, so either version of the tool can test its DSN connectivity.
The tool puts you in an interactive state with the database. From that state, you can query the database (such as SELECT * FROM Department).
To enable security on a database using isql, first connect to the database as the Master user, then use the SET SECURITY statement in SQL to set the Master user password. For example:
isql demodata Master
SET SECURITY = password
See SET SECURITY in SQL Engine Reference.
To connect to a secured database, pass the username and password as the second and third parameters respectively to isql. For example, to connect to demodata as user Master using password vforge, enter isql64 demodata Master vforge or isql demodata Master vforge.
Synopsis
<isql | isql64> DSN [UID [PWD]] [options]
Where:
• DSN is the data source name for the database to which you want to connect. Always required.
• UID is the username to connect to the Zen SQL database engine for a secured database. Required only for a secured database.
• PWD is the password for UID. Required only if UID used.
• options is one or more of the options as defined below.
Options
-b
Suppress prompts for batch processing. See Notes.
-c
Display column names on first row (use with -d)
-dx
Delimit columns with character x.
-llocnname
Set locale to locname.
-mn
Limit column display width to n characters.
-v
Display verbose explanations for errors and warnings.
--version
Display version of unixODBC in use.
-w
Wrap results in an HTML table.
-x0xHH
Delimit columns with HH, where x is in hex. For example, 0x09 is the tab character.
Commands
Once you are in interactive mode, the following commands may be used.
sql-statement
A valid SQL statement to execute against the database to which isql or isql64 is connected.
help [tablename]
Display column information. The output is the same as for the dbo.fSQLColumns catalog function. See dbo.fSQLColumns in SQL Engine Reference.
If tablename is omitted, the output is for all tables in the database, including system tables.
quit
Exits interactive mode.
Notes
By default, isql and isql64 display prompt information when in interactive mode (such as Connected!, sql-statement, help [tablename], and quit). For redirection and piping of output to a file, you may not want the prompt information. The -b option suppresses the output of the prompt information.
Isql and isql64 support redirection and piping for input and output. In addition, both utilities can process a file containing multiple SQL statements. Each statement must end with a carriage return/line feed. The last line of the file must be a blank line. See Examples.
Examples
The following example connects to an unsecured database named acctspay that will be accessed by a 64-bit ODBC application running on a 64-bit client:
isql64 acctspay
The DSN is also named acctspay and specifies the ODBC driver description Pervasive ODBC Interface.
The following example connects to a secured database named payroll as user Master with password j77b99:
isql payrollsecdb Master j77b99
The DSN is named "payrollsecdb" and specifies the deprecated, legacy-style ODBC driver description Pervasive ODBC Engine Interface. You could also use isql to test the DSN if the DSN had specified the ODBC driver description Pervasive ODBC Interface.
The following example shows how to process multiple SQL statements. Suppose that you want to run the following two queries against the Demodata sample database:
select count(*) from billing
select count(*) from person
Create a file (named two-queries.sql for discussion purposes) with the two lines. Include a blank line as the last line in the file.
Run the following command:
cat two-queries.sql | isql demodata -b
The result is as follows:
+------------+
| EXPR_1 |
+------------+
| 1315 |
+------------+
SQLRowCount returns 1
1 rows fetched
+------------+
| EXPR_1 |
+------------+
| 1500 |
+------------+
SQLRowCount returns 1
1 rows fetched
Note the use of the -b option to suppress the prompting information from the output. Without the -b option, the result is as follows:
+---------------------------------------+
| Connected! |
| |
| sql-statement |
| help [tablename] |
| quit |
| |
+---------------------------------------+
SQL> +------------+
| EXPR_1 |
+------------+
| 1315 |
+------------+
SQLRowCount returns 1
1 rows fetched
SQL> +------------+
| EXPR_1 |
+------------+
| 1500 |
+------------+
SQLRowCount returns 1
1 rows fetched
See Also
dsnadd
licgetauth
Description
The licgetauth tool is used in the second phase of the offline authorization process used for authorizing product keys. This tool is used in conjunction with clilcadm to complete the offline authorization process.
Synopsis
licgetauth.exe [output_filename.ath]
Options
output_filename.ath
The name for the authorization output file.
See Also
clilcadm
Offline Authorization Without Internet Access
psc
Description
Psc is a tool to retrieve and set control information for the Actian Zen Enterprise Server service.
You must have administrator authority to run psc.
Synopsis
psc < start | stop | restart | query | getpolicy > servicename
or
psc setpolicy servicename < automatic | manual | disabled >
Options
A service specifies the name of a program, routine, or process that performs a specific system function to support other programs, particularly at a low level (close to the hardware). Servicename is the name given to the service key in the registry. Note that service key name may differ – and in most cases does differ – from the service display name.
The options described below are case-insensitive.
start
Starts a Zen service
stop
Terminates the running of a Zen service
restart
Terminates the running of a Zen service then starts the service running again
query
Specifies whether servicename is running or not
getpolicy
Retrieves the type of startmode (automatic, manual, or disabled) associated with servicename
setpolicy
Sets the type of startmode (automatic, manual, or disabled) associated with servicename
automatic
The service starts automatically when the operating system starts
manual
The service must be started manually after the operating system starts
disabled
The service is disabled and does not start after the operating system starts
Examples
The following example is the same for all installations of Zen database products as a service. In past releases, the Enterprise Server, Cloud Server, Workgroup, Client, and Reporting services had different short names, but beginning in v14 they all use "zenengine."
psc start zenengine
The zenengine service name can be with start, stop, and restart.
Return Codes
The psc tool returns the following codes (DOS ERRORLEVEL) for the state of the service after the command has been run.
String
Value
BTI_SERVICE_ACCESS_DENIED
32775
BTI_SERVICE_ALREADY_RUNNING
32778
BTI_SERVICE_CANNOT_ACCEPT_CTRL
32779
BTI_SERVICE_CONTINUE_PENDING
32772
BTI_SERVICE_DATABASE_LOCKED
32780
BTI_SERVICE_DEPENDENCY_DELETED
32783
BTI_SERVICE_DEPENDENCY_FAIL
32784
BTI_SERVICE_DISABLED
32782
BTI_SERVICE_DOES_NOT_EXIST
32785
BTI_SERVICE_DUP_NAME
32776
BTI_SERVICE_EXISTS
32786
BTI_SERVICE_INVALID_CTRL
32789
BTI_SERVICE_INVALID_NAME
32777
BTI_SERVICE_MARKED_FOR_DELELE
32790
BTI_SERVICE_NOT_ACTIVE
32787
BTI_SERVICE_PAUSE_PENDING
32773
BTI_SERVICE_PAUSED
32774
BTI_SERVICE_REQUEST_TIMEOUT
32788
BTI_SERVICE_RUNNING
32771
BTI_SERVICE_START_PENDING
32769
BTI_SERVICE_STOP_PENDING
32770
BTI_SERVICE_STOPPED
32768
psregedit
Description
Psregedit is used to manage the Zen Registry on Linux. You must be root user or a member of the group zen-data to make changes to the Zen Registry.
Synopsis
psregedit
-key keyname [ -r ]
-key keyname -value valuename
-set -key keyname [-type type] value
-set -key keyname -value valuename [-type type] value
-delete -key keyname
-delete -key keyname -value valuename
-export -key keyname [-file filename]
-import [-file filename]
Where:
• keyname is in the form PS_HKEY\Subkey and PS_HKEY is one of the following: PS_HKEY_CONFIG, PS_HKEY_CONFIG_64, PS_HKEY_CLASSES, PS_HKEY_CLASSES_64, or PS_HKEY_USER. Subkey is a subordinate key under a major key.
• valuename is the name assigned to the Registry value or default.
• type is PS_REG_STR, or PS_REG_UINT32, or PS_REG_UINT64.
• value is the value assigned to valuename.
• filename is the name of a file, which may include a path.
Options
-key
Get the key value. If -value is not specified, then the entire key contents are displayed. To view all subkeys, specify -r (for recursive).
-set -key
Set the key value. If -value is not specified, the default value will be set. VALUE must be appropriate to the TYPE specified. PS_REG_STR is assumed if -type is not specified.
-delete -key
Delete the specified key or value. If -value is not specified, then the entire key and all subkeys are deleted.
-export -key
Export the given key, including all values and subkeys to standard output or to the named file.
-import [-file filename]
Import keys and values from either the standard input or from the named file.
Examples
Entering a key name value on Linux:
psregedit -set -key PS_HKEY_CONFIG\SOFTWARE\Actian\Zen\ELS -value proxy_host ‑type PS_REG_STR "192.168.220.128"
It is possible to import an .xml file containing this same value:
psregedit -import -file ELSProxy.xml
where ELSProxy.xml contains the following:
<?xml version="1.0" encoding="UTF-8" ?>
<key name="PS_HKEY_CONFIG\SOFTWARE\Actian\Zen\ELS">
<value name="proxy_host" type="PS_REG_STR">192.168.220.128</value>
</key>
psregsvr
Description
psregsvr is used to register components in the Zen registry on Linux systems.
Synopsis
psregsvr [ -s ] [ -u ] { [ -f file ] | filename }
Options
-s
Silent. Do not print any status or error messages.
-u
Unregister. If not specified, register is assumed.
-f file
Specifies a text file with PCOM modules listed one per line.
filename
Specifies a single PCOM module to register.
pvdbpass
Description
The pvdbpass tool allows users to change their passwords for secure databases without administrator intervention.
Synopsis
The tool will prompt for the passwords with this syntax
pvdbpass database username [-server name] [-port number]
This syntax includes the old and new passwords.
pvdbpass database username password newpassword
[-server name] [-port number]
Options
database
Database in which the username is defined (this can be a database name or a server DSN)
username
The user whose password will be changed.
password
The current password for the user. You must provide the original password in order to modify it. You can either provide the password as a parameter or omit it and be prompted.
newpassword
The new password for the user. See Identifier Restrictions in Advanced Operations Guide for password restrictions.
Note: If the new password begins with a nonalphabetic character, the password must be enclosed in single quotes. If the existing password begins with a non-alphabetic character, do not enclose it in single quotes (see examples).
-server name
Optional. Server name on which the database is defined. If you do not specify this option, the local machine is assumed
-port number
Optional. TCP port on which the SQL engine running on servername is listening. If you do not specify this option, the default port 1583 is assumed. See also Changing the Default Communication Ports in Getting Started with Zen.
Examples
To change the Master user password and be prompted:
pvdbpass demodata Master
To change an existing password to one that does not start with an alphabetic character (use single quotes):
pvdbpass demodata Joe oldpassword '123'
To change a password on a remote server:
pvdbpass demodata Joe oldpass newpass -server finance1
pvddl
Description
pvddl is used to execute a series of SQL statements in a command file.
Synopsis
pvddl database commandfile
[-separator character] [-username username] [-password password] [-server servername] [-port number] [-stoponfail] [-log logfile]
Options
database
Database against which the SQL statements in commandfile are to be executed. This can be a database name or a server DSN.
commandfile
Text file that contains the SQL statements. Certain categories of SQL statements, such as data definition language, are better suited for use in the command file. Contrast this with a data manipulation statement such as SELECT. A SELECT statement can be used, but the result set is not returned to standard output.
You need a separator character between each command in your command file. See -separator character.
Note: Pvddl does not support Unicode characters. If you use Unicode in the command file, pvddl returns the error message: "Cannot connect to the designated server."
-separator character
Character used in commandfile to separate SQL statements. The valid choices are any printable character. However, ensure that character does not occur within any of the SQL statements. Common character choices include the pound sign (#), semicolon (;), and at sign (@).
Note: On Linux, a semicolon separator must be enclosed in single quotation marks. If not, then only the first pvddl statement in commandfile runs successfully. The rest of the statements appear to run without error but are unsuccessful.
-username username
Name of a user defined for a database with security enabled.
-password password
Password for the user identified by username
-server servername
Name of the server on which the database is defined. If you do not specify this option, the local machine is assumed. You may also specify the IP address of the server.
-port number
TCP port number on which the database engine running on servername is listening. If you do not specify this option, the default port 1583 is assumed. (Port 1583 is the default port used for the Relational Engine.)
-stoponfail
Stop when the first SQL error is encountered in commandfile. Pvddl returns an error code of PS_E_FAIL if an error is encountered (which equates to -2147467259 decimal). The default action is for pvddl to continue after a SQL error is encountered.
-log logfile
Write output to a file instead of to standard output (stdout). Logfile specifies the name of the file to which output is logged and, optionally, a path to the file. If path is omitted, logfile is created in the same directory in which dvddl resides.
See Also
SQL Engine Reference for more information about supported SQL syntax.
pvnetpass
Description
Pvnetpass is the Zen network password tool. It is a command line tool used to manage the user IDs and passwords for servers to which your client connects. When trying to connect to a server, the client looks up the server name in the registry and uses the username and password set for that server.
If your application uses the MicroKernel Engine and connects to a Linux or Raspbian database engine that is configured to use BTPASSWD or PAM authentication, the application requires a set of credentials to connect to the database engine. Use pvnetpass to configure the sets of credentials that the application will use. Pvnetpass must be run on every machine that connects to the database engine, whether the database engine is local or remote. For more information, see Authentication in Getting Started with Zen.
If you have a global and a user entry for the same server, the user entry overrides the global. The username should include the full user context. For example, in a Windows environment with domain names, specify the user as domain\user. For a Linux or Raspbian environment, use the user account name and the full machine DNS name, such as mymachine.mydomain.
The pvnetpass tool can also be used by Windows clients to change their stored credentials that were saved when using the security login dialog. See also Allow Client-Stored Credentials and Prompt for Client Credentials, both in Advanced Operations Guide.
Synopsis
pvnetpass [-g] {-a | -r | -m} server [-u user] [-p pwd]
pvnetpass -d
Options
-a
Adds a server entry for a user specified by the -u parameter. If no user is specified, current user is assumed.
-d
Displays the list of configured servers. The configured servers will display in two groups that are separated by a dashed line. The ones above the line are global entries and are only viewable by administrators who are a member of group zen-data. The ones below the line are the current user's entries. If you have a global and a user entry for the same server, the user's entry overrides the global.
-g
Manipulates default settings for all users. Settings created with -g can be overridden by individual users.
-m
Modifies a server entry for a user specified by the -u parameter. If no user is specified, current user is assumed.
-p
Specifies the password for the user. If not provided, pvnetpass prompts for a password.
-r
Removes a server entry for a user specified by the -u parameter. If no user is specified, current user is assumed.
server
Server, local or remote, to which you want to add a connection entry. Server can be '*' (include the single quotes) to set the default server entry information. This default entry is used when there is no user entry for the server.
-u
Specifies the name of the user. If -u is not specified, your current username will be used.
See Also
Setting Up Client Access from a Windows Client
Examples
From current user to all servers (overrides -g)
pvnetpass -a '*' -p password
From current user to one server 'myserver' (overrides -g)
pvnetpass -a myserver -p password
From all users (-g) to one server 'myserver' using credentials joe:password
pvnetpass -g -a myserver -u joe -p password
From all users (-g) to all servers ('*'), use default credentials joe:password
pvnetpass -g -a '*' -u joe -p password
To add user 'acctadmin' with password '88sJkE5' to the local server named 'sles2HR':
pvnetpass -a sles2HR -u acctadmin -p p88sJkE5
To add user 'bholly' with password 'peggysue' to a remote server named 'myserver':
pvnetpass -a myserver -u bholly -p peggysue
To verify your entry was accepted, use the -d option:
pvnetpass -d
This command results in:
Server: myserver
User: bholly
Password: (not displayed)
To change the password with which you will connect to 'myserver' from your LinuxLinux client:
pvnetpass -m myserver -u bholly -p newpassword
To remove the entry for server 'myserver':
pvnetpass -r myserver
To add the default entry for users trying to connect to server ‘myserver’ when no user-specific entry exists:
pvnetpass -g -a myserver -u admin -p adminpassword
To add the default server entry in the user context (PS_HKEY_USER):
pvnetpass -a '*' -u admin -p adminpassword
To add the default server entry in the machine context (PS_HKEY_CONFIG):
pvnetpass -g -a '*' -u admin -p adminpassword
To authenticate from a Linux client to a Windows domain server (myserver) with a domain named mydomain and a usernamed user1:
pvnetpass -a myserver -u mydomain\user1 -p user1password
rbldcli
Description
The rbldcli tool is used to reconstruct MicroKernel data files on your server.
Synopsis
rbldcli [ -parameter ] file
rbldcli @command-file
Options
For a complete discussion of rebuild, see its Command Syntax in Advanced Operations Guide.
The Zen v16 release includes a standalone version of rbldcli, called rbldcli_offline. You can use this utility to convert Zen data files on systems where Zen is not installed. Rebuilding a large number of files, or very large files, can slow Zen database engine performance for other users. Rebuilding the files on another system avoids this problem.
See Also
Advanced Operations Guide for more information about rebuilding data files.
 
Last modified date: 11/04/2024