Integrated File System Open Exit Program
Required Parameter Group:
| 1 | Integrated file system open exit information | Input | Char(*) |
| 2 | Return Code | Output | Binary(4) |
QSYSINC Member Name: QP0LSTDIO
Exit Point Name: QIBM_QP0L_OBJ_OPEN
Exit Point Format Name: OBOP0100
The integrated file system open exit program is called to perform user processing when an integrated file system object is opened under the following conditions.
- An exit program is registered for this exit point.
- The QP0L_ATTR_RUNEXIT attribute of the object is QP0L_RUNEXIT_YES.
If no open exit program is registered, the file system will attempt to open the object, regardless of the value of the QP0L_ATTR_RUNEXIT attribute.
For more information about open processing, see open()--Open File. For more information on the open-exit-related attributes which can be set for objects, see Qp0lSetAttr()--Set Attributes.
The exit point supports a maximum of 10 exit programs. For information about adding an exit program to an exit point, see Registration Facility APIs.
Restrictions
- Only the "root" (/), QOpenSys, user-defined, and QDLS file systems support a QP0L_ATTR_RUNEXIT attribute value of QP0L_RUNEXIT_YES. For information about file systems, see the Integrated file system topic collection.
- The exit programs must exist in the system ASP or in a basic user ASP. They cannot exist in an independent ASP. Any ASP group could be associated with the thread when the exit program is called.
- The exit programs could be called from an exit point within a multi-threaded job and must be written to be threadsafe.
- In order to provide a path to an exit program, the user must have a minimum of *X authority to the object being opened and *RX authority to each directory in the path name preceding the object. If the user does not have the required authority, no exit programs will be called.
Authorities and Locks
- User Profile Authority
- *ALLOBJ (all object) and *SECADM (security administrator) special authorities to add exit programs to or remove exit programs from the registration facility
Required Parameter Group
- Integrated file system open exit information
- INPUT; CHAR(*)
Information that is needed by the exit program to do its processing. For details, see Format of Integrated File System Open Exit Information.
- Return code
- OUTPUT; BINARY(4)
The valid values are:
- 0
- The open should be accepted. The next exit program will be called or the open request will continue if there are no other exit programs. This is the default action.
- Any other value
- The open request should be rejected. No other exit programs will be called and the open operation will fail with EPERM.
Format of Integrated File System Open Exit Information (Input)
The following table shows the structure of the integrated file system open exit information for exit point format OBOP0100. For a description of the fields in this format, see Field Descriptions. This structure is defined in header file qp0lstdi.h as data type Qp0l_Open_Close_Exit_Info_t.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User profile name |
| 10 | A | CHAR(8) | Exit point format name |
| 22 | 16 | CHAR(10) | Object type |
| 18 | 12 | BINARY(4) | Open flags |
| 32 | 20 | CHAR(16) | File identifier |
| 48 | 30 | BINARY(4) | Object path length |
| 52 | 34 | CHAR(*) | Object path |
Field Descriptions
Exit point format name. The format name for the integrated file system open exit program. The possible format name follows:
| OBOP0100 | The format name that is used while an object is being opened. |
File identifier. The 16-byte file identifier of the object being opened. This value can be used to uniquely identify an object that is unlinked before it is closed.
Object path. The absolute path of the object being opened. The object path is supplied in CCSID 1200. The components of the path are delimited with slash (/) characters (hexadecimal 002F).
Object path length. The length of the object path. The maximum path length that can be supplied is 16711512 bytes. If the object path cannot be determined, this value will be zero.
Object type. The object type. See the Control language topic collection for descriptions of all object types.
Open flags. The open flags that were specified on the open request. For a description of all possible open flag values, see open()--Open a File.
User profile name. The exit program will be called under this user profile. Therefore, this user profile should have *USE authority to the exit program, and *EXECUTE authority to the exit program library.
Note: The system will not do any additional verification that this specified profile has authority to the object for which an exit program is being called.
Usage Notes
- The system will attempt to call all registered exit programs prior to the object being opened by the file system. Any error invoking an exit program, such as an authority error or the program not existing, will prevent any following exit programs from running. The open will fail with an appropriate error.
- The user must be authorized to perform any operations required by the exit program.
- If the Return code is set to a non-zero value by an exit program, then no further exit programs will be called and the open operation will fail with EPERM.
- If all exit programs complete successfully, the file system open will be performed. This open will run under the original signed-on user, even if one of the exit programs swapped users.
- Even if all exit programs complete successfully, the file system open may fail and report an error. Because file system close processing cannot occur if the file system open fails, close exit programs will not be able to release any resources acquired by open exit programs.
- If an exit program opens a file system object, the same exit program might be called again. It is the responsibility of the exit program to avoid unwanted recursion.
- Because the object path is in CCSID 1200, you will need to use NLS-enabled APIs such as Qp0lGetAttr()--Get Attributes to perform operations on the object or you will need to convert the path to job CCSID for use with other APIs and commands.
- An exit program can unlink the object from its parent directory. This will not prevent the open from succeeding and will not prevent the path from being supplied to subsequent open exit programs. The object will not be removed from the system until the object is closed. However, the path cannot be supplied to the exit programs called at the time the object is closed. The File identifier can be used to correlate a closed object with an opened object.
- If an exit program is registered to the QIBM_QPWFS_FILE_SERV exit point, that exit program will run before any exit programs registered to this exit point when a file is opened through the file server.
- If an exit program is registered to the QIBM_QP0L_SCAN_OPEN exit point and that exit program is eligible to be called, that exit program will run after all exit programs registered to this exit point.
- If an exit program swaps to a different user profile, the exit program processor will swap back to the original user profile before calling the next exit program or returning to the process performing the open. If this user profile swap fails, no further exit programs are called.
- If an object is linked into more than one directory, the path that is passed to the exit program might not be the path that was used to navigate to the object. Therefore, the user might require *RX authority to directories other than those that were used to navigate to the object.
Related Information
- The <qp0lstdio.h> file (see Header Files for UNIX®-Type Functions)
- Integrated File System Close Exit Program
- Qp0lGetAttr()--Get Attributes
- Qp0lSetAttr()--Set Attributes
Exit program introduced: V7R5
