******************************************************************
* *
* 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 headings.
SET FORMAT $REPORT PRINT 'Staff for System:' SET FORMAT * IN ROW 2, System Person SET FORMAT * OPTIONS NOHEADING
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Staff for System: | | ALPHA SAM | | JOHNNY | | BETTY | | Staff for System: | | BETA SAM | | BILL | | BETTY | +--------------------------------------------------------------+
The next example illustrates how PRINT expressions are placed by default. In the START OF REPORT section, the five expressions on row 3 are spaced evenly across the row. In the DETAIL section, two elements are specified, then a PRINT expression, and then another element is added, all spaced evenly across the same row.
SET FORMAT $REPORT AT START OF REPORT PRINT (CENTER) '********' SET FORMAT * IN ROW 3 PRINT 'ONE' SET FORMAT * PRINT 'TWO' SET FORMAT * PRINT 'THREE' SET FORMAT * PRINT 'FOUR' SET FORMAT * PRINT 'FIVE' SET FORMAT * IN DETAIL SYSTEM NAME SET FORMAT * PRINT 'DETAIL PRINT' SET FORMAT * + HOURS
+--------------------------------------------------------------+ | ******** | | | | ONE TWO THREE FOUR FIVE | | | | Nov. 10, 1982 Page 1 | | | | SYSTEM NAME HOURS | | ------------- ------------- ------------- | | ALPHA MASON DETAIL PRINT 5 | | ALPHA MASON DETAIL PRINT 7 | | ALPHA MASON DETAIL PRINT 2 | | ALPHA MASON DETAIL PRINT 4 | +--------------------------------------------------------------+
The IN ROW prefix is used to specify a row position within a section. Like the section designation prefixes, the IN ROW prefix need only be included once for each row -- it sets a "current row", and all subsequent commands apply to that row until another IN ROW prefix is included.
If no row prefixes are included in a section, the default row for starting sections is row 1, for ending sections, row 2.
You can specify a relative row position with the IN ROW prefix. For example:
AT START OF REPORT, IN ROW +3, PRINT $DATE
prints the value of $DATE 3 rows beyond the last value placed in the START OF REPORT section. The "IN ROW +n" prefix means "n" rows after everything else has been placed in the report section so far, no matter how many lines have been used. This enables you to place something after a multiply-occurring element. You can also specify "IN ROW *" to indicate the same row as the starting row of the last report item placed. This is valuable only when used in conjunction with the SKIP command. [See C.5.4.]
The following example shows the IN ROW prefix being used with several different sections.
SET FORMAT $REPORT Name Month Hours(SUM) SET FORMAT * GROUPED BY SYSTEM, MONTH SET FORMAT * AT START OF GROUP SYSTEM, PRINT '**********' SET FORMAT * AT START OF GROUP SYSTEM, IN ROW *, PRINT (RIGHT) @SYSTEM SET FORMAT * AT END OF GROUP SYSTEM, IN ROW 1, SUM HOURS SET FORMAT * AT START OF REPORT, IN ROW 20, PRINT (CENTER) 'ANNUAL REPORT' SET FORMAT * AT START OF REPORT, IN ROW +1, PRINT (CENTER) $DATE
+---------------------------------------------------------------+ | . | | . | | Annual Report | | 11/10/82 | |---------------------------------------------------------------| | 1Nov. 10, 1982 Page 1 | | | | Name Month Hours(SUM) | | ------------------ ------------------ ------------------ | | | | ********** ALPHA | | Smith JAN 49 | | | | FEB 27 | | *SUM 76 | +---------------------------------------------------------------+
This next example shows a definition of a DETAIL section where we place a PRINT expression following a multiply occurring element.
SET FORMAT $REPORT PRINT 'Hours for January' SET FORMAT * IN ROW +2, System Hours SET FORMAT * IN ROW +2, PRINT 'See next page for Summary'
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | System Hours | | ---------------------------- ----------------------------- | | Hours for January | | | | ALPHA 24 | | 12 | | 32 | | 8 | | | | See next page for Summary | +--------------------------------------------------------------+
In many cases, a single record takes more than one row to be displayed, due probably to multiply occurring elements. [See C.4.2.1.] If the elements are all defined as beginning on the same row, then it is still known as a "single row" record display. But sometimes you want to design the record display so that different elements appear on different rows. The IN ROW prefix allows you to do this. For example,
SET FORMAT $REPORT NAME (1,15) CITY (20,15) SET FORMAT * IN ROW 2, CAT.NAME (5,10) DOG.NAME (25,10)
adds two more elements to the element list and places them on row 2, with the column headings stacked at the top of the report, lined up with the columns they label, as in the following display.
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME CITY | | --------------- --------------- | | CAT.NAME DOG.NAME | | ---------- ---------- | | Carmen Miranda Palo Alto | | Felix Fido | | Esther Williams Mt. View | | Stella Spot | +--------------------------------------------------------------+
This is a simple example of placing singly-occurring record-level elements on explicit rows. If you have multiply-occurring elements, you must specify relative placement with an IN ROW +n prefix.
For example, if we have a record as follows:
NAME = Carmen; NAME = Esther; NAME = Ruby; PET = Felix; PET = Stella;
and a report definition like this:
SET FORMAT $REPORT IN ROW 1, NAME (1,15) SET FORMAT * IN ROW 2, PET (+2,10)
the element values overlap as follows:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME | | --------------- | | PET | | ---------- | | Carmen | | EsFelix | | RuStella | +--------------------------------------------------------------+
This happens because the PET element begins on row 2 no matter what has been placed previously. However, if we specify a relative row position for the PET element, we get the display that we want, with the PET element beginning on the first row following the last occurrence of the NAME element.
SET FORMAT $REPORT IN ROW 1, NAME (1,15) SET FORMAT * IN ROW +1, PET (+2,10)
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | NAME | | --------------- | | PET | | ---------- | | Carmen | | Esther | | Ruby | | Felix | | Stella | +--------------------------------------------------------------+
The SKIP command, in its simplest sense, is equivalent to the "IN ROW +n" prefix, and specifies a relative row position. For example,
AT END OF DETAIL, IN ROW 2, Name Address SKIP 3, PRINT @@PHONE
prints the specified expression 3 rows beyond the last occurrence of the Name and Address elements.
One thing the SKIP command can do that the "IN ROW +n" prefix cannot is to create trailing blank lines in a section. For example,
AT START OF PAGE, PRINT 'Monthly Report' SKIP 3
creates a page header with the string "Monthly Report" on the first row, followed by three blank lines.
The main difference between using the "IN ROW +n" prefix and the SKIP command is in how things are aligned vertically on the row. With the "IN ROW +n" prefix, no column alignment is attempted and, unless otherwise stated, a value begins in column 1 of the specified row. SKIP, however, retains the most recent column assignment.
Taking PRINT as a simple case for illustration purposes:
....v....1....v
+---------------+
IN ROW 1 PRINT (5) 'aaaaa' yields-> | aaaaa |
IN ROW +1 PRINT 'bbbbb' |bbbbb |
+---------------+
+---------------+
IN ROW 1 PRINT (5) 'aaaaa' yields-> | aaaaa |
SKIP 1 PRINT 'bbbbb' | bbbbb |
+---------------+
With SKIP, the second value is placed UNDER the first, rather than ON a new line. The same starting column is assumed for the second value since it is vertically bound with the first. A relative (+n) starting column for the second print is relative to this starting column. Thus:
....v....1....v
+---------------+
IN ROW 1 PRINT (5) 'aaaaa' yields-> | aaaaa |
SKIP 1 PRINT (+2) 'bbbbb' | bbbbb |
+---------------+
Of course, an explicit starting column can still be used for the second PRINT, if desired.
The starting column after a SKIP defaults to the starting column of the first PRINT in the preceding set of expressions -- that is, those belonging to the same explicit IN ROW prefix. For example:
....v....1....v
IN ROW 1 PRINT (3) 'First' +---------------+
PRINT 'Second' yields-> | First Second |
SKIP 1 PRINT 'Third' | Third |
+---------------+
If you had repeated the IN ROW designation, you would be beginning a new set of expressions for that row and the third PRINT would only relate to the single expression preceding it.
Thus:
....v....1....v
IN ROW 1 PRINT (3) 'First' +---------------+
IN ROW 1 PRINT (9) 'Second' yields-> | First Second |
SKIP 1 PRINT 'Third' | Third |
+---------------+
Although multiple PRINTs on the same row would more likely be handled as a single long expression, this illustrates that SKIP is tied to the first item placed after an IN ROW prefix, not to the immediately preceding statement, as shown in the above examples. [See C.5.5 for more details about the SKIP command as it relates to vertical binding of elements, C.6.5 for details about the vertical binding of functions.]
As described in Section C.5.4, vertical binding is the vertical alignment of items that occur when the SKIP command is used. Although it applies to the placement of all items, it is most useful when applied to element lists since they define multiple columns across the report page.
Suppose you want a value (element or expression) to be placed at the end of a column of multiply-occurring element values. Since the number of occurrences varies per record you cannot place the value on any particular row -- it must be positioned relative to the values above it. If your report has but a single column, you can use either SKIP or IN ROW +n as follows:
IN ROW 1 HIST.DATE (12) IN ROW 1 HIST.DATE (12) IN ROW +1 PRINT (12) '* LAST *' or SKIP 1 PRINT '* LAST *' IN ROW +1 LAST.DATE (12) SKIP 1 + LAST.DATE
Both definitions produce the following display:
....v....1....v....2....v +-------------------------+ | HIST.DATE | | --------- | | LAST.DATE | | --------- | | 11/12/82 | | 11/23/82 | | * LAST * | | 12/05/82 | +-------------------------+
The SKIP command tells $REPORT to align the values vertically; each new IN ROW prefix places the value in column one unless told otherwise, as shown. Note, also, that column headings always appear at the top of the columns, not mixed in with the values.
Each time you use the IN ROW prefix, you are specifying a new list of elements, and these elements are bound together. Because the SKIP command is adding more elements to the list begun by an IN ROW prefix, you must use the "+" as shown in the above example.
If your report consists of multiple columns of varying lengths, the SKIP command has another valuable effect. Unlike the "IN ROW +n" prefix, which specifies the next available row after any value placed so far in the report section, SKIP refers to the next available row after only those values since the last IN ROW prefix. Let's expand on our above example to illustrate this. Assume that our record is structured as follows:
NAME = Cosmo; NAME = Regis; NAME = Simone; NAME = Zazu; HIST.DATE = 11/12/82; HIST.DATE = 11/23/82; LAST.DATE = 12/05/82;
The following two displays show the difference between using the IN ROW prefix and the SKIP command.
Using IN ROW: Using SKIP:
IN ROW 1, NAME (1,8) IN ROW 1, NAME (1,8)
IN ROW 1, + HIST.DATE (12) IN ROW 1, + HIST.DATE (12)
IN ROW +1, PRINT (12) '*LAST*' SKIP 1, PRINT '*LAST*'
IN ROW +1, LAST.DATE (12) SKIP 1, + LAST.DATE
....v....1....v....2....v ....v....1....v....2....v
+-------------------------+ +-------------------------+
|NAME HIST.DATE | |NAME HIST.DATE |
|-------- --------- | |-------- --------- |
| LAST.DATE | | LAST.DATE |
| --------- | | --------- |
|Cosmo 11/12/82 | |Cosmo 11/12/82 |
|Regis 11/23/82 | |Regis 11/23/82 |
|Simone | |Simone * LAST * |
|Zazu | |Zazu 12/05/82 |
| * LAST * | | |
| 12/05/82 | | |
+-------------------------+ +-------------------------+
Here is a more complex example to show how the IN ROW prefix and the SKIP command work together. It is a form letter report that has at its heart a table of credit information alongside a table of debit information. The sums for each half must be directly beneath their appropriate columns, regardless of the relative size of each table:
SET FORMAT $REPORT IN ROW 1 PRINT 'Dear Sir,' SET FORMAT * SKIP 2 SET FORMAT * PRINT (5) 'Your account (#' @ACCOUNT ') shows the following' SET FORMAT * SKIP 1, PRINT 'credits and debits.' SET FORMAT * DEFINE VALUE SUM.CR AS SUM CR.AMT SET FORMAT * DEFINE VALUE SUM.DB AS SUM DB.AMT SET FORMAT * IN ROW +3 SET FORMAT * PRINT (5) '**** Credits **** **** Debits ****' SET FORMAT * IN ROW +1 CR.DATE (5,8) CR.AMT (+3,8,R) SET FORMAT * SKIP 1 PRINT (+11,8) '--------' SET FORMAT * SKIP 1 + SUM.CR (,8,EDIT ZZZ.99) SET FORMAT * IN ROW * DB.DATE (30,8) DB.AMT (+3,8,R) SET FORMAT * SKIP 1 PRINT (+11,8) '--------' SET FORMAT * SKIP 1 + SUM.DB (,8,EDIT ZZZ.99) SET FORMAT * IN ROW +3 PRINT (5) 'Pay up or die.' SET FORMAT * SKIP 2 PRINT (35) 'Sincerely,' SET FORMAT * OPTIONS NOREPORT
Here's what the report looks like:
+--------------------------------------------------------------+ |Dear Sir, | | | | Your account (#A15734) shows the following | | credits and debits. | | | | | | **** Credits **** **** Debits **** | | 04/12/82 12.95 04/19/82 116.50 | | 06/22/82 9.24 05/06/82 44.30 | | 11/15/82 100.00 07/12/82 72.95 | | 12/01/82 50.00 -------- | | -------- 233.75 | | 172.19 | | | | | | Pay up or die. | | | | Sincerely, | +--------------------------------------------------------------+
Notice the use of "IN ROW *" to start the two tables on the same row. The statement placing the CR.DATE element is followed by several statements that place values with the SKIP command. The "IN ROW *" prefix that places the DB.DATE element references the same row as the previous IN ROW prefix (i.e., the one placing the CR.DATE element), not the last row on which data has been placed.
Horizontal structural binding is what takes place in $REPORT when elements belonging to the same structure and defined on the same row are aligned horizontally such that new values from the next structure occurrence start after all values from the previous structure have been processed. [See C.4.2.2.]
"Vertical structural binding" takes place when values belonging to the same structure are placed on different rows using the SKIP command. The effect of vertical structural binding is that values belonging to the same structure occurrence are kept together and the pair (or more) of structurally bound lines repeat down the page. Another way of looking at it is that structure elements are interleaved to keep values belonging to the same structure together.
For example, assume a single record with a multiply occurring NAME/ADDRESS structure with the following values:
STR;
NAME = Dwight;
NAME = Mamie;
ADDR = White House;
ADDR = 1600 Pennsylvania Ave.;
ADDR = Washington, D.C.;
STR;
NAME = Zeke;
ADDR = Rural Box 11;
ADDR = Hashbrown, Idaho;
IN ROW 1 NAME ADDR --> +--------------------------------+
| Dwight White House |
| Mamie 1600 Pennsylvania Ave. |
| Washington, D.C. |
| Zeke Rural Box 11 |
| Hashbrown, Idaho |
+--------------------------------+
IN ROW 1 NAME --> +--------------------------------+
SKIP 1 + ADDR (+2) | Dwight |
| Mamie |
| White House |
| 1600 Pennsylvania Ave. |
| Washington, D.C. |
| Zeke |
| Rural Box 11 |
| Hashbrown, Idaho |
+--------------------------------+
Notice how SKIP caused ADDR values to start after the last NAME value within each structure occurrence.
Here is what happens when IN ROW is used instead -- vertical binding is lost and the two elements are dealt with separately. In the first example, explicit row numbers are used, thus causing the element values to be overlaid. Explicit row numbers do not take into account multiple occurrences.
IN ROW 1 NAME --> +-----------------------------+
IN ROW 2 ADDR (4) | Dwight |
| MamWhite House |
| Zek1600 Pennsylvania Ave. |
| Washington, D.C. |
| Rural Box 11 |
| Hashbrown, Idaho |
+-----------------------------+
The second example uses relative row numbers, which prevents values from being overlaid, but no structural binding takes place because the elements are placed on separate rows with repeating IN ROW prefixes, rather than the SKIP command.
IN ROW 1 NAME --> +-----------------------------+
IN ROW +1 + ADDR (+2) | Dwight |
| Mamie |
| Zeke |
| White House |
| 1600 Pennsylvania Ave. |
| Washington, D.C. |
| Rural Box 11 |
| Hashbrown, Idaho |
+-----------------------------+
Vertical structural binding can be to multiple levels, just like horizontal structural binding. For example,
SET FORMAT $REPORT Person SET FORMAT * SKIP 1, + Relative (+2) SET FORMAT * SKIP 1, + City (+2) State
Record: Report:
PERSON.STR; +----------------------+
PERSON = Dad; | Dad |
REL.STR; | Sis |
RELATIVE = Sis; | Norfolk Va |
ADDR.STR; | Cousin |
CITY = Norfolk; | Philadelphia Pa |
STATE = Va; | Mom |
REL.STR; | Brother |
RELATIVE = Cousin; | Dallas Tx |
ADDR.STR; | Aunt |
CITY = Philadelphia; | Seattle Wa |
STATE = Pa; +----------------------+
PERSON.STR;
PERSON = Mom;
REL.STR;
RELATIVE = Brother;
ADDR.STR;
CITY = Dallas;
STATE = Tx;
REL.STR;
RELATIVE = Aunt;
ADDR.STR;
CITY = Seattle;
STATE = Wa;
Note that if any of the values placed with a SKIP command do not belong to the structure, then vertical structural binding does not take place. For instance, take the simple NAME/ADDRESS example from above and interrupt the structure with a PRINT command or a record level element:
IN ROW 1 NAME +----------------------------+
SKIP 1 PRINT '*********' | Dwight |
SKIP 1 + ADDR (+2) | Mamie |
| Zeke |
| ********* |
| White House |
| 1600 Pennsylvania Ave. |
| Washington, D.C. |
| Rural Box 11 |
| Hashbrown, Idaho |
+----------------------------+
IN ROW 1 NAME +----------------------------+
SKIP 1 + RECORD.KEY | Dwight |
SKIP 1 + ADDR (+2) | Mamie |
| Zeke |
| <record.key> |
| White House |
| 1600 Pennsylvania Ave. |
| Washington, D.C. |
| Rural Box 11 |
| Hashbrown, Idaho |
+----------------------------+
Interleaving the NAME/ADDR values in these examples does not make sense since we have created a clear demarcation between all values of one and all values of the other. If you really wanted, say, the row of asterisks or a non-structural element to appear between the names and addresses of each structure occurrence, then you would define a dynamic element that was tied to either the NAME or ADDR fields:
DEFINE ELEMENT STARS FOR NAME AS '*********'
SET FORMAT $REPORT IN ROW 1, NAME +----------------------------+
SET FORMAT * SKIP 1, + STARS | Dwight |
SET FORMAT * SKIP 1, + ADDR (+2) | Mamie |
| ********* |
| ********* |
| White House |
| 1600 Pennsylvania Ave. |
| Washington, D.C. |
| Zeke |
| ********* |
| Rural Box 11 |
| Hashbrown, Idaho |
+----------------------------+
In general, to produce output with multiple character sets for printing on the IBM 3800 or the Xerox 9700, you must reserve column two of your output for a font selection character and specify the characters with a CHARS option on the PRINT command. To do this in $REPORT, you use either the FONT command in one or more sections, or the FONT parameter for PRINT expressions. [See C.5.2.] $REPORT automatically adjusts your report and controls the FONT column -- your report definition still references columns beginning with column 1.
Font selection using $REPORT must be tied in with options issued on the PRINT command in WYLBUR. For example,
PRINT UNN CC CHARS(CU12,BD12)
You can specify up to four character sets. The CC is necessary to signal the printer to interpret all characters in column 1 as carriage control characters [See C.5.1.] and all those in column 2 as font selection characters. The UNN (unnumbered) parameter is not necessary for carriage or font control, but presumably you do not want line numbers to appear in your report.
Font selection characters for both the 3800 and the 9700 are 0-3. A blank is equivalent to a "0". Each line that has either a blank or a "0" in column 2 prints with the first character set specified on the CHARS option of the WYLBUR PRINT command, each line with a "1" prints in the second character set, each line with a "2" in the third character set, and each line with a "3" in the fourth.
Font selection for your report is specified on a row-by-row basis. By including a FONT command, you specify that you want a particular number placed in column 2 of the current row. Note that you must specify the font character explicitly for each row (or else perhaps use the PRINT command with a single expression that wraps onto multiple rows). The following report format is probably not what the person defining it really wants or expects:
SET FORMAT $REPORT System Name Hours SET FORMAT * GROUPED BY SYSTEM SET FORMAT * AT END OF GROUP SYSTEM, SUM HOURS SET FORMAT * IN ROW 2, FONT = 2 SET FORMAT * PRINT 'Summary values are computed' SET FORMAT * IN ROW + 1, PRINT 'on a monthly basis.'
These statements produce the following report in the active file:
+--------------------------------------------------------------+ |1 Nov. 10, 1982 Page 1| | | | System Name Hours | | ------------------ ------------------ ------------------ | | | | Hydromatic Smith 5 | | Jones 7 | | Wilson 8 | | Peters 2 | | Carson 4 | | | | 2Summary values are computed *SUM 26 | | on a monthly basis. | +--------------------------------------------------------------+
The END OF GROUP section begins with the summing of the HRS element. The second command specifies that the number "2" is to appear in column 2 of row 2. The PRINT expression 'Summary values are computed' is placed on that row and the expression 'on a monthly basis' is placed under it. This row, however, does not have a "2" in column 2, because the FONT command only applied to the single row for which it was specified. So the single sentence ("Summary values...") is printed in two different fonts for no especially good reason. Remember once again that you need to specify the font character explicitly for each row in which it is meant to take effect. That is, unless you specify the PRINT expression as a single expression wrapping onto multiple rows, as suggested earlier.
If a FONT command is issued anywhere in the report definition, the entire report is moved over to begin in column 3. If this is the case, but no font selection is specified for a particular section, a blank appears in column 2, which indicates that the first character set in the CHARS option is to be used. If no CHARS option is included on your PRINT command, the font selection characters are ignored, and the entire report is printed in the default character set with the font control characters printed as part of your report.
A WYLBUR OPTIONS line can be added to the report by placing it in row 1 of the START OF REPORT section. [See C.8.1.]
Another way to put a font selection character in column 2 of the report is by using the FONT parameter with a PRINT expression or function. For example,
SET FORMAT * AT END OF GROUP MONTH, PRINT (FONT = 3) 'Summary for Month:'
puts the number "3" in column 2 of the row on which this PRINT expression appears. This means that anything else appearing on this row is printed in the specified character set. If more than one expression is placed on a single line, but with different FONT control specified, the last one in the report definition takes precedence.
Font control cannot be used in conjunction with the BOLD and ITALIC parameters for elements, PRINT expressions, or functions. [See C.4.3.7, C.5.2, C.6.5.]
One of the primary functions of a report is to group data in a meaningful way and provide summary information. This chapter describes the capabilities of $REPORT for grouping and summarizing values. The first sections describe grouping for horizontal reports; the last section describes grouping for vertical reports.
The GROUPED BY command is a global command that specifies how elements are grouped. In the following example, we are displaying 6 records, each with a singly-occurring DEPT, NAME and PROJECT element.
SET FORMAT $REPORT Dept Name (10) Project (25,25)
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Dept Name Project | | ------- ------------- ------------------------- | | ACTG Bennet Invoice Control | | ACTG Bennet Resource Monitoring | | ACTG Foster World Domination | | ACTG Foster Annual Audit | | SYST Clark Nuclear Waste | | SYST Jacobs Interplanetary Travel | +--------------------------------------------------------------+
The next report was created by adding a GROUPED BY command as follows:
SET FORMAT * GROUPED BY DEPT, NAME
This command indicates that the records are already sorted by certain elements and that we only want the element value to be printed once for each unique occurrence.
We get the following display:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Dept Name Project | | ------- ------------- ------------------------- | | | | ACTG Bennet Invoice Control | | Resource Monitoring | | | | Foster World Domination | | Annual Audit | | | | SYST Clark Nuclear Waste | | | | Jacobs Interplanetary Travel | +--------------------------------------------------------------+
The complete syntax is:
GROUPED BY element (parameters), element (parameters).....
where the optional parameters are NOFINAL, DISPLAY, BLANKS=n, HEADING, NAME and RECNO=n. These parameters allow you to control the final summaries for the group, the printing of group elements, the relative spacing of the groups, heading values and the record counter variable. [See C.6.1.1, C.6.1.2, C.6.1.3, C.6.1.4, C.6.1.5.]
You can specify up to five group elements. The group elements (i.e., those elements specified on the GROUPED BY command) do not have to also appear in the element list, in which case, of course, they do not print at all, but the records are grouped according to the value of the group element.
If a group element is multiply-occurring, $REPORT only uses the first occurrence of the element to determine when a new group begins. If you want each occurrence of the group element to be considered, you must first sort the records with SPISORT.
Note that the GROUPED BY command does not sort the records. This must be done by either the SEQUENCE command or the SPISORT facility if needed. Generally, you should issue a SEQUENCE command with the same elements as named in the GROUPED BY command. For example, if the command
GROUPED BY X Y Z
is in your report definition, you want to sort your records prior to display with the command
SEQUENCE X Y Z
to ensure that the records are in the proper order for grouping.
Often, when you group records, you later define summary items to be placed at the end of a particular group. [See C.6.4.] By default, the values placed in the END OF GROUP sections are repeated for a grand-total summary at the end of the report. If you want to suppress the final summary, include the NOFINAL parameter on the GROUPED BY command as in the following example:
GROUPED BY SYSTEM NAME (NOFINAL)
The final summary of all items specified in the END OF GROUP NAME section does not appear, but those items in the END OF GROUP SYSTEM section are still displayed at the end of the report. [See C.6.4 for more details and an example.]
Note that the final summary of END OF GROUP sections is not part of the END OF REPORT section, but appears before it. [See C.8.2.]
As mentioned above, group elements appear once for each unique value. If you want any individual element value to always be printed for each record, include the DISPLAY parameter after that element name on the GROUPED BY command. For example, if we specified in the above example,
SET FORMAT $REPORT Dept Name (10) Project (25,25) SET FORMAT * GROUPED BY DEPT, NAME (DISPLAY)
we get the following display, in which the NAME value prints every time.
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Dept Name Project | | ------- ------------- ------------------------- | | | | ACTG Bennet Invoice Control | | Bennet Resource Monitoring | | | | Foster World Domination | | Foster Annual Audit | | | | SYST Clark Nuclear Waste | | | | Jacobs Interplanetary Travel | +--------------------------------------------------------------+
By default, a single blank line is inserted at the beginning of every group. This can be changed by including the BLANKS parameter in parentheses following the name of the group element in the GROUPED BY command.
For example if we include the BLANKS parameter as follows:
SET FORMAT $REPORT Dept Name (10) Project (25,25) SET FORMAT * GROUPED BY DEPT (BLANKS=2), NAME (BLANKS=0)
we get the following display:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Dept Name Project | | ------- ------------- ------------------------- | | | | | | ACTG Bennet Invoice Control | | Resource Monitoring | | Foster World Domination | | Annual Audit | | | | | | SYST Clark Nuclear Waste | | Jacobs Interplanetary Travel | +--------------------------------------------------------------+
The "BLANKS=2" parameter put 2 blank lines between each DEPT group; the "BLANKS=0" put no lines between each NAME group. When both DEPT and NAME groups ended at the same place (after the name "Foster") then 2 blank lines were skipped (the BLANKS value for DEPT, the higher level group because it is named earlier in the GROUPED BY command). Whenever two or more groups change at once, the BLANKS value for the highest level group is used for spacing; the BLANKS values are not added together.
By default, when you create a group in a horizontal report, $REPORT makes it very obvious how the grouping works and where a new group begins:
Dept Name Project
------- ------------- -------------------------
ACTG Bennet Invoice Control
Resource Monitoring
Foster World Domination
Annual Audit
SYST Clark Nuclear Waste
Jacobs Interplanetary Travel
In the example above, the records are grouped by DEPT and NAME.
You can have $REPORT make a more obvious break by including the HEADING parameter in the GROUPED BY statement:
-> set format * grouped by dept(heading='Department:') name
which would create the following:
Dept Name Project
------- ------------- -------------------------
Department: ACTG
ACTG Bennet Invoice Control
Resource Monitoring
Foster World Domination
Annual Audit
Department: SYST
SYST Clark Nuclear Waste
Jacobs Interplanetary Travel
The HEADING parameter, in essence, requests a START OF GROUP section, printing a heading composed of the heading string, followed by the group value.
More likely, however, you might want to withdraw the DEPT column from the detail section once you display its value in the group heading.
Name Project
------------- -------------------------
Department: ACTG
Bennet Invoice Control
Resource Monitoring
Foster World Domination
Annual Audit
Department: SYST
Clark Nuclear Waste
Jacobs Interplanetary Travel
The NAME parameter can be used as another way to label the group value, in this case when it appears in verbose summary statistics at the end of the group and at the end of the report:
-> set format * options functions=verbose -> set format * at end of group dept, count project
In this example, before setting the NAME parameter, we might get this result:
Name Project
------------- -------------------------
Department: ACTG
Bennet Invoice Control
Resource Monitoring
Foster World Domination
Annual Audit
For ACTG
Count: 4
Department: SYST
Clark Nuclear Waste
Jacobs Interplanetary Travel
For SYST
Count: 2
For Overall
Count: 6
If you include the NAME option as part of the GROUPED BY statement, its value will be placed between the "For" and the group value in the verbose summary heading. For example, if your GROUPED BY statement looked like this:
-> set for * group by dept(name='Dept',heading='Department:') name
the final lines of the above report would look like this:
For Dept SYST Count: 2 For Overall Dept Count: 6
HEADING and NAME work slightly differently in vertical reports. [See C.6.8.]
By default, a system variable called $RECNO, counting from 1, contains the number of records processed in the report. As described in an earlier section, you could use this variable as a counter element that gets included for each record in a report by defining a dynamic element, like this:
DEFINE ELEMENT RECNO FOR key-element AS $RECNO
where you replaced "key-element" with the name of the key element of the goal record. [See C.4.2.3.]
The RECNO parameter on the GROUPED BY command in $REPORT lets you reset the counter each time a new group starts. This is useful when you need to start counting the records from "1" each time a group changes.
The syntax is:
GROUPED BY group-name (RECNO=n)
where "n" is a number from -2,147,483,647 to 2,147,483,647. The number specified will be the number assigned to the first record in the group, so you would specify "RECNO=1" to give 1 to the first record in the group. count from 1.
If you are issuing commands interactively at the terminal during the development of a report, you might want to see the effects of a GROUPED BY command, but then want to cancel it out. This can be done with the NOGROUP option of the OPTIONS command. [See C.4.5.] For example,
SET FORMAT * OPTIONS NOGROUP
Any GROUPED BY statement in effect is cancelled when this option is added. A new GROUPED BY statement cancels the effect of the NOGROUP option.
You would never want to use this option in a finalized report definition because there is no point in defining and then undefining groups of elements before the report is produced.
Once you have established a group of elements, you can place text or element values before the first detail record in that group by placing a PRINT expression [See C.5.2.] in the START OF GROUP section. The syntax is:
AT START OF GROUP group, PRINT [(parameters)] expression
where "group" is the name of the group element that defines the group you want the expression to precede. The IN ROW prefix and the SKIP command can be included to specify explicit positioning within the section.
For example, the following display was created by adding a START OF GROUP section to the definition:
SET FORMAT $REPORT Name (20) Project (35,25) SET FORMAT * GROUPED BY DEPT, NAME SET FORMAT * AT START OF GROUP DEPT, PRINT 'DEPARTMENT: ' @DEPT SET FORMAT * IN ROW 2, PRINT (5) '(Data for ' @MONTH ')'
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Name Project | | ------------- ------------------------- | | | | Department: ACTG | | (Data for October) | | Bennet Invoice Control | | Resource Monitoring | | | | Foster World Domination | | Annual Audit | | | | Department: SYST | | (Data for October) | | Clark Nuclear Waste | | | | Jacobs Interplanetary Travel | +--------------------------------------------------------------+
If you include an element reference in the START OF GROUP section, it retrieves the value from the first record in the group. If more than one group begins at the same place, the START OF GROUP sections are executed in the order in which they appear on the GROUPED BY command.
The NEWPAGE command can also be included in this section to cause the group to begin on a new page. [See C.5.1.] The IN ROW prefix and the SKIP command are used to specify explicit positioning within the section. [See C.5.3, C.5.4.]
When you have groups of records, you can calculate values across the group to provide, for example, the sum of all the values of an element, or the number of times a particular element occurs. These summary values are placed in the END OF GROUP section and calculated by arithmetic functions. Available arithmetic functions are: COUNT, SUM, MINIMUM, MAXIMUM, AVERAGE, and STD (standard deviation) and cumulative versions of these. [See C.6.5 for complete details on functions.] Arithmetic functions are specified by giving the name of the function followed by the name of the element against which the function is to be applied.
For example,
SET FORMAT $REPORT Dept (3,5) Name (10,10) Project (22,17) Hours (52,5,R) SET FORMAT * GROUPED BY DEPT, NAME SET FORMAT * AT END OF GROUP DEPT, COUNT NAME, SUM HOURS
prints the sum of all the occurrences of the HOURS element and counts the number of occurrences of the NAME element. The resulting display is as follows:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Dept Name Project Hours | | ----- ---------- ----------------- ----- | | | | ACTG Bennet Invoice Control 32 | | Resource Monitoring 20 | | | | Foster World Domination 112 | | Annual Audit 18 | | | | *COU 2 | | *SUM 182 | | | | SYST Clark Nuclear Waste 40 | | | | Jacobs Interplanetary Travel 250 | | | | *COU 2 | | *SUM 290 | | | | **COU 4 | | **SUM 472 | | | +--------------------------------------------------------------+
At the end of each group based on the SYSTEM element, the HOURS are summed, and the NAME element is counted. The values appear in the same columns as the element values; the function name (abbreviated to three characters and preceded by an asterisk) appears to the left of the left-most function value. At the end of the report, the END OF GROUP section is repeated for the entire report; these function names are preceded by two asterisks. The final summary that appears at the end of the report is separate from the END OF REPORT section [See C.8.2.] and appears after the final group, before the END OF REPORT section. This final summary can be suppressed with the NOFINAL parameter of the GROUPED BY command. [See C.6.1.1.]
The default starting row for END OF GROUP sections is row 2. Thus, a blank line separates group summary sections from the detail, but this may be overridden by placing data explicitly into row 1. A blank line also occurs at the beginning of every group of records. This blank line may not have values placed in it, but it may be eliminated by specifying BLANKS=0 for the group on the GROUPED BY command. [See C.6.1.]
For example,
SET FORMAT $REPORT Dept (3,5) Name (10,10) Project (22,17) Hours (52,5,R) SET FORMAT * GROUPED BY DEPT (BLANKS=0), NAME (NOFINAL) SET FORMAT * AT END OF GROUP DEPT, SUM HOURS SET FORMAT * IN ROW 3, PRINT (CENTER) '------------------------------' SET FORMAT * AT END OF GROUP NAME, COUNT PROJECT
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Dept Name Project Hours | | ----- ---------- ----------------- ----- | | | | ACTG Bennett Invoice Control 32 | | Resource Monitoring 20 | | | | *COU 2 | | | | Foster World Domination 112 | | Annual Audit 18 | | | | *COU 2 | | | | *SUM 182 | | ------------------------------ | | SYST Clark Nuclear Waste 40 | | | | *COU 1 | | | | Jacobs Interplanetary Travel 250 | | | | *COU 1 | | | | *SUM 290 | | ------------------------------ | | | | **SUM 472 | +--------------------------------------------------------------+
We first defined two groups, DEPT and NAME. There is no blank line at the beginning of DEPT groups, and there is no final summary generated for the NAME group. At the end of the DEPT group, the HOURS element are summed; this value is placed on row 2 of the section, because that is the default starting row. In the next command we place a PRINT expression on row 3 of the END OF GROUP DEPT section. At the end of the NAME group, a COUNT of the PROJECT element appears, but this value is not recalculated at the end of the report because of the NOFINAL parameter on the GROUPED BY command.
Function values are placed under the column of the element they summarize; this is "column binding". If the element does not appear in any column of the report, the summary value is placed at the beginning of its row. These defaults can easily be changed. See C.6.5 for complete details about functions and their placement in END OF GROUP sections.
Like START OF GROUP sections, you can place expressions in the section with the PRINT command. [See C.5.2.] Also, the NEWPAGE command can be used to cause the section to begin on a new page. [See C.5.1.] The IN ROW prefix [See C.5.3.] and the SKIP command [See C.5.4.] can be used in the section to specify placement of the values. The FONT command can be used to specify alternate character sets for the section. [See C.5.6.]
When you group records you may want to summarize data by computing values from numeric elements. This is done by specifying arithmetic functions that represent mathematical operations. The available functions are:
COUNT/CNT - Yields a count of occurrences of the element.
SUM - Totals the values of all occurrences of the element.
MINIMUM - Returns the minimum value of the element.
MAXIMUM - Returns the maximum value of the element.
AVERAGE/AVG - Returns the average of all values. Equal to SUM
divided by COUNT.
STD - Standard deviation, computed as:
square root of n(SUM(x2)) - (SUMx)2
--------------------
n(n-1)
where "SUM" indicates summation, "n" is number of
values, "x" indicates element values, and "2"
indicates "squared".
Functions can be used in three places in $REPORT:
- As an element parameter, providing a summary of the occurrences of that element in a single record. [See C.4.4.]
- To summarize data across groups. [See C.6.4.]
- To define summary elements. [See C.6.7.]
All of the functions except COUNT apply to numeric element values (including numeric values of text elements or encoded elements). The COUNT function may be used with any element, whether it's numeric or not.
Functions are most commonly used to calculate a summary value from a group of records specified with the GROUPED BY command or from the entire report. These calculations are specified in the END OF GROUP and END OF REPORT sections, by naming the function and the element to which the function should be applied. All arithmetic function names can be abbreviated to three characters. For example:
SET FORMAT * AT END OF GROUP PERSON, SUM HRS SET FORMAT * AT END OF REPORT, COUNT PROJECTS SET FORMAT * AT END OF GROUP MONTH, MIN AMT, MAX AMT
If no occurrences are found in computing minimum and maximum values, then a single hyphen ("-") prints in place of a numeric value. Up to 30 functions may be used in a single report; 10 may be used in the DEFINE VALUE command, [See C.6.7.] up to 30 as element parameters (i.e., element (SUM)), and up to 20 in ending sections. $REPORT uses 13 digits of precision for packed decimal values.
An alternate form of the functions allows you to accumulate a function value, sometimes called a "running count" or "running total". These are the function names preceded by a "C" (for "cumulative"), i.e. CCOUNT/CCNT, CSUM, CAVERAGE/CAVG, CMINIMUM, CMAXIMUM and CSTD. These functions can be specified at any time and provide the cumulative value of the function from the beginning of the report. They may be abbreviated to four characters.
Function values appear in the same column as the element values to which they apply; this is called "column binding". [See C.6.4 for examples of this.] A different line is used for each type of function used, i.e. all SUMs are on one line, all MAXIMUMs on another, etc. Their order is determined by the order in which they are listed in the section definition. For example,
AT END OF REPORT, IN ROW 3, SUM X, COUNT Y, MIN A, MAX B
places the SUM of X in row 3, the COUNT of Y in row 4, the MINIMUM of A in row 5, and the MAXIMUM of B in row 6. If you then issue the command
IN ROW +1 PRINT 'end of functions'
the PRINT expression appears on the next available line after all function values have printed, in this case, row 7.
The column-bound functions are labeled, by default, with the three- or four-character function identifier (SUM, CMAX, etc.) preceded by a single asterisk for group summary, or a double asterisk for end-of-report summary. The labels for column-bound functions appear to the left of the left-most column for which a function is calculated, separated from that column by two spaces. If the labels would be located too far to the left to fit on the page, then an automatic INDENT of 8 is created. [See C.7.6.]
You can also specify explicit positioning for summary functions and define other labels for them by including a parenthesized parameter list following the element name (see below).
You can also request "verbose" default labels instead of the rather terse 3- and 4-character identifiers. You do this with the FUNCTION option:
SET FORMAT * OPTIONS FUNCTIONS={VERBOSE|TERSE}
The default is TERSE. But if you choose VERBOSE, $REPORT will expansively use full words and multiple lines to display the summary results:
For ACTG Count: 45 Sum: 17 92
The numbers would be bound to the appropriate columns of the report.
If a function generates a summary value for an element not in any detail line (and thus not in a column), then it is not column-bound. The function value is placed on a line by itself. If it is the only non-column-bound function on that row, it is placed by default in column 1. If more than one non-column-bound function is specified for the same row, the values are evenly spaced across that row if no positioning information is supplied.
The default label for non-column-bound function values consists of the function abbreviation plus the element name (e.g., *COU NAME: ). This style of label is also used if you specify explicit positioning for summary functions, since those functions are not column-bound.
For example,
SET FORMAT $REPORT Credits (8,10) Debits (40,10) SET FORMAT * AT END OF REPORT SUM CREDITS SUM DEBITS SET FORMAT * SUM A SUM B
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Credits Debits | | --------- --------- | | 23.89 45.38 | | 13.35 23.98 | | 12.00 1.45 | | | | **SUM 49.24 70.81 | | | | **SUM A: 312 **SUM B: 624 | +--------------------------------------------------------------+
Defaults for the display of arithmetic functions are usually appropriate, but they can be overridden. The following parameters may appear in parentheses following the function specification to specify where the function value is to appear.
When an edit mask is in effect, the default for ADJUST is RIGHT.
The following arithmetic function prints the sum of the HOURS element. Even if the element HOURS appears in the DETAIL section, the presence of explicit positioning information makes the value non-column-bound, and it begins in column 50 of row 3 in the END OF REPORT section.
AT END OF REPORT, IN ROW 3, SUM HOURS (50)
The next example illustrates a function that is centered on the second row following the last item placed in the current section, and it is preceded with the specified label.
IN ROW +2, COUNT NAME (CENTER, LABEL = 'Number of Names: ')
This example specifies an arithmetic function to appear in the END OF GROUP section following the ITEM group, but it does not appear in the final summary at the end of the report, although other items in the END OF GROUP ITEM section might.
AT END OF GROUP ITEM, AVERAGE COST (NOFINAL)
Summary functions placed at the end of groups or at the end of the report already have a kind of binding taking place -- column binding. But functions may also be vertically bound.
As with element lists and PRINT expressions, functions are bound together with the IN ROW prefix and the SKIP command. Column-bound functions are placed first, then non-column-bound functions. A function can be changed from column-bound to non-column-bound by an explicit NOBIND parameter, by the presence of any specific positioning information (column or adjustment), or by the SKIP command.
The vertical alignment of values positioned after a SKIP are not compatible with column binding; therefore, any functions placed after a SKIP command become non-column-bound. There is an implicit SKIP=2 between column-bound functions and non-column-bound functions.
To illustrate the above:
AT END OF REPORT, IN ROW 1, SUM X, COUNT Y, SUM A, COUNT B +-----------------------------+ | X Y A B | | ---- ---- ---- ---- | |*SUM nnn nnn | |*COU nnn nnn | +-----------------------------+
All values are placed together since they are all specified on row 1, the SUMs appearing on the first row, the COUNTs on the next row. The SUMs are first because the function in the list is a SUM. All values are column-bound.
AT END OF REPORT, IN ROW 1, SUM X, COUNT Y IN ROW +2, SUM A, COUNT B +-----------------------------+ | X Y A B | | ---- ---- ---- ---- | |*SUM nnn | |*COU nnn | | | |*SUM nnn | |*COU nnn | +-----------------------------+
In this example, all values remain column-bound because they are placed on explicit rows. But in the following example, because the SKIP command is used, the second set of function values are no longer column-bound and appear two rows below the column-bound values.
AT END OF REPORT, IN ROW 1, SUM X, COUNT Y SKIP 2, SUM A, COUNT B +-----------------------------+ | X Y A B | | ---- ---- ---- ---- | |*SUM nnn | |*COU nnn | | | |*SUM A: nnn *COU B: nnn | +-----------------------------+
There are several methods of applying edit masks to numeric element values and function values in $REPORT. The chart below summarizes which values are affected by which method of specifying edit masks.
APPLIES TO:
element function value function value
METHOD: values (column-bound) (not column-bound)
-------------------- -------------------------------------------
$EDIT outproc in yes no no
file definition
EDIT info-element yes yes no
in file definition
EDIT parameter in yes yes no
$REPORT element list
[see C.4.3.6]
EDIT parameter in no yes yes
$REPORT function
specification
[see C.6.5]
Two types of default function labels are provided -- those for column-bound functions and those for non-column-bound functions. [See C.6.5.] The default label can be reset for each type of function using the LABEL command:
SET FORMAT * LABEL function [AS] expression
This resets the label for all functions of a certain type (i.e., all SUMs, all COUNTs, etc.) specified in all report sections -- both column-bound and non-column-bound functions.
For example,
SET FORMAT * LABEL SUM AS 'Total: '
changes the label for all SUMs from '*SUM:' to 'Total: '.
Functions can be separately labeled with the LABEL parameter following the function specification, so you can specify a label to override the default label for an individual function value.
For example,
SUM COST (LABEL = 'Total Cost: ')
changes the label for this one value only.
When an element is included in a report definition it is accessed on an occurrence by occurrence basis. Each occurrence prints separately in the DETAIL sections of the report. When it is used in a function, the element's values are extracted from each individual occurrence; for example, COUNT counts the number of times the element occurs in the report records, MINIMUM determines the smallest occurrence, etc. But sometimes you may want to compute data in larger groupings than are stored in the file. For instance, you may wish to summarize multiple occurrences of an element as though they were all part of a single occurrence.
As an example, suppose an accounting file stores each deposit as a separate element occurrence with an associated date value, and you want to know what the average monthly intake is. What you want is to sum the deposits within each month, then find the average of those sums:
Month Deposit The average Deposit is $73
----- -------
Jan $100 The average monthly deposits are
50 (150 + 215) / 2 = $182.50
Feb 60
110
45
Or in the same file you might want the maximum and mininum number of deposits per month. This requires a COUNT of deposits per month before one could compute minimum (2 deposits) or maximum (3 deposits).
Had the data in the above file been collected and stored by month, such that a real element kept the monthly sum or count, then the problem would be a simple one -- you would simply compute the average, minimum and maximum of those stored values. Or if each month's data were stored together as a single record, then a virtual element could be defined that represents the month's totals required. But what if the data is stored at a lower level -- for example, each record is a day's worth of deposits, or even a separate record for each deposit?
To accomplish the intermediate computation required you define a "summary element" that represents a single value extracted or computed from all the occurrences in a record or specified group of records. You may define up to 16 summary elements.
Summary elements are like dynamic elements in that they are not elements defined within the file definition, but rather entities created dynamically from values stored in the records. Unlike dynamic elements, they represent multiple element occurrences by a single value. They occur once per record or group of records and exist only within $REPORT.
A summary element is established by the DEFINE VALUE statement in $REPORT:
DEFINE VALUE name [AS] function element [BY group]
The "BY group" phrase lets you specify that the summary element is to be tied to a group of records. This option does not affect the way in which the current summary element is calculated, but means that the summary element only has a value at the level of the specified group and any higher level. The BY clause does have a profound effect, though, when summary elements are themselves objects of functions, either directly or as part of the definition of another summary element. (See the examples at the end of this section.)
If the final "BY group" is omitted, then values are computed within each record (think of a record as being the lowest level group). They are also accumulated to all higher report levels -- up to end of report -- such that placing the defined value at the end of groups or at the end of the report shows the running value up to that place in the report.
Once defined, a summary element can be referred to in the report's element list or in expressions using the "@element" form ("@element" and "@@element" are equivalent for summary elements). They can also be used in subsequent DEFINE VALUE statements. This enables the user to control more complex sequences of computations, like summing the minimum of averages, or averaging the sums of counts.
In the example above, you compute the average as follows:
SET FORMAT * DEFINE VALUE MONTH-SUM AS SUM DEPOSIT SET FORMAT * AT END OF REPORT AVG MONTH-SUM
Summary elements defined with the "BY group" option that are used in the report detail when summary mode is specified [See C.8.] print only in summary lines for that element's group and for control breaks at higher levels. Like other elements they can be used in function oriented columns that also accumulate values to higher groups or to the end of the report.
The following examples should illustrate how summary elements work. Note how the "BY group" phrase can be used in differing combinations with AT END OF GROUP statements. The four records used to produce these reports are:
SYSTEM = ALPHA; SYSTEM = ALPHA;
MONTH = JAN; MONTH = FEB;
SCHEDULE; SCHEDULE;
NAME = Smith; NAME = Smith;
HOURS = 30; HOURS = 32;
SCHEDULE; SCHEDULE;
NAME = Carter; NAME = Carter;
HOURS = 25; HOURS = 19;
SCHEDULE; SCHEDULE;
NAME = Jones; NAME = Jones;
HOURS = 15; HOURS = 42;
SYSTEM = BETA; SYSTEM = BETA;
MONTH = JAN; MONTH = FEB;
SCHEDULE; SCHEDULE;
NAME = Smith; NAME = Smith;
HOURS = 9; HOURS = 23;
SCHEDULE; SCHEDULE;
NAME = Carter; NAME = Carter;
HOURS = 3; HOURS = 17;
SCHEDULE; SCHEDULE;
NAME = Jones; NAME = Jones;
HOURS = 8; HOURS = 10;
SET FORMAT $REPORT System Month Name Hours
SET FORMAT * GROUPED BY SYSTEM, MONTH
SET FORMAT * DEFINE VALUE HRS.SUM AS SUM HOURS
SET FORMAT * DEFINE VALUE HRS.AVE AS AVE HOURS
SET FORMAT * + Hrs.Sum Hrs.Ave
SET FORMAT * AT END OF GROUP SYSTEM, COU HRS.SUM, AVE HRS.SUM, SUM HRS.AVE
+--------------------------------------------------------------+ | June 21, 1984 Page 1 | | | | System Month Name Hours Hrs.Sum Hrs.Ave | | -------- -------- -------- -------- -------- -------- | | | | ALPHA JAN Smith 30 70 23.33333 | | Carter 25 | | Jones 15 | | | | FEB Smith 32 93 31 | | Carter 19 | | Jones 42 | | | | *COU 2 | | *AVG 81.5 | | *SUM 54.33333 | | | | BETA JAN Smith 9 20 6.66667 | | Carter 3 | | Jones 8 | | | | FEB Smith 23 50 16.66667 | | Carter 17 | | Jones 10 | | | | *COU 2 | | *AVG 35 | | *SUM 23.33333 | | | | **COU 4 | | **AVG 58.25 | | **SUM 77.66667 | +--------------------------------------------------------------+
Here summary elements are defined at record level, then used in further calculations AT END OF GROUP. We could also have defined the functions in the element list as "SET FORMAT $REPORT System Month Person Hours Hours(SUM) Hours(AVE)", but then we couldn't have further manipulated these values in the END OF GROUP section.
SET FORMAT $REPORT System Month Person Hours SET FORMAT * GROUPED BY SYSTEM MONTH SET FORMAT * DEFINE VALUE HRS.SUM AS SUM HOURS BY SYSTEM SET FORMAT * DEFINE VALUE HRS.AVE AS AVE HOURS SET FORMAT * + HRS.SUM HRS.AVE SET FORMAT * AT END OF GROUP SYSTEM, COU HRS.SUM, AVE HRS.SUM, SUM HRS.AVE
+--------------------------------------------------------------+ | June 21, 1984 Page 1 | | | | System Month Name Hours Hrs.Sum Hrs.Ave | | -------- -------- -------- -------- -------- -------- | | | | ALPHA JAN Smith 30 23.33333 | | Carter 25 | | Jones 15 | | | | FEB Smith 32 31 | | Carter 19 | | Jones 42 | | | | *COU 1 | | *AVG 163 | | *SUM 54.33333 | | | | BETA JAN Smith 9 6.66667 | | Carter 3 | | Jones 8 | | | | FEB Smith 23 16.66667 | | Carter 17 | | Jones 10 | | | | *COU 1 | | *AVG 70 | | *SUM 23.33333 | | | | **COU 2 | | **AVG 116.5 | | **SUM 77.66667 | +--------------------------------------------------------------+
This example changes the report definition only in that the summary element HRS.SUM has a BY SYSTEM phrase added to it. This means that the HRS.SUM element only exists one time for each system group. It does not appear in the record detail because it is defined for a higher level group, but the calculations are still performed at the end of each system group. The COUNT function shows that there is now only a single occurrence of HRS.SUM for each system group, which in turn changes the average.
SET FORMAT $REPORT System Month Person Hours SET FORMAT * GROUPED BY SYSTEM MONTH SET FORMAT * DEFINE VALUE HRS.SUM AS SUM HOURS BY SYSTEM SET FORMAT * DEFINE VALUE HRS.AVE AS AVE HOURS SET FORMAT * + HRS.SUM HRS.AVE SET FORMAT * AT END OF GROUP MONTH, COU HRS.SUM, AVE HRS.SUM, SUM HRS.AVE
+--------------------------------------------------------------+ | June 21, 1984 Page 1 | | | | System Month Name Hours Hrs.Sum Hrs.Ave | | -------- -------- -------- -------- -------- -------- | | | | ALPHA JAN Smith 30 23.33333 | | Carter 25 | | Jones 15 | | | | *COU 0 | | *AVG 0 | | *SUM 23.33333 | | | | FEB Smith 32 31 | | Carter 19 | | Jones 42 | | | | *COU 0 | | *AVG 0 | | *SUM 31 | | | | BETA JAN Smith 9 6.66667 | | Carter 3 | | Jones 8 | | | | *COU 0 | | *AVG 0 | | *SUM 6.66667 | | | | FEB Smith 23 16.66667 | | Carter 17 | | Jones 10 | | | | *COU 0 | | *AVG 0 | | *SUM 16.66667 | | | | **COU 2 | | **AVG 116.5 | | **SUM 77.66667 | +--------------------------------------------------------------+
This third example changes the AT END OF GROUP statement to apply at the end of MONTH groups, rather than SYSTEM groups. Because the HRS.SUM element exists only at the end of SYSTEM groups, nothing exists for the element at the END OF GROUP sections defined for the MONTH element.
Most of the features of groups that you have read about in this chapter work the same for vertical reports as they do for horizontal ones. This section will cover the significant differences.
In vertical reporting, when you group one or more elements, SPIRES pulls the grouping elements out of the detail section of the report, as in this example:
-> set format $report option vertical -> set format * elements album-title album-number file label -> type June 26, 1993 Page 1 Album title: John Adams - Harmonium Album number: ECM//8214652 File: Composer Label: ECM Album title: John Adams - Shaker Loops Album number: New Albion/NA/14 File: Composer Label: New Albion -> set format * grouped by file, label -> type June 26, 1993 Page 1 FILE Composer LABEL ECM Album title: John Adams - Harmonium Album number: ECM//8214652 LABEL New Albion Album title: John Adams - Shaker Loops Album number: New Albion/NA/14
You can change the heading value by including the HEADING parameter in the GROUPED BY statement (not in the ELEMENT statement):
set format * grouped by file (heading='Filed under'), label
Notice that the heading value does not display with a colon as it does when used as a parameter on the ELEMENT statement.
Though you may start with an element in the detail that you later decide to group by, as in the example above, you sometimes know right from the start that you want to group by an element that you don't want in the detail. You might define the report this way in that case:
-> set format $report option vertical -> set format * elements album-title album-number -> set for * group by file(heading='FILE') label(heading='LABEL')
(That would create the same display as shown in the previous example.) You must include the HEADING parameters in the GROUPED BY statement to produce the group's headings, unless you intend to construct them yourself with PRINT in AT START OF GROUP statements.
If you want to include the element within the detail section, include an ELEMENT statement as usual, but also include the DISPLAY and HEADING parameters in the GROUPED BY statement:
-> set format $report option vertical -> set format * elements album-title album-number file label -> set format * grouped by file (display,heading='File'), label
Continuing the example above, the FILE element would be displayed both in the group section and in the detail section:
File Composer LABEL ECM Album title: John Adams - Harmonium Album number: ECM//8214652 File: Composer LABEL New Albion Album title: John Adams - Shaker Loops Album number: New Albion/NA/14 File: Composer
Important: You need both the DISPLAY and HEADING parameters. If you omit HEADING, the element will be displayed in the detail section, but no group heading will appear. (You may want to do that if you are constructing your own custom "at start of group" section.)
Instead of (or as well as) HEADING, you may specify the NAME parameter. The NAME value will be used in constructing the verbose summary statistic headings at the end of the group. And if HEADING is not specified, the NAME value will be used in its place to construct the start-of-group heading as well. (In other words, just as HEADING forces the group heading to appear, so does NAME in vertical reports.)
Summary statistics for groups were described earlier in this chapter. [See C.6.4, C.6.5, C.6.6.] Again, they work basically the same for vertical reports as for horizontal ones.
Other features that might be useful in vertical reports include:
The START OF PAGE and END OF PAGE sections are used to specify headers and footers for each page of the report. In addition to headers and footers, page formatting includes the specification of right and left margins, the number of lines per page, and line length.
This chapter describes the START OF PAGE and END OF PAGE sections, and the TITLE, LENGTH, LINES, and INDENT options.
$REPORT provides, by default, a page header that includes the following information:
- The current date in the form "Month day, year" (e.g. "Nov. 10, 1982"), in the left-hand corner.
- The page number in the form "Page n", in the right-hand corner.
You can add a title to the default page header by using the TITLE parameter of the OPTIONS command. For example,
SET FORMAT * OPTIONS TITLE 'Monthly Report'
centers the string 'Monthly Report' on the same line as the date and the page number. If your title is longer than the space remaining between the date and page number, the title will wrap to subsequent lines.
A single blank line separates the page header from the first row of column headings.
The page header appears at the top of the report one time when the report is displayed at the terminal. If the report is placed in the active file, the page header appears at the top of every page; the length of the page is determined by the LINES option. [See C.7.5.]
Carriage control is provided when a report is placed in the active file. This means that the entire report is moved over one column to the right and a "1" is placed in column 1 of the first line of the page header. The report can then be printed with the CC ("carriage control") option of the WYLBUR PRINT command (i.e., PRINT CC...). Note that this does not affect the columns of the printed report; column 1 of the report remains column 1 -- it just appears as column 2 in the active file. This also applies to font control characters added via the FONT command. [See C.5.6.]
If you would rather define your own header, use the AT START OF PAGE prefix and the PRINT command to place data values in the heading space. For example,
SET FORMAT * AT START OF PAGE, PRINT (ADJUST = CENTER) '- ' $PAGENO ' -' SET FORMAT * IN ROW 3, PRINT 'MONTHLY REPORT'// //$DATEOUT($UDATE,17)
creates a header that looks like this:
+------------------------------------------------------+ | - 1 - | | | | MONTHLY REPORT NOV 10, 1982 | | | +------------------------------------------------------+
If you create a START OF PAGE section (that is, issue any commands with the AT START OF PAGE prefix), the default page header is completely replaced.
If you do not want a page header at all, issue the command
SET FORMAT * AT START OF PAGE PRINT ' '
This creates a page header consisting of a single blank line.
For reports directed to the active file, you can include element references in the header. (The value will be taken from the first record on the page.) This would allow you to put "guide words" in the header, indicating which records are on the page. This feature is not available for reports directed to the terminal, however, because in that situation the records to appear on the terminal's "page" have not yet been accessed by the time that the header is executing.
If you want page numbering to begin at a number other than "1", you can set the system variable $PAGENO to whatever number you want to appear first. Issue the command:
SET PAGENO = n
This command must be issued after the SET FORMAT $REPORT command. You can either include it at the end of your report definition or issue it interactively before you issue the TYPE command.
The NEWPAGE command is not allowed in the START OF PAGE section. The IN ROW prefix and SKIP command [See C.5.3, C.5.4.] can be used for explicit placement of values in the section, and the FONT command [See C.5.6.] can be used to specify font control.
Page footers are created by defining an END OF PAGE section. Page footers only appear when the report is placed in the active file.
For example,
SET FORMAT * AT END OF PAGE, PRINT (CENTER) "Monthly Report" SET FORMAT * AT END OF PAGE, IN ROW 3, PRINT $CASE($DATEOUT($UDATE,17),10) SET FORMAT * AT END OF PAGE, IN ROW 3, PRINT (RIGHT) @@PROJECT
produces a footer like this:
+--------------------------------------------------------------+ | | | Monthly Report | | Nov 10, 1982 Salaries | +--------------------------------------------------------------+
A single blank line separates the last detail line from the first footer line, because the default starting row for all ending sections is row 2. You can eliminate this blank line by placing values explicitly in row 1 of the END OF PAGE section.
In our example above, the first PRINT expression ("Monthly Report") appears on row 2 of the END OF PAGE section because we did not specify any other row for it. Our next two PRINT expressions are placed explicitly in row 3. The page footer thus occupies 3 rows at the bottom of each page.
If an element reference appears in an expression placed in the END OF PAGE section, (e.g., PRINT @@PROJECT), the value is taken from the last record on the page.
The line length (i.e., the horizontal dimension of the overall report) is controlled by the LENGTH option. For example,
SET FORMAT * OPTIONS LENGTH = 45
sets the width of the report at 45 columns. The default width is the value of $LENGTH at the time the SET FORMAT $REPORT command is issued.
The LENGTH option only affects the default positioning of element values. You can override the right margin established by the LENGTH option by including explicit positioning values for an item.
Any SET LENGTH command issued in SPIRES once a report is established (by the SET FORMAT $REPORT command) has no effect on that report. If you are issuing commands interactively and wish to change the overall width of a report already established, issue a new OPTIONS command with the LENGTH parameter, and all columns are recomputed (unless, of course, they have explicit positioning specifications). Only one LENGTH can be in effect for the entire report. That is, you cannot include several LENGTH specifications for different sections to alter the width of parts of the report.
You can control the number of lines per page (including header and footer) by using the LINES option. For example,
SET FORMAT * OPTIONS LINES = 80
sets the number of lines per page to 80. You may specify any number from 1 to 255. The default value is equivalent to $LINEPP, which is 60 at the start of a SPIRES session.
Like LENGTH, only one LINES specification can be in effect at a time. Changing the value of $LINEPP does not affect the value of LINES once a report is established.
A report, by default, begins in column 1. You might want to change this to accomodate labels associated with column-bound functions or to allow sufficient space for the printed report to be bound. The left margin of the report is controlled with the INDENT keyword. For example,
SET FORMAT * OPTIONS INDENT = 12
causes the report to be moved 12 columns to the right. All column positions are relative to the INDENT value; that is, an INDENT value of 12 does not make column 1 become column 13. Indenting the report does not affect carriage control characters that appear in columns 1 and 2.
If you have functions bound to the left-most column and there is not sufficient space for the function label to print, an INDENT of 8 is automatically created. This can be overridden by explicitly specifying a different INDENT value. [See C.6.5.]
By placing data in the START and END OF REPORT sections of the report, you can create a title page and final report summaries (e.g., grand totals). This chapter describes the possible values that can be placed in these sections and how to use the AT START OF REPORT and AT END OF REPORT command prefixes.
The START OF REPORT section appears at the beginning of the report, before any detail information. Its primary purpose is to print prefatory material, so the PRINT command [See C.5.2.] is the main command used in this section.
For example, a simple title page is created with the following commands:
SET FORMAT * AT START OF REPORT SET FORMAT * IN ROW 10, PRINT (CENTER) "Monthly Report"
Or you can create a lengthy title page with several paragraphs of introductory material by putting each line of the text in a separate PRINT command, with consecutive row numbers, as follows:
SET FORMAT * AT START OF REPORT, IN ROW 1, PRINT 'First line' SET FORMAT * IN ROW 2, PRINT 'Second line' SET FORMAT * IN ROW 3, PRINT 'Third line' SET FORMAT * IN ROW 4, PRINT 'Fourth line' (etc.)
Or you can add a WYLBUR OPTIONS statement by placing it on the first row of the section.
SET FORMAT * AT START OF REPORT SET FORMAT * PRINT 'OPTIONS: CC UNN FORMS 9511 CHARS(TN12,BD12)'
Any element references ("@elem" or "@@elem") in a PRINT statement in the START OF REPORT section do not retrieve element values because no record has yet been accessed by the format.
Page and column headings do not print on title page(s). Also, title pages are not numbered; that is, page 1 is always the first page of the body of the report.
When you place the report in the active file, there is a page eject after the START OF REPORT section, before the first data record. By default, there is no carriage control (i.e., no "1" in column 1) at the beginning of the report. However, you can use the NEWPAGE command [See C.5.1.] in the START OF REPORT section to place a "1" in column 1 of the first line.
As with other sections, you can use the IN ROW prefix and the SKIP command [See C.5.3, C.5.4.] to control relative spacing of the rows, and the FONT command [See C.5.6.] to specify multiple character sets for the section.
The END OF REPORT section appears after the final summary generated by any END OF GROUP sections defined or after the last detail record if no END OF GROUP sections appear. It can be used for grand-total summaries or for closing text. The prefix AT END is equivalent to AT END OF REPORT.
The PRINT command [See C.5.2.] is used for placing values in the section. For example,
SET FORMAT * AT END OF REPORT PRINT (CENTER) "THE END"
prints "THE END" at the end of the report. It is centered on row 2 of the END OF REPORT section (the default starting row for all ending sections), and so is separated from the report by a single blank line.
Summing values for the END OF REPORT section is done exactly as for END OF GROUP sections. Values in the END OF REPORT section adhere to the rules described for column-bound functions in END OF GROUP sections. That is, if the element appears in the body of the report, the function value, by default, appears in that column. If there is no column for it, it appears on a separate row with the default label. [See C.6.5.]
The following example uses a data base of blood donors; each record has singly-occurring elements for NAME, CITY, and TOTAL.PINTS.
SET FORMAT $REPORT Name (5) Total.pints (50,10,R,HEADING = 'Total') SET FORMAT * GROUPED BY CITY (NOFINAL) SET FORMAT * DEFINE VALUE T AS SUM TOTAL.PINTS BY CITY SET FORMAT * AT END OF GROUP CITY, PRINT 'Total for ' @CITY ': ' @T SET FORMAT * DEFINE VALUE DONOR.COUNT AS COUNT NAME SET FORMAT * AT END OF REPORT, PRINT (CENTER) '-----------' SET FORMAT * IN ROW 4, PRINT 'Number of Donors: ' @DONOR.COUNT SET FORMAT * IN ROW 5, PRINT 'Total Number of Pints: ' @T
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Name Total | | ------------------------------------------- ---------- | | | | Hills, Beverly 11 | | Dew, Pinky 5 | | Hamlet, Ophelia 1 | | | | Total for Elsonora: 17 | | | | William, Harvey 1 | | Brewster, Harvey 9 | | Harvey, William 1 | | Larsen, John 1 | | | | Total for Mountain View: 12 | | | | Moreblood, Alex 2 | | Blutter, Rhed 2 | | Claret, Van E. 1 | | Harrison, Chevy 10 | | Brown, Robert 1 | | Kazoo, Lainie 1 | | Weinberger, Jaspar 4 | | | | Total for Palo Alto: 21 | | | | Leigh, Janet 1 | | Blut, Werner 2 | | Tuck, Brian 5 | | | | Total for Redblood City: 8 | | | | ------------ | | | | Number of Donors: 17 | | Total Number of Pints: 58 | +--------------------------------------------------------------+
In this report, we've defined two columns, and grouped the records by a third element, CITY. By including the NOFINAL parameter on the GROUPED BY command, we suppress the final repetition of any values placed in the END OF GROUP CITY section. At the end of every CITY group we print the total number of pints contributed. We create an END OF REPORT section to provide different information from the the END OF GROUP section. Because arithmetic functions are not directly allowed in PRINT expressions, we define a summary value that is the count of the number of NAME elements and reference that value in the PRINT expression.
So far the $REPORT report definitions in this manual have assumed that detail information would be printed for each record, and that summary information would be contained in END OF GROUP or END OF REPORT sections defined to print within or at the end of the record listings. However, sometimes you may not want to see these detailed record listings; summary information (of groups or perhaps for the report as a whole) may be all you want.
There are two general ways you can produce a summary report. You can define only ending sections, which are by definition summary sections. This means that no DETAIL sections are defined and no element list is included in the definition. The second way is to use the SUMMARIZE option of the OPTIONS command. This causes each group to be represented by a single line that includes only group elements and summary elements. Group elements are those elements listed on the GROUPED BY command [See C.6.1.] and represent the value(s) that are constant across a group. Summary elements are those elements that have been defined either with the DEFINE VALUE command [See C.6.7.] or with functions in the element list. [See C.4.2.]
This chapter describes and illustrates each approach to creating summary reports.
A report definition does not have to include a DETAIL section. You may define only END OF GROUP or END OF REPORT sections and produce a report that contains only the summary information defined for these sections. The simplest summary definition includes only an END OF REPORT prefix and function specifications, as follows:
SET FORMAT $REPORT AT END OF REPORT, SUM HRS, COUNT MON, AVERAGE HRS
This produces the following report:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | | | **SUM HRS 131 **COU MON: 5 AVG HRS: 10.91667 | +--------------------------------------------------------------+
You can add END OF GROUP sections and PRINT expressions as follows:
SET FORMAT $REPORT GROUPED BY SYSTEM SET FORMAT * AT START OF GROUP SYSTEM PRINT 'System: ' @SYSTEM SET FORMAT * AT END OF GROUP SYSTEM SUM HOURS (5) SET FORMAT * IN ROW 3 COUNT MONTH (5) SET FORMAT * LABEL SUM AS 'Total Hours: ' SET FORMAT * LABEL COUNT AS 'Number of Months: '
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | | | System: ALPHA | | | | Total Hours: 76 | | Number of Months: 16 | | | | System: BETA | | | | Total Hours: 46 | | Number of Months: 16 | | | | Total Hours: 122 | | Number of Months: 32 | +--------------------------------------------------------------+
This gives a count of the number of occurrences of MONTH for each SYSTEM and a sum of the HOURS, plus a grand-total of these values at the end. The LABEL command [See C.6.6.] changes the default label for the functions. [See C.6.4 for details about the END OF GROUP section, C.8.2 for details about the END OF REPORT section.]
With the SUMMARIZE option of the OPTIONS command you can cause all records in each group or all records in the report to be represented by a single summary line. This means that instead of every value appearing, only those values that represent a summary of values appear. Summary elements or values are those values defined with the DEFINE VALUE command or with an arithmetic function in the element list. Also, if you have groups of records defined with the GROUPED BY command, group element values may appear in the summary report.
Using the SUMMARIZE option only affects the DETAIL sections; all element values in the DETAIL sections do not appear in a summary report. Any data placed in other sections of the report still prints. You can lay out your report detail as you normally would, using only group and summary elements. When you add the SUMMARIZE option, it treats groups of records or the entire set of records as if it were a single record, producing a complete "detail" for that group of records.
By combining the SUMMARIZE option with the GROUPED BY command and summary elements, you can create summary reports of varying complexity. But you must remember that detail elements are not automatically summed; summary elements must be defined.
So, for example, if you have the following report definition
SET FORMAT $REPORT SYSTEM (1,12) NAME (+3,12) HOURS (+3,5,RIGHT) SET FORMAT * GROUPED BY SYSTEM, NAME SET FORMAT * AT END OF GROUP NAME, SUM HOURS, AVERAGE HOURS
you gain nothing by adding the SUMMARIZE option because there are no summary elements present. If you want only the summary values, this report is better formatted if defined with summary elements in the element list as follows:
SET FORMAT $REPORT SYSTEM NAME HOURS(SUM) HOURS(AVERAGE) SET FORMAT * GROUPED BY SYSTEM, NAME SET FORMAT * OPTIONS SUMMARIZE
The sum and average values are not to the record level but to each of the groups.
When there are no groups defined, a single "detail" is produced that represents all the records in the report. Only summary elements appear -- either those defined in the element list or with the DEFINE VALUE command. For example, the following commands define several summary elements, which print once for every record (assume that HRS is a multiply occurring element), as follows:
SET FORMAT $REPORT DEFINE VALUE HRS.SUM AS SUM HRS SET FORMAT * DEFINE VALUE HRS.COU AS COU HRS SET FORMAT * ELEMENTS SYSTEM MONTH HRS.SUM HRS.COU
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | SYSTEM MONTH HRS.SUM HRS.COU | | ------------- ------------- ------------- ------------- | | ABC Jan 16 2 | | ABC Feb 14 3 | | ABC Mar 7 2 | | XYZ Jan 92 3 | | XYZ Feb 2 2 | +--------------------------------------------------------------+
If we add the SUMMARIZE option we get the following display:
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | SYSTEM MONTH HRS.SUM HRS.COU | | ------------- ------------- ------------- ------------- | | 131 12 | +--------------------------------------------------------------+
You get the same result if the summary elements had been in the element list as follows:
SET FORMAT $REPORT SYS MON HRS(SUM) HRS (COU) SET FORMAT * OPTIONS SUMMARIZE
The report produced in Section C.9.1 with the AT END OF REPORT prefix could be produced in a different format but with the same information using the SUMMARIZE option as follows:
SET FORMAT $REPORT HRS(SUM) MON(COUNT) HRS(AVERAGE) SET FORMAT * OPTIONS SUMMARIZE
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | HRS(SUM) MON(COU) HRS(AVG) | | ------------------ ------------------ ------------------ | | 131 5 10.91667 | +--------------------------------------------------------------+
As described above, if no groups are indicated, i.e. there is no GROUPED BY statement, then only the final summary is generated. If you do have groups defined, SUMMARIZE works in conjunction with the GROUPED BY statement to cause summary to the lowest (last) group specified. A single line (i.e., a single "detail") is printed for each group, with intermediate summing to each group level. (Remember that the elements specified on the GROUPED BY statement must correspond to the elements specified on a SEQUENCE command; if the records are not sorted properly, their grouping will be unpredictable.)
All group and summary elements print on each line. If a summary element is defined at a group level (i.e., with the "BY group" parameter), it only prints at that level. Summary elements defined with a "BY group" parameter and used in the report detail ONLY print when the SUMMARIZE option is used. [See C.6.7.] They only print for that group and higher level groups. Although all column headings are produced, only columns that represent summary elements or group elements have values.
Let's say we have a data base of records with the following elements:
SYSTEM NAME MONTH HOURS
A single record contains a single hours entry, but several records might exist for a person each month.
In the following example, we group the records by name and create two summary elements in the detail section. We get a single line of summary information for each name.
SET FORMAT $REPORT Name (1,12) System (+3,12) SET FORMAT * + Hours (+3,12,R,SUM,HEADING = Hours) SET FORMAT * + Hours (+3,12,R,AVERAGE,HEADING = Average) SET FORMAT * GROUPED BY NAME SET FORMAT * OPTIONS SUMMARIZE
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | Name System Hours Average | | ------------ ------------ ------------ ------------ | | MASON 60 3.75 | | STARR 56 4 | | | | 116 3.86667 | +--------------------------------------------------------------+
No values appear for the SYSTEM element because it is not a group element or a summary element.
In the next example, we group records by two elements, so we get a summary line for both groupings. The numbers to the left of the box represent the group being summarized: "2" for each month summary, "1" for each system summary, and "0" for the summary of the entire report.
SET FORMAT $REPORT DEFINE VALUE HOURS.SUM AS SUM HOURS SET FORMAT * System Month Name Hours.sum (HEADING = 'Total Hours') SET FORMAT * GROUPED BY SYSTEM MONTH SET FORMAT * OPTIONS SUMMARIZE
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | System Month Name Total Hours | | ------------- ------------- ------------- ------------- | 2| ALPHA JAN 36 | 2| ALPHA FEB 40 | 1| ALPHA 76 | 2| BETA JAN 21 | 2| BETA FEB 19 | 1| BETA 40 | | | 0| 116 | +--------------------------------------------------------------+
If the NAME element had been included on the GROUPED BY command, we would have gotten another level of summary, that is, a line of summary for each unique name within each month.
The next example shows how the levels of summary generated by having several groups defined can be controlled by adding the "TO element" clause to the SUMMARIZE option. If you had specified three group elements on the GROUPED BY command, you would get a single line of summary for each unique occurrence of each group element. For example,
SET FORMAT $REPORT DEFINE VALUE HOURS.SUM AS SUM HOURS SET FORMAT * System Month Name Hours.sum (HEADING = 'Total Hours') SET FORMAT * GROUPED BY SYSTEM MONTH NAME SET FORMAT * OPTIONS SUMMARIZE
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | System Month Name Total Hours | | ------------- ------------- ------------- ------------- | 3| ALPHA JAN MASON 22 | 3| STARR 14 | 2| JAN 36 | 3| FEB MASON 18 | 3| STARR 22 | 2| FEB 40 | 1| ALPHA 76 | 3| BETA JAN MASON 8 | 3| STARR 13 | 2| JAN 21 | 3| FEB MASON 12 | 3| STARR 7 | 2| FEB 19 | 1| BETA 40 | | | 0| 116 | +--------------------------------------------------------------+
To specify the level of summarization you want, add a "TO" clause to the SUMMARIZE command as follows:
SET FORMAT * OPTIONS SUMMARIZE TO element
This prints only the summarizations for the element specified and all lower level groupings.
For example, the next two reports have a "TO" clause that changes the level of summarization in the above report.
SET FORMAT $REPORT DEFINE VALUE HOURS.SUM AS SUM HOURS SET FORMAT * System Month Name Hours.sum (HEADING = 'Total Hours') SET FORMAT * GROUPED BY SYSTEM MONTH, NAME SET FORMAT * OPTIONS SUMMARIZE TO MONTH
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | System Month Name Total Hours | | ------------- ------------- ------------- ------------- | 3| ALPHA JAN MASON 22 | 3| STARR 14 | 2| JAN 36 | 3| FEB MASON 18 | 3| STARR 22 | 2| FEB 40 | 3| BETA JAN MASON 8 | 3| STARR 13 | 2| JAN 21 | 3| FEB MASON 12 | 3| STARR 7 | 2| FEB 19 | +--------------------------------------------------------------+
As you can see, the summary lines representing levels "0" and "1" that were marked in the previous report have been suppressed by the inclusion of the "TO MONTH" clause on the OPTIONS SUMMARIZE command.
With the "TO NAME" clause included, you get only the lowest level of summary.
SET FORMAT $REPORT DEFINE VALUE HOURS.SUM AS SUM HOURS SET FORMAT * System Month Name Hours.sum (HEADING = 'Total Hours') SET FORMAT * GROUPED BY SYSTEM MONTH, NAME SET FORMAT * OPTIONS SUMMARIZE TO NAME
+--------------------------------------------------------------+ | Nov. 10, 1982 Page 1 | | | | System Month Name Total Hours | | ------------- ------------- ------------- ------------- | 3| ALPHA JAN MASON 22 | 3| STARR 14 | 3| FEB MASON 18 | 3| STARR 22 | 3| BETA JAN MASON 8 | 3| STARR 13 | 3| FEB MASON 12 | 3| STARR 7 | +--------------------------------------------------------------+
This chapter includes two tables that serve as quick reference guides to the commands, syntax, and defaults in the report writer command language.
SET FORMAT $REPORT statement
SET FORMAT * statement
[ELEMENT|+] element [(COLUMN=n, WIDTH=n, INDENT=n,
ADJUST=LEFT|RIGHT|CENTER|TRUNCATE|MARGINS|WRAP|
JUSTIFY|ALIGN, HEADING=string, EDIT=mask,
function, TYPE={NUMERIC|TEXT},
BUILD [='string'|= X'string'],
DEFAULT='string')]
DEFINE VALUE name [AS] function element [BY group]
OPTIONS LENGTH=n, LINES=n, INDENT=n, TITLE=string,
CLUSTER=n, MAXROWS=n, NOGROUP, [NO]BREAK,
[NO]REPORT, [NO]HEADING, NOUNDERLINE|UNDERLINE=x,
[NO]SUMMARIZE [TO element],
ADJUST [TEXT|NUMERIC]=LEFT|RIGHT|CENTER|TRUNCATE|
MARGINS|WRAP|JUSTIFY|ALIGN,
[NO]DEFAULT [ALL|TEXT|NUMERIC]='value',
DELIMITER=[X]'character', [NO]ELEMINFO,
FUNCTIONS={TERSE|VERBOSE}, [NO]PAGE,
[NO]QUOTE [ALL|TEXT|NUMERIC],
GAP=n, [NO]SQUEEZE, HORIZONTAL|VERTICAL
GROUPED BY element [([NO]FINAL, [NO]DISPLAY, BLANKS=n,
NOHEADING|HEADING='string', NAME='string')],
element ...
LABEL function [AS] expression
Detail: AT {[START|TOP|END|BOTTOM} OF DETAIL, [IN ROW n],
[+|ELEMENTS] element-list,
[NO]NEWPAGE [=n], [NO]FRONTPAGE [=n],
SKIP=n, FONT=n,
PRINT [(parameters)] expression
Group: AT {START|TOP} OF GROUP element, [IN ROW n],
[NO]NEWPAGE [=n], [NO]FRONTPAGE [=n],
SKIP=n, FONT=n,
PRINT [(parameters)] expression
AT {END|BOTTOM} OF GROUP element, [IN ROW n],
[NO]NEWPAGE [=n], [NO]FRONTPAGE [=n],
SKIP=n, FONT=n,
function [(parameters)],
PRINT [(parameters)] expression
Page: AT {START|TOP|END|BOTTOM} OF PAGE, [IN ROW n],
SKIP=n, FONT=n,
PRINT [(parameters)] expression
Report: AT {START|TOP} [OF REPORT], [IN ROW n],
[NO]NEWPAGE [=n], [NO]FRONTPAGE [=n],
SKIP=n, FONT=n,
PRINT [(parameters)] expression
AT {END|BOTTOM} [OF REPORT], [IN ROW n],
[NO]NEWPAGE [=n], [NO]FRONTPAGE [=n],
SKIP=n, FONT=n,
function [(parameters)],
PRINT [(parameters)] expression
PRINT Parameters: COLUMN=n, WIDTH=n, INDENT=n, EDIT=mask,
ADJUST=LEFT|RIGHT|CENTER|
TRUNCATE|MARGINS|WRAP|JUSTIFY,
FONT=n, [NO]FINAL,
HEADING='string', TYPE=TEXT|NUMERIC
Function Parameters: [NO]BIND, COLUMN=n, WIDTH=n,
ADJUST=LEFT|RIGHT|CENTER,
LABEL=string, EDIT=mask,
[NO]FINAL, TYPE=TEXT|NUMERIC
A report definition may begin with the DEFINE VALUE command or an OPTIONS statement. The first subsequent SET FORMAT * statement that is not DEFINE VALUE or OPTIONS is then taken as the initial element list. Note that if your report begins with elements whose names are DEFINE, OPTIONS, LABEL, FONT, PRINT, or NEWPAGE (or an abbreviation of these) then you must include the ELEMENT keyterm at the start of that list. Likewise, if your first element name is "ELEMENT" or an abbreviation of same, the keyterm ELEMENT is required to prevent your first term from being interpreted as the keyterm.
String values, such as those for EDIT or HEADING, need not be enclosed in quotation marks or apostrophes unless they contain blanks, commas, quotation marks, or apostrophes.
The following limits apply to a report definition:
- Up to 100 elements can be specified. [C.4.2]
- Structures up to a nested level of 8 can be accessed. [C.4.2.2]
- Up to 32 dynamic elements can be used. [C.4.2.3]
- Up to 5 group elements can be specified. [C.6.1]
- Up to 30 arithmetic functions can be used (10 in a DEFINE
VALUE command, up to 30 as element parameters, and up
to 20 in ending sections). [C.6.5]
- Column headings can be up to 36 characters, in 3 parts. [C.4.3.5]
- PRINT statements can contain up to 3 expressions of 132
characters. [C.5.2]
- The report can have no more than 64 literals or expressions
(PRINT expressions, LABEL expressions, literals in the
element list). [C.5.2]
- Up to 255 lines per page can be specified. [C.7.5]
- Packed decimal values will have 13 digits of precision. [C.6.5]
COMMAND SYNTAX
PARAMETER (section DEFAULT (if no default is listed, no action is
for description) taken unless specified in the report definition.)
------------------------------------------------------------------------------
ELEMENT (C.4.2) | [ELEMENT|+] element [(parameters)], element ....
|
COLUMN (C.4.3.1) | [COLUMN =] n
| Default = (computed by $REPORT)
WIDTH (C.4.3.2) | [WIDTH =] n
| Default = (computed by $REPORT)
ADJUST (C.4.3.3) | ADJUST = LEFT|RIGHT|CENTER|
| TRUNCATE|MARGINS|WRAP|JUSTIFY|ALIGN
| Default = MARGINS, LEFT except for edit masks
BUILD (C.4.3.3) | BUILD [= 'string'|= X'string']
INDENT (C.4.3.4) | INDENT = n
| Default = 0
HEADING (C.4.3.5) | HEADING = string (or) string//string//string
| Default: element name as typed in element list
EDIT (C.4.3.6) | EDIT = mask
functions (C.4.4) | SUM|COUNT|AVERAGE|MINIMUM|MAXIMUM|STD
| [(parameters)]
TYPE (C.4.3.7) | TYPE = {NUMERIC|TEXT}
DEFAULT (C.4.3.8) | DEFAULT = 'string'
------------------------|-----------------------------------------------------
OPTIONS (C.4.5) | OPTIONS option, option, option....
|
HORIZONTAL|VERTICAL | HORIZONTAL|VERTICAL
(C.4.7) | Default = HORIZONTAL
LENGTH (C.7.4) | LENGTH = n
| Default = 72 or $LENGTH
LINES (C.7.5) | LINES = n
| Default = 60 or $LINEPP
INDENT (C.7.6) | INDENT = n
| Default = 0
TITLE (C.7.1) | TITLE = string
CLUSTER (C.4.5.4) | CLUSTER = n
MAXROWS (C.4.5.2) | MAXROWS = n
| Default = 100
NOGROUP (C.6.2) | NOGROUP
BREAK (C.4.5.1) | [NO]BREAK
| Default = NOBREAK
REPORT (C.4.5.3) | [NO]REPORT
| Default = REPORT
HEADING (C.4.3.5) | [NO]HEADING
| Default = HEADING
UNDERLINE (C.4.3.5) | NOUNDERLINE|UNDERLINE = x
| Default: UNDERLINE = '-'
SUMMARIZE (C.9.2) | [NO]SUMMARIZE [TO element]
| Default = NOSUMMARIZE
(OPTIONS continued on next page)
------------------------------------------------------------------------------
OPTIONS (continued) | OPTIONS option, option, option....
|
ADJUST (C.4.5.6) | ADJUST [TEXT|NUMERIC] = LEFT|RIGHT|CENTER|
| TRUNCATE|MARGINS|WRAP|JUSTIFY|ALIGN
DEFAULT (C.4.5.5) | [NO]DEFAULT [ALL|TEXT|NUMERIC] = 'value'
DELIMITER (C.4.5.8) | DELIMITER = [X]'character'
ELEMINFO (C.4.6) | [NO]ELEMINFO
| Default = ELEMINFO
FUNCTIONS (C.6.5) | FUNCTIONS = {TERSE|VERBOSE}
| Default = TERSE
PAGE (C.4.5.3) | [NO]PAGE
| Default = PAGE
QUOTE (C.4.5.8) | [NO]QUOTE [ALL|TEXT|NUMERIC]
| Default = NOQUOTE
GAP (C.4.5.7) | GAP = n
| Default = 2
SQUEEZE (C.4.5.8) | [NO]SQUEEZE
| Default = NOSQUEEZE
------------------------|-----------------------------------------------------
GROUPED BY (C.6.1) | GROUPED BY element [(parameters)], element ...
|
FINAL (C.6.1.1) | [NO]FINAL
| Default = FINAL
DISPLAY (C.6.1.2) | [NO]DISPLAY
| Default = NODISPLAY
BLANKS (C.6.1.3) | BLANKS = n
| Default = 1
HEADING (C.6.1.4) | NOHEADING|HEADING = 'string'
| Default = NOHEADING
NAME (C.6.1.4) | NAME = 'string'
| Default: element name
------------------------|-----------------------------------------------------
PRINT (C.5.2) | PRINT [(parameters)] expression
|
COLUMN (C.5.2) | [COLUMN = ] n
| Default = 1
WIDTH (C.5.2) | [WIDTH = ] n
| Default = length of expression
INDENT (C.5.2) | INDENT = n
| Default = 0
ADJUST (C.5.2) | ADJUST = LEFT|RIGHT|CENTER|
| TRUNCATE|MARGINS|WRAP|JUSTIFY
| Default = TRUNCATE, LEFT except for edit masks
FONT (C.5.2) | FONT = n
BOLD|ITALIC (C.5.2) | BOLD|ITALIC
FINAL (C.5.2) | [NO]FINAL
| Default = FINAL
HEADING (C.5.2) | HEADING = 'string'
TYPE (C.5.2) | TYPE = TEXT|NUMERIC
------------------------------------------------------------------------------
------------------------------------------------------------------------------
|
functions (C.6.5) | SUM|MINIMUM|MAXIMUM|COUNT|AVERAGE|STD
| [(parameters)]
|
BIND (C.6.5) | [NO]BIND
| Default = BIND
COLUMN (C.6.5) | [COLUMN = ] n
| Default: same as element
WIDTH (C.6.5) | [WIDTH = ] n
| Default: length of value
ADJUST (C.6.5) | ADJUST = LEFT|RIGHT|CENTER
| Default: same as element
BOLD|ITALIC (C.6.5) | BOLD|ITALIC
LABEL (C.6.5) | LABEL = string
| Default: function name
EDIT (C.6.5) | EDIT = mask
FINAL (C.6.5) | [NO]FINAL
| Default = FINAL
TYPE (C.6.5) | TYPE = TEXT|NUMERIC
------------------------|-----------------------------------------------------
|
DEFINE VALUE (C.6.7) | DEFINE VALUE name [AS] function [BY group]
------------------------|-----------------------------------------------------
|
LABEL (C.6.6) | LABEL function [AS] expression
------------------------------------------------------------------------------
------------------------------------------------------------------------------ SECTION-SPECIFIC COMMANDS
SECTION SYNTAX
COMMAND (section DEFAULT (if no default is listed, no action is
for description) taken unless specified in the report definition.)
------------------------------------------------------------------------------
------------------------------------------------------------------------------
|
DETAIL (C.4.1) | AT {START|TOP|END|BOTTOM} OF DETAIL [,IN ROW n]
|
ELEMENT (C.4.2) | [ELEMENT|+] element [(parameters)], element....
NEWPAGE (C.5.1) | [NO]NEWPAGE [=n]
| Default: no page eject
FRONTPAGE (C.5.1) | [NO]FRONTPAGE [=n]
| Default: no page eject
SKIP (C.5.4) | SKIP = n
FONT (C.5.6) | FONT = n
PRINT (C.5.2) | PRINT [(parameters)] expression
------------------------|-----------------------------------------------------
|
START OF GROUP (C.6.3) | AT {START|TOP} OF GROUP [,IN ROW n]
|
NEWPAGE (C.5.1) | [NO]NEWPAGE [=n]
| Default: no page eject
FRONTPAGE (C.5.1) | [NO]FRONTPAGE [=n]
| Default: no page eject
SKIP (C.5.4) | SKIP = n
FONT (C.5.6) | FONT = n
PRINT (C.5.2) | PRINT [(parameters)] expression
------------------------|-----------------------------------------------------
|
END OF GROUP (C.6.4) | AT {END|BOTTOM} OF GROUP [,IN ROW n]
|
NEWPAGE (C.5.1) | [NO]NEWPAGE [=n]
| Default: no page eject
FRONTPAGE (C.5.1) | [NO]FRONTPAGE [=n]
| Default: no page eject
SKIP (C.5.4) | SKIP = n
FONT (C.5.6) | FONT = n
PRINT (C.5.2) | PRINT [(parameters)] expression
functions (C.6.5) | SUM|COUNT|MINIMUM|MAXIMUM|AVERAGE|STD
| [(parameters)]
------------------------------------------------------------------------------
|
PAGE (C.7.2, C.7.3) | AT {START|TOP|END|BOTTOM} OF PAGE [,IN ROW n]
|
SKIP (C.5.4) | SKIP = n
FONT (C.5.6) | FONT = n
PRINT (C.5.2) | PRINT [(parameters)] expression
------------------------------------------------------------------------------
------------------------------------------------------------------------------
|
START OF REPORT (C.8.1)| AT {START|TOP} OF REPORT [,IN ROW n]
|
NEWPAGE (C.5.1) | [NO]NEWPAGE [=n]
| Default: no page eject
FRONTPAGE (C.5.1) | [NO]FRONTPAGE [=n]
| Default: no page eject
SKIP (C.5.4) | SKIP = n
FONT (C.5.6) | FONT = n
PRINT (C.5.2) | PRINT [(parameters)] expression
------------------------|-----------------------------------------------------
|
END OF REPORT (C.8.2) | AT {END|BOTTOM} OF REPORT [,IN ROW n]
|
NEWPAGE (C.5.1) | [NO]NEWPAGE [=n]
| Default: no page eject
FRONTPAGE (C.5.1) | [NO]FRONTPAGE [=n]
| Default: no page eject
SKIP (C.5.4) | SKIP = n
FONT (C.5.6) | FONT = n
PRINT (C.5.2) | PRINT [(parameters)] expression
functions (C.6.5) | SUM|COUNT|MINIMUM|MAXIMUM|AVERAGE|STD
| [(parameters)]
------------------------------------------------------------------------------
If you have defined a report that will be used frequently, you will probably want to save the report definition so that it can be re-used. One way to save $REPORT commands for later execution was described in Section C.3.3.
Another method is to use the GENERATE FORMAT command to create a report format definition, in formats language, based on your $REPORT commands. If you create a report format, you can then simply name the format in a SET FORMAT command instead of issuing a series of $REPORT commands.
There are several benefits of using the GENERATE FORMAT command:
1. A compiled format written in formats language is more efficient than a
general system format such as $REPORT.
2. You and your subfile's users will probably find it easier to remember
a simple format name than a series of $REPORT commands.
3. A programmer can use the generated report format as the basis for
further customization. Since SPIRES generates much of the formats code
for you, you can save a considerable amount of programming time.
There are three simple steps required to generate a format from $REPORT:
1. Select the subfile and issue the $REPORT (and DEFINE ELEMENT)
commands that produce the desired report.
2. Issue the GENERATE FORMAT command and answer the questions
it asks.
3. Compile the format.
Each step is described in detail below.
The first step is to select the subfile for which the format will be generated. Then type the $REPORT commands to create your report. You should also issue commands to establish any dynamic elements that will be used in the report. For example:
-> select employees
-> define element monthly.sal as @salary/12
-> set for $report emp.name monthly.sal
(etc.)
The syntax of the command is simply
GENERATE FORMAT
Next, the format generator asks you a few questions. You can always type a question mark (?) or the word HELP in response to a prompt to get more information about any of the questions. Here is an example of a GENERATE FORMAT session:
-> generate format
-Welcome to the $REPORT code generator. This utility will create a
format that duplicates the $REPORT format you have created. You may
type ? or HELP in response to any question to receive help.
:Format ID? monthly.report
:Format Name? monthly report
-Please wait for code generation to complete
-Format GQ.DOC.MONTHLY.REPORT has been added to the FORMATS subfile.
Your next step is to compile the generated format. To do this, type:
-> select formats
-> compile GQ.DOC.MONTHLY.REPORT - to compile your format
->
Format definitions are stored in a public SPIRES subfile called FORMATS. The GENERATE FORMAT command creates a format definition in the proper form and adds it to the FORMATS subfile for you. The Format ID that you enter will be used as the identifying element (the key) of the FORMATS record.
The name that you enter in response to the "Format Name" prompt is the name that you will use with the SET FORMAT command to identify the format.
As the instructions indicate, before you can use the new format, you must compile it. (The compile step translates the high-level formats language into a lower-level machine language.)
To compile your new format, you must select the FORMATS subfile and use the COMPILE command:
-> select formats
-> compile gq.doc.monthly.report
-Compiled format: MONTHLY REPORT
-Format definition compiled
->
The message "Format definition compiled" indicates that the compile step was successful.
Though it is unlikely, you may receive an error message indicating that the format did not compile. If so, see your SPIRES consultant for assistance.
After the format is compiled, you may use it with your subfile.
-> select employees -> define element monthly.sal as @salary/12 -> set filter for monthly.sal where monthly.sal > 50000 -> set format monthly report -> find dept accounting -Result: 54 EMPLOYEES -> sequence emp.name -> in active type
Notice that the name used with the SET FORMAT command is the name that you entered in response to the "Format Name" prompt earlier. The format will appear in the list displayed by the SHOW FORMATS command on the day after the definition has been compiled. [See B.4.6.]
The command SET FORMAT MONTHLY REPORT replaces the $REPORT commands that were necessary before the format was generated. You must still issue the commands that define your report environment. For example:
- DEFINE ELEMENT (to specify dynamic elements used in the report) - SET FILTER (to filter element or structure occurrences) - FIND (to establish the report population) - SEQUENCE (to sort the records)
The GENERATE FORMAT utility automatically adds frames to your format to call the Prism load-format $PRISM.OVERFLOW. This will facilitate installation of the report format in Prism. [See Section 9.1 in "Prism Applications".]
If you are familiar with the SPIRES formats language, you can make changes to the generated format definition, update the record in the FORMATS subfile, and recompile the format.
Even if you do not know the formats language, you can revise your format. If the changes you wish to make are ones that can be defined with the $REPORT command language, you can follow the procedure outlined here to add the changes to the generated format.
1. Select the subfile and issue the new $REPORT and DEFINE ELEMENT
commands to create the report.
2. Issue the GENERATE FORMAT command. At the prompts for "Format ID"
and "Format Name" enter the ID and Name of the format that you want
to modify. The format generator will ask you to verify that it is
OK to replace the old version of the format.
3. In the compile step, use the REFORMAT command instead of FORMAT, to
indicate that you want to recompile a revised format definition.
[For information about format definitions, see the SPIRES manuals "A Guide to Output Formats -- a SPIRES Primer" or "SPIRES Formats".]
Subfile modification is the SPIRES term that encompasses
- adding new records to the subfile;
- updating (modifying) old records in the subfile;
- removing records from the subfile.
You will probably need to know the basic commands of subfile modification (sometimes called "subfile updating" or, perhaps unfortunately, "record updating") if you want to add, update or remove records in a SPIRES subfile. The word "probably" was used because more and more files created in SPIRES use an "interface" that sits between the user and SPIRES. The interface has its own commands that the user issues (or the user responds to a menu), and the interface then converts the user's desire into the corresponding SPIRES commands, eliminating the need for the user to know the SPIRES command language. "Prism" is such an interface, for example.
This part assumes that you will not be using such an interface, but that you will be using "standard SPIRES", i.e., responding to the SPIRES prompt with the SPIRES commands discussed here. If you will always be using SPIRES files through an interface, you may not need to know the material in this part of the manual. However, if you will be creating your own SPIRES files, this material is very practical, since the file definition and other components of a SPIRES data base are themselves records in SPIRES subfiles that must be added, updated and sometimes removed.
A general introduction to this material appears in the primer "A Guide to Data Base Development", chapter 2.
There are public subfiles that you may be able to use if you want to practice the subfile modification commands you will learn here. For example, the subfiles RESTAURANT, PEOPLE and BLOOD DONORS may be available for you to add records to. You may be able to remove records from these subfiles as well, but if you do, please "unqueue" your removal requests, so that there are records available to users who follow you! [See D.4.2.]
If you want your own subfile to modify, you need to define a file. The file definition process is discussed in detail in the documents "SPIRES File Definition" and "SPIRES File Definer". The SPIRES primer "A Guide to Data Base Development" is a good introduction to creating files.
A file definition establishes the fundamental structure of the file and its subfiles. The file definition:
- determines the types of goal records and index records in each subfile,
- describes the nature and relationship of the data elements in the records, and
- specifies the rules that apply to entry and indexing of data, as well as to searching and displaying the results.
For example, the file definition of PLANTBIO indicates that a subfile of the file contains bibliographic citations in the field of plant biology. The definition further specifies that each goal record in the subfile must contain an identification number, an author, a title, publication information, and the author's affiliation, as well as privacy restrictions on the various data elements. Finally, the definition states that the data elements "category" and "author" are to be indexed, and details how these values are to be treated as they are passed to the indexes (they are to be capitalized, for uniform searching purposes, for instance).
After a subfile has been defined, data records may be placed in the subfile according to rules stated in the file definition. At some later time, you might want to modify outdated or inaccurate records, remove extraneous records, or enter new records into this subfile. In any of these cases, you might need to add, update, or remove records. The various sections in Part D describe procedures for managing data within a SPIRES subfile.
This chapter will discuss the subfile modification procedures generally. A specific overview of the remainder of Part D appears at the end of this chapter. [See D.1.5.]
There are several different procedures for doing subfile modification:
- by putting the data for the record in your active file and telling SPIRES to read it; or
- by responding to prompts for the data, typing in lines of data or an entire screen's worth at one time.
There are variations on all these procedures. For example, some may allow the input data to be stored on a tape or in a data set other than the active file. A program called FASTBILD, somewhat similar to SPIBILD, can be used to build large subfiles with thousands of records more efficiently than SPIRES or SPIBILD. When multiple records are updated by SPIBILD, the same data may be used for each record or separate data may be read for each one.
Regardless of the variations, you will follow one of these procedures when you do subfile modification. Naturally, there are reasons to choose one method over another. For example, unless you have the "process" permission discussed above, you can't use either of the SPIBILD (or FASTBILD) methods at all. On the other hand, even if you do have that permission, it may not be advisable to use the SPIBILD process if many other people are using the subfile at the time, since it usually "locks" the subfile for the duration.
Specific advantages and disadvantages to each method are discussed in the documentation for each. The first two methods are discussed in this part of the manual. The SPIBILD and FASTBILD methods, since they are most frequently used by the file owner, are discussed in the SPIRES manual "File Definition".
Before you can do any subfile modification, you must be able to at least select the subfile. If you cannot select it, you cannot update it. But even being able to select a subfile does not necessarily mean you can update records in it. SPIRES is designed to provide data security for both the builders and users of SPIRES subfiles. Only certain accounts, specified by the file owner, are authorized to update the data or subsets of the data in a subfile. If you attempt to update a subfile under an unauthorized account, you will find your commands refused by the system. SPIRES will type out an error message, indicating that you are not allowed to carry out the requested action.
Another kind of data security can be built into a subfile when it is defined: the file owner may decide that certain information in a subfile or the use of certain commands with a subfile should be restricted. For instance, the file owner might not want a data element that gives personal information about someone to be included in a public subfile, either for perusal or for updating, even though the owner is willing to allow access to the rest of the information in the subfile's records. In another example, a file owner might want to restrict the number of users who could remove records from the subfile or to allow updating of only selected records.
Other types of security measures can be implemented by the file owner that will cause an unauthorized account to receive error messages when a requested action cannot be carried out. For example, the file owner can prevent BROWSE GOAL, SET or CLEAR FORMAT, SHOW ELEMENTS, or TRANSFER of a record when that record is being modified by another user.
Security provisions such as these may be defined as part of a subfile so that different accounts have different access privileges and restrictions. (See Chapter B.9, "Defining Subfile Privileges," in "SPIRES File Definition".) Occasionally then, a user may issue a command that violates the security provisions the file owner has implemented. The SPIRES response to such a command is:
-Privileged command
Security is provided by means of "secure-switches". To see which secure-switches are in effect for your account, you may issue the SHOW SSW command. SPIRES will respond with one or more secure-switch numbers. You may then use the EXPLAIN command to see an explanation of that secure-switch. For example:
-> show ssw
3
-> explain secure-switch 3
SECURE-SWITCH 3
FILE DEFINITION, section B.9.3.2
Secure switches 3 through 11 have the following functions:
- 3: prevents addition, updating or removal of goal records by
blocking ADD, UPDATE, ADDUPDATE, REMOVE, MERGE, DEQUEUE and
BATCH commands.
(the display continues)
Once you have received privileges from the data base owner, you may begin the process of updating records. When you receive permission to update, the data base owner should give you certain information about the records and the elements therein -- for instance, what is the goal record key? how many times can you enter a particular element in one record? are there values that should be entered in some type of code? The answers to these questions are found in the file definition, which tells SPIRES the owner's decisions on all such questions.
The owner chooses the elements that together comprise the goal record, then chooses a goal record key from those elements, if possible. Then the owner decides whether elements must have a value for each record and whether any are restricted to only a few, perhaps coded, values and whether each element's value should be restricted to any particular length or number of occurrences.
This section will discuss these ideas specifically, using the following example: You are updating a personnel file. It contains general information about employees: name, address, phone number, social security number, monthly salary, and so forth. In order to update your records correctly, you need to know:
The goal record in a subfile must have a key element. The key element of each and every goal record entered must be a unique value occurring only once. For instance, in your personnel file, the social security number could be the key element. Each employee would have exactly one, unique social security number. SPIRES uses the key element as a "name-tag", to differentiate between different records.
Suppose, however, that for some reason you were not allowed to use the social security number for the key. It is possible that there would not be an element that you were absolutely sure would always be unique. Since SPIRES must have some key element, the file definition can request SPIRES to invent one. If the file definition specifies that a goal record is a "slot key record," then SPIRES will assign a unique numeric value, which is used as the key element, to each record added. [See B.5.1.2.] The procedure is automatic -- you do not need to remember what "slot number" is next when adding records. In fact, you do not include or even mention the slot number in the input data; SPIRES will add it for you.
A goal record must have a key element, which is either a unique element in the input data or a system-generated slot number. The goal record key is thus a "required" element in each record -- that is, an element that must occur at least once. (As noted before, the key element must occur once and only once.) The file definition may stipulate that other elements in the subfile be required to occur as well.
For example, in the personnel file, the employee's name might be a required element. If it were required and a record were added that did not have a value for the name element, that record would be rejected.
Alternatively, elements can be specified as "optional" in the file definition, meaning that they do not have to occur. Suppose that employees can have their paychecks sent directly to their banks; BANK and BANK.ACCT.NUMBER could be optional elements that need not occur in records of employees paid directly.
Neither "required" nor "optional" implies a specific number of occurrences. An optional element may occur any number of times; a required element must occur at least once.
The file definition may specify the number of times an element can occur. For instance, an employee can presumably have only one name, so the file definition may limit the number of occurrences to one. NAME would then be a "singly occurring" element. Since the employee might have more than one phone number but, say, less than ten, there might be a limit of nine phone numbers allowed to be input. The phone number could then be a "multiply occurring" element.
If an occurrence is specified in the file definition, an upper limit is set on the number of entries. If it is not specified for an element, the element may occur any number of times, with two exceptions, already noted: first, a key element must occur once and only once; second, as noted before, a required element must occur at least once.
Some elements in a record may always be the same length -- telephone numbers, state abbreviations, zip codes, for instance, are always ten, two and five characters long respectively. A data base owner can put a length limitation on an element in the file definition to save storage space. SPIRES will always know exactly how much space to save for that element. Like the occurrence factor discussed above, the length limitation only specifies an upper limit on length. If an element value is shorter than the length limit, the value will be accepted. (The file definition can require that the value be exactly a certain length as well, or that there must be a certain number of occurrences of an element in each record, but these are special cases and should be discussed with the data base owner.)
Elements that have a length limit are called "fixed-length," not because the values of different elements have to be the same length (they do not), but because the space each value takes up in storage is always the same. "Fixed-length" does not imply that the element must occur; optional elements may be fixed length.
Employing special processing rules, the data base owner can limit the values allowed for an element. For example, an element called "sex" would only have two possible values: "male" or "female". So it might be worthwhile for the file owner to limit the element's possible values to those two, so that users do not accidentally put invalid data into the subfile. [See B.3.5.5.] Similarly, to save storage space, the file owner could "fix" the length of the element at one character, and store the element as either "M" or "F". Thus, you would have to know to enter "F" instead of "Female" when you were entering data.
The data base owner can develop very complicated substitution codes along these lines. It is the responsibility of the owner to see that privileged users understand any codes designed for the subfile.
Although it is not meant to supplant receiving information from the file owner about adding records to a subfile, the SHOW ELEMENT CHARACTERISTICS command can answer some of these questions:
SHOW ELEMENT CHARACTERISTICS [[FOR] element-name]
If you use the "element-name" option, SPIRES will display the information for only the named element, and if it is a structure, the elements within it.
SPIRES displays a list of the elements in the record in the exact order they would be displayed in the standard SPIRES format. [See B.4.6.] Each element is listed with its aliases. The key element of the record and the key of any structure [See D.1.3.] is noted by the word "key" next to it. If the key of the record is a slot number, the word "slot" appears next to the name of the key instead of "key".
The display also tells you whether an element is Fixed, Required, Optional, or Virtual (element categories determined by the file owner), and whether it is singly or multiply occurring. It tells in what form SPIRES is storing the value, like integer, hex, or string, and what length is reserved for it if it is a fixed-length element. It also tells you the element number, and through the hierarchical display, whether an element is part of a structure.
Here is an example of the display:
-> select restaurant
-> show element characteristics
Subfile RESTAURANT
Sec Occ Len Type St/El Element
--- ---- --- ------ ----- -------
Fix Sing 4 Int 00/00 slot ID
Fix Sing 4 Hex 00/01 DATE-ADDED, DA, DADD, DATEADD
Fix Sing 4 Hex 00/02 DATE-UPDATED, DATEUP, DU, DUP
Req Sing String 00/03 NAME, N, NAM
Req Mult Struc 00/04 LOCATION
Req Sing String 01/00 key . CITY, AR, LOC
Req Sing String 01/01 . STATE
Opt Sing 8 String 01/02 . PHONE, NUM, NUMBER, PH
Opt Sing String 01/03 . ADDRESS, A, ADD, ST, STREET
Opt Mult 5 String 01/04 . ZIP-CODE, ZC, ZIP
Opt Mult String 01/05 . LOC.D
(etc.)
The SHOW ELEMENT CHARACTERISTICS command is a useful reminder of such information as what elements are required or what elements are part of a structure. It will not give you all the information you need to know to be able to add records to a SPIRES subfile. In general, the specific meaning of each piece of information on this display is more useful to the file owner than to users updating the subfile, but it may come in handy.
There are basically two ways to enter records into a SPIRES subfile one at a time:
- 1) you can collect the data in your active file, positioning the data according to the specifications of a format; or
- 2) SPIRES can prompt you for the data, requesting either a line or a full screen's worth of data at a time.
In any case, the input data is always handled by a format. Custom formats can be developed to handle the data most efficiently for a given subfile. Anyone can create a custom format for any subfile to which he or she has access.
Custom formats require development time, however, as well as an understanding of the formats language. Hence SPIRES provides "system formats" that can be used with any subfile. The $PROMPT format can be used to prompt you for input, as its name suggests. The standard SPIRES format, which is the format used if no other format is set, can be used for data entry from the active file. (Sometimes the standard format is considered to be "no format", since it is in effect after a CLEAR FORMAT command is issued.)
But if the data is already in a well-defined arrangement, you may want to define a SPIRES input format that will allow the system to read data that is not in the standard format.
For example, data punched on cards or stored on magnetic tape is often in a fixed or rigid format, perhaps each element beginning in a certain column or field. Input formats can be used to read these records into a SPIRES data base.
After one of the subfile's formats has been set, [See B.4.6.3.] the SHOW FRAMES command can be used to determine if the format set was designed for input. Input formats will have their direction noted as "Input". You should contact the format definer to see how any input format works.
For example, the ENTRY COMMANDS subfile, [See E.2.] has a special format that modifies the appearance of records displayed or transferred (output direction) or records updated or added (input direction). According to the file definition, that format is set automatically when the subfile is selected. The following interaction illustrates several of these points:
-> select entry commands
-> show elements
Record Elements
NAME
COMMAND
-> show formats
Format Names:
PUBLIC (Set)
-> show frames
- Frames of Format PUBLIC
Name Type Direction - Usage
FR1 Data Input - Full
FR2 Data Output - Display, Transfer
The format definer should usually be consulted about the use of a specific input format. To find out more about the SHOW FRAMES command and learn to define special input formats, see the manual "SPIRES Formats".
Earlier in this chapter appeared a list of the methods used in subfile modification. [See D.1.1.] The last two, used in the SPIBILD program, are discussed in the "File Definition" manual. The remainder of Part D will discuss the first three methods listed there.
The first method involved working with one record at a time, to add it, update it, or remove it. Adding and updating records may be done by placing the data in the active file and then telling SPIRES where to find it and what to do with it. [See D.2.]
Alternatively, you can have SPIRES prompt you for the data, either element by element, or a terminal screen's worth of data at a time. The $PROMPT format is generally used in the first case. [See D.3.] Full-screen processing almost always uses a customized interface, so the material in this part of the manual does not discuss that. The file owner should give you instructions on how to update a subfile using a full-screen application.
Regardless of method, you may get error messages when you try to add, update or remove records. A discussion of error messages appears in chapter D.2, but it applies to the entire Part D. [See D.2.8.]
Removing records does not require any data in the active file or any prompting from SPIRES; you simply issue the REMOVE command. [See D.4.1.] You may also change your mind about subfile updates, deciding that you didn't mean to remove a particular record, for example. You may "unqueue" or "dequeue" a "transaction" (an add, update or remove request), if you want. [See D.4.]
Up to this point in this discussion, you needed to know the key of a record if you wanted to update or remove it. But if you need to update records based on some other criteria (e.g., an element value or an indexed value), you can use Global FOR to find the records to update or remove. [See D.5.]
You can also use Global FOR to examine the records you have updated, added, etc. Again, the advantage is that you do not need to know the keys of the records you are interested in. The FOR ADDS class, for instance, gives you access to all the records added since the file was last processed. [See D.7.]
In general, subfile modifications in SPIRES do not affect the indexes. The modifications go into the deferred queue and do not cause the indexes to be updated until the file is processed. A discussion of the immediate and delayed effects of subfile modification appears late in Part D. [See D.6.]
A discussion of "batch" methods of subfile modification in SPIRES, where many records are input into the data base at once, appears near the end of Part D. [See D.8.] Finally, Part D ends with a discussion of transaction group processing, which lets you bracket multiple update requests, so that none of the updates will be sent to the data base unless all of the bracketed transactions succeed. [See D.9.]
Adding and updating records is handled differently from removing records in SPIRES. When you add or update records, you are supplying data to SPIRES, but when you remove records, you are taking it away. So although record removal is a part of subfile modification, it is quite a different (in fact, simpler) process, and is discussed in another chapter. [See D.4.1.]
When adding and updating records in SPIRES, you can supply the data for a record by first placing it in your WYLBUR active file and then telling SPIRES to read it from there. That is the subject for this chapter. The other common method for adding and updating single records is for SPIRES to prompt you for the data, which is the subject of the chapter that follows this one. [See D.3.]
When you use the active file procedure, the basic commands that tell SPIRES to get the data are ADD, UPDATE, ADDUPDATE and MERGE. In addition, the TRANSFER command places a copy of an existing record in your active file so that it can be changed and then put back in the subfile with one of those commands.
SPIRES is a data base system running under Unix with the ability to pass commands to Unix and WYLBUR. To add and update records in a SPIRES subfile using the active file method, you must first place the data in the WYLBUR active file. Using WYLBUR text-editing commands, you can prepare records to be processed by SPIRES and incorporated into a SPIRES subfile.
Generally speaking, you place the data for one record in your active file and then tell SPIRES to read it from there by issuing a command such as ADD.
You may launch WYLBUR to collect the data (e.g., the COLLECT or VIEW commands), or to bring the data into your active file from another data set (the USE command). Remember that both WYLBUR and SPIRES are available to you; you do not have to leave SPIRES to use WYLBUR commands to gather your data.
SPIRES will expect the data to be arranged in a particular fashion so that it will be able to identify each piece of information. Most frequently you will arrange the data in the standard SPIRES format (element-name = value;), whose input rules are given in the next two sections. [See D.2.2, D.2.3.] If you are using another format, you should follow its rules for data arrangement, which will presumably be given to you by the file owner or the person who created the format.
The standard SPIRES format is the format used to handle goal records for both input and output when no other format is set. This section introduces the rules you should follow if you will be using it for data entry. For subfiles with only a few elements (say, fewer than 25), the $PROMPT format may be easier to use for input. [See D.6.]
The standard SPIRES format is a general scheme that relies upon data element names and value delimiters to locate and identify element occurrences. It is free-form (blanks that are not part of a value are ignored) and order-independent, within certain constraints mentioned below. Though the standard format is designed to be as flexible as possible, a few simple rules concerning content and notation must be followed.
- Each value must be preceded by the corresponding data element name. Any legal aliases may be used. The element name must be followed by at least one blank or by an equal sign optionally surrounded by blanks.
NAME = Duncan Hines; COURSE=Basket Weaving 101; INGREDIENT lard;
- Each value entered must be followed by a semicolon. A data element may cover more than one visual line of text, since SPIRES continues to build a value until it reaches a semicolon. SPIRES will insert a blank at the end of each line that does not end with a semicolon. When a value continues across multiple lines, those lines should begin in the first column; they should not be indented unless those extra indent spaces are part of the value. Note that the semicolon is not actually a part of the stored value; it is only a delimiter.
COMMENTS = This is a fairly long comment that wraps around into another line.;
- Any value with a semicolon embedded in it must be enclosed by quotation marks ("). Like
the ending semicolon, the quotation marks are not stored as part of the value.
COMMENTS = "Excellent book; lousy movie.";
- Any quotation marks embedded in the text of a value must be doubled and the entire value
enclosed in quotation marks. Alternatively, you might choose to let apostrophes (') serve as
quotation marks to avoid this problem altogether.
COMMENTS = "He cried out in anguish: ""Oh, ye gods! Who knows what it is to be running? Only he who is running knows.""";
- A value must be included for each required data element in the file definition. If an element is required by the file definition to occur in all records of a file but no value has been provided for that element in an individual record, the problem may be solved by entering the data element name immediately followed by a semicolon. This is termed a "null value".
AUTHOR;
- If a value must begin with one or more blank characters, the entire value should be enclosed in quotation marks.
COST = " 10.00";
- No record may be more than about 120,000 characters long.
Additional rules go into effect when structures are involved. [See D.2.3.]
The following is an example of most of the points outlined above, using a sample record from the RESTAURANT subfile. The line numbers used in the explanation below; they are not part of the data, which begins in column 1 of the active file.
1. NAME Pan's Natural Food Restaurant;
2. ADDRESS;
3. PRICE = reasonable prices suggested, but
4. pay whatever's right;
5. TYPE = natural foods, primarily vegetarian;
6. LOCATION = on El Camino, just north of
7. Arastradero Road;
8. COMMENTS = "great atmosphere; unfortunately,
9. the food doesn't always measure up";
10. service-quality = good; food-quality = good;
The preceding example illustrates some of the points made earlier:
A structure is a data element that contains other data elements. Data elements are grouped into a structure to establish a logical relationship among them. A structure thus contains elements, which may themselves be structures.
There are specific rules that govern the entry of values for structure data elements using the standard SPIRES format, as follows:
- For each occurrence of a structure, the structure's elements must be grouped together. They need not appear in the order specified in the file definition, but all elements in a structure must be entered as a single group.
- Each occurrence of a structure can be considered a "sub-record" within the record. Each element within the structure must follow the same rules given for elements within records. [See D.2.2.]
- To begin a structure, type the name of the structure, followed by a semicolon. Then enter the elements within that occurrence of the structure.
- When you are inputting a structure that has a key data element, you can skip the structure name altogether and begin your input with that key element and its value instead. Either technique can be used to signal the beginning of a structure. (You can see if a structure has a key by issuing the SHOW ELEMENT CHARACTERISTICS command.) [See D.1.1.6.]
- To end an occurrence of a structure, do one of the following:
- start another occurrence of the structure, either with the name of the structure followed by a semicolon or with the key element of the structure (see above);
- specify an element outside of the structure; or
- have no more data after the last element in the structure.
- When you are inputting multiple occurrences of a structure that does not have a key data element, you need to be careful to begin each structure with the structure name (followed immediately by a semicolon, since it has no value). In the majority of cases SPIRES will reject your input unless you do this.
- As the previous points suggest, you are best off beginning input into any structure with either the structure name or the key of the structure, if there is one. As it happens, there are a few cases where you are allowed to begin a structure with some other element besides the name or key, but that technique is not recommended. (For more information on these special cases, see the Technical Note at the end of this section.)
- The value given for the key element of the structure does not have to be unique for each occurrence of the structure, as the goal record key must be for each record in the subfile.
- The first line of each value entered for data elements in a structure can be indented for greater readability. However, if the value wraps into another line, do not indent the value in that line, or extra blanks will be incorporated into value. Whether or not the structure data elements are indented when entered, the standard SPIRES output format will indent the first line of these elements for output.
The following example illustrates some of the points made above concerning structures. This is a record being added to the BLOOD DONORS subfile, where DONATION is a structure containing the elements DATE (the key of the structure) and LOCATION. The line numbers are used in the discussion below; they are not typed as part of the input, which starts in the first column of the active file.
1. NAME = Widow, Mary;
2. ADDRESS = 88 Lehar Lane;
3. CITY = Palo Alto;
4. STATE = CA;
5. ZIPCODE = 94304;
6. CAN.BE.CALLED = No;
7. DONATION;
8. DATE = 01/04/84;
9. LOCATION = Stanford Shopping Center
10. (Bloodmobile);
11. DONATION;
12. DATE = 06/10/84;
13. LOCATION = Stanford Blood Bank;
14. BLOOD.TYPE = AB+;
15. DATE = 12/14/84;
16. LOCATION = Stanford Blood Bank;
Lines 7 through 13 and 15 through 16 contain occurrences of the DONATION structure. Three occurrences are included: lines 7-10, lines 11-13 and lines 15-16. The first two occurrences are signaled by the name of the structure (lines 7 and 11). The last is signaled by the key element DATE.
The end of each occurrence is signaled in a different way. The first is ended when another occurrence begins (line 11). The second ends when an element outside of the structure appears (line 14). The third ends when the data ends.
In addition, notice how the indentation helps delineate the structure but does not introduce extra blanks into the values. When SPIRES displays structures in the standard format, the elements within the structure are indented, except for the key of the structure, which is not indented.
Experienced users of SPIRES who are planning to create formats of their own may need to know more about the rules for beginning input of multiply-occurring structures.
In general, whenever you have just input an occurrence of a given structure and you want to input either another occurrence of the same structure or the first occurrence of a different structure, you need to signal SPIRES of this brand new occurrence by inputting as your first element either the structure name or the structure key (if there is one).
On the other hand, if after inputting your last occurrence of the structure you input some element from outside the structure (for instance the COMMENTS element in the input data above) that outside element will signal SPIRES to close the previous occurrence of the structure. In that case the system will allow you to begin a new occurrence of the structure with an element that is neither the structure name nor the structure key. (SPIRES will most likely rearrange your data into a more conventional order when it processes the record.) You should be aware that if you begin an occurrence of a multiply occurring structure with an element besides the key or structure name, the system may accept your data but alter its format in a way that you didn't anticipate.
The ADD command tells SPIRES that you want to add a record to the currently selected subfile. Depending on the format that is currently set, SPIRES will either read the data for the record from the active file or will prompt you for the data. [See D.1.4.] This section assumes that you are using the active file method; other sections will discuss the prompting method. [See D.1.5, D.3.] [Another method is the WITH DATA option, which says that the data to use for record input is part of the ADD command itself. This option is explained in detail in the manual "SPIRES Technical Notes"; online EXPLAIN WITH DATA.]
The new record is collected in the active file according to the rules for data entry, perhaps in the standard format. [See D.2.1, D.2.2.] The subfile should be selected, if it is not already selected.
The ADD command is then issued. The syntax of the ADD command is:
ADD [USING line-range]
If "USING line-range" is not specified, then the system default is to ADD the entire active file; "USING line-range" may be used to specify a line range when there is other data in the active file than the single record being added. [See D.2.4.1.]
If any error messages from SPIRES appear, they may be explained; the record can then be corrected with WYLBUR commands and resubmitted by issuing the ADD command again.
The following sequence illustrates a simple use of the ADD command.
-> select restaurant
-> collect clear
1. > NAME = Pan's Natural Food Restaurant;
2. > ADDRESS;
3. > PRICES = reasonable prices suggested, but
4. > pay whatever's right;
5. > TYPE = natural foods, primarily vegetarian;
6. > LOCATION = on El Camino, just north of
7. > Arastradero Road;
8. > COMMENTS = "great atmosphere; unfortunately,
9. > the food doesn't always measure up";
10. > *** <-- ATTN/BREAK key is pressed
-> add
-Added record 223
->
When a record is successfully added, the normal SPIRES prompt, "->", will appear. Certain subfiles have SPIRES assign the goal record key value for new records. In these cases, the slot number that is the key assigned to the record will be reported when the record is successfully added, as the example demonstrates. In other words, you could see the newly added record by issuing the command "DISPLAY 223". Remember that the new record will probably not be indexed immediately, so FIND commands may not retrieve it. [See D.6.]
This procedure works well when you want to add records individually to the subfile. If you want to add many records at one time, however, you may collect them end-to-end and submit them as a batch run, for instance, using the INPUT BATCH command. [See D.8.]
The TRANSFER command places a copy of a record in the active file; there it may be modified using WYLBUR text-editing commands. The UPDATE command will then replace that current version of the record in the subfile with this newly modified one from the active file.
The syntax for the TRANSFER command is:
TRANSFER record-key-value [CLEAR|KEEP]
where "record-key-value" is the key value for the desired goal record. The CLEAR option clears the contents of the active file before a record is tranferred. You can specify KEEP to open up a new active file without clearing contents of the current one. (The PICK command lets you restore the previous active file.) If CLEAR or KEEP is not specified and the active file is not empty, you will be prompted "Ok to clear?"
Once the goal record has been transferred into the active file, it can be modified just as any other WYLBUR text. When the text-editing process is complete, the old version of the record in the file may be replaced by the version in the WYLBUR active file with the UPDATE command.
The UPDATE command causes the contents of the active file to replace the goal record previously transferred. When the UPDATE command is issued, the actual goal record residing in the file is unchanged; this command simply places a replacement for the original record in the deferred queue.
The UPDATE command can also be used to replace a record that was never transferred. In this case, the new version of the record may be placed in the active file with WYLBUR COLLECT or USE commands. The UPDATE command must, in this case, specify the key value of the record to be replaced. In any case, the UPDATE operation generally uses the current contents of the active file to replace the old version of the record. [An exception involves the WITH DATA option, which says that the data to use for record input is part of the UPDATE command itself. This option is explained in detail in the manual "SPIRES Technical Notes"; online EXPLAIN WITH DATA.]
If there are any errors causing the update to fail, SPIRES will display error messages. [See D.2.7.]
The two forms of the command are as follows:
UPDATE [USING line-range]
or
UPDATE [USING-line-range] record-key-value
the first case being one in which the record has previously been transferred, and the second being one in which it has not. The USING option was discussed earlier. [See D.2.4.1.]
The transfer-update process might proceed as follows:
-> select restaurant
-> transfer 43 clear
-> list
1. ID = 43;
2. DATE-ADDED = APRIL 21, 1976;
3. DATE-UPDATED = JUNE 3, 1976;
4. NAME = Woodside Book and Bean;
5. CITY = Woodside;
6. STATE = California;
7. PHONE = 851-8499;
8. ADDRESS = 2975 Woodside Road;
9. RECOMMENDER = John Sack and Betsy Yount;
10. COMMENTS = This is primarily a book store, but has exotic
11. teas and aromatic coffees, and pastries and specialty
12. candies; iced drinks are especially nice in the summer.
13. The owner is an interesting and interested fellow.
14. There is also a nice little winery next door --
15. Shirrells Cellars.;
16. CUISINE = Coffeehouse;
17. FOOD-QUALITY = Excellent;
18. SERVICE-QUALITY = Excellent;
19. CREDIT = Check;
20. HOURS = 10-6 Tue-Sat;
21. ENTERTAINMENT = The Owner;
-> modify 20
20. HOURS = 10-6 Tue-Sat;
MODS > i, 12-6 Sun
20. HOURS = 10-6 Tue-Sat, 12-6 Sun;
MODS > (carriage return)
-> update
-> display 43
ID = 43;
DATE-ADDED = APRIL 21, 1976;
DATE-UPDATED = FEBRUARY 6, 1985;
NAME = Woodside Book and Bean;
CITY = Woodside;
STATE = California;
PHONE = 851-8499;
ADDRESS = 2975 Woodside Road;
RECOMMENDER = John Sack and Betsy Yount;
COMMENTS = This is primarily a book store, but has exotic
teas and aromatic coffees, and pastries and specialty
candies; iced drinks are especially nice in the summer.
The owner is an interesting and interested fellow.
There is also a nice little winery next door --
Shirrells Cellars.;
CUISINE = Coffeehouse;
FOOD-QUALITY = Excellent;
SERVICE-QUALITY = Excellent;
CREDIT = Check;
HOURS = 10-6 Tue-Sat, 12-6 Sun;
ENTERTAINMENT = The Owner;
Notice that when the updated record is displayed, the new version is shown. Not only did the element HOURS change, but the element DATE-UPDATED changed as well. Many subfiles have elements whose values are automatically supplied and/or changed when a record is added or updated; elements with names like DATE-ADDED, TIME.UPDATED, etc. usually fall in this category. When updating a record, you do not need to do anything at all about including or changing these elements and their values; SPIRES will take care of them for you.
The "UPDATE record-key-value" command would be used similarly to the example above, but since you would not have specified the record-key-value in a TRANSFER command, you would have to specify a record-key-value:
-> update 43
Occasionally you may ADD a record and get an error message telling you that the record already exists (i.e., there is a record with the same key value as the one you are trying to add already in the subfile). On the other hand, if you are going to UPDATE a record, you may get an error message telling you that the record does not already exist in the subfile. [See D.2.7.]
If you have a record in your active file and you do not know (or care) whether it is a record to be added or to be updated but you know that you want it to go into the subfile as is, you can issue the ADDUPDATE command. The ADDUPDATE command will take the contents of your active file and add the record if it does not already exist or update the record if it does.
You do not include the "key" value in the ADDUPDATE command, as you do in the UPDATE command. Its syntax is simply
ADDUPDATE [USING line-range]
The USING option directs SPIRES to a specific portion of your active file. [See D.2.4.1.]
SPIRES will look for the key of the record in the input data. When it finds the key, it will check to see whether a record with that key exists. If the record does not exist, the data will be treated as a record to be added. If the record does exist, the data will be used to update that record. If no key is supplied in the data, an error will occur, unless the key of the record is a slot key, in which case the record will be treated as a record to be added, and a slot key value will be assigned.
You may also use ADDUPDATE with the WITH DATA option, which says that the data to use for record input is part of the ADDUPDATE command itself. This option is explained in detail in the manual "SPIRES Technical Notes"; online EXPLAIN WITH DATA.
In many cases, only one or a few of the elements in a record are to be modified, perhaps to change part of an address, perhaps to correct a data entry error. In cases where only a small part of the record is to be updated, it is somewhat inefficient to TRANSFER and UPDATE the entire record, especially when large records are involved. The MERGE command will take the contents of the active file and use them to replace, delete or add appropriate elements in the record whose key is given in the MERGE command. Thus, the active file is "merged" into the existing record. [See D.6.1.4 for another method using $PROMPT.] [And yet another method is the WITH DATA option, which says that the data to use for record input is part of the MERGE command itself. This option is explained in detail in the manual "SPIRES Technical Notes"; online EXPLAIN WITH DATA.]
The MERGE and UPDATE commands differ in that the UPDATE command replaces the entire copy of the record with the input data. For example, if the input data omits elements that were in the older version of the record, those elements will be lost. On the other hand, MERGE will affect only the elements named in the input data; the other elements in the record will remain as they were (except for any elements automatically taken care of by SPIRES, such as DATE.UPDATED).
The syntax of the command is:
MERGE [USING line-range] [record-key-value]
If a line range is not specified, the entire contents of the active file will be merged into the record. [See D.2.4.1 for a discussion of the USING option.] If "record-key-value" is not specified, the system will prompt you for it.
If all the elements in the goal record are singly occurring, then an element value in the active file simply replaces the previous value of the element in the goal record or adds an occurrence if none existed.
However, if an element in the goal record is multiply occurring, then the first occurrence of that element in the active file replaces the first occurrence in the old goal record; the second occurrence replaces the second occurrence in the old goal record, and so on. If there were five occurrences of an element in the old goal record and only three occurrences of that element in the active file, the last two occurrences in the old goal record would not be altered. If there were only three occurrences in the old goal record and five occurrences specified in the active file, then all old occurrences would be replaced, and two new ones would be added, providing the file definition allowed that many occurrences.
Suppose a user, account D5.M07, wanted to replace the first two commands in the account's record in the ENTRY COMMANDS subfile. This might be done as follows (the extra DISPLAY commands are introduced for clarity):
-> select entry commands
-> clear format
-> display d5.m07
NAME = D5.M07;
COMMAND = SELECT FRESHMAN.ENGLISH;
COMMAND = SET XEQ;
COMMAND = SELECT CATALOG;
-> collect clear
1. > command = show date;
2. > command = show count;
-> merge d5.m07
-> display d5.m07
NAME = D5.M07;
COMMAND = SHOW DATE;
COMMAND = SHOW COUNT;
COMMAND = SELECT CATALOG;
You may want to specify specific occurrences of multiply occurring elements to be merged. In this case, the system is told explicitly which occurrence of the element is to be merged into the record. The methods are discussed in detail below.
Consider the problem of replacing the third occurrence of the COMMAND element in the following ENTRY COMMANDS record:
NAME = D5.M07; COMMAND = SELECT FRESHMAN.ENGLISH; COMMAND = SET XEQ; COMMAND = SELECT CATALOG; COMMAND = SHOW SUBFILE SIZE;
The third occurrence can be replaced without disturbing the other occurrences by specifying in parentheses immediately after the element name, COMMAND, the occurrence number to be merged. For example:
-> collect clear
1. > command(3) = select marc;
2. > *** (ATTN pressed)
-> merge d5.m07
-> display d5.m07
NAME = D5.M07;
COMMAND = SELECT FRESHMAN.ENGLISH;
COMMAND = SET XEQ;
COMMAND = SELECT MARC;
COMMAND = SHOW SUBFILE SIZE;
->
To add, rather than replace, occurrences of multiply occurring elements, you need only specify a high occurrence number, beyond any existing occurrences of the element. [The highest occurrence number you can specify is 16,382 (or 8,190 for structure elements).] For example:
-> collect clear
1. > command(99) = show indexes;
2. > *** (ATTN depressed)
-> merge d5.m07
-> display d5.m07
NAME = D5.M07;
COMMAND = SELECT FRESHMAN.ENGLISH;
COMMAND = SET XEQ;
COMMAND = SELECT MARC;
COMMAND = SHOW SUBFILE SIZE;
COMMAND = SHOW INDEXES;
->
To remove, rather than replace or add, occurrences of multiply occurring elements, you prefix the occurrence number with a negative ("-") sign. You do not include a value, but instead follow the "parenthesized" occurrence number with a semicolon. For example:
-> collect clear
1. > command(-2);
2. > command(-4);
-> merge d5.m07
-> display d5.m07
NAME = D5.M07;
COMMAND = SELECT FRESHMAN.ENGLISH;
COMMAND = SELECT MARC;
COMMAND = SHOW INDEXES;
When occurrences are removed, other occurrences fill in their place. That is, in the above example, occurrences 2 and 4 are removed. Occurrences 3 and 5 "move up" to become occurrences 2 and 3, respectively.
You can remove all occurrences of an element at once by using the occurrence number "-0", as in
-> collect clear
1. > command(-0);
2. > ***
-> merge d5.m07
-> display d5.m07
NAME = D5.M07;
->
If your active file contains some record elements, and you want the data to be either merged into an existing record or (if no record exists with that key) added as a new record, you can use the ADDMERGE command. The ADDMERGE command will take the contents of your active file and add the record if it does not already exist, or merge data into the record if it does.
The syntax of the command is simply
ADDMERGE [USING line-range]
The USING option directs SPIRES to a specific part of your active file. [See D.2.4.1.]
SPIRES will look for the key of the record in the input data. When it finds the key, it checks to see whether a record with that key exists. If the record does not exist, the data will be treated as a record to be added. If the record does exist, the data will be merged into the existing record, as if a MERGE command had been issued. If no key is supplied in the data, an error will occur, unless the key of the record is a slot key. In that case the record will be treated as a record to be added, and a slot key value will be assigned.
ADDMERGE may also be used with the WITH DATA option, which says that the data to use for record input is part of the ADDUPDATE command itself. This option is explained in detail in the manual "SPIRES Technical Notes"; online EXPLAIN WITH DATA.
When for some reason the update operation you request will not work, a message will be displayed at the terminal. The message not only signifies whether or not the operation has been performed, it gives the reason why (in code form), and if possible, the line number(s) of the error(s). These error codes (usually numerics) can be explained online via the EXPLAIN command. [See A.3.1.2.] The explanation describes the particular situation causing the operation to fail.
The following example shows the manner in which error messages are reported to you by the system, and the way in which you can request explanations of the errors.
-> add -Element=PRICE-AVERAGE: -Serious data error, code=E22 -Error at or before line 26.01 -Update terminated, code=S261 -> explain s261 S261: A serious error was detected by a processing rule. You have received an error message of the form: -Element=elem-name: -Serious data error, code Exxx where Exxx is the error message number, and elem-name is the name of the element causing the error. You may EXPLAIN the error message number by a command of the form: EXPLAIN Exxx. Other errors may cause Error Code S261. In each case, the error number will be explicitly given in an earlier message, or the previous message will give the line number in the active file where the error was detected. -> explain e22 E22: The value for the data element contains too many characters.
Users who do a large amount of batch processing may find it helpful to make a list of all error code explanations and system messages. To find out how to produce such a listing, type: SHOW SUBFILE DESCRIPTION SYSTEM MESSAGES. This listing can be used for consultation offline, thus saving on connect time and terminal I/O charges.
You can control the display of error messages in SPIRES with the SET MESSAGES command. [See E.4.]
In rare instances, you may get an unexpected error code S2 while trying to add, update or merge a record. If the record you are trying to add, update or merge is very large (several hundred lines, perhaps), it is possible that the system is not allocating its internal record-building space in the optimum way for your record. You can ask SPIRES to allocate more space by issuing the SET SUPERMAX command.
The commands take the form:
SET SUPERMAX nK
where "n" is an integer value indicating the amount of space, in 1024-character increments, to be allowed for the ADD, UPDATE, ADDUPDATE, MERGE and REFERENCE commands. ("K" is the symbol for kilobytes, i.e., 1024 bytes.) [See "SPIRES Technical Notes" for information on the REFERENCE command.] The default when you enter SPIRES is 32K.
SPIRES is actually allocating two areas of this size in memory. For more information, see the Protocols manual or EXPLAIN $SUPERMAX.
SPIRES provides a special format that will prompt you for the element values when you add or update records in a subfile. This general system format, called $PROMPT, may be used with any subfile. The $PROMPT format automatically adjusts its processing characteristics to the elements and structure of the particular subfile with which it is used.
The $PROMPT format is enabled when you issue the SET FORMAT $PROMPT command after you have selected a subfile. Subsequent record addition or modification commands (ADD, MERGE and, if you wish, UPDATE) prompt you for new and/or changed values. In addition, record display commands (DISPLAY and TYPE) will provide a simple, formatted list of elements and values, without the "=" and ";" of the default SPIRES format.
This chapter describes the use of the $PROMPT format for record addition and modification. The SET FORMAT $PROMPT command itself allows options that specify which elements are prompted and in what manner prompting is done. [See D.3.2, D.3.3.] While the $PROMPT format is prompting for element values, "subcommands" can be issued to add, modify, or delete element values, to direct the format to prompt for different elements, or to change other $PROMPT format characteristics. [See D.3.4.]
The file owner may add some information to the file definition that alters the way you are prompted for element values when the $PROMPT format is set. [See D.3.5.] The SHOW ELEMENT INFORMATION command can help you determine whether the subfile has been customized in this way.
The SET FORMAT $PROMPT command sets the format that prompts you with element names and allows you to enter element values in response to the prompts. Once set, the $PROMPT format is invoked (that is, used) by subsequent ADD, MERGE, TYPE, and DISPLAY commands (as well as the UPDATE command, if you wish); however, the use of the TRANSFER command does not change when the $PROMPT format is set. To return to the default SPIRES format, issue the CLEAR FORMAT command. [See B.4.6.4.]
The general syntax of the SET FORMAT $PROMPT command is:
SET FORMAT $PROMPT [(processing options)] [element options]
"Processing options" are used to change particular characteristics of the format, such as what types of error messages should be displayed, whether the terminal bell should be rung whenever a prompt is presented to you, etc. They are explained in full later in this chapter. [See D.3.3.] "Element options" specify which elements should be prompted; by default, if no element options are included in the command, SPIRES will prompt for all the elements in the goal record. [See D.3.2.] Note that processing options, if specified, must precede any element options specified on the SET FORMAT $PROMPT command and must be enclosed in parentheses.
Here is an example using the $PROMPT format to add and display a record:
-> select phone book -> show elements Subfile PHONE BOOK SLOT NAME PHONE -> set format $prompt -> add : NAME Brent Cavanaugh : PHONE 212-443-7874 for "business" calls -Added record: 411 -> display 411 SLOT 411 NAME Brent Cavanaugh PHONE 212-334-7874 for "business" calls -> clear format -> display 411 SLOT = 411; NAME = Brent Cavanaugh; PHONE = "212-334-7874 for ""business"" calls"; ->
SPIRES prompted the user for values for the two elements NAME and PHONE. (Note that it will not prompt for the slot key, since SPIRES provides that value on added records.) The user typed a value for the requested element, pressed the return key, and then typed a value for the next one. When SPIRES prompted for the last element and the user provided a value, SPIRES added the record to the subfile and returned the user to command mode.
The WYLBUR active file is not affected by the use of the $PROMPT format. Note however that if the system crashes while you are adding or updating a record using the $PROMPT format, the work done since issuing the last command is lost.
Occasionally while you are being prompted for elements, you may want to stop momentarily to do something else in WYLBUR, such as show your WYLBUR mail or send a message to another user in response to a message you have received. (This situation is especially common when you are working with large records.) Pressing ATTN/BREAK or issuing the subcommand "/X" [See D.3.4.4.] will end processing of the current record but SPIRES will throw away any data you have entered for that record since you issued the previous command. Alternatively, you may temporarily leave $PROMPT's and SPIRES control, but hold your current position within the record being processed, by responding to an element prompt with a "/w subcommand".
-> set format $prompt -> add : NAME Conrad Hilton : PHONE /w ls -1 SPIRESH* SPIRESH SPIRESH.MAP : PHONE 800-325-3535 -Added record: 412 ->
The "/w subcommand" is a shorthand for "/WYLBUR subcommand". You may pass commands to WYLBUR or Unix with this response. [See D.3.4.4.]
The next sections will discuss some of the following topics:
- How additional commands can be used to set format options and see what options are currently in effect [See D.3.1.1, D.3.1.2.]
- How to add, update and merge records using the $PROMPT format [See D.3.1.3, D.3.1.4.]
- How $PROMPT handles errors [See D.3.1.5.]
The SET FORMAT * command resets the current format. [See B.4.6.3.] When the command is issued when the $PROMPT format is in effect, you can replace the element list (if any) that you are currently using, or you can change the processing options that are set. For example,
-> set format $prompt
<-- Various commands using the format are issued
-> set format * - date.added
Here the DATE.ADDED element is removed from the list of elements to be prompted for. [See D.3.2.3.]
It is more efficient to issue the SET FORMAT * command than to issue another SET FORMAT $PROMPT command; SPIRES must do some extra work when you completely start over again. Note too that the SET FORMAT * command will not reset any processing options you may have already set unless you specify in the SET FORMAT * command that they be reset.
For the $PROMPT format, the SHOW FORMAT INFORMATION command shows information about record structure, element names, and element occurrences. It can be very useful when you want to know what elements $PROMPT will prompt you for, with what string they will be prompted, and what processing options are currently in effect. [See D.3.3.]
For example:
-> select restaurant -> set format $prompt -> show format information Information for format $PROMPT New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME (Prompt: Restaurant Name) required mult LOCATION (Prompt: Location) required 1 . CITY (Prompt: City) required 1 . STATE (Prompt: State) optional 1 . PHONE (Prompt: Phone) optional 1 . ADDRESS (Prompt: Address) optional mult . ZIP-CODE (Prompt: Zip) optional mult . LOC.D optional mult RECOMMENDER (Prompt: Recommender) optional 1 COMMENTS (Prompt: Comments) optional mult CUISINE (Prompt: Cuisine) optional 1 PRICE-RANGE optional 1 PRICE-AVERAGE (Prompt: Average Price of Meal) optional 1 FOOD-QUALITY (Prompt: Food Quality) optional 1 SERVICE-QUALITY (Prompt: Service Quality) optional 1 CREDIT (Prompt: Payment Accepted) optional 1 RESERVATIONS (Prompt: Reservations) optional 1 HOURS (Prompt: Hours) optional 1 ENTERTAINMENT (Prompt: Entertainment) optional mult BAR
The first lines of the response to the SHOW FORMAT INFORMATION command show the processing options in effect. Subsequent lines show which elements will be prompted for, with what name they will be prompted, and in what order.
Element names are preceded by information on whether they will be "supplied" by the system, "required" to be input or "optional", as well as by information on the number of occurrences (e.g., "mult" for "multiple occurences") that will be prompted by the system. (Another possible value under the "Input" column is "default", which would mean that a value will be supplied by default if you don't enter one yourself.) The parenthetical information to the right of some of the element names indicates the default wording of the prompt for that element. So, for instance, you would ordinarily not be prompted for "PRICE-AVERAGE" but for "Average Price of Meal".
If element names are indented, this means they are in a structure; in the above example, CITY, STATE, etc. are in a structure called LOCATION.
If the goal record has a slot key, [See D.1.3.1.] the slot element will be displayed by the SHOW FORMAT INFORMATION command (as "ID" above is shown), but the slot element will not be prompted by $PROMPT since the value is always assigned by SPIRES.
The SHOW FORMAT INFORMATION command can be preceded by the IN ACTIVE prefix to place the output from the command in the active file. [See A.2.9.1.]
There is also a SHOW FORMAT INPUT command, which works similarly in $PROMPT to the way that it works in $REPORT. [See C.2.3.] That is, it displays the set of commands that you have issued so far in setting up your format.
For example:
-> select restaurant -> set format $prompt -> set for * (nosort) city cuisine name -> sho format input SET FORMAT $PROMPT SET FORMAT * (nosort) city cuisine name
When the $PROMPT format is in effect (i.e., any time after the command SET FORMAT $PROMPT has been issued), the commands ADD and MERGE no longer look for data in your active file but instead begin prompting you for element values. The same holds true for the UPDATE command if you change the control option from the default NOUPDATE to UPDATE. [See D.3.1.4.]
When you issue the ADD command, SPIRES prompts you for the first element on the list of elements shown by the SHOW FORMAT INFORMATION command [See D.3.1.2.] unless that element is the slot key of the goal record, in which case SPIRES will go directly to the next element, providing the key later itself.
-> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required mult LOCATION required 1 . ADDRESS (Prompt: Street Address) required 1 . CITY optional mult . PHONE -> add : NAME
Here SPIRES begins handling the ADD command by prompting for the NAME element. You respond by typing the element value desired. In this case, the element value may be up to about 150 characters long; for longer values, you should indicate that the value will be longer by ending the first portion of the value with two slashes ("//"). [See D.3.4.1.] However, if the value entered is more than 100 characters long, the $PROMPT format will automatically prompt for "more-->" of the input value. If there is no more to be included for that element value, press the return key in response to the "more-->" prompt. [There is no absolute length for an element value in $PROMPT. The allowed length is based on the length of the element's prompt. The longer (and the more indented) an element's prompt is, the shorter the allowed value. In general, you should stop at about 110 characters, so that SPIRES will prompt you for more, if you are working with long element values.]
SPIRES will process the input value through any processing rules chosen for the element by the file definer; if the value causes an error, it will be reported by SPIRES and the element will normally be reprompted.
When an element value has been entered and then processed by SPIRES, either the next element or the next occurrence of the same element if it is multiply-occurring (see below) will be prompted. When the entire record has been prompted and the final element value entered, SPIRES adds the record to the deferred queue of the subfile. (There may be some "record closeout" processing done before the record goes to the deferred queue, such as assigning a key value if the goal record has a slot key.)
The $PROMPT format requires that you provide values for elements marked as "required" by the SHOW FORMAT INFORMATION command. If you do not provide a value, you will get an error message and be reprompted for that element. [See D.3.4.1 for information on the subcommands "/NULL" and "//", which help you avoid this when it becomes a problem.]
You do not have to provide values for optional elements; to skip an optional element, thus not giving it a value, press return when you are prompted for it. In the example below, NAME is a required element and PHONE is optional:
-> add : NAME <--press return Value required - enter /N or // for null value : NAME Reginald van Gleason : PHONE <-- press return -Added record: 984 ->
If you have entered all the data you want for a record and all the remaining elements to be prompted are optional, you may press return for each one, or issue the subcommand "/END" to end prompting. [See D.3.4.4.]
When prompting for an element that may have multiple occurrences, the $PROMPT format will, by default, prompt repeatedly with the element name, until you indicate that no more values for this element are to be prompted. [See D.3.2.1.2 to see how to change the default.] This is done by pressing only carriage return in response to the element name prompt. Elements that are multiply-occurring are suffixed by an occurrence count in parentheses when they are prompted. For example:
-> select account list -> set format $prompt -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied SLOT required 1 NAME required mult ACCOUNT required 1 PHONE -> add : NAME Lee Carmichael Williams : ACCOUNT(1) Beat Calendars, Inc. : ACCOUNT(2) Stanford Supper Bowls Company : ACCOUNT(3) <-- carriage return is pressed : PHONE 497-1511 -Added record: 45 ->
Elements in structures are prompted for exactly as are elements at the record level. For example, you press return to skip optional elements in a structure. However, by default, if you press only return in response to the first element prompted in an occurrence of a structure, then no other elements in that occurrence of the structure are prompted, and, if the structure is multiply-occurring, no additional occurrences of the structure are prompted. [See D.3.3 to see how to override the default.] For example:
-> select rolodex -> set format $prompt -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied SLOT required 1 NAME required mult PHONE required 1 . NUMBER optional 1 . TYPE optional 1 . HOURS optional 1 AFFILIATION optional 1 COMMENTS -> add : NAME Emily DuMonde Structure: PHONE : NUMBER 328-1232 : TYPE business : HOURS <-- carriage return is pressed : NUMBER <-- carriage return is pressed : AFFILIATION friend of the family : COMMENTS <-- carriage return is pressed -Added record: 324 ->
Note that the structure's name is displayed only once, when the structure is first entered for prompting; subsequent structure occurrences are separated from each other by a blank line.
Many subfiles allow you to enter a question mark in response to an element prompt; SPIRES then responds with an "element description" created by the file definer. Then you are reprompted for the element. The file definer should be able to tell you whether or not such descriptions are available. [See D.3.5.]
For example,
-> set format $prompt name interests -> add : NAME Chuck Tyler : INTERESTS(1) ? <-- user types question mark This element is multiply-occurring and contains information about the personal interests and hobbies of the person. It is indexed in the INTEREST index so that you can search for people with common interests. : INTERESTS(1)
In most cases, the MERGE command is used when you want to update records using the $PROMPT format. When processing a MERGE request, the $PROMPT format first displays portions of the record before prompting you for new values to replace existing values, or new elements and occurrences to be added to existing ones.
Each singly-occurring element is displayed, and then the $PROMPT format prompts for a replacement value. Each multiply-occurring element has all its occurrences displayed before replacement and additional values are prompted. To accept any value without modification as displayed, simply press the carriage return.
For example:
-> select mail list -> set format $prompt -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required mult ADDRESS required 1 ZIP required mult NOTE -> merge 27 *** 27 *** ID...........27 NAME.........Mary Anderson : NAME <-- return is pressed to accept the value ADDRESS(1)...1550 MAMA DRIVE ADDRESS(2)...BIG SUR, CA. : ADDRESS(1) 1550 Alma Drive : ADDRESS(2) Fremont, Ca. : ADDRESS(3) <-- return is pressed to skip new value ZIP..........95444 : ZIP <-- return pressed to accept value NOTE(1)......THIS WOMAN IS THE SALES MANAGER AT ANDERSON'S. : NOTE(1) <-- carriage return pressed to accept value -> display 27 ID 27 NAME MARY ANDERSON ADDRESS(1) 1550 Alma Drive ADDRESS(2) Fremont, Ca. ZIP 95444 NOTE(1) THIS WOMAN IS THE SALES MANAGER AT ANDERSON'S.
If you have updated all the elements that you want to change, you may use the subcommand "/E" or "/END" to skip the rest of the elements in the record. [See D.3.4.4.] Alternatively, you can issue a SET FORMAT $PROMPT command or a SET FORMAT * command to specify that SPIRES should prompt for only a few elements as specified in the command. [See D.3.2.] If you want only to add new occurrences, use the APPENDONLY option for a single element [See D.3.2.1.3.] or globally for all elements being prompted. [See D.3.3.]
By default, the $PROMPT format is not used in updating records with the UPDATE command. Instead, the UPDATE command would take data from the active file, assuming it was in the standard SPIRES format ("elementname = value;"). You can place the record in the standard format into your active file by issuing the TRANSFER command under the SET FORMAT $PROMPT command.
By changing a control option (NOUPDATE, the default, to UPDATE) you can use the UPDATE command with the $PROMPT format, though that is not done very often. [See D.3.3.] Unlike MERGE processing (but like ADD processing) under SET FORMAT $PROMPT, you must input the entire record being updated, not just the elements whose values you want to change. The record being updated is not even displayed as you update it, since your input will completely replace it. Most users prefer to change only portions of a record rather than input the entire record again when they wish to update one, so the MERGE command is more commonly used.
Error messages are issued by the $PROMPT format for three different reasons:
In nearly all cases of errors an error message will be issued, and you will be reprompted for the value of the element that caused the error. Thus, you are given a chance to re-input values that were in error.
In a few cases, the nature of the error is such that it is not detected until all elements have been input; in this case you must re-input the entire record. The most common cause for this problem is entering too many occurrences of a multiply occurring element: the $PROMPT format knows that an element may occur more than once but unless the file-owner has added the piece of "element information" called INPUT-OCC to the file definition, $PROMPT usually has no way of knowing how many times the element is supposed to occur. It simply prompts you for as many occurrences of the element as you want to try to input. When SPIRES tries to store the record after gathering all the input, it discovers that there were too many occurrences of the element and rejects the record. One way to circumvent this problem is discussed in the next section: setting the number of occurrences prompted for an element. Another way is to add the appropriate "elem-info". [See D.3.5 for more information on element information packets.]
You may decide after trying to add a record and receiving error messages that you want to cancel the operation altogether. If you press ATTN/BREAK, the $PROMPT format will ask you if you want to cancel the request:
: NAME ***<-- ATTN/BREAK is pressed : Do you wish to cancel this request? (YES/NO/HELP) yes -Update terminated, code=S2 ->
A more direct way to cancel a $PROMPT operation is with the "/X" or "/CANCEL" subcommand. [See D.3.4.4.] Note that the HELP response to the above question will give you a list of useful subcommands if you have forgotten them.
Just as with WYLBUR, if you detect an error in input of a value before you press the carriage return, you can press the ATTN/BREAK key to be reprompted for the element; or you may backspace to the error and retype, as you would with any other data entry.
For example:
-> select phone book -> set format $prompt -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required 1 PHONE -> add : NAME Julsie Olso<ATTN> <-- ATTN key pressed to reprompt : NAME Julie Olson : PHONE <-- return is pressed, attempting to skip the element -Value required - enter /N, or // for null value : PHONE none -Only numbers in the form "NNN-NNNN" are allowed. : PHONE /Z <-- "Z" entered instead of "X" Invalid subcommand: /Z : PHONE /X <-- "/X" entered to abort the ADD command request -Update terminated, code=S2
Note that once an element value has been input and the $PROMPT format has moved to prompting for another element occurrence, you cannot correct an error in the element's value except by:
- typing "/X" or "/CANCEL" to abort the request; this discards the data you have just typed in for this record request; or,
- completing the record processing request, and then issuing a MERGE command to correct the record's erroneous element value(s).
Like the SET ELEMENTS command [See B.4.3.2.] and the SET FORMAT $REPORT command [See C.1.1.] the SET FORMAT $PROMPT command can be followed by a list of elements. The element list specifies which elements are to be prompted and displayed when the $PROMPT format is used; if no element list is specified, then the default is to prompt and display all elements (except virtual elements). If an element in the list is the name of a structure, then all the elements in that structure are processed. If your file contains more than 100 elements you must specify the elements you want to be prompted (100 or fewer) to use $PROMPT. (But see below for the $LPROMPT format.)
The basic syntax of the SET FORMAT $PROMPT command with element options is:
SET FORMAT $PROMPT elem (elem-options) [elem (elem-options) ...]
where "elem" is an element from the goal record of the selected subfile. The "elem-options" control how the element is prompted, how many times it is prompted, and if only new occurrences are to be prompted during a merge. [See D.3.2.1.]
Here is an example demonstrating a common use of the element list:
-> show elements Subfile ADDRESSES ID NAME ADDRESS CITY STATE ZIP PHONE -> set format $prompt name phone -> show format information Information for format $PROMPT New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME optional mult PHONE -> merge 14 *** 14 *** NAME.........Phoebe Tyler : NAME <-- carriage return pressed to accept value PHONE(1).....555-4938 : PHONE(1) 555-4948 : PHONE(2) <-- carriage return pressed ->
Only the elements specified in the SET FORMAT $PROMPT command were prompted. The element list is particularly useful for MERGE and DISPLAY processing, where you only want to work with certain elements. If you use it when you are adding records, be sure that your element list includes all the required elements; otherwise your input records will be rejected.
$PROMPT can only prompt you for a maximum of 100 separate elements. If your subfile has more than 100 elements you can still use $PROMPT but you must specify in your SET FORMAT command the particular elements you would like to have prompted and the total you specify must be less than 100. If a structure is named in the element list, all the elements within the structure will count as part of the 100 element total.
If you need to have more than 100 elements prompted, you should use the $LPROMPT format. This format works the same way as $PROMPT, but has a limit of 450 elements. It is recommended that you only use $LPROMPT when you need to input more than 100 elements, since it is slightly less efficient than $PROMPT and requires more memory to use.
Elements in the list can be separated from each other by a comma and/or blanks. For example:
-> set format $prompt name address -> set format $prompt name,address -> set format $prompt name, address
As with the SET ELEMENTS command and other commands that specify elements, element paths can be specified to indicate a unique element when different elements have the same name:
-> set format $prompt name question@text answer@text
The name specified in the element list may be the element's name itself, or any of its aliases. However, the order in which elements are prompted is determined by the order in which they appear in the file definition, not the order of the element list, unless you use the NOSORT option. [See D.3.3.]
The SHOW FORMAT INFORMATION command indicates the elements to be prompted, gives the name with which they will be prompted, the order of prompting, and the maximum number of (new) occurrences that will be prompted, as shown in the example in the previous section.
Each element may be followed by element options. There are currently four options available; they are:
- An occurrence option to specify how many times an element is to be prompted.
- The PROMPT option to specify how the element is to be prompted.
- The APPENDONLY option to specify that only new occurrences are to be prompted for during a merge process.
- The STRUCTURE/NOSTRUCTURE option to specify that a structure should (or should not) be prompted as a single element.
These options are placed in parentheses following the element name, are separated by commas, and may appear in any order. They are described in the following sections.
By default, you are prompted for an element either with the name given in the SET FORMAT $PROMPT command or with the heading that the file owner has included in what is called the "element information packet". [See D.3.5.] (These headings are the text in parentheses at the right of the element names in the SHOW FORMAT INFORMATION example in Section D.3.1.2. By default a heading, if it exists, will override an element name and appear as the prompt.) Sometimes you might want to be prompted with something else. You can specify a different prompt up to 36 characters long using the PROMPT element option. For example,
-> set format $prompt name (prompt='Enter name') phone -> add Enter name Mary Beal PHONE 234-3637
Note that if the prompt string contains blanks or special characters it must be enclosed in apostrophes or quotation marks.
You can limit the number of times an element will be prompted in $PROMPT by following the element name in the element option list with the option "OCC=n" (or simply "n") where "n" represents the number of occurrences you wish to have prompted. For example,
-> set format $prompt name address(occ=3)
The ADDRESS element will only be prompted three times.
In MERGE processing, all existing occurrences are always prompted, regardless of the "prompted-occurrence limit"; but if the number of existing occurrences in the record is less than the prompted-occurrence limit, then additional occurrences will be prompted until the limit is reached. (Note: this option does not affect the number of occurrences of ADDRESS that will be displayed; all will be displayed.)
When you are updating records using the MERGE command, the $PROMPT format will display each current element value and prompt you for any changes. It will also prompt you for additional occurrences of elements that may occur multiple times. If you only want to be prompted for the additional occurrences, use the APPENDONLY element option, as follows:
-> set format $prompt name interests (appendonly) -> merge 30 *** 30 *** SLOT............30 NAME............Andy Mabel : NAME <-- carriage return is pressed to accept value : INTERESTS(5) rowing : INTERESTS(6) hiking : INTERESTS(7) <-- carriage return pressed to finish input ->
The INTERESTS element already had four occurrences. The APPENDONLY option caused $PROMPT to begin prompting at occurrence 5.
If you combine the number option described in the previous section with the APPENDONLY option, you will be prompted for additional occurrences up to the specified limit. For example,
-> set format $prompt name interests (5,appendonly)
will prompt you for additional occurrences of the INTERESTS element, but only until the record contains a total of 5 occurrences. If a record already has five or more occurrences of this element, you will not be prompted for any more. If the file definition specifies a maximum number of times that the element may occur, $PROMPT will not prompt for any more than that limit.
The APPENDONLY option has no effect when you are adding new records.
The element parameters STRUCTURE or NOSTRUCTURE can be specified on a structure name to specify whether the individual elements should be set within the structure or whether the structure itself should be treated (and prompted) as a single element. STRUCTURE (or STR) directs $PROMPT to treat the structure as a structure, that is, to prompt for each element in the structure separately. NOSTRUCTURE (or NOSTR) tells $PROMPT that the structure as a whole should be treated as a single element.
The file definition must have the structure correctly defined to accept input in this form, and therefore the file owner will usually have coded the appropriate options already as a default. On rare occasions you may wish to use the STRUCTURE parameter to override instructions that a file owner placed in the file definition to compress a structure into a single element value. [See the manual "SPIRES File Definition", C.13.1.11.]
Once an element list has been established via a command of the form "SET FORMAT $PROMPT element-list", the element list can be changed to
- reset the list to a new list
- add new elements to the current list
- exclude existing elements from the current list
- change the name or prompted-occurrence limit of an element on the current list.
These functions are accomplished either by reissuing the "SET FORMAT $PROMPT element-list" command or by issuing the command "SET FORMAT * element-list".
To completely change from one element list to another, specify the new list on a SET FORMAT * command:
-> set format $prompt name address -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required mult ADDRESS -> set format * phone zip -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID optional 1 PHONE optional 1 ZIP -> set format * -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required mult ADDRESS optional 1 PHONE optional 1 ZIP ->
Note that if no new list is specified, $PROMPT format processing is reset to the default element list. During ADD processing, the record key is automatically added to the element list set unless it is a slot key or a supplied key.
To modify the current element-list to include new elements and/or exclude current elements, you must begin the new element-list with a "+" or a "-". The list may also have additional "+" or "-" embedded in it, each preceded by a blank or a comma. The "+" indicates that subsequent element name(s) are to be added to the current list; the "-" indicates that subsequent element names are to be deleted from the current list.
For example, given the command:
SET FORMAT $PROMPT NAME ADDRESS(2) PHONE
the commands
SET FORMAT * - ADDRESS PHONE SET FORMAT * + ZIP STATE
are, taken together, equivalent to
SET FORMAT * + ZIP STATE - ADDRESS PHONE
and result in
-> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME optional 1 ZIP required 1 STATE
The number option has no effect when removing elements from the list. You can only remove all of the prompted occurrences of an element. If you want to change the number of times an element is being prompted, you must replace the whole list.
As a convenience, all elements in the goal record (except virtual elements) can be referred to at once by the shorthand "ALL" when used according to the following syntax:
SET FORMAT $PROMPT ALL {+|-} element-list
SET FORMAT * ALL {+|-} element-list
The use of ALL gives a convenient way of setting a new list and excluding a few elements at the same time. Note that ALL is optional if no previous list has been established.
For example:
-> select name list -> show elements Subfile NAME LIST ID NAME ADDRESS STATE ZIP -> set format $prompt - state -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required 1 ADDRESS optional 1 ZIP -> set format * all - zip -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required 1 ADDRESS required 1 STATE -> set format * - state -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required 1 ADDRESS ->
The formal syntax of the element options on the SET FORMAT $PROMPT command is:
SET FORMAT $PROMPT [ [ALL {+|-} | {+|-}] element-list ]
or
SET FORMAT * [ [ALL {+|-} | {+|-}] element-list ]
where "element-list" itself may contain embedded "+" or "-" specifications. This seemingly complex syntax can be more simply stated narratively:
- if used, ALL must be the first word in the element options
- if used, ALL must be followed by a "+" or a "-"
- if used without ALL, "+" or "-" must begin the element options
- "+" or "-" may also be used inside the element list
- the element options must follow all processing options [See D.3.3.]
A set of options is available on the SET FORMAT $PROMPT command (and SET FORMAT * command when the $PROMPT format is set) to control the processing characteristics of the $PROMPT format itself. These options determine such things as whether or not structure names are printed during input prompting or data display functions, whether file-owner specified error messages are displayed in addition to or in place of standard SPIRES error messages when input errors are detected, etc.
The syntax of these options on the SET FORMAT $PROMPT command is:
SET FORMAT $PROMPT [(options)] [element options]
where "options" is defined as any number of the following, separated by commas and with the entire list enclosed in parentheses:
[NO]BRIEF [NO]UCODE [NO]NEW [NO]RETURN [NO]UPDATE [NO]RING [NO]APPENDONLY [NO]SORT [NO]SQUEEZE ESCAPE = x HELP = x
For example:
-> set format $prompt (nobrief,ucode,ring)
Note that "(options)", if specified, must be the first thing following the SET FORMAT $PROMPT command or SET FORMAT * command.
If processing options are not specified on a SET FORMAT * command, then those options set by any SET FORMAT $PROMPT command currently in effect will be used. Processing options can be set and reset by issuing successive SET FORMAT * commands that explicitly name options to be set or reset; options not named will have their values taken from any SET FORMAT $PROMPT command currently in effect. These points can be illustrated by the following example:
-> select name file -> set format $prompt -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME optional mult ADDRESS (Prompt: Street Address) -> set format * (brief,ucode,nonew) -> show format information Nonew, Return, Sort, Ucode, Noring, Noupdate, Noappendonly, Brief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME optional mult ADDRESS (Prompt: Street Address) -> set format * (ring) -> show format information Nonew, Return, Sort, Ucode, Ring, Noupdate, Noappendonly, Brief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME optional mult ADDRESS (Prompt: Street Address)
This option indicates that structure names are not to be displayed during input prompting or during record display. NOBRIEF, the default, indicates that structure names are displayed. Note that in either case, structure names are only displayed before the first occurrence of the structure; structure occurrences are separated by a blank line.
The UCODE option indicates that only a file-definer-specified error message (specified by either the $MSG proc or the SET UCODE command) is to be printed at the terminal if an error is detected during input of an element value. NOUCODE, the default condition, indicates that both the file-definer-specified error message and the standard SPIRES error message are displayed.
The NONEW option indicates that no new occurrences of elements or structures are to be prompted for during MERGE command processing. NEW is the default.
The RETURN option indicates that if the first prompted element of a structure is presented and the response is a carriage return, then the remainder of the current structure occurrence and additional occurrences of the structure will not be prompted. NORETURN indicates that all set elements in the structure will be prompted, even if a carriage return has been entered in response to the first prompted element. To exit the structure when NORETURN is set and not all elements have been prompted for, you must use "/E". RETURN is the default.
The RING option will sound the terminal's bell at each element prompt. This allows for rapid data entry by an operator who does not have to look at the terminal to see when elements have been prompted. NORING is the default.
The NOUPDATE option indicates that data read to process an UPDATE command is to be taken from the active file in default SPIRES format; the UPDATE option specifies that the data read is to be prompted for. If you issue an UPDATE command and the $PROMPT format prompts you for values, all values must be re-entered, unlike merge processing where you enter values only for the elements you want to change. [See D.3.1.4.] The TRANSFER command is allowed in either case, although a warning message will be issued if a TRANSFER is done with the UPDATE option set; it warns the user that a corresponding UPDATE command will not read data from the active file. The NOUPDATE option is the default.
As an element option, APPENDONLY specifies that you only want to be prompted for new occurrences of a particular element during a MERGE process. [See D.3.2.1.3.] You can specify this for all elements being prompted by using APPENDONLY as a global processing option. This will cause you to be prompted only for new occurrences of all multiply-occurring elements you are being prompted for. NOAPPENDONLY is the default.
The SORT option tells $PROMPT to prompt elements in the order specified in the file definition, no matter in what order you have listed them in a SET FORMAT $PROMPT or SET FOR * command. By specifying NOSORT you can have the elements prompted in the order you have named them on your SET FORMAT $PROMPT or SET FOR * command, without having them "sorted" into the file definition's order. If you do specify NOSORT it will be up to you to specify elements according to the correct record hierarchy. SORT is the default.
$PROMPT by default pads its format with some blank lines for ease of reading. You can use the SQUEEZE option to remove some of these lines and compress the format. You might need to do this if, for instance, the record structures in your subfile were so lengthy that the beginning of the structure scrolled off the screen before the end came into sight. NOSQUEEZE is the default.
Subcommands are used to control the functioning of $PROMPT. They must begin with the "escape" character so that they will be interpreted properly. By default, the escape character is the slash (/). If input values contain the escape character such that a portion of the value could be mistaken for a subcommand, it is necessary to reset the escape character to another character that would not appear in the input. The ESCAPE option can be used to change the escape character to some other special character. The new escape character may not be a letter or a number; it must be a special character. For example, the following commands set the escape character to "@".
-> set format $prompt (escape = @) name address phone -> set format $prompt (ucode,escape = @,appendonly) name phone
By default during record processing typing a "?" in response to a prompt calls up any element description information that the file owner has provided. [See D.3.5 where the DESCRIPTION info-element is discussed.] You can change the default character for accessing this information from "?" to some other non-alphanumeric character using the HELP option. For instance, specifying "HELP=$" would change the character in question to a dollar sign. You would most likely use this option if some of the values you were to input began with a question mark.
All of these processing options can be changed while you are adding or updating a record by issuing the "/set" subcommand. [See D.3.4.4.]
During input prompting, it is sometimes necessary to pass instructions to the $PROMPT format in addition to passing data; for example, you can indicate that you want to end prompting and add the data record to the subfile, or you can indicate that you want to cancel prompting and not add the prompted data to the subfile. This kind of control is accomplished by "subcommands" recognized only while you are being prompted by the $PROMPT format.
Subcommands accomplish a variety of different functions, but they all have one thing in common: all make use of an "escape" character to indicate a special meaning for the character(s) that follow. In the $PROMPT format, the default escape character is the slash character (/). [See D.3.3 for description of how to change the escape character.]
In the following explanations, the default escape character is shown. The explanations describe the subcommands in logically related groups; there is no formal or syntactic difference among the groups, however.
The subcommands that control element input are described below:
Generally, pressing the carriage return key only -- noted by <return> here -- in response to a prompt indicates acceptance of what is displayed. Thus, <return> in response to a prompt for a new element value in ADD or UPDATE processing indicates that no value is desired for this element; i.e., that the element is to be skipped. However, if the file-owner has coded the DEFAULT info-element [See D.3.5.] then the user is notified of the default during the input process and presses return to accept the default value. Pressing return in response to a prompt for a replacement element value during a MERGE request indicates that the current value is not to be changed.
As with elements, <return> indicates that structures are skipped, or accepted as they are; however, this <return> must be issued in response to the first element prompted in the structure. (This action may be changed by the RETURN processing option [See D.3.3.] or you may use "/N" or "/NEXT" to skip the first element of a structure and move on to the second.) Note that the $PROMPT format will not let you continue past a required element using the <return> response; either "//" or "/N" (see below) must be used to do this.
It is infrequently necessary to enter a null-length (i.e., zero length) value for an element. Specifying "//" (i.e., a double escape character) only in response to the element name prompt indicates that the element is to occur, but with a null-length value.
The "/N" subcommand advances or skips $PROMPT format prompting to the next element without inputting any value for the element being prompted (note that this is not the same as a null-length value). During ADD processing, this is useful when elements with default values (such as an element that automatically records the date the record was added) are being prompted and you wish to accept the default value. (Note that if the file owner has coded the DEFAULT info-element [See D.3.5.] a user may simply press return to accept the default value.)
During MERGE processing, "/N" can be used to skip prompting for all occurrences of one element and go on to the next element. For structures, "/N" can be used to skip the first element prompted, without having the $PROMPT format leave the structure (as it would if <return> were the response). Note that "/N" skips all occurrences of an element, not just the occurrence being prompted.
If the value to be entered has leading blanks, the blanks must be preceded by the escape character. Normally, leading blanks are stripped before the value is added to the record.
Long element values may be continued on additional lines by appending each line of the value (except the last) with a double escape character. In most cases, about 150 characters may be entered before a line must be continued. However, it is recommended that you stop inputting a value when it reaches about 110 characters, and let SPIRES prompt you for "more". Continued lines, prompted by "more -->", are concatenated to each other with a space (blank) between the lines. Lines entered that are over 100 characters in length are automatically continued; simply press return in response to "more-->" if you have no more of the value to entered. On display, values are wrapped at the value of SET LENGTH. Note that $PROMPT subcommands are not recognized at the "more-->" prompt.
The following example demonstrates the use of "<return>", "value//", "/ value", "/N", and "//".
-> select customer list
-> set format $prompt
-> show format information
New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief
Nosqueeze, Help='?', Escape='/'
Input Occ Element
-------- --- -------
supplied SLOT
required 1 DATE-ADDED
required 1 NAME
required mult ADDRESS
required 1 ZIP
optional mult NOTE
optional mult NUMBER
-> add
: DATE-ADDED <-- return pressed to attempt to skip element
-Value required - enter /N, or // for null value
: DATE-ADDED /n <-- skips a required element with default value
: NAME Jessica Blake
: ADDRESS(1) // <-- enter a null (zero-length) value
: ADDRESS(2) 2731 Flamingo Road
: ADDRESS(3) Truro, Florida
: ADDRESS(4) <-- return pressed to stop prompting new values
: ZIP 01043
: NOTE(1) If this note is long, I can continue it//
: more--> on the next line by putting "//" on the end.
: NOTE(2) / This note has leading blanks.
: NOTE(3) /e <-- ends prompting for record element input
-Added record: 409
-> display 409
SLOT 409
DATE-ADDED 02/16/81
NAME Jessica Blake
ADDRESS(1)
ADDRESS(2) 2731 Flamingo Road
ADDRESS(3) Truro, Florida
ZIP 01043
NOTE(1) If this note is long, I can continue it on the
next line by putting "//" on the end.
NOTE(2) This note has leading blanks.
->
The following subcommands affect the processing of entire structures and all the elements in those structures. Note that all but the first command described below ("/E") affect only the single occurrence (called a "structure occurrence") of the structure currently being prompted; they do not operate on all occurrences of a given structure at once.
This subcommand exits the current structure occurrence and the current structure, and continues prompting with the next element after the structure in the $PROMPT format element list. If "/E" is issued while you are not in a structure, then it functions to end the current record input, followed by an attempt to perform the requested ADD or MERGE command processing. The "/E" subcommand can be issued in response to any element value prompt in a structure, not just the first element value prompt.
This subcommand causes prompting in the current structure occurrence to stop, and the $PROMPT format advances to prompting for the next occurrence of the current structure. During merge, if there is no next occurrence, that is, if the current occurrence is the last occurrence, "/S" begins prompting for a new occurrence of the structure. "/S" may be the response to any element value prompt in a structure, not just the first element prompt. If "/S" is issued when you are not in a structure, it acts as "/E" at the record level and ends prompting for input.
This subcommand causes the current structure occurrence to be deleted from the record. Note that this removes all element values in the current structure occurrence, not just the element currently being prompted. (To remove just a single element occurrence, use "/R".)
This subcommand causes prompting to stop for the current structure occurrence and move to creating a new occurrence of the same structure; the new occurrence is added after the current last occurrence of the structure. New occurrences of the structure will be prompted until <return> is entered in response to the first element value prompt, or "/E" or "/N" is entered, or until the occurrence count would exceed the prompted-occurrence limit specified on the SET FORMAT $PROMPT command. [See D.3.2.1 for an explanation of the "prompted-occurrence limit".]
The following example demonstrates the use of "<return>", "/E", "/S", "/RS", and "/AS" subcommands.
-> select rolodex
-> set format $prompt
-> show format information
New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief,
Nosqueeze, Help='?', Escape='/'
Input Occ Element
-------- --- -------
supplied ID
required 1 NAME
required mult PHONE
required 1 . NUMBER
optional 1 . TYPE
optional 1 . HOURS
optional 1 AFFILIATION
optional 1 COMMENTS
-> add
: NAME Emily DuMonde
Structure: PHONE
: NUMBER 328-1232
: TYPE business
: HOURS <-- carriage return is pressed
: NUMBER 326-3324
: TYPE /s <-- moves prompting to next structure occurrence
: NUMBER 322-7674
: TYPE /e <-- moves prompting to next element
after this structure
: AFFILIATION /e <-- ends record input
-Added record: 324
-> merge 324
*** 324 ***
: NAME..........Emily DuMonde
Structure: PHONE
NUMBER.....328-1232
: NUMBER /s <-- moves prompting to next structure occurrence
NUMBER.....326-3324
: NUMBER /rs <-- removes this structure occurrence
NUMBER 322-7674
: NUMBER /as <-- moves prompting to append
new structure occurrences
: NUMBER 328-0920
: TYPE /e <-- ends input of the current structure, moves
prompting to next element after structure
: AFFILIATION /e <-- ends record input
-> display 324
SLOT 324
NAME Emily DuMonde
Structure: PHONE
NUMBER 328-1232
TYPE business
NUMBER 322-7674
NUMBER 328-0920
The following subcommands are available during MERGE processing only, to allow the functions required to add, change, or remove data in an existing record.
In processing a MERGE command for multiply-occurring elements, all occurrences of the element are first displayed before any prompts. Prompting then begins on the first element occurrence displayed. To add additional occurrences to the element without having to skip (via <return>) over all existing occurrences one-by-one, an "/A" or "/APPEND" may be entered. When this subcommand is processed, prompting will skip to the occurrence one after the last, and new values are prompted until a <return>, "/E" or "/N" is entered. If the one-past-the-last occurrence is higher than the prompted-occurrence limit for the element, then the "/APPEND" or "/A" acts as "/N"; prompting continues with the next element. [See D.3.2.1.]
This command will remove the currently presented element occurrence.
The change subcommand can be used during MERGE processing to modify an existing element value without having to re-enter the entire value; this is particularly useful when the element occurrence is a long text-string. The "/C" or "/CHANGE" subcommand can be used to change a substring of the value or remove a substring. The "old" and "new" substrings must be preceded by a non-alphanumeric escape character. The escape character, in this case, is temporarily redefined as the first character following the "/C" or "/CHANGE" string. A blank or space is an acceptable escape character in this situation. If no "new" substring is given, then the "old" substring will be removed from the value.
When you use the "/c" subcommand, all occurrences of the string in the element value being modified will be changed.
This command is only valid when a change subcommand has been entered for the current element occurrence. The effect is to return the element value to the value that was stored in the data base prior to the MERGE command.
This command allows you to insert text at the beginning of the current value being prompted. It saves you the trouble of retyping a long value when all you want to do is add something to the beginning of it. You do not need to surround the inserted text with quotation marks but you should type one space between the subcommand itself and the text to be inserted. If the text you wish to insert contains trailing blanks, type the escape character after the blanks to ensure that they are not stripped away. (Note: on some terminals the final escape character may not be necessary.)
This command allows you to add text to the end of the current value during prompting; once again it can save you the trouble of typing out a long value when all you want to change is its ending. You do not need to surround the inserted text with quotes but you must type a space between the subcommand and the text to be inserted. Any additional blanks besides this first one will be treated as part of the text to be inserted. (See the example below.)
Since MERGE processing displays all occurrences of an element in a record before prompting for changes to the first occurrence, you usually know the occurrence number of the element value you wish to change. By specifying the "/n" subcommand, where "n" is the occurrence number you wish to modify, in response to a prompt for an occurrence of the element, you are immediately positioned at and prompted for changes to that element occurrence. Note that you cannot move to an occurrence whose number is less than the occurrence number currently being prompted. You may request an occurrence number greater than the highest existing occurrence number; this is equivalent to "/A" and begins prompting you for new occurrences.
The following example demonstrates the use of "<return>", "/A", "/R", "/C", "/U", "/n", "/IE", and "/E". Note that element value prompts from the $PROMPT format are prefixed by ":"; element values being displayed by the format have no prefix other than the element name itself.
-> select customer list -> set format $prompt -> show format information New, Return, Sort, Noucode, Noring, Noupdate, Noappendonly, Nobrief, Nosqueeze, Help='?', Escape='/' Input Occ Element -------- --- ------- supplied ID required 1 NAME required mult ADDRESS required 1 ZIP optional mult NOTE optional mult NUMBER -> merge 27 *** 27 *** ID...........27 NAME.........Mary Anderson : NAME <-- carriage return is pressed to accept the value ADDRESS(1)...1550 MAMA DRIVE ADDRESS(2)...BIG SUR, CA. ADDRESS(3)...SALES MANAGER : ADDRESS(1) /3 <-- used to skip to the third occurrence : ADDRESS(3) /r <-- used to remove the current occurrence ZIP..........95444 : ZIP <-- carriage return is pressed to accept value NOTE(1)......THIS IS A NOTE OF UNREST TO ALL. NOTE(2)......EITHER LINE MEANS MUCH. NOTE(3)......IT IS A MULTIPLY-OCCURRING ELEMENT : NOTE(1) /c/UNREST/INTEREST/ NOTE(1)......THIS IS A NOTE OF INTEREST TO ALL. : NOTE(1) <-- return pressed to accept displayed value : NOTE(2) /c EITHER NEITHER <-- temporary escape is a space NOTE(2)......NEITHER LINE MEANS MUCH. : NOTE(2) /u <-- undo current change to this occurrence NOTE(2)......EITHER LINE MEANS MUCH. : NOTE(2) /i N <-- prefixes the value with "N" NOTE(2)......NEITHER LINE MEANS MUCH. : NOTE(2) /c/LINE / <-- removes the string "LINE " NOTE(2)......NEITHER MEANS MUCH. : NOTE(2) /ie SORRY! NOTE(2) NEITHER MEANS MUCH. SORRY! : NOTE(2) /a <-- accepts current value & appends occurrences : NOTE(4) this is the first new occurrence : NOTE(5) and this is the second : NOTE(6) <-- return pressed to stop prompting new values : NUMBER(1) /e <-- end prompting -> display 27 ID 27 NAME MARY ANDERSON ADDRESS(1) 1550 ALMA DRIVE ADDRESS(2) FREMONT, CA. ZIP 95444 NOTE(1) THIS IS A NOTE OF INTEREST TO ALL. NOTE(2) NEITHER MEANS MUCH. SORRY! NOTE(3) IT IS A MULTIPLY-OCCURRING ELEMENT NOTE(4) this is the first new occurrence NOTE(5) and this is the second ->
The subcommands that control $PROMPT format options themselves or that stop Input Format processing are:
Further input for this record is not prompted, and an attempt is made to ADD or MERGE the data input so far. Note that if you end record input while required elements do not yet have values, the record will be rejected. "/E" or "/END" can also be used to end structure processing. [See D.3.1.1.]
Further input for this record is not prompted, and the ADD or MERGE command request is aborted with the data base unaffected; an UPDATE ABORT error message is issued. Note that all data just entered for this particular record is discarded when "/X" or "/CANCEL" is issued.
A processing option [See D.3.3.] such as RING or NONEW is set. The element name being prompted is reprompted.
A new escape character is set; subsequent subcommands, including a "set escape character" subcommand, must use this new character. The element name being prompted is reprompted.
Issue this subcommand to interrupt processing and see the $PROMPT help screen immediately. When you return from the help screen the element name currently being prompted will be reprompted.
Issue this subcommand in order to pass a command to WYLBUR without ending or interrupting your processing. The element currently being prompted is immediately reprompted. (See below for an example.)
-> select name list -> add : NAME Liz Courtney Curtis : ADDRESS New Salem : PHONE /e -Added record: 347 -> add : NAME Tod Chandler : ADDRESS /W to gq.jpr I'm adding the Chandler record now. : ADDRESS /=! : ADDRESS !W to gq.jpr His phone is listed as 'Virginia' : ADDRESS Salem : PHONE !=/ : PHONE Virginia -Element=PHONE: Value must be numeric -Serious data error, code=E21 : PHONE /set ucode : PHONE Virginia Value must be numeric : PHONE /x -Update terminated, code=S2 ->
Here is a summary list of the subcommands available in the $PROMPT format:
<return> continue to the next prompt // input a null-length value /NEXT or /N skip to the next element / value retain leading blanks in the value value// continue the value to another line
/END or /E end input into the current structure /SKIP or /S skip to the next occurrence of the structure /RS remove current structure occurrence (MERGE only) /AS add structure occurrence(s) (MERGE only)
/APPEND or /A add occurrence(s)
/REMOVE or /R remove the current occurrence
/CHANGE/old/new change substring of the occurrence
or /C/old/new from "old" to "new" text
/UNDO or /U undo the change ("new" text returns to "old")
/n position at the "nth" occurrence
/INSERT or /I insert text at the beginning of the value
/IE add text at the end of the value
/END or /E end record input
/CANCEL or /X cancel request
/SET option set processing option:
NOBRIEF|BRIEF
NOUCODE|UCODE
NEW|NONEW
RETURN|NORETURN
NORING|RING
NOUPDATE|UPDATE
SORT|NOSORT
NOSQUEEZE|SQUEEZE
HELP
ESCAPE
/=s reset escape character
/WYLBUR command pass a command to WYLBUR
or /W command
/HELP or /? access help screen immediately
/HELP='x' reset help character
File owners who would like to take advantage of the $PROMPT format should consider adding "element information packets" and the other features described below to their file definitions, in order to make it easier for users to work with the subfile using $PROMPT.
"Element information packets" allow the file owner to add information to the file definition about the element. This information then becomes directly or indirectly accessible to users of the file, helping them interpret the elements correctly and input correct values for them. The following "info-elements" are of use in conjunction with the $PROMPT format:
HEADING DEFAULT SUPPLIED INPUT-OCC VALUE-TYPE DESCRIPTION
This section will describe each of them briefly, but for fuller information you should consult chapter C.13 of the "File Definition" manual.
The HEADING info-element provides a default value for prompting that overrides the element name. (It in turn can be overridden by the user with the PROMPT option described earlier.) Using HEADING gives the file owner a chance to characterize the element clearly when the element name alone might be misleading. When prompting for an element, the $PROMPT format will look first for a value specified by the user with the PROMPT element option. If the user did not include this option, the format will look for the HEADING info-element in the file definition. If this does not exist, the element will be prompted with the alias used in the element list on the SET FORMAT $PROMPT command. Otherwise, the primary mnemonic is used.
The DEFAULT info-element tells the user that a default value will be supplied for the prompted element if none is input. In particular, DEFAULT lets the user skip the input of a Fixed or Required element simply by pressing the return key. It would be used in conjunction with an INCLOSE rule to provide the default value. The SUPPLIED info-element is somewhat similar to DEFAULT, except that the element to which it is applied will not even appear among the prompted elements unless explicitly named in the $PROMPT element list. Even when the element is named in the element list the user will not be able to input or change values for it during prompting.
The INPUT-OCC info-element can be very useful in limiting the number of times a multiply occurring element is prompted. The file owner uses it to "tell" $PROMPT how many occurrences of the given element have been allowed in the file definition. $PROMPT then prompts for values only until that allowed limit has been reached. (Note that INPUT-OCC doesn't actually change the number of occurrences allowed but merely passes the number to the format.) INPUT-OCC can eliminate the problem mentioned in D.3.1.5 where the user inputs more elements than the file definition allows and must re-enter the entire record.
Note that it is not enough simply to code the number of occurrences you want for an element in your file definition (in an OCC statement, e.g., OCC = 5;). $PROMPT still will not know that number until you tell it either through the INPUT-OCC info-element or through the SELECT-COMMAND (see below). If you don't provide this information your user may end up having a lengthy record rejected when the INCLOSE rules are finally applied to element values and occurrences entered much earlier.
The VALUE-TYPE info-element may be used to display a structure in $PROMPT as though it were a single value. The individual elements in the structure are compressed so that they appear as one value, assuming that the appropriate processing rule has also been applied [See C.13.1.11 of "File Definition" for more details.] The user can override this info-element using the element parameter STRUCTURE [See D.3.2.1.]
The DESCRIPTION info-element contains the description of the element that is displayed when the user responds to the prompt with a "?". For example:
-> set format $prompt -> add : NAME ? This element contains the student's name. : NAME
Such explanations are an integral feature of the File Definer, which can be used to create file definitions. They are created by using the EXPLAIN keyterm after an element input line. To see how info-elements are coded, try creating a test file definition with the File Definer, using the EXPLAIN keyterm. [See the SPIRES manual "File Definer".]
File owners often code customized error messages for element processing rules, so that the user doing data entry can be told specifically what mistake he or she has made, rather than just letting SPIRES display its more general error messages. These customized error messages are specified in the file definition with either the $MSG proc or the SET UCODE command in a USERPROC. The processing option SET UCODE [See D.3.3.] can turn off the SPIRES input error messages completely, so that only the customized error messages are displayed. Thus, if you have messages for all the errors that are likely to be made and you have tailored them specifically for your application, you can make error handling more attractive and useful. If SET NOUCODE, the default, is in effect, both the customized message and the SPIRES message will appear when an error is made.
The problem mentioned earlier with multiply occurring elements can be solved in another way besides providing element information packets. The file definer can instead include a SELECT-COMMAND in the subfile section of the file definition that will SET FORMAT $PROMPT with element options that include occurrence numbers for the multiply-occurring elements:
SELECT-COMMAND = SET FORMAT $PROMPT NAME ADDRESS(3) CITY;
In this example SPIRES will only prompt for three occurrences of the ADDRESS element. The SELECT-COMMAND statement is a useful way to customize the $PROMPT format for a subfile.
Note that if you use the FORMAT statement to set the $PROMPT format automatically when the subfile is selected, you cannot include options in the FORMAT statement. For example,
FORMAT = $PROMPT NAME ADDRESS(3) CITY;
will not set the format properly.
Removing records from a subfile is a much simpler operation than adding or updating them, both internally to SPIRES and externally to you. It is simpler because SPIRES needs only the key of the record. When a record is removed, only the key (not the entire record) is placed in the deferred queue to await overnight processing.
REMOVE is the command you issue to remove records from a subfile. It is not affected by formats, as the ADD, UPDATE and MERGE commands are. Hence there is but one basic method for removing records -- the REMOVE command. It is discussed in the first section of this chapter.
The REMOVE command does not actually cause the record to be removed from the subfile until overnight processing occurs. As a result, it can be "rescued", if you realize that you removed it by mistake, up until the time the file is next processed. Three different commands can be used to reverse the effects of online modification, and they are each discussed in this chapter:
When the information in a record is no longer needed, the record can be removed totally from the file using the REMOVE command. From the time the REMOVE command is issued and executed by SPIRES, the normal search procedures will no longer retrieve the record. After the REMOVE command is issued, the key of the record to be removed is placed in the deferred queue. Through the deferred queue the record may still be accessed and the REMOVE request "dequeued" if desired. [See D.4.2, D.4.3, D.5.5.] When SPIRES performs daily overnight processing on the file, the record disappears, and all pointers to it are removed from the index records.
The format of the command is as follows:
REMOVE record-key-value
where "record-key-value" is the value of the key data element that uniquely identifies a single goal record. For example:
-> select blood donors -> remove 58 -No such record, code=S256 -> remove 57 -> display 57 -No such record, code=S256
The returned prompt with no error message after the REMOVE command indicates that the command was successful.
The error message "No such record" is an indication that the record key value entered was incorrect, that the record has already been removed, or that it was never added. When the system replies with its normal prompt, "->", the removal has been successfully accomplished.
If you have erroneously issued the REMOVE command and desire to regain the original record, the command "UNQUEUE record-key-value" may be used. This command restores the record to the status it had before the REMOVE command was issued. Remember, however, that the record can be rescued only until the file is processed.
The UNQUEUE command discards the most recently issued transaction request for the named record. Its effect is to restore the record to its state before the last transaction was executed. For example, if a record was added, then updated, then removed, the UNQUEUE command will restore the record to its "updated" state.
The syntax is:
UNQUEUE record-key-value
You cannot unqueue more than one transaction back in a series of transactions. [See D.7 however.] When you issue this command, it becomes another transaction against that record in the deferred queue; a second UNQUEUE command will simply unqueue the previous UNQUEUE request. Because the DEQUEUE command is also a transaction, it is possible to unqueue a DEQUEUE request.
The UNQUEUE command is similar to the DEQUEUE command, except that the DEQUEUE command restores the record to the state it was in after the file was last processed, in effect discarding all transactions for the record. [See D.4.3.] But it is crucial to remember for both commands that they affect only transactions that are currently in the deferred queue. Once the file is processed, the UNQUEUE and DEQUEUE commands have no effect on transactions entered before the file was processed.
The following sequence illustrates the UNQUEUE command and how it differs from the DEQUEUE command:
-> select restaurant
-> collect clear
1. > NAME = Our House;
2. > ADDRESS = Private;
3. > TYPE-OF-FOOD = anything you want;
4. > COMMENTS = Swell place to visit;
5. > *** (ATTN)
(1) -> add
-Added record 220
-> transfer 220 clear
-> list
1. REC01 = 220;
2. NAME = Our House;
3. ADDRESS = Private;
4. TYPE-OF-FOOD = anything you want;
5. COMMENTS = Swell place to visit;
-> delete 5
(2) -> update
(3) -> unqueue 220
(4) -> display 220
REC01 = 220;
NAME = Our House;
ADDRESS = Private;
TYPE-OF-FOOD = anything you want;
COMMENTS = Swell place to visit;
(5) -> unqueue 220
(6) -> display 220
REC01 = 220;
NAME = Our House;
ADDRESS = Private;
TYPE-OF-FOOD = anything you want;
(7) -> dequeue 220
(8) -> display 220
-No such record, code=S256
(9) -> unqueue 220
-> display 220
REC01 = 220;
NAME = Our House;
ADDRESS = Private;
TYPE-OF-FOOD = anything you want;
->
The record is added (1), then updated with the COMMENTS element omitted (2) and then unqueued (3), which returns the record to its state after (1), as demonstrated by the DISPLAY command (4). When the record is unqueued again (5), the effect is to unqueue the unqueue, which returns the record to its state after (2), as demonstrated by another DISPLAY command (6).
Next the record is dequeued (7), which discards all transactions in the deferred queue for the record. Because the record had been added since the file was last processed (1), the record no longer exists, as the response to the next DISPLAY command demonstrates (8). When the record is unqueued again (9), the DEQUEUE command is rescinded and the record is restored to its state prior to the DEQUEUE command, as the final DISPLAY command shows.
The DEQUEUE command withdraws requests to add, update or remove records in a particular subfile. Once withdrawn from the deferred queue, these requests are never submitted to the overnight processor, and thus the file is not affected by them.
The syntax is:
DEQUEUE record-key-value
This command withdraws any modifications for the specified goal record in the selected subfile that were made since the file was last processed. It has no effect on records for which there are no transactions in the deferred queue.
The following sequence illustrates the DEQUEUE command:
-> select restaurant
-> collect clear
1. > NAME = Our House;
2. > ADDRESS = Private;
3. > TYPE-OF-FOOD = anything you want;
4. > COMMENTS = Swell place to visit;
5. > *** (ATTN)
-> add
-Added record 220
-> transfer 220 clear
<-- You make changes to the record in your active file
-> update
-> dequeue 220
-> display 220
-No such record, code=S256
Both the ADD and UPDATE transactions for record 220 were in effect discarded by the DEQUEUE command. Contrast that with the UNQUEUE command; had it been issued instead, the final DISPLAY command would have displayed the original added version of record 220. [See D.4.2.]
The ZAP DEFQ command withdraws all record modifications and batch requests for all of the subfiles of the file. [See D.8.] It can be issued only by the file owner.
The syntax is:
ZAP DEFQ [NOWARN]
When you issue this command, SPIRES will prompt:
-Do you want to clear the DEFQ of gg.uuu.filename?
where "gg.uuu.filename" is the name of the file to which the currently selected subfile belongs. Since the command completely erases all transactions since the file was last processed, SPIRES asks for confirmation of your intentions. You should respond with YES or OK; responding NO or pressing ATTN/BREAK stops SPIRES from executing the command further. If you include the NOWARN option on the command, you will not receive this prompt.
This command cannot be used on files that have any indexes that are updated immediately. [See D.2.1.] It also cannot be used when there is an open transaction group for the file. [See D.9.]
Although its effect is similar to the DEQUEUE command (if that command were issued for all the records in all the subfiles of the file that are in the deferred queue), it is drastically different. Unlike DEQUEUE, it actually discards the records in the deferred queue immediately; with DEQUEUE, you can issue the UNQUEUE command to undo any damage you do, but you cannot issue the UNQUEUE command to undo the ZAP DEFQ command.
When in Global FOR, the TRANSFER, UPDATE, MERGE, REMOVE and DISPLAY commands permit you to see and modify records without specifically knowing their respective key values. The command "FOR class" must first be issued to indicate to the system that records to be modified or displayed are in a particular class. [See B.5.3.3 for a summary of basic Global FOR processing, D.7.6, D.7.7 for the use of the DEQUEUE and UNQUEUE commands in Global FOR.] [Also see the manual "Sequential Record Processing in SPIRES: Global FOR".]
When the "FOR class" command is issued, any subsequent TRANSFER, UPDATE, MERGE, DISPLAY or REMOVE commands will refer to records in the class sequentially, rather than by key value. Updating under Global FOR can be particularly useful with search results, using the FOR RESULT command.
For example, if all records added to the RESTAURANT subfile before June 1976 were to be removed from the subfile, there is no need to find their key values and then issue REMOVE commands against each key value. The process can be done with the following commands:
-> select restaurant -> find date-added before june 1976 -Result: 22 RESTAURANTS -> for result +> remove all -Removed: 22 records +>
REMOVE ALL can be very powerful: with a single command you can remove all records in the search result. But this may be too powerful. Suppose you only wanted to remove some of the records in the result, and wanted to transfer and update others. To do this, an option other than "ALL" can be specified after most commands in Global FOR; basic syntax for these commands is included in this section.
Because many of the commands share the same options, here are some examples explaining them as they are used with different Global FOR commands. You may specify a number, which indicates the number of records to be removed or displayed. Note that this number is always relative to the "current" record, and not relative to the first record in the result.
For example, examine the following command sequence:
-> for result
+> display 5
<--- First five records are displayed
+> remove 3
<--- Next three records are removed; i.e., the sixth,
seventh and eighth records in the search result
are removed
+>
To "process" the next record you can specify NEXT instead of the ALL option. (Note: the term "process" is used in Global FOR documentation to refer to the handling of a record, e.g., if you display five records in Global FOR, you are "processing" them in Global FOR. This has absolutely nothing to do with "file processing", when records are moved from the deferred queue to the tree and the indexes are updated.)
You can also process the same record more than once by specifying "*" instead of ALL. "*" directs the system to process the record that was last processed by the previous command. For example:
-> for result +> display 5 <--- First five records are displayed +> remove * <--- Current (fifth) record is removed +> display next <--- Next (sixth) record is displayed +> remove * <--- Current (sixth) record is removed +> remove <--- Next (seventh) record is removed +> endfor -End of global FOR ->
Besides NEXT, ALL, and "*", other similar options allowed in the Global FOR process for updating are FIRST, LAST and REST. FIRST or LAST can be specified to indicate that the first or last record in the search result be acted upon. REST or REMAINING can be specified interchangeably to indicate that the next and all subsequent records be processed.
Having obtained a group of records with a "FOR class" command, you may then use the TRANSFER command in Global FOR to move sequentially through them, examining the records one-by-one and modifying them when appropriate. After the necessary modifications have been made, the individual record can be replaced in the file with the UPDATE command and the next TRANSFER command in Global FOR can be issued. If you examine the record after the TRANSFER operation in Global FOR and find that no modifications are necessary, the UPDATE command need not be issued; in this respect, TRANSFER in Global FOR is similar to the TRANSFER command outside of Global FOR. The essential difference is that TRANSFER operates on a single record by virtue of its specified key value, while TRANSFER in Global FOR operates on that record which is first or next in the class, an order determined by an internal SPIRES ordering procedure.
The basic form of the TRANSFER command in Global FOR is:
TRANSFER [FIRST|*|NEXT|n|LAST] [CLEAR|KEEP]
Specifying "*" indicates that the "current" record being examined is to be transferred; specifying "n", an integer number, indicates that the "nth" record past the current one is to be transferred. Specifying none of the options directs the system to transfer the "next" record. Note that the ALL and REST options are not available with the TRANSFER command because only one record can be transferred into your active file at a time.
The following sequence illustrates the use of the TRANSFER command in Global FOR:
-> find date-added after 1972
-Result: 10 RECORDS
-> for result
+> transfer
<-- modifications are made to the first record in the result
+> update
+> transfer clear
<-- modifications are made to the second record
+> update
+> transfer clear
<-- third record is transferred and examined
+> transfer clear
<-- no modifications were made to the third,
you then go to modify the fourth
+> update
+> transfer 3 clear
<-- the seventh record is transferred, since it is three
records past the last one processed. Note that
"transfer 3" does not mean to transfer three records,
but to transfer the third record from the current one.
+>
The REMOVE command in Global FOR operates on the records in a class in the same fashion as the TRANSFER command in Global FOR. Both move through the class in sequence, offering you a chance to indicate what action is to be taken on the individual record. The great advantage to both Global FOR commands is that you can work with records on the basis of the information they contain rather than search for and specify their individual record key values.
The form of the command is:
REMOVE [FIRST|*|NEXT|n|REST|LAST|ALL]
Specifying ALL indicates that all records in the class being examined are to be removed; specifying "n", where "n" is an integer number, removes "n" records past the current record in the class being examined. (Note the difference in the "n" option between the TRANSFER and REMOVE commands: "TRANSFER n" means transfer the "nth" record after the current one. "REMOVE n" means remove the next "n" records. You should note carefully which meaning of "n" each command has in the following sections as well.) "*" indicates the "current" record. The option NEXT is assumed if no other option is given.
The command also has two other options, the prefixes WITH FAST and WITH SEARCHONLY, which can be used by the file owner and by users with Master access to the file to speed up the processing. See the manual "SPIRES File Management", Part 6, for details about how these options work on the INPUT BATCH command, which is applicable to their use here; online, EXPLAIN WITH FAST PREFIX.
The following sequence illustrates the use of the REMOVE command in Global FOR mode:
-> for result +> remove all -Removed: 23 records +>
A message telling you how many records have been removed will be displayed. No such message is displayed when the REMOVE command is used outside of Global FOR since the REMOVE command only affects one record per request in those circumstances.
Note that the REMOVE command can act upon "ALL" records in a Global FOR class, such as RESULT, at once. The TRANSFER command, however, can only process a single record at a time. The REMOVE ALL command after a FOR RESULT command will remove all records in the search result from the subfile. The REMOVE ALL command after a FOR SUBFILE command will remove all the records in the subfile!
The DISPLAY command can be used in Global FOR to move sequentially through the class of goal records being examined. Like the REMOVE command in Global FOR, the DISPLAY command can examine and process one, more than one, or all records with a single command. [See B.5.3.4.]
You may want to move sequentially through the records, first displaying a record to determine, by visual inspection, whether or not it is to be removed, and then either removing it or going on to display the next record.
The technique for doing this is shown in the following example, which mixes DISPLAY and REMOVE commands in Global FOR mode.
-> show result
-Result: 3 ITEMS
-> for result
+> display next
<-- the first record is displayed
+> remove *
-Removed: 1 record(s)
+> display next
<-- the second record is displayed
+> display
<-- the third record is displayed
+> remove *
-Removed: 1 record(s)
+> display
-End of global FOR
->
Notice in this example that in Global FOR if nothing follows a DISPLAY or REMOVE command, the system will assume a default and process the next record in the search result (NEXT may be stated explicitly). But if "*" is indicated, the system will process the same record as was last processed by the previous command. Thus, the above example will display the first record, then remove it; display the second record; display the third record, then remove it. Also, note that since only three records were in the stack, an attempt to display a fourth record caused an automatic end to Global FOR processing. [See B.5.3.4.]
Like the TRANSFER command, the MERGE command is available in Global FOR mode. The MERGE command in Global FOR causes records in the class specified in the FOR command to be updated with the current contents of the active file if the standard format is in effect.
If the $PROMPT format is set, SPIRES will start prompting you for element values to be used to update the record. [See D.3.1.4.] You may use other input formats as well, though a format's designer will probably need to tell you how it should be used with MERGE. In some cases, it may ask you once for input to merge into all the records; in other cases, it may read the data from the active file once to merge into all the records; in still other cases, it may read one or more lines of data for each record being merged. [See the manual "SPIRES Formats" for information on how to write merge formats.]
The format of the command is:
MERGE [FIRST|*|NEXT|n|REST|LAST|ALL] [USING line-range]
Specifying "*" indicates that the "current" record being examined is to be merged; specifying "n", an integer number, indicates that the next "n" records are to be merged. As with the other commands discussed in this section, the NEXT option is assumed unless a different option is specified. The USING option may be specified as explained previously. [See D.2.4.1.]
The command also has two other options, the prefixes WITH FAST and WITH SEARCHONLY, which can be used by the file owner and by users with Master access to the file to speed up the processing. See the manual "SPIRES File Management", Part 6, for details about how these options work on the INPUT BATCH command, which is applicable to their use here; online, EXPLAIN WITH FAST PREFIX.
For example, suppose that all temporary employees in a personnel file are to be hired. All of their records could be updated with a "hire-date" element using the following commands:
-> select personnel
-> find status temporary
-Result: 4 EMPLOYEES
-> for result
+> collect clear
1. > hire-date = 10/15/76;
2. > *** <- ATTN key pressed
+> merge all
- MER Key = 120482-65
- MER Key = 130313-69
- MER Key = 186644-61
- MER Key = 192214-62
- Requests/Success:
MER 4 4
SUM 4 4
-End of merge input
+> endfor
-End of Global FOR
->
SPIRES displays the key of each record as it is updated (the lines marked MER for "merge"), and then summarizes the results of the command.
The SHOW KEYS command can be used in Global FOR mode to display the keys of the class of goal records being examined. Like the DISPLAY and REMOVE commands in Global FOR, the SHOW KEYS command can be used to process one, more than one, or all records with a single command.
The syntax for the command is:
SHOW KEYS [FIRST|*|NEXT|n|REST|LAST|ALL]
where "*" refers to the current record. If the "n" option is used, SPIRES will display the keys of the next "n" records. By default, the NEXT option is assumed if no other option is included in the command.
To obtain a list of the keys of the records in a search result, the following commands could be issued:
-> for result -> show keys all <--- Keys of all records in the search result are displayed +>
To put this same list in the active file, the IN ACTIVE prefix would be placed on the SHOW KEYS ALL command. [See A.2.9.1.]
The SHOW KEYS command can be used with any Global FOR commands. To put a list of all goal record keys in the active file, the following commands would be used:
-> for subfile +> in active clear show keys all +>
Note that the SHOW KEYS, STACK, UNQUEUE and DEQUEUE commands are the only commands that can be used to process removed records.
The existence of the deferred queue is a major difference between SPIRES and most data base management systems. In those other systems, record modification changes the record in the "tree" immediately and updates the indexes immediately as well. This method has the advantage of keeping the indexes current with the records; but it has some significant disadvantages too. Updating the indexes each time a record is updated, rather than doing it all at once after updating all the records you want to update, tends to be more expensive. In addition, you do not have the ability to reconsider a transaction; if you remove a record by mistake, it usually cannot be recovered.
On the other hand, SPIRES does not change the records in the tree or update the indexes immediately, but instead places the transactions into the deferred queue to await the processing of the file. The transactions thus have no immediate drastic effect; they can be unqueued or dequeued, as you have seen. [See D.4.2, D.4.3.] Moreover, saving the transactions so that the indexes are updated all at once when the file is processed rather than each time a goal record is updated is more economical. [Note though that SPIRES does allow a file owner to create "immediate indexes", which are updated immediately when a goal record is updated. Most subfiles do not have immediate indexing, however. [See D.6.3.]]
This chapter will discuss some of the effects of subfile modification, both before and after the file is processed.
When you add or update a record ("update" here includes "merge"), SPIRES puts the complete new version of the record into the deferred queue. When you remove a record, SPIRES puts the key of the record into the deferred queue, with an indicator that identifies it as a record to be removed.
For updated and removed records, the original version of each record still resides in the tree. But by default, when you ask SPIRES to display a record, SPIRES checks the deferred queue to look for the latest copy of the record. Hence, if the record has been removed, a "No such record" error message will be displayed, even though the record is still in the tree.
In most cases, it makes sense that you would want to see the latest copy of a record. Certainly, for example, if you issue the TRANSFER command, you want to get the latest version of the record to update, not the tree copy.
On the other hand, since the indexes are usually not updated immediately when a record is updated, there may be a discrepancy between the results of a search and the current contents of a record. The displayed records reflect the information in its most current form, but the records located during the search reflect only what the indexes "know" about the information as of the time the file was last processed.
For example, suppose a BLOOD DONORS record has an incorrect address, and several months later, the CITY element is corrected to PALO ALTO from PALE ALPO. The day the change is made, a search such as FIND CITY PALO ALTO will still not find the record. It would not be found by an index search until the file is processed. But that same day, the search FIND CITY PALE ALPO would retrieve the record, even though the record no longer has that value in it.
Similarly, for removed records, a search might produce a result that contains records that have been removed since the file was last processed. When a command such as TYPE is issued, SPIRES would check the deferred queue, discover that the desired record has been removed, and omit it from the display of the search result. In fact, SPIRES would then alter the count of records in the result. Suppose that, instead of updating that BLOOD DONORS record, you decided to remove it, and later that day someone issued the following commands:
-> find city pale alpo -Result: 1 DONOR -> type -Zero result ->
If you do not understand how the deferred queue works, such events can be disconcerting.
There are ways to tell SPIRES to ignore the deferred queue when handling search results or other situations in which you are not interested in the latest version of a record per se. In general, they involve the Global FOR command FOR TREE or the VIA TREE option. [See B.5.3.5, B.5.5.] For instance, if the user had typed VIA TREE TYPE instead of TYPE in the preceding example, the "Pale Alpo" record would have been displayed.
Note that the command SHOW SUBFILE SIZE does not reflect records added or removed since the file was last processed. [See B.2.4.]
When a SPIRES file is processed, basically two activities occur:
- 1) the data in the deferred queue is applied to the tree:
- added records are placed in the tree;
- updated records replace their old versions in the tree;
- removed records are removed from the tree; and
- 2) the index records are updated appropriately.
When this process is complete, the deferred queue is empty, ready to accept more record updates. At this point, the Global FOR classes TREE and SUBFILE are exactly the same, since no records exist in an updated state in the deferred queue. In addition, the indexes precisely reflect the contents of the records in the subfile.
The file owner, and others to whom the file owner gives special access, determines when the file is processed. The owners of most files choose to have SPIRES process the file overnight. [Note: Automatic overnight processing is not available at all sites running SPIRES. Check with your SPIRES consultant to determine for sure.] That means that every night, SPIRES checks the deferred queue of the file to see if it contains any update information. If it does, then SPIRES submits a batch job to process the file. If the deferred queue is empty, no job is submitted.
Processing the file overnight is recommended because it thus ends the day's updating activities. Rates are usually cheaper too. In addition, since few users are likely to have the subfile selected late at night, the actual processing is less likely to affect anyone. [A user who has a subfile selected while the file containing it is being processed may be inconvenienced in several ways. For example, a command that uses the subfile, such as FIND, would be suspended until the processing is completed, which is usually only a few seconds but can be much longer for a large file.]
The file owner can additionally or alternatively choose to process the file him- or herself. In any case, the file is processed in a program called SPIBILD (SPI for SPIRES and BILD for building a file). SPIBILD is introduced in the SPIRES Primer "A Guide to Data Base Development" and is discussed in detail in the reference manual "SPIRES File Management".
If you need or want to know whether there are many records in the deferred queue, you can use the Global FOR commands FOR ADDS, FOR UPDATES, FOR DEFQ and FOR REMOVES, along with the SHOW LEVELS command, to find out. [See D.7.] If there is a substantial number of records there, you might want to wait until the file is processed to do important searching, or else use Global FOR commands in your search.
In some subfiles, indexes can be defined to be updated immediately when a subfile transaction would affect them, so that those indexes always reflect the current state of the goal records. It is not necessary for every index in a subfile to be an "immediate" one; there might be only one index in the subfile that needs to be updated immediately because of critical searching needs. Whether an index is immediately updated or not does not affect the deferred queue and does not affect any updating procedures; it only affects the index records.
Record transactions (i.e., adds, updates, and removes) are still kept in the deferred queue until the next time the file is processed, so it is still possible to retrieve the tree version of a record [See B.5.5.] and to monitor subfile activity using Global FOR. [See D.7.] If a transaction has caused an index to be immediately updated, and that transaction is "undone" by either the UNQUEUE command or the DEQUEUE command, the index entry is also returned to its former state. [See D.4.2, D.4.3.]
A user responsible for file management or updating might want to obtain a record of all the file modification activity since the last time the deferred queue was processed. This might be done to produce a listing of all added or updated records, or perhaps to save the original copy of all updated or removed records, in case the changes or deletions are later discovered to be in error.
The ability to produce a list of transactions against a subfile, sometimes called an "audit trail", is provided by Global FOR processing. If necessary, you should review the basic summary of Global FOR processing found earlier in this manual. [See B.5.3.3, D.5.]
This chapter will discuss some Global FOR commands that give you access to various types of goal records (the added records, for instance) or different versions of a record (the tree copy vs. the deferred queue copy). Some additional capabilities are discussed in the manual "Sequential Record Processing in SPIRES: Global FOR". Capabilities discussed there include:
- the ability to see all versions of a record that have been in the deferred queue since the file was last processed, using the FOR TRANSACTIONS command;
- special techniques for creating complex WHERE clauses;
- the ability to process records based on the order in which they are indexed in a given index, using the FOR INDEX command;
- a command that shows you how many records have been processed so far during the current Global FOR processing, SHOW LEVELS.
In the sections that follow, note that SPIRES internally has only three types of update requests: adds, updates and removes. SPIRES determines which category a record is in by seeing whether a record with that key already exists in the tree. The category applicable to a given record does not necessarily correspond to the most recent commands issued for that record.
For example, if you add a new record and then update it, SPIRES considers the record to be an "add", and it will show up under the FOR ADDS command, not FOR UPDATES (discussed in this chapter). Similarly, if you remove a record and then add a new record with that key, internally SPIRES considers it an "update".
If you wish to look at all records added, updated or merged since the last time the file was processed, you should use the FOR DEFQ command. You will see the latest version of those records that have been modified.
The syntax of the command is:
FOR DEFQ [WHERE criteria-clause]
where the criteria-clause specifies which records in the deferred queue are to be selected. If no criteria are included, then all records in the deferred queue are selected. Note that removed records are not included under DEFQ processing, because the records being removed are not actually in the deferred queue; only their keys are there. [See D.7.4 for a discussion of the FOR REMOVES command.]
The commands necessary to produce a list in the active file of all deferred queue records are given in the following sequence:
-> for defq +> in active clear display all +>
If you want a listing of records added to the subfile since the last time the deferred queue was processed, you should use the FOR ADDS command.
The syntax of the command is:
FOR ADDS [WHERE criteria-clause]
where the criteria-clause specifies which added records in the deferred queue are to be selected. If no criteria are included, then all added records are selected.
The commands necessary to produce a list in the active file of all deferred queue records processed by the ADD command are given in the following sequence:
-> for adds +> in active clear display all +>
SPIRES determines whether a record in the deferred queue is an "add" by verifying that no record with that key exists in the tree. Hence a record added and then updated before the file is processed is considered an "add", not an "update" -- FOR ADDS will give you the latest copy of that record, even though it may have been created by an UPDATE command.
If you want a list of only the records processed with the UPDATE or MERGE commands since the last time the file was processed, such a list can be produced using the FOR UPDATES command. The list will contain the latest version of the records, not the version that existed before updating.
The syntax of the command is
FOR UPDATES [WHERE criteria-clause]
where the criteria-clause specifies which updated or merged records in the deferred queue are to be selected. If no criteria are included, then all records are selected.
The commands necessary to produce a list in the active file of all deferred queue records that are "updates" are given in the following sequence:
-> for updates +> in active clear display all +>
Remember that for Global FOR classes, SPIRES determines what class a deferred queue record belongs in by looking for a record with its key in the tree, not by the command issued to put it in the deferred queue. A record that has been removed and then added back to the subfile would appear under FOR UPDATES, not FOR ADDS nor FOR REMOVES -- the new version in the deferred queue will replace the old version in the tree, making it an update, as far as SPIRES is concerned.
If you need a list of the keys of the records removed since the last time the file was processed in SPIBILD, this list can easily be produced by using the FOR REMOVES command. Because each record has been removed, only its key is kept in the deferred queue. Thus, the contents of a removed record cannot be displayed directly, as added or updated records' contents can be with the FOR ADDS, FOR UPDATES and FOR DEFQ commands. But the next section describes how the contents of removed records can be displayed. [See D.7.5.]
The syntax of the command is
FOR REMOVES [WHERE criteria-clause]
where the criteria-clause specifies which removed records in the deferred queue are to be selected. The criteria-clause in this command can apply only to the key element and not to any other element, since only the key of a removed record is in the deferred queue to be examined. If no criteria are included, then all removed records are selected.
The commands necessary to produce a list in the active file of the keys of all records in the deferred queue processed by the REMOVE command are given in the following sequence:
-> for removes +> in active clear show keys all +> endfor -End of global FOR ->
Note that the SHOW KEYS ALL command is used instead of the DISPLAY ALL command shown in previous examples, since only the keys of the records are available to the system. The SHOW KEYS command can be used with all other Global FOR commands. [See D.3.5.] The SHOW KEYS, STACK, UNQUEUE and DEQUEUE commands are the only commands that can be used to process removed records.
Remember that SPIRES determines the Global FOR class of a record not by the command you issued to put it into the deferred queue but by checking to see whether a record with that key already exists in the tree. Hence, if you add a record and then immediately remove it, it will not show up in the records under FOR REMOVES. In fact, the only way to see such records is with the FOR TRANSACTIONS command. [See D.7.]
In many instances, it is not sufficient to have a list of all updated records, or a list of only the keys of all removed records. It may be very helpful to have the original contents of any updated or removed records, so that a particular record could be restored if errors are discovered later. This facility is available with the use of the STACK command in Global FOR mode.
The format of the STACK command in Global FOR mode (i.e, when there is a "+>" prompt) is:
STACK [FIRST|*|NEXT|n|LAST|REST|ALL]
where "*" can be used to indicate the current record. The next "n" records will be placed on the stack if the "n" option is used. If no other option is specified, the NEXT record will be stacked by default.
The resulting stack can then be processed by the TYPE and other SPIRES commands. [See B.5.4.1 for more details about the STACK command.]
You first build a stack of the records for which originals are desired, and then request the system to retrieve from the goal record tree the original of each record whose key is in the stack.
For example, if the original copies of all updated and removed records were to be placed in the active file for later archiving, the following commands should be issued:
-> for updates +> stack all -Stack: 7 RECORDS +> sequence ident-num -Stack: 7 RECORDS +> for removes +> stack all -Stack: 12 RECORDS +> for tree via stack +> in active clear display all +> endfor -End of global FOR -> clear stack ->
The FOR TREE VIA STACK command specifies that each record whose key is in the stack (here, all updates and removes) be looked up in the goal record tree. The IN ACTIVE CLEAR DISPLAY ALL command specifies that those original records in the tree be placed in the active file.
Note that the process of building a stack is cumulative: records are simply added on to any already in the stack, until a command is given that either replaces or clears the stack (such as CLEAR STACK, RESTORE STACK, CLEAR SELECT, or a FIND command). [See B.5.4.1.]
It is also possible to issue a SEQUENCE command any time before the records are displayed, in order to sort the records according to the value of certain elements. [See B.4.5.] Notice that removed records cannot be sequenced, so a stack such as the one above must be sequenced before removed records are placed on it.
The VIA option is occasionally useful, e.g. in the FOR TREE VIA STACK and FOR TREE VIA RESULT commands. It is discussed in greater detail in the manual "Sequential Record Processing in SPIRES: Global FOR".
Another alternative, once the stack is created, is to use the VIA prefix on the SEQUENCE and TYPE commands:
... -Stack: 12 RECORDS +> endfor -End of global FOR -> via tree sequence ident-num -Stack: 12 RECORDS -> in active clear via tree type ->
The VIA prefix was discussed earlier in this manual. [See B.5.5.]
Just as the TRANSFER, REMOVE, MERGE, and DISPLAY commands have their Global FOR counterparts, so does the DEQUEUE command. By using the DEQUEUE command in Global FOR mode, you can be more selective in choosing the class of record to be dequeued. For example, all removed records could be dequeued, or all added records could be dequeued, without affecting other kinds of updates in the deferred queue.
The syntax of the DEQUEUE command in Global FOR mode is:
DEQUEUE [FIRST|*|NEXT|n|REST|LAST|ALL]
where "*" can be used to specify the current record. The next "n" records will be dequeued if you use the "n" option. The NEXT option is assumed by default if no option is included in the command.
For example, suppose you wanted to dequeue all updates, but not disturb any adds or removes:
-> for updates +> dequeue all -Dequeued: 5 records +>
(Note the informational message telling you how many records have been dequeued. This message appears only when you issue the DEQUEUE command in Global FOR mode.) If, on the other hand, all adds and removes were to be dequeued, the commands would look like this:
-> for adds +> dequeue all -Dequeued: 17 records +> for removes +> dequeue all -Dequeued: 13 records +>
Suppose the records added to a subfile were to be examined, and, on the basis of the value of an element called "hire-date", were to be dequeued. This processing could be done with the following commands:
-> for adds +> set element hire-date +> display 4 <--- The "hire-date" in the first four adds is displayed +> dequeue * <--- The last record displayed is dequeued -Dequeued: 1 record +> display <--- The next (fifth) added record's "hire-date" is displayed +> dequeue * <--- The current (fifth) record is dequeued -Dequeued: 1 record +> dequeue 5 <--- The next 5 (sixth-tenth) records are dequeued -Dequeued: 5 records +>
The UNQUEUE command works in Global FOR similarly to the way it works outside of Global FOR. Instead of completely removing the record from the deferred queue as the DEQUEUE command does, the UNQUEUE command removes only the most recently issued transaction request against a record. [See D.4.2.]
The syntax of the UNQUEUE command in Global FOR mode is:
UNQUEUE [FIRST|*|NEXT|n|REST|LAST|ALL]
where "*" can be used to specify the current record. The next "n" records will be unqueued if you use the "n" option. The NEXT option is assumed by default if no option is included in the command.
For example, you could issue the UNQUEUE command for all removed records to cancel the request to remove the records, but any other transactions made against those records prior to the remove request that were still in the deferred queue would still take place. The following sequence of commands illustrates this:
-> for removes +> unqueue all -Unqueued: 5 records +>
The informational message tells you how many records have been unqueued. This message appears only when you issue the UNQUEUE command in Global FOR mode.
Batch subfile modification lets you add or update large numbers of records with a single command (or a small set of commands) instead of having to update the records one by one. Multiple-record updating techniques save you considerable time. They can also offer significant cost advantages over the single-record method described in previous chapters. Adding or updating records in a batch is particularly useful when the new records are already in machine-readable form.
There are five techniques for batching updates into a SPIRES file:
- You can assemble the data in your active file in standard SPIRES format and then issue the INPUT BATCH command in SPIRES. [See D.8.1.]
- You can assemble the data in your active file in a form that can be read by an input format and then issue one of these commands: INPUT ADD, INPUT ADDUPDATE, INPUT MERGE, or INPUT ADDMERGE. The command you choose depends on what sort of record updates are included in your active file. [See D.8.2.]
- You can use the SPIBILD program for batching updates, as described in the "SPIRES File Management" manual.
- You can assemble the data in a WYLBUR data set in standard SPIRES format and use the BATCH command to issue a batch update request. This request will take effect when the file is processed overnight. [See D.8.3.]
- You can assemble the data in a WYLBUR data set and use the BATSPI program to perform the batch update request. [See E.3.3.]
Which batch updating method is best in a given situation? Here is a brief comparison of the methods:
- INPUT BATCH (and the other INPUT commands) in SPIRES send record modifications to a file's deferred queue. Therefore, the file is still available to other users while the batch input takes place. (The data is written to the tree later during SPIBILD processing.) For this reason, one of these commands may be the preferred method for batch input during working hours, or whenever a file is likely to be shared by several users.
- Batch updating in SPIBILD, on the other hand, processes the file directly, writing data to the tree as well as the deferred queue. The file is usually unavailable for other updating during SPIBILD processing, which you would probably perform late at night when no one else is using the file.
- Since the INPUT commands in SPIRES cause the data to be sent to the deferred queue and only later (via SPIBILD) to the tree, this method usually uses more total computing resources than the SPIBILD batch updating methods.
Thus each method has different advantages, depending on the situation. SPIBILD is usually cheaper for the file owner, but the INPUT commands in SPIRES leave the file accessible to other users during the updating process, and leave added records in the deferred queue. Note also that the INPUT commands let you use the deferred queue for auditing daily updates.
The following sections discuss INPUT BATCH and the other INPUT commands in greater detail.
The final section of this chapter discusses the BATCH command in SPIRES, which is an alternate method (usually less desirable) of batching records into SPIRES overnight. [See D.8.3.] The main advantage of the BATCH command in SPIRES is that the file owner is charged for the batched transactions. With the other methods, costs are charged to the person who requests the batched transactions.
The INPUT BATCH command handles multiple-record ("batch") updating in SPIRES, using data in standard SPIRES format. INPUT BATCH can process requests for adds, updates, merges, and removes.
To use INPUT BATCH, assemble in your active file the data to be input (following the conventions described in the next paragraphs). Select the subfile into which the data will be batched and set an exception file for transactions that fail, if you wish. [See D.8.1.1.] Then issue the INPUT BATCH command:
[WITH FAST|WITH SEARCHONLY] INPUT BATCH [USING line-range]
You may append the USING option to the INPUT BATCH command to direct SPIRES to a certain range of lines in your active file. [See D.2.4.1.]
The WITH FAST and WITH SEARCHONLY prefixes will speed up the processing, though you must accept some restrictions. Those two options are available only to the file owner and to users who have Master access to the file containing the subfile. See the manual "SPIRES File Management", Part 6, for details about how the INPUT BATCH command works with these options; online, EXPLAIN INPUT BATCH COMMAND, IN FILE MANAGEMENT.
There is also a "FROM ddname" prefix available for naming the input DD-card for a batch SPIRES or batch SPIBILD job. See the same section in "SPIRES File Management" mentioned above for details.
The rules for arranging data in standard SPIRES input format apply to the INPUT BATCH command. [See D.2.2, D.2.3.] In addition, each individual record in your active file (or portion of a record, in the case of merge requests) must be preceded by the command to be executed, followed by a semicolon to set the command off from the individual records. An extra semicolon must follow the record.
Six different kinds of transactions -- ADD, MERGE, UPDATE, ADDUPD, ADDMERGE, REMOVE -- may be interspersed in any order in the active file. Records need not be in any special sequence. [Note: the DEQUEUE and UNQUEUE commands are not allowed in this format.] In the case of UPDATE, MERGE, and REMOVE, the record-key-value must be supplied as part of the command. When REMOVE is specified, no extra semicolon is used, since there is no record input to delimit.
The following example illustrates the format of data for INPUT BATCH:
ADD; ID = 11111; NAME = John Smith; PHONE = 969-2276; ; UPDATE 12345; ID = 12345; NAME = Sam Brown; PHONE = 672-3329; ; REMOVE 67890; ADDMERGE; ID = 22222; NAME = Bill Jones; PHONE = 732-2796; ; MERGE 54321; PHONE = 555-1212; ; ADDUPD; ID = 23456; NAME = Topo Gigio; PHONE = 466-6873; ; (etc.)
Each individual record in the input data set must be followed by a semicolon to indicate to SPIRES the end of the record. Although the example shows the command, each element, and the extra semicolon on separate lines for readability, you may place those items on a single line if you wish. Just be sure to leave an intervening blank between a semicolon and the next piece of data. For example, this is acceptable:
ADD; ID = 11111; NAME = John Smith; PHONE = 969-2276; ; UPDATE 12345; ID = 12345; NAME = Sam Brown; PHONE = 672-3329; ; REMOVE 67890; (etc.)
Note that the "extra" semicolon must not occur after a REMOVE command since there is no listing of an individual record. If the extra semicolon did occur after a REMOVE command, SPIRES would reject the remainder of the batch input.
Before batching in a large number of records with the INPUT BATCH command (or with the other INPUT commands) [See D.8.2.] you may want to issue the SET EXCEPTION command to prepare a Unix "exception" file. During batch inputting, any records that are rejected are automatically sent to this exception file, where you can examine and correct them without having to go through the entire original data set.
The syntax of the SET EXCEPTION command is as follows:
SET EXCEPTION Unix-file-name [REPLACE]
To bring the exception file into your active file, use the GET command followed by the name of the Unix file. See the "SPIRES File Definition" manual or EXPLAIN SET EXCEPTION.
Here is a sample session using the INPUT BATCH command:
-> select paperbacks -> set exception badstuff replace <-- (optional) -> use newbooks clear -> input batch
As the command is processed, it is followed by a tally of update requests and successes, like the one shown in part below. The person preparing the input data set apparently misspelled the element AUTHOR as AUTHER, causing an error:
- ADD @Line 40. Key = 10
(etc.)
- ADD @Line 819. Key = 80
-Unknown mnemonic: AUTHER
-Error at or before line 822.
-Update terminated, code=S2
-*ADD @Line 823. Key = 87 Err = S2
- ADD @Line 828. Key = 91
(etc.)
In this case, the incorrect data between lines 819 and 823 would be placed in the exception file named in the SET EXCEPTION command. You can then correct the data in the exception file and input it a second time.
Four commands are available for doing batch subfile modifications in conjunction with a SPIRES input format:
INPUT ADD [USING line-range] INPUT MERGE [USING line-range] INPUT ADDUPDATE [USING line-range] INPUT ADDMERGE [USING line-range]
The command you choose depends on the type of update transaction in your input data set. [See D.2.4, D.2.6, D.2.7, D.2.7a for explanations of ADD, MERGE, ADDUPDATE, and ADDMERGE.] As indicated above, you may append the USING option to any of the INPUT commands to direct SPIRES to a certain range of lines in your active file. [See D.2.4.1.]
You cannot use these commands with the SPIRES standard input format described in the previous section. Use the INPUT BATCH command if your data is in SPIRES standard format. [See D.8.1.] [If you use the INPUT BATCH command when an input format is set, it is the equivalent of INPUT ADD. That is, only add requests are processed.]
To use one of these INPUT commands, first assemble the data to be added, updated, or merged in your active file, in the arrangement called for by the input format you'll be using. Then select the subfile in which the modifications will be made. If you wish, set an exception file for any update transactions that may fail. [See D.8.1.1.] Then set the appropriate format, and issue one of the INPUT commands. (See "SPIRES Formats" for more information on multiple-record input formats.)
Note: All four of these INPUT commands (as well as INPUT BATCH) are available through the BATSPI program. [See E.3.3.]
As an alternative to batching records into the data base interactively with SPIRES or SPIBILD, you can submit a batch request to take effect at a later time, e.g., at night when the rates are down. One way to do this is to use the BATCH command in SPIRES to submit a deferred batch request to take effect as part of overnight processing of the file. Another method, using the BATSPI program, is explained in an upcoming section. [See E.3.3.]
To use the BATCH command, first prepare a data set containing the records to be batched, in the standard SPIRES batch format described in D.8.1. The SELECT the subfile to contain the records, and issue the BATCH command:
BATCH data-set-name ON {volume|CAT} [TIME=n] [LINES=n]
or, for data sets on tape:
BATCH data-set-name ON {volume|CAT} [TIME=n] [LINES=n] ...
... {TAPE|TAPE7|TAPE9} = description
The data set name must be in the form "WYL.gg.uuu.dsname" unless it is a data set on tape. (See examples below.) You must specify that the data set is cataloged (by using the ON CAT option) or give the name of the volume on which it resides. If no explicit values are given for TIME (CPU) and/or LINES, default values of 5 minutes of CPU time and 1000 lines of output will be used. The run will be aborted if these estimates are exceeded.
The TAPE option is used only if the input data set resides on magnetic tape. "TAPE" and "TAPE9" may be used interchangeably to mean nine-track tape. "TAPE7" must be used for seven-track tape input. (Note that seven-track tapes are not available at Stanford.) The internal volume and data set header labels for the tape must conform to IBM standard tape-labeling conventions. If you use a tape, "volume" is the VOLSER or internal name of the tape. "Description" is the tape's external name (which is usually the same as the internal name). Even if they are the same, "volume" and "description" must both be provided.
When the system accepts the job, it prints out the relevant information and asks you to verify it. Once this information is verified, SPIRES enters the job and informs you of the batch request number, as in the example below:
-> select thaunts -> batch wyl.gq.jpr.batch on int001 -Verify: Account = GQ.JPR Subfile = THAUNTS Data set = WYL.GQ.JPR.BATCH Volume = INT001 Unit = DISK 1000 lines, 5 minutes OK? ok -Added batch request: 8212 ->
After your batch request is verified, the job's information is sent to the deferred queue, where it may be found via the SHOW BATCH REQUESTS command:
-> show batch requests -Batch request: 8212 Account = GQ.JPR Subfile = THAUNTS Data set = GQ.JPR.BATCH Volume = INT001 Unit = DISK 1000 lines, 5 minutes ->
The batch request can be dequeued with the DEQUEUE BATCH REQUEST (batch-request-number) command, e.g., DEQUEUE BATCH REQUEST 8212.
1) If you do not have update access to the subfile, you will not be able to submit a job with the BATCH command. Also, if the subfile has NO JOBGEN set, the BATCH command will not be accepted. In both cases, you will receive the error message "-Batch not allowed."
2) Warning: If the file owner processes the file in SPIBILD before overnight processing takes place, the batch requests are ignored. Make certain that the file owner knows you have submitted batch updates so that he or she does not process the file and lose the requests accidentally. Do not scratch the data being batched until you have verified that it was actually put into the subfile.
When a batch run is processed in the overnight processor, documentation of the run is produced and delivered to the file owner's bin (not to the bin of the person submitting the job). This output contains system messages and, if there were errors, error codes that you can investigate, using the EXPLAIN command online. [See D.2.8.]
For the following batch input to an author-title subfile, assume that the author element, "A", is the key:
ADD;
A = JOHN SMITH;
T = INTRODUCTION TO STATISTICS;
;
ADD;
A = JOSEPH BROWN;
T = NON-EUCLIDEAN GEOMETRY;
;
UPDATE "JAMES ALLEN";
A = JAMES ALLEN;
T = COMPLEX VARIABLES;
;
ADD;
Q = CHARLES LOWE; <--- this line contains the error
T = INTEGRAL CALCULUS;
;
The output produced from this run might look in part like this:
ADD 1, 1 @Line 4. Key = JOHN SMITH
ADD 2, 2 @Line 8. Key = JOSEPH BROWN
UPD 3, 3 @Line 12. Key = JAMES ALLEN
-Unrecognized: Q = CHARLES LOWE
Error while processing ELEM=A
-Update terminated, code=S419
-Error at or before line 16.
*ADD 4, 3 @Line 16.
-Passing: 3 records of record-type REC01
- Requests/Success:
ADD 3 2
UPD 1 1
SUM 4 3
-End of BATCH/BUILD
-Compute time: 0.721 seconds
-Elapsed time: 3.430 seconds
-Core usage: 0241/0963
The first line of output tells the following: the first request was for an ADD operation; it was the first (1) request made, and it was the first (1) request to succeed; the semicolon delimiter for the record occurred at line 4. The two columns of numbers, "1, 1" in the first line, are therefore a running total of transactions and a running total of successful transactions, respectively.
Error messages generally begin with a '-', and the summary for the erroneous record begins with a "*". Statistics of the number of requests and successes are provided: a summary (SUM) of all, and a detail for ADD, UPDATE, MERGE, and REMOVE transactions.
Most individual adds or updates of records in SPIRES are "self-sufficient", in the sense that the success or failure of one transaction request has nothing to do with whether other transaction requests should succeed or not. (A transaction request is the issuing of an ADD, UPDATE, MERGE, REMOVE, DEQUEUE, or UNQUEUE command.) For instance, if you try to update an address file with two separate added records, one for "James Joyce" and one for "Virginia Woolf", you probably want the added record for Joyce to go into the data base, even if the add request for the Woolf record is rejected. The data for Joyce is independent of the data for Woolf, so the transactions are also independent.
But in some complex applications, multiple transactions may make up a single entity or "transaction group", where the success of one transaction is closely bound up with the success of the others. In that case, you would want to make sure the transactions are "all or nothing": no single transaction should enter the data base unless all the other transactions in the group are also entered. For example, if whenever you add an address to your file you also update a second file with a running count of addresses, you would want transactions in the two files to be closely correlated. Otherwise, if the system becomes disconnected before the second transaction takes place, information in the two files will no longer be synchronized.
Transaction group processing in SPIRES lets you group SPIRES transactions to guarantee this "all or nothing" process. (The records involved in a transaction group need not all be part of the same file.) The rest of this chapter will show how to use transaction group processing to bracket multiple-record updates. Specifically:
- Section D.9.1 will describe the commands needed to open and close a transaction group;
- Section D.9.2 will discuss some of the restrictions imposed on transaction group processing;
- Section D.9.3 will briefly discuss the mechanisms that SPIRES uses to guarantee the integrity of grouped transaction requests and will also show how to "lock" records for exclusive use within a group;
- Section D.9.4 will briefly discuss further considerations for file owners.
One restriction should be mentioned at the beginning. A subfile to be used in transaction group processing must have a private checkpoint file defined for it by the file's owner. [See Section B.10.9 in the "SPIRES File Definition" manual.] In fact, most transaction group processing will probably be performed either by the file owner or by a small subset of users taking advantage of a protocol written by the file owner.
One more introductory remark: you will probably need to be fairly familiar with the SPIRES protocols language as well as path processing in order to take full advantage of transaction groups. [See the "SPIRES Protocols" and "SPIRES Technical Notes" manuals for more information on these topics.]
Two commands define the beginning and ending of a transaction group:
OPEN TRANSACTION GROUP [gg.uuu.key]
CLOSE TRANSACTION GROUP {COMMIT|DECOMMIT|SAVE gg.uuu.key [TIME n]}
The "key", SAVE and TIME options are discussed at the end of this section.
The OPEN TRANSACTION GROUP command is issued after the primary subfile has been selected [See D.9.2.] but before any transactions in the group have taken place. The CLOSE TRANSACTION GROUP command is issued after all the transaction requests making up the group have been issued. (Thus all the transaction requests you issue between the OPEN and CLOSE commands make up a single group.)
In addition to announcing the completion of the group, the CLOSE TRANSACTION GROUP command declares through the COMMIT|DECOMMIT option whether the transactions as a group should be entered into the data base or not. The COMMIT option on CLOSE TRANSACTION GROUP signals that the modifications as a group should go through; the DECOMMIT option signals that the modifications as a group should be thrown away. (Either COMMIT or DECOMMIT is required as part of every CLOSE TRANSACTION GROUP command.)
If the system should become disconnected for any reason while transaction processing is in effect -- or if for any reason your primary file should become de-selected -- SPIRES will interpret this as an implicit CLOSE TRANSACTION GROUP DECOMMIT. In other words, in those situations your transactions will be decommitted or discarded automatically.
Transaction group processing still requires you to determine the success of individual transaction requests. For instance, if you request three transactions, one of which fails, your transaction group will still be committed if you use the COMMIT option. Thus you should test for the success or failure of each individual transaction (for instance, with the $NO variable in a protocol) before you commit the group into the data base. [See the "SPIRES Protocols" manual.]
Below is a brief annotated example of transaction group processing, shown as a simulated online session (rather than through a protocol), so that you can see the system's responses:
COMMANDS ISSUED COMMENTS
________________________________ ______________________________
> select articles
> thru journal select journals
-Path 1: JOURNALS
> open transaction group <---(Transaction group opened
for records in ARTICLES
and JOURNALS subfiles)
> transfer 234 <---(Record 234 in ARTICLES
transferred into the active
.... file and modified)
> update <---(this UPDATE will not take
effect until the group is
CLOSEd and COMMITted)
> thru journal transfer 56 <---(Another record is modified,
this time through a path)
....
> thru journal update <---(Likewise this UPDATE is still
provisional until a CLOSE
TRANSACTION GROUP COMMIT)
> close transaction group commit <---(At this point the UPDATEs
enter the DEFQ trees for each
file, and can be seen by other
users of either subfile)
Note that if another user displays record 234 above before the transaction group is closed, that user will see the version of the record preceding the update, while the user who opened the transaction group would see the latest updated version. [See D.9.3.]
In some circumstances, such as transactions in the client-server environment, a transaction group may need to exist in its uncommitted state longer than simply the duration of the current terminal session. For example, in a typical client-server transaction using a web browser program, the user may be prompted to enter data for a record on one page, which is then sent to the server (and eventually to SPIRES). The server session connects to SPIRES, and uses the data to create a record or records in SPIRES files, sends back a confirmation message, and ends the session. But suppose on the next page, the user needs to confirm that the entered data is correct or else should be discarded. On the server side, the transaction has already been completed.
So to make this kind of "stateless" situation work, SPIRES allows you to close a transaction group, leaving it uncommitted, for a limited amount of time determined by you:
CLOSE TRANSACTION GROUP gg.uuu.key [SAVE n]
The "gg.uuu.key" is a string of up to about 200 characters, which must begin with your account number. With the account prefix, it must also be unique among existing transaction groups.
By default, SPIRES will retain the saved transaction group for 30 minutes in its decommitted state; you may set the time to the number of minutes you want. Remember though that the records in the transaction group are essentially "locked" so that other users cannot update them till the transaction group is committed and closed.
You specify the length of time you want SPIRES to save the uncommitted group with the SAVE option, where "n" is the amount in minutes. So if you want the uncommitted transaction group to be stored no longer than an hour, you would include the "SAVE 60" option on the CLOSE TRANSACTION GROUP command. If an hour passes without the transaction group being opened again (see below), the transaction group is discarded.
To re-open the saved and uncommitted transaction group, you must re-select the primary subfile and then issue the OPEN TRANSACTION GROUP command with the "key" option:
OPEN TRANSACTION GROUP gg.uuu.key
where "gg.uuu.key" is the same key used in the CLOSE TRANSACTION GROUP command that caused it to be saved. Note that you must be on the same account that saved the group in order to re-open it.
The SAVE option lets you save transaction group activity at any particular point, then go into some other process that may have nothing to do with the saved transactions, and then return later, possibly in another session, and continue with the saved transaction group.
An important caveat: if the file is processed while a transaction group is saved, all the transaction data will be discarded.
You can get information about either the current open transaction group or any saved transaction groups for the currently selected subfile with the SHOW TRANSACTION GROUPS command:
SHOW TRANSACTION GROUPS [KEYS] [ALL|LIKE key-prefix]
If you issue the command without options, SPIRES provides information about the currently open transaction group, if any.
-> show transaction group
Information for OPENed Transaction Group
File-Name: ORV.GQ.JNK.SPIRES.SUBS
Record-Type: 1 UPD Key: 'SYBASE'
If you use the ALL or LIKE option, SPIRES will give you similar plus additional information (including time-stamp data) about saved transaction groups, either specific ones whose saved names begin with the key prefix (remember to take account of the account number prefix) or ALL of the saved transaction groups. You are limited to seeing only those transaction groups saved under your own account unless you have See (or higher) access to the file, in which case you are shown all saved transaction groups belonging to anyone.
The KEYS option, useful when you specify the ALL or LIKE option, simply shows the name of any saved transaction groups.
Similar commands are available when you want to discard saved transaction groups. Remember, you can discard only transaction groups saved under your own account unless you have Master access to the file.
CLEAR TRANSACTION GROUPS {gg.uuu.key|LIKE key-prefix|ALL]
If you specify a saved transaction group by its key, that single group will be discarded. The other two options will discard the groups whose names begin with the specified key prefix or all groups, if any.
The CLEAR TRANSACTION GROUPS command cannot be used to clear the current transaction group. Instead, you must use the CLOSE TRANSACTION GROUP DECOMMIT command, described above.
These are some of the restrictions and/or limits to transaction group processing:
- an OPEN TRANSACTION GROUP command can only be issued after a subfile is selected; the records to be grouped must be either in this primary subfile or in another subfile (or other subfiles) selected through a path;
- A single transaction group can update records in a maximum of eight files. (Since a file may contain more than one subfile, the maximum number of subfiles per transaction group is higher.);
- a maximum of 200 transactions can be processed within a single group;
- you can have only one transaction group open at a time;
- you must have exclusive access to a record before you can update it through a transaction group. [See D.9.3 for obtaining exclusive access to a record.]
Also remember that, as mentioned previously, a subfile used in transaction group processing must have a private checkpoint file defined for it by the file owner.
After issuing the OPEN TRANSACTION GROUP command, you can still clear the select of your primary subfile as long as no transactions have been requested for the file; but after the first transaction, you must issue a CLOSE TRANSACTION GROUP command before de-selecting the file. Likewise, you can clear any path until transaction requests have been issued through the path; but after that point you must close the transaction group before you can clear the path. [You may, if you wish, select a subfile through a path after opening a transaction group; transactions requested through this path will become part of the group.]
To take full advantage of transaction group processing, it helps to know how SPIRES handles these transaction requests internally. This section will discuss SPIRES internals, then will introduce two commands that help ensure you have access to the records you plan to update as a group.
SPIRES handles grouped transactions in a special way. Instead of completely processing the transaction request, SPIRES stores the transaction in the file's DEFQ (as usual), but does not upgrade the DEFQ tree on disk to point to the new record. (This explains why another user who displays the record before its transaction group is closed sees the previous version of the record instead of the updated version.)
Instead of updating the DEFQ tree of a record on disk, SPIRES does three things with a record updated within an open group:
- 1) It maintains a description of the transaction in main memory. (This description contains all the old and new DEFQ tree node values and also records the name of the file to which the transaction will eventually be applied.)
- 2) It updates the DEFQ tree copy being held in main memory, so that the record's current user (the person who opened the group) can look at the updates and revise them if necessary.
- 3) It locks the record so that other users cannot transfer or update it.
The CLOSE TRANSACTION GROUP command (with the COMMIT option) causes SPIRES to finish processing the transactions and write each of them into the DEFQ tree on disk. Specifically, after the CLOSE command has been issued, SPIRES temporarily reserves for its exclusive use the private checkpoint data set for each of the files involved in the transaction group. Once these data sets have been reserved, SPIRES acts on each of the transactions in turn, and then unlocks the records. Finally it releases the checkpoint files involved.
Only after a group is closed do all users access the same updated version of a record. (And note also that immediate indexing of transactions in a group only takes place when the group is closed -- not when the transactions are first entered by the user.) Because the transactions in a group are not actually written into the DEFQ tree until the CLOSE TRANSACTION GROUP command is issued, the ZAP DEFQ command is not allowed while a transaction group is open.
An optional note on efficiency considerations: grouped transactions may require as much as twice the number of I/O's to the DEFQ as ungrouped transactions would require, but they will probably cause only a small increment to CPU time. (Elapsed time may vary depending on the number of concurrent groups for a file and the number of records within each group.) For updates outside a transaction group, CPU time and number of I/O's will not be affected by the existence of concurrent transaction groups, but non-grouped updates may take more elapsed time if the file being updated is heavily reserved. The efficiency of searching and reporting should not be affected by the existence of concurrent transaction groups.
Because records in a transaction group must be locked by SPIRES before they can be updated, multiple users attempting updates of a single file can run into a "gridlock" situation. That is, you might find yourself in the middle of a transaction group, and be unable to update one of the records in it, because some other user has included the same record in his or her transaction group.
To prevent this from happening, you can lock a record in advance of the time that you update it by issuing the SET RECORD LOCK command after opening the group.
The form of the command is as follows:
[THRU path] SET RECORD LOCK key-value
For "key-value" you would substitute the value of the key of the record that you wish to lock in its external form.
The lock is automatically removed when the group is closed; or if you have not modified the record, you can issue the CLEAR RECORD LOCK command to clear the lock.
The form of the command is as follows:
[THRU path] CLEAR RECORD LOCK key-value
SPIRES will ensure that record locks are held only by users who are logged on. In addition, multiple users of a single file need to be careful to release locks when they are not needed.
You may use SET RECORD LOCK to lock the next slot key for subfiles with slot keys. If the slot key is augmented by a check-digit that is generated when the record is added, you can use the $NEXTSLOTKEY variable in the SET RECORD LOCK command to lock the record appropriately, like this:
-> /set record lock $nextslotkey ->
At this point, the value of the system variable $KEY has the normal key value for the record.
You may also use SET RECORD LOCK to lock a record with an augmented key. SPIRES will figure the appropriate augmentation for the next record with that key, lock that key value, and assign that key value to the system variable $KEY.
In addition to material contained in this chapter, file owners who plan to take advantage of transaction group processing will probably want to consult the "SPIRES File Definition" manual about these additional topics:
- the $TRANINFO function, which can return information about the status of a transaction group. [See the "SPIRES Protocols manual" or EXPLAIN $TRANINFO FUNCTION.]
- the SHOW SUBFILE TRANSACTIONS command, which provides the file owner with a display of all transactions performed on the file, including transaction group processing, and also tells whether a transaction group was committed or decommitted. [See B.10.7a of the "File Definition" manual or EXPLAIN SHOW SUBFILE TRANSACTIONS COMMAND];
- the $TRANSACTIONS record-type, which helps the file owner keep track of all transactions performed on his or her file. [See C.14.1 and C.14.2 of the "File Definition" manual or EXPLAIN $TRANSACTIONS RECORD-TYPE];
- the coding of a private checkpoint file, which is a prerequisite for transaction group processing. [See B.10.9 of the "File Definition" manual or EXPLAIN CHECKPOINT RECOVERY].
File owners will probably also want to consult Chapter 14 of the "SPIRES Technical Notes" manual, which covers path processing in detail, before preparing a file for transaction group processing.
Experienced SPIRES users often find themselves repeatedly issuing the same sequence of commands. They often collect the SPIRES commands in WYLBUR, add them to a special SPIRES subfile, and subsequently invoke them for execution.
Prestored sets of SPIRES commands are called "protocols". A detailed explanation of the protocol capability is not presented here. If you wish to write your own protocols, you should study the document "SPIRES Protocols."
Protocols are stored in SPIRES subfiles structured especially for that purpose. In order to gain access to protocols stored in a protocol subfile, you must select the protocol subfile, and then inform the system that any protocols to be executed can be found in that subfile.
The SET XEQ command establishes a subfile as your protocol subfile. Once the SET XEQ command has been issued, you may freely select other subfiles for searching, updating, etc. Any protocols invoked will be taken from the designated protocol subfile without disturbing the currently selected subfile. The protocol subfile is termed the XEQ subfile.
You can specify an XEQ subfile without selecting it first, by using the SET XEQ command with this syntax:
SET XEQ [subfile-name]
If no subfile name is given, then the currently selected subfile becomes the XEQ subfile; otherwise, the named subfile does.
A typical sequence for designating a protocol subfile is:
-> set xeq public protocols
More information on protocols can be found in "SPIRES Protocols".
You may also issue the SHOW XEQ command to see what protocol subfile has XEQ set. 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.]
To "unset" an XEQ subfile, issue the SET NOXEQ command.
The XEQ FROM command executes the specified protocol from a previously designated XEQ subfile.
The form of this command is:
XEQ FROM protocol-name
where protocol-name is the key of a protocol record in the XEQ subfile. A shorthand form of the XEQ FROM command is
..protocol-name
The following example portrays a complete sequence -- protocol subfile designation, followed by a request for protocol execution:
-> set xeq public protocols -> xeq from pager <--- The protocol executes
Users who find themselves issuing the same series of SPIRES commands at the beginning of a SPIRES session in order to select certain files and set certain system parameters might want to place these commands in the ENTRY COMMANDS subfile. Whenever you issue the SPIRES command, the commands that you have stored in the system's ENTRY COMMANDS subfile are executed before the first SPIRES command prompt is returned to you.
Any user can add a record for his or her account to this subfile. SPIRES, WYLBUR, and Unix commands can be entered. The key of the record that contains these commands as elements is your account number; using this key a record made up of entry commands can later be updated or removed just like a record in any SPIRES subfile.
Here is a sample session of a user (account number D5.M07) adding some frequently issued commands to the ENTRY COMMANDS subfile. Note that the first line of the record must be the user's account number prefixed by a "*<blank>" beginning in column one.
-> collect clear
1. > * d5.m07
2. > ! set nolist
3. > set xeq public protocols
4. > select marc
5. > show subfile size
6. > <--- ATTN/BREAK pressed
-> select entry commands
-> add
->
Note that a "!" may be placed before any individual command. This will prevent SPIRES from "echoing" (printing at the terminal) a particular command as it is executed.
SPIRES commands can be executed as a batch program, in one of three ways:
- through the batch SPIRES program, described in this chapter;
- through the BATWYL facility (the single most commonly-used method today);
- through the BATSPI program, described briefly at the end of this chapter.
In general, the advantage of batching commands, using any of these methods, is that you do not need to sit at a terminal while a long and involved series of SPIRES commands is executing, assuming you can formulate the series of commands ahead of time. Also, you can submit a batch job to run during the night or weekend when rates are cheapest, and you do not have to be physically present to take advantage of these rates. BATWYL in particular is often used for large-scale reporting needs. For a full description of the BATWYL facility, see the document "Using BATWYL".
Which of these three facilities should you use? In most cases, BATWYL is more efficient than the batch SPIRES program, can include WYLBUR commands, and can handle commands requiring input from the terminal or active file. Perhaps BATWYL's only limitation in comparison to batch SPIRES is the smaller maximum size of its active file. (But at 20 megabytes -- about 500,000 average-sized lines -- BATWYL's active file should be large enough for most uses.)
In contrast, the batch SPIRES program has an unlimited active file, but cannot handle WYLBUR commands, as BATWYL can. Also, in batch SPIRES any commands that require input from the terminal (such as "-More?" in response to a BROWSE) or from the active file (such as UPDATE or ADD) will receive an attention (ATTN) response.
The third alternative, the BATSPI program, is similar to BATWYL, except that it automatically places you in SPIRES, which might offer a slight efficiency gain in some situations. [See E.3.3.]
There are three commands that can only be issued in batch SPIRES. They are: PAGE, SET NOCC, and SET CONDITION=n.
The PAGE command can be inserted anywhere in the command list to cause a page eject in the output.
The SET NOCC command suppresses the output of carriage control characters to the SYSWDS data set; it would normally be used when SYSWDS has RECFM=FB rather than FBA. It should be included at the beginning of the command stream, or at least before any output is sent to the data set.
This command lets you set a condition code from within SPIRES that can be detected by JES. The syntax is:
SET CONDITION = n
where "n" is any integer value. If you issue more than one SET CONDITION command, the last one issued before the program terminates is the one used by JES.
To use batch SPIRES, simply collect a valid set of SPIRES commands in the active file and issue the OFFLINE command. This command has options that allow you to specify such things as number of copies of output. The batch job that is created will be submitted overnight, when CPU costs are lower.
The basic command form is:
OFFLINE jobname [options]
where "jobname" must be a valid WYLBUR jobname; the options are the following:
BIN bin-number TIME CPU-time-limit-in-minutes LINES line-limit-in-thousands COPIES number-of-copies-of-output-desired NOEJECT <---Specifies no auto-eject in output SAVE <---See E.3.1.1 for explanation
If BIN is not specified, output will be directed to the default bin specified by your SET OUTPUT command in WYLBUR. Default values are assumed for TIME, LINES, and COPIES if they are not given. The defaults are: TIME=5 (minutes of CPU), LINES=1 (thousands of lines), COPIES=1.
When the OFFLINE command is issued, you should have the OFFLINE subfile selected or no subfile selected. The active file must contain the commands that are to be executed offline.
SPIRES will save the contents of the active file and the OFFLINE command options as a record in the OFFLINE subfile with a key which is:
gg.uuu.jobname
where "gg.uuu" is your account number and "jobname" is the name given to the job when the OFFLINE command is issued.
You can see what jobs are in the OFFLINE subfile for your account using the following commands:
-> select offline -> for adds +> display all +> endfor
You can remove a job from the OFFLINE subfile using the following commands:
-> select offline -> remove gg.uuu.jobname
where "gg.uuu.jobname" is as defined above. After a job has executed, SPIRES removes it from the OFFLINE subfile automatically.
Note:
- Any lines in the active file beginning in column 1 with /* or // are interpreted as JCL (Job Control Language) modifications for the offline job.
- /* statements are placed into the job stream just prior to the EXEC statement. Examples include /*SETUP for devices and /*JOBPARM for job parameters, such as HOLD=OUTPUT.
- JCL or // statements are placed immediately following the EXEC statement. Normally, // statements are used for override of DD statements, such as //SYSWDS DD ...
- Any SPIRES commands which begin with / should have a blank following the / to prevent accidental interpretation as /* or // statements. Therefore, / *$DATE is a SPIRES command.
Here is a sample job to print a list of all the restaurants in the RESTAURANT subfile on letter-size paper (note JOBPARM statement), followed by all of the Chinese restaurants in the file:
-> collect
1. > /*JOBPARM FORMS=9511
2. > select restaurant
3. > for tree
4. > page
5. > display all
6. > page
7. > find cuisine chinese
8. > type
9. > logoff
10. > *** (ATTN pressed)
-> select offline
-> offline restrant bin=907 copies=2
If you believe that an OFFLINE job may be run again in the future, the SAVE option should be specified on the OFFLINE command.
This option may be specified as follows:
OFFLINE jobname [options] SAVE
When the SAVE option is specified, a copy of the OFFLINE job and the options specified for it are placed in the SAVED OFFLINE subfile. The job can then be rerun at any future time by issuing the OFFLINE RERUN command. [See E.3.2.2.]
You can remove a job that has been saved by selecting the SAVED OFFLINE subfile and issuing the REMOVE command; the key of a record in both the OFFLINE and SAVED OFFLINE subfiles is
gg.uuu.jobname
where "gg.uuu" is your account, and "jobname" is the name given to the job when the OFFLINE command was issued.
You can see what jobs are in the SAVED OFFLINE file for your account with the following commands:
-> select saved offline -> for adds +> display all +> for goal +> display all
You can remove a job from the SAVED OFFLINE file with the following commands:
-> select saved offline -> remove gg.uuu.jobname
where "gg.uuu.jobname" is as defined above.
Once a job has been saved in the SAVED OFFLINE subfile by specifying the SAVE option on the OFFLINE command, the job may be rerun any succeeding night by issuing the OFFLINE command with the RERUN option.
The form of the command is:
OFFLINE jobname RERUN
where jobname is the name given to the job when the OFFLINE RUN command was first issued. As with all OFFLINE commands, the OFFLINE subfile must be selected or no subfile selected.
The job will be run the night the OFFLINE RERUN command is issued, using the same job options specified when the OFFLINE command was first issued.
When the RERUN option is specified on an OFFLINE command, the job named in the command is copied from the SAVED OFFLINE subfile [See E.3.2.1.] into the OFFLINE file. [See E.3.2.] The commands used to examine jobs in the OFFLINE subfile and the SAVED OFFLINE subfile can be used to determine the status of a job for which RERUN has been specified.
There are four types of system messages in SPIRES: information, warning, serious and charge messages. Extensive facilities are available to you for controlling these system messages sent to the terminal during a SPIRES session and during a SPIRES protocol session.
All of the message control commands are of the form:
SET [type] MESSAGES [TO|=] {0|1|2|3|4}
When "type" is omitted, all system messages are set to the level specified. Otherwise, only the message type specified is affected. The types are as follows:
Type: Example message: INFORMATION (INFO) Result: 3 RECORD(S) WARNING (WARN) Zero result SERIOUS (SERI) Serious data error CHARGE (CHR) Database charge ALL (All of the above)
"0" suppresses messages of the type specified, and "2" is the default message level. "4" specifies that explanations for errors are to be invoked automatically, via an automatic EXPLAIN command; this level should be especially helpful to beginners. (Experienced or frequent users are discouraged from issuing the "SET MESSAGES 4" command, since this provides an automatic explanation even for informational messages. "SET SERIOUS MESSAGES = 4" will prove far more useful, since only serious messages will receive automatic explanations.)
Samples follow:
Example: Explanation: Sample message:
SET WARN MESSAGES 0 (no message)
SET WARN MESSAGES 1 (coded message) -133(W)-
SET WARN MESSAGES 2 (text message) -Zero result
SET WARN MESSAGES 3 (code and text) -133(W)- Zero result
SET WARN MESSAGES 4 (code, text and -133(W)- Zero result
explanation) - <explanation of message>
When error messages are automatically explained via SET MESSAGES 4, they are displayed into an area whose size is determined by the value given in a SET WIDTH command in SPIRES; the default is 150. [See E.4.2.]
The database 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 ->
Message levels 0 through 3 are available to control these messages, with level 2 the default. The messages are controlled by the following levels:
0 - No messages or prompt. 1 or 2 - Messages at SELECT and CLEAR SELECT time. 2 or 3 - CONTINUE SELECT prompt.
When you choose to have error messages automatically explained using the SET MESSAGES 4 facility, the messages are displayed into an area whose width is determined by the value given in a SET WIDTH command. If no value is set, the wrap-around effect of displaying such a message into an area the size of a CRT screen will be unattractive, so you are advised to issue the SET WIDTH command in SPIRES if message level 4 is in effect.
Note that this is a SPIRES command, and is different from the SET WIDTH command in MILTEN. If you are in WYLBUR mode (i.e., you have issued the SET WYLBUR command or included the "(W)" parameter on the CALL SPIRES command), you must precede the SET WIDTH command with a "/".
The syntax of the command is:
SET WIDTH n
where "n" is an integer value from 40 to 235. The value should be the width of the terminal's display screen or carriage, usually either 75-80 or 130-150.
(The following documents are not SPIRES documents per se, but describe utilities and programs that may be useful in developing SPIRES applications.)
The above documents (except any marked "in preparation") may be obtained through the PUBLISH command on the Forsythe computer at Stanford University. If you do not use SPIRES at Stanford, contact your local system administrator to find out how SPIRES documents are made available there.
SPIRES manuals are updated regularly as changes are made to the system. This does not mean that all manuals are out of date with each new version of SPIRES. The changes to the documentation match those made to SPIRES: they are usually minor and/or transparent. Not having the most current version of a manual may mean you do not have all the most recent information about all the latest features, but the information you do have will usually be accurate.
A public subfile, SPIRES DOC NOTES, contains information about changes to SPIRES manuals. Using this subfile, you can determine whether the manual you have has been updated and if so, how significant those updates are. You need to know the date your manual was published, which is printed at the top of each page. For details on the procedure, issue the command SHOW SUBFILE DESCRIPTION SPIRES DOC NOTES.