1. Inside Module 6 Working with Suprlink Page Accessing Suprlink 4
A sample scenario 6
Self-describing files 15
Linking files 19
Adding information 32
Suprlink requirements 41
Performance guidelines 43

2. Suprlink expands Suprtool capabilities
Adds multi-file linking to Suprtool’s remarkable speed
Works on IMAGE, KSAM, and MPE files
Merges up to 8 files into one
Creates one sorted file as input to your report programs
We love Suprtool’s speed, but couldn’t we have multiple dataset extracts too?  

3. Suprlink ties your data togetherDB
Suprtool
Suprtool
Suprtool
Combined file
Suprlink combines data from multiple datasets, files, or other sources into a single file. The combined output file contains data from all the input and link files. Suprlink uses common data values in the various files to link the records. You can link on any common field, even if it is not a key.
The files you feed to Suprlink are self-describing files. These files can come from anywhere; they do not have to be IMAGE datasets. With Suprlink, you can link a dataset to either a flat file or a KSAM file. Suprlink works with the same efficiency, no matter where the data comes from.
File1
File2
File3
Suprlink
Report program

4. Three ways to access Suprlink
Use the RUN command to use Suprlink directly
:run suprlink.pub.robelle +input file1 +link file2 +output file3 +exit
Use the Suprtool LINK command to start Suprlink
:run suprtool.pub.robelle >link +input file1 +link file2 +output file3 +exit >
Suprlink runs as a separate process from Suprtool. The Suprtool Link command starts Suprlink as a child process of Suprtool, which keeps the Suprlink process alive between commands.
Both Suprtool and Suprlink can be held suspended from other process handlers, such as Qedit or MPEX.
See "Programming Suprtool2" (Module 6) for information on executing Suprlink commands from an application program.

5. Three ways to access Suprlink continued
Use Suprtool’s LINK command to pass commands to Suprlink
:run suprtool.pub.robelle >link input file1 >link link file2 >link output file3 >link exit
On HP-UX run Suprlink directly.
/opt/robelle/bin/suprlink
An advantage of using the Suprtool Link command to pass commands to Suprlink is that all the commands (i.e., both Suprtool and Suprlink) will be in Suprtool’s redo stack. This makes it easier to use Listredo to create a usefile or job stream with all the commands in it.

6. I need all invoices over $100 for British Columbia customers, now!
Step 1: Identify the required data, and their sources
Step 2: Use Suprtool to select and sort records from each dataset or file, extracting the required fields
Step 3: Link the extracted files
Step 4: Produce the report from the linked file

7. What should the report look like?
May 12, : BC Sales over $ Page 1 Account# Name Purch Date Amount Product#
Melander John Nisbet Walley
You can design the report either on paper or on the screen. Decide which fields need to be included, their sequence on the line, and the sorting sequence of the report.
This report is first sorted by account number, then by purchase date if there are multiple records for the same account.

8. Step 1: Where are the records located?
Suprtool’s FORM SETS command lists all the sets in a database opened with the BASE command, and describes their attributes
Use the FORM dataset command to list field names in a dataset
Use COBOL Copylib or Cognos Qschema listings to get the layouts of non-IMAGE files
If you have a flat file with the same layout as a dataset, use Input=datasetname.

9. What datasets are in the Store database?
:run suprtool.pub.robelle >base store.demo >form sets
Database: STORE.DEMO.ROBELLE Set Item Entry Load Entry Sets: Num Type Count Capacity Count Factor Length B/F M-CUSTOMER M % M-PRODUCT M % M-SUPPLIER M % D-INVENTORY 4 D % D-SALES D %

10. What fields are in the m-customer dataset?
>form m-customer
Database: STORE.DEMO.ROBELLE M-CUSTOMER Master Set# Entry: Offset CITY X CREDIT-RATING J CUST-ACCOUNT Z <<Search Field>> CUST-STATUS X NAME-FIRST X NAME-LAST X STATE-CODE X STREET-ADDRESS X POSTAL-CODE X Capacity: 211 (7) Entries: 20 Bytes: 110
To get all the British Columbia customers, we need to extract the cust- account, name-first, and name-last fields of only BC customers from the customer master records.

11. What fields are in the d-sales dataset?
>form d-sales
Database: STORE.DEMO.ROBELLE D-SALES Detail Set# 5 Entry: Offset CUST-ACCOUNT Z (!M-CUSTOMER) DELIV-DATE J PRODUCT-NO Z (M-PRODUCT) PRODUCT-PRICE J PURCH-DATE J SALES-QTY J SALES-TAX J SALES-TOTAL J Capacity: 602 (14) Entries: 8 Bytes: 38
To get all the invoices over $100, we need to extract the cust-account, sales-total, purch-date, and product-no fields from the sales detail records. The records will be selected based on sales-total.

12. Step 2: Extracting and sorting records
First, we need to read all the customer records of British Columbia customers and extract the cust-account, name-last, and name-first fields
Next, we have to read all the records of invoices over $100 and extract the cust-account, product-no, purch-date, and sales-total fields
The cust-account field is common to both records, so we will sort both files by this cust-account

13. Reading records of British Columbia customers
Use Suprtool to select and sort British Columbia customers
>get m-customer >if state-code = "BC" >sort cust-account >extract cust-account,name-last,name-first >output custfile,temp,link >xeq
Output file The default output file is not self-describing; to generate an SD file, use Output filename,Link. To write to an existing file, use Output filename,Erase.
Custfile An output file that contains the sorted records of British Columbia customers selected from the customer master dataset.
Link This option creates a self-describing file that includes information, such as sort keys and compound items.
Temp This option saves the output file as a temporary file instead of a permanent file (the default).

14. List of British Columbia customers
>input custfile;list standard;xeq
CUST-ACCO NAME-LAST NAME-FIRST
10001 Hamilton Darlene Lackner Gordon Melander John Sarafin Thomas Nisbet Walley
Field names are truncated to fit the field length.

15. What is a self-describing file?
Hi, my name is Peter from BC
It is a standard MPE disc file
It has user labels that contain a mini-dictionary describing record structures
Use the FORM command to see the structure

16. Suprlink requires self-describing (SD) files
Suprlink uses self-describing files as input and creates SD files as output
The LINK option of the Suprtool OUTPUT command specifies a self-describing file
>output custfile,temp,link
In our example, Custfile and Tranfile are self-describing files that Suprlink can use as input

17. Reading records of invoices over $100
Use Suprtool again to select and sort records with invoices greater than $100
>get d-sales >item sales-total,decimal,2 >if sales-total > >sort cust-account >sort purch-date >extract cust-account,sales-total,purch-date,product-no >output tranfile,temp,link >xeq
Tranfile An output file that contains the sorted records of invoices over $100 extracted from the invoice detail dataset

18. List of invoices over $100 >input tranfile;list standard;xeq
CUST-ACCO SALES-TOTAL PURCH-DATE PRODUCT-NO

19. Step 3: Linking customer and invoice records
Use Suprlink to merge the extracted records
:run suprlink.pub.robelle +input tranfile link custfile +output reptfile,temp +exit
Reptfile Each record in this file combines the selected fields from both Tranfile and Custfile. There is no need to specify Link on the Output command because that is the default for Suprlink. If you want a non-SD file, use the Data option.
Linking order Each record in an input file can match only one record in the link file; a record in a link file can match any number of records in an input file.
Example In our example, Tranfile was selected first because each invoice needs only one match with a customer name. This order of linking results in a complete list of both invoices and customers.
All the files in our example are temporary and will be purged when the job is completed.
Caveat: If the job bombs, you must restart it from scratch instead of picking up where it left off.

20. What is the structure of the merged file?
>form reptfile
File: REPTFILE.DATA.SALES (SD Version B.00.00) Entry: Offset CUST-ACCOUNT Z <<Sort# 1 >> SALES-TOTAL I << .2 >> PURCH-DATE I <<Sort# 2 >> PRODUCT-NO Z NAME-LAST X NAME-FIRST X Limit: 6 EOF: 5 Entry Length: 50 Blocking: 81
Reptfile The link field appears only once in the merged file; all fields maintain the same format as the original IMAGE schema.
Example In our example, cust-account is the link field between Tranfile and Custfile. It appears only once in the merged file.
You can use this printout to help produce a COBOL Copylib or Qschema definition for Reptfile.

21. How does the merged file look?
>input reptfile;list standard;xeq
CUST-ACCO SALES-TOTAL PURCH-DATE PRODUCT-N NAME-LAST NAME-FIRST Melander John Melander John Melander John Nisbet Walley Nisbet Walley ...
This report gives us the required information, including the correct data for each record. However, the fields are arranged in the wrong order. At this point, we could pass the data to a report writer or another program to produce the final report. We could even use Suprtool to change the sequence of fields and produce a report similar to what the boss wanted (as shown in Step 4).

22. How does the link work?
Input file - 6 records
Hamilton Darlene
Lackner Gordon
Melander John
Sarafin Thomas
Oxenbury Gordon
Humphreys Wayne
Kirk William
Ferguson Percy
Andersen Colin
Nisbet Walley
Link file - 12 records
The input file “drives” the whole linking operation. Suprtool reads the input file one record at a time. For each input record, Suprtool sequentially reads records in the link file to find a match.
When there is a match, Suprlink copies the input data and the link data to the output record. Then Suprlink goes to the next input record.
Where there is no match, Suprlink just goes to the next input record without writing anything to the output record.
Suprlink scans both the input and link files sequentially, starting with the first record. This design, which uses MR NOBUF I/O, is what makes Suprlink so fast.

23. How the link works
Input file - 6 records
Hamilton Darlene
Lackner Gordon
Melander John
Sarafin Thomas
Oxenbury Gordon
Humphreys Wayne
Kirk William
Ferguson Percy
Andersen Colin
Nisbet Walley
Link file - 12 records
You can match a record in an input file with only one record in the link file. The relationship between a record in an input file and records in a link file is many to one. That is, many input records can match one link record. Some people may think of this as a one to many relationship. That’s okay with us.
Note that this method of linking produces different results from the Link command in QUIZ.
Melander John
Melander John
Melander John
Nisbet Walley
Nisbet Walley
Output file - 5 records

24. What happens if we reverse the linking order?
>link input custfile >link link tranfile >link output reptfile,temp >link xeq
>input reptfile;list standard;xeq
CUST-ACCO NAME-LAST NAME-FIRST SALES-TOTAL PURCH-DATE PRODUCT-N Melander John Nisbet Walley
...
If we specify Custfile as the first file, we get a complete list of customers, but only the first invoice for each customer. This order of linking results in an incomplete list of invoices.

25. Reversing the input and link files
Hamilton Darlene
Lackner Gordon
Melander John
Sarafin Thomas
Oxenbury Gordon
Humphreys Wayne
Kirk William
Ferguson Percy
Andersen Colin
Nisbet Walley
Input file - 12 records
Link file - 6 records
When the input and link files are reversed, the results are quite different.
Now the input file has only one record per key value because it came from a master dataset, which cannot have more than one record with the same key value. The link file is from the transaction detail dataset, which records multiple transactions per customer, so it can have multiple records per key value.
Suprlink matches the input record with the first link record that has the same key value. Then it goes to the next input record and looks for a match in the link file. Suprlink skips over the extra link records with the same key value.
Melander John
Nisbet Walley
Output file - 2 records

26. What if an invoice does not match a customer record?
By default, Suprlink drops input records without a matching record in the link file
Specify LINK OPTIONAL to override this default and include unmatched input records
LINK OPTIONAL does not include link records without a matching record in the input file

27. Including unmatched records
>link input tranfile
>link link custfile optional
>link output reptfile,temp
>link xeq
Optional If Suprlink does not find a matching record in the link file, it creates an output record and inserts either spaces or zeros in the unmatched fields.
Example In our example the unmatched link records (10001, , etc.) do not get included when Optional is specified.

28. Including unmatched input records
Input file - 6 records
Hamilton Darlene
Lackner Gordon
Melander John
Sarafin Thomas
Oxenbury Gordon
Humphreys Wayne
Kirk William
Ferguson Percy
Andersen Colin
Nisbet Walley
Link file - 12 records
Melander John Melander John Melander John Nisbet Walley Nisbet Walley
Output file - 6 records

29. Step 4: Produce the report
Use your favorite report writer to format the final report, adding headings, titles, and other features
The report writer has almost no work to do
Use Suprtool LIST command if the reporting needs are basic

30. Suprtool can (almost) produce the report
>input reptfile >extract cust-account,name-last,name-first,purch-date,& >>sales-total,product-no >list standard,title "BC Sales over $100",& >>heading "Account# Name ",& >>"Purch Date Amount Product#" >xeq
May 12, : BC Sales over $100 Page 1
Account# Name Purch Date Amount Product#
Melander John Melander John Melander John Nisbet Walley Nisbet Walley
The data is already sorted in the correct sequence. We just need to change the order of the fields on the line, and add a few titles and headings. Suprtool can produce just about everything the boss asked for, except for blanking out the account number and customer name when it repeats.
The job is done. The boss should be happy. Hopefully he won’t change his mind like he always does...

31. Suprlink Exercise 1
From the Store database, find all the British Columbia supplied products that have inventories less than 20
You should include the product number, quantity in stock, as well as the supplier's name and number
Here is the report you are trying to produce:
SUPPLIER- PRODUCT-N ON-HAND-QTY SUPPLIER-NAME
Makita Canada Inc Makita Canada Inc Makita Canada Inc Makita Canada Inc Black & Decker
...

32. Can I add more information to the report?
The boss has asked to see product descriptions on the report
May 12, : BC Sales over $ Page 1 Account# Name Purch Date Amount Product# Product
Melander John Drill Drill Saw Nisbet Walley Saw Jigsaw

33. Which dataset contains product descriptions?
>form sets Database: STORE.DEMO.ROBELLE
Set Item Entry Load Entry Sets: Num Type Count Capacity Count Factor Length B/F M-CUSTOMER 1 M % M-PRODUCT 2 M % M-SUPPLIER 3 M % D-INVENTORY 4 D % D-SALES 5 D %

34. What fields are in the product dataset?
>form m-product
Database: STORE.DEMO.ROBELLE M-PRODUCT Master Set# 2 Entry: Offset PRODUCT-DESC X PRODUCT-MODEL X PRODUCT-NO Z <<Search Field>> Capacity: 307 (12) Entries: 13 Bytes: 48
We need to add the prod-desc field to the report and to use the product- no field to link all the information together.

35. Selecting the required fields
We want to read the product-no and product-desc fields in the product master dataset
We want to read all the fields in Reptfile
Product-no field is common to both records

36. Reading product description records
>get m-product >sort product-no >extract product-no,product-desc >output prodfile,temp,link >xeq
Table You can also use the Table command to restrict the selection of records from the product master dataset
Example In the following example, only records that exist in Reptfile will be selected:
>get m-product >table prod-list,product-no,file,reptfile >if $lookup(prod-list,product-no) >extract product-no,prod-desc >output prodfile,temp,link >xeq
You can also use the Sorted keyword to indicate that the input file to a table is in sorted order. This reduces Suprtool's processing time by eliminating the sorting operation.
>get m-product >table prod-list,product-no,sorted,reptfile >if $lookup(prod-list,product-no) >extract product-no,prod-desc >output prodfile,temp,link >xeq

37. Re-sorting the invoices on the product field
Suprlink input and link files must have the same sort key, so the invoices have to be re-sorted on the product-no field
>input reptfile >sort product-no >output = input >xeq
Output = Input The output file overwrites the input file when the task is completed.
If the task is aborted, the input/output file may be lost.

38. Linking product descriptions to the invoices
>link input reptfile >link link prodfile >link output listfile temp >link xeq
Punctuation Either spaces or commas can be used between Suprlink command options. For example,
>link output listfile temp
is the same as
>link output listfile,temp

39. How does the new report look?
>input listfile >extract cust-account,name-last,name-first,purch-date,sales-total,product-no >extract product-desc >list standard,title "BC Sales over $100",& >>heading "Account# Name ",& >>"Purch Date Amount Product# and Description" >sort cust-account >sort purch-date >xeq
Account# Name Purch Date Amount Product# and Description
Melander John Makita 3/8" Var. Speed Drill
Melander John Makita 8 1/4" Circular Saw
Melander John Makita 1" Jigsaw
Nisbet Walley Makita 3/8" Var. Speed Drill
Nisbet Walley Makita 8 1/4" Circular Saw
IN=5, OUT=5. CPU-Sec=1. Wall-Sec=1.
The boss should be happy now. 
Wide listings The List command wraps at the configured width of the device or file to which it is writing. Usually this is 80 columns for the terminal or 132 columns for a printer. To override this default, use a File command for Suprlist.
Example If your terminal is in 132 column mode, to get the List command to print the full width of the terminal instead of the default 80 columns, use
:file suprlist=$stdlist;rec=-132

40. Suprlink Exercise 2
Add the product price to the list in Exercise 1 (page 31)
SUPPLIER- PRODUCT-N ON-HAND-QTY SUPPLIER-NAME Makita Canada Inc Makita Canada Inc Makita Canada Inc Makita Canada Inc Black & Decker ...

41. Specifying Link Fields
You can specify link fields:
+ input tranfile by cust-account
+ link custfile by account-num
Useful when files created with ,QUERY instead of ,LINK
Also useful for specifying a secondary link key:
+ link majors by ssn cmaj
If field names different in the input file:
+ link majors by ssn cmaj from ssn currmaj
By default, Suprlink assumes that the key-field to the Link-file is the same key-field specified for the Input-file. If the Link key-field is different from the Input key-field, use the BY-clause to specify the correct key-field:
+input customer {key-name is custnum}
+link sales by custno {new name for the same field}
You would also use the BY-clause if the Link file was created using the Suprtool Output,Query option instead of Output,Link.
Suppose that you are linking a master to a detail and the detail can have several entries for each master. Suprlink has an option that allows you to select which link record you want by matching a second key field in the master.
LINK filename BY primary-key secondary-key
It is possible that the second key field has a different name in the input file and the Link file. The FROM-clause lets you handle this case:
+link majors by ssn cmaj from ssn curmajor

42. Suprlink requirements
Suprlink requires enough disc space for the original database, each input file, the final output file, and hidden Sortscr files
Input and link files must be self-describing files
Input and link files must be sorted on the same key field
Link keys can be any type except a floating-point field type

43. Performance guidelines
Avoid using Suprlink if repeated sorting is required
Minimize record sizes by only selecting necessary fields
Minimize file sizes by only selecting required records

44. Summary Suprlink theory Input files versus link files
Implied record selection
Optional linking
Adding more information
Performance tips