Integrated File System Scan on Close Exit Program

Required Parameter Group:

Integrated file system close exit information

Input

Char(*)

Status information

Output

Char(*)

  QSYSINC Member Name: QP0LSCAN

  Exit Point Name: QIBM_QP0L_SCAN_CLOSE

  Exit Point Format Name: SCCL0100

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 about the *TYPE2 directory format, see the Integrated file system topic collection.

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

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].
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 about 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 about *TYPE2 directories, see the Integrated file system topic collection.
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.

Offset

Type

Field

Dec

Hex

Char(10)

User profile

Char(20)

Scan key

Char(12)

Scan key signature

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.

Offset

Type

Field

Dec

Hex

BINARY(4)

Integrated file system close exit information length

CHAR(20)

Exit point name

CHAR(8)

Exit point format name

BINARY(4)

Length of status information

BINARY(4)

Scan descriptor

BINARY(4), UNSIGNED

From CCSID

BINARY(4), UNSIGNED

To CCSID

BINARY(4), UNSIGNED

Last failure CCSID

BINARY(4)

Oflags

CHAR(16)

File ID

CHAR(10)

Object type

CHAR(1)

File system

CHAR(1)

Additional call

CHAR(1)

Object modified since last scan

CHAR(1)

Scan signatures different

CHAR(1)

Call after previous failure

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.

Offset

Type

Field

Dec

Hex

BINARY(4)

Close scan status information length

BINARY(4), UNSIGNED

Failing CCSID

CHAR(1)

Update object scan information

CHAR(1)

Scan status

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:

QP0L_SCAN_CALL_FIRST (x'00')

The first call to the exit program.

QP0L_SCAN_CALL_ADDL (x'01')

An additional call to the exit program because another exit program has indicated the object was modified.

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:

QP0L_SCAN_NO (x'00')

This is not a call after a previous scan failure.

QP0L_SCAN_YES (x'01')

This is a call after a previous scan failure. The Last failure CCSID field in conjunction with the From CCSID indicate the CCSID or binary indication of the failing scan request.

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

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:

SCCL0100

The format name that is used while an object is being closed.

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

QP0L_SCAN_ROOT_QOPENSYS_UDFS (x'00')

The object is in the "root" (/), QOpenSys, or a user-defined file system.

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

QP0L_SCAN_NO (x'00')

The object has not been modified since it was last scanned.

QP0L_SCAN_YES (x'01')

The object has been modified since it was last scanned.

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

QP0L_SCAN_NO (x'00')

The compared signatures are not different.

QP0L_SCAN_YES (x'01')

The compared signatures are different.

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:

QP0L_SCAN_SUCCESS (x'01')

The object was scanned and has no failures. If this indicator is returned by all exit programs that were called, the object will be marked as scan successful, and the close operation completes with no errors.

QP0L_SCAN_FAILURE (x'02')

The object was scanned and has at least one failure. If this indicator is returned by at least one of the exit programs that was called, the object will be marked as scan failure, and the close operation fails. Additionally, only the CCSID or binary indication related to this failing request will be kept in the object scan information, and the rest of the historical CCSID or binary information will be cleared.

Once an object has been marked as a failure under this condition, it will not be scanned again until the object's scan signature is different than the global scan key signature or independent ASP group scan key signature as appropriate. Therefore, subsequent requests to work with the object will fail with a scan failure indication. Examples of requests which will fail are opening the object, changing the CCSID of the object, copying the object etc..

QP0L_SCAN_FAIL_WANT_ MODIFY (x'03')

The object was scanned and has at least one failure. However, the exit program wanted to modify the file to correct the failure, but could not because it did not have write access. If this indicator is returned by at least one of the exit programs that was called, the object will be marked as scan failure, and the close operation fails. Additionally, only the CCSID or binary indication related to this failing request will be kept in the object scan information, and the rest of the historical CCSID or binary information will be cleared.

Once an object has been marked as a failure under this condition, it will not be scanned again until the object's scan signature is different than the global scan key signature or independent ASP group scan key signature as appropriate, or if a subsequent access would allow write access to be given to the exit program. Therefore, subsequent requests to work with the object will fail with a scan failure indication. Examples of requests which will fail are opening the object, changing the CCSID of the object, copying the object etc..

QP0L_SCAN_MODIFY (x'04')

The object was scanned, one or more failures were found, but the object was modified to remove the failures. If this indicator is returned by at least one of the exit programs that was called, then any exit programs which have previously been called will be called one more time so that they can scan the modified object information. This second call is indicated by an Additional call field value. If after this additional call, no failures are found, the object will be marked as scan successful, and the close operation completes with no errors.

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

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

QP0L_SCAN_NO (x'00')

The object scan information should not be updated. This might be used when the object was not actually scanned by the exit program, perhaps because it did not need to be, or perhaps because a deferred scan was initiated.

QP0L_SCAN_YES (x'01')

The object scan information should be updated. When this value is set, then the values in the Scan status field and Failing CCSID are used. If at least one exit program specified this value, then the object scan information will be updated.

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

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].
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].
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()
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.
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.
- Control Intrusion Detection and Prevention (QTOQIDSC, QtoqIDSControl) -- [ENOTSUP]
- 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]
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.
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.
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.
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 ]