Set Owner (29)

The Set Owner operation (B_SET_OWNER) assigns an owner name to a file, so that users who do not provide the name cannot access or modify the file. If an owner name has been set for a file, users or applications must specify the owner name each time they open 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

Set the Operation Code to 29.

Pass the Position Block that identifies the file to protect.

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. The owner name can be up to eight characters long and must end with a binary 0. The owner name cannot consist of all spaces (0x20).

Specify the length of the owner name, including the binary 0, in the Data Buffer Length parameter.

Set the Key Number to an integer that specifies the type of access restrictions and encryption for the file. (See Table 2-19.)

Details

Once you specify an owner name, it remains in effect until you issue a Clear Owner operation. The following table lists the access restriction codes you can specify for the Key Number.

Table 2-19 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.