UNLOAD

The UNLOAD utility unloads records from one or more areas of the database in preparation for reloading. The UNLOAD utility does not reload data.
idmscu19
The UNLOAD utility unloads records from one or more areas of the database in preparation for reloading. The UNLOAD utility
does not
reload data.
You cannot use UNLOAD to unload an SQL database that contains keys longer than 256 bytes. Instead, use the REORG utility instead of UNLOAD to reorganize a large key database.
This article describes the following information:
2
2
Authorization
To
You Need This Privilege
On
Unload an area
DBAREAD
The area
Any area(s) with set connections to the area
Any area(s) containing an index defined on records in the area
Unload a segment
DBAREAD
All areas of the segment
Syntax
  ►►─── UNLOAD SEGMENT unload-segment-name ─────────────────────────────────────►  ►─┬─────────────────────────────────┬────────────────────────────────────────►    └─ USING unload-subschema-name ───┘  ►─┬────────────────────────────┬─────────────────────────────────────────────►    │           ┌───── , ──────┐ │    └─── AREA ──▼── area-name ─┴─┘  ►─── RELOAD INTO reload-segment-name ────────────────────────────────────────►  ►─┬───────────────────────────────┬──────────────────────────────────────────►    └─ USING reload-subschema-name ─┘  ►─┬──────────────────────────┬───────────────────────────────────────────────►◄    └─ DMCL reload-dmcl-name ──┘  
Parameters
  • unload-segment-name
    Specifies the segment of the database to unload.
  • unload-subschema-name
    Specifies the subschema that describes the database.
    By default, if an
    unload-subschema-name
    is not specified, it indicates that an SQL-type segment is to be unloaded. In this case, the UNLOAD utility builds the required subschema for unload processing.
  • area-name
    Specifies an area in the unload segment to unload. The area must also exist in the reload segment.
    By default, if no areas are specified, all areas in the unload segment that are also defined in the unload subschema will be unloaded.
  • reload-segment-name
    Specifies the segment in which the data will be reloaded.
    This parameter is passed in a control record at the beginning of the RELDCTL file to be used by the RELOAD utility.
    If an SQL-defined database is being unloaded,
    segment-name
    must be the same as the one specified in the SEGMENT clause.
  • reload-subschema-name
    Specifies the subschema that describes the segment in which the data will be reloaded.
    Do not specify a reload subschema if unloading an SQL-type segment.
    This parameter is passed in a control record at the beginning of the RELDCTL file to be used by the RELOAD utility.
    By default, if a reload subschema is not specified, the subschema that was used to unload the data is used to reload the data.
  • reload-dmcl-name
    Specifies the DMCL that defines the segment into which the data will be reloaded. See "The Unload/Reload DMCL" in the "Usage" section for additional information.
    This parameter is passed in a control record at the beginning of the RELDCTL file to be used by the RELOAD utility.
    By default, if a reload-dmcl-name is not specified, the DMCL used during the unload process is used. Unload uses the DMCL that is specified in the SYSIDMS parameter file. If no DMCL is specified in the SYSIDMS parameter file, the name IDMSDMCL is used.
Usage
How to submit the UNLOAD statement
You submit the UNLOAD utility only through the batch command facility. You must run the batch command facility in local mode.
Using UNLOAD on an SQL-defined database
You can use the UNLOAD utility statement to unload and reload an SQL-defined database to make these changes:
  • Change area page ranges
  • Change page size
    See EXPAND PAGE for complete information about changing a page size.
  • Change the maximum number of records per page
The page changes are specified in the DMCL definition.
The modified DMCL must be available during the unload operation and during the reload operation.
You cannot make changes to table definitions in an SQL-defined database between the unload and reload steps.
Using UNLOAD on a non-SQL-defined database
You unload and reload a non-SQL-defined database in order to modify the database based on changes made to the schema or segment definition. These changes must be reflected in the subschema or DMCL used for the reload operation. An SQL-defined database must be reloaded into the same segment. You cannot reload it into another segment.
The modified DMCL or subschema must be available during the unload operation and during the reload operation.
You can make the following changes by using UNLOAD and RELOAD:
  • Change area page ranges
  • Change page size
    See EXPAND PAGE for complete information on changing a page size.
  • Change page ranges for record types
  • Reassign records to different areas
  • Change record placements within an area
  • Change record location modes
  • Store VIA records by means of a different set (as long as they already participate in the set)
  • Change compression and INDEX BLOCK CONTAINS options for indexes
  • Change area and page-range assignments for system-owned indexes
  • Change the maximum number of records per page
UNLOAD and ASF databases
If the UNLOAD utility is to be run against an ASF data or definition area, see the
CA IDMS ASF User Section
for more information.
When not to use UNLOAD
The areas processed by the UNLOAD utility cannot contain any logically deleted records. Therefore, do not use it until you have removed all logically deleted records with the CLEANUP utility statement.
The UNLOAD utility cannot be used against native VSAM files.
During UNLOAD and RELOAD processing, record formats are preserved, that is, the layout of data within a record and record positions within sets. This limits the modifications that you can make during an unload/reload operation. For example, you cannot use an unload/reload operation to:
  • Remove a set
  • Remove a record type
  • Insert new data fields into a record
  • Change the order of a sorted set
  • Connect records to new sets
  • Change or delete record IDs
  • Change the size, location, or data type of sort or index keys
  • Change a set from unordered to ordered
These type of changes require other utilities, such as RESTRUCTURE, and possibly user-written programs.
Using UNLOAD and Mixed Page Groups
UNLOAD cannot process mixed page groups. The subschemas specified for the UNLOAD cannot contain areas that reside in page groups other than the page group for the segment being unloaded. If the environment has an EXIT34 installed that exit will be invoked. If the CA supplied EXIT34 is used (RHDCUX34) and has not been altered a message will be produced indicating that an unqualified FIND/OBTAIN DBKEY command has been issued. If the exit has been modified to abort the associated run-unit when this type of command is encountered, the UNLOAD utility will be abnormally terminated. You must use multiple invocations of the utility to process areas in different page groups.
UNLOAD and the DCMT VARY SEGMENT/AREA PERMANENT
If the UNLOAD utility is to be run with the purpose of changing an area's page range and that change includes changing the area's low page, it is recommended that none of the DCMT VARY SEGMENT/AREA commands using the PERMANENT option be issued against the original area(s). The PERMANENT feature is implemented by carrying the area's low-page number in the journals across cycles of the CV. Changing an area's low-page will prohibit future cycles of the CV to properly identify the area once the new page range is implemented.
If a DCMT VARY SEGMENT/AREA PERMANENT command is still in effect when the new page range is implemented, the area's usage-mode at startup will be determined by the value specified in the DMCL. The entry in the journals for the old area's page range will remain until the next format of the journals.
UNLOAD and the CLEANUP utility
If the area being unloaded contains logically deleted records, run the CLEANUP utility before running unload.
For more information about making these kinds of changes, see the
CA IDMS Database Administration Section
.
How UNLOAD Works
During UNLOAD processing, an area sweep is performed, unloading all CALC, DIRECT, and unowned VIA records. At the same time, the area sweep extracts information for all indexes regardless of whether or not the index has been specified for the data area being unloaded.
After unloading the owner of a VIA set, the area sweep is interrupted to unload all the members of the set.
When unloading a CALC record for which duplicates are allowed, the CALC set is walked in the prior direction to determine the relative position of the record with respect to other record occurrences with duplicate keys.
Non-SQL-defined sets can be partially unloaded
Records in an area being unloaded or reloaded can have set connections (as owners or members) to records in areas not being processed in the same run.
For example, a CALC record in an area being unloaded can own a VIA member in an area that is not being unloaded.
The UNLOAD utility will keep track of the set connections, and the connections will be rebuilt when the records are reloaded.
UNLOAD cannot process mixed page groups and will issue an error message if mixed page groups are encountered. You must use multiple invocations of the utility to process different page groups.
SQL-defined segments
Area and table stamps are unloaded during the UNLOAD steps of an SQL-defined database and are reloaded during RELOAD processing. For this reason, you must format the affected areas using the FILE option between the unload and reload operations.
The one exception to this is when unloading and reloading the DDLCATLOD area in a segment defined for SQL. In this case, either format by area or use the INSTALL STAMPS utility before reloading the data.
DIRECT records and their VIA clusters
Since DIRECT records have been placed on a specific page by a user, it may be difficult for the UNLOAD utility to determine where they should be placed in the new area. If a DIRECT record's old page exists in the new area, the RELOAD attempts to place the occurrence on the same page. However, if the old page does not exist in the new page range, the occurrence is targeted to the low page of the new area.
If a DIRECT record owns a VIA record, the members are stored in their new area proportional to their owner's position in its old area. If the owners and members reside in the same area and the page range has been extended or completely changed, the VIA cluster may not be on the same page as the owner. If this is not acceptable, the user may want to consider using a user-written program to unload the database and the FASTLOAD utility to reload the area.
The Unload/Reload Subschemas
The UNLOAD utility uses information in the dictionary when processing an SQL-defined database. When processing a non-SQL-defined database, the unload and reload subschemas must include the items listed next.
The unload subschema
The subschema used in an unload operation must:
  • Include the areas being unloaded
  • Include all areas containing records with set connections to records in the areas being unloaded
  • Define all record types in the areas being unloaded
  • Define all sets in which the record types participate
  • Define all record types which can participate in the defined sets
The reload subschema
The subschema used in a reload operation (specified by RELOAD INTO..USING) must:
  • Define the same record types and sets as the unload subschema
  • Include the areas to be reloaded and all areas containing records with set connections to those areas.
  • Allow all included areas to be readied in exclusive update mode
Unloading a dictionary
When unloading a dictionary, the IDMSNWKU subschema should be used for all areas, except DDLCAT, DDLCATX, and DDLCATLOD.
The DDLCAT and DDLCATX areas should be unloaded and reloaded using the IDMSCATZ subschema.
The DDLCATLOD area should be unloaded and reloaded using the IDMSCATL subschema. Before reloading the DDLCATLOD area in a segment defined for SQL, you must install stamps either by formatting by area or using the INSTALL STAMPS utility.
The Unload/Reload SEGMENT
The SEGMENT used in the unload and reload operation must include:
  • The area(s) being unloaded.
  • All areas with physical connections to the area(s) being unloaded. This includes:
    • Areas containing indexes on records or tables being unloaded.
    • Areas with set connections to areas being unloaded.
    • Areas containing tables related through a constraint to tables being unloaded.
The Unload/Reload DMCL
The DMCL used in the unload and reload operations must include the segment whose areas are being unloaded.
The UNLOAD utility must establish access to DMCLs for the unloading of the original database and for determining the page ranges of the database areas to be used by the subsequent RELOAD utility. The DMCL(s) to be used by each step of the process is determined as follows.
Unloading the original database
The unload operation will use the DMCL specified in the SYSIDMS file for the UNLOAD utility jobstep. If no DMCL is specified in the SYSIDMS file, the DMCL named IDMSDMCL will be used.
Reloading the new database
The DMCL specified in the RELOAD clause of the UNLOAD utility parameter will be used. If a DMCL is not specified, the DMCL to be used by the UNLOAD operation will be used to determine record placement in the new DMCL and is passed on to the RELOAD utility.
If the area definitions between the original database and the reload database are different, the unload and reload DMCLs must have different names, or the area definition must reside in different segments within the same DMCL.
General Procedure for UNLOAD and RELOAD
Take the following steps to unload and reload a database:
  1. Create the new subschema or DMCL reflecting the changes to be made.
  2. Back up all areas to be unloaded and also areas linked to those areas through sets or linked constraints.
  3. Execute the CLEANUP utility if required.
  4. Execute the UNLOAD utility.
  5. Format the areas into which the data will be reloaded.
  6. Execute the RELOAD utility.
  7. Back up the same areas as in step 2.
This procedure may vary slightly depending on the type of change being made.
Output files
The following output files and sort parameters are generated by the UNLOAD utility for use by the RELOAD utility statement:
File
Contents
Size
SYS002
A record occurrence descriptor for each unloaded record occurrence.
For each occurrence descriptor: 24 bytes plus the size of the data portion of the record occurrence.
 
A set descriptor for each unloaded record occurrence and for each record occurrence that is not unloaded but has a set connection to an unloaded record occurrence.
For each set descriptor: 24 bytes plus 12 times the number of pointers associated with the record, up to 32 pointers. If the record has more than 32 pointers, it will get an additional set descriptor.
SYS003
An index key occurrence descriptor for each index on a record occurrence.
For each index on each record occurrence: 32 bytes plus the size of the symbolic keys in the index.
SYSPCH
Sort parameters
 
RELDCTL
A control record with information about the subschema, DMCL, and segment to be used by RELOAD.
60 bytes
 
A set descriptor for each set in the subschema.
60 bytes
JCL Considerations
When you submit an UNLOAD utility through the batch command facility, the JCL to execute the facility must include statements to define the following:
  • Files containing the areas to be processed
  • Journal file(s), which can be dummied
  • Output files
For more information about the generic JCL used to execute the batch command facility, see the section for your operating system in this section.
Example
The following example directs the UNLOAD utility to unload an area in an SQL-defined segment named USERDB.
unload segment userdb area "emp-area" reload into userdb dmcl newdmcl;
Sample Output
The UNLOAD utility generates the following listing after successful completion of the previous example.
IDMSBCF                                              IDMS Batch Command Facility                            mm/dd/yy   PAGE 1 SET BATCH WIDTH PAGE 80 ; Status = 0   UNLOAD SEGMENT USERDB     AREA  "EMP_AREA"   RELOAD INTO USERDB DMCL NEWDMCL ; UT001002 UNLOAD WILL USE SS   DMCL IDMSDMCL DBNAME USERDB UT001003 RELOAD WILL USE SS   DMCL NEWDMCL  DBNAME USERDB          SUBSCHEMA NAME ------ UNLD$SQL          COMPILE DATE -------- yy-mm-dd          COMPILE TIME -------- 09.54.26          SUBSCHEMA VERSION --- 1200 IDMSUNL1 AREA RECORD DEPENDENCY TABLE FOLLOWS: AREA-NAME          SET-NAME           RECORD-NAME: EMPIX_AREA         MANAGES            SR7                - OWNER EMPIX_AREA         EMPS               SR7                - OWNER EMPIX_AREA         DEPS               SR7                - OWNER ORG_AREA           DEPT_EMPL          DEPT               - OWNER ORG_AREA           JOB_POS            JOB                - OWNER UT004001 IDMSDBL1 RELEASE nn.n TAPE volser PROCESSING STARTED          SUBSCHEMA NAME ------ UNLD$SQL          COMPILE DATE -------- yy-mm-dd          COMPILE TIME -------- 09.54.26          SUBSCHEMA VERSION --- 1200 UT003002    67 INTERMEDIATE RECORDS WERE WRITTEN TO SYS003 UT004005    105 INTERMEDIATE RECORDS WERE WRITTEN TO SYS002 UT004006    36 CHARACTERS IN SMALLEST INTERMEDIATE RECORD UT004007    96 CHARACTERS IN LARGEST INTERMEDIATE RECORD UT004002 IDMSDBL1 RELEASE nn.n PROCESSING COMPLETED UT004003    NO ERRORS WERE ENCOUNTERED UT001001 RECORDS UNLOADED: 74 Status = 0 AutoCommit will COMMIT transaction Command Facility ended with no errors or warnings
For more information about unloading and reloading a database, see the
CA IDMS Database Administration Section
.