FORMAT

The FORMAT utility prepares a database file, area, segment, SYSTRK or disk journal file for use by CA IDMS/DB.
idmscu19
The FORMAT utility prepares a database file, area, segment, SYSTRK or disk journal file for use by CA IDMS/DB.
This article describes the following information:
2
2
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
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 ┤                                                               └ % ──────┘  
Parameters
  • SEGMENT
    Formats all files associated with the specified segment.
  • segment-name
    Specifies the name of a segment included in the DMCL module.
    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.
    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.
    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
    .
    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.
Usage
How to submit the FORMAT statement
A FORMAT AREA or FORMAT SEGMENT statement can be submitted through either the batch command facility or the online command facility. The batch command facility can be run in either local mode or under the central version. When submitted in local mode, FORMAT SEGMENT will behave like a FORMAT FILE for each file in the segment. When running under central version, it will behave like a FORMAT AREA for each area in the segment.
The FORMAT FILE, FORMAT SYSTRK, and FORMAT JOURNAL statements can be submitted only through the batch command facility in local mode.
When to use FORMAT
You must use the FORMAT utility to prepare:
  • Database files before loading any data into the database
  • Disk journal files before any journaling to the files occurs
  • SYSTRK files before they can be referenced as SYSTRK files in any CA IDMS execution JCL.
When necessary, you also use the FORMAT statement to
reformat
database files and areas, SYSTRK files and disk journal files.
When not to use the FORMAT statement
Do not try to reformat a file, area, or journal that is currently active under a DC/UCF system. Do not format an existing journal if it contains journal records that might be needed for recovery.
When formatting SQL-defined segments
When formatting an area or segment that contains SQL-defined tables, be sure you are connected to the catalog segment where the table definitions reside. You can issue an explicit CONNECT to the DBNAME of the dictionary containing the catalog segment or to the actual segment where the table definitions reside.
How FORMAT formats a database file or area
The FORMAT statement formats a database file or area into pages using information contained in the DMCL module. When formatting a database file or area, the FORMAT statement:
  • Establishes space management pages (SMPs)
  • Initializes the space management entry for each database page
  • Establishes a header and footer on each database page
  • Sets all data portions of each database page to binary zeros
  • Stores synchronization stamps when formatting areas or segments of an SQL-defined database
Restriction on the AREA parameter
When formatting a database by file, a sequential access method (QSAM) is used. When formatting a database by area, a direct access method is used. Because the database must be formatted into blocks by a sequential access method before it can be processed using a direct access method, you can use the AREA parameter of the FORMAT statement only when you are
reformatting
the area.
A format by segment in local mode is equivalent to format by file in this regard, and can be used to format new files. Format by segment under central version is equivalent to format by area and can only be used to reformat existing areas.
Area format depends on the area lock
In local mode, to prevent inadvertent formatting of an area that is being updated by another application, the area is locked for the duration of the operation when formatting by area. If the area is already locked, the format will not take place.
Formatting a locked area
If a local mode application abends while an area is being updated, the lock could remain on the area. In this case, you can either explicitly unlock the area using the UNLOCK utility, you can format by file, or you can use the ALREADY LOCKED option.
If ALREADY LOCKED is specified and the area was locked, the area will remain locked after the format is complete. The ALREADY LOCKED option is not required if formatting an area online or through batch/CV and is ignored if specified.
Formatting by segment does not lock areas
If you format by segment in local mode, the FORMAT utility does not lock the areas involved.
Reformatting an area
You can reformat a database by file, by area, or by segment. Processing by file is more efficient than processing by area. However, if you format by file in an SQL-defined database, you must run the INSTALL STAMPS utility for each affected area or segment.
How FORMAT formats a disk journal file
The FORMAT utility formats a disk journal file into blocks according to the journal file definition in a DMCL module. The FORMAT utility writes a journal header record at the beginning of each block and sets the remainder of the block to binary zeros, except when the FAST parameter is specified. The FAST parameter, used only with previously initialized journal files, reinitializes the header files only.
Formatting disk journal files
A certain amount of space is reserved in each disk journal file for information about other systems with which a system communicates. All journal files must have the same amount of space since the data in one journal file is replicated to every other journal file.
You can specify the size or allow it to default. The actual size allocated may be higher than the value specified due to rounding. Space is allocated in blocks whose size is (journal block size minus 256). By default, one block is allocated. Additional blocks are allocated if needed until the total size meets or exceeds the size specified. If the journal block size is less than 256, no space will be reserved.
Committing prior work
Before executing this utility under a central version, you must commit any previous work done within the current session. For more information, see Central Version Considerations.
When to use MAX AREA
Normally when a journal is formatted, a fixed number of JHDA blocks are created. A JHDA block stores the ready status of areas for warmstart purposes. The size of a journal block and the number of JHDAs limit the number of areas that a Central Version can have open at one time.
The MAX AREA option lets a journal be formatted that can handle more areas without increasing the size of a journal block. Ideally, the size of a journal block should be optimized to improve runtime efficiency, and should not be affected by the number of areas that might exist.
The MAX AREA option can also reduce the number of JHDA blocks that are created, which frees journal space.
To calculate the number of areas that one JHDA journal block can handle, use the following formula:
number_of_AREAS = (jrnl_blksize - 32) / 8
When MAX AREA is not specified, the FORMAT utility command will create 3 JHDA blocks. The number of areas that the default will support will vary depending on the journal block size. For example if the journal were formatted with a block size of 2032 bytes, 750 areas could be open at one time, 250 per JHDA.
Native VSAM files
Native VSAM files that are to be accessed by CA IDMS/DB are not structured like CA IDMS/DB database files. Do not use the FORMAT statement against native VSAM files.
Formatting areas and segments under central version
The areas to be formatted must be in update mode to CV. The physical area lock for each area will remain on during and after the format. A logical area lock is acquired to prevent online transactions from updating the area during the format. If other online transactions are holding a logical area lock, Format will wait until the locks are released. If the wait would cause a deadlock, the format will be aborted. Once acquired, the logical area lock is released when a commit transaction is explicitly issued, or implicitly when the batch step ends, or at the end of the pseudo-converse when running online.
Referencing SYSTRK Files During Format
To avoid I/O errors when building the runtime environment in local mode, only previously formatted files should be referenced using a DDname that matches the SYSTRK DDname prefix. For this reason, it is recommended that non-matching DDnames always be used to identify SYSTRK files being formatted.
SYSTRK File Attributes
If a SYSTRK file is being formatted to be added as a mirror of an existing file, the page sizes of the two files must be the same and the file being formatted must have at least as many pages as the existing file. If these criteria are not met the following conditions can occur:
  • Any attempt to make the newly formatted file an active mirror of the existing file fails.
  • If a LIKE parameter is specified, FORMAT does not copy the contents of the file specified by
    ddname2
    to the newly formatted file.
If INITIAL is not specified, the page size and number of pages of a file being formatted remain unchanged.
If INITIAL is specified, the number of pages written to the file is determined according to the following precedence rules:
  • If a FILE SIZE parameter is specified, then the number of pages is
    number-of-pages
    .
  • If a LIKE parameter is specified, then the number of pages is a value based on the number of pages in the file identified by
    ddname2
    . The value is calculated as:
    page-cnt * (100 + pct-increase) / 100
    • page-cnt
      Specifies the number of pages in the file identified by
      ddname2
      .
    • pct-increase
      Specifies the value in the EXPAND parameter, if specified or 0.
  • The number of pages is a value based on the size of the current DMCL calculated as:
    ((DMCL-size + page-size -1) / page-size)*4
    • DMCL-size
      Specifies the size of the DMCL load module.
    • page-size
      Specifies the page size of the file being formatted.
In the latter two cases, the number calculated is rounded up to the next larger integer value. If the calculated value is less than the minimum, it is set to the minimum of 10. If the calculated value is larger than the maximum, it is set to the maximum of 999,999.
If INITIAL is specified, the size of the pages written to a non-VSAM file is determined according to the following precedence rules:
  • If PAGE SIZE is specified, then the page size is
    page-size
    .
  • If a block size has been assigned (for example, specified in JCL or at the time the file was created), then page size is the block size.
  • If a LIKE parameter is specified, then page size is the
    page-size
    of the file identified by
    ddname2
    .
  • Otherwise, the page size is 7548.
For VSAM files, the page size is the file record size. Any attempt to override this through a PAGE SIZE parameter fails.
Choosing a SYSTRK Page Size
In most cases, the FORMAT utility's default page size for SYSTRK files provides an acceptable trade-off between memory, I/O, and disk space. Consider overriding the default only if the size of the DMCL is extremely large (500K or more). A larger page size will reduce I/Os and disk space requirements at the expense of slightly increased memory usage for buffers.
Estimating the Minimum Number of Pages for a SYSTRK File
To estimate the minimum number of pages needed for a SYSTRK file, perform the following steps:
  1. Take the size of the DMCL load module used by the CV, divide it by the SYSTRK page size and multiply it by 2.5.
  2. Multiply the resulting value with a factor to allow for overrides and growth. Overrides require approximately 100 bytes of space each and are generated for:
    • Each database or journal file defined in the execution JCL
    • Each dynamic change in the data set name of a database or journal file
    • Each dynamic change in the permanent status of an area
    • Each dynamic change in the status of a journal file
Copying SYSTRK File Contents
If a LIKE parameter is specified, the contents of the file identified by
ddname2
are copied to the files being formatted unless the file identified by
ddname2
is in use by a CV or the attributes of the two files are incompatible. If the contents of
ddname2
are not copied, a message indicates the reason.
If the file attributes are compatible, specify the keyword ACTIVE to force the copy to occur even if the file identified by
ddname2
is in use by CV. Only do this if you are sure that CV will not update the file while the copy is in progress, otherwise, the contents of the two files may not be the same which can lead to unpredictable results during CV restart. Ensure that a CV does not update its SYSTRK files by varying change tracking inactive before doing the format.
There is normally no need to force the contents of SYSTRK files to be copied. CV automatically updates newly formatted SYSTRK files as part of making them active mirrors.
JCL Considerations
When you submit a FORMAT statement through the batch command facility in local mode, the JCL to execute the facility must include statements to define the following:
  • Database files to be processed (or that map to the areas to be processed)
  • Journal files to be processed
  • Dictionary containing table definitions, if formatting all or part of an SQL-defined database by area or by segment.
  • SYSTRK files to be processed
To run under the batch command facility under central version, include a SYSCTL statement.
For more information about the generic JCL used to execute the batch command facility, see the section for your operating system in this section.
Examples
Formatting a segment
The following illustration shows a segment that includes three files:
┌────────┬────────┬────────┐ │ FILE_1 │ FILE_2 │ FILE_3 │ ├────────┴────────┴────────┤ │        SEGMENT_A         │ └──────────────────────────┘
To format all the files associated with the segment illustrated above, you could use the following FORMAT statement:
format segment segment_a;
Reformatting by database file
The following left-hand illustration shows two areas, each of which maps to a single database file. The right-hand illustration shows a single area that maps to two database files.
┌────────────┬────────────┐          ┌────────────┬────────────┐ │   FILE_1   │   FILE_2   │          │   FILE_1   │   FILE_2   │ ├────────────┼-----------─┤          ├────────────┴────────────┤ │   AREA_A   │   AREA_B   │          │         AREA_A          │ └────────────┴────────────┘          └─────────────────────────┘
The FORMAT utility can reformat the portions of the database illustrated above either by file or by area. However, because processing by file is more efficient, you would use the following FORMAT statements to do the job in both cases:
format file segment_a.file_1; format file segment_a.file_2;
Reformatting by area
The following left-hand illustration shows two areas that map to a single database file. The right-hand illustration shows an area that maps to two database files, one of which also contains another area.
┌─────────────────────────┐          ┌────────┬────────────────┐ │         FILE_1          │          │ FILE_1 │     FILE_2     │ ├────────────┬────────────┤          ├────────┴───────┬────────┤ │   AREA_A   │   AREA_B   │          │     AREA_A     │ AREA_B │ └────────────┴────────────┘          └────────────────┴────────┘
To reformat AREA_A in either illustration, you must use the following FORMAT statement:
format area segment_a.area_a;
Formatting a journal file
The following FORMAT statement requests formatting of the disk journal named SYSJRNL1:
format journal sysjrnl1;
Formatting by SEGMENT
In the following example, three database files are formatted for an SQL-defined database using the SEGMENT option of the FORMAT utility.
A CONNECT to the segment or database name containing the table definitions is issued. This is necessary so that the INSTALL STAMPS utility can automatically install area and table stamps during the FORMAT operation.
connect to syssql;  format segment userdb;
Formatting SYSTRK Files
The following sample IDMSBCF statement instructs the FORMAT utility to format three new SYSTRK files (track01, track02, track03). It directs the utility to format the files to have the default page size of 7548 and contain 60 pages each. CA IDMS will maintain 3 active mirrors.
format systrk track01, track02, track03    initial file count 3    file size 60;
Sample Output
Formatting by SEGMENT
The following listing was generated after the successful completion of the previous FORMAT SEGMENT USERDB example.
IDMSBCF                                              IDMS Batch Command Facility                            mm/dd/yy   PAGE 5     CONNECT TO SYSSQL;  Status = 0     FORMAT SEGMENT USERDB;  File USERDB.EMPF1                blocks 1 to 50.  Area USERDB.EMP_AREA             pages 5,001 to 5,050.  Page size in file 4,096.  File USERDB.ORGF1                blocks 1 to 50.  Area USERDB.ORG_AREA             pages 5,051 to 5,100.  Page size in file 4,096.  File USERDB.EMPIX                blocks 1 to 50.  Area USERDB.EMPIX_AREA           pages 5,101 to 5,150.  Page size in file 2,000.  Status = 0  AutoCommit will COMMIT transaction  Command Facility ended with no errors or warnings
For more information about allocating CA IDMS/DB files, see the
CA IDMS Database Administration Section
.
Formatting SYSTRK Files
The following listing was generated after the successful completion of the previous FORMAT SYSTRK example.
IDMSBCF                              CA IDMS Batch Command Facility FORMAT SYSTRK TRACK01, TRACK02, TRACK03        INITIAL FILE COUNT 3 FILE SIZE 60; Systrk file TRACK01 page size 7,548 file size 60         delete NULL file count 3. Systrk file TRACK02 page size 7,548 file size 60         delete NULL file count 3. Systrk file TRACK03 page size 7,548 file size 60         delete NULL file count 3. Status = 0        SQLSTATE = 00000 AutoCommit will COMMIT transaction Command Facility ended with no errors or warnings