General Reference > Getting Started Guide > Using Zen on Linux, macOS, and Raspbian
Using Zen on Linux, macOS, and Raspbian
The following topics are for Zen users on the supported Unix-based platforms:
Finding What You Need
Accessing the User Documentation
Man Pages
The man pages are installed with Zen Enterprise Server, Cloud Server, and Client. See the directory $ACTIANZEN_ROOT/man/man1for the man pages available.
To make these man pages easily accessible, add $ACTIANZEN_ROOT/man to your MANPATH environment variable. If you need more detailed information on a utility or application, see Command Line Interface Utilities Zen User’s Guide.
Note:  Check the man pages for the most current information. Every effort is made to ensure that the information in this guide matches that in the man pages. On occasion, last-minute changes may be included in the man pages after this guide has been published.
Zen Account Management on Linux, macOS, and Raspbian
The following topics provide information on Linux, macOS, and Raspbian user accounts with respect to operation of Zen. Use of the .bash shell is assumed, but similar instructions should apply to other shells.
After Installation Behavior
User zen-svc has no password and can be accessed only through the root account using su.
You can access the .bash_profile for user zen-svc with ~zen-svc/.bash_profile.
All Zen files have user:group ownership zen-svc:zen-data
You must be logged in as root to run the start and stop scripts for the Zen engines.
You can run utilities on other user accounts if you add needed environment variables to the user .bash_profile or system /etc/profile. See Using Utilities from Users Other Than zen-svc.
In addition to the instructions under Using Utilities from Users Other Than zen-svc, users other than root must be a member of the group zen-data to perform functionality with the following utilities:
Zen Control Center (ZenCC) to administer the local server.
License Administrator utility (clilcadm) for functions other than displaying current licenses.
Named Database Maintenance utility (dbmaint) for functions other than displaying current databases.
Zen Service Registry Editor (psregedit) for functions other than displaying the registry.
Command line configuration (bcfg).
The User Environment
The single environment variable $ACTIANZEN_ROOT is used to determine the location of installed components.
The generic location for configuration files are $ACTIANZEN_ROOT/etc.
For executable files, the location is $ACTIANZEN_ROOT/bin.
For shared libraries (32-bit) the location is $ACTIANZEN_ROOT/lib; for shared libraries (64-bit) the location is $ACTIANZEN_ROOT/lib64.
We recommend that you add $ACTIANZEN_ROOT/bin to your Path environment variable.
As described in the next topic, add $ACTIANZEN_ROOT/lib64 to LD_LIBRARY_PATH on Linux and Raspbian and to DYLD_LIBRARY_PATH on macOS.
If you are using the 32-bit Client Access package, you also must add $ACTIANZEN_ROOT/lib to LD_LIBRARY_PATH. This 32-bit package is not supported on macOS.
Using Utilities from Users Other Than zen-svc
To use utilities from user accounts other than zen-svc, you must first make modifications to the user account configuration. Copy the lines from the following example to either the profile for a specific user or to the /etc profile that all users inherit.
/home/username/.bash_profile
/Users/username/.bash_profile
Profile for the user. Similar to /etc/profile but only for the current user.
Look for this file in /home/username on Linux and Raspbian or in /Users/username on macOS.
/etc/profile
Default profile for all user accounts on the system. Use this profile to grant access to Zen utilities to all user accounts.
Changing this profile according to the example given does not grant administrative privileges or access to Zen data.
Examples of a Modified Profile
Be sure to export all variables specific to Zen.
Linux and Raspbian
ACTIANZEN_ROOT=/usr/local/actianzen
PATH=$PATH:$ACTIANZEN_ROOT/bin:/bin:/usr/bin
LD_LIBRARY_PATH=$ACTIANZEN_ROOT/lib64:$ACTIANZEN_ROOT/lib:$ACTIANZEN_ROOT/bin:/usr/lib
MANPATH=$MANPATH:$ACTIANZEN_ROOT/man
macOS
ACTIANZEN_ROOT=/usr/local/actianzen
PATH=$PATH:$ACTIANZEN_ROOT/bin:/bin:/usr/bin
DYLD_LIBRARY_PATH=$ACTIANZEN_ROOT/lib64:$ACTIANZEN_ROOT/lib:$ACTIANZEN_ROOT/bin:/usr/lib
MANPATH=$MANPATH:$ACTIANZEN_ROOT/man
Configuration
Generally, the default configuration settings for Zen servers and clients are sufficient. You typically do not have to configure any settings for the database engine and clients to communication and function together correctly. This topic discusses two settings that you may want or need to configure:
If you want to explore all of the configuration settings, see Configuration Reference in Advanced Operations Guide:
Samba Configuration File
A Zen server defines the path to the Samba configuration file (smb.conf), which is parsed on engine startup to determine mapping between share names and server directory locations. See Configuration File (Linux, macOS, and Raspbian Engines Only) in Advanced Operations Guide.
Authentication
This setting offers several options for the type of authentication to use for access to the server engine:
Emulate Workgroup Engine. Use this value when Samba is used to authenticate user access on the system.
Proprietary Authentication (using btpasswd). Use this value when not using Samba and the user does not have an account on the server. This allows a separate password file to be maintained when connecting to the Linux, macOS, or Raspbian system.
If you are using BTPASSWD or PAM authentication on your Linux, macOS, or Raspbian server, user names and passwords must be set up using the pvnetpass utility on the clients connecting to this server. For more information about pvnetpass, see the Zen User’s Guide.
Standard Linux Authentication. Use this value when Samba is not used, but users have accounts on the Linux, macOS, or Raspbian system.
Supported Path Formats for Samba
Windows Client
From a Zen client on Windows, the order of path parsing is as follows:
\\server\share\relative\path
Share denotes a valid Samba share, made accessible to a Windows client.
Server reads smb.conf to determine the absolute path to the shared directory, then combines it with the relative path to get a full path. The location of smb.conf is essential for valid resolution of the file path supplied in this format on the client. If the relative path is not correct, status code 12 is returned.
Drive:\path
Drive must be a Samba drive mapped on the Windows client, from which the Zen client determines the server where the Btrieve file resides.
Linux, macOS, or Raspbian Client
From a Zen client on a Linux, macOS, or Raspbian, the order of path parsing is as follows:
//server/share/relative/path
Share denotes a valid Samba share name on the server.
On systems that use a third-party Samba package, server reads smb.conf to determine the absolute path to the shared directory, then combines it with the relative path to get a full path. The location of smb.conf is essential for valid resolution of the file path supplied in this format on the client.
On macOS systems that use native SMB file sharing instead of smb.conf, server resolves sharing information directly from the operating system.
In all cases, if the relative path is not correct, an error status is returned.
/Mount/path
Mount must be a Samba drive mounted on the Linux, macOS, or Raspbian client, from which the Zen client determines the server where the Btrieve file resides.
Note:  Share names for clients for a Linux-based server are case-sensitive. If the share name on the server and the client do not match exactly, they cannot communicate.
On Linux, macOS, and Raspbian servers, if the Zen engine cannot find either smb.conf or a share name, it assumes a default of \\server\absolute\path format. If the absolute path is not correct, status 12 is returned.
Client Information
Zen Client on Linux, macOS, or Raspbian can connect to any of the Zen Servers, provided that the client and server machines communicate with a shared protocol.
Authentication to Remote Machines
To connect to a remote machine using the Linux, macOS, or Raspbian client, you must be able to authenticate to the remote machines. This is accomplished by using the pvnetpass utility to send a user name and password to the server. This utility stores the user name and password in an encrypted format for that particular server in the Zen registry on the client machine. If you do not specify user names and passwords, your applications can receive status code 3119.
See pvnetpass in Zen User’s Guide.
Creating a Client DSN
A client data source name (DSN) is required if applications on the client use the Zen Relational Engine through ODBC. To create a client DSN, you use the dsnadd utility included with the Zen Client. See dsnadd in Zen User’s Guide and the man page for dsnadd located in /usr/local/actianzen/man/man1.
Setting Up Web-based Data Access
The following topics cover the configuring of web servers to provide access to Zen data and provide connection snippets and samples for accessing Zen data from web applications on Linux or macOS. Raspbian is not supported for this use case.
ODBC Behavior
When you first install Zen, the odbc.ini file is written to /usr/local/actianzen/etc.
If you have other ODBC driver managers such as unixODBC, they may use an odbc.ini file in a different location, such as /etc/odbc.ini.
One way to unify the ODBC setup is to add soft links from between the Zen directories and the location where unixODBC expects to find the odbc.ini file, as shown in the following example:
su
cd /etc
ln -s /usr/local/actianzen/etc/odbc.ini
Configuring Web Server
This topic shows how you should set up the machine where the web server such as Apache resides.
You should make the user account under which you run any web server such as Apache a member of the group zen. These user accounts run under restricted accounts such as nobody
To find the user account, see your Apache configuration file, typically located at /etc/httpd/conf/httpd.conf.
In this file, the following lines show the user that the Apache server operates under:
User nobody
Group nobody
Options ExecCgi Indexes
You should add this user to the zen-data group, substituting the name used in your Apache configuration file.
/usr/bin/gpasswd -a nobody zen-data
PHP
PHP allows for easy development of web applications, using a style that is similar to both ASP in the Microsoft world and JSP in the Java world. Using PHP, you enclose database calls in special tags and format the output using HTML.
Zen PHP Requirements
PHP - obtain from http://www.php.net
DSN pointing to the database (use dsnadd)
PHP Connection Snippet
This code segment shows the essential part of connecting to a Zen database using PHP.
// connect to Demodata database no uid or password
$connect = odbc_connect("demodata", "", "");

// set the query variable to your SQL
$query = "SELECT * from Department";

// obtain a result object for your query
$result = odbc_exec($connect, $query);
PHP Sample
This complete sample presents the user a choice of three Demodata tables and then displays the table.
<HTML>
<HEAD>
<TITLE>PHP Sample</TITLE>
</HEAD>
<BODY>
<H1>Hello World Samples - PHP using PHP ODBC APIs)</H1>
<p>
This sample will display the Demodata database tables in the following drop-down
by using PHP.
</p>
<?
// -------MAIN MENU----------------------------
// if there is no function specified in the URL
if (!(isset ($HTTP_GET_VARS["_function"]))):
// --------------------------------------------
?>
<p>Please select from the following tables</p>
<form method=post action='<?=$PHP_SELF?>?_function=showtable'>
<select name="selecttable">
<option SELECTED value="Department">Department
<option value="Course">Course
<option value="Room">Room
</select>
<p>
<input type=submit value="Show table">
</p>
</form>
<?
// ------SHOWTABLE-----------------------------
Elseif ($HTTP_GET_VARS["_function"] == "showtable"):
// --------------------------------------------
print("<p>Return to <a href='$PHP_SELF'>Sample 1 Main menu</a></p>");
$thetable = $HTTP_POST_VARS["selecttable"];
// determine from FORMS data which table to open
$connect = odbc_connect("demodata", "", "");
// connect to Demodata database no uid or password
$query = "SELECT * from $thetable";
// set the query variable to contain the SQL you
// want to execute
$result = odbc_exec($connect, $query);
// perform the query
// print out the entire resultset as HTML table
// (uncomment following line)
// odbc_result_all($result);
// or format the output yourself and display
// a nicer table (but more code required)
// initialize row counter
$i = 0;
// determine number of columns
$numcols = odbc_num_fields($result);
// start HTML table
print("<table border=1 cellpadding=5>");
// Print column headings
print("<tr>"); // start of row
while ($i < $numcols)
    {
      $i++;
      $colname = odbc_field_name($result, $i);
      print("<th>$colname</th>");
    }
$i=0;
print("</tr>");       // end of row
// Print table data
// while there are still rows
while(odbc_fetch_row($result))
{
    print("<tr>");    // start row
    while ($i < $numcols)
      {
        $i++;
        $tablecell = odbc_result($result, $i);
        print("<td>$tablecell</td>");
      }
      print("</tr>");      // end row
      $i = 0;              // reset counter
}                       // end odbc_fetch_row
print("</table>");       // end HTML table
odbc_close($connect);     // CLOSE THE CONNECTION
// End of showtable
// ---Catch invalid menu options-----------------
Else:
// ----------------------------------------------
print("<p>An Invalid function was entered. Please <a href='$PHP_SELF'>try again</a>.</p>");
Endif;
?>
</BODY>
</HTML>
Perl
Perl allows for both command line and web-based applications using Zen.
Zen Perl Requirements
Perl
ODBC-DBD library
CGI library
DSN pointing to the database
Perl Connection Snippet
This code segment shows the essential part of connecting to a Zen database using Perl.
# specify use of Perl database interface (DBI)
use DBI;
# connect to Demodata database no uid or password
$dbInfo = "DBI:ODBC:DEMODATA";
$dbUserName = "";
$dbPassword = "";
# set the query variable to your SQL
$query = "SELECT * FROM Department";
# Connect to the server
$connect = DBI->connect($dbInfo, $dbUserName, $dbPassword);
# Prepare the SQL query
$myRecordSet = $connect->prepare($query);
# Execute the query and obtain a recordset
$myRecordSet->execute();
Perl Sample
This complete sample presents the user a choice of three Demodata tables and then displays the table.
# Perl sample
use CGI":cgi-lib";
$cgiquery = new CGI;
$functionreq = $cgiquery->url_param('_function');
# use 'url_param' for GET and 'param' for POST
print &PrintHeader;
print &HtmlTop("Hello World Sample - Perl");
print <<ENDOFMENU;
<H1>Hello World Samples - Perl</H1>
<P>
This sample will display the Demodata database tables in the following menu list by using Perl/DBI.
</p>
ENDOFMENU
# -----MAIN MENU-------------------------------
# if there is no function specified in the URL
if (!$functionreq) {
# ---------------------------------------------
print <<ENDOFTEXT;
<p>Please select from the following tables</p>
<form method=post action="$ENV{'SCRIPT_NAME'}?_function=showtable">
<select name="selecttable">
<option SELECTED value="Department">Department
<option value="Course">Course
<option value="Room">Room
</select>
<p>
<input type=submit value="Show table">
</p>
</form>
ENDOFTEXT
} # !($function)
# ------SHOWTABLE-------------------------------
elsif ($functionreq eq "showtable") {
print("<p>Return to <a href='$ENV{'SCRIPT_NAME'}'>Perl Hello World Sample - Main Menu</a></p>");
# determine from FORMS data which table to open
$thetable = $cgiquery->param('selecttable');
use DBI;
$dbInfo = "DBI:ODBC:DEMODATA";
$dbUserName = "";
$dbPassword = "";
$query = "SELECT * FROM $thetable";
$connect = DBI->connect($dbInfo, $dbUserName, $dbPassword);
$myRecordSet = $connect->prepare($query);
$myRecordSet->execute();
# start HTML table
print "<table border=1 cellpadding=5>";
# Print column headings
$num_fields = $myRecordSet->{NUM_OF_FIELDS};
$count = 0;
print "<tr >";
while ($count < $num_fields) {
$column_name = $myRecordSet->{NAME}->[$count];
print "<th>$column_name</th>";
$count++;
}
print "</tr>\n";
$count = 0;
# Print table data
while(@row=$myRecordSet->fetchrow_array) {
print "<tr>\n";
while ($count < $num_fields) {
print "<td>$row[$count]</td>\n";
$count++;
}
print "</tr>\n";
$count = 0;
}
print "</table>";            # end HTML table
# END OF SHOWTABLE
}
# -----CATCH INVALID MENU OPTIONS----------------
else {
print "<p>An Invalid function was entered. Please <a href='$ENV{'SCRIPT_NAME'}'>try again</a>.</p>";
}
print &HtmlBot;
Using Perl and ODBC with Zen
Note:  This procedure assumes you have a working installation of Zen, Perl, and an ODBC distribution. A free version of ODBC is available at www.iODBC.org. Perl can be found at www.perl.org.
To Get Zen to work with the Perl ODBC Interface
1. Download the database interface (DBI) support for Perl.
Read the readme or installation files for instructions.
2. Download the ODBC DBD database driver for Perl.
Please see the installation instructions in the readme or installation files.
3. Make sure that you have the proper environment variables set, as shown in the following example. These settings are also explained in the iODBC docs.
Code Snippet for Perl and DBI
print "using odbc...\n";
use DBI;
$dbName = "DBI:ODBC:DEMODATA";
$dbUserName = "";
$dbPassword = "";
print "connecting...\n";
$sql = "SELECT * FROM class";
$dbh = DBI->connect($dbName, $dbUserName, $dbPassword);
$dataObject = $dbh->prepare($sql);
$dataObject->execute();
while(@row=$dataObject->fetchrow_array)
{
print "$row[0]\t$row[1]\t$row[2]\n\n"
}
Last modified date: 10/31/2023