******************************************************************
* *
* 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 that every element need not occur for every goal record. Here is what the first list of elements for BLOOD DONORS might have looked like:
NAME Donor name
ADDRESS Donor's address
CITY City of residence
STATE State of residence
ZIPCODE Zipcode of residence
PHONE NUMBER Phone number(s)
BLOOD TYPE Type of blood donor has
CALL? Whether or not donor can be called
about contributing
DONATION DATE When a donation was given
DONATION PLACE Where a donation was given
TOTAL GIVEN Total number of pints contributed
COMMENTS Anything we left out that's relevant
As you have seen in records of the BLOOD DONORS subfile, element values can be short specific codes (such as the BLOOD.TYPE, restricted to one of eight short values) or can be free-form strings, such as the COMMENTS element. Thus, an element value could group together several small pieces of information in a value. On the other hand, that element could be split into several smaller elements. For instance, why did we, the file designers, choose to split the address into the separate components ADDRESS, STATE, CITY and ZIPCODE? Couldn't we instead have each occurrence of ADDRESS represent a single line of an address, as on a mailing label:
NAME = Blut, Werner; ADDRESS = 5225 Plasma Place; ADDRESS = Apt. A; ADDRESS = Redblood City, CA 94007;
That is certainly a reasonable alternative, except that we may need to sort records (using the SEQUENCE command) by the values of the city or zipcode, as shown earlier. [See I.5.2.] When a portion of a data value will be used for computation or sorting purposes or will be separately indexed or displayed, it must be a separate element. [See the discussion below on "Structures".]
Specific rules for choosing the names of the elements will be given later. [See IV.6.1.] Below are other questions you need to consider in choosing your elements.
One element in each goal record is always required to occur -- the key element. Not only must each record have exactly one occurrence of the key element, that value must be unique in the subfile; no other goal record may have the same key value. Normally the key is an element whose values will be fairly short, i.e., a few characters long, but this is not a requirement. Choosing one of the elements as a key gives you an automatic index on that element: using Global FOR, you will be able to process the goal records in their key order without having to sort them first. That can be a significant savings over the lifetime of your file.
Often the key element is a code of some type. For example, the public subfile PEOPLE uses I.T.S. account numbers as record keys. An inventory subfile might use unique stock numbers as keys.
If no element seems to be a "natural key", you can have SPIRES assign a slot key to each goal record. When a record is added, SPIRES assigns it the next available integer in the series 1, 2, 3, etc. as the key value.
The only possible natural key for BLOOD DONORS would be NAME, but a name element is not usually a good choice. The values can be long, and there is no guarantee that two donors would not share the same name. A slot key is preferable here.
As mentioned before [See I.5.] related elements are often bonded together into multiply occurring structures. For instance, rather than have the record contain a list of dates when blood was donated, followed by a list of places where blood was donated, we want the record to have groups of donation information, telling us for each donation where and when it was made. This is achieved by grouping the elements into structures.
Another time that structures may become necessary, mentioned above, is when a particular portion of a data value needs to become a separate element for indexing or sequencing reasons. Suppose that at first we decide to make DONATION an element whose values can be something like "Blood Bank on 3/18/81". Realizing that the two individual parts of this value, the location and date, need to be handled as separate elements and that the DONATION element can occur more than once, we should convert the DONATION element into a structure containing the LOCATION and DATE elements. That ensures that the location and date for each donation will be kept together as a group of elements and allows the two parts of DONATION to be used for separate sorting and indexing. Here's another example: if a person lived at more than one address, then it would make sense to make the address, with the city, state and zipcode elements, into a structure to keep each complete address together within the record.
If there is one element in the structure that will always occur if the structure occurs, it can be named the "key of the structure". For example, both LOCATION and DATE could be required to occur. There are two important advantages to choosing a structure key:
Specifically, this question asks you to consider the types of values that your elements will have and decide where they fit in these common types:
DATE such as "1 July 1980" or "3/79"
INTEGER an integer such as 0, 1, 90365, -47
DECIMAL a number such as 0, 1.643, 7.57E24, -9.8345E-54
DOLLAR a dollar-and-cents figure, such as $1.25, $17543,
$-3.13
SLOT to cause SPIRES to provide a unique integer value
(available only for the key)
NAME a person's name, such as "Robert E. Lee" or
"Kreskin, Amazing"
ENCODE one of a limited number of declared values
YESNO either YES or NO
TEXT a free-form string, such as an address or a comment
STRUCTURE an element that contains other elements; each of
the contained elements will be one of the above
types as well.
By selecting a type for each element, you tell SPIRES to ensure that only certain types of values be allowed for a given element; for example, only the values Y, YE, YES, N, and NO, regardless of case, are allowed for a YESNO-type element. Any other values entered for such an element during record input would be rejected, causing an error message to be displayed.
Other reasons for choosing a type for each element are:
- to promote efficient storage. For INTEGER, DECIMAL, DATE, DOLLAR, ENCODE, YESNO and SLOT elements, SPIRES converts the input value into special forms that require less storage space than the unconverted forms would.
- to allow special and proper handling of search requests. Date and personal name indexing only work when DATE and NAME elements are so specified.
- to permit proper sorting. Elements with numerical values, as well as DATE and NAME elements, that will be used to sequence records should always be specified with their proper types; otherwise, inefficient and invalid sequencing may occur. This is an important point to understand. Compare the sorting of the values "2" and "11" to the sorting of the values "02" and "11". In the first case, SPIRES, looking at the first character of each of the strings, would place "11" before "2", because the first character of "11" is "1", which precedes "2" in sort order. In the second case, the value "02" would precede "11" since the first character of "02" precedes the the first character of "11". Since you do not want to have to precede numerical values with some number of zeroes, SPIRES handles this type of process in a similar way automatically when the type is specified properly.
Let's choose the types for the BLOOD DONORS elements:
element type ID SLOT NAME NAME ADDRESS TEXT CITY TEXT STATE TEXT ZIPCODE TEXT PHONE NUMBER TEXT BLOOD TYPE TEXT CALL? YESNO DONATION STRUCTURE DATE DATE LOCATION TEXT TOTAL GIVEN INTEGER COMMENTS TEXT
We added a new element to represent the slot key, called ID, and created the DONATION structure. We didn't treat the phone number as an integer because we want the value to be able to include hyphens and because we may want to include "text"-type information such as the type of phone ("home", for example).
You may also wonder why we decided to make ZIPCODE a TEXT element rather than an INTEGER. The answer lies in the "code" part of the word "zipcode". A zipcode is a five-character code, whose five characters happen to be digits. The zipcode 00354 does not represent the number "354"; the leading zeroes are an important part of the element's value and we want them to be retained. We will see how to handle fixed-length numerical codes like a zipcode later. [See V.3.2.7.] However, suffice it to say for now that ZIPCODE should be a TEXT element.
The element BLOOD.TYPE could be an ENCODE element instead of a TEXT one since its values are limited to a set of eight. However, a limitation of ENCODE elements that will be discussed later makes it preferable to consider it a TEXT element. [See IV.6.4.3.]
Other element types are also available, e.g., a type for elements whose values are clock times. See the SPIRES manual "File Definer", section 5.1.5, for information about these other types.
Those elements whose lengths we can specify exactly can be stored more efficiently than others. That length, in bytes, is declared when we create the file definition. (A byte is the amount of storage space required to store a single character; the value "element-value" is 13 bytes long.) Usually this decision depends on the element type chosen above. The length chosen corresponds to the length of the value to be stored after any special conversions determined by the type, rather than to the length of the input value necessarily.
If the type is: Then the length will be: DATE 4 bytes INTEGER 4 SLOT 4 DOLLAR 4 ENCODE 1 YESNO 1 NAME, DECIMAL or TEXT undetermined
Except for the NAME, DECIMAL and TEXT types, the types will always use a fixed number of bytes. That amount of room will always be reserved for them (and always be filled by them) when they occur in the goal records.
Usually you do not need to concern yourself about length, unless you choose to. The appropriate length will always be supplied by the File Definer, except for NAME, DECIMAL and TEXT elements. Generally you cannot determine exactly how long a NAME or TEXT element will be. However, if you can, that information may be valuable. [See V.3.1.] A length is seldom declared for a DECIMAL element.
If you know exactly how many times an element will occur when it occurs in the record, you can make your file definition more efficient. Many elements will only occur once in the BLOOD DONORS records:
NAME CITY STATE ZIPCODE CALL? BLOOD TYPE LOCATION - 1 time per occurrence of the structure DATE - 1 time per occurrence of the structure TOTAL GIVEN
The other elements (ADDRESS, PHONE NUMBER, DONATION) may occur more than once. Generally, if the element may occur more than once, it is not important (or not even possible) to specify exactly how many times it will occur.
You may want to guarantee that some elements appear in each record, i.e., that they are required to occur at least once; other elements may be declared as optional. The key is always required. No other elements need be declared as required. (To clarify terminology, from this point on we will talk about the element categories "Required" and "Optional", capitalizing the first letter.)
It is possible that a specific Required element may have to occur, say, exactly three times, depending on rules we may choose for it. However, by declaring it a Required element, we are telling SPIRES that it must have at least one occurrence. This helps insure the integrity of the data by guaranteeing that records contain certain desired elements. [See II.1.3.]
SPIRES will store the elements in the goal record beginning with the Required elements, followed by the Optional ones. Remember that the order in which the elements are stored is the order in which they will be displayed in the SPIRES standard format and the order in which the $PROMPT format will prompt for them. This is important to remember when you want to use the $PROMPT format for data entry; you may want to declare most of your elements optional so that you can more easily control the prompting order. Unless your subfile will contain thousands of records, you will probably realize little savings by declaring elements Required rather than Optional. If such a declaration affects the input order adversely, the inconvenience may quickly nullify any storage savings gained.
For the BLOOD DONORS goal record, we will keep the $PROMPT format in mind since most of our data entry will be done with it. Hence, we will make the NAME, ADDRESS, CITY and STATE elements required, but none of the elements from ZIPCODE down. (A donor may not know his or her zipcode or blood type, for instance, and we would not want the record rejected because of that.)
Three other element categories are "Fixed", "Supplied" and "Virtual". The Fixed category is similar to Required, but requires that you know the exact length and number of occurrences for each element so declared. Technically speaking, a slot key is automatically considered Fixed. However, since the system supplies its value, it is listed on the SHOW FORMAT INFORMATION command as "supplied". More information about Fixed elements can be found in the manual "SPIRES File Definition", section B.1.3.
A virtual element is an element whose value is derived from other element values in the record but is not itself stored in the record. For example, we could have a virtual element called FIRSTNAME.FIRST, which, when displayed, showed us the value of the NAME element except with the donor's first name first, rather than the last name first. SPIRES does not need to store a value in the record for FIRSTNAME.FIRST, because it can get that value by manipulating the NAME element. [See section C.11 of the manual "SPIRES File Definition" for more information about virtual elements.]
You may index any of the elements in your goal record. Be aware that each index you choose to create represents redundant storage of information, and that costs money. (Consider the file cabinet example. You have to maintain more drawers of file folders than just the top drawer containing the "goal" folders, but the information in the index folders is taken from the goal folders, meaning duplication of data.) An index that is used regularly will help you find goal records very efficiently and cheaply. However, if you never use it, it is wasting your money to keep it.
Consider how you expect the subfile to be used for searching. If you (or other subfile users) would use the index frequently, it will probably be worthwhile. If you only use it irregularly, say, once every couple of months, you probably should not index that element. Remember, you can still locate records by non-indexed criteria, using Global FOR. [See VII.]
Elements may be in separate indexes, or you can put the values of several different elements into one index. An example of the latter case might be an "address" index that included the elements ADDRESS, CITY, STATE and ZIPCODE. Only elements of the same element type may be combined into a single index. (Note: Had we made ZIPCODE an INTEGER element, it could not be indexed with the others as described above.)
Adding and removing indexes to a subfile is usually not too difficult to do, so if you are unsure of whether or not an index will be valuable, go ahead and try it. Especially in the early stages of file development, you may want to change your file definition, so feel free to experiment at this point. [See V.4.]
Here is the basic layout of our BLOOD DONORS goal record. Some fine tuning will occur as we create the file definition in the next two chapters.
element characteristics
ID SLOT, key, 4 bytes long, occurs exactly once
NAME NAME, indexed, required to occur once
ADDRESS TEXT, required, may occur more than once
CITY TEXT, indexed, required to occur once
STATE TEXT, required to occur once
ZIPCODE TEXT, length 5, storage, optional, may occur once
PHONE NUMBER TEXT, optional, may occur more than once
CALL? YESNO, indexed, optional, may occur once
BLOOD TYPE TEXT, indexed, length 1, 8 possible values,
optional, may occur once
DONATION STRUCTURE, optional, may occur more than once
DATE DATE, index, length 4, optional, may occur once
LOCATION TEXT, index, optional, may occur once
TOTAL PINTS INTEGER, index, length 4, optional, may occur once
COMMENTS TEXT, optional, may occur more than once
The next step in building your SPIRES file is to use the File Definer to create a file definition. The File Definer subsystem was developed to make the file definition process easier. Using its own language, which is basically a subset of the standard SPIRES file definition language, it takes your description of the subfile and converts it into a complete file definition. The File Definer language is very concise, with single words incorporating standard choices and assumptions normally made in a file definition but which must be stated explicitly in it. One line of File Definer input may turn into two dozen lines of file definition code.
Chapters III through V of this manual serve as a primer to defining files with the File Definer. This chapter covers the basic instructions for using the File Definer and explains the most common keywords and attributes used to create a file definition. The next chapter describes a few of the more advanced features of the File Definer and should be considered optional if the features you need for your file are adequately covered in this chapter.
For more details about the subsystem, please refer to the manual "File Definer".
This section will discuss how to enter and return from the File Definer subsystem, and what commands can be issued within it.
To enter the File Definer, you must be in SPIRES. You then issue the command ENTER FILE DEFINER:
-> enter file definer * ENTERING FILE DEFINER :->
The new prompt, ":->" (or ":-?" if UPPER is set), indicates that you are in a subsystem of SPIRES. In this command mode, you may issue any WYLBUR, ORVYL or SPIRES command you wish, as well as other File Definer commands.
To return from the File Definer to SPIRES, issue the RETURN command:
:-> return ->
Creating a file definition in the File Definer involves three steps:
The INPUT ACTIVE command reads the contents of your active file, which are presumably "input lines" of an input file describing your subfile. The File Definer will scan each input line for proper syntax and will reject the input file if an error is detected. As input lines are successfully processed, they are placed in an internal storage area where they remain till cleared.
The basic syntax of the command is:
INPUT ACTIVE [QUIET]
Here is a simple example:
:-> collect
1. > subfile blood donors
2. > end
3. > *** <---ATTN/BREAK is pressed.
:-> input active
: 1. Input> subfile blood donors
: 2. Input> end
:->
Line 1 of the input shows a very simple input line: a keyword, SUBFILE, followed by a value, BLOOD DONORS. Input lines will be discussed in detail in the next section. [See IV.2.]
The keyword END signals the end of the input file, unless you are entering information about elements in a structure. [See IV.6.4.9.]
Notice that the File Definer echoed each line of the input file back to the terminal as it was read from the active file. By including the QUIET option on the command, you can suppress the echoing. If an error is encountered, an error message will be displayed and processing will stop. You should make the correction to the input file in your active file and then issue the INPUT ACTIVE command again; an error found by the File Definer when an INPUT ACTIVE command has been issued causes all of the input lines read before the error to be discarded by the File Definer (they remain in your active file, however).
Once you have entered the input file, you tell the File Definer to generate the file definition by issuing the GENERATE command:
GENERATE [CLEAR]
Since the file definition is placed in your active file, SPIRES will ask if it is "OK TO CLEAR?" if your active file is not empty and you do not include the CLEAR option. [See IV.7.] Since your active file may still have your input file, you will probably want to save the input file first before allowing SPIRES to clear your active file. (Alternatively, you can get another copy of your input file using the IN ACTIVE SHOW INPUT command, described below).
This command will show you the input lines entered after an INPUT ACTIVE command. The IN ACTIVE prefix will place the input file into your active file. (You could modify it and re-enter it with the INPUT ACTIVE command.) Note that the END input line will appear at the end of the input file, even if you forgot to enter it yourself.
The CLEAR INPUT command will discard all input lines stored by the File Definer. If you want to enter a new input file, you must issue the CLEAR INPUT command before the INPUT ACTIVE command; otherwise, the File Definer will try to append the new input file to the end of the old one.
The File Definer will automatically issue a CLEAR INPUT command when an error is detected during the input process.
The HELP command will display a list of commands specific to File Definer, along with brief descriptions of their function.
The syntax of each input line is:
keyword [=] [value]/ attribute [=] [value]/ attribute [=] [value]...
For example,
ELEMENT = address ELEMENT address/ TEXT
All input lines should begin with a keyword; if a keyword is not included, the keyword ELEMENT is assumed. Only one keyword may appear on a single input line. A keyword may be followed by a value, separated optionally by an equals sign. Often the value is a name: "ELEMENT = address". The keyword and its value may be followed by a slash (/), followed by attributes describing the particular keyword: "ELEMENT = address/ TEXT". These attributes may themselves have values. Each attribute is separated from the other by a slash as well. Spaces around the slashes are optional; traditionally, however, they are placed after slashes to make the input more readable. That convention will be observed here.
An input line may be no longer than 160 characters. To continue an input line onto another line, simply end the line with a plus sign (+). [See IV.7 for an example of this.]
Note that the case, whether upper, lower or mixed, of the keywords and attributes is not significant. However, the case of values (for example, customized error messages for the MSG attribute) may be significant. In our examples, we will put the File Definer keywords and attribute names in uppercase, but in general put the values we supply in lowercase for clarity.
All File Definer attributes and keywords described here may be abbreviated to their first three characters, if desired.
Basically there are three parts to an input file:
The input lines for these parts are described in the next few sections. (Remember that some extra features for them are discussed in the next chapter.) The final section of this chapter will show a complete input file and demonstrate the procedure for generating a file definition from it. [See IV.7.]
File definitions begin by stating a file name, by which SPIRES can identify a file uniquely. As you will see in the next chapter, a file definition is itself a record in a SPIRES subfile, and so the file name serves as the unique key value for the file definition as a goal record. In the File Definer input, the FILE input line may provide the name for the file definition. It may also include information about you, the author of the file definition.
The FILE keyword begins the line that specifies the file name and the characteristics of the file identification section of the file definition that will be generated. Though this line usually begins the File Definer input file, it may appear anywhere. The file name consists of your account number, followed by a period, followed by a name with no embedded blanks:
FILE gg.uuu.any.name/ attribute...
The file name, including your account number prefix, may be no longer than 21 characters in length ("gg.uuu." plus fourteen characters). By default, if no name is specified (as shown below), the File Definer will name the file after the first subfile name declared in a SUBFILE line. [See IV.4.]
FILE/ attribute...
The name of your file must be unique among your files; no other file under your account may have the same name.
This attribute has a value that should represent your name and phone number. It should be included in all file definitions so that you can be contacted by the SPIRES system staff in case of problems:
FILE/ AUTHOR John Klemm, 497-4420
The FILE statement for the BLOOD DONORS subfile, assuming we are going to let the File Definer name the file, will be the above example. Other attributes affecting the file may also appear on the FILE statement. Some of them are discussed in the next chapter, "Advanced File Definer Techniques". [See V.1.]
The SUBFILE keyword usually appears right after the FILE input line, though it may be placed anywhere in the input file. The SUBFILE input line may include an attribute that names the accounts that can select and use the subfile.
The File Definer requires you to supply a subfile name. If you omit it here, the File Definer will prompt you for it before generating the file definition. The subfile name must be no longer than 32 characters; it may contain embedded blanks and the special characters period (.) or hyphen (-). (Note: If no value is given for the FILE keyword [See IV.3.] the File Definer will use the subfile name to construct a file name; because of the length limit of 21 total characters for a file name, you should limit your subfile name to 14 characters if you want the File Definer to create a file name for you.) The syntax is:
SUBFILE subfile-name
Possibly, if you are the only person who will use your subfile, you will not need to add anything more to this keyword. If this is all you specify, the File Definer will give your account and no others access to the subfile named. Other attributes, such as that described below, may be used, however. Also, some of the other attributes for the SUBFILE input line are discussed in the next chapter. [See V.2.] For example, you can control how other accounts may use the subfile: whether only to display records or to add and update records. In addition, this section may also include a subfile explanation (which the user may examine with the "SHOW SUBFILE DESCRIPTION subfile-name" command), and may specify a format that should be set or commands that should automatically be issued when the subfile is selected.
This attribute specifies which accounts may select the subfile. If no other security attributes are specified, these accounts will be allowed to add and update records as well as search for and examine them. [See V.2.1.] The syntax is:
ACCOUNTS gg.uuu, gg.uuu...
where "gg.uuu" represents an account number or group of account numbers. By specifying a group code, followed by four periods, you can request that a group of accounts be given access. To give all accounts in group GQ access, you would enter "GQ....". To allow a subfile to be accessed by the public, specify PUBLIC for the account. For example,
SUBFILE blood donors/ ACCOUNTS gq.jnk, xw....
indicates that the account GQ.JNK and any account in group XW may select the subfile.
The GOAL keyword signals the beginning of the goal record description. It is optional, but is usually included because of its RESULT attribute. That attribute specifies an external name to be displayed in search result counts, such as "-Result: 153 DONORS". The word DONOR (minus the "S" that SPIRES automatically appends) is the value for the RESULT attribute. The RESULT attribute's value must not contain embedded blanks and must be less than 16 characters long.
The complete GOAL input line is:
GOAL/ RESULT donor
The next input lines name and describe your goal record elements. Element descriptions in our file definition will begin with the keywords ELEMENT or KEY.
In this section, we will take our element list from the end of the last chapter [See III.4.] and translate our specifications into the File Definer language described here.
The keywords ELEMENT and KEY are followed by element names:
ELEMENT element.name, alias, alias/ attributes ...
where "element.name" is the "primary mnemonic", the name that will appear with the element value in the standard SPIRES format. The aliases are the other names, usually short forms of the primary mnemonic, that can be typed instead of the primary mnemonic; they are displayed along with the primary mnemonic by the SHOW ELEMENTS command.
All element names, whether primary mnemonics or aliases, must follow the same rules:
- they must be no longer than 16 characters;
- they must contain no embedded blanks;
- they may contain only alphanumeric characters or the characters period (.), hyphen (-), or underscore(_). Those three special characters are often used as substitutes for blanks in element names, with the period being preferred.
Several of our elements as specified at the end of the previous chapter do not have acceptable names. Also, we should probably assign aliases to some of the longer ones. When an element is indexed, the File Definer automatically assigns all of the names for that element to be search terms that appear in the SHOW INDEXES command. [See I.4.] Here is a revised list of element names for the BLOOD DONORS goal record. Note that a recommended standard for aliases is the first three characters of the primary mnemonic.
ID NAME, DONOR.NAME, NAM ADDRESS, ADD CITY, CIT STATE, STA ZIPCODE, ZIP PHONE.NUMBER, PHO, PHN CAN.BE.CALLED, CAN, CAL BLOOD.TYPE, BLOOD, BLO, BLD DONATION, DON DATE, DAT, DATE.GIVEN LOCATION, LOC, WHERE.GIVEN TOTAL.PINTS, TOT, PINTS, PINTS.GIVEN COMMENTS, COM
Generally the first element specified is the key of the goal record. If the key is a slot key, this statement is very simple:
KEY id/ SLOT
In the example, ID is the name of the key element. [See III.3.1.]
If the key element is not a slot key, the SLOT attribute is replaced by the other relevant attributes as determined by the possibilities discussed in this section:
KEY record-number/ INTEGER
Here the key element is called RECORD-NUMBER. It is an integer that will be provided by the user entering the data. [See IV.6.4.6.] If the element type will be NAME, TEXT or STRUCTURE, and the REQUIRED statement is necessary, then place the KEY statement after the REQUIRED statement. [See IV.6.3.]
If you have decided to make all of your elements except the key Optional, you will not need these keywords. [See III.3.6.] If you decide to have a Required group of elements, they must be declared before the Optional ones. They are preceded by an input line with just the keyword "REQUIRED":
REQUIRED
After the Required elements comes an input line with the OPTIONAL keyword on it, followed by the input lines for the Optional elements.
REQUIRED ELEMENT name, nam/ NAME OPTIONAL ELEMENT comments, com/ TEXT
A key is automatically considered to be a required element.
Each of the elements in the goal record will have a particular type attribute. The most common types were discussed in the last chapter. [See III.3.3.] The element type is specified in the input line for each element. If no element type is declared, the default type is TEXT.
KEY id/ SLOT ELEMENT name, nam/ NAME ELEMENT address, add/ TEXT
Only one type attribute may appear for each element. The File Definer will add appropriate element processing rules to the element definition that will test the incoming element value for proper form and, in some cases, convert the value to a more efficient form for storage. [See V.3.2.]
The following sections briefly describe the effects of the various types.
TEXT indicates that no special processing or checking should be done to the element value because of its type. (Other processing may be added in the form of other attributes later in the input line.) [See IV.6.5.] If TEXT is the only attribute specified for an element, any input value will be accepted for that element.
This attribute will cause SPIRES to convert personal names to a standard form for storage. Values will be stored and output in the form LAST, FIRST MIDDLE, as in "Sousa, John Philip". This order allows you to sequence such element values by the last name; it is required if the element values are to be indexed. [See V.3.2.7 to see how to put the name in FIRST MIDDLE LAST order on output, if desired.]
The ENCODE attribute is specified when you can restrict the number of values allowed for that element to a reasonable number. (In the File Definer, the number is limited to about 50, depending on the lengths of the input values. In the standard SPIRES file definition language, the limit is 256 values.) SPIRES will convert the input value into a one-byte code for storage, based on the position of the value in the ENCODE string:
ENCODE value, value, value...
For example,
ELEMENT blood.type/ ENCODE A+, A-, AB+, AB-, B+, B-, O+, O-
The ENCODE attribute is followed by the list of values to be allowed and encoded. For the BLOOD.TYPE element, the eight blood types were specified. When a value is input for the element, SPIRES verifies that it is one of the allowed values; if so, it is converted into a one-byte value. If not, an error message is displayed, and the value is rejected.
Note that if the last value had been "O+", the File Definer would have been expecting that input line to continue on the next line. (Remember that a plus sign at the very end of an input line indicates continuation.) A plus sign may appear anywhere else on the input line without affecting the File Definer. However, the special characters comma (,) and slash (/) within values to be encoded must be treated specially: the value they are within must be surrounded by quotation marks (") or apostrophes ('). [See V.3.2.] For example:
ENCODE ab, 'a/b', "a,b"
An encoded value is sensitive to the case of the input value. For instance, the input value "a+" would be rejected since it is not "A+". The input value will be converted to uppercase if you add a CAPITALIZE attribute. [See IV.6.5.1.]
If you index an encoded element and then try to BROWSE the index [See I.4.] you will get the values as they are internally encoded rather than the values that are represented. Because of this limitation, we will make the BLOOD.TYPE element a TEXT element rather than an ENCODE one. There is another method available for limiting the possible values for an element, and we will use that instead later on. [See V.3.2.4.] Generally speaking, if you plan to index the element, you may not want to choose ENCODE.
Similar to ENCODE, this attribute causes SPIRES to permit only certain values for the given element: Y, YE, YES, N, or NO.
ELEMENT can.be.called, can/ YESNO
Here case is not important; the input value will automatically be converted to uppercase before being checked against this list. If the value is not one of these, an error is caused and the value rejected. If it is a permitted value, it is converted to either Y or N, a one-byte value, for storage. On output, the value is converted to either "Yes" or "No".
When a YESNO element is indexed, the search value in the FIND command may be any one of the five permitted values.
The DATE attribute will cause SPIRES to test that the value is a valid date and if so, to convert it to a four-byte value for storage. Values on output will be displayed in the form "MM/DD/CCYY", where "CC" is suppressed if it is "19", e.g., "07/01/54". [See V.3.2.7 to learn how to get other forms for output.]
ELEMENT date, dat, date.given/ DATE
The DATE attribute can also have either of two values:
DATE [ADD|UPDATE]
If DATE is followed by ADD, the element value will be set to the current date when the record is added, if no other value is supplied by the user. If DATE is followed by UPDATE, the element value will be replaced by the current date whenever a record is added or updated; any user-supplied value is discarded.
Many file owners want to have DATE.ADDED and DATE.UPDATED elements in each goal record, so that it is easy to see how many records have been added or updated since a given date or see when a particular record was added or last updated.
The INTEGER attribute specifies that the value should be verified to insure that it is an integer within the range -2,147,483,647 to 2,147,483,647 (inclusive!). If so, then the value is converted into a four-byte value for storage. If not, an error message is displayed and the value rejected. On output, the value is reconverted to its string form for display.
The DECIMAL attribute is specified when the element value may be a non-integer number. Packed decimal conversion takes place on input. The element value is rejected if it contains unrecognizable characters.
The DECIMAL attribute is specified as follows:
DECIMAL m.n
where "m" is the number of places allowed to the left of the decimal point, and "n" is the number of places allowed to the right. For example, DECIMAL 4.5 means that an input element value may range from -9999.99999 to 9999.99999.
Warning: If you index a DECIMAL-type element, any negative values will be interleaved with positive ones in the index. That is, the number -2 would be indexed between 1 and 3. Note that this is not a problem for INTEGER elements.
The DOLLAR attribute will ensure that the value is a proper dollars-and-cents value in one of the following forms:
$D $D. $D.CC $.CC
where D is a string of digits (no commas allowed), CC is two digits, and $ is an optional dollar sign, optionally preceded or followed by a negative sign. If the value does not match one of these forms, it will be rejected with an error message. The value will be converted into a four-byte value for storage.
Values will be output in the form "$D.CC" or "$-D.CC".
This attribute indicates that the named element is a structure [See II.1.4.] and that the element input lines that follow it are elements within the structure until the END keyword appears.
ELEMENT donation, don/ STRUCTURE ELEMENT date, dat, date.given/ DATE ELEMENT location, loc, location.given/ TEXT END
If desired, an element within the structure could itself be declared a structure in the same way. (Indenting the elements within the structure is sometimes done to help make the goal record structure more clear to see; it is not required.)
If you choose one of the elements within the structure to be a key element for the structure [See III.3.2.] it should be declared in a similar fashion as the record key:
ELEMENT donation, don/ STRUCTURE KEY date, dat, date.given/ DATE ELEMENT location, loc, location.given/ text END
Below are described two commonly used "processing rule attributes". These attributes may be included on an element input line if you want the processing that they cause to be done to the element.
Processing rule attributes are explained in detail in the next chapter, along with descriptions of several others. [See V.3.2.]
This attribute causes all lowercase letters in the element value to be converted to uppercase. It is most generally useful with element types ENCODE and TEXT.
ELEMENT blood.type/ CAPITALIZE
It guarantees some conformity of the element values across records; the element value will not be uppercase in one record and lowercase in another, depending on the whims of the person entering the record. It is often specified when you want to verify that the input value is or is not one of a list of values, as for the ENCODE element type. [See IV.6.4.3.] Note that the YESNO attribute has a "built-in" CAPITALIZE attribute -- you need not specify one when you use it.
CAPITALIZE may be abbreviated as CAP.
By the way, there is a complementary attribute that changes all uppercase characters to lowercase ones: LOWER.
Sometimes an element has the same value for most of the records in the subfile. For example, many of the blood donors will live in the city of Palo Alto. We can tell SPIRES to supply the value of "Palo Alto" for the CITY element anytime no value is given:
ELEMENT city/ TEXT/ DEFAULT Palo Alto
Whenever the CITY element is omitted on input, the value "Palo Alto" will be supplied for the record. If any value is input, that value will be the one that is stored.
Specifying DEFAULT means that there will always be at least one occurrence of the element in the record.
The default value is not given to the record until "record closeout", which is when you are finished adding or updating a record and SPIRES is examining the record to make certain that it has the right number of occurrences of an element or that all required elements are present. Suppose that CITY is a Required element. You are entering a record using the $PROMPT format [See II.1.3.] and you want to let SPIRES provide the default value of "Palo Alto":
: CITY <-- return is pressed so no value is supplied Value required - enter /N to skip or // for null value : CITY /N
In the first line you tried to skip the value by pressing return, but the $PROMPT format requires that a value be supplied. At this point, SPIRES does not know that a value will be supplied later, and since a value is required, the format tries again to get one from you. Issuing "/N" will skip the prompt and not provide a value, which will be provided later during closeout by the DEFAULT attribute.
You can avoid this problem entirely by making the element optional and adding the DEFAULT attribute. The value will be supplied by SPIRES anyway when no value is input, so the element will always occur.
The OCCURRENCE attribute specifies the maximum number of times the element or structure may occur in the goal record. The syntax is:
OCCURRENCE n
where "n" is an integer representing the maximum number of times the element may occur. The SINGLE attribute is equivalent to OCCURRENCE = 1. For example,
ELEMENT name, nam/ NAME/ SINGLE ELEMENT address, add/ TEXT/ LENGTH 30/ OCCURRENCE 3 ELEMENT donation, don/ STRUCTURE KEY date, dat, date.given/ DATE/ SINGLE ELEMENT location, loc, location.given/ TEXT/ SINGLE
Note that we limited the number of occurrences of ADDRESS to a maximum of three; again we made this decision based on an external factor, the size of the address labels we wish to use, which, we will say for the sake of the argument, restricts us to only five lines of output.
If no occurrence limit is specified, the File Definer assumes that we want the element to be allowed to occur multiple times without limit. Thus, the DONATION structure, which will occur many times for most of the goal records, has no occurrence limit. However, the elements within the structure are declared singly occurring because they will each occur only once for each occurrence of the structure. [See III.3.] Since the key element of a record or of a structure is by definition singly occurring, specifying SINGLE is unnecessary on the DATE element.
This attribute is specified for those elements you wish to index. This attribute also allows you to specify that an element be indexed with another element (see below). The syntax is:
INDEX [element-name]
where "element-name" is the name of another element being indexed.
For example,
ELEMENT name, nam, donor.name/ NAME/ SINGLE/ INDEX ELEMENT can.be.called, can/ YESNO/ SINGLE/ INDEX ELEMENT city, cit/ TEXT/ SINGLE/ INDEX ELEMENT location/ TEXT/ SINGLE/ INDEX/ WORD/ EXCLUDE
Normally, INDEX appears as the last attribute on the ELEMENT input line, though it may be followed by other attributes, usually WORD and EXCLUDE.
The WORD attribute will cause SPIRES to break the value into separate words when the element value is being placed in the index. It is needed when you want an index of TEXT elements to be a word index. [See I.4.4.] Apostrophes, hyphens and underscores are deleted from the value; all other punctuation is changed to a blank. Note that this transformation only occurs in passing values to the index; the value in the goal record remains unaffected by the WORD attribute (unless it precedes the INDEX attribute).
For most indexes, there are many words that are not worth indexing. Common articles and prepositions, such as "a", "the" or "of", can be excluded from word indexes by specifying the EXCLUDE attribute. The list of words that will be excluded is: A, AM, AN, AND, ARE, AS, AT, BE, BUT, BY, FOR, IN, IS, OF, ON, OR, THE, TO, WAS, WERE. You may create your own exclusion list if you want by following the EXCLUDE attribute with the values to be excluded from the index. [See V.3.2.4.]
Most word indexes should be specified with the WORD and EXCLUDE attributes. For example, if the LOCATION element is passed to a word index with the standard exclusion list, then the value "Lynne's Pick of the Chick, Atherton" would convert to the following four values for indexing:
LYNNES PICK CHICK ATHERTON
Note that the values indexed were in uppercase; by default, SPIRES changes alphabetic characters to uppercase before placing them in an index. The search values requested in a FIND command are also automatically converted to uppercase before SPIRES compares it to the indexed values.
Most TEXT elements that are indexed specify the WORD and EXCLUDE attributes for the index; those that do not are usually elements whose values are typically one or two words, such as CITY.
If we wanted to put several elements into one index, we could do it as follows:
ELEMENT address/ TEXT/ INDEX ELEMENT city/ TEXT/ INDEX address ELEMENT state/ TEXT/ INDEX address ELEMENT zipcode/ TEXT/ INDEX address
For the BLOOD DONORS subfile, however, we have decided already that the ADDRESS, STATE and ZIPCODE elements are not worth indexing. [See III.4.]
When several elements are indexed together, all of them should share the same type. [See IV.6.4.]
Below is a re-creation of a SPIRES session in which the first version of the DONORS file definition is created by the File Definer:
-> enter file definer
* ENTERING FILE DEFINER
:-> use blood.donors.definer.input on pub009
:-> input active
* 1. Input> FILE/ AUTHOR John Klemm, 497-4420
* 2. Input> SUBFILE blood donors/ ACCOUNTS gq.jnk
* 3. Input> GOAL/ RESULT donor
* 4. Input> KEY id/ SLOT
* 5. Input> REQUIRED
* 6. Input> ELEMENT name, nam, donor.name/ NAME/ SINGLE/ INDEX
* 7. Input> ELEMENT address, add/ TEXT/ OCCURRENCE 3
* 8. Input> ELEMENT city, cit/ TEXT/ SINGLE/ INDEX
* 9. Input> ELEMENT state, sta/ TEXT/ SINGLE/+
* 10. More-> CAPITALIZE/ DEFAULT CA
* 11. Input> OPTIONAL
* 12. Input> ELEMENT zipcode, zip/ TEXT/ SINGLE
* 13. Input> ELEMENT phone.number, pho, phn/ TEXT
* 14. Input> ELEMENT can.be.called, can, cal/ YESNO/ SINGLE/+
* 15. More-> INDEX
* 16. Input> ELEMENT blood.type, blood, blo, bld/ CAPITALIZE/+
* 17. More-> SINGLE/ INDEX
* 18. Input> ELEMENT donation, don/ STRUCTURE
* 19. Input> KEY date, dat, date.given/ DATE/ INDEX
* 20. Input> ELEMENT location, loc, where.given/ TEXT/+
* 21. More-> SINGLE/ INDEX/ WORD/ EXCLUDE
* 22. Input> END
* 23. Input> ELEMENT total.pints, pints, tot, pints.given/+
* 24. More-> INTEGER/ SINGLE/ INDEX
* 25. Input> ELEMENT comments, com/ TEXT
* 26. Input> END
:-> generate
-OK to clear? yes
:-> list first
1. FILE = GQ.JNK.BLOOD.DONORS;
:->
When we issue the GENERATE command near the end of the example, the File Definer creates the file definition from our input, placing it in our active file (asking first if it is "OK to clear" since our active file is not empty; here it was "ok to clear" since we had already saved our input file as a WYLBUR data set).
If we were to list our active file, we would discover that the File Definer had generated a long file of statements, each in the SPIRES standard format "element = value;". This collection of statements is our file definition, containing a translation of our File Definer input into the language of SPIRES file definitions. The file definition is much longer than our File Definer input; the generated file definition here is about 180 lines long.
In Chapter VI, we will use this file definition to create our SPIRES file. But we are not completely finished with the File Definer yet. Remember that it is always a good idea to save a copy of your File Definer input in case you decide later to make some changes to the file definition. The changes may be as simple as rewriting an error message that you do not like; on the other hand, you may want to add new elements, or change the accounts having access to the subfile. If you were to learn SPIRES File Definition itself, you could change the file definition directly; however, most users should change their File Definer input and generate new file definitions to replace the old ones.
Our File Definer work could be done at this point -- that is, we could now proceed to Chapter VI, create our SPIRES file and begin using it. However, there were some design considerations discussed in Chapter III that we have not incorporated into our file. For example, we wanted SPIRES to generate the value of the TOTAL.PINTS element; our File Definer input file says nothing at all about that. Also, we decided that we did not want BLOOD.TYPE to be an ENCODE element, but we did want to somehow restrict the values that could be entered for that element to a set of specific blood-types. The next chapter describes some techniques of file definition that are beyond the fundamental ones covered in this chapter, including ways to handle these two requirements.
So if you are eager to create a file at this point, you may want to skip ahead to Chapter VI and return to Chapter V later. If you think of changes that you want to make to your file after reading Chapter V, you can incorporate them by following the procedures described in Chapter VI. [See VI.4.]
This chapter covers some more capabilities of the File Definer. Most of the topics discussed here describe additional attributes that can be added to particular input lines discussed in the previous chapter, such as the FILE and SUBFILE input lines. In addition, a couple of other keywords relating to element descriptions will be introduced.
The FILE statement of the File Definer input may contain attributes other than the name of the file and information about the author. [See IV.3.] Some of these attributes are described below:
If you expect any element values in your goal records to be longer than 1,024 bytes, you should code this attribute here to allow it. The value must be a multiple of eight.
FILE/ MAXVAL 4096
would allow an element value to be up to 4,096 characters long.
The NOAUTOGEN attribute is specified when you do not want SPIRES to process your file automatically each night that there are records in the deferred queue. Automatic processing does occur by default if the NOAUTOGEN attribute is omitted. This attribute is not followed by a value. Note that automatic processing only occurs when subfile modification has occurred. If no records have been added, updated or removed during the day, the file will not be processed that night. [See VII.1.]
The syntax for this statement is:
BIN = {HOLD|PURGE|nnn}
When overnight file processing occurs, a batch job is run. The output from the job comes to your bin by default. The BIN attribute may be used to send the output to another bin, number "nnn". Alternatively, if the bin number you specify is HOLD, the output will be held until you release it or purge it. Another possibility is to specify bin PURGE, in which case the output will be purged if the processing is successful; you would only get output if the file did not process properly. That is the most popular choice; note that you are only saving the printing and dispatch charges, however -- the job itself still runs.
The complete FILE statement for the BLOOD DONORS subfile will be:
FILE/ AUTHOR John Klemm, 497-4420/ BIN purge
The SUBFILE input line also has several other attributes, some of which allow you to control the way different accounts can use the subfile. [See IV.4.]
The most common requirement of subfile security (beyond restricting the accounts that may select it, which is handled adequately by the ACCOUNTS statement) is restricting some accounts to displaying records only, rather than allowing them to add and update records. Many public subfiles, for instance, allow most users only to examine records and permit only the file owner to add and update the data.
In SPIRES, this type of security is handled by "secure switches". There are more than a dozen of them, some quite esoteric. They are requested by number. The most commonly used one is secure switch 3, specified as SWITCH 3 (or SWITCHES 3):
SWITCHES n[, n, n...]
Secure switch 3 blocks all of the subfile modification commands described in chapter II as well as several other commands for those accounts specified in the current SUBFILE input line. This means that there may be several SUBFILE input lines, depending on the characteristics of the subfile for a particular group of accounts:
SUBFILE blood donors/ ACCOUNTS gq.jnk, xw.inp SUBFILE blood donors/ ACCOUNTS xw..../ SWITCHES 3
These two input lines, entered one right after the other, indicate that the two accounts GQ.JNK and XW.INP will be allowed to add and update records, but all other group XW accounts are allowed only to examine the records. No other accounts may select the subfile. The subfile name need not be the same for the two sets of accounts shown above. The first could be called DONOR.UPDATE, the second DONOR.SEARCH, for example. This indicates very clearly that the subfile is to be used for two different purposes by the different sets of accounts.
Other secure switches are available: for example, number 8 prevents the subfile user from examining records except through the set format (see below). The format may not be cleared, nor may any other format be set. In addition, other security features are available, such as allowing only certain elements to be seen or updated for a record. [See the manual "SPIRES File Definition", sections B.9.3.1, C.6.12, C.11.3.]
Other attributes below may also lead you to specify more than one SUBFILE input line, depending on which attributes you want to apply to which accounts.
A custom format may be set automatically for the subfile when it is selected, by using the FORMAT attribute:
SUBFILE blood donors/ FORMAT address.label
The custom format ADDRESS.LABEL will be set when the BLOOD DONORS subfile is selected. Usually this would be a format written by the file owner.
You may specify the $PROMPT format here; however, if you want to add any special options, not described in this document but in section D.6 of "SPIRES Searching and Updating", they should be placed in a SET FORMAT command in the CMD input line.
The CMD ("command") keyword starts a new input line that follows a SUBFILE line. The CMD input line specifies a command that should be automatically issued when the subfile is selected:
CMD command
where "command" may be any SPIRES, ORVYL or WYLBUR command. The CMD input line refers only to the last SUBFILE input line specified; thus, if you want the same sequence of commands to be issued for two groups of accounts with different subfile privileges, you have to specify the CMD lines more than once.
The CMD input line has many valuable roles. One of the most popular is to alert users about "subfile news". The file owner may want to alert the subfile's users about changes to the subfile or provide other information. If SPIRES issues a "star" command (* text), that command displays the specified text to the user when the subfile is selected:
SUBFILE blood donors/ ACCOUNT gq.jnk CMD SET UPLOW CMD * UPLOW has been set for you. SUBFILE blood donors/ ACCOUNT xw.inp CMD * Be sure to SET UPLOW before you add any records!
When account GQ.JNK selects BLOOD DONORS, the SET UPLOW command will be issued and the message "UPLOW has been set for you." will be displayed. On the other hand, to account XW.INP, selecting the subfile might look like this:
-? select blood donors * Be sure to SET UPLOW before you add any records! -?
The star command often is used in SPIRES protocols to display information to the user. [See IX.6.]
Following a SUBFILE input line, the EXPLAIN keyword begins an input line that contains text used to provide information to the subfile user. The text here is the "subfile explanation", text that will be displayed whenever someone issues the command SHOW SUBFILE DESCRIPTION. The explanation is available only to people able to select the subfile.
The syntax is:
EXPLAIN text
where "text" is the explanation desired. It follows the SUBFILE input line. You may have many EXPLAIN input lines, depending on the length of your explanation; however, unlike the CMD input line, you may not have different subfile explanations for different groups of users, unless the subfile has different names.
All public subfiles should have subfile explanations.
SUBFILE blood donors/ ACCOUNTS gq.jnk SUBFILE blood donors/ ACCOUNTS xw.inp/ FORMAT $PROMPT EXPLAIN This subfile contains records about blood donors. EXPLAIN You are allowed to add, update or remove records. SUBFILE donor.search/ ACCOUNTS xw..../ SWITCH 3 EXPLAIN This subfile contains records about blood donors EXPLAIN that you may examine.
The next few sections describe additional attributes and keywords that may be specified for individual elements.
Generally speaking, the LENGTH attribute is only used by TEXT and NAME elements. It specifies an upper and/or lower limit for the length of each input value for the element being described.
The syntax of the LENGTH attribute is:
LENGTH n[,MINIMUM|,MAXIMUM|,EXACT]
where "n" is an integer. The LENGTH value may be followed by MINIMUM, MAXIMUM or EXACT. MAXIMUM is the default; MAXIMUM means that SPIRES will reject the input value if it is longer than the length specified. MINIMUM is the opposite -- SPIRES will reject the input value if it is not at least as long as the length specified. EXACT means the input value must be exactly the length specified; otherwise, the value is rejected with an error message.
For example,
ELEMENT phone/ TEXT/ LENGTH 8, MINIMUM/ LENGTH 20, MAXIMUM ELEMENT address, add/ TEXT/ LENGTH 30 ELEMENT state, sta/ TEXT/ LENGTH 2, EXACT
The ADDRESS element is here restricted to a maximum of 30 characters per occurrence. We might decide to do this because, say, the address labels we need to create may contain no more than 30 characters per line. By restricting the STATE element values to only two characters in length, we are in effect requiring the value to be one of the "official" two-character state abbreviations. The minimum and maximum length of the PHONE element might also be specified, as in the example above, though we have chosen not to do so in our final file definition.
The description of an element in a SPIRES file definition usually includes "processing rules"; such rules specify certain actions or transformations to be applied to the element value either when it is input (INPROC) or output (OUTPROC). Such processing may involve checking the input value to make sure it is the proper length, or contains the proper characters, or can be converted into some special form for storage. It may involve supplying a default value if none is provided in the incoming record. It may involve reconverting the stored element from its compact internal form into a more readable form for display. Or it may provide customized error messages along the way if one of the other processing rules is violated.
Two processing rule attributes were mentioned in the previous chapter: CAPITALIZE and DEFAULT. [See IV.6.5.]
The processing rule attributes described in this section may be applied to the element value either on input or output. By default, they are applied only to input values. To specify that you want the processing to occur on output instead of input, you precede the attribute name with the prefix "OUTPUT,":
ELEMENT location/ OUTPUT, CAPITALIZE
This means that the element value will be stored in whatever case in which it is input but that on output it will be capitalized. The "OUTPUT," prefix specifies that the rule should apply to output values only. Note that some of these attributes, such as CAPITALIZE, if applied only to input would naturally affect output as well.
An element may have several processing rule attributes.
Several of these attributes will themselves have values (notably CHANGE, INSERT, INCLUDE and EXCLUDE). If the processing rule attribute's values contain special characters (non-alphanumeric), the following rules apply:
Processing rules sometimes have a series of values separated by commas, in which case the above rules apply to each value in the series:
ELEMENT state/ CAP/ CHANGE ' NEW JERSEY ', NJ, ' NEW YORK ', NY
The processing rule attributes are combinations of SPIRES processing rules that are used frequently. Occasionally you may need a SPIRES processing rule that is not a File Definer attribute. In such cases, you may directly request specific INPROC or OUTPROC rules for the file definition, rather than select one of the "combination packages" that the File Definer provides. We will do this for the ZIPCODE element. [See V.3.2.7.]
Generally, you should put processing rule attributes in the order in which you want them to take place during element processing. [See V.3.2.2 for the example using the ENCODE attribute.]
This attribute is most often used with TEXT elements. It replaces all groups of multiple blanks with a single blank, and it strips leading and trailing blanks as well. It is recommended for all TEXT elements unless such blanks would be significant in the value.
ELEMENT comment/ TEXT/ SQUEEZE
This attribute will change one character string, if it is found within the value, to another character string. The attribute values must be specified in pairs. The syntax of CHANGE is:
CHANGE string1a,string1b [,string2a,string2b...]
The element value is examined for the first string; if it is found, the string in the element value is replaced by the second string of the pair. The element value is then examined for the third string, if there is one, and if one is found, it is replaced by the fourth one, and so forth. This means that multiple changes may affect each other (see the example below).
If only one pair of values is used, their total length, including the comma separating them, may be up to 255 characters. If more than one pair is used, no single value can exceed sixteen characters, and the total length of all the values, including the commas, may not exceed 255 characters. If you need to change character strings longer than 16 characters, you may use the CHANGE attribute with a single pair as often as necessary in the element description.
Here is an example of CHANGE within a possible definition for BLOOD.TYPE:
ELEMENT blood.type/ CAP/ CHANGE ' POSITIVE',+, ' NEGATIVE',-/ ENCODE A+,A-,AB+,AB-,B+,B-,O+,O-/INDEX
Notice the blank space before both POSITIVE and NEGATIVE: only values with a string containing either of those words preceded by a blank will be changed. Here is how some incoming values might be affected by the processing described above:
value after CAP after CHANGE ab- AB- AB- A positive A POSITIVE A+ O NEGATIVE O NEGATIVE O- Onegative ONEGATIVE ONEGATIVE b-neg B-NEG B-NEG
Notice particularly the results of the last two examples. The value ONEGATIVE was not affected by CHANGE because no space appeared before NEGATIVE, as specified in the CHANGE list; this value would be rejected on input. The "b-neg" value would be rejected by SPIRES on input because it does not match one of the eight codes. Study the possible effects of a CHANGE carefully before you enter it in your input file.
Another noteworthy aspect of the sample input line above is the position of the ENCODE type attribute, which follows the CAP and CHANGE attributes. Though we normally put the type attribute immediately after the element names, placing it there is not required. Placing it as shown above emphasizes that the CAP and CHANGE processes should occur before the encoding does. Remember that you should place attributes in the order in which you want them to occur when an element value is processed.
Next, consider this example:
ELEM sex/ CAPITALIZE/ CHANGE MALE,M, FEMALE,F
What if the input value were "female"? After capitalization, it would be changed to FEM because of the first pair of values in the CHANGE list. Switching the pairs around, "CHANGE FEMALE, F, MALE, M" would be one solution to this problem.
The CHANGE attribute may be used to eliminate a string by changing it to a null string:
ELEMENT sex/ CAPITALIZE/ CHANGE ALE, '', FEM, F
The null string is designated by a pair of apostrophes. Though it is less straightforward, the above is another solution to the MALE-FEMALE problem noted before. The value MALE is changed to M (ALE to null) and the value FEMALE is changed first from FEMALE to FEM and then from FEM to F.
This attribute causes SPIRES to insert a character string somewhere in the element value. It is generally used in record output to add some explanatory word or phrase to the element value. For example, instead of the value "3" being displayed for the TOTAL.PINTS element, we might prefer "3 pints". The attribute's syntax is:
INSERT string,[LEFT,n|RIGHT,n|END|FRONT]
where "n" is the column in the element value at which the string is to be inserted. By default, i.e., if only a string is specified, then FRONT is assumed, and the string will be inserted in front of the element value. Specifying the END option will place the string at the end of the value. If LEFT is specified, then the string will be placed to the left of the character in column "n" counting from the left. If RIGHT is specified, then the string will be inserted to the right of the character in column "n" counting from the right.
Here is an example for an element whose values are speeds in miles-per-hour:
ELEMENT speed/ INTEGER/ OUTPUT, INSERT ' mph',END
The INSERT attribute is used to append the string " mph" to the end of the numeric value on input.
Though it may seem fine at first glance, the above element input line would probably cause problems. An important point to observe is that you must match up input and output processing rules, which was not done here. Let's consider the processing of several values for this element as the record is added, transferred and then updated. [See II.3.]
input value (ADD) output value (TRANSFER) input value (UPDATE)
1) 55 55 mph 55 mph (error)
2) 55 mph (error)
The error in both cases occurs because the string value "55 mph" cannot be converted to an integer value. As shown by the first example, even if you always knew not to include the "mph" portion of the value when you added a record, SPIRES would append it when the record was transferred, and thus it would cause an error when the record was updated (unless you removed it before updating). The best solution is to add a CHANGE attribute for the input value:
ELEMENT speed/ CHANGE mph,''/ INTEGER/ OUTPUT, INSERT ' mph',END
Thus, if you intend to insert a string into an element value on output, be sure that you remove it on input.
These two attributes are complementary. They are both similar to the ENCODE element type in that they check the element value against a list of values provided in the attribute. However, they do not change the value for storage, as the ENCODE type does.
The INCLUDE attribute verifies that the element value is in the provided list of allowed element values; if it is not, an error occurs. We will use INCLUDE for the BLOOD.TYPE element. The EXCLUDE attribute, the opposite, verifies that the element value is not in the provided list of values; if the value is, then it is discarded without an error occurring. (If the element is a Required element and the value is discarded, an error will occur, however.) EXCLUDE is generally used with indexes, to keep undesired element values out of an index.
The syntax of these two attributes is similar:
INCLUDE string [,string,string,string...] EXCLUDE [string,string,string...]
At least one value is required for INCLUDE; no value is required for EXCLUDE, which by default will then exclude common words that are undesirable in word indexes. [See IV.6.7.] The total length of all strings in either attribute, including the separating commas, may be no longer than 255 characters. No single string may be longer than 16 characters. (If a string is longer than that, use the CHANGE attribute to change it to a shorter one before the INCLUDE or EXCLUDE attribute; you may change it back on output, if desired.)
As noted earlier, these two attributes are sensitive to case. If the value MAN is to be excluded, the value "man" will not be excluded. Place a CAPITALIZE attribute before the INCLUDE or EXCLUDE attribute if necessary.
Here is the BLOOD.TYPE element input line using INCLUDE:
ELEMENT blood.type/ CAP/ INCLUDE A+,A-,AB+,AB-,B+,B-,O+,O-
The RANGE attribute can be used to ensure that the value of an INTEGER, DECIMAL or DOLLAR type element is within a certain range of values:
RANGE m,n
where "m" is the minimum allowed value and "n" is the maximum.
Suppose the BLOOD DONORS goal record had an AGE element:
ELEMENT age/ INTEGER/ RANGE 18,100
Only a value from 18 to 100 would be allowed for that element. (Actually it would probably not be a good idea to store the donor's age, since it would change regularly. It would be better to store the birthdate. A virtual element [See X.4.] could be defined to figure out the donor's age on the current date.)
The MSG attribute lets you specify a customized error message to be displayed if a processing rule detects an error during record output or index searching. If MSG is not included, the standard SPIRES error message will be displayed. Since those messages are not very attractive, nor can they be as specific about the problem as custom ones, adding MSG attributes, especially where problems are likely to occur, is recommended. (An example of an element whose values might be troublesome is CHILDREN. Is the person adding a record supposed to give the names of children, or the number of children, or simply YES or NO? An error message such as "Please enter the number of children" would clarify the problem if an error were detected.)
The MSG attribute may appear only once per element. Its syntax is:
MSG [string]
where "string" is the error message to be displayed.
The MSG string may be as long as 128 characters. It often includes the list of allowed values for elements with inclusion lists (from the INCLUDE attribute or YESNO and ENCODE types):
ELEMENT can.be.called/ YESNO/ INDEX/ MSG Please enter YES or NO
See the example in section II.1, which shows how these messages are displayed to the user adding and updating records using the $PROMPT format.
If you only specify MSG, the File Definer will provide messages for you, depending on the element type. The messages are:
element type error message DATE Invalid Date value INTEGER Invalid Integer value DOLLAR Invalid Dollar value DECIMAL Invalid Decimal value ENCODE Invalid Entry value YESNO Value must be Yes or No
No default messages are available for NAME or TEXT elements since no input value will cause an error for those two types of elements.
As mentioned before, the processing rule attributes are a shortcut way of specifying one or more processing rules in the file definition language of SPIRES. That language can be quite complex, so the File Definer removes some of the complexity by packaging the most common rules into the attributes being described in this subsection, V.3.2.
However, there are many processing rules available other than those put together into attributes by the File Definer, and sometimes you may need them. For example, for the ZIPCODE element, we would like SPIRES to verify that the input value has exactly five characters, all of them digits. The LENGTH attribute could verify that the value is five characters long. And if it were an INTEGER, SPIRES would verify that all the characters were numbers. However, we do not want the value stored as an integer, but as a code of numerals. There is a processing rule in SPIRES, called "$FIXED.NUM", that does exactly the combination of actions we want: it will verify that the input value is exactly a certain number of characters long, and that the value consists of nothing but digits. To specify it, we must use the INPROC keyword:
INPROC processing-rule [/ processing-rule ...]
where "processing-rule" is the name of a SPIRES processing rule, along with any parameters that it may require. (Remember that a keyword, as opposed to an attribute, must begin an input line. The INPROC input line follows the input line for the element it is to affect.)
Processing rules are explained in detail in "SPIRES File Definition", section B.4. The most commonly seen processing rules, called "system procs", begin with a dollar sign, followed by the name: $FIXED.NUM, for instance. Following that, in parentheses, may appear some parameters:
INPROC $FIXED.NUM(5)
The numeral 5 here indicates that the input value should be tested to ensure that it is five digits long. Thus, our ZIPCODE element now looks like this:
ELEMENT zipcode, zip/ TEXT/ LENGTH 5, EXACT INPROC $FIXED.NUM(5)
One effect of an INPROC (unfortunate for our present purposes) is that in some cases it overrides a previous attribute. In the case of the ZIPCODE element the $FIXED.NUM inproc would have overridden the MSG attribute; you will therefore see in the final file definition the INPROC $MSG used in place of the MSG attribute.
Another keyword may be used to specify processing rules on output: OUTPROC. Two OUTPROCs occasionally seen in File Definer input are:
OUTPROC $NAME(FIRST.LAST) OUTPROC $DATE.OUT(DAY.LONG)
which appear for NAME and DATE elements respectively. The $NAME proc, used as an OUTPROC with the FIRST.LAST parameter shown, displays a name in first-name, last-name order, which is often preferred on output to the default "last-first" order of NAME elements.
The $DATE.OUT proc provides the output date in a different format than the default selected by the File Definer. Instead of "07/01/54", the date would be output as "THUR. JULY 1, 1954", displaying the date in the LONG form (with the month written out) and including the weekDAY. You can also specify just LONG or DAY in place of DAY.LONG as the parameter for the proc.
Warning: Using the INPROC or OUTPROC keywords will override any type or processing rule attributes for input or output respectively that appear in the element input line. For example,
ELEMENT date/ DATE/ OUTPUT, LOWER OUTPROC $DATE.OUT(DAY.LONG)
The LOWER processing rule attribute, here used to convert the output value to lowercase, would be overridden by the OUTPROC in the following line. Using the proper system proc in the OUTPROC line would correct the problem:
ELEMENT date/ DATE OUTPROC $DATE.OUT(DAY.LONG)/ $LOWER
This section is only meant to introduce you to system procs and show you how they provide more flexibility than the packaged processing rule attributes provided by the File Definer. In addition, some specific examples that you may wish to use in your own application (the $FIXED.NUM and $DATE.OUT procs) have been demonstrated. Most file definers find the File Definer's processing rule attributes to be adequate for their needs. Before using any other processing rules, however, you should read at least one of the sections of other manuals listed above, and read section 5.3 of the "File Definer" manual.
Other types of element value processing are available at record closeout, explained earlier. [See IV.6.5.2.] For example, if an element has multiple occurrences, you can specify that the values should be sorted, so that they are stored and displayed in ascending or descending order. You may specify these directly using the CLOSEOUT attribute:
CLOSEOUT rule
where "rule" is a SPIRES processing rule, such as those described below.
The closeout rules described briefly below are system procs, described above. You will also see dollar signs preceding system variables and functions. [See IX.] Several other rules are available, but these are the most common, besides those inherent in other attributes (DEFAULT, in particular).
When specified with the CLOSEOUT attribute, a proc is added to the end of the processing rules created by the File Definer in the generated file definition. The proc generates the value, which is then processed through the other processing rules. Thus it is important to specify that an element will be of type INTEGER if its value is generated by the $OCC proc, unless you want it stored as a TEXT element, the default.
We will use both of these CLOSEOUT procs. We can arrange the occurrences of the DONATION structure so that the most recent donation is the first one stored and displayed. That way we can quickly see the last time that blood was donated. Thus we will use the $SORT rule:
ELEMENT donation/ STRUCTURE/ CLOSEOUT $SORT(descend)
Note that although the occurrences of the structure will be sorted by the structure key (the DATE element), the $SORT rule is specified here. It is the occurrences of the structure that are being sorted, not the occurrences of DATE within each structure, which is what it would mean to put the $SORT rule on the DATE element. (Remember that DATE, being the structure key, can only occur once per structure anyway.)
The other element that can use a CLOSEOUT attribute is TOTAL.PINTS. Each time a person donates blood, a pint of blood is given. Hence, the number of occurrences of the DONATION structure is the total number of pints donated. The $OCC rule counts the number of occurrences of another element in the record:
ELEMENT total.pints/ INTEGER 2/ CLOSEOUT $OCC(donation)
The $OCC rule tells SPIRES to count the number of occurrences of the element DONATION at record closeout and then supply that number as the element value for TOTAL.PINTS. You can see that this is much easier than having the person who is adding or updating the record count the number of occurrences of the structure; it is also more reliable. Anytime you update the record by adding or removing occurrences of the DONATION structure, the TOTAL.PINTS value will be updated.
The $OCC rule may not be used if the current element is in a structure and the element whose occurrences are being counted is not in the same structure. Vice versa, the same restriction applies: if the current element is not in a structure and the element whose occurrences are being counted is in one, the $OCC rule may not be used. For example, TOTAL.PINTS could not be used to count the number of occurrences of the LOCATION element within the DONATION structure; nor could an element in the DONATION structure contain the number of occurrences of an element outside of it.
The value provided by the $OCC proc is an integer that is two bytes long, not four. (A "shorter" integer means that the value represented must be within a smaller range than a longer one.) We must tell the File Definer that the stored value will be a two-byte integer by following the INTEGER type attribute with the numeral 2, as shown above. We could also put a "4" after INTEGER in those places where we use that attribute, but "4", for a four-byte integer, is the default.
Sometimes the person entering records either forgets or does not know what type of value should be supplied for a particular element. The File Definer provides a method whereby the user can type a question mark in response to an element prompt from the $PROMPT format and receive an "element explanation" provided by the file owner. The explanation may be any message desired, but it usually explains what information the element is meant to contain and often shows sample values. [See II.1 for an example -- the input for the DATE element.]
The syntax of this attribute is:
EXPLAIN text
where "text" is the information you want displayed. It does not need to be enclosed in apostrophes or quotation marks, even though it may contain blanks and special characters.
EXPLAIN is a keyword and therefore it begins an input line. It refers to the previously described element. Each EXPLAIN input line is one line of text that will be displayed. Multiple lines for a single element are allowed. Here is how we might define the TOTAL.PINTS element:
ELEMENT total.pints, tot, pints.given/ INTEGER 2/+ OCC 1/ CLOSEOUT $OCC(donation)/ INDEX EXPLAIN The value for this element will be provided by EXPLAIN SPIRES. Please skip this element by pressing EXPLAIN carriage return in response to the prompt.
The difference between the MSG attribute and the EXPLAIN keyword is important to understand. The MSG message is displayed only when a processing error occurs during element input processing or during index searching. The EXPLAIN explanation is displayed when a question mark is entered as the value for the particular element during input.
This section has shown you the most often used element attributes, but there are others. Several that might prove useful to your application are:
- the TIME attribute. This element type handles time values.
- the BREAKUP attribute. This processing rule attribute lets you enter a series of values for the element as a single value with each individual value separated from the others by a designated separator character. The value will be split into the individual values for storage. This technique can make data entry of multiply occurring elements proceed much more quickly.
- the EDIT attribute. This attribute allows you to provide an edit mask for numerical element values.
These and other attributes are covered in the manual "File Definer", chapter 5.
Below is another File Definer session, similar to the one that ended the last chapter. [See IV.7.] The input file below includes some of the features described in this chapter as well. Most of the elements would be given EXPLAIN input lines, but in order to save room here, we have not done so except for one example, the DATE element. Note that the indentation shown is for clarity and is not required.
Again, the input file was collected using WYLBUR and then saved before we entered the File Definer.
-> enter file definer
* ENTERING FILE DEFINER
:-> use blood.donors.definer.input2 on pub009
:-> input active
* 1. Input> FILE/ AUTHOR John Klemm, 497-4420/ BIN purge
* 2. Input> SUBFILE blood donors/ ACCOUNTS public
* 3. Input> EXPLAIN This is a demonstration subfile for the +
* 4. More-> SPIRES manual "A Guide to
* 5. Input> EXPLAIN Data Base Development".
* 6. Input> GOAL/ RESULT donor
* 7. Input> KEY id/ SLOT
* 8. Input> REQUIRED
* 9. Input> ELEMENT name, nam, donor.name/ NAME/ SINGLE/ INDEX
* 10. Input> ELEMENT address, add/ TEXT/ LENGTH 30/ OCCURRENCE 3
* 11. Input> ELEMENT city, cit/ TEXT/ SINGLE/ INDEX
* 12. Input> ELEMENT state, sta/ TEXT/ SINGLE/ LENGTH 2, EXACT/+
* 13. More-> MSG This value must be the two-character code/+
* 14. More-> CAPITALIZE/ DEFAULT CA
* 15. Input> OPTIONAL
* 16. Input> ELEMENT zipcode, zip/ TEXT/ LENGTH 5, EXACT/SINGLE
* 17. Input> INPROC $MSG('Value must be 5-digit zipcode')/+
* 18. More-> $FIXED.NUM(5)
* 19. Input> ELEMENT phone.number, pho, phn/ TEXT
* 20. Input> ELEMENT can.be.called, can, cal/ YESNO/ SINGLE/+
* 21. More-> MSG/ INDEX
* 22. Input> ELEMENT blood.type, blo, blood, bld/ INCLUDE A+,A-,+
* 23. More-> AB+,AB-,B+,B-,O+,O-/ SINGLE/ CAPITALIZE/+
* 24. More-> MSG Value must be A+,A-,AB+,AB-,B+,B-,O+,O-/ INDEX
* 25. Input> STRUCTURE donation, don/ INCLOSE $SORT(descend)
* 26. Input> KEY date, dat, date.given/ DATE/ MSG/ INDEX
* 27. Input> EXPLAIN Please enter the date the donation was made.
* 28. Input> ELEMENT location, loc, where.given/ TEXT/+
* 29. More-> SINGLE/ INDEX/ WORD/ EXCLUDE
* 30. Input> END
* 31. Input> ELEMENT total.pints, tot, pints.given, pints/+
* 32. More-> INTEGER 2/ SINGLE/ INCLOSE $OCC(donation)/+
* 33. More-> INDEX
* 34. Input> ELEMENT comments, com/ TEXT
* 35. Input> END
:-> generate clear
:-> list first
1. FILE = GQ.JNK.BLOOD.DONORS;
:->
In the next chapter, we will use this generated file definition to create our SPIRES file.
This chapter will describe the next steps you should take to create your file definition. You will add the file definition to a SPIRES subfile called FILEDEF and then you will "compile" the file definition. At that point you can return to SPIRES and begin using your new subfile. The last section in the chapter will explain the procedures to follow if you then discover that you want to change the characteristics of your file as described by your File Definer input file and the generated file definition.
If you look at the file definition generated by the File Definer that sits in your active file, you will notice that each statement looks like an element in a record displayed in the SPIRES standard format. For example, the first line was:
FILE = GQ.JNK.BLOOD.DONORS;
which has the form:
element = value;
In fact, your file definition is a record in a SPIRES subfile, which is called FILEDEF. Once the File Definer has created your file definition, you may add it to the public subfile FILEDEF. Just as you add a record in the standard SPIRES format to any other subfile [See II.3.] you select the FILEDEF subfile and issue the ADD command.
:-> input active .... <-- File Definer input entered :-> generate :-> select filedef :-> add :-> in active show input -OK to clear? yes :-> save blood.donors.fd.input on pub009 WYL.GQ.JNK.BLOOD.DONORS.FD.INPUT saved on PUB009 :->
Note that we were still in the File Definer subsystem when we selected the FILEDEF subfile and added the new file definition (the returned prompt indicates that the record was added successfully when the record does not have a slot key), and then placed the File Definer input file in our active file in order to save it. You do not have to be in the subsystem to select the FILEDEF subfile; this sequence of commands was shown as one way to retrieve and save your input file.
You should be able to add any file definition created by the File Definer to the FILEDEF subfile. If an error is encountered, however, you will receive an error message that references the line number in your active file where the error occurred and the SPIRES error number, which can be explained using the EXPLAIN command. If you can, you should correct your input file, generate a new file definition and reissue the ADD command; alternatively, see your SPIRES consultant for more assistance.
The next step is to compile the file definition.
To compile your file definition, issue the COMPILE command:
COMPILE [gg.uuu.]filename
where the value supplied is the value shown in the FILE statement, the first line of your file definition. It may be specified with or without your account number in front:
-> compile gq.jnk.blood.donors -File definition compiled ->
Again, you may receive error messages, though it is unlikely. Explanations are available for the error messages through the EXPLAIN facility. Alternatively, you should see your SPIRES consultant. It is unlikely that a file definition created by the File Definer will not compile. [See VI.4.]
When SPIRES compiles your file definition, it creates "compiled file characteristics" and establishes the ORVYL files in which these characteristics and the goal and index records of your file will be stored. The compiled characteristics are a compact version of most of the information in the file definition. This block of information contains the names of the other ORVYL files that comprise the file and what type of data is in each (deferred queue data, goal records, index records, etc.). In addition, it contains the names of the elements, occurrence and length attributes for them, and so on. When you issue a SPIRES command that uses the file, SPIRES first goes to the compiled characteristics to learn where (i.e., in what ORVYL file) it can find the information requested by the command.
Though you will never use them yourself directly, you may see the names of the ORVYL files SPIRES creates and uses if you issue the ORVYL command SHOW FILES, which shows you the names of all of the ORVYL files you have:
-> show files ORVYL File System BLOOD.DONORS.DEFQ BLOOD.DONORS.MSTR BLOOD.DONORS.REC1 BLOOD.DONORS.REC2 BLOOD.DONORS.RES SYSTEM.CHKPT ->
The ORVYL files whose names begin with BLOOD.DONORS are the files SPIRES uses for the BLOOD.DONORS file. In addition, if this is your first SPIRES file, SPIRES will create an ORVYL file called SYSTEM.CHKPT (for "system checkpoint") used when your SPIRES files are processed. No matter how many SPIRES files you have, you will always have one ORVYL file called SYSTEM.CHKPT.
The SHOW FILES command is an ORVYL command that shows you the names of ORVYL files, the physical data sets that contain the data of your SPIRES file. You will never access your data directly from the ORVYL data sets. You will access it through the SPIRES subfile, leaving SPIRES to deal with ORVYL.
If all went well with adding the file definition to the FILEDEF subfile and compiling the file definition, you may now return to SPIRES and use the file by selecting the subfile. You may then issue commands such as SHOW INDEXES, SHOW ELEMENTS, SET FORMAT $PROMPT, ADD, UPDATE, TRANSFER, and so forth. All the commands discussed in this manual so far are available to you.
You should experiment with your file for awhile. For example, add a few records, display them, and transfer one and update it. Test your element attributes and error messages by deliberately typing values that should be rejected. Try even making some "stupid" mistakes in entering data -- the file definition should be able to cope with any end-user error, no matter how bizarre the error might be.
If all works as you expected, you are ready to use the file regularly. However, more likely you'll want to make some changes in the file definition after you test it. Even the most experienced file designers spend considerable time tuning and modifying a new file definition before entrusting real data to it. The next section describes the procedure for modifying your file definition.
If you decide that you want to make changes to the file definition, first change your File Definer input accordingly and generate a new file definition. Then, when the new file definition is in your active file, enter File Definer again and generate a new file definition, and update the FILEDEF subfile with the new version of the definition, as follows:
-> use blood.donors.fd.input on pub009
<-- make changes using WYLBUR commands
-> save blood.donors.fd.input2 on pub009
-> enter file definer
* ENTERING FILE DEFINER
:-> input active quiet
:-> generate clear
:-> select filedef
:-> update gq.jnk.blood.donors <-- whatever the file name is
:->
Remember to save the changed File Definer input.
If you have changed only the subfile identification section of the file definition, the changes will take place immediately the next time the file is selected. However, if you changed other parts, such as element definitions, you will need to recompile the file definition. This action may or may not involve destroying the file first, depending on the severity of the changes you made. (By the way, despite the sound of the word, "destroying" a file is neither difficult nor dangerous, as long as you do it carefully, as described below.)
You do not need to destroy the file if you change any of the following:
- change or add element aliases
- change or add error messages using the MSG attribute
- add explanations using the EXPLAIN attribute
- change or add the AUTHOR, BIN, NOAUTOGEN or MAXVAL attributes
- add more optional elements to the end of your input file, if you already have some optional ones; these new elements may be indexed, if desired.
You do need to destroy your file first if you change any of the following:
- add or remove required elements
- add new optional elements if you did not have any before
- remove optional elements
- change element types (in general)
- change processing rule attributes (in general)
- add indexes for previously defined elements
If you do have to destroy your file, here is the procedure to follow. If there are records in your old file that you would like to add to the new subfile, use Global FOR commands to place them in your active file and then save them in a WYLBUR data set for the time being. [See VIII.1, VIII.3.1.] To destroy the file, issue the ZAP FILE command.
-> zap file blood.donors -Do you mean to destroy file GQ.JNK.BLOOD.DONORS ? yes -> compile blood.donors -File Definition Compiled
"Zapping" the file is irreversible; thus, SPIRES asks you to verify that it is about to erase the right file. The file definition in the FILEDEF subfile is not affected by the ZAP FILE command; the updated version was used in the example above when the file was compiled again.
If you do not have to destroy the file first, you must "recompile" the file definition, as opposed to compiling it again:
-> recompile blood.donors -File Definition Compiled. ->
The RECOMPILE command changes only the compiled characteristics. It does not affect the ORVYL files containing your data.
A complete listing of the changes that can be made to a SPIRES file definition without zapping the file appears in the SPIRES manual "File Definition", section C.1.
Your file is now ready to use as you like. You may want to put this primer down for awhile and work with your subfile. If you remember that records you add and update will not affect the indexes until overnight processing has occurred, you may have read enough of this manual to satisfy your needs as a file owner.
In the remaining chapters of this manual, various facilities for using and controlling your file will be briefly explained. These features will give you additional power and flexibility as you use your subfiles.
Unless you specify otherwise, SPIRES will have your file processed automatically each night that the deferred queue contains subfile modifications. [See II.1.] When the file is processed, added records and the new versions of updated records are moved into the tree, and removed records and the records being updated are moved out. Then the index records are changed to reflect these transactions.
Sometimes file owners want to control the file processing themselves, particularly in the beginning of their applications when they are testing the subfile's new indexes to be sure they contain the right element values. But some file owners do not wish to incur the small expense of file processing when only one or two records will be processed. (Note however that for most files, the printing of the output from the processing job generally costs more than the job, which usually costs only a few cents. Remember that you can suppress the printing of the job output when the file processing is successful by specifying BIN = PURGE [See V.1.] in the FILE input line of your File Definer input.) Commands are available that allow you to process the file yourself whenever you want.
SPIRES does not actually handle the file processing; it occurs within another ORVYL program called SPIBILD. Issue the SPIBILD command to access SPIBILD: [The SPIBILD command supersedes the CALL SPIBILD command, which may still be issued, if desired.]
-> spibild -Welcome to SPIBILD -?
To leave SPIBILD, issue the ORVYL command EXIT or issue the SPIRES command to re-enter SPIRES.
The SPIBILD processor is used when you want to process the file yourself or when you want to add or update a large group of records and have the indexes be rebuilt immediately.
The file owner may process the file whenever desired by entering SPIBILD and issuing the PROCESS command:
PROCESS [gg.uuu.]filename
where the file name is entered with or without the account number prefix.
A SPIBILD sequence usually looks something like this:
-> spibild -Welcome to SPIBILD -? process blood.donors -Passing: 8 records of record-type REC01 -Processed: 8 DEFQ records of record-type REC01 -Compute time: 0.152 seconds -Elapsed time: 3.386 seconds -Core usage: 0088/0296 -?
This indicates that eight records were processed and that the process itself was very quick, lasting only a few seconds.
You may get error messages that cause the file processing to stop. The most common ones are "-System ATCHFILE error, code=S56" or "code=S36". The EXPLAIN facility is available in SPIBILD, so you may issue the EXPLAIN command to find out what is wrong. The S36 error means that the file requested does not exist, suggesting that you probably typed the file name incorrectly. The S56 error means that someone currently in SPIRES has a subfile of your file selected, and you may not process the file until it is not selected. This problem can be circumvented with the SET SHARE command, issued before the PROCESS command. [See 2.1.5.1 of the "SPIRES File Management" manual for more about the SET SHARE command..]
You are advised to let SPIRES handle the processing for you automatically, especially once the file is established and being used regularly. The file is then processed at night, when rates are cheapest.
Sometimes a file owner would like to add many records to a subfile at once. It may be, for example, that the file definition has been changed and the file had to be destroyed and rebuilt, in which case the old records need to be added back into the subfile. [See VI.4.] You certainly would not want to have to re-enter all the records individually.
The INPUT BATCH command can be used in SPIBILD to input many records (a "batch" of them) at once. Usually the records are in the SPIRES standard format, one after the other. Each record must begin with a line specifying the "command" that is to be applied to it, usually "ADD;". Other such commands are available as well, such as UPDATE, MERGE, and REMOVE. In those cases, the verb must be followed by the key of the record being processed: "UPDATE 362;" or "REMOVE GA.JNK;". Records to be added, updated or merged must end with an extra semicolon (;) that either begins the line or is preceded by a blank. (This format for data entry is discussed in detail in "SPIRES Searching and Updating", section D.8.1. It is also used with a "batch facility" in SPIRES, described in that section.)
Your active file containing three records being batched might look like this:
ADD; NAME John J. Brothers; (data for the first record continues) ; ADD; name Roger Bath; (data for the second record continues) ; REMOVE 198;
No record is entered for a removal request since you want to eliminate the record rather than enter more data for it. Note that there is no extra line with a semicolon following the REMOVE "command".
After you have gathered the records in your active file, follow these steps to batch them into the subfile. First, after entering SPIBILD, issue the ESTABLISH command:
ESTABLISH 'subfile name'
The subfile name in the command must be surrounded by apostrophes if it contains one or more blanks. Otherwise, the apostrophes are unnecessary.
ESTABLISH causes SPIBILD to process the file. Thus, any updated records already in the deferred queue from subfile modification in SPIRES will affect the tree and indexes.
Next, issue the INPUT BATCH command. The records being batched do not go through the deferred queue at all, but instead go directly into the tree (or out of it, for records being removed) and get indexed.
Any errors in the records that would cause them to be rejected if you added them through SPIRES will cause SPIBILD to reject them as well. For example, if you omit a Required element, SPIBILD will reject that record, issuing an error message saying that it was not admitted into the subfile. You may later correct the mistake and batch that record into the subfile again.
You the file owner may control when the file is automatically processed either by adding or deleting the NOAUTOGEN attribute from the FILE input line of your File Definer input, or by issuing the SET AUTOGEN or SET NOAUTOGEN commands.
If your file has NOAUTOGEN set by the file definition, whenever you would like the file to be processed overnight, you must issue the SET AUTOGEN command when you have the subfile selected. SPIBILD will process the file that night after midnight, if there are any transactions in the file's deferred queue. The file will return to the NOAUTOGEN setting after processing.
On the other hand, if the file does not have NOAUTOGEN set (i.e., if AUTOGEN is set by the file), then automatic processing can be halted by issuing the command SET NOAUTOGEN. The file will not be processed again until you issue the SET AUTOGEN command or process the file yourself. In either case, the file will return to the AUTOGEN setting after processing.
To see which state is in effect, issue the SHOW AUTOGEN command. Only the file owner can change the AUTOGEN setting, but anyone who can select the subfile can see which setting is in effect.
From Chapter I, you know how to access records in the subfile in two ways: if you know the key of a record, you can access it directly, using the DISPLAY, TRANSFER and other commands; if you know some element value within the record that is indexed, you can find it and display it using the searching commands, FIND and TYPE. One of the purposes of "Global FOR", a special group of SPIRES commands, is to provide a third way of accessing records: using record criteria other than their keys or indexed elements.
Global FOR allows you to handle records sequentially in a particular "class", whether it be the class of records added to the subfile since the file was last processed, the class of records that have been removed today, the class of all records currently in the subfile, the class of records in a search result, and so on. Each of the classes may be further subsetted, depending on the values in the records themselves. Many commands can be used to work with these records, the primary ones being the familiar DISPLAY and TRANSFER commands, here used with new options.
Global FOR is discussed briefly in the SPIRES manual "Searching and Updating", and the reference manual "Sequential Record Processing in SPIRES: Global FOR", contains complete information about the facility. This chapter can be considered a "Global FOR primer".
To use Global FOR, you must first enter its environment. You must have already selected the subfile you want to work with. Then, you issue a "FOR class" command, where "class" specifies a group of records to be handled sequentially. There are about a dozen main classes, such as the class of added records.
Suppose we want to examine all the records that have been added to the subfile today, that is, since the file was last processed. (A standard "abbreviation" in SPIRES documentation when parts of the deferred queue are being discussed is the word "today" for the phrase "since the file was last processed".) The class of added records is called ADDS:
-> select blood donors -> for adds +>
The "FOR class" command above tells SPIRES that you want to work with the group of records that have been added recently and that are now in the deferred queue. Most Global FOR commands issued after this "FOR class" command will affect one or more records in this class. The "FOR class" command itself does not access any records; that work is done by "record processing" commands issued under Global FOR, as you will see below. (There is a distinction in terminology between "file processing", when SPIBILD merges the deferred queue into the record tree and updates the indexes, and "record processing", when records are worked with in SPIRES.)
When you enter Global FOR mode, the SPIRES prompt changes from "->" to "+>" (or from "-?" to "+?" if UPPER is set). The plus sign indicates that you are in Global FOR mode and reminds you that some SPIRES commands act upon sets of a class of records instead of individual records by key value. However, most SPIRES commands (e.g., SHOW commands and the TYPE command) are unaffected and can still be issued, as can commands of other systems, such as WYLBUR or ORVYL.
Once you have told SPIRES which records you want, you can begin to sequentially process them. For example,
-> for adds +> in active display all +>
Here you request that SPIRES put copies of all the added records into your active file in whatever format is currently set. Under Global FOR, the command DISPLAY has different options than previously. [See I.7.] Instead of a record key, you supply an option such as ALL. [See VIII.3.]
In the next example, you will process the records in the subfile of donors not living in California: remember that the STATE element was not indexed.
-> for subfile where state ~= ca +> display -End of global FOR ->
The first command told SPIRES which records should be processed by subsequent Global FOR commands: all records in the subfile (including added records, the latest version of updated records, and not removed records) that do not have CA for the value of the STATE element. The DISPLAY command asked SPIRES to look through the subfile and display the first record found that fit that description. After examining all the records, SPIRES determined that none fit the description, and automatically left Global FOR mode. Whenever SPIRES has examined all the records in the class and has no more to process when you request one, you will be removed from Global FOR.
When you want to leave Global FOR mode, issue the ENDFOR command:
+> endfor -End of global FOR ->
Selecting a different subfile will also remove you from Global FOR mode.
This chapter will introduce you to a few of the Global FOR classes and to some of the record processing commands available, such as TRANSFER, REMOVE and DEQUEUE. In addition, some of the capabilities of the WHERE clause, the option on the "FOR class" command shown above, will be discussed. Global FOR is a very powerful tool that gives you many different ways to access your data.
Outside of Global FOR, most SPIRES commands used to process individual records of a subfile are key-dependent; that is, you must know the record's key value to process it. The TRANSFER command, for instance, requires the key value of the record to be transferred. In Global FOR, however, the "FOR class" command defines a group of records to be processed by subsequent Global FOR commands, and SPIRES determines the records' key values for you. All Global FOR processing begins with a "FOR class" command:
FOR class [WHERE clause]
Subsequent global FOR record-processing commands will handle the records described by the "FOR class" command. [See VIII.2 for a discussion of the WHERE clause.]
Of the dozen or so Global FOR classes, the most important are:
- SUBFILE, all the records currently in the subfile; it includes the tree copy of non-updated records, the latest copies of added records, and the latest copies of updated records; removed records are not included.
- TREE, all the records in the tree, which means ignoring all add, update and remove requests in the deferred queue.
- ADDS, the latest copy of each record being added to the subfile. (Note that added records that are updated later that day are still considered "adds".)
- UPDATES, the latest copy of each updated record.
- REMOVES, the key (not the entire record) of each record being removed.
- RESULT, the records in the current search result.
- STACK, the records in the current stack. [See I.5.2.]
Under the first four classes, records are by default processed in ascending key order. That means that this sequence of commands:
-> for subfile +> clear format <-- to set the SPIRES standard format +> in active display all -OK to clear? ok +>
would place copies of all the records currently in the subfile into your active file, arranged by the key value of each record, from lowest to highest. If you have to erase your file when changing the file definition, that sequence of commands would be one way to extract all of the records in your subfile before you issue the ZAP FILE command. [See VI.4.]
The order in which the records are processed can be reversed using the SET SCAN BACKWARDS command, though it is not allowed with all classes. [See "Sequential Record Processing in SPIRES", section 6.2.1.]
Note: Unlike all the other classes, the REMOVES class does not actually access the records directly. The deferred queue has only the keys of the records being removed, not the records themselves. Thus, not all of the record processing commands available for the other classes are available under FOR REMOVES. Those available that will be discussed in this chapter are DEQUEUE, STACK and SHOW KEYS. [See VIII.3.] There are ways to see records that have been removed since the file was last processed. [See II.4, IX.4.]
The WHERE clause lets you request that only a subset of records within the Global FOR class be processed. For example, if you wanted to find one particular added record, you could issue the FOR ADDS command and examine the records one at a time until you found the one you were looking for. However, you could have SPIRES do the examining instead of you, by restricting the processed records with a WHERE clause:
-> for adds where name = William Harvey +> display <-- William Harvey's record is displayed +>
(Note that the DISPLAY command is here used with no option, which means, under Global FOR, display the next record in the class that fits the WHERE clause criteria, if any is specified.) The WHERE clause here provides SPIRES with an element name, a relational operator and a value.
A simple WHERE clause on the "FOR class" command has the following syntax:
FOR class WHERE [NOT] criteria-clause
where "criteria-clause" has this syntax:
element [OCCURS|LENGTH] relational-operator value
where "element" is the name (or a valid alias) of the element to be examined by SPIRES, "relational-operator" is one of the standard SPIRES relational operators [See I.4.2.] and "value" is the value to be compared with the element value or values within the records in the class. OCCURS and LENGTH are discussed below. The element may be any element in the goal record, not just indexed elements. Global FOR processing works directly with the goal records, not with indexes -- that is, it is just like you going through the donors' folders in the top drawer of the file cabinet rather than using the indexes.
Compound WHERE clauses are allowed so that you can specify more than one criterion in a WHERE clause. The complete syntax of the criteria-clause is:
element [OCCURS|LENGTH] relational-operator value [AND|AND NOT|OR] criteria-clause
The logical operators are the same ones discussed earlier and they have the same meanings as before. [See I.4.3.]
Here are some examples of "FOR class" commands with WHERE clauses:
FOR UPDATES WHERE CITY = PALO ALTO FOR TREE WHERE CITY PALO ALTO AND ZIPCODE 94304 FOR RESULT WHERE PHONE.NUMBER STRING WORK
As shown in these examples, if no relational operator occurs, the equality operator is assumed.
When the "FOR class" command is issued, SPIRES does not immediately examine the class of records for those records fitting the WHERE clause criteria. The WHERE clause is examined by SPIRES to be sure that the element name is valid for the selected subfile and to determine whether the given value is allowed -- that is, the value is passed through the INPROC processing rules for that element. These checks ensure that SPIRES will be examining the records for valid criteria. An error message will be displayed if an error is detected at this point.
When you issue a Global FOR record-processing command, such as DISPLAY, SPIRES begins examining the records in the class, processing the ones that fit the criteria. Thus, when Global FOR processing is affected by a WHERE clause, there is a difference between the records examined (all the records in the class) and the records processed (those records in the class that fit the WHERE clause criteria).
When no WHERE clause is in effect, Global FOR processing is very efficient under all classes. However, if a WHERE clause is in effect, SPIRES must examine all records in the class for the criteria (unless a SET SCAN command is in effect. See the reference manual "Global FOR" for details). The smaller the class of records, the less work SPIRES must do. Hence, you should be careful when you use WHERE clauses with the SUBFILE and TREE classes, which may contain hundreds or thousands of records. Wherever possible, use indexed searching to narrow the number of records to be examined; then process the records under the FOR RESULT command. For example, suppose we need to examine all the records of donors who have type B-negative blood and who have given us their home phone numbers:
-> show subfile size -The subfile has 983 Records. -> find blood.type b- -Result: 112 DONORS -> for result where phone.number string home +> set format phone.list +> in active display all <-- copies of the records are placed in the active file +> endfor -End of global FOR ->
The SHOW SUBFILE SIZE command shows us how many records are in the selected subfile (actually how many are in the tree). Though we could have issued a "FOR class" command with a compound WHERE clause (FOR SUBFILE WHERE BLOOD.TYPE B- AND PHONE.NUMBER STRING HOME), that would mean that SPIRES would have to examine each of the records in the subfile. Instead, using the indexes first where possible, we gave SPIRES fewer records to examine individually -- only those records in the search result were examined directly.
You can also access records that have a particular number of occurrences of an element or that have occurrences of an element that are a particular length. Using the OCCURS option, you can specify that you want to process records that have no occurrences of a particular element or structure, for example:
-> for subfile where donation occurs = 0
Note that a value must be given; FOR SUBFILE WHERE DONATION OCCURS is not a complete WHERE clause.
Using the LENGTH option, you can ask SPIRES to process records with at least one occurrence of a particular element that is a particular length (or not of a particular length):
-> for result where address length > 30
LENGTH refers to the number of bytes of storage used by the element value in internal storage within the file. Remember that elements of type INTEGER and DATE, for example, are converted to four-byte values for storage; these values then would always have a LENGTH of four in this context. LENGTH is generally most useful with textual elements, such as an address or comments.
The DISPLAY command is not the only SPIRES command that can process records in Global FOR mode. The most commonly used commands are TRANSFER, MERGE, REMOVE, DEQUEUE, STACK and SHOW KEYS. (The last two, not introduced earlier, will be discussed in this section.)
All of those commands, except for the last one, are available outside of Global FOR, where they process a single record, specified on the command by its key value ("MERGE 17", for instance). Under Global FOR, where you do not need to know the key to process a record, the commands have new options, some of which allow you to process multiple records at once (DISPLAY ALL, for example).
Since the options are basically the same for all the commands, they are introduced here:
command-verb [FIRST|*|NEXT|n|REST|LAST|ALL]
If no option is used, the default is NEXT (except for the Global FOR commands GENERATE SET and GENERATE LOAD, not discussed in this primer). The options are discussed separately below.
This option indicates that the first record in the class should be processed. If a WHERE clause was specified on the preceding "FOR class" command, then the record processed will be the first record in the class meeting the WHERE clause criteria. Sometimes you may get this response:
-> for adds where blood.type = A+ +> display first -End of global FOR ->
That means that there was no "first" record in the class meeting the criteria of the WHERE clause. SPIRES did not know that when the FOR ADDS command was issued because it did not begin examining the records until the DISPLAY command was issued.
The "*" or "star" or "current record" option indicates that the current record should be processed by the command issued. The current record is the most recent record processed by a Global FOR command.
-> for adds +> display * -No * entry established +> display first <-- The first record in the class of ADDS is displayed. +> set format $prompt +> merge * (etc.)
In the example, the error message "No * entry established" occurred because we had not previously issued any record processing command in this Global FOR "session". Then, after displaying the first record, we decided to make some changes to it by issuing the MERGE command with the "*" option. If we had omitted the "*" option, we would have been merging the next record in the class (see below).
The next record past the current record (that meets the WHERE clause criteria in effect) is processed when this option is used. If no other record-processing option is used, NEXT is the default:
-> for adds +> display next <-- The first record is displayed. +> display next <-- The next record (second) is displayed. +> display <-- The next record (third) is displayed. +>
You could examine each record in the class, one record at a time, by repeatedly issuing the DISPLAY or DISPLAY NEXT command.
Most of the Global FOR commands discussed in this section allow you to process more than one record at a time. For example, more than one record can be shown with the DISPLAY command. Using some positive integer as "n", you can specify that the next "n" records be processed:
-> for subfile where comments occurs > 0 +> display 5 <-- The next five records fitting the criteria are displayed. +>
The processing commands for record updating, TRANSFER and MERGE, can only process a single record at a time. For these commands, "n" means something different: the "nth" record. For example, "TRANSFER 5" means "transfer the fifth record after the current record (meeting the WHERE clause criteria if any)".
Be very careful if your subfile has numerical keys (like a slot key) and you are using Global FOR. Suppose you decide to remove a record after examining it in Global FOR:
+> display next ID 214 NAME Mack, Theodore <-- rest of record is displayed COMMENTS Iron poor blood. +> remove 214 -214 records removed +>
What we meant to do was remove record 214, not the next 214 records in the class. We should have issued the command "REMOVE *" rather than "REMOVE 214". Had we not been in Global FOR mode, REMOVE 214 would have been correct. (To repair the damage, we would need to issue the FOR REMOVES command and use the DEQUEUE command).
Under this option, the remaining records in the class are processed. If a WHERE clause appears on the "FOR class" command in effect, only records that fit its criteria will be processed. Note that when this option is used on those commands that can process only single records at a time (TRANSFER, for instance), a warning message is displayed and the next record is processed. [See VIII.3.2 for an example.]
The last record in the class (that fits the WHERE clause, if any) is processed under this option. It is an inefficient option when a WHERE clause was specified on the preceding "FOR class" command since all the records in the class must be examined, as SPIRES tries to find the last one fitting the criteria.
This option causes SPIRES to process all the records in the class, beginning with the first and continuing through the last. If a WHERE clause exists, all records in the class will be examined and all records fitting the criteria will be processed.
As shown throughout this chapter, the DISPLAY command is used in Global FOR to display records in the class. Depending on the option appended, one or more records may be displayed. It is often preceded by the IN ACTIVE prefix in order to direct the copies of the records into your active file.
One common use of the DISPLAY command is to place copies of all the records in the subfile into your active file in a particular format:
-> set format phone.list -> for subfile +> in active clean display all +>
Note that the CLEAN option was added to the IN ACTIVE prefix in the example. This option, also available on the TYPE command [See I.5.] prevents each record from being preceded by the system separator line (an extra line containing the system separator, which by default is four asterisks: "****") and from being followed by an extra line containing a single semicolon. These lines help delineate separate records, but they are undesirable on some reports.
It was already mentioned that the sequence of commands shown above (without the CLEAN option) may also be used when you need to save your data before zapping the file and compiling a new file definition. However, you would want to clear the format, thus using the SPIRES standard format, rather than setting another format, so that the records could be batched into the new subfile in SPIBILD after changing the "****" lines to "ADD;". [See VII.2.]
The TRANSFER command is often used under Global FOR when you want to update the records in a subfile. Whether issued in Global FOR or not, the TRANSFER command puts a copy of the requested record into your active file. You may then alter the copy, making any corrections you wish. SPIRES awaits an UPDATE command, anticipating the return of the same record that was transferred.
The UPDATE command is not really a Global FOR command, since it works no differently in Global FOR than it does outside of it. Its syntax under Global FOR remains the same:
UPDATE [key]
If you are updating a record that was just transferred (the usual case), you will not need to use the "key" option. However, if you are updating a record that you did not transfer first, you will need to use the "key" option; otherwise, SPIRES will ask you which record you want updated.
-> for result where comments string "will donate money too" +> transfer first ... <-- Changes are made to the active file. +> update +> transfer next -OK to clear? yes ... <-- Changes are made to the active file. +> update +> transfer rest clear -ALL/REST invalid; FIRST/NEXT assumed ... <-- Changes are made to the active file. +> update +> transfer 4 clear -End of global FOR ->
In the example above, the CLEAR option was used on the TRANSFER command to tell SPIRES that it was "OK to clear" the active file without having to prompt for permission to clear it. Also note the effect of the TRANSFER REST command. Since REST is an invalid option (only single records may be processed by the TRANSFER command), it defaults to NEXT, meaning that the next record in the class fitting the WHERE clause criteria was processed. The final command failed because there was no fourth record that fit the WHERE clause criteria past the current record (i.e., the last record in the class), and so SPIRES removed you from Global FOR.
The MERGE command in Global FOR mode causes a single record in the class to be merged. If the $PROMPT format is set, you will be shown the old element values in the record and prompted for new ones. [See II.2.] If the SPIRES standard format is set, then the data collected in the active file in the standard format will be merged into the record being processed. [See II.3.]
As an example, suppose you want to add ZIPCODE elements for Menlo Park donors who did not know their zipcodes:
-> collect
1. > zipcode = 94025;
2. > ***
-> find city menlo park
-Result: 206 DONORS
-> for result where zipcode occurs 0
+> merge
+> merge
+> merge
-End of global FOR
->
In the example, you have merged the zipcode into all the records in the search result that did not have an occurrence of the ZIPCODE element. Apparently only two fit that criteria, so when you tried to merge a third record, you were removed from Global FOR.
Since MERGE, like TRANSFER, can be issued for only one record at a time, MERGE ALL and MERGE REST may not be used to merge all the records in a class at once. However, it is fairly simple to write a SPIRES "protocol" (a collection of commands that can be invoked automatically without having to type them in each time they are desired) that will merge each record in the class for you, saving you from typing MERGE over and over. [See IX.6.]
The effect of the REMOVE command in Global FOR mode is the same as it is outside of Global FOR. A removal request is placed in the deferred queue for each record that is removed. Though the record is still physically in the file, normal record display techniques (TYPE or "DISPLAY key") cannot access it. When the file is processed, the record is actually removed from the subfile and is physically gone.
Under Global FOR, the command has much more power since more than one record can be removed with a single command. Because of this power, SPIRES issues an informational message telling you how many records have been removed by the command when it is issued under Global FOR:
-> find total.pints < 5 -Result: 137 DONORS -> and not date.given after 1977 -Result: 12 DONORS -> for result +> remove all -Removed: 12 record(s) +> endfor -End of global FOR ->
The example shows how you would remove all the records of donors who have given less than 5 pints of blood and have not donated since 1977. Remember that it is much more efficient to use the indexes to narrow the class of records than to use a WHERE clause, which could have been done instead.
The DEQUEUE command, both inside and outside of Global FOR, is used to eliminate modification requests against a subfile. For instance, if a record has been updated that should not have been, the updated version may be dequeued. Like the REMOVE command, the DEQUEUE command gains additional power under Global FOR -- more than one record can be dequeued with one command.
For example, let's repeat the "disaster" that occurred earlier in this chapter [See VIII.3.] when too many records were removed by mistake:
+> display next ID 214 NAME Mack, Theodore <-- rest of record is displayed COMMENTS Iron poor blood. +> remove 214 -Removed: 214 record(s) +> for removes +> dequeue all -Dequeued: 214 record(s) +>
All of the 214 records that were accidentally removed were dequeued. Note that if other records had been removed, they too would have been dequeued. Also, if any of those 214 records had been added or updated that day, the added records would not be recovered, nor would the latest copies of the updated ones. Using the SHOW SUBFILE TRANSACTIONS and FOR TRANSACTIONS commands together, such problems could be solved, though such resurrections could be tedious. [See IX.3.] Naturally it is preferable not to get into this situation in the first place.
Sometimes you may need to create a stack in some other way than by sequencing a search result. [See I.5.2.] For example, suppose you want to sort the added records in order by the donor's name. The STACK command can be used to create a stack of records directly:
-> for adds +> stack all -Stack: 21 DONORS +> sequence name -Stack: 21 DONORS +> set format $report Name City +> in active type +>
Here we have created a quick report containing the name and city of residence for each donor who has given blood since the file was last processed, sorting the records in alphabetical order by the donor's name. (They were in key order in the ADDS class.)
The STACK command is also available outside of Global FOR. There you stack one record at a time by specifying the record key on the STACK command.
This command, exclusive to Global FOR, displays the key values of the records processed. It operates similarly to the DISPLAY command except that only keys are shown. It may be preceded by the IN ACTIVE prefix if you would like the key values to be placed in your active file.
Here is an example of the SHOW KEYS command:
-> for removes +> show keys all 11 256 258 562 +>
The command shows the keys of the four records that have been removed. (Remember that you cannot directly display the contents of these records under FOR REMOVES because only the record keys are in the deferred queue.)
This command, unlike all the others described so far, does not process any records. Instead, it shows you information about where you are in Global FOR mode:
-> for adds where blood.type = AB+
+> show keys all
946
949
955
+> show levels
Processed Examined
FOR ADDS 3 19
+>
The chart shows that of the 19 records examined in the ADDS class, three fit the WHERE clause criteria and were processed. Thus, three of the 19 records added today had a BLOOD.TYPE element value of AB-positive.
You may issue the SHOW LEVELS command anytime you are in Global FOR. If no records have been processed yet, no numbers will be displayed under "Examined" and "Processed". If there is no WHERE clause in effect when records have been processed, the two numbers shown will be the same.
Global FOR provides you with many powerful capabilities. It is used in many common subfile operations by the file owner. Besides those shown here, others will be demonstrated in the next chapter.
As the owner of a SPIRES file, there are some common file management tasks that you may want to know about. These tasks include controlling how and when your file is processed, adding or updating multiple records at one time, getting statistical information about your file, and destroying your file when you are finished with it. Several of these tasks were discussed in Chapter VII. This chapter covers other common file management tasks.
You may find everything you need to know in this chapter. If not, you may want to refer to the manual "SPIRES File Management". That manual discusses file management tasks in detail. Much of the material is geared to owners of large files (say, more than 1000 records). But Part 1 of "SPIRES File Management" consists of a primer to the detailed material and is useful to all file owners.
Occasionally the system crashes during automatic file processing. In such cases, a flag is set by SPIBILD saying that the file was not completely processed. This NOJOBGEN flag prevents the file from being processed again automatically until the flag has been reset. (You can still search and update records, however.) You, the file owner, must issue the SET JOBGEN command, telling SPIRES that you are aware that a problem may have occurred. Most of the time that will solve the problem: the file will be processed with no problems later that night. However, you should check the file the next day just to be sure. Of course, if another problem did occur, it would be noted in the output for the processing job. In that case, you should see your SPIRES consultant.
Most file owners discover the JOBGEN problem when they notice that the indexes of their subfiles do not seem to be up-to-date. To see if the NOJOBGEN flag is set, issue the SHOW AUTOGEN command when you have your subfile selected in SPIRES. If NOJOBGEN is set, the response may look like this:
-> select blood donors -> show autogen -AUTOGEN in effect (NO JOBGEN) -> set jobgen ->
Some day you may decide to get rid of your SPIRES file. When you want to destroy a single one of your files, you should issue the ZAP FILE command for that file. [See VI.4.] In addition, you should remove your file definition from the FILEDEF subfile:
-> zap file gq.jnk.blood.donors -Do you want to destroy file 'GQ.JNK.BLOOD.DONORS'? yes -> select filedef -> remove gq.jnk.blood.donors ->
In addition, if you are destroying all of your SPIRES files (or if this one is your only one), you should eliminate the ORVYL file SYSTEM.CHKPT, issuing this series of commands:
-> set clp system.chkpt -> erase system.chkpt SYSTEM.CHKPT erased in ORVYL file system ->
Do not erase SYSTEM.CHKPT unless you are destroying all your SPIRES files.
You may want to save a copy of your file definition in a public SPIRES subfile called BACKFILE. It is useful if you think you might ever want to create a file from that file definition again.
-> select filedef -> transfer gq.jnk.blood.donors -OK to clear? yes -> remove gq.jnk.blood.donors -> select backfile -> add ->
At some future date, you may reverse the procedure, i.e., transfer and remove the record from the BACKFILE subfile, add it back to the FILEDEF subfile and compile it anew. You are not charged for records you keep in these public subfiles.
The file owner can keep track of the updating activity to a subfile by issuing the SHOW SUBFILE TRANSACTIONS command:
-> select blood donors
-> show subfile transactions
06/24/83 Transaction Log of File GQ.JNK.BLOOD.DONORS
for Record-type REC01
Date Time Account Id Type Command Key Value
06/24/81 13:46:39 XW.INP S22 UPD Update 717
06/24/81 13:48:28 XW.INP S22 ADD Add 995
06/24/81 13:50:11 XW.INP S22 ADD Add 996
06/24/81 13:50:54 XW.INP S22 ADD Update 996
06/24/83 14:00:10 GQ.JNK V32 UPD Merge 13
06/24/81 15:20:12 XW.INP S22 REM Remove 104
06/24/81 15:20:20 XW.INP S22 DEQ Dequeue 104
06/24/81 15:20:30 XW.INP S22 REM Remove 105
->
This display shows the date, time, account number, terminal number, transaction request, command issued, and the key of the record processed for each transaction since the file was last processed. By examining this display, you can see who (what account) is updating your subfile.
Notice that record 996 was "added twice". The first time indicates that the record was added to the subfile; the second time indicates that the record has been updated. Because the original record was still in the deferred queue as an added record, SPIRES considers the updated version to be an added record. [See VIII.1.]
A Global FOR class, TRANSACTIONS, can be used with various Global FOR commands to access all versions of added and updated records in the deferred queue. For example, under FOR TRANSACTIONS, we could examine both versions of the new record 996, including the one added at 13:50:11, which is unavailable through FOR ADDS. That allows you to reclaim the original versions of added records that you have updated later the same day, for instance. The TRANSACTIONS class is fully discussed in the manual "Sequential Record Processing in SPIRES", section 2.8.
In most cases, records that have been removed from the subfile since the file was last processed are not displayed by TYPE and DISPLAY commands:
-> remove 184 -> display 184 -No such record, code=S256
If you need to examine the removed records, you can do so in either of two ways. In both ways the record is obtained from the tree without SPIRES first checking the deferred queue. To examine a single removed record whose key you know, use the VIA TREE prefix on the DISPLAY command. [See II.4.] To examine the stored copies of all records removed since the file was last processed, you need to create a stack of the keys of those records and then process the records in the tree with those keys:
-> for removes +> stack all -Stack: 11 DONORS +> via tree in active type +>
Using the VIA option on the TYPE command, you specify that you want to handle those records in the tree whose keys are in the current stack.
Similar techniques can be used to retrieve the "tree copies" of records that have been updated since the file was last processed. Again, you can use the VIA TREE prefix on the DISPLAY command if you know the key of the record you want to examine. Alternatively, create a stack of the keys of the updated records and process those records under the VIA TREE TYPE command.
-> for updates +> stack all -Stack: 19 DONORS +> via tree in active type (etc.)
For more information, see the manual "Sequential Record Processing in SPIRES", section 3.2.
Though any WYLBUR command can be issued from SPIRES, additional overhead is incurred when a WYLBUR command is issued, since SPIRES must examine it first to determine whether it is a SPIRES command. If you are going to be issuing WYLBUR commands more frequently than SPIRES commands, you may want to issue the SET WYLBUR command, which tells SPIRES to let WYLBUR examine the command first, passing it on to SPIRES if it is unrecognized as a WYLBUR command:
-> set wylbur COMMAND>
Although the prompt is the standard prompt for WYLBUR, you are still in SPIRES, and SPIRES commands will be recognized. Many users issue the SET WYLBUR command as soon as they enter SPIRES. [See IX.6.] (Warning: The SPIRES prompt reminds you that you are in Global FOR mode by changing from "->" to "+>". No such change will happen if you issue the SET WYLBUR command first.)
Note that you cannot use the WYLBUR facility of EXEC files when you are within SPIRES unless you have issued the SET WYLBUR command. (You may issue the EXEC command, but the file will not be executed until you exit SPIRES.) EXEC files will be executed immediately if the SET WYLBUR command has been issued.
You may issue the SET NOWYLBUR command to undo the effects of the SET WYLBUR command.
A SPIRES protocol is a collection of commands that can be invoked with a single command. The group of commands is then issued one at a time automatically. Protocols basically serve two functions in SPIRES: 1) to help you issue the same series of commands repeatedly or regularly; and 2) to help you control a user's SPIRES environment when he or she is using your data base. The first reason is more important to us here because we are working with personal data bases rather than data bases used by many other people.
A group of SPIRES commands (or WYLBUR, ORVYL or JES commands as well) may be collected in your active file and then executed using the XEQ command:
-> collect
1. > select blood donors
2. > find total.pints > 10
3. > set format $report Id(1,4,R) Name(6,30) Pints(37,R)
4. > in active clear type
5. > print cc
6. > clear select
7. > *** <-- ATTN is pressed
-> xeq
-? select blood donors <-- SPIRES begins issuing commands.
-? find total.pints > 10
-Result: 110 DONORS
-? set format $report Id(1,4,R) Name(6,30) Pints(37,R)
-? in active clear type
-? print cc
JOB 2833 JNKGQ183 AWAITING PRINT PRIO=9 FORMS=1181 LINES=118
-? clear select
->
In the above example, SPIRES used the commands collected in our active file to create a report on the people who have donated more than ten pints of blood. If this were a report we wanted regularly or frequently, we could save the commands somewhere and access them when we needed them. One way to save them might be as a WYLBUR data set, which we could retrieve by issuing a USE command before issuing the XEQ command. Another method is to create a SPIRES subfile for your protocols. [See section 12.13 of the reference manual "SPIRES Protocols".]
If you do not want SPIRES to "echo" each command to your terminal as it is issued, issue the SET NOECHO command before the XEQ command or include the SET NOECHO command in the protocol (see below).
A special subfile of protocols is the ENTRY COMMANDS subfile. If you place a protocol in that subfile, it will be executed whenever you enter SPIRES. Experienced SPIRES users commonly create a protocol that issues commands such as SET WYLBUR and SET NOLIST. You are allowed to have one protocol in this subfile. It must begin with an asterisk, followed by a blank, followed by your account number. Subsequent lines contain the commands to be executed.
-> collect
1. > * GQ.JNK
2. > !SET NOECHO
3. > SET NOLIST
4. > SELECT BLOOD DONORS
5. > * The BLOOD DONORS subfile is selected.
6. > *** <-- ATTN is pressed
-> select entry commands
-> add
-> exit
-Exiting SPIRES
COMMAND> spires
-Welcome to SPIRES ... if in trouble, try HELP
* The BLOOD DONORS subfile is selected.
->
The exclamation point (!) in front of the command SET NOECHO in line 2 indicates that this particular command should not be echoed to the terminal. The "star" command (* text) is often used in protocols to send a message from the protocol to the terminal. [See V.2.]
Protocols are the subject of their own manual, entitled "SPIRES Protocols". Their other capabilities are highlighted in the next chapter.
It is possible that this single SPIRES manual has shown you all that you need to know to construct your particular application. It is hoped that it also serves as a foundation for your use of SPIRES and that you will build upon this foundation by learning and reading about other parts of the system. Throughout this manual have appeared references to other SPIRES manuals that contain further details on particular subjects that this manual could only mention. This chapter too will reference other manuals, suggesting other topics that may interest you as you build a SPIRES application and providing a few trails of documentation for you to follow next.
SPIRES manuals are available at Document Sales in Forsythe Hall. More recent copies may be printed by issuing the SPIRES command "PERFORM PUBLISH MANUALS". Information about that service, including costs, is available by issuing that command as well. More information about the SPIRES manuals available is included in the Appendix.
The SPIRES search language is very rich and extensive. Some of its other capabilities include:
- the ALSO command -- a way to continue a search using unindexed element criteria without having to use Global FOR commands. This facility is much more limited than Global FOR, however.
- the STORE RESULT and STORE STACK commands -- two commands that let you "save" a search result or stack and restore them at any later time.
- the KEEP option on the TYPE command -- the ability to modify the search result by examining the records in it individually.
Part B of the manual "SPIRES Searching and Updating" contains information on these features and serves as the complete reference manual for searching in general.
Output formats can be written for the goal records of any subfile to display the record data any way you want. One of the best ways to discover the possibilities inherent in output formats is to select various public subfiles, such as RESTAURANT or RECIPES and display records through both the standard SPIRES format and the custom formats designed for the subfiles. Also, system formats such as $PROMPT and $REPORT have other options that make them more versatile. More information on them can be found in the SPIRES manual "Searching and Updating".
Some of the useful capabilities of output formats are:
- the ability to place element values (or any values, such as titles) wherever you want on the "output device" (usually the terminal screen or active file but also ORVYL or WYLBUR files). Values may be right-justified or centered if desired. More than one value may appear on a single line, or lines may be left blank.
- the ability to display only the elements desired. You can write formats that conditionally display an element value, using system functions and portions of the protocols language to verify the value.
- the ability to reference another record in another subfile to extract values for display. Again using a student subfile for an example, suppose that the student's record only had a set of course numbers for the COURSE element. The format could pull information for each course, such as its name, instructor, and so forth, out of the COURSE subfile and display it as part of a student's record, even though that information is not kept in the student's record itself.
- the ability to create reports, with page numbers, introductory and concluding sections or pages, and totals and other summary information for all the records being displayed or subsets of those records. As an example, most of the "Documentation Catalog", an I.T.S. document, is created from the public subfile DOCUMENTS using a report format.
The first document to read if you are interested in output formats is "A Guide to Output Formats", another in the series of SPIRES primers. Further information on formats in general may then be found in the manual "SPIRES Formats".
You have seen several methods for subfile modification in this primer, including the use of the standard SPIRES format and the $PROMPT format in SPIRES, and the use of the standard SPIRES format with the INPUT BATCH command in SPIBILD. You can also write your own input formats to read fixed or variable field data from an active file or other data file; such formats can be used either in SPIRES or SPIBILD. In SPIRES, such input formats can read information from the active file or prompt for it from the user, like the $PROMPT format. An input format can be used to update records, computing new values from the old stored values. For instance, a format for an inventory subfile could ask for, say, the number of items sold, and change the value of the number of items in stock.
More information on input formats is available in the reference manual "SPIRES Formats". Though it specifically explains output formats, the primer "A Guide to Output Formats" serves as a good introduction to formats in general, and it is recommended that you read it first.
In chapters III and IV, you learned the fundamentals of file design in SPIRES. Several other manuals explain many further extensions to the File Definer subsystem and the basic file definition language. Among the features of most interest are:
- virtual elements. These elements, mentioned earlier [See III.3.6.] have values that are not physically stored in the goal records but that are generated, usually based on other element values, when they are needed. For example, a virtual element called AGE could have its value computed by comparing the value of a BIRTHDATE element to the current date. Whenever the virtual element is displayed, its value is generated for output.
- processing rules in general. There are many varieties of processing rules for elements that were not discussed in this manual. Processing rules in their most basic form in SPIRES are called "actions", and actions are somewhat more versatile than system procs. If you find yourself using the same groups of processing rules over and over again, you can define your own "procs", so that a single proc-name can call a group of several processing rules to be executed. With the USERPROC facility, you can use the flexibility of system functions and other portions of the protocols language to process element values.
- processing rules for conversion. Though most of the element types were discussed before, there are other types of elements as well, such as TIME or REAL for time or floating-point elements respectively. Encryption of element values is also available for added security.
- processing rules for validation. Besides verifying element value length and occurrence, you can check that an element contains only certain characters or does not contain certain characters. Or you may check that the element value has specific characters at certain positions within the value. You may also check that an element value is the key value of a record in another subfile, with the option of replacing the value with another value from that other record. For example, a student goal record with a COURSE element might want to verify that the given course exists by seeing if a record with that key value is in a COURSE subfile.
- subfile logging. You can keep track of what accounts are selecting your subfile, how many records they are examining and even what commands they are issuing while your subfile is selected if you want.
- security. You can restrict or permit the use of your files by other accounts in a variety of different ways, using secure switches, USERPROCs, FILE-ACCESS statements, and others. A particular user can be given a range of permits, from no access to the file at all to the ability to process the file and issue most file-owner commands for the file. Specific elements and indexes can be "hidden" from a particular user or users. The file owner can limit the records (or even the specific elements within a particular record) that can be seen and/or updated by a given user.
These subjects and other aspects of file definition are discussed in the following manuals:
1) "File Definer". This reference manual provides full
details on the File Definer subsystem, providing complete
syntax of all options. The discussions of certain
advanced and complicated subjects of file definition are
incomplete, and the reader is assumed to be familiar with
them (if interested in them at all) from the manual below.
2) "File Definition". This reference manual is the complete
guide to file definition using the file definition
language. The manual does not cover the File Definer,
which is discussed in this primer and the "File Definer"
manual mentioned above.
Protocols are basically as simple as they appear in the discussion in the previous chapter. However, they can be used in an infinite variety of ways to perform simple or complex tasks. They are the subject of the reference manual "SPIRES Protocols", which explains how protocols are written and used and which also describes other SPIRES commands used primarily in protocols. Many of the commands and concepts of protocols may also be used within certain parts of format and file definitions.
Additional capabilities of protocols in which you might be interested include:
- compiling protocols. Protocols may be compiled so that they run more quickly and efficiently.
- variables. SPIRES has "system variables" such as $SELECT, which represents the name of the subfile you currently have selected. You may define your own "user variables" that represent whatever you choose. You may assign values to variables, verify the values, display the values or change the values, depending on the purpose of the protocol.
- functions. Functions perform particular operations on values, as do processing rules in a file definition. For example, a function called $CAPITALIZE will change all alphabetic characters in the function's argument to uppercase. Functions are used to manipulate the values of variables.
- input/output commands. You can ask the terminal user to provide particular information by
including the ASK command in a protocol. The protocol can tell the user something through
the * ("star") command. In addition, information can be sent to or read from the
active file or other files.
- condition testing. Using the IF...THEN..., THEN and ELSE commands you can vary the processing of a protocol based on certain conditions, such as the current value of a variable.
- label and comment statements. You can set off groups of commands using labels to identify them. Comment statements are also available.
- branching. Branching can be handled by the JUMP and XEQ PROC commands, directing the protocol to transfer execution to the label indicated. You can also transfer execution to another protocol altogether if desired.
Protocols are often used to control a user's environment, so that he or she can be led through a particular use of the data base rather than have to initiate the commands. They are often used in conjunction with formats and may affect their design; this may also apply to file definitions as well. If your application will be used by many novices, or if there are tasks involving your data base that will be done repetitively, you should investigate the protocols facility further.
As several of the previous sections have suggested, a SPIRES data base may consist of one or more files containing inter-related subfiles that may share data among themselves. For example, formats may be used to pull data from other subfiles for the display of a record in one subfile, presenting related information that should not be stored redundantly in more than one subfile.
Larger, more complex data base applications in SPIRES may use such features as "full-screen" record formatting, in which the user works with an entire terminal screen at a time, rather than working in "line-by-line" mode at the terminal. This means that data entry of a record can be done by moving the cursor around the screen to various fields, entering the data from the keyboard as one might type the information on a form. Then, pressing a single key on the terminal can send all the new data on the screen back to SPIRES as a new record. Though its use for data entry is most common, full-screen is also used to display records, and can even be used to display simple charts and graphs on the terminal.
Using a feature known as "path processing", you can effectively have several different subfiles selected at one time or several different formats set for a subfile at once. This feature is useful in many situations, such as when you have a data base of several different but related subfiles. Records can be displayed, added, removed, updated or dequeued from any of the subfiles that are "selected". Path processing also allows you to create multiple reports (using report formats) for a subfile even though the records are only retrieved from the file once.
Programs using these features generally reflect the interaction between formats, files, protocols, and "device services", a program that connects between SPIRES and the various types of terminals. Your SPIRES consultant can arrange demonstrations of such applications for you, as well as give you advice on how you might want to take advantage of some of these more advanced features. In fact, regardless of the projected size of your data base application, your SPIRES consultant remains your best source for advice and information about your particular application. Reading this primer should give you the ability to work independently to create and use small SPIRES files, but remember that your SPIRES consultant is available to provide help when you need it at any step along the way.
Below is a summary of the steps used to create a SPIRES file using the File Definer subsystem. Cross references to other sections of this primer are included.
keyword [=] [[value]/ attribute [=] [value]/ ... ] Some of the keywords you will probably use are FILE, SUBFILE, GOAL, ELEMENT, EXPLAIN and END.
(The following documents are not SPIRES documents per se, but describe utilities and programs that may be useful in developing SPIRES applications.)
The above documents (except any marked "in preparation") may be obtained through the PUBLISH command on the Forsythe computer at Stanford University. If you do not use SPIRES at Stanford, contact your local system administrator to find out how SPIRES documents are made available there.
SPIRES manuals are updated regularly as changes are made to the system. This does not mean that all manuals are out of date with each new version of SPIRES. The changes to the documentation match those made to SPIRES: they are usually minor and/or transparent. Not having the most current version of a manual may mean you do not have all the most recent information about all the latest features, but the information you do have will usually be accurate.
A public subfile, SPIRES DOC NOTES, contains information about changes to SPIRES manuals. Using this subfile, you can determine whether the manual you have has been updated and if so, how significant those updates are. You need to know the date your manual was published, which is printed at the top of each page. For details on the procedure, issue the command SHOW SUBFILE DESCRIPTION SPIRES DOC NOTES.