Integrated File System Close Exit Program
Required Parameter Group:
| 1 | Integrated file system close exit information | Input | Char(*) |
QSYSINC Member Name: QP0LSTDIO
Exit Point Name: QIBM_QP0L_OBJ_CLOSE
Exit Point Format Name: OBCL0100
The integrated file system close exit program is called to perform user processing after an integrated file system object is closed 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.
Note: If there are multiple descriptors referencing the same open instance of the object, then the exit program will only be called for the close request on the last descriptor.
For more information about close processing, see close()--Close File or Socket Descriptor. For more information on the close-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 closed 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 close exit information
- INPUT; CHAR(*)
Information that is needed by the exit program to do its processing. For details, see Format of Integrated File System Close Exit Information.
Format of Integrated File System Close Exit Information (Input)
The following table shows the structure of the integrated file system close exit information for exit point format OBCL0100. 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 close exit program. The possible format name follows:
| OBCL0100 | The format name that is used while an object is being closed. |
File identifier. The 16-byte file identifier of the object being closed. This value can be used to uniquely identify an object that is no longer linked when it is closed.
Object path. The absolute path of the object being closed. 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 associated with the file descriptor that was just closed. 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.
Usage Notes
- The user must be authorized to perform any operations required by the exit program.
- Because one of the primary purposes of the close exit program is to clean up any resources acquired or created by open exit programs, all close exit programs will be called in most circumstances, regardless of whether the file system close was successful, whether the exit program call itself fails (program not found, user not authorized to the program, or similar error), or whether an exit program experiences a failure.
- A diagnostic message will be sent to the job log for certain failures during exit point processing. However, there is no error reporting mechanism (such as a return code or message) for failures experienced by the exit program itself. It is the responsibility of the close exit program to report failures appropriately.
- If an exit program opens and closes 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.
- If the object being closed was previously unlinked from its parent directory, no path can be supplied to the exit program. The supplied Object path length will be zero. The File identifier can be used to uniquely identify the object in this case.
- If an exit program is registered to the QIBM_QP0L_SCAN_CLOSE exit point and that exit program is eligible to be called, that exit program will run before 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 close. If this user profile swap fails, no further exit programs are called.
- The exit programs will not be called when objects are being closed as a part of a process end request.
- 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 when it was opened. 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 Open Exit Program
- Qp0lGetAttr()--Get Attributes
- Qp0lSetAttr()--Set Attributes
Exit program introduced: V7R5
