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

The basic syntax of the URI is

access_method://user@host/dbname?parameters 

 
Table 3-1 Elements of a Database URI

Element	Definition
access_method	The method used to access the database. Currently, only btrv is supported.
user	An optional user name. The password for the user is specified in parameters if needed.
host	A server where the database is located. The local machine is assumed if host is not specified.
dbname	An optional database name, which corresponds to an entry in the DBNAMES.CFG file for the Pervasive.SQL V8 database engine. If no database name is specified, then the default database "DefaultDB" is assumed.
parameters	Additional parameters, which are delimited by the & (ampersand) character. table=table - allows you to specify a specific SQL table name. dbfile=file - Name of a file whose location is relative to the current database's data file locations entry in DBNAMES.CFG. The full file name will be resolved by the engine handling the request; the Pervasive.SQL client (MIF) will not manipulate <dbfile> in any manner. The use of drive letters is discouraged but if present will be assumed to be server side and not client side drive letters. Embedded spaces are permitted - they will be escaped by the engine. Using a UNC path is also permitted. file=file - allows you to specify a specific data file name. Embedded spaces are permitted in this parameter. pwd=password - clear text password. The Pervasive.SQL client (MIF) will change clear text passwords into encrypted passwords before transmission across the wire. prompt=[ yes | no ] Tells the Win32 requester how the application wants to handle the login dialog box pop-up when the MicroKernel 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 will always display the login dialog even if the Prompt for Client Credentials setting is Off. If prompt=no is specified in the URI, 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 NetWare machines that are acting in the role of a client.

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 fields 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 Btrieve URI syntax, and their associated escape sequences (represented by the percent sign and the hexadecimal value for the specified character). For more information on special characters in URIs, see the RFC1738 specification at http://www.faqs.org/rfcs/rfc1738.html.

 
Table 3-2 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	%23
&	Separates the parameters in the URI	%26
","	Indicates whole part	%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)	%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 3-3 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/demodata?file=c:/program%20files/pvsw/mydb/c.mkd	The %20 represents a space character. File to be opened is "C:\Program Files\pvsw\mydb\ c.mkd"
btrv://Bob@myhost/demodata?pwd= mypass%20Is%20%26%3f	User Bob with password "mypass Is &?"

Remarks

Some or all of the syntax elements user and ?parameters may be excluded.

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://foo@host/?pwd= has a user name of "foo" with an empty password.

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 describes the syntax and semantics of URIs for Pervasive.SQL databases, particularly using the Btrieve access.

 
Table 3-4 Examples of Btrieve URIs 

Example	Meaning
btrv://myhost/demodata	Database "demodata" on server "myhost."
btrv:///demodata	Database "demodata" on local machine.
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=c:/mydb/a.mkd	Unspecified user accessing data file c:/mydb/a.mkd under database "mydb" on server "myhost."
btrv://myhost/mydb?dbfile=class.mkd	Unspecified user accessing data file class.mkd within first data directory location specified for database "mydb."
btrv://myhost/demodata?dbfile=class.mkd	File class.mkd under data path of "demodata" on server "myhost". Because the file name is specified with dbfile= (and not file=) the P.SQL requester will not normalize class.mkd. Only the server engine will normalize class.mkd into a full path.
btrv://myhost/demodata?dbfile=c:\pvsw\demodata\ class.mkd	File c:\pvsw\demodata\class.mkd on server "myhost" and in database "demodata". Because the file name was specified with dbfile= the drive letter c: is meaningful only to the engine on the server. Drive letter c: is not associated with the client side.