******************************************************************
* *
* 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.
This document describes the File Definer, a SPIRES subsystem that allows the user interested in defining a SPIRES file to create a working file definition without getting involved in the intricacies of native SPIRES file definition language. It is not necessary to have prior experience in defining SPIRES files; the File Definer is a good tool for those computer users putting up their first SPIRES application.
It is assumed that you are familiar with the information in the manual "SPIRES Searching and Updating", both because you should be acquainted with some of the special terminology used in SPIRES before reading this manual and because it will help you visualize how your files may be used and thus help you design them more usefully. You should also be somewhat familiar with file definition terminology; a review is included below. Basic concepts of file definition are not explained in any detail here, although ample references are included throughout this manual directing you to other sources for detail information. Several other manuals exist that cover file definition and you should be aware of their contents:
Cross-references to "SPIRES File Definition" are provided in this manual to guide the reader to in-depth explanations of the terms and concepts used in the File Definer subsystem. You may also use the EXPLAIN facility in SPIRES for online explanations of any file definition term. For details about this facility, issue the command EXPLAIN EXPLAIN COMMAND.
When using a SPIRES file, the user deals with subfiles and their component parts -- goal records and index records -- both of which are in turn comprised of elements. A subfile basically contains a set of goal records, where each goal record represents one item in a particular class of objects. The "goal record record-type" or "goal record-type" is a template of the goal record. The term "record-type" often refers to the schema or template of a record, not a specific record, similar to the difference between a blank application form and one that has been filled out. The goal record is made up of elements, the basic unit of information in the subfile.
Elements are placed into categories determined by their length and number of occurrences: FIXED elements must occur and are fixed in their storage length and their number of occurrences; REQUIRED elements must occur, but need not have fixed length or occurrence, although they can have either; OPTIONAL elements do not have to occur, and do not need to have FIXED length or occurrence, but they can have either or both.
Elements are further defined by their type -- that is, what type of value the element will have, such as a standard date value, a time value, a personal name, or a number, to name a few. Element values can also be tested or converted by applying processing rules to them on input (called INPROC rules) or output (called OUTPROC rules). Some elements are themselves made up of other elements; the containing elements are called "structures" or repeating groups. One element, guaranteed to be a single, unique value for each record, is designated as the "key element". SPIRES uses this key element to distinguish between one goal record and another, just as we might use a page number in a book to find our way back to a certain page. Some goal record-types have a natural key (such as a social security number in a personnel file), while other record-types have no one element guaranteed to be unique; the latter are called "slot" record-types, for which SPIRES assigns a unique numeric key for each record added. Structures may have keys, but the keys need not be unique.
In most cases, a subfile also contains sets of index records used in searching. The file owner may index any, all or none of the goal record elements. An index (or index record-type) is a set of index records, very much like a set of goal records. These index records contain data that SPIRES extracts from your goal records.
A subfile, then, consists of a goal record-type (a set of goal records, all designed the same) and perhaps one or more index record-types (sets of index records). All subfiles have exactly one set of goal records; a subfile may or may not have indexes. It is possible for one file to have several different goal record-types, each of which is the goal record for a different subfile. Thus, a file may have one or more subfiles.
These characteristics for particular subfiles are specified in a "file definition". Basically the file definition:
Use of the File Definer allows you to concentrate on the first: the structure and use of the goal record.
The File Definer was developed by George Crane of SLAC with the support of the Data Resources Group at I.T.S. Many SPIRES users contributed to its development during the long testing period, and their suggestions and bug reports were very helpful. This document was written by Becky Morton of the Data Resources Group.
In this manual, examples of sessions are shown with prompts and messages from SPIRES as they appear in actual sessions -- usually a mixture of upper- and lowercase, preceded by a hyphen; commands you type are shown in lowercase. (You may use upper- or lowercase interchangeably when you are actually using SPIRES). For example:
-OK to clear? ok
Here SPIRES prompts you "-OK to clear?" and you type "ok".
In formal command syntax descriptions, uppercase letters denote command verbs or other command elements to be entered exactly as shown; a value for lowercase terms and characters must be supplied by you. For example:
SELECT subfile-name
To use this particular command, you type the command verb "SELECT" with the name of the desired subfile, for instance, "Restaurant":
-> select restaurant
where "->" is the prompt from SPIRES.
Brackets ([]) denote optional parts of a command's syntax. Braces ({ }) indicate that you must specify one (and only one) of the alternatives within the braces. Within the braces or brackets, a vertical line (|) separates possible choices. Neither brackets nor braces are to be typed as part of the command. For example:
TYPE [PAUSE|KEEP]
could be entered as
TYPE or TYPE PAUSE or TYPE KEEP
depending on whether you want one of the options. Here is an example of braces:
DEQUEUE {record-key-value|ALL}
This command must be entered either as
DEQUEUE record-key-value
where you supply the "record-key-value", or as
DEQUEUE ALL
with the choice again governed by the desired result.
The File Definer is designed as a productivity tool for SPIRES users who want to define a SPIRES file or data base. Because it offers a shorter, easier way of coding the file definition, it makes the process of designing a file easier. A file definition can be generated, compiled, and tested, and if it does not work exactly as desired, the file can be redesigned and a new file definition generated by making a few changes in the File Definer input. Such an approach makes the design task an iterative process, allowing several "test files" to be easily created.
For example, in the File Definer you may simply specify INDEX for a particular element and the File Definer will create in the file definition the necessary index record and linkage section, expanding one word in File Definer language into 10 to 15 lines of file definition code. Constructing an index in file definition language can be a time-consuming job, so if you were writing the file definition code yourself, you might be wary of experimenting with different indexes in your file because of the time involved in coding them. But since the File Definer simplifies the coding of the file definition, experimentation becomes faster.
The File Definer language includes commands with which to control the File Definer subsystem and special keywords to describe the components of the file. File Definer keywords are similar conceptually to the statements in SPIRES file definition language, and the components of a File Definer input file parallel the components of a file definition. File definition components, as discussed here, are the conceptual building blocks of a file: file, record, element, subfile.
The File Definer works with "input lines" -- each input line describing a file component. Each input line begins with a keyword, such as SUBFILE or ELEMENT, which names the particular component of the file being described on the line. For example, "SUBFILE PHONE-BOOK" specifies that "PHONE-BOOK" is to be the name of the subfile. In addition to the keyword, attributes may be added to the line to further define the file component and add additional characteristics to the file. In simpler terms, a keyword can be thought of as a noun that names the file component, and attributes are adjectives describing that noun. Some keywords are assigned values; the keyword ELEMENT, for example, is assigned a value which is the name of an element, such as PHONE.NUMBER. In the same sense, some attributes are assigned values. For example, the attribute LENGTH describing the element PHONE.NUMBER would be assigned the value of "12": ELEMENT PHONE.NUMBER/ LENGTH 12.
A complete file definition in the File Definer language is called an "input file". The following example is an input file with four input lines, which can generate a complete, albeit simple, file definition:
1. FILE EXAMPLE
2. SUBFILE PHONE-BOOK
3. ELEMENT NAME
4. ELEMENT PHONE.NUMBER/ LENGTH 12
We can separate each of these input lines into the four types of File Definer input values: Keyword, Keyword Value, Attribute, Attribute Value.
KEYWORD KEYWORD VALUE ATTRIBUTE ATTRIBUTE VALUE
FILE EXAMPLE
SUBFILE PHONE-BOOK
ELEMENT NAME
ELEMENT PHONE.NUMBER LENGTH 12
Not every component of the file need be specified in the File Definer input file; defaults are supplied where appropriate. A table of keywords, attributes and their defaults is supplied in Appendix A.
In most cases, your file definition will be much more complicated than the above example. The File Definer has the ability to specify in great detail the components of a file definition. Additional features include, but are not limited to, multiple record-types, USERPROCS, file and subfile security privileges, and file management statements. In addition, customized processing rules can be added to the file definition by using the INPROC, OUTPROC, SEARCHPROC, and PASSPROC keywords.
There are, however, limitations to the capabilities of the File Definer. Some of the things that the File Definer cannot do are:
1. Create indexes other than simple indexes.
(except for personal name indexes)
2. Add customized SEARCHTERM statements
3. Specify non-removed record types
You will probably still find the File Definer useful even if these limitations affect you. You can generate a prototype file definition with the File Definer and tailor it to your own needs. This requires a more sophisticated knowledge of file definition language and careful modification of the file definition. Consult "SPIRES File Definition" or your SPIRES consultant for assistance.
The process of creating a SPIRES file with the File Definer is similar to using native SPIRES file definition language. However, the ease of use of the File Definer will substantially shorten some steps for all but the more complicated definitions and applications. Designing a file is covered in detail in Chapter A.3 of "SPIRES File Definition", but the process is as follows:
For Step 5, it is recommended that you save the File Definer input file from Step 3, modify it and regenerate a new file definition rather than modifying the native SPIRES file definition code. A change in one place of the code often requires changes in other places, and you might end up with a file definition that does not compile. Letting the File Definer take care of the necessary internal consistencies will avoid this problem.
See Sections 7.3 and 7.4 for information about changing the file definition of a file containing data.
To show you the relative simplicity of creating a file definition using the File Definer, we will go through a complete File Definer session. Let's say we want to create an online phone book: a file composed of names, addresses and phone numbers. In addition, we want to make searching easier by indexing the name.
From within SPIRES, we enter the File Definer, input our file characteristics in File Definer language, save our input file for later use and then, with the GENERATE command, instruct the File Definer to create a file definition from our specifications. We then add the file definition to the system FILEDEF subfile and compile it:
COMMAND> spires
-Welcome to SPIRES ... if in trouble, try HELP
-> enter file definer
* ENTERING FILE DEFINER
:-> input
: 1. Input> subfile phone.book
: 2. Input> required
: 3. Input> element full.name/ name/ index
: 4. Input> element phone.number/ length 12,exact
: 5. Input> optional
: 6. Input> element address
: 7. Input> end
:-> in active show input
:-> list
1. SUBFILE PHONE.BOOK
2. REQUIRED
3. ELEMENT FULL.NAME/ NAME/ INDEX
4. ELEMENT PHONE.NUMBER/ LENGTH 12,EXACT
5. OPTIONAL
6. ELEMENT ADDRESS
7. END
:-> save #input
INPUT saved in WYL.GQ.BEC.LIB
:-> generate clear
:-> return
-> select filedef
-> add
-> compile gq.bec.phone.book
-File Definition Compiled
We now have a file that we can SELECT and test. The file definition was placed in our active file, so we can list it and see what the File Definer created.
-> list
1. FILE = GQ.BEC.PHONE.BOOK;
2. COMMENTS = Generated by FILE DEFINER 02/12/86;
3. RECORD-NAME = REC01;
4. REMOVED;
5. SLOT;
6. REQUIRED;
7. ELEM = FULL.NAME;
8. INPROC = $NAME;
9. OUTPROC = $NAME;
10. ELEMINFO;
11. VALUE-TYPE = TEXT;
12. INDEX = FULL.NAME;
13. ELEM = PHONE.NUMBER;
14. LEN = 12;
15. INPROC = $LENGTH(12);
16. OPTIONAL;
17. ELEM = ADDRESS;
18. RECORD-NAME = ZIN02;
19. REQUIRED;
20. KEY = FULL.NAME;
21. OPTIONAL;
22. ELEM = FIRST;
23. TYPE = STR;
24. STRUCTURE = FIRST;
25. REQUIRED;
26. KEY = FN;
27. INPROC = $PNAME;
28. OUTPROC = $PNAME;
29. OPTIONAL;
30. ELEM = POINTER;
31. TYPE = LCTR;
32. INPROC = $HEX;
33. OUTPROC = $HEX.OUT;
34. GOALREC-NAME = REC01;
35. PTR-ELEM = POINTER;
36. EXTERNAL-NAME = RECORD;
37. PASSPROC = $PASS.LCTR;
38. INDEX-NAME = ZIN02;
39. SEARCHTERMS = FULL.NAME;
40. SEARCHPROC = $PNAME(TRANS);
41. PASSPROC = $PASS.ELEM('FULL.NAME',NAME)/
$PNAME(TRANS,SPECIAL);
42. INDEXINFO;
43. SOURCE = FULL.NAME;
44. VALUE-TYPE = NAME;
45. SUB-INDEX = FIRST;
46. SEARCHTERMS = NONE;
47. PRIV-TAG = 1;
48. PASSPROC = $PASS.OCC;
49. PTR-GROUP = POINTER;
50. SUBFILE-NAME = PHONE.BOOK;
51. GOAL-RECORD = REC01;
52. ACCOUNTS = GQ.BEC;
53. NOSEARCH = 1;
As you can see, seven lines of File Definer input created 53 lines of file definition code. The File Definer provided defaults for those necessary components of the file definition that we did not specify: file name, record name and record key. It created the file name (line 1) from the file definer's account and the subfile name, assigned REC01 as the record name (line 3) and added the SLOT statement (line 5) to provide a key in the form of a slot number.
The first line of the input file specified the subfile section of the file definition (lines 50-53). We did not specify any attributes for the subfile, but the File Definer added an ACCOUNT statement, the standard default for the subfile section. (The NOSEARCH=1 statement was added by the INDEX attribute; see below.)
REQUIRED signaled the File Definer to begin the REQUIRED section of the record definition and to include all elements that follow (in this case the elements FULL.NAME and PHONE.NUMBER) in that section (lines 6-15). The element FULL.NAME was followed by the attribute NAME, which specified that the element was a personal name, so the File Definer added the appropriate processing rules to handle personal name conversion. (EXPLAIN $NAME PROC for details about personal name conversion rules.) The File Definer also supplied element information statements based on the element attributes for the FULL.NAME element (lines 10-12). The LENGTH attribute with the value of "12" specified that the element PHONE.NUMBER must be exactly 12 characters long, and the File Definer added the necessary processing rule. OPTIONAL in the File Definer input created an OPTIONAL section in the record definition which includes the element ADDRESS (lines 16-17).
To create the index for the FULL.NAME element, we added the attribute INDEX on the element input line. This directed the File Definer to create an index record definition (lines 18-33) that stores the information for the FULL.NAME index, and the linkage section (lines 34-49) that handles the creation and searching of the file. The personal name index is a complicated one, involving a sub-index for the first name that is not directly searchable (hence the PRIV-TAG=1 and NOSEARCH=1 statements), but it is something that is commonly needed, and its use in this example shows how the File Definer can greatly simplify coding an intricate component of a file definition.
This chapter covers the special File Definer commands used to enter and return from the File Definer subsystem, input file characteristics, generate file definitions and receive information about the status of the File Definer.
The File Definer is entered from within SPIRES with the following command:
ENTER FILE DEFINER [QUIET]
The QUIET option suppresses the welcoming message.
COMMAND> spires -Welcome to SPIRES ... if in trouble, try HELP -> enter file definer * ENTERING FILE DEFINER :->
There are two modes in the File Definer, command and input, identified by the prompts ":->" and "Input>". In the command mode, you may enter any WYLBUR, ORVYL or SPIRES command in addition to the File Definer commands described in this chapter. The input mode allows you to enter input lines describing the characteristics of the file you wish to define.
The SHOW ENTER command tells you what SPIRES subsystem you are in. For example:
:-> show enter * FILE DEFINER subsystem has been entered. :->
The RETURN command returns you to SPIRES. Any input lines stored internally by the File Definer are cleared. Your active file is not changed. For example:
:-> return ->
The INPUT command places you in the input mode and prompts you for input lines. The File Definer scans each input line you enter for proper syntax and rejects the entire line if an error is detected, issuing an error message and reprompting for the line. As input lines are successfully processed, they are stored internally by the File Definer until they are cleared. [See 2.7.]
The syntax of the command is:
INPUT [ACTIVE [QUIET]| DUMP]
When you finish entering data, either type the END keyword or press the ATTN key and you will be returned to command mode. For example:
:-> input : 1. Input> subfile list : 2. Input> element name : 3. Input> element address : 4. Input> end :->
INPUT ACTIVE accepts an entire input file from the active file, echoing it back to the terminal as the lines are processed. INPUT ACTIVE QUIET suppresses echoing of the input lines. If an error is encountered, an error message will be output and processing of the active file will stop. All input lines processed and stored before the error was encountered are removed from the File Definer's internal storage area. You can then modify the input lines in the active file and issue the INPUT ACTIVE command again until the entire file is successfully processed.
INPUT DUMP causes the File Definer to place each input line at the end of your active file as you enter it; you may then save it for later use. On the other hand, INPUT ACTIVE allows you to enter an already existing file from the active file. INPUT ACTIVE and INPUT DUMP are mutually exclusive commands.
The syntax of the input line is
keyword [=] [value]/ attribute [=] [value]/ attribute [=] [value]. . .
All input lines should begin with a keyword; if a keyword is not included, the File Definer assumes "ELEMENT". Only one keyword may appear on a single input line. Valid keywords are:
FILE FIXED USERPROC COMMENTS SUBFILE REQUIRED VARIABLE NOSAVE VIEW OPTIONAL INPROC END GOAL VIRTUAL OUTPROC ELEMENT CMD SEARCHPROC GLOBAL EXPLAIN PASSPROC KEY
A keyword and attributes are separated on the line by a slash (/) and generally may appear in any order (with a few exceptions that will be noted). The slash may be followed by one or more blanks; an equal sign may appear between a keyword or attribute and its value, but it is not required. If a slash must appear in a value, the entire value must be enclosed in quotes.
An input line can be up to 160 characters. To continue an input line onto the next line, end the line with a "+". For example:
:-> input : 1. Input> subfile test : 2. Input> element one/ capitalize/ squeeze/ length 12/+ : 3. More-> exclude XXX,YYY : 4. Input> element two : 5. Input> end :->
When entering input lines from the active file, the File Definer retains the WYLBUR line numbers. When prompting for input, the File Definer assigns line numbers to the input file with an increment of one for each new line.
You can exit from the input mode with the END keyword or by pressing the ATTN key; the File Definer remembers where you are: if you issue the INPUT command again it prompts you for the next input line; subsequent lines are added to the same input file stored internally by the File Definer. We could continue the above example as follows:
:-> input : 5. Input> element three : 6. Input> end
The GENERATE command generates a file definition in SPIRES file definition language, using the information in the input file that has been entered into the File Definer. The input file is not cleared by the GENERATE command. Your file definition is placed in your active file; it can then be added to the FILEDEF subfile and compiled.
The syntax of the command is:
[IN ACTIVE CONTINUE] GENERATE [CLEAR]
Because GENERATE automatically places the file definition in your active file, the IN ACTIVE prefix is not necessary unless you wish to append the file definition to your current active file, in which case you would use the IN ACTIVE CONTINUE prefix. GENERATE CLEAR is equivalent to IN ACTIVE CLEAR GENERATE.
To add the generated file definition to the FILEDEF subfile and then compile it, issue the following commands:
:-> generate :-> return -> select filedef -> add -> compile filename -File Definition Compiled
"Filename" is the name of the file, which can be found by listing the first line of the file definition; it is in the form "gg.uuu.filename". The "gg.uuu." prefix is optional in the COMPILE command.
Using the File Definer does not guarantee that your file definition will compile. If you have added customized INPROC and OUTPROC rules [See 5.3.] for example, the File Definer does not validate their correctness; if there is an error in the rule, the file definition will not compile. If such is the case, contact your SPIRES consultant.
The SHOW INPUT command displays the File Definer's image of the current input file. The IN ACTIVE prefix places the input file into the active file. END is added by the File Definer at the end of the input file, if not entered by you.
For example:
:-> input : 1. Input> subfile list : 2. Input> element name : 3. Input> element address : 4. Input> end :-> show input subfile list element name element address end :->
The File Definer normally retains a copy of the input file that it displays when the SHOW INPUT command is issued. The NOSAVE keyword is used to prevent the File Definer from retaining the input lines when the input file might exceed the storage capacity of the File Definer. This is not necessary unless your input file is likely to exceed 500 lines.
When NOSAVE is used, you receive the following response to the SHOW INPUT command:
* NOSAVE currently in effect. No input lines saved.
The information from the input file is still stored by the File Definer in a special configuration from which the file definition is generated.
If it is used, NOSAVE must appear as the first line of the input file:
:-> input : 1. Input> nosave : 2. Input> subfile list : 3. Input> element name : 4. Input> element address : 5. Input> end :-> show input * NOSAVE currently in effect. No input lines saved. :->
If NOSAVE is not used and your input file exceeds the storage capacity of the File Definer, you receive the following message:
-Core exhausted -Exiting SPIRES
You are then returned to WYLBUR. You must then CALL SPIRES again, enter the File Definer and add NOSAVE at the beginning of your input file.
The CLEAR INPUT command clears all input lines stored by the File Definer. If you wish to enter a new input file, you must issue the CLEAR INPUT command before the INPUT command; otherwise, the new input file is appended to the already existing input file.
The HELP command displays the list of commands that can be entered in the command mode. If the HELP command is preceded by the IN ACTIVE prefix, the command list is placed in your active file. If you are in input mode, a "?" displays a list of possible responses.
To get the HELP facility in SPIRES, the HELP command must be preceded by a "/". To get WYLBUR HELP, the HELP command must be preceded by a ",". For example:
:-> /help :-> ,help
The SHOW NEWS command displays in reverse chronological order information about recent changes to the File Definer subsystem. The IN ACTIVE prefix can be used to place the news in your active file.
To get WYLBUR News the SHOW NEWS command must be preceded by a ",". For example:
:-> ,show news
The File Identification section consists of the file name, a statement identifying the author of the file definition, optional statements that direct the processing of the file, a MAXVAL statement if the file is expected to contain very large element values, and statements controlling file access.
This chapter covers the FILE keyword and the attributes that are allowed on the FILE input line. In addition, the COMMENTS keyword is explained, which is used to add comments anywhere in the file definition.
The FILE keyword and all of its attributes are optional. Defaults are provided for all parts of the File Identification section. [See Appendix A.]
The FILE keyword begins the line that specifies the file name and the characteristics of the file identification section. The file name appears on the first line of the file definition and is used to identify the file definition when adding it to FILEDEF and compiling it. If no attributes are to be assigned to FILE, this line need not appear in the input file; the File Definer creates a name from your account and the name of the first subfile specified. If specified, the FILE keyword can appear anywhere in the input file. If blanks appear in the file name, they are converted to "." in the file name.
The syntax of FILE is:
FILE [gg.uuu.]filename
where "filename" contains 14 or fewer characters with no embedded blanks. For example:
FILE MAIL.LIST FILE GA.SPI.PEOPLE
The "gg.uuu" prefix is added automatically by the File Definer if not specified with the FILE keyword.
If you want to specify FILE attributes but want to let the File Definer create the file name, the FILE keyword can be used without a value, followed by a "/" and the desired attributes:
FILE/ attribute. . .
For further details see Section B.1.2 of "SPIRES File Definition" or [EXPLAIN FILE STATEMENT.]
The AUTHOR attribute adds an AUTHOR statement to the file definition. Its value is a text string of any length and should include your name and phone number. This attribute should be included in all file definitions so that you can be contacted by the SPIRES systems staff in case of problems. For example:
FILE/ AUTHOR your name, phone number
See Section B.1.8 of "SPIRES File Definition" or [EXPLAIN AUTHOR STATEMENT.]
The MAXVAL attribute is assigned a value that is an integral multiple of 8. It specifies the maximum data length for any single occurrence of an element. This attribute is only used if any single element value is expected to exceed 4,096 bytes or characters. For example:
FILE/ MAXVAL 8192
allows an element value to be up to 8192 characters long.
See Section B.1.8 of "SPIRES File Definition" or [EXPLAIN MAXVAL STATEMENT.]
The NOAUTOGEN attribute adds a NOAUTOGEN statement to the file definition. This prevents SPIBILD from automatically processing records in the deferred queue in normal overnight processing. For example:
FILE/ NOAUTOGEN
See Section B.1.8 of "SPIRES File Definition" or [EXPLAIN NOAUTOGEN STATEMENT.]
The BIN attribute adds a BIN statement to the file definition. The value of BIN is the bin number to which you wish the output from SPIRES-generated jobs to be sent. If the BIN attribute is not included, then such output is sent to your default bin. You may also specify BIN HOLD or BIN PURGE. BIN HOLD causes your output to be directed to your default bin, but held until you release or purge it. BIN PURGE causes the output to be purged unless there was an error encountered in the job. For example:
FILE/ BIN 237
See Section B.1.8 of "SPIRES File Definition" or [EXPLAIN BIN STATEMENT.]
The STATISTICS attribute is used in conjunction with the LOG attribute on the SUBFILE input line [See 6.4.] to specify disposition of the log information. The value of STATISTICS is "1" or "2" or both. For example:
FILE/ STATISTICS 1 FILE/ STATISTICS 1,2
See Section B.11.3.2 of "SPIRES File Definition" or [EXPLAIN STATISTICS STATEMENT.]
The attributes for defining file access privileges are MASTER, PROCESS, SEE, COPY and UPDATE, and their value is equal to the accounts that are to have the privileges. Accounts are in the standard form "gg.uuu". An entire group of accounts may be specified as "gg...." or a community as "g....". For example:
FILE/ MASTER gg.uuu,gg.uuu/ SEE gg.uuu. . .
Like most keywords and attributes, these attributes may be abbreviated to their first three letters: MASTER (MAS), PROCESS (PRO), COPY (COP), UPDATE (UPD).
See "SPIRES File Definition", Chapter B.9a, or [EXPLAIN FILE-ACCESS STATEMENT.]
The COMMENTS keyword is used to add comment statements to the file definition. The syntax of COMMENTS is:
COMMENTS string
where "string" is any free-form text string.
The COMMENTS keyword may be used in many places in your File Definer input, depending on where you need comments in your file definition: after the FILE, GOAL, or SUBFILE keywords, as part of an element definition, or in a Userproc. [See 5.4.2 for details about comments in Userprocs.]
A very simple file identification might consist of only the FILE keyword and AUTHOR attribute:
FILE/ AUTHOR Y.L. RATNOSE, 7-0007
A more complicated file identification section utilizing all of the options available in File Definer might look like this:
FILE ANIMAL/ AUTHOR Y.L. RATNOSE, 7-0007/ NOAUTOGEN/ MAXVAL 4096/+ STATISTICS 2/ MASTER GA.ABC,GQ..../ SEE GA.XYZ
The goal record specification outlines the basic structure of the goal record: the record name, the external name, its physical storage configuration (COMBINED or separate), element categories, and element specifications. All goal records specified with the File Definer are REMOVED record-types. Element specification is covered in Chapter 5 of this manual. The EXT-VIEW attribute is covered in section 6.5a. The other aspects of goal record definition are covered below.
Keywords associated with goal record definition are:
GOAL (with attributes COMBINE, RESULT, PASSER, and EXT-VIEW) FIXED REQUIRED OPTIONAL VIRTUAL COMMENTS
All of these keywords are optional, and defaults are provided. Most file definers use only the FIXED, REQUIRED and OPTIONAL keywords.
The GOAL keyword is used to specify the name of the goal record.
The syntax of GOAL is:
GOAL [record-name]
where "record-name" is 6 or fewer characters.
If not specified, the File Definer assigns a record name in the form "RECnn" where "nn" is the logical record number (e.g., REC01, REC02, etc.). All subsequent element or subfile statements apply to this goal record until another GOAL statement is input.
If only one record type is to be defined for the file and no attributes are to be assigned to GOAL, this line can be left out; the File Definer assumes "GOAL REC01". If you want to include any of the GOAL attributes but want to let the File Definer assign the record name, the GOAL keyword can be used without a value, followed by a "/" and the desired attributes:
GOAL/ attribute. . .
[For a complete explanation of goal record concepts, see Chapter B.1 of "SPIRES File Definition".]
The COMBINE attribute specifies that the goal record is to be stored in the same ORVYL file as another goal record whose name is the value of COMBINE. For example:
GOAL REC02/ COMBINE REC01
This puts both record types in the same ORVYL files, although they are kept separate logically. If the COMBINE attribute is not included, all index record-types are combined with the first index record-type and goal records are not combined. SLOT record-types [See 5.1.5.13.] may not be combined with any other record-types.
See Sections B.6.5 and B.7.12 of "SPIRES File Definition" or [EXPLAIN COMBINE STATEMENT.]
The RESULT attribute specifies an external name to be displayed in search result counts, such as "RESULT: 10 ACCOUNT(S)" where "ACCOUNT" is the external name. If the search result contains only one record, the "(S)" is not included. You may specify two names, separated by a comma, in which case the first name is used for search results containing a single record, and the second name is used for multi-record search results. Each name must be less than 16 characters and contain no blanks. For example:
GOAL/ RESULT ACCOUNT or GOAL/ RESULT MOUSE,MICE
If not specified, the external name is the same as the record name. If no indexes are defined for the record (which means that no index searches would be possible), this attribute is ignored.
For more details, see Section B.8.2 of "SPIRES File Definition" or [EXPLAIN EXTERNAL-NAME STATEMENT.]
The PASSER attribute specifies what type of information about the location of the goal record is passed to the index record when the goal record is added or updated.
The syntax of PASSER is:
GOAL/ PASSER {KEY|LOCATOR}
If PASSER KEY is specified, the record key is passed to the index record as the pointer element; if PASSER LOCATOR is specified, the physical address of the record is passed to the index. The default pointer is LOCATOR.
[See Section B.7.14 in "SPIRES File Definition" for details about indexes and pointers.]
The FIXED, REQUIRED, OPTIONAL and VIRTUAL keywords are used to define the element categories within a record-type. Each appears in the input file on a separate line; all elements following it are placed in that category. Once a category is specified, it remains in effect until a new category is specified, or until a new goal record is defined. If no categories are specified, then the File Definer assumes that all elements are OPTIONAL, with the exception of the record key, which is REQUIRED. [See 5.1.1.]
Categories must be specified in the following order: FIXED, REQUIRED, OPTIONAL, VIRTUAL. All elements within a category must be specified before specifying the next category.
Elements in the FIXED category must meet two criteria: 1) the number of occurrences must be fixed -- this may be specified via the OCCURRENCE attribute [See 5.1.3.] or, if not specified, defaults to OCCURRENCE = 1; 2) the LENGTH must be fixed -- it must be specified in the File Definer input file via the LENGTH attribute. [See 5.1.2.] Some attributes add a LENGTH statement to the element definition. [See 5.1.5.]
For further details about element categories, see "SPIRES File Definition", Chapters B.1.3 and C.11.2 or [EXPLAIN ELEMENT, CATEGORY.]
You actually need never include the GOAL keyword when you are only defining one goal record for your file -- the File Definer provides a default goal record name for you. You also do not need to specify any element categories; the File Definer places all elements (except for the key, if you specify one) in the optional category. However, you probably want to at least define element sections as in the following example:
FIXED ELEMENT ONE ELEMENT TWO REQUIRED ELEMENT THREE OPTIONAL ELEMENT FOUR
All elements, userdefs, and subfile specifications apply to this goal record.
Sometimes you will want to define more than one goal record-type per file, making each goal record-type a separate subfile. The most common use of this is when you want one goal record to be a table accessed by an element in the other goal record (with the LOOKUP attribute).
The process is a fairly simple one: the GOAL keyword must be used to signal the beginning of each goal record specification and the SUBFILE keyword must appear somewhere in that specification (i.e., before another GOAL keyword appears). The following example shows a single file with two goal records and two subfiles, with a table lookup from one to the other.
GOAL REC01/ RESULT NAME SUBFILE EMPLOYEES REQUIRED ELEMENT NAME OPTIONAL ELEMENT JOB.CLASS/ LOOKUP VERIFY,REC02/ LEN 4 VIRTUAL ELEMENT JOB.NAME/REDEFINES JOB.CLASS/ + OUTPUT,LOOKUP REPLACE,REC02,JOB.DESC GOAL REC02/ RESULT TITLE SUBFILE JOB DESC ELEMENT JOB.CLASS/ OCC 1/ LEN 4/ KEY OPTIONAL ELEMENT JOB.DESC
The element specification consists of the element name, optionally followed by length and occurrence attributes, a type description, processing rules that convert or test element values, USERPROCS to provide customized processing of element values, and other attributes that describe or limit the element value or connect the element to other parts of the file specification. The minimum requirement for an element specification is an element name; all other keywords and attributes are optional, although an element type [See 5.1.5.] and one or more processing rules [See 5.1.6.] are usually included.
Keywords associated with element specification are:
ELEMENT SEARCHPROC EXPLAIN KEY PASSPROC COMMENTS STRUCTURE USERPROC GLOBAL VARIABLE INPROC OUTPROC
In the explanations below, if no syntax is given, the keyword or attribute stands alone, with no values assigned to it.
The ELEMENT keyword begins the input line for the element specification.
The syntax of ELEMENT is:
ELEMENT element-name[,alias,alias. . .]
where "element-name" and "alias" are 16 or fewer characters with no embedded blanks. For example:
ELEMENT NAME, NAM, N
The ELEMENT keyword may be left out--if an input line does not begin with a recognizable keyword, the File Definer assumes "ELEMENT". But if you want to assign an element name that is the same as a File Definer keyword, the ELEMENT keyword must be included. For example:
TITLE AUTHOR ELEMENT COMMENTS
You can define up to 550 elements in a single file definition using the File Definer.
See Section B.1.5 in "SPIRES File Definition" or [EXPLAIN ELEMENT.] or [EXPLAIN ELEMENT NAMES.] or [EXPLAIN ELEMENT, ALIASES.]
The key of a record can be specified in one of two ways:
1) Using KEY as a keyword in place of the ELEMENT keyword:
KEY SOC.SEC.NO, SSN
2) Using KEY as an attribute following the ELEMENT keyword:
ELEMENT SOC.SEC.NO, SSN/ KEY
If no key is designated for the record, the File Definer assumes that the record is a SLOT type and SPIRES assigns a unique integer key to each record added. In addition, you can specify that the key is a SLOT type and assign a SLOT-NAME by using the SLOT attribute. [See 5.1.5.13.]
You may only specify one KEY element per record. Unless you make the key a SLOT key, the key element must be included in either the FIXED or REQUIRED categories, and must be the first element specified in that category. If no categories are defined, the key element is placed in the REQUIRED section, and all other elements are placed in the OPTIONAL section. If this is the case, the key element must be the first element defined.
For example, the following specifications are valid:
GOAL REC01 KEY NAME/ SLOT FIXED . .
GOAL REC01 FIXED KEY NUMBER (or ELEMENT NUMBER/ KEY) REQUIRED . .
GOAL REC01 REQUIRED KEY NAME OPTIONAL . .
But the following one isn't:
GOAL REC01 KEY NAME FIXED
because the key element is part of the REQUIRED section and cannot appear before the FIXED section.
The KEY keyword or KEY attribute is also used to designate the key of a structure. [See 5.1.5.14.]
See Section B.1.4 of "SPIRES File Definition" or [EXPLAIN KEY.]
The LENGTH attribute specifies an upper and/or lower limit to the length of a value on input.
The syntax of LENGTH is:
LENGTH n [,MINIMUM|,MAXIMUM|,EXACT]
where "n" is an integer value.
The LENGTH value may be followed by MINIMUM, MAXIMUM or EXACT. MAXIMUM is the default and checks that a value being input into the element is no longer than the LENGTH given, rejecting the element with a serious error if it is longer. MINIMUM checks that a value being input into the element is at least the length of the LENGTH given, rejecting the element with a serious error if it is shorter. EXACT checks that a value being input into the element is exactly the length of the LENGTH given, rejecting the element with a serious error if it is not. For example:
ELEMENT NAME/ LENGTH 24 ELEMENT L-CODE/ LENGTH 3, MINIMUM/ LENGTH 5, MAXIMUM ELEMENT Z-CODE/ LENGTH 12, EXACT
For elements in the FIXED section, a LENGTH EXACT or MAXIMUM attribute must be given for TEXT type elements (the default type) and other types that do not have a default length. [See 5.1.5.1.] The File Definer uses the MAXIMUM or EXACT length as the length to be stored, and any shorter values are padded to that length. In a file definition generated from File Definer, this storage length is represented by a LEN statement coded as part of the element definition. This storage length specification is independent of the length edits provided within the INPROC rule string. For REQUIRED or OPTIONAL elements, if you specify EXACT in your LENGTH attribute, the File Definer adds a LEN statement to the generated file definition.
See Section B.1.5 of "SPIRES File Definition" or [EXPLAIN LEN STATEMENT.]
The OCCURRENCE attribute specifies the maximum number of times the element can occur.
The syntax of OCCURRENCE is:
OCCURRENCE n
where "n" is the maximum number of times an element can occur. For example:
ELEMENT HABITS/ OCCURRENCE 2
For OCCURRENCE > 1, an INCLOSE rule is added to ensure that the element does not occur more than the specified number of times. The element value that exceeds the occurrence number is rejected with a serious error. If no OCCURRENCE attribute is specified for an element in the FIXED section, the File Definer assumes the value of OCCURRENCE to be 1.
The SINGLE attribute is equivalent to OCCURRENCE 1.
See B.1.5 of "SPIRES File Definition" or [EXPLAIN OCC STATEMENT.]
Indexes are often the most difficult part of coding a file definition. The File Definer takes care of most of the complexity of index specification. Two attributes are used to create the index record and linkage section in the file definition: INDEX and RECNAME. Other attributes that can be used to further define indexes are WORD, BREAKUP, TRUNCATE, and PASSER.
The INDEX attribute by itself creates a simple index and the appropriate linkage section containing SEARCHPROCS and PASSPROCS based on other attributes for the element. Searchterms are created from the element name and all aliases. SOURCE and VALUE-TYPE index info-elements are created for the index information packet, based on searchterms and element types. [See Appendix C.]
The syntax of INDEX is:
INDEX [element-name]
If you wish to pass the element value to the index of another element, the element name is specified as the value of INDEX:
ELEMENT ADDRESS/ INDEX ELEMENT STATE/ INDEX ADDRESS
The result is to have a single index that combines the STATE and ADDRESS values; it is searchable with "ADDRESS" (e.g., FIND ADDRESS CALIFORNIA).
Both conditions may be specified to pass the element to more than one index:
ELEMENT ADDRESS/ INDEX ELEMENT STATE/ INDEX/ INDEX ADDRESS
The result is to have the STATE value appear in both the STATE index and the ADDRESS index.
If all of the elements listed for a particular index are not of compatible types, a warning message is issued when the file definition is generated and only those elements that match the first element named are included in the index.
[See Section 5.1.6.4, 5.1.6.5 and 5.1.6.6 for an explanation of how INDEX is affected by the BREAKUP, WORD and TRUNCATE attributes. See Section 4.4 for an explanation of the PASSER attribute, which determines what type of pointer information is passed to the index. See Chapter B.7 of "SPIRES File Definition" for complete details about index records and Chapter B.8 for information about the linkage section. See Chapter C.13.3 for details about index information packets.]
If you want an index to be immediately updated every time a record is changed that would affect that index, use the IMMEDIATE INDEX attribute instead of the INDEX attribute.
The syntax is simply:
IMMEDIATE INDEX
It is used just like the INDEX attribute and creates a simple index with the appropriate linkage section, including the IMMEDIATE statement.
If you are passing more than one element to the same index, and you want it to be an immediate index, use the IMMEDIATE INDEX attribute for the first element that occurs in the input file and the INDEX attribute with the "element-name" option for the rest of the elements. The result is an immediate index containing all the specified elements. For example,
ELEMENT NAME/ IMMEDIATE INDEX ELEMENT STATE/ INDEX NAME
This creates a single immediate index that includes both the NAME and STATE elements.
See B.12 of "SPIRES File Definition" or [EXPLAIN IMMEDIATE INDEXING.]
The RECNAME attribute is used to specify a record name for the index record.
The syntax of RECNAME is:
INDEX [element-name]/ RECNAME record-name
where "record-name" is 6 or fewer characters. If no RECNAME is specified, the File Definer assigns a name in the form "ZINnn" where "nn" is the logical record number (e.g., ZIN01, ZIN02, etc.). This attribute allows you to later specify the index record as a goal record or to add indexes after records have been added to to the file. [See 7.4.]
The INDEX * attribute creates a goal-index. This allows users to search for records using record-key criteria in a FIND command. The goal record itself is used as the index. The INDEX * attribute is used with the KEY element in the goal record.
Creating a goal-index is more efficient than simply indexing the key element, because a separate index record-type is not created. The goal record-type is used as its own index. A goal-index also acts as an immediate index.
The syntax is simply:
INDEX *
For example,
ELEMENT SSN/ KEY/ INDEX *
See Chapter B.8.2.1 of "SPIRES File Definition" or [EXPLAIN GOAL-INDEX, DETAILS FOR CODING.]
The INDIRECT attribute creates an indirect index in the linkage section of your file definition. Indirect indexes allow you to use an index for one subfile as an index for a second subfile, when the index keys match the keys in the second subfile's goal record-type.
The syntax is:
INDIRECT subfile-name,indirect-index[,search-terms]
For example, suppose you have two subfiles, STUDENTS and COURSES. Here are the relevant elements and indexes of each:
STUDENTS COURSES
Elements: Elements:
STUDENT.ID (key) COURSE.ID (key)
COURSE.ID PROFESSOR
Indexes: Indexes:
COURSE.ID PROFESSOR
Because the key values appearing in the COURSE.ID index in the STUDENTS subfile are the same as the keys of goal records in the COURSES subfile, the indirect search technique can link the subfiles. That would allow the PROFESSOR index to be used as an index for the STUDENTS subfile (even though the index was defined in the COURSES subfile).
Here is how to specify the indirect index in the File Definer:
SUBFILE STUDENTS GOAL REC01 KEY STUDENT.ID ELEMENT COURSE.ID/ INDIRECT COURSES,PROFESSOR GOAL REC02 SUBFILE COURSES KEY COURSE.ID ELEMENT PROFESSOR/ INDEX
The PROFESSOR index will be included in the list of indexes for the STUDENTS subfile when the SHOW INDEXES command is used.
Note that you do not need to include the INDEX attribute for the indirect index. However, if the index is an immediate index, you should include the IMMEDIATE attribute in the indirect index specification. For example,
ELEMENT COURSE.ID/ IMMEDIATE/ INDIRECT COURSES,PROFESSOR
See Chapter C.12a in "SPIRES File Definition" or [EXPLAIN INDIRECT SEARCHING.]
The REPARSE attribute creates a linkage section for index reparsing. Reparsing is a technique by which a search value entered by a user can be transformed into a new search expression. The value of reparsing is its ability to disguise a search involving multiple indexes, sub-indexes, or qualifiers as a simple search issued by the user.
The syntax of REPARSE is:
REPARSE userproc-name, searchterm
where "userproc-name" is the name of the userproc that manipulates the user's search value. "Searchterm" is the searchterm that is identified in the userproc, and is the searchterm that would be entered by the user. [See 5.4.2.]
For example, suppose you have a subfile with a CODE element whose values are the numbers 1 through 10, standing for various priority codes. You could use the REPARSE attribute to define a PRIORITY index to allow users to search for "low," "medium," or "high" priority items.
ELEMENT CODE/ SINGLE/ INTEGER/ RANGE 1,10/ REPARSE CONVERT, PRIORITY USERPROC CONVERT IF $CAP($VAL) = LOW THEN SET VAL 'CODE >= 1 AND <= 4' THEN RETURN IF $CAP($VAL) = MEDIUM THEN SET VAL 'CODE > 4 AND <= 7' THEN RETURN IF $CAP($VAL) = HIGH THEN SET VAL 'CODE > 7' THEN RETURN END
Note that you do not need to include the INDEX attribute when you use the REPARSE attribute. The input line shown above will create both a CODE index (allowing searches for the numbers 1 through 10) and a PRIORITY index (allowing searches for low, medium, and high). The search FIND PRIORITY LOW, for example, would retrieve items with CODE values 1 through 4.
[EXPLAIN $REPARSE PROC.]
All elements may by classified as a particular type in the File Definer. That is, the element value will always be the same type of value -- a date, or an integer, or a dollar figure, for example. Element types are specified by an attribute following the ELEMENT keyword; only one type attribute may appear for each element. The File Definer adds appropriate processing rules to the element definition to test the element value for proper form and, in some cases, convert the element value to a form more efficient for storage. For some types, a LEN statement is added [See Appendix B]. File Definer also adds default VALUE-TYPE info-elements to the element information packet, based on the element type. [See 5.1.9.9.] If no type is specified for an element, the File Definer assumes TEXT; if more than one type is specified for an element, all but the last type specified is ignored.
Valid element types are:
TEXT DOLLAR STRUCTURE SLOT DATE INTEGER ENCODE SLOTCHECK TIME REAL YESNO PACKED ACCOUNT HEX XEQ DECIMAL NAME BITS
[See Chapter B.4 of "SPIRES File Definition" for information about Processing Rules.]
TEXT is the default element type. No processing rules are added to the element, so any element value is accepted.
The DATE attribute adds input and output processing rules to test that the value is a valid date and to convert it to a four-byte hexadecimal value for storage. It also supplies a LEN=4 default.
The syntax of DATE is:
DATE [ADD|UPDATE]
For example:
ELEMENT BIRTHDATE/ DATE
Values may be input in any recognizable date form: for example, May 6, 1980, 05/06/80, 6-5-80 (the Canadian date form; equivalent to 05/06/80), 6 May 1980. Values are output in the form MM/DD/CCYY; if CC is 19, it is suppressed.
If DATE is followed by ADD, the element value is set to the current date when the record is added, if no other value is input by the user. If DATE is followed by UPDATE, the element value is replaced by the current date whenever a record is added or updated; any user supplied value is discarded. The File Definer automatically provides a SUPPLIED info-element statement in the element information packet when DATE ADD and DATE UPDATE attributes are used. [See 5.1.9.13.]
For example:
ELEMENT DATE.ADDED/ DATE ADD ELEMENT DATE.UPDATED/ DATE UPDATE
[EXPLAIN $DATE PROC or EXPLAIN $DATE.OUT PROC.]
The TIME attribute adds input and output processing rules to test that the value is a valid time and to convert it to a two-byte hex or four-byte binary value for storage. It also supplies a LEN=2 or LEN=4 default.
The syntax of TIME is:
TIME [ADD|UPDATE|HOURS.FIRST|SECONDS.LAST|INT.ADD| ...
... INT.UPDATE|INT.HOURS.FIRST|INT.SECONDS.LAST]
The default, if no parameter follows the TIME attribute, is HOURS.FIRST processing.
For example:
ELEMENT TIME.SPENT/ TIME
Values for the TIME.SPENT element may be input in the form HOURS:MINUTES:SECONDS, HOURS:MINUTES, or HOURS. That is, a value entered as 5:26 will be interpreted as five hours and twenty-six minutes.
If TIME is followed by SECONDS.LAST, values for the element may be input in the form HOURS:MINUTES:SECONDS, MINUTES:SECONDS, or SECONDS. That is, a value entered as 5:26 will be interpreted as five minutes and twenty-six seconds.
If TIME is followed by ADD, the element value is replaced by the current time when the record is added, if no other value is input by the user. If TIME is followed by UPDATE, the element value is replaced by the current time whenever a record is added or updated; any user supplied value is discarded. For example:
ELEMENT TIME.ADDED/ TIME ADD ELEMENT TIME.UPDATED/ TIME UPDATE
The INT.ADD, INT.UPDATE, INT.HOURS.FIRST, and INT.SECONDS.LAST parameters specify that the time values are to be stored as four-byte integers. You should use one of these parameters if you expect to do any computations with the time value, since it is difficult to do arithmetic with the hex forms.
For all parameters, values are output in the form HH:MM:SS. If an invalid form is entered, non-digits and ":" are discarded and a valid time form is created from what remains; if no valid time value remains, the value is set to 00:00:00.
The File Definer automatically provides a SUPPLIED info-element in the element information packet when TIME ADD, TIME UPDATE, TIME INT.ADD, and TIME INT.UPDATE attributes are used. [See 5.1.9.13.]
[EXPLAIN $TIME PROC or EXPLAIN $TIME.OUT PROC.]
The ACCOUNT attribute adds an Inclose rule to generate a value for the element consisting of the logged-on account number.
The syntax of ACCOUNT is:
ACCOUNT [ADD|UPDATE|ONCE|ALWAYS]
For example:
ELEMENT ADD.ACCT/ ACCOUNT ADD
If ACCOUNT is followed by ADD (or ONCE), the element value is generated when no other value for the element exists. If ACCOUNT is followed by UPDATE (or ALWAYS), the element value is replaced by the logged-on account whenever a record is added or updated; any user supplied value is discarded. The File Definer automatically provides a SUPPLIED info-element statement in the element information packet when the ACCOUNT attribute is used. [See 5.1.9.13.]
[EXPLAIN $GEN.ACCT PROC.]
The NAME attribute adds input and output processing rules to convert personal names to a standard form before storage. Values are stored and output in the form LAST, FIRST MIDDLE. This allows sequencing of element values by last name and help create efficient and flexible personal name indexes. For example:
ELEMENT FULL.NAME/ NAME ELEMENT SPOUSE/ NAME
If a NAME type element is indexed, the index is constructed with a sub-index and appropriate SEARCHPROCS and PASSPROCS, allowing standard personal name searching, described in "SPIRES Searching and Updating", Section B.3.5.2.
[EXPLAIN $NAME PROC.]
The DOLLAR attribute adds input and output processing rules to test dollar and cents quantities and convert the value to a four-byte binary equivalent for storage. It also adds a LEN=4 statement. Values may be input in any of the following ways: $D, $D., $D.CC, or $.CC, where D is a string of digits, CC is two digits, and $ is an optional dollar sign. Values are output in the form $D.CC. [See 5.1.6.11.] For example:
ELEMENT COST/ DOLLAR
[EXPLAIN $DOLLAR PROC or EXPLAIN $DOLLAR.OUT PROC.]
The INTEGER attribute adds input and output processing rules to produce integer constants. The syntax of INTEGER is:
INTEGER [n]
where "n" is an optional length value.
If no length is specified on the INTEGER attribute, then a default four-byte result is stored. You may specify byte lengths of 1, 2 or 4. The following range values are acceptable:
LENGTH = 1 0 through 255 LENGTH = 2 -32768 through 32767 LENGTH = 4 -2147483647 through 2147483647
Warning: It is recommended that you use the default length of 4. With lengths of 1 or 2, some value translations take place if the input value is outside a minimum/maximum stored range but within an outside acceptable range. For example, if the length is 1 then negative values in the range of -1 through -256 are translated into a field of 255 through 0, but no error flag is set.
[EXPLAIN $INT PROC.]
The REAL attribute adds input and output processing rules to specify that floating point conversion is to take place and adds a LEN=4 statement. The single precision result is stored. The element value is rejected if it contains unrecognizable characters. For example:
ELEMENT NUMBER/ REAL
[EXPLAIN $REAL PROC.]
The HEX attribute adds input and output processing rules to convert the element value to and from hexadecimal format for storage. It also adds a LEN=4 statement. For example:
ELEMENT LOCATION/ HEX
[EXPLAIN $HEX PROC.]
The BITS attribute adds input and output processing rules to allow you to store data in a bitmask configuration. The length in bytes of the mask is determined by the value assigned to either the BITS attribute or the LENGTH attribute. [See 5.1.2.]
The syntax of BITS is:
BITS [n]
where "n" is an integer value. For example:
ELEMENT MASK/ BITS 2 ELEMENT MASK/ BITS/ LENGTH 2
Variable length BITS type elements are allowed, so a LENGTH value need not be specified.
[EXPLAIN $BITS PROC.]
The ENCODE attribute adds input and output processing rules and a LEN=1 statement that provide efficient storage of element values if it can be determined at the time the file is defined that the element value will always be one of a finite number (up to 255) of values.
The syntax of ENCODE is:
ENCODE string,string,string. . .
where "string" is one of a series of possible values for the element. No single string can be more than 16 characters. Any value that contains special characters or blanks must be enclosed in quotes. For example:
ELEMENT ANIMAL/ ENCODE DOG,CAT,FISH,BIRD,HORSE,OTHER ELEMENT SIGN/ ENCODE '$','%','ABC&XYZ'
When a value is input for the element, SPIRES stores only an integer value that points to the relative position of the value in the list. On output the proper value from the list is displayed. If the value does not appear in the list, the element is rejected with a serious error.
Case is significant for ENCODE values -- if "CAT" appears in the list of ENCODE values, an element value of "cat" is rejected. However, if the CAPITALIZE attribute precedes the ENCODE attribute, then all incoming values are converted to uppercase before being compared to the ENCODE values. For example:
ELEMENT ANIMAL/ CAPITALIZE/ ENCODE DOG,CAT,FISH,BIRD,HORSE,OTHER
If an encoded element is indexed, the same INPROC and OUTPROC rules are added to the index record. This allows the proper values to be displayed when the index is browsed.
[EXPLAIN $ENCODE PROC.]
The YESNO attribute adds input and output processing rules to limit the element values to either YES or NO. It also supplies a LEN=1 default. Values may be input as YES, YE, Y, NO or N, are stored as Y or N, and are output as YES or NO. For example:
ELEMENT ANSWER/ CAPITALIZE/ YESNO
[EXPLAIN $YESNO PROC.]
The XEQ attribute indicates that the element's values are SPIRES protocol commands to be executed. An element of type XEQ can appear only in the REQUIRED section and must be the first element following the KEY element, which also must be in the REQUIRED section; no FIXED elements can appear. For example:
ELEMENT COMMAND/ XEQ
See Chapter C.4 of "SPIRES File Definition" for a full explanation of how to add executable elements to your file definition or [EXPLAIN TYPE=XEQ STATEMENT.]
If no element is designated as the record key, [See 5.1.1.] the File Definer assumes that the record is a SLOT type. For a SLOT record-type, SPIRES assigns a unique integer key to each record added, and this integer key becomes an element with the name of the GOAL. If you would like to assign a different name to this element, you may input the element name with the ELEMENT or KEY keyword and assign it the type attribute SLOT. [See 5.1.1.] If this attribute is used for an element (whether it is specified with the ELEMENT or the KEY keyword), no other element may be designated as the key.
Type SLOTCHECK also creates a unique integer key, but adds a "check digit" to the right end of the number. This number is computed from the other digits in the number and creates an extra step of verification for the slot number.
SLOT and SLOTCHECK cannot both be specified for the same record.
The following examples are all valid specifications for defining slot-type files:
ELEMENT NUMBER/ SLOT ELEMENT TRANS.NO/ SLOTCHECK KEY NUMBER/ SLOT
See Section 5.1.1 for details about defining keys.
See Section B.2.2. of "SPIRES File Definition" for a complete explanation of SLOT and SLOTCHECK or [EXPLAIN SLOT STATEMENT.] and [EXPLAIN SLOTCHECK STATEMENT.]
The STRUCTURE attribute indicates that the element is a structure. The structure is made up of all elements defined after the STRUCTURE keyword until an END keyword is encountered. Like KEY, STRUCTURE may be used as an attribute, or as a keyword in place of the ELEMENT keyword.
Elements within a structure may be categorized as FIXED, REQUIRED, OPTIONAL or VIRTUAL. An element may be designated as the KEY [See 5.1.1.] of the structure, but must be the first element in the structure. For example:
ELEMENT PERSON/ STRUCTURE or STRUCTURE PERSON
FIXED
ELEMENT NAME/ KEY
OPTIONAL
ELEMENT ADDRESS
END
It is also possible to define nested structures in the File Definer. An END keyword must be used to end each structure. For example:
ELEMENT PERSON/ STRUCTURE
ELEMENT NAME
ELEMENT LOCATION/ STRUCTURE
ELEMENT ADDRESS
ELEMENT PHONE
END
END
Structures are defined in the File Definer quite differently than they are in native file definition language. In the File Definer, all of the elements that make up the structure are defined at the same time as the structure name; in file definition language, the structure is named in the primary element list and the structure elements are defined later. [See 5.3 for information about adding processing rules to structures.]
The File Definer allows you to define "floating structures". These are structures that are used in more than one place in the record; that is, there is only a single structure definition, but it is used for several elements. In the File Definer, you only define the structure elements once; all other times you reference that structure, simply include END instead of a structure definition. For example,
NAME
ELEMENT ADDRESS/ STRUCTURE
ELEMENT STREET
ELEMENT CITY
ELEMENT STATE
END
ELEMENT PHONE.HOURS/ STRUCTURE
ELEMENT PHONE
ELEMENT HOURS
ELEMENT ADDRESS/ STRUCTURE
END
END
END
The ADDRESS structure occurs at the record level and within the PHONE.HOURS structure. The elements of this structure are only defined the first time it is referenced; this creates the structure definition in the file definition. The second time it occurs, no elements are included for it. [EXPLAIN FLOATING STRUCTURES for more information about how this type of structure is used.]
[See 5.1.7a for instructions on how to define phantom structures.] [See Chapter B.3 of "SPIRES File Definition" for an explanation of structures.]
The PACKED attribute adds input and output processing rules to convert numeric values to packed decimal form for storage. The syntax of PACKED is:
PACKED [n]
where "n" is the number of bytes of storage. The default is a variable length element with the minimum length necessary stored for each value. For example:
ELEMENT SALARY/ PACKED 5/ EDIT '$ZZZ,ZZZ.99'/ INDEX
The input value can contain only leading blanks, a sign (+ or -) and the numbers 0-9. The maximum length for a packed value is 256 bytes.
See SPIRES Technical Notes, Chapter 18 for detailed information on packed decimal values.
[EXPLAIN $PACK PROC.]
The DECIMAL attribute adds input and output processing rules to store numeric values when the value may be a non-integer number. Packed decimal conversion takes place on input. The element value is rejected if it contains unrecognizable characters.
The syntax of DECIMAL is:
DECIMAL m.n
where "m" is the number of places allowed to the left of the decimal point, and "n" is the number of places allowed to the right. For example:
ELEMENT SALARY/ DECIMAL 4.5
allows any value between -9999.99999 and 9999.99999.
See SPIRES Technical Notes, Chapter 18, for detailed information on packed decimal values.
Warning: If you index a DECIMAL-type element, any negative values are interleaved with positive ones in the index. That is, the number -2 is indexed between 1 and 3. Note that this is not a problem for INTEGER-type elements.
[EXPLAIN $DECIMAL PROC.]
Processing rule attributes may be added as element attributes to test and convert element values beyond that done by the element type attributes. One element may have several processing rule attributes specified for it. Processing rule attributes can be applied to the value either on input or output, unless otherwise noted. The default direction for the rules described below is input only.
If the rule is to apply to output only, the attribute must be preceded by OUTPUT. The attribute then applies only to output. For example:
ELEMENT ANIMAL/ LENGTH 10/ OUTPUT CAPITALIZE
The following rules apply if the value of a processing rule attribute contains the specified special characters:
INSERT ', M.D.',END
CHANGE 'I/O''s','input/output cycles'
Processing rule attributes sometimes have a series of values separated by commas, in which case the above rules apply to each value in the series. For example:
ELEMENT A/ ENCODE LIKE,'LOVE''HATE'/ . . .
[See Chapter B.4 of "SPIRES File Definition" for a complete explanation of processing rules.]
The CAPITALIZE attribute adds the processing rule to cause lowercase letters in the element value to be converted to uppercase.
The syntax is:
CAPITALIZE [FIRST.WORD|EACH.WORD]
The CAPITALIZE attribute by itself causes all letters to be converted to upper case. By adding the FIRST.WORD operand, only the first character of the first word of the element value is capitalized. The EACH.WORD operand causes the first letter of each word in the element value to be capitalized.
For example:
ELEMENT TITLE/ CAPITALIZE EACH.WORD
[EXPLAIN $CAP PROC.]
The LOWER attribute adds the processing rule to cause all uppercase letters in the element value to be converted to lowercase. For example:
ELEMENT TITLE/ LOWER
[EXPLAIN $LOWER PROC.]
The SQUEEZE attribute adds the processing rule to cause all groups of more than one blank to be replaced by a single blank. All leading and trailing blanks are stripped. For example:
ELEMENT TITLE/ CAPITALIZE/ SQUEEZE
[EXPLAIN $SQU PROC.]
The BREAKUP attribute adds the processing rule that allows you to enter a series of values for the element in a single line, separated by one of several delimiter characters. BREAKUP cannot be specified as an output rule.
The syntax of BREAKUP is:
BREAKUP [string]
where "string" is one or more characters.
The character string is a list of delimiters and should be enclosed in apostrophes if it contains special characters. [See 5.1.6.] If no delimiter is specified, the File Definer assumes ' ' ( a single blank). For example:
ELEMENT WORD/ BREAKUP $
ELEMENT WORD/ BREAKUP ', '
ELEMENT WORD/ BREAKUP '''' (This provides a break on a
single apostrophe.)
On input of the element value, the input string is broken into separate parts at each occurrence of any one of the delimiters and each part is treated as a separate occurrence of the element. The delimiters and leading and trailing blanks are discarded. On output, the values are reconstructed into a single line separated by the first delimiter in the string.
If the BREAKUP attribute follows the INDEX attribute [See 5.1.4.] the value is not broken up on input to the record, but upon passing to the index; the search value is also broken up in searching commands. For example:
ELEMENT TITLE/ INDEX/ BREAKUP * ELEMENT TITLE/ INDEX/ BREAKUP
[EXPLAIN $BREAK PROC and EXPLAIN $BUILD PROC.]
The WORD attribute adds the processing rule to break the value into separate occurrences of the element at each blank. This is designed especially for creating word indexes, but also works on element input. If the WORD attribute appears before the INDEX attribute (or the INDEX attribute does not appear at all for that element), the attribute applies to element values. If WORD appears after the INDEX attribute, it applies to values as they are passed to indexes.
For example:
ELEMENT WORDS/ WORD
breaks the input value into separate element occurrences, but
ELEMENT TITLE/ INDEX/ WORD
breaks the element value into separate words when creating the index.
The File Definer automatically provides a VALUE-TYPE = WORD statement in the element information packet when the WORD attribute is used. [See 5.1.9.9.]
Apostrophes, hyphens and underscores are changed to nulls; that is, they disappear from the value. The following characters are changed to blank: "/\:,<{[(|)]}>&=;@!?*$^`%~.+#. [See 5.1.6.12 for an explanation of EXCLUDE and additional information on creating efficient word indexes.]
[EXPLAIN $WORD PROC.]
The TRUNCATE attribute is only recognized if INDEX is also specified for the element; it produces the SEARCHPROC rule that allows truncated search of an index.
The syntax of TRUNCATE is:
TRUNCATE [character]
where "character" is a special truncation character to be used in search commands.
Note that truncated searching can be done with the PREFIX operator, whether or not the TRUNCATE attribute is used. For a full explanation of truncated searching, see Section B.3.5.4 of "SPIRES Searching and Updating".
If no value is assigned to TRUNCATE, the File Definer assumes '#'. For example:
ELEMENT WORD/ INDEX/ TRUNCATE ELEMENT WORD/ INDEX/ TRUNCATE *
If both BREAKUP and TRUNCATE are specified for the same element, be sure that the special characters used for them are not the same.
The File Definer supplies a default TRUNCATE index info-element in the index information packet when you define a truncation character other than the default character '#' with the TRUNCATE attribute. [See Chapter C.13.3 of "SPIRES File Definition" for details about index information packets.]
[EXPLAIN $SEARCH.TRUNC PROC.]
The CHANGE attribute adds the processing rule that changes one character string, if found in the element value, to another character string. The attribute values must, therefore, occur in pairs.
The syntax of CHANGE is:
CHANGE string1A,string1B [,string2A,string2B,. . .]
The element value is scanned for the first string; if a match is found, the string in the element value is replaced by the second string of the pair. The second string may be null, which is designated with a pair of apostrophes. If more than one pair is used, no single attribute value can exceed 16 characters. For example:
ELEMENT ADDRESS/ CHANGE ST.,'' ELEMENT SIZE/ CHANGE HUGE,BIG,TINY,SMALL ELEMENT RULE/ CHANGE DON'T,DO NOT
Note that multiple changes affect each other. For example, CHANGE MALE,M,FEMALE,F does not work because FEMALE is changed to FEM by the first pair of values; CHANGE MALE,M,FEM,F works.
[EXPLAIN $CHANGE PROC or EXPLAIN $CHANGE.LIST PROC.]
The INSETL attribute adds the processing rule that allows you to left-justify the element value in a field of a specific length.
The syntax of INSETL is:
INSETL string,n
where "n" is the length of the field and "string" is the character (or character string) used to pad the field so that it is "n" characters long. For example:
ELEMENT AMOUNT/ INSETL 0,5 ELEMENT AMOUNT/ INSETL ' ',12
[EXPLAIN $INSETL PROC.]
The INSETR attribute adds the processing rule that allows you to right-justify the element value in a field of a specific length.
The syntax of INSETR is:
INSETR string,n
where "n" is the length of the field and "string" is the character (or character string) used to pad the field so that it is "n" characters long. For example:
ELEMENT AMOUNT/ INSETR 0,5 ELEMENT AMOUNT/ INSETR ' ',12
[EXPLAIN $INSETR PROC.]
The INSERT attribute adds the processing rule that allows you to insert a character string anywhere in the element value. The syntax of INSERT is:
INSERT string,[LEFT|RIGHT|END|FRONT][,n]
where "n" is the column in the element value at which the string is to be inserted. If LEFT is specified, then the string is inserted to the left of the character in column "n" counting from the left. If RIGHT is specified, then the string is inserted to the right of the character in column "n" counting from the right. If END or FRONT is specified, then no column number should be specified; the string is inserted either at the end or in front of the element value. If only "string" is specified, then FRONT is assumed. For example:
ELEMENT NAME/ INSERT 'SIR ',FRONT ELEMENT CODE/ INSERT -,LEFT,4 ELEMENT NAME/ INSERT ', M.D.',END
[EXPLAIN $INSERT PROC.]
The EDIT attribute adds the processing rule to provide an edit mask for the element value. It is allowed on elements of INTEGER, DOLLAR, DECIMAL, or PACKED types and overrides any default OUTPROCs created by these attributes. EDIT is only allowed as an OUTPROC, so OUTPUT need not precede it in the input file.
The syntax of EDIT is:
EDIT mask[,places]
where "mask" is composed of appropriate mask characters and "places" is the number of decimal places in the stored value. If "places" is not supplied, it is assumed to be zero. The "mask" is not enclosed in apostrophes unless it contains commas.
For example:
EDIT $99.99 EDIT 'ZZZ,ZZZ.99' EDIT 'ZZZ,ZZZ',2
The rules are best explained by examples. Assume that a value of '123456' or '-123456' is input:
EDIT MASK '123456' '-123456' '$ZZ,ZZZ.99' '$ 1,234.56' '$ 1,234.56' '+$ZZ,ZZZ.99' '+$ 1,234.56' '-$ 1,234.56' '-$ZZ,ZZZ.99' ' $ 1,234.56' '-$ 1,234.56' '+++++++.99' ' +1234.56' ' -1234.56' '-------.99' ' 1234.56' ' -1234.56' '$99,999.99' '$01,234.56' '$01,234.56' '$**,***.99' '$*1,234.56' '$*1,234.56' '$$$,$$$.99' ' $1,234.56' ' $1,234.56' '$$$,$$$.99CR' ' $1,234.56 ' ' $1,234.56CR' '$$$,$$$.99-' ' $1,234.56 ' ' $1,234.56-' '$$$,$$$.99DB' ' $1,234.56 ' ' $1,234.56DB'
The resulting value is always the length of the edit mask itself. It is never longer; if the input value is longer than can be expressed in the edit mask, the left-most (most significant) characters of the value are lost.
When the EDIT attribute is used, the File Definer will supply a default EDIT statement in the element information packet. [See 5.1.9.8.]
For detail information about edit masks, [EXPLAIN EDIT MASKS.]
The EXCLUDE attribute adds the processing rule that prevents particular element values from being accepted on input. EXCLUDE cannot be specified as an output rule.
The syntax of EXCLUDE is:
EXCLUDE [string,string,string. . .]
The entire element value is matched against the character strings given as values of the EXCLUDE attribute; if an exact match is found, the element value is discarded. Up to 255 values may be assigned to the EXCLUDE attribute; maximum size for each value is 16 characters. Case is significant for EXCLUDE -- if "MAN" appears in the list of EXCLUDE values, an element value of "man" is not excluded. However, if the CAPITALIZE attribute precedes the EXCLUDE attribute, then all incoming values are converted to upper case before being compared to the EXCLUDE values. For example:
ELEMENT ANIMAL/ CAPITALIZE/ EXCLUDE MAN,WOMAN
If EXCLUDE is used with an element of the ENCODE type, EXCLUDE should precede ENCODE in the attribute list. [See 5.1.5.10.] For example:
ELEMENT ANIMAL/ EXCLUDE MAN,WOMAN/ ENCODE DOG,CAT
If the EXCLUDE attribute follows an INDEX attribute for an element, the rule applies not to the element value on record input but to the value being passed to the index. This allows common words to be excluded from the index, for example. If no value is given for EXCLUDE, the following list of common words is excluded: A, TO, FOR, WERE, WAS, BUT, AND, ARE, THE, AS, OR, AN, AT, BY, IN, OF, ON, AM, BE, IS. The combination of INDEX/ WORD/ EXCLUDE can be used to create an efficient word index. [See 5.1.6.5 for details about the WORD attribute.] For example:
ELEMENT TITLE/ INDEX/ WORD/ EXCLUDE
[EXPLAIN $EXCLUDE PROC.]
The INCLUDE attribute adds the processing rule that ensures that the element value matches one of the values assigned to the INCLUDE attribute. INCLUDE cannot be specified as an output rule.
The syntax of INCLUDE is:
INCLUDE string [,string,string. . .]
The entire element value is matched against the character strings given as values of the INCLUDE attribute; if an exact match is not found, the element value is rejected with a serious error. Up to 255 values may be assigned to the INCLUDE attribute; maximum size for each value is 16 characters. Case is significant for INCLUDE -- if "MAN" appears in the list of INCLUDE values, an element value of "man" is not included. However, if the CAPITALIZE attribute precedes the INCLUDE attribute, then all incoming values are converted to upper case before being compared to the INCLUDE values. For example:
ELEMENT ANIMAL/ CAPITALIZE/ INCLUDE MAN,WOMAN
[EXPLAIN $INCLUDE PROC.]
The RANGE attribute adds the processing rule that tests whether a number value falls within a specified range. If an element value falls outside this range, it is rejected.
The syntax of RANGE is:
RANGE m,n
where "m" is the minimum value allowed and "n" is the maximum.
For example:
ELEMENT AMOUNT/ INTEGER/ RANGE 1,50
Unless the element has been assigned the INTEGER or REAL type attribute, the RANGE attribute is ignored.
[EXPLAIN $RANGE PROC.]
The LSTRING attribute adds the processing rule that truncates the element value at a specified length, giving the "left string" portion of the value.
The syntax of LSTRING is:
LSTRING n
where "n" is the length of the truncated value. For example:
ELEMENT DAY/ LSTRING 3
[EXPLAIN $LSTR PROC.]
The TRANSLATE attribute enables you to change a single character in an element value to another character.
The syntax of TRANSLATE is:
TRANSLATE input set,output set
where "input set" is the set of characters that are looked for in the element value and "output set" is the set of characters that replaces the input set.
The value is scanned for every character in the input string; if a match is found, it is replaced with the corresponding character in the output string. If the output string is a single character, then it replaces every character in the input string. Unless the output string is a single character, both strings must be of equal length. For example:
ELEMENT WORD/ TRANSLATE @$%^&*,# ELEMENT NAME/ TRANSLATE 123,abc
In the first example, each character in the first string is translated to "#"; in the second example, "1" is translated to "a", "2" to "b" and "3" to "c".
TRANSLATE differs from the CHANGE attribute [See 5.1.6.7.] in that CHANGE substitutes an entire string for another string which need not be of the same length; TRANSLATE substitutes only single characters.
[EXPLAIN $TRANS PROC.]
The LOOKUP attribute accesses a record from another record-type and either verifies that the element value in the current record matches the key of an element in the second record-type or replaces the current element value with an element value from the second record-type. If a match is not found, the record is rejected with a serious error.
The syntax of LOOKUP is:
LOOKUP {VERIFY|REPLACE},record-name[,element name]
where "record name" is the name of the record [See 4.1.] being accessed and "element name" is the name of an element in the accessed record. An element name is specified only when the REPLACE option is used; if it is a multiply occurring element, only the first occurrence is accessed. For example:
ELEMENT STATE/ LOOKUP VERIFY,REC02 ELEMENT STATE/ LOOKUP REPLACE,REC02,STATE
The first example accesses a record in the record-type REC02 with a key that matches the current element value, verifying that the current element value is found, but not replacing it. In the second example, if a match is found for the element value in REC02, the current value is replaced with the value of STATE found in the matching record in REC02 (replacing "CA" with "California", for example). [See 4.7 for an explanation of how to define multiple goal record-types in a file with the File Definer.]
You can also specify the record number instead of the record name in the LOOKUP attribute, but remember that SPIRES rearranges record types alphabetically so you must be sure that the number you use in this attribute is the actual number of the record type that SPIRES will use when it compiles the file definition. If you plan to index the element that uses the LOOKUP attribute (in the above example, STATE), you must either use the record number or have the table record come before the goal record.
[EXPLAIN $LOOKUP PROC.]
The MSG attribute allows you to insert a customized error message to be output if a processing rule detects an error. If not included, the standard SPIRES error message is used. EXPLAIN ERROR MESSAGES for information about standard SPIRES error messages. The syntax of MSG is:
MSG string
Only one message is allowed per element; it may be up to 128 characters long. The message does not need to be enclosed in apostrophes unless it contains a "/".
ELEMENT SEASON/ LSTRING 2/ MSG Must be either WI,SP,SU,FA/+ INCLUDE WI,SP,SU,FA
For element type attributes, MSG may be added with no value and the following defaults are supplied:
DATE -- 'Invalid date value' TIME -- 'Invalid Time value' NAME -- 'Invalid form of name' DOLLAR -- 'Invalid Dollar value' INTEGER -- 'Invalid Integer value' REAL -- 'Illegal Floating Point value' HEX -- 'Illegal HEX number value' BITS -- 'Bit value too large' ENCODE -- 'Invalid entry value' YESNO -- 'Value must be Yes or No' PACKED -- 'Invalid Packed Decimal value' DECIMAL -- 'Invalid Decimal value'
For example:
ELEMENT ANSWER/ YESNO/ MSG
[EXPLAIN $MSG PROC.]
The DEFAULT attribute allows you to specify a default value for the element if no element value is input.
The syntax of DEFAULT is:
DEFAULT string
where "string" is the element value to be input if one is not added by the user. The default element value may be up to 255 characters long. Remember that if you specify a DEFAULT value, you create at least one occurrence of the element.
The File Definer automatically provides a DEFAULT info-element statement in the element information packet when the DEFAULT attribute is used. [See 5.1.9.12.]
For example:
ELEMENT PET/ DEFAULT NO PET
[EXPLAIN $DEFAULT PROC.]
The CLOSEOUT attribute allows you to add a CLOSEOUT rule for an element. CLOSEOUT (or INCLOSE) rules are INPROC rules that "close-out" the processing rule string and hence must be the last attribute in a string of attributes. Closeout rules can supply values such as date or time; they can supply a value for one element that is the number of occurrences of another element; they can supply additional values or delete values if an element doesn't occur a specified number of times; they can be used to sort multiple occurrences of an element of a structure by its key value.
The syntax of CLOSEOUT is:
CLOSEOUT rule
where "rule" is a single CLOSEOUT rule. This attribute may be included more than once for a single element. The rule itself must be coded in file definition language.
Care should be taken with this attribute, since other attributes may also create CLOSEOUT rules of their own. (For example, ACCOUNT, DATE ADD, DATE UPDATE, TIME ADD, TIME INT.ADD, TIME UPDATE, TIME INT.UPDATE.) CLOSEOUT rules are added to the end of the other processing rule attributes specified; they do not override any other File Definer attributes or processing rules. For example:
ELEMENT ANIMAL/ OCCURRENCE 10/ EXCLUDE MAN,WOMAN/ CLOSEOUT $SORT
See Section B.4.8 of "SPIRES File Definition" or [EXPLAIN INCLOSE RULES.]
The REDEFINES attribute enables you to apply a set of processing rules to an already existing element value to create a new element. The new element must occur in the VIRTUAL section.
The syntax of REDEFINES is:
REDEFINES element-name
where "element-name" is the name of the element being redefined, which must be non-VIRTUAL. For example:
ELEMENT LAST.NAME.LAST/ REDEFINES LAST.NAME.FIRST OUTPROC $NAME(FIRST)
See Section C.11.2.3 of "SPIRES File Definition" or [EXPLAIN REDEFINED ELEMENTS.]
The SUBFILE and SUBGOAL attributes access records from another record-type to create a phantom structure. An element defined as a phantom structure must be in the VIRTUAL section, and the element must also have a REDEFINES attribute. [See 5.1.7.]
Use SUBGOAL if you are accessing a record-type in the same file. Use SUBFILE if you are accessing the goal record-type in a different subfile (which may or may not be in the same file).
The syntax is:
SUBFILE subfile-name
or
SUBGOAL record-type-name
For example, suppose you have two subfiles, one with records about automobile drivers and the other with records about their cars. The two subfiles have the following elements and indexes:
CARS subfile DRIVERS subfile AUTO.LICENSE (key) DRIVERS.LICENSE (key) AUTO.COLOR (indexed) DRIVERS.NAME DRIVERS.LICENSE DRIVERS.EYE.COLR
(The values in the two DRIVERS.LICENSE elements are identical.)
The goal record definition for the CARS subfile could include a phantom structure using the common element DRIVERS.LICENSE:
SUBFILE CARS GOAL REC01 KEY AUTO.LICENSE ELEMENT AUTO.COLOR/ INDEX ELEMENT DRIVERS.LICENSE VIRTUAL ELEMENT LINK.TO.DRIVERS/ SUBFILE DRIVERS/ REDEFINES DRIVERS.LICENSE SUBFILE DRIVERS GOAL REC02 KEY DRIVERS.LICENSE ELEMENT DRIVERS.NAME ELEMENT DRIVERS.EYE.COLR
The LINK.TO.DRIVERS element in the CARS subfile is a phantom structure. It consists of a goal record in the DRIVERS subfile that is accessed by the DRIVERS.LICENSE element that is common to both CARS and DRIVERS.
See Chapter 23 of "SPIRES Technical Notes" or [EXPLAIN PHANTOM STRUCTURES.]
The PRIV-TAG attribute allows you to assign a number to the element; the number can later be referenced by CONSTRAINT, NOUPDATE or NOSEARCH statements in the subfile security specifications. [See 6.5.] The syntax of PRIV-TAG is:
PRIV-TAG n
where "n" is an integer between 1 and 255. Only one PRIV-TAG number may be assigned to an element. For example:
ELEMENT SALARY/ PRIV-TAG 25
See Section B.9.4 of "SPIRES File Definition" or [EXPLAIN PRIV-TAG STATEMENT.]
Element information packets consist of statements ("info-elements") that provide descriptive information about the element or provide values to other pieces of a SPIRES application, such as a protocol or format. Element information is also accessed by the SHOW ELEMENT INFORMATION command. The following element attributes are used to generate info-element statements.
HEADING WIDTH INFO EDIT INPUT-OCC
COL-HEADING ADJUST VALUE-TYPE INFO DEFAULT
NOTE INDENT INFO INDEX SUPPLIED
MAXROWS
The INFO prefix is used with the EDIT, INDEX, and DEFAULT attributes to distinguish them from other element attributes of the same name. For clarity, you may use the INFO prefix with all of the attributes listed above if desired.
Note that the File Definer often provides default values for the ADJUST, EDIT, VALUE-TYPE, INDEX, DEFAULT, and SUPPLIED info-elements, based on other element attributes. [See Appendix C]
The EXPLAIN keyword (in the element specification section) also creates an info-element statement, specifically the DESCRIPTION info-element. [See 5.5.]
The following rules apply if the value of an element information attribute contains the specified special characters:
HEADING 'Name and/or title'
HEADING 'Employee''s classification and/or salary'
Here is an example of the use of element information attributes:
ELEMENT COURSE.NUMBER/ HEADING Course Number/+ COL-HEADING "Course//Number"/ WIDTH 8/ ADJUST RIGHT/+ INPUT-OCC 1 ELEMENT COURSE.DESC/ HEADING Course Description/+ COL-HEADING Description/ WIDTH 40/ ADJUST ALIGN/+ INDENT -2/ MAXROWS 5
[EXPLAIN INFO-ELEMENTS.]
The HEADING attribute adds the HEADING info-element to the information packet for that element. This info-element is used by the $REPORT format as a column heading if no COL-HEADING info-element exists. It is also used by the $PROMPT format as the value with which to prompt the user during input, and a heading for the element value when records are displayed.
The syntax is:
HEADING string
The string may be any length, but since column headings in $REPORT are limited to 36 characters, a warning message appears if you exceed that length when the file definition is added to the FILEDEF subfile.
For example,
ELEMENT COURSE.NUMBER/ HEADING Course Number
provides a more attractive label for the element than the mnemonic.
[EXPLAIN HEADING INFO-ELEMENT.]
The COL-HEADING attribute adds the COL-HEADING info-element to the information packet for that element. This info-element, if specified, is used by the $REPORT format as a column heading in place of the HEADING info-element.
The syntax is:
COL-HEADING string
or
COL-HEADING "string//string//string..."
The second form is used to create a multiple-row heading. The string may be any length, but since column headings in $REPORT are limited to 36 characters, a warning message appears if you exceed that length when the file definition is added to the FILEDEF subfile. Note that $REPORT currently does not support column headings of more than three rows.
For example,
ELEMENT COURSE.NUM/ HEADING Course Number/ COL-HEADING "Course//Number"
[EXPLAIN COL-HEADING INFO-ELEMENT.]
The NOTE attribute adds the NOTE info-element to the information packet for that element. This info-element usually contains a brief description of the element, supplementing the element name itself.
The syntax is:
NOTE string
For example,
ELEMENT COURSE.NUM/ NOTE Official University course number
[EXPLAIN NOTE INFO-ELEMENT.]
The WIDTH attribute adds the WIDTH info-element to the information packet for that element. This info-element is used by the $REPORT format as the width for the element (unless it is overridden by a width value in a SET FORMAT $REPORT command).
The syntax is:
WIDTH n
where "n" is a positive integer.
For example,
ELEMENT COURSE.NUMBER/ WIDTH 30
[EXPLAIN WIDTH INFO-ELEMENT.]
The ADJUST attribute adds the ADJUST info-element to the information packet for that element. This info-element is used by the $REPORT format to determine the adjustment of the value in its display (unless it is overridden by an adjust value in a SET FORMAT $REPORT command).
The syntax is:
ADJUST {LEFT|RIGHT|CENTER|TRUNCATE|JUSTIFY|ALIGN}
For example,
ELEMENT COURSE.NUMBER/ ADJUST CENTER
The File Definer supplies a default ADJUST = RIGHT info-element for the following element types: INTEGER, REAL, DOLLAR, PACKED, DECIMAL, SLOT, AND SLOTCHECK.
[EXPLAIN ADJUST INFO-ELEMENT.]
The INDENT attribute adds the INDENT info-element to the information packet for that element. This info-element is used by applications such as the $REPORT format to determine the indention of values that wrap into subsequent rows on output.
The syntax is:
INDENT n
where "n" is a positive or negative integer. A positive integer causes the first row of the value to be indented. A negative integer causes subsequent rows to be indented.
For example,
ELEMENT COURSE.DESC/ INDENT -3
[EXPLAIN INDENT INFO-ELEMENT.]
The MAXROWS attribute adds the MAXROWS info-element to the information packet for that element. This info-element is used by the $REPORT format to determine the maximum number of rows to allow for all occurrences of the element for a single record.
The syntax is:
MAXROWS n
where "n" is a positive integer.
For example,
ELEMENT COURSE.DESC/ INDENT -3/ MAXROWS 10
[EXPLAIN MAXROWS INFO-ELEMENT.]
The INFO EDIT attribute adds the EDIT info-element to the information packet for that element. This info-element provides an edit mask for applications to apply to the element value. Note that you do not usually need to use this attribute since the File Definer will supply a default INFO EDIT statement matching the edit mask specified with the EDIT attribute. [See 5.1.6.11.]
The syntax is:
INFO EDIT edit-mask[/divisor]
where "edit-mask" is a valid SPIRES edit mask and "divisor" is an integer representing a power-of-ten divisor by which the element should be divided before the edit mask is applied. You should enclose the edit mask in apostrophes if it includes a divisor.
For example,
ELEMENT COST/ EDIT $99.99/ INFO EDIT $99.99
[EXPLAIN EDIT INFO-ELEMENT, or EXPLAIN EDIT MASKS for detail information about edit masks.]
The VALUE-TYPE attribute adds the VALUE-TYPE info-element to the information packet for that element. This info-element describes the type of value the element represents.
The syntax is:
VALUE-TYPE [NUMERIC|CODED|DATE|MONTH|TIME|DOLLAR|YESNO| ... ... BITS|HEX|STRUCTURED|TEXT]
For example,
ELEMENT ZIPCODE/ VALUE-TYPE NUMERIC
The first three characters may be used to specify each value-type. The value-type given here does not have to match the real attributes of the stored element.
File Definer will supply default values for the VALUE-TYPE info-element, based on the element type:
Element type supplied VALUE-TYPE
NAME TEXT
DATE DATE
TEXT TEXT
TIME TIME
INTEGER NUMERIC
REAL NUMERIC
DOLLAR DOLLAR
YESNO YESNO
ENCODE CODED
BITS BITS
HEX HEX
PACKED NUMERIC
DECIMAL NUMERIC
XEQ XEQ
STRUCTURE n STRUCTURED (only if $STRUC.IN/$STRUC.OUT
processing rules are used.
See 5.3)
SLOT NUMERIC
SLOTCHECK NUMERIC
[EXPLAIN VALUE-TYPE INFO-ELEMENT.]
The INFO INDEX attribute adds the INDEX info-element to the information packet for that element. This info-element specifies the indexes to which the element is passed.
The syntax is:
INFO INDEX searchterm[, searchterm, searchterm...]
For example,
ELEMENT COURSE.NUM/ INFO INDEX COURSE.NUM, COURSE.DESC
Note that you do not usually need to use this attribute, since the File Definer will supply default values for the INDEX info-element, based on the indexes defined for the element.
[EXPLAIN INDEX INFO-ELEMENT.]
The INPUT-OCC attribute adds the INPUT-OCC info-element to the information packet for that element. This info-element is used by $PROMPT to determine the maximum number of element occurrences that should be prompted during input.
The syntax is:
INPUT-OCC n
where "n" is an integer value from 1 to 32767.
For example,
ELEMENT COURSE.NUM/ SINGLE/ INPUT-OCC 1
[EXPLAIN INPUT-OCC INFO-ELEMENT.]
The INFO DEFAULT attribute adds the DEFAULT info-element to the information packet for that element. This info-element describes the default value that will be supplied for this element if none is entered by the user. $PROMPT uses this info-element to show the user what the default value will be.
The syntax is:
INFO DEFAULT value
where "value" is optional. The value may be either the actual default value, or a description of the value.
For example,
ELEMENT AUTHORIZER/ DEFAULT Director/ INFO DEFAULT Program Director
Note that the File Definer automatically provides a DEFAULT info-element statement when the DEFAULT attribute is used. If you use the INFO DEFAULT attribute, that value will override the automatic DEFAULT info-element.
[EXPLAIN DEFAULT INFO-ELEMENT.]
The SUPPLIED attribute adds the SUPPLIED info-element to the information packet for that element. This info-element describes the value that will be supplied for this element automatically. If the SUPPLIED info-element is present, then $PROMPT will not include this element when establishing a default element list for prompting. That is, if the user issued the command SET FORMAT $PROMPT without specifying an element list, elements having a SUPPLIED info-element will not be included.
The syntax is:
SUPPLIED value
where "value" is optional. The value may be either the actual supplied value, or a description of the value.
For example,
ELEMENT AUTHORIZER/ SUPPLIED Director's name
The File Definer automatically provides a SUPPLIED info-element statement when the following attributes are used: ACCOUNT, DATE ADD, DATE UPDATE, TIME ADD, TIME UPDATE, TIME INT.ADD, TIME INT.UPDATE. [See Appendix C.]
[EXPLAIN SUPPLIED INFO-ELEMENT.]
The GLOBAL keyword is used when you want to specify the same attributes for several elements. All attributes following the GLOBAL keyword apply to all subsequent elements. To cancel the global attributes simply enter the GLOBAL keyword with no attributes following. For example:
GLOBAL/ OCCURRENCE 1/ DATE ELEMENT DATE.ONE ELEMENT DATE.TWO ELEMENT DATE.THREE GLOBAL
In this example, DATE.ONE, DATE.TWO and DATE.THREE are all assigned the attributes OCCURRENCE 1 and DATE.
The INPROC and OUTPROC keywords are used to add customized processing rules or processing rules not provided by the File Definer.
The syntax for INPROC and OUTPROC is:
INPROC rule-string OUTPROC rule-string
where "rule-string" is the actual rule or rule string. INPROC and OUTPROC lines apply to the most recently defined element. For example:
ELEMENT SEASON
INPROC $CAP/ $LSTR(2)/ $INCLUDE(WI,SP,SU,FA)
OUTPROC $CHANGE.LIST('WI,WINTER,SP,SPRING,SU,SUMMER,FA,FALL')
Processing rules added with the INPROC and OUTPROC keywords override all other processing rules added by other element attributes, so that although the element attributes may appear in your input file, they are ignored by the File Definer. This only applies to those attributes that generate processing rules. So if you are adding customized processing rules using the INPROC and OUTPROC keywords, you must include all desired input and output processing rules with the INPROC and OUTPROC keywords, because all processing rules added by the attribute are overridden when these keywords are used. [See Appendix B for a table of the processing rules to add for each attribute.]
You can add processing rules to structures in the same way. The INPROC and OUTPROC keywords are placed immediately following the structure name, before the first element of the structure. For example,
Input> element student/structure Input> inproc $SORT(ASCEND) Input> required Input> key name/ name Input> optional Input> element class Input> element major Input> end Input>
The rules for including special characters described in Section 5.1.6 must be followed; the File Definer then applies the standard record entry rules described in Section A.1.4.4 of "System Procs". The File Definer does not verify that what you specify as an INPROC or OUTPROC rule is valid, so the use of these keywords could easily produce a file definition that does not compile.
[EXPLAIN INPROC STATEMENT or EXPLAIN OUTPROC STATEMENT.]
You can also add the $STRUC.IN and $STRUC.OUT processing rules to a structure by simply adding an integer following the STRUCTURE attribute. This integer specifies the number of elements in the structure that are to be processed by the $STRUC.IN and $STRUC.OUT rules. For example,
Input> element item.code/structure 3 Input> element store Input> element dept.code Input> element price Input> end Input>
This creates a structure named ITEM.CODE that contains three elements; these three elements may be input separately or may be input as a single value, and are displayed as a single value named ITEM.CODE.
This parameter on the STRUCTURE attribute may be expanded further to specify a character other than a comma (the default) as the separator character for the individual elements of the structure. The separator character should be enclosed in apostrophes. For example,
Input> element item.code/structure 3,'/'
This allows the slash to be used as the separator character.
[EXPLAIN $STRUC.IN PROC for more details on how this processing rule works.]
Userprocs are defined in the File Definer with the USERPROC and VARIABLE keywords and the CALL attribute used with the ELEMENT keyword.
For a complete explanation of Userprocs, see Chapter C.11 in "SPIRES File Definition" or [EXPLAIN USERPROCS.]
The CALL attribute is added to the input line of the element that invokes a Userproc.
The syntax of CALL is:
ELEMENT element-name/ CALL userproc-name
where "userproc-name" is the name of the Userproc as defined with the USERPROC keyword.
The CALL attribute may be preceded by the "OUTPUT," option if the Userproc is to apply to output only. For example:
ELEMENT ADDRESS/ OUTPUT, CALL FIXIT
The USERPROC keyword names the Userproc. It is followed by the statements that comprise the Userproc. The syntax of USERPROC is:
USERPROC name
where "name" is the name of the Userproc and matches the name given on the CALL attribute; it can be up to 16 characters long with no embedded blanks.
The USERPROC keyword must appear within the goal record to which it applies. The list of Userproc statements is ended with the END keyword. For example:
Input> userproc grade Uproc> comments Computes GRADE in school from AGE value Uproc> let i1 = $lstr($udate,4) Uproc> if $lstr($date,2) <= '06' then let i1 = #i1-1 Uproc> - Assumes school year ends in June Uproc> let i2 = $val Uproc> set val #i1-#i2 Uproc> end Input>
Two types of comments are allowed in Userprocs. Comments entered with a COMMENTS keyword are always placed at the end of the Userproc definition in the generated file definition. These comments are useful to document the Userproc as a whole. On the other hand, comments entered after a dash retain their position as input in the Userproc, and are thus more useful for making comments about particular lines of the Userproc. [See C.11.2.6 of "SPIRES File Definition".]
The VARIABLE keyword is used to declare any variables used in the Userproc. VARIABLE input lines may appear anywhere in the input file, but apply to the most recently defined goal record. The syntax of VARIABLE is:
VARIABLE variable-name/ type/ LENGTH n/ OCCURRENCE n
where "type" is one of the following:
INTEGER DYNAMIC CHARACTER STRING REAL HEX PACKED FLAG LINE
Other attributes are allowed for the VARIABLE keyword that further define the variable and its range of values. These are:
SINGLE OCCURRENCE LENGTH
They are used for variables as they are for elements. For example:
VARIABLE VALUE/ INTEGER/ OCCURRENCE 1 VARIABLE NAME/ STRING
SUBFILE TEST VARIABLE I1/ INTEGER VARIABLE I2/ INTEGER ELEMENT GRADE/ CALL GRADE USERPROC GRADE COMMENTS Computes GRADE in school from AGE value LET I1 = $LSTR($UDATE,4) IF $LSTR($DATE,2) <= '06' THEN LET I1 = #I1-1 - Assumes school year ends in June LET I2 = $VAL SET VAL #I1-#I2 END
The EXPLAIN keyword is used to create element explanations.
The syntax of EXPLAIN is:
EXPLAIN text
"Text" is the text of the explanation. Each occurrence can be up to 120 characters long. You may use the continuation character (+) for a long explanation, or you may repeat the EXPLAIN keyword. If the text for a single EXPLAIN keyword is more than 120 characters, the File Definer will truncate it and give you a warning message. For an element explanation, the EXPLAIN input lines appear in the input file following the ELEMENT input line.
ELEMENT DATE EXPLAIN This contains a date in the form EXPLAIN Month day, year
or
ELEMENT DATE EXPLAIN This contains a date in the form + Month day, year
If you use the continuation character, the lines are run together. So if you want each line to be output as separate lines, use the EXPLAIN keyword to begin each line.
Element explanations are used mainly in conjunction with the system $PROMPT format. During prompting for element values, if the user responds to a prompt with a question mark, the element explanation is displayed. Element explanations are also shown by the SHOW ELEMENT INFORMATION and SHOW ELEMENT DESCRIPTION commands.
See "SPIRES Searching and Updating" for information about the system $PROMPT format. [See 6.8 of this manual for a description of the use of EXPLAIN to create subfile explanations.]
The SEARCHPROC (alias SRCPROC or SEARCH) and PASSPROC keywords are used to add customized processing rules to the linkage section of the file definition. These rules define the searching and passing logic for the file's indexes.
The syntax for SEARCHPROC and PASSPROC is:
SEARCHPROC rule-string PASSPROC rule-string
where "rule-string" is the actual rule or rule string. SEARCHPROC and PASSPROC lines apply to the most recently defined element. For example:
ELEMENT CATEGORY/ INDEX
SEARCHPROC $CAP/ $BREAK/ $TEST.LEN(IN.GT,3)/ $SEARCH.TRUNC
PASSPROC $PASS.ELEM('CATEGORY,SUB.CAT',WORD)/ $WORD(SEARCH)/+
$EXCLUDE(COMMON.WORDS)/ $TEST.LEN(IN.GT,3)
Processing rules added with the SEARCHPROC and PASSPROC keywords override all other processing rules added by the File Definer, so you must specify all desired SEARCHPROCs and PASSPROCs if you use these keywords. Note that the $PASS.ELEM proc is required for each index. This proc specifies which element is to be used in creating the index. If you do not add your own PASSPROCs, the File Definer includes a $PASS.ELEM proc for you. [EXPLAIN $PASS.ELEM PROC.]
The rules for including special characters described in Section 5.1.6 must be followed; the File Definer then applies the standard record entry rules described in Section A.1.4.4 of "System Procs". The File Definer does not verify that what you specify as an SEARCHPROC or PASSPROC rule is valid, so the use of these keywords could easily produce a file definition that does not compile.
[EXPLAIN SEARCHPROC STATEMENT or EXPLAIN PASSPROC STATEMENT.]
The subfile section consists of a subfile name and accounts permitted access; it may also contain file management statements, subfile security statements, a format selection statement, a subgoal statement, a subfile explanation, and protocol commands to be executed at the time of subfile selection.
Most of the subfile statements are specified in the File Definer as attributes of the SUBFILE keyword. The EXPLAIN, COMMENTS, CMD, and VIEW keywords are also used in the subfile section to add subfile explanations, comments, protocol commands, and element views to the file definition. This chapter covers the SUBFILE keyword and its attributes and the EXPLAIN, COMMENTS, CMD, and VIEW keywords.
The File Definer requires that a subfile name be specified. If one is not supplied in the input file, the File Definer prompts for one before generating a file definition.
The syntax of SUBFILE is in the form:
SUBFILE subfile-name
where "subfile-name" is less than or equal to 32 characters long (imbedded blanks are allowed). For example:
SUBFILE PEOPLE SUBFILE MAIL.LIST
The subfile name applies to the current goal record; if a subfile name is not included in the input file and the File Definer prompts for one, it applies to the first goal record named.
See Section B.1.9 of "SPIRES File Definition" or [EXPLAIN SUBFILE-NAME STATEMENT.]
If you want the subfile specification to apply to a different goal record than the one being currently defined, you can add the RECNAME attribute to the SUBFILE keyword. This is used primarily for specifying subfile sections for record sections not named as goal records, i.e, index records. For example,
SUBFILE MAIL.LIST ELEMENT NAME/INDEX ELEMENT ADDRESS/INDEX SUBFILE NAME INDEX/RECNAME ZIN02
This creates a subfile section for the index record defined for the NAME element. (See Section 5.1.4 for the conventions of naming index records.)
See Section 4.7 for information about defining more than one subfile per file.
The FORMAT attribute specifies a format to be set automatically when the subfile is selected.
The syntax of FORMAT is:
FORMAT format-name
For example:
SUBFILE PEOPLE/ FORMAT LIST
To SET FORMAT $PROMPT automatically, use the CMD keyword [See 6.6.] for more flexibility.
See Section B.9.2 of "SPIRES File Definition" or [EXPLAIN FORMAT STATEMENT.]
The ACCOUNTS attribute specifies the accounts that have access to the subfile. If no additional security is specified then accounts specified here have read and update access. [See 6.5, 6.5a, 6.5b.]
The syntax for ACCOUNTS is:
ACCOUNTS gg.uuu,gg.uuu. . .
An entire group of accounts can be specified as "gg....", or a community as "g.....". The commas are optional; the accounts can be separated with only a space. For example:
SUBFILE PEOPLE/ ACCOUNTS GG....,GA.SPI
If ACCOUNTS is not specified, the File Definer creates an ACCOUNTS statement with your account.
See Section B.1.9 of "SPIRES File Definition" or [EXPLAIN ACCOUNTS STATEMENT.]
The DIST-NAME attribute specifies a distribution list of accounts that have access to the subfile. The syntax is:
DIST-NAME gg.uuu.extdef.name[, gg.uuu.extdef.name...]
where "gg.uuu.extdef.name" is the ID of the EXTDEF record containing the distribution list. For example:
SUBFILE PEOPLE/ ACCOUNTS GA.SPI/ DIST-NAME GA.SPI.OFFICE.ACCTS
See Section B.9.2a of "SPIRES File Definition" or [EXPLAIN DIST-NAME STATEMENT.]
The LOG attribute is used to create a LOG statement in the subfile section.
The syntax of LOG is:
LOG n
where "n" is "1", "2", "3" or any combination thereof. For example:
SUBFILE BIBLIO/ LOG 1,3 SUBFILE PEOPLE/ LOG 2
Depending on the value of LOG, different types of information about subfile use are collected. Disposition of this information is controlled by the STATISTICS attribute for the FILE keyword. [See 3.6.]
SUBFILE PEOPLE/ LOG 3
See Section B.11.3.1 of "SPIRES File Definition" or [EXPLAIN LOG FILE.] and [EXPLAIN LOG STATEMENT.]
The PROGRAM attribute is used to create a PROGRAM statement in the subfile section.
The syntax of PROGRAM is:
PROGRAM program-name[, program-name...]
where "program-name" is a program chosen from the following list:
SPIRES PRISM SPIUTIL SPIBILD FASTBILD SPISRCH SOCRATES
For example:
SUBFILE BIBLIO/ PROGRAM PRISM
THE PROGRAM statement limits the programs in which a user can select the subfile. The most common use of this statement is to make a subfile available for selection only in Prism. See Section B.9.7 of "SPIRES File Definition" or [EXPLAIN PROGRAM STATEMENT.]
With the SWITCHES attribute you can specify secure-switches to be set. Secure-switches provide various forms of subfile security, such as preventing a particular user or group of users from updating a file, or preventing a user from setting a particular format.
The syntax of SWITCHES is:
SWITCHES n
where "n" is the desired secure-switch number. If more than one secure-switch is to be set, the numbers are separated by commas following the attribute. For example:
SUBFILE PEOPLE/ SWITCHES 3 SUBFILE PEOPLE/ SWITCHES 2,13
"SWITCHES 3" is most frequently used; it specifies that certain accounts are not allowed to update records.
If you need to assign different sets of secure-switches for different accounts, more than one subfile statement must be specified:
SUBFILE TEST/ ACCOUNTS GA.SPI/ FORMAT REPORT SUBFILE TEST/ ACCOUNTS GQ.PAC/ FORMAT REPORT/ SWITCHES 3
These two SUBFILE input lines define a single subfile called TEST that can be accessed by accounts GA.SPI and GQ.PAC. Both accounts select the subfile with the REPORT format set automatically, but no update access is allowed in GQ.PAC's use of the subfile.
Multiple subfile names can be specified in the same way:
SUBFILE TEST/ ACCOUNTS GA.SPI/ FORMAT REPORT SUBFILE PEOPLE/ ACCOUNTS GQ.PAC/ FORMAT REPORT/ SWITCHES 3
These two subfile lines do the same thing as the previous example, but the subfile name is different for each account.
See Chapter B.9.3 in "SPIRES File Definition" for complete information about secure-switches, or [EXPLAIN SECURE-SWITCHES STATEMENT.]
The VIEW keyword lets you define "element views" for a subfile. Like the SUBFILE keyword, the VIEW keyword may appear anywhere in the record definition. There are several attributes that are used with the VIEW keyword to specify elements that can or cannot be seen or updated.
After defining the views, you also add the VIEW-NAME attribute to the SUBFILE keyword, specifying which view applies to a specific account or group of accounts. (The EXT-VIEW attribute is used if the view definition is stored in the EXTDEF subfile.)
The syntax of the VIEW keyword is:
VIEW view-name/ view-option value/ view-option value/ ...
where valid "view-options" and "values" are:
HIDDEN element-list
SEE-ONLY element-list
UPDATE element-list
INPROC-REQ element-list
OUTPROC-REQ element-list
DEFAULT {HIDDEN|SEE-ONLY|UPDATE}
MODIFY-VIEW view-name
For example:
VIEW OFFICE/ SEE-ONLY RATING VIEW PUBLIC/ HIDDEN SALARY, RATING VIEW ENTRY/ UPDATE NAME, ADDRESS, PHONE
Here are brief explanations of the view-options. See Chapter B.9.4 in "SPIRES File Definition" for complete information about element views.
HIDDEN element-list -- This is a list of all elements that should
be completely hidden in this view. Users cannot see or update
the elements.
SEE-ONLY element-list -- Elements that may be seen but not updated
in this view.
UPDATE element-list -- Elements that may be seen and updated.
INPROC-REQ element-list -- Elements whose INPROC rules cannot be
bypassed.
OUTPROC-REQ element-list -- Elements whose OUTPROC rules cannot be
bypassed.
DEFAULT {HIDDEN|SEE-ONLY|UPDATE} -- Disposition of any elements
not controlled by the HIDDEN, SEE-ONLY, or UPDATE statements.
MODIFY-VIEW view-name -- View whose specifications are being
modified by the statements that follow.
A "view-name" may be 1 to 16 characters long. It may contain alphanumeric characters, periods, hyphens, and underscores, but no blanks or other special characters.
The "element-list" consists of one or more element or structure names, separated by commas or blanks. The maximum length of an element list is 3000 characters, but the HIDDEN, SEE-ONLY, UPDATE, INPROC-REQ, and OUTPROC-REQ statements may be repeated.
Valid abbreviations for the view-options are HID, SEE, UPD, INPR, OUTPR, DEF, and MOD.
Use the VIEW-NAME attribute with the SUBFILE keyword to specify which view should apply to a particular account or group of accounts. The syntax is:
VIEW-NAME view-name
where "view-name" is one of the views specified with the VIEW keyword. For example:
SUBFILE PEOPLE/ ACCOUNTS SI..../ VIEW-NAME PUBLIC
Only one view-name is allowed per SUBFILE statement.
You cannot use the VIEW-NAME attribute in any SUBFILE statement that contains the CONSTRAINT, NOUPDATE, INPROC-REQ, or OUTPROC-REQ attribute. That is, only one form of element security specification (element views or PRIV-TAG's) may be used in any one SUBFILE statement. [See 6.5b.]
View definitions may also be placed in the EXTDEF subfile. If you need to refer to such a view definition, use the EXT-VIEW attribute with the GOAL keyword. The syntax is:
EXT-VIEW extdef-record-id
For example,
GOAL REC01/EXT-VIEW SI.MAS.OFFICE.VIEW
[See B.9.4.2 of "SPIRES File Definition".]
Here is an example of element security specification with element views.
ELEMENT NAME ELEMENT SALARY ELEMENT RATING/ INDEX VIEW OFFICE/ SEE-ONLY RATING, SALARY VIEW PUBLIC/ HIDDEN RATING, SALARY VIEW ENTRY/ SEE-ONLY RATING SUBFILE PEOPLE/ ACCOUNTS SI..../ SWITCHES 3/ VIEW-NAME PUBLIC SUBFILE PEOPLE/ ACCOUNTS SH.INK, SH.WIM/ VIEW-NAME OFFICE SUBFILE PEOPLE/ ACCOUNTS SH.ARK/ VIEW-NAME ENTRY SUBFILE PEOPLE/ ACCOUNTS SH.MAS
Accounts in group SI can search the PEOPLE subfile but cannot update (secure-switch 3). They cannot see the SALARY or RATING elements or use the RATING index. Accounts SH.INK and SH.WIM may search and may update all parts of the record except the SALARY and RATING elements. Account SH.ARK may not update RATING. And account SH.MAS has full search and update access to the subfile.
The following attributes are used with the SUBFILE keyword to specify various forms of security for individual elements or indexes. These attributes are used in conjunction with the PRIV-TAG attribute in the element specification section. [See 5.1.8.]
CONSTRAINT n specified elements may not be seen
NOUPDATE n specified elements may not be updated
NOSEARCH n index for specified elements may not
be used
INPROC-REQ n INPROC rules for specified elements may
not be bypassed
OUTPROC-REQ n OUTPROC rules for specified elements may
not be bypassed
In these statements, "n" corresponds to the PRIV-TAG number specified for the element being affected. Valid abbreviations for these attributes are CON, NOU, NOS, INPR, and OUTPR. See Chapter B.9.4 in "SPIRES File Definition" for complete information about assigning security for individual elements and indexes, or [EXPLAIN CONSTRAINT STATEMENT.], [EXPLAIN NOUPDATE STATEMENT.], [EXPLAIN NOSEARCH STATEMENT.], [EXPLAIN INPROC-REQ STATEMENT.], and [EXPLAIN OUTPROC-REQ STATEMENT.]
Here is an example of element security specification with PRIV-TAG's:
ELEMENT NAME ELEMENT SALARY/ PRIV-TAG 3 ELEMENT RATING/ INDEX/ PRIV-TAG 4 SUBFILE PEOPLE/ ACCOUNTS SI..../ SWITCHES 3/ CONSTRAINT 3,4/+ NOUPDATE 3,4/ NOSEARCH 4 SUBFILE PEOPLE/ ACCOUNTS SH.INK, SH.WIM/ NOUPDATE 3,4 SUBFILE PEOPLE/ ACCOUNTS SH.ARK/ NOUPDATE 4 SUBFILE PEOPLE/ ACCOUNTS SH.MAS
Accounts in group SI can search the PEOPLE subfile but cannot update (secure-switch 3). They cannot see the SALARY or RATING elements or use the RATING index. Accounts SH.INK and SH.WIM may search and may update all parts of the record except the SALARY and RATING elements. Account SH.ARK may not update RATING. And account SH.MAS has full search and update access to the subfile.
Through SPIRES formats, members of a privilege group can access data in record-types of the file other than the goal record record-type. This is usually only necessary when indirect record-access via the LOOKUP attribute becomes too complex. This access is allowed by coding a SUBGOAL statement in the subfile section.
You can add a SUBGOAL statement to your file definition by including the SUBGOAL attribute.
The syntax of SUBGOAL is:
SUBFILE PEOPLE/ SUBGOAL record-name,record-name,....
where "record-name" is the name of the record-type that is to be accessed by a format via subgoal processing. Up to 10 record-types can be specified.
[EXPLAIN SUBGOAL STATEMENT.]
You can provide security for particular records or particular elements of records depending on who is using the subfile by defining several subfiles with different SUBCODE statements. You can create a SUBCODE statement in the file definition by using the SUBCODE attribute with the SUBFILE keyword as in the following example:
SUBFILE PEOPLE/ SUBCODE GRPA
The variable $SUBCODE is set to the value specified when the user selects the subfile. Any USERPROC can test the value of $SUBCODE and determine how the element or the entire record is to be processed, based on that value.
[EXPLAIN SUBCODE STATEMENT.]
The CMD keyword allows you to specify any SPIRES or WYLBUR or ORVYL command or protocol statement to be executed at the time of subfile selection.
The syntax of CMD is:
CMD statement
where "statement" is any valid command or protocol statement. For example:
CMD SET XEQ MYPROTO CMD ..STARTUP
A maximum of 10 CMD lines is allowed per subfile. They may be placed anywhere in the input file and apply to the most recently defined subfile.
See Section B.9.6 of "SPIRES File Definition" or [EXPLAIN SELECT-COMMAND STATEMENT.]
The EXPLAIN keyword is used to create subfile explanations.
The syntax of EXPLAIN is:
EXPLAIN text
"Text" is the text of the explanation. It can be up to 120 characters long. You may use the continuation character (+) for a long explanation, or you may repeat the EXPLAIN keyword. If the text for a single EXPLAIN keyword is more than 120 characters, the File Definer will truncate it and give you a warning message. For a subfile explanation, the EXPLAIN input lines appear in the input file following the SUBFILE input line.
For example:
SUBFILE PEOPLE EXPLAIN This a subfile that contains EXPLAIN information about various people.
or
SUBFILE PEOPLE EXPLAIN This is a subfile that contains + information about various people.
If you use the continuation character, the lines are run together. So if you want each line to be output as a separate line, use the EXPLAIN keyword to begin each line.
Subfile explanations are shown by the SHOW SUBFILE DESCRIPTION command.
See Section 5.5 of this manual for an explanation of the use of EXPLAIN to create element explanations.
See Section B.9.2 of "SPIRES File Definition" or [EXPLAIN EXP STATEMENT.]
The simplest subfile section consists of only a subfile name:
SUBFILE PEOPLE
If you were to utilize most of the available options, the subfile section might look like this:
SUBFILE PEOPLE/ LOG 3/ ACCOUNTS GA.SPI SUBFILE PEOPLE/ FORMAT LIST/ ACCOUNTS GA..../VIEW-NAME OFFICE CMD SET XEQ MYPROTOS CMD ..STARTUP
Once you have generated your file definition [See 2.5.] you then add it to the system FILEDEF subfile and compile it. A file definition generated by the File Definer should not have any errors, but if for some reason your file definition is not successfully added to FILEDEF or does not compile, see your SPIRES consultant. If you make modifications to the file definition in your active file, you run the risk of creating such errors.
This chapter takes you through the final steps of creating your file. See Chapter B.5 of "SPIRES File Definition" for complete details on the entire process.
When you have generated a file definition, it can be added to FILEDEF, the file definition subfile, just like any other record in a subfile. To add your file definition to FILEDEF, you must be in SPIRES, then issue the following commands:
-> select filedef (put your file definition in the active file) -> add
If your file definition is successfully added, SPIRES returns a command prompt to you. If an error is encountered, you receive an error message that references the line number of your file definition in the active file in which the error occurs and the SPIRES error number, which can be explained using the EXPLAIN command. You should correct your input file, regenerate your file definition and reissue the ADD command, or contact your consultant for assistance.
Once you have added the file definition to FILEDEF, you are ready to compile it.
The COMPILE command compiles your file definition and sets up the ORVYL files as specified by your file definition in FILEDEF.
To compile your file definition, issue the following command:
-> compile gg.uuu.filename
where "filename" is the value you assigned to the FILE keyword; the "gg.uuu" portion is optional on the COMPILE command.
Any compilation errors will be reported to you. They are not keyed to line numbers but to structures and elements in the FILEDEF record. Explanations and suggested solutions are provided for most error messages online, through the EXPLAIN command.
If no errors are detected, you receive the message "File Definition Compiled". If errors are detected, contact your consultant for assistance.
Your file is now ready to accept records. As the file owner, you may issue the SELECT command to select your subfile immediately. In addition, any other accounts to which you have given access to the subfile will now be able to select it, subject to the security constraints that you have specified.
After testing your file with a few records, you may decide to change the file definition. As mentioned earlier, you should use the File Definer to generate a new file definition from the saved copy of your original File Definer input file rather than modifying the code created by the GENERATE command. [See 1.]
To alter a file definition in the FILEDEF subfile use the following commands:
-> select filedef (put the new file definition in the active file) -> update gg.uuu.filename
You will probably want to erase your test records since presumably they did not do what you had hoped they would. You can erase the disk data sets created for your SPIRES file by the COMPILE command, and thus all records stored in the file, by issuing the ZAP FILE command:
-> zap file gg.uuu.filename -Do you mean to destroy file gg.uuu.filename? yes ->
The "gg.uuu" portion is optional. ZAP FILE takes the precaution of asking you if you really mean to erase the file because this is an irreversible step: records destroyed by this command cannot be recovered.
The ZAP FILE command does not affect your file definition record in the FILEDEF subfile. After you have updated the file definition in FILEDEF, you should COMPILE it again.
After you have begun using your file and have added "real" records to it, you may decide to change the file definition. This can be tricky business. It may involve erasing the disk files (after retrieving and storing the data), updating the file definition in FILEDEF and creating new disk files with the COMPILE command. Or, if you are making more limited changes (perhaps just adding a new alias to an element), you may only need to modify the file definition and RECOMPILE it; no data in the file would have to be changed.
If you radically alter the structure of the file, you run the risk of invalidating stored data. If you don't mind reentering the data record by record, then changing the structure of your file is not difficult, only time-consuming. But if your file contains hundreds of records, you have to consider the structure in which your data is already stored in SPIRES and work around that.
If radical changes are to be made, you need to first retrieve and store your data so that it can be reentered after the new file is created. This process is described in Chapter B.5.8 of "SPIRES File Definition." You would then issue the ZAP FILE command to erase your disk files, create a new definition with File Definer, replace it in FILEDEF, compile it and add the records in batch input mode in SPIBILD or SPIRES. (See Section D.5.2 in "SPIRES Searching and Updating".)
If more limited changes are to be made, the first step is to create a new file definition. It is best to work with the File Definer, but it cannot be guaranteed that the new file definition will be compatible with the records stored under the old file definition. The File Definer generates a file definition according to your specifications, so you must understand how you are changing the physical storage structure of your file.
In particular, if you try to add an index to an already existing element, you may invalidate any previously defined indexes. The File Definer assigns a record name to index records in the order in which they are specified, so if you are adding a new index, the File Definer might generate different record names for each element's index. The RECNAME attribute [See 5.1.4.] can be used to avoid this problem.
In general, there are clearly defined guidelines for what you can and cannot change in a file definition without invalidating your stored data. These guidelines are explained in detail in Chapter C.1 of "SPIRES File Definition"; but a brief guide follows:
If, after compiling a new file definition, you find that your records have been altered beyond recognition it is easy to go back and recover the original data if you have saved a copy of the old file definition. Replace the file definition in FILEDEF with the original file definition and RECOMPILE. Do this before any records are added or updated under the new definition, or use the DEQUEUE ALL command to remove these records. (See "SPIRES Searching and Updating", Section D.2.6.)
Changes in the SUBFILE keyword and its attributes may be made at any time; no recompilation is necessary, and the changes take immediate effect.
Our first example is a file definition for a simple mail file. It includes elements for name and address lines, with indexes for the name, institution and state. It also includes an element called "list-code" to enter multiply-occurring values by which to categorize each name; list-codes are indexed and can be input on a single line, separated by commas.
COMMAND> spires
-Welcome to SPIRES ... if in trouble, try HELP
-> enter file definer
* ENTERING FILE DEFINER
:-> input
: 1. Input> subfile mail.list
: 2. Input> required
: 3. Input> element name/ name/ single/ index
: 4. Input> optional
: 5. Input> element position
: 6. Input> element institution/ index
: 7. Input> element address
: 8. Input> element city/ single
: 9. Input> element state/ length 2,exact/ single/ index
: 10. Input> element zip.code/ length 5,exact/ single
: 11. Input> element phone/ single
: 12. Input> element list-code/ breakup ","/ index
: 13. Input> element comments
: 14. Input> end
:-> generate clear
:-> list
1. FILE = GQ.BEC.MAIL.LIST;
2. COMMENTS = Generated by FILE DEFINER 02/13/86;
3. RECORD-NAME = REC01;
4. REMOVED;
5. SLOT;
6. REQUIRED;
7. ELEM = NAME;
8. OCC = 1;
9. INPROC = $NAME;
10. OUTPROC = $NAME;
11. ELEMINFO;
12. VALUE-TYPE = TEXT;
13. INDEX = NAME;
14. OPTIONAL;
15. ELEM = POSITION;
16. ELEM = INSTITUTION;
17. ELEMINFO;
18. INDEX = INSTITUTION;
19. ELEM = ADDRESS;
20. ELEM = CITY;
21. OCC = 1;
22. ELEM = STATE;
23. LEN = 2;
24. OCC = 1;
25. INPROC = $LENGTH(2);
26. ELEMINFO;
27. INDEX = STATE;
28. ELEM = ZIP.CODE;
29. LEN = 5;
30. OCC = 1;
31. INPROC = $LENGTH(5);
32. ELEM = PHONE;
33. OCC = 1;
34. ELEM = LIST-CODE;
35. INPROC = $BREAK(',');
36. OUTPROC = $BUILD(', ');
37. ELEMINFO;
38. INDEX = LIST-CODE;
39. ELEM = COMMENTS;
40. RECORD-NAME = ZIN02;
41. REQUIRED;
42. KEY = NAME;
43. OPTIONAL;
44. ELEM = FIRST;
45. TYPE = STR;
46. STRUCTURE = FIRST;
47. REQUIRED;
48. KEY = FN;
49. INPROC = $PNAME;
50. OUTPROC = $PNAME;
51. OPTIONAL;
52. ELEM = POINTER;
53. TYPE = LCTR;
54. INPROC = $HEX;
55. OUTPROC = $HEX.OUT;
56. RECORD-NAME = ZIN03;
57. COMBINE = ZIN02;
58. REQUIRED;
59. KEY = INSTITUTION;
60. OPTIONAL;
61. ELEM = POINTER;
62. TYPE = LCTR;
63. INPROC = $HEX;
64. OUTPROC = $HEX.OUT;
65. RECORD-NAME = ZIN04;
66. COMBINE = ZIN02;
67. REQUIRED;
68. KEY = STATE;
69. OPTIONAL;
70. ELEM = POINTER;
71. TYPE = LCTR;
72. INPROC = $HEX;
73. OUTPROC = $HEX.OUT;
74. RECORD-NAME = ZIN05;
75. COMBINE = ZIN02;
76. REQUIRED;
77. KEY = LIST-CODE;
78. OPTIONAL;
79. ELEM = POINTER;
80. TYPE = LCTR;
81. INPROC = $HEX;
82. OUTPROC = $HEX.OUT;
83. GOALREC-NAME = REC01;
84. PTR-ELEM = POINTER;
85. EXTERNAL-NAME = RECORD;
86. PASSPROC = $PASS.LCTR;
87. INDEX-NAME = ZIN02;
88. SEARCHTERMS = NAME;
89. SEARCHPROC = $PNAME(TRANS);
90. PASSPROC = $PASS.ELEM('NAME',NAME)/
91 $PNAME(TRANS,SPECIAL);
92. INDEXINFO;
93. SOURCE = NAME;
94. VALUE-TYPE = NAME;
95. SUB-INDEX = FIRST;
96. SEARCHTERMS = NONE;
97. PRIV-TAG = 1;
98. PASSPROC = $PASS.OCC;
99. PTR-GROUP = POINTER;
100. INDEX-NAME = ZIN03;
101. SEARCHTERMS = INSTITUTION;
102. SEARCHPROC = $CAP;
103. PASSPROC = $PASS.ELEM('INSTITUTION',1)/ $NULL;
104. INDEXINFO;
105. SOURCE = INSTITUTION;
106. PTR-GROUP = POINTER;
107. INDEX-NAME = ZIN04;
108. SEARCHTERMS = STATE;
109. SEARCHPROC = $LENGTH(2);
110. PASSPROC = $PASS.ELEM('STATE',1)/ $NULL;
111. INDEXINFO;
112. SOURCE = STATE;
113. PTR-GROUP = POINTER;
114. INDEX-NAME = ZIN05;
115. SEARCHTERMS = LIST-CODE;
116. SEARCHPROC = $CAP;
117. PASSPROC = $PASS.ELEM('LIST-CODE',1)/ $NULL;
118. INDEXINFO;
119. SOURCE = LIST-CODE;
120. VALUE-TYPE = PHRASE;
121. PTR-GROUP = POINTER;
122. SUBFILE-NAME = MAIL.LIST;
123. GOAL-RECORD = REC01;
124. ACCOUNTS = GQ.BEC;
125. NOSEARCH = 1;
:-> return
-> select filedef
-> add
-> compile mail.list
-File Definition Compiled
->
Our second example is for a bibliographic file of articles. A word index is created for the article titles. The SUBJECT element is indexed twice: in an index containing only SUBJECT values and also in the TITLE index. This will allow for more flexible searching when searching for an article when you only have a general idea of what it's about. This input file also includes subfile and element explanations.
COMMAND> spires
-Welcome to SPIRES ... if in trouble, try HELP
-> enter file definer
* ENTERING FILE DEFINER
:-> input
: 1. Input> subfile biblio
: 2. Input> explain This subfile contains selected articles
: 3. Input> explain from microcomputer journals and
: 4. Input> explain magazines.
: 5. Input> required
: 6. Input> element title/ index/ word/ exclude
: 7. Input> element author/ name/ index
: 8. Input> optional
: 9. Input> element journal
: 10. Input> explain The JOURNAL element contains all
: 11. Input> explain information needed to locate
: 12. Input> explain article: journal name, volume,
: 13. Input> explain date and page number.
: 14. Input> element abstract
: 15. Input> element subject/ index/ word/ index title
: 16. Input> explain The SUBJECT element should be a
: 17. Input> explain word or short phrase identifying
: 18. Input> explain the contents of the article. It can
: 19. Input> explain occur any number of times.
: 20. Input> element comments
: 21. Input> end
:-> generate clear
:-> list
1. FILE = GQ.BEC.BIBLIO;
2. COMMENTS = Generated by FILE DEFINER 02/13/86;
3. RECORD-NAME = REC01;
4. REMOVED;
5. SLOT;
6. REQUIRED;
7. ELEM = TITLE;
8. ELEMINFO;
9. INDEX = TITLE, SUBJECT;
10. ELEM = AUTHOR;
11. INPROC = $NAME;
12. OUTPROC = $NAME;
13. ELEMINFO;
14. VALUE-TYPE = TEXT;
15. INDEX = AUTHOR;
16. OPTIONAL;
17. ELEM = JOURNAL;
18. ELEMINFO;
19. DESCRIPTION = The JOURNAL element contains all;
20. DESCRIPTION = information needed to locate the;
21. DESCRIPTION = article: journal name, volume,;
22. DESCRIPTION = date and page number.;
23. ELEM = ABSTRACT;
24. ELEM = SUBJECT;
25. ELEMINFO;
26. DESCRIPTION = The SUBJECT element should be a;
27. DESCRIPTION = word or short phrase identifying;
28. DESCRIPTION = the contents of the article. It can;
29. DESCRIPTION = occur any number of times.;
30. INDEX = TITLE,SUBJECT;
31. ELEM = COMMENTS;
32. RECORD-NAME = ZIN02;
33. REQUIRED;
34. KEY = TITLE;
35. ALIASES = SUBJECT;
36. OPTIONAL;
37. ELEM = POINTER;
38. TYPE = LCTR;
39. INPROC = $HEX;
40. OUTPROC = $HEX.OUT;
41. RECORD-NAME = ZIN03;
42. COMBINE = ZIN02;
43. REQUIRED;
44. KEY = AUTHOR;
45. OPTIONAL;
46. ELEM = FIRST;
47. TYPE = STR;
48. STRUCTURE = FIRST;
49. REQUIRED;
50. KEY = FN;
51. INPROC = $PNAME;
52. OUTPROC = $PNAME;
53. OPTIONAL;
54. ELEM = POINTER;
55. TYPE = LCTR;
56. INPROC = $HEX;
57. OUTPROC = $HEX.OUT;
58. RECORD-NAME = ZIN04;
59. COMBINE = ZIN02;
60. REQUIRED;
61. KEY = SUBJECT;
62. OPTIONAL;
63. ELEM = POINTER;
64. TYPE = LCTR;
65. INPROC = $HEX;
66. OUTPROC = $HEX.OUT;
67. GOALREC-NAME = REC01;
68. PTR-ELEM = POINTER;
69. EXTERNAL-NAME = RECORD;
70. PASSPROC = $PASS.LCTR;
71. INDEX-NAME = ZIN02;
72. SEARCHTERMS = TITLE, SUBJECT;
73. SEARCHPROC = $WORD(SEARCH)/ $EXCLUDE(COMMON.WORDS);
74. PASSPROC = $PASS.ELEM('TITLE, SUBJECT',2)/
75. $WORD(PASS)/
76. $EXCLUDE(COMMON.WORDS)/ $NULL;
77. INDEXINFO;
78. SOURCE = TITLE, SUBJECT;
79. VALUE-TYPE = WORD;
80. PTR-GROUP = POINTER;
81. INDEX-NAME = ZIN03;
82. SEARCHTERMS = AUTHOR;
83. SEARCHPROC = $PNAME(TRANS);
84. PASSPROC = $PASS.ELEM('AUTHOR',NAME)/
85. $PNAME(TRANS,SPECIAL);
86. INDEXINFO;
87. SOURCE = AUTHOR;
88. VALUE-TYPE = NAME;
89. SUB-INDEX = FIRST;
90. SEARCHTERMS = NONE;
91. PRIV-TAG = 1;
92. PASSPROC = $PASS.OCC;
93. PTR-GROUP = POINTER;
94. INDEX-NAME = ZIN04;
95. SEARCHTERMS = SUBJECT;
96. SEARCHPROC = $WORD;
97. PASSPROC = $PASS.ELEM('SUBJECT',2)/ $WORD(PASS)/
98. $NULL;
99. INDEXINFO;
100. SOURCE = SUBJECT;
101. VALUE-TYPE = WORD;
102. PTR-GROUP = POINTER;
103. SUBFILE-NAME = BIBLIO;
104. EXP = "This subfile contains selected articles";
105. EXP = "from microcomputer journals and";
106. EXP = "magazines.";
107. GOAL-RECORD = REC01;
108. ACCOUNTS = GQ.BEC;
109. NOSEARCH = 1;
:-> return
-> select filedef
-> add
-> compile biblio
-File Definition Compiled
->
KEYWORD SYNTAX
ATTRIBUTE DEFAULT (if no default is listed, no action is
(section for taken unless specified in the File Definer input.)
description) *Indicates a system default rather than a File
Definer default; that is, the File Definer
does not add a statement to the file definition,
but SPIRES takes the default.
------------------------------------------------------------------------------
|
FILE (3.1) | FILE gg.uuu.filename
| Default: filename = your account + first
| subfile named
AUTHOR (3.2) | AUTHOR your name and phone number
MAXVAL (3.3) | MAXVAL n (integral multiple of 8)
| Default*: 1024
NOAUTOGEN (3.4) | NOAUTOGEN
| Default*: AUTOGEN is set
BIN (3.5) | BIN HOLD|PURGE|n (3-digit bin number)
| Default*: the default bin number of
| your account
STATISTICS (3.6) | STATISTICS n ("1" and/or "2")
MASTER (3.7) | MASTER gg.uuu,gg.uuu. . .
SEE (3.7) | SEE gg.uuu,gg.uuu. . .
PROCESS (3.7) | PROCESS gg.uuu,gg.uuu. . .
COPY (3.7) | COPY gg.uuu,gg.uuu. . .
UPDATE (3.7) | UPDATE gg.uuu,gg.uuu. . .
------------------------|-----------------------------------------------------
|
GOAL (4.1) | GOAL record-name (up to 6 characters)
| Default: REC01,REC02,REC03. . .
| All goal record-types are REMOVED
COMBINE (4.2) | COMBINE record-name
| Default: Index records combined with first
| index record
RESULT (4.3) | RESULT external-name
| Default: RECORD
PASSER (4.4) | PASSER {KEY/LOCAT0R}
| Default: LOCATOR
EXT-VIEW (6.5a) | EXT-VIEW extdef-record-id
|
FIXED (4.5) | If no element categories are specified,
REQUIRED (4.5) | all elements become OPTIONAL.
OPTIONAL (4.5) |
VIRTUAL (4.5) |
|
------------------------|-----------------------------------------------------
SUBFILE (6.1) | SUBFILE subfile-name (up to 32 characters)
| Default: Value required; no default.
FORMAT (6.2) | FORMAT format-name
ACCOUNTS (6.3) | ACCOUNTS gg.uuu,gg.uuu. . .
| Default: your account
DIST-NAME (6.3a) | DIST-NAME gg.uuu.extdef.name
LOG (6.4) | LOG n ("1","2" or "3")
PROGRAM (6.4a) | PROGRAM program-name
SWITCHES (6.5) | SWITCHES n
VIEW-NAME (6.5a) | VIEW-NAME view-name
CONSTRAINT (6.5b) | CONSTRAINT n
NOUPDATE (6.5b) | NOUPDATE n
NOSEARCH (6.5b) | NOSEARCH n
INPROC-REQ (6.5b) | INPROC-REQ n
OUTPROC-REQ (6.5b) | OUTPROC-REQ n
SUBGOAL (6.9) | SUBGOAL record-name,record-name,....
SUBCODE (6.6a) | SUBCODE code
------------------------|-----------------------------------------------------
VIEW (6.5a) | VIEW view-name
HIDDEN (6.5a) | HIDDEN element-list
SEE-ONLY (6.5a) | SEE-ONLY element-list
UPDATE (6.5a) | UPDATE element-list
INPROC-REQ (6.5a) | INPROC-REQ element-list
OUTPROC-REQ (6.5a) | OUTPROC-REQ element-list
DEFAULT (6.5a) | DEFAULT {HIDDEN|SEE-ONLY|UPDATE}
MODIFY-VIEW (6.5a) | MODIFY-VIEW view-name
------------------------|-----------------------------------------------------
CMD (6.6) | CMD statement (valid command)
------------------------|-----------------------------------------------------
EXPLAIN (5.5, 6.7) | EXPLAIN text (subfile or element explanation)
------------------------|-----------------------------------------------------
COMMENTS (3.8) | COMMENTS text (file, subfile or element comments)
------------------------|-----------------------------------------------------
KEY (5.1.1) | KEY element-name
|
The same attributes may be used for the KEY keyword
that are used for the ELEMENT keyword, except OCCURRENCE.
------------------------|-----------------------------------------------------
ELEMENT (5.1) | ELEMENT element-name
|
LENGTH (5.1.2) | LENGTH n[,MINIMUM|,MAXIMUM|,EXACT]
OCCURRENCE(5.1.3) | OCCURRENCE n
SINGLE (5.1.3) | SINGLE
INDEX (5.1.4) | INDEX element-name
INDEX * (5.1.4a) | INDEX *
RECNAME (5.1.4) | INDEX/ RECNAME record-name (up to 6 characters)
INDIRECT (5.1.4b) | INDIRECT subfile-name,indirect-index ...
| ... [,search-terms]
REDEFINES (5.1.7) | REDEFINES element-name
SUBFILE (5.1.7a) | SUBFILE subfile-name
SUBGOAL (5.1.7a) | SUBGOAL record-type-name
PRIV-TAG (5.1.8) | PRIV-TAG n
|
Element Types | See Appendix B for LENGTH specifications and
| processing rules added for each element type.
|
| If no element type is specified, TEXT is assumed.
|
TEXT (5.1.5.1) | TEXT
DATE (5.1.5.2) | DATE [ADD|UPDATE]
TIME (5.1.5.3) | TIME [ADD|UPDATE|HOURS.FIRST|SECONDS.LAST ...
| ... INT.ADD|INT.UPDATE|INT.HOURS.FIRST| ...
| ... INT.SECONDS.LAST]
ACCOUNT (5.1.5.3a) | ACCOUNT [ADD|UPDATE|ONCE|ALWAYS]
NAME (5.1.5.4) | NAME
DOLLAR (5.1.5.5) | DOLLAR
INTEGER (5.1.5.6) | INTEGER [n]
REAL (5.1.5.7) | REAL
HEX (5.1.5.8) | HEX
BITS (5.1.5.9) | BITS [n]
ENCODE (5.1.5.10) | ENCODE string,string,string. . .
YESNO (5.1.5.11) | YESNO
XEQ (5.1.5.12) | XEQ
SLOT|SLOTCHECK | SLOT|SLOTCHECK
(5.1.5.13) |
STRUCTURE (5.1.5.14, | STRUCTURE [n]
5.3) |
PACKED (5.1.5.15) | PACKED [n]
DECIMAL (5.1.5.16) | DECIMAL m.n
|
Processing Rules | See Appendix B for processing rules added for
| each attribute.
|
CAPITALIZE (5.1.6.1) | CAPITALIZE
LOWER (5.1.6.2) | LOWER
SQUEEZE (5.1.6.3) | SQUEEZE
BREAKUP (5.1.6.4) | BREAKUP [string]
| Default: ' ' (blank)
WORD (5.1.6.5) | WORD
TRUNCATE (5.1.6.6) | TRUNCATE [character]
| Default: #
CHANGE (5.1.6.7) | CHANGE string1A,string1B [,string2A,string2B. . .]
INSETL (5.1.6.8) | INSETL string,n
INSETR (5.1.6.9) | INSETR string,n
INSERT (5.1.6.10) | INSERT string,{RIGHT|LEFT|END|FRONT}[,n]
EDIT (5.1.6.11) | EDIT mask
EXCLUDE (5.1.6.12) | EXCLUDE [string,string,string. . .]
| Default: EXCLUDE(COMMON.WORDS)
INCLUDE (5.1.6.13) | INCLUDE string[,string,string. . .]
RANGE (5.1.6.14) | RANGE m,n
LSTRING (5.1.6.15) | LSTRING n
TRANSLATE (5.1.6.16) | TRANSLATE input set,output set
LOOKUP (5.1.6.17) | LOOKUP {VERIFY|REPLACE},record-name,element-name
MSG (5.1.6.18) | MSG string
DEFAULT (5.1.6.19) | DEFAULT string
CLOSEOUT (5.1.6.20) | CLOSEOUT rule
CALL (5.4.1) | CALL userproc-name
|
Element Information |
Packets |
|
HEADING (5.1.9.1) | HEADING string
COL-HEADING (5.1.9.2) | COL-HEADING "string//string//string"
NOTE (5.1.9.3) | NOTE string
WIDTH (5.1.9.4) | WIDTH n
ADJUST (5.1.9.5) | ADJUST {LEFT|RIGHT|CENTER|TRUNCATE| ...
| ... JUSTIFY|ALIGN}
INDENT (5.1.9.6) | INDENT N
MAXROWS (5.1.9.7) | MAXROWS N
INFO EDIT (5.1.9.8) | INFO EDIT edit-mask[/divisor]
VALUE-TYPE (5.1.9.9) | VALUE-TYPE [NUMERIC|CODED|DATE|MONTH| ...
| ... TIME|DOLLAR|YESNO|BITS|HEX| ...
| ... STRUCTURED|TEXT]
INFO INDEX (5.1.9.10) | INFO INDEX searchterm[,searchterm...]
INPUT-OCC (5.1.9.11) | INPUT-OCC n
INFO DEFAULT | INFO DEFAULT value
(5.1.9.12) |
SUPPLIED (5.1.9.13) | SUPPLIED value
------------------------|-----------------------------------------------------
GLOBAL (5.2) | GLOBAL
------------------------|-----------------------------------------------------
INPROC (5.3) | INPROC rule-string
|
OUTPROC (5.3) | OUTPROC rule-string
------------------------|-----------------------------------------------------
SEARCHPROC (5.6) | SEARCHPROC rule-string
|
PASSPROC (5.6) | PASSPROC rule-string
------------------------|-----------------------------------------------------
USERPROC (5.4.1) | USERPROC userproc-name
|
VARIABLE (5.4.3) | VARIABLE variable-name/ type
| [/ LENGTH n/ OCCURRENCE n]
TYPE (5.4.3) |
LENGTH (5.4.3) |
OCCURRENCE (5.4.3) |
ACCOUNT ADD
INPROC = $GEN.ACCT(ADD)
ELEMINFO;
SUPPLIED = Your account
ACCOUNT UPDATE
INPROC = $GEN.ACCT(UPD)
ELEMINFO;
SUPPLIED = Your account
BITS
INPROC = $BITS(1)
OUTPROC = $BITS(1)
ELEMINFO;
VALUE-TYPE = BITS
BREAKUP *
INPROC = $BREAK('*')
OUTPROC = $BUILD('* ')
BREAKUP '#$%'
INPROC = $TRANS('$%','#')/ $BREAK('#')
OUTPROC = $BUILD('# ')
CALL userproc-name
INPROC = $CALL(userproc-name)
CAPITALIZE
INPROC = $CAP
CHANGE value,value
INPROC = $CHANGE('value','value')
CHANGE value,value,value,value (more than two values)
INPROC = A48:0,'value','value','value','value'
DATE
LEN = 4
INPROC = $DATE
OUTPROC = $DATE.OUT
ELEMINFO;
VALUE-TYPE = DATE
DATE ADD
LEN = 4
INPROC = $DATE/ $GEN.DATE(ADD)
OUTPROC = $DATE.OUT
ELEMINFO;
VALUE-TYPE = DATE
SUPPLIED = Today's date
DATE UPDATE
LEN = 4
INPROC = $DATE/ $GEN.DATE(UPD)
OUTPROC = $DATE.OUT
ELEMINFO;
VALUE-TYPE = DATE
SUPPLIED = Today's date
DECIMAL 4.2
INPROC = $PACK(MAXLEN,5)/ $RANGE(0,2,DEC)/
$RANGE(-1,4,MAG)/ $DECIMAL(2)
OUTPROC = $PACK.OUT
ELEMINFO;
ADJUST = RIGHT
VALUE-TYPE = NUMERIC
DEFAULT value
INPROC = $DEFAULT('value')
ELEMINFO;
DEFAULT = value
DOLLAR
LEN = 4
INPROC = $DOLLAR
OUTPROC = $DOLLAR.OUT
ELEMINFO;
ADJUST = RIGHT
VALUE-TYPE = DOLLAR
EDIT mask
INPROC = $EDIT(mask)
ELEMINFO;
EDIT = mask
ENCODE value,value,value
LEN = 1
INPROC = $ENCODE('value,value,value')
OUTPROC = $DECODE('value,value,value')
ELEMINFO;
VALUE-TYPE = CODED
EXCLUDE value,value
INPROC = $EXCLUDE('value,value')
HEX
LEN = 4
INPROC = $HEX
OUTPROC = $HEX.OUT
ELEMINFO;
VALUE-TYPE = HEX
INCLUDE value,value
INPROC = $INCLUDE('value,value')
INSERT value,BEFORE,n
INPROC = $INSERT(value,BEFORE,n)
INSETL value,n
INPROC = $INSETL(value,n)
INSETR value,n
INPROC = $INSETR(value,n)
INTEGER
LEN = 4
INPROC = $INT(4)
OUTPROC = $INT.OUT
ELEMINFO;
ADJUST = RIGHT
VALUE-TYPE = NUMERIC
LOOKUP VERIFY,record-name,element-name
INPROC = $LOOKUP(VERIFY,record-name,element-name)
LOWER
INPROC = $LOWER
LSTRING n
INPROC = $LSTR(n)
MSG text
INPROC = $MSG('text')
NAME
INPROC = $NAME
OUTPROC = $NAME
ELEMINFO;
VALUE-TYPE = TEXT
PACKED 2
LEN = 2
INPROC = $PACK(,2)
OUTPROC = $PACK.OUT
ELEMINFO;
ADJUST = RIGHT
VALUE-TYPE = NUMERIC
INTEGER/ RANGE m,n
INPROC = $RANGE(m,n,INT,S)
ELEMINFO;
ADJUST = RIGHT
VALUE-TYPE = NUMERIC
REAL/ RANGE m,n
INPROC = $RANGE(m,n,REAL,S)
ELEMINFO;
ADJUST = RIGHT
VALUE-TYPE = NUMERIC
REAL
LEN = 4
INPROC = $REAL
OUTPROC = $REAL.OUT
ELEMINFO;
ADJUST = RIGHT
VALUE-TYPE = NUMERIC
SQUEEZE
INPROC = $SQU
TIME
LEN = 2
INPROC = $TIME
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
TIME ADD
LEN = 2
INPROC = $TIME/ $GEN.TIME(ADD)
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
SUPPLIED = Current time
TIME UPDATE
LEN = 2
INPROC = $TIME/ $GEN.TIME(UPD)
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
SUPPLIED = Current time
TIME HOURS.FIRST
LEN = 2
INPROC = $TIME(HOURS.FIRST)
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
TIME SECONDS.LAST
LEN = 2
INPROC = $TIME(SECONDS.LAST)
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
TIME INT.ADD
LEN = 4
INPROC = $TIME(INT)/ $GEN.TIME(ADD)
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
SUPPLIED = Current time
TIME INT.UPDATE
LEN = 4
INPROC = $TIME(INT)/ $GEN.TIME(UPD)
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
SUPPLIED = Current time
TIME INT.HOURS.FIRST
LEN = 4
INPROC = $TIME(INT.HOURS.FIRST)
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
TIME INT.SECONDS.LAST
LEN = 4
INPROC = $TIME(INT.SECONDS.LAST)
OUTPROC = $TIME.OUT
ELEMINFO;
VALUE-TYPE = TIME
TRANSLATE input set,output set
INPROC = $TRANS(input set,output set)
TRUNCATE
SEARCHPROC = $SEARCH.TRUNC(#)
WORD
INPROC = $WORD
OUTPROC = $BUILD(' ')
ELEMINFO;
VALUE-TYPE = WORD
YESNO
LEN = 1
INPROC = $YESNO
OUTPROC = $YESNO.OUT
ELEMINFO;
VALUE-TYPE = YESNO
----------------------------------------------------------------------
File Definer | Default values supplied | Default values
element type | in the element information | supplied in the
| packets | index information
| | packets
-----------------|------------------------------|---------------------
| VALUE-TYPE ADJUST | VALUE-TYPE
-----------------|------------------------------|---------------------
NAME | TEXT | NAME
DATE | DATE | DATE
TEXT | TEXT | TEXT
TIME | TIME | TIME
INTEGER | NUMERIC RIGHT | NUMERIC
REAL | NUMERIC RIGHT | NUMERIC
DOLLAR | DOLLAR RIGHT | DOLLAR
YESNO | YESNO | YESNO
ENCODE | CODED | CODED
BITS | BITS | BITS
HEX | HEX | HEX
PACKED | NUMERIC RIGHT | NUMERIC
DECIMAL | NUMERIC RIGHT | NUMERIC
STRUCTURE n | STRUCTURED * |
SLOT | NUMERIC RIGHT | NUMERIC
SLOTCHECK | NUMERIC RIGHT | NUMERIC
* Only if $STRUC.IN/$STRUC.OUT processing rules are used.
[See 5.3]
If an element is indexed, the File Definer also supplies a SOURCE
statement in the index information packet and an INDEX statement
in the element information packet.
In addition, the File Definer supplies element information
statements according to the table below.
---------------------------------------------------
File Definer | Element information statement
attribute | supplied by File Definer
-------------------|-------------------------------
|
TRUNCATE character | TRUNCATE = character
|
EDIT mask | EDIT = mask
|
WORD | VALUE-TYPE = WORD
|
DEFAULT value | DEFAULT = value
|
DATE ADD | SUPPLIED = Today's Date
DATE UPDATE |
|
TIME ADD | SUPPLIED = Current time
TIME UPDATE |
TIME INT.ADD |
TIME INT.UPDATE |
|
ACCOUNT | SUPPLIED = Your account
(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.