The AREA statements create, alter, delete, display, or punch the definition of an area in the dictionary.
The AREA statements create, alter, delete, display, or punch the definition of an area in the dictionary.
- 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
►►─┬─ CREATE ─┬─ physical AREA ─┬─────────────────┬─area-name───────────────► └─ ALTER ──┘ └─segment-name. ─┘ ►─┬──────────────────────────────────────────┬───────────────────────────────► ├─initial-page-range-specification───────┤ └─ EXTEND SPACEextend-page-countpages ───┘ ►─┬─────────────────────────────────────────┬────────────────────────────────► └─ PAGE SIZEcharacter-countcharacters ──┘ ►─┬────────────────────────────────────────────────────────────────┬─────────► └─ PAGE RESERVE size ─┬─ 0 ◄──────────────────────┬─ characters ─┘ └─reserve-character-count─┘ ►─┬──────────────────────────────────────────────────────────┬───────────────► └─ ORIGINAL PAGE SIZEoriginal-character-countcharacters ─┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ STAMP BY ─┬─ TABLE ─┬─┘ └─ AREA ──┘ ►─┬──────────────────────────────────┬───────────────────────────────────────► └──── TIMESTAMPtimestamp-value───┘ ►─┬────────────────────────────────┬─────────────────────────────────────────► │ ┌────────────────────────────┐ │ └─▼──symbol-specification────┴─┘ ►─┬─────────────────────────────────┬────────────────────────────────────────►◄ │ ┌─────────────────────────────┐ │ └─▼────file-specification─────┴─┘
►►── DROP physical AREA ─┬─────────────────┬─area-name──────────────────────►◄ └─segment-name. ─┘
►►─── PRIMARY SPACEprimary-page-countpages FROM pagestart-page────────────► ►─┬──────────────────────────────────────┬───────────────────────────────────►◄ └─ MAXIMUM SPACEmax-page-countpages ─┘
►►─┬───────────────┬──────────────────────────────────────────────────────────► ├─┬─ ADD ◄────┬─┤ │ └─ INClude ─┘ │ └─┬─ DROP ────┬─┘ └─ EXClude ─┘ ►─┬─ SUBAREAsymbolic-subarea-name─┬─────────────────────────┬────────────┬─►◄ │ └─subarea-specification─┘ │ ├─ SYMBOLIC DISPLACEMENTsymbolic-displacement-name─┬──────────────────┬┤ │ └─page-cnt pages─┘│ └─ SYMBOLIC INDEXsymbolic-index-name─┬───────────────────────┬─────────┘ └─index-specification─┘
►►─┬─ FROM pagestart-pageTHRU pageend-page───────────────────────────┬────►◄ ├─ SPACEsubarea-page-countpages FROM pagesubarea-start-page───────┤ └─ OFFSET ─┬─ 0 ◄──────────────────────┬─ FOR ─┬─ 100 PERCENT ◄─────┬─┘ ├─offset-page-countPAGEs ─┤ ├─percentPERCENT ──┤ └─offset-percentPERCENT ──┘ └─page-countPAGEs ─┘
►►─┬ BLOCK CONTAINSkey-countkeys ─┬───────────────────────────────┬───────┬─►◄ │ └ DISPLACEMENTpage-countpages ┘ │ └ BASED ON ─┬──────────┬─ KEY LENGTHkey-length┌───────────────────────┬┘ ├ SORTED ◄─┤ └ FORindex-cntRECORDS─┘ └ UNSORTED ┘
►►─┬───────────────┬─┬─ FILEfile-name──────────────────┬────────────────────► ├─┬─ ADD ◄────┬─┤ └─ PATH FILEnative-vsam-file-name─┘ │ ├─ WITHIN ──┤ │ │ └─ INClude ─┘ │ └─┬─ REMOVE ──┬─┘ ├─ DROP ────┤ └─ EXClude ─┘ ►─┬───────────────────────────────────────────────────────┬──────────────────►◄ └─ FROMstart-block─┬─ THRUend-block───────────────┬─┘ └─ FOR ─┬─ ALL blocks ─────────┬─┘ └─block-countblocks ─┘
►►─┬─ DISplay ─┬─ AREA ─┬─────────────────┬─area-name───────────────────────► └─ PUNch ───┘ └─segment-name. ─┘ ┌───────────────────────────────────────┐ ►─▼─┬───────────────────────────────────┬─┴──────────────────────────────────► │ ┌────────────────┐ │ ├─ WITh ──────┬─▼─┬─ FILes ────┬─┴──┘ └─ WITHOut ───┘ ├─ SYMbols ──┤ ├─ DETails ──┤ ├─ HIStory ──┤ ├─ ALL ◄─────┤ └─ NONe ─────┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ VERb ─┬─ DISplay ───┬─┘ ├─ PUNch ─────┤ ├─ CREate ◄───┤ ├─ ALTer ─────┤ └─ DROp ──────┘ ►─┬───────────────────────┬──────────────────────────────────────────────────►◄ └─ AS ─┬─ COMments ◄──┬─┘ └─ SYNtax ─────┘
- segment-nameSpecifies the segment associated with the area.Segment-namemust 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-nameSpecifies the name of the area.Area-namemust be a 1- through 18-character name that follows the conventions described in "DDL Statement Naming Conventions."Area-namemust 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-specificationSpecifies 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 ofinitial-page-range-specification
- PRIMARY SPACEprimary-page-countSpecifies the initial number of pages to be included in the area.Primary-page-countmust 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 pagestart-pageSpecifies the page number of the first page in the area.Start-pagemust 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 SPACEmax-page-countpagesSpecifies the largest number of pages that can be included in the area.Max-page-countmust be:
Native VSAM:If specified, MAXIMUM SPACE must equal the primary page count.
- 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
- EXTEND SPACEextend-page-countOn 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-countmust 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:
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.This parameter is not valid on the CREATE AREA statement.
- One or more additional files
- File blocks beginning at the end of the last file with which the area is associated
- PAGE SIZEcharacter-countSpecifies the number of characters in each page of the area. This clause is required on a CREATE statement.Character-countmust 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 SIZEreserve-character-countSpecifies 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:
Reserve-character-countmust be either 0 or:
- 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.
Native VSAM:Do not specify this clause.
- 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
- ORIGINAL PAGE SIZEoriginal-character-countSpecifies 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-countmust 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 TABLEOn 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 AREAOn 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.
- TIMESTAMPtimestamp-valueSpecifies the value of the synchronization stamp to be assigned to the area.Timestamp-valuemust 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:pdExpansion ofsymbol-specification
- ADDFor 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/DBupdatesits value.
- DROPFor 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 assubarea-specification, are not allowed. EXClude is a synonym.
- SUBAREAsymbolic-subarea-nameNames a symbolic parameter that represents a subdivision of the area's page range.Symbolic-subarea-nameis a 1- to 18-character name that follows the conventions described in DDL Statement Naming Conventions.Symbolic-subarea-namemust be unique within the subareas defined for the area.
- subarea-specificationSpecifies 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 percentExpansion ofsubarea-specification
- FROM pagestart-pageSpecifies the starting page for the subarea.Start-pagemust be an integer in the range 1 through the high page number of the area.
- THRU pageend-pageSpecifies the last page for the subarea.End-pagemust be an integer:
- Within the page range defined for the area
- Greater than the value specified forstart-page
- SPACEsubarea-page-countpagesSpecifies the number of pages to be included in the subarea.Subarea-page-countis an integer in the range 1 through the number of pages in the area.
- FROM pagesubarea-start-pageSpecifies the first page of the subarea.Subarea-start-pagemust be an integer in the range 1 through the high page number of the area.
- OFFSETSpecifies 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-countPAGEsDetermines 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 areaOffset-page-countmust be an integer in the range 0 through the number of pages in the area minus 1.
- offset-percentPERcentDetermines 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 countOffset-percentmust be an integer in the range 0 through 100.
- FORpage-countPAGEsDetermines 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.
- FORpercentPERcentDetermines 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 areaPercentmust be an integer in the range 1 through 100. The default is 100. Ifpercentcauses 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 DISPLACEMENTsymbolic-displacement-nameNames 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-nameis a 1- to 18-character name that follows the conventions described in DDL Statement Naming Conventions.Symbolic-displacement-namemust be unique within the symbolic displacement names defined to the area.
- page-cnt-pagesSpecifies how many pages separate the member record of a VIA set from the owner record.Page-cnt-pagesis an integer in the range 0- through 32767.
- SYMBOLIC INDEXsymbolic-index-nameNames a symbolic parameter that represents index characteristics.Symbolic-index-nameis a 1- to 18-character name that follows the conventions described in DDL Statement Naming Conventions.Symbolic-index-namemust be unique within the symbolic index names defined to the area.
- index-specificationSpecifies 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.
- BLOCK CONTAINSkey-countkeysSpecifies the maximum number of entries in each internal index record (SR8 system record).Key-countmust be an integer in the range 3 through 8180.DISPLACEMENTpage-countpagesIndicates the number of pages bottom-level SR8 records are displaced from the top of the index.Page-countmust 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 LENGTHkey-lengthCalculates the size of the index block and displacement based upon the length of the key fields and the number of entries in the index. Specifykey-lengthas:
SORTEDIndicates that the index keys are sorted.UNSORTEDIndicates that the index keys are not sorted.FORindex-cntRECORDSSpecifies an estimated number of record occurrences to be indexed.Index-cntis an integer in the range 0 through 2,147,483,647. The default is 1000. For more information, see Usage, below.
- 0, for unsorted indexes
- 0, for indexes sorted by db-key
- An integer in the range 1 through 256 for other indexes
- file-specificationSpecifies the file(s) to which pages in the area map. An area can map to one or more files.Expansion offile-specification
- ADD FILEfile-nameAssociates 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-namemust identify a file that:
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.
- Is associated with the same segment as the area
- Is not defined with PATH as an access method
- DROP FILEfile-nameDissociates the area from the named file. REMOVE and EXClude are synonyms.File-namemust 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 FILEnative-vsam-file-nameIdentifies a native-VSAM PATH file for the area.Native-vsam-file-nameis a 1- to 18-character name of a PATH file defined to the segment. The following restrictions apply:
- The access method defined fornative-vsam-file-nameon 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
- FROMstart-blockSpecifies the number of the first block in the named file to be associated with the area.Start-blockmust 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 withoutthe 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
- THRUend-blockSpecifies the number of the last block in the named file to be associated with the area.End-blockmust be an integer in the range 2 through 2,147,483,647.
- FOR ALLSpecifies 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.
- FORblock-countblocksSpecifies the number of blocks in the named file to be associated with the area.Block-countmust be an integer in the range 2 through 2,147,483,647.
- segment-nameSpecifies the segment associated with the area.
- area-nameSpecifies the name of the area.
- FILesDisplays or punches information on all files to which the area is mapped.
- SYMbolsDisplays or punches information on all symbols defined to the area.
- DETailsDisplays or punches details about the area.
- HIStoryDisplays 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
- ALLDisplays or punches all information on the area. ALL is the default action for a DISPLAY or PUNCH verb.
- NONeDisplays or punches the name of the area.
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.
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.
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
The following algorithms are used to calculate BLOCK CONTAINS
key-countand the DISPLACEMENT
page-countvalues for symbolic index parameters when the BASED ON clause is specified.
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.
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
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;