1. Inside Module 2 Working with Databases Page
Choosing input from databases 2
Reading an entire dataset serially 6
Determining fields in a dataset 8
Reading specific data chains 10
Choosing Get versus Chain 11
Listing records 13
Changing Output Field Structure 14
Creating Basic Reports 16
Changing data in datasets 22
Suprtool has been engineered to primarily read Image and Eloquence databases. It is also capable of reading Oracle and Allbase databases as well. We will primarily focus on reading Image and Eloquence databases with some sprinkling of the commands necessary to read Oracle and Allbase databases.

2. Accessing data files
These Suprtool commands access TurboIMAGE and Eloquence datasets:
BASE GET
CHAIN FORM
PUT DELETE
UPDATE
Base Opens a specified database
Get Selects a dataset for serial access (MR Nobuf on MPE)
Chain Selects a dataset for chained access by key value
Form Displays information about the items and datasets in a database
Put Writes records to a dataset
Delete Removes records from a dataset
Update Changes values in dataset records
Base and Put differ slightly for Eloquence; the differences are discussed in module 3. Get, Chain, Form and Delete as described in this module work the same on TurboIMAGE and Eloquence.
For Oracle and Allbase:
Open Opens Oracle and Allbase databases
Select Reads Allbase or Oracle tables
Add Not for Image or Eloquence, Oracle only

3. Opening and closing a database (Image)
You can use the BASE command to open a database
>base store,5,READER
The BASE command without parameters closes a database
A database remains open until a BASE, RESET BASE or RESET ALL command is executed
Eloquence Base command is slightly different; see module 3
Syntax BASE [system#] database [,mode] [,password]
Defaults system = logon mode = 1 password = creator password
Password In session mode, the creator password is used by default if a password is not entered or if Suprtool is not running interactively.
To prompt for the password, put a question mark as the database password on the command line. This password will not be echoed.
>base store,5,? Password > {will not be echoed}
Modes Mode-1(default) - shared read, shared write Mode-3 - exclusive read, exclusive write Mode-4 - shared read, exclusive write Mode-5 - shared read, no write
Examples >base store,5,reader {open database}
>base newyork#store,5,reader {open remote database}
>base {if no parameters, close database}
Suprtool’s Get command is the slowest in mode-3.
Some MPE versions restrict remote database access. Run Suprtool on the remote database system and then transfer the output file.

4. How to find datasets in a database
Use the FORM SETS command to display datasets
>base store.demo Database password[;]? >form sets Database:STORE.DEMO.APPDEV TPI: SUPERDEX(15015d)
Set Item Capa- Entry Load Entry Sets: Num Type Count city Count Factor Length B/F M-CUSTOMER 1 M % 55 7 M-PRODUCT 2 M % M-SUPPLIER 3 M % 49 8 D-INVENTORY4 D % D-SALES 5 D % 19 14
Form Sets Requires an open database; displays information about datasets; displays fully qualified database name; identifies MPE/iX third-party indexing products; produces similar output as HP’s QUERY tool.
Eloquence databases show Indexes and the simulated indexes, will also show the version of Eloquence.

5. More about the Form command
The FORM command without parameters first defaults to the current input dataset. If no input has been specified, then it defaults to FORM SETS.
All output is written to the Formout file, which can be redirected to a line printer or a disc file. Currently the Formout file is not available on HP-UX.
No parameters If no parameters are specified with the Form command, and a Chain, Get, or Input command has been entered, the fields in the current input source are displayed as the first default.
If a Base command has been specified without an input source, Form Sets is the second default.
Example to a line printer >:file formout;dev=lp >form sets
Example to a disc file >:file formout=filename;dev=disc >form d-inventory >:reset formout

6. Datasets as input sources
The GET command reads a dataset in one of several ways
It can read the entire dataset serially
It can read a subset of dataset records serially
It can read records at a specified interval (e.g., every 5th record). This kind of sampling is useful for test purposes.
A database must be open before you can use the GET command
Syntax GET setname [(startrecord/endrecord) | (#count)]
If you only specify a setname, Suprtool reads the whole dataset serially. In most cases, the Get command is faster than a chained read, even if you are selecting key values on a path.
Examples >get dtrans(100/200) {read records 100 to 200}
>get dtrans(100) {read records 100 to EOF}
>get dtrans(#4) {read every 4th record}
Empty spots Dataset entry locations do not always have records in them. Like a parking lot, some locations will be empty. Reading a selection of records (e.g., 100/200) will not always get as many records as you expect (e.g., fewer than 101), because these options tell Suprtool which locations to look in for records.

7. Warnings using Get
Suprtool checks the dataset entry count before and after processing, and warns you if it has changed.
Suprtool permits concurrent changes, but warns you when this happens. If you need exclusive access, open the database in mode-4.
If you repeatedly receive warnings of new entries, use the SET EOFREAD ON command to read to end-of-file. (Must be specified before the GET command!)
Quit In many cases you can ignore warning messages, but in certain cases warning messages may indicate a serious problem with the current task. To stop the current processing task, use Control-Y.
Set Eofread On Forces Suprtool to read to end-of-file so that new records won’t be missed
Examples Records added New entries were added to the dataset. Suprtool may have ignored some dataset entries.
Records deleted The number of dataset entries was reduced. Suprtool may have included some deleted dataset entries.
All serial read tools that don’t lock the dataset during the read, including Query and your own programs, will get deleted records and miss new records. Suprtool just happens to tell you about it.

8. Determining fields in a dataset
Use FORM setname to display the fields in a dataset
>form m-customer
M-CUSTOMER MASTER SET 1 Entry: Offset CITY X12 1 CREDIT-RATING J2 13 CUST-ACCOUNT Z8 17 <<SearchField>> CUST-STATUS X2 25 NAME-FIRST X NAME-LAST X STATE-CODE X2 53 STREET-ADDRESS 2X ZIP-CODE X6 105
Capacity:211 (7) Entries:20 Bytes:110
Syntax FORM [SETS | ITEMS | PATHS | dataset | dataitem | filename]
By selecting a filename, you can use the Form command to display the structure of a self-describing file.
Form Items Displays all the items in a database
All the above commands work with Eloquence databases as well.
If the named set doesn’t exist, Suprtool tries to open the file as a self-describing MPE file.

9. Defining New Fields
Create new field definitions: > define D-STATUS,25,1,CHAR
ABSOLUTE definition: define field,byteposition,length[,type] e.g. > define ord-total,20,4,integer
RELATIVE definition: define field,fieldname[(subscript)][[offset]],length[,type] e.g. > define branch-no,cust-code[1],2
Relative defines are associated with a record item, so will stay correct if the field sequence changes.
What if your dataset (or flat file) contains logical fields that are not defined in the Root File (or file label)?
You can use the define command to tell Suprtool where these fields are, and what their datatypes are. After you have defined the fields, you can use them exactly the same way as regular Image/ Eloquence items.

10. Reading specific data chains
If you know the key value(s), use the CHAIN command to search a dataset and select records with the specified key
>chain d-sales,customer = “123456”
>chain dtrans,partnum = “A123”,“B654”,“G999”
>chain d-sales,customer = slist {use a table}
Even when you know the key values, the GET command may select the same records faster than CHAIN can
>get d-sales; if $lookup(slist, customer)
Syntax CHAIN setname, search-field = value [,...]
To use the Chain command, you must know the key value, and it must be based on an official IMAGE key.
In IMAGE terminology, Suprtool does a DBFIND and a chained DBGET (mode-5) on detail datasets for each key value instead of sequentially reading the entire dataset. For master datasets, it uses DBGET mode-7.
Speed Chain uses IMAGE intrinsics to read the data. Get uses MR NOBUF access to read the data. On HP-UX a Get command uses a DbGet Mode-2 currently.
You can use Set Stat On to compare the performance of the Chain and Get commands. .

11. Get versus Chain command
Serial access
Any dataset
All records
Physical order
MR NOBUF reads
Selection by any data fields
CHAIN
Keyed access
Only keyed datasets
Only records with key values
Forward chain pointers
DBFIND and DBGET mode-5 and -7
Selection by key field
Suprtool gives you two ways to retrieve records from a TurboIMAGE dataset. The Get command uses serial access, and the Chain command uses keyed access to a dataset.
The Chain command can be particularly useful when you know the value of the key field, such as finding a few customer addresses when you know the customer numbers.
On HP-UX with Eloquence it is currently unclear the best method of access and where the trade off occurs.

12. Exercise 1 Get versus Chain: quick, choose one!
Your task is to retrieve records from the infamous ord-line detail dataset which contains 2.3 million records of 308 bytes each. The key values to be selected are in a file called Ordfile. These 162,000 ord-num field values will select 261,000 records from the dataset.
Your mission, Jim, should you decide to accept it, will be to access the records as quickly as possible, using either the GET command or the CHAIN command. The final results must be sorted in ord-num sequence.
As always, should you fail, the Secretary will disavow all knowledge of your actions.
Using the Chain command
>chain ord-line,ord-num=my-table >table my-table,ord-num,file,ordfile >output myfile >xeq
Using the Get command
>get ord-line >table my-table,ord-num,file,ordfile >if $lookup(my-table,ord-num) >sort ord-num >output myfile >xeq
Which method would take less I/O?
How long would each task take, assuming 100 I/O operations per second?

13. Listing data from datasets
Use the LIST command without parameters to list records whose format is known
>get m-customer >list >xeq
>GET M-CUSTOMER (1) >OUT $NULL (0) CITY = Edmonton CREDIT-RATING = CUST-ACCT = CUST-STATUS = 30 NAME-FIRST = Terry NAME-LAST = Coyle STATE-CODE = AL
The List command produces a formatted dump of the data record displaying fields in the order they were defined.
The output of the List command is very similar to that of Query Report All, except Suprtool makes it more compact by putting as many fields as possible on every line.

14. Changing Field Structure of Output
By default all fields in the input record are copied to the output record.
The EXTRACT command overrides this default. extract field [(subscript)][=value][,....] extract field1\field2
Can have multiple EXTRACT commands
Up to 255 extracted fields
Can specify fieldnames, constants, strings
Output record will be assembled with fields in the same sequence as the EXTRACT commands.
By default, Suprtool copies the entire input record to the output file. If you require only a subset of fields, use EXTRACT commands to specify which fields you want.
You can have as many extract commands as you like. The output file will include all the fields you specify, in the sequence you specified them (up to a maximum of 255 fields).

15. Extract example ..... >get m-customer
>extract name-first, name-last
>extract " City: "
>extract city
>output *
>xeq
Wayne Humphreys City: Vancouver
Elizabeth Welton City: Coquitlam
William Kirk City: Richmond
Jack Morrison City: Calgary
James Young City: Edmonton
Percy Ferguson City: Coquitlam
Walley Nisbet City: Surrey

16. A quick way to produce basic reports
Use the LIST STANDARD command to produce a report with a predefined format
Feb 03, Base STORE.DEMO Set M-CUSTOMER Page 1
CUST-ACCO CITY NAME-FIRST NAME-LAST
Edmonton Arthur Rogers Edmonton Terry Coyle Edmonton James Young Edmonton Tara Bamford
IN=4, OUT=4. CPU-SEC=1. WALL-SEC=1.
Standard format For self-describing files and datasets, the Standard format represents the following set of options: Noname, Noskip, Norec and Rightjustnum. For MPE files, it represents Octal and Char options.
You can override the Standard format by selecting alternate options.
Suprtool’s LIST command does not currently provide the following features:
· formatted dates
· subtotals
· sort breaks
· grand totals
Suprtool’s List command is designed to produce simple reports in either column format or in a Query Report All format.

17. Suprtool lets you customize reports
You can modify reports to improve their appearance or functionality by doing the following:
changing the report title
changing heading names
changing the sort key to make the report contents more meaningful
The versatile List command has a number of options and parameters that give you quick and dirty reports.

18. Customizing a report title and column headings
It is easy to change your report title or column headings
>get m-customer >if city = "Edmonton" >sort name-last >list standard,title "Customers in Edmonton",& >> heading "Customer Name ",& >> "City ",& >> "Account" >ext name-last,name-first,city,cust-account >xeq
The example in this slide would produce the following report:
Feb 03, Customers in Edmonton Page 1
Customer Name City Account
Bamford Tara Edmonton Coyle Terry Edmonton Rogers Arthur Edmonton Young James Edmonton
Title This option allows you to substitute the default title with your own title
Heading You can chose alternate heading names that are more meaningful. To line up the headings with the columns of data, you have to provide enough space for the field width in each heading.
Sort Identifies the sort key and sorts the selected records
Extract Collects specified fields of selected records from an input source
If the extracted fields exceed the width of the output device (e.g., screen), the data will wrap around to the next line. Unlike the report contents, the heading line is truncated.

19. MPE/iX third-party indexing
Requires Omnidex or Superdex indexing software or HP B- tree support (not currently supported in Suprtool/UX)
CHAIN command can access third-party or IMAGE indexes
>chain m-customer,name-last =
FORM command marks IMAGE fields with third-party indexing as "<<TPI>>", and B-trees as "<<Indexed>>"
VERIFY BASE command displays name and version of indexing software
Indexing With MPE/iX 4.0, HP introduced third-party indexing to TurboIMAGE. This feature enables application programs to use third-party indexing software from either Dynamic Information Systems (OMNIDEX) or Bradmark (SUPERDEX) by calling the standard IMAGE intrinsics.
B-Trees MPE/iX 5.0 includes B-trees on master dataset key items.
Chain If third-party indexing or B-trees are enabled, the Chain command takes advantage of these indexes on IMAGE fields. You can use either an IMAGE or a third-party index as the search field. The length of the specified value is limited by the size of the search field. Suprtool supports only X- and U-type TPI or B-tree fields.
Form The Form command shows which IMAGE fields have third-party indexing or B-trees. If you specify a dataset name with the Form command, it finds fields with extra indexes and marks <<TPI>> or <<Indexed>> beside them.
Verify Base This command shows the name and version number of any third-party indexing software available in a database.

20. Form command shows third-party indexes
>form m-customer
M-CUSTOMER Master Set#1 Entry: Offset CITY X <<TPI>> CREDIT-RATING J CUST-ACCOUNT Z8 17 <<SearchField>> <<TPI>> CUST-STATUS X NAME-FIRST X <<TPI>> NAME-LAST X <<TPI>> STATE-CODE X2 53 <<TPI>> STREET-ADDRESS 2X POSTAL-CODE X6 105
Capacity: 211 Entries:20 Entry Length:55 Blocking:7
This example demonstrates how the Form command displays “<<TPI>>” beside IMAGE fields with a third-party index.

21. Exercise 2 Create a listing of the Alberta customers
Create the following report from the STORE database: Mar 20, : Alberta Customers Page 1 Account# Name City Rogers Edmonton Coyle Edmonton Frahm Calgary Tiernan Calgary Young Edmonton Bamford Edmonton Morrison Calgary Johnston Calgary
Note, you need to select records with STATE-CODE = “AL”

22. Changing data in datasets
The Put, Delete and Update commands make changes to the contents of a dataset
You must open the database in mode 1, 2, 3, or 4
You can disable the Put, Delete, and Update functions via the Set Limits ReadOnly command >set limits readonly on

23. Moving data into datasets
We recommend this set of commands to perform a major load of a dataset from a file
>input loadfile >set dumponerror on {default} >set defer on >set ignore on >put m-cust,store.pub,3 >xeq
Input file record structure must match the destination dataset structure exactly!
Input Selects the filename of the input source
Set Dumponerror If anything goes wrong (e.g., duplicate key values occur, missing chain head), Set Dumponerror On will dump the problem record to $stdlist and continue processing.
Set Defer On IMAGE defers some of its I/O until it is needed. With Set Defer On, you get faster deferred output. If your system crashes, however, you would have to restore your database from a backup tape. Mode-3 is required for the Set Defer command. Set Defer On has no impact with Eloquence databases.
Set Ignore On Instructs Suprtool not to stop if errors occur
Put PUT setname [,base [,mode [ ,password ]]]
You can Put records into another dataset in the current or in a different database. If you’re taking records from a disc file, you can also put them into a dataset.
In this example, using mode-3 in the final Put command gives Suprtool exclusive access to the database.

24. What if the data doesn’t match exactly?
Use EXTRACT commands to construct the output record
Use DEFINE and EXTRACT to change storage formats: > define amount,1,8,display {...in input file} > define new-amount,1,4,integer {new field} > extract new-amount = amount
Field will have attributes as defined, and value from input record, so the output record will contain the 4-byte integer value of the 8-byte display field in the input record.
The DEFINE command can be used in 2 ways:
To declare a logical field in the input file, and specify its storage attributes.
To create a new field, to be used in the output record.
In the above example, we are creating a new field called NEW- AMOUNT (Integer size 4). The offset used in the define command is not important, as we’ll be assigning it the value we need in the output phase of processing. We define the AMOUNT field, so that we can assign its value to the NEW-AMOUNT field in the extract command. Suprtool converts the value of AMOUNT (display, size 8 bytes) to a 4-byte integer, which is placed in the output record as NEW-AMOUNT.

25. Deleting selected records from the input dataset
Open the database in mode-1, -3, or -4
Access the dataset using GET or CHAIN
Select records to be deleted with IF command
Delete the selected records using DELETE
Optional step: copy the deleted records somewhere else (e.g., OUTPUT file, LIST file, PUT to another dataset)
>get d-sales >item purch-date,date,yymmdd >if purch-date < $date(*-1/*/*) >delete >output oldsales.data,append >xeq
Delete Deletes the selected records by calling DBDELETE for each selected record. Delete is logically done as part of the input phase when records are read and selected. This occurs before records are passed to the sort phase and before any records are written to the output file.
Set Dumponerror If a record cannot be deleted (e.g., master dataset that still has details), Dumponerror would display the record in question.
Set Defer On When Defer is On, IMAGE does not write the deletes to disc until it absolutely must do so. This speeds up the process. If there is a system failure during the task, however, the database would need to be restored.
Set Ignore On Instructs Suprtool not to stop if errors occur.

26. Using two passes guarantees safety
>get d-sales >item purch-date,date,yymmdd >if purch-date < $date(*-1/*/*) >output oldsales.data,append >xeq
>get d-sales >if purch-date < $date(*-1/*/*) >delete
>output $null >xeq
If your goal is to save or archive the records that you delete, doing it all in one pass as shown on the previous page is not the safest operation. We recommend using two passes.
By saving all the records in the first pass, you ensure that the target records are safely stored in a file before they are actually deleted. Once the records are archived, go back and delete them in the second pass.

27. Update selected records with new values
Open the database in mode-1, -2, -3, or -4
Access the dataset using GET or CHAIN
Select records to be updated using IF
Enable updating using UPDATE command; use CIUPDATE parameter to update critical fields
Specify fields and new values using EXTRACT commands
>get d-sales >item purch-date,date,yymmdd >if purch-date < $date(*-1/*/*) >update >extract purch-status = “OLD” >xeq
Update This command enables update mode for IMAGE datasets. Any selected records are updated with the new values as defined in the subsequent Extract statements.
Extract For every field selected, each Extract command updates the records with the new constant value. Many fields may be updated in one pass. All the updated records get the same new value.

28. Assigning Calculated Values
>get d-sales
>update
>extract sales-total = &
(product-price * sales-qty) + sales-tax
>xeq
Update all records from the D-SALES dataset [no]: yes
Warning: Using DBGET for the input records
IN=8, OUT=8. CPU-Sec=1. Wall-Sec=1.

29. Set Lock to control concurrent dataset access
Lock the dataset and unlock it again around every DELETE, PUT, and UPDATE
Least contention with other processes, but slowest option for Suprtool
SET LOCK 0
Lock the dataset at the beginning of the task and unlock it only at the end
Best performance for Suprtool, but locks out other processes for duration of Suprtool run
SET LOCK n
Lock dataset on n DELETE, PUT, or UPDATE transactions, then unlock
Compromise between SET LOCK 0 and SET LOCK 1
When Suprtool has the database open in any mode that permits multiuser access, IMAGE forces Suprtool to lock the dataset that it will be updating or deleting. How often Suprtool locks and unlocks the dataset(s) is up to you.
The Set Lock 1 default locks and unlocks the datasets around each Delete, Put, and Update transaction. This permits other processes to access the dataset without waiting.
Set Lock 0 gives Suprtool exclusive access to the dataset for the duration of the task. This is the fastest method for Suprtool, but obviously it affects other users.
Set Lock n lets you control how often Suprtool locks and unlocks the datasets. Suprtool starts with the dataset unlocked and locks it the first time it needs to do an Update, Delete, or Put transaction. It leaves the datasets locked until it has done n of these transactions. Then it unlocks the sets and leaves them unlocked until the next Update, Delete, or Put transaction.

30. Summary Display datasets Field names and formats Data chains
List datasets
Reports (e.g., standard, customized)
Third-party indexing
Adding, deleting, and modifying records
Changing data formats
Locking options