CRUISING with TPFDF
Tom Brocker, IBM TPF ID Core Team, and Rob Dunn, IBM TPF Development

TPFDF PUT 11 APAR PQ23489 introduced the capture/restore utility, information and statistics environment (CRUISE), a versatile and easy-to-use method of managing your database.

Based on file information stored in the TPFDF database definition (DBDEF), CRUISE is a process of recovering and validating data, controlling pool space, and creating statistics. CRUISE is a complete replacement for the ZUREC utility and provides the following improvements:

The ZFCRU commands are used to process CRUISE parameter tables. CRUISE uses the information stored in a parameter table to determine what processing should occur when starting a table. If you "hit a bump in the road," help is available by using the ZFCRU HELP command.

A CRUISE function comprises the process of performing the steps specified by a parameter table. These CRUISE functions are:

After installing APAR PQ23489 and before you can create your first CRUISE parameter table, complete the following steps:

  1. Create the parameter table index by using the ZFCRU EXPAND command; for example:
  2. ZFCRU EXPAND
    CSMP0097I 16.04.13 CPU-B SS-BSS  SSU-HPN  IS-01
    FCRU0009I 16.04.13 OK TABLE - EXPANSION - COMPLETED
  3. Set the default parameter table values. This is required even if you do not need to make any changes to the parameter table values. These default values are used as the initial settings when creating parameter tables. To set a default value, use the ZFCRU DEFAULT command. Additionally, these default values override the defaults created when CRUISE was compiled with the c$cruusr header file (which can be set by the user). In the following example, default value USABLE ECB START VALUE is set to 20%:
 ZFCRU DEFAULT ECB-20
 CSMP0097I 16.04.26 CPU-B SS-BSS  SSU-HPN  IS-01
 FCRU0000I 16.04.26 MODIFIED
 FCRU0000I 16.04.26 DEFAULT PARAMETER VALUES
 USABLE ECB START VALUE     20 PCT
 BUILD STATISTICS           YES
 NUMBER OF PRINT MESSAGES   ALL
 PRINTER ADDRESSES          000000  000000  000000 
 NUMBER OF LOG MESSAGES     ALL
 SET POOL ADDRESSES IN USE  NO
 TAPE NAME                  BFA
 TARGET SYSTEM NAME         TPF
 RESTORE OPTION             REBUILD/NORELEASE
 WID/ADR IMBED REFERENCES   YES
 FCRU0000I 16.04.26 END OF DISPLAY

You are now ready to use CRUISE to create and set up your first parameter table. By using the steps that follow, you will create a parameter table that will capture the database indexed by the B075 record ID:

  1. The parameter table must be locked before you can change the values. A parameter table is created by being locked if the parameter table does not already exist. To create and lock the CAPTURE_B075 table, use the ZFCRU LOCK command; for example:
  2. ZFCRU LOCK-CAPTURE_B075
    CSMP0097I 16.31.27 CPU-B SS-BSS  SSU-HPN  IS-01
    FCRU0000I 16.31.27 TABLE LOCKED
    FCRU0000I 16.31.27 PARAMETER TABLE DISPLAY FOR CAPTURE_B075
      FUNCTION
      USABLE ECB START VALUE     20 PCT
      TAPE NAME                  BFA
      TARGET SYSTEM NAME         TPF 
      WID/ADR IMBED REFERENCES   YES
      BUILD STATISTICS           YES
      NUMBER OF PRINT MESSAGES   ALL
      NUMBER OF LOG MESSAGES     ALL
      RESTORE OPTION             REBUILD/NORELEASE
    FCRU0000I 16.31.27 END OF DISPLAY

    Note: As with other parameter table commands, the ZFCRU LOCK command displays all the current parameter table settings.

  3. To capture the B075 database to a BFA tape, set the FUNCTION and REFERENCE ID parameter table values by using the ZFCRU SETUP command; for example:
     ZFCRU SETUP FUNCTION-CAPTURE REF-B075
     CSMP0097I 16.32.18 CPU-B SS-BSS  SSU-HPN  IS-01 
     FCRU0000I 16.32.18 MODIFIED
     FCRU0000I 16.32.18 PARAMETER TABLE DISPLAY FOR CAPTURE_B075
       FUNCTION                   CAP
       USABLE ECB START VALUE     20 PCT
       TAPE NAME                  BFA
       TARGET SYSTEM NAME         TPF
       WID/ADR IMBED REFERENCES   YES 
       BUILD STATISTICS           YES
       NUMBER OF PRINT MESSAGES   ALL
       NUMBER OF LOG MESSAGES     ALL
       REFERENCE ID               B075
     FCRU0000I 16.32.18 END OF DISPLAY

    In the previous example, you did not have to set the TAPE NAME value because BFA was the default.

  1. Before starting parameter table processing, the parameter table is unlocked by using the ZFCRU UNLOCK command; for example:
  2. ZFCRU UNLOCK-CAPTURE_B075
    CSMP0097I 16.32.54 CPU-B SS-BSS  SSU-HPN  IS-01
    FCRU0009I 16.32.54 OK TABLE - CAPTURE_B075 - UNLOCKED

    During unlock processing, the parameter table values are verified. If the values do not pass verification, an error message is issued and the table is unlocked.

  3. Now, the CAPTURE_B075 parameter table is ready to start, but do not forget to mount the BFA tape!
  4. Starting a parameter table is a two-step process. The first step verifies the parameter table values by using the ZFCRU START command; for example:
  5. ZFCRU START-CAPTURE_B075
    CSMP0097I 16.37.20 CPU-B SS-BSS  SSU-HPN  IS-01
    FCRU0021I 16.37.20 TABLE -CAPTURE_B075- ACTIVATED
    CSMP0097I 16.37.20 CPU-B SS-BSS  SSU-HPN  IS-01
    FCRU0000I 16.37.20 PARAMETER TABLE DISPLAY FOR CAPTURE_B075
      FUNCTION                   CAP
      USABLE ECB START VALUE     20 PCT
      TAPE NAME                  BFA
      TARGET SYSTEM NAME         TPF
      WID/ADR IMBED REFERENCES   YES 
      BUILD STATISTICS           YES
      NUMBER OF PRINT MESSAGES   ALL
      NUMBER OF LOG MESSAGES     ALL
      REFERENCE ID               B075
    FCRU0000I 16.37.20 REPEAT ENTRY TO START CRUISE

    If the values do not pass verification, an error message is issued and processing is stopped.

  6. If the values pass verification, you can start the capture by using the ZFCRU START command again; for example:
ZFCRU START-CAPTURE_B075
CSMP0097I 16.37.56 CPU-B SS-BSS  SSU-HPN  IS-01
FCRU0001I 16.37.56 TABLE -CAPTURE_B075- FUNCTION-CAP STARTED
CSMP0097I 16.37.56 CPU-B SS-BSS  SSU-HPN  IS-01
FCRU0001I 16.37.56 TABLE -CAPTURE_B075- FUNCTION-CAP STARTED
CSMP0097I 16.37.57 CPU-B SS-BSS  SSU-HPN  IS-01
FCRU0019I 16.37.57 00000059 RECORDS FOUND
                   00000059 RECORDS WRITTEN TO BFA
CSMP0097I 16.37.57 CPU-B SS-BSS  SSU-HPN  IS-01
FCRU0006I 16.37.57 TABLE -CAPTURE_B075- FUNCTION-CAP COMPLETED
                   00000000 ERRORS DETECTED
CSMP0097I 16.37.57 CPU-B SS-BSS  SSU-HPN  IS-01
COTC0300A 16.37.57 TCLS HPN    REMOVE BFA FROM DEVICE 421
                   VSN A00111 G     S0001 F38K     SL  NOBLK  NOCOMP 

You have successfully captured the database referenced by the B075 file ID to the BFA tape!

In addition to being able to capture a database to tape, CRUISE provides support for restoring data from tape, verifying data structures, and packing data structures. TPFDF PUT 12 APAR PQ23871 also enhanced CRUISE to use CINFC instead of globals; and CRUISE messages were standardized among other changes.

For more information about these functions and other ZFCRU commands, see the following TPFDF publications: