AdagerHome Your Adager Guide (Section 13 of 13)
First | Prev Table of Contents | Index  



Adager Remodeling Functions
You can add (create), delete (drop), rename, shuffle (reorder), and change the types of the datasets, fields and data items of your database. You can modify the security provisions for datasets and data items. You can add (create) and delete (drop) paths, as well as change a sorted path to an unsorted path or vice versa. For detail datasets with several paths, you can redefine the primary path.

You can change a database so that it will use LargeFile datasets (instead of Jumbo datasets) for datasets larger than 4 gigabytes.

If you have Adager Model One, you need to upgrade to Adager Model Two to use Adager's remodeling functions. Even though Adager Model One is very powerful, it does not include most of Adager's restructuring functions. To review, Adager Model One contains:

In addition, Adager Model One provides you with these restructuring functions: Change Primary, Change Security, Enable LargeFiles, Rename Database, Rename Dataset, Rename Field, Rename Item.

Adager Model Two (the full power of Adager) contains all of the functions in Adager Model One plus all of Adager's remodeling functions to add, change, delete, redefine, and shuffle structural IMAGE objects such as datasets, fields, data items, paths, primary paths, sort features, date-oriented data items and their fields.

You may upgrade your Adager license from Model One to Model Two at any time, with full credit for your previous license payments.


Add Dataset
Adager adds a dataset of any type (detail, manual master or automatic master) to a database. You can select the position of the new dataset (subject to IMAGE's requirement that a path's master must come before the detail, for DBLOAD's sake — as enforced by DBSCHEMA).

If you place the new dataset in front of existing datasets, Adager must increment their dataset numbers to accommodate the newcomer. If you add a dataset this way, thereby renumbering existing datasets in the database, you must modify programs that depend on current dataset numbers.

Please see Change Capacity for information on the dialogue that Adager uses to request capacity information from you. You may specify capacities that involve Dynamic Dataset Expansion (DDX) and jumbo datasets.

Adager defaults the new dataset's security so that all user classes can read but no user classes can write and the new dataset's device to DISC, although you can easily override these defaults.

Adager prompts you for the new dataset's entry layout on a field-by-field basis.

You specify each field by data item name. If the name you specify isn't in the item table, Adager helps you add it on the spot so you may continue.

You may define up to 16 paths for a detail dataset by means of detail search fields. A detail search field references a master dataset as the other member of the path. Optionally, a detail search field may also reference another detail field as the path's sort field. You specify these references just as you do in an IMAGE schema (don't worry about having to remember the syntax, because Adager displays the appropriate format at every prompt). If the detail search field references a non-existing master dataset, Adager helps you add it on the spot so you may continue.


Add Field
Adager introduces a new field to a dataset, anywhere in the dataset's entry layout.

You specify the new field by its data item name. If the name you specify is not in the database's item table, Adager helps you add it so you may continue.

The addition of new fields may result in a smaller blocking factor for the dataset.

Programs that use the "@" list to access this dataset will probably get an internal buffer overflow, because their programmers may not have allowed for the increased size of the dataset's entry. Internal buffer overflows in your programs cause horrible behavior. Users may say, "but these programs have worked just fine for many years and we have not changed them at all" (which is, precisely, the problem). Please change the buffer sizes of these programs.


Add Item
Adager adds an item of any type: character, integer, zoned decimal, packed decimal, logical, real (either HP e3000 reals or IEEE reals). You can position the new item anywhere in relation to existing items.

If you place the new item in front of existing items, Adager must increment their item numbers to accommodate the newcomer.

If you add an item this way, thereby renumbering existing items in the database, you must modify programs that depend on current item numbers.


Add Path
You may define up to 16 paths for a detail dataset by means of detail search fields. A detail search field references a master dataset as the other member of the path. Optionally, a detail search field may also reference another detail field as the path's sort field. You specify these references just as you do in an IMAGE schema (don't worry about having to remember the syntax, because Adager displays the appropriate format at every prompt). If the detail search field references a non-existing master dataset, Adager helps you add it so you may continue.

Adager honors IMAGE's requirement that a path's master must come before the detail, for DBLOAD's sake — as enforced by DBSCHEMA. If you specify a master that is currently "behind" the detail, Adager shuffles datasets to comply with IMAGE's rules.

If you add the new master dataset "in the middle", thereby renumbering existing datasets, you must modify programs that depend on current dataset numbers.

Adager links all existing detail entries with identical search-field values into chains which are indexed by master ChainHeads. Adager adds any missing master entries.

Please be sure that the master dataset's capacity is large enough to hold any necessary new master entries to avoid errors.

The resulting detail dataset may end up with a lower blocking factor (and a slightly higher capacity, to comply with IMAGE rules) due to the increase in media entry size caused by the addition of the ChainLinks.

The resulting master dataset may end up with a lower blocking factor due to the increase in media entry size caused by the addition of the ChainHeads.


Add Sort
Adager adds the sort feature to a path and reorganizes all of the path's chains accordingly. Note: older versions of IMAGE/3000 and TurboIMAGE required sort fields to be of type "U" or "X" or "K." Since 1995, IMAGE has not restricted the type of a sort field. Adager allows you to specify a sort field of any type and warns you (while producing a database's schema, for instance) whenever it encounters a sort field whose type may not be supported by older versions of DBSCHEMA.

The advantage of a sorted path is that chained access retrieves entries in order according to the sort-field values.

A potential disadvantage arises when you add entries to a sorted chain. If the sort field values of the new entries are random, DBPUT must, on average, traverse half of the chain to find the correct insertion point. For long chains, this can be time consuming. For short chains, this may not be a problem. (If new sort field values exceed existing values, there is no performance penalty, because DBPUT will place the new entries at the end of the chain.)

IMAGE treats all fields following the sort field as an extended sort field. If you don't want an extended sort field, use Shuffle Fields to move the sort field to the end of the detail dataset's entry.


Change Dataset
Adager changes the type of a dataset (from automatic to manual, from manual to automatic, from master to detail, from detail to master).

Why would you want to do such a thing? There are many (usually subtle) reasons having to do with database normalization and with performance. Let's discuss an example.

A manual master dataset with a large entry size has, by definition, a small blocking factor. This may cause poor performance if the dataset has a high percentage of secondaries, because IMAGE may have to traverse several blocks for a single DBGET, DBPUT or DBDELETE. In addition, the dataset needs a reasonable amount of free entries (scattered throughout) to help migrating secondaries find "free homes" quickly during a DBPUT. A manual master dataset with large entry sizes wastes a significant amount of disc space as well as backup time and tape reels.

To solve these problems, you may want to change the "residence" of your large entries. Instead of inhabiting a manual master, they might dwell in a detail dataset. Because detail datasets do not have secondaries, detail entries can be tightly packed. To still be able to take advantage of IMAGE's hashed access (available only through master datasets), you may decide to create a path between the detail and the "skinniest" possible master, such as an automatic master that contains just the search field.

With Adager, you can perform these convolutions very simply. As a first step, use Change Dataset to change the manual master to a detail (repacking it in the process).

Then, use Add Dataset to add the automatic master (whose search field should be the same as the search field in the original manual master). Finally, use Add Path to add a path between the newly-typed detail and the newly-created automatic master.

Whenever you change a detail to a master, remember that IMAGE does not allow duplicate master entries. Therefore, if the original detail dataset has several entries with the same search-field value, Adager only honors the first one it finds.

If you change a dataset's type (from master to detail or vice versa, from automatic to master or vice versa), please modify programs that depend on specific dataset types for their access.


Change Date
Adager changes date-oriented items (and all of their occurrences as fields in datasets) from a variety of formats into formats that are capable of holding dates beyond 1999.

Adager always asks you for the authentic type of date you have, regardless of the declared IMAGE type. For instance, you may have ASCII yymmdd information in an item with IMAGE type binary J3.

Change Date supports date-oriented items that have more than one subitem (for instance, 2X5 or 3J2).

Recommendation: You should use Examine Date before using Change Date. Examine Date produces an exhaustive report of potential problems. Armed with this information, you can easily configure Change Date to convert both the formats of your date-oriented data items as well as all of your dataset field values.

Adager easily deals with search fields as a matter of routine. Adager automatically rehashes master datasets whose search fields must be changed for the next millennium.

Do you have overloaded date values? Examine Date detects (and Change Date automatically converts) values such as 9999, ******, 000000, as well as other special cases.

Do you have PowerHouse, CA-MANMAN, MM/3000, HP Calendar, SRN Chronos, and other "proprietary" bit-packed formats? Adager certainly knows about them and handles them with authority.

Do you have embedded dates? Adager supports fillers around date fields. For instance, an X10 item may contain abc970123w with a 3-byte prefix abc followed by a 6-byte date field 970123 and a 1-byte suffix w which, after conversion via Adager's Change Date (according to your specific destination format), may end up as an X10 item ac1997023w containing a 2-byte prefix ac (if you drop the "b" to provide the item with an even byte count) followed by a 7-byte year and day-of-year date 1997023 and a 1-byte suffix w.

Adager allows you to specify the deletion of an existing filler byte (or the addition of a new filler byte) to comply with IMAGE's requirement that an item must have an even-byte length. In the above example, you specified the deletion of the second filler prefix byte "b". You can also ask Adager to add a new filler byte anywhere and to initialize it to any value of your choice. For instance, if you specify the addition of a filler byte in position 4 with an initial value of "m", you get an X12 "abcm1997023w" result.

Do you have odd-byte lengths? Adager supports date types such as yyddd and yyyyddd (year and day-of-year) in X5 and X7 formats (you need to have an even subitem count in these cases, to comply with IMAGE's rule that all items must have an even byte count).


Change Field
Change Field is a subset of Change Item. (Change Item can change any item. Change Field, on the other hand, does not change a search field or a sort field and does not deal with a field whose underlying data item defines other fields.) For further information, see Change Item below.

Use parm=16 to force signed non-negative numbers (as opposed to unsigned non-negative numbers, which is the default) when initializing or converting data fields to P (packed decimal) or Z (zoned decimal) types.


Change Item
Adager changes an item's data type, subitem count and/or subitem length. For instance, Z10 to P6, R2 (HP e3000 real) to E4 (IEEE real), X20 to X30).

Adager applies these changes to all datasets with fields that are defined by that data item. (Use Redefine Item if you want to change an item's definition in the root file only, without changing the data in the datasets where that data item defines fields.)

If any affected fields are search fields related to fields defined by some other data item names, Adager also applies the same changes to these other items. This, in turn, implies changes to the corresponding fields. Adager takes care of the potential ripple effects.

Adager enforces all IMAGE rules (for example, you cannot change a search field from X10 to 5X2 because IMAGE does not allow compound search fields).

If the changed item defines (directly or indirectly) a search field in a master dataset, Adager rehashes the master entries, because the hashing algorithm depends on the search field's type and length. With Adager, you don't have to worry about remembering this (and you don't have to be responsible for doing explicit rehashing).

For non-search fields, Adager allows you to change subitem counts and subitem lengths in combinations that are legal under the rules of IMAGE (including odd ones such as 4X1 or 6U3).

Use parm=16 to force signed non-negative numbers (as opposed to unsigned non-negative numbers, which is the default) when initializing or converting data fields to P (packed decimal) or Z (zoned decimal) types.


Change Primary
Adager changes the primary path definition for a detail dataset that has more than one path.

The primary path tells DBUNLOAD which path to use during a chained unload.

The primary path also serves a function for chained DBGETs on a detail dataset. When a program tells DBGET to "get the next detail entry on the chain", DBGET has to know which detail path to use. Normally, programs establish a current path by means of a call to DBFIND before requesting chained reads. If there is no current path in effect for a chained DBGET, IMAGE defaults to the detail's primary path.


Change Security
Adager reports and changes the security specifications of your database:

Please modify programs that depend on current security provisions.


Delete Dataset
Adager deletes a dataset from a database, deleting its paths (if any) in the process.

If you delete a dataset that is in front of existing datasets, Adager must decrement the required dataset numbers to fill in the vacancy.

If you delete a dataset from the middle, thereby renumbering datasets in the database, you must modify programs that depend on current dataset numbers.


Delete Field
Adager deletes a field from a dataset unless it is a search field or a sort field.

To delete a detail search field, please delete its related path before deleting the field.

To delete a sort field, please delete the sort feature from the path(s) in question—or delete the path(s)—beforehand.

The resulting dataset may have a larger blocking factor (and a slightly larger capacity, if it is a detail dataset, to comply with IMAGE rules).

Please update programs that refer to the deleted field.


Delete Item
Adager deletes unreferenced data items (items which do not define any dataset fields) from the database's item table.

You may delete specific items or you may delete all unreferenced items (with "@").

If you delete an item that is in front of other items, Adager must decrement the required item numbers to fill in the vacancy.

If you delete an item from the middle, thereby renumbering items in the database, you must modify programs that depend on current item numbers.


Delete Path
You may conserve disc space and improve the performance of DBPUT by deleting a path which your applications do not use regularly.

Either or both of the datasets involved may subsequently have larger blocking factors as a result of shorter media entry lengths. The detail may also have a slightly larger capacity, to comply with IMAGE rules.

Please update programs that refer to the deleted path.


Delete Sort
Adager removes the sort feature from a sorted path.

You may want to unsort a path that forces DBPUT to organize new detail entries within their chains according to a sorting criterion that nobody uses.

Programs that depend on the sorted organization of all chains in the path will require an explicit sorting procedure, because IMAGE no longer guarantees the ordering that was provided automatically by the sorted path.


Examine Date
Examine Date produces an exhaustive report of potential problems. Armed with this information, you can easily configure Change Date.

Examine Date supports the same date formats and data item characteristics as Change Date (see page 44 ).


Redefine Item
Adager allows you to redefine a data item's type, subitem length, and subitem count in the root-file tables only, without changing your data as it exists in dataset fields. This is useful to bring your database into line with reality if you had cheated in the past to overcome a previous limitation of IMAGE. See "Change Item" on page 45  for a superset of Redefine Item.

A typical case involves sort fields, which IMAGE did not allow as type I (integer) or Z (zoned decimal), for instance. You probably made them type K (logical) or X (ASCII). Now that IMAGE allows any data item type for sort fields, you can use Redefine Item to change them back to I or Z (or whatever you want) without disturbing your data.

Redefine Item allows you to change subitem counts and subitem lengths in combinations that are legal under IMAGE (including odd ones such as 4X1 or 6U3).


Rename Database
Adager changes the names of the files and tables associated with a database.

You may rename a database from one group to another within the same account, but operating-system restrictions prevent renaming across accounts.

If you are renaming across groups, you must have write and save access to the target (logon) group, and the target group must have enough space left in its file limit to hold the database.

If you wish to move the database to another account, please use Copy Database.


Rename Dataset
Adager changes the name of a dataset. Adager does not accept a duplicate name.

If you rename a dataset, you must modify programs that depend on the dataset's current name.


Rename Field
Adager changes the name of a dataset field, making sure your proposed new name is not a duplicate.

You must modify programs that depend on the field's current name.

If the new name refers to a data item which is already defined in the database tables, then both data items (the current item and the new item) must have the same definition.

If the new name is undefined, Adager helps you add it, assigning the current item definition to the new data item.

With Adager Model Two, besides changing a field's name, you can also change its item definition and convert its data values to conform to the new definition by:


Rename Item
Adager changes the name of a data item, making sure your proposed new name is not a duplicate. Adager renames all dataset fields defined by the renamed item. You must modify programs that depend on the item's current name.


Shuffle Datasets
Adager rearranges the order of the datasets within a database, effectively renumbering them (subject to IMAGE's requirement that a path's master must come before the detail, for DBLOAD's sake). You must modify programs that depend on dataset numbers.


Shuffle Fields
Adager rearranges the order of the fields within a dataset's entry.

You may do this for aesthetic reasons or to allow for IMAGE's "extended sort field" feature which applies to sorted paths. If your sort-field values are not unique and you want to avoid unnecessary DBPUT overhead, you should place the sort field at the end of the entry. If you want to take advantage of the extended sort feature, you should place the sort field near the end of the dataset's entry, followed by the fields you wish to include in the extended sort.

Please update programs that use the "@" list to access the fields in the dataset.


Shuffle Items
Adager rearranges the order of the data items within a database, effectively renumbering them.

You may rearrange specific data items or you may specify "@" to sort all of the items alphabetically, according to their names.

Please modify programs that depend on item numbers.



AdagerHome Your Adager Guide (Section 13 of 13)
First | Prev Table of Contents | Index