Overview

BST05ANA is a BSA database utility which you can use to:

• Analyze spool file contents, for example, to find out which indexes and lists are contained (entirely or in part) in a spool file (CHECK command)

  _beta doc|z plus administrators also use the CHECK command with the subcommand BUILD(SFR) to enable full recovery for spool files with list or index fragments that have been read in before Beta 93 Fast Retrieval V4R1. This command runs once against all existing spool files of the type SPOOL and INDEX during the upgrade procedure to V4 or later.

• Reorganize spool files in order to release used blocks that contain no valid data (REPAIR command)
• Reload all data from the archive that is affected by spool file corruption (RELOAD command)
• Empty spool files by moving all their data to other spool files (MOVE command)

Command availability matrix

The functions of BST05ANA are not available for all products and spool file types. The following table shows whether the corresponding command is available ( + ) or not ( - ).

Product and spool file type	CHECK	CHECK BUILD (SFR)	MOVE	RELOAD	REPAIR
Beta 92 Type SPOOL	+	-	-	-	-
Beta 93 Type SPOOL	+	+	-	+	-
Beta 93 Type RELOAD	+	+	-	+	-
Beta 93 FR Type CACHE	+	-	-	-	+
Beta 93 FR Type GLOBL	+	+	-	-	-
Beta 93 FR Type INDEX	+	+	-	-	+
Beta 93 FR Type SPOOL	+	+	+	+	+
Beta 93 FR Type RELOAD	+	+	+	+	+

License check

The following commands check for the presence of a valid license for the corresponding product:

	CHECK	CHECK BUILD (SFR)	MOVE	RELOAD	REPAIR
License article			I06		I04

Running BST05ANA in slave or master mode

You can run the utility BST05ANA in slave mode (SIGNON=YES) for almost all of the functions that are described in this section.

Exception: Spool file reorganization

BST05ANA must run in master mode (SIGNON=NO) when reorganizing spool files. This means that you must stop the _beta doc|z plus started tasks before running the batch utility with the following command:

REPAIR DSNAME(dsname) RECORD(REO) DO-IT

The started tasks can remain active when this function runs in analyze mode (same command without DO-IT).

JCL

+--------------------------------------------------------------------+
|jobcard |
|//BST05ANA EXEC PGM=BST01RFF,REGION=0M,PARM=('S=nn', |
|// 'PGM=BST05ANA', |
|// 'B01LST=xx', |
|// 'BnnLST=xx', |
|// 'SIGNON=YES') |
|//* |
|//STEPLIB DD DISP=SHR, |
|// DSN=BSA.LOAD |
|// DD DISP=SHR, |
|// DSN=BETAnn.LOAD |
|//* |
|//SFFPARM DD DISP=SHR, |
|// DSN=BETA.PARMLIB |
|//BnnDEF DD DISP=SHR, |
|// DSN=BETAnn.DB.DEF |
|//* |
|//BQLPROT DD SYSOUT=* |
|//BQLLOG DD SYSOUT=* |
|//BQLIN DD * |
| commands |
|/* |
+--------------------------------------------------------------------+

DD statements

All of the following cards are required.

DD name	Description
BQLPROT	Contents of the spool file(s) type SPOOL analyzed Notes: The presence of this DD card is checked at program start. This card must be present, even if the list of files to be analyzed does not include a spool file of type SPOOL. The keyword EXTENDED must be coded if you want to obtain this type of report for spool files of type INDEX.
BQLLOG	Processing log of the program; it contains a log of the BQLIN command(s), a list of the datasets that were analyzed, and internal information on these datasets
BQLIN	Input statements (commands that are to be carried out by BST05ANA) Each command must be coded on a separate line. You can specify wildcards in the dataset name if the task is to be carried out for all matching datasets. Supported commands are described below with the individual tasks.

Displaying spool contents (CHECK)

Availability: All spool file types of all products
(valid license for article T04 or I04 for corresponding product must be present)

Specify the following command to display the contents of a spool file:

CHECK DSNAME(dsname)

The program examines the contents of the specified spool file. If at least one page of a list is stored in the spool file under analysis, this list is displayed in DD BQLPROT.

EXTENDED to create BQLPROT for INDEX spools

Availability: _beta doc|z plus spool files of type INDEX

By default, BST05ANA does not create the BQLPROT report when analyzing spool files of the type INDEX because of performance reasons. Code the keyword EXTENDED if you need this information, for example:

CHECK DSNAME(BETA97.INDEX*) EXTENDED

BUILD(SFR) to enable spool file recovery

Availability: _beta doc|z plus spool files of type GLOBL, INDEX and SPOOL

_beta doc|z plus administrators also use the CHECK command with the subcommand BUILD(SFR) to enable full recovery for spool files with list or index fragments that have been read in before Beta 93 Fast Retrieval V4R1. This command runs once against all existing spool files of the type SPOOL and INDEX during the upgrade procedure to V4 or later, for example:

CHECK DSNAME(BETA97.SPOOL*) BUILD(SFR)
CHECK DSNAME(BETA97.INDEX*) BUILD(SFR)

BST05ANA writes an SFR record for each list or index fragment for which there is no pointer in the corresponding generation record of the database. This affects lists and indexes that span multiple spool files.

Emptying spool file (MOVE)

Availability: _beta doc|z plus spool files of type SPOOL
(valid license for article T06 or I06 must be present)

Specify the following command to empty a read-only spool file by moving all its lists to other spool files:

MOVE DSNAME(dsname)

The program examines the contents of the specified spool file. It copies each list to another spool file and deletes this list in the original spool file. If a list spans multiple spool files, the entire list is moved. All list fragments are deleted from the source spool files affected.

Notes

• The dataset status of the spool file must be READONLY.
• The MOVE command cannot be run in analyze mode, but you can run the CHECK command instead to find out which lists would be moved.

Reloading spool contents (RELOAD)

Availability: _beta doc|z plus spool files of type SPOOL

Specify the following command to reload the contents of a spool file from the archive, for example, because the spool file in question has become corrupted:

RELOAD DSNAME(dsname) DO-IT

The program carries out the following processing steps:

1. It examines the appropriate database tables to find out which data is stored in the specified spool files.
2. If the spool file under analysis is of the type SPOOL, it updates the generation records of all lists that are stored (in part or entirely) on this spool file as follows:
   • If a list is archived, it is marked as offline and to be reloaded.
   • If a list is not archived, it is marked as non-viewable and to be deleted.

   If the spool file under analysis is of the type INDEX, it updates the generation records of all indexes that are stored (in part or entirely) on this spool file as follows:

   • If an index is archived, it is marked as offline.
   • If an index is not archived, it is marked as offline; the corresponding list is marked as non-viewable and to be deleted.

For more detailed instructions on restoring spool content from the archive, see "Recovering or migrating spool contents" in _beta doc|z plus Administrator Guide.

Important requirements to enable spool file recovery:

To be able to recover the entire data of a corrupt spool file requires the following:

• The spool file must support complete recovery.

  An SFR record must be available for each list or index fragment for which there is no pointer in the corresponding generation record of the database. SFR records are generated automatically when lists and indexes are written as of Beta 93 Fast Retrieval V4R1. SFR records for earlier data in spools are generated when you run the program BST05ANA using the following command:

  CHECK DSNAME(dsname) BUILD(SFR)

• All data of this spool file must have been archived.

  If an affected list has not been archived, the program BST05ANA will mark the list for deletion and flag it as non-viewable. The remaining data of the list and its indexes will be removed from the database at the next run of the online cleanup batch utility (B97DEONL). You can recognize these lists by the value NV in the Status column of the report that is written to DD BQLPROT.

Analyze mode

If you run this command without the DO-IT parameter, the program runs in analyze mode. In this mode, the program processes all data and writes all logs, but does not actually mark any lists for reloading:

RELOAD DSNAME(dsname)

Reorganizing spool file (REPAIR)

Availability: _beta doc|z plus spool files of type SPOOL
(valid license for article I04 must be present)

Specify the following command to analyze and reorganize a spool file:

REPAIR DSNAME(dsname) RECORD(REO) DO-IT

During reorganization, blocks containing no data or invalid data are released.

Important: This command requires that BST05ANA runs in master mode (SIGNON=NO). This means that you must stop all BSA started tasks before starting the spool file reorganization.

Analyze mode

If you run this command without the DO-IT parameter, the program runs in analyze mode. In this mode, the program processes all data and writes all logs, but does not actually release any data:

REPAIR DSNAME(dsname) RECORD(REO)

Running the utility in analyze mode is useful if you want to find out how many spool file blocks would become available by reorganizing the spool files. BST05ANA can run in slave mode (SIGNON=YES) in analyze mode.

Example: DD BQLPROT

The contents of the analyzed spool files (type SPOOL only) is listed under DD BQLPROT. The following information is printed for each list:

• Name (Form, extension, report)
• List date and time
• Number of pages (according to database)
• Status

  NV appears in this column if the program BST05ANA has marked a list for deletion and flagged it as non-viewable (see RELOAD command).

  +--------------------------------------------------------------------------------------+
  |START DSNAME : QAB97.Q97V.DB.SPOOL1 |
  | |
  |FORM EXT REPORT B97DATE B97TIME PAGES STATUS |
  | ---------------------------------------------------------------------------------- |
  | |
  |REJ TRADE 09.12.2009 12:08:52:74 0000009 |
  |TC9761 NOARCH 27.11.2009 11:34:18:85 0001811 |
  |TC9761 FBM156 27.11.2009 11:34:21:46 0000003 |
  |TC9761 VBA156 27.11.2009 11:34:21:85 0000012 |
  |TC9761 DISK10000 27.11.2009 11:34:22:21 0000012 |
  |TC9761 SECIDXNOITEM 27.11.2009 11:34:24:56 0000026 |
  |TC9761 ITEMPHONE 27.11.2009 11:34:24:95 0000002 |
  |TC9761 AFPDVZ 27.11.2009 11:34:25:44 0000039 |
  |TC9761 AFPTLE 27.11.2009 11:34:26:04 0000009 |
  |TC9761 VBM135GT32K 27.11.2009 11:34:26:40 0001050 |
  +--------------------------------------------------------------------------------------+

Example: DD BQLLOG

The processing log of the BST05ANA is written to DD BQLLOG; it contains a log of the BQLIN command(s), a list of the datasets that were analyzed, and internal information on these datasets.

+-------------------------------------------------------------------------------+
|CHECK DSNAME(QAB97.Q97V.DB.SPOOL1) 00280005|
| |
| |
|START CHECK FOR FILE : QAB97.Q97V.DB.SPOOL1 |
| |
|SIR RBA : 00000000 BLOCKS ALLOCATED : 03179 WITH : 00000 READER BLOCKS |
|SIR RBA : 00000FA0 BLOCKS ALLOCATED : 01415 WITH : 00000 READER BLOCKS |
|SIR RBA : 00001F40 BLOCKS ALLOCATED : 00002 WITH : 00000 READER BLOCKS |
| |
|TIMESTAMPS FOUND : 00000038 TIMESTAMPS IN USE : 00000001 |
| |
+-------------------------------------------------------------------------------+

Return codes

0

The program was terminated normally.

16

An error has occurred, for example: Missing DD statement (BQLPROT, BQLLOG and BQLIN are required) Invalid command in DD BQLIN Spool file reorganization (REPAIR DSNAME(dsname) RECORD(REO) DO-IT) was started in slave mode (SIGNON=YES) License error (for example MOVE: license article I06/T06 for current product unavailable) Spool type or dataset status error (for example MOVE: spool file is not of type SPOOL and/or dataset status is not READONLY)