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 MicroKernel Engine to encrypt the file’s data on the disk. If you specify data encryption, the MicroKernel Engine encrypts all the data during the Set Owner operation. Therefore, the longer the file, the longer Set Owner takes to complete.


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

•

The file must be open.

•

No transactions can be active.

•

The file cannot already have an owner name.

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 SDK.

•

Once a long owner name is set, PSQL database engines earlier than v10.10 cannot read the data file.

•

The data file cannot be rebuilt to a file format before v9.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 MicroKernel Engine requires that the name be in both buffers to avoid accidentally specifying an incorrect value.

If the +17000 bias is not set, 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 set, 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

Set 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 27.)

Note: If the owner name is long and you select a key number that encrypts data in the file, then 128-bit encryption is used, which is stronger than that used for files with short owner names.

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 set for the key number.

Table 27

Access and Encryption Codes

Requires an owner name for any access mode (no data encryption).

Permits read-only access without an owner name (no data encryption).

Requires an owner name for any access mode (with data encryption).

Permits read-only access without an owner name (with data encryption).

If the Set Owner operation is successful, the MicroKernel Engine 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 MicroKernel Engine encrypts the data in the file (if encryption is specified).

Encryption begins immediately. The MicroKernel Engine 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 MicroKernel Engine 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 MicroKernel Engine must execute the encryption routine more frequently.

If the Set Owner operation is unsuccessful, the MicroKernel Engine returns one of the following status codes:


41	The MicroKernel Engine does not allow the attempted operation.
50	The file owner is already set.
51	The owner name is invalid.

The Set Owner operation has no effect on positioning.