******************************************************************
* *
* Stanford Data Center *
* Stanford University *
* Stanford, Ca. 94305 *
* *
* (c)Copyright 1994 by the Board of Trustees of the *
* Leland Stanford Junior University *
* All rights reserved *
* Printed in the United States of America *
* *
******************************************************************
SPIRES (TM) is a trademark of Stanford University.
This document 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:
Processing Rules and Actions B.4 INPROCs and OUTPROCs B.4 Processing Rule Strings B.4.3 Processing Rule Error Messages B.4.7 INCLOSEs B.4.8 SEARCHPROCs B.8.4, B.8.12 PASSPROCs B.8.4, B.8.9
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.
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.
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:
A30 A44:0,AUTUMN,FALL
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.
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:
$procname(parms) or $procname (parms)
2) Each parameter is separated from the other by a comma and optional blanks.
$procname(parm1,parm2,parm3) $procname (parm1, parm2, parm3)
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:
$INT(length,error,MSG)
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:
$INT(4,S,MSG)
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
$CHANGE(input,output,length,error)
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.
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:
INPROC = A56,'Value not integer from 1 to 100'/ AS21:1/ AS24,100,1;
INPROC = $MSG('Value not integer from 1 to 100')/ $INT(BYTE)/
$RANGE(1,100);
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.
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:
$INT(length,error,MSG)
If by accident we coded BYTE, the value for "length", as the value for "error":
$INT(,BYTE)
we would get error messages from the compiler, as shown below:
-> select filedef -> compile gq.jnk.test * RECORD-NAME = REC01 * * ELEMENT = INTEGER - INPROC error - Invalid action syntax -Unrecognized: ABYTE21:4 - INPROC error - Invalid action syntax -Unrecognized: $INT(,BYTE) -Compile error -Compile terminated ->
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.
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:
[PASSPROC] <MULT-PASS>
<SNGL-PASS>
<SMPL-PASS>
[MULT-PASS] (DEFAULT) <MULT-GET> {MIDDLE} <BREAK>
[SNGL-PASS] (DEFAULT) <SNGL-GET> {LAST}
[SMPL-PASS] <SMPL-GET>
<DEFAULT>
[BREAK] <NAME>
<SPLIT> {LAST}
[LAST] <MIDDLE>
<LAST1>
[NAME] A38
A41
[SPLIT] A45
[LAST1] A52
A164
[DEFAULT] A171
[SMPL-GET] A165
A167:0
A170
[SNGL-GET] A167:1
A167:5
A169
[MULT-GET] A166
A167:2
A167:6
[MIDDLE] A22 | A32 | A36 | A43 | A44 | A46 | A47 | A48
| A55 | A59 | A62 | A69 | A83 | A161 | A162 | A163 | A168
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.
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:
blank line feed comma slash colon semicolon
(#40#) (#25#) , / : ;
apostrophe quotation mark right parenthesis
' " )
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:
A48, 'New Jersey', NJ, 'New York', NY
is easier to code and read than the equivalent system proc:
$CHANGE.LIST('''New Jersey'', NJ, ''New York'', NY')
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:
- Hex values may not be specified.
- Values that do not include special characters may be specified without apostrophes.
- Values with special characters other than an apostrophe must be placed in apostrophes. Note that any record entry rules in regard to quotation marks and semicolons must be observed. [See 1.4.4.] Such rules are applied after these rules.
- Values containing an apostrophe must be placed in apostrophes, and each single apostrophe
within the value must be quadrupled ('''').
Examples for rule set 1:
Value desired How specified in proc ------------- --------------------- abcde abcde abc,de 'abc,de' abc"de 'abc"de' (see Standard Record Entry Rules below) abc'de 'abc''''de' abc'"de 'abc''''"de' (see Standard Record Entry Rules below)
The second set of special-character rules apply to a parameter if both of the following are true:
- the parameter represents a single value (not multiple values separated by commas, as in rule set 3); and
- in the system proc expansion, the parameter representation is not in apostrophes (e.g. &input in $CHANGE.HEX: A&err44:&len,&input,&output).
If both conditions are true, then the following rules apply:
- Hex values may be specified within pound signs (for example, #40#); apostrophes around them are allowed but are not necessary.
- Values that do not include special characters may be input without apostrophes.
- Values with special characters other than apostrophes must be placed within tripled
apostrophes ('''). Note that standard record entry rules in regard to quotation marks and
semicolons must be observed. [See 1.4.4.] Such rules are applied
after these rules.
- Values with an apostrophe must be placed within tripled apostrophes, and the apostrophe
within the value must be quadrupled ('''').
Examples for rule set 2:
Value desired How specified in proc ------------- --------------------- #0102# #0102# abcde abcde abc,de '''abc,de''' abc"de '''abc"de''' (see Standard Record Entry Rules below) abc'de '''abc''''de''' abc"'de '''abc"''''de''' (see Standard Record Entry Rules below)
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.
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:
- Separate the values to be encoded with commas.
- If any of the special characters listed above appear in any given single value, put that value in apostrophes.
- If the special character is an apostrophe, double it.
Then you apply the following system proc rules:
- Double all apostrophes. Hence, the single apostrophes surrounding some of the values must be doubled, and any doubled apostrophes within the values must again be doubled, thus making four apostrophes for each one within a given value.
- Place the entire set of values (the system proc parameter value) in apostrophes.
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:
ab cd;ef gh:jk lm'no pq"rs
First, apply the set of rules for multiple values in an action:
ab, 'cd;ef', 'gh:jk', 'lm''no', 'pq"rs'
Then apply the set of rules for system proc parameters. To begin, double all apostrophes:
ab,''cd;ef'', ''gh:jk'', ''lm''''no'', ''pq"rs''
Then put apostrophes around the entire parameter value:
'ab,''cd;ef'', ''gh:jk'', ''lm''''no'', ''pq"rs'''
Finally you may need to apply the rules for standard format data entry:
INPROC = "$ENCODE('ab, ''cd;ef'', ''gh:jk'', ''lm''''no'', ''pq""rs''')";
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.
- The element must begin with the element name or mnemonic, followed by the value, followed by a semicolon.
- If the value contains a semicolon, the value must be surrounded by quotation marks
("value;value").
- If the value contains a quotation mark, the value must be surrounded by quotation marks and
the quotation mark within the value must be doubled ("value""value").
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.
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.
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:
- D, take the "default recovery" and print no error message. The default recovery is specified in the description of each proc, unless the default is to do nothing at all to the value being processed.
- W, take the default recovery and print a warning message.
- E, reject the element being processed, and print an error message. Note that if a REQUIRED element is rejected on input, the entire record will be rejected.
- S, reject the record and print an error message.
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.
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:
INPROC = $MIN.LEN(5,,S,MSG) / $MAX.LEN(10,,S);
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.
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:
ELEMENT DATE.ADDED; INPROC = $DATE(ADD); OUTPROC = $DATE.OUT; ELEMENT DATE.UPDATED; INPROC = $DATE(UPD); OUTPROC = $DATE.OUT;
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.
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:
ALBUM (key)
NUMBER, RECORD.NUMBER
SELECTION, SEL
TITLE, T
FORM, F
NUMBER, FORM.NUMBER
KEY
COMPOSER, COM
NUMBER, BAND.NUMBER
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:
Alias Subtree Path RECORD.NUMBER NUMBER FORM.NUMBER SELECTION@TITLE@NUMBER BAND.NUMBER SELECTION@NUMBER
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.
This chapter contains the descriptions of the system procs, presented in alphabetical order. Each proc description begins with a standard set of information:
- the name of the proc and its parameters
- its purpose (in ten words or less)
- what type of proc it may be, i.e., INPROC, OUTPROC, PASSPROC, SEARCHPROC or INCLOSE
- which actions comprise it (e.g., A30, A169, etc.)
- the name of any system function that does similar processing
- the name of any complementary processing rules, which usually means an OUTPROC that reverses the procedure if the current proc is an INPROC and vice versa
- the names of any other system procs that seem to be of related interest
- the default error level and error message (if any)
- which sets of special character rules are in effect for the proc parameters
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.
Purpose: Adjust packed decimal value in a fixed-length field
Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC
Action Number: A36
Parallel System Functions: none
Complementary System Procs: none
Related System Procs: $PACKED, $DECIMAL, $DECIMAL.ADJ, $PRECISION
$WINDOW, $INSETR, $INSETL
Error Default: W
Error Message: none
Special Character Rules: "what" = rule set 2
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.
$ADJUST(length,error,how,what)
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.)
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.
$ADJUST(len,err,how,what) -- A&err36:&how,&what,&len
------------------------------------------------------
len Default: "1"
err Default: "W"
how Default: "2"
RIGHT = "2"
LEFT = "3"
what Default: "#00#"
Default: $ADJUST = AW36:2,#00#,1
Purpose: Convert between EBCDIC and ASCII Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A57:2 and A58:2 Parallel System Function: none Complementary System Procs: none Related System Procs: $ASCII Error Default: D Error Message: none
$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.
$ASCII.IN -- A57:2 $ASCII.OUT -- A58:2
Purpose: Augment record key to create a unique value Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A35 Parallel System Function: none Complementary System Procs: none Related System Procs: $UNIQUE.KEY Error Default: S Error Message: none Special Character Rules: "character" = rule set 1
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.
$AUGMENT(character,how,error)
- BLANK -- If the word BLANK is coded, the separator character will be a blank.
- COMMA -- If the word COMMA is coded, the separator character will be a comma.
- SLASH -- If the word SLASH is coded, the separator character will be a slash (/).
- BYTE or 1 -- creates one-byte augmentation
- HALF or 0 (default) -- creates two-byte augmentation
- 3 -- creates three-byte augmentation
$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.
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.
$AUGMENT -- A&err35:&how,'&char'
----------------------------------
char Default: "#"
BLANK = " "
COMMA = ","
SLASH = "/"
how Default: "0"
BYTE = "1"
HALF = "0"
err Default: "S"
Default: $AUGMENT = AS35:0,'#'
Purpose: Translate characters for banner character set BG10 or BG12 Used as: OUTPROC Action Number: A30, A48 Parallel System Functions: none Complementary System Procs: none Related System Procs: $BOLD, $ITALIC Error Default: none Error Message: none Special Character Rules: not applicable
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.
$BG -- A30/ A48, A,#C181#, B,#C282#, C,#C383#, D,#C484#, E,#C585#,
F,#C686#, G,#C787#, H,#C888#, I,#C989#, J,#D191#, K,#D292#,
L,#D393#, M,#D494#, N,#D595#, O,#D696#, P,#D797#, Q,#D898#,
R,#D999#, S,#E2A2#, T,#E3A3#, U,#E4A4#, V,#E5A5#, W,#E6A6#,
X,#E7A7#, Y,#E8A8#, Z,#E9A9#, 0,#F0B0#, 1,#F1B1#, 2,#F2B2#,
3,#F3B3#, 4,#F4B4#, 5,#F5B5#, 6,#F6B6#, 7,#F7B7#, 8,#F8B8#,
9,#F9B9#, ' ',#4040#, '^',#4A9C#, '+',#4EA1#, '&',#5079#,
'$',#5B9D#, '*',#5C8D#, '-',#60A0#, '/',#6171#, '%',#6C8E#,
'?',#6FDC#, '<',#4C8C#, '>',#6EAE#, '#',#7BDD#, '@',#7C9E#,
'~',#5F8F#, '=',#7EBE#, '_','__', #BF#,#BFBF#
Purpose: Convert numbers to bits and vice versa Used as: INPROC, OUTPROC, SEARCHPROC Action number: A50 Parallel System Function: none Complementary System Procs: none Related System Procs: none Error Default: S Error Message: Invalid characters or value too large Special Character Rules: not applicable
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".
$BITS(length,PAD,error,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.
$BITS(len,PAD,err,MSG) -- &msg A&err50:&pad,&len
--------------------------------------------------
len Default: "1"
pad Default: "0"
PAD = "1"
err Default: "S"
msg Default: ""
MSG = "A56,'Value too long'/"
Default: $BITS = AS50:0,1
Purpose: Translate characters for bold character set Used as: OUTPROC Action Number: A43 Parallel System Functions: none Complementary System Procs: none Related System Procs: $ITALIC, $BG Error Default: none Error Message: none Special Character Rules: not applicable
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.
$BOLD -- A43,ABCDEFGHIJKLMNOPQRSTUVWXYZ,
#4142434445464748495152535455565758596263646566676869#/
A43,abcdefghijklmnopqrstuvwxyz,
#8A9AAABACACBCDCECFDADBDCDDDEDFEAEBECEDEEEFFAFBFCFDFE#/
A43,'0123456789?!$&',#70717273747576777879E190C080#/
A43,#4A#,#D0#
Purpose: Split value into multiple occurrences at delimiters
Used as: INPROC, PASSPROC, SEARCHPROC
Action number: A45
Parallel System Function: $BREAK
Complementary System Procs: $BUILD
Related System Procs: $WORD
Error Default: D
Error Message: none
Special Character Rules: "character" in $BREAK - rule set 1
"character" in $BREAK.HEX - set 2
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.
$BREAK(character,error) $BREAK.HEX(character,error)
- character -- any single character. [See 1.4.1, 1.4.2 for rules for handling special characters. If you are using $BREAK, refer to the first set of rules; if you are using $BREAK.HEX, refer to the second set.] If the character is a hex character, such as #01#, it may be specified only in $BREAK.HEX. Values for some special characters are shown below.
- BLANK (default) -- If the word BLANK is coded, the value will be broken on blanks.
- COMMA -- If this word is coded, the value will be broken on any commas within it.
- SLASH -- If this word is coded, the value will be broken on any slashes within it.
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:
-> find state north dakota @ city bismarck
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.
The value will be broken into separate occurrences of the element at each period (hex 4B) character within the value.
$BREAK(char,err) -- A&err45,'&char'
-------------------------------------
char Default: " "
BLANK = " "
COMMA = ","
SLASH = "/"
err Default: "D"
Default: $BREAK = A45,' '
$BREAK.HEX(char,err) -- A&err45,&char
---------------------------------------
char Default: ""
BLANK = ""
COMMA = "','"
SLASH = "'/'"
err Default: "D"
Default: $BREAK.HEX = A45,
Purpose: Build value from multiple occurrences Used as: OUTPROC Action Number: A82 Parallel System Functions: none Complementary System Procs: $BREAK, $BREAK.HEX Related System Procs: none Error Default: none Error Message: none Special Character Rules: "character" = rule set 1
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.
$BUILD(character)
- character -- any character or characters. Unlike $BREAK and $BREAK.HEX, this value may be longer than one character. Hexadecimal characters, such as #01#, may not be specified in this proc; use A82 directly instead. If the value is a special character or contains one, see set 1 of the special character rules. [See 1.4.1.] Some values representing special characters are described below.
- BLANK (default) -- If the word BLANK is coded, a blank will be inserted between the values.
- COMMA -- If this word is coded, a comma and a blank will be inserted.
- SLASH -- If this word is coded, slashes will be inserted.
Note that the $BUILD proc has no effect under partial processing.
The formats Entry-Uproc SET BUILDSEP overrides the $BUILD proc.
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.
$BUILD(char) -- A82,'&char'
-----------------------------
char Default: " "
BLANK = " "
COMMA = ", "
SLASH = "/"
Default: $BUILD = A82,' '
Purpose: Call a user-defined processing rule Used as: INPROC, INCLOSE, OUTPROC, SEARCHPROC, PASSPROC Action Number: A62, A124 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: D Error Message: none Special Character Rules: not applicable
This proc calls a user-defined processing rule (Userproc). See the manual "SPIRES File Definition" for information on Userprocs or EXPLAIN USERPROCS.
$CALL(name,type,p1,error)
- NORMAL (default) -- for an Inproc, Outproc, Searchproc or Passproc.
- INCLOSE or CLOSEOUT -- for an Inclose.
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.
$CALL(name,type,p1,err) -- A&err&type:&p1,&name
-------------------------------------------------
name Default: ""
type Default: "62"
NORMAL = "62"
INCLOSE = "124"
CLOSEOUT = "124"
p1 Default: "0"
err Default: ""
Default: $CALL = A62:0,
Purpose: Capitalize words or entire value Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A30 Parallel System Functions: $CAP, $CASE Complementary System Procs: $LOWER Related System Procs: $UPPER Error Default: none Error Message: none Special Character Rules: not applicable
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.
$CAP(cap)
- FIRST.WORD -- Only the first letter of the first word in the value should be capitalized.
- EACH.WORD -- The first character in each word in the value should be capitalized.
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.
Here are some sample values as they would be processed by this proc:
Input Output spires files Spires Files SPIRES files SPIRES Files leland's place Leland's Place o'toole's place O'toole's Place
$CAP(cap) -- A30:&cap
-----------------------
cap Default: "0"
FIRST.WORD = "4"
EACH.WORD = "2"
Default: $CAP = A30:0
Purpose: Change character string to another string
Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC
Action Number: A44
Parallel System Functions: $CHANGE
Complementary System Procs: none
Related System Procs: $CHANGE.LIST
Error Default: D
Error Message: none
Special Character Rules: "input","output" in $CHANGE = rule set 1
"input","output" in $CHANGE.HEX = rule set 2
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.
$CHANGE(input,output,EXACT,error) $CHANGE.HEX(input,output,EXACT,error)
- BLANK -- If this value is coded, a blank will be used as the value of "input".
- COMMA -- If this value is coded, a comma will be used as the value of "input".
- SLASH -- If this value is coded, a slash (/) will be used as the value of "input".
- NULL -- If this value is coded, a null value will be used as the value of
"output", meaning that "input" will be deleted, i.e., changed to
null. This value is the default for $CHANGE.HEX; coding two apostrophes ('') for
"output" is equivalent and may be used in either proc.
- BLANK -- If this value is coded, a blank will be used as the value of "output".
- COMMA -- If this value is coded, a comma will be used as the value of "output".
- SLASH -- If this value is coded, a slash (/) will be used as the value of "output".
$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.
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.
If the input value contains the hex character FF, it will be changed to a blank.
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.
$CHANGE(input,output,EXACT,err) -- A&err44:&exact,'&input','&output'
----------------------------------------------------------------------
input Default: ","
BLANK = " "
COMMA = ","
SLASH = "/"
output Default: " "
NULL = ""
BLANK = " "
COMMA = ","
SLASH = "/"
exact Default: "0"
EXACT = "8"
err Default: ""
Default: $CHANGE = A44:0,',',' '
$CHANGE.HEX(input,output,EXACT,err) -- A&err44:&exact,&input,&output
----------------------------------------------------------------------
input Default: "' '"
BLANK = "' '"
COMMA = "','"
SLASH = "'/'"
output Default: ""
NULL = ""
BLANK = "' '"
COMMA = "','"
SLASH = "'/'"
exact Default: "0"
EXACT = "8"
err Default: ""
Default: $CHANGE.HEX = A44:0,' ',
Purpose: Change character strings to other strings Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC Action Number: A48 Parallel System Functions: none Complementary System Procs: none Related System Procs: $CHANGE, $CHANGE.HEX Error Default: D Error Message: none Special Character Rules: "values" = rule set 3
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.
$CHANGE.LIST(values,EXACT,error)
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.
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.
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.
$CHANGE.LIST(value,EXACT,err) -- A&err48:&exact,&value
--------------------------------------------------------
value Default: ""
exact Default: "0"
EXACT = "8"
err Default: ""
Default: $CHANGE.LIST = A48:0,
Purpose: Convert numeric string to binary; verify check digit Used as: INPROC, OUTPROC, SEARCHPROC, INCLOSE Action Number: A27 Parallel System Functions: none Complementary System Procs: $CHECK.OUT Related System Procs: $INT Error Default: S Error Message: Invalid integer or check digit value Special Character Rules: not applicable
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.)
$CHECK(length,error,MSG,other)
- value -- a number, such as 1, 2, or 4, representing the length of the converted value in bytes. Coding "1" is equivalent to coding BYTE (see below); "2" is equivalent to HALF; "4" is equivalent to FULL or INT.
- BYTE -- The value is converted to a one-byte value. The value being input can be from 0 to 255. Certain values outside that range can be entered and will be converted without warning to a number from 0 to 255.
- HALF -- The value is converted to a two-byte ("half-word") binary value. The
minimum value that can be stored is -32768; the maximum value is 32767. As above, some
numbers outside this range will be accepted on input and converted without warning to a
number within the range.
- FULL or INT -- The value is converted to a four-byte binary value. The minimum and maximum values that can be stored are -2,147,483,647 and 2,147,483,647 respectively.
- VERIFY -- This parameter value requests that the input value be verified to be an integer value with the correct check digit but not be converted. If it is not an integer value, an error is caused.
- SS -- SPIRES will use the student services rule rather than the default mod-11 rule in determining the check digit. When SS is coded as an INPROC, it should also be coded in the parallel OUTPROC as well.
- LEN -- SPIRES will use the extended student services rule rather than the default mod-11 rule in determining the check digit. When LEN is coded as an INPROC, it should also be coded in the parallel OUTPROC as well. (See details below.)
- LUHN -- SPIRES will use the Luhn formula for computing mod-10 check digits. When LUHN is coded in an INPROC, it should also be coded in the parallel OUTPROC as well.
- ABA -- SPIRES will use the ABA formula for computing mod-10 check digits. When ABA is coded in an INPROC, it should also be coded in the parallel OUTPROC as well. Note well: If you need to use the ABA formula when a 1-byte value will be stored, you should enter a "5" for the value of "other" instead of ABA.
- UNIQUE (INCLOSE only) -- SPIRES will use the default mod-11 rule in determining the check digit. In addition, if no value or a null value is provided for the element, SPIRES will generate a unique numeric value. (This is very similar to how SPIRES handles slot keys, but here the element does not have to be the record key.) The error flag is set if the record is not being added (i.e., UPDATE or MERGE) and the element has no value. In other words, a unique value is only generated when records are being added; a record being updated should already have a value for the element, and if they do not, the error flag is set. In a sense, this value is similar to an ADD symbol. [See 1.5.3.]
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.,
-? set compxeq public protocols <-- if not already set -? ..check.digit : NUMBER? 1 * 19 : NUMBER? <-- RETURN is pressed -?
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.
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.
$CHECK(len,err,MSG,other) -- &msg A&err27:&len+&other
-------------------------------------------------------
len Default: "4"
VERIFY = "0"
BYTE = "1"
HALF = "2"
FULL = "4"
INT = "4"
err Default: "S"
msg Default: ""
MSG = "A56,'Invalid integer or check digit value'/"
other Default: "0"
SS = "8"
LEN = "16"
UNIQUE = "0/ A&err125"
LUHN = "24"
ABA = "3"
Default: $CHECK = AS27:4
Purpose: Convert binary to character string, append check digit Used as: OUTPROC Action Number: A77 Parallel System Functions: none Complementary System Procs: $CHECK Related System Procs: $INT.OUT Error Default: W Error Message: Value too long Special Character Rules: not applicable
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.
$CHECK.OUT(length,PAD,error,MSG,other)
- SS -- The "student services" rule for determining the check digit is used, rather than the "MOD-11" rule that is the default.
- LEN -- The "extended student services" rule is used. In general, if LEN is coded, PAD should be coded too (see details below).
- LUHN -- The Luhn method of determining a check digit is used.
- ABA -- The ABA method of check-digit generation is used.
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.
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.
$CHECK.OUT(len,PAD,err,MSG,other) -- &msg A&err77:&other+&pad,
&len
----------------------------------------------------------------
len Default: "15"
pad Default: "0"
PAD = "1"
err Default: "W"
msg Default: ""
MSG = "A56,'Value too long'/"
other Default: "0"
SS = "8"
LEN = "4"
LUHN = "12"
ABA = "2"
Default: $CHECK.OUT = AW77:0,15
Purpose: Compress string values to save storage space Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A40, A57 Parallel System Functions: none Complementary System Procs: $EXPAND Related System Procs: $SQU Error Default: S Error Message: none Special Character Rules: not applicable
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).
$COMPRESS(how,error)
- ALPHA -- Only alphabetic characters, blanks, hyphens, commas or apostrophes are retained. Numbers and other special characters are translated to asterisks. This results in a reduction of 8 to 5.
- NUMERIC (default) -- Any character, punctuation or number is translated. This results in a reduction of 8 to 6.
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).
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.
$COMPRESS(how,err) -- A40/ A&err57:&how
-----------------------------------------
how Default: "1"
ALPHA = "0"
NUMERIC = "1"
err Default: "S"
Default: $COMPRESS = A40/ AS57:1
Purpose: Verify date value, convert to hexadecimal Used as: INPROC, SEARCHPROC, INCLOSE Action numbers: A31, A14, A126 Parallel System Function: $DATEIN Complementary System Procs: $DATE.OUT Related System Procs: $GEN.DATE Error Default: S Error Message: Invalid date Special Character Rules: not applicable
$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.
$DATE(how,NA,error,MSG)
- CONVERT (default) -- This value causes SPIRES to verify that the value is a real date and convert it to the hexadecimal form. The error flag is set if the value is not a valid date.
- VERIFY -- This value causes the action to verify that the value is a valid date but not to convert it. If the test fails, the error flag is set.
- EXACT -- This value is like CONVERT; however, additionally, the input value must resolve into a full date that has a day, month and year. So an input value like "3/1" would set the error flag when EXACT is in effect; the value "3/1" would be interpreted as "March 1901" with CONVERT or VERIFY.
- ADD (INCLOSE only) -- This value causes SPIRES to supply the current date for the value if no value is otherwise provided and then to convert it for storage. It is generally used to provide a value for an element representing the date the record was added. [See 1.5.3.]
- UPD (INCLOSE only) -- This parameter value causes SPIRES to discard any supplied value for the element, supply the current date, and convert it for storage. It is generally used to provide the date a record was last updated. [See 1.5.3.]
- TRUNC (SEARCHPROC only) -- This value allows truncated searching of date indexes. "July 1, 1954" would be retrieved by FIND DATE 1954 or FIND DATE JULY 1954. This value is available for simple indexes and qualifiers only.
- ACCO