Working with output of the RTVDIRINF and PRTDIRINF commands

 

The Retrieve Directory Information (RTVDIRINF) command is used to collect attributes for objects in the integrated file system. The collected information is stored in database files (tables) that are named using the information file prefix specified by the INFFILEPFX parameter. The tables are created in the library specified by the INFLIB parameter.

Three tables are created as a result of the RTVDIRINF command. One table stores object attributes, one is for directories, and the last table is used to determine which files were used to store object attributes.

The following table describes the fields that are provided for the table that stores the object attributes. If *GEN is specified in the information file prefix (INFFILEPFX) parameter, the database files are created with a unique prefix generated by this command. The prefix begins with QAEZD followed by four digits. The files created to store the collected information are named using this prefix followed by either the letter D (for the file that contains directory information) or the letter O (for the file that contains information about objects in directories). For example, the first time that the command is run with *GEN specified, files QAEZD0001D and QAEZD0001O are created in the library specified by the Information library (INFLIB) parameter. Users can specify a file prefix to use for naming this database, which can be up to nine characters long.

Table 1. QAEZDxxxxO (store object's attributes)
Field name Field type Field description
QEZACCTIM TIMESTAMP The date and time that the object's data was last accessed.
QEZALCSIZE 1 BIGINT The number of bytes that have been allocated for this object.
QEZALWCKPW SMALLINT Whether a stream file (*STMF) can be shared with readers and writers during the save-while-active checkpoint processing. Valid values are:

0 - The object can be shared with readers only.

1 - The object can be shared with readers and writers.

QEZASP SMALLINT The auxiliary storage pool in which the object is stored.
QEZAUDT GRAPHIC (10) The auditing value associated with the object. Valid values are:

*NONE - No auditing occurs for this object when it is read or changed regardless of the user who is accessing the object.

*USRPRF - Audit this object only if the current user is being audited. The current user is tested to determine if auditing should be done for this object. The user profile can specify if only change access is audited or if both read and change accesses are audited for this object.

*CHANGE - Audit all change access to this object by all users on the system.

*ALL - Audit all access to this object by all users on the system. All access is defined as a read or change operation.

QEZAUTLST GRAPHIC (10) The name of the authorization list that is used to secure the named object. The value *NONE indicates that no authorization list is used in determining authority to the object.
QEZBLKSIZ INTEGER The block size of an object.
QEZCASE SMALLINT Indicates the Case Sensitivity of the file system that contains this object.

0 - File system is not case sensitive.

1 - File system is case sensitive.

QEZCCSID INTEGER The CCSID of the data and extended attributes of the object.
QEZCEAS BIGINT Number of critical extended attributes associated with this object.
QEZCHGTIMA 1 TIMESTAMP The date and time that the object's attributes were last changed.
QEZCHGTIMD TIMESTAMP The date and time that the object's data was last changed.
QEZCHKOUT 1 SMALLINT An indicator as to whether an object is checked out. Valid values are:

0 - The object is not checked out.

1 - The object is checked out.

QEZCHKOWN GRAPHIC (10) The user who has the object checked out. This field is blank if it is not checked out.
QEZCHKTIM TIMESTAMP The date and time the object was checked out. If the object is not checked out, this field will have NULL as its value.
QEZCLSTRSP SMALLINT The object is the storage that was allocated for Integrated xSeries® servers to use as virtual disk drives for the IBM System x servers. From the perspective of the System i™ platform, virtual drives appear as byte stream files within the integrated file system.

0 - Object is not virtual disk storage.

1 - Object is virtual disk storage.

QEZCRTAUD GRAPHIC (10) The auditing value associated with an object created in this directory. Valid values are:

*NONE - No auditing occurs for this object when it is read or changed regardless of the user who is accessing the object.

*USRPRF - Audit this object only if the current user is being audited. The current user is tested to determine if auditing should be done for this object. The user profile can specify if only change accesses are audited or if both read and change accesses are audited for this object.

*CHANGE - Audit all change accesses to this object by all users on the system.

*ALL - Audit all accesses to this object by all users on the system. All accesses are defined as a read or change operation.

QEZCRTTIM TIMESTAMP The date and time at which the object was created.
QEZDIRIDX INTEGER The parent directory index.
QEZDIRTYP2 SMALLINT The format of the specified directory object. Valid values are:

0 - The directory format is *TYPE1.

1 - The directory format is *TYPE2.

QEZDOM GRAPHIC (10) The domain of the object. Valid values are:

*SYSTEM - Object exists in system domain.

*USER - Object exists in user domain.

QEZDSTGOPT SMALLINT This option should be used to determine how auxiliary storage is allocated by the system for the specified object. This option can only be specified for stream files in the "root" (/), QOpenSys and user-defined file systems. This option will be ignored for *TYPE1 byte stream files. Valid values are:

0 - The auxiliary storage will be allocated normally. That is, as additional auxiliary storage is required, it will be allocated in logically sized extents to accommodate the current space requirement, and anticipated future requirements, while minimizing the number of disk I/O operations.

1 - The auxiliary storage will be allocated to minimize the space used by the object. That is, as additional auxiliary storage is required, it will be allocated in small sized extents to accommodate the current space requirement. Accessing an object composed of many small extents may increase the number of disk I/O operations for that object.

2 - The system will dynamically determine the optimum auxiliary storage allocation for the object, balancing space used versus disk I/O operations. For example, if a file has many small extents, yet is frequently being read and written, then future auxiliary storage allocations will be larger extents to minimize the number of disk I/O operations. Or, if a file is frequently truncated, then future auxiliary storage allocations will be small extents to minimize the space used. Additionally, information will be maintained on the stream file sizes for this system and its activity. This file size information will also be used to help determine the optimum auxiliary storage allocations for this object as it relates to the other objects sizes.

QEZDTASIZE BIGINT The size in bytes of the data in this object. This size does not include object headers or the size of extended attributes associated with the object.
QEZEAS BIGINT Number of extended attributes associated with this object.
QEZEXTATRS BIGINT Total number of bytes for all the extended attribute data.
QEZFILEID 1 GRAPHIC (16) The file ID for the object. An identifier associated with the object. A file ID can be used with Qp0lGetPathFromFileID() to retrieve an object's path name.
QEZFILEIDS INTEGER The 4 byte file ID of the file. This number uniquely identifies the object within a file system. This number cannot identify the object in the whole system.
QEZFILTYP2 1 SMALLINT The format of the stream file (*STMF). Valid values are:

0 - The stream file format is *TYPE1.

1 - The stream file format is *TYPE2.

QEZFSID BIGINT The file system ID to which the object belongs. This number uniquely identifies the file system to which the object belongs.
QEZGENID BIGINT The generation ID associated with the file ID.
QEZGID INTEGER Group profiles are identified by a unique numeric group identification number (GID).
QEZINHSCN GRAPHIC (1) Whether the objects created in a directory will be scanned when exit programs are registered with any of the integrated file system scan-related exit points.

Valid values are: x'00' - After an object is created in the directory, the object will not be scanned according to the rules described in the scan-related exit programs.

If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.

x'01' - After an object is created in the directory, the object will be scanned according to the rules described in the scan-related exit programs if the object has been modified or if the scanning software has been updated since the last time the object was scanned. x'02' - After an object is created in the directory, the object will be scanned according to the rules described in the scan-related exit programs only if the object has been modified since the last time the object was scanned. It will not be scanned if the scanning software has been updated. This attribute only takes effect if the Scan file systems control (QSCANFSCTL) system value has *USEOCOATR specified. Otherwise, it will be treated as if the attribute is SCANNING_YES.

If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.

QEZJAFTERI SMALLINT When journaling is active, the image of the object after a change is journaled.

0 - Object is not journaled with after images.

1 - Object is journaled with after images.

QEZJBEFORI SMALLINT When journaling is active, the image of the object before a change is journaled.

0 - Object is not journaled with before images.

1 - Object is journaled with before images.

QEZJOPTENT SMALLINT When journaling is active, entries that are considered optional are journaled. The list of optional journal entries varies for each object type.

0 - Object is not journaled with optional entries.

1 - Object is journaled with optional entries.

QEZJRCVASP GRAPHIC(10) The name of the ASP that contains the journal receiver needed to successfully apply journal changes. The valid values are:

*SYSBAS - The journal receiver resides in the system or user ASP.

ASP device - The name of the ASP device that contains the journal receiver.

QEZJRCVLIB GRAPHIC(10) The name of the library that contains the journal receiver needed to successfully apply journal changes. This field is blank if the object has never been journaled.
QEZJRCVNAM GRAPHIC(10) The oldest journal receiver needed to successfully apply journal changes. When the Apply information field is set to PARTIAL_TRANSACTION, the journal receiver contains the start of the partial transaction. Otherwise, the journal receiver contains the start of the save operation. This field is blank if the object has never been journaled.
QEZJRNID GRAPHIC (10) This field associates the object being journaled with an identifier that can be used on various journaling-related commands and APIs. This field is blank if the object has never been journaled.
QEZJRNLIB GRAPHIC (10) If the value of the journaling status is JOURNALED, then this field contains the name of the library containing the currently used journal. If the value of the journaling status is NOT_JOURNALED, then this field contains the name of the library containing the last used journal. This field is blank if the object has never been journaled.
QEZJRNNAM GRAPHIC (10) If the value of the journaling status is JOURNALED, then this field contains the name of the journal currently being used. If the value of the journaling status is NOT_JOURNALED, then this field contains the name of the journal last used for this object. This field is blank if the object has never been journaled.
QEZJRNSTR TIMESTAMP The number of seconds since the Epoch that corresponds to the last date and time for which the object had journaling started for it. This field has NULL as its value if the object has never been journaled.
QEZJRNSTS 1 SMALLINT Current journaling status of the object. This field will be one of the following values:

0 (NOT_JOURNALED) - The object is currently not being journaled.

1 (JOURNALED) - The object is currently being journaled.

QEZJSUBTRE SMALLINT When this flag is returned, this object is a directory with integrated file system journaling subtree semantics.

0 - The object is not journaled with subtree semantics.

1 - The object is journaled with subtree semantics. New objects created within this directory's subtree will inherit the journaling attributes and options from this directory.

QEZJTRNI GRAPHIC(1) This field describes information about the current state of the object as it relates to commitment control boundaries. The valid values are:

x'00' (NONE) - There are no partial transactions.

x'01' (PARTIAL_TRANSACTION) - The object was restored with partial transactions. This object cannot be used until the Apply Journaled Changes (APYJRNCHG) or Remove Journaled Changes (RMVJRNCHG) command is used to complete or rollback the partial transactions.

x'02' (ROLLBACK_ENDED) - The object had a rollback operation ended using the "End Rollback" option on the Work with Commitment Definition (WRKCMTDFN) screen. IBM recommends that the object be restored as it cannot be used. As a last option, the Change Journaled Object (CHGJRNOBJ) command can be used to allow the object to be used. Doing this, however, can leave the object in an inconsistent state.

QEZLANGID GRAPHIC (3) A three character ID representing the language that the object name (field QEZOBJNAM) is in.
QEZLOCAL SMALLINT Whether an object is stored locally or stored on a remote system. The decision of whether an object is local or remote varies according to the respective file system rules. Objects in file systems that do not carry either a local or remote indicator are treated as remote. Valid values are:

1 - The object's data is stored locally.

2 - The object's data is on a remote system.

QEZMLTSIG SMALLINT Whether an object has more than one i5/OS® digital signature. Valid values are:

0 - The object has only one digital signature.

1 - The object has more than one digital signature. If the QEZSYSSIG field has the value 1, at least one of the signatures is from a source trusted by the system.

QEZMODE INTEGER The file access mode and type. For more information about mode, see open() API.
QEZMSTGOPT SMALLINT This option should be used to determine how main storage is allocated and used by the system for the specified object. This option can only be specified for stream files in the "root" (/), QOpenSys and user-defined file systems. Valid values are:

0 - The main storage will be allocated normally. That is, as much main storage as possible will be allocated and used. This minimizes the number of disk I/O operations since the information is cached in main storage.

1 - The main storage will be allocated to minimize the space used by the object. That is, as little main storage as possible will be allocated and used. This minimizes main storage usage while increasing the number of disk I/O operations since less information is cached in main storage.

2 - The system will dynamically determine the optimum main storage allocation for the object depending on other system activity and main storage contention. That is, when there is little main storage contention, as much storage as possible will be allocated and used to minimize the number of disk I/O operations. And when there is significant main storage contention, less main storage will be allocated and used to minimize the main storage contention. This option only has an effect when the storage pool's paging option is *CALC. When the storage pool's paging option is *FIXED, the behavior is the same as STG_NORMAL. When the object is accessed through a file server, this option has no effect. Instead, its behavior is the same as STG_NORMAL.

QEZNLNK INTEGER The number of hard links to the object.
QEZNMCCSID INTEGER The CCSID in which the object name (field QEZOBJNAM) is represented.
QEZNONSAV SMALLINT Whether the object can be saved or not. Valid values are:

0 - Object will be saved.

1 - Object will not be saved. Additionally, if this object is a directory, none of the objects in the directory's subtree will be saved unless they were explicitly specified as an object to be saved. The subtree includes all subdirectories and the objects within those subdirectories.

QEZOBJLEN INTEGER Number of bytes contained in the object name (field QEZOBJNAM).
QEZOBJNAM 1 VARGRAPHIC (1024) The object name. 2
QEZOBJTYPE 1 GRAPHIC (10) The object type.
QEZOFLOW SMALLINT Indicates if the object has overflowed the auxiliary storage pool it resides in. Valid values are:

0 - Auxiliary storage pool is not overflowed.

1 - Auxiliary storage pool is overflowed.

QEZOWN 1 GRAPHIC (10) The name of the user profile that is the owner of the object or the following special value:

*NOUSRPRF - This special value is used by the Network File System to indicate that there is no user profile on the local System i platform with a user ID (UID) matching the UID of the remote object.

QEZOWNPGP GRAPHIC (10) The name of the user profile that is the primary group of the object or the following special values:

*NONE - The object does not have a primary group

*NOUSRPRF - This special value is used by the Network File System to indicate that there is no user profile on the local system with a group ID (GID) matching the GID of the remote object.

QEZPCARC SMALLINT Whether the object has changed since the last time the object was examined.

0 - The object has not changed.

1 - The object has changed.

QEZPCHID 1 SMALLINT Whether the object can be displayed using an ordinary directory listing.

0 - The object is not hidden.

1 - The object is hidden.

QEZPCREAD SMALLINT Whether the object can be written to or deleted, have its extended attributes changed or deleted, or have its size changed. Valid values are:

0 - The object can be changed.

1 - The object cannot be changed.

QEZPCSYS SMALLINT Whether the object is a system file and is excluded from normal directory searches.

0 - The object is not a system file.

1 - The object is a system file.

QEZPRMLNK SMALLINT When an object has several names, this field will be set only for the first name found.
QEZRDEV BIGINT If the object represents a device special file, the real device it represents.
QEZREGION GRAPHIC (2) A two-character ID representing the country of the object name (field QEZOBJNAM). This ID affects actions that tend to be defined by the location of the action, such as collating sequence.
QEZSBINARY GRAPHIC (1) This indicates if the object has been scanned in binary mode when it was previously scanned. This field will be one of the following values:

x'00' - The object was not scanned in binary mode.

x'01' - The object was scanned in binary mode. If the object scan status is SCAN_SUCCESS, then the object was successfully scanned in binary. If the object scan status is SCAN_FAILURE, then the object failed the scan in binary.

QEZSCCSID1 INTEGER This indicates if the object has been scanned in the listed CCSID when it was previously scanned. If the object scan status is SCAN_SUCCESS, then the object was successfully scanned in this CCSID. If the object scan status is SCAN_FAILURE, then the object failed the scan in this CCSID. A value of 0 means this field does not apply.
QEZSCCSID2 INTEGER This indicates if the object has been scanned in the listed CCSID when it was previously scanned. If the object scan status is SCAN_SUCCESS, then the object was successfully scanned in this CCSID. If the object scan status is SCAN_FAILURE, then this field will be 0. A value of 0 means this field does not apply.
QEZSCN GRAPHIC (1) Whether the object will be scanned when exit programs are registered with any of the integrated file system scan-related exit points.

Valid values are:

x'00' (SCANNING_NO) - The object will not be scanned according to the rules described in the scan-related exit programs.

If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.

x'01' (SCANNING_YES) - The object will be scanned according to the rules described in the scan-related exit programs if the object has been modified or if the scanning software has been updated since the last time the object was scanned.

x'02' (SCANNING_CHGONLY) - The object will be scanned according to the rules described in the scan-related exit programs only if the object has been modified since the last time the object was scanned. It will not be scanned if the scanning software has been updated. This attribute only takes effect if the Scan file systems control (QSCANFSCTL) system value has *USEOCOATR specified. Otherwise, it will be treated as if the attribute is SCANNING_YES.

If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.

QEZSIG 1 SMALLINT Whether an object has an i5/OS digital signature. Valid values are:

0 - The object does not have an i5/OS digital signature.

1 - The object does have an i5/OS digital signature.

QEZSSIGDF GRAPHIC (1) The scan signatures give an indication of the level of the scanning software support.

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 value. This field will be one of the following values:

x'00' - The compared signatures are not different.

x'01' - The compared signatures are different.

QEZSSTATUS GRAPHIC (1) The scan status associated with this object. This field will be one of the following values:

x'00' (SCAN_REQUIRED) - A scan is required for the object either because it has not yet been scanned by the scan-related exit programs, or 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.

x'01' (SCAN_SUCCESS) - The object has been scanned by a scan-related exit program, and at the time of that last scan request, the object did not fail the scan.

x'02' (SCAN_FAILURE) - The object has been scanned by a scan-related exit program, and at the time of that last scan request, the object failed the scan and the operation did not complete. Once an object has been marked as a failure, 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.

x'05' (SCAN_PENDING_CVN) - The object is not in a *TYPE2 directory, and therefore will not be scanned until the directory is converted.

x'06' (SCAN_NOT_REQUIRED) - The object does not require any scanning because the object is marked to not be scanned.

QEZSTGFREE 1 SMALLINT Whether the object's data has been moved offline, freeing its online storage. Valid values are:

0 - The object's data is not offline.

1 - The object's data is offline.

QEZSYSARC SMALLINT Whether the object has changed and needs to be saved. It is set on when an object's change time is updated, and set off when the object has been saved.

0 - The object has not changed and does not need to be saved.

1 - The object has changed and does need to be saved.

QEZSYSSIG SMALLINT Whether the object was signed by a source that is trusted by the system. Valid values are:

0 - None of the signatures came from a source that is trusted by the system.

1 - The object was signed by a source that is trusted by the system. If the object has multiple signatures, at least one of the signatures came from a source that is trusted by the system.

QEZUDATE TIMESTAMP The number of seconds since the Epoch that corresponds to the date the object was last used. This field is zero when the object is created. If usage data is not maintained for the i5/OS type or the file system to which an object belongs, this field is zero.
QEZUDCOUNT INTEGER The number of days an object has been used. Usage has different meanings according to the specific file system and according to the individual object types supported within a file system. Usage can indicate the opening or closing of a file or can refer to adding links, renaming, restoring, or checking out an object. This count is increased each day that an object is used and is reset to zero by calling the Qp0lSetAttr() API.
QEZUDFTYP2 SMALLINT The default file format of stream files (*STMF) created in the user-defined file system. Valid values are:

0 - The stream file format is *TYPE1.

1 - The stream file format is *TYPE2.

QEZUID INTEGER Each user on the system must have a unique numeric user identification number (UID).
QEZURESET INTEGER The number of seconds since the Epoch that corresponds to the date the days used count was last reset to zero (0). This date is set to the current date when the Qp0lSetAttr() API is called to reset the Days used count to zero.
Notes:

  1. This field is included in the subset of fields used by the PRTDIRINF command.

  2. In this field, only the object name is stored. The rest of the path name is stored in field QEZDIRNAM1 if the length of the directory name is below 1 KB ( equals 1024 bytes) or in QEZDIRNAM2 if the directory names are above 1 KB (equals 1024 bytes).

The following table is an example of a table that lists the directories processed by the RTVDIRINF command.

Table 2. QAEZDxxxD (store directory's attributes)
Field name Field type Field description
QEZDFID INTEGER The file ID of the directory.
QEZDIRFID GRAPHIC (16) The file ID of the directory. An identifier associated with the object. A file ID can be used with Qp0lGetPathFromFileID() to retrieve an object's path name.
QEZDIRFSID BIGINT The file system ID of the directory.
QEZDIRGID BIGINT The generation ID.
QEZDIRIDX INTEGER Identifier of path name (applies only to directories).
QEZDIRLEN 1 INTEGER Length of directory's path name.
QEZDIRNAM1 1 VARGRAPHIC (1024) The parent directory path. Only used when path length is below 1 KB (1024 bytes).
QEZDIRNAM2 1 DBCLOB (16M) The parent directory path. Only used when path length is above 1 KB (1024 bytes) long. Can store paths up to 16 MB long.
QEZDRCCSID INTEGER The directory CCSID.
QEZDREGION GRAPHIC (2) The directory path region ID.
QEZLANGID GRAPHIC (3) The directory path language ID.

  • This field is included in the subset of fields used by the PRTDIRINF command.

The following table shows the information that the RTVDIRINF command stores regarding the files it has created when it runs. If the file that contains this information does not exist, the RTVDIRINF command creates it; when the command runs on subsequent occasions, the information is appended to the existing file. The PRTDIRINF command uses this information to determine which database files were used to store information that was retrieved by different instances of the RTVDIRINF command.

Table 3. QUSRSYS/QAEZDBFILE (store files created)
Field name Field type Field description
QEZDIRFILE 1 VARGRAPHIC (20) The name of the file generated to store the directory's indexes.
QEZDIRSRC VARGRAPHIC (5000) Path specified in DIR parameter (RTVDIRINF).
QEZENDTIME TIMESTAMP Date/Time when RTVDIRINF was completed.
QEZLIB 1 VARGRAPHIC (20) Library where both generated files reside.
QEZOBJFILE 1 VARGRAPHIC (20) The name of the file generated to store the object's attributes.
QEZPLANGID GRAPHIC (3) The path language ID
QEZPRCCSID INTEGER The path CCSID.
QEZPREGION GRAPHIC (2) The path region ID.
QEZSTRTIME TIMESTAMP Date/Time when RTVDIRINF was submitted.

  • This field is included in the subset of fields used by the PRTDIRINF command.

 

Parent topic:

Accessing using CL commands

 

Related information


Retrieve Directory Information (RTVDIRINF) command
Qp0lGetPathFromFileID()--Get Path Name of Object from Its File ID API
Qp0lSetAttr()--Set Attributes API
Apply Journaled Changed (APYJRNCHG) command
Remove Journaled Changes (RMVJRNCHG) command
Change Journaled Object (CHGJRNOBJ) command
Print Directory Information (PRTDIRINF) command