******************************************************************
* *
* 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.
The Stanford Public Information REtrieval System (SPIRES) is designed to permit easy access to information. SPIRES commands are simple English words; those you will learn here help you search for specific material within "subfiles" of information. (A SPIRES subfile is an online collection of records. You could think of a subfile as a more streamlined and accessible version of the file of records that offices sometimes keep in filing cabinets.) You do not have to be a computer programmer or know any other computer language to use SPIRES. However, you should be familiar with WYLBUR, the text-editing system, and it is assumed that you know how to log on to the computer.
A sample SPIRES session is included as an appendix to this document; you may want to glance at it now and then as you read the manual to see what a search in an actual SPIRES session looks like.
The complete introduction to using SPIRES is the "SPIRES Searching and Updating" manual, which at over 300 pages is rather lengthy for a beginning overview. This guide is intended as a short summary, an "introduction to the introduction", designed primarily to teach novices how to search SPIRES subfiles to retrieve information and display it. It should also be useful to people who need to refresh their SPIRES searching skills with a quick review of the important commands. It is not, however, a complete guide to searching and updating SPIRES subfiles; in fact, updating is not covered in this document at all.
For further information about a particular topic or about SPIRES in general, you should consult the larger manual, which can be found in the study racks in Forsythe Hall and is available for purchase at Document Sales in Forsythe Hall here at Stanford. Cross references to appropriate sections of "SPIRES Searching and Updating" are included and look like this: [B.4]. That example references section B.4 of the larger manual.
Most of the examples of SPIRES commands in this guide use the "Restaurant" subfile. This subfile contains information about particular restaurants primarily in this area, and is a public subfile which any I.T.S. account owner can access. Because anyone can add or change records in this subfile, it is possible that the results you get when trying a given example might be different from the results shown here. Don't be afraid to try the examples or even to invent your own. You cannot change or harm the contents of a subfile using any commands taught in this guide, so feel free to experiment with them.
One final word about the examples: the user's commands to SPIRES (those you would type at your terminal) are printed in lower case; responses from SPIRES are printed as they would appear on your terminal, often in upper case. A command's syntax is often printed in both cases -- words in upper case should be typed as shown; words in lower case stand for a value which you supply. (The EXPLAIN command in Section I.4 is a good example of this form.) These conventions are used to make the examples simpler to understand. When you are actually issuing commands to SPIRES, case does not matter -- you can type your commands in upper, lower or any mixture of cases.
Before you can use SPIRES files, you must enter the SPIRES environment. After logging on to the computer, issue the SPIRES command:
COMMAND> spires
You will receive a welcoming message from SPIRES which will end with the SPIRES prompt "->". If you issue the SET UPPER command in WYLBUR the SPIRES prompt will be "-?". When it issues the prompt, SPIRES is ready for your commands. While in SPIRES, you can issue any SPIRES, WYLBUR, ORVYL, MILTEN or HASP command. If the command is not a SPIRES command, SPIRES will pass it to the appropriate system for processing. [A.2.2]
When you are ready to leave the SPIRES system, type "EXIT" and you will be returned to WYLBUR's control. Note that you can logoff without exiting SPIRES first. [A.2.3]
-> exit -Exiting SPIRES COMMAND> <---You are returned to WYLBUR
Whenever you are using SPIRES and you are not sure what to do next, try issuing the HELP command:
-> help
SPIRES will make suggestions about what you can do, depending on what you have already done. For instance, if you type "HELP" when you first enter SPIRES, you may be told that you have not selected a subfile to use. (See Sections II.1 and II.2.) Later, after you have issued other SPIRES commands, issuing the HELP command will give you different suggestions for what to do, based on an evaluation by SPIRES of your commands.
The HELP command is usually a good place to start when you are having trouble in SPIRES. [A.3.1.1]
Another online aid is the EXPLAIN command, which is very useful to both novice and experienced SPIRES users. Almost 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 can ask SPIRES to clarify it by using the EXPLAIN command. The syntax of the command is:
EXPLAIN term
where the "term" can be virtually any SPIRES concept or facility.
The EXPLAIN command displays pertinent sections from SPIRES documentation to define and describe the term and, often, to show you command syntax or examples. [A.3.1.3] Here are some examples showing you how to get such explanations using the EXPLAIN command:
-> explain tracing <---explanation of a facility -> explain e45 <---explanation of an error code -> explain explain <---explanation of a command
Many SPIRES subfiles that you will search have their own explanations, provided by the file owner, discussing their purpose or giving you suggestions on how to search them. The command "SHOW SUBFILE DESCRIPTION subfile-name", where "subfile-name" is the name of the subfile you want, will provide this explanation to you if it exists. [B.2.2]
The responses SPIRES gives to either the HELP or EXPLAIN commands can be placed in your active file if desired. Just precede the command with the IN ACTIVE prefix:
-> in active help
or
-> in active explain exit
The resulting information can be printed or saved using WYLBUR commands. (If there is already material in your active file, SPIRES will prompt "OK to clear?") Many other SPIRES commands, including almost all SPIRES commands beginning with the word SHOW, can be prefixed with "IN ACTIVE"; many of these commands are discussed later in this guide. Other options available with the prefix are discussed in detail in "SPIRES Searching and Updating". [A.2.9.1]
After you have issued a command using the IN ACTIVE prefix, SPIRES may begin listing your new active file. If you do not want to look at it then, you can press ATTN/BREAK to stop the listing. Since the material was placed there before the listing began, stopping the display will not affect the active file.
SPIRES users often maintain their own collections of information. They build their own SPIRES files, which are made up of subfiles. Most files contain only one subfile. While the distinctions between files and subfiles are important to the data base owner, they do not affect the searcher, whose contact with the file is almost always through the subfiles.
Most SPIRES subfiles consist of two kinds of records: "goal records" and "index records". Goal records are what you are searching for -- they are your goal in a search. In a personnel subfile you would be searching for an employee's record, which would probably include a name, address, social security number and so forth; each personnel record is a goal record. Similarly, in a bibliographic subfile, the goal records would probably 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 look in a book's index for references ("pointers") to pages containing a certain word, SPIRES looks in a subfile's indexes for pointers referring to goal records containing a certain value. Unlike most books, however, SPIRES subfiles usually have more than one index, referencing different types of information separately. For instance, the "Restaurant" subfile has separate indexes on the name, street address, city, state, cuisine and entertainment information found in the goal records of restaurants. [B.1]
To search a subfile, you must first tell SPIRES which subfile you want to search, then issue search requests and display the results.
To do any searching, you must first choose a SPIRES subfile. If you know which subfile you will be searching, use the SELECT command:
SELECT subfile-name
For example, to use the subfile named "Restaurant", you would type:
-> select restaurant ->
where the returned "->" prompt shows that the subfile is ready to use. [B.2.3]
If you can't remember the name of a subfile or its correct spelling, or if you just want to see a list of all the subfiles available to you for searching, issue the command "SHOW SUBFILES". [B.2.1] The long list of subfiles can be placed in your WYLBUR active file using the IN ACTIVE prefix discussed in section I.5. When you have found the desired subfile name, use the SELECT command as described above to tell SPIRES which subfile you want to search.
There are many public subfiles that you can use to practice the SPIRES commands you learn in this manual. They are owned by I.T.S. or by various local, state and national organizations.
One example of an I.T.S. subfile is MASTERLIST, an online index to the Campus Facility Program Library. The PLANTBIO subfile contains bibliographic citations about botany, developed by the Carnegie Institution's Plant Biology Lab at Stanford.
Some public subfiles are used primarily as examples in SPIRES classes or documentation. These are usually good choices when you want to practice SPIRES commands. Examples are RESTAURANT (a subfile containing restaurant reviews, used in the examples in this primer), RECIPES, DRINKS, and UNITED STATES.
For more information about any particular subfile, use the SHOW SUBFILE DESCRIPTION command, described in section I.4. Data base owners can allow or disallow public access to their subfiles -- some of the subfiles mentioned here may not be available when you read this booklet. The SHOW SUBFILES command will always tell you which subfiles are currently available to you.
To start a search after selecting a subfile, you must tell SPIRES three things: first, that you want SPIRES to search the subfile; second, what index you want SPIRES to use in the search; and third, what values you'd like SPIRES to find in that index. All this can be done in one command, called a "search request".
When you issue a search request, SPIRES scans the index(es) 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". Search requests can be simple or complex, cheap or expensive, depending on how carefully you construct them.
Though you do not have to issue the commands discussed in this section in order to search a subfile, searching will be much easier for you to accomplish if you can use and understand them. The three commands are SHOW INDEXES, BROWSE, and SHOW SUBFILE SIZE. The IN ACTIVE prefix discussed in section I.5 can be used to place the SPIRES response to any of these commands into your active file.
Before issuing the search request, you should know what indexes are available for searching. Once you have a subfile selected, you can issue the command "SHOW INDEXES". For example,
-> select restaurant
-> show indexes
Goal Records: RESTAURANT
Combined Index Terms:
DATE-ADDED
DATE-UPDATED
PRICE-RANGE
PRICE-AVERAGE
FOOD-QUALITY
SERVICE-QUALITY
CREDIT
BAR
Simple Index: N, NAM, NAME
Simple Index: C, CUIS, CUISINE, T, TYPE, TYPE-OF-FOOD (Synonym)
Simple Index: A, ADD, ADDRESS, ST, STREET
Simple Index: RES, RESERVATIONS
Simple Index: H, HOURS, HRS
Simple Index: E, ENTER, ENTERTAIN, ENTERTAINMENT
Simple Index: CITY
Simple Index: STATE
The list shown indicates all the different indexes you can use to search the subfile. Any of the index names (such as "cuisine") or their indicated aliases (such as "c" or "cuis") can be used in a search request. [B.3.1.1]
As you can see, a subfile may contain different types of indexes, the most common of which are the "simple index" and the "combined index". While there are important distinctions between these two types, they are relatively unimportant to the searcher. The two distinctions pertinent to you as a searcher are that you cannot BROWSE a combined index (see below) and that two of the range operators (BETWEEN...AND... and FROM...TO...; see section III.3.3.) cannot be used to search a simple index. [B.3.1.3]
There are two other kinds of indexes that only rarely appear in the list of a subfile's indexes: the sub-index and the qualifier. [B.3.5.8, B.3.5.9]
As noted before, you tell SPIRES three things in a search request: first, that you want to search the selected subfile; second, what index you want to search (chosen from the list displayed by the SHOW INDEXES command); and third, what values you want SPIRES to find in the index. But the type of values contained in an index are not always obvious from the index name. It would be useless, for example, to look for a word (a character string) in an index that contained only numbers.
The index names usually suggest what kind of information is inside -- for instance, in the "Restaurant" subfile, the "state" index probably includes state names of this country. But does the "hours" index contain lists of numbers, as the index name might indicate? Actually it doesn't; the way to find out what types of values are in this simple index is with the BROWSE command. Its syntax is:
BROWSE index-name
When you issue this command, SPIRES will present you with a list of sample values taken from the index. For example, to find out what values are in that "hours" index:
-> browse hours BREAKFAST DINNER LUNCH
The BROWSE command can provide you with more than a sample list of values. Using different forms of the command, you can select specific "areas" of the index to BROWSE alphabetically. The complete form of the command is:
BROWSE [FIRST|LAST] index-name [value]
where the material inside the brackets is optional. (Note that you do not type the brackets when issuing the BROWSE command with any of the options.) If you want to see what values are indexed around a particular value, you can use the "value" option. For example, using the "cuisine" index, you can see what other values are indexed near the word "chinese".
-> browse cuisine chinese BRITISH CALIFORNIAN CASSEROLES CENTURY CHEESECAKE CHINESE CHIPS COFFEEHOUSE COFFEES COLONIAL -More? no ->
If you want to see more values, you may, of course, respond "yes" to "-More?". Note that you do not have to specify a value that is included in the index -- for instance, you could have typed "BROWSE CUISINE CHIN" or "BROWSE CUISINE C". (Note also the "peculiar" values in this index, such as "century" and "chips" which do not seem to relate to "cuisine" in any meaningful way. They are caused by "word indexing", which is discussed later in this guide.)
Similarly the commands BROWSE FIRST or BROWSE LAST, followed by an index name, will show you the first or the last values included in the index. By repeatedly responding "yes" to the "-More?" prompt over and over again, you can look at all the indexed values. You cannot use the FIRST or LAST option with the "value" option. [B.3.6.3]
On some indexes the results of a BROWSE command may appear nonsensical. You may get sample values that look like this: "###" or "##$###". The BROWSE command displays values as they are stored within the indexes; sometimes subfiles convert values into different forms for more compact storage. With most SPIRES commands that display data from the record, a reconversion takes place. Under the BROWSE command, however, no automatic reconversion takes place and "raw data" might be shown to you. In such cases, the BROWSE command will obviously be of little use.
Remember that the BROWSE command may not be used on combined indexes.
SPIRES subfiles vary in size. Some have only a few goal records; others have hundreds of thousands of them. If you would like to know how many goal records a subfile contains, issue the command "SHOW SUBFILE SIZE". [B.2.4]
-> select restaurant -> show subfile size -The subfile has 83 records.
Simple search requests consist of two parts: the command verb "FIND" and a "search expression". The search expression states the criterion to be used in selecting records. It consists of three parts: the name of the index to be searched, a "relational operator" (see the next section) and a search value. For example, to find restaurants in Palo Alto, you might type:
-> select restaurant -> find city = palo alto
In this search request "city" is the name of an index in the subfile, "=" is the relational operator, and "palo alto" is the search value. It is the search value that is compared against all the values in the specified index. (Note that it does not matter whether you use upper, lower or a mixture of case in a search request.)
Here is the syntax of a search request:
FIND index-name relational-operator search-value
More examples of search requests are shown below in the discussion of relational operators. [B.3.2.1, B.3.2.2]
When you issue a search request, SPIRES goes to the specified index and finds index records fitting the criteria stated. In the above example, for instance, SPIRES would go to the "city" index in the "Restaurant" subfile and find the index record for the value "Palo Alto". If there were no index record for the value "Palo Alto", SPIRES would respond "-Zero result". Each index record contains pointers to the goal records containing that indexed value. SPIRES collects the set of relevant pointers, counts how many different ones there are and tells you the number, which is thus the number of goal records that meet the search criteria. (Note that SPIRES only displays the number of goal records; to display the actual records takes another command, discussed in section IV.)
A search request and the SPIRES response look like this:
-> find cuisine = mexican -Result: 5 RESTAURANTS ->
According to SPIRES, five goal records in this subfile contain a "cuisine" index value of "Mexican". Those five goal records are the search result.
Each search request must have a "relational operator", a word or symbol that defines the relationship between the search value and the values you want to retrieve. There are four types of relational operators: the equality operator, inequality operators, range operators and content operators. [B.3.2.3]
When you want to find records with a specific indexed value, use the equality operator. In SPIRES, "=" or just a blank space is the equality operator. For example:
-> find name = pistachio's -> find street middlefield
The inequality operators are arithmetic symbols. They are most useful for searching indexes where the values are numeric, but can be used on any index. They are:
~= (not equal to) ["~" appears as a tilde on many terminals] > (greater than) >= (greater than or equal to) < (less than) <= (less than or equal to)
For example,
-> find price-average < $6.00
would retrieve records of restaurants where the average price is less than six dollars.
-> find name ~= mcdonalds
would find all the records whose name value is not "McDonalds".
Range operators find index values within the specified range. They are sometimes interchangeable with the inequality operators. The four range operators are:
BEFORE AFTER BETWEEN...AND... FROM...TO...
They are most efficiently used to search combined indexes; in fact, the last two cannot be used on simple indexes at all.
Here are some examples of their use:
-> find date-updated after june 1978 -> find date-added before august 1975 -> find price-average between $5.00 and $8.00 -> find price-average from $5.00 to $8.00
Note that in the first three examples, records whose indexed values are equal to the search value or values would not be included in the search result -- that is, in the first example, a record whose "date-updated" index value is "June 19, 1978" would not be included. However, in the fourth example, which uses the FROM...TO... operator, records whose "price-average" value is "$5.00" or "$8.00" would be retrieved, along with those within the range.
Content operators are used when you can only specify part of a value as your criteria (only part of a street address, for instance).
Content operators should be used more sparingly than the other operators -- they are generally the most expensive to use. A search using the content operators can cost several times more than a search using the equality operator which might get the same search result. Some cautions about using the content operators are discussed in the section on "word indexing" (section III.6.1).
Four of the content operators are discussed below. Two others, the HAVING and WITH operators, are infrequently used. They are included in "SPIRES Searching and Updating". [B.3.2.3]
The PREFIX operator specifies that any value retrieved must contain the designated characters in sequence at the beginning of the value. For example,
-> find name prefix pista
can be used if you can't remember how to spell "Pistachio's". The record for "Pistachio's" would be retrieved; so would the records of any other restaurants with the string "pista" at the beginning of an indexed "name" value.
SPIRES can search an index for values with a particular "prefix" quite efficiently; thus, the PREFIX operator is less expensive to use than the other content operators.
When you use the SUFFIX operator, SPIRES looks for the search value at the end of the indexed values. For example,
-> find city suffix to
would retrieve records whose "city" value ends with "to", such as "Palo Alto" or "Sacramento".
This operator causes SPIRES to search for the specified word or words anywhere in the indexed values. Indexed values in which the word or string of words are surrounded by blanks are retrieved. For example,
-> select documents -> find course word spires -Result: 5 DOCUMENTS
retrieves documents used in classes that have the word "SPIRES" in the course name. For instance, some of the classes might be "SPIRES Data Management" and "Introduction to SPIRES". If the search request had specified "find course word spire", no documents relevant to these courses would have been retrieved, since "spire" is not completely surrounded by blanks in either of these cases.
The WORD operator is not useful when you are searching a "word index"; in fact, it is unnecessary and quite expensive. See Section III.6.1 for relevant information about word indexes.
STRING specifies that any value retrieved must contain the designated characters in sequence contiguously to qualify for the search result. Blanks may be included within the search value. For instance,
-> select documents -> find course string intro
would retrieve records of documents used in "Intro" courses, such as "Introduction to PL/I" or "SPIRES Introduction".
The LIKE operator is used to search for character strings in sequence with the option of including two "wild card" characters in the search value. The "wild card" characters are:
the _ (underscore), which SPIRES interprets as "any one character in this position"; and the ? (question mark) which means "zero, one, or many characters in this position."
For instance,
-> select restaurants -> find name like ch_n
would retrieve the record "Chin Yeh," whereas
-> find name like ch?n
would also retrieve the restaurants "King Chuan" and "The Neon Chicken." The "wild card" characters can be used at the beginning or end of a text string. If you entered the command:
-> find name like ch?n?
SPIRES would, in addition to the above records, retrieve the records "Chinese Kitchen" and "Chantilly Restaurant."
Blanks may be included within the search value, unless the index is a "word index."
The \ (backslash) is a reserved character that tells SPIRES to interpret the _ (underscore) and ? (question mark) literally; e.g., \? is interpreted as a literal question mark, not as a "wild card."
So far, your searching has been limited to locating records fitting simple criteria using single indexes. But suppose you would like to further qualify a search result, using the information in a second index. For instance, suppose you want to find a restaurant in Stanford Shopping Center where you can eat for less than $3.00. Obviously you could find the restaurants whose "address" is Stanford Shopping Center and the restaurants whose "price-average" index value is less than $3.00 and compare the lists. However, SPIRES can do the work for you; all you do is issue "iterative search requests".
The FIND command starts a new search everytime it is issued. In order to add further criteria to an existing result, you type a logical operator (either "AND", "AND NOT" or "OR"; see below) followed by a search expression.
For example,
-> find address stanford shopping center -Result: 3 RESTAURANTS -> and price-average < $3.00 -Result: 1 RESTAURANT
Iterative searches can be constructed of any number of search expressions, each preceded by a logical operator at the start of the line. [B.3.3]
If you are issuing iterative commands using the same index, you do not need to repeat the index name. For example,
-> find city san francisco -Result: 5 RESTAURANTS -> or sacramento -Result: 7 RESTAURANTS
In the above example, a blank is used in both commands as the equality operator. Other relational operators can of course be used.
Logical operators used in iterative searches serve as commands telling SPIRES to continue the search, using the additional criterion.
The AND operator indicates that retrieved records must satisfy both criteria. For example,
-> find city = palo alto -Result: 22 RESTAURANTS -> and bar = cocktails -Result: 9 RESTAURANTS
meaning that there are nine records in this subfile for Palo Alto restaurants with cocktail bar service.
The AND NOT operator requires that goal records that would have been included using the AND operator be excluded from the result.
-> find city palo alto -Result: 22 RESTAURANTS -> and not bar = cocktails -Result: 13 RESTAURANTS
retrieves records of Palo Alto restaurants that do not have cocktail bars.
The OR operator requires that records that satisfy at least one of the criteria be included in the result.
-> find city palo alto -Result: 22 RESTAURANTS -> or bar cocktails -Result: 42 RESTAURANTS
would give you records of restaurants in Palo Alto and records of restaurants which have a cocktail bar (not necessarily in Palo Alto).
Be careful of the distinctions between the operators AND and OR as used in SPIRES and as used in casual speech. If you translate a sentence such as "Find all the restaurants in Palo Alto and Menlo Park" into the search command "FIND CITY PALO ALTO... AND CITY MENLO PARK", any restaurant retrieved would have to be located in both Menlo Park and Palo Alto. The correct translation would be "FIND CITY PALO ALTO... OR CITY MENLO PARK" which would retrieve records of restaurants located either in Palo Alto or Menlo Park.
Occasionally while making iterative searches, you may make a mistake. Suppose you issue the following search:
-> find city palo alto -Result: 25 RESTAURANTS -> and street el camino real -Result: 8 RESTAURANTS -> and price-average > $3.00 -Result: 5 RESTAURANTS
and you realize that you meant "less than" three dollars, not "greater than". Rather than issue all the commands over again, issue the BACKUP command.
-> backup -Result: 8 RESTAURANTS
The BACKUP command replaces the current search result with the search result "one step back" in an iterative search. Since SPIRES only keeps the current result and the previous one, the BACKUP command cannot be issued twice consecutively. Also, whenever another FIND command is issued, SPIRES erases all previous results; thus you cannot BACKUP right after a FIND command.
You may sometimes reduce an iterative search result to zero -- that is, your last command was too restrictive, and no records in the previous search result fit all the criteria. SPIRES automatically "backs up" when this happens, keeping the previous search result. [B.3.3.2]
-> find city palo alto -Result: 25 RESTAURANTS -> and city menlo park -Zero result, previous result retained -Result: 25 RESTAURANTS
Each part of an iterative search begins as a separate command on a new line. It is possible to combine the parts of an iterative search on one input line, connecting the parts with the appropriate logical operators. For example,
-> find hours lunch -Result: 43 RESTAURANTS -> and credit = card -Result: 19 RESTAURANTS
can be entered instead as
-> find hours lunch and credit = card -Result: 19 RESTAURANTS
This is called the compound FIND command. More than two search expressions can be included in a compound FIND command, if desired. [B.3.4]
Just as with iterative searches, if a search expression uses the same index name as the preceding search expression, you do not need to repeat the index name. For example, to find restaurants in either California or Oregon,
-> find state california or oregon
The order in which three or more expressions are written in the search request can affect the way it is evaluated. Sometimes SPIRES may interpret a search request quite differently from what you think you requested. For example, if you know of a French restaurant that is either on El Camino Real or University Avenue, you might want to type
-> find cuisine french and street university avenue or el camino real -Result: 14 RESTAURANTS
However, what you are actually requesting, evaluated left to right, is this: restaurants that serve French food and that are on University Avenue, or any restaurants that are on El Camino Real. What you really meant is
-> find street el camino real or university avenue and cuisine french -Result: 4 RESTAURANTS
Another way to clear up ambiguity is to use parentheses. Parentheses specify explicitly the order in which logical operations are to be performed.
Here is the original search request with parentheses added to get the desired result:
-> find cuisine french and (street el camino real or university avenue) -Result: 4 RESTAURANTS
Parentheses may be nested inside other parentheses, if necessary. As in algebra, expressions are evaluated starting with the innermost parentheses and proceeding from left to right within each parenthetical level. Here is a more complicated example, using nested parentheses:
-> find city palo alto -Result: 19 RESTAURANTS -> or ((city menlo park or mountain view) and street el camino real) -Result: 28 RESTAURANTS
which would find restaurants either in Palo Alto or on El Camino Real either in Menlo Park or Mountain View.
Sometimes confusion can arise if you are searching for a value that is also the name of an index or a relational operator. Suppose, to use a contrived example, that you want to find the record for a restaurant called "Bar One" or "Bar None", but you're not sure which is correct. This search request:
-> find name bar one or bar none -Result: 8 RESTAURANTS
would retrieve all restaurants named "Bar One" and all restaurants not serving any alcoholic beverages. (Remember that "Bar" is an index name for the subfile.) To get the result you want, use quotation marks around the search values:
-> find name "bar one" or "bar none"
Usually quotation marks or parentheses correctly placed will clear up confusion and ambiguity in search requests. [B.3.4.2, B.3.6.4]
Occasionally in this guide you have seen the phrase "word index". Several special types of indexing can be used in subfiles, making internal file storage less expensive and more efficient. They can also help you in searching if you know they exist and know how to use them.
Here are some brief discussions of several of them. For more information, including discussions of sub-indexes, qualifiers and other infrequently used tools, see section B.3.5 of "SPIRES Searching and Updating".
Many data elements (see section III.7) in the "Restaurant" subfile can be strings of text; for example, the "name" element in a record for "Golden Skillet" would contain two words. In indexing such values, most subfiles index the individual words of the string, rather than the whole string itself. Thus, in the "name" index, there would not be a record for "Golden Skillet" with one pointer to the "Golden Skillet" goal record; there would be two records, one for "Golden" and one for "Skillet", each with a pointer to the "Golden Skillet" goal record.
In a search, either
-> find name golden
or
-> find name skillet
would retrieve the goal record, along with any other records containing a "name" element that had either "golden" or "skillet" as a word. However, suppose you know the whole name (or more than one word of it) and thus enter
-> find name golden skillet
Practically all subfiles with word indexes are designed so that a search value of more than one word is split up into individual words, each separated by the logical operator AND. Therefore, the above search request is interpreted by SPIRES as
-> find name "golden" and "skillet"
An advantage of word indexing is that searchers need not remember a whole string of text that is indexed -- just a small portion will suffice to retrieve the record.
To see whether an index is word-indexed, you can use the BROWSE command. SPIRES will usually display enough sample values for you to determine whether you are using a word index. If all the values are single words, you probably are. (See the example in III.1.2.)
The equality operator is the most efficient operator to use to search word indexes. The least efficient operators are the content operators. Often, when a word index is involved, a search using a content operator could be written using the equality operator instead, saving considerable searching time and expense. For instance, the WORD operator should never be used on a word index; the equality operator gives equivalent results at much less cost. More useful information about searching word indexes can be found in B.3.6.5 of "SPIRES Searching and Updating".
Some words in an indexed element are unnecessary to index; these words are often short conjunctions or articles, such as "the" or "and". Subfiles often have "exclusion lists" which keep such words from occurring in the index. Usually the exclusion list will not affect your searching. For instance, in the "name" index, "the" is an excluded word. If you use it in a search, it will be ignored.
-> find name the winery
SPIRES would interpret the request as
-> find name winery
and any restaurant record with a name element including the word "winery" would be retrieved. (Remember that the "name" index is a word index.)
However, if you are looking for a specific restaurant and all you can remember is that its name began with "the", you will not be so successful.
-> find name the -Request has no content -Zero result ->
The first line of the SPIRES response indicates that all of the words in the search value are in an exclusion list for that index.
On the other hand, an index may have an "inclusion list"; only the words in the list are permitted to be indexed. If your search value is not in the inclusion list, you will get an error message. Any exclusion or inclusion list is chosen by the file designer and thus will differ for different subfiles. In the "reservations" index, the file designer chose to allow only three values: "recommended", "required" and "unnecessary". (You can use the BROWSE command to see sample indexed values in simple indexes.) If your search value is not in the inclusion list, you will get an error message.
-> find reservations none -Element=RESERVATIONS: Illegal Input -Serious data error, code=E46 -Not a legal or complete command
Since "none" is not one of the allowed values, the search is rejected. The error message can be explained, if desired, using the EXPLAIN command. (See I.4.)
If a subfile indexes the names of individual people, the index is usually constructed with "personal name indexing". This structure permits you to search records with indexed name elements when you have a different form of the name than might be indexed. (Since no names are indexed in the "Restaurant" subfile, examples in this section will use the "People" subfile.)
For example,
-> select people -> find name john sousa
would retrieve goal records for John Sousa, John Philip Sousa, J. Philip Sousa and J. P. Sousa. Likewise, the search requests
-> find name john philip sousa
or
-> find name j. philip sousa
or
-> find name sousa, john philip
would yield the same records as mentioned above. (In search requests, names can be inverted, last name first, where name indexing occurs; a comma must be used to separate the last name from the first name.)
SPIRES accomplishes this by matching. If a search request contains a name that does not match some character string in the indexed element, that record is not included in the search result. Thus,
-> find name john philip sousa
would not retrieve a record of J. Sousa, since "Philip" is in the search request but not the record. That same record would be retrieved by
-> find name john sousa
Like personal names, dates can be given special treatment in subfiles. Usually, if a subfile indexes dates, it allows searching for dates in all of the various ways of writing them. For example,
-> find date-added july 7, 1977 -> find date-added jul 7, 1977 -> find date-added 7 july 1977 -> find date-added 7 jul 77 -> find date-added 7/7/77 -> find date-added 7/7/1977
Date indexes are usually constructed to permit a record with a specific date, such as July 7, 1977, to be retrieved by searches such as
-> find date-added july 77 -> find date-added 1977
which would retrieve all records with a "date-added" of anytime in July of 1977 or anytime in 1977 respectively.
Goal records consist of information. In a subfile each goal record contains similar types of information -- for instance, in the "Restaurant" subfile, each goal record contains similar information about a restaurant, such as its name, address, hours and so forth. These basic units of information in a record are called "elements". Thus, in the "Restaurant" subfile, a goal record has a "name" element, an "hours" element, a "state" element and so on. An element in a particular record may have several values, only one value, or no value at all.
Records are added to subfiles as goal records; indexes are then built from the elements within the goal records. Many of the elements in a goal record may be "passed" to various indexes to be index values -- for instance, the value of the "state" element (say, "California") is passed to the "state" index to serve as the indexed value "California". (Whoever designs the file itself chooses the elements and the indexes to be built from them.) A pointer back to the original goal record, where the original value is still contained, is then created for the index. [B.1.1]
Some elements in a goal record may not be indexed, but occasionally it is necessary to find records with a particular value for some non-indexed element. There are several ways to search unindexed information in SPIRES. [B.5] The easiest way uses the ALSO command. However, before using it, you need to know the names of the elements in the subfile you are searching. They can be listed using the SHOW ELEMENTS command.
To get a list of all the possible elements in a specific subfile's goal records, type the SHOW ELEMENTS command. [B.4.1]
-> select restaurant -> show elements Subfile RESTAURANT ID DATE-ADDED, DA, DADD, DATEADD DATE-UPDATED, DATEUP, DU, DUP NAME, N, NAM LOCATION . CITY, AR, LOC . STATE . PHONE, NUM, NUMBER, PH . ADDRESS, A, ADD, ST, STREET . ZIP-CODE, ZC, ZIP . LOC.D RECOMMENDER, REC, RECOM COMMENTS, C, COM CUISINE, CU, CUIS, TYPE-OF-FOOD PRICE-RANGE, R, RAN, RANGE PRICE-AVERAGE, AVE, P, PRICE FOOD-QUALITY, F, FOOD SERVICE-QUALITY, S, SER, SERVICE CREDIT, CR, PAY, PAYMENT RESERVATIONS, RES HOURS, H, HRS ENTERTAINMENT, E, ENTER, ENTERTAIN BAR, B
The IN ACTIVE prefix can be used to place this list in your active file.
You should compare this list with the list of indexes to the "Restaurant" subfile, shown by the SHOW INDEXES command. (See section III.1.1.) Note that these are two different lists; some elements may not be indexed. Note also that no relationship necessarily exists between an element and an index that share the same name, although usually if they do share a name, the index contains values of that element. Also, element names are often in code or abbreviated, and they may not mean anything to you. (There is a way to display records so that you can see values for a given element and thus see what types of values the element can have. It is discussed under "The TYPE element-list Command" in section IV.1. See also the discussion on "The CLEAR FORMAT Command" in section IV.2.)
Finally, note in this example that one element ("location") is called a "structure", and beneath it are six other element names. Structures allow related information, such as parts of an address, to be kept together in the record.
The ALSO command can be used to search unindexed elements in goal records. [B.5.3.2] However, its use is restricted. First, it can only be used if a search result already exists. Second, it can only be used iteratively, issued on a separate line; it cannot be used as part of a compound search request.
Suppose you have the phone number for a Menlo Park restaurant.
-> find city menlo park -Result: 5 RESTAURANTS -> also phone = 322-4343 -Result: 1 RESTAURANT
Notice that you still have a search result -- that is, you can continue issuing iterative search commands, including more ALSO commands.
The syntax of the ALSO command is:
ALSO [NOT] element-name relational-operator search-value
where "element-name" is the name of the particular element you want SPIRES to examine, chosen from the list of elements displayed by the SHOW ELEMENTS command. NOT is optional, and the brackets are not typed if NOT is used. ("Relational-operator" and "search-value" were discussed in section III.2.)
SPIRES will directly examine the goal records in the search result for element values that fit the criterion of the ALSO command. Those records that do contain element values that fit the criterion are kept in the search result; all others are removed. If the NOT option is used, the reverse is true: those records that contain an element value that fits the criterion are removed from the search result, while the rest are retained.
The content operators are particularly valuable for searching using the ALSO command. Though they are generally inefficient to use to search indexes, they are just as efficient as any other relational operator when searching unindexed information. However, you should be aware that searching unindexed information in goal records is less efficient than searching indexes, and thus more expensive. [B.5.3.1]
Eventually you will want to examine the records retrieved by your searching. Anytime you have a search result, you can issue the TYPE command, which will display all the records in the result to you. The TYPE command is very flexible; its use and options are discussed below.
SPIRES displays records in "formats". Records can be displayed using the SPIRES default format, using custom formats designed for the subfile, or using formats that you design. You can selectively display parts of records using the "TYPE element-list" command. Somewhat more sophisticated is the $REPORT format, which permits you to design your own tabular format for displaying information in records. The SET FORMAT $REPORT command is also discussed in this section.
Whether you display records in tables or in their normal output format, you may want to have some control over the order of the records. Using the SEQUENCE command, you can arrange the records in a search result by some order based on element values. The SEQUENCE command is discussed at the end of this section.
The TYPE command issued alone will display all records in the search result to you. It displays them either in some custom format designed for the particular subfile or in the standard SPIRES format, which simply lists the elements and their values for each record. The TYPE command can be issued at any time during a search. A search can still continue iteratively even after a TYPE command. [B.4.6]
A complete search might look like this:
-> select restaurant -> find food-quality excellent -Result: 44 RESTAURANTS -> type
and a long display of all 44 restaurants, displayed in a custom format for the subfile, would begin. The TYPE command does not alter the contents of your active file. If you would like to place the display in your active file, use the IN ACTIVE prefix.
-> in active type -OK to clear? ok
and the records are placed in your active file.
The TYPE command has several options. The complete syntax of the command is
TYPE [element-list] [SKIP=n] [KEEP|PAUSE] [CLEAN]
where the bracketed material is optional. (When you issue the command, do not use the brackets. See the examples in the following sections.) (The vertical bar ("|") means "or"; you can use either the KEEP or PAUSE option, but not both.)
Each option is discussed briefly below. If you use more than one option in a single TYPE command, the element list, if used, should be specified first.
The TYPE command issued alone causes SPIRES to display all of the goal records in the search result, usually in complete form. For a large search result, such a display can be very lengthy and may show you a great deal of extraneous information. If you only need to look at the values of certain data elements in a record, you can use the "TYPE element-list" command to limit the display of records to those elements you particularly want to see. [B.4.3.2] Remember that a list of goal record elements for a subfile can be produced with the SHOW ELEMENTS command.
To use the command to display only certain elements of the records, enter the TYPE command, followed by the list of elements you want displayed. For instance,
-> find city menlo park -Result: 4 RESTAURANTS -> type name address NAME = Dutch Goose; ADDRESS = 3567 Alameda de las Pulgas; NAME = Le Pot au Feu; ADDRESS = 1619 El Camino Real; NAME = Ken's House of Pancakes; ADDRESS = 888 El Camino Real; NAME = Oasis; ADDRESS = El Camino;
Remember that the IN ACTIVE prefix can be used with this and all other forms of the TYPE command to place the results in your active file.
If you don't know what type of information a certain element might be, try this: get a search result of several records and issue the "TYPE element-list" command, using the name of the element in question as the element list. SPIRES will type the values for the element from the records in the search request (if values exist).
Sometimes, especially if you are examining many records in a search result, you may need to stop a display before you have seen all the records, using the ATTN/BREAK key. When you want to examine them again, entering "TYPE" will start the display over again from the beginning. To avoid this possible inconvenience, use the SKIP option.
-> type skip=3
will skip over the first three records and begin the display with the fourth. Any positive numeral can be used with the SKIP option. [B.4.2.1]
When you are examining the records in a search result, you might not be finished searching -- that is, you may want to eliminate some records from the search result on the basis of examining the complete record yourself. The TYPE KEEP command allows you to modify the result as you examine the records.
-> type keep
will display each goal record individually and then prompt "-Keep?" If you respond "yes" or "ok", the record is kept in the search result and the next record is displayed. If you respond "no", the record is deleted from the search result (not from the subfile) and the next record is displayed. If you press ATTN/BREAK, the record is retained and the display is halted, keeping all undisplayed records in the result as well. If you press ATTN/BREAK as a record is being displayed, the display of that record will stop and you will be prompted "-Keep?". This is a useful feature if you do not need to see the entire record. After you respond to the prompt, the next record is displayed, and you can continue as above.
Note that even after displaying a search result with the TYPE command, you can still alter the result by continuing the search (using the iterative search procedure) or by redisplaying the records (using the TYPE KEEP command). [B.4.2.1]
If you want to examine the records one at a time, at your own pace, use the PAUSE option with the TYPE command.
-> type pause
This will make SPIRES stop after displaying each record and wait for you to press the RETURN key before continuing. To end the display before you have seen all the records, press ATTN/BREAK; this does not affect the search result.
The KEEP and PAUSE options may not be used together; KEEP pauses between records anyway, as noted above. [B.4.2.1]
Using the TYPE command, you will get an extra blank line between records; if the IN ACTIVE TYPE command is issued, you will get a line containing "****" before each record and a line containing ";" after each one. These lines are often useful for distinguishing between records; however, they can be unattractive and can add many unnecessary lines to the display or the active file. If you want the extra lines suppressed, use the CLEAN option on the TYPE command. [B.4.2.1]
Most SPIRES subfiles display records in custom formats -- that is, formats designed especially for the subfile. To see whether a subfile has custom formats, issue the SHOW FORMATS command anytime after the subfile has been selected. [B.4.6.1]
-> show formats -Formats Set: OUTPUT (Subfile) -Subfile Formats: TEST TOTAL OUTPUT UPDATE RESTMNT CHECKOUT PRICE UPDATE
The list indicates that seven custom formats are designed for the "Restaurant" subfile. It also shows that the format named "Output" has been "set", either automatically or by you (see below), and records will be displayed using this format.
The list of formats can be placed in the active file, using the IN ACTIVE prefix.
Using the TYPE command, you can display records either in a format specifically designed for them (if one exists) or in a list made up of selected elements, as with the "TYPE element-list" command. But SPIRES can also help you design a display of search results to suit your own immediate needs. The simplest method uses the $REPORT system format.
The basic command used to establish the $REPORT format is
SET FORMAT $REPORT element-list
where "element-list" is a group of elements chosen from the list displayed by the SHOW ELEMENTS command. (See section III.7.1.) As shown below, the elements must be separated by blanks, not commas. SPIRES will construct a table, giving each element equal length across the display area. To display the table, using your search result, you issue the TYPE command.
-> find cuisine chinese and city palo alto -Result: 4 RESTAURANTS -> set format $report Name Address Phone -> type Feb. 11, 1983 Page 1 Name Address Phone ---------------------- ---------------------- ---------------------- China Lion 3345 El Camino Real 493-9989 Six Happiness 220 University Ave. 326-6565 Seven Seas 443 Emerson Feng Yuan 3950 Middlefield Road 494-7391
Using the IN ACTIVE TYPE command you can place the display in your active file. (Note that the first column will contain carriage control symbols for use in offline printing.)
Anytime you issue a TYPE command (except the "TYPE element-list" command) while you are using the same subfile, your results will be displayed in the table format you created. If you want to construct another table, use the SET FORMAT $REPORT command again. If you want to display the results in their normal format, enter the command "CLEAR FORMAT". "CLEAR FORMAT" is automatic when you select a different subfile.
The tabular display above is actually a very simple "report" on your subfile. SPIRES offers several ways of constructing more informative reports than the simple one above. Report Definer, for instance, described in the appendix to this manual, lets you compute summaries for your element values and group your records into subsets. $REPORT also offers a wealth of options for customizing a report with relative ease. For complete information on report writing in SPIRES, see Chapter C of the manual "SPIRES Searching and Updating".
Often the order of records displayed seems haphazard. They seldom appear to be in numeric or alphabetic order on any meaningful element. Using the SEQUENCE command, it is possible to create a "stack" of records in a particular arrangement, ordering them by a particular element value. The stack of records may then be displayed as usual using the TYPE command.
For example, suppose you would like the search result from the last section arranged in alphabetic order by name before you see them in the table:
-> find cuisine chinese and city palo alto -Result: 4 RESTAURANTS -> sequence name -Stack: 4 RESTAURANTS -> type
June 23, 1983 Page 1 Name Address Phone ---------------------- ---------------------- ---------------------- China Lion 3345 El Camino Real 493-9989 Feng Yuan 3950 Middlefield Road 494-7391 Seven Seas 443 Emerson Six Happiness 220 University Ave. 326-6565
(Remember that you do not have to issue the SET FORMAT $REPORT command again unless you want to alter the tabular display or unless you have used another subfile and returned to this one.) The syntax of the SEQUENCE command is:
SEQUENCE element-list
where "element-list" consists of one or more element names (as shown by the SHOW ELEMENTS command). 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 for those records; and so on. SPIRES normally sorts in "ascending" order -- that is, alphabetic order for alphabetic strings and numeric order for numbers. If a record has no value for the sequenced element, the record is placed first in the stack. If you would like the sequence to be in "descending" order, "(D)" should be used after the appropriate element name in the SEQUENCE command. For example,
-> sequence price-average(d) name
would give you a stack where the first restaurant displayed is the most expensive restaurant; if two restaurants had the same "price-average" then the first one in alphabetic order by name would be listed first; if a restaurant in the search result did not have a "price-average" value, it would be included at the end of the list, because the "(d)" reverses the normal ordering. [B.4.5]
This guide has given you a limited view of the capabilities of SPIRES and of searching SPIRES subfiles. Many other important SPIRES commands are easy to use and helpful in searching. They are discussed in detail in "SPIRES Searching and Updating". You can learn more about the following in that manual:
- an overview of SPIRES and its documentation [A.1.3]
- system logging of your commands [A.2.4]
- using abbreviations in SPIRES [A.2.7]
- SPIRES online documentation [A.3.1.7]
- reviewing searches [B.3.7]
- saving search results for later use [B.3.8]
- displaying records without using a search result [B.5.1.1]
- other methods of searching unindexed information [B.5.3]
The manual also discusses adding and updating records in subfiles. [D.2] It is the best large-scale introduction to using SPIRES. If you are interested in learning more about using SPIRES, you should certainly read that manual.
Here is a sample SPIRES session, from the initial SPIRES command issued in WYLBUR to the final EXIT command, when you are returned to WYLBUR. All commands used are explained in this booklet; you can refer to the index under "Commands" for the appropriate page numbers.
COMMAND> spires
-Welcome to SPIRES ... if in trouble, try HELP
-> select restaurant
-> show indexes
Goal Records: RESTAURANT
Combined Index Terms:
DATE-ADDED
DATE-UPDATED
PRICE-RANGE
PRICE-AVERAGE
FOOD-QUALITY
SERVICE-QUALITY
CREDIT
BAR
Simple Index: N, NAM, NAME
Simple Index: C, CUIS, CUISINE, T, TYPE, TYPE-OF-FOOD (Synonym)
Simple Index: A, ADD, ADDRESS, ST, STREET
Simple Index: RES, RESERVATIONS
Simple Index: H, HOURS, HRS
Simple Index: E, ENTER, ENTERTAIN, ENTERTAINMENT
Simple Index: CITY
Simple Index: STATE
-> find name le pot au feu
-Result: 1 RESTAURANT
-> type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Le Pot au Feu Cuisine(s): French
1619 El Camino Real Quality of Food: Excellent
Menlo Park, Calif Quality of Service: Good
Excellent French cuisine, simple, pleasant atmosphere.
Owned/managed by an imaginative French couple. Wide
range of selections. Specialties each night.
--Reviewed by Ann Wood. Reviewed on JUNE 3, 1978--
Hours: closed Sunday and Monday Phone: 322-4343
Entertainment: none Average Price: $12.00
Bar: Wine and Beer Payment: Cash, Check,
Reservations are unavailable. Credit Card(s)
-> find city palo alto
-Result: 25 RESTAURANTS
-> and cuisine hot dogs
-Zero result, previous result retained
-Result: 25 RESTAURANTS
-> browse cuisine
HOT
AMERICAN
NEAR
PIE!
RIB
SPECIALTIES
STYLE
WAR
-> and cuisine american
-Result: 15 RESTAURANTS
-> type name cuisine
NAME = SEVEN SEAS;
CUISINE = CHINESE, AMERICAN;
NAME = Good Earth;
CUISINE = American, Natural food, vegetarian;
NAME = Mrs Field's;
CUISINE = american junk food;
NAME = Bess and the Beefeater;
CUISINE = Continental, American, seafood, steaks, prime rib;
NAME = The Proud Popover;
CUISINE = Early American, Colonial;
NAME = Soup Kettle;
CUISINE = American, non-institutional cooking;
NAME = St. Michael's Alley;
CUISINE = Continental, Near-Eastern, American, French, India;
(the display continues)
-> and price-average < $3.00
-Result: 3 RESTAURANTS
-> set format $report Name Price-average Phone
-> in active type
-OK to clear? ok
1. 1March 22, 1983 Page 1
2. Name Price-Average Phone
3. ------------------ ------------------ ------------------
4. Jack In The Box $1.56 767-2676
5. Seven Seas $2.75
6. Mrs Field's $0.25
-> exit
-Exiting SPIRES
COMMAND>
To make a display of records from your subfile more readable and informative, you can quickly design a customized "report" format using the report creation tool called Report Definer. A report format not only makes a record display easier to read, but it can also display summary information such as sums and counts, thus increasing the information contained in your records. You will quickly spot the advantages of a custom report format by comparing the two displays below of identical records, one in standard SPIRES format and one in a customized report format:
+-----------+ +----------+
| Standard | | Custom |
| SPIRES | | report |
| format | | format |
+-----------+ +----------+
| |
| |
v v
NAME = John Swann; | Hourly
DEPT = Orders; | Department Name Salary
SALARY = $6.00; | ---------- -------------------- -------
| Orders Sally Love $10.00
NAME = Sally Love; | John Swann $ 6.00
DEPT = Orders; |
SALARY = $10.00; | Receipts Catlin Buzz $ 8.00
|
NAME = Catlin Buzz; |
DEPT = Receipts; |
SALARY = $8.00; |
Not only is the report format easier to read but it can display additional information -- average salaries for instance -- that would be difficult to determine from the standard SPIRES display.
To enter Report Definer take these four steps:
- SET TERMINAL "terminal-type" to tell the system what model of terminal you have (HELP TERMINAL TYPE for more information);
- Issue the SPIRES command (after you set terminal type);
- SELECT the subfile you will be using for your report and, if you wish, assemble the records of your report with the FIND command or Global FOR;
- Give the command ENTER REPORT DEFINER.
Note: The SET TERMINAL command is not necessary on a 3270-style terminal.
For example:
COMMAND> set terminal vt100
COMMAND> spires
-Welcome to SPIRES 87.06 ... if in trouble, try HELP
-> select restaurant
:
: <---------(Records assembled with the
: FIND command or Global FOR)
-> enter report definer
When you enter, Report Definer presents you with a series of screens that resemble blank forms. By filling in the blanks on the forms you tell the system what information you want the report to contain and how you want the report to look. For instance, on the first screen (below), you fill in the blanks with the names of elements to appear in the report:
(FILL IN THESE BLANKS WITH YOUR ELEMENT NAMES--name them in the same order
| | \ that you want them to appear
| | \ in the report)
\ | \
\----------------------|----------\-------------------------------------+
\ | \ |
|\ELEMENT 1 ELEMENT 2 ELEMENT 3 ELEMENT 4 ELEMENT 5 |
| \ | \ |
| ----------- ----------- ----------- ----------- ----------- |
| ELEMENT 6 ELEMENT 7 ELEMENT 8 ELEMENT 9 ELEMENT 10 |
| |
| ----------- ----------- ----------- ----------- ----------- |
| |
| Type one of the choices below, or use the appropriate PF key: |
| |
| |
| Your choice:______ HELP(PF1) CONTINUE(PF2) FINISH(PF3) SHOWELEM(PF4) |
| |
+----------------------------------------------------------------------+
Each element name must exactly match a name or alias given to that element in the subfile you have selected. Use the SHOWELEM option described below if you need to see a list of element names.
Once you are finished with the first screen it will look something like this:
+----------------------------------------------------------------------+
| |
| ELEMENT 1 ELEMENT 2 ELEMENT 3 ELEMENT 4 ELEMENT 5 |
| DEPT NAME SALARY HOURS |
| ----------- ----------- ----------- ----------- ----------- |
| ELEMENT 6 ELEMENT 7 ELEMENT 8 ELEMENT 9 ELEMENT 10 |
| |
| ----------- ----------- ----------- ----------- ----------- |
| |
| Type one of the choices below, or use the appropriate PF key: |
| |
| |
| Your choice:______ HELP(PF1) CONTINUE(PF2) FINISH(PF3) SHOWELEM(PF4) |
| | | | | |
+------------------------|---------|------------|------------|---------+
| | | |
| | | |
| | | |
+-----------------------------------------------------+
| (WHEN YOU ARE READY TO LEAVE THE SCREEN TYPE ONE OF |
| THESE FOUR CHOICES TO THE RIGHT OF "Your choice:" |
| OR PRESS THE PF KEY ASSOCIATED WITH IT.) |
+-----------------------------------------------------+
These five choices or commands let you move from screen to screen in Report Definer:
- HELP shows you more information about the current screen of input and then returns you to it;
- CONTINUE checks your input for errors and then usually takes you to the next screen;
- FINISH creates a report format based on any specifications you have input and takes you from the input screens into command SPIRES;
- SHOWELEM (available on the first input screen only) will show you a list of your subfile's elements, then return you to the first screen;
- BACKUP (available on all input screens except the first one) will move you to the previous screen, where you can modify your input.
On many terminals pressing the PF key does the same thing as typing out the option, and is much easier. If your PF keys do not work as expected, try pressing the escape key and a numeral instead (e.g., <escape> 3 instead of PF3).
The next screen lets you ask for summaries for your elements and looks something like this:
+----------------------------------------------------------+
+------------+ |Summarization --Report Definer-- 05/15/84 09:22 |
|Your element| | |
|names appear| | ELEMENT COUNT AVERAGE SUM MINIMUM MAXIMUM |
|here auto- | |------- ----------- --- ----- ------- --- ------- ------- |
|matically----------> Name X |
+------------+ | Final.Grade / X X X |
+------------+ | / / / / |
|Type 'X's' ------>------>--------->--/----->---/-----------/-----/ |
|for the | | |
|summaries | | |
|you want | |INSTRUCTIONS: Place an "X" under the option you wish |
+------------+ | performed on the element. |
|COUNT -- The count of the element's occurrences. |
|AVERAGE -- The average of the element's values. |
|SUM -- The sum of the element's values. |
|MINIMUM -- The minimum value found for the element. |
|MAXIMUM -- The maximum value found for the element. |
| |
| |
|Your choice: ______ HELP CONTINUE FINISH BACKUP |
| (PF1) (PF2) (PF3) (PF4) |
+----------------------------------------------------------+
Thus for a subfile containing the final course grades for a collection of students (with A = 4.0, B = 3.0, etc.) you could have your report compute for you the average grade, the maximum grade and the minimum grade, simply by filling in the "X's" as shown. Note that AVERAGE, SUM, MINIMUM and MAXIMUM can only be computed for numerical elements. For a textual element such as a name or comment, you can ask for a COUNT but not for the other statistics listed.
The next screen lets you organize your report into groups of records. In report terminology, a group is a sequenced display in which, whenever the grouping element changes its value, a new cluster of records begins. Here's a simple example of grouped vs. non-grouped displays of identical records:
(UNGROUPED) (GROUPED) (GROUPED WITH SUMMARY)
Dept Name Dept Name Dept Name
------- ---------- ------- ---------- ------- ----------
ACCT Golem ACCT Golem ACCT Golem
ACCT Galante Galante Galante
DVPT Feinberg
DVPT Scotto DVPT Feinberg ----> *COU 2
Scotto |
| DVPT Feinberg
| Scotto
+-----------------------------------------+ |
| Here the report first counts the names |--------> *COU 2
| in each "Dept" group, then counts the |
| total names at the end of the report. |-------> **COU 4
+-----------------------------------------+
All three displays contain the same records but the two "grouped" displays (in this case grouped by "Dept") provide much more information than the ungrouped display does. (The records being grouped have also been sequenced or sorted in SPIRES by the element "Dept". You must sequence your records in SPIRES if you wish them to be grouped properly in your report.) Note how summaries appear beneath each group of records as well as at the end of the report.
The screen for grouping looks like the one you just saw but with additional blanks that you can optionally fill in.
+--------------------------------------------------------------------------+
| Organization --Report Definer-- 5/14/84 09:26 |
|(SUB-TOTAL) |
| GROUP BY ELEMENT NEWPAGE COUNT AVERAGE SUM MINIMUM MAXIMUM |
|------------- ---------------- ------- ----- ------- --- ------- ------- |
| X Course X |
| \ Name | X |
| \ Course.grade | \ X X X |
| \ | \ | | / |
| \ | \ | | / |
+----------\--------------------|-----------\--|-----------|-----/---------+
\ | \ | | /
\ | \| | /
+---------------------+ +-------------+ +-----------------------------+
| Fill in this "X"'s" | |Type an "X" | |These summary values appear |
| to group your report| |to start a | |automatically from the |
| by values for course| |new page for | |previous screen -- but you |
| each course to begin| |each course. | |can change them if you want. |
+---------------------+ +-------------+ +-----------------------------+
The next screen lets you specify the width of each element on a given line of the report, as well as a heading for the element. When the heading options are blank, the element names you specified earlier automatically become your headings.
+-------------------------------------------+
|(When "default" values appear here, you can|
|simply accept them if you want and continue|
|to the next screen.) |
+-------------------------------------------+
| |
| |
+--------------------|------|------------------------------------------+
| Element Layout | --R|port Definer-- 06/30/84 10:10 |
| V V |
| ELEMENT WIDTH HEADING |
| --------------- ----- ------------------------------ |
| DEPT 10 Department |
| NAME 25 Name |
| SECURITY 10 Security//Level |
| SALARY 10 Monthly//Salary |
| |
| |
| |
| INSTRUCTIONS: If you like, change the layout values above. |
| |
| WIDTH -- This number specifies the maximum width (before wrapping) |
| allowed for the element value. |
| HEADING -- The text that will be placed above the element value at |
| the top of each page. Use double slashes '//' to stack |
| heading values. |
| |
| Your choice:________ HELP(PF1) CONTINUE(PF2) FINISH(PF3) BACKUP(PF4) |
| |
+----------------------------------------------------------------------+
The resulting display will look something like this:
Security Monthly
Department Name Level Salary
---------- ------------------------- ---------- ----------
(10 cols.) (25 columns.............) (10 cols.) (10 cols.)
(The heading and values for "Monthly Salary" will be adjusted to the rightmost column as shown if an edit mask is applied to that element's values in the file definition.)
The final inputting screen in Report Definer lets you change the way your report will look on each page:
+---------------------+
| You can change any |
+--------------------------------------| of these options |--------+
|Report Options | by typing over the | |
| | value displayed | |
|SUMMARY-ONLY NO <------------| and replacing it | |
| -- | | with your own value.| |
|LINES 60 <------| +---------------------+ |
|INDENT 7 <---------+ | |
|SKIP 0 <---------| |
|TITLE From: SUBFILE-NAME <-------+ |
| |
| |
| |
|INSTRUCTIONS: If you like, change the report options above. |
| |
|SUMMARY-ONLY -- If you specify 'YES', then ONLY summary |
| information will be displayed. |
|LINES -- The maximum number of lines you wish to have |
| per page. |
|INDENT -- Indicates the column in which the report starts. |
| INDENT of 5 starts the report in column 6. |
|SKIP -- The number of lines you wish skipped between |
| each record. |
|TITLE -- The text given will be placed at the top center |
| of each page of your report. |
| |
| |
|Your choice:________ HELP(PF1) CONTINUE(PF2) FINISH(PF3) BACKUP(PF4)|
| |
+---------------------------------------------------------------------+
Ask for SUMMARY-ONLY (by changing the "NO" to "YES") only if you do not want to see anything BUT summary statistics. SUMMARY-ONLY reports suppress the record-by-record detail and print ONLY the report subtotals and totals.
On the last screen when you say FINISH or CONTINUE (as on any of the previous screens when you say FINISH after naming elements), Report Definer removes you from the input screens and sets the format for your report. The Report Definer version of the familiar SPIRES prompt appears (":->"); you can now issue all the regular SPIRES commands. For instance, to assemble the records for your report, you can issue the FIND command or use Global FOR techniques. You can sequence the records for a grouped display. To see the report you can issue the TYPE command, or IN ACTIVE TYPE to place it in your active file for printing.
To see the SPIRES subcommands that created your report format you can issue the command SHOW FORMAT INPUT. (The subcommands, written in the $REPORT subcommand language, are described in the manual "SPIRES Searching and Updating".) To place the subcommands in your active file (perhaps to modify them there using further $REPORT statements) you can issue the command IN ACTIVE SHOW FORMAT INPUT.
In addition, the following useful commands are specific to Report Definer:
DEFINE returns you to the Report Definer input
screens where you can modify your specifications
for the current report.
DEFINE CLEAR returns you to the Report Definer input screens
but erases the specifications for your current
report, so you can begin defining a brand new one.
RETURN removes you from Report Definer altogether.
You can type the HELP command for further assistance. The SHOW COMMANDS command will provide you with a virtually complete list of appropriate commands at this point.
Here is a sample report using the Restaurant subfile and Report Definer:
COMMAND> set terminal vt100
COMMAND> spires
-Welcome to SPIRES 87.06 ...If in trouble, try HELP
-> select restaurant
-> fin cuisine italian and city palo alto
-Result: 4 RESTAURANTS
-> or (cuisine italian and city san francisco)
-Result: 7 RESTAURANTS
-> sequence city name
-Stack: 7 RESTAURANTS
-> enter report definer
(CONTINUED)------->
+--------------------------
|First screen:
|
| ELEMENT 1 ELEMENT 2 ELEMENT 3
| City Name Price +-------------------+
| ---------------- ---------------- ---------------- | These three ele- |
| \ | ments specified; |
----------| then CONTINUE... |
+-------------------+
+--------------------------
|Second and third screens:
|
| (SUBTOTAL)
| GROUP BY ELEMENT NEWPAGE COUNT AVERAGE SUM MINIMUM MAXIMUM
| -------------- --------------- ------- ----- ------- --- ------- -------
| X City
| Name
| Price X X X
+--------------------------
|Fourth screen:
|
| ELEMENT WIDTH HEADING
| ---------------- ----- ------------------------------
| City 20 City
| Name 25 Restaurant Name
| Price 10 Average//Price
+--------------------------
|Fifth screen:
|
| SUMMARY-ONLY NO
| LINES 60
| INDENT 0
| SKIP 0
| TITLE From: RESTAURANT
(Return to a prompted SPIRES environment:)
:-> type
(CONTINUED)------------>
+-------------------------+
| The final report looks |
| like this: |
+-------------------------+
|
|
V
May 7, 1984 From: RESTAURANT Page 1
City Restaurant Name Average
Price
-------------------- ------------------------- ----------
Palo Alto Liaison $ 18.00
Mama's $ 12.00
Rudolfo's $ 8.00
The New Varsity $ 10.00
*AVG $ 12.00
*MIN $ 8.00
*MAX $ 18.00
San Francisco Alfred's Restaurant $ 15.00
Iron Pot $ 6.00
Tomasso's $ 8.00
*AVG $ 9.66
*MIN $ 6.00
*MAX $ 15.00
**AVG $ 11.00
**MIN $ 6.00
**MAX $ 18.00
:-> return
(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.