Set Owner (29)
The Set Owner operation (B_SET_OWNER) assigns an owner name (a password) to a file. If an owner name has been set for a file, users or applications must specify the owner name each time they access the file. You can specify that an owner name be required for any access or just for update privileges.
When you assign an owner name, you can also direct the transactional interface to encrypt the file’s data on the disk. If you specify data encryption, the transactional interface encrypts all the data during the Set Owner operation. Therefore, the longer the file, the longer Set Owner takes to complete.
Parameters
 
Op Code
Pos Block
Data Buf
Data Buf Len
Key Buffer
Key Number
Sent
* 
* 
* 
* 
* 
* 
Returned
 
* 
 
 
 
 
Prerequisites
•
The file must be open.
•
No transactions can be active.
•
The file cannot already have an owner name.
Procedure
1
Set the Operation Code to 29.
Optionally, you can include a bias of +17000 to create an owner name up to 24 bytes long (a “long” owner name). This bias is also defined in btrconst.h as B_LONG_OWNER_NAME_BIAS. Btrconst.h is provided with the Btrieve software development kit (SDK).
•
Once a long owner name is specified, the data file cannot be read by a database engine prior to Pervasive PSQL v10.10.
•
A data file with a long owner name cannot be rebuilt to a file format prior to 9.5 unless the owner name is first removed.
2
Pass the Position Block that identifies the file to protect.
3
Store the owner name in both the Data Buffer and the Key Buffer. The transactional interface requires that the name be in both buffers to avoid accidentally specifying an incorrect value.
If the +17000 bias is not specified, the owner name can be up to 8 bytes long and must end with a binary 0. This is referred to as a “short” owner name. If the +17000 bias is specified, the owner name can be up to 24 bytes long and must end with a binary 0. This is referred to as a “long” owner name. In either case, the owner name cannot consist of all spaces (0x20).
4
Specify the length of the owner name, including the binary 0, in the Data Buffer Length parameter. If the owner name is shorter than the maximum length allowed (either 8 or 24 bytes), the owner name is padded with spaces.
5
Set the Key Number to an integer that specifies the type of access restrictions and encryption for the file. (See Table 26.)
Details
Once you specify an owner name, it remains in effect until you issue a Clear Owner (30) operation. The following table lists the access restriction codes you can specify for the Key Number.
Table 26
Access and Encryption Codes 
Code
Description
  0
Requires an owner name for any access mode (no data encryption).
  1
Permits read-only access without an owner name (no data encryption).
  2
Requires an owner name for any access mode (with data encryption).
  3
Permits read-only access without an owner name (with data encryption).
Result
If the Set Owner operation is successful, the transactional interface prevents future operations from accessing or modifying the file unless those operations specify the correct owner name. The only exception is if read-only access is allowed without an owner name. In addition, if the Set Owner operation is successful, the transactional interface encrypts the data in the file (if encryption is specified).
Encryption occurs immediately; the transactional interface has control until the entire file is encrypted, and the larger the file, the longer the encryption process takes. Reading data from an encrypted file is slower than reading data from an unencrypted file. The transactional interface decrypts a page when it loads the page from the disk, then encrypts the page when it writes to the disk again. If you have a small cache or use a relatively large amount of modification operations, the transactional interface must execute the encryption routine more frequently.
If the Set Owner operation is unsuccessful, the transactional interface returns one of the following status codes:
41
The transactional interface does not allow the attempted operation.
50
The file owner is already set.
51
The owner name is invalid.
Positioning
The Set Owner operation has no effect on positioning.