Open Stream File (QHFOPNSF) API

The Open Stream File (QHFOPNSF) API opens and optionally creates a single stream file. Applications can use the QHFOPNSF API to perform these tasks:

• Open an existing file.
  
  
• Open and replace an existing file. (You cannot perform this operation on read-only files)
  
  
• Create a new file and open it.
  
  
• Return an error if the specified file exists.
  
  
• Return an error if the specified file does not exist.
  
  

Do not use the QHFOPNSF API to change the directory entry attributes for an existing file. Instead, see Change Directory Entry Attributes (QHFCHGAT) API.

When the file is opened, the file pointer is set to the first byte of the file (position 0). Subsequent read/write operations move or increase the value of the file pointer. To move it explicitly, see Change File Pointer (QHFCHGFP) API.

Authorities and Locks

None.

Required Parameter Group

Open file handle

OUTPUT; CHAR(16)

An identifier made up of arbitrary characters assigned by the API and used to refer to the file in subsequent operations.

Path name

INPUT; CHAR(*)

The path name for the file. The last element of the path name is the file name.

Path name length

INPUT; BINARY(4)

The length of the path name, in bytes.

Open information

INPUT; CHAR(10)

Whether or not to open the file, and what the opened file's characteristics are. Each character of this parameter has a specific meaning. The characters and their meanings are:

1	The action to take if the file already exists. Valid values are: 0 Do not open the file. Return an error. 1 Open the file. When an existing file is opened and the file size is extended, the file system might not define the value of the new bytes. 2 Replace the existing file. This is equivalent to deleting and re-creating the file. The directory entry information is replaced.
2	The action to take if the file does not exist. Valid values are: 0 Return an error. 1 Create the file.
3	The write-through flag for the file. Valid values are: 0 Write operations to nonvolatile storage can be asynchronous. (Nonvolatile storage is any storage area whose contents are not lost when power is cut off or when the system is loaded.) An asynchronous write operation returns control to the application immediately, so it can continue the operation. The write operation occurs at a later, unspecified time. 1 Write operations to nonvolatile storage must be synchronous. A synchronous write operation returns control to the operation only after the write operation completes.
4	Reserved. This field must be blank.
5	The file's lock mode. The lock mode defines what operations other jobs can perform on the file. Valid values are: 1 Deny None 2 Deny Write 3 Deny Read 4 Deny Read/Write (exclusive) For a detailed description of lock modes, see Lock and Access Modes.
6	The file's access mode, indicating the application's access rights to the file. Valid values are: 0 Read Only 1 Write Only 2 Read/Write For a detailed description of access modes, see Lock and Access Modes.
7	The type of open operation to perform. Valid values are: 0 Normal 1 Permanent. The file can be closed in only two ways: explicitly with the QHFCLOSF API, described in Close Stream File (QHFCLOSF) API, or implicitly when the job ends. The End Request (ENDRQS) and Reclaim Resource (RCLRSC) commands do not close the file.
8-10	Reserved. These characters must be blank.

Attribute information table

INPUT; CHAR(*)

The table specifying the attributes of the directory entry for this file. The file system determines which standard and extended attributes you can specify. For detailed descriptions of the standard attributes and the format of the table, see HFS Attribute Information Table.

Use this parameter only when creating a new file or replacing an existing file. It is ignored when opening an existing file.

Length of the attribute information table

INPUT; BINARY(4)

The length of the attribute information table, in bytes, or a special value indicating which attributes to use. Valid values are:

length	Use the attributes contained in the attribute information table.
0	Use the system defaults for standard attributes.

Action taken

OUTPUT; CHAR(1)

One of these values, indicating the action taken by the file system:

1	The file already existed and was not replaced.
2	The file did not exist and was created.
3	The file already existed and was replaced.

Error code

I/O; CHAR(*)

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

Lock and Access Modes

Lock and access modes determine which operations jobs can perform on files. The following sections describe lock and access modes in detail.

Lock Modes

The lock mode determines the type of access your job lets other jobs have to the file. For example, if other jobs can continue reading a file but cannot write to it without impeding your job, specify deny write. This lock mode lets other jobs read the file but keeps them from writing to it.

When you assign a lock mode, it applies only to that specific occurrence of the file being opened. The lock mode you specified when opening a stream file restricts open operations by other jobs only; it does not restrict additional open operations by the job that locked the file.

A file can be opened multiple times by different jobs as long as the lock modes specified on the open operations are compatible.

Any locks placed on a file opened with the QHFOPNSF API are removed when the file is closed with the Close Stream File (QHFCLOSF) API or when the job ends.

The lock modes you can specify when opening a file are:

Access Modes

The access mode characteristic determines the type of access your job needs to the file. For example, if your job requires read/write access and another job has already opened the file with a lock mode of deny none, your open request succeeds. However, if another job opened the file with a lock mode of deny write, your job is denied access.

The following table shows the results of opening and then trying to reopen the same file using all combinations of access and lock modes:

Error Messages