Start of changeIntegrated File System Open Exit Program

  Required Parameter Group:


  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.

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.


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

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

The valid values are:

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.

Field Descriptions

Exit point format name. The format name for the integrated file system open exit program. The possible format name follows:

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

  1. 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.
  2. The user must be authorized to perform any operations required by the exit program.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. 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

Exit program introduced: V7R5 End of change

[ Back to top | UNIX-Type APIs | APIs by category ]