Integrated File System Scan on Open Exit Program

The integrated file system scan on open exit program is called to do scan processing when an integrated file system object is opened 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 is being opened for write access only.
• -or- the object is being truncated as part of the open request.
• -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 is different than the last two To CCSIDs that were specified and previously scanned for this object.
• -or- the object is being opened in binary, 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.

For more information on open processing, as well as CCSID values, see open()--Open File. 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 open operation will continue unless the QSCANFSCTL system value has *ERRFAIL specified which will cause the operation to fail.
2. If the oflags specified when the object 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 opened that has a scan attribute of *YES, and the open request is not through the file servers when *FSVRONLY is specified. If O_FORCE_SCAN is specified on that open 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 opened with 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).
• 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 open operation will continue unless the Scan file systems control (QSCANFSCTL) system value has *ERRFAIL specified which will cause the operation to fail.
• 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 open 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 Open 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 Open Exit Information (Input)

The following table shows the structure of the integrated file system open exit information for exit point format SCOP0100. 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 Open 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:

Exit point format name. The format name for the integrated file system scan on open 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.

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 opened. 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. 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.

Integrated file system open exit information length. The length in bytes of all data passed to the integrated file system open 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.

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 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.

Open scan status information length. The length in bytes of all data returned from the integrated file system open 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 open operation will continue unless the Scan file systems control (QSCANFSCTL) system value has *ERRFAIL specified which will cause the operation to fail.

Scan descriptor. A descriptor representing the object that is being opened. 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.
• It will be a different descriptor than will actually be returned to the user, if the open is ultimately successful.
• 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

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. 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 Close 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. Therefore, this will be the CCSID in which data will be returned (when the user will be reading from the object), or the CCSID in which data will be supplied (when the user will be writing to the object). Therefore, the exit program should be converting the data to this CCSID since this is how the data will be presented to the user if the open request completes successfully. For more information on CCSIDs and conversions, see Coded Character Set Identifier (CCSID) Information.

Note: If the To CCSID and From CCSID values match, it is the same as if the object will be 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 open operation will continue unless the Scan file systems control (QSCANFSCTL) system value has *ERRFAIL specified which will cause the operation to fail. 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.

Scan Key List and Scan Key Signatures

A list of scan keys and associated scan key signatures will be used to help minimize unnecessary scan calls, while allowing users to ensure scans occur when needed. The scan key list and scan key signature will allow an association of scanning software level with the various scan-related exit programs (Integrated File System Scan on Close Exit Program and Integrated File System Scan on Open Exit Program). Updates to this information will allow the system to increment its global scan signature field to reflect the software updates.

The system will maintain a global scan signature field and independent ASP group scan signature fields. Each integrated file system object which supports scanning will have an object scan signature field.

The global scan signature indicates the state or level of the scanning software. It will or will not be modified under the following rules:

• When the scan-related exit programs are added or registered, the user specifies a scan key and a scan key signature. These values are added to the scan key list. If the scan key has previously been specified, e.g. for a different exit program registration, then the global scan signature will only be incremented if the specified scan key signature is not hex zero. If the scan key has not previously been specified, and the scan key signature is not a hex zero value, the global scan signature will be incremented.
• By calling the Change Scan Signature (QP0LCHSG) API to specify that a new scan key signature be associated with a specific scan key. This will cause the system to update the scan key list and increment the current global scan signature value.
• When the scan-related exit programs are removed, the user specifies a scan key and a scan key signature. These values are removed from the scan key list if no other scan-related exit programs are registered that have that scan key. Removing entries from the scan key list does not update the global scan signature.

The independent ASP group scan signature indicates the state of the scanning software as well. Since it moves with the independent ASP group, it represents the state of the scanning code software in relationship to when and where that independent ASP group was varied on. The independent ASP group scan key list and independent ASP group scan signature will or will not be modified under the following rules:

• If the independent ASP group is available and online, the independent ASP group scan key list will be updated whenever the system scan key list is updated. Any changes to the independent ASP group scan key list will cause the independent ASP group scan signature to be incremented under the same rules as to when the global scan signature is updated.
• If the independent ASP group is varied on after any global scan key list changes, then when the first scannable integrated file system object on the independent ASP group is opened or its scan information is retrieved, the independent ASP group scan key list will be compared to the global scan key list.
  • If the global scan key list has more scan keys or different scan key signatures than the independent ASP group scan key list has, then the independent ASP group scan list will be updated to match. Additionally, the independent ASP group scan signature will be incremented.
  • If the global scan key list is a proper subset of the scan keys and scan key signatures in the independent ASP group scan key list, then the independent ASP group scan list will be updated to match. However, the independent ASP group scan signature will not be incremented. If the global scan key list exactly matchs the scan keys and scan key signatures in the independent ASP group scan key list, then no changes are made.

It is highly recommended that the scanning software level of support which is indicated by scan keys and scan key signatures be maintained the same across all systems in the independent ASP Cluster group. See Cluster for more information.

When an object in an independent ASP group is about to be scanned or its scan information is retrieved, the object scan signature will be compared to the associated independent ASP group scan signature. When an object is not in an independent ASP group, the object scan signature will be compared to the global scan signature value.

When an object is successfully scanned, the object scan signature will be updated to match the global scan signature or independent ASP group scan signature when scanning was begun as appropriate. Other associated fields will be updated as well as described in Update object scan information.

Coded Character Set Identifier (CCSID) Information

The CCSID values presented on this interface have the following meanings and inter-relationships. The From CCSID represents the value for the data that is stored in the object. Therefore, when discussing reading and writing in the From CCSID format, it means the data is read or written as is, no conversion occurs between what is given to or returned by the system, and the data in the object itself. The scan descriptor that is passed to the exit program is not an open instance which provides CCSID conversion. But, when the object is ultimately opened, the file descriptor that is returned will include conversion using the value in To CCSID. If the To CCSID and From CCSID values match, it is the same as if the object would have been opened in binary. If the object is not being opened in binary, the scan exit program should do its scanning using the To CCSID value, and can use the appropriate APIs to do the conversion. If the scan succeeds or fails, then the CCSID which is preserved with the scan status information is the To CCSID, except for the following case. If the Call after previous failure field has a value of QP0L_SCAN_YES, and the value in the Last Failure CCSID is different than To CCSID, then the scan exit program should also scan the object data using the Last Failure CCSID. In this case, if the scan succeeds, then the CCSID which is preserved with the scan status information is the To CCSID. If the scan fails, then the CCSID which is preserved with the scan status information is the Failing CCSID.

For more information on CCSIDs and conversions, see open()--Open a File and Globalization topic.

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 Close Exit Program
• Qp0lGetAttr()--Get Attributes
• Qp0lSetAttr()--Set Attributes
• Retrieve Scan Signature (QP0LRTSG) API
• Retrieve System Values (QWCRSVAL) API