******************************************************************
* *
* 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 should probably use the equality operator.
Using the WORD operator, you can search for values containing a single word. The word may appear anywhere within the retrieved value.
For example, "FIND TITLE WORD ENVIRONMENT" would retrieve records with indexed titles such as THE COMPUTER ENVIRONMENT and THE ENVIRONMENT AS PROVIDER.
-> find composition word variations -RESULT: 4 ITEMS
would retrieve all records containing the word "variations" in the indexed title, such as THE EIGHTEEN VARIATIONS and VARIATIONS ON A SCREAM, but not THE EIGHTEENTH VARIATION.
The WORD operator should not be used to search word indexes. [See B.3.5.1, B.3.6.5.]
To be considered a word, the matching value in the index must be preceded and followed by a blank character (or any character below hex 7F, inclusive). For that purpose, SPIRES considers each indexed value to have "implicit blanks" at the front and back.
STRING specifies that any indexed value retrieved must contain the designated characters in sequence and contiguous to qualify for the search result. Unlike the WORD operator, the STRING operator does not require that the designated characters be surrounded by blanks in the indexed value (though they can be).
Thus, FIND TITLE STRING IRON would produce ENVIRONMENT and THE IRON IN US. FIND TITLE STRING EVEN would not, however.
-> find author string dis -Result: 50 BOOKS ->
This search request would retrieve all records in which the indexed AUTHOR value contained the sequential contiguous string DIS, as in ADDISON.
Blanks can be included in the search value.
-> find painting string can go -Result: 1 PAINTING
would retrieve AMERICAN GOTHIC. Paintings whose indexed "painting" value did not have the "n" and "g" separated by a blank would not be retrieved.
The HAVING operator specifies that the designated characters must be in sequence in the indexed value. Though the characters need not be contiguous, they may not be separated by blanks, unless a blank appears at the correct position in the search value.
Thus, although HAVING EVEN would retrieve EVENT and ENVIRONMENT, it would not retrieve DUE VENGEANCE.
-> find author having hand -Result: 35 BOOKS
This search request would retrieve records in which indexed AUTHOR values contain the characters "H","A","N" and "D" in sequence. Thus, PETER HANDKE would be retrieved, but NATHAN DONNELLY would not.
-> find author having han d
would retrieve NATHAN DONNELLY but not PETER HANDKE.
The WITH operator specifies that the designated characters must be in sequence in the indexed value. While characters must occur in the order specified, they need not be contiguous or occur in a single word or number. WITH is useful when an index consists of codes or similarly structured information.
For instance, FIND TITLE WITH EVEN might retrieve records that contain the word ENVIRONMENT, since ENVIRONMENT contains the letters in the specified order.
-> find diagnosis with acn -Result: 1 PATIENT
would retrieve all records in which DIAGNOSIS contains the characters ACN in sequence, such as the record that contains ACDFLN.
Note that if an index is a "word-index" [See B.3.5.1, B.3.6.5.] all words of an element would be indexed separately -- hence, no value in the index would be longer than one word. In this situation, the characters in the specified value for the search must occur only in a single word. If your specified value contains a blank, no records will be retrieved and an error message may result.
The MASK operator is used to search for values that are stored as bit masks. Bit masks are a special way of storing coded data in a compact form. [EXPLAIN $BITS PROC for an explanation of how bit masks are created.]
For a value to be retrieved, it must be the same length as the search value, and all bits set in the search value must be set in the stored value.
For example, assume that a subfile has a CODES element whose values are stored as a bit mask. The following search looks for CODES elements where the first, second, and fourth bits are set. Other bits may be set in the stored value as well, but these three bits must be set for the item to be retrieved.
-> find codes mask 1, 2, 4 -Result: 1 ITEM
A search procedure consisting of several criteria issued as successive commands is called "iterative." An iterative search begins with a FIND command that retrieves a search result, which is then modified by other commands.
-> find composer j.s. bach -Result: 511 PIECES -> and piece fugue -Result: 131 PIECES
Here one search request, indicated by the single presence of the command FIND, locates records fitting more than one requirement -- in this case, works by J.S. Bach that are titled "Fugue".
If two successive search expressions have the same index name, you do not need to repeat it.
-> find composer shostakovich -Result: 47 PIECES -> or f.j. haydn -Result: 215 PIECES
Logical operators connect expressions in iterative and compound search procedures. [See B.3.4.] The operator describes how two criteria combine to specify a subset. Logical operators are sometimes referred to as Boolean operators.
The logical operator AND adds a limiting criterion to the search expression by requiring that both values occur as specified.
-> find author smith -Result: 11 ITEMS -> and author jones -Result: 4 ITEMS
specifies all the books of which Smith and Jones are co-authors.
AND NOT requires that a goal record that would have been included with AND be excluded from the search result.
-> find author smith -Result: 11 ITEMS -> and not author jones -Result: 7 ITEMS
specifies all the books written by Smith except those co-authored by Jones.
The logical operator OR specifies that records which satisfy at least one criterion in the search expression be included in the search result.
-> find author smith -Result: 11 ITEMS -> or author jones -Result: 25 ITEMS
searches for all the books written by either Smith or Jones, or books by both of them together. The OR operator cannot be used to search an index qualifier. [See B.3.5.9.]
The TAND, TOR, and TNOT operators function as the AND, OR, and AND NOT operators when used on simple indexes. But if the indexes have qualifiers, the TAND, TNOT, and TOR operators cause SPIRES to compare both the index value and any qualifiers contained in the index. [See B.3.5.10.]
Logical operators may be abbreviated with the following symbols under some circumstances:
AND & AND NOT &~ OR |
The AND NOT operator can be abbreviated to "&~". The symbol following the ampersand may be either a tilde or a "not sign", depending on your terminal and/or printer.
Search commands may not begin with the symbolic abbreviations, e.g. when you are searching iteratively. However, the abbreviations may be used in the middle of a search command. For example:
-> find composer j.s. bach -Result: 511 PIECES -> & piece fugue -Disabled command -> and piece fugue -Result: 131 PIECES -> find composer j.s. bach & piece fugue -Result: 131 PIECES
The exception to this rule is that there is no restriction to the use of logical operator symbols from within protocols or when SPIRES is executed as a batch program. [See E.3.] [See the manual "SPIRES Protocols" for information about protocols.] The restriction does apply to commands issued from Exec files.
During an ongoing iterative search request, the BACKUP command causes the system to replace the current search result with the search result "one step back," if one exists. SPIRES retains only the current and previous search results; therefore two consecutive BACKUP commands cause SPIRES to send the message "BACKUP not possible" to the terminal.
When a FIND command is issued, SPIRES erases all previous search results and begins collecting results anew. Use of BACKUP immediately after a FIND command also produces the response "BACKUP not possible."
For example:
-> find author theodore white -Result: 2 BOOKS -> and date after 1974 -Result: 1 BOOK -> backup -Result: 2 BOOKS -> backup -BACKUP not possible -Result: 2 BOOKS -> find author klemm -Zero result -> backup -BACKUP not possible -Zero result
Sometimes while searching, you may reduce your search result to zero by stating too many restrictive criteria. An "automatic BACKUP" will occur; the system will keep the search result that you had previous to issuing the last command. (Technically, the system is not actually backing up; when an existing result could be reduced to zero with more iterative search commands, SPIRES keeps that current result until the new result is found. If the new result is not zero, it replaces the current result, which then becomes the "backup" result. However, if the new result is zero, the current result remains the current result, and you can still issue a BACKUP command to get the result one step before the current one.)
-> find composer beethoven -Result: 96 ALBUMS -> and subtitle choral symphony -Result: 3 ALBUMS -> and chorus the beegees -Zero result, previous result retained -Result: 3 ALBUMS -> backup -Result: 96 ALBUMS
When a search result exists and the SEQUENCE command is issued, SPIRES creates a stack of records; subsequent TYPE commands display the records according to the stack, not the search result. [See B.4.5, B.5.4.1.] If the BACKUP command is issued, the stack will be discarded, and TYPE commands will display the records in the search result again.
SPIRES must allocate a certain amount of main memory in the computer to keep the search result that can be obtained with the BACKUP command. You can tell SPIRES not to reserve that memory for backup but instead to allocate it to the area for the current search result, meaning that the current search result has a larger size limit. This is done by issuing a SET SUBFILE OPTION command:
SET SUBFILE OPTION [BACKUP|NOBACKUP]
Specifically, the NOBACKUP option tells SPIRES that whenever the continuation of an iterative search succeeds, the preceding result should be discarded. Any subsequent BACKUP commands would fail, the exception being when the BACKUP would return a search result from a sequenced stack. [See B.3.3.2.]
To return to the default condition, SET SUBFILE OPTION BACKUP. Clearing or changing the selected subfile will also reset the default condition.
At times you may need to issue many different search requests, all compounded with a single "search modifier" that alters the search result by the same criteria each time. You can pre-define this modifier, and the system will automatically append it to all search requests (except ALSO). [See B.5.3.2.]
The command format is:
SET SEARCH MODIFIER [term]
where "term" is a character string not greater than 128 characters. If "term" does not begin with a logical operator (AND, AND NOT or OR), the AND operator is assumed. If no term is specified, any existing search modifier is cleared.
The following command can be issued to determine if a search modifier exists:
SHOW SEARCH MODIFIER
In the following example, a search modifier is used to restrict all searches in the RESTAURANT subfile to restaurants that accept credit cards.
-> select restaurant -> set search modifier and credit = card -> find cuisine = italian -Result: 8 RESTAURANTS <--- Retrieves Italian restaurants -> show search modifier that accept credit cards -Search modifier: AND CREDIT = CARD ->
You may use quotation marks to resolve ambiguities when your search modifier contains words that SPIRES would interpret as logical operators or relational operators. [See B.3.6.4.]
-> set search modifier and not drink "after dinner" -> set search modifier or title "rock and roll"
The file definer may specify that a search modifier be appended automatically to all search requests, and may prevent you from changing or seeing this search modifier by making SET SEARCH MODIFIER and SHOW SEARCH MODIFIER privileged commands. [See D.1.2.]
A search modifier may be set even if a search result already exists.
For example,
-> find publisher benteen -Result: 6 ITEMS -> set search modifier and title word polka -RESULT/STACK must be cleared, code=132
SPIRES does not check whether the search modifier makes any sense until a search command is issued. If, for example, you misspell an index name on the SET SEARCH MODIFIER command, the error will not show up, if at all, until the next FIND command is issued. [See B.3.6.4.1 to see how such a misspelling could affect the search but not cause an error.]
A large number of search expressions can be connected by logical operators in one command. This "compound search request" functions like an iterative search, but is stated in a single command. A compound search request is interpreted by SPIRES from left to right. Thus different results can be obtained by changing the order in which search terms occur, or by using parentheses.
The compound FIND command is used when you want to specify two or more criteria in a search request. It is formed from two or more search expressions joined by logical operators:
| AND | | AND |
FIND search-expression | OR | search-expression | OR | ...
|AND NOT| |AND NOT|
For example:
-> find author smith and author jones
will retrieve books co-authored by Smith and Jones;
-> find author smith or author jones
will retrieve books authored by either Smith or Jones;
-> find author smith and author jones or author brown
will retrieve books authored by Brown as well as books co-authored by Smith and Jones;
-> find author smith or author brown and author jones
will retrieve books co-authored by Smith and Jones as well as books co-authored by Brown and Jones. SPIRES processes the search in left-to-right order, unless parentheses are used to change the order. [See B.3.4.2.]
You can mix index names in a search request, e.g.,:
-> find title rise and title empire and author gibbon -Result: 1 BOOK ->
If two successive search expressions have the same index name, you do not have to repeat it. The above example can be shortened to
-> find title rise and empire and author gibbon
Note that ambiguities can arise if a search value contains a word that is also a relational or logical operator. Quotation marks surrounding the complete search value will usually solve the problem. [See B.3.6.4.]
The order in which three or more expressions are written in the search procedure may affect the way the procedure is evaluated.
For example,
-> find author jones and smith or brown
will produce a different result from:
-> find author brown or smith and jones
The first command will retrieve books written by Brown and books co-authored by Jones and Smith. The second command will retrieve books co-authored by Jones and either Brown or Smith. The distinction can be clarified with parentheses:
-> find (author jones and smith) or brown -> find (author brown or smith) and jones
Parentheses may be used to specify explicitly the order in which logical operations are to be performed. Parentheses may be nested, in which case logical operations are performed from left to right within each group of parentheses, beginning with the innermost set.
The following search request retrieves books written by Smith as well as books co-authored by Brown and Jones:
-> find author smith or (brown and jones)
Here is another example:
-> find author smith or ((brown or jones) and james)
This request will retrieve books by Smith as well as books co-authored either by James and Brown or by James and Jones.
Note these restrictions on parentheses placement: a left parenthesis may follow only the command verb FIND, a logical operator or another left parenthesis; a right parenthesis may follow only a search value or another right parenthesis.
-> find author (smith or jones)
is invalid. It should be
-> find (author smith or jones)
Sometimes you have several search criteria that must be met by a single occurrence of an indexed value. When certain relational operators are used in conjunction with certain other relational operators, there can be a difference in the result depending on whether the search request is issued as a single compound request or a series of iterative commands. By using a compound search request, you can guarantee that all the stated criteria are met by a single indexed value.
The relational operators that work in this way are:
LIKE, WITH, STRING, HAVING, WORD, SUFFIX
used in conjunction with:
<, <=, >, >=, BEFORE, AFTER, PREFIX
If the above relational operators are used in a compound search request for a single simple index, the index is scanned once, and all search criteria are applied to each value in the index record at the same time. So the value must meet all the criteria to become a part of the search result.
But if they are used in separate commands, then the index is scanned for each command. So if a value meets the criteria for a single criterion, it is placed in the search result.
To illustrate this, let's say we have a group of records as follows:
ID = 1; WORD = COUNTS; ID = 2; WORD = COMMENTS; ID = 3; WORD = CONFER; WORD = ACCOUNTS; ID = 4; WORD = COMB; ID = 5; WORD = PETS;
If we issue the command
-> find word prefix co
we get records 1, 2, 3, and 4 because the words COUNTS, COMMENTS, CONFER, and COMB met the criterion of "prefix co". If we issue the command
-> find word suffix ts
we get records 1, 2, 3, and 5 because the words COUNTS, COMMENTS, ACCOUNTS, and PETS met the criterion of "suffix ts". If we issue these two commands
-> find word prefix co -> and word suffix ts
we get records 1, 2 and 3. Both criteria were met in records 1 and 2 by the same words, COUNTS and COMMENTS. In record 3, each criterion was met by a different indexed occurrence of WORD. But if we include both criteria in a single command as follows
-> find word prefix co and suffix ts
the search result will include only records 1 and 2 because both criteria are applied to each value during a single pass of the index.
Several indexing options are available to facilitate searching for special kinds of data elements, such as dates, names and titles. The more commonly used options are described in this section. The subfile or index descriptions should indicate whether any of them apply to a particular subfile. [See B.2.2, B.3.1.1.]
It is often desirable to index individual words within a data element when the data is text. The most common example of this type of data element indexing is the title or abstract in a bibliographic subfile.
If the simple index TITLE has been built using the word-indexing option, then the search request:
-> find title physics
yields goal records whose TITLE elements have values like the "The Physics of Electricity" or "Modern Physics".
Most subfiles using word indexing supply an automatic "and" between words in a search value. For example, "FIND title for eyes only" would be treated as "FIND TITLE for AND eyes AND only". Only a goal record with a "title" element containing all three of these words would be retrieved. Note, however, that these three words could appear in any order within the "title" element. Goal records retrieved might include titles like "FOR EYES ONLY", "ONLY EYES FOR YOU", and "FOUR EYES ONLY FOR YOU". [See B.3.6.5 for suggested search techniques using word indexes.]
Personal name values in a search expression require special treatment because names can be written in a number of ways. SPIRES retrieves a goal record if it contains a valid form of a particular name, even when the search request uses another form of the same name.
If the simple index PNAME has been built using the personal name indexing option, then the search request:
-> find pname john brown
yields a result containing goal records whose indexed PNAME values have values like "John Raymond Brown", "J.R. Brown", "J. Raymond Brown", etc. Likewise, the search requests:
-> find pname john raymond brown
or
-> find pname j. raymond brown
would yield records having those same values. Note that in most subfiles, periods after initials are ignored in search values for personal name indexes.
SPIRES accomplishes all this by matching. If a search request contains a name that does not match some character string in the indexed PNAME value, that record will not be included in the search result.
Thus,
-> find pname John Raymond Brown
would not retrieve a goal record whose PNAME data element had the value "J. Brown".
The following describes in detail the way the "personal name algorithm" matches (or does not match) values in search commands with values in indexes. (Note to file owners: it is assumed that processing rule $PNAME or A38 is coded as both a PASSPROC and SEARCHPROC for the index, or $NAME or A41 is coded as both the PASSPROC and SEARCHPROC for the index.
The algorithm first checks for a match between the surname (last name) portion of the name given in the search command and the name in the index. The surname is assumed to be the last character string in the expression which contains no blanks. Hence "Gogh" would be the surname for "Vincent van Gogh". If only a single word is given, it is assumed to be the surname. The algorithm will examine all records whose surname matches the surname given in the search expression.
The algorithm then compares the non-surname portions of each name. For indexes built with $PNAME (A38), each record must be retrieved to obtain the sub-index values needed to do these compares. For indexes built with $NAME (A41), the non-surname portions are in the keys of the index records, and the record is only retrieved if it satisfies the non-surname compare process.
The first non-surname character string in the search value is compared with the first non-surname field in the the index. The values need only match through the length of the shorter of the two values. Hence "D" will match with "David", and "Anne" will match with "Ann".
If a match is found, the search continues by comparing the next character strings in both the search and index. If the values do not match, the same name from the search value is compared with the next string in the index value. This process continues until the character strings in the search expression are used up.
If all the non-surname fields in the index are used up before those in the search value, then the names do not match. Thus there must be at least as many character strings in the index value as there are in the search value for that value to be retrieved. In addition, since the two values are both scanned left-to-right, the order of the names are critical.
For example, a search command "FIND NAME J R SMITH" would retrieve records with:
John R Smith
John Raymond Smith
J Ray Smith
But not: J Smith
R Smith
R J Smith
A search "FIND NAME JOHN SMITH" would retrieve:
John Raymond Smith (or J R Smith)
Raymond John Smith (or R J Smith)
Johnny R Smith
But not: Jay Smith
There is an option on the personal name algorithm used in building indexes that allows multiple index entries to be built from a single name. This is particularly useful with married women's names. For example:
Patty Duke Astin
would be indexed as both of the following:
Astin, Patty Duke Duke, Patty
This allows retrieval by maiden names to succeed.
If the non-surname does not match, then for the A38 form of index record, the process skips this sub-index and proceeds to the next sub-index in this record. The non-surname compare process repeats until there are no more sub-indexes in the record. Both A38 and A41 then examine the next key in the index, and perform the surname check until the surname doesn't match. If the surname portion matches, the non-surname process is repeated on this record (A38) or key (A41).
Pointer groups associated with matching names are OR'd together. Pointer groups associated with non-matching names are skipped.
Date values can be specified in a number of ways. The file owner can choose several options to make the searching of date indexes easier for the user.
For example, one such option insures that all of the various ways of writing a date are converted to the form found in the index, so that the indexed date "July 27, 1952" can be matched by any of the following commands:
-> find date jul 27, 1952 -> find date 7/27/52 -> find date 7/27/1952 -> find date 27 july 1952
File owners may also allow searches to be made with less exact dates, so that a record with the date July 27, 1952 can be retrieved by searches such as the following:
-> find date july 1952 -> find date 1952
These commands would retrieve not only a July 27th record but also any records with dates in July of 1952 or in 1952 respectively. A full list of forms you can use to match index dates appears after this section. [See B.3.5.3a.]
All of the relational operators may be used with date indexes, although you might not always get the expected result because of the way date values are stored and the way search arguments are compared. The following examples assume that both of the options described above have been specified by the file owner.
One of the most important things to remember when using date indexes is how partial dates are stored. If a value is entered as "9/82" it is stored as "9/0/82", which makes it before or less than "9/1/82". So if you issue the command
-> find date < 9/1/82
your search result will include any record with a date of 9/82. Likewise, with a date entered simply as "1982". It is stored as 0/0/82, so the command
-> find date < 9/82
will retrieve any record with a date value of 1982.
However, date values in search arguments are not converted in this manner. In a search request such as
-> find date > 9/82
the "9/82" is not converted to "9/0/82" before comparing it to the values stored in the date index. It is simply interpreted as "any date value in September of 1982". So the above search request would not retrieve a date value of "9/5/82", but would retrieve a value such as "10/82" or "10/2/82".
The chart below shows indexed date values that would be retrieved for various search requests, shown in the left column:
+-----------------------------------------------------------------+ | Search: | Dates in the Index | | FIND DATE | 1982 | 8/31/82 | 9/82 | 9/1/82 | 9/30/82 | 10/1/82 | |-----------------------------------------------------------------| | = 1982 | Yes | Yes | Yes | Yes | Yes | Yes | | = 9/82 | No | No | Yes | Yes | Yes | No | | > 9/82 | No | No | No | No | No | Yes | | < 9/82 | Yes | Yes | No | No | No | No | | >= 9/82 | No | No | Yes | Yes | Yes | Yes | | <= 9/82 | Yes | Yes | Yes | Yes | Yes | No | | = 9/1/82 | No | No | No | Yes | No | No | | < 9/1/82 | Yes | Yes | Yes | No | No | No | | > 9/1/82 | No | No | No | No | Yes | Yes | +-----------------------------------------------------------------+
This chart assumes that the rules for variant and imprecise date searches have been included by the file owner. If you do not retrieve records according to the above chart, check with the file owner.
SPIRES is more flexible than most computer programs in what forms it allows you to use to specify dates. Both specific dates ("July 4, 1776") and general dates ("today") may be used in index searches, in WHERE clauses, and in data entry situations. All date values that SPIRES recognizes convert to a specific date (having day, month and year), or to a specific month and year, or to a specific year.
This section provides a list of all the date forms that SPIRES recognizes, along with some details of what forms SPIRES either doesn't recognize or tries to treat unorthodoxly.
In the lists, the individual pieces used to represent the forms are:
month - a month name or any abbreviation down to three characters.
Case is not significant. Examples: MARCH, Jan., Aug
mm - the numeric representation of the month, from 1 to 12. A
leading zero is allowed but optional for 1 to 9 (ex: 02).
dd - the numeric representation of the day of the month, from
1 to 31. A leading zero is allowed but optional for 1 to 9.
cc - the century digits of the year. ("19" in 1976) In any form
in which "cc" is not used, "19" is assumed, for now! See
below.
yy - the last two digits of the year. ("76" in 1976)
Other characters shown in the form should be treated as required if that form is intended.
Note about cc (century): In general, SPIRES will assume the current century if it is omitted. For example, if you enter the date "7/4/76" on December 31, 1999, SPIRES will assume the "76" means "1976"; if you enter the same date on January 1, 2000, SPIRES will assume the "76" means "2076". File owners and application developers have options that may use different rules of interpretation, such as treating any two-digit year from 0 to 90 as a "2000" year, but from 91-99 as "1900" years. (If they choose alternate rules, they should let you know.) For the utmost clarity during this decade of transition from 1900 to 2000 years, your best choice, where possible, is to use the 4-digit year for input; that will always be interpreted correctly. If you don't have room to use the 4-digit year, try to display your input to verify that SPIRES interpreted the 2-digit year the way you meant it.
To specify a particular date (including day, month and year), you may use any of the forms shown in the chart below. In all the examples, July 4, 1976, is the date being specified, and the day of input is in the year 1994.
Form Examples ------------------------ ------------------------------------------------ month dd, ccyy July 4, 1976 Jul. 04, 1776 month dd, yy July 4, 76 Jul 04, 76 mm/dd/ccyy 07/04/1976 7/4/1976 mm/dd/yy 07/04/76 7/4/76 dd month ccyy 4 July 1976 04 JUL 1976 dd month yy 4 July 76 04 jul 76 dd-mm-ccyy 04-07-1976 4-7-1976 (Canadian or dd-mm-yy 04-07-76 4-7-76 European forms) ccyy.mm.dd 1976.07.04 1976.7.4 (metric form) ccyy month dd 1976 July 4
To specify a particular month and year, you may use the forms shown below. The examples all use July 1976.
Form Examples ------------------------ ------------------------------------------------ month ccyy July 1976 JUL 1976 month yy July 76 mm/ccyy 7/1976 07/1976 mm/yy 7/76 mm/--/ccyy 07/--/1976 mm-ccyy 07-1976 mm-yy 07-76 ccyy.mm 1976.07 1976.7 ccyy month 1976 July yy month 76 July
To specify a particular year, you use either the form "ccyy" or simply "yy".
You can also specify dates using general, everyday terms, whose specific value is relative to today's date. This is particularly important in programs where you need to express a date whose value depends on the date the program runs; for instance, the program needs to find all the records that were added to the file "last month".
In the charts that follow, the forms include "[+n|-n]", indicating that the last named "unit" should be increased or decreased by "n" -- for example, "this year-5" means "5 years before this year". Also new to these charts is:
weekday - a weekday name or any abbreviation down to three characters.
Case is not significant. Examples: Monday, TUE, fri.
Keep in mind that uppercase in a form indicates a required word for the form, but in actual use, any case combination is allowed for the word.
Below is a chart of the allowed relative forms that convert to a specific date. Note numbers in the chart refer to relevant details in the numbered notes that follow the chart.
Form Examples (and meanings) ----------------------------- --------------------------------------------- TODAY [+n|-n] today today+3 (3 days from today) TOMORROW [+n|-n] tomorrow tomorrow+7 (7 days from tomorrow) YESTERDAY [+n|-n] yesterday yesterday-1 (day before yesterday) +n +1 (tomorrow) +7 (a week from today) -n -1 (yesterday) -7 (a week ago from today) weekday OF THIS WEEK [+n|-n] Friday of this week [Notes 1, 2] weekday OF NEXT WEEK [+n|-n] Sunday of next week [Note 1] weekday OF LAST WEEK [+n|-n] Monday of last week [Notes 1, 3] mm/dd OF THIS YEAR [+n|-n] 12/31 of this year [Note 2] mm/dd OF NEXT YEAR [+n|-n] 1/1 of next year mm/dd OF LAST YEAR [+n|-n] 12/25 of last year [Note 3] month dd OF THIS YEAR [+n|-n] July 1st of this year [Notes 2, 4] month dd OF NEXT YEAR [+n|-n] August 29 of last year [Note 4] month dd OF LAST YEAR [+n|-n] Nov 29 of last year [Notes 3, 4] dd OF month OF THIS YEAR [+n|-n] 4th of July of this year [Notes 2, 4] dd OF month OF NEXT YEAR [+n|-n] 20th of Sept. of next year [Note 4] dd OF month OF LAST YEAR [+n|-n] 31st of Oct of last year [Notes 3, 4] dd [DAY] OF THIS MONTH [+n|-n] 1st day of this month [Notes 2, 4] dd [DAY] OF NEXT MONTH [+n|-n] 10th of next month +2 [Note 4] dd [DAY] OF LAST MONTH [+n|-n] 2nd of last month [Notes 3, 4] LAST [DAY] OF THIS MONTH [+n|-n] last day of this month [Notes 2, 5] LAST [DAY] OF NEXT MONTH [+n|-n] last day of next month+3 [Note 5] LAST [DAY] OF LAST MONTH [+n|-n] last day of last month [Notes 3, 5] dd [DAY] OF THIS YEAR [+n|-n] 1st day of this year [Note 2, 4] dd [DAY] OF NEXT YEAR [+n|-n] 100th day of next year [Note 4] dd [DAY] OF LAST YEAR [+n|-n] 200th day of last year [Note 3, 4] LAST [DAY] OF THIS YEAR [+n|-n] last of this year [Notes 2,5,6] LAST [DAY] OF NEXT YEAR [+n|-n] last day of next year [Notes 5, 6] LAST [DAY] OF LAST YEAR [+n|-n] last day of last year -10 [Notes 3,5,6] dd [DAY] OF mm/ccyy [+n|-n] 20th day of 11/1990 [Note 4] dd [DAY] OF mm/yy [+n|-n] 22nd of 9/55 [Note 4] LAST [DAY] OF mm/ccyy [+n|-n] last day of 1/1990 [Note 5] LAST [DAY] OF mm/yy [+n|-n] last day of 6/54 [Note 5]
Notes for the chart above:
If you append the "+n" or "-n" here, SPIRES will add or subtract "n" weeks from the specified week. So, again, if today is Tuesday, "Friday of this week +4" is the Friday four weeks from this coming Friday.
Below is a chart of the allowed relative forms that convert to a specific month and year, or to a specific year:
Form Examples (and meanings) ----------------------------- --------------------------------------------- THIS MONTH [+n|-n] this month +3 [See Note 2 above] NEXT MONTH [+n|-n] next month LAST MONTH [+n|-n] last month-2 [See Note 3 above] month OF THIS YEAR [+n|-n] May of this year [See Note 2 above] month OF NEXT YEAR [+n|-n] Oct of next year month OF LAST YEAR [+n|-n] Sept of last year [See Note 3 above] THIS YEAR [+n|-n] this year [See Note 2 above] NEXT YEAR [+n|-n] next year+5 LAST YEAR [+n|-n] last year -100 [See Note 3 above]
Some subfiles may let you specify special "accounting" dates: August 32nd, August 33rd, and August 34th of any year. These artificial dates, which have no "day" (e.g., Sunday) associated with them, do not affect relative dates such as "last day of 8/90" -- in other words, that value would always be "8/31/90" and never "8/34/90" to SPIRES.
To find all indexed values that begin with a given character string, you may use the PREFIX operator [See B.3.2.3.6.] or you may specify a "truncated value" in the search expression. SPIRES must be able to distinguish between a complete and truncated value, however. For this reason, the file owner specifies a special truncation character to be used in an index. When the system encounters that character at the end of a search expression, it searches for the truncated value.
If the truncation character "#" has been specified for the title word index by the file owner, then the search request:
-> find title canad#
retrieves values with the words "CANADA", "CANADIAN", "CANADAS", etc.
Most SPIRES files with indexes that permit truncated searching use "#" as the truncation character. Though any character may be defined as the truncation character, for practical reasons the "pound sign" has been traditionally used in SPIRES. If it does not work in a search request, you might check the description of the index or the subfile [See B.2.2, B.3.1.1.] to see whether any information regarding truncated searching or special characters is included.
Some files may permit a special type of truncated search. The special truncation search is very useful with subject tracings in a bibliographic file. Using the form "string1#string2" for a search value (assuming again that "#" is specified in the file definition as the truncation character), the search finds records having element values that begin with the "string1" character string and containing the "string2" character string later in the value.
For instance,
-> find subject woman#history -Result: 29 BOOKS
would retrieve records with indexed subject values beginning with the characters "woman" and containing the characters "history" later in the value, such as "WOMAN -- RIGHTS OF WOMAN -- U.S. HISTORY" or "WOMANKIND IN THE HISTORY OF THE WORLD".
When word indexing is specified [See B.3.5.1.] the file owner usually excludes frequently occurring articles or conjunctions like "and", "an", "the", etc. Less frequently, the file owner may also eliminate values which are indexed many, many times in the goal records of a subfile. Such words would cause large search results: e.g. the word "history" in a collection of history books.
When an exclusion list exists for an index, and an excluded word is used as the value in a search expression, then that search expression will retrieve nothing. If all search values in a command are excluded words, the system will respond with the message "-Request has no content".
The following illustrates a search command in which both search values have been excluded from the index:
-> select history books -> find title american and title history -Request has no content -Zero result ->
In an index using an inclusion list, only those values in the list may be used as search values. Inclusion lists are used for indexes where only specific values (often codes) are allowed. For example, in a subfile indexed by sex, there will probably be only two possible types -- male or female. If there is an inclusion list incorporating these two values, then a search cannot be done using any other value.
-> find sex male -Result: 34 PERSONS -> find sex insex -Element=SEX: -Serious data error, code=E49 -Not a legal or complete command ->
An element may be made up of a concatenated string of codes, where each code is separated by a specified special character, such as a period. SPIRES can search code stems, allowing the specification of an incomplete string of one or more codes in a search expression. The final character specified may not be the separator character. SPIRES retrieves goal records with values of the data element containing the code specified in the search expression.
If the code separator character is ".", and the subfile contains a document (divided by the part, chapter, section, and paragraph) whose paragraphs are the goal record, then the search expression:
-> find part II.6.3
would retrieve the paragraph corresponding to the specified value, plus other elements which comprise the included parts, chapters, and sections, e.g., II.6.3.1, II.6.3.1.1, II.6.3.2, etc.
If an indexed data element has syntax rules associated with its values, the file owner can cause SPIRES to check the validity of search expressions. Under these syntax rules, SPIRES issues an error message when an improperly stated value is entered.
The following example shows a possible sequence of commands:
-> select documents
-> show indexes
Goal Records: DOCUMENT
Simple Index: K, KEY, KEYWORD, S, SUB, SUBJECT, T, TITLE
Compound Index Terms:
PUB-DATE
LOCATION
DISTRIBUTION
CLASSIFICATION
-> find pub-date october
-Element=PUB-DATE: -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.
-> find pub-date october 1975
-Result: 11 DOCUMENTS
->
A common use of search value validation is checking numeric values. The syntactic rules are simple: the value is composed of digits with an optional '+' or '-' preceding the value. If the file owner has specified that search expression values be checked for validity, then any search expression value not satisfying the validation rules is rejected.
The file owner can also prevent the use of any but the equality relational operator ("=" or blank) with simple indexes. Compound indexes and qualifiers would still allow all relational operators in this case.
A sub-index is an index within a simple index. A sub-index cannot be searched with FIND, AND, OR, and AND NOT commands directly. It contains additional search criteria, and cannot be searched independently of the simple index of which it is a part. The only operator allowed when searching sub-indexes is the equality (=) operator. There may be more than one level of sub-index.
Imagine the following indexes: a simple index called GAME, and sub-indexes of SECTION, ROW and SEAT. This might be represented in a subfile containing tickets as follows:
Goal Record: TICKET Simple Index: GAME Sub-Index: SECTION Sub-Index: ROW Sub-Index: SEAT
The following search request, using the character "@" to search the sub-indexes, would retrieve the ticket for a particular game, section, row and seat:
-> find game = ucla @ section = center @ row = b @ seat = 24
Another example, which retrieves all tickets for a particular game and section, regardless of row and seat, might be:
-> find game ucla @ section center
Although you do not have to use all the sub-indexes to an index in each search, you must supply search values for all those sub-indexes through the lowest one you need to use.
-> find game ucla @ seat 19
would not retrieve any records, since the section and row sub-indexes were not included in the request.
Qualifiers are special search terms that may be used following a simple or compound index search expression to narrow a search procedure. A global qualifier, listed by the SHOW INDEXES command immediately after the goal record name, may be used to qualify any search. A local qualifier, listed in the SHOW INDEXES command immediately after the index to which it applies, may only be applied to searches of that index. A qualifier is used with the logical operators AND or AND NOT. All relational operators are valid.
The qualifier term may not be the first term in a FIND command. The qualifier may not be immediately preceded by the logical operator OR except in a parenthetical group where several qualifier values are joined by ORs.
-> select parker files -> find author smith -Result: 8 PAPERS -> and date 1976 <---Date is a qualifier -Result: 1 PAPER -> find author smith and (date 1976 or 1987) -Result: 3 PAPERS -> find author smith or date 1976 -Illegal use of qualifier <---Use of OR with qualifiers is -Unrecognized: date 1976 restricted
Sometimes when you are searching a subfile that has qualifiers, a single record may be counted more than once in the search result if it fits more than one of the criteria in your search request. Thus, the search result may not be exactly accurate. If you need to know the precise number of unique records in a search request that uses qualifiers, you can issue the command SHOW RESULT COUNT. (This command is handled like a SHOW RESULT command if you are not searching qualifiers.) Note that if you were to display the records (using the TYPE command, for instance), the "duplicate" record would only be displayed once, and the corrected number of records in the result would be displayed after the last record. The IN ACTIVE option can be used to direct the output of the SHOW RESULT COUNT command into the active file.
Local qualifiers can also be defined for indexes that contain elements in multiply-occurring structures. If these qualifiers uniquely identify the structures, the logical operators TAND, TNOT, and TOR can be used in search requests to insure that all search criteria are met by element values in the same structure occurrence. [See B.3.5.10.]
Global qualifiers are created only for a single occurrence of the qualifier element, never multiple occurrences.
The logical operators TAND, TOR, and TNOT are used in a compound search request to cause SPIRES to compare both the index value and any qualifiers that exist for the index. The primary purpose of this comparison is to insure that the search criteria are met by values in the same structure occurrence. TAND, TOR, and TNOT are equivalent, respectively, to AND, OR, and NOT, the "T" meaning "together in a structure." The qualifier may be another element in the structure that uniquely identifies it, or it may be the occurrence number of the structure.
For example, suppose the following records appeared in a simple file that assisted water conservationists. Each record contains observations made at a single site; each occurrence of an OBSERVATION structure records the soil type at a certain depth at the one site and the date the observation was made.
SITE = 1; SITE = 2; OBSERVATION; OBSERVATION; SOIL = 10; SOIL = 10; DEPTH = 30; DEPTH = 50; DATE = 3/5/82; DATE = 3/5/82; OBSERVATION; OBSERVATION; SOIL = 20; SOIL = 50; DEPTH = 50; DEPTH = 20; DATE = 3/12/82; DATE = 3/12/82;
A searcher might want to retrieve all records that showed a SOIL type of 10 at a DEPTH of 50. If both SOIL and DEPTH were indexed in separate simple indexes, then SPIRES would falsely report that both of the above records met the criteria. Actually, a researcher would only want the second record to be retrieved.
If these indexes were qualified by a value that would uniquely identify the structure (such as the occurrence number, or the date value if unique), you could achieve the results you want by using the TAND, TNOT or TOR operators to tell SPIRES to compare both the element values and the qualifiers in both indexes. For example,
-> find soil = 10 -Result: 2 SITES -> and depth = 50 -Result: 2 SITES -> backup -Result: 2 SITES -> tand depth = 50 -Result: 1 SITE -> type site SITE = 2; ->
In the first two commands of the search, SPIRES looks only for records with a SOIL value of "10" and a DEPTH value of "50", and both records 1 and 2 contain such values. However, when you use the TAND operator, the qualifiers are also compared, so only record 2 would match, because the index values would be qualified with the same value.
Of course, you can still use each index separately as a simple index, if, for example, you wanted the records of all the sites at which the soil was at any time tested at a depth of 50 feet.
Remember that the file must be designed by the file owner for just such a purpose. If not, you can achieve the same results by using Global FOR searching techniques. See Section 4.3.2 in "Sequential Record Processing in SPIRES: Global FOR" for information about using the WHERE clause for comparing elements within the same structure.
Some files permit a form of searching known as proximity searching. Proximity searching lets you search for words based upon their position in a text element. This is particularly useful for searching titles and abstracts in bibliographic subfiles; it lets you search for two words that are near or next to each other. You can only perform proximity searching on subfiles that have proximity search indexes.
For example, if you wanted to locate articles about "information retrieval," you would want to find articles that have both those words directly next to each other, in that order. If only a standard word index were used, you might locate articles that contained the words "information" and "retrieval," but not necessarily next to each other.
The following types of proximity word searches can be performed (Assume that PWORD is a proximity word index):
1) FIND PWORD word1 word2 2) FIND PWORD word1 W word2 3) FIND PWORD word1 N word2 4) FIND PWORD word1 Wn word2 5) FIND PWORD word1 Nn word2
In the first form, there are only two words, and they are meant to be found in exactly the given order in consecutive positions. For example, given a subfile with TITLE as a proximity word index:
-> find title modern art
would retrieve only those records that have the title "MODERN ART" directly next to each other, in that order.
Different types of proximity word searches can be performed by using one of the proximity search operators, W or N.
The W operator specifies that the words must be found in the order given (and without a number, it is the same as no operator). The W operator with a number (Wn) specifies that the words must be located in the order given, and that there may be a maximum of "n" intervening words. For example,
-> find abstract snow w2 mountain
would retrieve:
"... the snow on the mountain..." "... Snow Mountain is a lofty peak..."
The N operator (for Nearness) specifies that the words are to be found near each other, but the order is not specified. Using the N operator with a number indicates that there can be a maximum of "n" intervening words. For example:
-> find abstract apple n candy
would retrieve records whose abstracts contained both "APPLE CANDY" and "CANDY APPLE".
-> find abstract lucid n3 dream
would retrieve:
"... a lucid dream can ..." "... in the dream he was quite lucid..."
One additional benefit of a proximity word index is that the file owner can also define it to be used as a standard word index with an optional sub-index. [See B.3.5.8.] In this case, a normal word search can be performed on a proximity word index if the value consists of just a single word. Therefore, the following are equivalent searches:
-> find pword banana -> find word banana
where pword is a proximity word index, and word is a standard word index.
Also in this case, you can use the sub-index to find records based upon the specific position of the word within the indexed value:
-> find pword last @position 2
would find any records where "last" was the second word within the element (e.g., "The Last Picture Show", etc.)
Be aware that only two words plus an optional proximity search operator can be used in a proximity search. Therefore, "FIND PWORD ALPHA N BETA N DELTA" would result in an error. Also, truncated searches are not permitted with proximity word indexes.
To determine if the file you're searching has one or more proximity word indexes, look for indexes that have names like PROX, use the SHOW INDEX INFO command for any additional information, or consult the file owner.
As you have seen, SPIRES offers many different techniques for indexing and searching. For instance, when you are searching a simple index, there are four different types of relational operators you can use in a search expression, including "=", ">", WITH, BEFORE and so forth. These operators are very powerful, but they can also be relatively expensive to use. If you construct search expressions carelessly, a simple search for a few records can easily cost ten times as much as a better-worded one.
This section will make suggestions on how to keep your costs down while searching SPIRES subfiles. There are three main suggestions:
- monitor CPU time
- determine the type of information within an index, and
- choose the best expressions for a search.
The SHOW CLOCKS command gives statistics on Unix CPU time used, broken down into search usage and file update usage. Figures in the first column are for the most recent search and update operations; figures in the second column are cumulative for the current SPIRES session. The elapsed time figure includes all Unix CPU use during the SPIRES session.
-> show clocks -Search: 0.153, 3.731 seconds -Update: 0.000, 0.000 seconds -Elapsed: 5.311 seconds
The SPIRES search timer can tell you the amount of CPU time a search is taking as the search is progressing. Thus you can abort a search that is taking a good deal of time. Without such a timer, it is difficult to know how much CPU time a search is taking, because the elapsed time varies depending on the resources being used by other system users. The timer also lets you monitor elapsed CPU time during Global FOR processing. [See B.5.3.3 or "Sequential Record Processing in SPIRES: Global FOR".]
The syntax of the command is:
SET TIMER {n | PAUSE}
where "n" is an integer greater than or equal to zero. The integer specifies the interval, in seconds, of CPU time that is allowed to elapse during searching and display operations before you are warned. If the timer is set to zero, then no warnings are issued. The default timer setting is five.
SET TIMER PAUSE actually stops the processing of your command when the timer interval in effect has elapsed. SPIRES will then ask if the search or display operation should be continued.
To cancel the PAUSE setting, issue the command SET NOTIMER PAUSE.
In this example, the timer is changed from the default five seconds to two seconds. Each time two seconds of CPU time elapses, a warning message is displayed.
-> set timer 2 -> select telephone directory -> find name smith -Elapsed CPU time: 2 seconds -Elapsed CPU time: 2 seconds -Result: 2048 NUMBERS ->
This time, not only is the timer interval changed, but the PAUSE option is used:
-> set timer 1 -> set timer pause -> select telephone directory -> find name smith -Elapsed CPU time: 1 second -Continue search? yes -Elapsed CPU time: 1 second -Continue search?
At the question "-Continue search?" you may unhurriedly consider whether the search is worth continuing. If you respond "yes", the search will resume where it stopped; if you respond "no", the search will be discarded without retrieving any records, though your previous search result, if any, will be retained.
Even if you have not used SET TIMER PAUSE, you can interrupt a search if it seems to be taking longer than you expected. To do so, press the BREAK/ATTN key. SPIRES will respond with the question "-Continue search?" to which you can respond either "yes" or "no".
The timer is reinitialized for each command issued. Thus, if the timer is set to five seconds (the default), issuing two separate commands that each took four seconds of CPU would not cause any warning messages to be displayed.
The SET TIMER command has other options (WAIT, COUNT) that are useful in protocols. For details on those options, see 5.18 in "SPIRES Protocols". [See E.1 for a brief explanation of protocols.]
When you are beginning a search, it is often difficult to determine what kind of values can be found in a given index. For example, in the public subfile RESTAURANT, there is a simple index called HOURS. What type of search value would you use? You might try
-> find hours 5 to 9 -Element=HOURS: Illegal Input -Serious data error, code=E46 -Not a legal or complete command -> find hours evening -Element=HOURS: Illegal Input -Serious data error, code=E46 -Not a legal or complete command
The "BROWSE index-name" command gives you a random list of values for any simple index chosen. It gives you an idea of what sorts of values are contained in the simple index so that you can construct a useful search request.
The form of the command is:
BROWSE {[FIRST|LAST] index-name | index-name value}
For example, to find out what types of values are in that HOURS index:
-> select restaurant -> browse hours BREAKFAST LUNCH DINNER ->
Specifying FIRST or LAST will cause the display to begin listing sequentially all the indexed values starting at either the beginning or the end of the index record set. Neither FIRST nor LAST may be abbreviated in this command. The "index-name" may be the name of any simple index identified by the SHOW INDEXES command.
The "value" option may be used to specify where the user wishes to begin looking in the index. SPIRES will respond with the values surrounding the specified value (or, if the value does not appear in the index, SPIRES will show the values surrounding that point in the index where the value would appear).
If you specify any of the options on the "BROWSE index-name" command, SPIRES will prompt with "-More?" after displaying a small number of values. You have the following options:
- to terminate: reply NO or press ATTN/BREAK
- to continue in the same direction: reply YES or OK
- to go backward: reply BACKWARD or "-"
- to go forward: reply FORWARD or "+"
Here are some more examples:
-> select people -> browse first discipline ACCOUNTING ART BROADCAST COMMUNICATION BUSINESS AND ECONOMICS CATEGORICAL IMPERATIVE CHEMICAL ENGINEERING -More? <---User presses ATTN/BREAK -> browse name san ROSEN SABIN SALEM SALTZMAN SAVIANO SCHMIDT SCOTT -More? <---User presses ATTN/BREAK
The IN ACTIVE prefix can be used to place the output into your active file. [See A.2.9.1.] If you add the CLEAN option to the IN ACTIVE prefix, SPIRES will not prompt you with "-More?", but will place about 10 values in your active file. For example,
-> select people -> in active clean browse name san -> list 1. ROSEN 2. SABIN 3. SALEM 4. SALTZMAN 5. SAVIZNO 6. SCHMIDT 7. SCOTT 8. SCOVEN 9. SCOVETTI 10. SCOWE ->
If the index is large but you need a complete list of all the indexed values, you should discuss your needs with the file owner, who can create a complete list or provide an alternate way for you to get one, rather than have you request "more" hundreds of times in response to the "More?" prompt.
This section deals with some shortcuts in forming a search request which, while convenient, can lead to ambiguities in the meaning of a search procedure. It will also describe the default conditions in effect when you do not specify a particular index name or logical operator.
When the index name is left out of a search expression, then the last index named that was not a qualifier is assumed. The system interprets the following four search procedures identically:
-> find title canadian and title history -Result: 450 BOOKS
-> find title canadian and history -Result: 450 BOOKS
-> find title canadian -Result: 650 BOOKS -> and history -Result: 450 BOOKS
-> find title history and canadian -Result: 450 BOOKS
Note that if you misspell an index name, SPIRES may assume that it is part of the search value to be located in the previously named index. For example:
-> find title canadian and ttle history -Zero result
is being interpreted as:
-> find title canadian and title ttle history
Note too that SPIRES will carry a default index name into a new search; for example:
-> find title canadian and history -Result: 450 BOOKS -> find canadian -Result: 43049 BOOKS
SPIRES uses TITLE as the default index, assuming that there is no index called CANADIAN.
There is no default index name for the first search command after a subfile is selected.
When no logical operator precedes a search expression using the default index name, AND is usually assumed to be the logical operator (although the file definer may specify otherwise).
-> find title canadian and title history -> find title canadian and history -> find title canadian history -> find title history canadian
The first two search requests are always interpreted identically by SPIRES. If the index is word-indexed (the usual case), the latter two requests are also interpreted the same way. [See B.3.6.5.]
Ambiguous search procedures may be entered inadvertently if the search expression contains words that have other meanings to SPIRES. An even greater number of ambiguities may arise when using default index names and default logical operators. The following are some rules for avoiding these pitfalls, while still making use of the convenient shorter forms.
Values that contain words with specific meanings in SPIRES, such as AND or OR, can be misinterpreted by the system.
Suppose, for example, an index is formed referencing subject phrases. Note that this is not a word index. The search expression:
-> find subject war, revolution and peace
will be interpreted by SPIRES as:
-> find subject war, revolution -> and subject peace
If the value is enclosed in quotation marks,
-> find subject "war, revolution and peace"
SPIRES will search for the subject "war, revolution and peace" only. In general, ambiguities of this type can be avoided by placing the value string in quotation marks ("value string"), but not apostrophes ('value string').
If the quoted value string contains quotation marks, then the surrounding quotation marks must be doubled; for example,
-> find title ""the man who cried,"i die!" and lived""
This rule applies only to quotation marks within the value, not to apostrophes.
Similar ambiguities involving relational operator names can also be solved with quotation marks.
-> find title word game
would retrieve all records with the word "game" in the title. On the other hand, if you placed quotation marks around your search value:
-> find title "word game"
would retrieve records with "word game" as the title (or as part of the title if the index is a word index).
Note also that a relational operator is not carried across a logical operator in a compound or iterative search.
-> find title prefix libr or biblio
would retrieve items with indexed "title" values of "biblio" or values that began with "libr", which is probably not what is intended.
-> find title prefix libr or prefix biblio
would retrieve items with indexed values that began with either "libr" or "biblio".
Other ambiguities can arise when index names become confused with values.
-> find title little wagon -Result: 7 BOOKS -> and color red -Result: 3 BOOKS
This procedure is ambiguous if the subfile has both a COLOR and a TITLE index name, since it can direct the search to either all records with the words, "little," "wagon," "color," and "red" in the title or to all records with the words "little" and "wagon" in the title, and with "red" as the indexed value of COLOR. The system will assume the latter interpretation to be the correct one, unless you specifically state the TITLE index name again or put the value in quotes:
-> and title color red
or
-> and "color red"
The file owner can also minimize confusion by choosing index names that will seldom be used as values in search expressions.
In general, search values containing non-alphabetic characters pose no special problem for SPIRES:
-> find department m-pg -Result: 1 ITEM
A problem may arise, however, when your search value contains a special character with a particular meaning for SPIRES in a searching context: for instance &, ), >, <, (, and, in certain circumstances, @. Suppose you are searching for a department with the unlikely name of M&N:
-> find department m&n -Zero result
SPIRES is interpreting the ampersand character as the logical operator AND, and searching for records containing the two separate values "m" and "n". To clear up this ambiguity you must surround your search value with quotation marks (not apostrophes):
-> find department "m&n" -Result: 1 ITEM
The @ symbol is used to search sub-indexes in SPIRES, and is used for for stored results and the result history feature. [See B.3.5.8.] In most cases, if your search value contains @ you should enclose the value in quotation marks.
Search values occur in several commands within SPIRES. They follow some combination of 'logical operator', 'search mnemonic' and 'relational operator'. Many times the logical operators are words, like: AND, OR, NOT. AND NOT is considered a single logical operator, as are both 'AND ~' and '& NOT'. Several of the relational operators are also words, such as: LIKE, WITH, WORD, MASK, STRING, PREFIX, SUFFIX, BEFORE, AFTER. Relational operators longer than four letters may be abbreviated to their first three letters; thus STRING could be: STRIN, STRI, or STR. The ALSO command and Global-FOR commands allow OCCURS and LENGTH prior to in/equality operators. In all of these cases, there are words involved that might be part of the value.
Here is a simple example:
find phrase pianos and string instruments
How should this be interpreted? Since there are no quoted values, SPIRES interprets it like this:
FIND PHRASE = "pianos" AND PHRASE STRING "instruments"
PHRASE is recognized as a search mnemonic. If there is no such search mnemonic, SPIRES issues an error message. In the original example, 'phrase' is followed by an implied equality (relational operator). The first value is "pianos". That is followed by a logical operator, AND, then a relational operator, STRING. The PHRASE mnemonic is assumed because logical operators do not have to be followed by a search mnemonic. The last value is "instruments".
But this may not have been how you wanted it interpreted. There are at least two distinct alternatives.
find phrase pianos and "string instruments"
find phrase "pianos and string instruments"
The first alternative is still two separate search values joined by the AND logical operator, but now the word 'string' is part of the second value. The second alternative is a single search value containing 'and' as part of the value. Both alternatives use implied 'equality' relations for the values. You could have written what follows for the first alternative:
find phrase pianos and = string instruments
The specific 'equality' operator satisfies the relational operator requirement, so until a 'logical operator' occurs, what follows is all value, even though it isn't quoted.
As a general rule, if you want to be specific about identifying any value, surround the value with quotes (not apostrophies). All quotes within values must be doubled. You must also quote values that have quotes in them, or begin or end with significant blanks. Here is an example where blanks are significant:
find phrase string " leading and trailing blanks "
[See B.3.2.3, B.3.3.1, B.3.6.4.3.]
The word index is very common and provides great flexibility in search requests; however, it can create problems for searchers unaware that words are indexed individually rather than indexed together in the phrases that may occur as element values. [See B.3.5.1.]
If you are searching a word index using content operators, your search value should not be longer than one word. Otherwise, an error message may result; the search may continue, but only the first word of the search value will be used.
-> select catalog -> find title prefix fear of -Element=TITLE: -Warning data error, code=E45 -Result: 224 BOOKS
The records retrieved by SPIRES would include not only those books whose titles began with "fear of" but also any that had the string "fear" at the beginning of any word in the title. FEAR OF FLYING would be found, but so would THE GREAT FEAR and DIABETES WITHOUT FEAR and KICKLE SNIFTERS AND OTHER FEARSOME CRITTERS.
In making this search, SPIRES first sees the search value is longer than one word and that the index only permits searches for values of one word. An error message is issued; some subfiles will completely reject the search at this point, but others, such as CATALOG above, will simply warn you of the problem and then continue the search, discarding all but the first word of the search value. SPIRES then looks through the entire index for any value that begins with the string FEAR, including FEARS, FEARSOME and so on. Since the title index makes each word in a title into a separate value in this word index, all words in the index beginning with the "fear" string satisfy the PREFIX criterion. Obviously you did not want all of these records. To solve this problem, you should use the equality operator instead:
-> find title fear of
which will retrieve records with the words FEAR and OF anywhere in their titles. [See B.3.5.1.]
The WORD operator should not be used at all to search a word index. It is not necessary; if it is used, it will make a simple search overly complicated and possibly quite expensive.
Using the equality operator, SPIRES searches for a specific value in an index just as you might look for a word in a dictionary. You would guess where the word should be in the book, figure how far off your guess was, try a few pages ahead, figure again, go back a few pages, and so forth, narrowing the range of your search till you found the word. SPIRES can do this type of searching very quickly.
However, suppose that you had to search the dictionary for every entry that had the word "bond" in it. You would have to look through the entire dictionary to find all of the entries, including "bond," "ionic bond," "bond paper," and "chemical bond." To look through the entire dictionary would be rather tedious but necessary in this case.
Similarly, when the WORD operator is used, SPIRES must search the entire index looking for occurrences of the search value. Even though each word in the word index occurs only once and only as a complete element, SPIRES does not realize this when it is searching. The system looks at every indexed value, even after finding the single occurrence of the value for which it is searching, because as far as it knows, that value could be in other element values later in the index. Thus it is highly inefficient to search a word index with the WORD operator; the equality operator should always be used instead.
The SET BIG SEARCH command is used when you need to retrieve a large number of records, and your search result will not fit in the space that SPIRES ordinarily allows for search results. SPIRES has only a certain amount of space in the main memory of the computer in which to work; this space is called "core". If there is not enough space in core to hold your search result, you will receive an error message, and your search request will not be completed.
The circumstances under which this occurs vary a great deal, depending on the size of the index records and how much space is already taken up in core by other components. So there are no true guidelines concerning when you might expect to have a search result too large to fit into main memory. Let it suffice to say that if you receive an S274 or, less likely, an S198 error message when issuing a FIND command, you will probably want to issue the SET BIG SEARCH command.
Its syntax is:
SET BIG SEARCH [nK]
This command reserves additional space outside of core to store large search results.
If you want SPIRES to process the records out-of-core before using up all of your core space, use the size (nK) option, where "n" is a positive integer, and K refers to "K bytes". This will automatically limit the size of core SPIRES uses for a result. Any result that exceeds this size becomes an out-of-core result. If "nK" is not specified, then SPIRES will use all available core. The usual amount of core space available is typically 200K.
For example,
-> select huge.file -> find code x -SEARCH ABORT. CODE=S274 -> set big search 100K -> find code x -Result: 10000 RECORDS
When you have a result saved out-of-core, you can issue the TYPE command to display the records or a FOR RESULT command to allow you to display the records sequentially. Note that under FOR RESULT, however, the SKIP command, SET SCAN SKIP command, or any command that references the LAST record (e.g., DISPLAY LAST) is not very efficient with out-of-core results. [See B.5.3.3.]
You can also use the STORE RESULT.name command to save the search result for later use. A stored result can be read by FOR SET RESULT.name, and can be used to create an out-of-core result with the search commands using the @RESULT.name form. [See B.3.8.1, B.3.8.2.]
If you think that you will be retrieving large search results, you should issue the SET BIG SEARCH command at the beginning of the session, before selecting a subfile. This provides a slight efficiency gain. Once you have issued the SET BIG SEARCH command, it remains in effect until you issue a CLEAR BIG SEARCH command. The CLEAR BIG SEARCH command can only be issued if there is no current out-of-core search result. So if you have an out-of-core result, first issue the CLEAR RESULT command and then the CLEAR BIG SEARCH command. [See B.3.7.1.]
To see if SET BIG SEARCH is in effect, issue the SHOW SETTINGS command. If it is, you will see the words BIG SEARCH at the end of the list of settings. [See A.2.9.5.]
You cannot have an out-of-core "stack", which means you cannot issue the SEQUENCE command for an out-of-core result. [See B.4.5.] There is one case, however, when you would be able to SEQUENCE from an out-of-core result. Consider the following example:
-> set big search -> select huge.file -> find code x -Result: 99534 RECORDS -> and date > 5/6/82 -Result: 356 RECORDS -> sequence date -STACK: 356 RECORDS
In this example, the first FIND command retrieved an out-of-core result, but by qualifying our result with an AND command, we reduced the size of the result and the stack could then fit in core.
If you have an out-of-core result, and you EXIT from SPIRES, there will be a slight delay because SPIRES must "clean up" the out-of-core files created for the large result. [See B.3.5.9.]
Once SPIRES produces a search result, you may review both the result and the means by which the search result was obtained. Beginning with a FIND command, the system records each step in the search procedure until a new FIND command is issued.
The SHOW RESULT command allows you to see the number of records in the current search result. Showing the result does not change it; to do that, you must issue further search commands. This command is useful when you have compiled a search request, left it momentarily to do something else, and later want to be reminded of the result record count.
The following is a simple example:
-> select restaurant -> find type chinese -Result: 9 RESTAURANTS -> or type french -Result: 14 RESTAURANTS : : : <---- User loses track of current status : -> show result -Result: 2 RESTAURANTS ->
The IN ACTIVE option can be used to place the output of the SHOW RESULT command into the active file. [See A.2.9.1.] To clear a search result, type:
CLEAR RESULT
This clears the current search result.
The SHOW SEARCH command allows the user to review the search commands executed since the last FIND command was issued.
The list does not include any illegal search requests, any requests that produced "Zero result" and caused the system to backup automatically, any results the user rejected by issuing the BACKUP command, or any search modifier in effect. SHOW SEARCH lists all criteria used to create a specific search result, and excludes all system-generated "Results" statements. The IN ACTIVE option may be inserted at the beginning of the SHOW SEARCH command to cause the output to be put into the active file. [See A.2.9.1.]
Here is an example of the SHOW SEARCH command:
-> select people -> find name s# -Result: 27 PERSONS -> or name b# -Result: 49 PERSONS -> or interest computers -Result: 63 PERSONS -> and interest chess -Zero result, previous result retained -Result: 63 PERSONS -> or interest water -Result: 68 PERSONS -> show search FIND name s# OR name b# OR interest computers OR interest water ->
You may have occasion to make an extensive and costly search involving a large number of records. With the "STORE RESULT.name" command, SPIRES has the capability to store the result in a Unix file for later use. "Storing the result" does not mean that the records themselves are stored; only the search commands issued and the locations ("pointers") of the records currently in the result are saved. Thus, if a record in a stored result is updated, then the next time the stored result is displayed, the updated version of the record will appear. [See B.3.8.2.]
The "STORE RESULT.name" command saves the current search result as a Unix file:
STORE RESULT.name [REPLACE]
where "name" is a valid Unix file name from 1 to 26 characters long. (The period after "RESULT" can be replaced by one or more blanks.) If a result with that name is already stored under your account, SPIRES will tell you that and ask you if that file can be replaced. To avoid that prompt, you can add the REPLACE option to the command.
You can also store a result as a temporary Unix file. A temporary result will be discarded when you exit the current SPIRES session. To store a temporary result, type:
STORE TEMPORARY RESULT.name or STORE TRESULT.name
The word "TEMPORARY" can be abbreviated to one letter.
The information stored includes the search result as well as all the commands used to obtain it beginning with the SELECT command. If you have set a search modifier, it will be included too. You can later see the stored search with the SHOW RESULT.name command [See B.3.8.3.] and you can use the stored search as the basis for another search, with the FIND @RESULT.name command [See B.3.8.2.] These techniques may save you the expense of searching twice for the same information, particularly when a large number of records is involved. (However, the STORE RESULT.name command will be blocked if your account has not been allocated sufficient Unix file space.)
Here is a sample session using the STORE RESULT.name command:
-> select catalog -> find author jones -Result: 310 BOOKS -> or author hawkes -Result: 327 BOOKS -> store result.books -"RESULT.BOOKS" put in Unix file system
If you wanted to store the result temporarily:
-> find author jacobs -Result: 12 BOOKS -> store temp result.books2 -'TRESULT.BOOKS2' put in Unix file system
Note that storing and restoring a search result is done in a different way from storing and restoring a stack [See B.5.4.2.] There is no RESTORE command for restoring a search result; that function is instead taken care of by the @RESULT.name facility described in the following section [See B.3.8.2.]
A temporary stored result is actually an attached Unix device. If you need to monitor the number of attached devices, you will also need to factor in temporary stored stacks and results.
When a search result has been saved with the STORE RESULT.name command, it may be used by including a search expression of the form:
@RESULT.name
where "name" is the same name that was used in the STORE RESULT.name command. (The period after "RESULT" can be replaced by one or more blanks.) To retrieve a temporary result, use the form:
@TEMPORARY RESULT.name or @TRESULT.name
"TEMPORARY" can be abbreviated to one character.
The following examples illustrate how to use stored results:
-> select catalog -> find @result.books -Result: 327 BOOKS -> select restaurant -> find @result.food and type german -Result: 15 RESTAURANTS -> select catalog -> find title watergate -Result: 80 BOOKS -> and not @result.watergate -Result: 3 BOOKS -> find @temp results.books2 -Result: 12 BOOKS
Note that in the second and third examples, the pre-stored result is used in conjunction with other search expressions. The third example shows how to retrieve all occurrences of "title watergate" since RESULT.WATERGATE was last modified. The last example assumes that the result was stored during the current session.
If you have proper file privileges, you can also access results stored under another account. To do this, you need to specify the other account's user code and, if in a different group from yours, its group code.
The full form of the "@RESULT.name" search expression is:
@[ORV.gg.uuu.]RESULT.name
or
@RESULT.name [USER uuu][GROUP gg]
where "gg" is the group code and "uuu" is the user code, both of the account "owning" the search result.
An alternate form of the search expression is:
@[@gg.][&uuu.]RESULT.name
For example:
-> select restaurant -> find @orv.ga.jnk.result.food and type mexican -Result: 1 RESTAURANT -> find @result.food user jnk group ga and type mexican -Result: 1 RESTAURANT
Some important features of stored results to remember:
- 1) The stored result does not contain the records in the result but "pointers" to the records that SPIRES uses to get the latest copy of each record when the result is restored. That means that a record that was in a result stored several days ago may have been removed or changed such that it no longer fits the original search criteria by the time the result is restored.
- 2) Although the stored result does contain the commands issued to create the stored result, SPIRES does not reissue those commands to restore the result. Only the records that were in the result at the time it was stored will be retrieved; new records fitting the criteria that have been added since the result was stored will not be included. [See B.3.8.4.]
- 3) If the stored result was originally retrieved using a goal-index [See B.3.1.1, B.3.1.2.] the added records that the goal-index retrieved may no longer appear within the result. (This is because they would have been stored with temporary deferred queue locators instead of permanent locators; see Section B.8.2.1 of the "SPIRES File Definition" manual for more information on this topic.)
The ERASE RESULT.name command is used to remove the search result from the Unix file system when you no longer need to store it:
ERASE RESULT.name [QUIET]
(The period after "RESULT" can be replaced with one or more blanks.) The QUIET option suppresses the system response if the command is successful. To erase a temporary result, use the ERASE TEMPORARY RESULT.name or ERASE TRESULT.name command. (Remember, though, that by default, temporary results will be discarded when you exit the session).
For instance,
-> erase result.books RESULT.BOOKS erased in Unix File System -> erase tresult.books2 TRESULT.BOOKS erased in Unix File System
The SHOW RESULT.name (or SHOW RESULT name) command lists the search commands that were stored in a Unix file as a result of the STORE RESULT.name command, as well as the date you created the stored result. [See B.3.8.1.] The IN ACTIVE option is also available to place the data in the WYLBUR active file. [See A.2.9.1.]
To see the search commands stored in a temporary Unix file, use the SHOW TEMPORARY RESULT.name or SHOW TRESULT.name command.
To see the search commands stored in a temporary CMS file, use the SHOW TEMPORARY RESULT name or SHOW TRESULT name command.
-> select catalog -> show result.books -'GQ.JPR.RESULT.BOOKS' created 04/20/1990 SELECT CATALOG FIND author jones OR author hawkes -> show tresult.books2 -'GQ.JPR.RESULT.BOOKS2' created 04/20/1990 SELECT CATALOG FIND author jacobs
The SHOW RESULT NAMES command lists all the "RESULT.name" files stored under your account in the Unix file system. Information displayed by the command includes the creation (CR) and last access (LA) dates.
To see temporary stored results, use the SHOW TEMPORARY RESULT NAMES or SHOW TRESULT NAMES command. Information displayed by this command includes the Unix device id.
The following is a sample list:
-> show result names RESULT.BOOKS RESULT.FOOD RESULT.WATERGATE -> show temp result names Temporary Result Names: TRESULT.BOOKS2 (13) ->
Another method for saving results is to keep a "history" of search results which you can refer back to. You can use a result history instead of "storing the result" -- stored results are primarily useful when you want to save a result for a future session. [See B.3.8, B.3.8.1, B.3.9.1, B.3.9.2.]
The SET RESULT HISTORY command creates a temporary file to hold previous search results created from a FIND, AND, OR, NOT, or GENERATE RESULT command. The syntax of this command is:
SET RESULT HISTORY n
"n" indicates the number of results that will be retained. This number defaults to 100, but can range from 20 to 2000. For example, the default of 100 will retain the last 100 search results.
When you use this command, SPIRES appends each "-Result" message with the result history number (@n). The result history does not include illegal search requests, or any requests that produced "Zero result."
Result histories only last for the duration of the session, and are subfile specific--that is, you need to set a new history whenever you select a subfile.
The "@n" search expression can be used to retrieve an existing result from the result history set. For example, FIND @3 will restore result "@3" from the result history. FIND @n does not create a new entry in the result history; instead, it takes you back to the old entry as though you had just generated it.
An example of using the SET HISTORY and FIND @n commands:
-> select restaurants -> set result history 50 -> find cuisine mexican -Result: 29 RESTAURANTS (@1) -> and city menlo park -Result: 5 RESTAURANTS (@2) -> or city palo alto -Result: 115 RESTAURANTS (@3) -> backup -Result: 5 RESTAURANTS (@2) -> find @1 -Result: 29 RESTAURANTS (@1) -> or @3 -Result: 134 RESTAURANTS (@4)
The SET RESULT HISTORY command may be issued even when a result history exists; you can change "n" to increase or decrease the range of stored results.
When the size of the result history reaches "n," a message is displayed: "Full Result History". You should increase the result history size if you don't want to lose the earliest entries. Once lost, they cannot be retrieved from the result history.
The SHOW RESULT HISTORY command displays the number of result history sets currently saved, and gives a one line description for each result set. It works only when the SET RESULT HISTORY command has been issued for the selected subfile. [See B.3.9.1.]
For example:
-> show result history -Result History: range=50; last=4 @1 Result: 29 FIND cuisine mexican @2 Result: 5 FIND @1 AND city menlo park @3 Result: 115 FIND @2 OR city palo alto @4 Result: 134 FIND @1 OR @3
"range" shows the maximum number of results that can be retained; "last" displays the number of the last saved result. The IN ACTIVE prefix is also available to place the data in the WYLBUR active file.
Note that the result history begins with FIND @n whenever the command was a continuation of a search (and, not, or). This indicates which result set was the basis for the continuation.
The CLEAR RESULT HISTORY command clears result history for the subfile. It does not discard the current result; only the result history is discarded. Future results will not be retained unless the SET RESULT HISTORY command is re-issued.
For example:
-> find name b# -Result: 14 PERSONS (@1) -> and interest sailing -Result: 1 PERSON (@2) -> clear result history -> or name g# -Result: 15 PERSONS
Note that "@n" is no longer appended to the result statement after the result history is cleared. The previous results can no longer be retrieved with the FIND @n command.
You can use the BACKUP command to backup through an iterative search that has result history entries for each iteration. You can BACKUP to the initial FIND, providing the result history still contains the initial FIND.
If you have multiple FIND's within a result history, you can use FIND @n to go to any existing entry, and use the BACKUP command to go back to the originating FIND. You cannot backup past the FIND.
For example:
-> show result history -Result History: range=100; last=5 @1 Result: 110 FIND city palo alto @2 Result: 30 FIND @1 AND hours lunch @3 Result: 1 FIND @2 AND hours breakfast @4 Result: 38 FIND city menlo park @5 Result: 9 FIND @4 AND hours lunch -> find @3 -Result: 1 RESTAURANT (@3) -> backup -Result: 30 RESTAURANTS (@2) -> backup -Result: 110 RESTAURANTS (@1)
Once you have a search result, you may examine the goal records retrieved. The search result, in whole or in part, may be displayed at the terminal or placed in your active file, in the SPIRES standard format or using a custom format when one has been defined.
The SHOW ELEMENTS command displays a list of the elements that make up each goal record in the subfile. For example,
-> select blood donors -> show elements Subfile BLOOD DONORS ID NAME, DONOR.NAME, NAM ADDRESS, ADD CITY, CIT STATE, STA ZIPCODE, ZIP PHONE.NUMBER, PHN, PHO CAN.BE.CALLED, CAL, CAN BLOOD.TYPE, BLD, BLO, BLOOD DONATION, DON . DATE, DAT, DATE.GIVEN . LOCATION, LOC, WHERE.GIVEN TOTAL.PINTS, PINTS, PINTS.GIVEN, TOT COMMENTS, COM
The list of elements displayed in the above example shows some additional, abbreviated names for each element. These are "aliases". An element might have a long name for clarity (such as CAN.BE.CALLED), but the length can be a problem when you have to type it repeatedly in various commands. File owners can give each element one or more aliases, usually abbreviations of the original element name. You can use an element's aliases instead of its full name in any command that uses an element name, including TYPE, SEQUENCE, and other commands discussed in this chapter. Aliases can also be used in data entry. [See D.2.2.]
The element names are shown in the order in which the elements in a record are displayed using the standard SPIRES format. Elements occurring within a "structure" [See D.2.3.] are indented beneath the name of the structure and preceded by periods to show the structural hierarchy.
The IN ACTIVE prefix may be used to place the listing in the active file. [See A.2.9.1.]
The file owner can store a great deal of information about each element, such as a description, what type of value is allowed, or formatting instructions to be used by system formats such as $REPORT. [See C.3.6.] This information is stored in "element information packets" and so is referred to as "element information". Because this information is created by the file owner, not every subfile will display element information.
The information shown on a SHOW ELEMENTS command might include some element information if it has been added by the file owner. Possible additions are a heading for the element (sort of a "super-alias" for the element used by the $REPORT and $PROMPT formats, among others) and a description of it.
The following example shows a display that includes all possible information shown by this command:
-> select almanac
-> show elements
Subfile ALMANAC
ENTRY -- Num. Entry number (slot number)
DATE, D, 2 -- Date Exact Date of Event
DAY
NAME, N -- Name Name of celebrant
CLAIM-TO-FAME, C -- Claim to Fame Celebrant's claim to fame
WHAT, W -- Event Event being commemorated
CURRENT-DATE, NOW, THIS-YEAR, 1 -- Anniversary date this year.
Anniversary Date
ANNIVERSARY, ANN -- Anniversary Which anniversary this year
WEEKDAY -- Weekday Weekday this year for
anniversary
SERENADE.DATE
LOCATOR
The element names and aliases are shown before the dash (--), the heading appears after the dash, and the description appears in the column to the right.
The SHOW ELEMENTS command is one of a group of commands that displays information about the elements in a subfile. The complete syntax for these commands is:
SHOW ELEMENT[S] [NAMES|INFORMATION|DESCRIPTION|CHARACTERISTICS]...
...[[FOR] element]
The SHOW ELEMENT NAMES, SHOW ELEMENT DESCRIPTION, and SHOW ELEMENT INFORMATION commands show you more of the element information. They are discussed in following sections. [See B.4.1.1, B.4.1.2, B.4.1.3.] The SHOW ELEMENT CHARACTERISTICS command displays information about the elements that might be useful when doing data input. [See D.1.3.6.]
The "FOR element" phrase may be added to limit the display to information about a particular element or structure. The "FOR" is optional unless it is necessary to prevent ambiguity, as when, for example, you have an element named "DESCRIPTION" or "CHARACTERISTICS". If you name a structure, information about all the elements within the structure will be displayed.
The SHOW ELEMENT NAMES command displays only the names and aliases of the elements in the subfile, and does not show any descriptive information about the elements. The syntax is:
SHOW ELEMENT NAMES [[FOR] element]
If no element information has been added to the file by the file owner, the SHOW ELEMENT NAMES and SHOW ELEMENTS commands will produce identical displays.
Here is an example of the SHOW ELEMENT NAMES command:
-> show element names Subfile ALMANAC ENTRY DATE, D, 2 DAY NAME, N CLAIM-TO-FAME, C WHAT, W CURRENT-DATE, NOW, THIS-YEAR, 1 ANNIVERSARY, ANN WEEKDAY SERENADE.DATE LOCATOR -> show element names for claim-to-fame CLAIM-TO-FAME, C
The SHOW ELEMENT DESCRIPTION command shows you a description of the elements if one has been included by the file owner. The syntax is:
SHOW ELEMENT DESCRIPTION [[FOR] element]
Included in the display are the element name and aliases, the descriptive heading, and both a brief and a long description. Only those items that have been included by the file owner as part of the file definition will appear in the display, although all elements and their aliases will be listed.
The following is an example of the display:
-> show element description
Subfile ALMANAC
Slot ENTRY -- Num.
Entry number (slot number)
This element is the slot key of the subfile.
Element DATE, D, 2 -- Date
Exact Date of Event
The DATE element represents the exact date that the event took place.
If the event does not have an exact date but happens regularly (e.g.,
Christmas on December 25), then use the DAY element.
(the display continues)
The FOR phrase may be added to display the description of a single element (or the elements within a single structure), as follows:
-> show element description for claim-to-fame Element CLAIM-TO-FAME, C -- Claim to Fame Celebrant's claim to fame This element represents the claim to fame of the person named by the NAME element. It is usually the person's nationality and occupation.
The SHOW ELEMENT INFORMATION command displays all of the information about the element that has been included by the file owner. This includes a lot of information that is used by system facilities such as the $REPORT format. They are primarily formatting instructions, such as how wide to make the column if the element is used in a multiple-record display created by the $REPORT format. [See C.3.6 for more details about using this information.]
The SHOW ELEMENT INFORMATION command will show you whether the file owner has defined such things for the subfile. If so, it is probably best to use these defaults since they were chosen as the best or most useful way to display the data.
The syntax is:
SHOW ELEMENT INFORMATION [[FOR] element]
Below is an example of the display of this information:
-> show element information
Subfile ALMANAC
Slot ENTRY -- Num.
Note: Entry number (slot number)
Width: 4 Adjust: RIGHT Indent: Edit:
Description:
This element is the slot key of the subfile.
Element DATE, D, 2 -- Date
Note: Exact Date of Event
Width: 16 Adjust: Indent: Edit:
Value type: DATE
Input occ: 1
Index: DATE
DAY
Description:
The DATE element represents the exact date that the event took
place. If the event does not have an exact date but happens
regularly (e.g., Christmas on December 25), then use the DAY
element.
(the display continues)
The "FOR element" option may be added to limit the display to the information for a particular element or structure.
Once a search result has been retrieved, the records may be displayed at the terminal using the TYPE command. Options for the TYPE command allow you to pause between display of each record, display only selected data elements in a record, or eliminate a record from the search result after having examined it.
The TYPE command displays at the terminal those goal records in the current search result (or in the current stack if a SEQUENCE or STACK command has been issued). [See B.4.5, B.5.4.1.]
The command format is:
TYPE [element-list] [SKIP=n] [KEEP|PAUSE] [CLEAN]
The "element-list" is an optional set of data element names; it restricts the display to the elements specified. [See B.4.3.1.] The "SKIP=n" option specifies that "n" records are to be passed over before the display begins. KEEP causes SPIRES to prompt you for acceptance of each record after it is displayed. [See B.4.4.] PAUSE instructs SPIRES that, after displaying each record, it should await a carriage return before continuing. (See below for more details on the PAUSE option.) KEEP and PAUSE are mutually exclusive. CLEAN suppresses the usual blank line that separates multiple records from each other during a TYPE command. (See below for more details on the CLEAN option.)
It is often necessary to place the results of a search in the active file, so that they can be printed, for instance. Hence, the IN ACTIVE option is particularly useful with the TYPE command. [See A.2.9.1.]
When no other condition has been specified, SPIRES displays all the records in the search result in their complete form. All records are displayed in the standard SPIRES format, unless a special format has been defined and is currently in effect. [See B.4.6.]
The most up-to-date copy of each record will be displayed, unless you request otherwise by adding the VIA prefix. [See B.5.5.] (The VIA prefix can also limit the display to only those records that have been recently updated, for example.) It is possible then that a record retrieved with a search may have been updated since the indexes were last updated such that the record as shown does not reflect the indexed data. This is a relatively rare occurrence, however; if it is a problem for you, however, consider using the VIA prefix.
Here is an example of the TYPE command, using the "element-list" option:
-> select people
-> find interest computers
-Result: 19 PERSONS
-> type name interest
NAME = Agnes Bandersnatch;
INTERESTS = water polo, plants, computers, zen-tennis, rock 'n' roll;
(the display continues)
The PAUSE option causes SPIRES to stop after displaying each record, type a hyphen, and await a carriage return before continuing. Any response other than pressing the ATTN/BREAK key will also cause display to continue. To end the display, press ATTN/BREAK; this causes the display to stop, but the current search result is unaffected.
For example:
-> select restaurant -> find cuisine chinese -Result: 9 RESTAURANTS -> type name pause NAME = Yangtze River; - <---(User presses carriage return to continue) NAME = Ming's; - *** <---(User presses ATTN/BREAK to stop) ->
The PAUSE option is timed. After a record has been displayed for five minutes, SPIRES will automatically display the next one.
Normally, SPIRES inserts a blank line between the display of each record during the execution of a TYPE command. If the IN ACTIVE option is used with the TYPE command, SPIRES begins the display of each record with a line (containing "****") and ends each one with another line (containing ";"). These lines make it easier to distinguish between different records. Sometimes, however, the extra lines can be an annoyance: for instance, more information could fit on a CRT screen or on a printed page if the lines were suppressed. The CLEAN option suppresses these extra lines.
For example:
-> select restaurant -> find cuisine chinese -Result: 3 RESTAURANTS -> type name clean NAME = Yangtze River; NAME = Ming's; NAME = Chef Chu's; ->
When displaying records, you can restrict the data elements displayed for each. The TYPE command can be limited to displaying only those elements you choose to display. You specify an element list, instructing the system which data elements to display. You may include this element list with each TYPE command, or you may establish elements to be displayed with the SET ELEMENTS command.
The "TYPE element-list" command displays only the elements named as it processes the search result.
For example:
-> select documents -> find keyword spires -Result: 24 DOCUMENTS -> type title price PRICE = NOT APPLICABLE; TITLE = Data File Directory; PRICE = $0.50; TITLE = Using the EDUNET Subfiles at Stanford; PRICE = FREE; TITLE = Sorting Records in SPIRES; PRICE = FREE; TITLE = Building A Concordance Using SPIRES; (the display continues)
A list of elements you can display can be found with the SHOW ELEMENTS command. [See B.4.1.]
The "TYPE element-list" command displays elements in the order in which they occur in the record, which is not necessarily the order you might specify them in the TYPE element-list command. (See the example above for just such a rearrangement.)
TYPE followed by an element-list temporarily overrides a previously issued SET ELEMENTS command. [See B.4.3.1.] It also overrides any format that has been set -- the requested elements will be displayed in the standard SPIRES format, not in the set format. [See B.4.6.3.]
The SET ELEMENTS command specifies which elements are to be displayed with the TYPE and DISPLAY commands. [See B.5.1.1.] It is most often used when you want to display the same set of elements in examining several different search results: it allows you to type the list only once, rather than on each TYPE command. [See B.4.3.1.]
The command has the form:
SET ELEMENTS [[+|-] element-list]
The element-list contains data element names separated from each other by blanks or commas. The "plus or minus" option can be used if an element list has been set previously. Using the "plus" option, you can add other elements to the set list without respecifying the list; the "minus" option removes the specified elements from the set list.
Only the elements in the set element list are printed at the terminal by DISPLAY or TYPE commands. The command overrides (but does not cancel) any format that is set, as well. That means that the elements in the set element list will be displayed in the standard format, whether or not a format is set. [See B.4.6.3.]
A SET ELEMENTS command is cancelled when another SELECT or SET ELEMENTS command without the plus or minus option is issued. The CLEAR ELEMENTS command also cancels any previous SET ELEMENTS command; the system reverts to displaying all elements of each goal record. If a format is still set, the records will be displayed through it.
Here is an example using the SET ELEMENTS command:
-> select people
-> set elements name interests
-> find interests swimming or books
-Result: 3 PERSONS
-> type
NAME = Tillie Williams;
INTERESTS = good food, books, tennis, football,
coffee, but not tea;
(the display continues)
-> set elements + background
-> type
NAME = Tillie Williams;
BACKGROUND = B.A. from Foothill Community College
with double major in business and applied engineering.
(Summer sessions at Bucknell);
INTERESTS = good food, books, tennis, football,
coffee, but not tea;
(the display of records continues)
The SHOW ELEMENTS SET command will display a list of the elements that have been set.
For example,
-> show elements set NAME INTERESTS BACKGROUND
A virtual element is a special kind of element that is not actually stored in a subfile, but is created dynamically from other existing elements, when specifically requested. [See C.11.2 in "SPIRES File Definition".] Virtual elements are listed when you issue a SHOW ELEMENTS or SHOW ELEMENT CHARACTERISTICS command. The SHOW ELEMENT CHARACTERISTICS display specifies which elements are virtual elements. [See D.1.3.]
You can include a virtual element in a SET ELEMENTS command, just like any other element.
Normally when a record is displayed in standard SPIRES format with no SET ELEMENTS command in effect, virtual elements are not shown. To see virtual elements as well as the rest of the record, you can use a special form of the SET ELEMENTS command:
SET ELEMENTS ALL + virtual-element-list
where "virtual-element-list" consists of the names of the virtual elements you would like displayed.
Searching alone does not always provide you with sufficient information to create a final search result. The TYPE KEEP command allows you to modify the search result by examining each record individually and then deciding whether it should be kept in the search result.
TYPE KEEP causes SPIRES to prompt "Keep?" following the display of each goal record. A "yes", "y" or "ok" response retains the record in the search result and causes the next record to be typed. A "no" or "n" response drops the record from the search result and causes the next record to be typed. Pressing ATTN/BREAK retains the record and halts the display of other records. In no case will any of the three responses cause records to be deleted from the subfile.
After this series of system prompts and user responses, the system displays the new search result if different from the original result. This result reflects the number of records in the original search result, less the number to which you responded "no". If you respond "no" to all the records, the search result will be zero, and if a previous search result existed, an automatic backup will occur. [See B.3.3.2.]
-> find author brown -Result: 7 BOOKS -> set element author, id -> type keep ID = 18; A = JOE E. BROWN; -Keep? yes ID = 13; A = JOHN BROWN; -Keep? no ID = 11; A = BUSTER BROWN; -Keep? *** (ATTN/BREAK) -Result: 6 BOOKS ->
Records retrieved in a search result may appear to be in random order. Even when the ordering of the records is recognizable, the order may not be what you want. The SEQUENCE command permits you to order records in the search result according to the value of one or more elements.
The general forms of the command are:
SEQUENCE element-name [(D)|(X)|(DX)] [element-name list] SEQUENCE (D) SEQUENCE
The first element-name is the primary sort field and the optional values specified in the element-name list are secondary sort fields in the same form as the primary; element names are separated by a comma or a blank. The SEQUENCE command may appear with only (D) or with nothing following it (see the "Technical Note" below). The VIA prefix may be added to front of the SEQUENCE command to limit the records being sequenced. [See B.5.5.]
SEQUENCE sorts records in ascending order, with letters coming before numbers. For sequencing, letters are converted to upper case. This means that values that are identical except for variances in upper and lower case are considered equivalent for the SEQUENCE command. To obtain a sort in descending order on a particular element, the element-name must be followed by the value "(D)". If a single element value occurs several times in a single record, then only its first occurrence is used in the sort. In ascending order, nonexistent values precede null values, which in turn precede non-null values. In descending order, the reverse is true.
In subfiles, an element may be transformed into a different value for internal record storage and transformed back into its original form when records are displayed. SPIRES normally sequences records by the internal "stored" form of the element value. Occasionally you may want to sequence records using the external value; use "(X)" after the element's name in the SEQUENCE command, or "(DX)" if you want the records sequenced on the external form in descending order. Note: most searchers do not need to use the "(X)" option.
Here is an example using the SEQUENCE command:
-> find grade 5 -Result: 113 PERSONS -> sequence sex age(D) height weight -Stack: 113 PERSONS
This statement sorts a search result by sex and, when sex is the same, by age in descending order. When age also is the same, the sort is by height; and, when height also is the same, by weight.
The SEQUENCE command creates a "stack" of records. Stacks are also created using the STACK command. [See B.5.4.1, D.7.5.] The stack created by the SEQUENCE command can be used like a search result -- for example, the sequenced result can be displayed using the TYPE command, or the search can continue iteratively. (If both a stack and a result exist when the TYPE command is issued, the latest one created is displayed. If you start a new search with a FIND command or continue the current search iteratively, the stack is discarded.)
If you are sequencing a stack of records that includes duplicate records, that is, the same record is in the stack more than once, that record will appear only one time in the new stack created by the SEQUENCE command.
In addition to sorting records in a search result, the SEQUENCE command may be used to sort records in a Global FOR class. [See B.5.3.3.] After establishing a Global FOR class, use the STACK command to create a stack of records on which SEQUENCE can operate. [See B.5.4.1.] For example:
-> for adds
+> stack all
-Stack: 10 RECORDS
+> sequence name
-Stack: 10 RECORDS
+> type <--- to see the 10 sorted records in
the stack
The SEQUENCE command can be issued without any element names, which tells SPIRES to arrange the records by the record key (if it is in the stack or result) or by the locator if the key is not available. When you are sequencing a search result, that means the key is used if the goal record-type is non-REMOVED; for subfiles with a REMOVED goal record-type (the majority of subfiles), the locator is used.
SEQUENCE by itself sorts the keys or locators in ascending order. If SEQUENCE (D) is used, the keys or locators are sorted in descending order. If you intend to GENERATE RESULT from a stack, it is best to have the stack in descending sequence by keys or locators. [See B.5.4.2a.]
When you issue the SEQUENCE command, you can limit the records placed in the stack by adding a VIA prefix to front of the command. [See B.5.5.] This allows you to sequence only those records in the result that meet particular criteria, like those just added or updated.
The SPISORT facility provides another SPIRES method for sorting records. It can order an arbitrarily large number of records, unlike the SEQUENCE command, which cannot handle more than, say, 3,000 records, depending on the size of the records. However, the SPISORT facility in SPIRES does require that a batch job be submitted, and thus does not provide immediate results like the SEQUENCE command. A comparison of these two different techniques is included in the SPIRES manual "Technical Notes", section 1, which also includes the command syntax for the SPISORT facility.
When you use a search command such as FIND, you are in effect asking SPIRES to filter out any records in the data base that fail to match your search criteria. In much the same way that search commands filter data on a subfile level, the element filters described in this section filter data on the record level, letting you display only element occurrences that fit the criteria you name.
For example, suppose you have a subfile called SUPPLIERS, containing records of companies from which you order equipment. Each record in SUPPLIERS contains the supplier's name, as well as a multiply-occurring structure, where each occurrence describes a particular order. If you retrieve all records with a given order date and display them without filters, you'll see all occurrences of the order structure for each record, including occurrences that you don't care about:
-> find date.ordered 1985 -Result: 1 SUPPLIER -> type ID = 10891; SUPPLIER = Rutland Discount; ORDER; DATE.ORDERED = 1979 Apr 1; <---(Orders are displayed for ITEM = Typewriter; all dates, not merely 1985) ORDER; DATE.ORDERED = 1985 Apr 9; ITEM = Macintosh Keypad; ->
However, by setting a display filter with the SET FILTER command, you can narrow the display to occurrences with a particular date: e.g., you can display orders placed in 1985, filtering out orders placed in other years:
-> find date.ordered 1985 -Result: 1 SUPPLIER -> set filter for order where date.ordered = 1985 -> type ID = 10891; SUPPLIER = Rutland Discount; ORDER; DATE.ORDERED = 1985 Apr 9; <--(Occurrences for 1979 are ITEM = Macintosh Keypad; filtered out of the display) ->
To set a filter, issue the SET FILTER command:
SET FILTER FOR elem.name [(occ)] [(SEQUENCE elem.list)]... ... [WHERE clause]
"Elem.name" is the name of the element being filtered; any element can be filtered, including a virtual or dynamic element. [See Chapter 20 in "SPIRES Technical Notes" for information about dynamic elements.] The element to be filtered can also be a structure, as in the previous example.
The "(occ)" option specifies which occurrences of the element named should be processed by subsequent commands, after the WHERE clause on the SET FILTER command has finished filtering the record.
The SEQUENCE option lets you specify how (or whether) the element values that pass filter constraints should be sequenced. The syntax of the SEQUENCE option is very similar to that of the SEQUENCE command, described in B.4.5:
(SEQUENCE elem.name [(D)|(X)|(DX)] [elem.name...] )
If the element is a structure, the SEQUENCE option may name elements (one or more) within the structure by which the structure should be sequenced. If the filtered element is not a structure, only the element itself may be named in the SEQUENCE clause. The (D) option causes filtered values to be sequenced in descending order, while the (X) option causes filtered values to be sequenced according to their external form, in those cases where the internal and external form differ.
"WHERE clause" is a clause following the same rules as a WHERE clause in Global FOR, such as the clause "where date.ordered = 1985" in the example in the previous section. [See the SPIRES Global FOR manual for more information on WHERE clauses.] Among other uses, the "WHERE clause" option on the SET FILTER command lets you filter an element's occurrences according to each occurrence's value.
Consider again the SUPPLIERS subfile where each goal record contains the name and address of a supplier, as well as information about each ORDER (a structure) placed with it. Unfiltered records might look as follows:
-> find date.ordered = 1984 -Result: 2 SUPPLIERS -> type ID = 10964; SUPPLIER = Fly Pie Shoe Shop; ORDER; DATE.ORDERED = 1983 May 28; ITEM = Electric Shoe Horns; ORDER; DATE.ORDERED = 1983 Jul 12; ITEM = Sock Parts; ORDER; DATE.ORDERED = 1984 Jan 14; ITEM = Toe Girdles; ORDER; DATE.ORDERED = 1984 Mar 20; ITEM = Plaid Shoe Polish; ID = 10643; SUPPLIER = 3-D House of Beauty; ORDER; DATE.ORDERED = 1982 Dec 11; ITEM = Pancake Hair Spray; ORDER; DATE.ORDERED = 1984 Feb 8; ITEM = Eyelid Wax; ORDER; DATE.ORDERED = 1984 Feb 10; ITEM = Dimple Putty;
But if you set a filter you can get rid of those extraneous orders for pre-1984:
-> set filter for order where date.ordered = 1984 -> type ID = 10964; SUPPLIER = Fly Pie Shoe Shop; ORDER; DATE.ORDERED = 1984 Jan 14; ITEM = Toe Girdles; ORDER; DATE.ORDERED = 1984 Mar 20; ITEM = Plaid Shoe Polish; ID = 10643; SUPPLIER = 3-D House of Beauty; ORDER; DATE.ORDERED = 1984 Feb 8; ITEM = Eyelid Wax; ORDER; DATE.ORDERED = 1984 Feb 10; ITEM = Dimple Putty;
Furthermore, with the SEQUENCE option, you can ask SPIRES to sequence occurrences that have passed the filter:
-> set filter for order (sequence item) where date.ordered = 1984 -> type ID = 10964; SUPPLIER = Fly Pie Shoe Shop; ORDER; DATE.ORDERED = 1984 Mar 20; ITEM = Plaid Shoe Polish; ORDER; DATE.ORDERED = 1984 Jan 14; ITEM = Toe Girdles; ID = 10643; SUPPLIER = 3-D House of Beauty; ORDER; DATE.ORDERED = 1984 Feb 10; ITEM = Dimple Putty; ORDER; DATE.ORDERED = 1984 Feb 8; ITEM = Eyelid Wax;
The "(occ)" option specifies which of the element occurrences should be processed of those that passed the WHERE filters. For example, after the WHERE clause below has filtered occurrences of the order structure to find keypad orders, the option "(1/2)" would cause subsequent display requests to show only the first two keypad orders, suppressing any orders beyond these first two:
-> set filter for order (1/2) where item = keypad
The following values may be used for the "(occ)" option:
n - a number, representing the "nth" occurrence
FIRST - the first occurrence
LAST - the last occurrence
LAST-n - the "nth" occurrence from the last
n/m - the "nth" through "mth" occurrences;
"n" or "m" may be any of the above forms
ALL - all occurrences (the same as leaving the option off)
Here is an example using the "(occ)" and "sequence" options:
-> set filter for order (1/2) (sequence date.ordered(D)) -> type ID = 10964; SUPPLIER = Fly Pie Shoe Shop; ORDER; DATE.ORDERED = 1983 Jul 12; ITEM = Sock Parts; ORDER; DATE.ORDERED = 1983 May 28; ITEM = Electric Shoe Horns; ID = 10643; SUPPLIER = 3-D House of Beauty; ORDER; DATE.ORDERED = 1982 Dec 11; ITEM = Pancake Hair Spray; ORDER; DATE.ORDERED = 1984 Feb 8; ITEM = Eyelid Wax;
In this command, only the first two occurrences (1/2) of the ORDER structure in each record were procesed. They were arranged in descending order by the DATE.ORDERED element.
To see what filters are currently in effect for the goal records, you can issue the SHOW FILTERS command.
To clear the filter set for a single specified element, issue the CLEAR FILTER command, naming the element whose filters should be removed:
CLEAR FILTER FOR elem-name
To clear all filters currently in effect, issue the CLEAR FILTERS command.
The following segment of a terminal session shows how these three commands could be used:
-> set filter for order where date.ordered ~= 1985 -> set filter for supplier where supplier = ibm -> show filters SET FILTER FOR ORDER WHERE DATE.ORDERED ~= 1985 SET FILTER FOR SUPPLIER WHERE SUPPLIER = IBM -> clear filter for supplier -> show filters SET FILTER FOR ORDER WHERE DATE.ORDERED ~= 1985 -> clear filters -> show filters -No filters found
In addition to limiting the display of element occurrences after a DISPLAY or TYPE request, filters can also determine which element occurrences should be scanned by a WHERE clause in Global FOR.
Only one filter may be set for a single element. (Setting a second filter for an element causes the first filter to be replaced by the newcomer.) Up to twenty filters may be set at a time for a given goal record set.
Filters affect the following display commands:
- the DISPLAY command
- the TYPE command
- the SEQUENCE command
In general, filters do not affect the following commands:
- input commands, such as ADD or UPDATE
- the TRANSFER command [One form of the SET FILTER command does apply to merging of data into a record with the MERGE command or a merge input format. See Chapter 21 of "SPIRES Technical Notes" for details.]
There other options for the SET FILTER command, too. For a complete description of filters, see Chapter 21 of "SPIRES Technical Notes".
The following record from the RESTAURANT subfile is in standard SPIRES format ("element-name = element-value;"). [See B.4.2.1.]
ID = 38;
DATE-ADDED = FEB. 26, 1976;
DATE-UPDATED = FEB. 26, 1976;
NAME = Hsi-Nan;
CITY = Palo Alto;
STATE = California;
PHONE = 323-6550;
ADDRESS = Town and Country Village;
RECOMMENDER = Rita Taylor;
COMMENTS = Small friendly restaurant with great hot & sour soup,
kuo-teh ;
CUISINE = Northern Chinese, Hot, spicy food;
PRICE-AVERAGE = $4.50;
FOOD-QUALITY = Good;
SERVICE-QUALITY = Good;
HOURS = lunch, dinner;
ENTERTAINMENT = None (just the other diners);
BAR = Beer;
With a custom format set, the same record looks like this:
+--------------------------------------------------------------------+ | Hsi-Nan Cuisine(s): Northern Chinese, | | Town and Country Village Hot, spicy food | | Palo Alto, California Quality of Food: Good | | Quality of Service: Good | | | | Small friendly restaurant with great hot & sour soup, kuo-teh | | --Reviewed by Rita Taylor. Reviewed on FEB. 26, 1976 | | | | Hours: lunch, dinner Phone: 323-6550| | Entertainment: None (just the other diners) Average Price: $4.50| | Bar: Beer Only | +--------------------------------------------------------------------+
The standard SPIRES format may not be suited for displaying elements of a goal record. A user has the option of devising format definitions that provide a tailored layout of data element values in a goal record display. In addition, there are system formats designed to be used with any subfile to perform common tasks such as displaying the records in your subfile as a report, or prompting you at the terminal for information to create new records or modify existing ones. Some system formats currently available are $REPORT [See C.1.] and $PROMPT. [See D.3.] System formats can be identified by the "$" that precedes the format name. Detailed information on creating custom formats can be found in the manual "SPIRES Formats".
This section describes system facilities that allow you to determine when formats exist, specify a particular format for use, and return to the system standard format. Note that the SET, CLEAR and SHOW FORMATS commands discussed below may be privileged commands; you may not be able to use them for some subfiles. [See D.1.2.]
The format definer may write one or more custom formats for displaying the goal records of a subfile. It is also possible to specify in the file definition that a particular format be automatically chosen whenever the subfile is selected. In that case, a TYPE or DISPLAY command will automatically use the format to display the records, rather than use the standard SPIRES format.
When a format is set, certain commands ("TYPE element-list" and SET ELEMENTS) temporarily remove the user from format control, causing the record to be typed out in the standard SPIRES format. [See B.4.3.]
To see if a format has been set automatically for you, use the SHOW FORMATS command or the SHOW FORMAT SET command. [See B.4.6.2, B.4.6.5.]
The SHOW FORMATS command displays a list of available formats, and may indicate which format is currently in effect. For the most part, formats are associated with subfiles; commands used to show and set formats apply to the subfile currently selected. Thus, you cannot set a subfile format without having a subfile selected.
The following sequence illustrates the use of the SHOW FORMATS command:
-> select biblio -> show formats -Formats Set: SHORT.FORM (Subfile) -Subfile Formats: FULL.CITATION SHORT.FORM ->
The display indicates that the format SHORT.FORM is currently set and belongs to the class of formats known as SUBFILE formats. (See below for descriptions of all classes of formats.) That class of formats is then listed, and we see that there are two custom formats available for use with the BIBLIO subfile. Also, since no other format has been set since "Biblio" was selected the SHOW FORMATS display here indicates that SHORT.FORM is automatically set when the subfile is selected. [See B.4.6.1.]
You can add options to the SHOW FORMATS command to specify different classes of formats you wish to see. The syntax is:
SHOW [NON] [SUBFILE|USER|SYSTEM|ALL] FORMATS [LIKE stem]
The classes of formats are:
The LIKE option will show you a list of formats whose name begins with the LIKE "stem."
For example:
-> show formats like l -Subfile Formats: LEDGER LOG
If you do not include any options you will see all SUBFILE formats, plus the name of the format currently set.
The NON option can be used to eliminate one of the classes from the list. For example,
SHOW NON SYSTEM FORMATS
will display all the SUBFILE and USER formats. You cannot use the NON option with the ALL class.
The IN ACTIVE option can be used to direct the output of the SHOW FORMATS command into the active file. [See A.2.9.1.]
If you wish to see just the name of the currently set format, use the SHOW FORMAT SET command. [See B.4.6.4.]
The SET FORMAT command invokes the specified format for processing goal records. Though formats can be used when records are being added or updated (the SPIRES format $PROMPT, for instance), most formats are created for record display.
The syntax is:
SET FORMAT format-name
where format-name is the name of the desired format.
The following sequence illustrates how to set a format:
-> select survey -> show formats -Subfile Formats: QUESTIONNAIRE CROSSTAB -> set format questionnaire -> show formats -Formats Set: QUESTIONNAIRE (Subfile) -Subfile Formats: QUESTIONNAIRE CROSSTAB ->
A TYPE command issued at this point would presumably display the record through the QUESTIONNAIRE format. ("Presumably" is used here because the format could be defined for input only, and thus an output command like TYPE would not invoke the format.)
If you want to cancel the format currently in effect (in other words, you want to use the standard SPIRES format), issue the CLEAR FORMAT command. [See B.4.6.4.]
Some formats allow you to pass parameters to them in the SET FORMAT command. The system format $PROMPT is an example of this:
-> set format $prompt name address(3) city zip
Here the parameter "name address(3) city zip" is passed to the format for its internal use.
If the format you are setting is designed so that you pass parameters to it, the syntax of the command is:
SET FORMAT format-name [,parm|'parm'|"parm"]
System formats, recognized by the dollar sign that begins their names (e.g., $PROMPT), are always named by a single word and do not need to be separated from their parameters by special characters, as shown in the example above.
You can reset the format currently in effect by replacing the format name with an asterisk:
SET FORMAT *
This is, for instance, often used with the $PROMPT format [See D.3.1.] and the $REPORT format [See C.1.] to pass new or additional parameters to the format.
The command CLEAR FORMAT cancels use of the custom or system format currently in effect; it causes the system to return to the standard SPIRES format.
The SHOW FORMATS SET command will display the name of the currently set format and what class the format belongs to. If no format is set, the message "-No Formats Set" is displayed.
The following illustrates use of this command:
-> select biblio -> show subfile formats -Subfile Formats: FULL.CITATION SHORT.FORM -> show formats set SHORT.FORM (Subfile) -> clear format -> show formats set -No Formats Set
While searching with indexes is the most convenient means of locating records in SPIRES subfiles, sometimes a direct examination of the subfile's contents is useful. SPIRES permits direct examination of goal records and indexes. Examination of indexes involves obtaining some possible values for a particular search term, using the BROWSE command. [See B.3.6.3.] Direct examination of goal records may include the entire record, as in the case of DISPLAY, or just the goal record keys, as in BROWSE GOAL.
"Direct examination of goal records" means the ability to see information in a SPIRES subfile without first creating a search result. Some subfiles may not even have indexes.
If you have the "key" element value of a goal record, you can examine that record directly by issuing the DISPLAY command. For many subfiles, you can see goal record keys by using the BROWSE GOAL command.
The DISPLAY command, followed by the key value of an individual record, causes SPIRES to display that record at the terminal. This command accesses the actual record in the data base directly, bypassing the search process entirely.
The basic form of the command is:
DISPLAY key
where "key" is the record's key value. The key of a goal record is an element whose value is guaranteed to be unique for each record in the subfile. The key is used by SPIRES to identify records. It can be compared to the license plate number of a car, which can be used for identification because no two cars have the same plate number. [See D.1.3.1 for a detailed discussion of keys, B.5.1.2 for a method of finding sample keys.]
The DISPLAY command does not disturb the current search result. The command displays only one goal record each time it is issued. The display can be put into the active file using the IN ACTIVE prefix. [See A.2.9.1.] The DISPLAY command may be preceded with the VIA prefix if you wish to see, say, the original version of a record that has been updated that day. [See B.5.5.]
Here is an example using the DISPLAY command:
-> select blood donors -> display 13 #13 Brewster, Harvey Ph: 497-0431 (work) Last Donated: 12/21/82 Total pints donated: 9 2193 Dayton Drive ->
The BROWSE GOAL command provides you with a random or specified sample of the goal record key values in a subfile. In those files where key values may be displayed, BROWSE GOAL and DISPLAY used in combination enable you to examine sample records without searching.
The form of the command is:
BROWSE [FIRST|LAST] GOAL [key]
If none of the options is specified, then SPIRES will display a seemingly random selection of goal record keys from the subfile (unless the key element is a "slot key"; see below). The FIRST, LAST and "key" options work exactly as they do for the "BROWSE index-name" command. [See B.3.6.3.]
Only one of these options may be used per command; you cannot combine FIRST and "key", for instance.
If any option is used, after the keys are displayed you will receive the prompt, "More?" You have the same options for answering as you do with the "BROWSE index-name" command:
- to terminate: reply NO or press ATTN/BREAK - to continue in the same direction: reply YES or OK - to go backward: reply BACKWARD or "-" - to go forward: reply FORWARD or "+"
The IN ACTIVE option can be used to place the output from the BROWSE command into the active file. [See A.2.9.1.]
Here is an example of the BROWSE GOAL command:
-> select payroll -> browse goal 031-22-0238 125-71-7181 226-82-3846 242-71-7270 314-00-2213 338-51-0983 415-32-4054 443-95-4242 681-60-7580 707-01-1954 ->
This example illustrates a random sample of goal record keys. The goal record is an employee's pay record; the goal record keys are social security numbers.
Many subfiles have SPIRES create a unique number for each record when it is entered into the subfile. Each number serves as a goal record key for one record. As records are entered, each record is given a number, beginning with "1" and continuing sequentially. Records of this type are called slot records. When you browse the goal of a slot-record file, you will receive a response such as "Next slot: 255", rather than a random list of record numbers. You are thus told that the goal record key is a slot number and that the last record entered is numbered 254. Theoretically then, there should be 254 records, numbered from one to 254 (excluding records that have been deleted from the file), any of which you can examine by using the DISPLAY command with the number of your choice.
BROWSE FIRST GOAL, BROWSE LAST GOAL and "BROWSE GOAL key" work the same way for slot keys as they do for other types of keys.
There are several situations in which the BROWSE GOAL command may not show you keys of records in the subfile:
- The file owner may prevent you from issuing the BROWSE GOAL command.
- A goal record key can appear in the BROWSE GOAL list even though the record has been removed and no longer exists (see below).
In some rare cases, the BROWSE and BROWSE GOAL commands will display keys or index values that do not actually exist in the subfile when the DISPLAY or FIND commands are issued. The most likely explanation for this happening is that a record has been removed or updated since the indexes were last built. (That can affect both BROWSE and BROWSE GOAL.) A less likely, but no more harmful possibility is that a record has been removed but SPIRES must keep the index or goal record entry for internal identification purposes. Such an entry is not counted as a record, but is used by SPIRES as a file point for storing and retrieving index and goal records.
There are other possible reasons why an indexed value may not have goal records associated with it. Although it can be disconcerting to search for an indexed value seen with the BROWSE command but find no record, it is usually nothing to worry about.
Occasionally a subfile index may have a synonym facility that can give you search values with similar meanings to a particular value. If the value has been used unsuccessfully in a FIND command, the similar values can be used instead.
The SYNONYM command allows you to find alternate values or synonyms for a search term. The command specifies the name of an index, and a value for which synonyms are desired. The SYNONYM command can only be used in conjunction with indexes for which synonyms have been defined; these indexes have the notation "(SYN)" following them in the "SHOW INDEXES" display.
The form of the command is:
SYNONYM index-name search-value
where index-name refers to the name of an index containing a synonym. The search-value is the value for which a synonym is desired.
-> select music -> browse type vocal SONATA SONG SYMPHONY TONE POEM TRIO VOCAL - Forward range exhausted -More? no -> find type vocal -Zero result -> synonym type vocal CHORAL OPERA SONG ARIA DUET -> find type opera -Result: 12 ALBUMS
In this example, the search value named in the FIND command did appear in the index, but it had no pointers to goal records associated with it -- that is, the search value itself does not appear in any goal records. Thus, the "Zero result" message was displayed. However, the user, who knew that the TYPE index contained synonyms, tried the SYNONYM command and discovered that the indexed VOCAL entry had some synonyms to try.
The example does not mean that an indexed value with synonyms cannot have pointers to goal records in it. An indexed value that contains synonyms may have pointers of its own.
Occasionally you may want to narrow an existing search result by criteria that are not indexed. SPIRES provides two ways of doing such a search, each method being useful in different situations. You must take care that the most efficient method for the given circumstance is chosen. The two methods are Global FOR and the ALSO command.
Because the information that must be examined is contained only in the goal records themselves, and not in indexes, SPIRES must examine each record in sequence to determine if it meets the search criteria. For this reason, searching without indexes is called "sequential searching". Since each record must be read by the system, sequential searching is, in most cases, more time consuming and expensive than indexed searching.
The following sections should allow you to decide which method of sequential search, Global FOR or ALSO, is more expedient and less expensive in a given situation.
Sequential searching is sometimes not as flexible as index searching, since SPIRES is examining element values, and not the values in the index records. Several cautions must be observed, then, when searching sequentially.
Index and sequential searching are alike in some ways: for instance, numeric elements being searched sequentially are handled like numbers, and character data is converted to uppercase for the purposes of searching. There are some important differences, however.
Sequential searching requires that the exact value in the goal record be specified. As a consequence, personal name searching via sequential techniques is less convenient than via indexes.
A FIND command specifying the name "Maurice Merleau-Ponty" will retrieve, through indexes, records containing "M. Merleau-Ponty," but a sequential search specifying the full first name, "Maurice," will not find records in which the first name is absent, since the element being examined does not contain the complete value specified.
A FIND command searching a title-word index for the word "Computer" might locate all titles in which the word "Computer" occurs, such as "The Computer and Society". But a sequential search specifying only the word "Computer" would not locate these books, but would only locate those with the title "Computer." Truncated search is not available with sequential searching techniques, although another method is available.
To avoid the problems just described, the relational operators WORD, PREFIX, SUFFIX and STRING are quite useful when searching sequentially. [See B.3.6.5.] If no relational operator, such as STRING, is specified, then SPIRES will assume the equality (=) relational operator, which would mean that the search value must be identical to the value of the element being searched.
The ALSO command allows you to narrow an existing search result by specifying unindexed criteria; the command can never be used to expand a current search result.
The command is issued as follows:
ALSO [NOT] criteria-clause
A simple criteria-clause has the form:
element [OCCURS|LENGTH] [relational operator] value
OCCURS lets you create a criteria clause specifying the number of times an element must occur in any records in the class. LENGTH searches for records having the particular element where the element value is a particular length. Both LENGTH and OCCURS must be followed by a relational operator (which can be a blank, for the equality operator) and an integer value.
Several criteria clauses can be joined together, like a compound search request, using any of the three logical operators, AND, AND NOT, and OR.
When an ALSO command is issued, each goal record in the current search result is scanned for all criteria given in the ALSO command, and is retained in (or removed from, if ALSO NOT is specified) the result if all criteria are met. The system then reports the number of goal records in the new search result, just as it does after a FIND command.
The ALSO command can only operate on an existing search result or stack. ALSO must always be the first word in a command line -- it may not be specified after other search commands on the same line, but other search commands may be placed after it. All relational operators are valid. [See B.3.2.3.]
For example: The BACKGROUND element of the PEOPLE subfile is not indexed, but the INTEREST element is indexed. So, to find those people interested in computers who have attended a university, you could do the following:
-> select people -> find interest computer# -RESULT: 16 PERSONS -> also background word university -RESULT: 3 PERSONS
Note that the following is incorrect because ALSO is not the first word used in the command line:
-> find interest computer# also background having university -Zero result ->
Here SPIRES thinks that the "also" part of the command is part of the search value, since it is not looking for ALSO in the FIND command.
Except for OCCURS and LENGTH comparisons, when you supply a value in the ALSO command, SPIRES may apply the element's "input processing rules" to the input value in order to compare it to the values stored in the records. For example, dates are usually stored in a special form in records, so the value in the ALSO command must also be converted into the same form. On the other hand, the processing rules may simply verify that your input value is already in the proper form. [See D.1.3 for more information on processing rules.] However, some processing rules that would be applied to the value if it were being added as part of a new record are not applied to the value in an ALSO command. These are the same rules that are ignored during WHERE clause processing, as described in the SPIRES manual "Global FOR", section 4.1. Furthermore, dynamic elements have their input values converted according to the TYPE of the dynamic element, not by any declared INPROC rules.
The "FOR class" command heads an entire array of commands (called Global FOR commands) for locating and manipulating goal records sequentially. Only the commands most useful for examining goal records via unindexed information will be covered here. Other sections of this manual will cover other Global FOR commands. [See D.5, D.7.] The SPIRES manual "Sequential Record Processing in SPIRES: Global FOR" is the best reference for more information about Global FOR.
The syntax of this particular Global FOR command can be expressed as:
FOR class [WHERE [NOT] criteria-clause]
where class is defined to be:
A criteria-clause can be defined as:
element [OCCURS|LENGTH] relational-operator value
OCCURS lets you create a criteria clause specifying the number of times an element must occur in any records in the class. LENGTH searches for records having the particular element where the element value is a particular length. Both LENGTH and OCCURS must be followed by a relational operator (which can be a blank, for the equality operator) and an integer value.
Several criteria clauses can be joined together, like a compound search request, using any of the three logical operators.
After a FOR command has been issued, and its syntax and semantics have been accepted by the system, a "+>" prompt is returned to you, instead of the usual "->" prompt. This is to remind you that Global FOR mode is in effect, and that the syntax of several commands has changed, as explained in detail below.
To leave Global FOR mode and return to normal SPIRES processing, issue the command ENDFOR, or simply ENDF. The message "End of Global FOR" will be sent to the terminal, followed by a "->" prompt on the next line.
A simple example shows the change of the prompt when in Global FOR mode, and illustrates the use of ENDFOR to return from Global FOR processing:
-> for subfile +> <--- Other Global FOR commands +> endfor -End of Global FOR ->
Unlike the ALSO command, the "FOR class" command and other Global FOR commands will not affect any search result you may have, though they may use it (the FOR RESULT command, for example). [See B.5.3.2.]
Outside Global FOR when you wish to look at a record for which you know the key value, you use the DISPLAY command followed by that key value. [See B.5.1.1.] To look at records under Global FOR, there is another, more powerful form of the DISPLAY command, which does not require you to specify (or even know) the key values of the records you want to examine. Since you have already issued a "FOR class" command, SPIRES already has the means of identifying the records you want to see, so there is no need for you to specify the key values.
The syntax of the DISPLAY command in Global FOR is:
DISPLAY [FIRST|*|NEXT|n|LAST|REST|ALL]
DISPLAY typed alone will show you each record one at a time. DISPLAY and DISPLAY NEXT are equivalent. DISPLAY FIRST and DISPLAY LAST will display the first and last records in the group specified by the preceding "FOR class WHERE" command. "DISPLAY *" will show you the most recently displayed record again.
To see several records at once, use the "n" option. "DISPLAY n", where "n" is an integer, will show you the next "n" records. You can see all the remaining records by typing DISPLAY REST at any time. DISPLAY ALL will show you all the records at one time.
The IN ACTIVE prefix is very useful with the DISPLAY command; the displayed records are placed in the active file. [See A.2.9.1.]
The DISPLAY command will show a record to you in its normal output format, unless a SET ELEMENTS command has been issued. (See the third example below.) You can see one, several or all of the records at a time.
The following example shows how two commands are issued to effect Global FOR processing:
-> for subfile
+> display all
<--- All goal records are displayed
+> endfor
-End of global FOR
->
Just as it takes a FIND and TYPE command to search and display records in an index search, it takes a "FOR class" and DISPLAY command to search and display records sequentially. But the "FOR class" command itself does very little "work"; it is the subsequent command, such as DISPLAY, that causes examination and display of goal records.
If an "End of Global FOR" response follows a DISPLAY command when in Global FOR, it means that no further records in the class specified meet the criteria of the WHERE clause. If there were no records in the class specified, such as FOR RESULT when no search result exists, an "End of Global FOR" condition occurs as soon as the system attempts to examine the class of records -- that is, as soon as a DISPLAY command is given. When an "End of Global FOR" condition occurs, the system automatically returns you to normal SPIRES searching and gives a "->" prompt to indicate this.
If you want to produce a listing of all records in the RESTAURANT subfile, it might be done as follows:
-> select restaurant -> for subfile +> in active clear display all +> endfor -End of global FOR ->
If only the NAME and STATE elements of restaurants out of California were desired in the report, the following could be done:
-> select restaurant -> set elements name state -> for subfile where not state prefix ca +> in active clear display all +> endfor -End of global FOR ->
A more attractive report could be created by combining this technique with the $REPORT or $PROMPT system format. [See C.1, D.3.]
Here is another example, using other DISPLAY command options:
-> for subfile
+> display
<--- the first record is displayed
+> display next
<--- the second record is displayed
+> display 3
<--- the third, fourth and fifth records are displayed
+> in active display *
<--- the fifth record is put in the active file
+> display
<--- the sixth record is displayed
+> display all
<--- the first through last records are displayed
+>
The FOR TREE command tells SPIRES to sequentially search records in the subfile without looking at records in the deferred queue. Any records that have been added or updated since the file was last processed will not be examined. Similarly, if any records have been removed since the file was last processed, they will be examined, because they will not actually be removed from the tree until the next time the file is processed. [See B.3.1.2.]
Generally, because the tree includes all records added, updated or removed before the indexes were last rebuilt (usually the previous night), the FOR TREE command is usually not far "out of synch" from FOR SUBFILE. [See B.5.3.5.] FOR TREE can be cheaper to use than FOR SUBFILE, especially for very large subfiles, since SPIRES does not have to check whether each record has been updated or removed since the indexes were rebuilt.
If you wanted all individuals in a subfile whose office addresses were Polya 110 or Polya 162, and were not concerned with changes of office address during the day, the appropriate Global FOR search might look like this:
-> select people
-> for tree where address string polya 110 or string polya 162
+> display
<--- First record is displayed
+> display
<--- Second record is displayed
+> display rest
<--- Third/last records are displayed
+> display all
<--- All records are displayed again
+> endfor
-End of global FOR
->
If you suspected that some addresses might be entered as "162 Polya" or "Polya Hall 162" instead of the simple "Polya 162," the FOR TREE command might be changed to the following:
-> for tree where office-address ...
... string polya and (string 162 or string 110)
FOR SUBFILE is used when you must guarantee that record updates during the day are taken into account when records are examined and displayed; that is, you want the most recent information in each goal record. SPIRES examines both the tree and the deferred queue for records, providing you with the most up-to-date version of each record in the subfile.
For example, you may want to find all the people in the "People" subfile who have offices in Polya Hall. Since "office-address" is unindexed, we must use sequential search techniques. And since no preceding search result exists, FOR SUBFILE or FOR TREE would be useful. The following sequence illustrates the use of FOR SUBFILE:
-> select people
-> for subfile where office-address string polya
+> display all
<--- All records meeting criteria are displayed
+> endfor
-End of global FOR
->
In a small subfile (say, less than 200 records), sequentially searching the entire set of goal records (using FOR TREE) and perhaps examining the deferred queue for updated records in addition (using FOR SUBFILE) will probably take only a couple of seconds of processing. But in a larger subfile, examining records under FOR TREE or FOR SUBFILE may take many seconds of processing. In a large subfile, containing perhaps tens or hundreds of thousands of records, these commands should only be issued if absolutely necessary, and then they might best be done in batch SPIRES using the OFFLINE command. [See E.3.2.]
In large files especially, a subset of records to be searched sequentially should first be obtained by using the indexed search commands such as FIND, AND, AND NOT, and OR. The FOR RESULT command then can be used to examine that subset sequentially. Only the records in the result will be examined sequentially.
You might want to narrow a search of the "interest" index in the PEOPLE subfile to those who have noted that they have a Ph.D. in the BACKGROUND element. Since BACKGROUND is not indexed, a FOR RESULT sequential search would be most efficient. For example:
-> select people
-> find interest computer#
-Result: 21 PERSONS
-> for result where background with phd
+> display all
<--- All records meeting criteria are displayed
+> for result where background with ma or with ba
+> in active clear display all
<--- All records meeting criteria are
placed in the active file
+> endfor
-End of Global FOR
->
The second FOR RESULT command illustrates that Global FOR commands can follow each other, and no ENDFOR need be issued to end one before beginning another. Global FOR commands do not "nest" however: the same twenty-one records are examined by both FOR RESULT commands
Stacks can also be processed under Global FOR, using the FOR STACK command, just as results are processed by the FOR RESULT command. (Remember that stacks are often search results that have been sequenced.) Both commands are used similarly. [See B.5.4.1 for more information on stacks.]
It is occasionally necessary to examine groups of records that have no single element or index values in common. Using the STACK and EXTRACT commands, you can create groups containing the records you want. You can then use the SEQUENCE command to arrange the records in a particular order, or you can process them with other SPIRES commands, such as the ALSO comand.
The STACK command allows you to build a stack of records to examine all at once, if desired, even though they may have no common criteria. This facility is particularly useful if you need to look at specific records and you do not want to construct a search. If you cannot arrange records in an order you want using the SEQUENCE command, you can use the STACK command to arrange them individually. All that is required is a list of keys to the records you want to examine.
The syntax of the STACK command is:
STACK record-key-value [CLEAR]
The CLEAR option eliminates a previous stack; if a stack already exists, and you don't use this option, the new stack will be combined with the old one.
Only one record-key-value may be included in a single STACK command. A stack is built cumulatively, record by record, with one record added for each command (unless you are in Global FOR processing [See D.4.5]). Stacks are constructed from the top down -- that is, the first record stacked remains the first record in the stack, the second record stacked becomes the second record in the stack, and so forth.
The UNSTACK command lets you remove records from an existing stack. Like the STACK command, you specify the keys of records to be removed from the stack.
The UNSTACKed records can be located anywhere within the stack. If there is more than record with the same key in the stack, all occurrences of that record are removed.
The syntax of the UNSTACK command is:
UNSTACK record-key-value
An example using the STACK and UNSTACK commands:
-> select masterlist -> stack 450 -Stack: 1 RECORDS -> stack 792 -Stack: 2 RECORDS -> stack 216 -Stack: 3 RECORDS -> unstack 792 -Stack: 2 RECORDS
and so forth.
To see how many records are in the current stack, issue the command
SHOW STACK
The IN ACTIVE option can be used to place the output into your active file. [See A.2.9.1.]
The resulting stack can be altered by the SEQUENCE or ALSO commands or examined with the TYPE or SCAN commands. [See B.5.4.4.] Note that if you use the ALSO command and you reduce the stack to zero, no "automatic backup" will occur; if this is a possibility, you might want to store the stack first (see below). The TYPE command will display records in a search result or in a stack; if both a stack and a result exist when the TYPE command is issued, the latest one created is displayed. You can also examine the records in the stack by using the FOR STACK command with other Global FOR processing. [See B.5.3.7.]
Remember that a search result (or another stack) processed with the SEQUENCE command becomes a stack, which means that it too can be processed with the commands mentioned above. [See B.4.5.]
Terminology note: Although SPIRES users (and this document) refer to a stack of records, a stack really consists only of record keys, or pointers, through which SPIRES can access records. The significance of this point is that when you issue the STACK command, SPIRES does not verify that a record with that key exists, but verifies that the key is a valid key (i.e., a record with that key could exist). If you issued the command STACK GA.SPI when the keys of the subfile's records must be numeric, SPIRES would give you an error message.
The CLEAR STACK command eliminates any previous stack you have built. You can issue this command if you want to start a new stack when a stack already exists.
A new FIND command will also clear an existing stack.
The SCAN command is particularly useful with the STACK command. The STACK command is also valuable in Global FOR processing. These uses will be discussed in later sections. [See B.5.4.4, D.7.5.]
Technical note: If you select a subfile and then stack records before issuing any FIND command, SPIRES will not know the "name" of the records but will call them RECORDS in the "stack message":
-> select blood donors -> stack 1 -Stack: 1 RECORD -> find blood.type = ab- -Result: 25 DONORS -> sequence name -Stack: 25 DONORS -> clear stack -> stack 1 -Stack: 1 DONOR ->
SPIRES does not know that records in the stack are "donors" until after the first FIND command.
You may need to use the same stack in a subfile more than once. If it is a stack containing many records, having to recreate it record by record would be very inconvenient. The STORE STACK.name command can be used to save the stack. This command creates a Unix file to save the record key values of the stacked records. Thus, it is similar to the STORE RESULT.name command which saves search results, except that later you use a form of the RESTORE command (instead of a form of the FIND command) to restore the stack. You can also store a stack temporarily; the stack will be discarded when you exit the session. [See B.3.8, B.3.8.1.]
The syntax of the "STORE STACK.name" command is simply:
STORE STACK.name
where "name" is the name you wish to give the stack. (Optionally, the period after "STACK" can be replaced with one or more blanks.) The name may be any valid Unix file name from 1 to 27 characters long. To store a temporary stack, type
STORE TEMPORARY STACK.name or STORE TSTACK.name
"TEMPORARY" can be abbreviated to one character.
The STORE STACK.name command, like its search result counterpart, stores the record key values, not the actual records themselves. Thus, if you use a saved stack at a later time, it will access the latest versions of the records, not the records as they were at the time you saved the stack.
To use a saved stack, issue the command "RESTORE STACK.name". Issue "RESTORE TEMPORARY STACK.name" to use a temporary stack. These commands recreate the stored stack for your use. When you no longer need the stored stack, you should issue the command "ERASE STACK.name" (for non-temporary stacks). (You can append the option "QUIET" to the ERASE command to suppress the system response if the command is successful.) To get a list of stored stacks on your account, issue the command SHOW STACK NAMES. This command will display permanently stored stacks. In the list, each stack name will be displayed to you, including the date it was created (CR) and the date it was last used (DA). The IN ACTIVE prefix can be used to direct the listing to the active file. To get a list of temporary stored stacks, issue SHOW TEMPORARY STACK NAMES or SHOW TSTACK NAMES. The Unix device id is displayed.
To see some basic information about a particular stored stack, use the SHOW STACK.name command:
SHOW STACK.name
where "STACK.name" is the name of the stack as stored in the Unix file system.
SHOW STACK.name will show you the date the stack was created and what subfile it is connected to. This command is particularly useful when you have issued a SHOW STACK NAMES command and you want to know more about the stacks listed there.
-> show stack.views -'GQ.RLG.STACK.VIEWS' created 07/22/93 SELECT FILEDEF
It is possible to restore a stack stored under someone else's account, if you have appropriate privileges to that Unix file. The full form of the command is
RESTORE [ORV.gg.uuu.]STACK.name
where "gg.uuu" is the account under which the stack is stored.
Here is a sample session using these commands:
-> select restaurant -> stack 10 -Stack: 1 RECORD -> stack 23 -Stack: 2 RECORDS -> store stack.food1 -'STACK.FOOD1' put in Unix file system -> clear stack -> stack 14 -Stack: 1 RECORD -> stack 17 -Stack: 2 RECORDS -> store temp stack.food2 -'TSTACK.FOOD2' put in Unix file system -> show stack names Unix FILE SYSTEM STACK.FOOD1 -- CR: 07/28/78 LA: 07/28/78 -> show temp stack names Temporary Stack Names: STACK.FOOD2 (12) -> show stack -Stack: 2 RECORDS -> clear stack -> show stack -NO STACK EXISTS -> restore stack.food1 -Stack: 2 RECORDS -> in active clear type -> erase stack.food1 STACK.FOOD1 ERASED IN Unix FILE SYSTEM
The two records from the "Food1" stack are now listed in the active file, while the Unix file has the "Food2" stack stored.
A temporary stored stack is actually an attached Unix device. If you need to monitor the number of attached devices, you will also need to factor in temporary stored stacks and results.
The GENERATE RESULT command converts an existing stack into a search result. Stacks cannot be refined through index searching. Once a stack is converted to a search result, however, this result can then be used as the basis of further index searching, that is, with the AND, NOT, and OR operators.
A stack must exist or be restored before the command is successful. When the GENERATE RESULT command is issued, any current result is cleared (as if you had done a CLEAR RESULT) and the stack is used to build a result. For large stacks, it may be more efficient to use SEQUENCE (D) to place the keys or locators into descending sort order before issuing the GENERATE RESULT command. [See B.4.5.]
The SHOW SEARCH command will show the GENERATE RESULT command as what created the result.
In the following example, a stack is converted to a result that is then used for further index searching:
-> restore stack.books1 -Stack: 208 BOOKS -> generate result -Result: 208 BOOKS -> or author white -Result: 256 BOOKS -> show search generate result OR author white -> show stack -No stack exists
The EXTRACT command builds a stack of records that are in the goal record tree, using either all of the tree or some sequential, contiguous subset of it. The stack that is built can then be altered by the SEQUENCE or ALSO commands [See B.4.5, B.5.3.2.] or can be examined with the TYPE command. [See B.4.2.1.]
The syntax of the EXTRACT command is:
EXTRACT [SKIP=x] [LIMIT=y] [START key-value]
The "=" is optional and may be replaced by a blank.
The SKIP option specifies the number of records to skip from the starting point (which may be determined by a START value). SKIP is assumed to be zero if it is not given.
The LIMIT option specifies the number of records that are to be included in the resulting stack. No limit is imposed if the LIMIT option is not specified.
The START option specifies a key-value in the subfile. SPIRES will begin the EXTRACT command at the first record with a matching key-value, or the first record beyond the key-value specified if no exact match is found. If the START option is included, it must be the last option on the command. If START is not specified, then EXTRACT begins with the first goal record. Note that the case (UPPER or lower) of a character string specified here may be significant, depending on the file definition.
The EXTRACT command is particularly useful when the goal records are to be ordered using the SEQUENCE command. The EXTRACT command works from the goal record tree, meaning that it will not retrieve added records, since they are not in the goal record tree, but will retrieve records that have been removed since the file was last processed, since they are in the goal record tree. However, other commands that affect the stack, such as TYPE or SEQUENCE, will examine the deferred queue as usual, thus taking updated and removed records into account.
Here are some examples of the EXTRACT command:
-> extract <-- All records in the subfile are placed on the stack.
-> extract limit=5 <-- Only the first five records are stacked.
-> extract skip=5 start box
<-- All records starting with the fifth record after
"box" are placed on the stack.
The SCAN command allows you to place all or part of a subfile's goal records in your active file. Using appropriate options, you can specify how many records are to be output or where the records to be output are to be found.
This command has the following syntax:
SCAN [TREE|SUBFILE|DEFQ|ADDS|UPDATES|RESULT|STACK|GOAL] [BACKWARDS]
[LIMIT x] [SKIP y] [CONTINUE|CLEAR] [CLEAN] [criteria]
The basic SCAN command will put all the goal records from the TREE into your active file.
The following example will put all the records currently in the RESTAURANT subfile in the active file:
-> select restaurant -> scan subfile
Options such as CONTINUE and CLEAR specify whether the records are to be appended to the active file (CONTINUE) or to replace the current active file. The CLEAN option specifies that the "****" and ";" record delimiters are not to be put into the active file. [See A.2.9.1.]
The LIMIT and SKIP options can be used to control the starting and ending point of a scan, or the number of records scanned, by specifying the number of records, "n".
The BACKWARDS option, available only on a SCAN TREE or SCAN GOAL command, will place the records in the active file beginning with the last and moving toward the first. This option is not allowed if the subfile has slot keys. [See D.1.3.1.]
The TREE, SUBFILE, GOAL, DEFQ, ADDS, UPDATES, RESULT, and STACK options specify which "part" of the file is to be examined by the SCAN command. If no area is specified, TREE is assumed. The areas have the same definition as those in Global FOR. [See B.5.3.3, D.7.] "Criteria" may be specified to determine which records are placed in the active file. Although other options can be specified in any order, any criteria specified must follow all other options, and may optionally be separated from the options by a " , " (a comma surrounded by blanks). Criteria are specified just as in a WHERE clause in Global FOR. [See B.5.3.3.] For example:
SCAN DEFQ ENTRY-DATE FROM 2/84 TO 4/84 SCAN RESULT COST OCCURS > 0 AND DATE-ADDED AFTER 1/84 SCAN LIMIT 7 , LIMIT FROM 3 TO 5
In the last example, the " , " delimiter is necessary to prevent the LIMIT option ("LIMIT 7") from being confused with the LIMIT element (whose values will be from 3 to 5 for the records that are scanned and placed in the active file).
By default, when you issue the TYPE command to examine the records in a search result, you see the latest copy of each record. That is, if an updated version of a record is in the deferred queue, then it is that version you will see. The VIA TREE prefix can be added to tell SPIRES to get the copy of each record from the tree, rather than checking the deferred queue.
The VIA prefix may be added to several commands, and several different classes of records besides TREE can be specified. In each case, the VIA prefix tells SPIRES to carry out the named command, but only if the specified records are in the named class. In addition, the copy of each record that is in the named class is used by the command.
The syntax of the VIA prefix is:
VIA [TREE|SUBFILE|DEFQ|ADDS|UPDATES] command
where "command" is one of the following commands:
TYPE DISPLAY SEQUENCE STACK TRANSFER REFERENCE
The first four commands have already been discussed. [See B.4.2.1, B.5.1.1, B.4.5, B.5.4.1.] The TRANSFER command will be discussed later. [See D.2.5.] The REFERENCE command is discussed in the SPIRES manual "Technical Notes".
The classes available are a subset of the Global FOR classes, of which TREE and SUBFILE were discussed earlier. [See B.5.3.5, B.5.3.6.] The others will be discussed in the chapter on monitoring subfile updating activity using Global FOR. [See D.7.]
Here is an example showing one way in which the VIA prefix might be used. Suppose you want to see the records in a search result that have been updated today:
-> find blood.type = A+ -RESULT: 254 DONORS -> via updates type
Of the 254 records in the search result, only those with copies marked as "updates" in the deferred queue will be displayed.
The VIA TREE prefix is useful with the TYPE command when you want to see the version of each search-result goal record that is represented in the indexes. (Remember that the information in updated records does not cause the indexes to change until the file is processed, usually overnight.) [See B.5.3.5.] You might also use it with the DISPLAY command to see the original version of a record whose key you know: "VIA TREE DISPLAY GQ.JNK", for example.
If you use the SEQUENCE command, remember that only records appearing in the class named by the VIA prefix will remain in the created stack:
-> find blood.type = A+ -RESULT = 254 DONORS -> via updates sequence name -STACK: 5 DONORS ->
The VIA prefix is also very useful when you are processing records in Global FOR mode. In effect it circumvents Global FOR processing:
-> for subfile +> display 5 <-- the first 5 records in the subfile are displayed +> via subfile display gq.jnk <-- the record whose key is GQ.JNK is displayed +>
Without losing your place in Global FOR, you were able to examine the latest copy of a record by using its key to access it. (Or you could have typed VIA TREE DISPLAY GQ.JNK and seen the tree version of the record.) At this point, you could continue examining records in Global FOR.
Adding the VIA prefix to the STACK command works similarly; in fact, Global FOR is the only situation where VIA is allowed on the STACK command. It lets you add a record to the current stack based on its key value without losing your place in Global FOR. [See D.7.5.]
The VIA and the IN ACTIVE prefixes may together be specified on the TYPE or DISPLAY commands; the order in which they appear is inconsequential.
As a SPIRES user you may often need to create quick, informative reports -- or formatted displays of records -- from the subfile you have selected. A report format not only organizes the display of your SPIRES records, but can also convey information, such as subtotals and summaries, that would have been hidden in an unformatted display:
-------------------------------------------------------------------
+----------------------+ +----------------------------+
| Records Displayed in | | The Same Records Displayed |
|Standard SPIRES Format| | in a Report Format |
+----------------------+ +----------------------------+
| |
| |
v v
Employee Name Hours Worked
------------------ ------------
NAME = Cecile Frame;
HOURS = 40; Sally Belle 80
NAME = Bel Blum; Bel Blum 60
HOURS = 60;
Mack Blum 10
NAME = Mack Blum; 20
HOURS = 10;
HOURS = 20; Cecile Frame 40
NAME = Sally Belle; **SUM 210
HOURS = 80; **MIN 10
**MAX 80
-------------------------------------------------------------------
A well-designed report format emphasizes information about your records that even a casual reader can grasp immediately.
To make "reporting" on a subfile more convenient SPIRES offers two report-writing tools that provide the power and flexibility of user-compiled formats but are easier to use. These tools are:
- $REPORT, a system format that allows you to customize a format with a series of subcommands; and
- Report Definer, a utility based on $REPORT (and simpler to use), that lets you create a customized report format by filling in screens with your report specifications.
You can use either Report Definer or $REPORT to create a report from any SPIRES subfile you have selected, and the SPIRES concepts treated so far in this manual should provide you with more than enough background for getting started.
Both Report Definer and $REPORT let you:
- choose what elements you would like displayed and format the display in columns laid horizontally across the page.
- provide headings for your columns, furnish the report with a title, and group records in your search result to emphasize important information.
- calculate subtotals and summaries (for instance, the number of times a particular element occurs).
- specify the page layout you want.
Report Definer offers you substantial online coaching and help while you define your report, whereas $REPORT expects that you already have learned the special $REPORT command syntax covered later in these sections. So Report Definer is much easier to use; on the other hand it provides less reporting power than $REPORT. You can use the two reporting tools together by first creating a report format with Report Definer, then enhancing that format with $REPORT subcommands.
Part C of this manual is devoted entirely to the subject of report writing in SPIRES, beginning with Report Definer and moving on to $REPORT. The early sections of Part C can be read quickly, but the later sections grow more and more complex as they describe $REPORT in exhaustive detail. For practical purposes, your best strategy might be to read the early sections of Part C for an overview of Report Definer and $REPORT, then use the later sections only as a reference guide for when you need the particular feature they cover.
Here are the steps to take for entering Report Definer:
- 1) SET TERMINAL "terminal-type" to tell the system what type of terminal you are using. (HELP TERMINAL TYPE for more information about the SET TERMINAL command.)
- 2) Issue the SPIRES command.
- 3) SELECT a subfile and, if you wish, perform a search or use Global FOR to assemble the set of records that will make up the contents of your report. [See B.2.3, B.5.]
- 4) Issue the command ENTER REPORT DEFINER.
For example:
----------------------------------------------------------------
(STEP 1) > set terminal vt100
(STEP 2) > spires
-Welcome to SPIRES ... if in trouble, try HELP
(STEP 3) -> select restaurant
-> find city menlo park or city palo alto
-Result: 85 RESTAURANTS \ +--------------------+
-> sequence city name \ | A search can also |
-Stack: 85 RESTAURANTS \ \|be performed AFTER |
-> type city name price \ |defining a report. |
NAME = Dutch Goose; \ +--------------------+
CITY = Menlo Park; \
PRICE-AVERAGE = $1.50; \
+----------------------------------+
NAME = El Rincon Tarasco; |Sequencing is important if you |
CITY = Menlo Park; |plan to group your records [C.1.5]|
PRICE-AVERAGE = $7.00; +----------------------------------+
NAME = Flea Street;
CITY = ... <------(ATTN/BREAK key pressed)
(STEP 4) -> enter report definer
-----------------------------------------------------------------
Notes: 1) Your terminal must be able to support full-screen display for you to use Report Definer; 2) the SET TERMINAL command is not necessary on an IBM 3270-style terminal.
The command ENTER REPORT DEFINER places you in a full-screen environment with a series of mostly blank screens for you to fill in. Each screen is like a page in a form; the completed form defines your report. To move around each screen use the cursor keys or tab key, filling in appropriate blanks. To leave a screen, temporarily or permanently, press the PF ("Program Function") keys listed next to each choice on the banner line at the bottom of the screen, or type your choice on this banner line to the right of the prompt marked "Your choice:".
Here are the five choices or commands that you can issue while you are on the report defining screens:
- HELP (PF1) shows you more information about the current screen of input and then returns you to it;
- CONTINUE (PF2) checks your input for errors and then usually takes you to the next screen;
- FINISH (PF3) creates a report format based on any specifications you have input and takes you from the input screens into command SPIRES;
- SHOWELEM (PF4 -- 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 (PF4 -- available on all input screens except the first one) will move you to the previous screen, where you can modify your input.
Note that pressing a PF key automatically issues the command associated with it so that you never have to type the command out -- pressing PF1 accomplishes exactly the same thing as typing the word "HELP" in the appropriate place. If the PF keys do not work the way you expect them to, try pressing the escape key and a numeral instead (e.g., <escape> 3 instead of PF3).
Assuming you simply CONTINUE from screen to screen, here is the order in which you will see the screens and the basic task that each one accomplishes:
- Naming your elements (first screen) [See C.1.3.]
- Summarizing the element values (second screen) [See C.1.4.]
- Organizing the elements into groups (third screen) [See C.1.5.]
- Specifying element layout and headings (fourth screen) [See C.1.6.]
- Specifying page layout (fifth screen) [See C.1.7.]
On the first screen you tell Report Definer which elements your report will contain. Name the elements in the order that you want them displayed (from left to right) in the final report. If your report will be "grouped by" one or more elements, name that element (or elements) first on this screen. [See C.1.5 for further discussion of "groups".]
The first screen includes a display like this:
+------------------------------+
|Fill these blanks in with your|
| element names |
+------------------------------+
| | \ \
+-------|---------|--------\----------\------------------------------------+
| | | \ \ |
| 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) |
| \ \ | | |
+--------------------------\----------\-----------|-----------|------------+
\ \ | |
\ \ | |
+------------------------------------------------+
|When you wish to leave the screen type one |
|of these commands to the right of "Your choice:"|
|or use the PF key listed next to it. |
+------------------------------------------------+
For instance, to make a RESTAURANT report you could type in the element names CITY, NAME, FOOD-QUALITY and PRICE, with up to ten elements total:
+------------------------------------------------------------------+ | ELEMENT 1 ELEMENT 2 ELEMENT 3 ELEMENT 4 ELEMENT 5 | | | | CITY_______ NAME_______ FOOD-QUALITY_ PRICE________ ____________ | | | | ELEMENT 6 ELEMENT 7 ELEMENT 8 ELEMENT 9 ELEMENT 10 | | ___________ ___________ _____________ _____________ ____________ | | | +------------------------------------------------------------------+
Specifying elements on this screen is enough to produce a fully formatted report. Here is roughly how the report would look using the sample search from C.1.1:
+--------------------------------------------------------------------------+
May 29, 1984 From: RESTAURANT Page 1
City Restaurant Name Food Average
Quality Price
-------------------- ------------------------- ---------- -------
Menlo Park Dutch Goose Good $ 1.50
Menlo Park El Rincon Tarasco Excellent $ 7.00
Menlo Park Flea Street Excellent $ 6.00
Menlo Park Flea Street Cafe Good $ 8.00
: : : :
: : : :
Palo Alto Acapulco Excellent $ 5.00
Palo Alto Alouette Excellent $ 12.00
: : : :
: : : :
(Report continues until all restaurants from both cities are listed.)
+--------------------------------------------------------------------------+
If your subfile's file definition has specified "element information" values for column widths and headings, Report Definer uses those values for your report, as it has done for Restaurant above. [See C.13 of "SPIRES File Definition" for more information on element information packets.] Otherwise it chooses reasonable "default" values of its own for formatting. For instance, the Report Definer default for column width is 10 spaces per element and the default for heading is the element name you type on the first screen. These default values may suit your report, but then again they may not! To improve on them, use the CONTINUE option to move to the next screen.
The next screen lists the elements you have chosen and offers you the chance to have their values summarized.
For example, to make our report from the Restaurant subfile [See C.1.3.] more informative, we could have Report Definer generate some summaries by typing an "X" in the appropriate places on the screen:
+--------------------------+ +-----------------------+
|Your element names appear | | Type "X's" here for |
| here automatically. | | the summaries you want|
+--------------------------+ +-----------------------+
| / | |
+----|-----------------------------------/----|-------|---------+
| | / | | |
| ELEMENT COUNT AVERAGE SUM MINIMUM MAXIMUM |
| -|------------- ------- ----- ----/-- --- |------ |------ |
| CITY___________ / | | |
| NAME___________ / | | |
| FOOD-QUALITY___ / | | |
| PRICE__________ X - X X |
| |
+---------------------------------------------------------------+
Since we typed the "X's" in the same row as the PRICE element, here Report Definer would automatically compute the average price, minimum price and maximum price for all of the restaurants in the report, as well as for each group of restaurants if any groups are defined. [See C.1.5.]
As you can see, there are five different ways to summarize elements with numeric values in Report Definer:
- COUNT summarizes the number of occurrences of the element
- AVERAGE provides an average of the values for the element
(and would be equal to SUM divided by COUNT)
- SUM adds up or sums all of the element's values
- MINIMUM displays the element's minimum value
- MAXIMUM displays the element's maximum value
The COUNT function may be used on elements with textual values but the other four functions only apply to numeric elements.
In addition to the five functions named above, $REPORT (but not Report Definer) offers a sixth function, STD, for measuring the "standard deviation". [See C.6.5.]
The summary information you request appears at the end of your report. If you choose also to organize or group your records according to one or more elements, the summaries will also appear as subtotals below each group. (See the following section for an explanation of organized or grouped records in Report Definer.) Report Definer also offers a way of constructing a report to display summaries only -- that is, a report that displays sums and averages for element values without displaying any of the individual values themselves. [See C.1.7.]
The next screen lets you format your report into grouped displays of records instead of one large line-by-line display. For instance, using the Restaurant report begun earlier [See C.1.3, C.1.4.] we can group our records by the element CITY (remember we sequenced the records by CITY before entering Report Definer). The report will now be formatted into two groups, one of Menlo Park restaurants and one of Palo Alto restaurants. The summaries we asked for earlier will be computed for each city group as well as for the report as a whole. With one simple "X" we have just about doubled the amount of useful information the report will provide:
+--------------------------+
|Type "X's" next to any |
|element that you want to |
|group your records around.| +------------------------------+
+--------------------------+ |Summaries you requested before|
\ +-------------------------+ |appear here automatically. |
\ |Your element names appear| +------------------------------+
\ | here automatically. | |
\ +-------------------------+ |
\ | |
\ +---------------|----------------------------|------------------+
\| Organization | --Report Definer-- | 05/31/84 15:44 |
\(SUB-TOTAL) | | |
|\GROUP BY ELEMENT NEWPAGE COUNT AVERAGE SUM (etc.) |
| \__________ __|___________ _______ ______ |______ ___ : |
| \ | | |
| X CITY | : |
| NAME | |
| FOOD-QUALITY | : |
| PRICE X : |
| |
| |
+---------------------------------------------------------------+
Grouping records makes your report more readable, emphasizing important relations between record elements. It also provides you with the means of compiling statistics for subsets of your records.
Each group is displayed in a single cluster or paragraph and the element heading the group has a single value within the group (and is displayed once per group, as well as at the top of each new page). Each time that element's value changes, the display skips a line and begins a new group of records. So if you organize a report by an element named DEPT and there are two different values for DEPT in your set of records (for instance: ACCT and DVPT), your report will have two groups total:
(Ungrouped) (Grouped) (Grouped w/summary)
Dept Name Dept Name Dept Name
------- ---------- ------- ---------- ------- ----------
ACCT Chisholm
ACCT Galante ACCT Chisholm ACCT Chisholm
DVPT Arness Galante Galante
DVPT Scotto
DVPT Arness *COU 2
Scotto
DVPT Arness
Scotto
*COU 2
**COU 4
The three displays all contain the same records, but the two grouped displays convey more information than the ungrouped display; this advantage would show up even more clearly in a longer or more complicated report. However, note that grouping only functions properly for records that are sequenced by the element leading the group.
NEWPAGE is quite straightforward. If you place an "X" by an element under NEWPAGE, the report will begin a new page every time the element's value changes.
On the next screen you specify the width each of your elements will take and the name of the heading that will appear above each element. For instance, an element named "DEPT" might be given a width of 10 columns and the heading "Department".
- WIDTH is the number of spaces allotted for an element on each line of the report.
- HEADING is the text that will identify the element and its values on each page of the report.
The number specified in WIDTH should be large enough to accommodate the width of your HEADING as well as the width of the element values beneath the heading.
In many situations you can simply accept the "default" values that appear automatically on the screen, particularly if the file owner has provided element information in his or her file definition. [See C.4.6.] The Restaurant subfile, as you see below, does have this "elem-info", which makes reporting on the file considerably easier.
Here is how we might lay out the report on Restaurant that we have been working on:
+------------------------------------------------+ | | | ELEMENT WIDTH HEADING | | --------------- ----- -------------------------| | CITY 20 City | |The double slashes | NAME 25 Restaurant Name | | ( // ) | FOOD-QUALITY 10 Food//Quality | <-----|stack the heading | PRICE-AVERAGE 10 Average//Price | |so it will fit | | |within the width +------------------------------------------------+ |allotted.
The resulting display will look something like this:
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + | Food Average | City Restaurant Name Quality Price |-------------------- ------------------------ ---------- ---------- | (20 columns........) (25 columns.............) (10 cols..) (10 cols.) | | + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
The heading and values for "Average Price" would be adjusted to the rightmost column of their fields because an edit mask has been applied to that element's values in the file definition for the Restaurant subfile. EXPLAIN EDIT MASKS for more information.
On the next screen you can change the page layout of your report: for instance, you can alter the number of lines per page, the number of spaces between each record, or the amount of indentation on the left-hand side of each page. You can also ask for a customized title or request a SUMMARY-ONLY report. Since there are automatic ("default") values for all these features you could also leave this screen completely untouched and still produce an attractive report.
+---------------------+
| 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 <-------+ |
| |
| |
| |
|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)|
| |
+---------------------------------------------------------------------+
If you want your report to include summaries of element values and you are not interested in displaying the individual values, you can change the default value of the SUMMARY-ONLY option here from NO to YES. This option does not add any information to your report but suppresses some of the detail-level information so that the summaries you asked for are easier to read. This option only appears on the screen if you requested summaries on the Summarization Screen.
Here is a simple comparison of two reports, one with summary and record detail, the other with summary only:
(SUMMARY-ONLY = NO) (SUMMARY-ONLY = YES)
Dept Name Dept Name
------- ---------- ------- ----------
ACCT
ACCT Chisholm
Galante
*COU 2
*COU 2
DVPT
DVPT Arness
Scotto *COU 2
*COU 2 **COU 4
**COU 4
$REPORT can offer you some refinements in summarizing a report that go well beyond the basic summary reports in Report Definer. [See C.9, C.6.]
After you leave the inputting screens by issuing the FINISH option (or, on the final screen, the CONTINUE option), the system sets your format, then returns you to a prompted environment. The SPIRES prompt begins with a colon (":->") to remind you that you are still in Report Definer and have access to commands that are unavailable in regular SPIRES. All SPIRES and WYLBUR commands are also once again available, but special options associated with Report Definer inputting, such as BACKUP, can no longer be used. Thus for help you would now type a "?" or the word "HELP" instead of pressing the PF3 key.
Some of the standard SPIRES commands that could be useful include:
TYPE to display the report online. (IN ACTIVE TYPE
would put the report in your active file
complete with carriage control characters for
offline printing).
SHOW FORMAT INPUT to show the $REPORT commands that Report
Definer generated to set your format.
(IN ACTIVE SHOW FORMAT INPUT would put these
commands in your active file where they could
be further modified using $REPORT [See C.2.3]);
If you are in Global FOR, you can use the DISPLAY command instead of TYPE. By the way, remember that the report needs a subset of the subfile to work on, so if you have not already performed a search or assembled records with Global FOR, you need to do so now.
The following commands are specific to the Report Definer environment:
DEFINE returns you to the first screen in input mode
where you can modify the options you have
specified for the report so far;
DEFINE * returns you to the screen in input mode that
you most recently modified;
DEFINE CLEAR returns you to input mode but begins a brand new
report. DEFINE CLEAR erases the specifications
for your previous report;
RETURN leaves Report Definer altogether and returns
to standard SPIRES;
HELP shows you a list of commands useful at the
specific time that you request the HELP;
SHOW COMMANDS shows you a more comprehensive list of relevant
commands.
You can move back and forth in Report Definer. For example, you can create a report, display it, then use the DEFINE command to modify your report definition further. Once it looks the way you want you can place the report itself into your active file, or you can save the report specifications by using the IN ACTIVE SHOW FORMAT INPUT command. (This input actually consists of a series of $REPORT statements.) Later you can reuse this input without entering Report Definer by placing it in your active file and issuing the command XEQ. [See C.3.3.]
Here is what the report we have been creating from the Restaurant subfile would look like. Note that the field width for the CITY element has been shortened so that the report can fit comfortably within this manual's layout. Also the carriage control characters that automatically appear in column 1 when you place your report into the active file are not shown here. Otherwise this is a faithful model of what you can expect:
April 19, 1984 Local Restaurants Page 1
City Restaurant Name Food Average
Quality Price
-------------- ------------------------- ---------- ----------
Menlo Park Dutch Goose Good $ 1.50
El Rincon Tarasco Excellent $ 7.00
:
:
:
Su Hong Good $ 6.00
The Bay Window Fair $ 8.00
*AVG $ 7.07
*MIN $ 1.50
*MAX $ 20.00
Palo Alto Acapulco Excellent $ 5.00
Alouette Excellent $ 12.00
:
:
:
:
Village Cheese House Good $ 3.00
Watercourse Way Fair $ 5.00
*AVG $ 7.48
*MIN $ 0.25
*MAX $ 25.00
**AVG $ 7.40
**MIN $ 0.25
**MAX $ 25.00
Notice how the report definition changes character when you request a SUMMARY-ONLY report:
April 19, 1984 Local Restaurants Page 1
City Restaurant Name Food Average
Quality Price
-------------- ------------------------- ---------- ----------
Menlo Park
*AVG $ 7.07
*MIN $ 1.50
*MAX $ 20.00
Palo Alto
*AVG $ 7.48
*MIN $ 0.25
*MAX $ 25.00
**AVG $ 7.40
**MIN $ 0.25
**MAX $ 25.00
Only grouping elements and summaries appear in a SUMMARY-ONLY report, so in fact there is no reason to specify the elements NAME and FOOD-QUALITY in the report shown above.
Here is a list of the steps to take in using Report Definer. Note that some of the steps are optional, or can be performed at different stages of the process:
This chapter introduces the $REPORT format upon which REPORT DEFINER is based and discusses some of the added features that $REPORT offers. The remaining chapters in Part C of this manual will treat $REPORT in great detail, beginning with a summary of the command language [See C.3.] and then applying these commands to the body of the report [See C.4.] and to specific sections within the report. [See C.5.]
After covering these topics exhaustively Part C will go on to discuss ways of grouping your elements and summarizing the data they contain [See C.6, C.8.] as well as summarizing the entire report [See C.9.] and altering the general appearance of the printed page. [See C.7.] Reference charts of $REPORT command syntax are included in Part C. [See C.10.] And the last section of Part C describes the GENERATE FORMAT command, which creates a format definition in SPIRES formats language from your $REPORT commands. This utility is useful if you want to improve the efficiency of a report that you prepare frequently.
The $REPORT command language makes a consistent whole, but for any given report you will probably only need a subset of its features. If the many options offered seem overwhelming at first, you should find most of what you need for starting out in Chapters C.2 through C.4.
$REPORT consists of a self-contained command language or set of "sub-commands" that is recognized only when the $REPORT format is set. You can issue these special report writer commands any time you have a subfile selected.
You must use the report writer command language in conjunction with SPIRES search and display commands to produce a report. The $REPORT format merely determines the way records are displayed; it does not select, access, or sequence the records themselves. You take care of record access with one of the output commands you have already learned, such as TYPE or DISPLAY, and you sort the records as usual with the SEQUENCE or SPISORT commands. The following series of commands demonstrates how you would select records, define a report, and display the records according to your report definition.
-> select employees -> find project cleanup -Result: 4 RECORDS -> sequence name -> set format $report Name (1,20) Dept (+4,20) Hours (50,5) -> set format * options title = 'Project Cleanup' -> type
The resulting display looks like this:
+--------------------------------------------------------------+ | Nov. 10, 1982 Project Cleanup Page 1 | | | | Name Dept Hours | | -------------------- -------------------- ----- | | Wally Berg Development 22 | | Gigi Grinder Operations 27 | | Karla Olsen Accounting 20 | | Susan Schmoo Programming 38 | +--------------------------------------------------------------+
The SET FORMAT $REPORT command begins the report definition. In this case, the three columns of the report were defined on the SET FORMAT $REPORT command, each column representing the element named, with explicit positioning determined by the parameters in parentheses following each element name. Each row of this report represents one goal record. The SET FORMAT * command defines more parts of the report, building on the specifications already established. In this example, we are specifying a title to appear at the top of the page. By default, the page header consists of the date and page number, but in this case, the OPTIONS TITLE "command" places the title phrase "Project Cleanup" in the center of the page header.
If you display a single record (e.g., via the "DISPLAY key" command), no page header is generated. Multiple record display (e.g., via the TYPE command) to the terminal includes a single page header and column headings at the beginning of the display. Multiple record output to the active file includes complete report mode processing: headers, footers (if defined), and carriage control.
(Most examples in this chapter are shown as they would appear at the terminal, that is, with a single page header and no carriage control. They were also generated with a line length of 60.)
Like user-defined formats, $REPORT replaces any other format when it is set, and it is cleared by setting another format or by the CLEAR FORMAT command. Issuing a new SET FORMAT $REPORT command begins a new report definition.
After you issue the SET FORMAT $REPORT command, all records displayed use the report format specified, except when a "TYPE element-list" command is issued or when a SET ELEMENTS command is in effect. $REPORT does not affect the TRANSFER command or any input activity.
When you begin to design a report, you will find that the $REPORT format is simple to use and fosters an iterative approach to report design. You can issue the report writer commands interactively at the terminal, and display the report after each command to see the effect of each new command statement. Once you have the report the way you want it, you can issue the SHOW FORMAT INPUT command [See C.3.3.] and see what commands you issued to achieve the end result; IN ACTIVE SHOW FORMAT INPUT places the report definition in the active file.
Because a report definition is a series of SET FORMAT commands and often also includes SPIRES search and display commands, it can be executed as a protocol. That is, you can place the commands in the active file and issue the XEQ command or store them in a protocols subfile. [See C.3.3.]
Specifying the elements you want to appear in your report is simply a matter of listing them on a SET FORMAT $REPORT command, as follows:
SET FORMAT $REPORT DEPT NAME HOURS
This places the three specified elements in columns across the page, labeling the columns DEPT, NAME, and HOURS. The column dimensions are computed for you -- the available space (i.e., the current line length) divided evenly among the elements. [See C.4.2 for more details about the element list.]
Or you may specify explicit placement, size, labels, and display editing (edit masks, value adjustment, etc.). [See C.4.3.] Or the file owner may have specified some default placement, size, label and display editing characteristics that will be used by SPIRES if you don't specify your own. (You can see those characteristics, if any, by issuing the command SHOW ELEMENT INFORMATION for the selected subfile.)
In this example, where we request explicitly what we want, assume that we have the following records:
RECORD = 1; NAME = Smith; DEPT = ACCT; HOURS = 9; HOURS = 7; RECORD = 2; NAME = Carter; DEPT = ACCT; HOURS = 2; HOURS = 8; HOURS = 4;
The following report writing commands create the display shown:
SET FORMAT $REPORT DEPT (5,10,HEADING = Group) SET FORMAT * + Name (20,20) Hours (45,10,EDIT='ZZ.99')
+--------------------------------------------------------------+ | Jul. 10, 1993 Page 1 | | | | Group Name Hours | | ---------- -------------------- ---------- | | ACCT Smith 9.00 | | 7.00 | | ACCT Carter 2.00 | | 8.00 | | 4.00 | +--------------------------------------------------------------+
The DEPT element begins in column 5 for a length of 10 and the column is labeled "Group" rather than "DEPT". The SET FORMAT * command indicates that more is being added to the current report definition; the "+" indicates that more elements are being added. The element NAME begins in column 20 for a length of 20 and is labeled "Name". The HOURS element begins in column 45 for a length of 10 and the values are processed by an edit mask. (Because of the edit mask, values for HOUR are adjusted to the right of their field by default.) Note also that the default page header appears.
Another possibility is to display the elements down the page rather than across it:
+--------------------------------------------------------------+ | Jul. 10, 1993 Page 1 | | | | Group: ACCT | | Name: Smith | | Hours: 9.00 | | 7.00 | | | | Group: ACCT | | Name: Carter | | Hours: 2.00 | | 8.00 | | 4.00 | +--------------------------------------------------------------+
That is done by requesting a "vertical" report instead of a horizontal one:
SET FORMAT $REPORT OPTION VERTICAL SET FORMAT * DEPT (HEADING = Group) Name Hours (EDIT='ZZ.99')
As you can see, you specify vertical reports very similarly to the way you define horizontal ones, using many of the same features. Since horizontal reports are generally more common (and in some regards, more interesting) than vertical ones tend to be, this chapter concentrates mainly on horizontal ones. However, you will find information about vertical reports in one specific section, as well as in discussions of $REPORT features that behave differently in vertical reports from horizontal ones. [See C.4.7.]
When creating a report with $REPORT, you can indicate that records are arranged in order by as many as five elements with the GROUPED BY command, which defines "groups" of records. Records in a group have the same value for a particular element, and that element value prints only once. This assumes that your records have already been sorted by those elements using the SEQUENCE command [See B.4.5.] (or by SPISORT). Records having the same value for the primary sort element make up a group of records. Each group may also be divided into sub-groups, down to a nested level of five. [See C.6.1.]
For each group of records, you can define prefatory or summary data, plus an ending or grand-total summary. These sections can include element values, text, or arithmetic functions (SUM, AVERAGE, COUNT, MINIMUM, MAXIMUM, and STANDARD DEVIATION). [See C.6.5 for details about arithmetic functions.]
For example,
SET FORMAT $REPORT DEPT (1,5) NAME (10,10) PROJECT (25,24) HOURS (55,5)
displays 6 records as follows:
+----------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | DEPT NAME PROJECT HOURS | | ----- ---------- ------------------------ ----- | | ACTG Bennet Invoice Control 40 | | ACTG Bennet Resource Check 35 | | ACTG Foster World Domination 15 | | ACTG Foster Annual Audit 20 | | SYST Clark Nuclear Waste 10 | | SYST Jacobs Interplanetary Travel 20 | +----------------------------------------------------------------+
The following display shows the same records placed in groups with summary values appearing at the end of each group:
+----------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | DEPT NAME PROJECT HOURS | | ----- ---------- ------------------------ ----- | | ACTG Bennet Invoice Control 40 | | Resource Check 35 | | | | Foster World Domination 15 | | Annual Audit 20 | | | | *SUM 110 | | | | SYST Clark Nuclear Waste 10 | | | | Jacobs Interplanetary Travel 20 | | | | *SUM 30 | | | | **SUM 140 | +----------------------------------------------------------------+
The second example was created by adding two statements to the report definition:
SET FORMAT $REPORT DEPT (1,5) NAME (10,10) PROJECT (25,24) HOURS (55,5) SET FORMAT * GROUPED BY DEPT, NAME SET FORMAT * AT END OF GROUP DEPT, SUM HOURS
The GROUPED BY command indicated that the records are grouped by department and within each department by name. Like element values were only printed once. At the end of each department group, the hours were summed.
$REPORT provides enough default formatting to produce an attractive report with evenly spaced and labeled columns, left and right margins, carriage control, and a page header including the date and the page number. But if you desire, you can assume complete control of the layout of your report. You can control the width of the report and the number of lines per page. You can control when page breaks occur between records or groups. You can create title pages, ending data, and page headers and footers. [See C.7 for details about page formatting.]
For example,
SET FORMAT $REPORT DEPT (1,12) NAME (18,20) HIRE.DATE (45,9) SET FORMAT * OPTIONS, LINES = 55, INDENT = 5 SET FORMAT * AT START OF PAGE, PRINT "Monthly Report"// //$DATE SET FORMAT * AT END OF PAGE, PRINT "Crammett, Inc."//$PAGENO//Personnel
sets the lines-per-page to 55, moves the left margin over 5 spaces, and provides a header and a footer to appear on every page as in the following display:
+----------------------------------------------------------------------+ | 1 Monthly Report 11/10/82 | | | | DEPT NAME HIRE.DATE | | ------------ -------------------- --------- | | ACTG Bennet 5/10/80 | | ACTG Foster 6/23/76 | | ACTG Chandler 11/10/52 | | SYST Clark 8/1/67 | | SYST Jacobs 2/30/79 | | | | Crammett, Inc. 1 Personnel | +----------------------------------------------------------------------+
Though the "page" in this example is condensed, the last line of the footer is on line 55 of the page of the printed report. Remember that the footer and the carriage control character (the "1" in column 1) only appear when the report is placed in the active file.
Once you have the report formatted, you will want to print it. After issuing the $REPORT commands and selecting the records you want to be included in the report, put the records in the active file and issue a PRINT command. For example,
-> in active clear type -> print unnumber cc copies 6
Print options, such as character sets and number of copies, are, of course, up to you and depend on your particular needs. Issue the WYLBUR command
-> help print
for complete details on printing from the active file.
A report is logically divided into several parts, such as the page header, a title page, or summary sections. Likewise, a report definition is divided into sections, each section creating a logical part of the report. The parts of a report definition using $REPORT are:
- START OF REPORT
- END OF REPORT
- START OF DETAIL
- END OF DETAIL
- START OF GROUP
- END OF GROUP
- START OF PAGE
- END OF PAGE
The START OF REPORT section is used to create a title page or other prefatory text. The END OF REPORT section generally contains summary data, like grand totals of numeric values, or closing text.
The DETAIL sections make up the space in the body of the report for the display of a single record. In most cases, only the START OF DETAIL section is used.
The START OF GROUP section appears at the beginning of a group of records defined by the GROUPED BY command, and is intended to contain prefatory text. The END OF GROUP section appears at the end of a group of records and may contain summary values or text. Since there can be up to five groups of records defined, there can be up to five START OF GROUP and five END OF GROUP sections.
The START OF PAGE section is used to define page headers, and the END OF PAGE section is for page footers.
A report section is created by including a section-designation prefix such as "AT START OF PAGE" and placing a value in that section, with, for example, an element list, a PRINT expression, or an arithmetic function. You need only define those sections that you want to appear in your report. That is, not all sections are required; you can have as many or as few as you need. Also, there is no default size for each section -- a section is the size you define it to be.
The following drawing illustrates these sections and how they relate to some of the basic $REPORT commands. [See C.3.4.]
+-----------------+
| AT START OF |
| REPORT |
| |
| +---------------------------------------+
| |+-------------------------------------+|
+----------|| AT START OF PAGE ||
|+-------------------------------------+|
| +---------------------------------+ | -----+
| | AT START OF GROUP | | |
| +---------------------------------+ | |
| +-----------------------------+ | |
| | AT START OF DETAIL | | |
| | AT END OF DETAIL | | |
| +-----------------------------+ | GROUPED BY
| +-----------------------------+ | |
| | AT START OF DETAIL | | |
| | AT END OF DETAIL | | |
| +-----------------------------+ | |
| +---------------------------------+ | |
| | AT END OF GROUP | | |
| +---------------------------------+ | -----+
| |
| +---------------------------------+ | -----+
| | AT START OF GROUP | | |
| +---------------------------------+ | |
| +-----------------------------+ | |
| | AT START OF DETAIL | | |
| | AT END OF DETAIL | | |
| +-----------------------------+ | GROUPED BY
| +-----------------------------+ | |
| | AT START OF DETAIL | | |
| | AT END OF DETAIL | | |
| +-----------------------------+ | |
| +---------------------------------+ | |
| | AT END OF GROUP | | |
| +---------------------------------+ | -----+
|+-------------------------------------+|
|| AT END OF PAGE +-----------------+
|+-------------------------------| AT END OF |
+--------------------------------| REPORT |
| |
| |
| |
+-----------------+
A report definition consists of an initial SET FORMAT $REPORT command and a series of SET FORMAT * commands. The initial command usually specifies the elements to be displayed in the report. Additional features of the report (detail lines, page headers, summaries, etc.) are specified in subsequent SET FORMAT * commands, each SET FORMAT * command building upon the information established to that point. A new SET FORMAT $REPORT command begins a new report definition.
As described above, a report definition begins with the SET FORMAT $REPORT command, which may be issued at any time after you have selected a subfile. The rest of the report definition is composed of SET FORMAT * commands.
The syntax of these commands is:
SET FORMAT $REPORT statement SET FORMAT * statement
where "statement" is a command statement from the report writer command language.
The complete command can be up to 160 characters long. The report writer command language allows you to build the report definition in small pieces by issuing a series of SET FORMAT * commands, so you need never reach this command length limit.
Once you have issued a SET FORMAT $REPORT command, you can issue the SHOW FORMAT INFORMATION command to see the global settings currently in effect for your report.
For example,
-> select mail file -> set format $report Name Address City -> show format information Information for format $REPORT Current section: START OF DETAIL No groups defined Length=72, Lines=60, Indent=0, Cluster=0, Maxrows=100 Nosummarize, Report, Heading, Nobreak, Underline='-' No title
The SHOW FORMAT INPUT command displays the commands that you have issued so far in your report definition. The output from this command can be placed in the active file (with the IN ACTIVE SHOW FORMAT INPUT command), saved, and then used later to redefine the same report. [See D.3.1.2.]
The output includes all of the commands that you issued, not just those that are in effect at the time. That is, if you have redefined element lists or other options, the original commands still appear in the report definition. So if you are doing a great deal of iteration, it is a good idea to periodically issue the IN ACTIVE SHOW FORMAT INPUT command, remove all unnecessary commands, and issue the XEQ command [See E.1.] to update your report definition.
For example,
-> select mail file -> set format $report Name Address City -> set format * grouped by city -> set format * at end of group city, count name -> in active clear show format input -> list 1. SET FORMAT $REPORT Name Address City 2. SET FORMAT * grouped by city 3. SET FORMAT * at end of group city, count name -> sav #report
At a later date, you can put your report definition in the active file and with the XEQ command redefine the same report as follows:
-> select mail file -> use #report -> xeq
A command statement generally has several parts to it (in addition to the SET FORMAT $REPORT or SET FORMAT * prefix). The statement contains one or more of the following:
- a section-designation prefix (e.g., AT START OF PAGE)
- a row prefix (e.g., IN ROW 3)
- one or more commands (e.g., GROUPED BY NAME)
- one or more parameter lists (e.g., (10,15,RIGHT,EDIT='ZZ.99'))
- an element list (e.g., ELEMENTS DEPT NAME HOURS)
A section-designation prefix establishes the section of the report being defined. A row prefix is used in conjunction with section-designation prefixes to specify an exact location in the section. A parenthesized parameter list describes how and where a particular item is to be displayed in the report. Parameters are composed of keywords and values, or keywords that stand alone.
Except when noted, either a comma or spaces may be used to separate items in a command statement, and either an equal-sign or spaces may be used to separate a keyword from its value. When multiple parameters are available, they may be given in any order. All commands, parameters, and keywords can be abbreviated to three or more characters, except for those that begin with NO, in which case they can be abbreviated to NO plus three characters.
Following are some sample report writer command statements:
SET FORMAT * SKIP 4, PRINT $DATE
| |
¾þþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþ commands
SET FORMAT $REPORT DEPT (5,10) NAME (17,20) PROJECT (39,30)
| |
| ¾þþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþ parameters
|
¾þþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþþ element
SET FORMAT * AT END OF REPORT, IN ROW 3, SUM HOURS, COUNT DEPT
| | | |
| | ¾þþþþþþþ arithmetic functions
| ¾þþþþþþþþþþþþþþþþþþþþþþþþþþþ row prefix
¾þþþþþþþþþþþþþþþþþþþþþþþþþþþþþ section-designation prefix
The following sections show the syntax (in boldface) and provide a brief description of each command. For more complete information and examples, see the referenced sections.
Section prefixes establish the report section (REPORT, PAGE, GROUP, and DETAIL) being defined. They must be followed by a command, but once a section is established by the use of one of the section prefixes, the prefix does not need to be repeated -- all commands are assumed to apply to that section until another section prefix is included. When the SET FORMAT $REPORT command is first issued, it is assumed that you are working in the START OF DETAIL section. START and TOP are equivalent; END and BOTTOM are equivalent.
The DETAIL section is the area within which a single record is displayed. IN DETAIL is equivalent to AT START OF DETAIL. [See C.4.1.]
Each group of records defined with the GROUPED BY command can have prefatory or summary information, which is placed in the START OF GROUP and END OF GROUP sections. [See C.6.3, C.6.4.]
These sections are used to include prefatory or summary information for the entire report. AT START is equivalent to AT START OF REPORT. AT END is equivalent to AT END OF REPORT. [See C.8.1, C.8.2.]
These sections are used to create page headers and footers. [See C.7.2, C.7.3.]
This prefix can appear before or after any of the above section prefixes and specifies a row in the section being defined. Like the section-designation prefixes, the IN ROW prefix sets a default row for subsequent commands. [See C.5.3.]
The element list specifies which elements are to appear in the report. It is only allowed in the DETAIL section. More than one list may appear in a definition, adding to or replacing a previous list or putting elements on different rows.
Each element name may be followed by a parenthesized parameter list to specify explicit positioning. [See C.4.2.] Parameters are:
- COLUMN = n. Specifies starting column position. [See C.4.3.1.]
- WIDTH = n. Specifies column width. [See C.4.3.2.]
- ADJUST = LEFT|RIGHT|CENTER|TRUNCATE|MARGINS|JUSTIFY|ALIGN. Specifies adjustment of the value within the column. [See C.4.3.3.]
- BUILD = 'string'. Specifies that multiple occurrences of the element are to concatenated, separated by the "string". [See C.4.3.3.]
- INDENT = n. Specifies an indentation for the value. [See C.4.3.4.]
- HEADING = 'string'. Names a heading for the column, if different from the element name. [See C.4.3.5.]
- EDIT = mask. Specifies an edit mask for the value. [See C.4.3.6.]
- Arithmetic Function. Specifies that all occurrences of the value in a record are to be calculated into one value. [See C.4.4.]
- TYPE = NUMERIC|TEXT. Specifies whether the element is a numeric value or a text value, for the use of the DEFAULT option. [See C.4.3.7.]
- DEFAULT = 'string'. Specifies a default value to appear when there is no occurrence of the element.
Section-specific commands are those commands that apply to a specific section. Some are valid for all sections, while others are only valid for certain sections.
Allowed in any section, this command specifies a relative position in the section. [See C.5.4.]
Indicates that the section is to begin on a new page or on a new front page of the piece of paper. It is not allowed in the START OF PAGE or END OF PAGE sections. [See C.5.1.]
This command is allowed in any section and indicates that a font control character is to be placed in column 2 of the active file for the current row. [See C.5.6.]
This command can be used in any section and places the expression in the current section. The parenthesized parameter list includes explicit positioning information. [See C.5.2.] Parameters are:
- COLUMN = n. Specifies the starting column for the value.
- WIDTH = n. Specifies column width.
- ADJUST = LEFT|RIGHT|CENTER|JUSTIFY|TRUNCATE|MARGINS. Specifies adjustment of value within column.
- INDENT = n. Specifies an indentation for the value.
- EDIT = mask. Defines an edit mask for the expression.
- FONT = n. Specifies font control for the row on which the value appears.
- HEADING = 'heading'. Specifies a heading for the print expression similar to the heading for an element. It is generally more useful for vertical reports than the normal horizontal ones.
- TYPE = NUMERIC|TEXT. Specifies the type of the print expression, which is important to certain other global options, such as ADJUST and QUOTE.
- FINAL|NOFINAL. Controls whether the PRINT expression is also to be printed at the end of the report. Valid only for END OF GROUP sections.
Arithmetic functions provide a way of summarizing values. They are: SUM, MINIMUM, MAXIMUM, AVERAGE, COUNT, and STD (standard deviation). Cumulative functions (as in the minimum value in the report so far) are also available: CSUM, CMINIMUM, CMAXIMUM, CAVERAGE, CCOUNT, CSTD. Function names must be followed by an element name. Only the COUNT function can be used with non-numeric element values. Arithmetic functions are usually specified in the END OF GROUP and END OF REPORT sections, though a special form is available for use for summarizing values in a single record in the detail section. A parenthesized parameter list may be included to specify explicit positioning. [See C.6.5.] Parameters are:
- COLUMN = n. Specifies starting column for function value.
- WIDTH = n. Specifies column width.
- ADJUST = LEFT|RIGHT|CENTER. Specifies adjustment of value within column.
- TYPE = NUMERIC|TEXT. Specifies the type of the function, which is important to certain other global options, such as ADJUST and QUOTE.
- LABEL = string. Defines a label for the function value.
- EDIT = mask. Defines an edit mask for the value.
- BIND|NOBIND. Controls whether the function value appears in the same column as the element.
- FINAL|NOFINAL. Controls whether the function also appears at the end of the report. Valid only for END OF GROUP sections.
- TYPE = NUMERIC. Specifies the type of the function, which is important to certain other global options, such as ADJUST and QUOTE.
Global commands are those that do not apply to any specific section and can be issued at any place in the report definition.
Indicates that the records are grouped according to certain elements. This is usually the same set of elements named in a SEQUENCE command. Element values that are alike only print once if that element is specified on the GROUPED BY command. There can be up to five groups. [See C.6.1.] Parameters are:
- FINAL|NOFINAL. Controls the printing of final summary values. [See C.6.1.1.]
- NODISPLAY|DISPLAY. Controls the printing of like element values in a group. [See C.6.1.2.]
- BLANKS = n. Controls the number of blank lines between groups of elements. [See C.6.1.3.]
- HEADING = 'heading'. Sets a heading label for the group, which will appear with the group value that distinguishes the group. This may also cause a "start of group" section to appear that would not appear without it. [See C.6.1.4, C.6.8.]
- NAME = 'name' Sets a label for the group that will appear in verbose summary functions at the end of the group. It may also appear in the "start of group" section in a vertical report. [See C.6.1.4, C.6.8.]
Defines a summary element that can be used in the report or further manipulated in arithmetic functions or expressions. [See C.6.7.]
Specifies a label for arithmetic function values. [See C.6.6.]
Takes one or more options that specify various overall report characteristics. [See C.4.5.] Options are:
- VERTICAL|HORIZONTAL. Switches between vertical reports and horizontal reports (the default). [See C.4.7.]
- LINES = n. Specifies the number of lines per page. [See C.7.5.]
- LENGTH = n. Specifies the line length. [See C.7.4.]
- INDENT = n. Specifies the indentation of the left margin. [See C.7.6.]
- TITLE = string. Specifies a title to appear centered in the default page header. [See C.7.1.]
- CLUSTER = n. Places a blank line after the specified number of records. [See C.4.5.4.]
- GAP = n. Sets the gap (number of spaces) between columns for horizontal reports. [See C.4.5.7.]
- MAXROWS = n. Raises the default line limit per element occurrence. [See C.4.5.2]
- NOGROUP. Cancels any groups that have been defined. [See C.6.2.]
- BREAK|NOBREAK. Controls whether a record can be broken across page boundaries. [See C.4.5.4]
- REPORT|NOREPORT. Controls the level of report mode processing. [See C.4.5.3]
- HEADING|NOHEADING. Controls whether the column headings appear. [See C.4.3.5.]
- PAGE|NOPAGE. Turns on or off page control, page headers and footers. [See C.4.5.3.]
- UNDERLINE = x|NOUNDERLINE. Specifies a character to be used to underscore column headings. [See C.4.3.5.]
- SUMMARIZE [TO element]|NOSUMMARIZE. Controls summary level of report. [See C.9.2.]
- ADJUST = adjustment-value(s). Specifies a default adjustment for data values (such as centered, left-justified, truncate, etc.). [See C.4.5.6.]
- DEFAULT [ALL|TEXT|NUMERIC] = 'string' | NODEFAULT. Specifies a default value for elements that do not occur in the data. [See C.4.5.5.]
- ELEMINFO|NOELEMINFO. Turns on or off the importing of element information packets for use by $REPORT. [See C.4.6.]
- FUNCTIONS = {TERSE|VERBOSE}. Sets short or long forms of summary statistic labels. [See
C.6.5.]
- DELIMITER = [X]'character'. Specifies a character to be printed in front of each value, to delimit it from the previous value on the row. [See C.4.5.8.]
- SQUEEZE|NOSQUEEZE. Squeezes out all blanks between columns of data, generally used with DELIMITER. [See C.4.5.8.]
- QUOTE [ALL|NEXT|NUMERIC] | NOQUOTE. Puts quotation marks around values. [See C.4.5.8.]
In a report definition, you might have several section definitions. [See C.2.6.] Sections may be defined in any order, and you may put pieces of section definitions in various places throughout the report definition. That is, a section definition does not have to be contained in a single block of commands.
To define a particular section, begin with a section-designation prefix (e.g., AT START OF REPORT). This establishes that section, and all subsequent commands are assumed to be part of that section until another section-designation prefix is encountered. When you first issue the SET FORMAT $REPORT command, it is assumed that the START OF DETAIL section is being defined.
To place items on multiple rows within the section, use the IN ROW prefix. For example,
SET FORMAT * IN ROW 3, ELEMENT Name Hours
places the two elements, "Name" and "Hours", on row 3 of the DETAIL section. Or,
SET FORMAT * AT START OF PAGE, IN ROW 2, PRINT $DATE
prints the value of $DATE on the second row of the page header.
The IN ROW prefix may be followed with a number to specify an explicit row, a number preceded by a "+" to specify a relative starting row, or a "*" to specify the current row. [See C.5.3 for details about the IN ROW prefix.]
The following report definition illustrates the use of most of the section prefixes.
1. SET FORMAT $REPORT Dept (1,10) Name (15,20) Hrs (40,10,RIGHT)
2. SET FORMAT * IN ROW +1, PRINT 'Project: ' @@PROJECT
3. SET FORMAT * GROUPED BY DEPT, NAME
4. SET FORMAT * AT END OF GROUP DEPT, SUM HRS, COUNT PROJECT
5. SET FORMAT * AT END OF GROUP NAME, SUM HRS
6. SET FORMAT * AT END OF PAGE, PRINT (CENTER) 'C.M., Inc.'
7. SET FORMAT * AT START OF REPORT, PRINT (CENTER) 'MONTHLY REPORT'
8. SET FORMAT * IN ROW +2, PRINT (CENTER) 'Consolidated Monkeys, Inc.'
9. SET FORMAT * AT END OF REPORT, NEWPAGE
10. SET FORMAT * AT END OF REPORT, PRINT (CENTER) 'THE END'
11. SET FORMAT * OPTIONS TITLE 'Monthly Report'
Lines 1-2 define the DETAIL section, where actual records are displayed. Because it is defined first, the AT START OF DETAIL section designation prefix is not required. Line 1 specifies the element list, defining which elements are to appear and where the columns are to be placed. Line 2 specifies that on the row following the last element value the string 'Project: ' is placed followed by the value of the PROJECT element. Line 3 defines 2 groups, one based on the element DEPT, the other on the element NAME. Lines 4-5 define two END OF GROUP sections, one for each group of records defined. At the end of each DEPT group, the sum of the HRS element and the COUNT of the PROJECT element is calculated using all the records that are in the DEPT group. At the end of each NAME group, the HRS element is again summed, using only those records in the group sharing a like NAME value. Line 6 defines a single line of a page footer on which the specified string is centered. Lines 7-8 define a title page. Lines 9-10 define a single line of closing text that appears on a separate page because of the NEWPAGE command on line 9. Line 11 defines a title that appears in the default page header.
To create the body of the report, you work in the START OF DETAIL and END OF DETAIL sections. It is here that you define which elements are to appear in the report and how they are to be positioned.
Many aspects of a report can be pre-defined in the file definition by way of "element information packets". A packet may include descriptions of how an element is to be displayed, such as column width, column heading, adjustment within the column, and edit masks. See Section C.4.6 for details about element information packets.
The START OF DETAIL and END OF DETAIL sections make up the area within which a single record is displayed. Both sections may include element lists, PRINT expressions, and font control. You would ordinarily only use the START OF DETAIL section. [See C.4.2, C.5.2, C.5.6.]
Following is an example of a simple definition using the START OF DETAIL section and specifying an element list:
SET FORMAT $REPORT NAME CITY
Because no other section has been specified, it is assumed that you meant AT START OF DETAIL. Also, we did not specify any explicit positioning information so $REPORT calculates the column spacing. With one simple command, we get the following report:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME CITY | | ---------------------------- ---------------------------- | | Ann Claire Wesley Moondale | | Langley Wallingford Pine Valley | | Rebecca Ferrett Alphaville | | Pinky Dew Foster City | +--------------------------------------------------------------+
However, if you had specified another report section previously, you would have to include the AT START OF DETAIL prefix because the element list is only valid in this section. For example,
SET FORMAT $REPORT AT START OF REPORT PRINT 'Monthly Report' SET FORMAT * AT START OF DETAIL NAME DEPT HOURS
Column headings always appear at the top of the page, just under the page header. The column headings are, therefore, not an actual part of the DETAIL sections. They can be changed for an individual element via the HEADING parameter, or suppressed altogether with the NOHEADING option. [See C.4.3.5.]
The END OF DETAIL section prints immediately following the START OF DETAIL section. Like all ending sections, the default starting row for the END OF DETAIL section is row 2. This provides a blank line between the START and END of sections. You can, however, place data explicitly in row 1 (i.e., IN ROW 1 AT END OF DETAIL) and it appears on the row immediately following the last row of data placed in the START OF DETAIL section.
When you use both the START OF DETAIL and END OF DETAIL sections any column headings generated by the inclusion of an element list in either section appears at the top of the body of the report.
For example,
SET FORMAT $REPORT NAME (1,15) CITY (21,15) SET FORMAT * AT END OF DETAIL CAT.NAME (1,10) DOG.NAME (21,10)
produces the following report:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME CITY | | --------------- --------------- | | CAT.NAME DOG.NAME | | ---------- ---------- | | Carmen Miranda Palo Alto | | | | Felix Fido | | Esther Williams Mt. View | | | | Stella Spot | +--------------------------------------------------------------+
If you wish to create a multi-row record display as in the above example, you can also use the IN ROW prefix, which is a more efficient and easier way of creating a multi-row DETAIL. [See C.5.3.]
The main use of the END OF DETAIL section is to cause a page eject in the middle of a record display. This is because a page eject can only occur at the beginning of a section. [See C.5.1.] It is recommended that you only use the END OF DETAIL section if you need this page eject.
The element list can appear anywhere in the report definition, and does not even have to appear at all for summary reports. [See C.9.] The element list is a series of element names, each of which may be followed by a parenthesized parameter list. The parameters include specifications to control the placement and formatting of the element values. No other command can appear in the same command statement with an element list.
The basic syntax is:
[ELEMENT|+] element-name (parameters) element-name (parameters)......
The ELEMENT command is used to signal the beginning of the element list, but is always optional unless the first element in the element list is OPTIONS, PRINT, LABEL, FONT, NEWPAGE, GROUPED, or DEFINE. (These words signal other commands.) If an element list already exists for any given row, a new element list completely replaces the previously defined one. If you wish to add new elements to an already existing list, use the "+" in front of the new element list.
The element list must be in one of the DETAIL sections. The START OF DETAIL section is the default at the beginning of a report definition, so if you begin your definition with the element list, you need not specify the section. But if you have specified any other sections before including the element list, you must use the AT START OF DETAIL or AT END OF DETAIL prefix with the element list.
Up to 100 elements can be included in a report. They may be any of the following:
- Any element (real, virtual, or phantom) defined for the subfile. For non-unique names, fully qualified element names must be used (i.e., struc@struc@...@elem).
- Dynamic elements. These elements must be defined prior to the report. With them you can create new elements based on values derived from one or more elements in a record. [See C.4.2.3.]
- Summary elements. These are values computed across groups of one or more records, and are specified in the report definition either by including a function name in the parameter list for an element or with the DEFINE VALUE command. [See C.6.7.]
A simple report can be specified by including only an element list on the SET FORMAT $REPORT command. For example,
SET FORMAT $REPORT NAME DEPT HOURS
creates a display that looks like this:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME DEPT HOURS | | ------------------ ------------------ ------------------ | | Wally Berg Accounting 20 | | Gigi Grinder Development 22 | | Karla Olsen Programming 38 | | Susan Schmoo Operations 27 | +--------------------------------------------------------------+
If you wish to alter the element list, use the SET FORMAT * command with the ELEMENT keyword or "+" keyword. The "SET FORMAT * +" command names items to be added to whatever has been established so far (with appropriate readjustment of the columns). The "SET FORMAT * ELEMENTS" command is used to completely replace an element list for a report already established. They both apply only to the current row if a multi-row display is being defined.
For example:
-> SET FORMAT $REPORT EIN ZWEI <--report has 2 elements
-> SET FORMAT * + DREI VIER <--report now has 4 elements
-> SET FORMAT * IN ROW 2 UNO DOS TRES <--report now has 7 elements
on two rows
-> SET FORMAT * ELEMENT UN DEUX TROIS <--elements on row 2
replaced
It is recommended that if you want to replace an element list, use the IN ACTIVE SHOW FORMAT INPUT command to place the report definition in your active file, modify the element-list, and XEQ the definition. This prevents confusion when making numerous iterations or when defining multi-row record displays.
Column placement and width are calculated by $REPORT, unless specified in the element parameter list. [See C.4.3.] This calculation is performed independently for each row of a multi-row display. The current value of $LENGTH is used as a default right margin for the report or a length can be specified in a $REPORT OPTIONS statement; [See C.7.4.] system computed columns cannot exceed this margin. However, explicit positioning information causes the right margin to expand outward as needed.
If an element has multiple occurrences, they are displayed one underneath the other. The next record begins on the row following the last element occurrence of the record before it. This is called "horizontal binding." When all elements are defined on the same row, this horizontal binding merely displays the records as you would expect.
For example, if the records in the example in C.3.2 have more than one occurrence of the HOURS element, the report then looks like this:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME DEPT HOURS | | ------------------ ------------------ ------------------ | | Wally Berg Development 22 | | 35 | | 12 | | Gigi Grinder Operations 27 | | 25 | | Karla Olsen Accounting 20 | | 43 | | 35 | | Susan Schmoo Programming 38 | | 20 | | 37 | +--------------------------------------------------------------+
Element filters may be set to specify which occurrences of an element are to be displayed. The filters must be set prior to the execution of the format (i.e., the actual output of the records), but need not be set prior to the definition of the report. EXPLAIN SET FILTER COMMAND or see Chapter 21 of the SPIRES manual "Technical Notes" for more details about element filters.
In horizontal reports, elements within structures are displayed according to the structural hierarchy. That is, if elements in a structure are multiply occurring, elements that occur at the same level in the structure begin on the same row. This is "structural binding" and is similar to the "horizontal binding" of multiply-occurring elements at the record level.
Say, for example, that you have a record with the following structures:
PEOPLE; NAME= Madge; ADDRESS = 1442 Trenton Drive; ADDRESS = Apt. D3; ADDRESS = Palo Alto, CA; PEOPLE; NAME = Thelma; ADDRESS = 179 Simmons Circle; ADDRESS = Menlo Park, CA;
Structural binding allows these structures to print like this:
+--------------------------------+ | NAME ADDRESS | | -------- -------------------- | | Madge 1442 Trenton Drive | | Apt. D3 | | Palo Alto, CA | | Thelma 179 Simmons Circle | | Menlo Park, CA | +--------------------------------+
rather than like this:
+--------------------------------+ | NAME ADDRESS | | -------- -------------------- | | Madge 1442 Trenton Drive | | Thelma Apt. D3 | | Palo Alto, CA | | 179 Simmons Circle | | Menlo Park, CA | +--------------------------------+
Structural binding holds true only if all elements in the structure are defined on the same row (i.e., SET FORMAT $REPORT NAME ADDRESS or SET FORMAT * IN ROW 3 NAME DEPT HOURS). If you want elements within a structure to be on different rows, you must use the SKIP command to create a vertically bound unit of display for the structure. [See C.5.5 for information about vertical structural binding.]
$REPORT can handle structures up to a nested level of 8, and can access and display phantom structures.
In vertical reports, the structural elements need to be named together (next to each other) in the element list in order to assure structural binding. [See C.4.7.]
A dynamic element is an element whose value is derived from one or more elements in the subfile or it may be derived from non-data-base values, such as the current date or time. It must be tied to an element defined in the file definition, however; whenever that element has an occurrence, an occurrence of the dynamic element also exists.
You can define up to 32 dynamic elements at a time. When used in a report, they must be defined prior to the report, and must not be zapped or redefined prior to the execution of the report.
A dynamic element is defined by the DEFINE ELEMENT command:
DEFINE ELEMENT element [FOR primary] AS expression
where "element" is the name of the dynamic element being defined, and "primary" is the name of the element in the goal record to which the dynamic element is tied.
The "expression" is required in a DEFINE ELEMENT command, and describes how the value for the element is to be created. It may consist of strings, functions, variables (user or system), arithmetic operators, concatenation operators, parenthetical subexpressions, commas, and element names (in the form "@elem" for the internal form of the element value or "@@elem" for the external form -- the $GETUVAL and $GETCVAL system functions are not allowed). Remember to enclose the element name in apostrophes or quotation marks if the name contains a hyphen or plus-sign (for example, @@'DATE-UPDATED').
Note that this is a SPIRES command, not a $REPORT sub-command. It is not preceded by a SET FORMAT $REPORT or SET FORMAT * command.
EXPLAIN DYNAMIC ELEMENTS or see Chapter 20 in Technical Notes for more information about defining dynamic elements.
Let's say we have a subfile of employee records with an element that is the employee's yearly salary and we want to print in a report a value that was the employee's monthly salary. We then define a dynamic element that is the salary element divided by 12, as follows:
DEFINE ELEMENT MONTHLY.SAL AS @SALARY/12
We can now include the element MONTHLY.SAL in the element list of our report definition:
SET FORMAT $REPORT EMP.NAME MONTHLY.SAL
Or, suppose we want to number the records in a report; then:
DEFINE ELEMENT NUMBER FOR key AS $RECNO
where "key" is the element name of the record key. The dynamic element named "number" occurs each time the record key occurs (that is, once per record) and is a sequential number representing that record in the report. This allows you to number the records in your report.
Or you might want a string to appear only if a particular element occurs and as many times as that element. In this case, you define a dynamic element tied to that element as follows:
DEFINE ELEMENT X FOR DEBIT AS '***'
The X element occurs only when the element DEBIT occurred. We then use the dynamic element in a report definition as follows:
SET FORMAT $REPORT NAME (1,15) ACCT.NUM (+2,7) SET FORMAT * + CREDIT (+2,7) DEBIT (+2,7) X (+2,3)
and we get the following display, where the three asterisks appear next to any DEBIT value.
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME ACCT CREDIT DEBIT X | | --------------- ------- ------- ------- --- | | Smith 384676 100.50 | | Jones 385762 45.34 *** | | Mason 99876 300.45 *** | | Brown 11423 35.45 23.10 *** | | Green 37554 58.23 | +--------------------------------------------------------------+
A literal string is a character value that you wish to appear exactly as entered, as opposed to an expression or variable value where the characters represent another value that is to be calculated or substituted by SPIRES. For example, if you want the words 'Monthly Report' to appear in the display, it is a literal string, whereas the value '#NUM-#LAST.NUM' is an expression where you are performing an arithmetic operation on two values that are stored by SPIRES as variables.
You can include literal strings in the element list if you wish these strings to appear as values within a column. When you place a literal string in the element list, it must be enclosed in quotation marks or apostrophes. You can include a parameter list for these values just as you would for an element name. The column width by default is only as wide as needed for the literal. The column has no heading, but one can be specified with the HEADING parameter. For example,
SET FORMAT $REPORT NAME (1,15) AMOUNT (16,6) '___________________'
(30,20,HEADING='Signature:')
creates the following display:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME AMOUNT Signature: | | ------------ ------ -------------------- | | Smith 1,250 ____________________ | | Carter 2,000 ____________________ | | Johnson 975 ____________________ | +--------------------------------------------------------------+
The string appears only once per record and is not bound to the occurrence of any other element. If you want a string to appear only if another element occurs and as many times as that element, you must use dynamic elements. [See C.4.2.3.] If you want to include an expression or variable value in the report, use the PRINT command. [See C.5.2.]
Unless otherwise specified, elements are positioned according to information supplied in the file definition or according to default rules calculated by $REPORT, which divide the available space evenly among the values. But if your element values are particularly long or if they are of differing lengths, this default positioning might make the report look unbalanced. So you would probably want to specify starting positions and column dimensions for each value.
This is done by including a parenthesized list of parameters after each element name. The parameter list consists of one or more items separated by commas or spaces. The parameters themselves are keywords, some of which can have values assigned to them. They can appear in any order.
The first parameter, if just an integer, is interpreted as a COLUMN value, giving the starting column for the value. If this is followed by a second integer, then the second value is assumed to be WIDTH.
For example,
SET FORMAT $REPORT NAME (1,10) DEPT (12,5) PROJ (20,30)
sets the display to:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME DEPT PROJ | | ---------- ----- ------------------------------ | | Bennet ACCT Annual Audit | | Carter SYST Space Stations | | Smith FINA Fund Raising on Mars | +--------------------------------------------------------------+
If you place two values in the same space, the values are overlaid. For example,
SET FORMAT $REPORT PRINT (1,20) '...................' SET FORMAT * + NAME (1,10) DEPT (12,5) PROJ (20,30)
creates the following display:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME DEPT PROJ | | ---------- ----- ------------------------------ | | Bennet.....ACCT....Annual Audit | | Carter.....SYST....Space Stations | | Smith......FINA....Fund Raising on Mars | +--------------------------------------------------------------+
The next sections describe these parameters.
This parameter designates a starting column for the element value. If only a number is given following the COLUMN keyword, it is assumed to be an explicit column number.
If designated first in the parameter list, the "COLUMN" keyword is optional. So,
SET FORMAT $REPORT NAME (5)
is the same as
SET FORMAT $REPORT NAME (COLUMN = 5)
If the number is preceded by a "+" (e.g., COLUMN=+3), it specifies a starting position that is relative to the end of the previous column of data. The amount of space between data columns is called the gap. [See C.4.5.7.]
If a relative column position is given for the first element on a particular row of a multi-row display, that column is placed the specified number of spaces to the right of the first column. For example,
SET FORMAT $REPORT NAME (1,20) ADDRESS (+4,20) PHONE (+4,20)
places the three columns across the page with 4 spaces between each. But,
SET FORMAT $REPORT NAME (1,20) ADDRESS (+4,20) SET FORMAT * IN ROW 2, PHONE (+4,20)
places the PHONE element on row 2, beginning in column 5 (i.e., 4 spaces to the right of the first column of the row).
If not given, the starting position is computed by $REPORT.
This parameter designates a maximum column width. As stated above, if two integer values are included at the beginning of the parameter list, the second is assumed to be WIDTH. If you don't specify a width, $REPORT computes one for you.
If you specify an edit mask for an element [See C.4.3.6.] and the edit mask is wider than the width specified for the column, the column will automatically be widened to fit the edit mask.
This parameter determines the placement of the value within its column. It also applies to the placement of the column heading. All leading and trailing blanks are stripped from the value before placing it in the column. Possible values are:
- LEFT or RIGHT. These cause the value to be left- or right-justified. The value will be truncated if it does not fit on one line, unless you also specify WRAP, MARGINS or ALIGN.
- TRUNCATE. By default, values longer than the column width are wrapped to multiple lines, unless the SQUEEZE option is in effect. SQUEEZE, without TRUNCATE, will ignore column width and not wrap values to other lines. Use TRUNCATE if you would rather have the value truncated at the column width, with or without the SQUEEZE option. [See C.4.5.8.]
- WRAP or MARGINS. This parameter causes values to wrap to multiple lines rather than being truncated at the column width. If a subfile has an ADJUST value of TRUNCATE in the element information packet, you can use the ADJUST = WRAP parameter in $REPORT to override the default truncation.
- JUSTIFY. This still wraps values onto multiple lines, but also justifies each line but the last, i.e., the right margin is made even.
- CENTER. This causes the value to be centered within the margins. The value will be truncated if it does not fit on one line, unless you also specify WRAP, MARGINS or ALIGN.
- ALIGN (obsolete). This causes multiple occurrences of the value to be concatenated on the same line as previous occurrences, with a space between. Only occurrences at the record level or within the same structure are aligned. This option has been superseded by the BUILD parameter described below, which is more versatile.
The default is LEFT, WRAP except where there is an edit mask, in which case the default is RIGHT. The ADJUST keyword is optional, and the ADJUST values may be abbreviated to one or more characters. For example, the following are equivalent:
SET FORMAT $REPORT Name (1,18,RIGHT) SET FORMAT $REPORT Name (1,18,ADJUST=RIGHT) SET FORMAT $REPORT Name (1,18,R)
Combinations are allowed, and $REPORT uses the combinations when possible (i.e. when they are not contradictory, like LEFT and RIGHT). In particular, you may combine WRAP with LEFT, RIGHT or CENTER so that long values wrap into multiple rows but each row is aligned left, right or center. (Remember, the combination LEFT, WRAP is the default if you don't specify any adjustments.)
The BUILD parameter, like the ADJUST=ALIGN parameter, concatenates multiple occurrences of the element for output, separating them with an optional string of up to two characters that you choose:
BUILD [= 'string'| = x'string']
where 'string' is a 0, 1 or 2 character string (or a hex string for the "x" hex form, representing 0, 1 or 2 characters, as in "x'05'" for the hex 05 tab character) that SPIRES should place as a separator between the occurrences.
For example:
-> set format $report album-title performer
-> type
Album Title Performer
----------------------- -----------------------------------
Babalou Barbara Walters, guitar
Lou Reed, vocals
Jessica Tandy, tambourine
-> set format $report album-title performer(build='; ')
-> type
Album Title Performer
----------------------- -----------------------------------
Babalou Barbara Walters, guitar; Lou Reed,
vocals; Jessica Tandy, tambourine
The BUILD parameter works very well with the ADJUST parameters such as RIGHT and CENTER. It is recommended over ALIGN, which does the same thing but does not allow you to specify a separator string -- ALIGN always uses a single space as the separator. With BUILD, you can have no separator (BUILD = '', or BUILD alone), or any other one- or two-character separator of your choice.
Examples of the ADJUST parameter: suppose you had records with a NAME element, a DEPT element, and a multiply-occurring ACCOUNT element. The command
SET FORMAT $REPORT Name (1,18,RIGHT) SET FORMAT * + Dept (20,10,CENTER) SET FORMAT * + Accounts (30,22,BUILD = ', ')
creates a display as follows:
+--------------------------------------------------------------+ | Feb. 10, 1988 Page 1 | | | | Name Dept Accounts | | ------------------ ---------- ---------------------- | | Bob Smith ACCT GA.ABC, GE.ABC, HK.ZYX | | Lloyd Smith FINA AU.ABC, AU.XYZ | | Ben Smith ACCT GQ.PRG, GP.ETC, GR.EDC | | GT.TYU | +--------------------------------------------------------------+
If the last line of the previous report definition were
SET FORMAT * + Accounts (30,20,ALIGN,BUILD,CENTER)
the display would look like this:
+--------------------------------------------------------------+ | Feb. 10, 1988 Page 1 | | | | Name Dept Accounts | | ------------------ ---------- ---------------------- | | Bob Smith ACCT GA.ABC, GE.ABC, HK.ZYX | | Lloyd Smith FINA AU.ABC, AU.XYZ | | Ben Smith ACCT GQ.PRG, GP.ETC, GR.EDC | | GT.TYU | +--------------------------------------------------------------+
This parameter is used to control indentation of values that wrap to multiple lines. If you specify both INDENT and an ADJUST of LEFT, RIGHT, or CENTER, the ADJUST parameter is ignored. If you specify an INDENT value for an element that also has ADJUST=ALIGN, the multiple rows of concatenated values are treated as a single paragraph. So only the first line of the set of aligned values is indented.
The INDENT keyword is followed by an integer that determines the type and amount of indentation. If the number is positive, then the first line is indented that many spaces, and the rest of the lines begin at the column's starting position. If the number is negative, the value starts in the first position of the column defined for the element and continuation lines are indented the number of spaces specified to create a hanging indent.
For example,
INDENT = 3
creates a value indented as follows:
-------------
----------------
----------------
and
INDENT = -3
creates a value indented like this:
----------------
-------------
-------------
The column width, as determined or computed based on COLUMN and WIDTH values, does not change.
The columns of your report are labeled with the name of the element that you specified in the element list and separated from the data with a dashed line. The case of the element name in the list is kept, so that a form of the element name in mixed upper-lower case may be specified. If the heading is longer than the column width, it is truncated.
If, however, you want the column labeled with something other than an element name or alias, use the HEADING keyword in the parenthesized parameter list. For example:
SET FORMAT $REPORT NAME (1,20,HEADING = Participant)
The column is now labeled "Participant" rather than "NAME". The column heading may be up to 36 characters long; if longer, it is truncated.
Up to three parts may be given, separated by double slashes, each to appear on a different row in the heading. The three parts added together may be up to 36 characters (not including the "//"). The number of rows used for the report's column headings is determined by the maximum number of rows used in any single column.
The entire heading value must be surrounded by quotation marks or apostrophes if any part of it contains blanks, commas, equal signs, slashes, apostrophes, or quotation marks. Leading and trailing blanks are retained, allowing you to position the heading within the column space. Headings are right-, left-, or center-adjusted if the corresponding elements have adjustments specified.
For example:
SET FORMAT $REPORT NAME (1,16,HEADING = "Name//of Participant") SET FORMAT * + HRS (20,16,HEADING = 'Number of//Hours//Per Week'
creates the following display:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Name Number of | | of Participant Hours | | Per Week | | ---------------- ---------------- | | Smith, B. 35 | | Carter, S. 16 | | Johnson, K. 5 | +--------------------------------------------------------------+
If you have a multi-row record display, all the column headings are stacked at the top of the body of the report, and each row's headings are underlined.
If you wish to change the line separating the column headings from the element values to something other than a dashed line, use the UNDERLINE parameter of the OPTIONS command, specifying the character you wish to use in the line. [See C.4.5 for details about the OPTIONS command.] For example,
SET FORMAT * OPTIONS UNDERLINE = *
creates a separating line of asterisks instead of a line of dashes. By specifying UNDERLINE = ' ', you can replace the underline row with a blank line. By specifying NOUNDERLINE, you can eliminate the underline row completely (i.e., no blank line).
If you wish to eliminate the heading for an individual element, but retain the separating line, set the heading to blank, e.g., NAME (HEADING = ' ').
To eliminate the heading for a single element, set the HEADING parameter to null for that particular element, e.g., NAME (HEADING = '').
You can eliminate all column headings and the separating line by including the NOHEADING parameter on an OPTIONS command, as follows:
SET FORMAT * OPTIONS NOHEADING
If you have numeric values to be displayed and wish them to appear in a consistent format not provided for in the file definition (via the $EDIT proc or element information packets), you can specify an edit mask for the value in the parameter list for that element. Some examples are:
ELEMA (EDIT = 'ZZZ.99') ELEMA (EDIT = 'ZZZ/-2') ELEMA (EDIT = '$99.99/+2')
The value following the slash specifies an explicit decimal shift (like the "divisor" parameter for the $EDIT function and proc) that moves the decimal to the right (if the value is negative) or left (if the value is positive) from its implied stored value.
For example, the display of a large budget figure might be specified as follows:
ELEMX (EDIT = 'ZZ,ZZZ/-3',HEADING = 'DOLLARS//IN THOUSANDS')
When an edit mask is in effect, the default for ADJUST is RIGHT. If you have an edit mask that creates trailing blanks (such as 'ZZ,ZZZ.99-' or 'ZZZDB') you must be aware that if you also specify an ADJUST value, then all leading and trailing blanks are ignored when placing the value in the column. In order to properly align values with trailing blanks, you must define your edit mask to be the same width as the column and let the edit mask handle the adjustment of the value within the column rather than specifying a separate ADJUST value.
The edit mask specified here in the element list applies not only to individual element values, but also to summary function values such as totals or averages, unless overridden by an edit mask for a specific function (column-bound functions only). [See C.6.5 for explanations of summary functions.]
If the column width is narrower than the edit mask specified with the EDIT parameter, the column is automatically widened to fit the edit mask.
EXPLAIN EDIT MASKS or see Chapter 19 in "Technical Notes" for more information about edit masks.
For some $REPORT features, it may be important or useful to let $REPORT know what type of element to expect, in particular, whether the element's values are numeric or text. For instance, you can request globally that all numeric elements be right-adjusted, or that all text elements be justified, unless overridden by the element's specific parameters.
Or, for perhaps a more significant example, if you are creating a report to download data from SPIRES to a microcomputer program (e.g., a spreadsheet program like Lotus 1-2-3 or Microsoft Excel) where you need all text fields to be quoted, you can tell $REPORT globally to quote all text elements -- but you also need to identify the text elements.
To do that, add the TYPE parameter to the element parameter list:
TYPE = {NUMERIC|TEXT}
For example,
SET FORMAT $REPORT Name (Type=Text) Hours (+2,Type=Numeric)
establishes the Name element as a text field, and the Hours element as a numeric one.
You may also specify the type in the parameters for print expressions and for functions. [See C.5.2, C.6.5.]
The type may also be set for an element in element information packets. [See C.4.6.]
In horizontal reports, when an element doesn't occur, the space where its value would be printed remains blank. In vertical reports, no line appears where that element would be displayed.
With the DEFAULT parameter, you tell SPIRES to print a string of your choice (such as "None" or "0") as the value for the current element if it does not occur. That is often useful when the output from your report will be used as input data for another process, which is counting on receiving a value for every element or field.
The DEFAULT parameter is available on an element-by-element basis as described here or on a global basis for all elements in the report. [See C.4.5.5.]
For an individual element, add the DEFAULT parameter to the element's parameter list:
DEFAULT = 'string'
The value is a string you specify. If it is a single word that contains no special characters, you may omit the apostrophes (or quotation marks).
If you have both a global DEFAULT option set and an individual element default set, then the individual one will override the global one for the specific element.
Here is an example:
-> set format * name(1,30,default='Unknown')
The value "Unknown" will be supplied when the NAME element does not occur.
Remember that DEFAULT is for elements that have no occurrences. In some SPIRES subfiles, elements may have "null" occurrences -- that is, the element occurs but has a value whose length is 0 characters. So a null occurrence will not trigger default processing. (You may be able to circumvent that, i.e., put some value out, by redefining the element as a dynamic element, e.g., "DEFINE ELEMENT XORDERED FOR ORDERED AS 'Yes'" so that if the element ORDERED occurs, the dynamic element XORDERED will have the value "Yes".)
Also, remember that if you assign a DEFAULT parameter to an element within a multiply occurring structure, then the default value will be displayed once for each time that the structure occurs but the element does not occur within that structural occurrence. If the structure does not occur, the default value for the element within the structure will not be displayed at all by $REPORT.
Normally, when an element is included in a report, each occurrence of that element appears on a separate row (except with ADJUST=ALIGN). However, you may request only a single summary value representing all occurrences of an element in the record. This kind of value summarization within a record is specified by including a function name in the element's parameter list that indicates the type of summarization desired. Available functions are SUM, COUNT, AVERAGE, MINIMUM, MAXIMUM, STD. [See C.6.5.]
For example, the following report displays all occurrences of the specified elements:
SET FORMAT $REPORT Account(1,7) Units(10,5,RIGHT) Amount(17,6,RIGHT)
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Account Units Amount | | ------- ----- ------ | | Mason 1 $1.95 | | 12 $20.50 | | 7 $12.70 | | Starr 3 $7.22 | | 9 $15.40 | +--------------------------------------------------------------+
But, if we include function names in the parameter lists, we get a different display:
SET FORMAT $REPORT Account(1,7) Units(10,10,SUM,R) Amount(22,11,AVG,R)
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Account Units(SUM) Amount(AVG) | | ------- ---------- ----------- | | Mason 20 $11.72 | | Starr 12 $11.31 | +--------------------------------------------------------------+
Notice that the default column heading now includes the name of the function in parentheses after the element name.
Summarization is to the record level and includes all values from the record (unless element filters are set) regardless of their distribution across structure occurrences. It is not currently possible to perform intermediate totalling to structural levels using $REPORT.
If you want to summarize values to an intermediate level across groups of records, these values can be computed with the DEFINE VALUE command, and can then be manipulated as regular elements. [See C.6.7.] Summary values can also be generated across groups of records by specifying functions in the END OF GROUP section [See C.6.4.] or for the entire report with the END OF REPORT section. [See C.8.2.]
For more details about creating summary reports, see Section C.8.
The OPTIONS command allows you to set several report-level options. You've already seen how this command can be used to change the column headings. [See C.4.3.5.] Some of the other things you can do with the OPTIONS command are change the line length, indent the left margin, create a summary report or create a vertical report.
The basic syntax is:
SET FORMAT * OPTIONS option, option, ....
The options can be given in any order and anywhere in the report definition. [See C.3.4.4 for a list of all possible options.]
The following sections describe some options that affect the DETAIL section. [See C.4.7 for the VERTICAL option.]
A single record display is not, by default, broken across page boundaries. You can change this and allow records to be broken by including the BREAK option as follows:
SET FORMAT * OPTIONS BREAK
The NOBREAK parameter reverses this.
This only applies to reports that are placed in the active file and, thus, have carriage control. Otherwise, the option is ignored.
If the number of lines per page is less than the number of lines in a particular record, that record must be broken regardless of whether or not the NOBREAK option is in effect.
If a single record might exceed 100 lines, you must include the MAXROWS option to raise this limit. For example,
SET FORMAT * OPTIONS MAXROWS = 200
allows a single element occurrence to take up to 200 lines to be displayed.
An S808 error occurs if you attempt to display a record that would take more than the specified number of lines.
Note that a slight efficiency gain may be achieved by setting this limit to less than 100.
You might sometimes want to place elements in columns, but have no column headings, no carriage control, and no page header or footer. This allows you, for example, to put values in columns that can then be used as input to another program, such as a statistical package.
For one way to do this, use the NOREPORT parameter on the OPTIONS command, as in the following example:
SET FORMAT $REPORT DEPT (1,15) NAME (20,15) SALARY (40,10) MOS.EMP (55,5) SET FORMAT * OPTIONS NOREPORT
The resulting display looks like this:
+--------------------------------------------------------------+ | Zippers Karla Olsen 15000 13 | | Zippers Wally Berg 15000 16 | | Zippers Susan Schmoo 18000 15 | | Buttons Gigi Grinder 25000 23 | | Buttons Hank Dane 25000 32 | | Buttons Hugh Dew 18000 14 | +--------------------------------------------------------------+
All groupings and group summarizations still take place. For example,
SET FORMAT $REPORT DEPT (1,15) NAME (20,15) SALARY (40,10) MOS.EMP (55,5) SET FORMAT * GROUPED BY DEPT SET FORMAT * AT END OF GROUP DEPT AVG SALARY SET FORMAT * OPTIONS NOREPORT
produces the following display:
+--------------------------------------------------------------+ | Zippers Karla Olsen 15000 13 | | Zippers Wally Berg 15000 16 | | Zippers Susan Schmoo 18000 15 | | | | *AVG 16000 | | | | Buttons Gigi Grinder 25000 23 | | Buttons Hank Dane 25000 32 | | Buttons Hugh Dew 18000 14 | | | | *AVG 22666.667 | | | | **AVG 19333.333 | +--------------------------------------------------------------+
Note that this is different in effect from the SPIRES command CLEAR REPORT. When the CLEAR REPORT command is issued, group summarization is also cancelled.
A similar effect can be achieved with the NOPAGE option, which eliminates the page headers and footers, the carriage control, and all but the very first appearance of the column headings in a horizontal report:
SET FORMAT * OPTIONS NOPAGE
Hence, its primary difference from NOREPORT is that it retains the column headings. For vertical reports, it has the same effect as NOREPORT.
If you are experimenting with the NOPAGE option, you can turn paging back on with the PAGE option:
SET FORMAT * OPTIONS PAGE
Sometimes, you might want to place records together to make them easier to read on the page. The CLUSTER option allows you to group records arbitrarily, according to the number of records (not the number of lines) displayed. For example,
SET FORMAT * OPTIONS CLUSTER = 5
inserts a blank line after every five records. Clustering begins again at each new group. [See C.6.1.]
An interesting use of the CLUSTER option is to specify "CLUSTER=1". This places a blank line between each record, so that you do not have to specify a blank line at the beginning or end of your DETAIL definition.
For vertical reports, the default value of CLUSTER is 1 rather than 0 -- that is, every record is separated from the next by a blank line. [See C.4.7.]
In horizontal reports, when an element doesn't occur, the space where its value would be printed remains blank. In vertical reports, no line appears where that element would be displayed.
With the DEFAULT option, you call tell SPIRES to print a string of your choice (such as "None" or "0") as the value for elements that don't occur. That is often useful when the output from your report will be used as input data for another process, which is counting on receiving a value for every element or field.
The DEFAULT option is available on an element-by-element basis [See C.4.3.8.] or on a global basis as described here.
DEFAULT is one of the options of the OPTIONS statement. Its syntax is:
OPTIONS DEFAULT [ALL|TEXT|NUMERIC] = 'value'
The value is a string you specify. If it is a single word that contains no special characters, you may omit the apostrophes (or quotation marks).
If you include the NUMERIC option, only elements designated as type NUMERIC will be affected. (Note that an element whose VALUE-TYPE info-element is NUMERIC would be affected too.)
If you specify the TEXT option, then any element not designated as NUMERIC will be considered a "text" element for the purposes of this option. See the example below.
You can set all elements to the same default string by using the ALL option, which is the default if you don't type any of the three choices in the command.
You can turn off DEFAULT value processing with the NODEFAULT option.
Here are some examples:
SET FORMAT * OPTIONS DEFAULT = 'None'
The value "None" will be supplied for any element that does not occur.
SET FORMAT * OPTIONS DEFAULT = 'None' SET FORMAT * OPTIONS DEFAULT NUMERIC = '0'
The value "0" will be supplied for any element declared as NUMERIC that doesn't occur; any other element that doesn't occur will get the value "None".
Remember that DEFAULT is for elements that have no occurrences. In some SPIRES subfiles, elements may have "null" occurrences -- that is, the element occurs but has a value whose length is 0 characters. So a null occurrence will not trigger default processing. (You may be able to circumvent that, i.e., put some value out, by redefining the element as a dynamic element, e.g., "DEFINE ELEMENT XORDERED FOR ORDERED AS 'Yes'" so that if the element ORDERED occurs, the dynamic element XORDERED will have the value "Yes".)
Be aware that SPIRES will use whichever DEFAULT statements are in effect at the time the report is displayed to provide defaults for all elements. In other words, you can't change from one DEFAULT TEXT string to another mid-way through the report; the latter string will be used as the default value for all text elements when the report is displayed. So basically there are two DEFAULT strings: one for NUMERIC elements, and another for all the rest (the TEXT elements). If you use the ALL option, you will set both strings to the same value. But you can't have two different NUMERIC strings in the same report.
Each element you position in the detail section (as well as print values or functions in the detail section or others) may include an "adjust" specification, for instance, to center the value within the column available for it. The ADJUST option lets you set the adjustment globally for all values being positioned, or for all text or for all numeric values.
It is part of the OPTIONS statement. Its syntax is:
OPTIONS ADJUST [TEXT|NUMERIC] = one-or-more-adjustments
where the adjustments are:
LEFT|RIGHT|CENTER|JUSTIFY|WRAP|MARGINS|TRUNCATE|ALIGN
In some cases, you would specify only a single adjustment. However, you can combine either WRAP, MARGINS (which mean the same: wrap long values into multiple rows), TRUNCATE or ALIGN with LEFT, RIGHT or CENTER. You may abbreviate each of the adjustment values down to any length, one character or more. [See C.4.3.3 for more information about the adjustment options.]
If you include the NUMERIC option, only elements designated as type NUMERIC will be affected. (Note that an element whose VALUE-TYPE info-element is NUMERIC would be affected too.)
If you specify the TEXT option, then any element not designated as NUMERIC will be considered a "text" element for the purposes of this option.
The ADJUST option must be specified prior to any data placement commands; once it has been set and you have begun placing data, it cannot be changed. However, you can override the global default adjustments at any time for any element by entering an ADJUST parameter for it.
Note that your single setting here overrides all the default settings. In other words, if you set ADJUST=LEFT as an option, you override the default of ADJUST=LEFT,WRAP.
Similarly, if you use the ADJUST parameter on an element, it completely overrides the ADJUST option rather than combines with it.
When SPIRES is determining how to position your elements in the detail row, it by default leaves two blank character positions between one element and the next. The two blanks are called the "gap". The GAP option lets you set the gap's width globally for all values being positioned.
GAP is part of the OPTIONS statement. Its syntax is:
OPTIONS GAP = n
where "n" is an integer from 0 up.
The gap between any two elements can be controlled explicitly with the starting position and the width of each element. Explicit positioning always overrides the GAP value. [See C.4.3.1, C.4.3.2.]
Several options that affect the data in the detail option were designed especially for use in creating data files that copy data from a SPIRES subfile for importing into a microcomputer program, such as a spreadsheet program like Lotus 1-2-3 or Excel. While it is not inconceivable that you might find other uses for them, it is worth discussing them together in the context of downloading. Note that they don't seem very useful with vertical reports -- though again, you may have other ideas. [See C.4.7.]
You may be creating a report that will be used as input to a spreadsheet program that expects that the data to be imported will be arranged one record per row, with a tab character between fields. You might begin your $REPORT format like this:
-> set format $report option adjust=truncate
You are willing to risk losing some data that would normally wrap into another row of the report -- if it were to wrap in this report, it would become a separate line item in the import data. [See C.4.5.6.] If you use the SQUEEZE option (described below), you may not want the adjust=truncate option because SQUEEZE will not wrap long values. [See C.4.3.3.]
Next you might add the following:
-> set format * option nopage
That will eliminate all page control, page headers and footers, and all but the very first appearance of the column headings. In other words, it will make the first row (or rows) of information in the output be column headings, but once the data from the records begins, there will be no interruptions for printed-page features. [See C.4.5.3.]
Next, you might want to issue a command to set the "delimiter" character, that is, the tab character you want placed between each field, to delimit the fields for the microcomputer program.
-> set format * option delimiter=x'05'
The delimiter character must be either a single character, as in DELIMITER = '*', or the EBCDIC hex representation of a single character, as shown in the example above: the hex 05 is a tab character.
After you issue a command for your record elements, e.g.,
-> set format * elements ID(1,10) Name(+2,40) Hours(+2,5)
you might take a look at a couple records:
ID *Name *Hours ---------- *---------------------------------------- *----- 59433921 *Chandler, Stewart *13 95206650 *Chandler, Adam *8
(In the example display, we substituted the "*" for the tab character, which would not be visible. However, tabs would be in the data at the positions where the asterisks are.)
Note that the delimiter does not count in any width or positioning calculations -- there are still 2 gap columns between each field, and the length of the Name field is still 40 columns. In other words, if the overall width of your 5-column report without a delimiter would be 75 characters, it will be 79 characters (75 plus 4 delimiters to delimit the 5 columns), even if you set the width of the report to be only 75.
You can "unset" the delimiter by setting it to a null character, e.g., DELIMITER=''.
The delimiter may affect data in some other parts of the report if you have them, including the start of group, end of group and end of report sections. It does not affect the data in the top of page or bottom of page sections. But again, the DELIMITER feature is meant for use with creating data sets to import into other programs, where you are probably interested only in creating detail lines.
An option that is often useful in conjunction with DELIMITER (and QUOTE, discussed below) is SQUEEZE, to eliminate the extra blank spaces between the values (though not within the values):
-> set format * option squeeze
The same records above would now look like this:
ID*Name*Hours ----------*----------------------------------------*----- 59433921*Chandler, Stewart*13 95206650*Chandler, Adam*8
The SQUEEZE option should be given before you define the elements to be output. That's because SQUEEZE affects positioning, just like STYLE and VERTICAL. SQUEEZE also eliminates the need for ADJUST=TRUNCATE, unless you really want to truncate fields. [See C.4.3.3.]
You can unset the SQUEEZE option with the NOSQUEEZE option.
Some microcomputer programs require that the imported data fields be surrounded by quotation marks to demark them. The QUOTE option can handle this requirement.
SET FORMAT * OPTIONS QUOTE [ALL|TEXT|NUMERIC]
In our continuing example, if we unset the delimiter and the SQUEEZE option and then set QUOTE for all (the default when QUOTE is specified), we'll get something that looks like this:
-> set format * option nosqueeze delimiter='' -> set format * option quote -> type "ID " "Name " "Hours" "----------" "----------------------------------------" "-----" "59433921 " "Chandler, Stewart " "13 " "95206650 " "Chandler, Adam " "8 "
If you include the NUMERIC option, only elements designated as type NUMERIC will be affected. (Note that an element whose VALUE-TYPE info-element is NUMERIC would be affected too.)
If you specify the TEXT option, then any element not designated as NUMERIC will be considered a "text" element for the purposes of this option.
It is common to use both SQUEEZE and QUOTE options with "Tab-Delimited Data" and "Comma Separated Value" forms of output. You use DELIMITER=X'05' or DELIMITER=',' along with SQUEEZE and QUOTE.
If your report contains groups, you may want to eliminate the GROUPED BY statement, or, if you want to keep it for some reason, you may want to use the DISPLAY option on the GROUPED BY statement so that the group value does not get suppressed on subsequent rows after its first appearance. [See C.6.1.2.]
The DEFAULT option may also be useful to force a value such as "None" when an element does not occur. As was hinted above, some microcomputer programs do not want any fields of import files to have missing values. [See C.4.5.5.]
Several options used for downloading are set at one time using the STYLE option. [See C.4.5.8.]
There are four styles currently defined, all of which must be given before you define the elements to be output. That's because the STYLE options affect positioning. All styles set VERTICAL to False, SQUEEZE to True, Number Adjust to Right, and they cause recalculation of positions. The four styles are:
-> set format $report option style=BTF -> set format $report option style=DELIM -> set format $report option style=FIXED -> set format $report option style=WFIXED
BTF uses vertical bars as delimiters (|), and is used by Wylbur's QUERY output. DELIM uses tab characters as delimiters (x'05'), as used by Excel. FIXED and WFIXED do not insert delimiters. FIXED outputs fixed-columns, no wrap. WFIXED outputs fixed-columns with wrapping, $REPORT's default behavior.
You may follow and STYLE specification with your own redefinition of a DELIMITER, such as:
-> set format $report option style=BTF,DELIMITER='%'
Many of the element parameters used by the $REPORT format can be predefined by the file owner in element information packets. This means that you do not have to specify these parameters in the report definition. For example, the file owner might include a width specification of "15" for a particular element. Whenever this element is displayed using the $REPORT format, the width of the element's column is 15. This can be overridden, however -- including a width parameter for the element in the report definition is one way, or using the NOELEMINFO option in the report definition is another.
The element information packets, then, are used by the file owner to establish default settings for the display of elements. This makes it easier for the user to create simple, attractive reports on an ad hoc basis without having to take the time and trouble to specify display parameters for each element. But you as the report definer can override these defaults and define the report to fit your specific needs.
The info-elements that are used by $REPORT are:
Although there are other possible values for VALUE-TYPE as an info-element, $REPORT is only interested in TEXT or NUMERIC.
In order to find out if the file owner has included any element information for the subfile, issue the SHOW ELEMENT INFORMATION command. This displays a list of all the information available as in the following display:
-> show element information
Subfile ALMANAC
Element DAY
Element NAME, N -- Name
Note: Name of celebrant
Width: Adjust: Indent: -2 Edit:
Index: NAME
Description:
This is the name of the person being commemorated.
(the display continues)
This display shows you that there is no information defined for the DAY element; but for the NAME element there is an INDENT value, so you do not have to specify an INDENT value in your report definition if you want to use the predefined value.
Only the file owner can add this information to the subfile, so if none exists, you have to include all the information in the parameter list for each element in the report definition. (The exception to this is if you use the DECLARE ELEMENT command to define your own dynamic elements for the subfile. EXPLAIN DECLARE ELEMENT COMMAND for more information.)
You may want to summarily prevent SPIRES from using any information packets that may be defined for the elements you plan to use in your report. To do that, you would set the NOELEMINFO option prior to any references to element placement in the report definition:
SET FORMAT * OPTION NOELEMINFO
You may turn element information on and off on a local basis too. For example, if you set the NOELEMINFO option after specifying several elements in the report, those elements will use element information, and subsequent elements will not. You can turn element information use back on with the ELEMINFO option.
With the $REPORT format, you can choose between two basic layouts for the elements in the detail section. The most common is what you've seen the most in this chapter: the elements displayed across the line, in table fashion, sometimes called "horizontal report layout":
ID Name Favorite Scent -------- ---------------- ------------------------ 94523404 Chung, Constance Channel no. 5 59323911 Johnson, Donald English Leathermen
But another layout you can choose is "vertical layout", where each element with its heading appears on a separate line:
ID: 94523404 Name: Chung, Constance Favorite Scent: Channel no. 5 ID: 59323911 Name: Johnson, Donald Favorite Scent: English Leathermen
An element's heading occurs only once when multiple occurrences (together in the same structural occurrence or at record-level) are displayed:
ID: 69504334
Name: Simpson, Homer
Favorite Scent: Taco Raban
Paternity
To request vertical reporting instead of the default horizontal layout, you specify the VERTICAL option:
SET FORMAT $REPORT OPTION VERTICAL
You must specify the VERTICAL option prior to any data placement commands, so generally, you will use this option right on the SET FORMAT $REPORT command, rather than on the following "SET FORMAT *" commands. (There is a HORIZONTAL option too, but it is not needed since horizontal reporting is the default.)
So a simple vertical report, such as the one in the example above, would have a definition something like this:
-> set format $report option=vertical -> set format * id name fave.fragrance(heading='Favorite Scent') ->
The detail area of the report in essence consists of two parts side by side: the heading area on the left, and the value area on the right. The headings for each value come from its HEADING parameter, or from the HEADING info-element for the requested element, or from the element name as specified in the $REPORT command.
The widths of these areas, and the width of the whole area of the report, are determined by the following formulas:
Width of the report: whichever of these 2 is larger:
$LENGTH ("SET LENGTH n")
or
Heading area + 2 + Value area
Width of heading area: maximum of all heading widths (up
to 36 characters) + 1 (for colon)
Width of value area: whichever of these 2 is larger:
$LENGTH - Heading width - 2
or
maximum sum of each value's width
plus its starting position - 1
Here is an example to show how the vertical report width is determined:
-> set format $report option=vertical -> set format * name (width=25,heading='Name') -> set format * + fave.fragrance(5,60,heading='Favorite scent')
Suppose the user's current value for $LENGTH is 72.
Starting with the heading area, the two headings are "Name" and "Favorite scent". The longest is 14 characters long. Add one character for the colon at the end, and the heading area becomes 15 characters wide.
By default, the width of the value area would be the value of $LENGTH (72) minus the heading area width (15) minus two characters for the gap between the areas -- so the default width would be 55. However, the maximum allowed width for the FAVE.FRAGRANCE element is 60, and it starts in column 5; following the formula above, the value area for FAVE.FRAGRANCE would require 60+5-1 characters, or 64, so that is the overall width for the value area.
That means the total report width is the heading width (15) plus the gap (2) plus the value width (64) for a total of 81 characters wide.
In most cases, if you place two elements from the same multiply-occurring structure into the report, you want them the values in the same structural occurrence to be displayed together. For example, suppose the elements CITY and STATE are in a multiply occurring LOCATION structure:
-> set format $report option vertical -> set format * name city state -> display 32 name: Fresh Choice city: Palo Alto state: CA city: Menlo Park state: CA
All the occurrences of CITY and STATE within the first occurrence of LOCATION print first, followed by the occurrences of CITY and STATE within the second.
As long as the structural elements are together in the list of elements, the structural binding will be kept. However, if you separate them by other elements outside of the structure, you will get a very different result, with all occurrences of CITY together and all occurrences of STATE together:
-> set format $report option vertical -> set format * city name state -> display 32 city: Palo Alto city: Menlo Park name: Fresh Choice state: CA state: CA
This is different from horizontal reports, where structural binding is still maintained even when the structural elements are separated by others on the row. [See C.4.2.2.]
In general, most options in $REPORT work the same way for vertical reports as for horizontal ones. Here are differences, along with other details to know about vertical reporting. These are the differences with regard to the detail section; there are some differences in group sections as well, discussed in a later chapter. [See C.6.8.]
Starting columns for a value are not usually specified. They are measured within the value area only and neither affect nor count the heading area. So if your specification looks like this:
-> set format $report option=vertical -> set format * name (heading='Name') -> set format * + fave.fragrance(5,heading='Favorite scent')
Your output might look like this:
Name: Chung, Constance Favorite Scent: Channel no. 5
You can specify either absolute column numbers, as in the example above, or relative, positive ones (e.g., "+2", meaning two columns further to the right than the previous element). You cannot do relative, negative ones (e.g., "-2"). [See C.4.3.1.]
These three parameters work the same as they do in horizontal reports. [See C.4.3.2, C.4.3.3, C.4.3.4.]
As shown above, the HEADING parameter affects the width of the heading area and it can affect the width of the value area as well, taking space away from the value area as it expands. The maximum heading length is 36 characters.
In a vertical report, if no HEADING is specified, $REPORT will look for the HEADING info-element for the element, not the COL-HEADING info-element that it uses in horizontal reports. If no HEADING info-element can be found, it will use the element name as typed in the $REPORT command. [See C.4.3.5.]
The NOREPORT option suppresses the heading part of the detail area, shifting its contents to the left. It resets the width of the heading area to 0, so the default element data width goes up accordingly. If you want to use it, it is recommended that you issue this option before any data placement $REPORT commands.
The NOHEADING option blanks out the heading part of the detail area. [See C.4.3.5.]
The CLUSTER option, which defaults to CLUSTER=0 for horizontal reports, defaults to CLUSTER=1 for vertical ones, meaning that a blank line separates each record. If you specify CLUSTER=2, then a blank line will appear only between each pair of records (i.e., two records, one blank line, two records, one blank line, etc.) [See C.4.5.4.]
See the discussion in the chapter on "Grouping". [See C.6.8.]
The following options work the same way in both horizontal and vertical reports.
PAGE|NOPAGE UNEDIT|NOUNEDIT ADJUST DEFAULT ELEMINFO|NOELEMINFO
The options below are ignored in vertical reports. It is possible that they may have a meaning in future versions of SPIRES.
UNDERLINE|NOUNDERLINE GAP
The following options are not ignored by $REPORT in vertical reports, but they were designed for use in horizontal reporting, and their effect on vertical reports sometimes borders on the bizarre. Since they might be changed to do something more useful in a future version of SPIRES, we discourage you from growing attached to them if you choose to try them out.
SQUEEZE DELIMITER QUOTE
Additionally, there may be useful ways to employ the features of multi-row record display for horizontal reports in a vertical report (that is, using AT START OF DETAIL, IN ROW n, for example) but they were not designed for vertical reports. [See C.5.3, C.5.4.]
This chapter describes those commands that can be issued in any section. For the most part, they function the same in every section, but any differences are noted.
The NEWPAGE command, when given as the first command in a section, forces that section to begin on a new page -- i.e., causes a page break -- by placing a "1" in column one of the output at that point.
The FRONTPAGE command, when given as the first command in a section, forces that section to begin on the front side of the next piece of paper, which might mean leaving the back side of the previous sheet blank. Technically, FRONTPAGE causes a page break by placing an "F" in column one of the output.
Each command affects only output that is placed in the active file; it does not affect online display of the report.
The command must always be the first command to occur in a section; thus it cannot be used to cause a page eject in the middle of a section. It is also not allowed in the START OF PAGE or END OF PAGE sections.
If placed in the START OF REPORT section [See C.8.1.] NEWPAGE or FRONTPAGE causes a "1" or "F" to be placed in column one at the very beginning of the report. Otherwise, no carriage control would be included at the beginning of the report.
Most commonly, you would use either command to ensure that a specified group of records begins on a new page. Thus, for example, if you have grouped your records by project and want each new project to begin on a new page, you could accomplish this by issuing the command
AT START OF GROUP PROJECT, NEWPAGE
If you want all summary information for a group to begin on a new page, include the NEWPAGE command at the beginning of the END OF GROUP section.
You can turn this feature off with the command NONEWPAGE.
You can set or reset the page numbering of a report by specifying an integer value to accompany the NEWPAGE or FRONTPAGE command, in the form "NEWPAGE=n" or "FRONTPAGE=n", where "n" is the new starting page number. For example, in a large report grouped by department, you could cause each group to begin at a brand new "page one" by issuing a command like the following:
AT START OF GROUP DEPT, FRONTPAGE=1
This feature would be useful if you needed to break one large report into smaller pieces that could each be distributed as a separate report. In the example above for GROUP DEPT, each separate departmental section might be detached into a separate report and distributed to that particular department.
The PRINT command places an expression in a section. The syntax is:
PRINT [(parameters)] expression
The parameters specify positioning and display of the PRINT expression and are similar to the positioning parameters for elements. Each parameter is described in detail below.
The expression can be any one or a combination of the following:
- Literal strings. Strings with special characters must be enclosed in quotation marks or apostrophes. This includes text with embedded blanks; otherwise the words are interpreted as a series of concatenated strings. Some examples are:
PRINT "Monthly Report"
PRINT MONKEY
PRINT '25%'
- Variables. User and system variables are allowed. User variables, dynamic or static, are valid but must be defined both at report definition and execution time; variable substitution takes place at execution time. Refer to the manual "SPIRES Protocols" for information about variables. Some examples are:
PRINT $DATE
PRINT #LAST.NOTE
PRINT 'Page: ' $PAGENO
- Element values. You may refer to data elements in PRINT expressions in all sections except AT START OF REPORT. In DETAIL sections, the element value is, of course, retrieved from the current record. The element's value is retrieved from the first record in the group or on the page for starting (i.e., AT START OF...) sections, and the last record in the group or on the page for ending (i.e., AT END OF...) sections. Only the first occurrence of multiply-occurring elements is retrieved. You may use element filters to control which occurrence is retrieved. (See functions below for another work-around.) You must use the "@element" (internal form of value) or "@@element" (external form of value) forms to specify that you want the element's value to be displayed; otherwise, the element name is interpreted as a literal string. Remember to enclose your element name in apostrophes or quotation marks if the name contains a hyphen or plus-sign. Some examples are:
PRINT @NAME
PRINT @@HRS
PRINT @@'HRS-CHARGED'
PRINT @DEPT ': ' @PROJECT
- Functions. You may use SPIRES functions to manipulate or transform values. Refer to the manual "SPIRES Protocols" for information about functions. You can use the $GETxVAL functions to retrieve element values other than the first occurrences, for example; or use the various string manipulation functions to change the retrieved element values, such as $CAP. Some examples are:
PRINT $CAPITALIZE(@@name)
PRINT 'Section ' $LEFTSTR(@@name,1)
PRINT '2nd address line: ' $GETXVAL(address,1,'none')
- Mathematical expressions. You can calculate values using the four basic mathematical operators: "+" (addition), "-" (subtraction), "*" (multiplication), "/" (division). Some examples are:
PRINT @HRS + 8
PRINT #NUM - #LAST.NUM
PRINT @SALARY * 12
If more than one item is included in an expression, the expression is evaluated left to right unless parentheses are included. For example,
PRINT 'Value: ' #NUM - #LAST.NUM
causes an error because the string 'Value: ' is concatenated to the value of #NUM before the subtraction operation is attempted. But if parentheses are included, all expressions within parentheses are evaluated first, before the complete expression is evaluated left to right. The above expression is correctly written as:
PRINT 'Value: ' (#NUM - #LAST.NUM)
If more than one command appears in a statement, the PRINT command must be the last command. For example,
SET FORMAT * SKIP 4, SUM HOURS (30,1), PRINT (1,7) 'The End'
If you do not include a parameter list to specify the position for the expression, it is placed in the current row; if it is the first item to be placed on this row it begins in column 1. If more than one PRINT expression is placed on a row with no column positioning specified, they are spaced out evenly on the row, just as element columns are.
If you put PRINT expressions and element values on the same row in the DETAIL section, the columns are evenly spaced across the row in the order in which they were specified in the report definition. If you use the SKIP command [See C.5.4.] to specify relative placement of items, this default positioning is changed. See the discussion of vertical binding in Section C.5.5.
Up to three expressions may be placed at once, separated by "//" (i.e., PRINT expression1//expression2//expression3). They are left-, center-, and right-adjusted on the row. If an expression contains blanks or special characters, it must be enclosed in apostrophes. For example,
PRINT 'Project Scope'//CLEANUP//'Staff Requirements'
The expressions count as three statements when figuring limits.
Your complete report can have no more than 64 literals or expressions. PRINT expressions, LABEL expressions, and literals in the element list all count in this limit. [See C.6.6, C.4.2.4.]
There is also a limit on the length of any one PRINT expression. When your PRINT expression is evaluated and converted into an internal form (using $GETUVAL and $GETCVAL functions) that expression can be no more than 132 characters. In figuring these limits, you can use this guideline to determine if your PRINT expression approaches that limit: any element reference in your PRINT expression (@element or @@element) counts as 29 characters in its internal form. If you need to use a longer expression, you can create a dynamic element and reference it in the PRINT expression. [See C.4.2.3.]
The PRINT command may be followed by a parenthesized parameter list, which includes specific location and formatting instructions. It must appear between the PRINT command and the expression. The parameters are:
AT END OF DETAIL PRINT (Heading='2nd place') $GETXVAL(place,1) 2nd place: Miss Liechtenstein
The following example places an element value in the upper right-hand corner of the page. This value is taken from the first record on the page. We also create a footer that takes a value from the last record on each page. Note that the footer and carriage control only appear when the report is placed in the active file.
SET FORMAT $REPORT System Month Hours SET FORMAT * AT START OF PAGE, PRINT (RIGHT) @SYSTEM SET FORMAT * AT END OF PAGE, PRINT (RIGHT) @SYSTEM
+---------------------------------------------------------------+ | 1 ABC | | | | System Month Hours | | ------------------ ------------------ ------------------ | | ABC Jan 9 | | LMN Jan 25 | | XYZ Jan 31 | | | | XYZ | +---------------------------------------------------------------+
Here's an example where we print something at the beginning of the record detail. The PRINT command assumes "AT START OF DETAIL, IN ROW 1". Note that we put the element list in row 2, and suppress the column headin