Open (0)

The Open operation (B_OPEN) makes a file available for access. To access a file, your application must first perform an Open operation. The file does not have to reside in the current directory as long as you specify the full or relative pathname.

The transactional interface normally expands the file name to a fully-qualified UNC file name. For example, J:\Data\File.dat would be converted to \\Servername\ShareName\Data\File.dat. This expanded name must file into 255 bytes including the null terminator.

However, if the Btrieve Open request is sent to a local engine, the MIF will not replace the local drive letter with the computer name and share name. Even though you may get by with a longer path name if opened locally, remote clients may not be able to open the file.

Pervasive.SQL 2000 added support for long pathnames with spaces based on a client configuration option, "Embedded Spaces". By default, this configuration parameter is set to Off, which means spaces maybe be considered a delimiter. With this parameter set to On, spaces are considered part of the path, and a null byte must delimit the filename.

For more information about path names transactional interface supports, refer to Getting Started With Pervasive PSQL.

This section describes the open modes that are supported.

---

Caution
The database engine cannot guarantee transaction atomicity, transaction durability, or archival log safety for any client during use of Accelerated mode by any client. The reason for this restriction is that in the event a restore from log is needed, the log may not contain adequate information to complete the restore, because it is only a partial record of operations on a data file.

For example, if a system failure occurs while the same file is being accessed by a client performing inserts using Accelerated mode and a client performing updates using Normal mode, it is possible for the transaction log to contain updates to records that do not yet exist in the data files, because the Accelerated insert operation in memory was never flushed to disk, while the transactional update operation was written to the transaction log.

An attempt to roll forward an archival log containing this combination of operations will fail.

---

When you open a file, you can instruct the transactional interface through the open mode to use either a local or remote engine. You specify the open mode in the Key Number parameter.

---

Note
The Open operation makes no distinction between workstation, workgroup, and server engines when you specify that the local engine should open the file.

---

The transactional interface allows a maximum of 250 open files, but you might be unable to open that many files due to limitations on system resources.

A file is opened only once by the transactional interface. (The transactional interface recognizes and handles the situation in which more than one client at a time opens a file, or a single client has more than one Position Block in the file.) When you open an extended file, the transactional interface uses a single handle, and opens the base file and all extension files.

---

Note
When the NetWare server transactional interface opens an extended file, it enforces NetWare security on the base file, but not on the extension files. In the rare event that a user has NetWare rights to a base file, but not the extension files, NetWare security can be violated. For workstation engines, NetWare does enforce security; therefore, such a user would not have access to the extension files.

---

If the Open operation is successful, the transactional interface assigns a file handle to the file, reserves the Position Block passed on the Open call for the newly opened file, and makes the file available for access.

If the Open operation is unsuccessful, the transactional interface returns one of the following status codes:

The following tables show the possible combinations for open modes involving local clients.

Table 2-18 shows open modes involving local clients.

An Open operation does not establish any positioning except that the physical next record becomes the first physical record of the file.