Overview of the RCLSTG Command

RCLSTG Considerations:

1.    Reclaim Storage is invoked through the RCLSTG command.  Authority is required to the command which is shipped with public *EXCLUDE authority.  The RCLSTG command should be run upon IBM direction or documentation as listed due to it possibly being a long running restricted state function.  

 2.    At R540 and beyond, the RCLSTG ESTIMATE(*YES) option can be run to assist with determining how long the RCLSTG command takes to complete.  The estimate is calculated by using statistics collected during previous RCLSTG operations and the values specified for the other RCLSTG parameters.                   

3.    To display how long the previous RCLSTG took to complete (providing a RCLSTG was previously run on the system), type the following on the command line:
    
    DSPDTAARA  DTAARA(QRCLSTG) or DMPOBJ OBJ(QRCLSTG) OBJTYPE(*DTAARA)
    
    Press the Enter key.  For more information regarding this command, refer to IBM Technote, Time Required to Run Reclaim Storage.

4.    To run the RCLSTG command for SYSBAS (that is the System and Basic ASPs), the system must be in restricted state (using the ENDSBS *ALL or ENDSYS command).  To run RCLSTG for an ASP group, there must be no one using the ASP.  

5.    The RCLSTG command requires some disk storage for processing.  On systems with a lot of less frequently used database objects, the RCLSTG command may require a considerable amount of disk storage.  This is because it opens each member which creates temporary runtime segments for each file and member.

6.    If possible, an IPL is suggested just prior to running the command to reduce the time spent in RCLSTG.

7.    Commitment control must be inactive for the ASP groups RCLSTG is running in.

8.    The RCLSTG command touches every object in the ASP group it is running in.

9.    The RCLSTG command can be ended (using system request).  However, if a RCLSTG *ALL or RCLSTG *DBXREF is terminated prior to completion, a RCLSTG *DBXREF must be run to completion in order to avoid unpredictable results within regard to the database cross-reference files.
    
    To correct database cross-reference files for an ASP group in error, type the following for that ASP group:
    
    RCLSTG  *DBXREF  Press the Enter key.
    
    Note:  A dedicated (restricted state) environment is required.  Once started, this step must run to completion.  
    
    Note:  If database file objects are damaged, the keyed access paths may need to be rebuilt.  This operation can take a substantial amount of time.

10.    The RCLSTG command cannot be checkpointed. If a RCLSTG is terminated prior to completion, the ensuing RCLSTG will restart from the beginning of the process.

11.    The RCLSTG command does not run if critical libraries such as QRECOVERY, QSYS, QSYS2, QUSRSYS, QDOC, and QSPL are missing, nor if profiles such as QDBSHR, QDBSHRDO, QSYS, QSECOFR, QDFTOWN, QSNADS, QDOC, QSPL, QDSNX, and QMSF are missing.

12.    Damaged user profiles are deleted if they are not considered critical by the system.  If the RCLSTG command detects damaged user libraries, it will stop processing the command.  To recover, the library must be deleted and restored from a previous successful save.  The RCLSTG command could then be run again.
RCLSTG does not need to be run solely for the following:

1.    For physical or logical damage (soft/partial damage).  
    
    RCLSTG  may uncover some, find some already damaged objects or even deal with certain kinds of damage, but RCLSTG is not intended to hunt for damage.  It is suggested to attempt in understanding the damage that is occurring and the best options to deal with it.  Regarding Physical Files, refer to Rochester Support Center knowledgebase document  New, Check Damage on Physical Files (CHKPF).  To link to document N1010157 immediately, click here [<a href="http://www-01.ibm.com/support/docview.wss?uid=nas8N1010157"><img src="http://www-01.ibm.com/support/icons/doclink.gif" border="0" alt="Database 'DCF Technotes (IBM i)', View 'Products', Document 'Check Damage on Physical Files (CHKPF)'"></a>].
    
    ALL objects on the system MUST be associated with a library and owned by a profile.  If the object has lost the addressability to either the library or profile, it is classified as being orphaned.  RCLSTG will find these objects.   
    
    Note:  An orphaned object is not an addressable object, thus no reference can be made to it through WRKLIB, WRKOBJ, WRKOBJOWN, and so on.  Upon attempting to perform any command against the object, a message is received stating object not found.
    
    Note: If a WRKOBJ is performed against an object that has the existence bit set to indicate damage, a message stating the object is damaged would be received and RCLSTG does not flag these objects.

2.    System power outages.  RCLSTG is not automatically recommended upon encountering a power outage.  Refer to RCLSTG does the following section as applicable.

3.    When unfamiliar messages are received.  If messages received are not understood, contact IBM support for explanation(s).

4.    System ended abnormally several times since the last RCLSTG command was run.  The RCLSTG command does not need to be run prior to an update unless there is a warranted reason for running it.

5.    Normal system maintenance.

6.
    Preparing for an upgrade.
    
    Note: Estimates gathered before hardware changes may change upon new configurations.
    
RCLSTG Restrictions:

1.    This command is shipped with public *EXCLUDE authority.  The QPGMR, QSYSOPR, QSRV, and QSRVBAS user profiles have private authorities to use the command.                               

2.    If option ASPDEV(*SYSBAS) is specified, all subsystems must be inactive before the RCLSTG command can be specified.  The End System (ENDSYS) or End Subsystem (ENDSBS) command with SBS(*ALL) specified can be used to make the subsystems inactive.  The profile issuing the ENDSYS or the ENDSBS commands must have job control (*JOBCTL) authority.

3.    Only permanent objects in auxiliary storage are reclaimed.  Temporary objects are reclaimed by running a system initial program load (IPL).

4.    Before running the RCLSTG command after an IPL, wait several minutes for the IPL to complete.  Use the Work with Active Jobs (WRKACTJOB) command to verify that no jobs are running.

5.    If option *SYSBAS is specified on the ASPDEV parameter, this job must be in the controlling subsystem and must be the only job active in the system.

6.    Network server descriptions (NWSD) must be varied-off to run the RCLSTG command.                           

7.    When ASPDEV(*SYSBAS) is specified, all the auxiliary storage pool (ASP) devices configured in the system must be in the VARY OFF status.

8.    If an auxiliary storage pool (ASP) device or an ASP group is specified on the ASPDEV parameter, it cannot have active users or be in use by a different job.  The ASP device or group must be in the AVAILABLE or FAILED status to allow the RCLSTG command to run.  This can be checked for IASPs in Operations Navigator or iSeries Navigator by going to My Connections -> Configuration and Service -> Hardware -> Disk Units -> Disk Pools.  Then, right click on the desired Disk Pool, and take the option for jobs.  If the new window shows no jobs, RCLSTG on that IASP can be run.  At R540, the WRKASPJOB command can also be used.

9.    All ASPs in an ASP group must be done at the same time.  If RCLSTG is started for one, they will all be done.  This means that there must be no locks on any of the ASPs.

10.    The directory conversion function must not be active while RCLSTG runs.  The Convert Directory (CVTDIR) command with OPTION(*CHECK) can be used to verify directory conversion is not active.  Otherwise, option OMIT(*DIR) should be specified to omit the directory recovery portion of the reclaim function.

11.    At R540, to provide an estimate of the amount of time that a future RCLSTG will require, statistics are collected when running the RCLSTG ESTIMATE(*NO) command.  If ESTIMATE(*YES) is specified and these statistics are not available, message CPF8281 is issued.   
RCLSTG Command Parameters

    Select (SELECT) - Specifies the reclaim functions that are performed.
    
    RCLSTG SELECT(*ALL) - All reclaim functions are performed.                       
                                                                        
    RCLSTG SELECT(*DBXREF) - The database cross-reference table reclaim function is performed. This option recovers the database cross-reference catalog data for all the libraries on the system.  This option should be used when problems with the database cross-reference catalogs occur.  
    
    (At R540) RCLSTG SELECT(*DIR) - The directory recovery portion of the reclaim function is performed.  Some of the following actions are performed during this process: addressing user-defined file system problems, resolving internal object problems, removal of invalid object links, flagging of hard damaged objects, and creation of missing system objects.  It corrects issues found on the different IFS's existing on the system.  At R540 and beyond, RCLSTG should be used after RCLLNK has failed to correct a problem.                                        
    Omit (OMIT) - Specifies the reclaim functions to be omitted from the reclaim operation.
    
    RCLSTG OMIT(*NONE) - No reclaim functions are omitted.
    
    RCLSTG OMIT(*DBXREF) - Database cross-reference table reclaim function is omitted.
    
    (At R540) RCLSTG OMIT(*DIR) - Directory recovery portion of the reclaim function is omitted.  
                                                                     
    RCLSTG SELECT(ASPDEV) - Auxiliary device or group - Specifies the IASP or ASP group to be reclaimed.                                             
    RCLSTG ASPDEV(*SYSBAS) - The system ASP and all basic ASPs are reclaimed.  The system ASP has an ASP number of 1.  Basic ASPs have ASP numbers of 2 through 32.  To do SYSBAS, the system must be in restricted state.
    
    Note:   When option *SYSBAS is specified for the ASPDEV parameter, all the Independent auxiliary storage pool (IASP) devices configured in the system must be in the VARY OFF status.  The directory conversion function must not be active while the RCLSTG command runs. The Convert Directory (CVTDIR) command with OPTION(*CHECK) can be used to verify directory conversion is not active.  Otherwise, option OMIT(*DIR) should be specified to omit the directory recovery portion of the reclaim function.                                                    
    
    auxiliary-storage-pool-device-or group name - The specified ASP device or ASP group is reclaimed.  Basic ASP devices have ASP numbers less than or equal to 32.  Independent ASPs have numbers greater than 32.  Reclaim storage for an ASP device can be run without being in restricted state.  Multiple jobs may be submitted, each performing RCLSTG on a different ASP device, to reclaim multiple ASP devices in parallel.  If RCLSTG for one IASP that is part of an ASP group is done, all IASPs in the ASP group will be done at the same time.  To do a RCLSTG for an ASP group, all IASPs in that group must have no one using them.  See the restrictions for how to check this.
Considerations after running the RCLSTG Command:

1.    Check for any messages in the history log, QSYSOPR message queue, and the job log.

2.    Check for any dumps.

3.    Review QRCL library:
    - QRCL is created and, if no objects are inserted into it, the library is deleted.
    - Objects in this library must be handled, the library should not be left with objects inside of it
    - Object description entries are not valid for objects in QRCL.
    - The data for files in QRCL may be copied to new files.
    - Contact IBM support if there are any questions regarding objects in QRCL.

4.    Review any objects whose ownership is transferred to QDFTOWN:
    - Message is generated for any external object transferred.
- Use the WRKOBJOWN command to show all objects owned by QDFTOWN.
- User is responsible for determining the appropriate owner.
- Authorities may need to be granted again (GRTOBJAUT).
    - Review objects on damaged/destroyed authorization list.
    - Display objects secured by QRCLAUTL (DSPAUTLOBJ).
- Move objects to another authorization list (GRTOBJAUT).

5.    Deleted objects include internal system objects that show up in the count but do not have an external message.
Factors That Affect RCLSTG Performance:

    - Number of objects.
- Types of objects.
- Amount of relational damage on system.
- Amount of auxiliary storage configured to the system.
- Percentage of auxiliary storage in use.
- Size of some objects.
    - Amount of main store on system (can have a very significant effect on RCLSTG command performance)
Functions of RCLSTG:

    Object Functions of RCLSTG:
    - Ensures objects owned by profile.
    - Ensures objects are in a library.
    - Ensures objects not secured by damaged/destroyed authorization list.
    - Ensures complex objects.
    - Deletes objects not completely created.
    - Processes object storage counts in all user profiles.
    - Deletes duplicate profiles.
    - Incomplete or header damaged subsystem descriptions are deleted.
    - Incomplete or header damaged save files are deleted.
    - Deletes duplicate I/O descriptions.
    - Internal objects will be deleted if they are not needed.
    - Invalid objects are deleted, if possible.
    - Duplicate objects are renamed; the original name is in the text description.

    Library Functions of RCLSTG:
    - Ensures all pieces of library are connected.
    - Removes object description entries if there is no corresponding entry in library.
    - All partially created libraries are destroyed.
    - Each library is checked for damage.
    - Duplicate libraries are deleted.

    Office Functions of the RCLSTG Command:
    - Performs different functions than the RCLDLO command.
    - Ensures DLO objects are in QDOC.
    - Ensures DLO objects are owned.
    - Destroys DLO objects that are not valid.
    - Verifies the mail logs on the system.
    - Ensures all mail is on someone's mail log.
    - Ensures all mail documents are attached to a mail item.

    Database Functions of the RCLSTG Command:
    - Database recovery is performed.
    - Performs any pending commit recovery.
    - Determines which secondary pieces are danglers.
    - If the danglers are not required, they are deleted.
    - Database cross-reference files are built during RCLSTG SELECT(both *ALL and *DBXREF) processing.
    - Identifies the database formats and directories that are danglers.
    - Identifies damage on database objects; however, not all damage will be detected.  Does not scan the data space or data space indexes for damage.
Reclaim Storage Messages:

    msgCPI8220     Message queue QSYSOPR in *HOLD delivery mode.
msgCPI8212     Data base/library/directory recovery in progress.
msgCPI8213     Processing objects on the system.
msgCPI8206     &1% of objects read from disk.
msgCPI8210     Processing data base relationships.
msgCPI8207     File Identifier table recovery in progress.
msgCPI8218     Directory recovery in progress.
msgCPI8219     Directory cleanup in progress.
msgCPI8215     Object description verification in progress.
msgCPI8217     Mail Server Framework cleanup in progress.
msgCPI8216     Final clean up in progress.

    The following messages are sent to qsysopr during a RCLSTG SELECT(*ALL):
    
    msgCPF8217 -  Message queue QSYSOPR is now in *HOLD delivery mode.
msgCPF8240 -  &3 &1 inserted in QRCL library.  (Logged each time RCLSTG moves an object to the QRCL library)
msgCPF8266  - File &2 in &1 found damaged during reclaim storage.  (Logged only when RCLSTG finds a damaged file)
msgCPF8260  - Data base objects destroyed by reclaim storage operation.
msgCPFA914 - File Identifier table recovery complete.
msgCPI8202   - Database cross reference files processed successfully.
msgCPC8208  - RCLSTG processing complete. &1 objects processed. &2 deleted.
ESCAPE Messages (not all messages at all releases):

    msgCPF180B     Function &1 not allowed.  
    msgCPF180C     Function &1 not allowed.
    msgCPF2119     Library &1 locked.                                   
    msgCPF2120     Cannot delete library &1.                            
    msgCPF2126     Attempt to recover library &1 failed.                
    msgCPF2127     User profile &2 damaged.
    msgCPF5729     Not able to allocate object &1.
    msgCPF8201     User profile &1 does not exist or is damaged.        
    msgCPF8204     Commitment control cannot be active during reclaim storage.   
    msgCPF8205     Library &1 does not exist or is damaged.           
    msgCPF8206     Directory conversion cannot be active during RCLSTG or RCLLNK.  
    msgCPF8209     System not in proper state to reclaim storage.
    msgCPF8210     Reclaim storage failed for auxiliary storage pool device &2.
    msgCPF8211     Library &1 damaged.  RCLSTG command ended.
    msgCPF8212     SELECT(*DBXREF) or OMIT(*DBXREF) invalid when reclaiming an User Defined File System (UDFS)  ASP.
    msgCPF8214     Estimate option cannot be performed.
    msgCPF8216     SELECT(*DBXREF) or OMIT(*DBXREF) not allowed for a UDFS ASP.
    msgCPF8224     Duplicate object found while moving or renaming member
    msgCPF8232     Commitment definitions prevent RCLSTG or RCLOBJOWN.    
    msgCPF8251     RCLSTG command ended. Library &1 damaged.             
    msgCPF8252     Error occurred during rebuild of damaged library &1.  
    msgCPF8281     Unable to estimate time required to run RCLSTG.
    msgCPF9814     Device &1 not found.                            
    msgCPFB8ED    Device description &1 not correct for operation.
    msgCPFA473     Network server &1 must be varied off.
    STATUS Messages  (releases only before R540)                                                
    msgCPI8206     &1% of objects processed.                             
    msgCPI8210     Processing data base relationships.                   
    msgCPI8212     Data base/library/directory recovery in progress.     
    msgCPI8213     Processing objects on the system.                     
    msgCPI8214     All permanent objects have valid owners.              
    msgCPI8215     Object description verification in progress.          
    msgCPI8216     Final clean up in progress.                           
    msgCPI8217     Mail Server Framework cleanup in progress.            
    msgCPI8218     Directory recovery in progress.                    
    msgCPI8219     Directory cleanup in progress.                     
    msgCPI8220     Message queue QSYSOPR in *HOLD delivery mode.
    msgCPIA916     &1% of directories processed.

From R540 and beyond, rather than getting status messages, you get a status screen similar to the following:

At R540:  Specifies whether to calculate an estimate for the amount of time that the RCLSTG command takes to run.  The estimate is calculated by using statistics collected during previous RCLSTG operations and the values specified for the other RCLSTG parameters.                                                                 
*NO - The estimate function is not performed.  The reclaim function specified by the other parameters is performed.                                                                                         
*YES - The estimate function is performed for the type of reclaim specified by the other parameters.  Nothing is reclaimed.  If SELECT(*DBXREF) is specified, no estimate can be provided.  Rather, the time taken to run the last RCLSTG SELECT(*DBXREF) is provided, if available.  Messages are displayed showing the results of the estimate.  

This is a useful option to determine when is the best time to schedule a RCLSTG on your system.  Because RCLSTG can be a long-running command, this option provides you with the amount of time that the next RCLSTG would take.

Before you can get an estimate for RCLSTG, a RCLSTG of the same type as the one you want to estimate or a full RCLSTG must have been run previously in that system.  Each time a RCLSTG is run, statistics regarding the time that the command execution takes are stored.  Therefore, the next time you will be able to get the estimate.

To estimate a RCLSTG OMIT(*DBXREF), it is necessary to have statistics of a RCLSTG of the same type.  The information collected by a full RCLSTG can be used to estimate the following RCLSTG types:

RCLSTG SELECT(*ALL)
RCLSTG SELECT(*DIR)
RCLSTG OMIT(*DIR)     

In these cases, the estimated time is provided according to the following major RCLSTG steps:

-  Reading objects from disk
-  File ID table recovery
-  Directory recovery
-  Object description verification

Messages will be sent to the joblog to display the estimated time for each step, and a final message will state the total time which is made up of the amount of time that each one of these steps would take.  If the estimate function is specified, no reclaim function is performed.

Note:  In some cases (according to the RCLSTG type), the time provided does not consider all of the above major RCLSTG steps.

The estimate option is different for a RCLSTG SELECT(*DBXREF).  When trying to estimate a RCLSTG of this type, a message is sent stating that it is not possible; however, if there are available statistics, the last date a RCLSTG (*DBXREF) was run and also the time it took to run will be displayed in the second-level text.

The function of estimate can be performed when the system is not in restricted state.  Then, whenever you want to schedule a RCLSTG, it is not necessary to interrupt your system activities to know the estimated time it will take.

The following screen shows how the parameters must be specified to estimate the time that a full RCLSTG would take

Because the estimate function is calculated in base to the data stored from previous RCLSTG commands and also considering the current amount of objects in the system, the certainty of the estimate can vary if the data belongs to a very old RCLSTG run or if the number of objects in auxiliary storage increased/decreased recently.

Estimate function is also available for Independent Auxiliary Storage Pools (IASPs) and User Defined File Systems (UDFSs).

The panel gives information about the type of RCLSTG that is being run, the date and time the execution started, the current and total steps for this type of RCLSTG, and also it points to the step that is actually running.

The Percent column states the percent complete for each step.  Therefore, like Time Elapsed shows the amount of time the step has been running, the Time Remaining column is updated every time that the percent and time elapsed ones are.  However, the difference with those is that this column can vary according to the progress that the step has shown.  This means that, if the speed in the step execution increases, the time remaining decreases reflecting the change.  In addition, if the step is running slower, it may increase the amount of time remaining.

At the bottom of the screen, the total time elapsed and remaining will give you an idea of how much time remains for the RCLSTG command to finish. When it is the first time a RCLSTG is run or if no statistics have been collected for a specific step, the Time Remaining column will show blanks for that step.

For the RCLSTG SELECT(*DBXREF) command, the tracking panel is not displayed.

The tracking panel function is also displayed when reclaiming Independent Auxiliary Storage Pools (IASPs) or User-Defined File Systems (UDFSs).