How to Configure Network Communications for Your Zen Clients
To access network files from a machine where a Zen application is running, you must use an appropriate client requester on that machine. Zen calls made by your application go through the client requester, which sends them to the server and then passes the reply to your application.
Generally, the default property settings for Zen server and its clients are sufficient to enable them to communicate and function correctly. You typically do not have to change any properties, but if other settings are needed, they are covered in the following topics:
This topic lists the configuration settings used by the Zen Client for network communication. These settings may be changed using a command line utility or from within ZenCC on the engine properties.
The Advanced Operations Guide provides detailed information about each of the settings. See the following configuration settings in Advanced Operations Guide for network communication:
When using your Requester, you connect to the Zen database engine to access data files. This topic covers variations in network file syntax to access files on your network using Btrieve or DTI applications.
Zen supports the Universal Naming Convention (UNC) and Drive path formats (explicit and current) across the majority of operating environments.
For more information on the path formats, see the following items:
If you are an application developer, also note that the certain access methods, such as the Btrieve API, support URI connection strings. For details about URI strings, see Database URIs in Zen Programmer’s Guide. In Btrieve API Guide, see Create (14), Open (0), and Login/Logout (78).
Universal Naming Convention (UNC) Path Formats
The following UNC path formats are supported on all clients to all servers:
\\ServerName or IP address\share\path\file
\\ServerName or IP address\share:[\]path\file
UNC syntax is resolved correctly regardless of the actual type of network operating system (NOS) running on the target server. If you use an IP address, it must be a dotted IPv4 address or one of the two formats supported for IPv6. See IPv6 Addresses.
Note In all instances above, backslashes (\) can be interchanged with forward slashes (/) except for the double backslash (\\). The syntax [\] indicates that the backslash is optional.
Drive-based Formats
The following drive representations are supported on all clients to all servers:
On macOS servers, third-party packages are not the only way to enable Samba sharing. macOS supports native SMB-style sharing without a smb.conf file. Use System Preferences > Sharing or the sharing command to configure a share or view existing shares.
IPv6
A Zen Client using any of the access methods supported by Zen connects using IPv6 to an IPv6 host running the Zen database engine the same way as it does for IPv4. That is, the client specifies a server and connects through one of the supported access methods. The server can be either the name or IP address of the machine running Zen Enterprise Server, Cloud Server, or Workgroup.
All of the Zen access methods except for ActiveX support IPv6 connections. Some access methods are Windows only, but can be used with a client-server combination of Windows and Linux, macOS, or Raspbian.
This topic addresses the following aspects of IPv6:
Raw IPv6 addresses can be written as 8 colon-separated segments where each segment is a 4-digit hexadecimal value. For example, 1234:5678:90ab:cdef:1234:5678:90ab:cdef. Within this framework, several forms of IPv6 names are possible.
Recommendations for Numeric IPv6 Addresses
In general, numeric IPv6 addresses are more complex and difficult to manipulate than IPv4 addresses. Numeric Link Local addresses are notably problematic, especially with regard to Zone IDs.
For that reason, we recommend the use of host names through DNS servers, LLMNR, host files, or other means of address resolution, particularly for production environments. Zen support for numeric IPv6 addresses is intended mainly for development environments. Because many contexts require square brackets for IPv6 numeric addresses, when in doubt, add them if numeric addresses are necessary.
Unicast Addresses
Zen supports only unicast addresses. The following are the unicast address formats that can be used with Zen.
Table 2 IPv6 Unicast Address Formats Supported by Zen
Unicast Address Format
Description
Loopback
The local loopback address, which in IPv6 is 0:0:0:0:0:0:0:1. The loopback address can be abbreviated to ::1.
The IPv6 loopback address is equivalent to the IPv4 loopback address of 127.0.0.1.
Global
Global addresses have a 64-bit prefix where the first 3 bits are always 001, the next 45 bits are set to the global routing prefix, the next 16 bits are set to the subnet ID and the last 64-bits are the interface ID.
Example: 2001:db8:28:3:f98a:5b31:67b7:67ef
Link Local
Link Local addresses are used by nodes when communicating with neighboring nodes on the same link. Link Local addresses have a 64-bit prefix where the first 10 bits are set to 1111 1110 10, the next 54 bits are set to 0 and the last 64 bits are the interface ID. The link local prefix is often represented as FE80::/64.
Example: fe80:0:0:0:713e:a426:d167:37ab (which may also be specified as fe80::713e:a426:d167:37ab)
IPv6 includes address modifiers that can act as shortcuts or can specify the destination in more detail. Zen supports the following ones for IPv6.
Modifier
Explanation
::
Represents one or more colon-separated zeroes. For example, ::1 is equivalent to 0:0:0:0:0:0:0:0:1. The :: modifier can be used only once within an IPv6 address.
%
Represents the Zone ID or interface of a destination node. On Windows, a Zone ID is an integer that specifies the zone of the destination for IPv6 traffic. Zone IDs are primarily used with Link Local addresses to disambiguate those addresses.
Unix distributions support only the text form of a Zone ID in a link local address. For example, you must use the “eth0” form of a Zone ID: eth0 fe80:0:0:0:713e:a426:d167:37ab. See also Limitations and Conditions.
Note Linux, macOS, and Raspbian distributions do not support IPv6-literal.net names.
Bracketed IPv6 Addresses
A bracketed IPv6 address is a raw IPv6 address with square brackets around it. This format is also referred to as a Uniform Naming Convention (UNC)-safe address.
Examples:
Initial Addresses
fe80::713e:a426:d167:37ab%4
2001:db8:28:3:f98a:5b31:67b7:67ef
Modified Addresses
[fe80::713e:a426:d167:37ab%4]
[2001:db8:28:3:f98a:5b31:67b7:67ef]
Note Linux, macOS, and Raspbian distributions do not natively support UNC paths and UNC-safe addresses. However, the Zen interfaces that accept a file path, a numeric address, or both as input support both UNC paths and UNC-safe addresses on Linux, macOS, and Raspbian for compatibility with Windows.
IPv6 and the MicroKernel Engine
The following table lists the restrictions on the use of IPv6 with the MicroKernel Engine.
Table 3 IPv6 Restrictions for MicroKernel Engine
Restriction
Discussion
The Zen server engine in an IPv6-only environment
The engine is supported in an IPv6-only environment on Windows Vista and later operating systems, and in IPv6-only environments on the most current Linux, macOS, and Raspbian distributions.
UNC paths do not allow certain special characters, such as colons, that are part of IPv6 addresses
Failure to bracket the IPv6 address results in status code 3014 or 3103 for Btrieve calls using a URI, or status code 11, 94, or 170 for Btrieve calls using a UNC.
In a URI, if you include a ZoneID to a server address, the “%” ZoneID character must be escaped with “%25”
If you use a btrv:// connection with an IPv6 address, you must escape the ZoneID for the host name. Zone IDs are usually required with IPv6 Link Local numeric addresses.
The inclusion of a port number with an IP address is necessary only when you need to override the default port. Generally, a port number can be appended to an IP address using either a colon (:port number) or a dot (.port number).
All of the previous topics about IPv6 apply to Linux, macOS, and Raspbian distributions, with specifics noted. The following topics discuss additional aspects of IPv6 when used with Linux, macOS, and Raspbian.
Suggested Distributions
Full IPv6 support is a relatively recent feature of operating systems. For this reason, we recommend that you use the most current Linux, macOS, or Raspbian distribution. See the Actian website for a list of the Linux, macOS, and Raspbian distributions and use the most current distribution of the latest one listed.
Limitations and Conditions
Note the following limitations and conditions when you use IPv6 with Linux, macOS, or Raspbian:
•Ping commands are specific for IPv4 (ping) and IPv6 (ping6). If you use ping6 with a Link Local address, the Zone ID is a separate argument, not a part of the address. For example, “eth0” is the Zone ID in the following ping6 command: ping6 -I eth0 fe80::1574:833f:b328:30ab.
•As previously mentioned, Zen interfaces running on Unix-based systems support UNC paths and UNC-safe addresses, even though Unix itself does not. This could be a source of confusion when you perform operations at the operating system level. For example, assume that you receive a network error when you run the following command for butil:
You may attempt to diagnose the error with commands such as the following:
ping [fe80::1574:833f:b328:30ab%eth0]
ping6 [fe80::1574:833f:b328:30ab%eth0]
ping6 fe80::1574:833f:b328:30ab%eth0
However, all of those commands fail with “unknown host” or “invalid argument” because of the brackets in the address, the appended Zone ID, or both. You must use the following command to determine if the network connection actually exists:
ping6 -I eth0 fe80::1574:833f:b328:30ab .
•The mount command does not accept a Zone ID with an IPv6 numeric address. A Link Local address cannot be used with mount. You can use a host name that resolves to an IPv6 address.
Best Practices
We recommend the following practice when you use IPv6 with Linux, macOS, or Raspbian.
Use pvnetpass to ensure that the Zen Client platform provides the required credentials on a server when the client connects to the database engine on that server. Pvnetpass is required for each different server address connection, even equivalent server addresses. For example, suppose that a host name and an IPv6 numeric address refer to the same server. A connection to each one requires the use of pvnetpass. See pvnetpass in Zen User’s Guide.
Frequently Asked Questions About IPv6
The following table answers some frequently asked questions about IPv6 support and Zen.
Table 4 FAQs About IPv6 Support and Zen
Question
Answer
Does a network environment that includes both IPv4 and IPv6 affect Zen user counts?
No. IPv4 and IPv6 are just different address formats of TCP/IP.
Because a Zen client can have both IPv4 and IPv6 addresses, will confusion result over how many licenses are required?
No. This is not a new situation. In the past, clients have sometimes had more than one IPv4 address. Zen handles the situation by recognizing all of the addresses of a machine to identify it and also follows the same logic for multiple addresses using more than one IP version.
Any restrictions with IPv6 and the use of License Administrator?
Yes. The Zen licensing server does not yet support IPv6. Because of this, you can use License Administrator over IPv6 to administer licenses. However, to authorize a license with License Administrator, the utility must be running on a machine that uses IPv4 to communicate with the Zen licensing server.
Does the use of IPv6 change the use of DSNs?
No, continue to use DSNs as usual. You can use IPv6 numeric address, with or without brackets, when creating DSNs. See DSN Setup and Connection Strings in ODBC Guide.
Can Zen System Analyzer still test connections?
Yes, you can test IPv6 addresses. The transaction engine test requires a mapped drive or a UNC path to the samples folder. An IPv6 numeric address used in a UNC path must include brackets. See Zen System Analyzer (PSA) in Zen User’s Guide.
Can Zen User’s GuideAuto Reconnect be used with IPv6?
1 Some utilities accept UNC path formats that are not valid for the operating system, file system, or file sharing protocol.
2 Rbldcli must have direct file access for proper operation. Any file paths specified in a rbldcli command must also be accessible through the file system or through a file sharing protocol such as Windows File Sharing or Samba. One method of verifying valid paths is to check whether they work with operating system commands such as dir or ls.
Using TCP/IP to Connect to a Windows Server
This section documents the use of TCP/IP when connecting to a Zen server running on a Windows server platform.
Configuring a Client for the Server IP Address
When Zen operates in a TCP/IP network, your client must be able to obtain the IP address of your Windows server from the name given to that server. There are two mechanisms that enable this address-to-name translation:
•DNS (Domain Naming Service)
•Editing the hosts file
The following procedures provide an overview for how to set up the IP address using each method. For details about network configuration and set up, refer to the documentation for the operating system.
Using DNS to Configure the Server IP Address
When you use DNS, you specify settings that allow your computer to look up the address of the server in a database of servers. Your network administrator can provide the information you need to configure DNS.
►To configure your Windows clients to use DNS to resolve the server IP address
1 From the operating system, access the Network information.
2 Select the Properties for Local Area Connection.
3 Select the Properties of the TCP/IP connection being used (IPv4 or IPv6, for example).
4 Enable DNS and enter the appropriate server information.
Using the Hosts File to Configure the Server IP Address
The hosts file is a way to manually enter a relationship between a name and an IP address. Use this method if DNS is not used in your organization.
►To edit the hosts file on your Windows client
1 Find the hosts file on your Windows machine.
For example, on certain Windows platforms it is located here: %WINDIR%\SYSTEM32\DRIVERS\ETC\HOSTS
2 Edit the hosts file with a text editor such as Notepad.
3 Enter your server IP address and name in the hosts file as a new line as shown in the following example. Your network administrator can provide you with the IP address.
# the following is an example of a hosts file entry for IPv4 address
146.23.45.2 acctserver
Preventing the Windows Dial-Up Network Dialog Box from Displaying When Using a Zen Application with TCP/IP
Depending on the settings for your browser, the Windows Dial-Up Networking dialog box can display when a TCP/IP request is made. Usually, this is to make an Internet connection, but this feature can be an annoyance when using Zen applications and TCP/IP.
►To prevent the dial-up networking dialog box from displaying automatically
1 In Control Panel, double-click Internet Options.
2 Click the Connections tab.
3 Clear the Dial whenever a network connection is not present option (select one of the other options, such as Never Dial a Connection).
Changing the Default Communication Ports
Zen uses access three communication ports for remote access to the server database engine:
•3351 for the MicroKernel Engine
•1583 for the Relational Engine
•139 for named pipes (see note)
Typically, you do not need to modify the ports unless you have a conflict with them.
Note Windows uses port 139 for operating system authentication. If you cannot open port 139 through a firewall, you can enable Zen database security. Once Zen security is enabled, it authenticates users instead of the operating system. See To turn on security using Zen Explorer and To create a new user using Zen Explorer in Advanced Operations Guide.
For the Relational Engine, port assignment 1583 is configurable on the server through the Zen utilities. This port is manually configurable for clients. See TCP/IP Port in Advanced Operations Guide.
We recommend not changing port assignment 3351. If you must change it, contact Technical Support.
Ensure that the port configurations match on both the server and all clients.
After changing your server listening port, you must stop and restart your database engine for the port assignment changes to take effect. See Using Zen in Zen User’s Guide.
Services File
The services file is a text file used for network communications. In the file you can manually assign the ports used by a Zen server and its clients. Be sure that the applicable ports listed in the services file are in agreement with the ports set by Zen in the utilities and with the associated Windows Firewall rules.
After changing port assignments in the services file, you must stop then start the Zen database engine for the changes to take effect.See Starting and Stopping the Database Engine in Zen User’s Guide.
Windows FireWalls
Zen installation performs certain firewall actions. Windows Defender Firewall with Advanced Security provides firewall profiles that enable the firewall by default. The following table summarizes the Zen installation actions pertaining to these profiles.
Active Firewall Profile1
Rules Added for Zen Services
State of Rules After Installation2
•Domain
•Private
•Public
•Domain – Yes
•Private – Yes
•Public – Yes
•Domain – Enabled
•Private – Enabled
•Public – Disabled
Public only
Yes
Enabled
1 “Active” means that the profile is monitoring network connections.
2 An “enabled” rule means that inbound TCP and UDP traffic can communicate with the Zen service on all ports for any network connection managed by that firewall profile.
As the table shows, if the Public profile is active with one or more other active profiles, the Zen rules are added for the Public profile but disabled. Neither the interactive nor the silent installation of a Zen product can be modified to change this behavior. If you want to enable the rules for the Public profile, you must do so manually. See To enable Zen rules for the Public profile.
►To enable Zen rules for the Public profile
1 Open the console for Windows Firewall with Advanced Security.
2 Click Inbound Rules in the left pane.
3 Locate the desired Zen rule in the list in the center pane.
Note that the rules are listed twice. The enabled rules (indicated by a check mark on a green circle) apply to profiles other than Public. The disabled rules apply to the Public profile.
4 Right-click the disabled rule you want then click Properties.
5 Click the Advanced tab. Ensure that the Public profile is selected. If not, select it.
6 Click the General tab, then click the Enabled option.
7 Click OK.
8 Exit the console for Windows Firewall with Advanced Security.
Profile Changes After Installation
If you change a network profile after installation, Zen may no longer be able to accept communications. For example, assume that only the Private network profile was active during installation. At some point after installation, the active profile is changed to Domain (assume its settings are very different from those of Private). The database engine will no longer be able to communicate across the network.
If you change profiles or firewall rules in a way that prevents Zen communications, refer to the steps in To enable Zen rules for the Public profile. Use the steps as a general guideline for how to enable the Zen rules for the active profiles. This will allow the database engine to communicate again across the network.
Notes About Policies
A corporate policy may prevent a local administrator from modifying the firewall profiles on a particular machine. If so, the Zen installation cannot add or enable the firewall rules required for the database engine to communicate across a network connection monitored by a profile blocked in this way. For such a situation, you should contact a corporate systems administrator and request that the firewall policy be modified to allow inbound TCP and UDP traffic on all ports to communicate with all installed Zen services.
Also be aware that a Group Policy only prevents the installation from adding and enabling rules on firewall profiles controlled by the Group Policy when the target system is joined to the domain. If the user installing Zen is logged into the target system as a local user instead of as a domain user, the installation does add and enable the rules on the firewall profiles. However, the rules are disabled if the target system is later joined to the domain controlling the Group Policy.
Using TCP/IP to Connect a Windows Client to Linux, macOS, or Raspbian Servers
Your Samba must be properly configured on your Linux, macOS, or Raspbian server to network with Windows-based clients when using mapped drives.
Configuring a Client for the Server IP Address
When Zen operates in a TCP/IP network, your client must be able to obtain the IP address of your Linux, macOS, or Raspbian server from the name given to that server. Two mechanisms enable this translation of address to name:
•DNS (Domain naming service)
•Editing the hosts file
The following procedures provide an overview for how to set up the IP address using each method. For details about network configuration and set up, see the documentation for the operating system.
Using DNS to Configure the Server IP Address
When you use DNS, you specify settings that allow your computer to look up the address of the server in a database of servers. Your network administrator can provide the information you need to configure DNS.
►To configure your clients to use DNS to resolve the server IP address
For clients on Windows platforms:
1 From the operating system, access the Network information.
2 Select the Properties for Local Area Connection.
3 Select the Properties of the TCP/IP connection being used (IPv4 or IPv6, for example).
4 Enable DNS and enter the appropriate server information from your network administrator.
Using the Hosts File to Configure the Server IP Address
The hosts file is a way to manually enter a relationship between a name and an IP address. Use this method if DNS is not used in your organization.
►To edit the hosts file on your Windows client
1 Find the hosts file on your Windows system.
For example, on certain Windows platforms it is located here: %WINDIR%\SYSTEM32\DRIVERS\ETC\HOSTS
2 Edit the hosts file with a text editor such as Notepad.
3 Enter your server IP address and name in the hosts file as a new line as shown in the following example. Your network administrator can provide you with the IP address of your server.
# the following is an example of a hosts file entry for IPv4 address
146.23.45.2 acctserver
Preventing the Windows Dial-Up Network Dialog Box from Opening
The Windows Dial-Up Networking dialog box can open when a TCP/IP request is made to Windows. Usually, this is to make an Internet connection, but this feature can be an annoyance when you are using Zen applications and TCP/IP.
►To prevent the dial-up networking dialog box from displaying automatically
1 In Control Panel, double-click Internet Options.
2 Click the Connections tab.
3 Clear the Dial whenever a network connection is not present option (select one of the other options, such as Never Dial a Connection).
Data Encoding
The use of encoding methods is intended for advanced users. In general, the default encoding settings are sufficient and do not require changing. See Database Code Page and Client Encoding in Advanced Operations Guide.
Using the DOS Requester
Zen supports DOS Btrieve applications with the DOS Requester. The DOS requester supports Btrieve applications only, not ODBC applications. This topic explains how to use the DOS requester to run Zen-based DOS applications in Windows.
DOS Box support allows a DOS application to run in a DOS box on a Windows platform. This enables direct communication to the Windows 32-bit workstation components rather than to the database engine. This configuration can be used with either a local Zen Workgroup engine, or a remote engine. The TCP/IP protocol supported for client-server access depends on the configuration of the Windows 32-bit components.
Supported Configurations
The DOS requester supports both Workgroup and Client to remote Zen server configurations.
DOS Box Support on Windows
The Requester for Windows is BTRBOX. You can use this Requester for DOS applications.
Running DOS Applications on Windows 32-bit Platforms
All of the components needed to run DOS applications using BTRBOX are installed with your client. After the Windows client component installation, you have everything you need to run a DOS or Windows 32-bit application. The default DOS application support installed is the Win32 DOS Box configuration.
DOS applications are not supported on 64-bit Windows platforms. Therefore, BTRBOX is not supported on 64-bit Windows platforms.
Using DOS Box Support
On Windows platforms, the DOS Box install configures the drivers to be completely transparent. Thus, you are able to immediately open a command prompt and run a DOS Btrieve application. The CONFIG.NT file, located in the %WINDIR%\SYSTEM32 directory, contains the command that enables DOS application support. This file is similar to CONFIG.SYS in DOS. The Windows operating system loads the driver for each DOS session opened. In the configuration file, the install places the following path to load the DOS Box driver: