Database URIs
A key concept in using the Btrieve Login API or the implicit login functionality via the Create or Open functions is the database URI (Uniform Resource Indicator). It provides a syntax to describe the address of a database resource on a server.
This section describes the syntax and semantics of the URIs used in Btrieve APIs.
Syntax
A URI uses the following syntax:
access_method://user@host/dbname?parameters
 
 
Table 8
Elements of a Database URI  
Element
Definition
access_method
The method used to access the database. This element is required. Currently, only btrv is supported.
user@
An optional user name. The password for the user is specified in parameters if needed. The “@” character must be used to delimit the user name even if no host is specified.
host
A server where the database is located. The local machine is assumed if host is not specified. Host can be a machine name, an IP address, or the keyword “localhost.”
Note: host is a required element if the URI is accessing a database on a Linux or OS X system.
dbname
An optional database name, which corresponds to an entry in the DBNAMES.CFG file for the PSQL database engine. If no database name is specified, then the default database “DefaultDB” is assumed.
parameters
Additional, optional parameters, which are delimited by the & (ampersand) character.
•
table=table – specifies a specific SQL table name. The table name must exist in DDFs for the database.
•
dbfile=file – name of a file whose location is relative to the data file location entry in DBNAMES.CFG for the current database. Since a relative location is specified, the use of drive letters, full or UNC paths is not permitted. The database engine resolves the full file name. The PSQL client does not manipulate file in any manner. Embedded spaces are permitted and are escaped by the database engine.
•
file=file – specifies a specific data file name. The PSQL client normalizes file and replaces the input name with the resultant fully qualified UNC name in the URI before sending the request to the database engine. Drive letters may be used and, if present, are interpreted as client-side drives. Using a UNC path is also permitted, as are embedded spaces.
•
pwd=password – clear text password. The PSQL client changes clear text passwords into encrypted passwords before transmission.
•
prompt=[ yes | no ] – tells the PSQL client how the application wants to handle the login dialog box pop-up when the database engine returns status 170 (Login failed due to missing or invalid user name) or 171 (Login failed because of invalid password). If prompt=yes is specified, the requester always displays the login dialog even if the Prompt for Client Credentials setting is Off. If prompt=no is specified, the requester assumes that the application wants to receive the status 170/171 directly and does not want the requester to display the dialog. This is useful if you want your applications to handle the prompting for credentials in response to any 170 or 171 status codes. Values other than “yes” or “no” are ignored and the requester displays the login dialog based on the Prompt for Client Credentials setting. This option is ignored on Linux and OS X systems that are acting in the role of a client.
Parameter Precedence
The database engine enforces a precedence level on the parameters “file,” “table,” and “dbfile” when more than one of them is specified in a URI. That is, after parsing, the database engine leaves the parameter with the highest precedence. If two or more have the same precedence, the last parameter in the URI is returned after parsing.
The order of precedence from highest to lowest is “file,” “table,” and “dbfile.”
Precedence Examples
 
Initial URI String
Parsed URI String
btrv://?file=MyFile.btr&table=MyTable&dbfile=DataFile.btr
btrv://?file=MyFile.btr
btrv://?table=MyTable&dbfile=DataFile.btr
btrv://?table=MyTable
btrv://?dbfile=DataFile.btr&file=MyFile.btr
btrv://?file=MyFile.btr
btrv://?dbfile=DataFile.btr
btrv://?dbfile=DataFile.btr
btrv://?file=FileOne&file=FileTwo
btrv://?file=FileTwo
btrv://?table=TableOne&table=TableTwo&file=MyFile.btr
btrv://?file=MyFile.btr
Special Characters
As with any URI, certain non-alphanumeric characters have special significance in the URI syntax. If you wish to use one of these characters within one of the elements in the URI, you must use an escape sequence to identify the character as actual text rather than a special character. An escape sequence is simply another special character or character combination that represents the plain text equivalent of a special character.
The table below shows the special characters supported by the MicroKernel Engine URI syntax, and their associated escape sequences (represented by the percent sign and the hexadecimal value for the specified character).
Table 9
Special Characters in a Database URI
Character
Meaning
Hexadecimal Value
/
Separates directories and subdirectories
%2F
?
Separates the base URI from its associated parameters
%3F
%
Specifies a special character
%25
#
Indicates a bookmark or anchor
%23
&
Separates the parameters in the URI
%26
" "
Indicates the entire content enclosed by the double quotes
%22
=
Separates a parameter and its value
%3D
space
No special meaning, but is reserved.
%20
:
Separates host from port (reserved, but not currently supported). The colon is also used in some IPv6 addresses. See IPv6.
%3A
Although the space character is reserved in the URI specification, it can be used without quotes and without escape sequencing because it is not used as a delimiter. The other symbols in the table above are used as delimiters and therefore must be escaped.
Examples
This section shows examples of URIs using escape sequences to identify special characters used within the field values.
Table 10
URI Examples with Escape Sequences
URI
Meaning
btrv://Bob@myhost/demodata?pwd= This%20Is%20Bob
User “Bob” with password “This Is Bob.”
btrv://Bob@myhost/demodata?pwd= This Is Bob
User “Bob” with password “This Is Bob.”
btrv://myhost/mydb?file=c:/data%20files/pvsw/mydb/c.mkd
The %20 represents a space character. File to be opened is “C:\data files\pvsw\mydb\c.mkd”
btrv://Bob@myhost/demodata?pwd= mypass%20Is%20%26%3f
User Bob with password “mypass Is &?”
Remarks
Note that an empty user name or password is different than no user name or password. For example, btrv://@host/ has an empty user name, while btrv://host/ has no user name, and btrv://sam@host/?pwd= has a user name sam with an empty password.
Some URIs allow the use of user:password syntax. However, the password is then transmitted as clear text. To prevent the transmission of the password as clear text, the PSQL database URI ignores the password if one is provided using the user:password syntax. Use the pwd= parameter to provide a password, which the PSQL client changes into an encrypted password before transmission.
Some URIs allow for server based naming authority with a syntax of user@host:port. The PSQL database URI does support specifying a port element.
Examples
A URL (or "Uniform Resource Locator") is simply the address of a file or resource on the Internet. The database URI uses the same notion to address a database on a server. This section gives examples of the syntax and semantics of URIs for PSQL databases, particularly using the MicroKernel Engine access.
Table 11
Examples of the MicroKernel Engine URIs 
Example
Meaning
btrv://myhost/demodata
Database “demodata” on server “myhost.” The server operating system can be any of the ones supported by PSQL
btrv:///demodata
Database “demodata” on the local machine. The local machine is running a Windows operating system. The host element is required for Linux and OS X systems (see the example above).
btrv://Bob@myhost/demodata
User Bob without a password accessing database “demodata” on server “myhost.”
btrv://Bob@myhost/mydb?pwd=a4
User Bob with password “a4” accessing database “mydb” on server “myhost.”
btrv://myhost/demodata?table=class
Unspecified user accessing database table named “class” in database “demodata” on server “myhost.”
btrv://myhost/?table=class
Unspecified user accessing database table named “class” in default database (“DefaultDB”) on server “myhost.”
btrv://myhost/mydb?file=f:/mydb/a.mkd
Unspecified user accessing the data file “f:/mydb/a.mkd” as seen by the client using the security credentials of the database "mydb" on server "myhost."
Note that the client normalizes drive “f:” which means that “f:” must be mapped at the client to server "myhost."
btrv://mydb?file=c:/mydb/a.mkd
Unspecified user accessing the data file “c:/mydb/a.mkd” under database "mydb" on the local machine.
Drive “c:\” is a local drive on the local machine. The local machine is running a Windows operating system.
btrv://myhost/demodata?dbfile=class.mkd
Unspecified user accessing data file “class.mkd” within one of the data directories defined for the “demodata” database on server “myhost.” Because the file name is specified with dbfile= (and not file=) the client requester does not normalize class.mkd. Only the server engine normalizes class.mkd into a full path.
IPv6
The URI and UNC syntax does not allow certain special characters, such as colons. Since raw IPv6 addresses use colons, different methods of handling UNC paths and URI connections are available. PSQL supports IPv6-literal.net Names and Bracketed IPv6 Addresses.
See IPv6 in Getting Started With PSQL.