******************************************************************
* *
* 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 "SPIRES Searching and Updating" Manual is divided into five distinct but closely related parts, progressing steadily from a general overview of SPIRES to the topics of searching, displaying, reporting upon, and updating (or modifying) the information in SPIRES records.
Part A offers a general introduction to SPIRES.
Part B describes commands for searching and displaying
stored information.
Part C describes methods to create special reports using
this stored information.
Part D covers techniques for adding and updating data.
Part E discusses additional tools available for advanced
SPIRES users.
Many examples in the text are taken directly from applications and sample data bases currently in use at Stanford or at other sites. Other examples are fictitious but suggest plausible future applications of SPIRES.
SPIRES was originally developed for the ORVYL/WYLBUR/MILTEN operating environment developed at Stanford University. It also ran under IBM's VM/CMS (Virtual Machine / Conversational Monitor System) and under MTS (Michigan Terminal System).
This version of "SPIRES Searching and Updating" was prepared for the Unix version of SPIRES.
You do not need to know a computer programming language to use SPIRES. This manual does assume some familiarity with the WYLBUR text editor, a Stanford system that provides communication between your terminal and the computer. WYLBUR can also help you prepare or correct data for use with SPIRES. The document "WYLBUR Overview" serves as a helpful introduction to the subject.
SPIRES is an expanding system that is continually being improved. Changes to the system are usually made every few months in an upward-compatible fashion -- that is, new facilities are added, but old ones are not taken away. On its publication date, each new edition of "Searching and Updating" incorporates documentation on the latest of these improvements. However, each new edition becomes outdated in its turn as the system continues to expand.
You can keep informed of changes to this manual and to SPIRES by consulting the online file SPIRES NEWS (SHOW SPIRES NEWS). The SPIRES NEWS file is always kept current with SPIRES system enhancements, so you can learn about changes there without waiting for the SPIRES manuals to be revised and republished. [See A.3.1.5.]
In SPIRES manuals, examples of sessions are shown with prompts and messages from SPIRES as they actually appear on the terminal screen; SPIRES prompts usually end with a question mark or greater-than sign (">"), while SPIRES messages usually begin with a hyphen. Commands you type are shown in lowercase, following a prompt. (You may generally use upper or lower case interchangeably when you actually use SPIRES.) For example:
-OK to clear? ok
Here SPIRES types "-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 elements. 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:
SHOW SPIRES MAIL [CLEAR|NOCLEAR]
could be entered as
SHOW SPIRES MAIL or SHOW SPIRES MAIL CLEAR or SHOW SPIRES MAIL NOCLEAR
depending on whether you want the option. Here is an example from the report writer command language using braces:
AT {START|TOP} OF PAGE ...
You must choose one of the words in the braces when using this command. For example, this command could be entered as
AT START OF PAGE ...
or as
AT TOP OF PAGE ...
Sections and subsections of this manual whose titles are preceded by an asterisk in parentheses -- (*) -- may be considered optional reading at that point. Usually the material provides details that most users will not need about how to handle uncommon situations, or technical information about how SPIRES internally handles some particular command.
The usefulness of sophisticated data base and information retrieval systems has been demonstrated by a multitude of specialized online systems -- credit card data, airline reservations, etc. But the cost of developing such systems is high, and little of the investment in one specialized system is transferrable to any other.
SPIRES (Stanford Public Information REtrieval System) was developed to meet the need for a generalized data base management system -- one that could serve a bibliographic data base, a medical data base, or any of a variety of administrative and research applications. Since development costs are spread over its many users, a generalized system brings data base services within the reach of smaller applications.
SPIRES differs substantially from most commercially available data base systems in other respects, too. Most systems in the 1970's were designed primarily for batch and online access, and had only rudimentary self-contained command language capability for inquiry and searching. In contrast, SPIRES provided a rich command language for searching and updating both online and in batch.
Another important SPIRES capability missing in most systems is file definition and creation by the users; SPIRES users may develop and administer their own data base applications without the constraints found in systems requiring centralized administration.
Finally, SPIRES is designed to handle bibliographic and text applications, as well as those oriented toward administration and management. The wide range of applications found in a university environment demands a system that employs generalized data structures and manipulative capabilities. At the same time, SPIRES, with its high-level command interface and its generality, may be less CPU-efficient than a set of host language programs carefully designed and optimized for a specific application. However, the rising costs of development and maintenance, as well as decreasing CPU costs, make SPIRES an attractive alternative, especially when professional programmers are not available or their time is limited, or when the size and scope of an application rule out developing a large, specialized system.
Who is doing research on solar energy?
What routines to calculate the Kendall coefficient of concordance
can be called from FORTRAN?
What Chinese restaurants serve lunch?
Who are the clerical employees who have not been promoted during
the last two years?
Where are there donors with A-negative blood who have not given
in the last 90 days?
SPIRES can give you immediate answers to questions like these. The answers to these questions can be obtained from SPIRES files of the past and present, and could be found at a terminal with only two commands.
However, SPIRES capabilities go beyond quick answers to one-time questions, as useful as those may sometimes be. Once you know where those blood donors are, for example, you might want to print a set of mailing labels and a letter to each reminding them how long it's been since the last time they donated. If it's an emergency situation, you'd instead want a list of their names and telephone numbers, and you would probably want the list ordered starting with those donors that you haven't called recently.
These are simple examples where SPIRES report generation capabilities could be useful. Real applications currently in use produce many different "reports", ranging in format from letters and mailing labels to medical records, purchase orders, conference schedules, catalogs and directories. Reports can be printed on your own hard-copy terminal, on a high-speed line printer connected to the computer, or on any other output device. Although many SPIRES files use predefined formats to produce reports, you can produce other types of reports as well, depending on your particular needs, perhaps by defining your own, or by using the Report Definer or $REPORT features in SPIRES. Or, if you are a programmer, you can combine SPIRES services with some other processor (COBOL, PL/I, etc.) to perform further operations on SPIRES results.
In summary, you can use SPIRES to answer your individual questions at the terminal, you can use it for selective retrieval of data for processing by another program, or you can use it to produce almost any kind of report you can imagine.
You will probably have many different files available to you in SPIRES for searching. Some demonstration files may be available. For example, RESTAURANT, a file on local restaurants, and BLOOD DONORS, a file on donors to an imaginary blood bank, are available for use at most sites running SPIRES. This manual will teach you how to use the files available to you, and at the same time should help you decide whether you might benefit from designing a file of your own, a private file for your own particular application.
Before any data can be entered into a SPIRES file, the file must be defined, using a special file definition language. (You may want to create your own files after you are familiar with the searching and updating capabilities. This manual does not discuss the file definition language. That is the purpose of the "SPIRES File Definition" and "SPIRES File Definer" manuals.) [See A.1.3.] The file definition specifies, among other things, how the data in your file is to be organized, how SPIRES should index the data and how the data is to be searched, and what restrictions there will be, if any, on who can use the file.
Once a file is defined, data is entered from a terminal, processed according to the file definition and saved in the computer's disk storage. Each record (probably one per person in the hypothetical file of blood donors) can be made up of a variety of required and optional data elements either fixed or varying in length -- name, address, age, blood type, etc. Each day that new records are added to a file, SPIRES builds indexes to these data elements; the indexes will be used later in answering your search requests.
Index information is just another kind of record to SPIRES, so we speak of "goal records" and "index records" to distinguish the two. Goal records (or some of the data elements in the goal records) are the object of your searches. Indexes and index records help you retrieve goal records. In the blood donor file the goal record would be a person, and one index might be on blood types; in a bibliographic file the goal record would be a book, with indexes perhaps on authors and titles.
In addition to index searching, SPIRES can do direct, sequential searching of the goal records. Although less efficient for some searches, this technique is a practical alternative when certain elements are used as search criteria so rarely that the cost of building and maintaining indexes is not justified.
Searching takes place in the form of a conversation between you and SPIRES. SPIRES types its prompt (->) on your terminal and you answer with an appropriate command. Then SPIRES executes your command and prompts you for another.
A search consists of three steps:
1. Choose the collection of records (the data base) to search 2. Specify the search criteria 3. Display the records retrieved
Because SPIRES allows the file owner to define different search and update privileges to the same data for different users or user groups, and because common information can be shared among related data collections, SPIRES files are organized into "subfiles." To choose the collection you want to search, you must tell SPIRES the subfile name.
What does a search look like? Let's use those first questions in the Introduction as examples. First:
Who is doing research on solar energy?
The terminal conversation would look like this (the notes to the right explain the session):
COMMAND> spires <-- Calling SPIRES
-Welcome to SPIRES ...
-> select faculty profile <-- Choosing the subfile
-> find keyword = solar energy <-- Specifying the criterion
-Result: 5 PERSONS <-- 5 records found matching the
criterion
-> type name, identification <-- Requesting a display from the
records
NAME = Seifert, Howard S.; <-- SPIRES begins typing data IDENTIFICATION = applied physicist, aerospace propulsion engineer, fluid dynamicist, space systems engineer, rocket designer;
NAME = Walker, Arthur B.C., Jr.; IDENTIFICATION = physicist, astrophysicist;
NAME = Wilcox, John M.;
IDENTIFICATION = solar p... <-- User interrupts typing by
pressing ATTN key
-> <-- SPIRES prompts for a new command
Let's look at the search for the second question, which was:
What Chinese restaurants serve lunch?
That terminal conversation would look like this:
-> select restaurant <-- New subfile chosen
-> find cuisine = chinese <-- A new search request
-Result: 28 RESTAURANTS
-> and hours = lunch <-- Another criterion added
-Result: 8 RESTAURANTS
-> type <-- User asks SPIRES to type
the complete records
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Chung King Cuisine(s): Far-Eastern, Chinese
2209 El Camino Real Szechuan
Palo Alto, CA Quality of Food: Excellent
Quality of Service: Excellent
Very tasty Chinese food. Reasonable prices and generous portions.
Try the smoked chicken and sizzling rice soup.
--Reviewed by Denny Wong. Reviewed on MAY 14, 1981 and on JULY 10,
1981--
Hours: Lunch & dinner every day Phone: 327-1811
Bar: Wine and Beer Average Price: $3.00
Reservations are Unnecessary. Payment: Cash, Credit
Card(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
China Lion Restaurant Cuisine(s): Chinese
3345 El Camino Real Quality of Food: Excellent
Palo Alto, CA Quality of Service: Good
Why people go to a crowded place like Chef Chu's when there is a
restaurant just as good wi... <-- User interrupts typing
-> <-- SPIRES prompts for a new command
As you read the rest of this manual, you will learn commands that provide detailed information about individual subfiles, so you will know which one to search and know how to phrase your requests. The examples above are very simple index searches. You can make your requests much more specific or broaden them with successive commands using logical operators, relational operators, and other SPIRES features. Part B covers the search procedure in detail.
The search commands covered in Part B of this manual are only one facet of the SPIRES system. Efficient and powerful searching was the original reason for designing the whole system, and the SPIRES searcher need never be aware of other parts of the system. However, SPIRES provides a number of other tools. The system can generally be thought of as a set of modules:
Function: Define the structure of each file, determine handling
of data entered into and retrieved from the file
(input and output processing rules) and specify
indexes to be built by the system.
Documentation: "SPIRES File Definition" and "SPIRES File
Definer".
Function: Locate information in a file and present it
to the user. Some search commands utilize
the indexes maintained by SPIRES; others
examine each record directly.
Documentation: Part B of this manual: "SPIRES Searching
and Updating".
Function: Use information within a file to create reports.
Documentation: Part C of this manual: "SPIRES Searching
and Updating".
Function: Add, remove, or modify records in a file.
Documentation: Part D of this manual: "SPIRES Searching
and Updating".
Function: (a) Transform SPIRES data from its default format
into a variety of arrangements for display on any of
the available output devices (output formats); and,
(b) Transform input data, from an arrangement
convenient to the person preparing it, to SPIRES
internal input format. Any number of formats can be
defined for a file, including full-screen formats.
Documentation: "SPIRES Formats" and "SPIRES Device Services".
Function: Carry out a previously prepared sequence of SPIRES
commands (WYLBUR and Unix commands can also be
included). Facilities for conditional branching,
variable definition, string manipulation and
interactive communication with the terminal are also
provided.
Documentation: "SPIRES Protocols".
Function: Manipulation of records using sequential techniques,
rather than indexes. Provides powerful facilities
for processing parts of records, and management
facilities for the file owner.
Documentation: "Sequential Record Processing in SPIRES:
Global FOR".
Function: Links SPIRES to devices, such as terminals and files.
Provides full-screen support, Host Language
Interface, and file transfers.
Documentation: "SPIRES Device Services".
Function: Informs users of changes and additions to SPIRES
and points them toward updated documentation.
Documentation: "SPIRES NEWS (SHOW SPIRES NEWS command)".
See also the Appendix on documentation in each
SPIRES manual.
In addition to the reference manuals cited above, SPIRES has several primers that introduce some of these components in a less rigorous way than the reference manuals. Each primer's title begins with "A Guide to". Here are the titles in the series so far:
A Guide to Data Base Development
- the basic primer to SPIRES; covers searching, updating,
reporting, data base creation, and sequential processing
A Guide to Searching
- covers the basic commands of searching and reporting
A Guide to Output Formats
- covers the procedure for creating customized formats for
output
The material in this chapter covers fundamentals of conversing with SPIRES. Sections A.2.1 through A.2.3 relate to the use of SPIRES on the mainframe computer. You will need: (1) an account for computer services and (2) a terminal.
Account information should be available at the computer center whence this manual came. The people there (and specifically, your SPIRES consultant) should be able to help you determine any particular setup requirements for your account to be able to use SPIRES (if any). (You may, for example, need a particular amount of storage space reserved for you if you intend to create a SPIRES file.) The people at the computer center can also give you information on terminals that can be used to access the computer on which SPIRES runs.
Before you can use SPIRES, you must establish a connection between your terminal and the computer, and respond to the logon prompts that ask you to identify yourself. Your SPIRES consultant or other staff members at the computer center should be able to help you logon if need help. If you have difficulty establishing a connection or any problems with operation of your terminal, contact them as well.
Your computer center probably has literature to give you that has detailed instructions for logging on to the computer.
When you have completed the logon procedure, the system shows you it is ready to accept commands by typing "Command>". (This prompt may vary, depending on different parameters set in Unix. See Unix documentation for more information.)
To enter SPIRES, type the command "spires" (the complete command syntax is shown later).
spires
As soon as SPIRES has been summoned, you will get a welcoming message [See A.2.4.] and the first SPIRES command prompt: "->". (This prompt can and will vary during your SPIRES session, depending on other settings and modes you will learn about.) Sometimes you may also get a message about system changes, a referral to SPIRES NEWS [See A.3.1.5.] and possibly a message that you have received SPIRES mail. [See A.2.10.]
The procedure looks like this:
Command> spires -Welcome to SPIRES 87.06 ... if in trouble, try HELP -> <---- SPIRES is ready to accept your first command
SPIRES displays its release number in the welcome message to help you identify which release of the program you are using. The first two digits represent the year, and the second two represent the month of the release ("June 1987" in the sample above). Which release of SPIRES you are using is particularly useful to your consultant if you are reporting problems.
SPIRES is a public program running under Unix, which is a timesharing monitor and file system.
SPIRES may be disabled by system's programmers. If SPIRES is not available when you attempt to enter SPIRES, the following message is likely to appear:
Command> spires -SPIRES is not currently available
You should try again when SPIRES is available.
You may add some special parameters to the SPIRES command to tailor the SPIRES environment and control the messages SPIRES displays as you enter. Generally these parameters are a set of dash-options, like: -q
When you are through using SPIRES, type
EXIT [QUIET]
Control will be returned to WYLBUR, and you will again receive the "Command>" prompt.
-> exit -Exiting SPIRES Command>
When you have finished working, type LOGOFF. (You may also log off without exiting SPIRES.)
If you use the QUIET option, you will be returned to WYLBUR without receiving the "Exiting SPIRES" message.
(Note: Command tracing as discussed below is currently disabled at most, if not all, SPIRES sites. Contact your SPIRES consultant to find out whether it is enabled at your site.)
Unless you take specific action to prohibit it, SPIRES logs all commands issued during a terminal session. This is done to provide the SPIRES consultants with knowledge about how the system is being used and how it might be improved. It also provides a complete record of actions taken by a user during the terminal session preceding a software problem; this is often an invaluable aid to timely problem resolution. It should be emphasized, however, that only commands are traced, not data. Furthermore, it is the right of every user to turn off the tracing facility.
You may issue the command:
SET NOTRACE
at any time during the session to disable the trace facility. If you have disabled tracing, it may be restarted with the command:
SET TRACE
You can issue almost all WYLBUR and Unix commands while in SPIRES. This means you can edit SPIRES results and print material offline or submit other jobs without needing to exit SPIRES and later reenter. When you type a command SPIRES does not recognize, it simply passes the command to Unix.
If the commands issued during a SPIRES session are primarily SPIRES commands, then there is no problem with the efficiency of passing commands from SPIRES to WYLBUR and Unix. However, if a SPIRES session consists primarily of WYLBUR editing commands and only occasionally of SPIRES searching and updating commands, some small degree of inefficiency is introduced. If you need to issue a series of WYLBUR commands, you may wish to save yourself the expense of passing them through SPIRES first. Using the EXIT command is a possible answer but is not convenient, since you would completely lose your place in SPIRES -- you would probably have to issue several commands just to regain your previous position in SPIRES. The best methods to get in more direct contact with WYLBUR is to launch WYLBUR while you are still in SPIRES. There are several ways to do that, described elsewhere.
The BREAK command no longer does anything useful in the Unix version.
The ATTN/BREAK key has different meanings to SPIRES depending on when it is pressed.
Pressing ATTN/BREAK after you have begun typing a command has the effect of ignoring what you have typed so far, and you are prompted for a new command.
If you press ATTN/BREAK while SPIRES is typing out information, the typing will be interrupted and you will get a new command prompt, "->".
In most cases, if you issue a SPIRES command, press carriage return, and then press ATTN/BREAK before SPIRES responds to the command, ATTN/BREAK is ignored. It neither revokes nor interrupts processing of the command. A few commands, such as the FIND command, can be interrupted; SPIRES will ask you if it should continue executing the command. [See B.3.6.2.]
Most SPIRES command verbs of four or more characters in length can be abbreviated to the first three characters. FIND and FIN are identical in effect, for example. In addition, longer fragments of a command element (e.g., SELE or SELEC for SELECT) are accepted. Options may usually be abbreviated as well: the PAUSE option on the TYPE command may be abbreviated to PAU or PAUS, for instance.
Command verbs of three or fewer characters may not be abbreviated.
If ambiguities exist between a SPIRES abbreviation and one from another system (e.g., CONTinue XEQ in SPIRES and CONdense in WYLBUR), you must use as many characters as it takes to resolve the ambiguity, such as CONT XEQ.
When SPIRES cannot properly process your command, an error message will be displayed. Most error messages associated with searching and updating commands also include an error code. [See D.2.8.]
You can get more specific information about the meaning of the code by typing
EXPLAIN code
where "code" is the number of the error code.
For example,
-> select restaurant -> find date-added june 36, 1978 - Element=DATE-ADDED: -Serious data error, code=E31 -Not a legal or complete command -> explain e31 E31: The data element value is supposed to be a recognizable date but does not appear to be. ->
Common error messages from SPIRES include:
SPIRES does not recognize the "term" you have typed. The command has been passed to WYLBUR or Unix, but is still unrecognized or encountered an error.
This message will occur if your command is made up of recognized terms but cannot be processed for some other reason. For example, IN ACTIVE CONTINUE SHOW TIME is invalid because it is a mixture of SPIRES options with a WYLBUR command, SHOW TIME.
The command verb you have typed is valid, but some part of the phrase is meaningless in this context.
For example,
-> show spires news today -Unrecognized: today
In this example, SPIRES recognizes the SHOW SPIRES NEWS command [See A.3.1.5.] but the word "today" is not valid on that command. Often, as in this case, the command will work successfully with the unrecognized term omitted.
This response after an EXPLAIN command means no online explanation is available for the term you have given. [See A.3.1.2.]
SPIRES files necessary to process your command are being used for a function that requires exclusive access. Your command will be processed, as soon as those files are released for general use.
The command you have issued is not allowed for the account under which you are currently logged on.
SPIRES does not have enough memory to perform the requested operation. When this happens, the EXIT command [See A.2.3.] is automatically invoked by SPIRES. You should re-enter SPIRES and reissue the command. If this does not correct the problem, please call the SPIRES consultant.
This message will be typed in response to the SPIRES command if internal system work is being done that precludes user access to SPIRES. An automatic EXIT will be issued immediately and you will be returned to WYLBUR. When this message appears, the systems staff is at work on the problem, and there is no need for you to notify Consulting. This condition is infrequent and is usually of short duration.
The last command you issued caused an error to be detected in SPIRES. The error is serious enough that SPIRES cannot continue processing. About twenty lines of information will be printed on your terminal; this information should be saved (please write it down if you are on a CRT), since it may help your consultant locate and correct the problem. Please save a list of commands you have typed, if possible. Contact the SPIRES consultant with this information promptly.
This response after a SELECT command [See B.2.3.] often means the subfile name was misspelled. Try SHOW SUBFILES [See B.2.1.] to verify the name of the file you want.
This message after a command means you have neglected to specify which subfile you want to use before you issued commands against it. [See B.2.3.]
The selected subfile does not have indexes, and you have issued index searching commands.
Your command is valid, but the subfile simply does not contain any records that satisfy the given criteria.
Your command used only words that were part of an exclusion list in the file definition and thus are not stored in the file's indexes. [See B.3.5.5.]
For most communication with SPIRES, you issue commands at the terminal and SPIRES responds by displaying responses on the terminal screen. At other times, however, you might want SPIRES to put the response into a data set (a listing of records in a SPIRES subfile, for example), that you will print. Or you might want to add records that you have saved in a data set into a SPIRES subfile, without having to re-type them at the terminal.
SPIRES generally uses the WYLBUR active file in such cases. You can ask SPIRES to place that listing of records in your active file so that you can then issue the PRINT command to get an offline listing. (Or you can use other WYLBUR commands on the listing as desired -- VIEW, MODIFY, SAVE, COPY, etc.) For input purposes, you can tell SPIRES to read records from your active file to be entered into the subfile.
For output purposes, you usually precede a command with the IN ACTIVE prefix to tell SPIRES to place the results in your active file instead of displaying them at the terminal. [See A.2.9.1.]
Anytime that you issue a command to place data in your active file when there is already something there, SPIRES will prompt "-Ok to clear?" If SPIRES may clear your active file, type YES or OK; if SPIRES may not, then type NO or press the ATTN/BREAK key.
SPIRES gives a name and title to a newly created WYLBUR active file when you have issued a command that places data in the active file. This name will be the name of the SPIRES processor you are in (SPIRES, SPIBILD, etc.). The title of the active file is generally the name of the currently selected subfile, followed by the command that created the active file.
For example, if you are using the RESTAURANTS subfile, and issue the command IN ACTIVE DISPLAY ALL, the title of the new active file will be : "RESTAURANTS: DISPLAY ALL".
The IN ACTIVE prefix may precede many SPIRES commands. This prefix causes the normal output from the command to be placed in the active file. It is valid with almost all SHOW commands that are processed by SPIRES.
The command prefix syntax is as follows:
IN ACTIVE [CLEAR|CONTINUE|APPEND|KEEP] [CLEAN] command
The CLEAR option may be used to cause the system to clear the active file before sending data to it. The CONTINUE option may be used to cause the output from the command to be appended to the end of the current active file contents. APPEND performs the same function as CONTINUE. KEEP opens up a new active file without clearing the contents of the old one. (The PICK command lets you restore the previous active file.) If there is information in the active file, and neither CLEAR, KEEP, nor CONTINUE (or APPEND) is specified, the system will prompt "-OK to clear?", to which you may respond only YES, OK or NO. If you have SET CLEAR, the information already in the active file will be cleared automatically. [See A.2.9.3.] If you press ATTN/BREAK, you will receive the message "-No action taken."
Note that even after you give permission to clear the active file, SPIRES will not actually clear it until some data is placed in it. Hence, if you issue a command such as "IN ACTIVE CLEAR, TYPE" and there are no records in the current result or stack to be displayed, the current contents of the active file will be retained.
The SET DELTA command must be issued in SPIRES if you want lines to be sent to the active file with a line number increment other than the default of 1.
If the IN ACTIVE option prefixes a SPIRES command for which its use is invalid, it is ignored; that is, no message will interrupt or warn you, and the active file will not be altered.
If you are placing records from a SPIRES subfile into the active file by using the IN ACTIVE prefix and either the TYPE command [See B.4.2.1.] or the DISPLAY command in Global FOR, [See B.5.3.4.] you may add the CLEAN option to the IN ACTIVE prefix to suppress the separating lines that normally appear when multiple records are displayed.
The IN ACTIVE prefix is one of several SPIRES command prefixes. The prefix may be separated from the command itself by either a blank or a comma, e.g.,
IN ACTIVE CONTINUE, EXPLAIN SPIRES
A single command may have multiple prefixes; the particular order of the prefixes does not matter in any case.
The SET LIST command causes SPIRES to issue a LIST command to WYLBUR automatically whenever data is placed in the WYLBUR active file. SET NOLIST suppresses this automatic listing. The default upon entry to SPIRES is LIST.
The listing can be interrupted at any time by pressing ATTN/BREAK. Data transfer is completed before listing begins, so ATTN/BREAK has no effect on the amount of information placed in the active file.
The SET LIST and SET NOLIST commands is also availalble in SPIBILD.
The SET NOCLEAR command causes the system to prompt "-OK to clear?" whenever a command is issued that would replace the contents of the active file. When the SET CLEAR command is issued, many commands will automatically clear the active file without asking you for permission -- the permission is assumed from the SET CLEAR command. Warning: this command can be dangerous; it is not generally recommended.
The default upon entry to SPIRES is NOCLEAR.
SPIRES has a system variable called $LENGTH that can be used to set the maximum length of output lines from various SPIRES utilities. You will probably never need to change the line length setting, but there may be times when you do. System formats frequently use the value of SET LENGTH to determine how long the lines of output they produce can be. The standard format, the $REPORT format and the $PROMPT format all use the set length, for example. [See B.4.6, C.2.1, D.3.1.]
If a value is too long to be placed within the set length without breaking it somewhere other than at blanks, an error will result (error code S259). If you get this error, you may want to raise the value of the SET LENGTH so that the value can break across lines appropriately, without adding blanks that are not part of the value.
SPIRES automatically assumes a WYLBUR line length of 72. This length may be altered by issuing the WYLBUR command SET LENGTH during the SPIRES session.
The form of this command is
SET LENGTH number
where "number" is a line length less than or equal to 235.
Remember that if you have issued the SET WYLBUR command or used the "(W)" parameter on the SPIRES command, you must preface the SET LENGTH command with a "/" so that SPIRES will "see" the command first. Otherwise, SPIRES will still assume a line length of 72.
Some of the options currently set may be displayed by typing the command:
SHOW SETTINGS
The SHOW SETTINGS command will give you a list of various WYLBUR and SPIRES options that you have set or that were set by entry commands or by default.
For example,
-> show settings -Settings: UPPER, ECHO, DIAG, STOP, LIST, NOCLEAR
This user has retained the default LIST and NOCLEAR settings. UPPER refers to the WYLBUR case commands SET UPPER|UPLOW. The SET UPPER and SET UPLOW commands also control whether SPIRES translates your responses to uppercase (UPPER) or leaves them as entered (UPLOW).
If SET BIG SEARCH had been issued, then the words BIG SEARCH would appear at the end of the list of settings. [See B.3.6.6.]
The other settings are SPIRES settings discussed in the "SPIRES Protocols" manual. Also discussed there are the STORE SETTINGS and RESTORE SETTINGS commands, which can be used to save and restore the current settings if you want to change them temporarily.
The IN ACTIVE option can be used to direct the output of the SHOW SETTINGS command into the active file. [See A.2.9.1.]
Occasionally when you enter SPIRES you may receive the message "Mail waiting" or simply "(Mail)". This means someone has used the SPIRES mail facility to send you a message.
Issue the command
SHOW SPIRES MAIL [QUIET]
and the message will be typed on your terminal. If the message is long, or if you are using a CRT (video) terminal and want a permanent record of the message, type
IN ACTIVE SHOW SPIRES MAIL [QUIET]
The message will first be placed in your active file and then listed. You can interrupt the listing at any time to save the data set or make an offline listing. [See A.2.9.1.]
If no SPIRES mail is waiting, then issuing the SHOW SPIRES MAIL command will cause SPIRES to respond "-No SPIRES mail". If you add the QUIET option to the SHOW SPIRES MAIL command, that message will be suppressed if there is no mail for you.
Whenever you SHOW SPIRES MAIL, the system asks permission with a "-Clear mailbox?" prompt to discard mail you have just seen. If you wish to keep your mail in the SPIRES mailbox so you can look at it again later, reply "no" to the question. To avoid the prompt altogether, you can tell SPIRES to clear your mailbox when you issue the SHOW SPIRES MAIL command by typing:
SHOW SPIRES MAIL CLEAR
Or, you can avoid the prompt and tell the system not to clear your mailbox by typing:
SHOW SPIRES MAIL NOCLEAR
When you use the colon (:) parameter on the SPIRES command, no check for SPIRES mail is made. [See E.2.]
To send mail to another SPIRES user, collect the message in your active file, return to command mode and then type
SEND SPIRES MAIL TO account [USING range]
where "account" is the account number (in the form uuu$gg or gg.uuu) of the user to whom you are sending mail. Be sure that the account number is valid; SPIRES will not verify that the account actually exists. The USING range option may be used when only the specified range of the active file is to be sent as the message. [See D.2.4.1.] You may then collect the message at the end of the active file and send it without disturbing the rest. The addressee need not be logged on at the time the message is sent.
When you issue the SEND SPIRES MAIL command, SPIRES will respond by telling you how many lines from your active file were sent.
For example,
-> send spires mail to gq.jpr -Sent: 10 line(s)
A single SEND SPIRES MAIL command will transmit about 1,900 characters, which is approximately the amount of information that will fit on a CRT screen. Thus, if a message is long, it may not all be sent. The SPIRES response indicating the number of lines sent can be used to determine whether the message was completely delivered. If it was not, the USING option can then be employed to send the remainder of the message.
SPIRES has several facilities to help you learn to use the system effectively. Online, several commands provide assistance; offline, consulting and printed documentation are available.
For consulting assistance at Stanford, contact the consultants in Forsythe Hall, or issue the SPIRES command EXPLAIN CONSULTING for information on current consulting services.
SPIRES can help you learn about SPIRES. The HELP, EXPLAIN, SHOW SYNTAX and SHOW EXAMPLE commands provide up-to-date information ranging from introductory material to detailed explanations. In addition, you may experiment as much as you like; searching is a safe process that does not affect the information stored in SPIRES files. (Updating, obviously, is a different matter!)
In addition to the commands described below, others are available to help you learn about particular files. [See B.2.]
The HELP command is useful when you are lost. HELP causes SPIRES to explain where you are -- whether you have selected a subfile, whether you have a search result, etc. It changes its response to you depending on what you have done in your current session with SPIRES. HELP also points you to appropriate EXPLAIN commands for information on what to do next.
For example,
COMMAND> spires -Welcome to SPIRES ... if in trouble, try HELP -> help
You do not have a SPIRES subfile SELECTed. To obtain a list of
all the subfiles you are allowed to SELECT, issue the command:
SHOW SUBFILES
This will give you a list of the subfile-names you can access.
If you want to use any of the subfiles listed but need more
information about them, type
SHOW SUBFILE DESCRIPTION subfile-name
When you are ready to use a subfile, type
SELECT subfile-name
Then type the HELP command again if necessary. You might also
try some of the following commands:
EXPLAIN EVERYTHING
EXPLAIN SELECT
EXPLAIN SHOW SUBFILES
To leave SPIRES, type the EXIT command.
->
The EXPLAIN command provides summaries of the syntax and use of SPIRES commands. There are also explanations of topics such as abbreviations and error messages. About three thousand explanations are available.
The general form of the command is:
EXPLAIN term
You may specify the first one or more characters of the term you want explained. If more than one explanation is available for the term you specify, you are shown a list of alternatives and then are given the opportunity to specify one term from the list.
-> explain find -Terms with same stem: 1. FIND COMMAND 2. FIND COMMAND, COMPOUND 3. FIND COMMAND, PARENTHESES IN 4. FIND COMMAND, SIMPLE -Which number? 4 <-- The user selects term number 4. <-- The explanation for the simple FIND command is displayed.
If you put a period (.) after the term you wish explained, you will not be shown a list of terms; SPIRES will give you an explanation only if the exact term you specified is found.
If you receive a menu of explanations like the one shown for FIND above, and none of the listed explanations is what you were looking for, you can answer the "-Which number?' prompt with a 0 (zero) to indicate that you don't want to see any of the explanations. This is equivalent to pressing the ATTN/BREAK key.
Any explanation retrieved by the EXPLAIN command can also be placed in the active file by adding the IN ACTIVE prefix to the EXPLAIN command. [See A.2.9.1.]
Most of the explanations come directly from the various SPIRES reference manuals. For example, if you issue the command EXPLAIN EXPLAIN COMMAND, this section of the "Searching and Updating" manual will appear. The name of the manual and the section number are displayed at the beginning of the explanation, so you can use the EXPLAIN file as a master online index to the SPIRES documentation.
At the end of the display, many explanations will have several lists of cross-references, identified by the headings "Reference to", "Referenced by" and "See also". For more information, you can explain any of those terms. [Since the online explanations are simply sections in the various SPIRES manuals, the "Reference to" and "Referenced by" refer to sections cross-referenced in the text. "See also" references refer to sections beneath the current section. For example, an explanation that displays the text of section B.3 in this manual might have "See also" references for sections B.3.1, B.3.2, etc.]
The EXPLAIN command is also available in SPIBILD. However, it is not available in batch SPIRES or batch SPIBILD.
The SHOW EXAMPLE command provides a subset of the information available from the EXPLAIN command. [See A.3.1.2.] Instead of giving a detailed explanation of a command or concept, it only gives a short example that shows the forms and options of a command. Otherwise, it is similar to the EXPLAIN command. [See A.3.1.3.]
The format of the command is:
SHOW EXAMPLE term
where "term" identifies the concept or command for which you want an example. Alternative terms with the same stem will be shown to you, and you are given the opportunity to specify one of them.
For example, you could get an example of a particular FIND command as follows:
-> show example find
-Terms with same stem:
1. FIND COMMAND, COMPOUND
2. FIND COMMAND, PARENTHESES IN
3. FIND COMMAND, SIMPLE
-Which number? 3
FIND COMMAND, SIMPLE
SEARCHING AND UPDATING, section B.3.2.1
Here is an example of a simple FIND command:
-> find author Karl Deutsch
-Result: 4 BOOKS
SPIRES reports the number of goal records satisfying the search
request in a "-Result:" message. The search may then be
continued iteratively or the records in the search result may
be displayed by issuing the TYPE command. The BROWSE command
may be useful in finding sample search values (such as DEUTSCH
in the example above) to use in a search expression.
**Reference to: SEARCHING, ITERATIVE
TYPE COMMAND
BROWSE COMMAND
For further information, you can EXPLAIN the term, or EXPLAIN or SHOW EXAMPLE for the referenced terms at the end of the explanation.
The SHOW SYNTAX command provides a subset of the information available from the EXPLAIN command. Instead of giving a detailed explanation of a command or concept, it gives only a short syntactic definition containing the forms and options of a command. Otherwise, it is used similarly to the EXPLAIN command. [See A.3.1.2.]
The format of the command is:
SHOW SYNTAX term
where "term" identifies the concept or command for which you want a syntactic definition. Alternative terms with the same stem will be shown to you, and you are given the opportunity to specify one of them.
For example, you could get a syntactic definition of the FIND command with the following command:
-> show syntax find
-Terms with the same stem:
1. FIND COMMAND, COMPOUND
2. FIND COMMAND, PARENTHESES IN
3. FIND COMMAND, SIMPLE
-Which number? 3
FIND COMMAND, SIMPLE
SEARCHING AND UPDATING, section B.3.2.1
The syntax of the simple FIND command is:
FIND search-expression
News of the most recent SPIRES changes is maintained in an online file that is updated whenever a change occurs. When you enter SPIRES, a message is displayed if SPIRES NEWS has been added recently. [The message is suppressed if you call SPIRES with the "Q" (for "quiet") option. [See A.2.2.]]
For example,
COMMAND> spires(b) -6/9 New command to build files: "SHOW SPIRES NEWS" for details -Welcome to SPIRES ->
The command
SHOW SPIRES NEWS
will begin a listing of the SPIRES NEWS file at your terminal, with the most recent items first. Like many other SPIRES commands, it can place SPIRES NEWS directly into your active file, using the IN ACTIVE prefix. [See A.2.9.1.]
The information displayed by the SHOW SPIRES NEWS command gives only the most recent changes to SPIRES. If older news is needed, then issue the WYLBUR command:
USE SPIRES.NEWS PUBLIC
This will place the SPIRES NEWS archive (all SPIRES NEWS since July 1976, in reverse chronological order) into your active file. Printed listings of SPIRES.NEWS are available in Document Sales.
An index to SPIRES NEWS items is available online; for a printed copy, issue the command PERFORM PUBLISH.
This manual, "Searching and Updating," is one of the best places to begin learning about SPIRES. If you want to learn more about the SPIRES system, you should consider studying the following manuals:
"A Guide to Searching" (a simplified presentation of searching)
"A Guide to Data Base Development -- A SPIRES Primer"
"SPIRES Protocols"
"SPIRES File Definition" and "SPIRES File Definer"
"SPIRES File Management"
"SPIRES Formats" and "A Guide to Output Formats"
Reference Guides (one or two page documents) to special topics such as searching or the $REPORT format are also available.
At Stanford, to be sure you have the most current edition of a document, issue the PUBLISH command to place an order for the documents you need:
COMMAND> publish
You will be asked what manuals you want, and then jobs will be constructed to print copies of the manuals for you on the 9700 printer.
A list of SPIRES documents is included in this manual [See the Appendix.] and is also available online. Type:
EXPLAIN DOCUMENTATION, BIBLIOGRAPHY
This part of the manual describes the search procedure in SPIRES. The simplicity of the search procedure makes it one of the best features of the SPIRES system. Using straightforward commands such as SELECT, FIND and TYPE, you can choose a subfile to search, learn about its contents, find the goal records that meet criteria you specify, and then display them at your terminal. The variations on this basic searching formula are discussed in Part B.
The first chapter of Part B is a broad overview of the search procedure. Included is a brief description of the structure of files and subfiles. The second chapter tells you how to find the appropriate subfile and "select" it -- that is, how to access the subfile for your searching.
Basic search methods using the FIND command are discussed at length in the third chapter. Within this large chapter are sections about different types of indexes found in various subfiles, including techniques for searching them, ways to save searches to use again later, and suggestions for making searches more efficient and inexpensive.
Once you have found records that meet the criteria you have set, you will want to look at the records. You can look at entire records or just at selected elements. Methods for the display of records are the subject of the fourth chapter.
Most searches use indexes, since searching is most efficiently done using them. However, you may occasionally need to search unindexed data elements; the fifth chapter discusses several techniques that can be used for searching unindexed information, including some of the powerful Global FOR commands.
Subfiles may be searched indirectly, using the information contained in index records, or directly, using the information contained in the goal record. This manual deals primarily with index searching; the capability of retrieving records via direct examination is discussed briefly in this manual and discussed fully in the manual "Sequential Record Processing in SPIRES: Global FOR." [See B.5, D.5, D.7.]
This section contains a brief discussion of the structure of SPIRES files and subfiles, as well as an overview of the search procedure using SPIRES subfiles. The other chapters in Part B will then describe search techniques in specific detail.
"Goal record" is the SPIRES term for a data record that could be found as a result of a SPIRES search operation. In a collection of data about automobile registration, for example, the goal records would probably be automobile owners; in a bibliographic subfile, the goal record would most likely be a book.
The basic unit of information in a SPIRES goal record is the data element; a car owner's name, address and license plate numbers would be some of the elements of the automobile registration file. Elements may be simple or structural. The simple data element is a fixed or varying length character string; it may be required or optional and may be singly or multiply occurring. Each goal record of a subfile has one data element which is the goal record key. Each goal record's key value is unique; the key value identifies the goal record to SPIRES as an individual entity. [See D.1.3.1.]
Structure data elements are made up of other data elements; these may, in turn, be either simple data elements, or other structure data elements. Structures group related data elements together. [See D.2.3.]
For example, in a subfile of students at a university, the goal record would be a student. Elements in the goal record might include the name, address, student number, phone number, school at the university, year admitted and so forth. Since SPIRES needs one element in each goal record to always be a unique value, the data base owner must choose an element to be the goal record key. The best choice for the key in the student subfile might be the student number; none of the other elements in the goal record is guaranteed to be unique. (In subfiles where there is no unique element to be used as the key, SPIRES assigns a unique number to each record entered. This system-manufactured element serves as the goal record key.) The student's courses would probably be a structure data element, made up of a course number, a course name and a grade; there would be a separate occurrence of the structure for each course.
Each SPIRES file has a definition that determines the goal record characteristics of the various subfiles of the file.
The file definition specifies:
- the data elements contained in the goal records of each subfile, and the rules for entering, modifying, and displaying individual goal records.
- the indexes to the information in the goal records and the rules for how those indexes may be used to facilitate searching (not all subfiles have indexes).
- user groups and their privileges to search, display, and modify various elements and structures within the goal records.
A SPIRES file may contain more than one subfile. A single subfile may present different data elements from the same goal record to different groups of users. Goal records from different subfiles vary greatly in structure as well as content. The various subfiles within the file may contain different goal record sets.
SPIRES subfiles are being used to store information on a great variety of subjects -- clinical medicine, administration, library technical processing -- so the user can expect search procedures to vary somewhat from subfile to subfile. However, the basic search commands themselves do not vary.
No searching is possible until you tell the SPIRES system which subfile you want to use. Many public subfiles are available for you to search, some of which also permit updating by the general public. There may also be group and private subfiles that you have privileges to use for searching and perhaps updating. Once you have determined which subfile you want, you can issue the SELECT command to get access to its data. [See B.2.]
Once a subfile has been selected, you search it by issuing a FIND command followed by criteria to be used for locating and retrieving goal records. [See B.3.] SPIRES replies with a message telling you the number of records which meet the criteria. This group of records is called the search result.
After obtaining a search result, you may choose to:
- display the retrieved records
- modify the result using another command
- back up to the previous result
- store the search result for later use
- issue a new search command
For example, suppose you are searching a bibliographic subfile. If you ask SPIRES to find books by Theodore H. White, you might receive the search result "8 BOOKS". You might then ask for the books among these eight having the title word "President" and receive the search result "3 BOOKS". Finally, you might ask for the books among these three published after 1963 and receive the search result "2 BOOKS".
Once a search result that meets the necessary criteria has been retrieved, you may examine the contents of the records. [See B.4.] Several options are available; you can:
- examine all or part of each record
- have the results displayed at the terminal
- have the results placed in the WYLBUR active file for subsequent manipulation using WYLBUR text-editing commands, or for printing
The following sections describe a number of commands that provide information about the subfiles available to you and the data they contain. Having decided on a subfile of interest, you may issue the SELECT command and begin searching.
SPIRES allows file owners to create many different kinds of subfiles, more than can possibly be discussed here completely. Therefore, the explanations provided online for many public subfiles should be consulted via the SHOW SUBFILE DESCRIPTION command. [See B.2.2.]
Once you have entered SPIRES, you may issue the SHOW SUBFILES command to obtain a list of the available subfiles.
The SHOW SUBFILES command has the following syntax:
SHOW [NON] [PRIVATE|GROUP|COMMUNITY|PUBLIC|ALL] SUBFILES [LIKE stem]
You may ask to see a list of one, three, or all of the four types of subfiles: PUBLIC, PRIVATE, GROUP or COMMUNITY. For security reasons, only subfiles available for your use are shown. Public subfiles are available to all the users of SPIRES, while private subfiles are available only to designated users, chosen by the subfile's owner. Group subfiles are available to all users that have the same group code in their account. Community subfiles are available to all users whose group codes (in their account numbers) begins with the same letter. Used with the SHOW SUBFILES command, these options produce various lists of subfiles: PUBLIC, PRIVATE, GROUP, or some subset of the four such as NON PUBLIC. ALL is the default value.
NON can be entered before one of the four types of subfiles only. A list of all the subfiles in the other three categories will be displayed. The "LIKE stem" option causes SPIRES to display the appropriate set of subfile names that begin with the root specified. The IN ACTIVE prefix can be used to place the list in the active file. [See A.2.9.1.]
The following are some examples of SHOW SUBFILES commands:
-> show subfiles -> show public subfiles -> show non public subfiles -> show subfiles like r
In the last example, SPIRES will list all subfiles whose names begin with the letter R.
The SHOW SUBFILES command will list all subfiles available to you, even those to which you have access because your account is included in an "access list" named by the file owner. Those subfiles are listed separately in each category, preceded by the name of the access list. For example,
-> show subfiles like r -Private Subfiles: MUSICAL INSTRUMENTS ... -From access list: GQ.DOC.WRITERS MEIOSES ...
[See B.9.2a in the manual "SPIRES File Definition" for information about access lists.]
The SHOW SUBFILE DESCRIPTION command provides a short description of a subfile, i.e., what information is contained in the goal records, how the records are structured, and notes on any special restrictions on searching the subfile. The file definer is responsible for providing the subfile description, and thus these descriptions do not follow a general form; the information can range from very sparse to very complete.
The form of the command is:
SHOW SUBFILE DESCRIPTION [subfile-name]
If you do not specify which subfile you want described, you will receive the description of the subfile you have selected. [See B.2.3 for information about selecting a subfile.] If you have no subfile selected and do not specify a subfile name in the SHOW SUBFILE DESCRIPTION command, you will be asked to provide the name of a subfile. The subfile description can be placed in your active file using the IN ACTIVE option. [See A.2.9.1.]
You can see descriptions of only those subfiles you can select.
Here is an example, requesting the explanation for a (fictitious) subfile:
-> show subfile description art holdings The SPIRES subfile ART HOLDINGS contains information about art treasures of the University Art Gallery of Franklin Pierce University. Each record represents one treasure. To search the subfile, you must first SELECT it, if you have not already done so. Then issue FIND and TYPE commands to create and examine searches. Other commands you might find helpful are SHOW INDEXES, SHOW SUBFILE SIZE and BROWSE. For more information about any of these commands, issue the EXPLAIN command. Issuing the HELP command can be useful too. ->
Once you have decided on a subfile to be searched, issue the SELECT command. You cannot search or retrieve the records in a subfile until the SELECT command has been issued.
The command is typed as:
SELECT subfile-name
The following commands are also useful:
SHOW SELECT
displays the name of the subfile currently selected. The IN ACTIVE option can be used to direct the output of the SHOW SELECT command into the active file. [See B.2.9.1.]
CLEAR SELECT
cancels the previous SELECT command, leaving you with no subfile selected.
Some subfiles allow you to pass parameters to them with the SELECT commands. These subfiles have SELECT-COMMANDs that accept parameters. If the subfile you are selecting is designed so that you can pass parameters to it, the syntax of the command is:
SELECT subfile-name[, parm-list]
You can also omit the comma by putting the subfile name in quotation marks or apostrophes.
Once a subfile has been selected, the SHOW SUBFILE SIZE command displays the number of goal records comprising the subfile.
The form of the SHOW SUBFILE SIZE command is:
SHOW SUBFILE SIZE
The IN ACTIVE prefix can precede the command to put the result in the active file. [See A.2.9.1.]
For some complex files, the SHOW SUBFILE SIZE command may produce the message "-The subfile has an unknown size". SHOW SUBFILE SIZE does not reflect records added or removed since the file was last processed. [See D.6.1.]
Owners of SPIRES data bases are often interested in how their subfiles are being used. In order to monitor the activity on a subfile, the owner can tell SPIRES to log all commands issued by users who have selected that subfile. If you select one of these monitored subfiles, SPIRES will tell you that all your commands are being logged.
For example,
-> select spires manual -Command logging in effect for this subfile ->
Unlike the SPIRES system logging [See A.2.4.] which you can choose to have on or off, subfile command logging cannot be turned off except by the data base owner. During the time the subfile is selected, all commands that you issue are logged, whether or not they actually involve using the file. When you select another subfile or exit SPIRES, the command logging ends.
Some owners of SPIRES data bases instruct the system to maintain records of who uses their subfiles, the length of time used and the number of records displayed. These data base owners may decide to charge a fee for subfile use based on the statistics SPIRES will collect for them. Such a subfile is a "chargeable" subfile.
When you attempt to select a chargeable subfile, SPIRES will inform you of the rates that the file owner has set for its use. SPIRES will then ask you whether you agree to accept charges for using the subfile. If you refuse, no record of your SELECT command is kept; if you accept, record of your use of the subfile is maintained. When you issue the CLEAR SELECT command, select another subfile, or issue the EXIT command, you will receive an approximate calculation of your charges for use of the subfile.
If a data base for which you incur charges is maintained by the computer center, then charges for its use will appear on your regular billing from the computer center. If you use data bases maintained by other account holders at the center, you may have to make separate arrangements with them for billing purposes.
The data base charging messages appear as follows:
-> select plant biology -Database charge: $6.00/hour, $10.00/1000 displays, $1.00 minimum -Continue select? OK -> clear select -Approximate database charge: $1.00 ->
The file owner can charge for any or all of the following:
- Hourly charge -- a fixed fee charged for each hour (or fraction of an hour) you have the subfile selected.
- Display charge -- a fee charged for each record in the file that you see (any SPIRES command that displays the contents of a record is counted); the amount for this charge is given for a thousand records, even though the actual number of records displayed is counted.
- Minimum charge -- a fee that is assessed if the sum of the other charges (hourly and/or display) is not larger than the minimum.
After selecting a subfile, you probably want to find information within the records contained there. Depending on the file definition, the subfile may have indexes to use for searching a particular type of information. If it does not, other methods of searching will be needed. [See B.5.]
You must first determine whether there is an appropriate index to use. If there is, a search request can be made. You specify a FIND command verb followed by a single index name and value, or multiple search expressions linked by logical operators. The procedure may become intricate as additional criteria are specified. A search request is constructed as a logical expression; therefore, the order of the criteria affects which records are retrieved.
If desired, you can review the requested search and store it in a Unix file for re-use at another time.
In SPIRES, search terms correspond to indexes (collections of index records constructed according to the file definition). In order to efficiently search for goal records, you must learn how a subfile is indexed. The SHOW INDEXES command displays a list of search terms and their valid aliases, as well as the kind of indexes to which they correspond.
The SHOW INDEXES command provides you with a list of indexes and the valid search terms for a selected subfile. A search term is the name of an index that has been defined for the subfile. "Index name" and "search term" are generally synonymous.
The form of the SHOW INDEXES command is:
SHOW INDEXES [RECNAMES]
The RECNAMES option tells SPIRES to include the name of the index record-type from the subfile's file definition at the end of the list of searchtypes for each non-compound index.
The following terms are listed:
- the goal record name
- any "global qualifiers" which apply to all indexes of the subfile, and their allowed abbreviations [See B.3.5.9.]
- simple index search terms and their allowed abbreviations
- any "local qualifiers" specific to the simple index listed above it, and their allowed abbreviations [See B.3.5.9.]
- whether the simple index is an "immediate" index [See B.3.1.2.]
- compound index terms
For example:
-> select documents
-> show indexes
Goal Records: DOCUMENT
Simple Index: K, KEY, KEYWORD, S, SUB, SUBJECT
Simple Index: T, TITLE
Qualifier: B, BINDING
Simple Index: TOP, TOPIC
Compound Index Terms:
PUB-DATE
LOCATION
DISTRIBUTION
COURSE
->
The example shows that the subfile "Documents" has simple indexes built from keyword, title (with a local qualifier) and topic information and a compound index with index records on the pub-date, location, distribution and course information contained in each goal record. Also, those words and their listed abbreviations are available as search terms for use in a search request on this subfile.
If the file owner has set up the subfile so that the goal record can also be used as an index, the display will show this by labeling the goal record name as "Goal -- Index:" rather than "Goal Records:" as shown in the above example. This means you can then use the goal record name in a search request just as you would use an index name. [See B.3.1.2 for information on the goal-index in searching.]
If the file owner had set the TITLE index to be immediately indexed, it would be displayed as "Simple Index: T, TITLE (Immediate)".
A subfile's search terms can be placed in the active file by preceding the SHOW INDEXES command with the IN ACTIVE option. [See A.2.9.1.]
In some cases, the file owner will add some additional information about the indexes to help the user in choosing the proper index to search. This includes things like the type of index, what types of values can be used in a search request, and a description of the index and how it might be used. There are two commands that display this information: SHOW INDEX INFORMATION and SHOW INDEX DESCRIPTION.
The complete syntax of these commands is:
SHOW INDEX DESCRIPTION [index-name] SHOW INDEX INFORMATION [index-name]
If you don't specify an index name, information for all of the indexes in the subfile will be displayed.
For example,
-> select almanac
-> show indexes
Goal Records: EVENT
Simple Index: D, DAY
Simple Index: DATE, DT, EXACT-DATE
Simple Index: N, NAM, NAME
-> show index information day
Simple Index:
Note: Index by day, such as "March 1"
Description:
This index contains days of the year, rather than specific dates. For
example, the day March 1 is indexed here, but not March 1, 1982. You
can use this index to find events of the past that took place on a
given day of the year. Although SPIRES handles this as if it were a
complete date, it internally is not.
Source: DAY
DATE
Value-type: DATE
-> show index description day
This index contains days of the year, rather than specific dates. For
example, the day March 1 is indexed here, but not March 1, 1982. You
can use this index to find events of the past that took place on a
given day of the year. Although SPIRES handles this as if it were a
complete date, it internally is not.
If the file owner has not entered any information about the index, you will receive the message "-No information defined" (or "-No description defined").
Sometimes the names file owners give to indexes are not as easy to use as you might like. SPIRES lets you use a command called DEFINE INDEX to define aliases for simple indexes in the currently selected subfile, as shown in this example:
-> select housing -> show indexes Goal - Index: STUDENT Simple Index: ACCOMMODATIONS -> find accomodations = open <- misspelled -Unrecognized: accomodations = open -> find accommodation = open <- still misspelled -Unrecognized: accommodation = open -> define index a for accommodations of housing -> find a = open -Result: 46 STUDENTS
The alias lasts only as long as you have the subfile selected.
The DEFINE INDEX command has other uses as well: it can be used to link to indexes in another subfile when those indexes are relevant to the goal records in the currently selected subfile. [EXPLAIN DEFINE INDEX COMMAND for more information.]
SPIRES builds an index using values of one or more goal record data elements; within each index record SPIRES stores a unique data element value and a reference pointer to each goal record that contains the value.
Indexes provide pathways which allow you to form goal record subsets based upon element values stored in index records. A search result is a collection of goal record references gathered from these index records. When you want to display the records, SPIRES uses the references in the search result to retrieve records from the goal record subset.
When records are added or changed in a subfile, SPIRES places them into the "deferred queue" where they stay until the data base owner has the file "processed". When a file is processed, the deferred queue records are moved into the goal record data set or "tree", the area where the goal records already in the subfile are kept. Then the subfile indexes are updated, incorporating the new information.
Many files are processed overnight each night that there are records in the deferred queue -- this means indexes are "fresh" each morning. But unless an index is defined by the file owner to be an "immediate" index (see below), it will not reflect recent changes made in the subfile (the changes residing in the deferred queue) until the file has been processed. Thus, for files with overnight processing, a non-immediate index does not reflect changes made to the subfile during the day.
However, any index can be defined by the file owner to be updated immediately whenever changes are made to a record that would change the index. This is known as "immediate indexing". An immediate index can be used to retrieve values that have just been added to the subfile (and which would ordinarily not be passed to the index until the file was processed). Whether or not an index is updated immediately does not affect the way an index is searched, but it might affect the result, so you should use the SHOW INDEXES command to see any of the indexes in the subfile are immediately updated. [See D.6.1, D.6.2, D.6.3.]
If a file owner has defined a "goal-index", which is an index built upon the file's goal record, [See B.3.1.1.] the goal-index acts much like an immediate index. For instance, this goal-index can be used to retrieve a newly-added record with the FIND command, even though the file has not yet been processed.
Structurally speaking, SPIRES maintains two different kinds of indexes: simple and compound. Simple and compound indexes differ in their structure; depending on the type of searching involved, one type may be more efficient (and hence less expensive) than the other. While the distinctions between simple indexes and compound indexes are important to the data base owner creating a file definition, they are not so important to the user searching the files; the searcher probably has no real choice with regard to the type of index he needs to use. There are, however, two distinctions between the types that are meaningful to the searcher. First, in a search command, there are two relational operators ("FROM...TO..." and "BETWEEN...AND...") [See B.3.2.3.] that cannot be used on simple indexes. Second, the BROWSE command cannot be used on a compound index. [See B.3.6.3.]
A simple search request begins a search for all records that satisfy the specified criterion.
The FIND command initiates a simple search. You specify a single search expression following the FIND command verb, which causes the system to gather a list of those records that satisfy the criterion, based on their indexed values. [See B.3.2.2.] When you issue the FIND command, any previous search result is dropped.
The syntax of the simple FIND command is:
FIND search-expression
Here is an example of a simple FIND command:
-> find author Karl Deutsch -Result: 4 BOOKS
SPIRES reports the number of goal records satisfying the search request in a "-Result:" message. The search may then be continued iteratively [See B.3.3.] or the records in the search result may be displayed by issuing the TYPE command. [See B.4.2.1.] The BROWSE command may be useful in finding sample search values (such as DEUTSCH in the example above) to use in a search expression. [See B.3.6.3.]
The "search expression" states the criterion to be used in selecting records, and is written as:
index-name relational-operator search-value
where:
The phrase "search term" is often used instead of "index name". [See B.3.1.1.]
Here are some examples of search expressions, used with the FIND command:
index- relational- search-
name operator value
FIND author = White
FIND author (blank) White
FIND diagnosis with coronary disease
FIND age > 64
FIND date after 1968
A space or " " between the index name and search value is equivalent to "=". [See B.3.2.3.]
Whether the index name is typed in upper case, lower case or a mixture makes absolutely no difference to SPIRES. Almost invariably, the case of the search value makes no difference either -- SPIRES will convert it to uppercase for comparison to the uppercase indexed values. Though quite rare, there are indexes where the case of the search value makes a difference, but the file owner should tell you so, either in the subfile or index description. [See B.2.2, B.3.1.1.]
There are four different types of relational operators: equality, inequality, range and content.
The equality operator is used to specify a precise numeric or alphanumeric value in a search request. It retrieves records with a specific indexed value. This operator is indicated by either a "=" or a blank (" ").
-> find author=jones -> find title empire
Although the inequality operators are mostly mathematic symbols, they are useful for searching in indexes with numeric or text values:
(1) -> find city ~= fresno (not equal to)
(2) -> find date > 1973
(3) -> find date after 1973
(4) -> find age >= 37
(5) -> find date < 1926
(6) -> find date before 1926
(7) -> find age <= 78
Note that examples 2 and 3 are equivalent, as are 5 and 6.
Range operators cause a search to retrieve records that have an indexed value within a specific range.
-> find date between june 74 and july 76 -> find date from 1943 to 1953
Content operators such as STRING are also provided for use in situations that require you to find records through pattern matching or substring matching on indexed values or within words of indexed values.
-> find title with energy -> find author having john -> find title string temp -> find comment word best
The inequality and content operators are most efficient when used to search compound indexes. [See B.3.1.3.] They are least efficient (and most expensive) when used to search simple indexes in large files. To prevent you from using a large amount of CPU-time in a search, SPIRES will issue a warning after certain intervals of CPU-time have elapsed during a search. [See B.3.6.2 for an explanation of the SPIRES timer facility.]
Here is a list of all the relational operators:
equality inequality range content
= ~= BETWEEN...AND LIKE
(blank) > FROM...TO PREFIX
>= SUFFIX
< WORD
<= STRING
HAVING
WITH
MASK
The following sections describe each of the relational operators in detail.
The equality operator indicates that a search should find records where an indexed value is equivalent to the search value. In SPIRES "=" is the equality operator; SPIRES also recognizes a blank between a search term and a value as an equality operator.
-> find name = katy winters -> find city palo alto
The equality operator is the most efficient of the relational operators for searching simple indexes.
The LIKE operator is used to search for specific characters in sequence in an indexed value, with the option of using single and multiple "wild-card" characters in the search request.
The "wild-card" characters reserved for the LIKE operator are:
_ (underscore) : indicates a single character ? (question mark) : indicates zero or more characters
Without the "wild-card" characters, the LIKE operator is functionally equivalent to the EQUALITY operator. With these reserved characters, however, the LIKE operator becomes a very flexible string-matching facility.
For example, FIND TITLE LIKE A_E would retrieve indexed titles that contain the word AGE, ACE, or APE. FIND TITLE LIKE A?E would retrieve the former result as well as titles with words such as AVERAGE, ACHE, AMUSE, and ANNOUNCE.
The "wild card" characters can be combined in a single search request.
-> find movies like ?a_oon -Result: 2 MOVIES
would retrieve indexed values BRIGADOON and the BLUE LAGOON.
If the index is not a "word index," blanks can be included in the search value.
Thus,
-> find titles like l_st in l? -Result: 2 SONGS
might retrieve the titles LOST IN LOVE AGAIN or LAST IN LINE.
The \ (backslash) is a reserved character for the LIKE operator that functions as an escape character. The strings \? and \_ are interpreted as the literal ? and _ characters respectively. \\ is interpreted as the literal \ character.
FIND TITLE LIKE ?FAR\? would retrieve the record "HOW FAR?" but not the title "OLD MCDONALD'S FARM".
Most of the inequality relational operators are represented by standard mathematic symbols. Two others, BEFORE and AFTER, are equivalent to two of those symbols.
The inequality operators are:
~= not equal to
> greater than
>= greater than or equal to
< less than
<= less than or equal to
BEFORE less than
AFTER greater than
The "not equal" sign consists of a tilde or a "not sign", depending on the terminal or printer character set, followed by the equals sign.
Here are examples of FIND commands that use inequality operators:
-> find age > 65
The above command will find records with indexed "age" values that are greater than 65. The following command would provide equivalent results:
-> find age after 65
Although most are mathematical symbols, the inequality operators are not restricted to indexes containing numeric values. In the commands below, which are equivalent, you are requesting SPIRES to find records with indexed NAME values that fall alphabetically before the letter K:
-> find name < k -> find name before k
The indexed value JOHNSON would fit the criteria, but not KENNEDY.
The "BETWEEN value AND value" operator is a combination of BEFORE and AFTER ("> and <") over the range of specified values. This operator retrieves records with values in the specified range, excluding the values named.
-> select restaurant -> find date-added between January 1, 1975 and Jan. 1, 1985 -Result: 16 RESTAURANTS ->
The "BETWEEN...AND..." operator can be used to search compound indexes and qualifiers but cannot be used to search simple indexes. The ">" and "<" operators can be used in combination to perform the "BETWEEN...AND..." function on simple indexes.
The FROM-value-TO-value operator retrieves records containing values over the range specified and including the values named.
-> select restaurant -> find date-added from jan 1, 1975 to jan 1, 1985 -Result: 27 RESTAURANTS ->
The "FROM...TO..." operator can be used to search compound indexes and qualifiers, but like the "BETWEEN...AND..." operator, it cannot be used to search simple indexes. The ">=" and "<=" operators can be used in combination to perform the "FROM...TO..." function on simple indexes.
The PREFIX operator specifies that any indexed value retrieved must contain the designated alphabetic characters in sequence at the beginning of the value.
For example, "FIND TITLE PREFIX ENVI" might retrieve records containing ENVIRONMENTS AROUND US or ENVIOUS LADY.
-> find title prefix over an
would retrieve all records in which the indexed title value has the characters "over an" at the beginning, such as "OVER AN IGLOO", "OVER AND OVER" or "OVER ANDOVER". A record with a title value of "UNDER, OVER AND THROUGH" would not be retrieved.
You should note that if an index is a "word index", where each word in the element value is indexed separately [See B.3.5.1, B.3.6.5.] no value in the index will be longer than one word. In such an index, if your search value is longer than one word, an error message will result. You might want to use the equality operator instead.
The SUFFIX operator works like the PREFIX operator, except that the search value must be appear at the end of the retrieved value instead of at the beginning. If the end of the value matches the SUFFIX string specified, the record is retrieved.
For instance, "FIND TITLE SUFFIX MENT" would find records with the indexed value ENVIRONMENT or WET CEMENT or NO COMMENT.
-> find publisher suffix nd smith -Result: 2 ITEMS
would retrieve all records containing the phrase "nd Smith" at the end of the indexed value, including BROWN AND SMITH and LELAND SMITH.
As with the PREFIX operator, you should note that if an index is "word-indexed" [See B.3.5.1, B.3.6.5.] no value in the index will be longer than one word. In that type of index, if your search value is longer than one word, an error message will result. In that case you shoul