INDEX
*  SPIRES System Procs
+  Introduction to this Manual
+1  Acknowledgments
1  Introduction to System Procs; Special Considerations
1.1  The General Form and Rules of System Procs
1.2  System Procs and Actions
1.3  System Procs and Compilation
1.3.1  Passproc Syntax
1.4  Specifying Special Characters in System Proc Parameters
1.4.1  Special Characters Rule Set 1
1.4.2  Special Characters Rule Set 2
1.4.3  Special Characters Rule Set 3
1.4.4  Standard Record Entry Rules
1.5  Common System Proc Parameters
1.5.1  The "error" Parameter
1.5.2  The MSG Parameter
1.5.3  The ADD and UPD Symbols
1.5.4  The "element" Parameter
2  System Proc Descriptions
2.0.1  ($ADJUST)
2.0.1a  ($ASCII)
2.0.2  ($AUGMENT)
2.0.3  ($BG)
2.0.4  ($BITS)
2.0.5  ($BOLD)
2.0.6  ($BREAK and $BREAK.HEX)
2.0.7  ($BUILD)
2.0.8  ($CALL)
2.0.9  ($CAP)
2.1.0  ($CHANGE and $CHANGE.HEX)
2.1.1  ($CHANGE.LIST)
2.1.2  ($CHECK)
2.1.3  ($CHECK.OUT)
2.1.4  ($COMPRESS)
2.1.5  ($DATE)
2.1.5a  ($DATE.IN)
2.1.5b  ($DATE.IN.CC)
2.1.6  ($DATE.OUT)
2.1.6a  ($DATE.OUT.CC)
2.1.6b  ($DATEYY)
2.1.6c  ($DATEYY.OUT)
2.1.7a  ($DATETIME.IN)
2.1.7b  ($DATETIME.OUT)
2.1.8  ($DECIMAL)
2.1.8a  ($DECIMAL.ADJ)
2.1.8b  ($DECIMAL.OUT)
2.2.0  ($DECODE)
2.2.1  ($DEFAULT)
2.2.1a  ($DEFAULT.COND)
2.2.2  ($DISCARD)
2.2.3  ($DOLLAR)
2.2.4  ($DOLLAR.OUT)
2.2.5  ($EDIT)
2.2.6  ($ENCODE)
2.2.7  ($ENCRYPT)
2.2.7a  ($EVAL)
2.2.8  ($EXCLUDE)
2.2.9  ($EXPAND)
2.3.0  ($FIND)
2.3.1  ($FIXED.NUM)
2.3.2  ($GEN.ACCT)
2.3.3  ($GEN.DATE)
2.3.3a  ($GEN.DATETIME)
2.3.4  ($GEN.TIME)
2.3.5  ($GETELEM)
2.3.5a  ($GOAL.INDEX)
2.3.6  ($HEX)
2.3.7  ($HEX.OUT)
2.3.8  ($INCLUDE)
2.3.9  ($INSERT and $INSERT.HEX)
2.4.0  ($INSETL)
2.4.1  ($INSETR)
2.4.2  ($INT)
2.4.3  ($INT.OUT)
2.4.4  ($ITALIC)
2.4.5  ($LENGTH)
2.4.6  ($LOGICAL)
2.4.6c  ($LOOKSUBF)
2.4.7  ($LOOKSUBG)
2.4.7a  ($LOOKSYS)
2.4.8  ($LOWER)
2.4.9  ($LSTR)
2.5.0  ($MAX.LEN)
2.5.1  ($MAX.OCC)
2.5.2  ($MIN.LEN)
2.5.3  ($MIN.OCC)
2.5.4  ($MSG)
2.5.5  ($NAME)
2.5.6  ($NOPASS)
2.5.7  ($NULL)
2.5.8  ($OCC)
2.5.9  ($PACK)
2.6.0  ($PACK.OUT)
2.6.1  ($PACK.TEST)
2.6.2  ($PARAGRAPH)
2.6.3  ($PASS)
2.6.4  ($PASS.BY)
2.6.5  ($PASS.COND)
2.6.6  ($PASS.DEF)
2.6.7  ($PASS.ELEM)
2.6.8  ($PASS.FIELD)
2.6.9  ($PASS.LCTR)
2.7.0  ($PASS.LEN)
2.7.1  ($PASS.OCC)
2.7.2  ($PASS.UPPER)
2.7.3  ($PHONETIC)
2.7.4  ($PHONETIC.SEARCH)
2.7.5  ($PNAME)
2.7.6  ($PRECISION)
2.7.6a  ($PROXIMITY)
2.7.7  ($PUTELEM)
2.7.8  ($RANGE)
2.7.9  ($REAL)
2.8.0  ($REAL.OUT)
2.8.0a  ($REPARSE)
2.8.1  ($REQUIRED)
2.8.2  ($RESTORE)
2.8.2a  ($RSTR)
2.8.2b  ($SEARCH.DATE and $SEARCH.DATE.CC)
2.8.3  ($SEARCH.LOGOP)
2.8.3a  ($SEARCH.PHRASE)
2.8.4  ($SEARCH.QUAL)
2.8.4a  ($SEARCH.ROUTE)
2.8.4b  ($SEARCH.SUBF)
2.8.5  ($SEARCH.TRUNC)
2.8.6  ($SHIFT)
2.8.6a  ($SIN)
2.8.6b  ($SIN.OUT)
2.8.7  ($SORT)
2.8.8  ($SQU)
2.8.9  ($SSN)
2.9.0  ($SSN.OUT)
2.9.1  ($STORE)
2.9.2  ($STRUC)
2.9.3  ($STRUC.IN)
2.9.4  ($STRUC.OUT)
2.9.6  ($SUBSTR)
2.9.7  ($TEST.ACCT)
2.9.8  ($TEST.ELEM)
2.9.9  ($TEST.LEN)
2.10.0  ($TEST.OCC)
2.10.0b  ($TEST.UNIQUE)
2.10.1  ($TIME)
2.10.2  ($TIME.OUT)
2.10.3  ($TRANS and $TRANS.HEX)
2.10.4  ($TRANS.NULL)
2.10.5  ($TRIM)
2.10.5a  ($UNEDIT)
2.10.5b  ($UNIQUE.KEY)
2.10.6  ($UPPER)
2.10.7  ($VERIFY)
2.10.7a  ($VERIFY.SUBSTR)
2.10.8  ($WINDOW)
2.10.9  ($WORD)
2.10.9a  ($XSTR)
2.11.0  ($YESNO)
2.11.1  ($YESNO.OUT)
3  Indexes for System Procs
3.1  Action Cross-Reference
3.2  System Procs by Function
3.2.1  * string values
3.2.2  * binary values
3.2.3  * floating-point values
3.2.4  * packed decimal values
3.2.5  * hexadecimal values
3.2.6  * bit values
3.2.7  * money values
3.2.8  * date values
3.2.9  * time values
3.2.10  * personal name values
3.2.11  * structures
3.2.12  * numeric strings
3.2.13  * account values
3.2.14  * yes/no values
3.2.15  * multiple occurrences -- break, build
3.2.16  * value generation
3.2.17  * length testing
3.2.18  * occurrence testing
3.2.19  * including or excluding values
3.2.20  * value translation
3.2.21  * printing translations
3.2.22  * PASSPROC only rules
3.2.23  * SEARCHPROC only rules
3.2.24  * special purpose rules
3.3  Alphabetic Listing of System Procs and their Purposes
:
:29  SPIRES Documentation

*  SPIRES System Procs

******************************************************************
*                                                                *
*                     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.

+  Introduction to this Manual

This document is the reference manual for SPIRES System Procs, a collection of processing rules useful to writers of file and format definitions. The manual is written for people already familiar in general with processing rules (INPROCs, OUTPROCs, PASSPROCs, SEARCHPROCs and INCLOSEs). (Users who write format and record definitions may only be familiar with INPROCs and OUTPROCs.) The primary source for information about processing rules is the SPIRES reference manual "File Definition". Below is a chart listing the major topics concerning processing rules, along with the chapter numbers in "File Definition" where they are discussed:

You may not need to be familiar with all that material in order to handle your own application. For example, if you are working with a file definition created by the File Definer and you want to make a change to one INPROC, you probably need to be familiar only with section B.4.3 of "File Definition". (Of course, for you to even know that it is an INPROC you want to change, you will have to have some familiarity with the concepts of processing rules in the first place.)

You may need to know about other areas of file definition to use some procs. The proc $CALL, for example, is not useful unless you understand USERPROCs, which are described in chapter C.11 of "File Definition". Cross references to the appropriate chapter of "File Definition" appear within the descriptions of such procs in this manual.

Although the main reference source for the background information is the "File Definition" manual, the primer "A Guide to File Definition", sections 3, 6.3 and 6.4, is an alternate source for the most important information; unlike the "File Definition" reference manual, its emphasis is on the use of system procs, rather than actions, for processing rules.

In any case, if there is a topic or word that you do not understand, try issuing the EXPLAIN command to get an explanation, as well as a cross reference to the manual and the section within it in which the topic is discussed. Note that a complete list of all available SPIRES documents is included as an appendix to this and other SPIRES manuals.

The EXPLAIN command can also be used to get online information extracted from this manual. You can get the complete description of any system proc by issuing the command "EXPLAIN $procname PROC", where "$procname" is the name of the desired proc.

Smaller subsets of each proc description are also available online. The command "SHOW EXAMPLE $procname PROC" will display the sections of the named proc's description that are marked with the word "Example"; this is very handy if you want to simply see how the proc is commonly used. The command "SHOW SYNTAX $procname PROC" will display the sections of the description marked "Syntax and Parameters" and "System Proc Expansion". Issuing that command is the fastest way to get details on how to specify the proc in a processing rule string.

If you are working online and do not have a copy of this manual near, there is an easy way to find specific system procs when you forget their names. All of the index entries in the back of the manual that are marked with an asterisk (*) may also be explained online. For example, "EXPLAIN SYSTEM PROCS" will give you a large menu of sub-topics, such as "SYSTEM PROCS, FOR YES/NO VALUES" or "SYSTEM PROCS, FOR DATE VALUES". Choosing the appropriate sub-topic will give you a list of system procs in that particular area, and each proc in the list can be explained as described above.

+1  Acknowledgments

Many people contributed to the development of system procs, and we want to gratefully acknowledge that support. The basic collection of system procs was developed in 1979 by John Habrovansky (who was then working for the Research Libraries Group), with additions or alternate designs suggested by Guy Scharf of C.I.T.'s Administrative Information Systems. Dick Guertin of the C.I.T. Data Base Management Division, who is currently in charge of supporting system procs, has also been responsible for several procs and innumerable adjustments to others. Many SPIRES users participated in the testing and fine-tuning of them, including people who created file definitions with the File Definer subsystem, which has used system procs in place of most actions since its inception.

The first draft of this document was written by Becky Morton, with subsequent drafts by John Klemm. The writers are grateful to John Sack, director of the Data Base Management Division, whose support did not waver, even as the deadlines did. Thanks also to those who reviewed this lengthy manual in its several versions; their hard work in double- and triple-checking the accuracy of the myriad details in this manual was greatly appreciated.

The published version of this manual was printed on the Xerox 9700. The cover was constructed by Dana Madsen of C.I.T.'s Technical Support Services.

1  Introduction to System Procs; Special Considerations

Processing rules are used in SPIRES file definitions and formats to test and convert element values when records are added and updated (INPROCs) or displayed (OUTPROCs). They are also used in file definitions to test and convert element values being passed to indexes (PASSPROCs) or to test and convert values provided by the searcher trying to use those indexes (SEARCHPROCs). Also, a special type of INPROC known as an INCLOSE rule can be used to generate element values on record input.

The basic form of processing rule is called an "action". Actions have their own special language and coding rules. An action is specified by the letter A followed by a number, optionally followed by a colon and one or more parameter values that either alter the specific details of the action processing or provide values to be used by the action. Two examples of valid actions are:

If you are not familiar with the action language, you would not know (or perhaps even suspect) that the first action, A30, tells SPIRES to convert the element value to uppercase, or that the second action tells SPIRES to convert any occurrence of the character string AUTUMN to the string FALL in the element value. [See "SPIRES File Definition", section B.4, for more information on action specification.]

Actions become easier to use when a capability known as "procs" is used. A "proc" is a string of one or more actions denoted by a name. It is defined by the file (or format) designer, who places its definition either in the file or format definition or in a separate record in the PROCDEF subfile. By referring to the proc's name in a processing rule string, the file designer can invoke that string of actions. For example, a proc named CAP could represent the action A30 described above. Procs can also pass parameter values into the action string; a proc such as CHANGE(AUTUMN,FALL) could be equivalent to the A44 rule string above. Procs can thus be easier to use, since they can replace abstract symbols with meaningful names, depending on how they are designed. [See "SPIRES File Definition", section C.10, for further information about procs.]

"System procs" are a collection of predefined procs that were designed to simplify the coding of processing rules. Though many of the procs with their parameters correspond one-to-one to single actions, many others were designed to combine actions frequently used together or to automatically supply the most commonly used parameters. A given action usually provides a very general capability, whose specific details must be modified by various parameters. Many of the system procs convert a generalized action into a rather specific proc, thus relieving you of the need to remember many specific coding details of the actions.

Compared to actions then, system procs generally are easier to specify. They are certainly easier to learn and remember. They also help make file definitions easier to read.

System procs resemble SPIRES functions. They are preceded by a dollar sign ($) and may be followed by one or more parameters, enclosed within parentheses: $CAP or $CHANGE(AUTUMN,FALL). Many of the procs have the same purpose as parallel SPIRES functions; often a proc and a function share the same name and may have the same or similar parameters. An important distinction between them is that a function's first parameter is always the value being operated on; in a proc, that value is always the current element value (the value of the element as the processing begins) and thus does not need to be specified in a parameter.

System procs can appear practically anywhere that actions can. They may be specified in INPROC, OUTPROC, PASSPROC and SEARCHPROC statements in a file definition or in INPROC and OUTPROC statements in a format or record definition. With some restrictions, they may even appear within a RULE statement in a file definition or PROCDEF record. [See 1.2.]

The individual system procs are described in detail in chapter A.2 of this manual, where they are arranged in alphabetical order. Chapter A.3 provides several indexes to help you find system procs to meet particular requirements.

The remainder of this chapter will discuss rules and details of using system procs -- how they relate to actions, how they are handled during compilation, and how parameters are specified. In particular, in regard to the last item, this chapter will discuss how special characters within parameter values must be handled and how to use several standard parameters that are used by multiple procs, such as "error" and "message" parameters. Be sure you are familiar with the material in this chapter before you start using system procs.

1.1  The General Form and Rules of System Procs

System procs are identified by the dollar sign ($) that precedes each of their names, e.g., $BREAK, $PASS. If a proc's name is composed of two "words", they are connected by a period: $FIXED.NUM, $PASS.ELEM, etc.

Most of the procs have one or more parameters, which are specified within parentheses following the name of the proc. Parameters are used to provide values for the proc to use. For example, in "$CHANGE(AUTUMN,FALL)", you are providing the value to be searched for and the value to which it should be changed. Parameters are also used to specify a particular form of processing that SPIRES should do. For example, the proc "$VERIFY(LIKE,ALPHA)" tells SPIRES to verify that the element value only contains alphabetic characters. In many cases, a system proc has been designed so that the basic processing done by SPIRES is what most people using the proc want. When that is the case, you may not need to specify any parameters for the proc, even though it does allow some.

The parameters for each proc are described in detail in chapter A.2. Rules for specifying parameters in general will be discussed here.

1) Parameters are specified as a group of values within parentheses following the proc name. A blank may be placed between the proc name and the parameter list if desired:

2) Each parameter is separated from the other by a comma and optional blanks.

Note that the blanks are not considered part of the parameter values. Blanks to be included in parameter values are considered special characters. To include a blank as part of a parameter value, you must follow the rules for special characters. [See 1.4.] You must also apply those rules if your parameter value contains one or more of these special characters: a comma [,], a slash [/], a colon [:], a semicolon [;], an apostrophe ['], a quotation mark ["], a right parenthesis [)] or a line feed [hex 25].

3) No single parameter may contain more than 255 characters. This is an important rule to remember when you are using a proc such as $ENCODE, $INCLUDE or $CHANGE.LIST, where a single parameter may actually be a list of many values. The total length of the list must be no greater than 255 characters. If the list would be longer than that, you may need to use the appropriate action, rather than the system proc. Alternatively, in some cases, you may be able to use the proc twice.

4) A distinction is made between two types of parameters in the system proc descriptions. Consider the form of the proc $INT, which verifies that the element value is an integer and then converts it into a binary form:

It has three parameters: "length", "error" and MSG. The parameters in lower case represent values that are supplied by the file or format designer -- that is, you replace the word "length" with a value, either from a list of reserved words or in some cases a value that you create yourself. Such parameters are called symbolic parameters, because the lowercase parameter name symbolizes another value that replaces it.

The other type of parameter is called a "literal" parameter, as represented by the parameter MSG, which is in uppercase. When you want to specify a literal parameter, you specify the parameter name itself in the parameter list. Generally either that or nothing is coded for such a parameter.

For example, you might code the $INT proc like this:

where you provided values for the two symbolic parameters and specified the name of the literal parameter as the last parameter.

As mentioned, symbolic parameters often have reserved words that may be used for their values. For example, the "input" and "output" values for the $CHANGE proc

both have the reserved words BLANK and COMMA. The proc $CHANGE(COMMA,BLANK) means "change all commas in the element value to blanks". These reserved words, called "symbols", are each described in the proc descriptions. Do not place symbols within apostrophes; if you do, they will be interpreted as literal strings rather than symbols to be replaced.

5) Processing rule parameters are "positional parameters", meaning that the parameters shown for a given proc must be specified in the order in which they are shown; otherwise, they will be misinterpreted. The first parameter must always appear before the first comma, the second must appear between the first and second commas, and so forth.

6) Each parameter has a default value. If no value is specified for that parameter, the default value will be taken. In many cases, such as $INT, the default parameter values are the most commonly chosen ones. If you want a parameter to keep its default value, you specify no value for it and SPIRES will take the default.

There are two ways to declare "no value". First, if they are the last parameters in the string, they may be left out entirely, along with the preceding and intervening commas. For example, $INT(BYTE) indicates that the second and third parameters, "error" and MSG, have not been given values, so the default values for those parameters will be in effect. In general, system procs have been designed such that the least used parameters are the last ones in each parameter list.

The second way to declare "no value" is used when the "no value" parameter(s) precedes a parameter being specified, in which case the "no value" parameter's position must be represented by the placement of commas. For example, $INT(,,MSG) indicates that the first and second parameters, "length" and "error", are not being given values, meaning "take the default procedure as described". Often, for readability of the code, it is worthwhile to specify the default value, if possible, rather than have to interpret a string of commas later.

1.2  System Procs and Actions

System procs are almost completely interchangeable with actions. The following two rule strings, one comprised of actions and the other of system procs, have the same effect:

A rule string may be comprised of a mixture of system procs, actions and procs you defined yourself.

All but one system proc may be used in user-defined procs, as long as that user-defined proc is not in turn called by another proc. In other words, procs, whether they are system procs or user-defined procs, may only be nested one deep: a proc may call another proc, but that proc may not call a third one. The one system proc that cannot be used in another proc is $PHONETIC.SEARCH, because it already calls another proc, $PHONETIC.

As noted before, system procs are comprised of actions, the basic form of processing rules in SPIRES. The relationship between a system proc and the action or actions that it is made of depends on the number of and the meaning of the parameters involved. The values of some system proc parameters may be identical to the values that you would use in parameters for the action. On the other hand, a parameter value may be a symbol that the proc translates into appropriate values for the action.

Consider these examples. The proc $PUTELEM has three parameters, the first of which is "element", the name of an element. Values supplied for "element" are placed directly into action A147. The proc $GEN.TIME has a single parameter, "how", which has four symbols that can be used. The symbols ONCE and ADD, which both mean that the proc should only supply the current time if no value has already been supplied, are converted to the number 0 for the P1 parameter of the action. The other two symbols, ALWAYS and UPD (for "update"), which mean that the proc should supply the current time regardless of whether a value has already been supplied, are converted to the number 1 for the P1 parameter of the action. These four symbols, which have more meaning in regard to the purpose of the proc than the numbers 0 or 1, are described in detail in the description of $GEN.TIME in the next chapter.

Although most users would choose ADD or ONCE rather than 0 (preferring the symbol to the P1 parameter), the action parameter can be coded directly: $GEN.TIME(0) is equivalent to $GEN.TIME(ONCE), though its meaning is not as easy to determine. In other words, if the value given for a system proc parameter does not match any of the allowed symbols for that parameter, the value will be passed on to the action, being inserted at the appropriate place within it. "The appropriate place" may be the place where one of the parameters of the action is specified, or the position where the error level is specified or one of several other locations within an action that may be used by proc parameters. If you want to use values other than the given symbols for a proc, be sure that you have examined and understood the "System Proc Expansion" section of each system proc description as it appears in the next chapter. [See 2.] The "System Proc Expansion" shows how SPIRES translates each system proc and its parameters into an action rule string.

1.3  System Procs and Compilation

When you compile a file definition that contains system procs, the compiler first substitutes the appropriate actions and parameter values for each system proc given. Then the actual compilation can begin.

Though the use of system procs should reduce the number of compilation errors by making processing rules easier to specify, it does not eliminate them. Because the compiler is examining actions during compilation, error messages may display the action or actions into which a proc was converted, as well as the actual proc.

For example, the $INT proc has these parameters:

If by accident we coded BYTE, the value for "length", as the value for "error":

we would get error messages from the compiler, as shown below:

Here you see first the action to which the proc was converted (BYTE, since it was specified for the "error" proc, appears where the error level should be, i.e., right after the "A"). Later, the original proc is shown as well.

You can use the EXPLAIN command in SPIRES to read more about the error messages: EXPLAIN INPROC ERROR or EXPLAIN INVALID ACTION SYNTAX, for example.

Note that procs, like actions, are not checked for validity when the file definition containing them (or format or record definition) is added to the FILEDEF (or FORMATS or RECDEF) subfile. That activity occurs only during compilation.

1.3.1  Passproc Syntax

When you compile a file definition that contains PASSPROC rules, you may encounter an INVALID SYNTAX error. That may mean you have placed PASSPROC rules in the wrong order.

Here is a table describing the order of PASSPROC rules:

Names like [NAME] are the definition, and terms which follow are the components of that definition. Alternative definitions occur on blank-indented lines under the definition. Names like <LAST> are required components. Names like (DEFAULT) are one-time optional components. Names like {MIDDLE} are multiply occurring optional components. Lastly, [MIDDLE] is defined as a set of alternatives separated by |. Choose one alternative for each occurrence of a {MIDDLE} component.

1.4  Specifying Special Characters in System Proc Parameters

This section explains in detail how to specify parameter values in system procs that have special characters. Most uses of system procs do not involve special characters and thus do not need to take these rules into account. However, you should know where these rules are documented (here) and to what they apply.

The rules described here are split into three sets. [See 1.4.1, 1.4.2, 1.4.3.] For any proc that may need these rules, a note in the description of that proc in the next chapter explains which set of rules should be applied to the parameter value. The value may be either a string value or a hex value, which is represented like this: #C3F0#, i.e., pairs of hex characters surrounded by pound signs. Note: not all parameters allow hex values -- those following rule set 1 don't allow them, those following rule set 2 do allow them, and those following rule set 3 may or may not allow them, as described in the parameter's description.

The special characters to which these rules apply are the following:

Special characters can make the coding of a system proc somewhat complicated, especially when rule set 3 is used. In such cases, it may be easier to code the basic action. For example, you might find that the following action:

is easier to code and read than the equivalent system proc:

1.4.1  Special Characters Rule Set 1

In the system proc expansion, if the individual parameter itself is in apostrophes (e.g., &input in $CHANGE: A&err44:&len,'&input','&output'), then the following rules apply:

Examples for rule set 1:

1.4.2  Special Characters Rule Set 2

The second set of special-character rules apply to a parameter if both of the following are true:

If both conditions are true, then the following rules apply:

Examples for rule set 2:

This set of rules, more complicated, is meant to be used less frequently. Only a few system procs require them. Three of them, $CHANGE.HEX, $BREAK.HEX and $TRANS.HEX, are primarily aimed at hex character representation anyway and have parallels whose names lack the ".HEX" that can be used with the first set of rules.

1.4.3  Special Characters Rule Set 3

Perhaps the most complicated use of special characters is when you are trying to specify multiple values in a single proc parameter value, as in $ENCODE (the '&values' parameter: A&err46:&type,&values). You must first apply the rules for multiple values in actions:

Then you apply the following system proc rules:

Finally, if necessary, you would apply any record entry rules that apply to quotation marks and semicolons. [See 1.4.4.]

Hex values may or may not be allowed; see the specific proc description.

The example below is admittedly more complicated than you'd ever hope to see.

Example for rule set 3:

You want to ENCODE the following values, which form a single value for the "values" parameter:

First, apply the set of rules for multiple values in an action:

Then apply the set of rules for system proc parameters. To begin, double all apostrophes:

Then put apostrophes around the entire parameter value:

Finally you may need to apply the rules for standard format data entry:

1.4.4  Standard Record Entry Rules

Probably you will use system procs within a file or format definition in which you enter the specifications in the standard SPIRES format, in which case the standard record entry rules must be followed. These rules apply to the entire element value, that is, to the entire INPROC, OUTPROC, SEARCHPROC or PASSPROC string, not just to a single proc or single proc parameter in the string.

These rules would be applied at the time shown in the final example above, that is, after the other rules have been applied. Note that they would apply to the examples shown for semicolons and quotation marks in the first two sets of rules. They were not applied there since they should be done only in the context of the actual rule as an element value.

If you are using the File Definer subsystem to create a file definition, File Definer will take care of the standard record entry rules when you use the INPROC or OUTPROC keyword attributes.

1.5  Common System Proc Parameters

Many of the system procs have specific parameters in common. For example, most of them have an "error" parameter, representing the error level of the proc. Others have a MSG parameter, which provides a special error message when a processing error occurs. This section will cover details of several of the most common system proc parameters. These details are generally not repeated within the system proc descriptions.

1.5.1  The "error" Parameter

Often a system proc is used to test an element value. If the test fails, the "error flag" is set. For example, $CHANGE will set the error flag if the element value does not contain the string (the "input" parameter) being searched for. The "error" parameter in system procs specifies the level of the response if the error flag is set by the processing rule. The most common values for "error" are D, W, E and S, described below:

Other values may be specified as well: VD, VE, VW, VS, or X (which is equivalent to VD). These indicate variable error levels that depend on what the user's account number is. They are explained in the manual "SPIRES File Definition", section B.9.3.1.

Although "error" is the most common parameter in system procs, it is probably used less than many others. The default error levels for system procs, that is, the error level for the system proc when no "error" parameter is explicitly specified, is generally the most frequently chosen level. Thus, this parameter, which is usually near the end of the parameter list, is very often omitted.

Be sure to read the system proc descriptions carefully so that you know what effect an error will have if it occurs during element processing. The effect can change quite drastically depending on the value of the "error" parameter.

1.5.2  The MSG Parameter

This literal parameter can be coded if you want a special message to be displayed when the error flag for the proc is set and the error level is W, E or S. (No error messages will be displayed when a D-level error occurs.)

Each proc with a MSG parameter has its own message. Some, like $INT, have a very simple message, like "Invalid integer value". Others may use other parameters within the message; the $LENGTH proc, which checks that the element value is a given length, has the error message "Value must be &LEN characters", where &LEN is the value of the "length" parameter.

A separate proc, $MSG, can be used to create custom error messages for processing rule strings.

Note that a message, once in effect, will remain the error message for the remainder of the action rule string, unless overridden by another MSG parameter in another proc or by the $MSG proc or by the SET UCODE statement in a USERPROC. For example, in the following rule string:

which checks first to see that the value is at least 5 characters long and then to see that the value is no more than 10 characters long, the MSG from $MIN.LEN remains in effect for the $MAX.LEN proc. Thus, if the value is longer than 10 characters, the user might be startled to receive the error message "Value must be at least 5 characters". This problem would be easily remedied by adding the MSG parameter to $MAX.LEN or by inserting a $MSG proc before $MAX.LEN that contained a new message or no special message at all.

1.5.3  The ADD and UPD Symbols

File designers often include elements such as DATE.ADDED or TIME.UPDATED or ACCOUNT.ADDED to a goal record definition. Such elements can make it easier to keep track of data in the subfile -- you can subset the records based on what account added them or see which records have been updated recently, and so forth. To request such elements, the file designer generally codes an INCLOSE rule that will generate an element value based on the current time, date or logged-on account. (An INCLOSE rule is a special type of INPROC, explained in detail in the SPIRES manual "File Definition", section B.4.8.)

The system procs associated with the above-mentioned element types are $DATE, $TIME, $GEN.DATE, $GEN.TIME and $GEN.ACCT. The first two are normally INPROCs, but when the "how" parameter is either ADD or UPD, they become INPROCs with INCLOSEs that generate the current time or date. The second three are always INCLOSE rules. They also have "how" parameters that can be either ADD or UPD.

When the ADD symbol is used, SPIRES will generate the appropriate type of value (the current date, time, etc.) if no other value has been supplied. Thus, when no value has been supplied for the element, a value is "added". When the UPDATE symbol is used, SPIRES will generate the appropriate type of value whether or not another value has been supplied. So, if a value already exists, it is "updated" with the new value.

Consider a subfile whose goal records have a DATE.ADDED and a DATE.UPDATED element. The element definitions look like this:

The people who do the data entry never deal with these two elements; SPIRES takes care of them automatically. When a user is adding a record to the subfile, these elements are usually skipped. During record closeout, SPIRES generates the current date for the value of both elements. Later, when the record is updated, the elements are once again ignored by the user. Because the DATE.ADDED element, which has the value of ADD for "how" in the $DATE proc, already has a value (the date the record was added), no new value is generated by $DATE. On the other hand, the DATE.UPDATED element gets a new value, which is the current date, since the element value is replaced regardless. In this way, SPIRES handles ADD and UPDATE elements for you.

Note that if the user is adding a record and supplies a value for an "add" element, that value will not be replaced by a newly generated one. For example, if the user were to provide the value "July 1, 1901" for DATE.ADDED rather than skipping that element, that value is the value that would be stored. Because of this possible problem, many applications that store "add" and "update" elements use input formats that do not prompt for values for these elements, leaving SPIRES to take care of them.

1.5.4  The "element" Parameter

Some of the system procs that are INCLOSE or OUTPROC rules have a parameter called "element", which represents another element in the same structure as the current one. (Alternatively, both elements may be at the record level.) The $OCC proc, for example, has an "element" parameter that names the element whose occurrences are to be counted. That number is supplied as the value for the current element.

For such procs, the value of "element" can be either the element name, a valid alias, or the element number.

The element name may be given by itself if it is unique, i.e., if no other element in the record-type has the same name. If it is not unique, it may still be used if it is preceded by the subtree path, which describes where it is in the record: "structure@...element", where "element" is the name of the element and "structure@..." represents the names of the structures containing it.

For example, suppose the goal record has these elements:

In this record-type designed for a classical record album, there are three different elements named NUMBER. The easiest way to specify any given one of them would be to use its alias, since that uniquely identifies it. However, they may also be identified by specifying the subtree path:

Thus, if a proc names the element by the subtree path SELECTION@NUMBER, it is referring to the element whose alias is BAND.NUMBER. If only NUMBER is specified, it is referring to the element whose alias is RECORD.NUMBER. Again, note that using aliases is much simpler if possible.

If the name of an element begins with a digit (e.g., 5) you must use an alias that does not begin with a digit, or precede the element name by a subtree path name that does not begin with a digit; otherwise, the compile process will think it is an element number, described below. If it is a record-level element, you will have to refer to it either by an alias or by its element number, since it will have no subtree path.

An element number may be specified instead of an element name. The number is the element number within the structure. The first element in a record or in a structure is element 0. The second element is element 1, and so on. If the record has a slot key, the slot number is element 0.

For example, consider the goal record shown above. If a record-level element called OCC used $OCC to count the occurrences of another element, the elements it could count would be ALBUM (number 0), NUMBER (number 1 -- also could be called RECORD.NUMBER) and SELECTION (number 2). If OCC were in the SELECTION structure, it could count the occurrences of elements TITLE (element 0), COMPOSER (element 1) or SELECTION@NUMBER (element 2 -- or BAND.NUMBER). If OCC were in the TITLE structure, it could count the occurrences of elements FORM (element 0), SELECTION@TITLE@NUMBER (element 1 -- or FORM.NUMBER) and KEY (element 2). Any of those forms could be given for "element" in the proc.

2  System Proc Descriptions

This chapter contains the descriptions of the system procs, presented in alphabetical order. Each proc description begins with a standard set of information:

Following this listing is a general description of the proc. It describes what processing is done to the "input value" (the element value before the proc is executed), which will convert it to the "output value" (the element value after the proc is executed). The general description is followed by a formal description of the syntax and parameters of the proc.

The parameter descriptions begin by noting the default value of the parameter, that is, the value that will be assumed if no overriding value is supplied. Following this is an explanation of the meaning of the parameter, and a listing of its possible or suggested values. Each parameter is described as either a symbolic parameter, whose name is replaced by the value to be supplied, or a literal parameter, whose name is the value being supplied. [See 1.1.]

Following this section in most proc descriptions will be at least one example presenting a common specification of the proc and an explanation of its effect as it is coded. That is followed by the "System Proc Expansion", which shows how the system proc and its parameters are translated into actions during compilation. See chapter C.10 of "SPIRES File Definition" for an explanation of how to interpret this section, if you want. Remember that understanding actions is not necessary for using system procs.

2.0.1  ($ADJUST)

$ADJUST(length,error,how,what)

This proc adjusts the input value within a given field of characters, overlaying the value onto the field either from the left or right end, depending on the value of the "how" parameter. It can be considered a combination of the $INSETR and $INSETL procs, which are generally easier to use for string manipulations of that kind.

Usually the $ADJUST proc is used to adjust packed decimal values within a specified length to facilitate storage and sorting. It is often used with packed values being passed to an index or those being stored in a fixed-length field. When used, it should follow a proc that converts the input value to a packed decimal, such as $PACKED. Note that it is seldom used if the input value may be negative (see below).

This proc, when used, often follows the $DECIMAL proc; there is also a $DECIMAL.ADJ proc that combines the processing of the $DECIMAL and $ADJUST procs.

For more information about packed decimals in SPIRES, see section 18 of the SPIRES manual "Technical Notes" or EXPLAIN PACKED DECIMALS.

Syntax and Parameters

          length = (digits + 3) / 2

This proc is usually one of the last in a series of procs specified for a packed decimal-type element. After input values are converted to packed decimals ($PACK proc) and are adjusted to have a fixed number of decimal places ($DECIMAL proc), they are adjusted to have a fixed length by prefixing shorter values with zeroes, using the $ADJUST proc. This guarantees that values will be indexed properly, as long as all the values are positive. (The $PACK.TEST proc can be used to verify that.)

Example: $ADJUST(5,S)

This proc could be used to adjust a packed decimal value with seven places of precision (i.e., 5 = (7+3)/2) such that sorting and indexing of positive element values could be handled properly. The length of the element could be fixed at 5 bytes; if the input value would exceed that length, a serious error would occur.

System Proc Expansion

2.0.1a  ($ASCII)

$ASCII.IN or $ASCII.OUT

$ASCII.IN converts IBM's EBCDIC character set into the ASCII character set. $ASCII.OUT converts ASCII character set into IBM's EBCDIC character set. These rules are sometimes used as the INPROC and OUTPROC of keys of records obtained from ASCII sources where the ASCII sequence needs to be maintained.

In ASCII, the digit characters sort before the alphabetic characters. In EBCDIC, the digit characters sort after the alphabetic characters.

System Proc Expansion

2.0.2  ($AUGMENT)

$AUGMENT(character,how,error)

The $AUGMENT proc is used as an INPROC to guarantee that an input value will be unique. It may be coded only for the key element of a non-slot record type. It is usually the first proc coded in either an INPROC or an OUTPROC string.

Externally, the complete key value consists of three parts: a value, a separator character ("#" by default) and an integer number, e.g., "LC#23". The integer portion of the key is called the augmented portion, because normally it is a value supplied by SPIRES.

When a record is added, SPIRES examines the key value for the separator character. If it appears and is followed by an integer value within the appropriate range, as determined by the "how" parameter, then that value will be used as the key of the record. If the separator character does not appear, then SPIRES will augment the key with an integer value one greater than the highest augmented portion currently existing for that key. For example, if the record being added has a key of LC and SPIRES determines that 23 on "LC#23" is the highest augmented portion for an existing record whose key begins with LC, then it will append the integer 24 to the new record's key. If no record already existed with an LC key, then SPIRES would assign "LC#0" as the key of this first one.

If the separator character appears at the end of the input value, it is discarded. If it appears within the value, SPIRES assumes that whatever follows is an integer; if what follows is not an integer, the result is unpredictable and an error occurs. Note that the last occurrence of the character is used as the separator if the character appears within the value more than once.

Although $AUGMENT appears at the beginning of the INPROC string, the actual augmentation does not occur till the end. When the input value already has the augmented portion of the key, it is stripped from the value and saved when rule processing begins and then restored and converted to binary at the end of the rule string. Thus, any other processing rules will not affect the augmented portion. (Note that the separator character is not stored; it is only used in the external form of the augmented key. Because SPIRES knows the length of the augmented portion in bytes, it knows automatically where the augmented portion of the stored value begins.)

On output, the augmented portion is again stripped from the key value before any other rule processing occurs. When the OUTPROC processing for the key is complete, the separator character and the augmented portion are appended to the key again. As in INPROC processing, other processing rules do not affect the augmented portion.

To access a specific record, the entire key, including the augmented portion, must be specified: DISPLAY LC#24.

$AUGMENT may be used as a SEARCHPROC, often coded as the SEARCHPROC for a "goal-index" record-type (the goal record-type serves as its own index) that has augmented keys. If you want to allow truncated searching, you should precede $AUGMENT with the $SEARCH.TRUNC proc.

Syntax and Parameters

$AUGMENT can be used to conserve slot record-types in a file by allowing a record-type that would be slot to be non-slot. A file may have only eight slot record-types, none of which may be COMBINEd with other record-types.

$AUGMENT is often used to create record keys in order to avoid the need for the SEQUENCE command when producing reports. If reports are frequently produced using one element as the sort-key, then it may be advantageous to make that element the record key; SPIRES will process records in key sequence automatically under most Global FOR classes, such as FOR SUBFILE, FOR TREE, etc.

Example: $AUGMENT(':',BYTE)

If this example is an INPROC, the input value (assuming it does not have a colon, the separator character, in it) will be augmented with a one-byte integer from 0 to 254, depending on whether another record with that stem is already in the record-type and, if so, depending on the highest augmented value already stored for that stem. If the input value already contains a colon followed by an integer less than 255, it will be used as the key; were the integer 255 or greater, a serious error would occur. If the input value contains a colon followed by non-numeric characters, a serious error would occur.

System Proc Expansion

2.0.3  ($BG)

$BG

This proc, generally used in output formats or on redefined virtual elements, converts all alphanumeric characters to the hex characters that will, on output, print in a banner type font on the 3800 laser printer when a banner character set is used. At this writing, those sets available at Stanford are BG10 and BG12.

Note that values processed by this proc may not be readable at a terminal. Only elements with values that will be printed on the 3800 laser printer using one of those character sets should use this proc. Values processed on output through this proc should probably not be re-input into the subfile in this form.

All alphanumeric characters and many punctuation characters in the input value are in effect doubled in size, meaning that a character string that was 15 characters long will become about 30 characters long after processing by $BG. The punctuation characters whose size is doubled are listed in the last four lines of the System Proc Expansion below; some of those characters whose size does not double are the period, comma, colon (:) and semicolon (;).

There are no parameters, and no errors can occur.

System Proc Expansion

2.0.4  ($BITS)

$BITS(length,PAD,error,MSG)

On input (when $BITS is an INPROC or SEARCHPROC) a value consisting of a set of numbers separated by commas and/or blanks is transformed into a bit mask, where each number in the original value represents a bit position to be set in the final mask. For output, the mask is converted back into a set of numbers separated by commas and blanks, e.g., "1, 2, 4".

The numbers allowed in the input value are determined by the length of the bit mask in bytes; since there are eight bits to a byte, a one-byte bit mask may represent the numbers 1-8, a two-byte one may represent the numbers 1-16, etc. By default, the length of the bit mask is one byte.

The length of the stored value may vary, depending on whether the higher numbers allowed appear in the input value. For example, if the value may contain the numbers 1-32, but an actual value is only "1,3,7" which would need only the first byte (representing the numbers 1-8), the stored value would be one byte long. However, if the value is "1,32", then on conversion by $BITS, the value would be four-bytes long, since the fourth byte is needed for the number 32.

The bits are numbered from left to right within each byte; thus, a byte whose bit pattern is 10100010, represents "1,3,7".

Syntax and Parameters

Example: $BITS(2,PAD,,MSG)

The input value, a set of numbers from 1-16 separated by commas, is transformed into a two-byte bit mask. The converted value will always be two bytes long, even if the input value contains only numbers under 9. (If PAD were not coded, an input value containing only numbers under 9 would be converted into a one-byte bit mask.) If a number greater than 16 appears in the input value, a serious error will occur, and the message 'Invalid characters or value too large' will be displayed.

System Proc Expansion

2.0.5  ($BOLD)

$BOLD

This proc, generally used in output formats or on virtual redefined elements, converts all alphanumeric characters to the hex representation that will, on output, print as boldface type on the 3800 laser printer when a multiple-font character set is used. At this writing, those sets available at Stanford are MT10, MT12, MT15, MH12, ML10 and MC10.

Note that values processed by this proc are not readable at a terminal. Only elements with values that will be printed on the 3800 laser printer using one of those character sets should use this proc. Values processed on output through this proc should probably not be re-input into the subfile in this form.

There are no parameters, and no errors can occur.

System Proc Expansion

2.0.6  ($BREAK and $BREAK.HEX)

$BREAK(character,error)

$BREAK.HEX(character,error)

The value is treated as a string of values, each separated by a delimiter character. The delimiter may be a space (the default) or some other character. Each of these procs breaks the value into its separate parts, discarding the delimiter and surrounding blanks; the rest of the rule string handles each part as an occurrence of the element, with all rules following the $BREAK or $BREAK.HEX repeated for each occurrence of the element generated by $BREAK or $BREAK.HEX. All rules preceding and including $BREAK or $BREAK.HEX are executed only once, operating on the entire original value. Any element having one of these procs as an INPROC should thus be multiply occurring.

Commonly these rules are used to allow data entry of several occurrences of an element as a single occurrence. Usually occurrences are separated by blanks or commas, and whichever condition is desired may be specified easily with this proc (see "character" below).

These procs are often used in PASSPROCs for word indexes, in order to break up a textual value into individual words for indexing. The proc $WORD provides this same function and also eliminates punctuation. Only a single one of these rules ($BREAK, $BREAK.HEX, $WORD) should appear in any rule string.

Syntax and Parameters

Neither $BREAK nor $BREAK.HEX may be placed between a pair of $STORE/$RESTORE (A61) procs in a rule string. Also, neither proc should appear in the SEARCHPROC string for a sub-index. Either may appear in the SEARCHPROC for a simple index that contains a sub-index, but search commands should not try to use both the sub-index and the value breakup. For instance, if a blank is used for the breakup character for the STATE simple index, the following command would fail:

If the delimiter in the incoming value is several characters long, or if several different characters may be used as a delimiter, use the procs $CHANGE (A44) or $TRANS (A43) respectively to change the delimiters to a single character that would not appear in the value before you apply the $BREAK or $BREAK.HEX proc.

If the value consists of nothing but blank and delimiter characters, then the value will become a null one for Inprocs, an exclusion term for Searchprocs and a null value discarded by Passprocs.

Examples: $BREAK(.) or $BREAK.HEX(#4B#)

The value will be broken into separate occurrences of the element at each period (hex 4B) character within the value.

System Proc Expansion

2.0.7  ($BUILD)

$BUILD(character)

All occurrences of the element are combined into one value with each occurrence separated by a blank (by default). When this proc appears in a string of OUTPROC rules, it should be the first proc.

Syntax and Parameters

Note that the $BUILD proc has no effect under partial processing.

The formats Entry-Uproc SET BUILDSEP overrides the $BUILD proc.

Example: $BUILD(COMMA)

All occurrences of the element will be put together and treated as a single value, with each occurrence separated from the other by the string ", ", as in "apples, oranges, grapes". This form of $BUILD is perhaps the most commonly used.

System Proc Expansion

2.0.8  ($CALL)

$CALL(name,type,p1,error)

This proc calls a user-defined processing rule (Userproc). See the manual "SPIRES File Definition" for information on Userprocs or EXPLAIN USERPROCS.

Syntax and Parameters

Example: $CALL(FIXIT,,,S)

This proc calls a Userproc named FIXIT. If the Userproc sets the error flag, a serious error is produced. No P1 parameter is being passed. This proc may be any type of rule other than an Inclose since the INCLOSE type is not specified.

System Proc Expansion

2.0.9  ($CAP)

$CAP(cap)

This proc by default converts all lowercase characters in the value to uppercase. It is often used as an INPROC to guarantee that all values are in uppercase so that value testing is simpler. (Some procs, such as $INCLUDE and $ENCODE, are sensitive to the case of a value.)

By specifying a value for the "cap" parameter, you can limit which characters are capitalized in the value, based on their positions within the value.

Syntax and Parameters

For a complete list of possible number-options for 'cap', [EXPLAIN $CASE FUNCTION.]

Note that if either symbol for the "cap" parameter is specified, only those characters are affected by the proc. If a value contains uppercase characters within it, those characters will not be affected (see example). The $LOWER proc can be used to ensure that all characters other than the first in the first word or the first in each word are in lowercase.

Example: $CAP(EACH.WORD)

Here are some sample values as they would be processed by this proc:

System Proc Definition

2.1.0  ($CHANGE and $CHANGE.HEX)

$CHANGE(input,output,EXACT,error)

$CHANGE.HEX(input,output,EXACT,error)

These two procs are used to change occurrences of one character string in the incoming value to another. For example, if the incoming element value might be FEMALE, the $CHANGE proc could be used to change FEMALE to F for storage and then from F to "Female" on output. By default, the proc changes any and all occurrences of the "input" string that appear in the input value to the "output" string. However, you can require that a change be made only if the entire element value matches the "input" string, using the EXACT parameter.

For example, suppose you wanted to change MALE to M. By default, the value FEMALE would be changed to FEM, since MALE is a string in FEMALE. If the EXACT parameter is used to require that the change should be made only when the entire element value matches the "input" one, that change would not occur.

These two procs are basically the same, except that $CHANGE.HEX must be used when you want to change hex characters. Also $CHANGE is somewhat easier to use when the "input" or "output" value contains special characters.

Syntax and Parameters

$CHANGE and $CHANGE.HEX, along with $CHANGE.LIST, are often used before $ENCODE or $INCLUDE, two procs that determine whether the input element value is among those values listed. In such cases, you may allow the person adding records to input several different values that mean the same thing, such as F or FEM or FEMALE. You might code the two rules $CHANGE(FEMALE,F) and $CHANGE(FEM,F) to change all such values all to F before checking for F with $INCLUDE or $ENCODE.

Case is relevant to the $CHANGE and $CHANGE.HEX procs. The above example, $CHANGE(FEMALE,F) will not change the value "Female" to F because "Female" is not entirely in uppercase.

Example: $CHANGE(AUTUMN,FALL) or $CHANGE.HEX(AUTUMN,FALL)

If the input value contains the string AUTUMN (all in uppercase), that string will be changed to FALL. If the input value does not contain the string AUTUMN, the error flag will be set, but with no effect.

Example: $CHANGE.HEX(#FF#,BLANK)

If the input value contains the hex character FF, it will be changed to a blank.

Example: $CHANGE(MPH,NULL) or $CHANGE.HEX(MPH,NULL)

These procs change the string MPH to a null string, in effect deleting the string from the value if it occurs. Often an OUTPROC for an element will contain the $INSERT proc in order to append a string to the value for display, such as " MPH" added to a MAX.SPEED element for a vehicles data base: "12 MPH". In such cases, the INPROC for that element usually has a $CHANGE proc like that shown above to delete the extra MPH when the record is updated. Otherwise, when the record was displayed again, it would appear as "12 MPH MPH" as another MPH gets tacked on.

System Proc Expansion

2.1.1  ($CHANGE.LIST)

$CHANGE.LIST(values,EXACT,error)

This proc is similar to $CHANGE and $CHANGE.HEX in that it is used to examine the element value and change occurrences of the "input" string to the "output" string. $CHANGE.LIST can be used to provide a list of values to be searched for, each value followed by the value to which it should be changed; thus, the input and output values are specified in pairs. For example, $CHANGE.LIST('LIKE,DISLIKE,COFFEE,TEA') would change the value "TILLIE WILLIAMS LIKES COFFEE" to "TILLIE WILLIAMS DISLIKES TEA".

Like $CHANGE and $CHANGE.HEX, you can use the EXACT parameter to state that the element value is only to be changed if the entire value matches the "input" string. Thus, $CHANGE.LIST('LIKE, DISLIKE, COFFEE, TEA', EXACT) would not change TILLIE LIKES COFFEE to TILLIE DISLIKES TEA, but would change the element value COFFEE to TEA.

Syntax and Parameters

Because the element value is repeatedly examined and possibly changed several times, one change may affect another. For example, $CHANGE.LIST('MALE,M,FEMALE,F') will never process a value of FEMALE the way it was apparently meant to. Because the value FEMALE has MALE in it, when the value is scanned for MALE, it will be changed to FEM. FEM does not match FEMALE, so the value will remain as FEM.

Alternatively, you could code either $CHANGE.LIST('FEMALE,F,MALE,M') or $CHANGE.LIST('MALE,M,FEM,F'). Either solution would provide the desired result.

Case is significant for the values being compared by $CHANGE.LIST. For instance, in the example above, the value "female" would not be changed at all, since the values do not match because of case. Often the $CAP proc proceeds the $CHANGE.LIST proc to insure that the incoming value is in uppercase.

Example: $CHANGE.LIST('NORTH,N, SOUTH,S, EAST,E, WEST,W',,W)

If the element value contained any of the strings NORTH, SOUTH, EAST or WEST, they would be changed to N, S, E or W respectively. The value NORTHWEST would be changed to NW, for instance. (If the EXACT parameter had been specified, such a value would not have been changed.) If no value is found to be changed, the error flag is set, causing a warning error.

Example: $CHANGE.LIST('RECORDS,,TAPES,')

This proc causes the character strings RECORDS and TAPES in the element value to be converted to null strings. The values parameter contains four values: RECORDS, a null string, TAPES and another null string. The null strings are here indicated as strings of no length -- that is, a string of no length is between the pair of commas separating RECORDS and TAPES as well as between the last comma and the apostrophe that ends the proc parameter value.

System Proc Expansion

2.1.2  ($CHECK)

$CHECK(length,error,MSG,other)

A check digit may be added to the end of an integer to help verify that the integer has been input correctly. When the integer is input, the check digit (the last digit in the number) is stripped off. The number remaining is processed through a mathematical formula that generates the check digit. If the generated check digit matches the input check digit, then the input value is accepted as a valid one.

The $CHECK proc provides check-digit processing for elements. The last digit of the value is stripped from the value. Then, using either a MOD-11 rule (the default), the "student services rule", the "extended student services rule", the "Luhn rule", or the "ABA rule", SPIRES generates a check digit from the remaining part of the value. (Those rules are described in detail in the description of action A27.) If the check digit generated matches the input check digit, then the action continues in the manner of the $INT proc. Otherwise the error flag is set. The remaining part of the value is converted to a binary value for storage.

Note that the check digit is not considered part of the value. For example, if the input value is "19", the digit "1" is the element value and the digit "9" is the check digit. Only the "1" is stored. (If "9" were not the correct check digit for the number 1, the error flag would be set.)

Syntax and Parameters

An element processed by $CHECK as an INPROC is usually processed by $CHECK.OUT on output, which appends the check digit to the value. You can learn the correct "mod-11 rule" check digit for a given number by executing the public protocol CHECK.DIGIT, e.g.,

Because integers outside the storage range may be converted without warning to numbers inside the range when one- or two-byte values are being stored (BYTE or HALF for the "length" parameter), it is generally recommended that integer elements be stored as four-byte values (FULL or INT). The input value can easily be verified to be within an acceptable range by following $CHECK with $RANGE.

When LEN is coded for the "other" parameter, SPIRES uses the same check digit formula that it uses for SS, except that any leading zeroes, which would be discarded by the SS rule before computation of the check digit, are retained by LEN, which affects the value of the check digit. In other words, given the value "000000019", the SS rule would discard the leading zeroes and find that 9 was not the proper check digit for the value "1", setting the error flag. The LEN rule would not discard the leading zeroes, and would compute the check digit using them -- the result being that 9 is the proper check digit for the value "00000001".

Generally speaking, the LEN symbol is used when the input value represents a code rather than a number, i.e., a code where leading zeroes are significant. The symbol is called LEN (for "length") because the input value's length is generally fixed, so that all values going in and out for that element have the same length and are thus processed by the identical pattern of the formula. You may want to insure that input values all have the same length prior to LEN processing either by testing the length with the $MIN.LEN proc or by padding the value on the left with zeroes, using the $INSETR proc.

Example: $CHECK(BYTE,S,MSG)

The input value should be an integer from 0 to 255 with the proper check digit appended to it. If the check digit is not correct, or if the value is not an integer or is outside the proper range, a serious error will occur and the error message "Invalid integer or check digit value" will be displayed.

System Proc Expansion

2.1.3  ($CHECK.OUT)

$CHECK.OUT(length,PAD,error,MSG,other)

This proc converts the binary value to a character string, like $INT.OUT. It also appends the check digit for the value, as described for $CHECK. The converted value contains digits or a minus sign followed by digits.

Syntax and Parameters

The discussion of the $CHECK proc noted that LEN is specified there for the "other" parameter when the input value represents a code rather than a number. In those circumstances, leading zeroes become significant, so they are used in determining the check digit, rather than discarded before the check digit is determined. For output, the leading zeroes must be replaced, so the PAD parameter is usually specified, to pad the value with zeroes on the front to the desired length for the code. The check digit is then generated for the output value.

Example: $CHECK.OUT(9,PAD)

This proc will convert the stored binary value into a string, adding the proper check digit at the end, using the "MOD-11" rule. The output value will normally be nine characters long, including leading zeroes and possibly a minus sign. If the value would require more than nine places, it would still be displayed, but a warning error would occur.

System Proc Expansion

2.1.4  ($COMPRESS)

$COMPRESS(how,error)

This proc first squeezes out all extra blanks and deletes leading and trailing blanks, like $SQU. Any character, punctuation or number is then converted into a more compact form for storage. Lowercase letters are always translated to uppercase before conversion. The final result is reduced in size by a ratio of 8 to 6; that is, 8 characters can be stored in the amount of space normally required for six. If only alphabetic characters, blanks, hyphens, commas or apostrophes need to be retained, a greater reduction can be achieved by specifying ALPHA for the "how" parameter (see below).

Syntax and Parameters

The following chart compares the reduction of ALPHA and NUMERIC. The "Input Size" represents the length of the string entered; the "Result Size" represents the number of bytes needed to store it.

           ALPHA                           NUMERIC
     Input Size   Result Size        Input Size   Result Size
          1            1                  1           1
          2            2                  2           2
          3            2                  3           3
          4            3                  4           3
          5            4                  5           4
          6            4                  6           5
          7            5                  7           6
          8            5                  8           6
          9            6                  9           7

Indexing the converted values is not generally recommended, unless only the equality operator will be used in search requests. Normally it is best to reconvert the value before it is stored in an index (see the OUT parameter on the $PASS and $PASS.ELEM procs).

Example: $COMPRESS(ALPHA)

The input value would have leading and trailing blanks stripped, and any multiple blanks within the value would be squeezed down to single ones. All alphabetic characters would be converted to uppercase. All non-alphabetic characters other than blanks, hyphens, commas or apostrophes would be translated to asterisks. An input value such as "James Bond-007" would be converted to "JAMES BOND-***". That value would be stored in 9 bytes, rather than the normal fifteen.

System Proc Expansion

2.1.5  ($DATE)

$DATE(how,NA,error,MSG)

$DATE by default verifies that the value supplied is in a standard form for a date (see below) and converts the value to a four-byte hexadecimal string for storage. A serious error is caused if the value is not in one of the standard date formats shown below, or if the value is not a valid date (e.g., "Feb. 29, 1979" would cause an error; "Feb. 29, 1980" would not). The action $DATE.OUT can be used to reconvert the value for output.

Syntax and Parameters

Example: $DATE(ADD)

This INCLOSE rule would supply the current date as a value for the element (assuming no other value were supplied by the user) and then convert it for storage. A serious error would be caused if the user supplied an invalid date.

Example: $DATE(TRUNC,,,MSG)

This rule is a SEARCHPROC that would allow the searcher to truncate date values and that would return the error message if the user typed an invalid date.

The four-byte hexadecimal string into which the date is converted is in the form #CCYYMMDD# where the first byte, CC is the century, the second, YY, is the year, MM the month, and DD the date. For example, "July 1, 1954" would be translated into the hex string #19540701#, each pair of numbers being the representation of a single hexadecimal character. Note that if the century is not supplied by the user, "19" (or whatever the current century is at the time of input) is assumed, except for metric dates (see example below). Over the next few years, as confusion over the meaning of 2-digit years grows, we recommend you use 4-digit years on input for clarity.

Specific date formats allowed include:

Most combinations of these work as well.

Many relative date forms are also allowed, which express dates in terms of their relation to the current date. Here are some of the forms allowed:

Notice that the value always converts to a specific date, or a specific month and year, or a specific year. A value that would convert to a range of days within a month (such as "last week") will not be recognized, and will set the error flag.

A full description of allowed forms appears in the manual "SPIRES Searching and Updating" -- online, EXPLAIN DATES, FOR INPUT.

System Proc Expansion

2.1.5a  ($DATE.IN)

$DATE.IN(how,NA,error,MSG,century)

$DATE.IN by default verifies that the value supplied is in a standard form for a date (see below) and converts the value to a four-byte hexadecimal string for storage. A serious error is caused if the value is not in one of the standard date formats shown below, or if the value is not a valid date (e.g., "Feb. 29, 1995" would cause an error; "Feb. 29, 1996" would not). The action $DATE.OUT or $DATE.OUT.CC can be used to reconvert the value for output.

The $DATE.IN proc (like $DATE.IN.CC) is very similar to $DATE; the main differences are:

If you have turn-of-the-century concerns but need the facilities mentioned in the first two points above, you can use $DATE with the $GEN.DATE proc in the first case, or use $SEARCH.DATE in the second.

The $DATE.IN and $DATE.IN.CC procs differ in these ways:

Syntax and Parameters

Example: $DATE.IN(,NA,,MSG,75)

This rule would verify that the input value is a valid date, and if it is not, set a Serious error and display the error message "Invalid date". If the input value is "None" or "N/A", SPIRES will convert it to an internal form that represents "Not Applicable". If the input value has only a two-digit year, if the two digits are 75 or higher, SPIRES will put "19" in front of them; if they are less than 75, SPIRES will put "20" in front of them.

The four-byte hexadecimal string into which the date is converted is in the form #CCYYMMDD# where the first byte, CC is the century, the second, YY, is the year, MM the month, and DD the date. For example, "July 1, 1954" would be translated into the hex string #19540701#, each pair of numbers being the representation of a single hexadecimal character. Note that if the century is not supplied by the user, "19" (or whatever the current century is at the time of input) is assumed, except for metric dates (see example below). Over the next few years, as confusion over the meaning of 2-digit years grows, we recommend you use 4-digit years on input for clarity.

Specific date formats allowed include:

Most combinations of these work as well.

Many relative date forms are also allowed, which express dates in terms of their relation to the current date. Here are some of the forms allowed:

Notice that the value always converts to a specific date, or a specific month and year, or a specific year. A value that would convert to a range of days within a month (such as "last week") will not be recognized, and will set the error flag.

A full description of allowed forms appears in the manual "SPIRES Searching and Updating" -- online, EXPLAIN DATES, FOR INPUT.

System Proc Expansion

2.1.5b  ($DATE.IN.CC)

$DATE.IN.CC(century,how,error,MSG)

$DATE.IN.CC by default verifies that the value supplied is in a standard form for a date (see below) and converts the value to a four-byte hexadecimal string for storage. A serious error is caused if the value is not in one of the standard date formats shown below, or if the value is not a valid date (e.g., "Feb. 29, 1995" would cause an error; "Feb. 29, 1996" would not). The action $DATE.OUT or $DATE.OUT.CC can be used to reconvert the value for output.

The $DATE.IN.CC proc (like $DATE.IN) is very similar to $DATE; the main differences are:

If you have turn-of-the-century concerns but need the facilities mentioned in the first two points above, you can use $DATE.IN.CC with the $GEN.DATE proc in the first case, or use $SEARCH.DATE in the second.

The $DATE.IN and $DATE.IN.CC procs differ in these ways:

The NA handling built into $DATE.IN.CC means that the user updating records can supply any of the following values instead of a date: N/A, NA or NONE (case is not significant). By default, $DATE.IN or $DATE would reject such a value. This is useful when some value must be input because of the occurrence of a $MIN.OCC rule (minimum occurrences) following the $DATE.IN.CC proc. The NA parameter should be coded on the $DATE.OUT proc used to process the element on output; however, if you use $DATE.OUT.CC as the Outproc, NA values are it is handled automatically by the $DATE.OUT.CC proc. (Note that an NA value is translated internally into the date 9/9/9999, meaning that if the date element is indexed, a search such as FIND DATE > 1979 would retrieve the NA records, unless that value were excluded from passing.)

Syntax and Parameters

Example: $DATE.IN.CC(75)

This rule would verify that the input value is a valid date, and if it is not, set a Serious error. If the input value is "None" or "N/A", SPIRES will convert it to an internal form that represents "Not Applicable". If the input value has only a two-digit year, if the two digits are 75 or higher, SPIRES will put "19" in front of them; if they are less than 75, SPIRES will put "20" in front of them.

The four-byte hexadecimal string into which the date is converted is in the form #CCYYMMDD# where the first byte, CC is the century, the second, YY, is the year, MM the month, and DD the date. For example, "July 1, 1954" would be translated into the hex string #19540701#, each pair of numbers being the representation of a single hexadecimal character.

All date formats allowed as input to $DATE and $DATE.IN are allowed for $DATE.IN.CC as well. For specific date formats allowed, see the description of $DATE.IN. [See 2.1.5a.] A full description of allowed forms appears in the manual "SPIRES Searching and Updating" -- online, EXPLAIN DATES, FOR INPUT.

System Proc Expansion

2.1.6  ($DATE.OUT)

$DATE.OUT(form,NA,case,size,style,century)

This proc converts the value stored using $DATE to a specified date format on output. The particular format is determined by the "form", "size" and "style" parameters. No errors can occur.

The sixth parameter, "century" controls how SPIRES handles the two century digits of a year in the default and the DAY forms; other forms are not affected. The default and DAY forms suppress the two century digits (e.g., display the year as "95" instead of "1995") when they match the century digits of the current year. This can be confusing or cause problems for users or other programs handling the SPIRES output as input. In many cases, it is advisable, where possible, to force the year to be displayed as a four-digit value.

The $DATE.OUT.CC proc may be useful to you if you are converting a simple $DATE.OUT or $DATE.OUT(DAY) proc to handle century issues; the "century" parameter comes first and is thus easier to code than in $DATE.OUT, where it is the sixth.

Syntax and Parameters

Examples

If the date January 5, 1981 were stored with the $DATE proc, the $DATE.OUT proc would produce the following results in 1995:

As you can see, many different formats for date output are available.

If you used the ACCOUNTING symbol on the $DATE proc so that the dates "August 32", "August 33" and "August 34" are allowed for input, then any output form you choose for "$DATE.OUT that displays the weekday will be output with the string "+----" for the weekday. For example, $DATE.OUT(DAY) would return "+---- 08/32/87" for "August 32, 1987".

System Proc Expansion

2.1.6a  ($DATE.OUT.CC)

$DATE.OUT.CC(century,form,case,size)

This proc converts the value stored using $DATE to a specified date format on output, which is basically "MM/DD/CCYY" (for instance, 07/01/1954) with some variations. If DD or MM is unknown, its field is set to "--".

The first parameter, "century" controls how SPIRES handles the two century digits of a year. You can choose to suppress the two century digits (e.g., display the year as "54" instead of "1954") when they match the century digits of the current year. (The default form for $DATE.OUT does this.) However, this can be confusing or cause problems for users or other programs handling the SPIRES output as input. In many cases, it is advisable, where possible, to force the year to be displayed as a four-digit value, which is the default for $DATE.OUT.CC.

The $DATE.OUT.CC proc may be useful to you if you are converting a simple $DATE.OUT or $DATE.OUT(DAY) proc to handle century issues; the "century" parameter comes first and is thus easier to code than in $DATE.OUT, where it is the sixth. Additionally, the NA ("Not Applicable") handling that must be explicitly requested in $DATE.OUT is built in to $DATE.OUT.CC. So if the stored value is #99990909#, it will automatically be converted to "N/A" by $DATE.OUT.CC.

The $DATE.OUT proc supports many more forms of date output than $DATE.OUT.CC, which is designed specifically to handle problems with the basic date output form where the two century digits may be suppressed. Many forms where the century digits are never suppressed (as well as another one where they are, the basic CANADIAN form) are available on that proc.

Syntax and Parameters

Examples

If the dates January 5, 1981 and July 1, 2004 were stored with the $DATE proc, the $DATE.OUT.CC proc would produce the following results in 1995 (or any future year before 2090):

$DATE.OUT.CC                 =  01/05/1981         07/01/2004
$DATE.OUT.CC(YY)             =  01/05/81           07/01/04
$DATE.OUT.CC(90)             =  01/05/1981         01/05/04
$DATE.OUT.CC(,DAY)           =  MON.  01/05/1981   THUR. 07/01/2004
$DATE.OUT.CC(YY,DAY,,FIXED)  =  MON 01/05/81       THU 07/01/04

If you used the ACCOUNTING symbol on the $DATE proc so that the dates "August 32", "August 33" and "August 34" are allowed for input, then any output form you choose for $DATE.OUT.CC that displays the weekday will be output with the string "+----" for the weekday. For example, $DATE.OUT.CC(,DAY) would return "+---- 08/32/1987" for "August 32, 1987".

System Proc Expansion

2.1.6b  ($DATEYY)

$DATEYY(how,century,method,error,msgna)

[Note: This is preliminary documentation. This proc combines features of $DATE and $DATE.IN.CC; for details about how this system proc works in handling dates in general, please see the descriptions of those procs.]

Syntax and Parameters

System Proc Expansion

2.1.6c  ($DATEYY.OUT)

$DATEYY.OUT(form,century,case,size,style,NA)

[Note: This is preliminary documentation. This proc combines features of $DATE and $DATE.OUT.CC; for details about how this system proc works in handling dates in general, please see the descriptions of those procs.]

Syntax and Parameters

The parameter allows the user to enter a value of N/A (for "Not Applicable"). This value will be reconverted to N/A on output by this proc if the NA parameter is specified.

If you used the ACCOUNTING symbol on the $DATE proc so that the dates "August 32", "August 33" and "August 34" are allowed for input, then any output form you choose for $DATEYY.OUT that displays the weekday will be output with the string "+----" for the weekday.

System Proc Expansion

2.1.7a  ($DATETIME.IN)

$DATETIME.IN(how,err,MSG)

$DATETIME.IN by default takes the value supplied in a standard form for a datetime (see below) and converts the value to an eight-byte hexadecimal string for storage. A serious error is caused if the value is not in one of the standard datetime formats shown below, or if the value is not a valid datetime (e.g., "Feb 29, 1979" would cause an error; "Feb 29, 1980" would not). The action $DATETIME.OUT can be used to reconvert the value for output.

Syntax and Parameters

Example: $DATETIME.IN(ADD)

This rule would supply the current datetime as a value for the element (assuming no other value were supplied by the user) and then convert it for storage. A serious error would be caused if the user supplied an invalid date.

The eight-byte hexadecimal string into which the datetime value is converted is in the form #CCYYMMDDTTTTTTTT# where CC is the century, YY is the year, MM the month, DD the day, and TTTTTTTT is the time as an integer. For example, "July 1, 1954 12:15:58" would be translated into the hex string #1954070102A1CC30#. Note that if the century is not supplied by the user, "20" (the current century) is assumed. The only exception is for metric dates such as "33.03.05 12:30". Over the next few years, as confusion over the meaning of 2-digit years grows, we recommend you use 4-digit years on input for clarity.

The input form of a datetime value is a DATE followed by a separator followed by a TIME which must include a colon (:) character, or just a "date", NA, N/A, or NONE.

The "time" portion must be a "hh:mm:ss.fff" form, with "h:" as a minimum. Time consists of decimal digits, colon characters, and possible period character between seconds and fractions of seconds. Time range: "0:" through "23:59:59.999" which become 00000000 through 05265BFF as the time portion of the stored form (tttttttt). Values that exceed this amount cause the error flag to be set, and the value is replaced with the integer -1.

The input is scanned from right to left looking for the digits, colons, and periods. If colon is not found, the input form is assumed to consist of only a date. If a time is supplied, the separator between date and time may be any character other than digits, colons or periods. Blank is the preferred character, which is what will be output when the time portion of the stored form is not the integer -1 (indicating an unknown time). [EXPLAIN A28 RULE FOR TIME.]

The "date" portion may be any form of date allowed by $DATEIN with the NA option. That means dates without the century will default to the current century. You may also use "relative" dates, such as today, yesterday, tomorrow. N/A and NA and NONE are also accepted by this input process creating #99990909FFFFFFFF# as the 8-byte HEX form. If the "date" portion fails to convert properly, the resultant 8-byte datetime value will be: #00000000FFFFFFFF#.

Data elements which hold DATETIME values probably should be defined with LENGTH = 8; The TYPE defaults to HEX if you use the inproc rule described below.

The default input form is: "mm/dd/ccyy hh:mm:ss", which is output by the $DATEOUT function or A76. [EXPLAIN A76 RULE FOR DATETIME.]

Specific date formats allowed include:

Most combinations of these work as well.

Relative date forms are also allowed, which express dates in terms of their relation to the current date. Here are some of the forms allowed:

Notice that the value always converts to a specific date, or a specific month and year, or a specific year. A value that would convert to a range of days within a month (such as "last week") will not be recognized, and will set the error flag.

A full description of allowed forms appears in the manual "SPIRES Searching and Updating" -- online, EXPLAIN DATES, FOR INPUT.

System Proc Expansion

2.1.7b  ($DATETIME.OUT)

$DATETIME.OUT(form,NA,case,size,style,century)

This proc converts the datetime value stored using $DATETIME.IN to a specified date and time format on output. The particular format is determined by the "form", "size" and "style" parameters. No errors can occur.

Syntax and Parameters

Datetime values are output either as date alone, because the time-portion is the integer -1, or as a date-portion followed by a blank followed by a time-portion. The time-portion, when output, has the form: HH:MM:SS[.fff] where the [.fff] portion only occurs if there are fractional seconds. The parameters of $DATETIME.OUT control the format of the date-portion. [EXPLAIN A76 RULE FOR DATETIME.]

System Proc Expansion

2.1.8  ($DECIMAL)

$DECIMAL(places,error,MSG,PACK)

This proc manipulates a packed value to have a specified number of decimal places. The input value should be a packed decimal value (see the PACK parameter below). If necessary, zeroes are appended to the value to produce the appropriate number of places; or if there are too many places, the right-most digits are discarded (with appropriate rounding).

For example, if the value of the "places" parameter is 3 and the input value is 1.5, the result from $DECIMAL would be 1.500, a value having three decimal places; but if the input value were 1.50096, the result would be 1.501.

You can also use $DECIMAL to round to the nearest "one" or the nearest hundred or thousand or other positive power of ten, as shown in the examples below. For more information about packed decimals in SPIRES, see section 18 of the SPIRES manual "Technical Notes" or EXPLAIN PACKED DECIMALS.

Syntax and Parameters

Because zeroes may be added to the end of the value or digits may be dropped from the end of the value, this proc may change the precision of the value. (Precision is defined as the number of digits in the value counting from the left-most non-zero digit to the right-most digit, whether it is zero or not.) If the precision of the result is greater than 30, the result will be "-@@" or "@@" (positive or negative infinity); if the precision is 0, the result is 0.

Technical note: This proc does not guarantee that a value processed by $DECIMAL on input will be output with the specified number of decimal places. The output form depends on how the value is processed by $EDIT, $DECIMAL, $PACK.OUT or $DECIMAL.OUT. Specifically, this proc guarantees that the processed value will have the negated value of "places" as its exponent. The input value is adjusted so that it will have, for example, an exponent of -2 if the value of "places" is 2.

Example: $DECIMAL(2)

The input value, if it is a packed decimal value, is adjusted so that it has two decimal places. If the input value is not a packed decimal, the error flag is set and a serious error occurs.

Example: $DECIMAL(-3)

The input value, if it is a packed decimal value, is rounded to the nearest thousand. (This is because the "places" value represents the negated value of the packed decimal's exponent, meaning that the output value from this proc will have an exponent of 3.) If the input value is not a packed decimal, the error flag is set and a serious error occurs.

System Proc Expansion

2.1.8a  ($DECIMAL.ADJ)

$DECIMAL.ADJ(length,places,err,PACK,MSG)

In general, because of the way they are created, packed decimal elements in SPIRES are not suitable for indexing when range searching is desired (e.g., FIND READING > 9.49). This proc helps remedy that situation. It allows you to specify a length in bytes for the value as well as the number of decimal places it should have. Besides fixing the value length so that a packed element can be stored as a fixed-length element, this proc standardizes the internal form of the value so that most sequencing works properly. Note, however, that negative values will be interleaved with positive values in a packed decimal index, even with the use of this proc. But if all values are positive, indexing will work properly, allowing range searching.

This proc can be considered a combination of the $DECIMAL and $ADJUST procs. The $DECIMAL part forces the value to have a specified number of decimal places. The input value should be a packed decimal value (but see the PACK parameter below). If necessary, zeroes are appended to the value to produce the appropriate number of places; or if there are too many places, the right-most digits are discarded (with appropriate rounding).

Syntax and Parameters

The $DECIMAL portion of this proc may add zeroes to or delete digits from the value, thus possibly changing the precision of the value. (Precision is defined as the number of digits in the value counting from the left-most non-zero digit to the right-most digit, zero or not.) If the precision of the result is greater than 30, the result will be "infinity"; if the precision of the result is 0 (zero), the result will be 0.

When you choose a value for the "length" parameter, remember that the output value from the proc will always have the number of decimal places specified by "places". Thus, if the number of digits in the value is (length*2)-3, then the number of digits that can precede the decimal point of the input value will be (length*2)-(places+3). For example, if we want the processed value to have 3 decimal places, and we choose a "length" of six bytes, then the total number of digits in the input value may be (6*2)-3, or 9; three of those places will be decimal places, so up to six digits can appear in the integer portion of the value. In other words, the highest possible value allowed with those parameters is 999,999.999; the lowest is -999,999.999.

Though the "places" and "length" parameters do provide a limited method for range testing, the $PACK.TEST proc gives you full capabilities here. (For indexing purposes, you may want to verify that the input value is not less than zero.) If you want to check ranges, the INPROC rule string might look like this:

For more information about packed decimals in SPIRES, see section 18 of the SPIRES manual "Technical Notes" or EXPLAIN PACKED DECIMALS.

Example: $DECIMAL.ADJ(3,2)

This proc will adjust a packed decimal value so that it has two decimal places and so that the length in bytes of the converted value is three. If the formula cited above is applied, the number of digits in the value is (3*2)-3, or three, of which two will be decimal places. Hence, the allowed range of values for this proc will be -9.99 to 9.99. The error flag would be set for values outside of that range, and a serious error would occur. The error flag would also be set if the input value were not a packed decimal value.

System Proc Expansion

2.1.8b  ($DECIMAL.OUT)

$DECIMAL.OUT(places,error)

Like $PACK.OUT, this proc is used to convert a packed decimal value to a string for output. In addition, this proc adjusts the value so that it has a specified number of decimal places. If necessary, zeroes are appended to the value to produce the appropriate number of places; or if there are too many places, the right-most digits are discarded (with appropriate rounding). For example, if the value of the "places" parameter (the number of places in the value; see below) is 3, then the packed value 4.5678 would be output as 4.568, while the value 4.56 would be output as 4.560. Leading zeroes in the value will be stripped.

Syntax and Parameters

All three "$DECIMAL" procs ($DECIMAL, $DECIMAL.ADJ and $DECIMAL.OUT) affect the precision of the processed value. ("Precision" is defined as the number of digits in the value, counting from the left-most non-zero digit to the right-most digit, zero or otherwise.) If the precision of the result is greater than 30, the result will be "infinity" (either "@@" or "-@@"). If the precision of the result is 0, then the result will be 0. If you do not want the precision of the value changed, you should use the $PACK.OUT proc instead.

For more information about packed decimals in SPIRES, see section 18 of the SPIRES manual "Technical Notes" or EXPLAIN PACKED DECIMALS.

Example: $DECIMAL.OUT(2)

This proc would convert a packed decimal value to a string, with the output value having two decimal places of accuracy:

System Proc Expansion

2.2.0  ($DECODE)

$DECODE(values,error)

$DECODE is usually included as an OUTPROC whenever $ENCODE is included as an INPROC. The stored integer value created by the $ENCODE proc will be replaced by the appropriate value from the list of values included with the $DECODE proc.

Syntax and Parameters

Example: $DECODE('APPLES, BANANAS, CUMQUATS, ORANGES')

This proc would return the value APPLES, BANANAS, CUMQUATS or ORANGES, depending on whether the input value was the binary value 1, 2, 3 or 4, respectively. This proc would return the "correct" values only if $ENCODE had been included with the same list of values. If $ENCODE had included the list "APPLES, BANANAS, ORANGES, CUMQUATS", then $DECODE in this example would have the effect of changing CUMQUATS to ORANGES and ORANGES to CUMQUATS.

System Proc Expansion

2.2.1  ($DEFAULT)

$DEFAULT(value,occ,error)

This proc provides default values for the element if "not enough" values are input. This proc is similar to $MIN.OCC except that $DEFAULT is designed primarily for situations where you want SPIRES to supply a single value by default if no value is provided. In such cases, you need only supply the "value" parameter when coding the proc. $MIN.OCC is designed primarily for testing the number of occurrences of an element and then, if desired, providing a default value for the element if not enough values naturally occur.

Syntax and Parameters

Example: $DEFAULT(None)

This proc will provide a value of 'None' if no other value is input for the element.

System Proc Expansion

2.2.1a  ($DEFAULT.COND)

$DEFAULT.COND(value,element,relation,list,NOOCCUR)

The $DEFAULT.COND proc provides a default value for an element based on the value or values of another element. Specifically, if no value is given for the current element, this action retrieves all the values of the element named in the proc in their internal forms. It compares the values to values given in the proc, determining whether any of the values relates (e.g., "is equal to", "is greater than") to the values in the proc. If the relationship succeeds for any occurrence, then the current element is assigned another value given in the proc.

In other words, if the current element has no value, SPIRES sees whether any of the values of another element match certain conditions described in the proc. If any does, then the current value gets a specific default value.

Syntax and Parameters

Any null values retrieved for "element" are abandoned; that is, they will never satisfy the specified condition.

A serious error occurs in the event of a coding problem: if the named "element" is a structure and it occurs, then the system proc fails.

Example: $DEFAULT.COND('4',TYPE,EQ,'INTEGER,REAL,HEX')

If the current element has a value already, do nothing more to it. However, if it does, fetch the values of the element TYPE. (If there are no values of TYPE, do nothing further; the proc will not return a value.) If any of the retrieved values of TYPE match any of the values INTEGER, REAL or HEX, then assign the current element the value "4".

Example: $DEFAULT.COND('N/A',SPOUSE.NAME,0,,NOOCCUR)

In this rather specialized form, the proc will provide the value "N/A" for the current element if no occurrences of SPOUSE.NAME exist. Note that the "relation" parm was assigned the value "0", and that no list of values was given for comparison.

System Proc Expansion

2.2.2  ($DISCARD)

$DISCARD(what)

On input, the value is converted to null and discarded. No occurrence of the element is stored. In addition, if the STR symbol is used (see below), the structure containing the element will be discarded.

Syntax and Parameters

No errors can occur during execution of the $DISCARD proc.

This proc, with the ELEM symbol, may be used when you have an optional element you no longer wish to keep values for. As new records are added and old records containing the element are added and updated, the element can slowly disappear from the subfile. This procedure also keeps the element in the list of element names for the record-type. You may prefer to rebuild the file instead, eliminating the element that way, but if the file is large, the cost of rebuilding it may be more than the cost of following this procedure.

[See 2.5.7.]

The situation in which $DISCARD with the STR symbol is most commonly used is in full-screen applications where you want to give the user a way to indicate that an entire occurrence of a structure should be removed. For example, here is a skeletal structure definition:

On an input screen during merge processing, if a user "marks" a value for the DELETE element (e.g., typing an "X" in its field), then the entire structure would be discarded.

Warning: If the structure contains "non-updateable" elements for some accounts (elements affected by a priv-tag and the NOUPDATE statement in the file definition), then the "delete" element should also be made non-updateable for those accounts. Otherwise, such a user could update the non-updateable elements, in the sense that he or she could remove the entire structure.

System Proc Expansion

2.2.3  ($DOLLAR)

$DOLLAR(how,error,MSG)

This proc will test that the value is in one of the following forms for dollars and cents: ($)D, ($)D., ($)D.CC, ($).CC. (The dollar sign is optional.) If it is not, the error flag is set. The value is usually converted for storage in a manner specified by the "how" parameter (see below).

$DOLLAR.OUT is often coded as an OUTPROC to convert the value back to the proper form for output. Alternatively, you can use the $EDIT proc to provide your own edit mask on output if you store the value using the INT or INT.SHORT symbols for the "how" parameter in $DOLLAR.

Syntax and Parameters

Example: $DOLLAR(INT.SHORT)

SPIRES will verify that the incoming value is in a standard monetary form, allowing zero, one or two decimal places in the value. If it passes that test, the value is converted to a four-byte integer form for storage. (An integer is made by multiplying the value by 100, thus eliminating the decimal point. The $DOLLAR.OUT proc will replace the decimal point properly.) If the value is too large for conversion (e.g., larger than $21,474,836.47) or if it fails the initial form test, then the error flag is set and a serious error occurs. Note that this example proc is equivalent to the default $DOLLAR.

Although the sample range values shown above have commas in them to make them easier to read, they are not allowed in the input value. If a value containing commas might be input, you should precede the $DOLLAR proc with a proc like $CHANGE(COMMA,NULL).

Because of certain peculiarities in the handling of floating point values by the outproc $DOLLAR.OUT, you are advised to store monetary values as integers (or as packed decimals using the $PACK or $DECIMAL proc) rather than floating point values if possible.

System Proc Expansion

2.2.4  ($DOLLAR.OUT)

$DOLLAR.OUT(how,length,error,MSG)

This proc will convert the element value generated by $DOLLAR back to the dollar-and-cents format $D.CC. Note that the "length" parameter works differently depending on the value of the "how" parameter.

Syntax and Parameters

Example

Here are some sample values as they would be displayed using various forms of $DOLLAR.OUT. Items marked with an exclamation point (!) indicate that the error flag has been set.

Because of the inconsistencies involved with REAL and REAL.ERR handling, file designers often prefer to store dollar values as integers or packed-decimal values rather than floating point values. Integer values stored with $DOLLAR can also be converted for output by $EDIT, the proc that lets you specify your own edit mask.

System Proc Expansion

2.2.5  ($EDIT)

$EDIT(divisor,mask,type,error)

The $EDIT proc converts a stored binary or packed decimal number into a character string that is then processed through the specified edit mask. This proc is used to provide different formats for money values than $DOLLAR.OUT can provide.

Syntax and Parameters

Examples

The rules for edit masks are best demonstrated by example. Below are two values demonstrated in a variety of edit masks. The "divisor" parameter is set to 2.

If the "divisor" parameter were 0, the first two edit masks would be " $23,456.00" and "-$23,456.00". The length of the value on output is always the length of the edit mask. If the value is too large to fit into the edit mask, digits are removed from the front of the value until it fits. Note that this condition does not cause the error flag to be set.

If the input packed value is positive or negative infinity, it will always be displayed as "@@" or "-@@", regardless of the edit mask.

Generally, an element that has a $EDIT proc in its OUTPROC rule string should have a $UNEDIT proc in its INPROC rule string. This is recommended because the procs that convert a numeric string for storage (such as $DOLLAR, $PACK, $INT, etc.) cannot handle many of the special characters allowed in edit masks, such as commas, trailing minus or plus signs, and CR or DB signs.

If you choose PACKED for the "type" parameter, SPIRES will assume the input value is a packed decimal value, but will not actually verify that it is. Hence, a non-packed value may be processed by $EDIT, which will treat it as if it were a packed value (i.e., it is "retyped" to packed for $EDIT processing).

For more information about packed decimals in SPIRES, see section 18 of the SPIRES manual "Technical Notes" or EXPLAIN PACKED DECIMALS.

System Proc Definition

2.2.6  ($ENCODE)

$ENCODE(values,type,error)

If $ENCODE is used an INPROC or SEARCHPROC, the incoming value is matched against a string of values and is accepted if a match is found. If accepted, the value is replaced by a one-byte integer representing the relative position of the value in the list of values. If the value does not match a value in the list, the error flag is set. To retrieve the original value, $DECODE should be coded as an OUTPROC with the same list of values.

As a PASSPROC, $ENCODE works the same as above, except that the values are matched against the list on passing to the index, rather than on input. If the value does not appear in the list, it will be discarded, and no error will occur.

During the matching procedure, the case of the values is significant, meaning that a value such as "Abc" will not match "ABC". File designers often precede this proc with a $CAP proc to guarantee that the incoming values conform to the case of the values in the $ENCODE list, which should thus be all uppercase.

Syntax and Parameters

Example: $ENCODE('APPLES, BANANAS, CUMQUATS, ORANGES')

In this example, the four values shown would be the only acceptable values for the element; they would stored as "1", "2", "3" and "4". All other values would cause a serious error.

Example: $ENCODE('SUN,MOON',,E)

This example would function the same as the above example, except that the error level has been changed to "E". If the element had a value other than SUN or MOON, the element would be rejected but the record would be accepted.

Note that the value stored by this proc is a one-byte integer, not the string. If the stored value is passed to an index, it is recommended that the value be processed through the element's OUTPROC rule string (one of the options of the $PASS and $PASS.ELEM procs) so that the indexed value will be the proper string value rather than an integer. The expanded form will take up more space in the index but makes the index "browsable" and more flexible for searching.

System Proc Definition

2.2.7  ($ENCRYPT)

$ENCRYPT(type)

This proc specifies encoding of the element according to an encryption key specified in the SET CRYPT command. Its use is to be avoided with any but the most sensitive data, since it relies on the user's memory and in some instances restricts the searching and processing of the data. The type of encryption is determined by the "type" parameter. [EXPLAIN SET CRYPT COMMAND for more information about element encryption.]

Syntax and Parameters

System Proc Expansion

2.2.7a  ($EVAL)

$EVAL(expression,error,p1)

This proc defines an expression to be evaluated to create a string answer. The input to the proc is passed into the expression as the $VAL system variable. The type of $VAL is determined by the preceding processing rules. However, the value returned by the proc is always a string. Besides $VAL, the system variables $P1 and $VELEM are also available to the expression. The expression may be any valid combination of functions, system variables, and user variables that are dynamic or defined by visibly allocated static vgroups, but not #variables defined for use by Userprocs.

In most cases, it is more efficient and actually easier to write a Userproc that will do the same work. This is admittedly contrary to the general principle that system procs are more efficient that Userprocs.

Syntax and Parameters

Example: $EVAL('$DAYS($UDATE)-$DAYS($DATEIN($VAL))')

In this example, the expression returns a numeric string equivalent to the number of days between today and the date value in $VAL. $EVAL can be used to replace one-line Userprocs, as illustrated by the following:

System Proc Definition

2.2.8  ($EXCLUDE)

$EXCLUDE(values,type,error)

If $EXCLUDE is used as an INPROC or SEARCHPROC, the entire incoming value is matched against the string of values included as a parameter on the $EXCLUDE proc. If a match is found, the value is excluded and the error flag set.

As a PASSPROC, $EXCLUDE works the same as when used as an INPROC, but the values are matched against the list on passing to the index, rather than on input. Values that match are not passed to the index.

If $EXCLUDE is used as an OUTPROC, those values that appear in the list of values will be excluded from output. No errors will occur when $EXCLUDE is used in this way.

Syntax and Parameters

Case is significant in the matching procedure of $EXCLUDE. If the value "ABC" were to be excluded and the input value were "Abc", the input value would not be excluded. File definers frequently code a $CAP proc before $EXCLUDE processing to ensure that the input value will be in uppercase like the values in the $EXCLUDE list, which should be entered that way.

Example: $EXCLUDE('CAT,DOG,BIRD')

In this example, any value except CAT, DOG and BIRD will be accepted. The values listed would cause a serious error.

Example: $EXCLUDE('M,,F',,W)

In this example, if M, F or a null value are entered as element values, the error flag would be set, causing a warning error, but they would not be excluded.

System Proc Expansion

2.2.9  ($EXPAND)

$EXPAND(how,error)

The value translated by $COMPRESS is retranslated to its expanded form. The "how" parameter (see below) must be specified the same for both $COMPRESS and $EXPAND.

Syntax and Parameters

System Proc Expansion

2.3.0  ($FIND)

$FIND(how)

This system proc by default allows a search request to retrieve the next higher value in the index if the requested value does not exist. It may alternatively be used to allow a search request to retrieve the index record for the next lower key if that key matches the initial characters of the search value.

It may only be used with simple indexes; it may not be used with qualifier, sub-index or compound index terms.

Syntax and Parameters

Example: $FIND(HIGHER)

If this proc were coded for an element called INCOME, a search request of FIND INCOME 12500 would retrieve the next higher value (e.g., 12850) if 12500 were not there.

Example: $FIND(LOWER)

If this proc were coded as a SEARCHPROC for a SUBJECT index, a search such as FIND SUBJECT FARMS would, if it didn't retrieve an index record for FARMS, find an index record for FARM if it were the next lower value in the index from the point where FARMS would have been. That works because the key of the next lower index record, FARM, matches the first characters of FARMS, the search value. On the other hand, if that next lower value in the index had been FARMHAND, no index records would have been retrieved, because FARMHAND does not match the first characters of FARMS.

System Proc Expansion

2.3.1  ($FIXED.NUM)

$FIXED.NUM(length,error,MSG)

$FIXED.NUM verifies that the input value is numeric and of a specified length. It does not alter the element value, but the error flag is set if the value contains anything other than numerals or if the value is longer or shorter than the allowed length. It was designed to check the form of numeric codes of a fixed length, such as zipcodes.

Syntax and Parameters

Example: $FIXED.NUM(2,,MSG)

This proc ensures that the input value is two digits long; if it is not, the error message "Value must be 2 digits" is displayed and a serious error occurs.

$FIXED.NUM is generally used to process elements whose values are numeric codes rather than numbers. For example, a numeric code might have the value "02", while a number would only be "2". System procs designed to process numbers, such as $INT and $INT.OUT, would not retain the leading "0". File owners often want to store short numeric codes as character strings of a certain length, rather than converting them to binary. This ensures that the leading zeroes on some values are retained and that sequencing of such values can be done properly.

System Proc Expansion

2.3.2  ($GEN.ACCT)

$GEN.ACCT(how)

This proc generates an element value using the logged on account number. The value will be in the form "GG.UUU". No errors can occur. This proc is similar to the SPIRES system variable $ACCOUNT, which contains the logged-on account number.

Syntax and Parameters

Note: This proc will not change the value if another Inclose rule has generated a value prior to the execution of this proc.

Example: $GEN.ACCT(ADD)

If account GA.SPI were the currently logged on account, that would be the value returned for this proc if the record were being added and no other value had been supplied. If the record is being updated (meaning that this element already has a value), then no value would be supplied. Thus, in effect this proc tells you what account has added the given record.

System Proc Expansion

2.3.3  ($GEN.DATE)

$GEN.DATE(how,century)

This proc generates an element value using the current date. The value will be in the eight-character form: MM/DD/YY, where MM, DD and YY are numbers representing the month, day and year respectively; if you request the CCYY option, the value will be 10 characters: MM/DD/CCYY where "CC" is the century indicator. No errors can occur. This proc is similar to the SPIRES system variable $DATE, which contains the current date.

Syntax and Parameters

Note: This proc will not change the value if another Inclose rule has generated a value prior to the execution of this proc.

The $DATE proc has options that generate the current date just as $GEN.DATE does; that proc also converts the generated date string into a four-byte hexadecimal value for compact storage. However, the $GEN.DATE proc may be used with $DATE if desired. Note then that the following two rule strings are equivalent:

File definers often prefer the latter form, since it is easier to code.

The $GEN.DATE proc must be used with $DATE (or $DATE.IN) if "date-added" processing is desired and if another processing rule, such as $CALL, appears after $DATE:

The following is not allowed:

because the ADD parameter on $DATE represents an INCLOSE rule, which may not be followed by a non-INCLOSE INPROC.

Example: $GEN.DATE(UPD)

This proc would provide the value of the current date each time the record was added or updated. In effect it provides the date the record was last updated.

System Proc Expansion

2.3.3a  ($GEN.DATETIME)

$GEN.DATETIME(how)

This proc generates an element value using the current date and time. The value will be in the nineteen-character form: CCYY.MM.DD HH:MM:SS, where the double-letters representing the century, year, month, day, hours, minues and seconds respectively; No errors can occur. For details on datetime values, [See 2.1.7a.]

Syntax and Parameters

Note: This proc will not change the value if another Inclose rule has generated a value prior to the execution of this proc.

The $DATETIME.IN proc has options that generate the current datetime just as $GEN.DATETIME does; that proc also converts the generated datetime string into an eight-byte hexadecimal value for compact storage. However, the $GEN.DATETIME proc may be used with $DATETIME.IN if desired. Note then that the following two rule strings are equivalent:

File definers often prefer the latter form, since it is easier to code.

The $GEN.DATETIME proc must be used with $DATETIME.IN if "datetime-added" processing is desired and if another processing rule, such as $CALL, appears after $DATETIME.IN:

The following is not allowed:

because the ADD parameter on $DATETIME.IN represents an INCLOSE rule, which may not be followed by a non-INCLOSE INPROC.

Example: $GEN.DATETIME(UPD)

This proc would provide the value of the current datetime each time the record was added or updated. In effect it provides the datetime the record was last updated.

System Proc Expansion

2.3.4  ($GEN.TIME)

$GEN.TIME(how)

This proc generates an element value using the current time. The value will be in the form: "HH:MM:SS". If you want the time value to be converted to a binary value, you must also specify the $TIME proc in the rule string. No errors can occur. This proc is similar to the SPIRES system variable $TIME, which contains the current time.

Syntax and Parameters

Note: This proc will not change the value if another Inclose rule has generated a value prior to the execution of this proc.

$GEN.TIME is not often used because file owners generally choose to have the $TIME proc do both the generating and converting of the time value for storage. These two rule strings are identical:

Unless you do not want the time value stored in the more compact two-byte form provided by $TIME, it is easier to use the $TIME proc, specifying either ADD or UPD as the "how" parameter, than to use $GEN.TIME.

If you want to generate a time and convert it and if you want to follow the $TIME proc with another processing rule, such as $CALL, you must use the first form shown above:

The following is not allowed:

because the ADD parameter on $TIME represents an INCLOSE rule, which cannot be followed by a non-INCLOSE INPROC.

System Proc Expansion

2.3.5  ($GETELEM)

$GETELEM(elem)

The $GETELEM proc will test for the occurrence of a second element. If no value exists for that element, nothing is retrieved. The internal value of the first occurrence of the specified element will be concatenated to the value of the current element. Both elements must be at the record level or occur within the same structure.

Syntax and Parameters

This proc can only be used as an OUTPROC. The concatenated value is not stored anywhere, and neither element's internal value is affected. The concatenated value is not processed by that element's OUTPROCs before being attached to the current element value. Only the first occurrence of the concatenated element can be accessed this way. You can use the $GETUVAL function in a USERPROC if you need other occurrences.

The types of both the retrieved value and the original value are significant in determining the type of the final value:

During compilation, SPIRES does not verify that you have given a proper element number; however, if you have not, an "unconditional error" will occur when the OUTPROC is executed. In that case, no further processing of the record will occur and an error message will be displayed. (You cannot control the "level" of an unconditional error; it is always like a serious error.)

Example: $GETELEM(3)

This example would concatenate the first occurrence of the fourth element to the value of the current element on output. If the current element is not within a structure, then the element to be concatenated is the fourth record-level element in the record. If the current element is within a structure, then the element being concatenated is the fourth element in the structure. (Remember that the element numbers start with "0" for the first element, "1" for the second, and so forth.)

System Proc Expansion

2.3.5a  ($GOAL.INDEX)

$GOAL.INDEX

$GOAL.INDEX provides some additional flexibility to the goal-index searching capability, described in the reference manual "SPIRES File Definition". The easiest way to request that the goal record-type be used as an index to the records (i.e., that users can search by record key) is by adding a Searchproc string to the Global Parameters section of the linkage.

As an alternative, or to allow multiple searchterms and Searchprocs to point to the same goal-index (perhaps for purposes of indirect searching), you can code additional individual index linkages that use $GOAL.INDEX to announce that the named index is the goal record-type so special processing can be done.

Syntax and Parameters

There are no parameters, and no errors can occur.

There are, however, some very specific rules that must be followed for this proc to work properly. The individual linkage section in which it appears must include the PTR-GROUP statement; moreover, the PTR-ELEM named in the global linkage section must be an element in the goal record-type, even though $GOAL.INDEX effectively tells SPIRES not to use it. The common approach to this problem is to add the PTR-ELEM value as an alias to the goal record's key element, which meets the requirement.

In addition, since the PTR-GROUP is not to be used as a true pointer group, this INDEX-NAME section should follow all other INDEX-NAME sections, especially those which define valid pointer groups. (The first INDEX-NAME section should always define a valid pointer group, if any exist.)

Part of a typical linkage section using $GOAL.INDEX is shown below. Record-type REC01 is the goal record-type for the subfile, as shown by the global linkage section at the start (GOALREC-NAME = REC01). It is named as a goal-index twice, first declared in the global linkage section (by the SEARCHPROC statement) and then again in the individual linkage section that follows (INDEX-NAME = REC01).

When anyone uses the PERFORMER index, SPIRES searches for the given value in the SOLOIST index in the ALBUMS2 subfile; the keys it retrieves there presumably will match keys in the current subfile, and SPIRES will use those keys to retrieve records in the current subfile.

System Proc Expansion

2.3.6  ($HEX)

$HEX(length,odd,error,MSG)

The $HEX proc will convert an alphanumeric hexadecimal string to bit string for storage. Only the characters zero through nine (0-9) and A through F (upper or lower case) can be used in the alphanumeric string. Other characters, including blanks, will set the error flag. The processing rule treats each pair of characters in the alphanumeric string as the hexadecimal representation of a byte; the pair is converted to that one-byte value. $HEX.OUT can be used as an OUTPROC to reconvert the value to hexadecimal string form.

Syntax and Parameters

Example: $HEX(ANY,ODD.ERR,S,MSG)

An input value containing only the characters 0 through 9 and A through F will be accepted and converted into a bit string for storage, one byte for each pair of characters in the input value. If the value contains an odd number of characters, meaning that the value has an incomplete pair of characters, the error flag is set, a serious error occurs, and the error message "Invalid hex value" is displayed. Except for the MSG parameter being included, this sample proc is the same as the default for $HEX.

System Proc Expansion

2.3.7  ($HEX.OUT)

$HEX.OUT(length,PAD,error,MSG)

This proc will convert the value stored by $HEX back into its hexadecimal representation. It may also be used to display the hexadecimal representation of any element value as it is stored in the record, if desired. The length of the converted value will be twice the length of the stored value, unless padding is specified.

Syntax and Parameters

Example: $HEX.OUT(4,PAD)

This proc would interpret the stored value as a two-byte hexadecimal code, such as "A5D3" or "528F"; in other words, the stored value's hexadecimal representation would be returned. If the converted value were shorter than four characters, it would be padded on the left with zeroes. If the converted value were longer than four characters, the error flag would be set, causing a warning error, but the value would be converted and displayed anyway.

System Proc Expansion

2.3.8  ($INCLUDE)

$INCLUDE(values,type,error)

If $INCLUDE is used as an INPROC or SEARCHPROC, the entire incoming value is compared to the string of values included as a parameter on the $INCLUDE proc and accepted only if a matching value is found. If no match is found, the error flag is set.

As a PASSPROC, $INCLUDE works the same as when used as an INPROC, but the values are matched against the list on passing to the index, rather than on input. Only values that match members of the list are passed; however, no error occurs for those that do not.

If $INCLUDE is used as an OUTPROC, only those values in the value list parameter will be output, although other values may be stored in the record.

Syntax and Parameters

Example: $INCLUDE('CALIFORNIA, NEVADA, OREGON, WASHINGTON')

In this example, only the four values listed would be accepted as element values. Any other value would cause a serious error.

System Proc Expansion

2.3.9  ($INSERT and $INSERT.HEX)

$INSERT(what,how,where,error)

This proc will insert a specified string either before or after the input value or at a specified point within it. You would generally use $INSERT, but $INSERT.HEX is useful when you want to insert a hex string.

Syntax and Parameters

Example: $INSERT(KB-,FRONT)

This example would insert the string "KB-" at the front of each input value. If the value were null, the error flag would be set and a warning error would occur; the null value would remain unchanged.

Example: $INSERT(-,RIGHT,5)

The string "-" would be inserted to the right of the fifth character in the value counting from the right end, as follows:

If the input value were shorter than five characters, a warning error would occur and the value would have been left unchanged.

Example: $INSERT.HEX(#40#,LEFT,3)

A blank (hex 40) would be inserted to the left of the third character in the value, counting from the left end.

System Proc Expansion

2.4.0  ($INSETL)

$INSETL(what,length,error)

This proc will duplicate a character string as many times as necessary to create a value of a specified length. The input value is then overlayed onto this string, beginning from the left.

Syntax and Parameters

Example: $INSETL(0,10)

This example, in effect, will add as many zeroes as necessary to the end of the value so that the resultant value is 10 characters long. If the input value is already longer than ten characters, a warning error would occur and the value would not be changed.

Example: $INSETL(ab,5,S)

With this example, an input value such as "12" would result in the value "12aba". Note that the string "ab" is first built up to the string "ababa", repeating the "what" string up to the "length" given, before the overlay occurs. An input value such as "123456" would cause a serious error because it is longer than the allowed "length".

System Proc Expansion

2.4.1  ($INSETR)

$INSETR(what,length,error)

This proc will duplicate a character string as many times as necessary to create a value of a specified length. The input value is then overlayed onto this string, "right justifying" the value in the field. For example, if the duplicated string is XXXXXX, and the input value is ABC, then the value returned by $INSETR is XXXABC.

Syntax and Parameters

Example: $INSETR(0,10)

This example will in effect add as many zeroes as necessary to the beginning of the input value so that the value is 10 characters long.

Example: $INSETR(,5)

This proc will right-justify the input value in a field five characters long. An input value of XX would be preceded by three blank spaces, making a total length of five.

System Proc Expansion

2.4.2  ($INT)

$INT(length,error,MSG,UNIQUE)

This processing rule by default verifies that the value is an integer and converts the value into a four-byte binary value. If the value is not an integer or is outside the input boundaries as described below, a serious error occurs. By default, any number from -2,147,483,647 to 2,147,483,647 can be stored. Numbers outside that range are rejected. The converted value can be processed for output by $INT.OUT.

For the input value, leading or trailing blanks are allowed, and a leading sign (+ or -), optionally surrounded by blanks, is also allowed. Any characters other than these signs and numerals causes an error. Note that the input value may not normally be null (but see "value" below).

Syntax and Parameters

Because some values outside of the range of values for storage are accepted when the "length" parameter value is BYTE, HALF or 3, these values are seldom used in situations where data integrity is vital. Note that the $RANGE proc cannot be used to guarantee that the values are within the allowed range in those cases because the conversion has already taken place by the time the $RANGE proc is executed. This range problem does not arise with the default "length", INT, but of course, using it means the stored value will be slightly longer.

Example: $INT(FULL)

This is equivalent to the default for $INT. The value is converted to a four-byte binary value for storage. Failure to convert properly, either because it is not in the form of an integer or because the value is outside the range boundaries noted above, causes a serious error.

Example: $INT(BYTE,E,MSG)

The value is converted to a one-byte value, if possible, for storage. If the conversion fails or if the value is outside the range noted above, an E-level error occurs and the message "Invalid integer value" is displayed.

System Proc Expansion

2.4.3  ($INT.OUT)

$INT.OUT(length,PAD,error,MSG)

This proc converts the fixed binary value stored by the $INT proc to a character string. The converted value contains digits or a minus sign followed by digits.

Syntax and Parameters

Example: $INT.OUT(5,PAD)

This proc will convert binary values to strings for output. If the length of the converted value exceeds five characters, a warning error will occur, but the value will be output anyway. If the length is less than five characters, the value will be padded on the left with zeroes to make it five characters. If the values 123 and -123 were stored, they would be converted to "00123" and "-0123" respectively.

System Proc Definition

2.4.4  ($ITALIC)

$ITALIC

This proc, generally used in output formats, converts all alphanumeric characters to the hex characters that will, on output, print as italic type on the 3800 laser printer when a multiple-font character set is used. At this writing, those sets available at Stanford are MT10, MT12, MT15, MH12, ML10 and MC10.

Note that values processed by this proc are not readable at a terminal. Only elements with values that will be printed on the 3800 laser printer using one of those character sets should use this proc. Values processed on output through this proc should probably not be re-input into the subfile in this form.

There are no parameters, and no errors can occur.

System Proc Expansion

2.4.5  ($LENGTH)

$LENGTH(length,recovery,PAD,error,MSG)

This proc tests the value to see if its length matches the specified length. If the value is not the exact length, the error flag is set, which by default causes a serious error. If desired, the error level can be changed and the value can then be shortened if it is too long or padded with blanks if it is too short.

Syntax and Parameters

Example: $LENGTH(12,KEEP.FIRST,PAD,W)

This example will truncate any value longer than 12 characters, keeping the first 12 characters, or will pad to the right with blanks any value shorter than 12 characters. In either case, the error flag will be set and a warning message be displayed.

Example: $LENGTH(5)

This example will reject any value longer or shorter than 5 characters, causing a serious error.

System Proc Expansion

2.4.6  ($LOGICAL)

$LOGICAL(how,chars,error)

This proc performs bit manipulation on the input value. For most values of the "how" parameter, a bit string, created by replication of the "chars" value (see below) to the length of the input value, is compared bit by bit to the input value. One of the three logical operators AND, OR and XOR is performed on each bit of the input value and the bit string, generating a third value, which is the value returned by the proc.

Another way to use this proc, to convert integer and floating-point numeric values so that they can be indexed properly when negative ones may be present, is described further down in this section.

Syntax and Parameters

This form of the proc is used for manipulating bits in string values.

          Value bit       String bit     Resulting bit
              0              0                0
              0              1                1
              1              0                1
              1              1                1
          Value bit       String bit     Resulting bit
              0              0                0
              0              1                0
              1              0                0
              1              1                1
          Value bit       String bit     Resulting bit
              0              0                0
              0              1                1
              1              0                1
              1              1                0

Example: $LOGICAL(XOR,#FF#)

This proc first generates a character string of the same length as the input value, each character within the string being a hex FF (all bits set to 1). Each bit of the input value is compared to its corresponding bit in the generated string. The consequence of the XOR processing here is that each bit in the input value is inverted; a 1 bit in the input value is converted to a 0 bit in the output value, while a 0 bit in the input value is converted to a 1 bit in the output value. This processing rule, followed by $BITS, could be used on output for an element value that was processed by $BITS on input; it would reverse the set bits, in effect telling you which bits had not been set in the input value.

Syntax and Parameters

This description applies when you want to use $LOGICAL to adjust integer or floating-point number values so that they can be indexed properly when negative ones may be present. The proc is used twice -- first on input, and later on output.

Adding the $LOGICAL proc to the Inproc and Outproc string and in the Searchproc for an integer or real number element will guarantee that the values will sort properly in indexes. Without them, negative numbers do not sort properly, which can skew range searches in particular.

So for real numbers, you would want to add this proc to the Inproc and Searchproc after the value's conversion to real:

And add this proc to the element's Outproc string, before the conversion of the value to string:

For integers, the same proc works for both input and output:

System Proc Expansion

2.4.6c  ($LOOKSUBF)

$LOOKSUBF(how,subfile,element,error,via)

This proc works like $LOOKSUBG, the "table lookup" proc. $LOOKSUBF will access a record in another subfile that has a key equal to the value input to this proc. The input value must match the internal form of the record key and should be the same type (e.g., both are type integer). If no record is retrieved from the subfile, the error flag is set (but see NONE.VERIFY as a value for the "how" parameter). The accessed record may then be used to verify the current input value or provide a replacement value for it. Unlike $LOOKSUBG, this proc can access records in subfiles of other files, as long as the user can access that subfile. But note that this proc cannot be used as a PASSPROC.

Note: $SUBF.LOOKUP and $LOOKSUBF are different names for the same proc. In other words, you could replace the "word" $LOOKSUBF with $SUBF.LOOKUP, using the parameters listed below. $LOOKSUBF is preferred because of its parallel with the system function $LOOKSUBF.

Syntax and Parameters

The $LOOKSUBF proc should not be used if you will be extracting more than one element from the accessed goal record. Subgoal processing in formats is the efficient approach. Here, the record would be accessed each time the $LOOKSUBF proc was called, which would not be very efficient.

Example: $LOOKSUBF(REPLACE,'U.S. STATES',ABBREVIATION)

This proc is presumably for an element containing the name of one of the United States. The proc would access the subfile U.S. STATES, looking for a goal record whose key was the value input to this proc. If the record were retrieved, the value for the element ABBREVIATION in that record would become the value output by this proc. The error flag would be set (causing a serious error) if there were no subfile named U.S. STATES that the user could access, if no record having the appropriate key had been accessed, or if no occurrence of the element ABBREVIATION (or no element named ABBREVIATION) were in the retrieved record.

When the "lookup-subfile" is rigged for command logging, the message COMMAND LOGGING IN EFFECT FOR THIS SUBFILE will be displayed the first time the $LOOKSUBF proc is executed -- it cannot be suppressed. (The "first time" means the first time the proc is executed while the current subfile is selected; thus, the message is usually only displayed once per set of subfile transactions for the currently selected subfile.) Because this message can be disconcerting to a user if it appears during the midst of a subfile transaction such as DISPLAY or UPDATE, you might want it to appear earlier in the session, either by selecting the lookup-subfile through a path (perhaps in the select commands for the current subfile) or by setting a format containing a startup frame with a $LOOKSUBF proc in it.

System Proc Expansion

2.4.7  ($LOOKSUBG)

$LOOKSUBG(how,record,element,error,via)

This proc is sometimes called the "table lookup" proc. This proc will look in another record-type for a record having a key equal to the value of the current element. If no record is retrieved from the second record-type, the error flag is set. The accessed record is then used to verify the value of the current element or to provide a replacement value for it. (Only replacement is allowed when this proc is used as a PASSPROC.) The input value must match the internal form of the record key (though the types do not have to match).

Note: $LOOKUP and $LOOKSUBG are different names for the same proc. In other words, you could replace the "word" $LOOKSUBG with $LOOKUP, using the parameters listed below. $LOOKSUBG is preferred because of its parallel with the system function $LOOKSUBG.

Syntax and Parameters

The following syntax applies when $LOOKSUBG is used as an INPROC, OUTPROC or SEARCHPROC:

If $LOOKSUBG is used as a PASSPROC, the syntax is simpler:

If $LOOKSUBG as a PASSPROC does not find the record or retrieve a value from a record, no further passing for the input value occurs.

If the values to be verified or replaced are limited in number and not likely to change, $INCLUDE or $CHANGE can be coded instead of $LOOKSUBG. The values in question would then be coded into the file definition and the value processing would be more efficient. $LOOKSUBG provides a flexible way of adding and modifying the data against which the values will be matched, since you add and change records in the second record-type rather than modify and recompile the file definition.

Remember that if you supply a record name or an element name for either of those parameters, you must supply both. Both of them default to a number if no value is given.

For more information about "table lookup" applications, see "Indirect Record-Access" in the manual "SPIRES File Definition", Section C.5.

Example: $LOOKSUBG(REPLACE,REC03,COURSE.NAME)

This proc (which could only be coded in the file definition since it uses record and element names) would access record-type REC03. If a record existed in that record-type that had the current element value for its key, the element value would be replaced by the first occurrence of the element COURSE.NAME in that record. (The element value input might have been a course number.) If a record with that key did not exist or if the record existed but it did not contain any occurrences of the COURSE.NAME element, the error flag would have been set, and a serious error would have occurred.

Example: $LOOKSUBG(REPLACE,REC01,KEY,S,LCTR)

This proc would probably be used on the pointer element of an index-record type. It would access record-type REC01 (the goal record) and replace the current element value (which is a pointer to the goal record record-type) with the key of the goal record.

System Proc Definition

2.4.7a  ($LOOKSYS)

$LOOKSYS(file,elem,err,uplow)

This proc, similar to $LOOKSUBF, provides access to records in several system subfiles. You provide a code identifying the system subfile you want to use and the name of the element whose value you want returned. The value input to this proc should be the internal form of the key of the system subfile you are accessing, and the value is forced to upper case unless the UPLOW option is given.

Currently it is useful only in Prism for use with Prism meta-data. For details about how this proc is used in Prism applications, see the manuals "How to Install a Routing Application in Prism" and "Prism Applications".

Syntax and Parameters

Example: $LOOKSYS(ROUTE,STATUS)

In this example, the value of the STATUS element is looked up in the Prism routing file.

System Proc Expansion

2.4.8  ($LOWER)

$LOWER(cap)

This proc converts all uppercase characters to lowercase. Non-alphabet characters are not affected. Using the "cap" parameter, you can specify that some of the characters in the value should then be capitalized.

Syntax and Parameters

For a complete list of possible number-options for 'cap', [EXPLAIN $CASE FUNCTION.]

Example: $LOWER(CAP.FIRST)

This proc would affect values as follows:

System Proc Expansion

2.4.9  ($LSTR)

$LSTR(length,recovery,error)

This proc will test a value to see if it is longer than a specified length. If it is, then by default the value is truncated at the right end so that the output value has that length.

Syntax and Parameters

Example: $LSTR(10)

This proc will truncate any input value longer than ten characters to a length of ten, dropping the excess from the right end. If the input value is shorter than ten characters, it is not changed. Note that this is the normal form of $LSTR; the second and third parameters are seldom used on this proc.

System Proc Expansion

2.5.0  ($MAX.LEN)

$MAX.LEN(length,recovery,error,MSG)

This proc tests the value to see if it is longer than the number of characters specified in the "length" parameter. If it is, the error flag is set and a serious-level error occurs. Alternatively you can specify a W- or D-level error and have the value be truncated rather than be rejected.

Syntax and Parameters

Example: $MAX.LEN(25)

In this example, any element value longer than 25 characters would cause a serious error.

Example: $MAX.LEN(4,DROP.FIRST,W)

This example would drop the first 4 characters of any value that is longer than 4 characters and would display a warning message. This can be useful when dealing with values that all begin with the same 4 character prefix or a 4 character prefix that need not be stored.

System Proc Expansion

2.5.1  ($MAX.OCC)

$MAX.OCC(occ,recovery,error)

This proc will test that an element occurs no more than a specified number of times. If it occurs more, then the error flag is set and a serious error occurs. Alternatively, the error level can be changed so that the action specified in the "recovery" parameter be taken.

Syntax and Parameters

Example: $MAX.OCC(4)

This proc will count the number of occurrences and, if there are more than four, a serious error will occur.

Example: $MAX.OCC(3,DROP.ALL,D)

This proc will count the number of occurrences and, if there are more than three, all occurrences of the element will be dropped.

System Proc Expansion

2.5.2  ($MIN.LEN)

$MIN.LEN(length,PAD,error,MSG)

This proc tests the value to see if it is at least the length specified in the "length" parameter. If the value is shorter, a serious-level error occurs. Alternatively you can specify that any value that is shorter should be padded with blanks so that it equals the specified length; in that case you must change the error level to W or D.

Syntax and Parameters

Example: $MIN.LEN(5,PAD,W)

In this example, any value shorter than 5 characters would be padded on the right with blanks. A warning error would occur if the value were short.

Example: $MIN.LEN(5)

This proc would reject any value shorter than 5 characters. A serious error would occur.

System Proc Definition

2.5.3  ($MIN.OCC)

$MIN.OCC(occ,value,error)

This proc will test that an element occurs at least a specified number of times. If it does not, then a serious error will occur. Alternatively, if the error level is changed to D or W, a specified value can be used to create additional occurrences of the element.

Syntax and Parameters

Example: $MIN.OCC(3,OTHER,W)

This proc will count the number of occurrences for the element; if it is less than three, the value OTHER will be used to create additional occurrences of the element, and a warning error will occur. The final occurrence count will always be three.

System Proc Expansion

2.5.4  ($MSG)

$MSG(message)

This proc defines an error message to be displayed if a processing rule fails and the error level for the rule is W, E or S. It must appear in the rule string before the rule to which it applies and can appear more than once in a rule string. Any subsequent error in the processing rule string will cause the most recent $MSG message to be displayed. The $UCODE system variable contains the current user-defined error message.

Syntax and Parameters

No errors can occur with the $MSG proc.

If the user has set system messages to 0 or 1, the user-defined error message will not be displayed when an error occurs. Similarly, if a W-level error occurs and the user has set warning messages to 0 or 1, or is an S-level error occurs and the user has set serious messages to 0 or 1, the message will not be displayed.

Example: $MSG(Value longer than 12 characters)

In this example, error message "Value longer than 12 characters" will be displayed if any subsequent processing rule in the rule string fails.

System Proc Definition

2.5.5  ($NAME)

$NAME(order,error,MSG)

This proc will accept name values in any of the following forms:

(Note that the "title" portion, as well as any comma or commas directly preceding it, is optional.) The value will be converted to the form specified by the ORDER parameter (see below). If the element will be used to sequence results in last name alphabetical order, then the last name should be stored at the beginning.

The ORDER parameter can also specify that search procs be added to allow flexible searching on name values. Note that the $PNAME proc is generally used as a SEARCHPROC for name indexes, which are always made up of sub-indexes, and which cannot be handled by $NAME as a SEARCHPROC. The $NAME proc should be used as a SEARCHPROC for a name index that is coded as a simple index. Generally then, $NAME is the INPROC and OUTPROC rule for a name element in a goal record or as the key of an index record built and searched by using $NAME as the PASSPROC and SEARCHPROC.

Syntax and Parameters

Example: $NAME(LAST.FIRST)

This form of the proc, equivalent to the default, stores a name in the order LAST, FIRST MIDDLE, TITLE. (If no TITLE exists, it and the two extra commas are omitted, as shown in the chart above.) This form is commonly used as an INPROC and an OUTPROC, especially for index records built with $NAME as a PASSPROC.. The form $NAME(FIRST.LAST) is often used as an OUTPROC but seldom as an INPROC since file owners usually want names in LAST.FIRST order for sorting.

SEARCHPROC and PASSPROC

When used as a PASSPROC, the order parameter (P1) is usually 1 or 2 to create a "LAST, FIRST MIDDLE" form of key to the index record. Any title field is dropped by both SEARCHPROC and PASSPROC versions of $NAME (A41). When used as a SEARCHPROC, the order parameter (P1) is usually coded with values of 4 thru 7 corresponding to 0 thru 3 for $PNAME (A38). And like $PNAME, you can append a truncated-search rule in the SEARCHPROC.

System Proc Expansion

2.5.6  ($NOPASS)

$NOPASS

This proc is used to prevent an element value from being passed to an index. Though it is occasionally used during file maintenance operations, it is more generally used in these two situations:

1) When you have a single index but want to have multiple SEARCHPROC rule strings, called by different index names. For example, suppose an index of department codes is treated as two indexes, called DEPARTMENT and DEPARTMENT.CODE. If a user issues the command FIND DEPARTMENT.CODE = C04, then the appropriate SEARCHPROC may contain only the $CAP proc, for instance. On the other hand, the user might type FIND DEPARTMENT = MUSIC, which could invoke a separate SEARCHPROC string that contains a $LOOKSUBG proc, which looks at another record-type for a record whose key is MUSIC and returns the value C04, which in turn is used to search the index as before. This efficiently allows an index to do double duty; the extra work of $LOOKSUBG is done only if the user does not know the proper code; and if the table record-type needs to be there anyway, you are getting a second index for the storage price of one.

In this situation, you have to specify in the file definition a second index linkage for the index, as shown below. The $NOPASS proc is used to prevent the same index values from being passed to the same index twice:

In order to have separate sets of search terms (index names) and SEARCHPROCs, the index linkage must be declared twice. During SPIBILD processing, values from the DEPARTMENT.CODE element are passed to record-type REC03 by the first linkage, but not by the second, due to $NOPASS.

2) Sometimes an index is "prebuilt", and the file owner does not want it changed. Such an index may be a table used by $LOOKSUBG; by naming it as an index with search terms, the file owner allows the user to browse the record-type to see whether a particular code is present. Since the table does not contain pointers back to the goal records and since it is generally built independently from the goal records, $NOPASS is coded as the PASSPROC so that SPIBILD will not try to pass values and pointers from the goal records into the table. The linkage section for such an index might look like this:

Syntax and Parameters

There are no parameters and no errors can occur.

System Proc Expansion

2.5.7  ($NULL)

$NULL(how)

As an INPROC or SEARCHPROC, this proc sets the value of the element to null. As an OUTPROC, the value is set to null, but the action specified by the "how" parameter (see below) is also taken.

[See 2.2.2.]

As a PASSPROC, $NULL prevents null element values from being passed to an index. At one time, it was recommended for almost all PASSPROCs since a null value cannot be the key of an index record (of any record, for that matter). SPIBILD no longer tries to create an index record for a null value, so the $NULL proc is superfluous in PASSPROCs for simple indexes. It may still be useful for qualifiers, sub-indexes and compound indexes, which can pass null values without it.

The $NULL proc must follow any $BREAK or A45 action in the rule string, if it is used. It is usually the last proc specified in a rule string.

Syntax and Parameters

No errors can occur.

$NULL is occasionally used following a USERPROC, in which the element value is being tested. If the value passes the test, then the UPROC that stops further element processing is executed (SET LASTRULE), allowing the element value "through". However, if it does not pass the test, then SET LASTRULE is not executed, in which case the element value proceeds to the $NULL proc and is set to null.

Remember that setting a value to null is not the same as discarding it. On input, a null value is stored in the record as an element occurrence, unless other processing rules declare otherwise.

Example: $NULL(ELEM)

In this example, $NULL is used as an OUTPROC that sets the value of the element to a null value. Neither the element name nor its null value are output.

System Proc Expansion

2.5.8  ($OCC)

$OCC(element)

This proc will count the number of occurrences of a specified element. The value returned will be a five-digit number from "00000" to "99999". (The current limit to the number of occurrences of an element is 32,767.)

If no other processing rules appear in the INPROC rule string, SPIRES will then convert that number to a 2-byte binary number, and store the value as the single occurrence of the current element. Note however that the element type will be considered string, not integer (see the second example below). If other processing rules appear in the INPROC string, the value will not be converted to integer, allowing the other rules to convert the value as desired (e.g., to a packed decimal with $PACK).

Syntax and Parameters

No errors can occur.

Example: $OCC(CHILDREN)

In this example, the number of occurrences of the element CHILDREN will be stored as the value of the current element.

If you want the value to be stored as an integer, you should consider preceding the $OCC proc with the $INT proc:

Although converting the value to a two-byte integer is the default if no other processing rules are coded in the INPROC string, the $INT proc here also defines the element as type integer, which $OCC alone does not. For most applications, this is not necessary but it is recommended. Whether you add the $INT proc or just use $OCC alone in the INPROC rule string, you should use $INT.OUT on output. (Of course, if you add other processing rules to convert the value to another type, such as packed decimal, you would use the appropriate OUTPROC for that type.)

System Proc Expansion

2.5.9  ($PACK)

$PACK(type,length,error,MSG,style)

$PACK will convert the value to a packed decimal form. The input value can be either a character string or a binary value. If a storage length is not specified, the minimum possible length of the value is stored.

If $PACK is used as an INPROC, the stored value may be processed by $PACK.OUT, $EDIT or $DECIMAL.OUT on output.

Leading and trailing blanks are stripped from the value before any other processing occurs. Next the input value is adjusted so that it begins with an integer, followed by an exponent. For example, "12.345" is adjusted to "12345E_3" (meaning "12345 times 10 to the -3rd power). Then, following any other processing directed by the "type" and "style" parameters, the value is stored. The stored value consists of one byte containing the exponent (ranging from -128 to 127), a byte to contain a sign character and the final digit of the integer, and then a byte for each two digits in the remainder of the value:

where "d" represents a digit, "s" represents the sign character and "exp" represents the exponent. Thus, the minimum length for a stored value is two bytes. The storage length is controlled by parameters, as described below.

For more information about packed decimals in SPIRES, see section 18 of the SPIRES manual "Technical Notes" or EXPLAIN PACKED DECIMALS.

Syntax and Parameters

Example: $PACK(CHAR,5,S,MSG)

The input value is a character string that is converted to a packed decimal value. If the conversion fails because invalid characters appear in the input value, or if the converted value is longer than five bytes, the error flag is set, a serious error occurs and message "Invalid packed value" is displayed.

System Proc Expansion

2.6.0  ($PACK.OUT)

$PACK.OUT(strip,error,MSG)

This proc will convert the packed decimal value stored by $PACK to a character string. The value will be converted into one of four formats: integer, decimal point, exponential or "infinity". The appropriate form is determined by SPIRES using these rules:

When the value has an exponent of 0 (i.e., no digits to the right of the decimal point), it is output in integer format, that is, a leading minus sign (if needed) and digits, e.g., 100, -9834, or 0.

If the value has a negative exponent (i.e., the value has a fractional portion), then SPIRES evaluates the total of the exponent and the number of significant digits in the value (which is the number of digits counting from the left-most non-zero digit to the right-most digit, whether zero or not). If that number is greater than or equal to -4, then the value is output with a decimal point. For example,

If the value does not meet the above requirements (or if the EXP symbol is specified), it is output in exponential format, that is, a signed integer followed by the letter E and a signed exponent:

If the value is infinity, represented internally as hex FCFF in packed, it is output as either @@ or -@@ (positive or negative infinity).

For more information about packed decimals in SPIRES, see section 18 of the SPIRES manual "Technical Notes" or EXPLAIN PACKED DECIMALS.

Syntax and Parameters

Example: $PACK.OUT(STRIP)

The value, presumably stored as a packed decimal, will be converted to a string value. Leading zeroes will be deleted.

System Proc Expansion

2.6.1  ($PACK.TEST)

$PACK.TEST(how,value,error)

This proc is used to test the value of a packed decimal. The input value is compared to the "value" parameter using the relational operator specified by the "how" parameter. For example, the value may be confirmed to be less than 14, or greater than or equal to 0.

Syntax and Parameters

Unlike the $RANGE proc, which can be used to test values of integer and floating-point (real) elements, $PACK.TEST will not change the input value if the comparison fails.

Example: $PACK.TEST(GE,0)

This proc verifies that the input value is a non-negative packed decimal (that is, it is greater than or equal to zero). If it is not, then the error flag is set and a serious error occurs.

System Proc Expansion

2.6.2  ($PARAGRAPH)

$PARAGRAPH(fields,how,error,HALF)

This proc is designed to handle numeric codes, such as "1.1" or "3.5.7", where the value consists of a series of integers separated by periods. Such values may be found as paragraph numbers, section numbers, or any other series of codes used to identify a hierarchical set of values. Using this proc can give you the advantages of numeric codes (proper sorting, easy handling) and the storage advantages of integers (less space for large numbers).

As an INPROC or SEARCHPROC, this proc will accept an incoming value only if it is a series of positive integers separated by periods. Each integer in the value is converted to a byte or half-word (two-byte) value, depending on the value of the HALF parameter. The length of the converted value can be specified.

As an OUTPROC, this proc converts the stored value (in bytes or half-words) to a set of numeric values separated by periods.

Syntax and Parameters

       For example, on output the value 1.23.4 is treated as follows:
         Rule                    Converted Value
          $PARAGRAPH(0,3)         1.23.4
          $PARAGRAPH(1,3)         01.23.04
          $PARAGRAPH(2,3)         001.023.004
          $PARAGRAPH(2,2)         001.023.004 (error)

See "fields" and "how" above for an explanation of how to determine how much storage space values will use.

Example: $PARAGRAPH(4,1,S)

This proc might be used as an INPROC for an element called TRANSACTION.NUM, a four-part numeric code such as "81.8.15.5", where the first numeral represents the year (1981), the second the month (August), the third the date (the 15th) and the fourth represents the transaction number for that day. This value would always be stored in four bytes. If the input value contained non-numeric characters other than leading and trailing blanks or internal periods, the error flag would be set. The error flag would also be set if the value contained more than four integers, or if any one of the integers was greater than 255 or less than 0. A serious error would occur.

System Proc Expansion

2.6.3  ($PASS)

$PASS(type,what,OUT)

This processing rule is used to fetch the values of the element named in the preceding GOALREC-ELEM statement of the linkage section in order to create or update the appropriate index records. By default, it fetches the value and converts it to uppercase. If the value is numeric (i.e., if it was processed on input by $INT, $REAL, $DOLLAR, etc.) or if the value will be processed by $WORD or $PNAME (for word or personal name indexes respectively), other options should be chosen.

This proc may only pass one element. To pass multiple elements to a single index, use the $PASS.ELEM proc.

Syntax and Parameters

Example: $PASS(UPPER,NAME)

This is the usual proc found at the start of a PASSPROC string for a personal name element. The element named by the GOALREC-NAME statement is fetched and converted to uppercase, if it is not in that form already. Later in the rule string it will presumably be processed by $PNAME.

Example: $PASS(UPPER,WORD)

This is the usual proc found at the start of a PASSPROC string for an element whose value is being passed to a word index. Since the value is a character string, it is converted to uppercase, even though it may contain numerals (numerals in character strings are not affected by case conversion). Later in the rule string, it will probably be processed by $WORD.

Example: $PASS(BINARY)

The element being passed to the index should not be "forced to uppercase" because it is not a character string.

System Proc Definition

2.6.4  ($PASS.BY)

$PASS.BY(passer,elem,relation,value)

This unusual proc may be used for a form of conditional passing. It is generally used in the following way. For the current index, the element values being passed to it from any given record are passed only if the internal value of some other element in the record matches one of a set of given values. The proc is quite general, however, and provides a number of variations on this scenario.

Specifically, this proc will pass values for the "passer" elements only if another element in the record ("element" below) meets certain criteria. The first occurrence of "element" is retrieved and compared to the list of "values" given in the proc, using the element's internal value and using the relational operator specified as "relation". If a comparison succeeds, the element is passed.

Note that this proc follows a $PASS or $PASS.ELEM proc that determines the complete list of elements being passed. Elements being passed that are not included in the "passer" list are not affected by this proc and are passed regardless.

If desired, this proc may be used more than once in a PASSPROC string.

Syntax and Parameters

Example: $PASS.BY('HOME.ADDRESS,BILL.ADDRESS', STATUS,NE,'DECEASED')

This example might be in a PASSPROC for the address index of a patient file. During passing of the two elements HOME.ADDRESS and BILL.ADDRESS, the STATUS element of the record is fetched. If its internal value is not equal (NE) to DECEASED, then the two elements HOME.ADDRESS and BILL.ADDRESS are passed to the index. If its value is equal to DECEASED, the elements are not passed. If the STATUS element does not occur for that record, the elements are not passed either. Any other elements that would be passed to the index, if any, would be passed regardless of the value of STATUS.

System Proc Expansion

2.6.5  ($PASS.COND)

$PASS.COND(elems,how)

This proc, which follows a $PASS or $PASS.ELEM proc, passes an element value depending on the occurrence or non-occurrence of another element.

Syntax and Parameters

Example: $PASS.COND('ARRANGER,COMPOSER',NOOCCUR)

If the current element being passed is ARRANGER, then if there is an occurrence of the COMPOSER element within the same structural bounds, ARRANGER will not be passed. If some other element is being passed, this action will have no effect.

System Proc Expansion

2.6.6  ($PASS.DEF)

$PASS.DEF(value)

This proc specifies a default value to be passed if no other value is available for the element being processed. If used, it should be the first rule in the PASSPROC string. It is usually coded in the PASSPROC for qualifier elements.

Syntax and Parameters

If this proc causes the default value to be passed (because the fetcher rule, e.g., $PASS.ELEM, fails to fetch a value to pass), then some subsequent rules in the PASSPROC string may not be executed. Specifically, in that situation, the following system procs and actions will be skipped if they appear later in the PASSPROC:

System Proc Expansion

2.6.7  ($PASS.ELEM)

$PASS.ELEM(elements,type,OUT)

This proc allows you to pass multiple elements into a single index. Instead of coding a GOALREC-ELEM statement, specifying an element to be passed to the index, you specify the elements to be passed in the $PASS.ELEM proc. The specific processing of each value to be passed is determined by the "type" parameter (see below).

Syntax and Parameters

Example: $PASS.ELEM('ADDRESS,CITY,STATE,ZIP', WORD)

This sample proc will pass the four named elements to the current index, converting their values to uppercase. Later in the PASSPROC string, they will be processed further by a $WORD proc that will have to be coded.

System Proc Expansion

2.6.8  ($PASS.FIELD)

$PASS.FIELD(start,stop,type)

This proc allows certain delimited strings to be deleted from the value before it is passed. The delimiter is specified by the "start" parameter (see below). An additional test can be made, matching a specific value (see "stop" below) with the beginning characters of the value, to determine whether the value should be scanned for the delimiter or not. That is, the delimiter can be "turned off" for certain values.

Note that if this proc changes the value to null by deleting all its characters, no attempt is made to pass the value further.

Syntax and Parameters

The effects of this proc vary considerably depending upon the value of the "type" parameter. For this reason, the explanation of the syntax is broken into two parts, the first for "type" = 0, and the second for "type" ~= 0.

For "type" = 0:

For "type" ~= 0,

Note that once character deletion has been "turned on" by a "start" character, it will delete all characters, even another "start" character (regardless of the value of "type") until a "stop" character is encountered. Similarly, if a "stop" character is encountered when deletion is not occurring, the "stop" character will not be deleted.

Example: $PASS.FIELD(SLASH)

This example, where "type" is 0, would not affect input values that did not have a slash in them. Also, since there is no value for "stop" here, all values would be examined for the slash character. Characters following any slash in the input value would be deleted until another slash character, if any, was found. The slashes would be deleted:

Example: $PASS.FIELD('(',''')''',3)

This example, where "type" is not 0, would affect only those values that contained a left parenthesis, the "start" character. Characters following any left parenthesis would be deleted until a right parenthesis character, the "stop" character, was found. Both parentheses would be deleted. (Because a right parenthesis is a special character in system procs, special character rule set 2 was followed, resulting in the tripled apostrophes around it in the example.)

System Proc Expansion

2.6.9  ($PASS.LCTR)

$PASS.LCTR

This proc will fetch and pass the locator of the goal record being processed. The goal record-type must be REMOVED. This proc is coded at the beginning of the linkage section of a file definition as a global PASSPROC when indexes are built using locators instead of keys. (This proc replaces $PASS.PTR, which is identical.)

Syntax and Parameters

There are no parameters.

System Proc Expansion

2.7.0  ($PASS.LEN)

$PASS.LEN(how)

This proc will pass a binary value representing the length of the element value that was being passed, as determined by the GOALREC-ELEM statement or the $PASS.ELEM proc. The passed value may be searched with $INT as a SEARCHPROC.

Syntax and Parameters

Example: $PASS.LEN(BYTE)

Instead of passing the values of the element or elements named in the GOALREC-ELEM statement or in the $PASS.ELEM proc, this proc changes the passed value to the length of those values. This length is stored in the index as a one-byte integer. The index should have $INT for a SEARCHPROC. No values larger than 255 characters will be properly handled; if values were expected to be larger than this, HALF would be coded for "how" rather than BYTE.

System Proc Expansion

2.7.1  ($PASS.OCC)

$PASS.OCC(occ)

This proc is used without the "occ" parameter to indicate that a value was already passed by the previous PASSPROC. There are two situations where it is used in this way:

See "SPIRES File Definition", section C.6.11.

The "occ" parameter gives this proc other, completely different meanings. If BYTEONE, BYTETWO, HALFONE or HALFTWO (or one of their abbreviations) is coded, a unique number is passed as a one- or two-byte binary quantity, using one of two possible counters. Both counters are initialized to 1 for each INDEX-NAME processed for each goal record. The appropriate counter is incremented by 1 each time it is used. The counter value passed is the value before the counter is updated.

This use of $PASS.OCC, restricted to local QUAL-ELEM and SUB-INDEX terms, allows counting of values passed to an index. Each value passed causes the counter to be incremented; thus if a value is being split by PASSPROC rules, the counter will be incremented several times during the passing process.

If one of the other forms below (e.g., ELEM or S2.S1.ELEM) is coded, another type of occurrence count is passed, such as the occurrence number of the element just passed, or of the structure containing it, or a combination of such numbers. This use of $PASS.OCC is also restricted to local QUAL-ELEM and SUB-INDEX terms. It is generally used to create occurrence qualifiers for same-structure index searching, using the TAND, TNOT and TOR logical operators. [See the SPIRES manual "File Definition", section C.6.13, for more information about designing that type of indexing.]

And a third use of $PASS.OCC is used to count the position of words within the element being passed when it is being passed to a word index. This use, with the PROX1 and PROX2 symbols, supports proximity searching. [See the SPIRES manual "File Definition", section C.6.2, for more information about proximity searching.]

Syntax and Parameters

For the ELEM through S3.S2.S1.ELEM symbols, the value passed will be from one to four bytes long, depending on the number of occurrence numbers being passed. For ELEM, for instance, the value is a one-byte integer; for S3.S2.S1.ELEM, the value passed is a four-byte value, each byte representing a different integer. The $PARAGRAPH proc may be useful in handling these values on output, if you are examining index records directly.

The occurrence numbers passed range from 1 to 255. If you choose a form such as S2.S1.ELEM and the particular element is not inside a structure, then S2 and S1 will be "1" by default. Or, if the element is inside a single structure, S2 would be given the value "1". In other words, "1" is supplied for structure levels not represented in the actual structure tree leading to the element.

Example: $PASS.OCC(S2.S1)

The occurrence number of the structure (S1) containing the element previously passed in the current INDEX-NAME section, preceded by the occurrence number of the structure (S2) containing it, will be passed as a two byte quantity. The occurrence number of the element itself is not passed.

System Proc Expansion

2.7.2  ($PASS.UPPER)

$PASS.UPPER(elements,type)

This proc will convert the values of specified elements to uppercase before passing. Other elements being passed will not be so converted. This PASSPROC generally follows a $PASS.ELEM proc that specifies that element values being passed should not be converted to uppercase. This proc thus gives you a way to specify that only some of the elements being passed to the index should be converted to uppercase.

Syntax and Parameters

Example: $PASS.UPPER(ADDRESS)

In this example, the ADDRESS element will be converted to uppercase as it is passed. Any other elements named in the preceding $PASS.ELEM proc would not be converted to uppercase, assuming the $PASS.ELEM proc did not itself convert the values to uppercase, which would make the current proc superfluous.

System Proc Definition

2.7.3  ($PHONETIC)

$PHONETIC

This proc allows flexible searching based on phonetic similarities of words. If used, it should appear as both a SEARCHPROC and a PASSPROC. For more information about this proc, refer to the SPIRES manual "File Definition", section C.6.14 or EXPLAIN PHONETIC SEARCH.

If the element for which phonetic searching is desired is a personal name, you might prefer to use the proc $PHONETIC.SEARCH for the SEARCHPROC, rather than $PHONETIC, since it provides more flexibility yet for search values as well as handles personal name indexes correctly.

Syntax and Parameters

There are no parameters and no errors can occur.

System Proc Expansion

2.7.4  ($PHONETIC.SEARCH)

$PHONETIC.SEARCH(order,error)

The $PHONETIC.SEARCH proc is designed for use on name values that are indexed to provide flexible searching based on phonetic similarities, using the $PHONETIC proc as a PASSPROC rule. For more information about phonetic searching, please see "SPIRES File Definition", section C.6.14.

The search value may contain a pound sign (#) to indicate truncated searching. Also, the $SEARCH.TRUNC proc is in effect, meaning that a search such as FIND NAME SMITH would retrieve values such as SMITH, J. J. J. or SMITH WESSON, JOHN, regardless of whether personal name indexing using a sub-index is in effect.

Note: This proc cannot be used in a user-defined proc. [See 1.2.] The form $PHONETIC.SRC is an allowed, but obsolete, abbreviation.

Syntax and Parameters

Example: $PHONETIC.SEARCH

The values in the index are personal names that have been converted by the $PHONETIC proc for storage. They are stored in LAST.FIRST order. The input value in the search request is converted into this form and processed by $PHONETIC. In addition, the search value may contain a "#" to indicate truncated searching.

System Proc Expansion

2.7.5  ($PNAME)

$PNAME(TRANS,how,error)

This proc is generally used as a SEARCHPROC or PASSPROC for the indexing of personal names, the name being split into two parts: the "surname" and the "remaining" part. The surname part becomes the key of the index record, and the remaining part becomes the keys of sub-index structures contained within the index record. This can cause the creation of very large index records containing several "remaining" parts. An alternative is the $NAME (A41) method that creates separately keyed index records for each unique "surname, remaining" form of personal names.

For more information about how searching works with names, [EXPLAIN PERSONAL NAME INDEXING.]

As an INPROC, $PNAME converts the value to uppercase, squeezes multiple blanks to single ones, deletes any leading or trailing blanks and then prefixes the value with a single blank. All blanks are then replaced by a byte containing the length of the non-blank portion of the name that follows, up to a maximum of 255 characters. As an OUTPROC, $PNAME replaces the length bytes with blanks. Name handling is usually done by $NAME in INPROCs and OUTPROCs.

Syntax and Parameters

The parameters below, with the exception of TRANS, have no effect if the proc is used as an INPROC or OUTPROC, so the remainder of this explanation assumes that $PNAME is being used as a PASSPROC or SEARCHPROC.

        Search                      Indexed Values
        Value                  J S BACH     JOHANN SEBASTIAN BACH
        ---------------------  --------     ---------------------
        BACH                   Yes          Yes
        J S BACH               Yes          No
        J BACH                 Yes          No
        JOHANN SEBASTIAN BACH  No           Yes
        JOHANN BACH            No           Yes
        Search                      Indexed Values
        Value                  J S BACH     JOHANN SEBASTIAN BACH
        ---------------------  --------     ---------------------
        BACH                   Yes          Yes
        J S BACH               Yes          No
        J BACH                 No           No
        JOHANN SEBASTIAN BACH  No           Yes
        JOHANN BACH            No           No

     - 3 (SEARCHPROC only) -- When specified as part of a
        Searchproc rule, this value will retrieve records only if
        the first names of the search value match or are shorter
        than the indexed values:
        Search                      Indexed Values
        Value                  J S BACH     JOHANN SEBASTIAN BACH
        ---------------------  --------     ---------------------
        BACH                   Yes          Yes
        J S BACH               Yes          Yes
        J BACH                 Yes          Yes
        J S H BACH             No           No
        JOHANN SEBASTIAN BACH  No           Yes
        JOHANN BACH            No           Yes

System Proc Definition

2.7.6  ($PRECISION)

$PRECISION(digits,error,MSG,PACK)

"Precision" is a characteristic of packed decimal values that is defined as the number of digits in the value counting from the left-most non-zero digit to the right-most digit, zero or not. For example, the precision of "123" is 3, of "845.231" is 6, and of "007" is 1. This proc lets you specify the amount of precision that a packed decimal value will have.

The amount of precision determines the amount of space needed to store a packed decimal value. In fact, the number of bytes needed to store a packed decimal is determined by the formula:

with the value of "Bytes" rounded up to an integer if necessary. For example, a value with 5 digits of precision would require (5+3)/2 or 4 bytes for storage. By using $PRECISION, you can specify the stored size of an input value by controlling its precision.

The input value must be a packed decimal value (see the PACK parameter below). The input value is adjusted to have a certain number of digits of precision, specified by the "digits" parameter. This may mean adding or subtracting precision by either adding zeroes to the end or removing digits from the end (and rounding appropriately). For example, if "digits" is 3 and the input value is 17, $PRECISION would add precision, making the value "17.0". On the other hand, if the value were 17.96, $PRECISION would subtract precision, making the value "18.0" (rounding was applied).

Syntax and Parameters

The $PRECISION and $WINDOW procs are similar in that both deal with the precision of a packed decimal value. However, $PRECISION can add precision (by adding trailing zeroes) as well as subtract precision, while $WINDOW can only subtract it.

Warning: It is possible for $PRECISION and $WINDOW to create a value containing one extra place of precision, owing to rounding of the input value. For example, the value 99.6 to two places of precision would be 100. This can only happen when rounding causes the value to be increased to a power of ten (e.g., 10, 10000, 0.1).

Example: $PRECISION(5,S,MSG)

This proc would insure that the input packed decimal value had five digits of precision. If the value were not a packed decimal value, the error flag would be set, a serious error would occur, and the error message "Invalid decimal value" would be displayed.

System Proc Expansion

2.7.6a  ($PROXIMITY)

$PROXIMITY

$PROXIMITY is used in the Searchproc of a word index that supports proximity searching, a feature that lets the user specify that two words in the record be next to or no more than a certain number of words apart from each other. It has very specific usage rules, which are explained in detail in section C.6.2.1 of the manual "SPIRES File Definition".

Syntax and Parameters

There are no parameters.

To support proximity searching, the word index also has a special sub-index with positional information that SPIRES uses to determine how close words are to each other in the goal record.

The error flag is set, and a serious-level error occurs, for any of the following:

System Proc Expansion

2.7.7  ($PUTELEM)

$PUTELEM(element,occ)

$PUTELEM will count the occurrences of the current element. If the element occurs more than the specified number of times, all additional occurrences will become occurrences of another element. Both elements must be at the record level or within the same structure. If the value of the current element has been created by another INCLOSE rule (e.g., $DEFAULT), then the second element must come before the current element in the structure, because closeout rules are applied in element order within a structure.

Syntax and Parameters

Example: $PUTELEM(EXTRA.DATES,2)

If more than two occurrences are input for the current element, the additional occurrences would be entered as values for EXTRA.DATES.

System Proc Expansion

2.7.8  ($RANGE)

$RANGE(minimum,maximum,type,error)

This system proc has different functions, depending on the type of the element being processed. If the input value is a binary or floating point value, the proc lets you test whether it falls within a given numeric range. Generally, the $RANGE proc is placed after a $INT or $REAL proc when it is used. If either limit is exceeded, the error condition is set and the value is replaced with the value of the limit.

The proc may also be used to test the values of various parts of a packed decimal value, such as its exponent, precision, or magnitude. (General packed decimal range testing is done with the $PACK.TEST proc.)

Syntax and Parameters

If the input value is binary or floating point (i.e., it has been converted to one of those types by a $INT or $REAL proc), then the following parameters apply:

For integer values, $RANGE is most effective for those stored as four-byte values. Remember that for integer values of one or two bytes, some values outside of the normal range (e.g., 0 through 255 for one-byte integers) will be accepted by the $INT proc and converted to values within the range without warning. Note then that $RANGE could not be used to test for these values since conversion to acceptable values has already occurred before the $RANGE proc is executed. This problem only arises for one- and two-byte integers; it is not a problem for four-byte integers.

If you are testing a value converted by $DOLLAR, you must give the range without the decimal point, taking into account the number of decimal places specified by the proc. For instance, if you want to insure that the value is between 0 and $100.00, your rule string might look like this:

Example: $RANGE(1000,9999)

The input value must be a binary value (probably converted by $INT) from 1000 to 9999 inclusive. If it is not, the error flag is set and a serious error occurs.

Example: $RANGE(-1,1,REAL,W)

The input value must be a floating point value (probably converted by $REAL) from -1 to 1 inclusive. If the value exceeds one of these ranges, the error flag is set, the value is converted to the exceeded range (either -1 or 1) and a warning error occurs.

Syntax and Parameters

If the input value is a packed decimal value (i.e., it has previously been converted to packed by a proc such as $PACK or $ADJUST), then the following applies:

            P2 or P3
              -2      allow negative values, including infinity (-@@)
              -1      allow negative values but not infinity
               0      allow 0
               1      allow positive values but not infinity (@@)
               2      allow positive values, including infinity

For more information about packed decimal values in SPIRES, see section 18 of the SPIRES manual "Technical Notes", or EXPLAIN PACKED DECIMALS.

Example: $RANGE(0,2,SIGN,S)

This proc verifies that the input value is a packed decimal ranging from 0 to positive infinity (@@). If the value is not in that range (that is, if it is negative), the error flag is set and a serious error occurs.

Example: $RANGE(0,5,EXP)

This proc verifies that the input value is a packed decimal with an exponent from 0 to 5. If the value has a decimal portion (that is, it has a negative exponent) or if the exponent is larger than 5, the error flag is set and a serious error occurs.

System Proc Expansion

2.7.9  ($REAL)

$REAL(type,error,MSG)

This proc converts an alphanumeric "real" constant to floating-point; the form of the converted value is controlled by the "type" parameter. The error flag is set if the input value contains unrecognizable characters. If a value cannot be converted, the default value is zero. The range of allowed values for a single precision result is:

allowing as many as seven places of accuracy. If a value is below 5.4E-79 but above -5.4E-79, it will be converted to zero (0) without warning, i.e., the error flag will not be set.

The range for double precision values is similar except that more decimal places can be stored.

Syntax and Parameters

System Proc Expansion

2.8.0  ($REAL.OUT)

$REAL.OUT(type,length,frac,error,MSG)

This proc will convert the floating-point number stored by $REAL to a character string. The value will be either in exponential format or in decimal format depending on the value of "length" (see below). The converted value is made up of a possible minus sign, integer portion, decimal point, fractional portion not longer than the length specified in "frac", and a possible exponential portion consisting of the letter E followed by an integer exponent. (If the exponent is negative, it will be preceded by an underscore (_), not a hyphen (-), e.g., 143E_22.) If the converted value is longer than the specified length, the error flag is set and the value not converted.

Syntax and Parameters

System Proc Expansion

2.8.0a  ($REPARSE)

$REPARSE(error)

The $REPARSE proc returns the current search value to SPIRES as a substitute search expression or expressions for the original one. SPIRES thus does no searching in the named index because the index's SEARCHPROC passes the search value back to SPIRES as a new search expression.

The value of $REPARSE is its ability to disguise a search involving multiple indexes, sub-indexes or qualifiers as a simple search issued by the user. For example, if a bibliographic subfile has many users issue author-title searches, such as FIND AUTHOR FERBER AND TITLE SHOW BOAT, the file owner might decide to create a "reparsing index" that allows a user to issue the same search as FIND AT FERBER/SHOW BOAT.

The reparsing index could also be called a "virtual index", since it is not directly connected to index records. Instead, the index's SEARCHPROC rule string contains rules (such as $CHANGE, $INSERT or $CALL) to convert the value such as "FERBER/SHOW BOAT" to "AUTHOR FERBER AND TITLE SHOW BOAT". The final rule in the SEARCHPROC string would be $REPARSE, telling SPIRES to use the converted value as a new search expression or expressions in the search.

Syntax and Parameters

The linkage section for a reparsing index generally looks something like this:

The $NOPASS Passproc tells SPIRES not to pass anything to the named index. [See 2.5.6.] Of course, since $REPARSE will send the search expression to other indexes anyway, that is not a problem. In fact, because the index record-type named is neither searched nor updated, it is not affected by this index linkage section at all -- the value given in the INDEX-NAME statement may be chosen arbitrarily from the list of index record-types for the goal record.

The search value must be converted to a legitimate search expression before the $REPARSE proc is executed. (That operation is presumably done by the PREP.TO.REPARSE Userproc referred to in the example above.) The index(es) named in the new expression may use the $REPARSE proc as well, but this single nesting is all that is allowed.

When $REPARSE returns the new search expression to SPIRES, SPIRES treats the expression as if it were in parentheses. This handling can be significant if the user's command contains multiple search expressions itself. For example, SPIRES treats this command:

as if it were

rather than

which would probably retrieve a different result.

As noted in the description of the "error" parameter, the original search expression may not contain a relational operator other than the equality operator. For example, the command "FIND AT AFTER BUCK/GOOD EARTH" would set the error flag. However, the search expression or expressions returned to SPIRES by $REPARSE may contain any of the relational operators, e.g., "AUTHOR BUCK AND TITLE WORD GOOD AND TITLE WORD EARTH".

But keep in mind that you can keep and then use the relational operator supplied by the user (without an error occurring) if you precede $REPARSE with the $SEARCH.PHRASE proc, using the "relop" parameter.

System Proc Expansion

2.8.1  ($REQUIRED)

$REQUIRED(occ,value,recov,error)

The $REQUIRED proc tests for an exact number of occurrences of the current element. If fewer or more occurrences are input, the error flag is set and a serious error occurs. Alternatively, you can specify that a value be used by default to generate additional occurrences, or if too many occurrences are input, the action specified in "recovery" is taken.

Syntax and Parameters

Example: $REQUIRED(4,,,W)

If fewer than 4 occurrences are input, a null value will be generated enough times to create four occurrences. If more than four are input, they would all be retained. In any case, if there were not four occurrences to begin with, the error flag would be set and a warning error would occur.

Example: $REQUIRED(2)

If more or fewer than two occurrences were input, a serious error would occur and the record would be rejected.

System Proc Definition

2.8.2  ($RESTORE)

$RESTORE(more,error)

This proc allows a value that been stored by $STORE to be restored. The value in the $STORE storage area replaces the current element value.

Syntax and Parameters

$RESTORE and $BREAK (or $WORD or any other form of the A45 action) can appear in the same rule string, but only if no value has been saved when the $BREAK appears; thus, the $BREAK can appear before the $STORE proc or after the $RESTORE proc, but not between them.

Example: $STORE/ ------- /$RESTORE(HOLD)/ ------- /$RESTORE(RELEASE)

The value of the current element is saved in the storage area by the $STORE proc. After some processing to test the value (which may have been changed by the testing), the original value is restored, but the value is saved in the storage area. After more processing, the stored value once again replaces the element value, and the storage area is released.

System Proc Expansion

2.8.2a  ($RSTR)

$RSTR(length,recovery,error)

This proc will test a value to see if it is longer than a specified length. If it is, then by default the value is truncated at the left end, removing that number of characters.

Syntax and Parameters

Example: $RSTR(10)

This proc will truncate any input value longer than ten characters, dropping 10 characters from the left end. If the input value is shorter than ten characters, it becomes a null value. Note that this is the normal form of $RSTR; the second and third parameters are seldom used on this proc.

System Proc Expansion

2.8.2b  ($SEARCH.DATE and $SEARCH.DATE.CC)

$SEARCH.DATE(how,NA,error,MSG,century)

$SEARCH.DATE.CC(century,how,error,MSG)

$SEARCH.DATE and $SEARCH.DATE.CC by default verify that the value supplied is in a standard form for a date (see below) and converts the value to a four-byte hexadecimal string for comparison to stored date index values. A serious error is caused if the value is not in one of the standard date formats, or if the value is not a valid date (e.g., "Feb. 29, 1995" would cause an error; "Feb. 29, 1996" would not).

The two procs are very similar to $DATE(TRUNC) for Searchproc use; the main differences are:

The $SEARCH.DATE and $SEARCH.DATE.CC procs differ in these ways:

Syntax and Parameters

Note that the parameters differ slightly between these two procs; be careful that you specify them in the correct order for the proc you choose.

Example: $SEARCH.DATE(,NA,,,75) or $SEARCH.DATE.CC(75)

This rule would verify that the search value is a valid date, and if it is not, set a Serious error. If the search value is "None" or "N/A", SPIRES will convert it to an internal form that represents "Not Applicable". If the input value has only a two-digit year, if the two digits are 75 or higher, SPIRES will put "19" in front of them; if they are less than 75, SPIRES will put "20" in front of them.

The four-byte hexadecimal string into which the date is converted is in the form #CCYYMMDD# where the first byte, CC is the century, the second, YY, is the year, MM the month, and DD the date. For example, "July 1, 1954" would be translated into the hex string #19540701#, each pair of numbers being the representation of a single hexadecimal character. Note that if the century is not supplied by the user, "19" (or whatever the current century is at the time of input) is assumed, except for metric dates (see example below). Over the next few years, as confusion over the meaning of 2-digit years grows, we recommend you use 4-digit years on input for clarity.

Specific date formats allowed include:

Most combinations of these work as well.

Many relative date forms are also allowed, which express dates in terms of their relation to the current date. Here are some of the forms allowed:

Notice that the value always converts to a specific date, or a specific month and year, or a specific year. A value that would convert to a range of days within a month (such as "last week") will not be recognized, and will set the error flag.

A full description of allowed forms appears in the manual "SPIRES Searching and Updating" -- online, EXPLAIN DATES, FOR INPUT.

System Proc Expansion

2.8.3  ($SEARCH.LOGOP)

$SEARCH.LOGOP(operator)

By default, if no SEARCHPROC rule string is specified, SPIRES supplies the $BREAK proc, meaning that the search value will be broken upon blanks into individual "words"; again by default, the logical operator AND is interpolated between the words. So, for example, the search command FIND TITLE = LASSIES FLEE CIRCUS would be interpreted as FIND TITLE LASSIES AND FLEE AND CIRCUS, assuming no SEARCHPROC at all was coded for the TITLE index.

The $SEARCH.LOGOP proc lets you override the default logical operator AND, replacing it with either OR or AND NOT. However, since coding a SEARCHPROC overrides the default $BREAK, you need to code $BREAK explicitly as part of the SEARCHPROC rule string before you code $SEARCH.LOGOP.

Note that $BREAK must precede $SEARCH.LOGOP, not follow it.

This proc can only be used on simple indexes and not on qualifier, sub-index or compound index terms. The abbreviation $SRC.LOGOP is an allowed but obsolete form of the proc.

Syntax and Parameters

Example: $SEARCH.LOGOP(OR)

All search requests that have multiple values and no specified logical operators would have an implied OR interpolated between the multiple values, presuming this proc follows $BREAK or $WORD (A45). "FIND index-name = value value value" would become "FIND index-name = value OR value OR value".

System Proc Expansion

2.8.3a  ($SEARCH.PHRASE)

$SEARCH.PHRASE(relop)

$SEARCH.PHRASE has two purposes: to override the default Searchproc processing, or to retain the relational operator as part of the search value.

By default, if no SEARCHPROC rule string is specified, SPIRES supplies the $BREAK proc, meaning that the search value will be broken upon blanks into individual "words"; again by default, the logical operator AND is interpolated between the words. So, for example, the search command FIND TITLE = LASSIES FLEE CIRCUS would be interpreted as FIND TITLE LASSIES AND FLEE AND CIRCUS, assuming no SEARCHPROC at all was coded for the TITLE index.

In some circumstances, it is desirable to override the default processing but without having SPIRES do any other processing to the value. That is the first purpose of $SEARCH.PHRASE; it can do nothing at all, but its presence (with no parameters) will override the default $BREAK proc.

The second purpose is to bind non-equality relational operators to the search value that follows it, for simple indexes and goal-indexes. This is often useful, for example, with word indexes that may contain the relational operators that are themselves words, such as HAVING or MASK. Depending on the specified parameter, you can tell SPIRES to treat the search command FIND TITLE HAVING IT ALL as FIND TITLE "HAVING IT ALL" (the way it was probably intended -- few people know or remember that HAVING is a relational operator to SPIRES) rather than as FIND TITLE HAVING "IT ALL".

Syntax and Parameters

       >   >=   <   <=   ~=

Note that you cannot specify the equality operator ("=" or none).

Example: $SEARCH.PHRASE(WORDS.SYMBOLS)

SPIRES will treat any non-equality relational operator that precedes the search value as part of the search value. Here are some examples:

Command                     Interpretation
------------------------    --------------------------
FIND TITLE MASK OF ZORRO    FIND TITLE "MASK OF ZORRO"
FIND DATE >1985             FIND DATE "> 1985"

The last example demonstrates that when the relational operator is "reattached" to the search value, it is always followed by a blank. The operators that are words will be converted to uppercase, unless secure-switch 16 is in effect, which means they will retain the case in which they were input by the user.

In most uses, $SEARCH.PHRASE should appear as one of the first rules in the Searchproc string, so that subsequent rules can act upon the entire value.

System Proc Expansion

2.8.4  ($SEARCH.QUAL)

$SEARCH.QUAL(operator)

This proc supplies a relational operator for compound index or qualifier requests if none has been supplied in the search request. For example, when you are searching a compound index, "FIND index-name value" becomes "FIND index-name relational-operator value" with the relational operator specified in the "operator" parameter (see below). If this proc is not included in the SEARCHPROC of a compound index or qualifier then "index-name value" becomes "index-name = value" in the search request. However, if any other SEARCHPROC were coded, this default action would be overridden and $SEARCH.QUAL would have to be included.

$SEARCH.QUAL is the only proc that can be specified in the SEARCHPROC of a compound index, and it applies to all elements in the index.

The abbreviation $SRC.QUAL is an allowed but obsolete form of the proc.

Syntax and Parameters

Example: $SEARCH.QUAL(GE)

If this example were the SEARCHPROC for a compound index, a search request like FIND DATE 06/16/79 would be equivalent to FIND DATE >= 06/16/79. Other search requests could be made, such as FIND DATE BEFORE 05/04/80, with the logical operator being specified.

System Proc Expansion

2.8.4a  ($SEARCH.ROUTE)

$SEARCH.ROUTE(form-id,'',searchterm,key.index.type,NOCHECK)

This system proc requests indirect search processing of Prism's routing subfile. For details about how this proc would be used in Prism routing applications, see Chapter 6 in the manual "How to Install a Routing Application in Prism". For online help, EXPLAIN $SEARCH.ROUTE. For information about indirect searching in general, see section C.12a in "SPIRES File Definition" or EXPLAIN INDIRECT SEARCHING.

Syntax and Parameters

Example: $SEARCH.ROUTE('RTDEMO/FUND REQUEST','',STATUS,SIMPLE)

A Prism application creates electronic forms with form-id of 'RTDEMO/FUND REQUEST'. The file definition has a simple index of its record keys. SPIRES will take the current search value and use it to search the STATUS index in the Prism routing subfile. The keys that the search retrieves (minus the form-id) will be used to search the index of record keys in your subfile.

System Proc Expansion

2.8.4b  ($SEARCH.SUBF)

$SEARCH.SUBF(subfile,searchterm,option,error)

This system proc requests indirect search processing, a search technique that allows you to connect subfiles via indexes. [The technique is discussed in full in the manual "SPIRES File Definition", section C.12a. For online help, EXPLAIN INDIRECT SEARCHING.]

This proc appears at the end of a SEARCHPROC rule string. It names an index in another subfile that will be used as the indirect index. SPIRES will go to that other subfile, search the indirect index with the current search value, retrieve the keys of goal records that search finds, and use those keys to search the current index. The keys in the current index must thus match the keys in the goal records of the named subfile.

Syntax and Parameters

As the "error" parameter suggests, most of the possible errors are caused by coding problems, which are not necessarily found during compilation. For example, the $SEARCH.SUBF proc must be the final proc in the SEARCHPROC string; otherwise an error will occur.

Remember that the LASTRULE option refers to the SEARCHPROC that is executed when the indirect index is used as a direct index. If you want it to be executed in addition to the current SEARCHPROC string, you should omit the LASTRULE option. If you do not want it to be executed, add the LASTRULE symbol.

Example: $SEARCH.SUBF('TEST SCORES', LETTER.GRADE)

SPIRES will take the current search value and use it to search the LETTER.GRADE index in the TEST SCORES subfile. The keys that that search retrieves will be used to search the current index. Because LASTRULE was not specified, the SEARCHPROC rule string for the LETTER.GRADE index will be executed, if one is defined, to obtain the search value for that index. Note the apostrophes surrounding the subfile name; because it contains a blank, the special character rules needed to be heeded.

System Proc Expansion

2.8.5  ($SEARCH.TRUNC)

$SEARCH.TRUNC(char,how,length,error)

$SEARCH.TRUNC can provide flexible searching by allowing truncated search values. By default, the last character of a search value can be a specified delimiter character, and the search result will contain all values that begin with the characters that precede the delimiter in the search value. Other search methods can be specified with the "how" parameter.

This proc can be used only with simple indexes and qualifiers (but see the "how" parameter description below); it may not be used with sub-index or compound index terms.

The abbreviation $SRC.TRUNC is an allowed but obsolete form of the proc.

Syntax and Parameters

Example: $SEARCH.TRUNC(,,5,S)

This example uses the default method for searching with a pound sign (#) as the delimiter. The search FIND WORD CALCUL# would retrieve the following values: calculate, calculated, calculating, calculation, calculator, calculus. But the search FIND WORD CAL# would not be allowed because it is too short; a serious error would occur.

If you use this proc on a qualifier index term, the default relational operator is PREFIX rather than the equality operator (=). That means that a user command such as AND NOT DATE JUNE 1987 (assuming DATE is a qualifier) would be interpreted as AND NOT DATE PREFIX JUNE 1987, which would drop records with qualifier values of any date in June 1987 from the result. Note that the user can override the default by including a relational operator in the command; the SEARCHPROC can change the default by including the $SEARCH.QUAL proc.

Example: $SEARCH.TRUNC(,SPECIAL,3,S)

This example uses the SPECIAL method for searching with the default delimiter character "#", a minimum length requirement of 4 characters, and a serious error level. For the search "FIND SUBJECT WOMAN#HISTORY", the search result would contain all those values that begin with WOMAN and have HISTORY somewhere in the remainder of the value.

Note that the use of an inequality operator such as < or >= (but not ~=) or a range operator such as BEFORE in the search request will cause SPIRES to ignore the part of the search value from the delimiter character on. In other words, FIND SUBJECT AFTER WOMAN#HISTORY would give the same result as FIND SUBJECT AFTER WOMAN.

Example: $SEARCH.TRUNC(COMMA,MATCH)

This example uses the MATCH type of searching and specifies that any values in the index that begin with the given value and that have a comma immediately following it would be retrieved. The search FIND PLACE PORTLAND would retrieve all values beginning with PORTLAND and having any comma following it, such as "Portland, Oregon" and "Portland, Maine".

System Proc Expansion

2.8.6  ($SHIFT)

$SHIFT(length,how,error)

This proc will rotate the characters in a value a specified number of characters in a specified direction.

Syntax and Parameters

Example: $SHIFT(1)

All characters within the value would be shifted 1 space to the left. The value S2K becomes 2KS; the value S4P becomes 4PS.

System Proc Expansion

2.8.6a  ($SIN)

$SIN(error)

This proc is designed for elements whose values are social insurance numbers (SIN), the Canadian parallel to social security numbers in the U.S. The $SSN proc removes any hyphens or blanks from the incoming value (presumably a social insurance number such as "226-823-846"), tests that resulting value is 9 digits long, and stores the value as a 4-byte fixed binary value. $SIN.OUT should be coded as an Outproc to output the value in the social insurance number format.

Note that the proc does not verify that the hyphens or blanks are in the right place; it does verify that 9 digits remain after removing any hyphens or blanks that may occur.

Syntax and Parameters

System Proc Expansion

2.8.6b  ($SIN.OUT)

$SIN.OUT(error)

This proc is designed for elements whose values are social insurance numbers (SIN), the Canadian parallel to social security numbers in the U.S. It is generally used as an Outproc when the $SIN proc has been used as an Inproc. The $SIN.OUT proc converts a stored binary value to a character string of numerals, and places hyphens after the third and sixth numerals. If the value contains more than 9 digits, conversion still occurs, but a warning message that the value is larger than 9 digits is output. If the value is shorter than 9 digits, it is padded to the left with zeroes.

Syntax and Parameters

System Proc Expansion

2.8.7  ($SORT)

$SORT(how,error)

This proc will sort the multiple occurrences of an element by its values or the multiple occurrences of a structure by the structure's key values (or the values of the first occurrence of the first element in each structure, if the structure does not have a key element). They can be sorted in either ascending or descending order, and non-unique values can be flagged.

Syntax and Parameters

Structures whose keys are varying-length structures themselves are sorted by the length of the key and then by the key's value.

Null occurrences sort to the beginning in ascending order, and to the end in descending order.

Example: $SORT(DESCEND.ERR,W)

This example would sort all the occurrences of an element in descending order. A non-unique value would set the error flag and a warning message would be displayed. All occurrences would be retained.

System Proc Expansion

2.8.8  ($SQU)

$SQU

SQU stands for SQUISH, SQUASH or SQUEEZE. Groups of more than one blank are replaced by a single blank. All leading and trailing blanks are discarded. The result replaces the value.

Syntax and Parameters

There are no parameters, and no errors can occur.

System Proc Expansion

2.8.9  ($SSN)

$SSN(error)

This proc is designed for elements whose values are social security numbers (SSN). The $SSN proc removes any hyphens from the incoming value (presumably a social security number such as "226-32-8936"), tests that the resulting value is 9 digits long and stores the value as a 4-byte fixed binary value. $SSN.OUT should be coded as an OUTPROC to output the value in social security number format.

Note that the proc does not verify that the hyphens are in the proper place; it does verify that 9 digits remain after removing any hyphens that might occur.

Syntax and Parameters

System Proc Expansion

2.9.0  ($SSN.OUT)

$SSN.OUT(error)

The $SSN.OUT proc is generally used as an OUTPROC when the $SSN proc has been used as an INPROC. The $SSN.OUT proc converts a stored binary value to a character string of numerals and places hyphens after the third and fifth numerals. If the value contains more than 9 digits, conversion still occurs, but a warning message is output that the value is larger than 9 digits. If the value is shorter than 9 digits, it is padded to the left with zeroes.

Syntax and Parameters

error (default = W) -- This symbolic parameter specifies the error level for the proc. [See 1.5.1.]

System Proc Expansion

2.9.1  ($STORE)

$STORE

$STORE allows an element value to be stored temporarily so that the value may be converted and tested. Later in the rule string, the original value can be restored with the $RESTORE proc. The storage area is always cleared after each element occurrence is processed.

Syntax and Parameters

There are no parameters and no errors can occur.

$STORE and $BREAK (or $WORD or any other form of the A45 action) can appear in the same rule string, but only if no value has been saved when the $BREAK appears; thus, the $BREAK can appear before the $STORE proc or after the $RESTORE proc, but not between them.

System Proc Definition

2.9.2  ($STRUC)

$STRUC(type,error)

The system procs $STRUC, $STRUC.IN and $STRUC.OUT may be coded as INPROCs and OUTPROCs for elements that are structures. These allow the user adding records to enter the elements of the structure as a single element value, which $STRUC or $STRUC.IN split into the separate elements of the structure. Only single occurrences of each element may be entered using these procs.

During INPROC processing, SPIRES splits the input value for the structure into the separate elements, which are then separately processed by their own INPROCs. For OUTPROC processing, the reverse applies -- the first occurrence of each element in the structure is processed by its own OUTPROC, and then these occurrences are put together in the manner prescribed by $STRUC or $STRUC.OUT. (When processing records through the standard SPIRES format, $STRUC or $STRUC.OUT will not work on output unless $STRUC or $STRUC.IN or the A33 rule has been coded as an INPROC for the structure. An output format may, however, include $STRUC or $STRUC.OUT in an OUTPROC even though no counterpart has been coded for the structure's INPROC.)

The $STRUC.IN and $STRUC.OUT procs allow the structure to have from two to eight elements; each element in the structure is delineated by a separator character, such as a slash (/) or comma. Naturally this character may not appear within any element value; if it did, it would signal the end of that value and the beginning of the next element. Sometimes there is no single character that you can guarantee will not appear in one or another of the element values in the structure.

The $STRUC proc lets you specify your own set of separator characters, which may change from element to element within the structure. In fact, changing from a numeral to an alphabet letter can signal a new element, and the letter itself can be considered part of the value. Other similar capabilities are available if you choose the separators yourself; note, however, that $STRUC.IN and $STRUC.OUT are easier to use if you can use them.

Note that using this proc as an INPROC does not mean that the elements of a structure must be entered this way; it simply allows this form of data entry as an additional convenience. The elements may still be entered separately if desired. (In fact, the $PROMPT system format will always prompt for individual structural element values rather than for the structure itself, even when one of these procs is coded for the structure.)

Syntax and Parameters

Example: $STRUC('J''' ''',J'''-''',X'''\''' ')

This proc specifies that the element is a structure consisting of three elements. If it is an INPROC, the structure may be input as a value such as "Dietrich Fischer-Dieskau", and the value will be separated into the three elements as follows:

The elements within the structure are singly occurring; also, they must be input in the same order in which they are declared in the structure definition.

If this proc is an OUTPROC, the three elements in the structure would be put together and displayed as shown ("Dietrich Fischer-Dieskau") as the value for the structure.

Usually the same $STRUC is used as both INPROC and OUTPROC for an element.

Using $STRUC with other Procs

Assume for this discussion that a "structure value" is comprised of the individual element values separated by the appropriate separator characters specified in the $STRUC, $STRUC.IN or $STRUC.OUT proc. Sometimes file definers want to process the structure value as a single element value before splitting it into its separate elements. In most cases such processing is allowed. For example, you can test the length of the structure value ($TEST.LEN) or verify that the correct separator characters have been used in the proper places.

There are some restrictions, however. Neither $BREAK (A45) nor action A37 can be used in the structure's INPROC. Thus, multiple occurrences of the structure cannot be entered as a single structure value. Also, if $STORE and $RESTORE are used, they must appear before $STRUC (or $STRUC.IN) in the INPROC string, and the storage area must be empty (i.e., RELEASE should be coded for the "more" parameter of $RESTORE) before the $STRUC or $STRUC.IN proc is encountered.

As mentioned earlier, only single occurrences of each element in the structure can be entered using $STRUC or $STRUC.IN. This restriction may not be circumvented by coding $BREAK as an INPROC for any of the elements of the structure; subsequent occurrences of the element following the break character will be discarded.

Similarly, it is also true that coding $BUILD as an OUTPROC for an element in the structure will have no effect when the structure is processed through a $STRUC or $STRUC.OUT proc -- only the first occurrence of the element will be accessed. Though that occurrence will be processed through the element's own OUTPROC string, the $BUILD proc will be ignored. Generally speaking, coding $STRUC or $STRUC.OUT as an OUTPROC when a structure element may be multiply occurring is not recommended since the "extra" occurrences of the element may easily be forgotten (for example, on display in the SPIRES default format) or lost (e.g., on a TRANSFER/UPDATE operation).

System Proc Expansion

2.9.3  ($STRUC.IN)

$STRUC.IN(type,separator,error)

This proc allows the elements of a structure to be input as a single value, with each individual element delimited by a specified character. The elements within the structure do not have to be singly occurring, but only single occurrences of each element may be entered this way.

For example, suppose the structure TRANSACTION were composed of the singly occurring elements DATE, TIME and AMOUNT. Instead of entering the data for an occurrence of the structure like this:

you could enter it like this:

The separator character does not have to be a comma; any character or character string may be chosen. The values will be split up at the separator character, processed through the appropriate INPROCs for the various elements, and stored in the record as separate elements within the structure.

For output, the elements may be displayed as shown in the first example, that is, as separate elements, or they may be "put back together" like the second example, using $STRUC.OUT.

Syntax and Parameters

Warning: No input value should contain reverse slashes ("\") since these are also considered to be separator characters.

As noted in the discussion on the $STRUC proc, the input "structure value" can be processed by other INPROCs before the $STRUC.IN proc, with some restrictions:

Note too that only single occurrences of the individual elements in the structure may be handled by $STRUC.IN. Attempting to circumvent this restriction by coding $BREAK (A45) as part of an element's INPROC string will not be successful -- though that INPROC string will be executed, only the "first occurrence" of the element will be processed and kept; the rest will be discarded.

Example: $STRUC.IN(5)

The input value for this example would be a series of five values, representing five elements, each separated by a comma followed by a blank. They would be stored as single occurrences of the five elements of the structure, in the order in which they are specified in the structure definition.

System Proc Definition

2.9.4  ($STRUC.OUT)

$STRUC.OUT(type,separator,error)

This proc allows the elements of a structure to be output as a single value, each separated by a specified character. It is generally coded only when $STRUC.IN has been coded as an INPROC. In fact, when records are processed with the standard SPIRES format (i.e., no format set), $STRUC.OUT will be ignored on output unless $STRUC.IN or $STRUC or action A33 is coded in the structure's INPROC. An output format may, however, include $STRUC.OUT despite the absence of $STRUC.IN (or the others) from the structure's INPROC.

Though the elements within the structure may be multiply occurring, only the first occurrence of each element will be retrieved by this proc. (Note that this condition could cause "extra" occurrences of the structure's elements to be lost during a TRANSFER/UPDATE operation.)

Syntax and Parameters

Possible values for "separator" are:

Example: $STRUC.OUT(4,-)

This example would output the four elements of a structure as a single value, with each individual element value separated by hyphens.

System Proc Expansion

2.9.6  ($SUBSTR)

$SUBSTR(skip,length,error)

This proc allows you to extract a string from within the input value. The "skip" parameter specifies how many characters should be skipped before the desired substring begins, and the "length" parameter specifies how long the substring is.

Syntax and Parameters

Example: $SUBSTR(2,4,W)

This example would delete the first 2 characters from the value, retain the next 4 characters, and delete the remainder. Values would be modified as follows:

     NA5801-34  would become  5801
     NA57       would become  57
     ARBOREAL   would become  BORE

For all three cases, a warning error would occur.

System Proc Expansion

2.9.7  ($TEST.ACCT)

$TEST.ACCT(what,error,symbol)

As an INPROC or SEARCHPROC, this proc will either verify that the first six characters of the input value fit the rules for an account number, or verify that the first six characters match the current user's account number. If the requested verification fails or if the element value is less than six characters long, the error flag is set. If the value is longer than six characters, the seventh must be a period (but see the details below on using the "*", "." and "$" characters to represent accounts).

As an OUTPROC, this proc functions the same as above, but the account number is not checked if secure-switch 4 has been set in the file definition. Also, if the error flag is set, the action specified by the "what" parameter is taken.

Syntax and Parameters for $TEST.ACCT as INPROC

Syntax and Parameters for $TEST.ACCT as OUTPROC

The abbreviations described above under the SHORT parameter are always valid for input. For example, for values that must be preceded by your account number when $TEST.ACCT processing is taking place (FILE, the key of FILEDEF subfile records is an example), you can replace your account number with a period. That is, instead of typing the key as "gg.uuu.filename", you can type it as ".filename" or "*filename". SPIRES will convert the abbreviation to the full form of your account number before the account-checking described earlier takes place.

Example: $TEST.ACCT(,S)

If used as an OUTPROC, this example would compare the value of the element with the current user's account number. If the values of the first six characters do not match, the error flag is set and a serious error occurs.

System Proc Expansion

2.9.8  ($TEST.ELEM)

$TEST.ELEM(type,relop,element,error)

$TEST.ELEM will compare the occurrences of the current element with those of a second element occurrence by occurrence. Both elements must be at the record level or within the same structure. Depending on the value of the "type" parameter, the elements are compared for length or value. If the two elements differ in the comparison, then the error flag is set, by default causing a serious error. If the number of occurrences for the two elements differ, the comparison is made for the smaller number of occurrences; the additional occurrences of the element with more occurrences are not examined.

Syntax and Parameters

Example: $TEST.ELEM(,,3,W)

This example will compare the occurrences of the current element with those of the fourth element. (Remember that elements are numbered beginning from zero in this situation.) If the occurrences are not of equal length, the error flag will be set and a warning error will occur.

System Proc Expansion

2.9.9  ($TEST.LEN)

$TEST.LEN(what,length)

This proc will include or exclude values depending upon their lengths. Its most common use is as a PASSPROC that keeps short words out of an index. If a value's length is zero or if the length parameter specifies zero, this proc has no effect.

No errors occur with this proc; the value is either included or excluded. If this proc is used in a SEARCHPROC and the search value is excluded, the message -REQUEST HAS NO CONTENT will be displayed.

Syntax and Parameters

Example: $TEST.LEN(IN.GT,5)

In this example, only those values whose lengths are greater than five characters will be accepted. Anything shorter will be rejected.

System Proc Expansion

2.10.0  ($TEST.OCC)

$TEST.OCC(element,type,error)

This INCLOSE rule tests for occurrences of a second element. If the occurrences of the two elements do not match in the specified way (see "type" below), the error flag is set.

Both elements must be at record level, or they must both be in the same exact structure.

Syntax and Parameters

Example: $TEST.OCC(DAY,SAME)

This example will count the number of occurrences of the element DAY. If the current element does not occur the same number of times, the error flag will be set and the record will be rejected.

Example: $TEST.OCC(COUNT,EITHER,W)

This example will test for an occurrence of the element COUNT. If both the current and COUNT elements occur (at least once each), the error flag is set. If neither element occurs, or only one of them occurs, the error flag is NOT set. If the error flag is set, the elements will be accepted, but a warning message will be displayed.

System Proc Expansion

2.10.0b  ($TEST.UNIQUE)

$TEST.UNIQUE(error)

This INCLOSE rule compares all occurrences of the element in the record. If any occurrences are duplicates, the error flag is set.

If the element is a structure, then the key elements of the structural occurrences are compared within the record. If any occurrences are duplicates, the error flag is set.

This proc does not test for uniqueness across multiple records, only across multiple occurrences within a single record.

Syntax and Parameters

Unlike the $SORT proc, which is comparable to this one, $TEST.UNIQUE does not delete the duplicate entries. Moreover, $TEST.UNIQUE does not change the order of the values, as $SORT does.

System Proc Expansion

2.10.1  ($TIME)

$TIME(how,error,MSG)

This proc converts an alphanumeric time value to a 2-byte hex or 4-byte binary (integer) value. The standard forms of time specification are based on a 24-hour clock. The way in which the value is read and stored is determined by the "how" parameter. The time value may not be null; in that case, an error occurs.

The precision of the stored value depends on the size of the converted value. If you choose the 2-byte hex form, the range of values is 0:00:00 to 36:24:30, by 2-second increments. If you choose the 4-byte integer form, the range is 0.000 seconds to 24 days, 20 hours, 31 minutes and 23.647 seconds, by millisecond increments.

The input value may be in several different forms, perhaps using colons, an AM or PM indicator, or words such as "days" or "hours". Details on input forms are described later.

The resultant value is suitable for output processing by $TIME.OUT.

Syntax and Parameters

               TIME = 3:01:26   FORM = Hours:Minutes:Seconds
               TIME = 1:26      FORM = Minutes:Seconds
               TIME = 26        FORM = Seconds
               TIME = 3:01:26   FORM = Hours:Minutes:Seconds
               TIME = 3:01      FORM = Hours:Minutes
               TIME = 3         FORM = Hours
               TIME = 3:01:26   FORM = Hours:Minutes:Seconds
               TIME = 1:26      FORM = Minutes:Seconds
               TIME = 26        FORM = Seconds
               TIME = 3:01:26   FORM = Hours:Minutes:Seconds
               TIME = 3:01      FORM = Hours:Minutes
               TIME = 3         FORM = Hours

As with date processing, SPIRES lets you input time values in many different ways. Here are some rules for guidance:

1) Hours, minutes and seconds of time may be specified in numeric form with colons between the numbers (as the examples above show) or with words to identify each value, with reasonable abbreviations allowed and case irrelevant, e.g.:

2) You may not mix the numeral-colon form with the numeral-word form. For example, the following causes an error: "12 hours, 24:05".

3) A decimal value is allowed on smallest portion of the input value. For example, "12 hours, 5.5 minutes" is allowed; however, "4.3:12.6:19" would cause an error. Remember that non-even seconds will be rounded down to the next lower even number with the 2-byte form; "11.999 seconds" will be rounded to "10 seconds".

4) AM or PM may be added at the end of a time value (in upper, lower or uplow case, with or without periods) as needed. However, the hours value must not exceed "12" or an error will occur; "13:00:00 PM" would not be allowed.

5) NOON or MIDNIGHT, optionally preceded by the number 12 (or 12:00 or 12:00:00) and optionally abbreviated to three characters or more, are allowed values. They may be in upper, lower or mixed case.

6) A "days" option may be added at the beginning of any time value described above. "Days" may be abbreviated. To specify days, you must use the word "days" -- you cannot add another numeric value to the front of the numeral-colon form.

More examples of valid time values for input are shown in the description of $TIME.OUT, where you choose the form in which the time value should be displayed on output.

If you expect to do any computations with the time value, you should choose one of the 4-byte integer forms. It is difficult to do arithmetic with the hex form.

Example: $TIME(HOURS.FIRST)

Element values being input are assumed to begin with the "hours" portion of the time. A value such as "12:30" would be interpreted as 12 hours, 30 minutes or 12:30:00. If the value were null or greater than 36:24:31.999, a serious error would occur. The value will be stored as a 2-byte hex value.

System Proc Expansion

2.10.2  ($TIME.OUT)

$TIME.OUT(form,error)

The 2-byte hex or 4-byte integer value stored by the $TIME proc is converted to a time format for output as a string, the format being determined by the value of the "form" parameter.

Syntax and Parameters

Form         Picture                        Example (4:49:30 p.m.)
----------   ----------------------------   ------------------------
COLON.DHMS   [d Days,] hh:mm:ss[.s]         16:49:30
COLON.DHM    [d Days,] hh:mm[.m]            16:49.5
COLON.DMS    [d Days,] mm:ss[.s]            1009:30
CLOCK.HMS    hh:mm:ss[.s] {AM|PM}           04:49:30 PM
CLOCK.HM     hh:mm[.m] {AM|PM}              04:49.5 PM
CLOCK.H      h[.h] {AM|PM}                  4.825 PM
DHMS         [d Days,] h Hours, m Minutes,  16 Hours, 49 Minutes,
               s[.s] Seconds                  30 Seconds
DHM          [d Days,] h Hours, m[.m]       16 Hours, 49.5 Minutes
               Minutes
DH           [d Days,] h[.h] Hours          16.825 Hours
DAYS         d[.d] Days                     0.70104167 Days
HMS          h Hours, m Minutes,            16 Hours, 49 Minutes,
               s[.s] Seconds                  30 Seconds
HOURS        h[.h] Hours                    16.825 Hours
MS           m Minutes, s[.s] Seconds       1009 Minutes, 30 Seconds
MINUTES      m[.m] Minutes                  1009.5 Minutes
SECONDS      s[.s] Seconds                  60570 Seconds
NONZERO.DHMS - Same as P1=6, but only       16 Hours, 49 Minutes,
                non-zero units appear -       30 Seconds

Below is a chart showing the longest and shortest (non-null) possible values that can be displayed by each form. The length of each appears in parentheses. It is important to realize that SPIRES attempts to maintain the precision of the input value as best it can, but if your input value is always a standard "hh:mm:ss" time, then "Days" and fractional portions of seconds will never be displayed. Thus, the maximum length shown here may not be the maximum length of a value in your particular application.

Form          Longest Value                     Shortest Value
----------    -------------------------------   --------------------
COLON.DHMS    24 Days, 20:31:23.647 (21)        00:00:00 (8)
COLON.DHM     24 Days, 20:31.39412 (20)         00:00 (5)
COLON.DMS     24 Days, 1231:23.647 (20)         00:00 (5)
CLOCK.HMS     11:59:59.999 PM (15)              01:00:00 AM (11)
CLOCK.HM      11:59.99998 PM (14)               01:00 AM (8)
CLOCK.H       11.9999997 PM (13)                1 AM (4)
DHMS          24 Days, 20 Hours, 31 Minutes,    0 Hours, 0 Minutes,
                23.647 Seconds (45)               0 Seconds (29)
DHM           24 Days, 20 Hours, 31.39412       0 Hours, 0 Minutes
                Minutes (35)                      (18)
DH            24 Days, 20.5232353 Hours (25)    0 Hours (7)
DAYS          24.85513479 Days (16)             0 Days (6)
HMS           596 Hours, 31 Minutes, 23.647     0 Hours, 0 Minutes,
                Seconds (37)                      0 Seconds (29)
HOURS         596.5232353 Hours (17)            0 Hours (7)
MS            35791 Minutes, 23.647 Seconds     0 Minutes, 0 Seconds
                (29)                              (20)
MINUTES       35791.39412 Minutes (19)          0 Minutes (9)
SECONDS       2147483.647 Seconds (19)          0 Seconds (9)
NONZERO.DHMS  24 Days, 20 Hours, 31 Minutes,    0 Seconds (9)
                23.647 Seconds (45)

Notes:

System Proc Expansion

2.10.3  ($TRANS and $TRANS.HEX)

$TRANS(input,output,error)

$TRANS.HEX(input,output,error)

Both $TRANS and $TRANS.HEX will translate one character in the input value into another, or will translate any of a group of characters into a single character. If none of the characters is found in the input value, the error flag is set. Only single characters can be translated with this proc; for string replacement, use $CHANGE, $CHANGE.HEX, or $CHANGE.LIST.

If you want to delete characters from an input value (that is, translate them to nulls), use the $TRANS.NULL proc.

Syntax and Parameters

Example: $TRANS(XY,Z)

This example would change all occurrences of X or Y in the input value to Z. If the value did not contain either an X or a Y, the error flag would be set, but since the error level is D, no error processing would occur. Note that case is significant; if the value contained "x", it would not be changed to Y.

Example: $TRANS.HEX(#00#,#40#)

This example would change the hex character #00# to #40#.

System Proc Expansion

2.10.4  ($TRANS.NULL)

$TRANS.NULL(input,trans,error)

This proc will delete all occurrences of one or more characters within the input value by translating them to nulls. It is useful, for instance, when you want to eliminate all punctuation from a value.

Syntax and Parameters

Example: $TRANS.NULL(SPECIAL)

This proc will convert any punctuation in the input value to null, in effect deleting it. An input value such as "LYNNE'S HOUSE OF PANCAKE DUMPLINGS (CLOSED FOR REPAIR)" would be converted to LYNNES HOUSE OF PANCAKE DUMPLINGS CLOSED FOR REPAIR.

System Proc Expansion

2.10.5  ($TRIM)

$TRIM

$TRIM strips all blanks from the right end of the value.

Syntax and Parameters

There are no parameters and no errors can occur.

System Proc Expansion

2.10.5a  ($UNEDIT)

$UNEDIT

This proc removes or translates characters appearing in monetary or numeric values so that they may be properly handled by one of the numeric conversion procs. For example, the value "$1,954" is unacceptable to the numeric conversion procs because of its comma (for $DOLLAR) or because of both its dollar sign and its comma ($INT, $PACK, $REAL and $DECIMAL). The $UNEDIT proc would remove both the comma and the dollar sign, changing the value to "1954".

This proc is commonly used with elements having $EDIT within their OUTPROC strings. Any value processed through $EDIT on output can be translated properly for input by $UNEDIT.

Syntax and Parameters

There are no parameters and no errors can occur.

Specifically, this proc strips all blanks, commas and dollar signs from the value; trailing CR, DB and minus signs are changed to leading minus signs, and trailing plus signs are changed to leading plus signs. Decimal points and exponential notation are not affected. Here are some sample values as processed by $UNEDIT:

System Proc Expansion

2.10.5b  ($UNIQUE.KEY)

$UNIQUE.KEY(character,type,length)

The $UNIQUE.KEY proc, available as an Inproc for key elements, can guarantee that an input value for the key element is unique by adding a special character to the end of it. $UNIQUE.KEY contrasts with the $AUGMENT proc in these ways:

The augmentation is done using letters or numbers, from 1 to 4 characters in length, as you choose.

For example, if the augmentation character is "*", and a two-character numeric augmentation is chosen, then the input value "WRECK*" might be converted to WRECK01 or WRECK02, etc., depending on what values already exist in the record-type. SPIRES will try to add 1 to the highest value it finds. So if the record-type already has WRECK29, then a new WRECK* would become WRECK30.

Syntax and Parameters

Example: $UNIQUE.KEY('#',NUM,3)

Assuming the records would otherwise be added to the subfile successfully, here are some sample keys being input and the results. Remember, augmentation doesn't occur unless the augmentation character "#" ends the value.

The S438 error indicates that all possible values may have been assigned. Though that's not quite true, you can see by the course of the examples above that SPIRES doesn't look for empty places but augments by the value after the highest value for that key.

In most cases users will not supply the augmentation already (as in the example ABCD999 above); instead, the key will end with the augmentation character so that the augmentation will be done automatically and no gaps will occur.

System Proc Expansion

2.10.6  ($UPPER)

$UPPER

This proc converts all lowercase characters to uppercase.

Syntax and Parameters

There are no parameters and no errors can occur.

System Proc Expansion

2.10.7  ($VERIFY)

$VERIFY(type,chars,more,error)

This proc will verify that all characters in the value are or are not from a specified group of characters. The error flag is set if the specified condition is not satisfied. For example, you can insure that all characters in a value are alphabetic.

Syntax and Parameters

Be aware that null values are not tested by the proc -- in other words, a null value will not cause an error. If you do not want to allow null values, include the $MIN.LEN proc, testing for a minimum length of 1 character.

Example: $VERIFY(LIKE,ALPHA)

This example would accept only input values containing only alphabetic characters. If the value "BC3" were input, a serious error would occur.

Example: $VERIFY(UNLIKE,SPECIAL)

This example would accept only those input values that did not contain any blanks or special characters. The value "John's sock" would cause a serious error because of the apostrophe and the blank space.

System Proc Expansion

2.10.7a  ($VERIFY.SUBSTR)

$VERIFY.SUBSTR(column,how,type,list,error)

The $VERIFY.SUBSTR proc is used in either of two ways:

The "type" parameter determines which way the proc will work.

Syntax and Parameters

Syntax and Parameters

When the "type" parameter is STRING, SPIRES will find the specified character position in the input value (according to the "column" parameter) and consider the rest of the value from that point as the substring. SPIRES then compares the substring to each string in the list, through the length of the string in the list, not the substring. That is, the a match may be found if the substring is longer than a string in the list, but not if it is shorter.

For example, if the value is DRAFT and the substring is RAFT and the list of strings includes RAF, then a match is found: RAFT, the substring, is longer than the string in the list. But if the list had RAFTS instead, then no match would be found, because the substring RAFT is shorter than the string in the list.

Example: $VERIFY.SUBSTR(3)

SPIRES will verify that the third character in the value is an uppercase alphabet character. If it is not, a serious error will occur.

Example: $VERIFY.SUBSTR(3,LIKE,CHAR,'.',W)

SPIRES will verify that the third character in the value is a period. If it is not, a warning error will occur.

Example: $VERIFY.SUBSTR(1,LIKE,STRING,'A-, B-, C-')

SPIRES will verify that the value begins with one of the listed strings, "A-", "B-" or "C-". If it does not, a serious error will occur.

System Proc Expansion

2.10.8  ($WINDOW)

$WINDOW(digits,error,MSG,PACK)

"Precision" is a characteristic of packed decimal values that is defined as the number of digits in the value counting from the left-most non-zero digit to the right-most digit, zero or not. For example, the precision of "123" is 3, of "845.231" is 6, and of "007" is 1. This proc lets you limit the amount of precision that a packed decimal value will have, thus setting a maximum for the amount of storage it can take.

The amount of precision determines the amount of space needed to store a packed decimal value. In fact, the number of bytes needed to store a packed decimal is determined by the formula:

with the value of "Bytes" rounded up to an integer if necessary. For example, a value with 5 digits of precision would require (5+3)/2 or 4 bytes for storage. By using $WINDOW, you can limit the stored size of an input value by limiting its precision.

The value input to $WINDOW must be a packed decimal value (see the PACK parameter below). The input value is adjusted to have no more than a certain number of digits of precision, specified by the "digits" parameter. This may mean subtracting precision by removing digits from the end of the value (and rounding appropriately). However, unlike the $PRECISION proc, which otherwise is very similar to it, $WINDOW will never add precision to the value; if the input value has less precision than "digits" specifies, the value is left unchanged. For example, if "digits" is 3 and the value is 17.96, $WINDOW subtracts precision, making the value "18.0" (rounding is applied). On the other hand, if "digits" is 3 and the input value is 17, $WINDOW leaves the value unchanged.

Syntax and Parameters

Example: $WINDOW(5,S,MSG)

This proc would insure that the input packed decimal value had no more than five digits of precision. If the value were not a packed decimal value, the error flag would be set, a serious error would occur, and the error message "Invalid decimal value" would be displayed. Values stored by this proc would be no more than four bytes long.

System Proc Expansion

2.10.9  ($WORD)

$WORD(chars,BREAK.HYPHEN)

The $WORD proc is most often used in the PASSPROC and SEARCHPROC for a word index. In its default form, this proc changes the apostrophe, hyphen and underscore characters to null and changes most other punctuation to blanks. The value is then broken upon blanks, being split into separate occurrences of the element. Thus it would take a sentence such as "If you don't wear your knee-socks, you'll catch a cold!" and convert it to "If you dont wear your kneesocks youll catch a cold". Then it would be broken down into separate words.

Syntax and Parameters

This proc is often used in a PASSPROC in conjunction with $EXCLUDE (with its COMMON.WORDS symbol) and $TEST.LEN as the special processing for word indexes. The input value has extra punctuation and common words removed, is broken into individual words and, if desired, has words shorter than a given length (such as four characters) eliminated as well.

Though it rarely occurs, a warning error can happen when this proc is used as an INPROC or SEARCHPROC. If a search value in a FIND command or a value in a Global FOR WHERE clause is processed through the $WORD proc and if a relational operator other than the equality operator is used, a warning error occurs and only the first word in the value is processed any further.

The $WORD proc should not be used in the SEARCHPROC for a sub-index; it may be used in the SEARCHPROC for the simple index containing the sub-index, but a search command should not try to take advantage of both the word breakup and the sub-index. For example, a command such as "FIND STATE WEST VIRGINIA @ CITY WHEELING" would fail if the STATE value were being broken up on blanks.

System Proc Expansion

2.10.9a  ($XSTR)

$XSTR(length,recovery,error)

This proc will test a value to see if it is longer than a specified length. If it is, then by default the value is truncated at the left end, leaving that number of characters. However, other forms of truncation, allowing you to truncate the value from the right end or to remove that number of characters from the value from either end.

Syntax and Parameters

Example: $XSTR(10,DROP.LAST)

This proc will truncate any input value, dropping 10 characters from the right end. If the input value is shorter than ten characters, it becomes a null value.

System Proc Expansion

2.11.0  ($YESNO)

$YESNO(error,MSG)

$YESNO will accept only values of YES or NO; acceptable variations are YE, Y, OK, and N. Case of the input value is insignificant because the proc converts the value to uppercase prior to testing. Null values are not accepted.

Values are then converted to Y or N for storage in a single byte; they can be processed for output with $YESNO.OUT.

Syntax and Parameters

System Proc Expansion

2.11.1  ($YESNO.OUT)

$YESNO.OUT(error)

$YESNO.OUT converts the values Y and N, probably input with the $YESNO proc, to "Yes" or "No" for output.

Syntax and Parameters

System Proc Expansion

3  Indexes for System Procs

3.1  Action Cross-Reference

The following list indexes the system procs by action number. It can be used to convert action-defined Inprocs, Outprocs, Searchprocs, and Passprocs to the appropriate system proc. If the basic rule string of the system proc includes more than one action, then the proc will be indexed for each action, with the other actions being shown in parentheses. For example, $LENGTH is indexed under both A22 and A23. Actions that only become part of a system proc's rule string when a particular symbol is specified for a parameter are not included in this list.

3.2  System Procs by Function

This index categorizes the system procs by their function and indicates for each proc whether it may be used as an INPROC, OUTPROC, SEARCHPROC, PASSPROC or INCLOSE. Some procs can be used only as SEARCHPROCS or PASSPROCS; these are listed separately near the end of this index.

The one character codes in the column to the left of the system proc name indicate how the proc may be used: I (INPROC), O (OUTPROC), S (SEARCHPROC), P (PASSPROC), or IC (INCLOSE). In the right column is the specific function of the proc.

3.2.1  * string values

System Procs for string values

     I,O,S,P     $ADJUST          Overlay value on right or left end
                                     of field; justification
       O         $BG              Translate characters for banner
                                     character set
       O         $BOLD            Translate characters for bold
                                     character set
     I,O,S       $CAP             Convert lowercase characters to
                                     uppercase
     I,O,S,P     $CHANGE          Change character string to another
                                     string
     I,O,S,P     $CHANGE.HEX      Change character string to another
                                     string
     I,O,S,P     $CHANGE.LIST     Change character strings to other
                                     strings
     I,O,S       $COMPRESS        Compress string values to save
                                     storage space
       O         $DECODE          Convert stored symbol to string
     I,O,S,P     $ENCODE          Verify value in list, convert to
                                     symbol for storage
     I,O,S,P     $EXCLUDE         Discard values in list
     I,O,S       $EXPAND          Reconvert compressed strings for
                                     output
     I,  S       $FIXED.NUM       Test for numeric string of a
                                     specified length
     I,O,S,P     $INCLUDE         Retain only values in list
     I,O,S,P     $INSERT          Insert string before, after or
                                     within value
     I,O,S,P     $INSETL          Overlay value onto left end of
                                     string; left justification
     I,O,S,P     $INSETR          Overlay value onto right end of
                                     string; right justification
       O         $ITALIC          Translate characters for italic
                                     character set
     I,O,S       $LOWER           Convert uppercase characters to
                                     lowercase
     I,O,S,P     $LSTR            Truncate value at given length
     I,O,S       $PARAGRAPH       Handle paragraph numbers, special
                                     numeric codes
           P     $PASS.UPPER      Convert some elements to uppercase
                                     before passing
     I,O,S,P     $PHONETIC        Convert value to phonetic code for
                                     searching
         S       $PHONETIC.SEARCH Convert personal name to phonetic
                                     code for searching
     I,O,S,P     $RSTR            Truncate value from left end
     I,O,S,P     $SHIFT           Rotationally shift characters
                                     within value
     I,O,S,P     $SQU             Squeeze out extra spaces, delete
                                     leading and trailing blanks
     I,O,S,P     $SUBSTR          Extract string from within value
     I,O,S,P     $TRANS           Convert characters to other
                                     characters
     I,O,S,P     $TRANS.HEX       Convert characters to other
                                     characters
     I,O,S,P     $TRANS.NULL      Delete characters from the value
     I,O,S       $TRIM            Strip trailing blanks
     I,O,S       $UPPER           Convert lowercase characters to
                                     uppercase
     I,O,S       $VERIFY          Verify characters in value are a
                                     specific type
     I           $VERIFY.SUBSTR   Verify characters in substring of
                                     value
     I,  S,P     $WORD            Separate value into individual
                                     occurrences at blanks
     I,O,S,P     $XSTR            Truncate value

3.2.2  * binary values

System Procs for binary values

     I,O,S       $AUGMENT         Augment record key to create a
                                     unique value
     I,O,S       $CHECK           Convert numeric string to binary;
                                     verify check digit
       O         $CHECK.OUT       Convert binary to character
                                     string, append check digit
       O         $DECODE          Convert stored symbol to string
     I,  S       $DOLLAR          Convert money value to binary or
                                     floating-point
       O         $DOLLAR.OUT      Convert binary or floating-point
                                     value to money value
       O         $EDIT            Editing packed decimal or binary
                                     value against an edit mask
     I,O,S,P     $ENCODE          Verify value in list, convert to
                                     symbol for storage
     I,  S       $INT             Convert character string to binary
       O         $INT.OUT         Convert binary value to character
                                     string
     I,O,S,P     $LOGICAL         Adjust binary values for proper
                                     indexing
           P     $PASS.LEN        Pass binary length of fetched
                                     element
     I,  S       $RANGE           Test range of binary or floating
                                     point value
     I,  S       $SIN             Validate social insurance numbers
                                     and convert to binary
       O         $SIN.OUT         Convert binary value to social
                                     insurance number
     I,  S       $SSN             Validate social security numbers
                                     and convert to binary
       O         $SSN.OUT         Convert binary value to social
                                     security number
     I,O,S       $VERIFY          Verify characters in value are a
                                     specific type

3.2.3  * floating-point values

System Procs for floating-point values

     I,  S       $DOLLAR          Convert money value to binary or
                                     floating-point
       O         $DOLLAR.OUT      Convert binary or floating-point
                                     value to money value
     I,O,S,P     $LOGICAL         Adjust floating-point values for
                                     proper indexing
     I,  S       $RANGE           Test range of binary or floating
                                     point value
     I,  S       $REAL            Convert string value to
                                     floating-point
       O         $REAL.OUT        Convert floating-point value to
                                     string

3.2.4  * packed decimal values

System Procs for packed decimal values

     I,O,S,P     $ADJUST          Adjust packed decimal value to have
                                     a fixed length
     I,O,S,P     $DECIMAL         Force value to have certain number
                                     of decimal places
     I,O,S,P     $DECIMAL.ADJ     Adjust value to have specified
                                     length for indexing
       O         $DECIMAL.OUT     Convert packed value to string with
                                     a given number of decimal places
       O         $EDIT            Editing packed decimal or binary
                                     value against an edit mask
     I,  S       $PACK            Convert string value to packed
                                     decimal
       O         $PACK.OUT        Convert packed decimal value to
                                     string
     I,  S       $PACK.TEST       Test value (range) of packed decimal
     I,O,S,P     $PRECISION       Specify precision of packed
                                     decimal values
     I,  S       $RANGE           Test characteristics of packed
                                     decimal value
     I,O,S       $UNEDIT          Translate edited values for input
     I,O,S,P     $WINDOW          Limit precision of packed decimal
                                     values

3.2.5  * hexadecimal values

System Procs for hexadecimal values

     I,  S       $HEX             Convert string value to
                                     hexadecimal
       O         $HEX.OUT         Convert hexadecimal value to
                                     string
     I,O,S       $VERIFY          Verify characters in value are a
                                     specific type

3.2.6  * bit values

System Procs for bit values

     I,O,S       $BITS            Convert numbers to bits and vice
                                     versa
     I,O,S,P     $LOGICAL         Manipulate bits in value using
                                     logical operator

3.2.7  * money values

System Procs for money values

     I,  S       $DOLLAR          Convert money value to binary or
                                     floating-point
       O         $DOLLAR.OUT      Convert binary or floating-point
                                     value to money value
       O         $EDIT            Editing packed decimal or binary
                                     value against an edit mask

3.2.8  * date values

System Procs for date values

     I,  S,  IC  $DATE            Verify date value, convert to
                                     hexadecimal
     I,  S       $DATE.IN         Verify date value, convert to
                                     hexadecimal
     I,  S       $DATE.IN.CC      Verify date value, convert to
                                     hexadecimal
       O         $DATE.OUT        Convert hex value to a standard
                                     date format
       O         $DATE.OUT.CC     Convert hex value to a standard
                                     date format
             IC  $GEN.DATE        Generate value using current date
         S       $SEARCH.DATE     Verify date value, convert to
                                     hexadecimal
         S       $SEARCH.DATE.CC  Verify date value, convert to
                                     hexadecimal

3.2.9  * time values

System Procs for time values

             IC  $GEN.TIME        Generate value using current time
     I,  S,  IC  $TIME            Validate time value and convert to
                                     hex or binary
       O         $TIME.OUT        Convert hex or binary value to
                                     standard time format

3.2.10  * personal name values

System Procs for personal name values

     I,O,S,P     $NAME            Convert personal names to standard
                                     format and key style indexing
     I,O,S,P     $PHONETIC        Convert value to phonetic code for
                                     searching
         S       $PHONETIC.SEARCH Convert personal name to phonetic
                                     code for searching
     I,O,S,P     $PNAME           Convert personal names for sub-index
                                     style indexing

3.2.11  * structures

System Procs for structures

       I         $DISCARD         Discard all values, or discard
                                     containing structure
     I,O         $STRUC           Separate value into elements of
                                     structure, or reverse
     I           $STRUC.IN        Separate value into elements of
                                     structure
       O         $STRUC.OUT       Build elements of structure into
                                     single value

3.2.12  * numeric strings

System Procs for paragraph number and numeric string values

     I,  S       $FIXED.NUM       Test for numeric string of a
                                     specified length
     I,O,S       $PARAGRAPH       Handle paragraph numbers, special
                                     numeric codes
     I,  S       $SIN             Validate social insurance numbers
                                     and convert to binary
       O         $SIN.OUT         Convert binary value to social
                                     insurance number
     I,  S       $SSN             Validate social security numbers
                                     and convert to binary
       O         $SSN.OUT         Convert binary value to social
                                     security number

3.2.13  * account values

System Procs for account number values

             IC  $GEN.ACCT        Generate value using logged-on
                                     account number
     I,O,S       $TEST.ACCT       Verify value is in account-number
                                     form; compare value to logged-
                                     on account
     I           $VERIFY.SUBSTR   Verify characters in substring of
                                     value

3.2.14  * yes/no values

System Procs for yes/no values

     I,O,S       $YESNO           Test and convert Yes/No values for
                                     storage
       O         $YESNO.OUT       Convert stored Yes/No values for
                                     output

3.2.15  * multiple occurrences -- break, build

System Procs for multiple occurrences

     I,  S,P     $BREAK           Split value into multiple
                                     occurrences at delimiters
     I,  S,P     $BREAK.HEX       Split value into multiple
                                     occurrences at delimiters
       O         $BUILD           Build value from multiple
                                     occurrences
     I,  S,P     $WORD            Separate value into individual
                                     occurrences at blanks

3.2.16  * value generation

System Procs for value generation

             IC  $CHECK           Generate unique numeric value,
                                     convert to binary, verify
                                     check digits for update
             IC  $DEFAULT         Generate default values
             IC  $DEFAULT.COND    Provide default value depending
                                     on value of another element
             IC  $GEN.ACCT        Generate value using logged-on
                                     account number
             IC  $GEN.DATE        Generate value using current date
             IC  $GEN.TIME        Generate value using current time
             IC  $INT             Generate unique numeric value,
                                     convert to binary
           P     $PASS.DEF        Provide a default value for
                                     passing
             IC  $REQUIRED        Verify exact number of
                                     occurrences, generate default
                                     values

3.2.17  * length testing

System Procs for length testing

     I,  S       $FIXED.NUM       Test for numeric string of a
                                     specified length
     I,  S       $LENGTH          Verify value is a specific length
     I,O,S,P     $MAX.LEN         Verify maximum length of value
     I,  S       $MIN.LEN         Verify minimum length of value
         S,P     $TEST.LEN        Test length, and include or
                                     exclude value based on result

3.2.18  * occurrence testing

System Procs for occurrence testing

             IC  $DEFAULT         Generate default values
             IC  $DEFAULT.COND    Provide default value depending
                                     on value of another element
             IC  $DISCARD         Discard all values, or discard
                                     containing structure
             IC  $MAX.OCC         Verify maximum number of
                                     occurrences
             IC  $MIN.OCC         Verify minimum number of
                                     occurrences
             IC  $OCC             Generate occurrence count of
                                     another element
           P     $PASS.OCC        Pass nothing; or pass the
                                     occurrence number
             IC  $PUTELEM         Test maximum number of
                                     occurrences, move extras to
                                     other element
             IC  $REQUIRED        Verify exact number of
                                     occurrences, generate default
                                     values

3.2.19  * including or excluding values

System Procs for including or excluding values

     I,O,S,P     $CHANGE          Change character string to another
                                     string
     I,O,S,P     $CHANGE.HEX      Change character string to another
                                     string
     I,O,S,P     $CHANGE.LIST     Change character strings to other
                                     strings
       O         $DECODE          Convert stored symbol to string
     I,O,S,P     $ENCODE          Verify value in list, convert to
                                     symbol for storage
     I,O,S,P     $EXCLUDE         Discard values in list
     I,O,S,P     $INCLUDE         Retain only values in list
     I,O,S       $LOOKSUBF        Verify or replace value with value
                                     from another subfile
     I,O,S,P     $LOOKSUBG        Table lookup for value
                                     verification or replacement
     I,O,S       $LOOKSYS         Lookup in system meta-data files
         S,P     $TEST.LEN        Test length, and include or
                                     exclude value based on result
     I,O,S,P     $WORD            Separate value into individual
                                     occurrences at blanks
     I,O,S       $YESNO           Test and convert Yes/No values for
                                     storage
       O         $YESNO.OUT       Convert stored Yes/No values for
                                     output

3.2.20  * value translation

System Procs for value translation

       O         $BG              Translate characters for banner
                                     character set
       O         $BOLD            Translate characters for bold
                                     character set
     I,O,S       $CAP             Convert lowercase characters to
                                     uppercase
     I,O,S       $ENCRYPT         Encrypt values for security
       O         $ITALIC          Translate characters for italic
                                     character set
     I,O,S       $LOWER           Convert uppercase characters to
                                     lowercase
     I,O,S,P     $TRANS           Convert characters to other
                                     characters
     I,O,S,P     $TRANS.HEX       Convert characters to other
                                     characters
     I,O,S,P     $TRANS.NULL      Delete characters from the value
     I,O,S       $UPPER           Convert lowercase characters to
                                     uppercase

3.2.21  * printing translations

System Procs for special printing

       O         $BG              Translate characters for banner
                                     character set
       O         $BOLD            Translate characters for bold
                                     character set
       O         $ITALIC          Translate characters for italic
                                     character set

3.2.22  * PASSPROC only rules

System Procs used only as PASSPROCs

           P     $NOPASS          Prevent element value from being
                                     passed
           P     $PASS            Fetch values of single element for
                                     passing
           P     $PASS.BY         Pass element depending on value of
                                     another element
           P     $PASS.COND       Pass element depending on
                                     occurrence of another element
           P     $PASS.DEF        Provide a default value for
                                     passing
           P     $PASS.ELEM       Pass multiple elements to single
                                     index
           P     $PASS.FIELD      Delete delimited strings from
                                     passed value
           P     $PASS.LCTR       Fetch the locator for passing
           P     $PASS.LEN        Pass binary length of fetched
                                     element
           P     $PASS.OCC        Pass nothing; or pass the
                                     occurrence number
           P     $PASS.UPPER      Convert some elements to uppercase
                                     before passing

3.2.23  * SEARCHPROC only rules

System Procs used only as SEARCHPROCs

         S       $FIND            Retrieve higher or lower value if
                                     requested value not indexed
         S       $GOAL.INDEX      Use goal record-type as index
         S,P     $PHONETIC        Convert value to phonetic code for
                                     searching
         S       $PHONETIC.SEARCH Convert personal name to phonetic
                                     code for searching
         S       $PROXIMITY       Use for proximity searching, finding
                                     words next to or near each other
         S       $REPARSE         Forward search expression(s) to
                                     other index(es)
         S       $SEARCH.DATE     Verify date value, convert to
                                     hexadecimal
         S       $SEARCH.DATE.CC  Verify date value, convert to
                                     hexadecimal
         S       $SEARCH.LOGOP    Change default logical operator in
                                     searching
         S       $SEARCH.PHRASE   Override default search value
                                     processing; keep relational
                                     operator as part of value
         S       $SEARCH.QUAL     Provide default relational
                                     operator for special indexes
         S       $SEARCH.ROUTE    Process indirect searches of Prism
                                     routing files
         S       $SEARCH.SUBF     Process indirect searches
         S       $SEARCH.TRUNC    Allow truncated searching in index

3.2.24  * special purpose rules

System Procs for special purposes

     I,O,S       $AUGMENT         Augment record key to create a
                                     unique value
     I,O,S,P,IC  $CALL            Call a user-defined processing
                                     rule
             IC  $DISCARD         Discard all values, or discard
                                     containing structure
     I,O,S,P     $EVAL            Evaluate user-defined expression
       O         $GETELEM         Concatenate value of another
                                     element to output value
     I,O,S       $MSG             Provide user-defined error
                                     messages for later procs
     I,O,S,P     $NULL            Delete null values on passing;
                                     change value to null
             IC  $PUTELEM         Test maximum number of
                                     occurrences, move extras to
                                     other element
     I           $RESTORE         Restore value from temporary
                                     storage
             IC  $SORT            Sort occurrences of element or
                                     structure
     I           $STORE           Save current value temporarily
             IC  $TEST.ELEM       Compare values with occurrences of
                                     another element
             IC  $TEST.OCC        Test for occurrences of another
                                     element
             IC  $TEST.UNIQUE     Verify uniqueness of occurrences
                                     within the record
             IC  $UNIQUE.KEY      Augment record key to create a
                                     unique value

3.3  Alphabetic Listing of System Procs and their Purposes

This list is included to provide you with a brief listing of all the system procs available. It includes information on how they can be used (as INPROC, OUTPROC, SEARCHPROC, PASSPROC or INCLOSE, indicated by their abbreviations in the left column) and on their purposes.

:

:29  SPIRES Documentation

I. Primers

II. User Language

III. Application Development

IV. Reference Guides (Cards)

V. Prism

VI. SPIRES Aids and Study Materials

VII. Other Related Documents

(The following documents are not SPIRES documents per se, but describe utilities and programs that may be useful in developing SPIRES applications.)

Obtaining Documentation

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.

Updates to SPIRES Manuals

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.


INDEX


$ADJUST PROC   2.0.1
$ASCII.IN PROC   2.0.1a
$ASCII.OUT PROC   2.0.1a
$AUGMENT PROC   2.0.2
$BG PROC   2.0.3
$BITS PROC   2.0.4
$BOLD PROC   2.0.5
$BREAK PROC   2.9.2
              2.9.1
              2.8.3
              2.8.2
              2.7.5
              2.0.6
$BREAK.HEX PROC   2.7.5
                  2.0.6
$BUILD PROC   2.9.2
              2.0.7
$CALL PROC   2.0.8
$CAP PROC   2.0.9
$CHANGE PROC   2.1.0
               2.0.6
$CHANGE.HEX PROC   2.1.0
$CHANGE.LIST PROC   2.1.1
$CHECK PROC   2.1.2
$CHECK.OUT PROC   2.1.3
$COMPRESS PROC   2.1.4
$DATE PROC   2.1.5
$DATE.IN PROC   2.1.5a
$DATE.IN.CC PROC   2.1.5b
$DATE.OUT PROC   2.1.6
$DATE.OUT.CC PROC   2.1.6a
$DATETIME.IN PROC   2.1.7a
$DATETIME.OUT PROC   2.1.7b
$DATEYY PROC   2.1.6b
$DATEYY.OUT PROC   2.1.6c
$DECIMAL PROC   2.1.8
$DECIMAL.ADJ PROC   2.1.8a
$DECIMAL.OUT PROC   2.1.8b
$DECODE PROC   2.2.0
$DEFAULT PROC   2.2.1
$DEFAULT.COND PROC   2.2.1a
$DISCARD PROC   2.2.2
$DOLLAR PROC   2.2.3
$DOLLAR.OUT PROC   2.2.4
$EDIT PROC   2.2.5
$ENCODE PROC   2.2.6
               2.1.0
$ENCRYPT PROC   2.2.7
$EVAL PROC   2.2.7a
$EXCLUDE PROC   2.2.8
$EXPAND PROC   2.2.9
$FIND PROC   2.3.0
$FIXED.NUM PROC   2.3.1
$GEN.ACCT PROC   2.3.2
$GEN.DATE PROC   2.3.3
$GEN.DATETIME PROC   2.3.3a
$GEN.TIME PROC   2.3.4
                 1.2
$GETELEM PROC   2.3.5
$GOAL.INDEX PROC   2.3.5a
$HEX PROC   2.3.6
$HEX.OUT PROC   2.3.7
$INCLUDE PROC   2.3.8
                2.1.0
$INSERT PROC   2.3.9
$INSERT.HEX PROC   2.3.9
$INSETL PROC   2.4.0
$INSETR PROC   2.4.1
$INT PROC   2.4.2
$INT.OUT PROC   2.4.3
$ITALIC PROC   2.4.4
$LENGTH PROC   2.4.5
$LOGICAL PROC   2.4.6
$LOOKSUBF PROC   2.4.6c
$LOOKSUBG PROC   2.4.7
$LOOKSYS PROC   2.4.7a
$LOOKUP PROC   2.4.7
$LOWER PROC   2.4.8
$LSTR PROC   2.4.9
$MAX.LEN PROC   2.5.0
$MAX.OCC PROC   2.5.1
$MIN.LEN PROC   2.5.2
$MIN.OCC PROC   2.5.3
$MSG PROC   2.5.4
$NAME PROC   2.5.5
$NOPASS PROC   2.5.6
$NULL PROC   2.5.7
$OCC PROC   2.5.8
$PACK PROC   2.5.9
$PACK.OUT PROC   2.6.0
$PACK.TEST PROC   2.6.1
$PARAGRAPH PROC   2.6.2
$PASS PROC   2.6.3
$PASS.BY PROC   2.6.4
$PASS.COND PROC   2.6.5
$PASS.DEF PROC   2.6.6
$PASS.ELEM PROC   2.6.7
$PASS.FIELD PROC   2.6.8
$PASS.LCTR PROC   2.6.9
$PASS.LEN PROC   2.7.0
$PASS.OCC PROC   2.7.1
$PASS.PTR PROC   2.6.9
$PASS.UPPER PROC   2.7.2
$PHONETIC PROC   2.7.3
$PHONETIC.SEARCH PROC   2.7.4
                        1.2
$PHONETIC.SRC PROC   2.7.4
$PNAME PROC   2.7.5
$PRECISION PROC   2.7.6
$PROXIMITY PROC   2.7.6a
$PUTELEM PROC   2.7.7
$RANGE PROC   2.7.8
$REAL PROC   2.7.9
$REAL.OUT PROC   2.8.0
$REPARSE PROC   2.8.0a
$REQUIRED PROC   2.8.1
$RESTORE PROC   2.8.2
$RSTR PROC   2.8.2a
$SEARCH.DATE PROC   2.8.2b
$SEARCH.DATE.CC PROC   2.8.2b
$SEARCH.LOGOP PROC   2.8.3
$SEARCH.PHRASE PROC   2.8.3a
$SEARCH.QUAL PROC   2.8.4
$SEARCH.ROUTE PROC   2.8.4a
$SEARCH.SUBF PROC   2.8.4b
$SEARCH.TRUNC PROC   2.8.5
$SHIFT PROC   2.8.6
$SIN PROC   2.8.6a
$SIN.OUT PROC   2.8.6b
$SORT PROC   2.8.7
$SQU PROC   2.8.8
$SRC.LOGOP PROC   2.8.3
$SRC.QUAL PROC   2.8.4
$SRC.ROUTE PROC   2.8.4a
$SRC.TRUNC PROC   2.8.5
$SSN PROC   2.8.9
$SSN.OUT PROC   2.9.0
$STORE PROC   2.9.1
$STRUC PROC   2.9.2
$STRUC.IN PROC   2.9.3
$STRUC.OUT PROC   2.9.4
$SUBF.LOOKUP PROC   2.4.6c
$SUBSTR PROC   2.9.6
$TEST.ACCT PROC   2.9.7
$TEST.ELEM PROC   2.9.8
$TEST.LEN PROC   2.9.9
$TEST.OCC PROC   2.10.0
$TEST.UNIQUE PROC   2.10.0b
$TIME PROC   2.10.1
$TIME.OUT PROC   2.10.2
$TRANS PROC   2.10.3
              2.0.6
$TRANS.HEX PROC   2.10.3
$TRANS.NULL PROC   2.10.4
$TRIM PROC   2.10.5
$TRUNC.SRC PROC   2.8.5
$UNEDIT PROC   2.10.5a
$UNIQUE.KEY PROC   2.10.5b
$UPPER PROC   2.10.6
$VERIFY PROC   2.10.7
$VERIFY.SUBSTR PROC   2.10.7a
$WINDOW PROC   2.10.8
$WORD PROC   2.10.9
             2.9.1
             2.8.2
             2.7.5
             2.0.6
$XSTR PROC   2.10.9a
$YESNO PROC   2.11.0
$YESNO.OUT PROC   2.11.1
ACCOUNT NUMBER VALUES, SYSTEM PROCS FOR   3.2.13
ACCOUNT NUMBER, COMPARISON   2.9.7
ACCOUNT NUMBER, GENERATION   2.3.2
ACCOUNT NUMBER, VERIFICATION   2.9.7
ACTIONS   1.2
          1
ADD SYMBOL IN SYSTEM PROCS   1.5.3
ALPHABETIC CHARACTER TEST   2.10.7a
                            2.10.7
ALPHANUMERIC CHARACTER TEST   2.10.7a
                              2.10.7
APPEND STRING TO VALUE   2.3.9
AUGMENTED KEYS   2.10.5b
                 2.0.2
BG CHARACTER SETS   2.0.3
BINARY CONVERSION   2.8.6b
                    2.8.6a
                    2.9.0
                    2.8.9
                    2.4.3
                    2.4.2
BINARY CONVERSION, WITH CHECK DIGIT   2.1.3
                                      2.1.2
BINARY EDIT MASKS   2.2.5
BINARY RANGE TEST   2.7.8
BINARY VALUES, SYSTEM PROCS FOR   3.2.2
BIT CONVERSION   2.0.4
BIT MANIPULATION   2.4.6
BIT VALUES, SYSTEM PROCS FOR   3.2.6
BLANKS, REMOVE EXTRA   2.8.8
BLANKS, REMOVE TRAILING   2.10.5
BOLD PRINT   2.0.5
BREAK VALUE INTO SEPARATE OCCURRENCES   2.0.6
BUILD VALUE FROM SEPARATE OCCURRENCES   2.0.7
CAPITALIZE   2.0.9
CASE CONVERSION   2.7.2
                  2.4.8
                  2.0.9
CHANGE DEFAULT LOGICAL OPERATOR IN SEARCHING   2.8.3
CHANGE STRING TO ANOTHER STRING   2.1.0
CHANGE STRINGS TO OTHER STRINGS   2.1.1
CHARACTER SETS, BANNER   2.0.3
CHARACTER SETS, MULTIPLE FONT   2.4.4
                                2.0.5
CHECK DIGITS   2.1.3
               2.1.2
COMPRESS STRING VALUES   2.1.4
CONDITIONAL PASSING   2.6.5
CONVERT BINARY TO MONEY OUTPUT   2.2.5
CONVERT BINARY TO MONEY VALUE   2.2.4
CONVERT BINARY TO STRING   2.8.6b
                           2.9.0
                           2.4.3
CONVERT BINARY TO STRING, WITH CHECK DIGIT   2.1.3
CONVERT BINARY TO TIME STRING   2.10.2
CONVERT BITS TO NUMERALS   2.0.4
CONVERT CHARACTERS TO NULL   2.10.4
CONVERT CHARACTERS TO OTHER CHARACTERS   2.10.3
CONVERT COMPRESSED STRING FOR OUTPUT   2.2.9
CONVERT DATE TO HEX   2.1.6b
                      2.8.2b
                      2.1.5b
                      2.1.5a
                      2.1.5
CONVERT DATETIME TO HEX   2.1.7a
CONVERT FLOATING-POINT TO STRING   2.8.0
CONVERT HEX TO DATE STRING   2.1.6c
                             2.1.6a
                             2.1.6
CONVERT HEX TO DATETIME STRING   2.1.7b
CONVERT HEX TO STRING   2.3.7
CONVERT HEX TO TIME STRING   2.10.2
CONVERT MONEY VALUES TO BINARY OR REAL   2.2.3
CONVERT MULTIPLE BLANKS TO SINGLE BLANKS   2.8.8
CONVERT NUMERALS TO BITS   2.0.4
CONVERT PACKED DECIMAL TO MONEY OUTPUT   2.2.5
CONVERT PACKED DECIMAL TO STRING   2.1.8b
                                   2.6.0
CONVERT PERSONAL NAMES FOR INDEXING   2.7.5
CONVERT PERSONAL NAMES TO STANDARD FORMAT   2.7.4
                                            2.5.5
CONVERT REAL TO MONEY VALUE   2.2.4
CONVERT STORED SYMBOL TO STRING   2.2.0
CONVERT STRING TO BINARY   2.8.6a
                           2.8.9
                           2.4.2
CONVERT STRING TO BINARY, WITH CHECK DIGIT   2.1.2
CONVERT STRING TO FLOATING-POINT   2.7.9
CONVERT STRING TO HEX   2.3.6
CONVERT STRING TO LOWERCASE   2.4.8
CONVERT STRING TO PACKED DECIMAL   2.5.9
CONVERT STRING TO PACKED DECIMAL, CONTROL PRECISION   2.7.6
CONVERT STRING TO PACKED DECIMAL, LIMIT PLACES   2.1.8
CONVERT STRING TO PACKED DECIMAL, LIMIT PLACES AND LENGTH   2.1.8a
CONVERT STRING TO PACKED DECIMAL, ROUND VALUE   2.1.8
CONVERT STRING TO SYMBOL FOR STORAGE   2.2.6
CONVERT STRING TO UPPERCASE   2.7.2
                              2.0.9
CONVERT TIME TO BINARY   2.10.1
CONVERT TIME TO HEX   2.10.1
CONVERT VALUE TO NULL   2.5.7
CONVERT VALUE TO PHONETIC CODE FOR SEARCHING   2.7.4
                                               2.7.3
CONVERT YES/NO VALUES FOR OUTPUT   2.11.1
CONVERT YES/NO VALUES FOR STORAGE   2.11.0
CREATE SUBSTRING FROM LEFT PART OF STRING   2.4.9
CREATE SUBSTRING FROM PART OF STRING   2.10.9a
CREATE SUBSTRING FROM RIGHT PART OF STRING   2.8.2a
DATE GENERATION   2.3.3
                  2.1.5
DATE OUTPUT   2.1.6c
              2.1.6a
              2.1.6
DATE TEST AND CONVERSION TO HEX   2.1.6b
                                  2.8.2b
                                  2.1.5b
                                  2.1.5a
                                  2.1.5
DATE VALUES, SYSTEM PROCS FOR   3.2.8
DATETIME CONVERSION TO HEX   2.1.7a
DATETIME GENERATION   2.1.7a
DATETIME GENERATION, INCLOSE   2.3.3a
DATETIME OUTPUT   2.1.7b
DEFAULT VALUE GENERATION   2.8.1
                           2.6.6
                           2.5.3
                           2.2.1
DELETE CHARACTERS   2.10.4
DISCARD ALL VALUES   2.2.2
DISCARD CONTAINING STRUCTURE   2.2.2
DISCARD VALUES IN LIST   2.2.8
DOCUMENTATION, BIBLIOGRAPHY   :29
DOLLAR-CENTS INPUT   2.10.5a
DOLLAR-CENTS OUTPUT   2.2.5
                      2.2.4
DOLLAR-CENTS TEST AND CONVERSION TO BINARY OR REAL   2.2.3
EDIT MASKS   2.10.5a
             2.2.5
ELEMENT PARAMETER, IN SYSTEM PROCS   1.5.4
ELEMENT, COMPARE WITH OCCURRENCES OF ANOTHER   2.9.8
ELEMENT, COUNT OCCURRENCES OF ANOTHER   2.5.8
ELEMENT, RETRIEVE VALUE OF SECOND   2.3.5
ELEMENT, SORT OCCURRENCES OF   2.8.7
ENCRYPT VALUE   2.2.7
ERROR MESSAGES   2.5.4
                 1.5.2
ERROR PARAMETER, IN SYSTEM PROCS   1.5.1
EVALUATE EXPRESSION   2.2.7a
EXCLUDING VALUE, SYSTEM PROCS FOR   3.2.19
EXCLUSION LISTS   2.2.8
EXPONENTIAL NOTATION   2.5.9
EXTRACT STRING FROM WITHIN VALUE   2.9.6
FETCHER PROC   2.6.9
               2.6.7
               2.6.3
FLOATING-POINT CONVERSION   2.8.0
                            2.7.9
FLOATING-POINT RANGE TEST   2.7.8
FLOATING-POINT VALUES, SYSTEM PROCS FOR   3.2.3
FUNCTIONS   1
GENERATE CURRENT ACCOUNT NUMBER   2.3.2
GENERATE CURRENT DATE   2.3.3
                        2.1.5
GENERATE CURRENT DATETIME   2.3.3a
GENERATE CURRENT TIME   2.10.1
                        2.3.4
GENERATE DEFAULT VALUES   2.8.1
                          2.6.6
                          2.5.3
                          2.2.1
GENERATE UNIQUE VALUE   2.4.2
                        2.1.2
HEX VALUES, IN SYSTEM PROC PARAMETERS   1.4
HEXADECIMAL CHARACTER TEST   2.10.7a
                             2.10.7
HEXADECIMAL CONVERSION   2.3.7
                         2.3.6
HEXADECIMAL VALUES, IN SYSTEM PROC PARAMETERS   1.4
HEXADECIMAL VALUES, SYSTEM PROCS FOR   3.2.5
INCLUDING VALUE, SYSTEM PROCS FOR   3.2.19
INCLUSION LIST   2.3.8
                 2.2.6
INDEX INTEGER VALUES   2.4.6
INDEX PACKED DECIMAL VALUES   2.0.1
INDEX REAL NUMBER VALUES   2.4.6
INDIRECT SEARCHING   2.8.4b
                     2.8.4a
INSERT STRING WITHIN VALUE   2.3.9
ITALIC PRINT   2.4.4
JUSTIFICATION OF VALUE WITHIN FIELD   2.4.1
                                      2.4.0
KEY, AUGMENTED   2.10.5b
                 2.0.2
LASER PRINTER   2.4.4
                2.0.5
                2.0.3
LEADING BLANK REMOVAL   2.8.8
LENGTH TEST, EXACT   2.4.5
LENGTH TEST, IN PASSING   2.9.9
LENGTH TEST, IN SEARCHING   2.9.9
LENGTH TEST, MAXIMUM   2.5.0
LENGTH TEST, MINIMUM   2.5.2
LENGTH TEST, NUMERIC STRING   2.3.1
LENGTH TEST, STRING   2.10.9a
                      2.8.2a
                      2.5.2
                      2.5.0
                      2.4.9
                      2.4.5
LENGTH TEST, TRUNCATION   2.10.9a
                          2.8.2a
                          2.4.9
LENGTH TESTING, SYSTEM PROCS FOR   3.2.17
LITERAL PARAMETERS IN SYSTEM PROCS   1.1
LOGICAL OPERATORS, CHANGING DEFAULT IN SEARCHING   2.8.3
MANIPULATE BITS IN VALUE   2.4.6
MONEY VALUES   2.10.5a
               2.2.5
               2.2.4
               2.2.3
MONEY VALUES, SYSTEM PROCS FOR   3.2.7
MSG PARAMETER, IN SYSTEM PROCS   1.5.2
MULTIPLE ELEMENT OCCURRENCES, INTO SINGLE OCCURRENCES   2.0.7
MULTIPLE OCCURRENCES, SYSTEM PROCS FOR   3.2.15
NAME CONVERSION   2.7.4
                  2.5.5
NAME, CONVERSION   2.7.5
NULL VALUES   2.5.7
NUMERIC CHARACTER TEST   2.10.7a
                         2.10.7
NUMERIC CODE HANDLING   2.6.2
                        2.3.1
NUMERIC STRING VALUES, SYSTEM PROCS FOR   3.2.12
NUMERIC VALUE TEST   2.4.2
                     2.3.1
NUMERIC VALUES   2.10.5a
OCCURRENCE TESTING, SYSTEM PROCS FOR   3.2.18
OCCURRENCES TEST, EXACT NUMBER   2.8.1
OCCURRENCES TEST, MAXIMUM   2.7.7
                            2.5.1
OCCURRENCES TEST, MINIMUM   2.5.3
                            2.2.1
OCCURRENCES TEST, OF ANOTHER ELEMENT   2.10.0
OCCURRENCES, COUNT ANOTHER ELEMENT'S   2.5.8
PACKED DECIMAL CONVERSION   2.1.8b
                            2.1.8a
                            2.10.8
                            2.7.6
                            2.6.0
                            2.5.9
                            2.1.8
PACKED DECIMAL EDIT MASKS   2.2.5
PACKED DECIMAL PRECISION   2.10.8
                           2.7.6
PACKED DECIMAL RANGE TEST   2.6.1
PACKED DECIMAL VALUES, SYSTEM PROCS FOR   3.2.4
PARAGRAPH NUMBER HANDLING   2.6.2
PARAGRAPH NUMBER VALUES, SYSTEM PROCS FOR   3.2.12
PASSING, CONDITIONAL   2.6.4
PASSING, CONVERT TO UPPERCASE FOR   2.7.2
PASSING, COUNT OCCURRENCE NUMBERS FOR   2.7.1
PASSING, DELETE DELIMITED STRINGS DURING   2.6.8
PASSING, FETCH ELEMENT FOR   2.6.3
PASSING, FETCH ELEMENTS FOR   2.6.7
PASSING, FETCH LENGTH OF ELEMENT FOR   2.7.0
PASSING, FETCH LOCATOR FOR   2.6.9
PASSING, LENGTH TEST   2.9.9
PASSING, PERSONAL NAMES   2.7.5
PASSING, PREVENT ELEMENT FROM   2.5.6
PASSING, PREVENT NULL VALUES FROM   2.5.7
PASSING, PROVIDE DEFAULT VALUE FOR   2.6.6
PASSING, SUPPRESS   2.7.1
PASSING, WORD INDEXES   2.10.9
PASSPROC SYNTAX   1.3.1
PASSPROCS, SYSTEM PROCS USED ONLY AS   3.2.22
PERSONAL NAME CONVERSION   2.7.5
                           2.7.4
                           2.5.5
PERSONAL NAME VALUES, SYSTEM PROCS FOR   3.2.10
PHONETIC SEARCHING   2.7.4
                     2.7.3
PRECEDE VALUE WITH STRING   2.3.9
PRINTING, SYSTEM PROCS FOR   3.2.21
PROCESSING RULES   1
PROCS   1.2
        1
PROCS, SYSTEM   1
PROCS, USER-DEFINED   1
PROXIMITY SEARCHING   2.7.6a
QUALIFIERS   2.7.1
RANGE TEST, BINARY OR FLOATING POINT   2.7.8
RANGE TEST, PACKED DECIMAL   2.6.1
RELATIONAL OPERATORS   2.8.3a
RELATIONAL OPERATORS, CHANGING DEFAULT   2.8.4
REPLACE VALUE WITH VALUE FROM ANOTHER RECORD-TYPE   2.4.7
REPLACE VALUE WITH VALUE FROM ANOTHER SUBFILE   2.4.6c
RETAIN ONLY VALUES IN LIST   2.3.8
RETRIEVE HIGHER OR LOWER VALUES IN INDEX   2.3.0
RETRIEVE VALUE OF SECOND ELEMENT   2.3.5
ROTATE CHARACTERS IN STRING   2.8.6
SEARCHING, INDIRECT   2.8.4b
                      2.8.4a
SEARCHING, PERSONAL NAME   2.7.5
                           2.7.4
SEARCHING, TRUNCATED   2.8.5
SEARCHPROCS, DEFAULT   2.8.3a
                       2.8.3
SEARCHPROCS, FOR GOAL-INDEX   2.3.5a
SEARCHPROCS, RELATIONAL OPERATORS   2.8.3a
SEARCHPROCS, SYSTEM PROCS USED ONLY AS   3.2.23
SEPARATE VALUE INTO INDIVIDUAL WORDS   2.10.9
SET CRYPT COMMAND   2.2.7
SET TRUE ACCOUNT COMMAND   2.9.7
SHIFT CHARACTERS IN STRING   2.8.6
SINGLE ELEMENT OCCURRENCE, INTO MULTIPLE OCCURRENCES   2.0.6
SOCIAL INSURANCE NUMBERS   2.8.6b
                           2.8.6a
SOCIAL SECURITY NUMBERS   2.9.0
                          2.8.9
SORT ELEMENT OCCURRENCES   2.8.7
SORT STRUCTURE OCCURRENCES   2.8.7
SPECIAL CHARACTER TEST   2.10.7a
                         2.10.7
SPECIAL CHARACTERS IN SYSTEM PROC PARAMETERS   1.4
SPECIAL CHARACTERS RULE SET 1, IN SYSTEM PROCS   1.4.1
SPECIAL CHARACTERS RULE SET 2, IN SYSTEM PROCS   1.4.2
SPECIAL CHARACTERS RULE SET 3, IN SYSTEM PROCS   1.4.3
SQUEEZE EXTRA BLANKS   2.8.8
STANDARD RECORD ENTRY RULES, WITH SYSTEM PROCS   1.4.4
STORAGE SPACE   2.2.0
STORAGE, TEMPORARY ELEMENT   2.9.1
                             2.8.2
STRING INSERTION   2.3.9
STRING OVERLAY   2.4.1
                 2.4.0
STRING VALUES, SYSTEM PROCS FOR   3.2.1
STRUCTURE PROCESSING   2.9.4
                       2.9.3
                       2.9.2
STRUCTURE, SHORT OCCURRENCES OF   2.8.7
STRUCTURE, TREATED AS ELEMENT   2.9.4
                                2.9.3
                                2.9.2
STRUCTURES, SYSTEM PROCS FOR   3.2.11
SUB-INDEXES   2.7.1
SUBTREE PATHS   1.5.4
SUPPORT PROXIMITY SEARCHING   2.7.6a
SYMBOLIC PARAMETERS IN SYSTEM PROCS   1.1
SYSTEM PROCS   1
SYSTEM PROCS AND COMPILATION   1.3
SYSTEM PROCS, ADD SYMBOL   1.5.3
SYSTEM PROCS, COMPLETE LIST OF   3.3
SYSTEM PROCS, ELEMENT PARAMETER   1.5.4
SYSTEM PROCS, ERROR PARAMETER   1.5.1
SYSTEM PROCS, EXPANSION   2
SYSTEM PROCS, FOR ACCOUNT NUMBER VALUES   3.2.13
SYSTEM PROCS, FOR BINARY VALUES   3.2.2
SYSTEM PROCS, FOR BIT VALUES   3.2.6
SYSTEM PROCS, FOR DATE VALUES   3.2.8
SYSTEM PROCS, FOR FLOATING-POINT VALUES   3.2.3
SYSTEM PROCS, FOR HEXADECIMAL VALUES   3.2.5
SYSTEM PROCS, FOR INCLUDING OR EXCLUDING VALUES   3.2.19
SYSTEM PROCS, FOR LENGTH TESTING   3.2.17
SYSTEM PROCS, FOR MONEY VALUES   3.2.7
SYSTEM PROCS, FOR MULTIPLE OCCURRENCES   3.2.15
SYSTEM PROCS, FOR NUMERIC STRING VALUES   3.2.12
SYSTEM PROCS, FOR OCCURRENCE TESTING   3.2.18
SYSTEM PROCS, FOR PACKED DECIMAL VALUES   3.2.4
SYSTEM PROCS, FOR PARAGRAPH NUMBER VALUES   3.2.12
SYSTEM PROCS, FOR PERSONAL NAME VALUES   3.2.10
SYSTEM PROCS, FOR SPECIAL PRINTING   3.2.21
SYSTEM PROCS, FOR SPECIAL PURPOSES   3.2.24
SYSTEM PROCS, FOR STRING VALUES   3.2.1
SYSTEM PROCS, FOR STRUCTURES   3.2.11
SYSTEM PROCS, FOR TIME VALUES   3.2.9
SYSTEM PROCS, FOR VALUE GENERATION   3.2.16
SYSTEM PROCS, FOR VALUE TRANSLATION   3.2.20
SYSTEM PROCS, FOR YES/NO VALUES   3.2.14
SYSTEM PROCS, LITERAL PARAMETERS   1.1
SYSTEM PROCS, MSG PARAMETER   1.5.2
SYSTEM PROCS, RULES   1.1
SYSTEM PROCS, SPECIAL CHARACTER RULES   1.4
SYSTEM PROCS, SPECIAL CHARACTERS RULE SET 1   1.4.1
SYSTEM PROCS, SPECIAL CHARACTERS RULE SET 2   1.4.2
SYSTEM PROCS, SPECIAL CHARACTERS RULE SET 3   1.4.3
SYSTEM PROCS, SYMBOLIC PARAMETERS   1.1
SYSTEM PROCS, SYNTAX   1.1
SYSTEM PROCS, UPD SYMBOL   1.5.3
SYSTEM PROCS, USED ONLY AS PASSPROCS   3.2.22
SYSTEM PROCS, USED ONLY AS SEARCHPROCS   3.2.23
TABLE LOOKUP   2.4.6c
               2.4.7
TIME GENERATION   2.10.1
                  2.3.4
TIME OUTPUT   2.10.2
TIME TEST AND CONVERSION TO BINARY   2.10.1
TIME TEST AND CONVERSION TO HEX   2.10.1
TIME VALUES, SYSTEM PROCS FOR   3.2.9
TRAILING BLANK REMOVAL   2.10.5
                         2.8.8
TRUNCATE VALUE   2.10.9a
TRUNCATE VALUE AT GIVEN LENGTH   2.8.2a
                                 2.4.9
TRUNCATED SEARCHING   2.8.5
UNIQUENESS TEST   2.10.0b
UPD SYMBOL, IN SYSTEM PROCS   1.5.3
USER-DEFINED PROCESSING RULES   2.0.8
USERPROCS   2.0.8
VALUE GENERATION, SYSTEM PROCS FOR   3.2.16
VALUE TRANSLATION, SYSTEM PROCS FOR   3.2.20
VERIFY CHARACTERS ARE A SPECIFIC TYPE   2.10.7
VERIFY CHARACTERS IN SUBSTRING ARE A SPECIFIC TYPE   2.10.7a
VERIFY EXACT LENGTH OF VALUE   2.4.5
VERIFY MAXIMUM LENGTH OF VALUE   2.5.0
VERIFY MAXIMUM NUMBER OF OCCURRENCES   2.7.7
                                       2.5.1
VERIFY MINIMUM LENGTH OF VALUE   2.5.2
VERIFY MINIMUM NUMBER OF OCCURRENCES   2.5.3
VERIFY NUMERIC STRING OF GIVEN LENGTH   2.3.1
VERIFY VALUE IS IN ANOTHER RECORD TYPE   2.4.7
VERIFY VALUE IS IN ANOTHER SUBFILE   2.4.6c
WORD INDEXES   2.10.9
               2.0.6
YES/NO VALUES   2.11.0
                2.11.1
YES/NO VALUES, SYSTEM PROCS FOR   3.2.14