Integrated File System Scan on Close Exit Program

The integrated file system scan on close exit program is called to do scan processing when an integrated file system object is closed under the following conditions.

The exit program will not be called if:

• No exit programs exist for this exit point.
• -or- the Scan file systems (QSCANFS) system value has *NONE specified so that no file systems will be scanned.
• -or- the object was marked to not be scanned and a scan is not required because the object was restored. (See Note 2)
• -or- the object being closed was opened for write access only.
• -or- the object is being used as a network server storage space or as a virtual volume. From the perspective of the server, these objects appear as byte stream files within the integrated file system.
• -or- the object is not being accessed from a file server, and the Scan file systems control (QSCANFSCTL) system value has *FSVRONLY specified so that only file server accesses are scanned. (See Note 2)
• -or- the object is in a file system that has not completely converted to the *TYPE2 directory format. For information on the *TYPE2 directory format, see the Convert Directory (CVTDIR) command and the Integrated file system information in the Files and file systems topic.

If the previous conditions have been met, the exit program will be called if:

• The object has never been scanned.
• -or- the object's data has been modified since the last time it was scanned. Data modifications include writes, memory map writes, truncates or clears.
• -or- the CCSID of the object has been modified since the last time it was scanned.
• -or- the To CCSID specified on the open request associated with this close is different than the last two To CCSIDs that were specified and previously scanned for this object.
• -or- the object was opened in binary in association with this close request, and it has not previously been scanned in binary.
• -or- there have been updates to the scanning software and the object was not marked to be scanned only if the object changed. (See Note 2) Updates to scanning software occur by either registering additional exit programs for the scan-related exit points, or by calling Change Scan Signature (QP0LCHSG) API to update the scan key signature associated with existing exit program scan keys.

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. Additionally, the From CCSID of the object will be the value it is at the point in time of the close operation while the To CCSID will be reflective of the value specified at open.

For more information on close processing, see close()--Close File or Socket Descriptor. For more information on the scan-related attributes which can be set for objects, see Qp0lSetAttr()--Set Attributes. For more information on the integrated file system scan processing and various options, see the Integrated file system information in the Files and file systems topic.

The exit point supports a maximum of 50 exit programs. For information about adding an exit program to an exit point, see the Registration Facility.

Notes:

1. If the integrated file system exit program returns any error messages or if any errors are received when attempting to call the exit program, the object will be treated as if the program was not called and the object was not scanned. Therefore, the close operation will continue unless the Scan file systems control (QSCANFSCTL) system value has *ERRFAIL specified which will cause the operation to fail. If a scan detects a failure, the close operation will still proceed and complete to release the resources. If the Scan file systems control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation will not return any failure indication. If *NOFAILCLO is not specified, the close operation will fail with error code [ESCANFAILURE].
2. If the oflags specified when the object being closed was opened include the O_FORCE_SCAN value, then one or more of the following conditions will be ignored when determining whether the integrated file system scan-related exit programs will be called:
   • The QSCANFSCTL system value specification of *FSVRONLY.
   • The object was marked to not be scanned (e.g. scan attribute of *NO).
   • The object was marked to be scanned only if the object changed (e.g. scan attribute of *CHGONLY).
   For example, an object is closed that has a scan attribute of *YES, and the close request is not through the file servers when *FSVRONLY is specified. If O_FORCE_SCAN is specified on the open request associated with this close request, the object will be scanned if all the remaining conditions are met. Similarly, if an object that has a scan attribute of *NO or *CHGONLY is closed whose associated open request had O_FORCE_SCAN specified, the object will be scanned if all the remaining conditions are met. See Using the oflag Parameter in open()--Open File for more information on oflags.

Restrictions

• Only objects of type *STMF that are in the "root" (/), QOpenSys, and user-defined file systems that have completely converted to the *TYPE2 directory format are scanned. For information on *TYPE2 directories, see the Convert Directory(CVTDIR) command and the Integrated file system information in the Files and file systems topic.
• The exit programs will not be called during an IPL or the vary-on of an independent Auxiliary Storage Pool (ASP).
• The exit programs will not be called when objects are being closed as a part of a process end request.
• During the call to the exit programs, the ASP group associated with the thread will not be able to be changed.
• 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. If the exit program is not found, the object will be treated as if the program was not called and the object was not scanned. Therefore, the close operation will continue unless the Scan file systems control (QSCANFSCTL) system value has *ERRFAIL specified which will cause the operation to fail. If the Scan file systems control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation will not return any failure indication. If *NOFAILCLO is not specified, the close operation will fail with error code [ESCANFAILURE].
• The exit programs could be called from an exit point within a multi-threaded job and must be written to be threadsafe.

Authorities and Locks

User Profile Authority

*ALLOBJ (all object) and *SECADM (security administrator) special authorities to add exit programs to the registration facility

*ALLOBJ and *SECADM special authorities to remove exit programs from the registration facility

Program Data

When you register the exit program, the following program data must be provided. The following table shows the structure of the program data information. For a description of the fields in this format, see Field Descriptions. This structure is defined in header file qp0lscan.h as data type Qp0l_Scan_Program_Data_t.

Required Parameter Group

Integrated file system close exit information

INPUT; CHAR(*)

Information that is needed by the exit program to do its object scan processing. For details, see Format of Integrated File System Close Exit Information.

Status information

OUTPUT; CHAR(*)

Information that is returned by the exit program indicating what scan processing has occurred. For details, see Format of Status 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 SCCL0100. For a description of the fields in this format, see Field Descriptions. This structure is defined in header file qp0lscan.h as data type Qp0l_Scan_Exit_Information_t.

Format of Status Information (Output)

The following table shows the structure of the status information. For a description of the fields in this format, see Field Descriptions. This structure is defined in header file qp0lscan.h as data type Qp0l_Scan_Status_Information_t.

Field Descriptions

Additional call. Whether the exit program was called an additional time because another Integrated File System Scan on Close Exit Program that was called has indicated the object was modified. See the scan status field for this modify indication. The possible values are:

Call after previous failure. Whether the exit program was called after the object had previously been scanned and a failure detected. The possible values are:

Close scan status information length. The length in bytes of all data returned from the integrated file system close exit program. The only valid value for this field is 10. If anything else is specified, the object will be treated as if the program was not called and the object was not scanned. Therefore, the close operation will continue unless the Scan file systems control (QSCANFSCTL) system value has *ERRFAIL specified which will cause the operation to fail. If the Scan file systems control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation will not return any failure indication. If *NOFAILCLO is not specified, the close operation will fail with error code [ESCANFAILURE].

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

Exit point name. The name of the exit point that is calling the exit program.

Failing CCSID. This field only has meaning if the Call after previous failure field had a value of QP0L_SCAN_YES when the exit program was called, and if the Update object scan information field has a value of QP0L_SCAN_YES, and if the Scan status field has a value of QP0L_SCAN_FAILURE or QP0L_SCAN_FAIL_WANT_MODIFY. When the Call after previous failure had a value of QP0L_SCAN_YES, then the scan exit program should verify that the object does not have any problems when scanned using both the To CCSID and Last failure CCSID values. If either scan fails, then this field should be filled in with the failing CCSID which will be stored as part of the object scan information with the failure indication. If the value of this field does not match either of the two input CCSID fields, then the To CCSID value will be used. If more than one exit program indicates a failure, the failing CCSID value which will be preserved is from the last exit program which scanned the object and indicated a failure. For more information on CCSIDs and conversions, see Coded Character Set Identifier (CCSID) Information in Integrated File System Scan on Open Exit Program.

Note: If the Failing CCSID and From CCSID values match, it is the same as if the object would have been opened in binary.

File ID. A unique identifier associated with the object that is being closed. A file ID can be used with Qp0lGetPathFromFileID()--Get Path Name of Object from Its File ID, to retrieve an object's path name.

File system. The file system that the object being scanned is in. The possible value follows:

From CCSID. The CCSID value that the data is in on the system itself at the point in time of the close operation. Therefore, this will be the CCSID in which data is to be returned (when reading from the object using the Scan descriptor), or the CCSID in which data is being supplied (when writing to the object using the Scan descriptor). For more information on CCSIDs and conversions, see Coded Character Set Identifier (CCSID) Information in Integrated File System Scan on Open Exit Program.

Integrated file system close exit information length. The length in bytes of all data passed to the integrated file system close exit program.

Last failure CCSID. The CCSID value that was specified when this object was last scanned and indicated a scan failure. This field only has meaning if the Call after previous failure field has a value of QP0L_SCAN_YES. Therefore, this would have been the CCSID in which data was to have been returned (when the user was to be reading from the object), or the CCSID in which data was to have been supplied (when the user was to be writing to the object). However, that request failed for this CCSID. This is now being returned so that this CCSID can also be scanned, if it is different than the To CCSID value. For more information on CCSIDs and conversions, see Coded Character Set Identifier (CCSID) Information in Integrated File System Scan on Open Exit Program.

Note: If the Last failure CCSID and From CCSID values match, it is the same as if the object would have been opened in binary.

Length of status information. The length in bytes allocated for the returned status information.

Object modified since last scan. Whether the exit program was called because the objects data or CCSID has been modified since it was last scanned. Examples of object data or CCSID modifications are: writing to the object, directly or through memory mapping; truncating the object; clearing the object; and changing the objects CCSID attribute, etc.. The possible values are:

Object type. The object type. See Control Language (CL) information in the iSeries Information Center for descriptions of all object types.

Oflags. The oflags that were specified on the open request associated with this close request with the following exceptions. For a description of all possible oflag values, see open()--Open a File.

• If the oflags do not contain write access, the system will attempt to upgrade the access intent to include write, unless the Scan file systems control (QSCANFSCTL) system value has *NOWRTUPG specified or the object is not eligible for write access. If the upgrade is not attempted or is unsuccessful, the access intent matches the users invocation. If it is successful, the write access intent is included in this oflag information. This upgrade would be useful if the exit program wanted to modify the object to correct any problems found while scanning.
• The CCSID related flags will have been removed. This includes O_TEXTDATA, O_CCSID, O_CODEPAGE, and O_TEXT_CREATE.
• The synchronization flags will have been removed. This includes O_SYNC, O_DSYNC, and O_RSYNC.

Scan descriptor. A descriptor representing the object that is being closed. This scan descriptor has the following characteristics:

• It can be used to do any read processing on the object being processed. Reads using this descriptor will not update the last access timestamp information for the object.
• It can be used to do any write processing on the object being processed. If write processing is done by the exit program, the exit program should indicate QP0L_SCAN_MODIFY in the Scan status field. If it does not, the object's scan information will be cleared as if the objects data has been modified.
• It cannot be used to memory map the object, see mmap()--Memory Map a File.
• It cannot be used to close the object using close()--Close File or Socket Descriptor. When control returns from the exit program, the system code will do the close of this scan descriptor. The system will wait on this close attempt until all accesses to this object are closed. Therefore, if the exit program uses givedescriptor()--Pass Descriptor Access to Another Job and takedescriptor()--Receive Socket Access from Another Job or sendmsg()--Send Data or Descriptors or Both and recvmsg()--Receive Data or Descriptors or Both to pass the descriptor to another job, the job which used takedescriptor() or recvmsg() must close that descriptor when it is done processing, else the system will be waiting for that close.
• dup()--Duplicate Open File Descriptor and fcntl()--Perform File Control Command with F_DUPFD cannot be used to duplicate the scan descriptor. This is so the system has tight control of the closing of this scan descriptor.
• Data read using this descriptor will be in the From CCSID format. If any data is written using this descriptor, it must be in the From CCSID format. For more information on CCSIDs see Coded Character Set Identifier (CCSID) Information in Integrated File System Scan on Open Exit Program.
• It will be a different descriptor than was specified on the close request.
• The oflags for this descriptor are what are passed on this interface.
• It is scoped to the process. However, one can use givedescriptor() and takedescriptor() or sendmsg() and recvmsg() to pass this descriptor to another job or process. Again, that process must complete its use of that descriptor before control is returned to the system from the exit program because the system will close the descriptor when exit program processing is complete. The system will wait on this close attempt until all accesses to this object are closed.
• No other threads in the process, other than those created by the exit program, will be able to access this descriptor.
• It only lives for the life of the exit program invocation. That is, once control is returned from the exit program, it will be destroyed. Therefore, it cannot be stored for later use.

Scan key. The scan key associated with this exit program. The first character of this scan key can not be hex zeros or a blank. For more information on the scan key, see Scan Key List and Scan Key Signatures in Integrated File System Scan on Open Exit Program.

Scan key signature. The scan key signature associated with the specified scan key. For more information on the scan key signature, see Scan Key List and Scan Key Signatures in Integrated File System Scan on Open Exit Program. If the specified scan key already exists in the scan key list, and the exit program is being added to replace an existing exit program entry, then the specified scan key signature must match the scan key signature associated with the scan key in the scan key list. If the specified scan key already exists in the scan key list, and the exit program is not being added to replace an existing exit program entry, then the specified scan key signature must match the scan key signature associated with the scan key in the scan key list unless the scan key signature associated with the scan key in the scan key list is all hex zeros. More than one exit program, including exit programs associated with the Integrated File System Scan on Open Exit Program, can have the same scan key signature.

Scan signatures different. Whether the exit program was called because the object's current scan key signature is different than the appropriate associated signature. When an object is in an independent ASP group, the object scan signature is compared to the associated independent ASP group scan signature. When an object is not in an independent ASP group, the object scan signature is compared to the global scan signature. The possible values are:

Scan status. The status of the scan processing. This field is only used if the Update object scan information field value specifies a value of QP0L_SCAN_YES. The possible values are:

To CCSID. The CCSID value that was specified on the open request associated with this close request. Therefore, this will be the CCSID in which data was returned (when the user was reading from the object), or the CCSID in which data was be supplied (when the user was writing to the object). Therefore, the exit program should be converting the data to this CCSID since this is how the data was presented to the user after their open request completed. For more information on CCSIDs and conversions, see Coded Character Set Identifier (CCSID) Information in Integrated File System Scan on Open Exit Program.

Note: If the To CCSID and From CCSID values match, it is the same as if the object was opened in binary.

Update object scan information. Whether the scan information associated with the object should be updated or not. The object scan information includes the following:

• Scan status for the object.
• Scan signature associated with the object scan status.
• The To CCSID value of the object which was scanned or if the object was scanned in binary.

  Note: Actually, the last two To CCSID values which have been scanned will be maintained as well as a separate indication of binary scans.

The possible values are:

User profile. 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. If the user profile is not valid or accessible at the time the exit program is called, the object will be treated as if the program was not called and the object was not scanned. Therefore, the close operation will continue unless the Scan file systems control (QSCANFSCTL) system value has *ERRFAIL specified which will cause the operation to fail. If the Scan file systems control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation will not return any failure indication. If *NOFAILCLO is not specified, the close operation will fail with error code [ESCANFAILURE]. The first character of the user profile can not be hex zeros or a blank.

Note: The system will not do any additional verification that this specified profile has authority to the object for which the exit program is being called when that exit program is being called, even when the access levels for the object are upgraded to include write. By registering this exit program, you are indicating this is acceptable.

Usage Notes

1. When the exit program is executing (including any created threads), if it does any operations on other objects which might normally trigger another call to a scan-related exit program, the scan-related exit program will not be called, and it will be treated as if no scanning occurred for the object. For example, if the exit program opens a separate object, that object will not be scanned as part of that open request, even if an exit program is registered to the QIBM_QP0L_SCAN_OPEN exit point. If however, that object has previously failed a scan, then the operation will fail with error code [ESCANFAILURE].
   
   
2. When the exit program is executing (including any created threads), if it does any opens of other objects, then the descriptors which will be returned will come from the same table of descriptors that the Scan descriptor is derived from. Therefore, customer application code will not be impacted by 'regular' descriptors being used and possibly reaching an application specified limit on the number of descriptors which can be used. Additionally, the exit program will not be able to use any of the 'regular' descriptors when it or any of its created threads are executing. That is, it will not be able to access any objects which have been opened outside the scope of the exit program execution. Any attempts to do so will fail with error code [EBADF].
   
   
3. When the following APIs are called from the thread executing the exit program and any of its created threads, the table of Scan descriptors, will not be inherited by the spawned process.
   • spawn()--Spawn Process
   • spawnp()--Spawn Process with Path

   Therefore, when the following APIs are called from the thread executing the exit program and any of its created threads, the descriptors returned by these APIs will only work within the same process.

   • pipe()--Create Interprocess Channel
   • Qp0zPipe()--Create Interprocess Channel with Sockets()
   
   
4. When the exit programs are executing (including any created threads), signals are blocked from being delivered to a thread. When a signal is blocked, the signal-handling action associated with the signal is not taken. The signal remains pending until all exit programs have completed execution. For more information, see Signal concepts.
   
   
5. When the following APIs are called from the thread executing the exit program and any of its created threads, they will fail with the listed error code.
   • DosSetFileLocks()--Lock and Unlock a Byte Range of an Open File-- [ENOTSUP]
   • DosSetFileLocks64()--Lock and Unlock a Byte Range of an Open File (Large File Enabled)-- [ENOTSUP]
   • DosSetRelMaxFH()--Change maximum number of file descriptors -- [ERROR_GEN_FAILURE]
   • dup2()--Duplicate Open File Descriptor to Another Descriptor -- [ENOTSUP]
   • fcntl()--Perform File Control Command with F_SETLK, F_SETLK64, F_SETLKW or F_SETLKW64 -- [ENOTSUP]
   • recvmsg()--Receive Data or Descriptors or Both-- [ENOTSUP]
   • socketpair()--Create a Pair of Sockets-- [ENOTSUP]
   • takedescriptor()--Receive Socket Access from Another Job -- [ENOTSUP]
     
     
6. Unpredictable results will occur if the select()--Wait for events on multiple sockets or poll()--Wait for events on multiple descriptors APIs and any of their associated type and macro definitions are used in the thread executing the exit program and any of its created threads. Therefore, these interfaces should not be used under these conditions.
   
   
7. It is recommended that the exit program use the large-file enabled APIs such as lseek64()--Set File Read/Write Offset (Large File Enabled) to work with the scan descriptor as these APIs will work with any size object.
   
   
8. If Kerberos is configured on the system, then the thread executing the exit program and any of its created threads will not be able to access objects in any file systems which use Kerberos for authentication. If they do, the operation will fail with error code [ENOTSUP]. E.g. the exit program cannot access objects in the QFileSvr.400 file system when Kerberos is configured.
   
   
9. The exit program should not call the open or close API interfaces on the object represented by the scan descriptor. If this is done from the thread executing the exit program, then [EDEADLK] will be returned. If the object is opened or closed from any other process or thread, that process or thread will wait until this invocation's scan is completed.

Related Information

• The <qp0lscan.h> file (see Header Files for UNIX-Type Functions)
• Change Scan Signature (QP0LCHSG) API
• Integrated File System Scan on Open Exit Program
• Qp0lGetAttr()--Get Attributes
• Qp0lSetAttr()--Set Attributes
• Retrieve Scan Signature (QP0LRTSG) API
• Retrieve System Values (QWCRSVAL) API