Open Directory (QHFOPNDR) API

The Open Directory (QHFOPNDR) API opens the specified directory so its directory entries can be read. At open time, the directory pointer points to the first entry in the directory. As directory entries are read using the Read Directory Entries (QHFRDDR) API, the directory pointer advances so that the next entries will be read during future read operations.

Opening a directory can help streamline information retrieval and protect the directory. For example, you might open a directory to:

• Improve performance when obtaining information from more than one directory entry.
  
  
• Prevent the directory from being renamed or deleted. A deny none lock mode lets other processes read or change the contents of the directory, but keeps them from renaming or deleting the directory itself.
  
  
• Prevent the contents of the directory from being changed. A deny write lock mode keeps other processes from adding to or otherwise changing the open directory's contents. Directories and files cannot be created in the directory until it is closed.

Authorities and Locks

None.

Required Parameter Group

Directory handle

OUTPUT; CHAR(16)

An identifier made up of arbitrary characters returned by the API and used to identify the directory for subsequent operations, such as reading and closing.

Path name

INPUT; CHAR(*)

The path name for the directory being opened. The path and directory must exist.

For the directory name (the last element of the path name), you can use either a specific name or a generic name.

If the last element in the path is a specific name, that directory is opened and all directory entries in the directory are available for subsequent read operations.

If the last element in the path is a generic name, it identifies the directory entries to make available for subsequent read operations; the previous name in the path specifies the directory to open. Directory entries that are in the directory to open and that match the generic name are made available.

You can use these special matching characters in generic names:

*	An asterisk stands for zero or more characters. You can use it anywhere in a string.
?	A question mark at the end of a string represents zero or one character. A question mark embedded in a string represents one character.

For example, /QDLS/BUSY/DEPT* indicates all directories and files that have names beginning with DEPT and that are located in directory BUSY in the QDLS file system.

Path name length

INPUT; BINARY(4)

The length of the path name, in bytes.

Open information

INPUT; CHAR(6)

Information about the type and mode of the open operation. The characters and their meanings are:

1	The lock mode, indicating what other jobs can do to the directory. Valid values are: 0 No lock. Other jobs can read, change, rename, or delete the directory. 1 Deny none. Other jobs can read or change directory entries, but they cannot rename or delete the directory. 2 Deny write. Other jobs can read the contents of the directory, but they cannot change, rename, or delete it.
2	The type of open operation to perform. Valid values are: 0 Normal. 1 Permanent. The directory can be closed in only two ways, explicitly by the Close Directory (QHFCLODR) API, or implicitly, when the job ends. End request and reclaim resource operations do not close the directory.
3-6	Reserved. These characters must be blank.

Attribute selection table

INPUT; CHAR(*)

The table specifying which attributes are available when reading directory entries. The file system determines which standard and extended attributes you can specify. For detailed descriptions of the standard attributes, see HFS Directory Entry Attributes. For the format of the table, see HFS Attribute Selection Table.

This parameter lets you choose which attributes of the directory entries are available for reading when the directory is open. It does not determine which directory entries can be read. Use the path name parameter to select the directory entries you want to read.

Length of the attribute selection table

INPUT; BINARY(4)

The length of the table, in bytes, or a special value indicating which attributes are made available. Valid values are:

length	The attribute selection table parameter contains the attributes the application wants to make available.
0	Only the standard attribute QNAME is available.
-1	All attributes are available.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Error Messages