SET-RELOCATE-PARAMETERS sets the parameters which are needed to enable a RELOCATE-DML to be executed.
Relocation takes place in a sequence of relocation actions which are executed in one or more consecutive online utility runs. Here the DBH maintains the cross-transaction information on the progress of the relocation (e.g. source and target levels) internally. This information is lost when the session or session section ends or when the database of the realm concerned is detached.
SET-RELOCATE-PARAMETERS | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SUBSCHEMA-NAME = <structured-name 1..30>
Subschema name. Only names of user subschemas are permitted.
REALM-NAME = <structured-name 1..30>
Realm name. The realm name must be a valid name in the defined subschema. Only names of user realms are permitted. Names of temporary realms are not permitted.
The subschema must also include all realms which contain the DBTTs whose entries refer to records and tables in the realm which are to be relocated. The corresponding check takes place only when the DMLs are executed. Record types and sets of the realm, on the other hand, need not be fully contained in the specified subschema. To this extent the relocation of records and tables takes place independently of the specifications in the subschema.
RELOCATE-TYPE =
Relocate type. Defines the relocation variant.
RELOCATE-TYPE = *RECORD-PAGES(...)
Relocates records and small tables within a realm.
INITIALIZE =
Defines the behavior of the RELOCATE DML when relocation in a realm is distributed over multiple online utility runs.
Whenever initialization of source and target levels takes place when INITIALIZE = *ANY or *YES, the free place search is implicitly positioned to the beginning of the realm; this corresponds to calling FPASCAN with SEARCH-MODE=*REUSE. In particular, after a complete relocation the source and target levels are not automatically reinitialized. Further execution of relocation actions using INITIALIZE = *NO or INITIALIZE = *ANY will consequently always result in the return information that there is nothing more to do.
INITIALIZE = *ANY
The source and target levels are reinitialized in accordance with certain conditions:
- If a relocation had already been started in a previous utility routine run, this relocation is continued. The source and target levels are not reinitialized.
- If no relocation had been started in a previous online utility run in this session section or in the period since the realm concerned was last attached, the first relocation action implicitly leads to the source and target levels being initialized.
INITIALIZE = *YES
The source and target levels are always reinitialized.
When the first relocation action takes place, the source and target levels are always initialized. The relocation consequently begins again.
You can use this setting to relocate these pages retroactively above all when a previous CLASH-HANDLING=*SKIP-PAGE means that access conflicts with other user transactions have resulted in relocatable pages being skipped.
INITIALIZE = *NO
The source and target levels are not reinitialized.
A relocation which had already been started in the previous online utility run is continued. If no relocation had been started, the source and target levels are not initialized. If you want to execute relocation in a realm in multiple online utility runs, you can use INITIALIZE=*NO to prevent an intended continuation resulting in a restart. It could be that between two online utility runs offline activities are performed in the realm which mean that there is no sense in continuing relocation (now reinitialized).
PAGES-PER-DML = <integer>
Specifies the maximum number of source pages which are to be emptied with a RELOCATE DML (default value: 1).
SKIP-ABOVE-FILLING = <1..100>
Defines a percentage value which specifies the maximum level to which the source page may be filled to permit it to be emptied. The default value of 100 includes all relocatable pages. A lower value enables you to restrict relocation to pages which are not very full. The DBH also uses a specification of under 100 to exclude pages from relocation on the basis of the free place administration data. This optimization consequently also enables you to prevent unnecessary reading of data pages.
CLASH-HANDLING =
Defines how the RELOCATE DML behaves when a source page which is locked by another transaction is to be processed next.
CLASH-HANDLING = *BREAK-DML
The RELOCATE DML is aborted, but any relocations already performed in this DML or in previous DMLs of the same transaction are retained. With the next RELOCATE DML - as a rule in a new transaction -, possibly after a delay in the UDS online utility, another attempt is made to relocate this page.
When CLASH-HANDLING=*BREAK-DML, all required pages are relocated if the source and target levels match. However, if conflicts occur it is possible that additional RELOCATE DMLs are required for this purpose.
CLASH-HANDLING = *SKIP-PAGE
The page is skipped. No attempt is made in a subsequent DML to repeat relocation for this page. However, if too many source or target pages were skipped in a RELOCATE DML, the DML is always aborted.
When CLASH-HANDLING=*SKIP-PAGE, the required number of pages (PAGES-PER-DML parameter) is generally relocated with a RELOCATE DML. However, it can happen that not all required pages are relocated within a RELOCATE cycle. In this case a follow-up action (INITIALIZE=*YES) can be used to complete the relocation later when, for example, corresponding conflicts are less likely.
CLASH-HANDLING = *WAIT-FOR-TRANSACTION
The RELOCATE transaction is waiting until the locked page is released by the locking transaction.
RELOCATE-TYPE = *BASE-LEVEL-TABLE-PAGES(...)
Relocates level 0 pages of multi-level tables within a realm, in other words moves whole level 0 pages of a table to the free beginning of a realm.
INITIALIZE =
See “INITIALIZE =” for RELOCATE-TYPE = *RECORD-PAGES(...).
PAGES-PER-DML= <integer 1..16777215>
Specifies the maximum number of source pages which are to be emptied with a
RELOCATE-DML (default value: 1).
CLASH-HANDLING =
See “CLASH-HANDLING =” for RELOCATE-TYPE = *RECORD-PAGES(...).
RELOCATE-TYPE = *INDEX-LEVEL-TABLE-PAGES(...)
Relocates level N pages of multi-level tables within a realm, in other words moves level N pages of a table to the free beginning of a realm.
INITIALIZE =
See “INITIALIZE =” for RELOCATE-TYPE = *RECORD-PAGES(...).
PAGES-PER-DML= <integer 1..16777215>
Specifies the maximum number of source pages which are to be emptied with a
RELOCATE-DML (default value: 1).
CLASH-HANDLING =
See “CLASH-HANDLING =” for RELOCATE-TYPE = *RECORD-PAGES(...).
RELOCATE-TYPE = *DISTRIBUTABLE-TABLE-PAGES(...)
Relocates level 0 pages of a distributable list from one realm to another realm.
INITIALIZE =
See “INITIALIZE =” for RELOCATE-TYPE = *RECORD-PAGES(...).
PAGES-PER-DML= <integer 1..16777215>
Specifies the maximum number of source pages which are to be emptied with a
RELOCATE-DML (default value: 1).
CLASH-HANDLING =
See “CLASH-HANDLING =” for RELOCATE-TYPE = *RECORD-PAGES(...).
SET-NAME= <structured-name 1..30>
Specifies the distributable list for which relocation is to take place.
The set specified must be a distributable list, otherwise no relocation will take place. In this case an error message is issued and the procedure is aborted.
The corresponding checks are performed only when the DMLs of the UDS online utility are executed.
TARGET-REALM-NAME= <structured-name 1..30>
Defines the target realm, in other words the realm to which relocation is to take place. This realm must be different from the source realm (REALM-NAME parameter) and must be known in the subschema selected (SUBSCHEMA-NAME parameter) and belong to the distributable list (WITHIN clause of the member record type’s DDL-RECORD declaration).
The corresponding checks are performed only when the DMLs of the UDS online utility are executed.