ZUDFM INIT (ZUDFM OAINIT): Initialize files

Use this command to initialize an entire file or part of a file, and to optionally release embedded pool file references or save the prime blocks.

Last updated

Changed in 2022.
Changed in 2020.
Changed for 2019.
Changed for PUT14.
Changed for PUT12.
Changed for PUT11.
Changed for PUT10.
Changed for PUT08.
Changed for PUT03.
Changed for PUT01.
Changed for PUT00.

Requirements and restrictions

You cannot enter this command while the capture and restore (ZFCRU) or recoup (ZRECP) utilities are running.
Only one file initialization can be pending on a subsystem user at a time.
When you first install the z/TPFDF product, you must initialize the z/TPFDF control files in order to use the ZUDFM INIT command.
You must enable get file storage (GFS) on the z/TPF system by being in CRAS state or higher or by entering the ZPOOL 1052 command in 1052 state before you can use this command.

Format

Optional parameters

Note: You can use either the ZUDFM INIT or ZUDFM OAINIT command.

fileid

A 2-character alphanumeric or 4-character hexadecimal file ID.

CANcel

Cancels a pending initialization that was entered from the same terminal and subsystem user. This parameter does not affect an initialization that is already in progress.

FVN/filever

Specifies the file version of a file ID, where filever is a hexadecimal number from X'00' to X'FF'.

Note: You cannot use the FVN parameter when the RELEASE parameter is specified.

|ordrange

Specifies the ordinal range within the file that will be initialized. Use one of the following forms:

|beginord-endord
|beginord-LAST

beginord: Specifies the begin ordinal, which is a decimal ordinal number with a maximum size of 10 digits.
endord: Specifies the end ordinal, which is a decimal ordinal number with a maximum size of 10 digits.
LAST: Specifies that all the ordinals are processed up to the last ordinal, including the last ordinal.

Notes:

You can use a different delimiter by setting the #DBENUFB variable in the ACPDBE macro.
If you specify the SSU-ALL parameter, the specified ordinal range must exist for every subsystem user (SSU). If the specified ordinal range is not valid on one or more SSUs, an error is issued and no initialization is performed on any SSU.

SSU

Specifies the subsystem user (SSU) where the file will be initialized. Specify one of the following values:

ssuname

The 2- to 4-character name of an SSU in the current subsystem.

ALL

Initializes all active or dormant SSUs in the current subsystem.

Notes:

If the specified ID is not defined as subsystem user unique in the database definition (DBDEF), the file is initialized only once for the current subsystem.
If the specified ID is excluded from one or more subsystem users in the database definition (DBDEF), initialization of the file on those subsystem users is skipped.

HOLD

Specifies that records are locked and held while being initialized. Processing is done by using multiple ECBs.

NOHOLD

Specifies that records are not locked or held while being initialized. Processing is done by using a single ECB.

FILE-'fqname'

Saves the prime blocks of the z/TPFDF file to a specified z/TPF file system file or mounted general tape, where fqname is the fully qualified path name.

Specify the name in one of the following formats:

If fqname is a file system file, use the fully qualified case-sensitive file system file path. For example, if you specify /mydir/myfiles/MyFile.fil for this parameter, the prime blocks of the z/TPFDF file are copied to the MyFile.fil file in the /mydir/myfiles directory. The file path that you specify must be unique. If the specified file path does not exist, the file path is created. If the specified file path exists, the prime blocks are not saved, and the z/TPFDF file is not initialized.
Note: The file system must be active if the prime blocks are saved to a z/TPF file system file.
If fqname is a mounted general tape, use the /dev/tpf_tape/tapename format, where tapename is the general tape name that you want to save the z/TPFDF file to.

If you specify the FILE parameter with the SSU-ALL parameter, the prime blocks of the z/TPFDF file for all subsystem users are saved in the specified z/TPF file system file or on the mounted general tape.

You can use the ZCFIL RESTORE command to restore the z/TPFDF files that are backed up by using this parameter. The z/TPFDF product assumes that the pool blocks that are referenced from the restored prime blocks are still available.

RELease

Specifies that embedded pool file references are released and remote subfile documents are deleted from the remote data stores. Records are locked and held during initialization. Processing is done by using multiple ECBs.

This parameter can be used only on active SSUs. If you specify the SSU-ALL parameter with the RELEASE parameter and a dormant SSU is encountered, initialization of the file is skipped on the dormant SSU.

Notes:

If you do not specify this parameter, no forward chains or embedded references are released. If you do not release all of the forward chains and embedded references, lost pool addresses might occur. In addition, all documents that correspond to remote subfiles in the file become orphaned in the remote data store.
You can specify this parameter only for z/TPFDF files; that is files that are defined with ACPDB=YES on the DBDEF macro. If you initialize a non-z/TPFDF file, lost pool addresses might occur.
If you specify this parameter for a remote subfile, the tpfrdsClient JAM must be active. Otherwise, all documents that correspond to the initialized remote subfiles become orphaned in the remote data store. For more information, see Configuring and starting the tpfrdsClient JAM.
If you specify this parameter and command processing detects an invalid embedded reference, the referenced file address is not released, but initialization processing continues.
If you specify this parameter and a system error occurs during command processing, all of the subfiles might not be correctly initialized. To ensure that all of the subfiles are correctly initialized, enter the ZUDFM INIT command again without the RELEASE parameter specified.
When you specify this parameter, command processing does not automatically deindex the referenced subfiles, even when AUTODEINDEX=YES is specified on the DBDEF macro for the referenced file. In other words, if any released pool file addresses are referenced from other subfiles, initialization processing does not remove the references from those other subfiles. This might result in file retrieval errors. Other index files and the algorithm information file must be initialized separately.
To control the maximum number of ECBs that are allocated for command processing when you specify this parameter, you can set the #DF_UDFM_MAX_ECB equate in the ACPDBE macro.
To determine the frequency that the initialization status messages are displayed, you can set the #DF_UDFM_INIT_SI equate in the ACPDBE macro.

INClude

Specifies what kind of records and files are released or deleted.

Note: If you specify the RELEASE parameter for a P-type file, only forward chains are released. Any other values specified on the INCLUDE parameters are ignored.

FCHonly

Indicates that only forward chains are released.

ALL

Indicates that all the forward chains and embedded references are released.

embedid

A 2-character alphanumeric or 4-character hexadecimal embedded file ID of the subfiles to be released. You can specify as many as 10 file IDs.

Note: If you specify embedded file IDs, the following behaviors occur:

Processing releases only subfiles with these IDs.
Processing searches for embedded references in only the subfiles with the IDs that you specify.
Processing deletes all documents in a remote data store that correspond to remote subfiles with these IDs.

Additional information

You must enter the ZUDFM INIT command twice to initialize a file. After you enter the command once, you are prompted to enter the command again to confirm the pending initialization. If you do not enter the command a second time within two minutes, the pending initialization is automatically canceled.
The use of the ZUDFM INIT command should be restricted on the live system with the ZUDFM RESTRICT command.
If you initialize a remote subfile, the initialized subfile is no longer marked remote and is stored locally.

Examples

In the following example, the specified file ID is initialized. Because a file is changed permanently when initialized, you must enter the ZUDFM INIT command twice as a precaution. The first entry displays file ID information. The second entry completes the initialization of the file ID.

User:   ZUDFM INIT B075

System: UDFM0384A 10.58.49 THE FOLLOWING FILE WILL BE INITIALIZED WITH HOLD.
                           ID-B075  FVN-00  FACET-#BTREE  SSU-COMMON
                           BOR-0000000052   EOR-0000000077

                           TO CONFIRM THE INITIALIZATION,
                           REPEAT THE COMMAND WITHIN 2 MINUTES.

User:   ZUDFM INIT B075

System: UDFM0383I 10.59.12 ZUDFM DATABASE INITIALIZATION COMPLETED
                           ID-B075  FVN-00  TOTAL ORDINALS-0000000026

In the following example, the database with the specified file ID B075 is initialized, and all the referenced pool files with ID B076 or B077 are released. The initialization status message is issued because the initialization process takes longer than the time that you specified by using the #DF_UDFM_INIT_SI equate in the ACPDBE macro.

User:   ZUDFM INIT B075 RELEASE INC-B076/B077

System: UDFM0384A 11.07.06 THE FOLLOWING FILE WILL BE INITIALIZED WITH RELEASE.
                           ID-B075  FVN-00  FACET-#BTREE  SSU-COMMON
                           BOR-0000000000   EOR-0000031903

                           TO CONFIRM THE INITIALIZATION,
                           REPEAT THE COMMAND WITHIN 2 MINUTES.

User:   ZUDFM INIT B075 RELEASE INC-B076/B077

System: UDFM0424I 11.07.22 DATABASE INITIALIZATION RUNNING FOR ID B075, FVN 00 
          TOTAL ORDINALS       -      31904   
          COMPLETED ORDINALS   -      31300 
          ACTIVE ORDINALS      -         10 
          NOT STARTED ORDINALS -        594
        END OF DISPLAY
        UDFM0383I 11.07.46 ZUDFM DATABASE INITIALIZATION COMPLETED
                           ID-B075  FVN-00  TOTAL ORDINALS-0000031904

In the following example, the four prime blocks in the database with file ID B311 are saved to a file in the z/TPFDF hierarchical file system (HFS). The database is initialized.

User:   ZUDFM INIT B311 FILE-'/mydir/myfile.save'

System: UDFM0384A 10.13.04 THE FOLLOWING FILE WILL BE INITIALIZED WITH HOLD.
                           ID-B311  FVN-00  FACET-#IR11AS  SSU-COMMON
                           BOR-0000000000   EOR-0000000003

                           TO CONFIRM THE INITIALIZATION,
                           REPEAT THE COMMAND WITHIN 2 MINUTES.

User:   ZUDFM INIT B311 FILE-'/mydir/myfile.save'

System: UDFM0383I 10.13.36 ZUDFM DATABASE INITIALIZATION COMPLETED
                           ID-B311  FVN-00  TOTAL ORDINALS-0000000004

In the following example, an SSU-unique file ID is initialized on the target subsystem user in the current subsystem. The first entry displays file ID information. The second entry completes the initialization of the file ID.

User:   ZUDFM INIT C211 SSU-SSUC NOHOLD

System: UDFM0384A 10.58.49 THE FOLLOWING FILE WILL BE INITIALIZED WITH NOHOLD.
                           ID-C211  FVN-00  FACET-#GRT1SR  SSU-SSUC
                           BOR-0000000081   EOR-0000000106
               
                           TO CONFIRM THE INITIALIZATION,
                           REPEAT THE COMMAND WITHIN 2 MINUTES.

User:   ZUDFM INIT C211 SSU-SSUC NOHOLD

System: UDFM0383I 05.14.42 ZUDFM DATABASE INITIALIZATION COMPLETED
                           ID-C211  FVN-00  TOTAL ORDINALS-0000000026

In the following example, the specified SSU-unique file ID is initialized on all subsystem users for the current subsystem. The first entry displays file ID information. The second entry begins the file initialization on the first SSU. Notification is provided when the initialization on each SSU completes and when all initialization processing completes.

User:   ZUDFM INIT C211 SSU-ALL

System: UDFM0384A 10.54.46 THE FOLLOWING FILE WILL BE INITIALIZED WITH HOLD.
                           ID-C211  FVN-00  FACET-#GRT1SR  SSU-ALL
                           BOR-0000000000   EOR-00000010000

                           TO CONFIRM THE INITIALIZATION,
                           REPEAT THE COMMAND WITHIN 2 MINUTES.

User:   ZUDFM INIT C211 SSU-ALL

System: ...
        UDFM0386I 10.55.12 ZUDFM DATABASE INITIALIZATION COMPLETED ON SSU SSU1
                           ID-C211  FVN-00  BOR-0000000000  EOR-0000010000
        ...
        UDFM0386I 10.55.42 ZUDFM DATABASE INITIALIZATION COMPLETED ON SSU BOB
                           ID-C211  FVN-00  BOR-0000000000  EOR-0000010000
        ...
        UDFM0386I 10.56.12 ZUDFM DATABASE INITIALIZATION COMPLETED ON SSU SSUC
                           ID-C211  FVN-00  BOR-0000000000  EOR-0000010000 
        ...
        UDFM0383I 10.56.12 ZUDFM DATABASE INITIALIZATION COMPLETED
                           ID-C211  FVN-00  TOTAL ORDINALS-0000030003