AREA Statements

The AREA statements create, alter, delete, display, or punch the definition of an area in the dictionary.
idms19
The AREA statements create, alter, delete, display, or punch the definition of an area in the dictionary.
2
2
Authorization
  • To create, alter, or drop an area, you must have the following privileges:
    • DBADMIN on the dictionary in which the area definition resides
    • ALTER on the segment with which the area is associated
  • To display or punch an area, you must have DISPLAY privilege on the segment with which the area is associated or DBADMIN on the dictionary in which the area definition resides
Syntax
CREATE/ALTER AREA
►►─┬─ CREATE ─┬─ physical AREA ─┬─────────────────┬─
area-name
───────────────► └─ ALTER ──┘ └─
segment-name
. ─┘ ►─┬──────────────────────────────────────────┬───────────────────────────────► ├─
initial-page-range-specification
───────┤ └─ EXTEND SPACE
extend-page-count
pages ───┘ ►─┬─────────────────────────────────────────┬────────────────────────────────► └─ PAGE SIZE
character-count
characters ──┘ ►─┬────────────────────────────────────────────────────────────────┬─────────► └─ PAGE RESERVE size ─┬─ 0 ◄──────────────────────┬─ characters ─┘ └─
reserve-character-count
─┘ ►─┬──────────────────────────────────────────────────────────┬───────────────► └─ ORIGINAL PAGE SIZE
original-character-count
characters ─┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ STAMP BY ─┬─ TABLE ─┬─┘ └─ AREA ──┘ ►─┬──────────────────────────────────┬───────────────────────────────────────► └──── TIMESTAMP
timestamp-value
───┘ ►─┬────────────────────────────────┬─────────────────────────────────────────► │ ┌────────────────────────────┐ │ └─▼──
symbol-specification
────┴─┘ ►─┬─────────────────────────────────┬────────────────────────────────────────►◄ │ ┌─────────────────────────────┐ │ └─▼────
file-specification
─────┴─┘
DROP AREA
►►── DROP physical AREA ─┬─────────────────┬─
area-name
──────────────────────►◄ └─
segment-name
. ─┘
initial_page
►►─── PRIMARY SPACE
primary-page-count
pages FROM page
start-page
────────────► ►─┬──────────────────────────────────────┬───────────────────────────────────►◄ └─ MAXIMUM SPACE
max-page-count
pages ─┘
symbol_specification
►►─┬───────────────┬──────────────────────────────────────────────────────────► ├─┬─ ADD ◄────┬─┤ │ └─ INClude ─┘ │ └─┬─ DROP ────┬─┘ └─ EXClude ─┘ ►─┬─ SUBAREA
symbolic-subarea-name
─┬─────────────────────────┬────────────┬─►◄ │ └─
subarea-specification
─┘ │ ├─ SYMBOLIC DISPLACEMENT
symbolic-displacement-name
─┬──────────────────┬┤ │ └─
page-cnt pages
─┘│ └─ SYMBOLIC INDEX
symbolic-index-name
─┬───────────────────────┬─────────┘ └─
index-specification
─┘
subarea_specification
►►─┬─ FROM page
start-page
THRU page
end-page
───────────────────────────┬────►◄ ├─ SPACE
subarea-page-count
pages FROM page
subarea-start-page
───────┤ └─ OFFSET ─┬─ 0 ◄──────────────────────┬─ FOR ─┬─ 100 PERCENT ◄─────┬─┘ ├─
offset-page-count
PAGEs ─┤ ├─
percent
PERCENT ──┤ └─
offset-percent
PERCENT ──┘ └─
page-count
PAGEs ─┘
index_specification
►►─┬ BLOCK CONTAINS
key-count
keys ─┬───────────────────────────────┬───────┬─►◄ │ └ DISPLACEMENT
page-count
pages ┘ │ └ BASED ON ─┬──────────┬─ KEY LENGTH
key-length
┌───────────────────────┬┘ ├ SORTED ◄─┤ └ FOR
index-cnt
RECORDS─┘ └ UNSORTED ┘
file_specification
►►─┬───────────────┬─┬─ FILE
file-name
──────────────────┬────────────────────► ├─┬─ ADD ◄────┬─┤ └─ PATH FILE
native-vsam-file-name
─┘ │ ├─ WITHIN ──┤ │ │ └─ INClude ─┘ │ └─┬─ REMOVE ──┬─┘ ├─ DROP ────┤ └─ EXClude ─┘ ►─┬───────────────────────────────────────────────────────┬──────────────────►◄ └─ FROM
start-block
─┬─ THRU
end-block
───────────────┬─┘ └─ FOR ─┬─ ALL blocks ─────────┬─┘ └─
block-count
blocks ─┘
DISPLAY/PUNCH AREA
►►─┬─ DISplay ─┬─ AREA ─┬─────────────────┬─
area-name
───────────────────────► └─ PUNch ───┘ └─
segment-name
. ─┘ ┌───────────────────────────────────────┐ ►─▼─┬───────────────────────────────────┬─┴──────────────────────────────────► │ ┌────────────────┐ │ ├─ WITh ──────┬─▼─┬─ FILes ────┬─┴──┘ └─ WITHOut ───┘ ├─ SYMbols ──┤ ├─ DETails ──┤ ├─ HIStory ──┤ ├─ ALL ◄─────┤ └─ NONe ─────┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ VERb ─┬─ DISplay ───┬─┘ ├─ PUNch ─────┤ ├─ CREate ◄───┤ ├─ ALTer ─────┤ └─ DROp ──────┘ ►─┬───────────────────────┬──────────────────────────────────────────────────►◄ └─ AS ─┬─ COMments ◄──┬─┘ └─ SYNtax ─────┘
Parameters
CREATE/ALTER AREA
  • segment-name
    Specifies the segment associated with the area.
    Segment-name
    must identify a segment defined in the dictionary.
    If you do not specify a segment name when you issue an AREA statement, you must first establish a current segment as described in “Entity Currency" at "DDL Statement Naming Conventions."
  • area-name
    Specifies the name of the area.
    Area-name
    must be a 1- through 18-character name that follows the conventions described in "DDL Statement Naming Conventions."
    Area-name
    must be unique within the segment associated with the area.
    If the area is associated with an SQL segment in an application dictionary, you must drop any tables or indexes associated with the area before you attempt to delete the area by issuing a DROP AREA statement.
    If the area is associated with a non-SQL segment, the name of the area must be the same as the area defined in the non-SQL schema.
  • initial-page-range-specification
    Specifies the initial page range assigned to the area. This clause is required on a CREATE statement.
    Native VSAM:
    For special considerations that apply to the page ranges of native VSAM data sets, see "Usage" below.
    Expansion of
    initial-page-range-specification
    • PRIMARY SPACE
      primary-page-count
      Specifies the initial number of pages to be included in the area.
      Primary-page-count
      must be an integer in the range 2 through the maximum number of pages determined by the MAXIMUM RECORDS clause of the SEGMENT statement. The upper limit is 1,073,741,821.
      This parameter establishes the default CALC page range of the area and should not be specified with new values on an ALTER AREA request unless the area is empty or is to be reloaded using the RELOAD or REORG utilities.
    • FROM page
      start-page
      Specifies the page number of the first page in the area.
      Start-page
      must be an integer in the range 1 through the maximum number of pages determined by the MAXIMUM RECORDS clause of the SEGMENT statement. The upper limit is 1,073,741,821.
    • MAXIMUM SPACE
      max-page-count
      pages
      Specifies the largest number of pages that can be included in the area.
      Max-page-count
      must be:
      • An integer in the range 2 through the maximum number of pages determined by the MAXIMUM RECORDS clause of the SEGMENT statement; the upper limit is 1,073,741,821.
      • Greater than or equal to the primary page count for the area
      The default maximum number of pages is the area's primary page count.
      Native VSAM:
      If specified, MAXIMUM SPACE must equal the primary page count.
  • EXTEND SPACE
    extend-page-count
    On an ALTER AREA statement, specifies a number of pages to be added to the area. The new pages are numbered starting after the last page currently in the area.
    Extend-page-count
    must be an integer in the range 1 through the maximum number of pages determined by the MAXIMUM RECORDS clause of the SEGMENT statement. The upper limit is 1,073,741,818. The number of new pages plus the number of existing pages cannot exceed the maximum number of pages allowed for the area.
    When you add pages to an area, you must also associate the added pages with either:
    • One or more additional files
    • File blocks beginning at the end of the last file with which the area is associated
    Added pages are automatically associated with file blocks, by specifying the 'WITHIN FILE'-clause without the 'FROM'-clause for the <file-name> (if only 1 file is associated with the area) or for the last <file-name> (if more than 1 file is associated with the area). All other changes in the assignment of file blocks require first an EXCLUDE of the <file-name(s)>, followed by a new 'WITHIN FILE <file-name> FROM'-clause.
    When specifying an EXTEND SPACE parameter, do not specify a PRIMARY SPACE parameter which alters the original page range of the area.
    Native VSAM:
    Do not specify the EXTEND SPACE clause.
    For special considerations that apply to EXTEND SPACE see Usage, below.
    This parameter is not valid on the CREATE AREA statement.
  • PAGE SIZE
    character-count
    Specifies the number of characters in each page of the area. This clause is required on a CREATE statement.
    Character-count
    must be a multiple of 4 in the range 48 through 32,764 and must be at least 40 bytes larger than the largest fixed-length record or uncompressed row in the area. Some operating systems may not support a page size of 32764 characters. Check your operating system limitations.
    Native VSAM:
    Do not specify the PAGE SIZE clause.
  • PAGE RESERVE SIZE
    reserve-character-count
    Specifies the number of characters to be reserved on each page to accommodate increases in the length of records or rows stored on the page. Reserved space will be used for:
    • SR8 index records, which vary in length at the bottom level of the index. The length of a bottom-level SR8 record can change due to any operation that updates an indexed record. Reserved space is not available for new SR8 records.
    • Variable-length records that expand during DML MODIFY operations.
    • Compressed rows or records whose physical length increases due to a change in the data values.
    Reserve-character-count
    must be either 0 or:
    • A multiple of 4 in the range 48 through 32,716
    • Less than or equal to the size of a page in the area minus 48
    The default is 0.
    Native VSAM:
    Do not specify this clause.
  • ORIGINAL PAGE SIZE
    original-character-count
    Specifies the page size of the area when it was last formatted. This clause must be specified the first time the page size of an area is increased using the EXPAND PAGE utility statement, and should not be specified again unless you reformat the area using the new specification.
    Original-character-count
    must be a multiple of 4 in the range 48 through 32764 and cannot be greater than the value specified for the PAGE SIZE clause. The default on a CREATE AREA statement is the value specified for the PAGE SIZE clause.
    Native VSAM:
    Do not specify this clause.
  • STAMP BY TABLE
    On a CREATE AREA statement, directs CA IDMS/DB to update the synchronization stamp for an individual table in the area when the definition of the table or any associated CALC key, index, or referential constraint is modified. This clause is valid only for areas that are associated with an SQL segment.
    STAMP BY TABLE overrides the synchronization stamp specification defined for the segment with which the area is associated.
    This parameter is not valid on the ALTER AREA statement.
  • STAMP BY AREA
    On a CREATE AREA statement, directs CA IDMS/DB to maintain a synchronization stamp for the area as a whole in addition to the synchronization stamps for individual tables. CA IDMS/DB updates the stamps for both the individual table and the whole area when the definition of any table in the area or any associated CALC key, index, or referential constraint is modified. Maintaining stamps at the area level allows validation of access modules by area rather than by individual table. However, a change to a table within the area requires that an access module that references any table within the area be recompiled.
    STAMP BY AREA overrides the synchronization stamp specification defined for the segment with which the area is associated.
    This clause is valid only for areas that are associated with an SQL segment.
    This parameter is not valid on the ALTER AREA statement.
  • TIMESTAMP
    timestamp-value
    Specifies the value of the synchronization stamp to be assigned to the area.
    Timestamp-value
    must be a valid external representation of a timestamp. This clause is valid only for areas associated with an SQL segment and for which area-level stamping is in effect.
  • symbol-specification
    :pd
    Expansion of
    symbol-specification
    • ADD
      For areas associated with non-SQL segments, specifies a value for a symbolic parameter defined in a non-SQL schema definition. ADD is the default. INClude is a synonym.
      If the symbolic parameter is already defined to the area, CA IDMS/DB
      updates
      its value.
    • DROP
      For areas associated with non-SQL segments, removes the symbolic parameter.
      To drop a symbolic parameter, specify only the name of the symbol to be dropped. Optional clauses, such as
      subarea-specification
      , are not allowed. EXClude is a synonym.
    • SUBAREA
      symbolic-subarea-name
      Names a symbolic parameter that represents a subdivision of the area's page range.
      Symbolic-subarea-name
      is a 1- to 18-character name that follows the conventions described in DDL Statement Naming Conventions.
      Symbolic-subarea-name
      must be unique within the subareas defined for the area.
    • subarea-specification
      Specifies an actual page range for the subarea or a relative page range for the subarea based upon the total number of pages defined for the area. If you do not specify an actual or relative page range for the subarea, the default is the page range of the area expressed as this offset specification:
      offset 0 pages for 100 percent
      Expansion of
      subarea-specification
      • FROM page
        start-page
        Specifies the starting page for the subarea.
        Start-page
        must be an integer in the range 1 through the high page number of the area.
        • THRU page
          end-page
          Specifies the last page for the subarea.
          End-page
          must be an integer:
          • Within the page range defined for the area
          • Greater than the value specified for
            start-page
      • SPACE
        subarea-page-count
        pages
        Specifies the number of pages to be included in the subarea.
        Subarea-page-count
        is an integer in the range 1 through the number of pages in the area.
        • FROM page
          subarea-start-page
          Specifies the first page of the subarea.
          Subarea-start-page
          must be an integer in the range 1 through the high page number of the area.
      • OFFSET
        Specifies a relative page range for the subarea, in terms of either a percentage of the area or a displacement relative to the first page of the area. The assigned relative page range must fall within the page range for the area.
      • offset-page-count
        PAGEs
        Determines the first page of the subarea within the area. CA IDMS/DB uses the calculation below to determine the relative page number:
        first subarea page = (LPN + offset-page-count) where LPN = the lowest page number in the area
        Offset-page-count
        must be an integer in the range 0 through the number of pages in the area minus 1.
      • offset-percent
        PERcent
        Determines the first page of the subarea within the area based on the lowest page number of the area and the total number of pages in the area:
        first subarea page = (LPN + (PPC * offset-percent * .01)) where LPN = the lowest page number in the area and PPC = the primary page count
        Offset-percent
        must be an integer in the range 0 through 100.
        • FOR
          page-count
          PAGEs
          Determines the last page of the subarea within the area based on the first page of the subarea:
          last subarea page = (FSP + page-count - 1) where FSP = the first subarea page (determined by calculations above)
          The calculated page must not exceed the highest page number in the area.
        • FOR
          percent
          PERcent
          Determines the last page of the subarea within the area based on the first page of the subarea and the total number of pages in the area:
          last subarea page = (FSP + (TNP * percent * .01) - 1) where FSP = the first page in the subarea (determined by calculations above) and TNP = the total number of pages in the area
          Percent
          must be an integer in the range 1 through 100. The default is 100. If
          percent
          causes the calculated last page of the subarea to be greater than the highest page number in the area, the compiler ignores the excessive page numbers, and CA IDMS/DB will store the record occurrences up to and including the last page in the area.
    • SYMBOLIC DISPLACEMENT
      symbolic-displacement-name
      Names a symbolic parameter that represents the displacement of member records that participate in a VIA set from the owner record of the set.
      Symbolic-displacement-name
      is a 1- to 18-character name that follows the conventions described in DDL Statement Naming Conventions.
      Symbolic-displacement-name
      must be unique within the symbolic displacement names defined to the area.
    • page-cnt-pages
      Specifies how many pages separate the member record of a VIA set from the owner record.
      Page-cnt-pages
      is an integer in the range 0- through 32767.
    • SYMBOLIC INDEX
      symbolic-index-name
      Names a symbolic parameter that represents index characteristics.
      Symbolic-index-name
      is a 1- to 18-character name that follows the conventions described in DDL Statement Naming Conventions.
      Symbolic-index-name
      must be unique within the symbolic index names defined to the area.
    • index-specification
      Specifies either:
      • The values that represent the number of entries in an SR8 record and the displacement of bottom-level SR8 records from the remainder of the index.
      • The values that are used to calculate the number of SR8 entries and the displacement.
      Expansion of
      index-specification
      • BLOCK CONTAINS
        key-count
        keys
        Specifies the maximum number of entries in each internal index record (SR8 system record).
        Key-count
        must be an integer in the range 3 through 8180.
        DISPLACEMENT
        page-count
        pages
        Indicates the number of pages bottom-level SR8 records are displaced from the top of the index.
        Page-count
        must be either 0 or an integer in the range 3 through 32,767. The default is 0, which means bottom-level index records are not displaced.
        BASED ON KEY LENGTH
        key-length
        Calculates the size of the index block and displacement based upon the length of the key fields and the number of entries in the index. Specify
        key-length
        as:
        • 0, for unsorted indexes
        • 0, for indexes sorted by db-key
        • An integer in the range 1 through 256 for other indexes
        SORTED
        Indicates that the index keys are sorted.
        UNSORTED
        Indicates that the index keys are not sorted.
        FOR
        index-cnt
        RECORDS
        Specifies an estimated number of record occurrences to be indexed.
        Index-cnt
        is an integer in the range 0 through 2,147,483,647. The default is 1000. For more information, see Usage, below.
  • file-specification
    Specifies the file(s) to which pages in the area map. An area can map to one or more files.
    Expansion of
    file-specification
    • ADD FILE
      file-name
      Associates the area with the named database file or native VSAM file that has an access method of KSDS, ESDS or RRDS. WITHIN and INClude are synonyms.
      File-name
      must identify a file that:
      • Is associated with the same segment as the area
      • Is not defined with PATH as an access method
      Native VSAM
      : Native VSAM files with access method KSDS, ESDS, or RRDS must map to one and only one area. Likewise, the area must map to one and only one native VSAM file and PATH file.
      You can associate an area with 1 through 32,767 files. Pages in the area are mapped consecutively to blocks in the first file named, then to blocks in the second file named, and so on. If any files are associated with the area, you must identify enough file blocks to accommodate all the pages in the area.
    • DROP FILE
      file-name
      Dissociates the area from the named file. REMOVE and EXClude are synonyms.
      File-name
      must identify a database file previously associated with the area.
      If you dissociate a file from an area, you must identify enough additional file blocks in the same ALTER AREA statement to accommodate the pages that no longer map to the file, unless all files are dissociated from the area.
    • PATH FILE
      native-vsam-file-name
      Identifies a native-VSAM PATH file for the area.
      Native-vsam-file-name
      is a 1- to 18-character name of a PATH file defined to the segment. The following restrictions apply:
      • The access method defined for
        native-vsam-file-name
        on a CREATE/ALTER FILE statement must be PATH.
      • The file cannot map to any other areas
      • The area must map to a file whose access method is KSDS or ESDS
    • FROM
      start-block
      Specifies the number of the first block in the named file to be associated with the area.
      Start-block
      must be an integer in the range 1 through 2,147,483,646. The default depends on the verb:
      • For CREATE AREA, the default is 1
      • For ALTER AREA with
        out
        the EXTEND SPACE clause, the default is 1
      • For ALTER AREA with the EXTEND SPACE clause, the default is the current high block number of the file plus 1
    • THRU
      end-block
      Specifies the number of the last block in the named file to be associated with the area.
      End-block
      must be an integer in the range 2 through 2,147,483,647.
    • FOR ALL
      Specifies that blocks in the named file are to be associated with the area for the entire page range of the area, or, if specified for an ALTER AREA with an EXTEND SPACE clause, for the number of pages in the extended space.
    • FOR
      block-count
      blocks
      Specifies the number of blocks in the named file to be associated with the area.
      Block-count
      must be an integer in the range 2 through 2,147,483,647.
DROP AREA
  • segment-name
    Specifies the segment associated with the area.
  • area-name
    Specifies the name of the area.
DISPLAY/PUNCH AREA
  • FILes
    Displays or punches information on all files to which the area is mapped.
  • SYMbols
    Displays or punches information on all symbols defined to the area.
  • DETails
    Displays or punches details about the area.
  • HIStory
    Displays or punches:
    • The user who defined the area
    • The user who last updated the area
    • The date the area was created
    • The date the area was last updated
  • ALL
    Displays or punches all information on the area. ALL is the default action for a DISPLAY or PUNCH verb.
  • NONe
    Displays or punches the name of the area.
For more information about DISPLAY/PUNCH, see Generic DISPLAY/PUNCH Statement.
Usage
Unique Page Range
The range of pages reserved for an area is defined by the FROM PAGE parameter in conjunction with the MAXIMUM SPACE parameter (or the PRIMARY SPACE parameter if you do not specify MAXIMUM SPACE). This page range must not overlap the page range for:
  • Any other area contained in the segment
  • Any other area in a DMCL in which the area's segment is included if the page groups are the same
Contiguity of Page Ranges
Page ranges within a segment can be, but do not have to be, contiguous with one another.
Page Range Limits Depend on Maximum Number of Records Per Page
The highest page number for an area depends on the maximum number of records or rows that can fit on a single page. Use the table provided under "Usage" in SEGMENT Statements to determine the highest page number.
Page Ranges for CALC Records
The last page of a subarea that can be used to store CALC record occurrences depends on the type of offset specification:
  • For page offsets, the last page of the CALC range is the last page of the subarea.
  • For percentage offsets, this calculation is used to determine the last page of the CALC range:
    calc-lastpage-of-subarea = firstpage-of-subarea + percent * primary-page-count * .01
Copying an Extended Area Into a New Segment
It may become necessary to copy the definition of an area that was extended into a new segment. If you issue a DISPLAY command for the original area definition, the PRIMARY SPACE parameter for the area is generated with the total number of pages defined to the area due to any previous EXTEND SPACE operations. Information regarding the original number of pages defined to the area is generated as a comment.
When using DISPLAY to add the area to a new segment definition, the area primary space is defined with the total number of pages assigned to the extended area and does not carry forward the extended condition of the area. If this new definition is used against a copy of the original area, the page range for CALC records in the new definition is different than that used in the original area. This causes  NOT FOUND errors when attempting to access CALC records when using their CALC keys.
To properly copy an extended area definition to a new segment, it is necessary to code the PRIMARY SPACE using the area original page range on the creation of the area within the new segment. Following the creation, you must perform an EXTEND SPACE procedure on the new area definition for the total number of pages in the extended portion of the original area.
What Happens to Offsets When You Expand an Area
When you expand an area by using the EXTEND SPACE clause on the ALTER AREA command, the following occurs to the first page, last page, and CALC last page of a subarea:
  • The first page does not change
  • The last page changes if you specified a percentage offset; CA IDMS/DB allows CALC overflow records and records with other location modes to be stored in the expanded space
  • The last page of the CALC range does not change; that is, CALC records continue to target to the original page range assigned to the subarea
You must exercise care when expanding an area containing subarea definitions that use offset percentages because subareas can overlap after the EXTEND SPACE is performed. For example:
Given the following subarea allocations for an area containg 1000 pages, the page ranges are as follows:
Definition LoPage HiPage SUB1 OFFSET 0% FOR 25% 1 250 SUB2 OFFSET 25% FOR 25% 251 500 SUB3 OFFSET 50% FOR 25% 501 750 SUB4 OFFSET 75% FOR 25% 751 1000
If an EXTEND SPACE is executed, and 1000 more pages are added to the area, the allocations are as follows:
Sub Area LoPage HiPage SUB1 1 500 SUB2 251 750 SUB3 501 1000 SUB4 751 1250
You can see that adding 1000 pages to the area did not significantly increase the space available in which to store records, nor did the additional space get used by any areas mapped to defined subarea definitions -- only SUB4 benefits by the additional pages.
Percentage Offsets Most Flexible
Percentage offset specifications are the most flexible in terms of database maintenance. As the database grows and must eventually be expanded, the areas of the database must also be expanded. If you use percentage offsets, CA IDMS/DB automatically assigns record occurrences to the appropriate percentage of the new area.
Page Range for RRDS Native VSAM Areas
CA IDMS/DB constructs the db-key for a record in an RRDS native VSAM area in the following manner:
dbkey = low-dbkey-of-area + relative-record-number
Therefore, for an RRDS file, the number of pages specified by the page range must be calculated as follows (rounded up to the next integer):
number-of-pages = (number-of-vsam-records-in-file + 1) / (maximum-records-per-page + 1)
Maximum-records-per-page is specified on the CREATE SEGMENT statement and determines the format of the database keys for records in areas that are contained in the segment.
Page Range for KSDS Native VSAM Areas
CA IDMS/DB constructs the db-key for a record in a KSDS native VSAM area by randomizing the record's prime key to a database key in the database key range for the area. Therefore, for a KSDS file, a rule-of-thumb for calculating the page range is as follows (rounded up to the next integer):
number-of-pages = number-of-vsam-records-in-file / x where x = 10 if number-of-vsam-records-in-file < 100,000 100 if number-of-vsam-records-in-file > 100,000
The idea is to specify a page range that minimizes the probability of constructing duplicate keys without specifying an excessive number of pages for the area.
Page Range for ESDS Native VSAM Areas
CA IDMS/DB constructs the db-key for a record in an ESDS native VSAM area in the following manner:
dbkey = low-dbkey-of-area + relative-byte-address
Therefore, for an ESDS file, the number of pages specified by the page range must be calculated as follows (rounded up to the next integer):
number-of-pages = total-bytes-in-file / (maximum-records-per-page + 1)
Maximum-records-per-page is specified on the CREATE SEGMENT statement and determines the format of the database keys for records in areas that are contained in the segment.
Physical Device Blocking
A database page is a fixed block. As a general rule, you should use pages that are an even fraction of the track size.
The following table lists the optimal page sizes by device type for five IBM disk drives. Manufacturers of other brands of direct access storage devices (DASD) should be able to provide similar information for their own equipment.
Per track
3330
3340
3350
3375
3380
3390
1
13028
8368
19068
32764
32764
32764
2
6444
4100
9440
17600
23476
27996
3
4252
2676
6232
11616
15476
18452
4
3156
1964
4628
8608
11476
13680
5
2496
1540
3664
6816
9076
10796
6
2056
1252
3020
5600
7476
8904
7
1744
1052
2564
4736
6356
7548
8
1508
896
2220
4096
5492
6516
9
1324
780
1952
3616
4820
5724
10
1180
684
1740
3200
4276
5064
11
1060
608
1564
2880
3860
4564
12
960
544
1416
2592
3476
4136
13
876
488
1296
2368
3188
3768
14
804
440
1180
2176
2932
3440
15
740
400
1096
2016
2676
3172
Notes:
The bytes per page for FBA devices must be a multiple of 512.
On z/VM, the size of a database page must be less than or equal to 4096 bytes.For VSAM database files the character-count must be at least 8 bytes larger than the page size.
Synchronization Stamps
If you expect frequent changes to the definitions of SQL tables, you should maintain synchronization stamps at the table level. If you do not expect frequent changes, you should maintain stamps at the area level.
Specifying a Synchronization Stamp Value
When defining or altering an area for which area-level stamping is in effect, you can specify an explicit value for its synchronization stamp. This allows you to create databases that have identical physical attributes and can therefore be accessed through a single schema definition.
Since an area's synchronization stamp is updated each time any DDL statement affecting the area is issued, the synchronization stamp must be set after issuing the SQL DDL statements that define the database.
Care should be exercised when specifying a specific timestamp, since its purpose is to enable the detection of discrepancies between an entity and its definition. If explicitly specified, the timestamp should always be set to a new value following a definitional change so that the change is detectable to the run time system.
Contiguity of File Blocks
Block ranges within a file associated with more than one area must be contiguous.
To specify that all pages of the area map to all pages of the file, specify:
...from 1 for all
on the file specification.
If the file has multiple areas associated with it, the block range will overlap if both of the areas map to the file having this specification. You can map the first area using "FROM 1 FOR ALL", but you must map the second area "FROM
last-block-of-the-file
+1 FOR ALL".
Device Types or Access Methods May Limit the Number of File Blocks
Device types or access methods may further restrict the number of blocks allowed in a file. For example, a maximum of 65,535 tracks can be addressed in BDAM files.
For more information on device types and access methods, see Allocating and Formatting Files.
Native VSAM File Restrictions
An area that maps to native VSAM files has the following restrictions:
  • A native VSAM file defined with an access method RRDS, KSDS, or ESDS can map to one and only one area
  • An area that maps to a native VSAM file must map to one and only one file
  • If an area is associated with one or more files defined with PATH as an access method, then:
    • The area must map to either an ESDS or KSDS file
    • The PATH file must not be associated with any other area
Index Calculations
The following algorithms are used to calculate BLOCK CONTAINS
key-count
and the DISPLACEMENT
page-count
values for symbolic index parameters when the BASED ON clause is specified.
Index block:
Step 1: Assuming 3 SR8's per page, compute the following: The maximum size of the variable portion of an SR8: ( (Page size - Page reserve - 32) / 3 ) - 40 = SR8-vsize The maximum number of entries in an SR8: Sorted index: (SR8-vsize / ( 8 + Keylen) ) - 2 Unsorted index: (SR8-vsize / 4 ) - 1 If the number of SR8 entries is less than 3, set it to 3; if greater than 8180, set it to 8180. Step 2: Establish the number of index entries: Use the FOR index-cnt value, if specified, or 1000. Step 3: Estimate the number of entries per SR8 for a 3-level index: Find the first entry in the following table whose Number of Entries column is greater than or equal to the value established in Step 2. Number of Number of entries SR8 entries 1,000 10 15,625 25 125,000 50 512,000 80 1,000,000 100 2,000,376 126 3,375,000 150 5,359,375 175 8,000,000 200 15,625,000 250 -1 8180 Step 4: Determine the INDEX BLOCK value: Use the lesser of the Number of SR8 entries from the table and the value from Step 1 as the INDEX BLOCK (IBC) value in the remaining calculations.
Displacement:
For unsorted indexes, the displacement is set to 0; for sorted indexes, it is calculated as follows:
Step 1: Calculate the number of bottom level and higher level SR8s: Set N = #-of-entries High-level-SR8s = 0 Bottom-level-SR8s = 1 Repeat N = (N + IBC - 1) / IBC (truncate) If N = 1, exit If High-level-SR8s = 0, High-level-SR8s = 1 Bottom-level-SR8s = N Else High-level-SR8s = High-level-SR8s + N Set Total-SR8s = High-level-SR8s + Bottom-level-SR8s Step 2: Determine the number of SR8s per page: Calculate size of an SR8: SR8-size = 32 + (IBC + 1) * (keylen + 8) Calculate number of SR8s per page: (Page-size - Page-reserve - 32) / (SR8-size + 8) Step 3: Establish the INDEX DISPLACEMENT: If Number of Higher Level SR8s is less than 2, set the DISPLACEMENT = High-level-SR8s. (For a one or two-level index, displacement will be 0 or 1 respectively.) If Number of Higher Level SR8s is greater than 1, compute the displacement: (High-level-SR8s + SR8s-per-page - 1) ------------------------------------- + 1 (truncate) SR8s-per-page If the calculate displacement is greater than the number of pages in the area containing the index, then: Displacement = Number of pages in area / 2
Examples
Mapping to a Single File
The CREATE AREA statement below defines an area that has only one associated file. All 100 pages in the area will map to the first available 100 blocks in the file.
create area demoseg.emp_space primary space 100 pages page size 4276 within file demoseg.emp_file;
Mapping to Two Files
The CREATE AREA statement below defines an area that maps to two files. The first 500 pages in the area map to the first 500 blocks in the PUB_FILE_1 file. The second 500 pages in the area map to 500 blocks of the PUB_FILE_2 file, starting at block number 1001.
create area salesseg.sales_space primary space 1000 pages from page 85001 maximum space 1500 pages page size 3820 characters page reserve size 800 characters within file pub_file_1 from 1 for 500 within file pub_file_2 from 1 for 500;
Adding Pages to an Area
The ALTER AREA statement below adds 200 pages to the SALES_SPACE area. The new pages are mapped to the PUB_FILE_3 file.
alter area salesseg.sales_space extend space 200 pages within file pub_file_3 from 1 thru 200;
Dropping an Area
The following DROP AREA statement deletes the definition of the SALES_SPACE area from the dictionary. If SALESSEG is defined as an SQL segment, then you must first drop all tables and indexes associated with the area:
drop area salesseg.sales_space;