HyperHit

By Paul Whittington, Susan Venn, Griffin Software, Inc.

HyperHIT: A HyperCard-Friendly Database Engine

[Paul Whittington holds a Bachelor of Science degree in Electrical Engineering and a Master of Management degree. He has been developing software since 1974, and started Griffin Software with Susan Venn in 1985, to develop software for the Macintosh.

HyperCard is a wonderful development environment for the Macintosh. It provides an easy way to take advantage of a graphical user interface, without having to become a Macintosh toolbox expert. Developing and modifying applications is easy, because HyperCard is interpreted. It directly supports buttons and menus. It introduces users to some concepts of object programming and encourages “non-programmers” to develop programs (after which they are programmers, whether they like it or not).

What HyperCard is not is a database. True, you can do some database functions with HyperCard. By using the card marking feature of HyperCard 2.0, you can select, sort, and print subsets of data. You can find information fairly quickly using HyperCard’s “Find” command. But you cannot easily develop different views of data, or manage non-homogeneous data without duplicating data and using multiple stacks.

For example, if you want to keep recipe cards in a stack, it is very straight-forward. You simply substitute a HyperCard card for an index card. Finding a recipe based on a style of cooking or a main ingredient is very simple. It is much faster and simpler than trying to do the same thing with index cards.

Now let’s complicate the application. Let’s say that you want to not only keep the recipes, but also keep track of your food inventory. You want to keep track of which foods were served when, in order to provide variety. You might also want to correlate this information with your diet and weight database. Finally, you want to have the application automatically print a shopping list on demand, based on current inventory levels and next week’s menus.

You say you can do this in HyperCard, no sweat. Good for you! I would fall back on a database program to do this. Better yet, I would use a database engine which uses HyperCard as a front-end.

There is no one database product that is the best choice for every application. Each has its strengths and weaknesses. Most database engines used with HyperCard were retrofitted to allow you to access them from HyperCard. The result is that the interface between HyperCard and the database can get awkward. On the other hand, they do greatly improve the data handling abilities of HyperCard.

HyperHIT Product Family

But one database engine gives you the ease of HyperCard and the power of databases. It is HyperHIT, which was developed by Griffin Software, Inc. and is published by SoftStream International, Inc. The HyperHIT product line actually contains three database products to meet different design needs; they are HyperHIT, HyperHIT-R and HyperHIT-N.

A Hierarchical Database: HyperHIT

HyperHIT is the original product. It is based on a hierarchical database model. The keys are text keys that can be up to 128 characters in length. You can have multiple sets of keys (keysets) and you can define the set of keys as being ASCII, International, number or date, to ensure that they will be sorted in the order that you want.

Each key can point to both a record and another keyset. By allowing the key to point to another keyset you can build a hierarchy of keys. Each key can point to only one keyset, but the keyset can have up to 32K keys pointing to it.

Records can be either text, sounds (snd ) or pictures (PICT). You do not define fields for the record, but maintain that within your scripts. This allows you to use HyperCard’s chunking expressions to delimit fields. Typically, returns are used as field delimiters so that line 1 is field 1, line 2 is field 2, etc.

HyperHIT has the advantage of being very flexible. Through your scripting you can create enormously complex databases with very complicated structures. It has the disadvantage of placing the burden of maintaining the database structure on the scripter. In other words, be prepared to do some thinking through and studying before you build a database with HyperHIT.

A Relational Database: HyperHIT-R

Since a lot of HyperCard users were willing to give up the flexibility of HyperHIT for an easier-to-use database, we developed another product called HyperHIT-R. This is based on the relational database model.

With HyperHIT-R, you define tables, or relations, by defining the fields that will exist in the relation. You can define multiple tables per database file (collection), to allow you to keep all related data in one physical file. As in HyperCard, all fields are actually stored as text fields, but by defining the field type, you indicate how comparisons are made on those fields. For example, if a field is defined as a number field, then “1.00” is equal to “1”; but if you define a field as a text field, then “1.00” is not equal to “1”. Fields in HyperHIT-R may be text, number, date or logic.

HyperHIT-R also maintains the field delimiters, which allows you to extract fields by name. In other words, it is easy to use. By the way, the HyperHIT-R package also includes a copy of HyperHIT. (We’ll tell you why at the end of this article.)

A major strength of HyperHIT-R is the way it supports complex search criteria, automatically optimizing on an indexed field if one exists. The following is an example of such a query:

 (HHIT Zip >= “60000” And HHIT Zip <= “69999”) and
 (HHIT LastName Starts_With cd fld lastInitial)

A Multi-User Database: HyperHIT-N

HyperHIT-N is the third member of the HyperHIT family. It is simply the network version of HyperHIT and HyperHIT-R. It consists of a server application and network versions of the XCMDs. All of the HyperHIT and HyperHIT-R commands are supported, with appropriate record-locking extensions. The HyperHIT Server can run in the background under MultiFinder and, unless you have an extremely old Mac Plus, you can run a HyperCard client in the foreground at the same time.

Let Us Show You How This Works

We recently discussed an application with a staff member at a city zoo. He wanted to develop a database that would let zoo visitors request facts about various animals such as their habitat, family, markings, etc., and be able to do look-ups based on these attributes.

While we will not attempt to completely cover all of the application design, we will try to show how such an application can be developed using the HyperHIT database engine.

We want to keep the following information about each animal:

Field Type Contents

Name Text Common name of the animal.

Species Text Latin species name.

Genus Text Latin genus name.

Family Text Latin family name.

Habitat Text Environment where animal is normally found.

Continent Text Region of the world where animal is found.

Markings Text Colorings unique to the species.

Diet Text Normal diet for animal.

Relatives Text Return separated list of related species.

Let’s jump right into some scripting. The following script is all that is needed to create the initial database:

--1

on InitDatabase
    global db
    Put “HyperHIT” into db
    CreateCollection “db”
    CreateRelation “db”,”Animals”
    CreateField “db”,”Animals”,”Name”,”Text”
    CreateField “db”,”Animals”,”Species”,”Text”
    CreateField “db”,”Animals”,”Genus”,”Text”
    CreateField “db”,”Animals”,”Family”,”Text”
    CreateField “db”,”Animals”,”Habitat”,”Text”    
    CreateField “db”,”Animals”,”Continent”,”Text”
    CreateField “db”,”Animals”,”Markings”,”Text”
    CreateField “db”,”Animals”,”Diet”,”Text”
    CreateField “db”,”Animals”,”Relatives”,”Text”
    CreateIndex “db”,”Animals”,”Name”,20
    CreateIndex “db”,”Animals”,”Family”,20
end InitDatabase

With every HyperHIT database you must declare a global variable and initialize it with the word “HyperHIT”. HyperHIT uses this global variable to keep all the data it needs to manage the database. Since HyperCard expects only text to be kept in a variable, HyperHIT stores a handle to the actual data block in this global variable.

Global Variables

At this point we need to explain about HyperCard, global variables and XCMDs. Those of you who have written handlers in HyperTalk know that HyperCard treats parameters as local variables. That is, they exist within the handler, but do not exist once the handler is completed. The same is true of XCMDs. Any parameters that are passed to the XCMD are disposed of when the XCMD completes. So you cannot pass a variable to an XCMD and have it change the value of that variable, as you can in other languages.

An XCMD can, however, get or change the value of a global variable if it knows the name of the global variable. This means that we can pass a variable to an XCMD and have it change the variable’s value, by passing the name of the global variable to the XCMD. Kind of convoluted, but it works.

This is the reason that all the HyperHIT commands require the name of a global variable as the first parameter. It would have been easy for us to hard-code in a global variable name, but then you would run the risk of using a global name that someone else has employed for their XCMD. Furthermore, HyperHIT allows you to open more than one database file at a time, so you would still be required to pass some parameter to indicate which database the command should apply to.

Defining the Database

With HyperHIT-R you define a relation in four steps. First you create a collection. The collection is simply the physical file where you will keep your data. You can put all the relations you want into a single collection, or you can keep each relation in a separate collection; the choice is yours.

The second step is to define the relation. The simplest way to think of a relation is as a table. Defining the relation means giving the table a name. This initializes some data structures and reserves the relation name.

The third step is to define the fields in the relation. In terms of a table, this is defining the columns of the table. Each field must be given a field type. In the example above, all of the fields are of type text. Since this is the most likely type of field, this is also the default. So for all of the fields above, the last parameter could have been left off.

The fourth step is to define any indexes. These are used to optimize searches. You define an index by telling HyperHIT which field is to be indexed. If the field is a text field, you also want to tell HyperHIT how long the key is. HyperHIT uses fixed length keys. While this is not the most efficient method in terms of disk storage, it is the most efficient in terms of speed. The default key size is 128 characters for text fields. As a rule-of-thumb, 20 is usually sufficient.

Please note that the field and record size are allowed to be whatever size the data requires. Only indexes are fixed length.

The length of the keys does not affect the evaluation for matching the search criteria, since HyperHIT will still read in the record and evaluate each field based on its total contents. Using the keys, however, can limit the number of records that need to be evaluated.

Now Let’s See Some Real HyperCard Power

Let’s use the database we have set up and do some queries. (Assume at this point that the data has already been entered.) In HyperCard we have defined a scrolling field containing the Latin names of all the animal families. This card is shown in figure 1.

Figure 1. Card “Family Names”

To create a query we could use a script for that field that looks like:

--3

on mouseUp
    Put clickText() into Family
    Put “HHIT Family = “ & quote & family & Quote into criteria
    SetSelection “db”,”Animals”,”Name”,criteria
    SortSelection “db”,”Animals”,”Name,A”
    Put SelectionToVar(“db”,”Animals”) into fld “Animal Names”
    Put CountSelection(“db”,”Animals”) into fld “Count”
end mouseUp

This builds a selection containing all of the animals in the family that was selected, sorts the animal names in alphabetical order and puts the names into a background field named “Animal Names” and the number of records matched into the field named “Count”.

An example of this is shown in figure 2. In this case the family name chosen was “Felidae”. The animals listed are all members of the cat family.

Figure 2. Card “Animal Names”

Selections

A selection can be thought of as a read-only table. You determine which fields are put into the table. You can sort the records in the table. You can even export the table to a file. You cannot, however, change any of the values in any of the fields in the selection.

Since the number of animals in a family is quite large, it is possible to narrow down the search by putting additional criteria on the selection. This is accomplished through the TrimSelection command. You can do this by having a button with the following script:

--3

on mouseUp
    Ask “In what type of habitat is this animal normally found?”
    If it is empty then exit to HyperCard
    Put “HHIT Habitat = “ & quote & it & quote into criteria
    TrimSelection “db”,”Animals”,criteria
    Put SelectionToVar(“db”,”Animals”) into fld “Animal Names”
    Put CountSelection(“db”,”Animals”) into fld “Count”
end mouseUp

If the user selects “Felidae” as the family and “jungle” as the habitat, the result will be a list of all the members of the cat family that live in a jungle.

The list can be further reduced by having a button with the following script:

--4

on mouseUp
    Ask “What markings does this animal have?”
    If it is empty then exit to HyperCard
    Put “HHIT Markings contains “ & quote & it & quote into criteria
    TrimSelection “db”,”Animals”,criteria
    Put SelectionToVar(“db”,”Animals”) into fld “Animal Names”
    Put CountSelection(“db”,”Animals”) into fld “Count”
end mouseUp

If, for example, the user enters “Stripes”, the result will be a list of all cats who live in the jungle and have stripes.

As you can see, this has very flexible and powerful searching capabilities. But, as they say on late night television, stay tuned - there’s more. You can add to a selection by using the AppendSelection command. For example, If you wanted to now add all other jungle animals in Africa to the list that you have already selected you could use the following script:

--5

on AddToSelection
    Put “HHIT Habitat = “ & quote & “jungle” & quote & ¬
    “ and HHIT Continent = “ & quote & “Africa” & quote into criteria
    AppendSelection “db”,”Animals”,criteria
    SortSelection “db”,”Animals”,”Name,A”
    Put SelectionToVar(“db”,”Animals”) into fld “Animal Names”
    Put CountSelection(“db”,”Animals”) into fld “Count”
end AddToSelection

A quick note here about selection criteria. In all of the above examples the criteria matched a HyperHIT field against a literal in quotes. While this makes the examples nice and clear, it is not a restriction of HyperHIT-R. The rule is that one of the operands must be a HyperHIT field. The other can be a HyperHIT field, a global variable, a card field, or a background field. This provides the flexibility for creating your search criteria.

Once you have selected the list of animals, how do you retrieve the record for the specific one that you are interested in? I’m glad you asked. One way is the following script for the background field named “Animal Names”.

--6

on mouseUp
    global recNum
    select clickLine()
    Put word 2 of clickLine() into recNum
end mouseUp

Word 2 of clickLine() is the actual line number that was clicked on. We will save the line number off into the global variable recNum. This line also corresponds with the row in the selection that this line represents.

Now put the following script in the button named “Show Me This Animal”.

--7

on mouseUp
    global rec, recNum
    Put GetSelectionRecord(“db”,”Animals”,recNum) into rec
    Go to card “Individual Animal”
    Put “Name,Species,Genus,Family,Habitat,”¬
    & “Continent,Markings,Diet,Relatives” into FieldNames
    FillHCFields rec,FieldNames,FieldNames
end mouseUp

GetSelectionRecord retrieves the record that corresponds to row recNum in the selection. The card named “Individual Animal” has nine background fields on it. These field names are the same as the field names in the record. This is not a requirement, but it makes the scripting easier to follow.

The variable “FieldNames” contains a comma-separated list of the names of the fields. FillHCFields takes the fields from the record and puts them into the HyperCard fields using the two “FieldNames” parameters to map the HyperHIT fields to the HyperCard fields.

Figure 3 shows what happens when the animal “Tiger” is selected and the button “Show Me This Animal” is clicked.

Figure 3. Card “Individual Animal”

Notice in the preceding script that rec is declared as a global variable. There is no requirement that records be put into global variables. This was done here so that the record would be available in case we want to make modifications to it. Say, for example, that we wanted to change the field “Continent” to South America. The follow script segment accomplishes that:

--8

On ChangeContinent
    global rec
    Put SetRecordField(rec,”Continent”,”South America”) into rec
    UpdateRecord rec
end ChangeContinent

Remember that parameters are considered local variables to XCMDs. Since we want to change a variable, HyperHIT gets around this restriction by making SetRecordField an XFCN and returning the modified record as the result. By putting this result back into the original variable, we know that rec will contain the modified record.

Notice that UpdateRecord does not require that you name the global variable for the database, or the name of the relation the record is from. This is because that information is embedded in the record itself.

One feature that I haven’t talked about yet are result codes. HyperHIT-R returns all error messages to a global variable named “HHITErrorCode”. Item one of the returned value indicates the severity of the error as either “no error”, “warning”, or “error”. Item 2 of the returned value has a text explanation of the problem. For example, if you try to put a value into a field that doesn’t exist, you get an error “Error,Invalid field name”.

To simplify the individual scripts, many scripters put a handler similar to the following into their stack:

--9

on ErrorCheck
    global HHITErrorCode
    If item 1 of HHITErrorCode   “no error” then
        Answer (item 2 of HHITErrorCode)
        exit to HyperCard
    end If
end ErrorCheck

Then, after each HyperHIT-R command, they invoke the ErrorCheck handler.

Add Pictures and Sound

Finally, let’s add one more dimension to the zoo application. Let’s say that in addition to the text information that we currently display, we also want to display a picture of the animal and, optionally, play a sound of the animal.

We can do that by using HyperHIT in conjunction with HyperHIT-R. (And that is why we give you both products. Sometimes you want to use them together.) First add two number fields to the “Animals” relation using the following commands:

--10

 CreateField “db”,”Animals”,”Picture”,”number”
 CreateField “db”,”Animals”,”Call”,”number”

Then store each picture and sound in a HyperHIT file using an arbitrary number as the key. Store this key into the “Picture” and “Call” fields of the animal’s record. Then add the following scripts to the two buttons on the card:

--11

button “Show my picture”
on mouseUp
    global rec, PictVar
    Put GetRecordField(rec,”Picture”) into PicKey
    Get GoToMarker(“HyperHITDB”,”Pictures”)
    Put FindAt(“HyperHITDB”,PicKey) into temp
    If item 1 of temp   0 then
        Answer “No picture for this animal”
    else
        Put “HyperHIT” into PictVar
        Get ReadPict(“HyperHITDB”,”PictVar”)
        Get DisplayPict(“PictVar”)
        Get ClearPict(“PictVar”)
    end If
end mouseUp

button “Listen to me”
on mouseUp
    global rec, SoundVar
    Put GetRecordField(rec,”Call”) into SoundKey
    Get GoToMarker(“HyperHITDB”,”Sound”)
    Put FindAt(“HyperHITDB”,SoundKey) into temp
    If item 1 of temp   0 then
        Answer “No sound for this animal”
    else
        Put “HyperHIT” into SoundVar
        Get ReadSound(“HyperHITDB”,”SoundVar”)
        Get PlaySound(“SoundVar”)
        Get ClearSound(“SoundVar”)
    end If
end mouseUp

Want to Know More? Here’s How

This is a very brief introduction to HyperHIT. We hope that it whets your appetite to find out more. We haven’t touched on some of the features, like the import command that brings your data in from existing sources, and the export commands that let you take data from your databases to other applications.

HyperHIT products are compatible with HyperCard 2.0 and with SuperCard 1.5.

A HyperHIT-R demo and syntax stacks for the command sets are available. Furthermore, we are always ready to answer questions of a technical nature if you contact us on AppleLink at D1743, America Online at PaulW34, or CompuServe at 73557,505.

For information about purchasing any of the HyperHIT products, contact: Softstream International, 19 White Chapel Dr., Mt. Laurel, NJ 08054. (800)866-1187

We want to thank MacTutor for giving us this forum to present HyperHIT.

© 1991 Griffin Software, Inc.