******************************************************************
* *
* Stanford Data Center *
* Stanford University *
* Stanford, Ca. 94305 *
* *
* (c)Copyright 1994 by the Board of Trustees of the *
* Leland Stanford Junior University *
* All rights reserved *
* Printed in the United States of America *
* *
******************************************************************
SPIRES (TM) is a trademark of Stanford University.
As computing costs drop and more non-specialists discover the rich resources of the computer, the need for easier-to-use information management systems increases. People of many different technical and non-technical backgrounds increasingly want to use the computer to store, retrieve and manipulate their data. The types of data vary from highly structured data, such as statistics and laboratory measurements, to unstructured data such as bibliographies, address files and even memos and letters. A good data base management system, that is, a computer program that supervises this data for you, can be used to search for, arrange, analyze, display and print data much faster and more accurately than you can. A better one lets you do these tasks fairly easily, without your having to spend a great deal of time learning how.
SPIRES, the Stanford Public Information REtrieval System, is a data base management system that allows you to create, own and manage your own collections of data, known as data bases. You may do this completely on your own; no one else needs to help you with your data base application, if you so choose. Unlike some data base management systems, SPIRES is very generalized: it is designed to handle all types of data efficiently, from compact, numerical values found in administrative and scientific data to lengthy, textual values such as bibliographic data.
In SPIRES, a data base application (that is, the file or files of data, as well as the programs and tools used with it) may consist of several parts, depending on what pieces of the SPIRES system (and possibly other programs on the computer as well) you want to use. The basis for any SPIRES application is a "SPIRES file", in which your data is stored.
Some people who build their own SPIRES files do so by learning at least part of the SPIRES file definition language. This very extensive and flexible language is the subject of the very extensive manual "SPIRES File Definition", a 400-page document. That manual provides not only detailed instructions on all facets of creating a SPIRES file but also technical explanations of how the parts of the file work together with SPIRES "behind the screens" to be a useful data base. Though most of the material therein is valuable to SPIRES programmers, it is more than most users need for constructing their own simple applications.
Many users want such straightforward SPIRES files that they need only a small, easily determined subset of the features available in SPIRES. People needing "personalized data bases" -- that is, a data base used solely by the owner -- and other small data-filing and record-management data bases usually have many similar requirements for their applications. The File Definer, a SPIRES subsystem, is designed in part to simplify the initial construction of such data bases. It reduces the number of technical concepts and terms necessary to create a "file definition", which is a description of your file in the specialized file definition language.
Using a small group of terms and concepts, you describe the desired characteristics of your file to the File Definer, which in turn makes some assumptions about technical details and generates a file definition. By using the File Definer in conjunction with this primer, you should be able to create and begin using your first file within a few hours.
This primer is one of a series of primers on the SPIRES system. It will explain how you can create your own file, using the File Definer subsystem in SPIRES, and how your file can be used: how to add, update and remove data, and how to examine it. The files you design by following this manual should be relatively small -- certainly no larger than about 1000 data records. When the file is larger than that, you should read other manuals or see your SPIRES consultant, because you will probably want to be more concerned about storage efficiency than will the owner of a smaller data base. Such concerns may not drastically alter your file design, but they will probably influence it to some degree. When you are investing much time and effort in your data, it may be worth spending some extra time designing the file more carefully.
You do not need to know anything at all about SPIRES before you read this manual. However, you should know how to logon to one of the IBM computers operated by I.T.S. and how to issue basic WYLBUR commands. (See the I.T.S. document "WYLBUR Overview" if you are not familiar with WYLBUR.) Whether or not you have a specific application for SPIRES in mind as you read this primer, you may find the document more useful if you can invent a small data base, such as an address file, and go through the process of creating it as you read. Sitting at a terminal and issuing the commands discussed will help reinforce the topics as they are covered; doing so is highly recommended.
Naturally a primer that condenses material from several other reference manuals cannot cover all the material thoroughly. However, it should serve as a springboard for you into various areas of SPIRES, demonstrating and describing, if not teaching, its most useful and important capabilities. The other manuals in the primer series are probably the best "next step" for readers of this document. If you want your application to have capabilities not discussed here, you should read further and/or contact your SPIRES consultant. Cross references to other SPIRES manuals appear throughout this document, pointing to locations for further information about the current topic. Those manuals are discussed in the final chapter, and an annotated list of all SPIRES documents appears as an appendix.
Cross references may also suggest that you issue the SPIRES command "EXPLAIN term", where "term" is a specific concept or term in SPIRES. For example, issue the command EXPLAIN SPIRES CONSULTING for information about how to contact your SPIRES consultant. The EXPLAIN facility, described in the first chapter of this manual, is a powerful tool that provides detailed explanations extracted from various SPIRES documents on the particular subject requested. It serves as a valuable master index to SPIRES documentation, helping you find the information you need on a specific topic.
In this primer, examples of sessions are shown with SPIRES prompts and messages printed in standard emphasis and preceded by a hyphen, while the commands you would type are displayed in boldface. (Although our sessions mostly use lowercase, you may use upper- or lowercase interchangeably when you are actually using SPIRES). For example:
-OK to clear? ok
Here SPIRES prompts you "-OK to clear?" and you type "ok".
In formal command syntax descriptions, uppercase letters denote command verbs or other command elements to be entered exactly as shown; a value for lowercase terms and characters must be supplied by you. For example:
SELECT subfile-name
To use this particular command, you type the command verb "SELECT" with the name of the desired subfile, for instance, "Restaurant":
-> select restaurant
where "->" is the prompt from SPIRES.
Brackets ([]) denote optional parts of a command's syntax. Braces ({ }) indicate that you must specify one (and only one) of the alternatives within the braces. Within the braces or brackets, a vertical line (|) separates possible choices. Neither brackets nor braces are to be typed as part of the command. For example:
TYPE [PAUSE|KEEP]
could be entered as
TYPE or TYPE PAUSE or TYPE KEEP
depending on whether you want one of the options. Here is an example of braces:
DEQUEUE {record-key-value|ALL}
This command must be entered either as
DEQUEUE record-key-value
where you supply the "record-key-value", or as
DEQUEUE ALL
with the choice again governed by the desired result.
The first requirement when you want to create a SPIRES application is that you must have or anticipate having some data to place in a file. That being said, there are many considerations to be made. For example, why should your data be placed in a SPIRES file? What features does SPIRES have that will be useful to you when you use your data base? How will you use your data base? What output products (reports, labels, etc.) do you need to derive from your data base? Seeing the capabilities of SPIRES and the ways in which other SPIRES file owners use their files may help you answer these questions.
The first chapter of this primer will introduce you to the powerful index searching capabilities of SPIRES and the ways in which data records are displayed to the user. The second chapter will show you how to add, update and remove records from the data base. These first two chapters present the type of day-to-day activities for which most simple SPIRES data bases are used. Besides helping you determine whether your data would be appropriately handled in these situations, these chapters also introduce file design considerations in terms of how they affect the searching, displaying and updating of the data.
Once you have a basic idea of the strengths of the SPIRES searching language and of the way records are modified, you will have a better sense of what a SPIRES data base is and how it is used. In Chapter 3, you are presented with a series of questions to help you determine if your data would make a good SPIRES data base and, if so, how the data base should be designed. Then, in Chapters 4 and 5, you create your file definition using the File Definer subsystem. In Chapter 4, the specific concepts of creating a file definition will be introduced, including the File Definer language that encapsulates many file definition concepts and terms. Chapter 5 introduces some slightly more advanced capabilities of files and file definitions; it may be considered optional reading.
Chapter 6 tells you how to create an empty SPIRES file from your file definition. In addition, that chapter describes procedures to follow when you want to make changes to your file definition after you have used your file for awhile. (An appendix to this primer provides a checklist summary of the procedure for creating a SPIRES file as explained in Chapters 3 through 6.)
As you will learn in the early chapters of this manual, SPIRES handles record updates specially. When records are added, updated or removed, they do not immediately affect the records already stored in the data base. Not until the file owner permits it will the modified records be merged with or replace the other records nor will the indexes be updated to reflect the changes. [See II.2.] When this happens, that is, when the file is "processed", another program called SPIBILD does the work. Its functions are explained in Chapter 7.
Chapter 8 discusses Global FOR, a collection of commands that allow you to handle groups of records in your data base based on non-indexed criteria and/or the records' status in the data base (the newly added, non-indexed records, for example).
Chapter 9 describes a number of common situations and minor problems that the file owner may confront, along with suggested solutions. Included is an explanation of what to do when you no longer need your SPIRES file at all. The final chapter, Chapter 10, describes many other capabilities of SPIRES not covered in this primer and refers you to additional documentation where you can read more about them. A complete list of the SPIRES documentation appears as an appendix.
Two notable features of the index at the end of the primer are the complete list of commands discussed in the text (see entries under "command") and the list of tasks you might be trying to accomplish (see entries under "tasks"). For example, if you have a task you want to do in SPIRES but you don't remember the name of the command or procedure to do it, check the "tasks" entries in the index.
This primer will not teach you everything you need to know about owning any SPIRES file, because every owner has different needs, and SPIRES was designed as a generalized system so that each owner could get the precise capabilities needed. However, the most common and most important facets of application design, creation and ownership are covered. If you need more help, you should contact your SPIRES consultant. Your SPIRES consultant is your best source for advice on your specific application.
To demonstrate that creating and using a SPIRES file is relatively simple, below are two SPIRES sessions. You probably will not understand all aspects of these two examples at this point. (If you do, you probably should be reading more advanced manuals, such as "SPIRES File Definition" or "SPIRES File Definer".) However, you should be able to follow in a general way the activities described. In the first session, you will create a SPIRES file. In the second, you will use it to add a record and display it. The file being created will hold data for a bibliography.
(1) COMMAND> spires
-Welcome to SPIRES ... if in trouble, try HELP
(2) -> enter file definer
* ENTERING FILE DEFINER
(3) :-> collect
1. > subfile bibliography
2. > element title/ occurrence = 1/ index/ word
3. > element author/ name/ index
4. > element journal/ occurrence = 1
5. > explain The JOURNAL element contains all information
6. > explain needed to locate the article: journal name,
7. > explain volume, date and page number.
8. > element abstract/ occurrence = 1
9. > element subject/ index/ word
10. > explain The SUBJECT element should be a word or short
11. > explain phrase identifying the contents of the article.
12. > element comments
13. > end
(4) 14. > *** <-- ATTN/BREAK key is pressed.
(5) :-> input active
* 1. Input> subfile bibliography
* 2. Input> element title/ occurrence = 1/ index/ word
* 3. Input> element author/ name/ index
* 4. Input> element journal/ occurrence = 1
* 5. Input> explain The JOURNAL element contains all information
* 6. Input> explain needed to locate the article: journal name,
* 7. Input> explain volume, date and page number.
* 8. Input> element abstract/ occurrence = 1
* 9. Input> element subject/ index/ word
* 10. Input> explain The SUBJECT element should be a word or short
* 11. Input> explain phrase identifying the contents of the article.
* 12. Input> element comments
* 13. Input> end
(6) :-> generate
(7) -OK to clear? yes
(8) :-> list first
1. FILE = GQ.JNK.BIBLIOGRAPHY;
(9) :-> select filedef
(10) :-> add
(11) :-> compile gq.jnk.bibliography
-File Definition Compiled
(12) -> exit
-Return to WYLBUR
COMMAND>
Here is a brief explanation of the above session: You issue the command SPIRES to enter the SPIRES system (1). (The numbers in parentheses here refer to the parenthesized numbers at the left in the above example.) Once you receive the SPIRES prompt (->), you "enter" the SPIRES subsystem File Definer (2). There, you collect a description of your file characteristics (3) and then tell the File Definer you want to "input" the description from your active file (5). File Definer reads your active file, displaying each line as it is read. Note that you begin each line of the input with a keyword, such as SUBFILE or ELEMENT, that identifies what the input line is describing. For example, the "elements" are the individual pieces of information in the data records; each bibliographic citation will probably have a title element, an author element, an abstract element, and so on.
Once all the input is entered, you tell the File Definer to "generate" a SPIRES file definition, which is placed in your active file (7). You then "add" your new file definition to the data base called FILEDEF that contains SPIRES file definitions (9 and 10), and then "compile" the file definition (11).
Once you have created the file, you may add and display records:
(1) COMMAND> spires
-Welcome to SPIRES ... if in trouble, try HELP
(2) -> select bibliography
(3) -> show elements
Subfile BIBLIOGRAPHY
REC01
TITLE
AUTHOR
JOURNAL
ABSTRACT
SUBJECT
COMMENTS
(4) -> set format $prompt
(5) -> add
(6) : TITLE Diplomacy: Lying in State?
(7) : AUTHOR(1) Alexander Kissinger
(8) : AUTHOR(2) <-- Return is pressed to skip this element
(9) : JOURNAL ? <-- entered to request more information
The JOURNAL element contains all information
needed to locate the article: journal name,
volume, date and page number.
(10) : JOURNAL U.S. and World Affairs
(11) : ABSTRACT Foreign policy discussed in one-syllable words.
(12) : SUBJECT(1) foreign policy
(13) : SUBJECT(2) monosyllabic
(14) : SUBJECT(3) <-- Return is pressed to skip this element
(15) : COMMENTS(1) <-- Return is pressed to skip this element
-Added record 1
(16) -> display 1
REC01 1
TITLE Diplomacy: Lying in State?
AUTHOR(1) Kissinger, Alexander
JOURNAL U.S. and World Affairs
ABSTRACT Foreign policy discussed in one-syllable words.
SUBJECT(1) foreign policy
SUBJECT(2) monosyllabic
->
After calling SPIRES (1), you "select" the subfile of data you want to use (2). To add a record to the subfile, you may "set" a special SPIRES format called $PROMPT (4) and then issue the ADD command (5). The $PROMPT format prompts you for element values for the record you wish to add, indicated by the lines that begin with a colon (:) (6-15). Shown above, the element name prompts are on the left, and the values you enter are shown on the right. Note that the elements that were described in the File Definer input in the first session with "occurrence = 1" are prompted only once -- TITLE and JOURNAL, for instance (6,9). For the others, which may have multiple values in a single record, the format prompted you until you entered only a carriage return to stop prompting for that element (12-15). Note too that when you were not sure what to enter for the JOURNAL element, by responding with a question mark you received the explanation entered in the File Definer input (9); then you were reprompted for that element (10). The COMMENTS element was skipped by not providing a value (15) -- like all the other elements here, it is optional, and no value need be given for it. Once all the data was input, SPIRES added the record to the subfile. Then you issued a DISPLAY command to examine the record just added (16).
This primer will take you step by step through the material shown in the examples, as well as through material that shows other capabilities and facilities. Each of these commands, terms and concepts will be discussed. For the purpose of illustrating the concepts and facilities, throughout the rest of this manual we will create and use a data base of information about blood donors.
This chapter will introduce you to SPIRES from the perspective of the "searcher", the person wanting to use a SPIRES data base to find, examine and display information. It describes the basic concepts of a SPIRES file and subfile, and presents the main commands used to search a pre-existing subfile. In addition, several different ways of displaying the retrieved data are discussed.
The material presented here is a condensed version of the material in the SPIRES primer "A Guide to Searching", which in turn is derived from Parts A, B and C of the SPIRES reference manual "Searching and Updating". More information about the material in this chapter can be found in those manuals.
Before you can access a SPIRES data base, you must enter the SPIRES environment. After logging on to the computer, you issue the command SPIRES:
COMMAND> spires -Welcome to SPIRES ... if in trouble, try HELP ->
You will receive a welcoming message from SPIRES that will end with the SPIRES prompt "->" or "-?", depending on whether you have SET UPPER in WYLBUR. [The SPIRES command supersedes the CALL SPIRES command, which may still be issued, if desired.] (Case is almost never significant in SPIRES commands, though it may be, as far as your data is concerned.) When it issues the prompt, SPIRES is ready for your commands. While in SPIRES, you may issue any SPIRES, WYLBUR, ORVYL, MILTEN or JES command. If the command is not a SPIRES command, SPIRES will pass it to the appropriate system for processing.
When you are ready to leave SPIRES, issue the EXIT command and you will return to WYLBUR's control.
-> exit -Exiting SPIRES COMMAND>
The SPIRES and EXIT commands are ORVYL commands, telling ORVYL how you want to use one of its programs -- SPIRES in this case.
The welcoming message suggests that you issue the SPIRES command HELP if you are "in trouble". SPIRES will then make suggestions about what you can do, depending on what you have already done. The HELP command is usually a good place to start when you are not sure what to do next in SPIRES.
Another online aid in SPIRES is the EXPLAIN command. The HELP command often suggests that you issue an EXPLAIN command to give you further information about a particular topic. Approximately 3,000 explanations and descriptions of SPIRES commands, codes, subfiles and features are available. Whenever SPIRES types a term or phrase you do not understand, you may issue the EXPLAIN command, using the following syntax:
EXPLAIN term
where "term" is the item you want explained. SPIRES then displays pertinent sections from SPIRES documentation to define and describe the command. Examples and syntax are often shown as well.
The responses that SPIRES gives to the HELP or EXPLAIN commands can be placed in your active file if desired. Just precede the EXPLAIN command with the IN ACTIVE prefix:
-> in active explain spires consulting
The resulting information can be printed or saved using WYLBUR commands. (If your active file is not empty when you issue the command, SPIRES will prompt "OK to clear?") Many other SPIRES commands, including almost all SPIRES commands that begin with the word SHOW, can be prefixed with IN ACTIVE; many of these commands will be discussed in this primer. Other options available with the prefix are discussed in detail in "SPIRES Searching and Updating".
After you have issued a command with the IN ACTIVE prefix, SPIRES may begin listing your new active file. If you do not want to look at it then, press the ATTN/BREAK key to stop the listing. Since the material was placed there by SPIRES before the listing began, stopping the display will not affect your active file. If you do not want SPIRES to list your active file in such cases, issue the SPIRES command SET NOLIST during your session. Because listing the entire active file each time it is changed would mean this document would be about twenty pages longer, we will assume that SET NOLIST is always in effect for us. [See IX.6 to learn how to SET NOLIST automatically each time you enter SPIRES.]
Suppose that you have a file cabinet with several drawers, each drawer containing folders with similar information. For example, the file cabinet contains folders relating to blood donations. The top drawer has a folder for each blood donor, in which each folder has the donor's name, address, donation history, and so forth. Each folder has a tag at the top that identifies the folder; the tag is, say, a serial number and each folder has a different number. The folders are kept in numerical order in the file cabinet drawer.
In another drawer of the file cabinet is another set of folders. Each folder here has a city's name for a tag, and the folders are filed in alphabetical order by city. Inside each "city" folder is a list of numbers, corresponding to the tags of folders in the first drawer. For instance, the folder with PALO ALTO as the tag might have the number 27 inside, indicating that record 27 in the first drawer represents a donor living in Palo Alto.
When you use the file cabinet and want to find all the folders of donors living in Palo Alto, there are two approaches you can take. The less efficient method is to look at every donor folder in the top drawer individually. The faster method is to find the folder in the "city" drawer for that particular city and then use the information there to pull folders from the "donors" drawer.
A SPIRES file is like the file cabinet described. It is the file cabinet that holds the data of your data base. Groups of drawers in the file cabinet that relate to a particular "folder-type", such as the donors folders, are called a "subfile". Taken together, the donor folder drawer and the city folder drawer are analogous to a SPIRES subfile. A file may contain more than one subfile in SPIRES, though many files contain only one. Generally only the file owner deals directly with the file as a whole; the data is most often accessed through a subfile, both by the file owner and by any one else using the data base for searching and updating purposes. Thus, most SPIRES users will only see the data in a file through a subfile.
Most SPIRES subfiles consist of two kinds of data "records", which are analogous to the individual folders in a file drawer: "goal records" and "index records". Goal records are what you are searching for -- they are your goal in a search. In our example subfile we will be searching for information about blood donors. Similarly, in a bibliographic subfile, the goal records might consist of the information in a card catalog about a book.
To find goal records containing particular information, you can use index records. Just as you looked in the "city" drawer of the file cabinet for references ("pointers") to folders of donors living in a particular city, SPIRES looks in a subfile's indexes for pointers referring to goal records containing particular information. SPIRES subfiles usually have more than one index, referencing different types of information separately. For example, our blood donors will be indexed by their names, blood types, total amounts donated, and so forth.
To search a subfile, you must first tell SPIRES which subfile you want to search, then issue search requests and display the results.
The remainder of this chapter will acquaint you with some of these basic searching commands in SPIRES. You will see how a SPIRES data base looks to and is used by a searcher; this will be useful when you design a data base in the next chapter. The greatest strength of SPIRES is in its searching facilities, so it is important to incorporate into the data base design the ways in which you expect to use them for searching your subfile.
To do any searching, you must first choose a SPIRES subfile. When you know which SPIRES subfile you want to search, use the SELECT command:
SELECT subfile-name
For example, to use the subfile of blood donors we will create, you would type:
-> select blood donors ->
where the returned "->" prompt shows that the subfile is ready to use. Once you have selected a subfile, many other SPIRES commands specifically relating to a selected subfile become available. For example, if you now issue the SHOW SUBFILE SIZE command, SPIRES will tell you how many goal records are in the selected subfile.
If you cannot remember the name of a subfile or if you just want to see a list of all the subfiles available to you for searching, issue the command SHOW SUBFILES. When you have found the desired subfile name, issue the SELECT command as described above to tell SPIRES which subfile you want to use.
The blood donors subfile we will be using does really exist as a public subfile, although the data in it is fictitious. You are invited to use it to practice most of the commands described in this document. (Only those commands that would destroy data or "process the file", described in later chapters, are prohibited.) Other public subfiles are also designed for you to practice searching: RESTAURANT, DRINKS and RECIPES. You are welcome to search any subfile that is a public subfile, as noted in the listing, for the purpose either of finding particular information or practicing the SPIRES commands you will learn here. For more information about the contents of a particular subfile, try issuing the command "SHOW SUBFILE DESCRIPTION subfile-name". Subfile descriptions are written by the file owner, and, though they are not required, owners of public subfiles are urged to provide them. You will learn how to provide such an explanation for your subfiles later. [See V.2.4.]
To begin a search after selecting a subfile, you must tell SPIRES three things: first, that you want SPIRES to search an index; second, what index you want SPIRES to use in the search; and third, what values you want SPIRES to find in that index. All that is done in one command, called a "search request". When you issue a search request, SPIRES scans the index or indexes you name for values that match the criteria you specify in the search request; SPIRES then reports the number of goal records meeting those criteria. These retrieved goal records are the "search result".
Before issuing a search request, you need to know what indexes are available for searching. Once you have selected a subfile, you can issue the command SHOW INDEXES. For example,
-> select blood donors -> show indexes Goal Records: DONOR Simple Index: DONOR.NAME, NAM, NAME Simple Index: CIT, CITY Simple Index: CAL, CAN, CAN.BE.CALLED Simple Index: BLD, BLO, BLOOD, BLOOD.TYPE Simple Index: DAT, DATE, DATE.GIVEN Simple Index: LOC, LOCATION, WHERE.GIVEN Simple Index: PINTS, PINTS.GIVEN, TOT, TOTAL.PINTS
The list indicates all the different indexes you can use to search the subfile. Any of the index names, such as DONOR.NAME, or their indicated aliases, such as NAM or NAME, can be used in a search request.
The BLOOD DONORS subfile thus has goal records that contain information about a DONOR and index records for the donor's name, dates and locations where the donor has given blood, and so forth. The index names usually suggest the type of information that is indexed. If you are not sure what types of values might appear in a particular index, you can issue the BROWSE command:
BROWSE index-name
For example, to find out what type of values are in the BLOOD.TYPE index:
-> browse blood.type A+ A- AB+ AB- B+ B- O+ O-
The BROWSE command shows sample values (in the above case, all the values) from the index. Here you can see that the values in the index are blood types, such as A+ (A-positive). The values shown by the BROWSE command can help you formulate a useful search request.
The BROWSE command can be used to examine all the values in an index or the values at a particular point in an index. EXPLAIN BROWSE COMMAND for details.
Simple search requests consist of two parts: the SPIRES command verb FIND and a "search expression". The search expression states a criterion to be used in selecting goal records for the search result. It consists of three parts: the name of the index to be searched, a "relational operator" [See I.4.2.] such as an equals sign, and a search value. For example, to find donors with a blood type of A+, you would type:
-> select blood donors -> find blood.type = a+ -Result: 153 DONORS ->
In the search request, BLOOD.TYPE is the name of an index in the subfile, "=" is the relational operator, and "A+" is the search value. It is the search value that is compared against the values in the specified index. (Note that it usually does not matter whether you use upper, lower or a mixture of cases in a search request.)
Here is the syntax of a search request:
FIND search-expression
which means
FIND index-name relational-operator search-value
When you issue a search request, SPIRES looks in the named index for index records fitting the criteria specified. In the above example, for instance, SPIRES would look in the BLOOD.TYPE index for an index record with the value "A+". That index record contains references or "pointers" to those goal records containing the value "A+" for the donor's blood type. SPIRES collects the set of relevant pointers from the index record, counts the number of different pointers, and tells you that number, which is thus the number of goal records that meet the search criteria -- 153 goal records, in this case. If there had been no index record for the value "A+", SPIRES would have responded "-Zero result".
The next step might be to display the goal records in the search result, by issuing the TYPE command. [See I.5.] Alternatively, you could continue the search, further subsetting the records in the search result, using the same or other indexes. [See I.4.3.]
The equality operator (the equals sign) is not the only relational operator, though it is certainly the most commonly used. There are eighteen of them altogether. Here are the more common ones:
-> find city = menlo park -> find city menlo park
~= (not equal to) ["~" appears as a tilde on many terminals] > (greater than) >= (greater than or equal to) < (less than) <= (less than or equal to)
Here are some examples of these relational operators:
-> find blood.type ~= O+
(find donors that don't have blood type O-positive)
-> find total.pints >= 10
(find donors who have contributed 10 or more pints)
-> find name > m
(find donors whose last names come after M alphabetically)
-> find blood.type prefix b
(find donors whose blood type begins with the letter B,
i.e., whose blood type is B+ or B-)
In the third example, SPIRES would probably discover that there was no index record for the value "M" but would find the place in the index where that index record would be if it existed; then it would retrieve all the index records from that point on.
For a complete list of the relational operators, EXPLAIN RELATIONAL OPERATORS.
You may further qualify a simple search result using the information in the same or other indexes. For example, if you wanted to know how many people you can telephone when you need type AB-negative blood:
-> find blood.type = ab- -Result: 96 DONORS -> and can.be.called = yes -Result: 88 DONORS ->
The FIND command starts a new search every time it is issued. To add further criteria to an existing result, you type a "logical operator" (either AND or AND NOT or OR) followed by a search expression. Continuing a search in this way is called "iterative searching". Iterative searches can be constructed of any number of search expressions, each preceded by a logical operator at the start of a new command.
The AND operator indicates that retrieved records must satisfy both criteria, e.g., that the donor must have AB-negative blood and be willing to be called.
The AND NOT operator requires that goal records that would have been included using the AND operator be excluded from the result:
-> find can.be.called = yes -Result: 713 DONORS -> and not blood.type prefix ab -Result: 522 DONORS ->
The OR operator requires that records that satisfy at least one of the criteria be included in the result:
-> find blood.type = ab+ -Result: 97 DONORS -> or ab- -Result: 196 DONORS ->
Note that you do not need to repeat the index name if you issue iterative search commands using the same index. (Also note that the same result can be acquired in one command: "FIND BLOOD.TYPE PREFIX AB", which generates a bit less work for SPIRES since it only needs to search the index once.)
Anytime after you have issued an iterative search command, you may issue the BACKUP command to return to the previous search result:
-> find blood.type a- -Result: 116 DONORS -> and city palo alto -Result: 29 DONORS -> backup -Result: 116 DONORS ->
You may only issue BACKUP "one time in a row" -- you may not issue the command again until you have issued another iterative search command.
You may combine the parts of two or more iterative searches in one command if you like, called a "compound search". The first example above can be entered instead as
-> find blood.type = ab- and can.be.called = yes
More than two search expressions can be included in a compound search, if desired. Again, you can shorten the command by not repeating the index name if it is the same in both search expressions:
-> find blood.type ab+ or a+ or b+
Several special types of indexing are available that give you extra flexibility in searching. For file owners, they help make internal file storage less expensive and more efficient. Understanding how these types of indexes are used is very valuable when you are designing a data base yourself.
Many data "elements", that is, the individual pieces of data in a record [See I.5.] can be strings of text; for example, the "location" element in a BLOOD DONORS goal record might be "Polya Hall, Stanford University", a string of four words. In indexing such values, most subfiles index the individual words of the string, rather than the entire string itself. Thus, in the LOCATION index, there would not be a record for "Polya Hall, Stanford University" with pointers to goal records containing that value; rather, there would be four entries in the index, one for "Polya", one for "Hall", etc., each with pointers to the goal records.
In a search, FIND LOCATION POLYA or FIND LOCATION HALL would retrieve these goal records (and possibly others if they had either "Polya" or "Hall" in their locations). Thus you do not need to remember an entire string of text that is indexed -- just a small portion will suffice to retrieve the desired records.
If you do know the entire string or more than one word of it, SPIRES will automatically split the search value into individual words, each separated by the logical operator AND. Thus,
-> find location polya hall
is treated like
-> find location polya and hall
The best way to determine whether an index is a "word index" is to issue the BROWSE command. If all the values are single words that do not stand alone very well as index values, the index is probably a word index.
Though a word index is slightly more expensive for the file owner, since it usually means a larger index to store, it is highly efficient for the searcher who uses the index often. For instance, it is much more efficient for SPIRES to find a specific word in a word index than to find a specific word within a longer indexed value, using the STRING relational operator. [See I.4.2.]
Sometimes the file owner allows only certain values to be indexed. For example, in the BLOOD.TYPE index, only the eight types of blood shown when the index was browsed [See I.4.] are allowed as values. These "inclusion lists" help prevent indexes from accumulating erroneous data. If your search value is not in the inclusion list, you will receive an error message.
-> find blood.type = blue -Element=BLOOD.TYPE: Value must be A+,A-,AB+,AB-,B+,B-,O+,O- -Serious data error, code=E46 -Not a legal or complete command -> explain e46 E46: The value input for a data element does not match one of a set of codes defined for the element by the file owner. ->
Since "blue" is not one of the allowed values, the search is rejected. The error message can be explained, if desired, by issuing an EXPLAIN command ("EXPLAIN E46", using the error code shown in the error message). [See I.1.]
If a subfile indexes the names of individual people, the index is usually a "personal name index". You can search name indexes when you have a different form of the name than might be indexed. For example,
-> find name e. borden -> find name elizabeth borden -> find name borden -> find name borden, elizabeth
would all retrieve the goal record for donor Elizabeth Borden. If her middle name were "Rae" and it were included in the goal record, the following would also retrieve the record:
-> find name e. r. borden -> find name e. rae borden
Like personal names, dates are usually given special treatment in indexes. Usually when a subfile indexes dates, it allows searching for dates in a variety of forms. For example, all of the forms below are equivalent:
-> find date.given july 1, 1980 -> find date.given jul 1, 1980 -> find date.given 7/1/80 -> find date.given 7/1/1980 -> find date.given 1-7-80 -> find date.given 1 july 1980
Other variations are allowed as well. Date indexes are usually constructed to permit a record with a specific date, such as July 1, 1980, to be retrieved by searches such as
-> find date.given july 80 -> find date.given 1980
which would retrieve all records with a "date.given" of anytime in July 1980 or anytime in 1980 respectively.
Eventually you will want to examine the records retrieved by your searching. Anytime you have a search result, you may issue the TYPE command, which will display all the records in the result. For example,
-> select blood donors -> find name werner blut -Result: 1 DONOR -> type ID = 3; NAME = Blut, Werner; ADDRESS = 5225 Plasma Place; ADDRESS = Apt. A; CITY = Redblood City; STATE = CA; ZIPCODE = 94007; PHONE.NUMBER = 733-2355 (home); PHONE.NUMBER = 328-0920 ext. 593 (work); CAN.BE.CALLED = Yes; BLOOD.TYPE = B+; DATE = 03/22/81; LOCATION = Tresidder Union; DATE = 12/10/80; LOCATION = Stanford Blood Bank; TOTAL.PINTS = 2; ->
Here you see a complete goal record from the subfile, the result of your search. Each goal record in the subfile would contain similar types of information -- the donor's name, blood type, amount contributed, and so forth. These basic units of data in a record are called "elements".
To understand searching, it helps to understand how goal records and indexes are related. The elements for a particular donor are gathered together and added to the subfile as a goal record. Many of the elements in a goal record are then "passed" to various indexes to be index values -- for instance, the value of the CITY element (say, "Palo Alto") is passed to the CITY index to serve as the indexed value PALO ALTO. (The file owner chooses the elements and the indexes that should be created from them.) A pointer back to the original goal record, where the original value is still contained, is then created for the index record. This is just like the procedure that would be used to keep the "city" drawer of the file cabinet up-to-date in our earlier example. [See I.2.]
You can see what elements are in the goal records by issuing the SHOW ELEMENT CHARACTERISTICS command:
-> show element characteristics
Subfile BLOOD DONORS
Sec Occ Len Type St/El Element
--- ---- --- ------ ----- -------
Fix Sing 4 Int 00/00 slot ID
Req Sing String 00/01 NAME, DONOR.NAME, NAM
Req Mult String 00/02 ADDRESS, ADD
Req Sing String 00/03 CITY, CIT
Req Sing 2 String 00/04 STATE, STA
Opt Sing 5 String 00/05 ZIPCODE, ZIP
Opt Mult String 00/06 PHONE.NUMBER, PHN, PHO
Opt Sing 1 String 00/07 CAN.BE.CALLED, CAL, CAN
Opt Sing String 00/08 BLOOD.TYPE, BLD, BLO, BLOOD
Opt Mult Struc 00/09 DONATION, DON
Fix Sing 4 Hex 01/00 key . DATE, DAT, DATE.GIVEN
Opt Sing String 01/01 . LOCATION, LOC, WHERE.GIVEN
Opt Sing 2 Int 00/0A TOTAL.PINTS, PINTS, PINTS.GIVEN,
TOT
Opt Mult String 00/0B COMMENTS, COM
Each line lists a separate element of the goal record. Each element, as shown at the right, may have several names: the primary name (the first one) and "aliases", generally shorter names that may be used anywhere the primary name can be used. (For example, see the "element-name" option on the TYPE command described below.) The command displays other descriptive information about the elements as well.
Comparing the list above to the list of indexes shown earlier [See I.4.] you will see that not all the elements are indexed. For example, ZIPCODE is not indexed. Methods are available for searching for goal records using non-indexed criteria, such as finding all the records with a particular zipcode value. [See VIII.] Indexes and elements do not necessarily correspond one-to-one. Besides elements that are not indexed, a subfile might have indexes that contain several elements, or elements that are in several indexes.
You may also notice that each goal record may not have all elements. For example, in the goal record above, there is no COMMENTS element, apparently because there were no comments about the donor to include.
Note how the element names DATE and LOCATION are indented beneath the element name DONATION in the list above. That indicates that DONATION is a "structure". Structures provide a way to link related information together -- in this case, each date that a donor gives blood is linked to the location where the donation was made. If the elements were not kept together by means of the structure, the relationship between them would no longer be clear:
ID = 378; NAME = Blut, Werner; ... DATE = 03/22/81; DATE = 12/10/80; LOCATION = Tresidder Union; LOCATION = Stanford Blood Bank;
In the sample record, the elements and their values are shown in the form:
element-name = value;
or sometimes just
element-name;
(The latter usually indicates the name of a structure being displayed.) When records are displayed in the form shown above (i.e., "element-name = value;"), they are in the SPIRES "standard format". The semicolon at the end of each element is a "delimiter" that tells SPIRES where one element ends and another begins; it is an essential part of the standard SPIRES format.
It is possible to see only specific elements in the goal records of the search result, which is particularly desirable when you have a large result. Issue the TYPE command followed by the names of the elements whose values you want to see.
-> find blood.type o+ -Result: 86 DONORS -> and city palo alto -Result: 58 DONORS -> type name phone.number NAME = Sand, Marvin; PHONE = 212-5933; NAME = Water, Karen; PHONE = 938-6390 (home); PHONE = 347-8000; NAME = Gutz, Ralph; NAME = Sweat, Abner; PHONE = 497... <---the ATTN/BREAK key is pressed ->
This form of the TYPE command is called the "TYPE element-list" command.
You may prefix the TYPE command with IN ACTIVE if you would like to place a copy of the displayed records in your active file.
The TYPE command does not change the search result. After issuing a TYPE command, you may continue the search with iterative search commands if desired, or you may arrange the records in the search result in some other order, using the SEQUENCE command [See I.5.2.] or issue the TYPE command again.
Though some subfiles only use the SPIRES standard format (as shown above) to display records, most subfiles have special formats designed especially for them. These custom formats can present only the information that the format designer wants the searcher to see, and present it in a more attractive manner. For example,
-> find name werner blut -Result: 1 DONOR -> set format address.label -> type Werner Blut 5225 Plasma Place Apt. A Redblood City, CA 94007 ->
Here someone designed a custom format named ADDRESS.LABEL to put some of the element values in a format that could be used to create address labels. Only the elements pertinent to an address label are displayed. By issuing the TYPE command with the IN ACTIVE prefix, the address label could be placed in your active file and then directed to a printer.
To see the names of the custom formats designed for the goal records, issue the command SHOW FORMATS. When you want to set a format, issue the command
SET FORMAT format-name
where "format-name" is a name chosen from the list. In addition, SPIRES has several "system formats" that can also be set. [See II for use of the $PROMPT format.] Only one format may be set at a time. Setting a new format clears the old one.
To return to the SPIRES standard format, issue the CLEAR FORMAT command.
Most subfiles that have at least one custom format usually set one automatically when the subfile is selected. (For example, try selecting the public subfiles DRINKS or RESTAURANT and displaying the records in a search result.) You will have to use the CLEAR FORMAT command if you want to display the records in the SPIRES standard format, even though you may not have set the custom format yourself. Then, to return to a custom format, you would issue another SET FORMAT command.
You can create a custom format for the goal records of any subfile you can select. The SPIRES primer "A Guide to Output Formats" is a good place to begin learning about SPIRES formats.
Often the order of records displayed seems haphazard. By using the SEQUENCE command, you can create a "stack" of records in a particular arrangement, ordering them by the values in the records for a particular element. The stack of records may then be displayed using the TYPE command.
For example, suppose you want to mail a notice to those donors who cannot be called and that to reduce your mailing costs, you need to arrange them in order by zipcode:
-> select blood donors -> find can.be.called no -Result: 127 DONORS -> sequence zipcode -Stack: 127 DONORS -> type zipcode ZIPCODE = 91302; ZIPCODE = 94001; ZIPCODE = 94001; ZIPCODE = 94002; ... <--- ATTN/BREAK is pressed, stopping the listing -> set format address.label -> in active type ->
In the example, you issue the command TYPE ZIPCODE just to verify that the records were in the proper sequential order.
The syntax of the SEQUENCE command is:
SEQUENCE element-list
where "element-list" consists of one or more element names. SPIRES sorts the records on the values of the first element listed. If several records share the same value for that element, then the next element in the list is compared, and so on. SPIRES normally sorts in ascending order -- that is, alphabetic order for alphabetic strings and numeric order for numbers. If an element may contain either alphabetic or numeric strings, the alphabetic strings sort first. If a record has no value for the sequenced element, the record is placed first in the stack.
You may also sequence in descending order if you want, by specifying the option "(D)" after the appropriate element name in the SEQUENCE command. For example,
-> sequence total.pints (d) name
would arrange the records in the search result in order by the number of pints of blood donated, starting with those contributing the most. If several people have given the same amount, then they are listed in alphabetic order at that point in the list. If a record did not have a value for the sequenced element TOTAL.PINTS, that record would be included at the end of the list, because the "(D)" reverses the normal ordering.
Using the TYPE command, records can be displayed either in a format designed for them, if one exists, or in the SPIRES standard format (or a subset of elements thereof, using the "TYPE element-list" command), or in the SPIRES system format called $PROMPT [See II.] However, you can also design a tabular display of the records yourself with relative ease, using the $REPORT format. This system format lets you arrange your records in a simple tabular report without programming.
To create a simple report, issue the following command:
SET FORMAT $REPORT element-list
where "element-list" is a list of elements selected from the list shown by the SHOW ELEMENTS command. [See I.5.] The element names must be separated by blanks. SPIRES will construct a table, giving each element equal length across the display area "by default", that is, unless you specify otherwise. To display the table, using your search result, you issue the TYPE command.
-> find city palo alto and date.given 5/1/81 -Result: 4 DONORS -> sequence name -Stack: 4 DONORS -> set format $report Name Address Total.Pints -> type Feb. 11, 1983 Page 1 Name Address Total.Pints ---------------------- ---------------------- ---------------------- Blutter, Rhed 1383 Scarlet Road 2 Brown, Robert 123 Olive St. 1 Claret, Van E. 1422 Rouge Road 1 Harrison, Chevy 1383 Washout Way 10
Using the IN ACTIVE prefix on the TYPE command, you can place the display in your active file. SPIRES will then put carriage control symbols in the first column for use in offline printing.
Anytime you issue a TYPE command (except the "TYPE element-list" command) or the DISPLAY command [See I.7.] while you are using the same subfile, the record or records will be displayed in the report format you created. If you want to change the report, issue another SET FORMAT $REPORT command. If you want to display the results in the default format, issue the CLEAR FORMAT command. CLEAR FORMAT is issued automatically when you select another subfile.
$REPORT offers a wealth of additional options for creating more than a simple tabular display. In fact, $REPORT offers so many different features that you may find yourself feeling somewhat overwhelmed by it at first. Report Definer, a full-screen SPIRES utility, provides you with a way of customizing SPIRES reports merely by filling in blanks on Report Definer input screens. Using Report Definer you can obtain the most widely-used features in $REPORT by specifying them directly; you do not need to learn a special subcommand language to translate your wishes into programming code.
(To use Report Definer you will need a terminal that supports full-screen display, and unless you use an IBM 3270-style terminal you may also need to SET TERMINAL terminal-type before entering SPIRES. DESCRIBE TERMINAL TYPE for more information.)
For example, to create a donors report using Report Definer, first select the subfile and, if you wish, assemble a collection of records with the FIND command or Global FOR techniques. (You can just as easily collect the records after defining your report.) SEQUENCE the records if their order within the report is important. Then issue the command ENTER REPORT DEFINER and fill in blanks on the series of input screens to tell SPIRES how you want your report to look.
-> select blood donors
-> find city menlo park or city palo alto
-Result: 9 DONORS
-> sequence city id
-Stack: 9 DONORS
-> enter report definer
(continued)----->
In Report Definer:
+------------------------------
|On the first input screen,
|specify your elements....
|
+------------------------------------------------------------------|----
| |
| ELEMENT 1 ELEMENT 2 ELEMENT 3 ELEMENT 4 ELEMENT 5 |
| City_____ ID_______ Name_____ Phn______ Total.pints <--+
|
|
|
|
+--------------------------------------------
| On the 2nd and 3rd screens, you can request
| summaries (such as a SUM of total pints) as
-------------| well as groupings |
/ | (e.g., by city).... |
/ |
+-----------/----------------------------------------|------------------
|(SUB-TOTAL/ |
| GROUP BY/ ELEMENT NEWPAGE COUNT AVERAGE SUM MINIMUM MAXIMUM
| _______/____ ______________ _______ _____ _______ |__ _______ _______
| X City |
| ID |
| Name X |
| Phn |
| Total.pints X
|
+-----------------------------------
|On the fourth screen you specify a
|layout for your elements and decide
| what headings they should have....
|
+-------------------------------------------------------- | -----------
| ELEMENT WIDTH HEADING | (For instance
| City 10 City | you can specify
| ID 3 ID | the heading
| Name 20 Name | "Phone" instead
| Phn 17 Phone <--------------+ of PHN.)
| Total.pints 7 Total//pints
|
|
Continuing in Report Definer:
+----------------------
|On the 5th screen you
|can change the page
|layout or add a title
+---------------------------------------------------------------
|
|SUMMARY-ONLY NO <-----(Typing "YES" displays summaries only
|
|LINES 60 <---------------- LINES is the number of
|INDENT 7 <------- lines per page, INDENT
|SKIP 0 is the starting
|TITLE Donors in Menlo Park and Palo Alto column, SKIP is
| number of lines
| between records.
Once you are finished inputting your report definition, Report Definer sets the format for you. At this point you can issue any SPIRES or text editing command, such as FIND, TYPE or IN ACTIVE TYPE.
Or you can issue one of the special Report Definer commands: DEFINE to go back to the input screens and touch up your report definition, DEFINE CLEAR to begin defining a brand new report, DEFINE * to return to the last input screen you used, or RETURN to leave Report Definer. HELP and SHOW COMMANDS can also give you ideas on what to do next.
On the next page is a slightly annotated version of the report defined above:
June 25, 1984 Donors in Menlo Park and Palo Alto Page 1
Total
City ID Name Phone pints
---------- --- -------------------- ----------------- -------
Menlo Park 16 Coale, Blanche 324-6828 1
324-6929
17 Tree, R. 324-6020 2 +-------------
324-6121 |(Note how the
|records are
*COU 2 <---------------------------|grouped into
*SUM 3 |two different
|cities, with
Palo Alto 4 Blutter, Rhed 332-1125 2 |subtotals for
6 Claret, Van E. 271-5678 1 |each city.)
9 Brown, Robert 327-1234 (home) 1 +-------------
555-1212 x345 |
(work) |
10 Moreblood, Alex 333-3871 (home) 2 |
854-3300 x1111 |
(work) |
23 Weinberger, Jaspar 212-4678 (home) 4 |
328-0920 x93 |
(work) |
24 Harrison, Chevy 212-1905 10 |
27 Kazoo, Lainie 1 |
|
*COU 7 <---+
*SUM 21
+-------------
**COU 9 <------------------------------|Summaries
**SUM 24 |with ** are
|for the whole
|report.....
+-------------
If you decide to enhance your report with additional features, one relatively easy way is to save your report format input by typing IN ACTIVE SHOW FORMAT INPUT, then refining it as you like with $REPORT subcommands. See Part C of "SPIRES Searching and Updating" if you would like more information on either Report Definer or $REPORT.
When you want to call someone on the telephone, you dial the number directly, if you know it, rather than look it up first in the phone book. Similarly, when you use a SPIRES subfile, if you know the "number" of the specific record you want to examine, you do not have to search the indexes for it first; rather, you can request it directly, using the DISPLAY command.
Each goal record in the subfile has one element called the "key element" or "key". It is a unique value in each goal record; no other goal record may have the same value for the key. For example, in a personnel subfile, where each employee is represented by a goal record, the key for the subfile might be the employee's social security number.
One way to discover which element is the key is to issue the SHOW ELEMENT CHARACTERISTICS command. [See I.5.] That command, which shows you what elements can be in a goal record for the selected subfile, also names one as the key element, denoted by the word "slot" preceding its name, since this particular key is a slot key [See III.3.1.] whose value SPIRES assigns automatically when a record is added:
slot ID
Another element, DATE, is also marked as a key:
DONATION, DON
key . DATE, DAT, DATE.GIVEN
. LOCATION, LOC, WHERE.GIVEN
but it represents a structure key, because it is indented. [See III.3.2.]
When you want to examine a record directly, issue the DISPLAY command:
DISPLAY key
where "key" is the key value of the record you want to see. For example,
-> display 3 ID = 3; NAME = Blut, Werner; ADDRESS = 5225 Plasma Place; ADDRESS = Apt. A; (etc.) ->
The DISPLAY command may be preceded by the IN ACTIVE prefix if you want to place a copy of the record in your active file.
So now you have two different ways to examine records: by using the indexes to search for records based on indexed criteria (the FIND and TYPE commands) and by directly accessing a record when you know its key value (the DISPLAY command). [See VIII.1 for a third way, using Global FOR, which allows you to examine records based on unindexed criteria.] The record key, which uniquely identifies a record, is also used on other commands, specifically those used in subfile modification, discussed in the next chapter.
Just as you can see sample values in an index by issuing the BROWSE command, you can discover what type of value makes up the record key by issuing the BROWSE GOAL command for the selected subfile:
-> browse goal -Next slot = 893 ->
In the case of BLOOD DONORS, which has a "slot key", the BROWSE GOAL command here tells you the value for ID that will be assigned to the next record added to the subfile. (When a subfile's goal records have slot keys, it means that SPIRES will assign an integer value to each record as it is added.) If the records do not have slot keys, then BROWSE GOAL will show you sample key values just as the BROWSE command shows you sample index values. [See III.3.1.]
You cannot search a subfile unless there are records in it. This chapter will show you a simple way to add records to a subfile where SPIRES will prompt you for the element values to be placed in each record, using a SPIRES system format called $PROMPT. (A SPIRES system format is one that is designed for use with many different subfiles, rather than customized for a specific one. The names of such formats begin with a dollar sign.) Besides the ADD command, other "subfile modification" commands to be discussed in this chapter are MERGE, TRANSFER, UPDATE, REMOVE and DEQUEUE, which give you a wide variety of options for managing the data in the subfile.
Before you can do any subfile modification, you must have permission from the data base owner. This permission is given in the file definition, where various user accounts are given various privileges to the subfile. [See V.2.] Some public subfiles, such as RESTAURANT and FILEDEF, allow anyone to add and update records in them; others, such as DRINKS, may only allow you to search them. If you are the file owner, you have no doubt given yourself permission to update your subfile. If you are not, you must find out from the file owner if you can. (Public subfiles that allow you to update them usually say so in their subfile explanations, which you can see by issuing the "SHOW SUBFILE DESCRIPTION subfile-name" command.)
SPIRES has two basic methods for adding single records to your subfile:
Here is an example session using the $PROMPT format.
-> select blood donors -> set format $prompt -> add : NAME William Harvey <--RETURN is pressed to enter value : ADDRESS(1) 193 Circulation Drive <--RETURN is pressed : ADDRESS(2) <-- RETURN is pressed to skip the element : CITY Mountain View <--RETURN is pressed, etc. : STATE CA : ZIPCODE 940041 -Element=ZIPCODE: Value must be 5 digits -Serious data error, code=E22 : ZIPCODE 94041 : PHONE.NUMBER(1) 328-0920 (work) : PHONE.NUMBER(2) 212-5903 (home) : PHONE.NUMBER(3) <-- RETURN is pressed : CAN.BE.CALLED Yes : BLOOD.TYPE A -Element=BLOOD.TYPE: Value must be A+,A-,AB+,AB-,B+,B-,O+,O- -Serious data error, code=E46 : BLOOD.TYPE A+ Struc: DONATION : DATE ? <-- entered to request more information Please enter the date the donation was made. : DATE 3/11/81 : LOCATION Stanford Barn : DATE <-- RETURN is pressed to skip the element : TOTAL.PINTS <-- RETURN is pressed to skip the element : COMMENTS(1) This man will be on sabbatical leave for// : more--> a year but wants to be called next year. : COMMENTS(2) <-- RETURN is pressed to skip the element -Added record 952 ->
The prompts and messages on the left side are from SPIRES; the responses on the right in boldface are typed by you, after which you press the return key.
The element value entered using the $PROMPT format may be roughly 140 characters in length. For elements with long values (whether or not they are longer than 140 characters), you can enter part of the value and then request to continue it by ending it with two slashes (//), as shown for COMMENTS. The format will then prompt you for "more-->" of the input value. If the value you enter is more than 100 characters long, the $PROMPT format will automatically prompt for "more-->". If there is no more to be included for that element value, press the return key in response to the "more-->" prompt.
SPIRES prompts you for each element that can appear in the goal record, on those lines beginning with a colon (:). In some cases, such as NAME, only one value is allowed. In others, such as ADDRESS or PHONE.NUMBER, there can be more than one, and SPIRES prompts you for more occurrences until you signal that you are through by pressing return in response. For some elements, such as TOTAL.PINTS, you may not want to provide a value; as before, you simply press return to skip that value.
For some subfiles, depending on their file definitions, if you provide an invalid value, as shown for ZIPCODE and BLOOD.TYPE, SPIRES will tell you so and reprompt for a valid one. For some subfiles (again depending on their file definitions), when you are not sure what type of value is being requested, such as DATE, if you enter a question mark you will receive an explanation.
The $PROMPT format also allows you to issue "subcommands" in response to an element prompt. These subcommands, identified by their initial slash character (/), specify some action that the format should take, such as "end prompting and process the record as input" (/E) or "cancel the request entirely" (/X). They will appear from time to time in this chapter.
When you are through providing values, SPIRES adds the input record to the subfile. (Notice that SPIRES then tells you the slot number assigned to the new goal record -- here, 952. SPIRES did not prompt for that value when you were adding the record since it would be assigning the value itself. If the goal record did not have a slot key, SPIRES would have prompted you for the key value of the record.) You may then want to add another record or examine the one you have added.
The $PROMPT format can also be used to examine records, displaying them somewhat differently than the standard SPIRES format. Continuing the above example, we will now display the record just added, using the $PROMPT format already set:
-> display 952
ID 952
NAME Harvey, William
ADDRESS(1) 193 Circulation Drive
CITY Mountain View
STATE CA
ZIPCODE 94041
PHONE.NUMBER(1) 328-0920 (work)
PHONE.NUMBER(2) 212-5903 (home)
CAN.BE.CALLED Yes
BLOOD.TYPE A+
Struc: DONATION
DATE 03/11/81
LOCATION Stanford Barn
TOTAL.PINTS 1
COMMENTS(1) This man will be on sabbatical leave for a
year but wants to be called next year.
->
Notice that the TOTAL.PINTS element obtained a value even though we skipped it during input. That will be explained later. [See V.3.2.8.]
When you add a record to a SPIRES subfile, it is placed in an area of the file called the "deferred queue". All added and updated records, as well as requests for records to be removed from the subfile, are stored in the deferred queue until the file owner "processes" the file. When the file is processed, the added records are moved from the deferred queue into the "tree", that part of the file where the records are permanently stored. The old tree versions of the updated records are replaced in the tree by the new updated version of each; the records being removed are removed from the tree. At the same time, the subfile indexes are altered to reflect these changes: new information added for the added records, old information changed or removed for the updated or removed records. Thus, adding, updating or removing a record will not change the indexes right away; the FIND command will not locate an added record until the file is processed.
The DISPLAY command can show you an added record if you know its key, as shown above; alternatively, you can issue Global FOR commands to see the added records in a subfile. [See VIII.]
Both the TYPE and DISPLAY commands will access the latest copy of a record, hence giving you an updated version if it has been updated, or telling you that there is no such record if it has been removed. File owners, in most cases, have the files processed automatically overnight for every day that any subfile modification has occurred. [See VII.3.]
That is the basic procedure for adding and displaying records using the $PROMPT format. In the remainder of this section, we will focus on some of the specific rules and details involved. Some features of this method of adding records work only when the file definition is created with them in mind. As you read this section, keep track of the features you find valuable, because your file design will depend on them.
For the $PROMPT format, the SHOW FORMAT INFORMATION command shows information about the structure of the goal record, element names and element occurrences. It will tell you which elements SPIRES will prompt you for and what special format processing options are currently in effect:
-> select blood donors -> set format $prompt -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied 1 ID required 1 NAME required mult ADDRESS required 1 CITY required 1 STATE optional 1 ZIPCODE optional mult PHONE.NUMBER optional 1 CAN.BE.CALLED optional 1 BLOOD.TYPE optional mult DONATION optional 1 . DATE optional 1 . LOCATION optional 1 TOTAL.PINTS optional mult COMMENTS ->
The options noted in the first two lines of the display from the SHOW FORMAT INFORMATION command are discussed in "SPIRES Searching and Updating", section D.6.3. Below them is a listing of the elements that SPIRES will prompt you for. The element names that are indented are in the structure DONATION, just as they were shown by the SHOW ELEMENT NAMES command. The codes to the left of each element name, based on information in the file definition, declare whether the element can have single ("1") or multiple ("mult") occurrences (i.e., whether the record is allowed to have only one or more than one value for that element) and whether the element is Supplied, Fixed, Required, Optional or Virtual, discussed below.
When an element is marked as singly occurring (indicated by the "1" in the "occ" column of the SHOW FORMAT INFORMATION display), then SPIRES will only prompt for a single occurrence. This means that the file owner will allow the element to have only one value, as declared in the file definition.
When an element is marked as multiply occurring, SPIRES will prompt for one occurrence after another, each time enclosing the number of the occurrence in parentheses, following the element name. When you have no more occurrences to enter, you press the return key in response to the next occurrence prompt.
: PHONE.NUMBER(1) 328-0920 (work) : PHONE.NUMBER(2) 212-5903 (home) : PHONE.NUMBER(3) <--RETURN is pressed; no more values : CAN.BE.CALLED Yes (etc.)
There are five element categories that can appear in the "input" column of the SHOW FORMAT INFORMATION display: "fixed", "required", "optional" "supplied" and "virtual". They will be discussed in detail later. [See III.3.6.]
The $PROMPT format requires that you provide values for elements marked as Fixed or Required. If you do not provide a value, you will get an error message and be reprompted for that element. For example, the NAME element in the BLOOD DONORS subfile is required:
-> add
: NAME <--RETURN is pressed
Value required - enter /N to skip or // for null value
: NAME Sam Peckinpah
(etc.)
The subcommand "/N" can be given if you want to skip the value. This is useful for elements whose values are assigned by SPIRES when you add the record. For example, many subfiles have a record element called DATE-ADDED that contains the date that the record was added to the subfile. In most cases, the file definition specifies that SPIRES is to assign that value when the record is added. But if it is a required element, SPIRES will only let you skip it during $PROMPT format processing if you issue the subcommand "/N". In such a case, SPIRES will later supply the value. On the other hand, if the element is not one in which SPIRES will supply the value, you should not issue the subcommand "/N" to skip it; if you do, SPIRES will discover after you have input the rest of the record that a required element is missing and then reject the record, in effect losing the entire input record. [See IV.6.5.2, V.3.2.8.] In our BLOOD DONORS subfile, all the elements except the key element ID and NAME, ADDRESS, CITY and STATE are shown as "optional", meaning that we do not need to supply values for any of them. Once you have entered all the data you want for a record and all the remaining elements to be prompted are optional, you may press return for each one, or you may issue the subcommand "/E" in response to an element prompt in order to end prompting altogether.
Since the key is assigned by SPIRES and thus not prompted, it is listed as a "supplied" element. The $PROMPT format will not prompt you for the value of a slot key. If the record key were not a slot key, however, it would be a required element, and the $PROMPT format would require you to provide a value for it.
Elements that need to be kept together are stored in structures. [See I.5, III.3.2.] Elements within structures (as opposed to "record-level elements", which are elements that are not within structures) may be singly or multiply occurring, and they may be required or optional, just as record-level elements are. In addition, the structure that contains them may be required to occur or optional, and it may be singly or multiply occurring as well. For example, suppose a goal record had a PHONE structure that contained the elements AREA.CODE, NUMBER, and TYPE (such as "business" or "home"):
PHONE; NUMBER = 497-4420; AREA.CODE = 415; TYPE = work; PHONE; NUMBER = 328-6425; AREA.CODE = 415; TYPE = home;
The entire structure might be optional, since someone might not have a telephone. If the structure does occur, the NUMBER element would probably be required, since there would be no reason for the PHONE structure to occur at all if there were no NUMBER.
Considering the number of occurrences, notice that a goal record may have more than one phone, so the PHONE structure could occur more than once. However, for any single occurrence of the structure, which represents a single phone, there will be only one AREA.CODE and one NUMBER. (Perhaps the TYPE element might be multiply occurring within the structure, since a single phone might have more than one purpose.) Thus, the structure itself is multiply occurring, as is the TYPE element within it, but the other structural elements, AREA.CODE and NUMBER, are singly occurring.
This example shows only one possibility for the relationships between a structure and its elements; many others are possible too. It may be helpful to think of a group of occurrences of a structure in a record as similar to a group of goal records in a subfile, but just a level deeper into the subfile. (Structures too may contain structures, which may contain structures, to a level of nine deep.)
The $PROMPT format prompts you for elements in structures exactly as it does other elements. For example, you press return to skip optional elements in a structure. However, by default, if you press only return in response to the first element in an occurrence of a structure, then no other elements in that occurrence of the structure are prompted, and, if the structure is multiply occurring, no other occurrences of the structure are prompted:
Struc: DONATION
: DATE 3/11/81
: LOCATION Stanford Barn
: DATE <-- RETURN is pressed to skip the second
occurrence of the structure
: TOTAL.PINTS (etc.)
If you discover as you enter a value that you have made a mistake, you may correct it just as you correct an error in WYLBUR: either backspace and type in the correct values or press ATTN/BREAK and begin the input line again when you are reprompted:
-> add : NAME Drew Blood*** <--- ATTN/BREAK is pressed : NAME Andrew Blood
On the other hand, if you have already pressed return and the $PROMPT format has prompted you for another element occurrence, you cannot correct an error in any previous elements' values except by:
- typing the subcommand "/X" to abort the request; this discards the data you have already typed for this record request; or
- completing the record request and later updating the record.
Errors may be detected by the $PROMPT format as well. Error messages are issued for three different reasons:
In nearly all cases of errors, an error message will be displayed, and you will be reprompted for the value of the element that caused the error. Thus, you are allowed to re-input values that were in error.
You may decide after trying to add a record and receiving error messages that you want to cancel the request altogether. You may either enter the subcommand "/X":
: PHONE.NUMBER /x -Update terminated, code=S2 ->
or you may press ATTN/BREAK:
: PHONE.NUMBER *** <--- ATTN/BREAK is pressed : Do you wish to cancel this request? (YES/NO/HELP) yes -Update terminated, code=S2 ->
Responding HELP will give you a list of useful subcommands. Responding NO will restart element prompting.
Subfile modification usually involves more than just adding records; you may want to change the data in a record, or even remove the entire record from the subfile. SPIRES even allows you to change your mind once you have updated or removed a record (if you change your mind that day) and "dequeue" your request, hence leaving the record in its original form. In this section and the next, updating a record, i.e., changing element values in a record, will be discussed. Later in this chapter, removing and dequeuing records will be covered. [See II.4.]
You can use the $PROMPT format with the MERGE command to change or add values in a record. The syntax of the MERGE command is:
MERGE key
where "key" is the key value of the record you wish to update.
Below is an example of updating a record with the $PROMPT format. The original record was added and displayed earlier. [See II.1.] Note that the element values are displayed to you before you are prompted for changes.
-> select blood donors
-> set format $prompt
-> merge 952
*** 952 ***
ID................952
NAME..............William Harvey
: NAME <-- RETURN is pressed to accept the value shown
ADDRESS(1)........193 Circulation Drive
: ADDRESS(1) <-- RETURN is pressed to accept the value
: ADDRESS(2) <-- RETURN is pressed; no new occurrences
CITY..............Mountain View
: CITY Los Altos <-- correct value is entered
STATE.............CA
: STATE <-- RETURN is pressed to accept the value
ZIPCODE...........94041
: ZIPCODE <-- RETURN is pressed to accept the value
PHONE.NUMBER(1)...328-0920 (work)
PHONE.NUMBER(2)...212-5903 (home)
: PHONE.NUMBER(1) /r <-- subcommand to remove the occurrence
: PHONE.NUMBER(2) <-- RETURN is pressed to accept the value
: PHONE.NUMBER(3) 212-5904 (home) <-- new occurrence added
: PHONE.NUMBER(4) <-- RETURN is pressed; no more values to add
CAN.BE.CALLED.....Yes
: CAN.BE.CALLED /e <-- subcommand to end prompting and
update the record
-> display 952
ID 952
NAME Harvey, William
ADDRESS(1) 193 Circulation Drive
CITY Los Altos
STATE CA
ZIPCODE 94041
PHONE.NUMBER(1) 212-5903 (home)
PHONE.NUMBER(2) 212-5904 (home)
CAN.BE.CALLED Yes
BLOOD.TYPE A+
Struc: DONATION
DATE 03/11/81
LOCATION Stanford Barn
TOTAL.PINTS 1
COMMENTS(1) This man will be on sabbatical leave for a
year but wants to be called next year.
->
During the MERGE processing, the $PROMPT format displays the value for each element in the record and then prompts for a new value to replace it, with the exception of the key value, which you may not change this way. As before, lines beginning with a colon indicate that the format is prompting you for an element value. When you do not want to change the displayed value, you simply press return to accept it as it is shown. If the element is a multiply occurring one, then all the values are displayed together, and you are prompted for replacement values one at a time following that, with allowances for new occurrences, as shown above for ADDRESS and PHONE.NUMBER.
Once you have made all the changes and the $PROMPT format stops prompting, SPIRES merges the changed input values with the old data in the record, creating a new version of the record. The new version is placed in the deferred queue; the next time the file is processed, it will be moved into the tree and the indexes will be updated accordingly. Remember that a DISPLAY or TYPE command that would display the record (or another MERGE command, for that matter) will access the updated version in the deferred queue. If you need to see the original tree version of the record, use Global FOR processing [See VIII.1.] or use the VIA TREE prefix on the DISPLAY command:
VIA TREE DISPLAY key
where "key" is the key value of the desired record. SPIRES will display the tree copy of the record.
Several useful subcommands were used in the above example:
- "/R" means "remove the current occurrence of this element". In the example, the first occurrence of the PHONE.NUMBER element was removed. When you are through processing the record and SPIRES places the new "merged" version of the record in the deferred queue, the later occurrences move up to replace the removed one.
- "/E" means "stop element prompting and process the input data". This subcommand, discussed earlier in regard to adding records to the subfile [See II.1.3.] is more useful during record merging. Once you have entered all the changes and no further elements will be modified, entering "/E" will stop the prompting and update the record.
- "/RS", though not shown above, is used to remove an occurrence of an entire structure. For example, by responding "/RS" when the DATE element within the DONATION structure is prompted, you can remove the occurrence of the structure, rather than respond "/R" for all the elements in the occurrence you want to remove.
- "/X" means "stop element prompting and abort the update process". The data input before the /X subcommand is issued is not used to update the record.
Earlier in this chapter, it was mentioned that there were two simple ways to add records to a subfile in SPIRES. One method was through the $PROMPT format, which we have used to add and update records. The other method is to collect a record in the standard SPIRES format in your active file and then, without setting a format first, issue the ADD command. SPIRES will read the data from your active file and try to add it as a record to the subfile. Naturally, the input must still meet any requirements specified by the file definer; for example, only one of eight allowed blood types may be input for that element.
A disadvantage of this method is that you must remember the element names as well as element values when you are entering data; the $PROMPT format remembers the element names for you. However, an advantage of this method is that it is cheaper than using the $PROMPT format. Another major advantage is that since your data is in your active file, if the computer crashes or your communications line loses its connection to the computer, WYLBUR will recover your active file, and hence your data will not be lost. The $PROMPT format, which does not use your active file, cannot save your input data if such a problem occurs. As machine stability increases, that becomes a smaller problem, however.
Below is an example of adding a record using the standard SPIRES format. Note that you can enter the input exactly as it would appear if it were displayed in that format; however, using the rules described below, the input is made easier, as shown in the example:
-> select blood donors
-> collect
1. > name = Julius Caesar;
2. > address 44 Appian Way;
3. > city Rome; state CA;
4. > blood.type = O-;
5. > can.be.called no;
6. > donation; date March 15, 1981;
7. > location Senate Mall,
8. > Rome CA;
9. > *** <-- ATTN/BREAK is pressed.
-> add
-Added record 979
-> display 979
ID = 979;
NAME = Julius Caesar;
ADDRESS = 44 Appian Way;
CITY = Rome;
STATE = CA;
CAN.BE.CALLED = No;
BLOOD.TYPE = O-;
DONATION;
DATE = 03/15/81;
LOCATION = Senate Mall, Rome CA;
->
The ADD command did not begin prompting for element values because the $PROMPT format has not been set since the subfile was selected. When the standard SPIRES format is set and you issue the ADD command, SPIRES looks for record input in that format in your active file.
Note these rules for record input using the standard SPIRES format:
element = "val;ue".
Other rules for this method of record input are described in "SPIRES Searching and Updating", section D.2. Remember that if you get an error message, you can use the EXPLAIN command to receive an explanation of the problem. [See I.4.4.]
You can also update records via your active file, using the TRANSFER and UPDATE commands. The TRANSFER command will place the requested record in your active file, where you may modify it by adding, deleting or changing lines using WYLBUR editing commands. When you issue the UPDATE command, SPIRES will then read the record back from your active file:
-> transfer 979
-OK to clear? yes
-> list
1. ID = 979;
2. NAME = Julius Caesar;
3. ADDRESS = 44 Appian Way;
4. CITY = Rome;
5. STATE = CA;
6. CAN.BE.CALLED = No;
7. BLOOD.TYPE = O-;
8. DONATION;
9. DATE = 03/15/81;
10. LOCATION = Senate Mall, Rome CA;
-> change 'O-' to 'O+' in 'BLOOD.TYPE'
7. BLOOD.TYPE = O+;
-> insert end
11. > comment = His wife, Calpurnia, should be contacted.;
-> update
-> display 979
ID = 979;
NAME = Julius Caesar;
ADDRESS = 44 Appian Way;
CITY = Rome;
STATE = CA;
CAN.BE.CALLED = No;
BLOOD.TYPE = O+;
DONATION;
DATE = 03/15/81;
LOCATION = Senate Mall, Rome CA;
COMMENT = His wife, Calpurnia, should be contacted.;
->
The syntax of the TRANSFER command is:
TRANSFER key
where "key" is the key value of the desired record. The UPDATE command does not require a key value if the record being updated is the same as the record last transferred; SPIRES is expecting the record named by the TRANSFER command to be returned.
By default for the $PROMPT format, if a record is transferred when it is set, it will be transferred into your active file in this standard SPIRES format; hence, the TRANSFER and UPDATE procedure shown above works whether or not the $PROMPT format is set.
The MERGE command, if used when the standard SPIRES format is set, will take the contents of your active file and use them to replace, delete or add appropriate elements in the record whose key is given in the MERGE command. See the manual "SPIRES Searching and Updating", section D.2.5.4, for directions on using the MERGE command that way.
When you want to remove a record from the subfile, you issue the REMOVE command:
REMOVE key
where "key" is the key value of the record you want to remove. As noted before, the record is not physically removed from the file right away; instead, a "removal request" is placed in the deferred queue. Later when the file is processed, the record will be removed from the tree. (Incidentally, if a record with a slot key is permanently removed from a subfile, then that particular slot key value will never again be used in that subfile.)
Since SPIRES normally checks the deferred queue for the latest copy of a record before displaying it, if you try to display a record after removing it, the deferred queue will tell you that the record does not exist:
-> remove 976 -> display 976 -No such record, code=S256 ->
However, using Global FOR techniques or using the VIA TREE prefix described earlier [See II.2.] you can access a record that has been removed:
-> via tree in active display 976 ->
As usual, the returned prompt indicates that the command was successful: the tree version of record 976 is now in your active file.
You might decide, after examining the tree copy of record 976, that you did not want to remove it after all. Because the removal request is delayed till the file is processed, it can be "unqueued", i.e., withdrawn from the deferred queue:
-> unqueue 976 -> in active display 976 -OK to clear? yes ->
Since the error message "-No such record" did not appear, the record 976 must once again be a record that exists in the subfile.
The UNQUEUE command has the same syntax as the REMOVE command:
UNQUEUE key
where "key" is the key value of the record to be dequeued.
The UNQUEUE command may also be used to withdraw ADD or UPDATE requests. If you have added a record earlier in the day that you decide later should not be added, you may issue a UNQUEUE command (or a REMOVE command) to withdraw it. Similarly, if you update a record by mistake, you can withdraw the updated version by issuing the UNQUEUE command.
Unqueuing a record counts as a transaction request, so you cannot use the UNQUEUE command to unqueue any update request except the most recent one for that record, even though earlier update requests may still be in the deferred queue. The DEQUEUE command may be helpful in that situation.
The DEQUEUE command followed by the key of a record can be used to dequeue not just the last add or update request for that record, but every update request that has been made for that record since the file was last processed. Note the difference between DEQUEUE and UNQUEUE: DEQUEUE "key" removes every update request for that record from the deferred queue, whereas UNQUEUE "key" merely removes the most recent request.
Occasionally you may make a mistake such as unqueuing an added record you wanted to keep or updating by accident a record you have already updated. SPIRES keeps a copy of each added and updated version of a record in the deferred queue, no matter what commands (UPDATE, MERGE, REMOVE, UNQUEUE or DEQUEUE) may have been issued to supersede that copy. Thus, if you discover the mistake before the file has been processed, you may access the correct version of the record, using Global FOR. [See IX.3.]
Though many other capabilities of SPIRES can be exploited by the BLOOD DONORS subfile user, the discussion of the basic searching and updating language in the previous chapters has shown you two of the most common uses of a subfile -- online searching and maintenance of a data collection. But a data base may be used for many other purposes as well. The BLOOD DONORS subfile, for example, could also be used to generate mailing labels, to create phone lists of potential donors with specific characteristics, to provide an online phone directory, and to create reports on the amount of blood donated in a specific time period or place or on the blood donors themselves.
When you are creating a data base, you should try to determine what capabilities you will need from SPIRES, i.e., how your subfile will be used. Naturally, such decisions will affect the design. This chapter will discuss some factors you should consider as you design your SPIRES data base.
Not all collections of data are appropriate candidates for SPIRES files. Generally speaking, if a data collection can be divided into similar groups of data ("records") about individual objects or people, it could be made into a SPIRES data base. For example, a data collection of names, addresses and blood types for a group of people might make a good SPIRES file.
But there are some practical matters to consider too. In some cases, a WYLBUR data set that can be "searched" using an associative range on a LIST command (e.g., LIST 'AB+' AND 'MENLO PARK' to find donors with type AB-positive blood living in Menlo Park) might be an easier and cheaper "data base system" to use than SPIRES.
Some people creating SPIRES files have very structured data, such as laboratory measurements, where most records look very much alike, containing numeric elements or elements whose values are restricted to only a few values, such as YES or NO. Other people have unstructured data, such as correspondence, where the type of element values may vary a great deal from one record to the next. SPIRES is very suitable for either type of data; most data bases, in fact, contain a mixture of these two types.
In most cases, at least a couple of the following conditions should be true if you are going to create a SPIRES file:
- You have an amount of data that is unwieldy to use without something to manage it. For instance, if there were only two blood donors and no more were expected, creating a SPIRES file would not be worthwhile. This factor relates not only to the number of records for which you have data but also the number of data items for each record; even if you have data for 1000 donors, if the information you collect for each donor is only a name and phone number, keeping the data in a WYLBUR data set would probably be as effective and would certainly be cheaper.
- You have data that is changed regularly or changed by several people at once. The typical SPIRES file is either a data base where the separate goal records are changed frequently (the number of pints donated for a specific person, for example) or a file where the goal records seldom change but where so many records are being added that it takes several weeks or months (or forever) to build the complete file (a library's card catalog, for instance).
- You need a data base management system to help you collect your data and keep it organized. If you were going to collect your data in a WYLBUR data set, you would have to remember exactly which type of data to include and where it should be placed. SPIRES, on the other hand, can prompt you for the specific data elements for each record and it determines where they are stored. SPIRES can also insure data validity -- it can verify that the value entered for a given element is within a certain range or is a certain length or is or is not one of a limited set of values. These two features are among the most important reasons people use SPIRES to manage their data.
- You need the data indexed in a variety of ways. SPIRES's efficient indexes can help you locate or arrange groups of records quickly using a simple-to-learn and -teach command language.
- You need to display the data in a variety of ways. A goal record may be examined through different formats, allowing users different views of the data. In the BLOOD DONORS subfile, you have already seen a format used to create mailing labels. Another format might list a donor's name, followed on the next line by the date and location of each donation. SPIRES allows you to format your data practically any way you might wish.
- Certain security constraints must be enforced for your data. For example, you want some users to be able to update the records but others to only examine records. Or you want some data elements or some records to be seen or changed only by certain users. SPIRES offers many different levels of data base security.
- You need to keep track of how your data is being used or changed. SPIRES provides ways to examine all changes to the records in a subfile and all commands issued against the subfile. (In the latter case, i.e., if the file owner has turned on "command logging" for the subfile, that fact is announced to the user when the subfile is selected.)
- At a future date you might need to change the type of data collected. If you decide later that you want to add some new elements to each goal record, it can be done without rebuilding the file in most cases.
If, say, fewer than three of the above conditions are true for your application, a SPIRES file may not be appropriate. Remember that your SPIRES consultant can further assist you in making this important decision.
Assuming that the answer to the question posed at the beginning of this section is "Yes", we will proceed to specific questions of file design.
You will usually have an intuitive idea of what the goal record should represent. [See I.2.] For example, suppose you decide you want to keep track of blood donors; having each goal record in your subfile represent one blood donor seems obvious. However, why not make each contribution be the goal record? Each goal record would have the name and address of the donor, as well as the blood type, and so forth.
There are several reasons why the donors -- as opposed to the donations -- make better goal records. First, less information is stored redundantly. If most donors make more than one donation, then their names and addresses would be stored multiple times in a DONATIONS subfile, taking a great deal of space. Moreover, when a donor's address changed, multiple records would need to be updated in a DONATIONS subfile, rather than the one in a BLOOD DONORS subfile.
But most importantly, the main purposes of the data base seem to warrant donor goal records: mailing labels, phone directories, reports on the blood donors, and so forth. All of those are "about" the donors rather than specific donations. Each of these end-products (reports, labels, etc.) could be considered as a collection of condensed goal records from the BLOOD DONORS subfile, with selected data formatted in specific ways. Although it would be possible to generate such end-products about donors from a subfile of donations, the programming would be more complicated and less direct, since the desired individual records would not match the goal records of the subfile. (It is also possible to have a single SPIRES file where donors are the goal record for one subfile and donations are the goal record for another subfile. Multiple subfiles within a file, with the data being shared across subfiles, are not uncommon in SPIRES, but are beyond the scope of this document. See "SPIRES File Definition".)
Consider also the type of search criteria people using the subfile will have and the type of data they will expect in return. For example, the blood bank gives the criteria "We need donors with type O-positive blood who have not donated in the past 60 days". Since the data requested is information about donors, it makes sense that the goal records should represent them.
Again, your SPIRES consultant can help you choose the proper alternative if you need assistance choosing your goal record.
The answer to this question will be based on what types of data you have collected or can collect for each goal record. Remember that you are paying for storage space on the computer for the elements you are keeping. Thus, be sure that the data you are storing is data that you will need to use again. You may be able to collect the names of each donor's children, but such information is probably not relevant to your use of the subfile.
Try creating a list of the elements you want in your goal records. Remember