Clarion Community Help

There are switches or “driver strings” you can set to control the way your application creates, reads, and writes files with a specific driver. Driver strings are simply messages or parameters that are sent to the file driver at run-time to control its behavior. See Common Driver Features--Driver Strings for an overview of these runtime Database Driver switches and parameters.

The Btrieve Driver supports the following Driver Strings:

ACS

DRIVER('BTRIEVE', '/ACS = filename' )

[ SortSeq“ = ] SEND(file, 'ACS [ = filename ]' )

When creating a Btrieve file you can specify an alternate collating sequence for sorting STRING keys. This sorting sequence is normally obtained from the sort sequence you define in the INI file for your program. However, Btrieve supplies files for doing case insensitive sorts. To create your file using these sort sequences you specify the name of the sort file in the driver string.

ALLOWREAD

DRIVER('BTRIEVE', '/ALLOWREAD = ON | OFF' )

[ Read” = ] SEND(file, 'ALLOWREAD [ = ON | OFF ]' )

By default, a Btrieve file created with an owner name may be accessed only in read-only mode when the owner name is not known. To prevent all access to the file without the owner name, set ALLOWREAD to OFF. SEND returns the ALLOWREAD setting (ON or OFF) in the form of a STRING(3).

APPENDBUFFER

DRIVER('BTRIEVE', '/APPENDBUFFER = size ' )

[ Buffer“ = ] SEND(file, 'APPENDBUFFER [ = size ]' )

By default, APPEND adds records to the file one at a time. To get better performance over a network you can tell the driver to build up a buffer of records then send all of them to Btrieve at once. Size is the number of records you want to allocate for the buffer. SEND returns the number of records that will fit in the buffer.

BALANCEKEYS

DRIVER('BTRIEVE', '/BALANCEKEYS = ON | OFF' )

[ Balance” = ] SEND(file, 'BALANCEKEYS [ = ON | OFF ]' )

When creating a Btrieve file, you can use this driver string to tell Btrieve that all keys associated with the file must be stored in a balanced btree. This saves disk space, but will slow down file adds, deletes and updates where key values change. SEND returns the BALANCEKEYS setting (ON or OFF) in the form of a STRING(3).

COMPRESS

DRIVER('BTRIEVE', '/COMPRESS = ON | OFF' )

[ Read“ = ] SEND(file, 'COMPRESS [ = ON | OFF ]' )

Btrieve lets you compress the data before storage. This allows for a smaller storage requirement, but reduces performance. When COMPRESS is ON, CREATE creates a compressed Btrieve file. SEND returns the COMPRESS setting (ON or OFF) in the form of a STRING(3).

CLIENTID

DRIVER('BTRIEVE', '/CLIENTID = xx' )

[ Read” = ] SEND(file, 'CLIENTID = xx ' )

Btrieve allows you to specify the Client ID used in the Btrieve APIs to uniquely identify a client application. This can be used to help monitor Btrieve activity as well as avoid a deadlock situation inside the MicroKernel if multiple threads access the MicroKernel simultaneously.

To set the Client ID, add /CLIENTID=xx to the driver string for the first Btrieve file that you use.

xx is the ID you want to set. This is limited to 2 characters. The following character pairs should not be used:

Used internally by the MicroKernel:

Used to identify clients originated by Scalable SQL:

You can also use SEND before any file I/O to set this value. You can also use SEND to read the value.

FREESPACE

DRIVER('BTRIEVE', '/FREESPACE = 0 | 10 | 20 | 30' )

[ Read“ = ] SEND(file, 'FREESPACE [ = 0 | 10 | 20 | 30 ]' )

Specifies the percentage of free space to maintain on variable length pages. The default is zero. SEND returns the percentage of free space to maintain on variable length pages.

LACS

DRIVER('BTRIEVE', '/LACS [ = | country_id,codepage ]' )

[ Sequence” = ] SEND(file, 'LACS [ = | country_id,codepage ]' )

Btrieve v6.15 and later offers the Local Alternate Collating Sequences feature. This allows your string keys to sort based on the country code for the machine running your program. To use this feature include '/LACS' in your driver string.

/LACS=country_ID,code_page

You can also specify a User-Defined Alternate Collating Sequence. This allows your string key to sort based on the DOS country code and code page for a particular country. To use this feature you put '/LACS=country_id,codepage' in your driver string. Note that there must be no spaces surrounding the comma.

SEND returns country_id,codepage or the string ',' if using the Local Alternate Collating Sequences feature.

MEMO

DRIVER('BTRIEVE', '/MEMO = SINGLE | LVAR | NOTE [,delimiter]' )

[ Memo“ = ] SEND(file, 'MEMO [ = SINGLE | LVAR | NOTE [,delimiter]]' )

/MEMO=SINGLE

To access existing Btrieve files created with the Btrieve LEM from Clarion Professional Developer 2.1(DOS), or files with variable length records set MEMO to SINGLE.

To access a file with variable length records, use a SINGLE style MEMO whose size equals the maximum size of the variable length component of the record. To add/put records to this style file with binary data stored in the variable length section, use the ADD(file,length), APPEND(file,length) and PUT(file,pos,length) functions. The driver ignores the pos parameter in the PUT function, but initialize it to 0 (zero) for future compatibility. The ADD, APPEND or PUT functions will remove all trailing spaces for text memos and NULL characters for binary memos before storing the record.

/MEMO=LVAR

/MEMO=NOTE,<;delimiter>

To access Xtrieve data files that have data type of Note or LVar, set the driver string to NOTE and LVAR respectively. With the NOTE data type, specify the end-of-field delimiter. Specify the ASCII value for the delimiter. NOTE and LVAR memos do not require the use of the size variants of ADD, APPEND and PUT, when storing records. The end of record marker is not necessary for a NOTE style memo. The driver automatically adds the end of record marker before storing the record and removes it before putting the memo data into the memo buffer.

As an example, ”/MEMO=NOTE,141“ indicates a file with an Xtrieve Notes field using CR/LF as the delimiter. For more information on the Xtrieve data types refer to the documentation supplied by Novell.

SEND(file,'MEMO')

Returns the MEMO setting: NORMAL, NOTE, LVAR, or SINGLE.

PAGESIZE

DRIVER('BTRIEVE', '/PAGESIZE = SIZE' )

[ PSize” = ] SEND(file, 'PAGESIZE[=SIZE' )

Sets the Btrieve Page size at file creation time. The size must be a multiple of 512, with a maximum of 4096. Larger page sizes usually result in more efficient disk storage.

SEND returns the page size setting.

PREALLOCATE

DRIVER('BTRIEVE', '/PREALLOCATE = n' )

[ Read“ = ] SEND(file, 'PREALLOCATE [ = n ]' )

When creating a Btrieve file, you can preallocate n pages of disk space for the file. The default is zero. SEND returns the number of pages of allocated disk space.

TRUNCATE

DRIVER('BTRIEVE', '/TRUNCATE = ON | OFF' )

[ Trunc” = ] SEND(file, 'TRUNCATE [ = ON | OFF ]' )

When creating a Btrieve file, you can use this driver string to tell Btrieve to truncate trailing spaces. This forces the record to be stored as a variable length record. SEND returns the TRUNCATE setting (ON or OFF) in the form of a STRING(3).

Btrieve:Driver Properties

You can use Clarion's property syntax to query and set certain driver properties. These properties are described below.

PROP:PageLevelLocking

PROP:PageLevelLocking sets the type of locking the driver uses with LOGOUT. The driver uses either page or file level locking schemes. Set to PageLevelLocking by setting the property to '1'. This is the default. To set the driver to file level locking, set the property to . MyFile{PROP:PageLevelLocking} = '1'      !Set Page level locking MyFile{PROP:PageLevelLocking} = ''       !Set File level locking loc:lock = MyFile{PROP:PageLevelLocking} !read locking scheme PROP:PositionBlock PROP:PositionBlock returns the Btrieve pointer to the Btrieve position block used by the Btrieve driver for the named file. This allows you to call Btrieve operations directly. For example:  MAP  MODULE('Btrieve')   BTRV(USHORT,LONG,<;*STRING>,*UNSIGNED,<;*STRING>,BYTE,BYTE),|    NAME('BTRV'),PASCAL,RAW    END  END StatData STRING(33455) KeyData  STRING(64) DataLen  UNSIGNED(33455) CODE PosBlock = file{PROP:PositionBlock} BTRV(15,PosBlock,StatData,DataLen,KeyData,64,0)  !Get file statistics