Integrated File System Scan on Open Exit Program


  Required Parameter Group:


  QSYSINC Member Name: QP0LSCAN

  Exit Point Name: QIBM_QP0L_SCAN_OPEN

  Exit Point Format Name: SCOP0100

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:

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

For more information about 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 about the integrated file system scan processing and various options, see the Integrated file system topic collection

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

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


Restrictions


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 about 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 about 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 about 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 the Control language topic collection 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.

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:

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 about 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 about 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:

If a value other than the possible values 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.

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 about 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:

The possible values are:

If a value other than the possible values is specified, a value of QP0L_SCAN_NO is assumed.

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:

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:

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 about CCSIDs and conversions, see open()--Open a File and the i5/OS globalization topic collection.


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.

    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.

  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

Exit program introduced: V5R3

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