RESTRUCTURE

The RESTRUCTURE utility modifies record occurrences to match new schema specifications.
idmscu19
The RESTRUCTURE utility modifies record occurrences to match new schema specifications.
Using the RESTRUCTURE utility, you can:
  • Insert new data items anywhere in a record
  • Delete existing data items
  • Change the length and position of data items
  • Change the format of a record from fixed length to variable length or from variable length to fixed length
  • Compress or uncompress a record
  • Add pointers for new or existing sets
  • Delete pointers from existing sets
  • Add or delete prior or owner pointers for existing sets
This article describes the following information:
2
2
Authorization
To
You need this privilege
On
Restructure an area
DBAWRITE
The area
Restructure a segment
DBAWRITE
All areas of the segment
Syntax
  ►►─── RESTRUCTURE ──────────┬── SEGMENT 
segment-name
 ──┬───────────────►                             └── DBNAME 
db-name
 ────────┘  ►─── USING 
subschema-name
 ────────────────────────────────────────────►  ►─┬───────────────────────┬───────────────────────────────────────────►    └─ CONTINUE ─┬─ YES ──┬─┘                 └─ NO ◄──┘    ►─┬──────────────────────────────┬────────────────────────────────────►    └─ RSTTMOD ─┬─ 
rstt-modname
 ─┬─┘                └─ IDMSRSTT ◄────┘  ►─┬───────────────────────────────────────────────────┬───────────────►◄    │             ┌───────────────────────────────────┐ │    └────── AREA ─▼──────────────── 
area-name
 ────────┴─┘  
Parameters
  • db-name
    Identifies the name of the database to be restructured.
  • USING
    Specifies the subschema that defines all the records and sets to be restructured.
  • subschema-name
    The name of a subschema compiled under a schema that describes the database before restructuring.
  • CONTINUE
    Specifies whether processing is to continue if an error condition is detected during processing.
    By default, if you do not specify YES, processing stops when an error is detected.
  • YES
    Directs processing to continue when an error is detected.
  • NO
    Directs processing to stop when an error is detected.
    NO is the default.
  • RSTTMOD
    Specifies the base restructuring table that defines the changes to be made in the database.
    By default, if you do not specify a base restructuring table, IDMSRSTT is used.
  • rstt-modname
    The name of the base restructuring table.
    The default base restructuring table is IDMSRSTT.
  • AREA
    Restricts processing to one or more specified areas. The parameter
    segment-name q
    ualifies which area the changes need to be made in
    By default, if you do not specify one or more areas, all areas in the specified segment that contain occurrences of the records or members of the sets being restructured are processed.
  • area-name
    The name of an area.
Usage
How to submit the RESTRUCTURE statement
You submit the RESTRUCTURE statement only through the batch command facility. When submitting RESTRUCTURE statements, you must run the batch command facility in local mode.
The base restructuring table
The RESTRUCTURE statement modifies record occurrences according to the specifications in a
base restructuring table
. You assemble the base restructuring table from IDMSRSTT macro statements that define the changes to be made. Typically, you use the IDMSRSTC utility to generate the IDMSRSTT macro statements; however, the statements can also be coded sectionly.
For more information, see IDMSRSTT Macro Statements.
The spill file
If you specify a
set-name
in the SETPTR statement of IDMSRSTT during RESTRUCTURE processing, a
spill file
of work records that describes new pointers being added to database records is generated. If the database restructure includes the addition of new prior pointers to existing sets, you use the spill file as input to the RESTRUCTURE CONNECT utility statement. The information in the spill file and the specifications in the base restructuring table are used during RESTRUCTURE processing to connect the new prior pointers.
Database keys of restructured records
During RESTRUCTURE processing all changes to the database are made in place (that is, no unload/reload occurs). As a result, database keys are not changed by a restructure operation.
Back up the database
Back up the database before performing a restructure operation. If the database restructure is unsuccessful, you can then restore the database from the backup copy.
Remove logically deleted records
You cannot use the RESTRUCTURE utility statement to make changes that will modify the prefix portion of a record if there are logically deleted records in the database area to be modified. To ensure there are no logically deleted records, use the CLEANUP utility to erase them before performing a restructure operation.
Restructure ready mode
All areas to be processed are readied in exclusive update mode for RESTRUCTURE processing.
Modifying CALC and sort keys
During a restructure operation, you should not modify CALC and sort keys.
For more information about modifying database components, see Administrating CA IDMS Database.
Native VSAM data sets
You cannot use RESTRUCTURE to restructure records in native VSAM data sets.
New pointers
New pointers in an owner record are initialized to the database key of the owner record (indicating an empty set). In a member record, new pointers are initialized to -1.
To connect new pointers for existing sets, use the RESTRUCTURE CONNECT utility statement. To connect pointers for new sets, you must run a user-written program after the restructure process is complete.
Consideration when using data compression routines
If the named subschema references a data compression routine and a compressed record is involved in the restructure (for example, changing the record to fixed length), the subschema will be modified. To modify the subschema, it must be nonreentrant. If necessary, relink the subschema as nonreentrant and run it from another load library.
If the subschema resides in a dictionary load area, this is not a consideration.
Restructuring a database
To restructure a database, follow these steps:
  1. Back up the database
    .
  2. Compile a new schema
    that describes the database after restructuring. The new schema must have a different name or version number from the schema that describes the existing database.
  3. Execute the IDMSRSTC utility
    to generate the IDMSRSTT macro statements that define the changes to be made to the database. Verify that the statements are correct; make any necessary modifications.
  4. Assemble the base restructuring table
    .
  5. Link edit the base restructuring table
    .
  6. Execute the RESTRUCTURE utility statement
    to restructure the database. Use a subschema that was compiled under the old schema.
  7. Compile a subschema under the new schema
    . Give the new subschema a temporary name to distinguish it from the old subschema.
    If no new pointers have been added to existing sets, skip to step 10.
  8. Execute the RESTRUCTURE CONNECT utility statement
    to connect the new prior or owner pointers for existing sets in the restructured database. Use a subschema that was compiled under the new schema.
  9. Validate the restructure
    using IDMSDBAN, CA OLQ, CA Culprit, or some other retrieval program.
  10. Recompile, under the new schema, all subschemas that use the changed records or sets
    .
  11. Alter all access modules referencing changed records or owner and member records of changed sets.
  12. Drop and recreate SQL views of records whose element descriptions have changed.
JCL Considerations
When you submit a RESTRUCTURE statement through the batch command facility, the JCL to execute the facility must include statements to define:
  • The database file(s) that map to the area(s) to be processed.
  • The file containing the assembled base restructuring table.
  • The spill file to be used as input to the RESTRUCTURE CONNECT utility statement. The size of the spill file should be a multiple of 40 with a maximum size of 32,760.
For more information about the generic JCL used to execute the batch command facility, see the Batch Command Facility (z/OS) or z/VSE JCL topics.
Examples and Sample Output
Adding set pointers
The following example directs the RESTRUCTURE utility to use the base restructuring table, LRDKRSTT, to add prior pointers to the owners and members of set A-B and owner pointers to the members of set A-B.
Input to RESTRUCTURE
RESTRUCTURE empdemo using restr01      rsttmod lrdkrstt continue yes;
Output from RESTRUCTURE
When the RESTRUCTURE operation is completed, the following listing is generated.
IDMSBCF                                              IDMS Batch Command Facility                            mm/dd/yy   PAGE 1    RESTRUCTURE EMPDEMO USING RESTR01         RSTTMOD LRDKRSTT CONTINUE YES; 0UT000038 Starting Restructure of area EMPDEMO.EMP-DEMO-REGION  UT000041 Completed processing of area EMPDEMO.EMP-DEMO-REGION, Pages read=10  Records read=6  UT011023   Record name AA  Found=2  Changed=2  Ldel=0 0UT000038 Starting Restructure of area EMPDEMO.INS-DEMO-REGION  UT000041 Completed processing of area EMPDEMO.INS-DEMO-REGION,  Pages read=10  Records read=3  UT011023   Record name BB  Found=3  Changed=3  Ldel=0  Status = 0
Connecting prior and owner pointers
To complete this restructure operation, the RESTRUCTURE CONNECT utility is executed to connect the prior and owner pointers in all occurrences of set A-B after restructuring records A and B.
Input to RESTRUCTURE CONNECT
restructure connect segment empdemo using EMPSS01      rsttmod lrdkrstt continue yes;
Output from RESTRUCTURE CONNECT
When the RESTRUCTURE CONNECT operation is completed, the following listing is generated.
IDMSBCF                                              IDMS Batch Command Facility                            mm/dd/yy   PAGE 1    RESTRUCTURE CONNECT SEGMENT EMPDEMO USING EMPSS01         RSTTMOD LRDKRSTT CONTINUE YES; 0UT000038 Starting Connect of area EMPDEMO.EMP-DEMO-REGION  UT000041 Completed processing of area EMPDEMO.EMPDEMO-REGION,  Pages read=10  Records read=6  UT011023   Record name AA  Found=2  Changed=2  Ldel=0 0UT000038 Starting Connect of area EMPDEMO.INSDEMO-REGION  UT000041 Completed processing of area EMPDEMO.INSDEMO-REGION,  Pages read=10  Records read=3  UT011023   Record name BB  Found=3  Changed=3  Ldel=0  Status = 0
More Information
Callable Restructure Utility
The Callable Restructure Utility (IDMSCRSU) is a version of the CA IDMS RESTRUCTURE utility that is callable from a user-written program. It uses the standard base restructuring table to control the restructure of the data portion of a database record.
For more information about assembling a base restructuring table, see IDMSRSTT Macro Statements.
IDMSCRSU is called with the following register values and parms:
On Entry:
  • R1 points to a four-word parmlist.
  • R13 should point to a 36-word save and work area.
  • R14 contains the return address.
  • R15 contains the entry point address.
Considerations
IDMSCRSU does not support changes to pointers or calling database procedures. The assumption is that the caller has obtained the database record in the old subschema format and now wants to store or modify a record in the new subschema format.
To save a search of the IDMSRSTT base restructuring table on every call, the caller can save the RREC address returned in R0 after the first call. This address can then be passed instead of the IDMSRSTT address on all subsequent calls for the same record type.
A 36-word register save area and work area is expected to be passed in R13. If called from a DC assembler program, you can use a "#CHKSTK =36" instruction to ensure there is enough room in the stack.
Parameters
  • parm-1
    The address of the FSR (SR51) control block from the "old"subschema. This block should describe the record as it exists before the restructure takes place.
  • parm-2
    The address of the IDMSRSTT base restructuring table that describes the changes being made to the database record. This table is generated from the IDMSRSTT macro. (See Section B.) The table is searched for the RREC block that matches the FSR name passed in parm-1.
    - or -
    The address of the RREC control block in the IDMSRSTT table. (No search is done.)
  • parm-3
    The address of the data record to be restructured. Only the data should be passed, not pointers or internal fields.
  • parm-4
    The address of a buffer where the restructured record will be returned. It should be large enough to hold the maximum size of the record being restructured as described in the 'new' subschema.
    On exit:
    • R0 contains the address of the IDMSRSTT RREC block for the record just restructured, if found.
    • R15 contains one of the following return codes:
      • 0: Call successful - The output buffer contains the restructured record.
      • 4: FIELD=ALL was specified for the record in the IDMSRSTT table. There were no changes to the data. The output buffer does
        not
        contain a copy of the record; the caller should use the input record image.
      • 8: The record was not found in the IDMSRSTT table.