FORMAT

The FORMAT utility prepares a database file, area, segment, SYSTRK or disk journal file for use by CA IDMS/DB.

Authorization

To FORMAT	You Need This Privilege	On
An area	DBAWRITE	The area
A segment	DBAWRITE	All areas of the segment
A file	DBAWRITE	All areas that map to the file
A disk journal file	USE	The DMCL
A SYSTRK file	USE	The DMCL

FORMAT Syntax

►►─── FORMAT ─────────────────────────────────────────────────────────────────►

 ►─┬─ SEGMENT segment-name ──────────────────────────────────────────────────┬►◄
   ├─ FILE segment-name.file-name ───────────────────────────────────────────┤
   ├─ AREA segment-name.area-name ──┬─────────────────────────────────┬──────┤
   │                                ├────────────────┬─── LOCKED ─────┘      │
   │                                └─ ALREADY ──────┘                       │
   │                                  ┌─────────────────────────────────────┐│
   ├─ JOURNAL ─┬─ journal-file-name ─┬▼─┬──────────────────────────────────┬┴┤
   │           └─ ALL ───────────────┘  ├─ MAX AREA nnnn ──────────────────┤ │
   │                                    ├┬──────┬─ STORAGE ─┬──────┬─ nnn ─┤ │
   │                                    │└ DATA ┘           └ SIZE ┘       │ │
   │                                    └─ FAST ───────────────────────────┘ │
   └─ SYSTRK ── SYSTRK-format-options ───────────────────────────────────────┘

Expansion of SYSTRK-format-options

      ┌─────────,─────┐
►─────▼── target-ddn ─┴──────┬──────────────────────────────────────────┬─────►◄
                             └─ INITIAL ┬───────────────────────────┬───┘
                                        └─ initial-SYSTRK-options ──┘

Expansion of initial-SYSTRK-options

    ┌───────────────────────────────────────────────────────────────────────┐
►───▼──┬─ FILE COUNT file-cnt ─────────────────────────────────────────────┬┴─►◄
       ├─ DELETE ┬ ON ─┬───────────────────────────────────────────────────┤
       │         └ OFF ┘                                                   │
       ├─ PAGE SIZE page-size ─────────────────────────────────────────────┤
       ├─ FILE SIZE number-of-pages ───────────────────────────────────────┤
       └─ LIKE ─ ddname2 ─┬────────┬─┬────────────────────────────────────┬┘
                          └ ACTIVE ┘ └ EXPAND ─ pct-increase ─┬─────────┬─┘
                                                              ├ percent ┤
                                                              └ % ──────┘

FORMAT Parameter

SEGMENT

Formats all files associated with the specified segment.

segment-name

Specifies the name of a segment included in the DMCL module.

Note: If you are formatting a segment of an SQL-defined database, synchronization time stamps for all areas in the segment are also stored.

FILE

Formats the specified file.

segment-name

Identifies the segment associated with the file.

file-name

Identifies the name of a database file described by the DMCL module.

AREA

Formats the files associated with the specified area. Only the portion of each file that maps to pages in the area is formatted.

If you are formatting an SQL-defined area, synchronization time stamps are stored for the area.

Note: You can use the AREA parameter only when you are reformatting an area that has been formatted at least once before.

ALREADY LOCKED

Specifies that if the target area or areas are currently locked, processing will continue. This option is honored in local mode only. It is ignored when processing under the central version and has no effect on the processing of unlocked areas.

segment-name

Specifies the name of the segment associated with the area.

area-name

Specifies the name of an area included in the DMCL module.

JOURNAL

Formats the specified disk journal file.

journal-file-name

Specifies the name of a disk journal file included in the DMCL module.

ALL

Formats all disk journals in the DMCL.

MAX AREA nnn

The maximum number of areas to define for the journal, where nnn is an integer from 1 to 100,000. The actual number of areas that CA IDMS/DB can handle can be higher because of rounding and the size of a journal block.

DATA STORAGE SIZE nnn

Specifies the amount of space to reserve in 1K (1024 bytes) increments for Data Storage in a journal file, where nnn is an integer from 1 32,767.

FAST

Formats only the journal header blocks of already existing and formatted journal files. If MAX AREA is specified, the number of JHDA entries are recalculated and the number formatted may change. If the STORAGE clause is specified, the number of JHD2 entries are recalculated and the number formatted may change.

SYSTRK

Indicates that one or more SYSTRK files are to be formatted.

target-ddn

Specifies the DDname or linkname of a SYSTRK file to be formatted.

Note: The target-ddn should not begin with the DDname prefix used for referencing SYSTRK files. Otherwise, CA IDMS attempts to use it for building the DMCL definition and fails if it cannot do so.

INITIAL

Indicates this is the first time the SYSTRK file is being formatted. If specified, no check is made to determine whether the file is in use by a CV. INITIAL must be specified the first time a file is formatted. It should not be specified when a file is being re-formatted unless you are sure that the file is not in use by a CV.

file-cnt

Specifies the number of SYSTRK files that are maintained as active mirrors. The file-cnt must be an integer in the range 2 through 4.

If file-cnt is not specified, the value is taken from the file identified by ddname2, if specified, or at run time from the file count currently in use by the DC/UCF system. If file-cnt has never been specified on a format for a related SYSTRK file, the first time that a DC/UCF system writes to a set of SYSTRK files, it sets file-cnt to be the lesser of the number of files currently allocated and 4. The value can be altered dynamically by a DCMT VARY CHANGE TRACKING command.

DELETE

Specifies whether the DC/UCF system is to automatically delete obsolete SYSTRK files.

ON: (z/OS and z/VM systems only) Enables automatic file deletion.
OFF: Disables automatic file deletion.

If DELETE is not specified, the value is taken from the file identified by ddname2, if specified, or at run time from the delete option currently in use by the DC/UCF system. If DELETE has never been specified on a format for a related SYSTRK file, the first time that a DC/UCF system writes to a set of SYSTRK files, it sets the option to OFF. The option can be altered dynamically by a DCMT VARY CHANGE TRACKING command.

page-size

Specifies the size of each page to be written to the SYSTRK file being formatted and must be an integer in the range 4088 through 32764. On z/VM, the value must be 4096. On z/OS, the maximum page-size is 32760. Do not specify page-size for VSAM files.

number-of-pages

Specifies the number of pages to be written to the SYSTRK file being formatted and must be an integer in the range 10 through 999,999.

ddname2

Specifies the DDname of a file from which the attributes and contents may be taken. If ddname2 is specified together with either or both page-size and number-of-pages, the latter values override the respective attributes of the file identified by ddname2.

Note: ddname2 should not begin with the DDname prefix used for referencing SYSTRK files unless the identified file contains the DMCL definition to be used during execution of the command facility.

ACTIVE

Indicates that the contents of the file identified by ddname2 are to be copied to the file being formatted even if the file identified by ddname2 is currently in-use by a CV.

pct-increase

Specifies the percentage increase in the number of pages written to the file being formatted over the number of pages in the file identified by ddname2. The pct-increase must be an integer in the range 0 through 1000.