CONVERT PAGE

The CONVERT PAGE utility changes the page range for an area or changes the maximum number of records that can be stored on a page of an area.
idmscu19
The CONVERT PAGE utility changes the page range for an area or changes the maximum number of records that can be stored on a page of an area.
This article describes the following information:
2
2
Authorization
To
You Need This Privilege
On
Change the page range for an area or the maximum number of records that can be stored on a page of an area
DBAWRITE
All areas being converted
Syntax
  ►►─ CONVERT PAGE IN ─┬─ SEGMENT source-segment ─┬─────────────────────┬─┬────►                      │                          └─ TO target-segment ─┘ │                      └─ area-specification ─────────────────────────────┘  ►─┬────────────────────┬────────────────────────────────────────────────────►    └─ DMCL target-dmcl ─┘  ►─┬──────────────────────────────────────────────────────────────────┬──────►    │        ┌────────────────────────── , ──────────────────────────┐ │    └─ FILE ─▼─┬──────────────────┬─ filename ─┬───────────────────┬─┴─┘               └─ source-segment. ┘            └─ INTO new-ddname ─┘  ►─┬────────────────────────────────────┬────────────────────────────────────►◄    └─ NOTIFY INTERVAL ─┬─ not-interval ─┤                        └─ 10000 ◄───────┘  
Expansion of
 
area-specification
          ┌─────────────────────── , ─────────────────────┬──────────────────►◄ ►►─ AREA ─▼─ source-seg.area ─┬───────────────────────────┤                               └─ TO target-seg ─┬─────────┤                                                 └─ .area ─┘  
Parameters
  • source-segment
    Names a segment to be processed. All areas in this segment are compared to matching areas in the target segment for page range and maximum records per page changes. Unless restricted by the FILE parameter, all files in this segment are scanned for page range changes and copied to new files.
  • source-seg.area
    Names an area to be processed. All specified areas are compared to the corresponding target areas and checked for page range and maximum records per page changes. Unless restricted by the FILE parameter, all files for this area are scanned for page range changes and copied to new files.
  • target-segment
    Names the segment with the new page range and maximum records per page definitions. If you omit target-segment, it defaults to the source segment name. You should use this when the target segment is in the same DMCL as the source.
  • target-seg.area
    Names the area that contains the new page range and maximum records per page definitions. If you omit this, it defaults to source-seg.area name. If you omit the area, it defaults to the source area name. You should use this when the target area is in the same DMCL as the source.
  • target-dmcl
    Names the DMCL that contains the target segment or area definitions. Use this parameter when the target segment or area is defined in a different DMCL than the current one.
  • filename
    Restricts the conversion to the selected source files. If you do not specify the FILE parameter, then all files for selected segments and areas are converted. However, all target file definitions must have ddnames that are different from the source file definitions.
  • new-ddname
    Names the JCL ddname used for the output file. This name must be unique in the job step. If you don't specify new-ddname, the ddname in the target file definition is used. In this case the name of the target file must match the source file.
  • not-interval
    Specifies the notify interval. After every not-interval record read, a message is issued to the console stating how far the job has progressed. If omitted, the default interval is 10,000 records. If specified as zero (0), no notify message is issued.
Usage
You can process an entire segment or one or more individual areas using this utility. The utility first identifies the changes that need to be made by comparing old and new definitions for the segment or areas. Once all changes have been identified, it converts one or more files. It is possible to run the utility in parallel to process several files concurrently.
This utility allows you to reassign the page range of an area so that you can consolidate free pages. It also allows you to change the maximum number of records on a page permitting more effective use of the space on a page and more flexibility in choosing page sizes.
To use the feature, you must define one or more new segments and include them in a DMCL, or alter the definition of an existing segment and include it in a new DMCL. The utility requires both the old and new definitions of the affected segment or areas to be available at runtime.
Once the definitions are available, you can execute the utility. There must be enough disk space available to hold all converted files. The converted files can also be written to tape and then copied back to the original database files. Be sure to back up the original database beforehand.
Once all files have been converted, you must make the new segment or area definitions effective.
Page range and radix changes
Page range and radix changes are determined by comparing all source and target area definitions. Regardless of which files are selected for conversion, all differences are applied to all files selected for conversion.
File conversion
File conversion is performed against all files in the specified segment or areas, unless the FILE parameter is specified, in which case only specified files are converted.
File conversion consists of copying a page from the source file to the target file while making any required changes. Page number changes are accomplished by subtracting the old low page and adding the new low page. Maximum records per page changes are effected by breaking up a dbkey into a line and page number using the old information and reassembling it using the new information.
If no changes apply to a selected file it is copied anyway.
The CONVERT PAGE utility also has the following usage considerations:
  • If an area that is being converted has a cross-area set or linked constraint, then you must convert all areas touched by the set or link. You must determine what files are affected, and therefore what files must be converted.
  • If you need to convert multiple files, the files do not all have to be converted in the same job.
  • As long as all changes are identified to each job, you can convert each affected file separately. It may be desirable to run several jobs in parallel to reduce the time required to convert an area.
    It is important that you identify all page range changes that affect a file before the file is converted. Depending on the nature of the page range change, it may not be possible to apply a partial change to a previously converted file.
  • If you omit a change identification, then you will need to reapply all changes to the original file, not the converted file.
  • You cannot change the number of pages assigned to an area, nor lower the maximum number of records per page to less than the actual number of records stored on any page of an area.
  • This utility must run in local mode and with update activity quiesced on the affected areas.
  • The source and target files must match in page size and number of blocks. (The source file is copied block for block.) If the target file does not match then the converted file will not be usable by the new file definition.
JCL Considerations
All input and output ddnames must be unique within the same job step. If the target DMCL files do not have unique ddnames, use the INTO option for each output file.
JCL must include DD statements for the output files. If a file is not defined to use dynamic file allocation, then DD statements for the input files are also required.
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
The EMPDEMO database has three areas: the Emp-demo-region, Org-demo-region, and the Ins-demo-region. There are cross-area sets between the Emp and Org-demo-regions, and between the Emp and Ins-demo-regions, but there are no sets between the Ins-demo-region and the Org-demo-region; therefore, if you need to change the:
  • Page range for the Org-demo-region, you must convert both the Emp-demo-region and the Org-demo-region.
  • Page range for the Ins-demo-region, you must convert both the Emp-demo-region and the Ins-demo-region.
  • Page range for the Emp-demo-region, you need to convert all three areas.
Example 1
The first step in converting an area's page range is to define the new segment with all changes. This new segment could be included in the current DMCL if its name is different from the old segment, if the page group and page ranges are different from the old ones, and if the ddnames are different from the old ones.
After the DMCL is updated, the required syntax to do all conversions would be:
CONVERT PAGE IN SEGMENT EMPDEMO TO NEWDEMO;
The CONVERT PAGE utility scans both segments and determines which areas are being changed. Because the output files have unique ddnames, they do not need to be identified, but all three files that are in the EMPDEMO segment are converted, even if the changes do not affect all files.
To restrict the process, you could code the following:
CONVERT PAGE IN SEGMENT EMPDEMO TO NEWDEMO    FILE EMPDEMO-FILE, ORGDEMO-FILE;
This syntax would only convert the EMPDEMO and ORGDEMO files. If the INSDEMO file were not affected by any changes, then this would be all that would be needed. However, if the INSDEMO file were affected, it could be converted with a separate job as follows:
CONVERT PAGE IN SEGMENT EMPDEMO TO NEWDEMO    FILE INSDEMO-FILE;
This works because all changes were identified to both jobs, because all changes are contained in the single segment.
When completed, the DMCL would have to be modified a second time to remove the old segment definition and to possibly rename the new segment to the old one, to possibly change the new page group to the old page group, and to possibly change the ddnames back to the old ones.
Example 2
Another approach is to define a new DMCL with all changes made to the existing segment.
In this case you would not have to modify the DMCL a second time, but more syntax is required for the conversion process, as follows:
CONVERT PAGE IN SEGMENT EMPDEMO TO EMPDEMO DMCL NEWDMCL    FILE EMPDEMO-FILE INTO EMPDDX,            INSDEMO-FILE INTO INSDDX,            ORGDEMO-FILE INTO EMPDDX;
This syntax requires that you give each output file a unique ddname for the run only, because the defined ddnames in the target DMCL are the same as the source DMCL. However, once converted, the old DMCL is discarded, and the new one is renamed and the old one is replaced.
Again, if all three files are not affected, the number of files converted can be reduced by not naming the unaffected files.
Example 3
If area syntax were being used, the syntax could be as follows:
CONVERT PAGE IN AREA          EMPDEMO.EMP-DEMO-REGION TO NEWDEMO,          EMPDEMO.INS-DEMO-REGION TO NEWDEMO,          EMPDEMO.ORG-DEMO-REGION TO NEWDEMO;
Or if the areas were in a different DMCL:
CONVERT PAGE IN AREA EMPDEMO.EMP-DEMO-REGION,                    EMPDEMO.INS-DEMO-REGION,                    EMPDEMO.ORG-DEMO-REGION                    DMCL NEWDMCL                    FILE EMPDEMO-FILE INTO EMPDDX,                         INSDEMO-FILE INTO INSDDX,                         ORGDEMO-FILE INTO EMPDDX;
This syntax works because all areas affected by the changes are identified. Again, this converts all files even if some are not affected.
Example 4
To only convert affected files, specify only the files that should be converted:
CONVERT PAGE IN AREA EMPDEMO.EMP-DEMO-REGION TO NEWDEMO,                    EMPDEMO.INS-DEMO-REGION   TO NEWDEMO,                    EMPDEMO.ORG-DEMO-REGION   TO NEWDEMO                    FILE EMPDEMO-FILE, INSDEMO-FILE;
Or if the areas were in a different DMCL:
CONVERT PAGE IN AREA EMPDEMO.EMP-DEMO-REGION,                    EMPDEMO.INS-DEMO-REGION,                    EMPDEMO.ORG-DEMO-REGION                    DMCL NEWDMCL                    FILE EMPDEMO-FILE INTO EMPDDX,                         INSDEMO-FILE INTO INSDDX;
This syntax would only cause the Emp-demo-region and the Ins-demo-region to be converted.
If you decided that the Org-demo-region also needed to be converted, you could run the following:
CONVERT PAGE IN AREA EMPDEMO.EMP-DEMO-REGION,                    EMPDEMO.INS-DEMO-REGION,                    EMPDEMO.ORG-DEMO-REGION                    DMCL NEWDMCL                    FILE ORGDEMO-FILE INTO ORGDDX;
This syntax works because all three areas were identified to compare phase. Even though the files were converted in separate jobs, all jobs knew about all changes.
Bad Example 4
The wrong way to do the previous example would be to reduce the areas considered for change, instead of the files to be converted:
CONVERT PAGE IN AREA EMPDEMO.EMP-DEMO-REGION,                    EMPDEMO.INS-DEMO-REGION,                    DMCL NEWDMCL                    FILE EMPDEMO-FILE INTO EMPDDX,                         INSDEMO-FILE INTO INSDDX;
This syntax works only if the Org-demo-region is unaffected by any changes. Only the Emp-demo-region and the Ins-demo-region are converted. But if it were later discovered that the Org-demo-region required conversion, you would have to reconvert the Emp-demo-region.
CONVERT PAGE IN AREA EMPDEMO.EMP-DEMO-REGION,                    EMPDEMO.INS-DEMO-REGION,                    EMPDEMO.ORG-DEMO-REGION                    DMCL NEWDMCL                    FILE EMPDEMO-FILE INTO EMPDDX,                         ORGDEMO-FILE INTO ORGDDX;
Ins-demo-region did not have to be reconverted because it was unaffected by changes to the Org-demo-region, but because the Emp-demo-region is affected by changes to the Ins-demo-region; Ins-demo-region is included in the list of changed areas.
Sample Output
IDMSBCF  nn.n    CA IDMS Batch Command Facility   mm/dd/yy   PAGE    1 CONVERT PAGE       AREA EMPDEMO.EMP-DEMO-REGION TO EMPXDEMO,            EMPDEMO.ORG-DEMO-REGION TO ORGXDEMO,            EMPDEMO.INS-DEMO-REGION TO INSXDEMO       DMCL EMPXDMCL       NOTIFY 10   ; UT018000 Convert Page Utility Starting: UT018001 Source DMCL:    LRDTDMCL  Target DMCL:    EMPXDMCL UT018003 Comparing source area: EMPDEMO.EMP-DEMO-REGION UT018004      with target area: EMPXDEMO.EMP-DEMO-REGION UT018012    Area added to change table. UT018013     SOURCE AREA Range: 75,001 to 75,100  Radix: 8 UT018013     TARGET AREA Range: 75,001 to 75,100  Radix: 7 UT018003 Comparing source area: EMPDEMO.ORG-DEMO-REGION UT018004      with target area: ORGXDEMO.ORG-DEMO-REGION UT018012    Area added to change table. UT018013     SOURCE AREA Range: 75,151 to 75,200  Radix: 8 UT018013     TARGET AREA Range: 75,001 to 75,050  Radix: 9 UT018003 Comparing source area: EMPDEMO.INS-DEMO-REGION UT018004      with target area: INSXDEMO.INS-DEMO-REGION UT018012    Area added to change table. UT018013     SOURCE AREA Range: 75,101 to 75,150  Radix: 8 UT018013     TARGET AREA Range: 75,001 to 75,050  Radix: 8 UT018005 File EMPDEMO.EMPDEMO has been selected for processing UT018006      Source DDname: EMPDEMO  Target DDname: EMPXDEMO UT018005 File EMPDEMO.INSDEMO has been selected for processing UT018006      Source DDname: INSDEMO  Target DDname: INSXDEMO UT018005 File EMPDEMO.ORGDEMO has been selected for processing UT018006      Source DDname: ORGDEMO  Target DDname: ORGXDEMO Starting CONVERSION of file EMPDEMO.EMPDEMO UT001006 Program IDMSUCON processed 10 records UT001006 Program IDMSUCON processed 20 records UT001006 Program IDMSUCON processed 30 records UT001006 Program IDMSUCON processed 40 records UT001006 Program IDMSUCON processed 50 records UT001006 Program IDMSUCON processed 60 records UT001006 Program IDMSUCON processed 70 records UT001006 Program IDMSUCON processed 80 records UT001006 Program IDMSUCON processed 90 records UT001006 Program IDMSUCON processed 100 records CONVERSION complete    Pages   Read: 100  Modified: 100    Records Read: 346  Modified: 346    Dbkeys  Read: 2,847  Modified: 2,847  Null: 1    Errors  Page: 0  Dbkey:    0 Starting CONVERSION of file EMPDEMO.INSDEMO UT001006 Program IDMSUCON processed 110 records UT001006 Program IDMSUCON processed 120 records UT001006 Program IDMSUCON processed 130 records UT001006 Program IDMSUCON processed 140 records UT001006 Program IDMSUCON processed 150 records CONVERSION complete    Pages   Read: 50  Modified: 50    Records Read: 84  Modified: 84    Dbkeys  Read: 494  Modified: 494  Null: 0    Errors  Page: 0  Dbkey:    0 Starting CONVERSION of file EMPDEMO.ORGDEMO UT001006 Program IDMSUCON processed 160 records UT001006 Program IDMSUCON processed 170 records UT001006 Program IDMSUCON processed 180 records UT001006 Program IDMSUCON processed 190 records UT001006 Program IDMSUCON processed 200 records CONVERSION complete    Pages   Read: 50  Modified: 50    Records Read: 195  Modified: 195    Dbkeys  Read: 1,285  Modified: 1,285  Null: 65    Errors  Page: 0  Dbkey:    0 UT001006 Program IDMSUCON processed 200 records Status = 0        SQLSTATE = 00000 AutoCommit will COMMIT transaction Command Facility ended with no errors or warnings
More Information
  • For more information about page ranges, see the
    CA IDMS Database Administration Section
    .
  • For more information about max records per page, see the
    CA IDMS Database Administration Section
    .