Open Stream File (QHFOPNSF) API


  Required Parameter Group:

1 Open file handle Output Char(16)
2 Path name Input Char(*)
3 Path name length Input Binary(4)
4 Open information Input Char(10)
5 Attribute information table Input Char(*)
6 Length of attribute information table Input Binary(4)
7 Action taken Output Char(1)
8 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: No

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

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:

Deny Read/Write Access to the file is exclusive for the current job. The current job can perform additional open operations on the file. However, no other job can open the file in any lock mode until the current job either closes it or ends.
Deny Write Other jobs can read but cannot write to the file. In other words, no other job can open the file with write access; the file must be closed first, or the current job must end.
Deny Read No other job can read the file until the current job either closes it or ends.
Deny None Other jobs can read and write to the file. However, they cannot delete, rename, move, or change the attributes of the file until the current job either closes it or ends.


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:

1st Open Operation (by your job) 2nd, 3rd, 4th Open Operation (by other jobs)
Lock Mode Access Mode Deny Read/Write Deny Write Deny Read Deny None
R/O R/W W/O R/O R/W W/O R/O R/W W/O R/O R/W W/O
Deny Read/ Write R/O N N N N N N N N N N N N
R/W N N N N N N N N N N N N
W/O N N N N N N N N N N N N
Deny Write R/O N N N Y N N N N N Y N N
R/W N N N N N N N N N Y N N
W/O N N N N N N Y N N Y N N
Deny Read R/O N N N N N Y N N N N N Y
R/W N N N N N N N N N N N Y
W/O N N N N N N N N Y N N Y
Deny None R/O N N N Y Y Y N N N Y Y Y
R/W N N N N N N N N N Y Y Y
W/O N N N N N N Y Y Y Y Y Y
Key:

Y Open is allowed
N Open is denied
R/W Read/write
R/O Read only
W/O Write only



Error Messages

Message ID Error Message Text
CPF1F01 E Directory name not valid.
CPF1F02 E Directory not found.
CPF1F06 E Directory in use.
CPF1F07 E Authority not sufficient to access directory.
CPF1F08 E Damaged directory.
CPF1F2A E Number of open files exceeds limit.
CPF1F21 E File name not valid.
CPF1F22 E File not found.
CPF1F24 E File name already exists.
CPF1F26 E File in use.
CPF1F27 E Authority not sufficient to access file.
CPF1F28 E Damaged file.
CPF1F29 E Use of reserved file name not allowed.
CPF1F37 E File is a read-only file.
CPF1F41 E Severe error occurred while addressing parameter list.
CPF1F42 E Attribute information table not valid.
CPF1F43 E Attribute name not valid.
CPF1F44 E Attribute value is not valid.
CPF1F46 E Use of reserved attribute name not allowed.
CPF1F48 E Path name not valid.
CPF1F49 E Open information value not valid.
CPF1F52 E Error code not valid.
CPF1F61 E No free space available on media.
CPF1F62 E Requested function failed.
CPF1F63 E Media is write protected.
CPF1F66 E Storage needed exceeds maximum limit for user profile &1.
CPF1F71 E Exception specific to file system occurred.
CPF1F72 E Internal file system error occurred.
CPF1F73 E Not authorized to use command.
CPF1F74 E Not authorized to object.
CPF1F75 E Error occurred during start-job-session function.
CPF1F81 E API specific error occurred.
CPF1F82 E Function not supported.
CPF1F83 E File system name &1 not found.
CPF1F85 E Not authorized to file system &1.
CPF1F87 E Missing or damaged exit program &2.
CPF1F97 E File system &1 in use.
CPF3C90 E Literal value cannot be changed.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R1

[ Back to top | Hierarchical File System APIs | APIs by category ]