****************************************************************** * * * 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.
- ACCOUNTING -- This value is the same as CONVERT, but in addition allows the dates "August 32", "August 33" and "August 34" in any given year.
- ACCTG.EXACT -- This value is a combination of ACCOUNTING and EXACT.
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.
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:
7/1/1954 7/1/54 07/01/54 Thursday, July 1, 1954 Thursday, 1 July 1954 1-7-54 ("Canadian" dates) 1954.7.1 ("metric" dates) The 1st of July in '54 1st day of 7/54 (All of the above would be converted into #19540701#.) July 1954 7/54 7/--/54 (The above three samples would be converted into #19540700#.) 1954 54 (The above two samples would be converted into #19540000#.)
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:
today tomorrow yesterday +5 <- five days from today -3 <- three days ago Monday of this week Friday of last week Sunday of next week 10th of last month last day of this month January 1 of last year 7th of this month +6 <- 7th day of the 6th month from this one September of next year next month this year
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.
$DATE(how,NA,err,MSG) -- &msg &na A&err31:&how ------------------------------------------------ how Default: "0" CONVERT = "0" VERIFY = "1" EXACT = "4" ACCOUNTING = "2" ACCTG.EXACT = "6" ADD = "0/ A126:2" UPD = "0/ A126:3" TRUNC = "0/ A44,#0000#,#00#/ A14,#00#" na Default: "" NA = "A40/ A30/ A48:8,'N/A','NA', 'NONE','NA', 'NA','09/09/9999'/" err Default: "S" msg Default: "" MSG = "A56,'Invalid date'/" Default: $DATE = AS31:0
Purpose: Verify date value, convert to hexadecimal Used as: INPROC, SEARCHPROC Action numbers: A70 Parallel System Function: $DATEIN Complementary System Procs: $DATE.OUT, $DATE.OUT.CC Related System Procs: $DATE, $DATE.IN.CC, $GEN.DATE, $SEARCH.DATE, $SEARCH.DATE.CC Error Default: S Error Message: Invalid date Special Character Rules: not applicable
$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:
- $DATE can automatically generate the current date for "date added" and "date updated" elements as an Inclose rule;
- $DATE with its TRUNC parm provides truncated searching of date indexes, so that FIND DATE 1954 would find all dates with a 1954 year;
- $DATE.IN and $DATE.IN.CC can handle turn-of-the-century issues that $DATE cannot (See the century parameter below.)
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:
- Their parms are in a different order. If you want to add century-handling features to a plain $DATE proc, $DATE.IN.CC is easier to use. But if you have options coded on $DATE (other than ADD, UPD or TRUNC; see above discussion), you may prefer to use $DATE.IN.
- $DATE.IN.CC incorporates NA (Not Applicable) handling into the proc; it is not requested through a separate parameter as it is on $DATE and $DATE.IN.
- The two procs differ in their default handling of 2-character years for input: $DATE.IN will assume the current century is meant, while $DATE.IN.CC will set the error flag if the year is not entered as a 4-character value. But both can be changed.
$DATE.IN(how,NA,error,MSG,century)
- 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.
- ACCOUNTING -- This value is the same as CONVERT, but in addition allows the dates "August 32", "August 33" and "August 34" in any given year.
- ACCTG.EXACT -- This value is a combination of ACCOUNTING and EXACT.
- an integer from 1 to 99 -- SPIRES will supply "20" as the century if the two-digit year in the input value is less than this integer, but will supply "19" if it is greater than or equal to this integer. For example, if the integer is 50, then the input date "2/14/95" would be interpreted as a 1995 date, but "2/14/02" would be interpreted as a 2002 date.
- the integer "0" (the default) -- SPIRES will supply the current century at input time for the century portion of the year.
- CCYY -- If this literal value is coded, SPIRES will set the error flag if the input value does not contain a four-digit year; in other words, a value like "12/31/99" would cause an error, but "12/31/1999" would not.
- CC19 -- If this literal value is coded, SPIRES will always supply "19" as the century for two-digit years, even into the next century.
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:
7/1/1954 7/1/54 07/01/54 Thursday, July 1, 1954 Thursday, 1 July 1954 1-7-54 ("Canadian" dates) 1954.7.1 ("metric" dates) The 1st of July in '54 1st day of 7/54 (All of the above would be converted into #19540701#.) July 1954 7/54 7/--/54 (The above three samples would be converted into #19540700#.) 1954 54 (The above two samples would be converted into #19540000#.)
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:
today tomorrow yesterday +5 <- five days from today -3 <- three days ago Monday of this week Friday of last week Sunday of next week 10th of last month last day of this month January 1 of last year 7th of this month +6 <- 7th day of the 6th month from this one September of next year next month this year
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.
$DATE.IN(how,NA,err,MSG,century) -- &msg &na A&err70:&how,¢ury -------------------------------------------------------------------- how Default: "0" CONVERT = "0" VERIFY = "1" EXACT = "4" ACCOUNTING = "2" ACCTG.EXACT = "6" na Default: "" NA = "A40/ A30/ A48:8,'N/A','NA', 'NONE','NA', 'NA','09/09/9999'/" err Default: "S" msg Default: "" MSG = "A56,'Invalid date'/" century Default: "0" CC19 = "-1" CCYY = "-4" Default: $DATE.IN = AS70:0,0
Purpose: Verify date value, convert to hexadecimal Used as: INPROC, SEARCHPROC Action numbers: A70, A40, A30, A48 Parallel System Function: $DATEIN Complementary System Procs: $DATE.OUT, $DATE.OUT.CC Related System Procs: $DATE, $DATE.IN, $GEN.DATE, $SEARCH.DATE, $SEARCH.DATE.CC Error Default: S Error Message: Invalid date Special Character Rules: not applicable
$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:
- $DATE can automatically generate the current date for "date added" and "date updated" elements as an Inclose rule;
- $DATE with its TRUNC parm provides truncated searching of date indexes, so that FIND DATE 1954 would find all dates with a 1954 year;
- $DATE.IN and $DATE.IN.CC can handle turn-of-the-century issues that $DATE cannot (See the century parameter below.)
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:
- Their parms are in a different order. If you want to add century-handling features to a plain $DATE proc, $DATE.IN.CC is easier to use. But if you have options coded on $DATE (other than ADD, UPD or TRUNC; see above discussion), you may prefer to use $DATE.IN.
- $DATE.IN.CC incorporates NA (Not Applicable) handling into the proc; it is not requested through a separate parameter as it is on $DATE and $DATE.IN.
- The two procs differ in their default handling of 2-character years for input: $DATE.IN will assume the current century is meant, while $DATE.IN.CC will set the error flag if the year is not entered as a 4-character value. But both can be changed.
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.)
$DATE.IN.CC(century,how,error,MSG)
- an integer from 1 to 99 -- SPIRES will supply "20" as the century if the two-digit year in the input value is less than this integer, but will supply "19" if it is greater than or equal to this integer. For example, if the integer is 50, then the input date "2/14/95" would be interpreted as a 1995 date, but "2/14/02" would be interpreted as a 2002 date.
- the integer "0" -- SPIRES will supply the current century at input time for the century portion of the year.
- CCYY (the default) -- If this literal value is coded, SPIRES will set the error flag if the input value does not contain a four-digit year; in other words, a value like "12/31/99" would cause an error, but "12/31/1999" would not.
- CC19 -- If this literal value is coded, SPIRES will always supply "19" as the century for two-digit years, even into the next century.
- 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.
- ACCOUNTING -- This value is the same as CONVERT, but in addition allows the dates "August 32", "August 33" and "August 34" in any given year.
- ACCTG.EXACT -- This value is a combination of ACCOUNTING and EXACT.
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.
$DATE.IN(century,how,err,MSG) -- A40/ A30/ A48:8,'N/A','NA', 'NONE','NA', 'NA','09/09/9999'/ &msg A&err70:&how,¢ury -------------------------------------------------------------------- century Default: "-4" CC19 = "-1" CCYY = "-4" how Default: "0" CONVERT = "0" VERIFY = "1" EXACT = "4" ACCOUNTING = "2" ACCTG.EXACT = "6" err Default: "S" msg Default: "" MSG = "A56,'Invalid date'/" Default: $DATE.IN.CC = A40/ A30/ A48:8,'N/A','NA', 'NONE','NA', 'NA','09/09/9999'/ AS70:0,-4
Purpose: Convert hex value to a standard date format Used as: OUTPROC Action Number: A86 Parallel System Functions: $DATEOUT Complementary System Procs: $DATE, $DATE.IN, $DATE.IN.CC Related System Procs: $DATE.OUT.CC Error Default: none Error Message: none Special Character Rules: not applicable
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.
$DATE.OUT(form,NA,case,size,style,century)
- MONTH -- MONTH DD, CCYY, where MONTH is the month's name or abbreviated name. The "CC" is never suppressed in this form.
- DAY -- DAY MM/DD/CCYY, where DAY is the abbreviated name of the weekday. If the date is unknown, the day field is set to "-----". The CC is suppressed if it matches the "CC" for the current year.
- DAY.MONTH -- DAY MONTH DD, CCYY. This form is a combination of the above two. The CC is never suppressed.
- SQU -- Multiple blanks in the value are converted to single blanks. This cosmetic action is useful when MONTH or DAY appears in the output form. As shown in the examples below, these fields each have a standard length of five characters, but some of the values (such as OCT. or FRI.) do not use five spaces. Hence, such values leave multiple blanks within the value. (An extra blank can also occur in the DD field if the date is earlier than the tenth of the month; see the examples.) Coding SQU eliminates these extra blanks.
- FIXED -- All abbreviations for MONTH and DAY are three characters in length when FIXED is coded. No periods appear. This causes the length of the output value to be fixed for any date with any given form containing words.
- FULL -- No abbreviations for MONTH and/or DAY appear in the output value; they are written out in full, all uppercase (unless UPLOW is specified for the "case" parameter). Also, a comma is added after DAY if the requested "form" displays it. Extra blanks are squeezed out.
- CANADIAN -- The MM and DD fields are reversed. If only this is specified in the parameter list, the form is "DD-MM-CCYY" (the CC is suppressed, by default, if it matches the CC of the current year). If MONTH is coded for "form", CANADIAN will change the form to DD MONTH CCYY (no suppression of CC). (See the examples below.)
- METRIC -- The basic metric form is "CCYY.MM.DD". If MONTH is also specified in the parameter list, the form is "CCYY MONTH DD". The CC is never suppressed for METRIC.
- CCYY -- The year will always be displayed as a four-digit year (e.g., as 1999 rather than 99).
- YY -- The year will always be displayed as a two-digit year; the two century digits will never be displayed.
- CC19 -- If the year begins with "19", then those two digits will be suppressed; any other century will be displayed. This will remain true even when the current year begins with "20".
- 0 (zero) -- If the year begins with the same two digits as the current year at the time the proc executes, the CC will be suppressed. This is the default for $DATE.OUT.
- an integer from 1 to 99 -- CC is suppressed whenever the year is greater than or equal to the value of 1900 + this integer and less than the value of 2000 + P3. For example, if the integer is 50, then if the value is a 1997 date, the "19" would be suppressed; if the value is a 2010 date, the "20" would also be suppressed.
If the date January 5, 1981 were stored with the $DATE proc, the $DATE.OUT proc would produce the following results in 1995:
$DATE.OUT = 01/05/81 $DATE.OUT(MONTH) = JAN. 5, 1981 $DATE.OUT(DAY) = MON. 01/05/81 $DATE.OUT(DAY.MONTH) = MON. JAN. 5, 1981 $DATE.OUT(,,,,,CCYY) = 01/05/1981 $DATE.OUT(DAY,,,,,50) = MON. 01/05/81 $DATE.OUT(MONTH,,UPLOW,SQU) = Jan. 5, 1981 $DATE.OUT(DAY.MONTH,,UPLOW,FIXED) = Mon Jan 5, 1981 $DATE.OUT(DAY.MONTH,,UPLOW,FULL) = Monday, January 5, 1981 $DATE.OUT(DAY,,UPLOW,,CANADIAN) = Mon. 05-01-81 $DATE.OUT(,,,,METRIC) = 1981.01.05 $DATE.OUT(DAY.MONTH,,,,CANADIAN) = MON. 5 JAN. 1981 $DATE.OUT(DAY.MONTH,,,,METRIC) = MON. 1981 JAN. 05
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".
$DATE.OUT(form,NA,case,size,style,century) -- &na A86:&form+&style, &case&size, ¢ury --------------------------------------------------------------------- form Default: "0" MONTH = "1" DAY = "2" DAY.MONTH = "3" na Default: "" NA = "A44,#99990909#, 'N/A'/" case Default: "" UPLOW = "4" size Default: "0" SQU = "1" FULL = "2" FIXED = "4" style Default: "0" CANADIAN = "4" METRIC = "8" century Default: "0" CC19 = "-1" YY = "-2" CCYY = "-4" Default: $DATE.OUT = A86:0+0, 0, 0
Purpose: Convert hex value to a standard date format Used as: OUTPROC Action Number: A86, A44 Parallel System Functions: $DATEOUT Complementary System Procs: $DATE, $DATE.IN, $DATE.IN.CC Related System Procs: $DATE.OUT Error Default: none Error Message: none Special Character Rules: not applicable
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.
$DATE.OUT.CC(century,form,case,size)
- CCYY (default) -- The year will always be displayed as a four-digit year (e.g., as 1999 rather than 99).
- YY -- The year will always be displayed as a two-digit year; the two century digits will never be displayed.
- CC19 -- If the year begins with "19", then those two digits will be suppressed; any other century will be displayed. This will remain true even when the current year begins with "20".
- 0 (zero) -- If the year begins with the same two digits as the current year at the time the proc executes, the CC will be suppressed.
- an integer from 1 to 99 -- CC is suppressed whenever the year is greater than or equal to the value of 1900 + this integer and less than the value of 2000 + P3. For example, if the integer is 50, then if the value is a 1997 date, the "19" would be suppressed; if the value is a 2010 date, the "20" would also be suppressed.
- SQU -- Multiple blanks in the value are converted to single blanks. As shown in the examples below, these fields each have a standard length of five characters, but most of the values (such as FRI.) do not use five spaces (only TUES. and THUR. do). Hence, such values leave multiple blanks within the value. Coding SQU eliminates these extra blanks.
- FIXED -- All abbreviations for DAY are three characters in length when FIXED is coded. No periods appear. This causes the length of the output value to be fixed for any date when using the DAY parameter. Note that the default is "fixed" in length too, but at a length two characters longer, with the possibility of an extra blank inside the value (see SQU above).
- FULL -- No abbreviations for DAY appear in the output value; they are written out in full, all uppercase (unless UPLOW is specified for the "case" parameter). Also, a comma is added after DAY in the value.
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".
$DATE.OUT.CC(century,form,case,size) -- A44,#99990909#, 'N/A'/ A86:&form, &case&size, ¢ury ----------------------------------------------------------------- century Default: "-4" CC19 = "-1" YY = "-2" CCYY = "-4" form Default: "0" DAY = "2" case Default: "" UPLOW = "4" size Default: "0" SQU = "1" FULL = "2" FIXED = "4" Default: $DATE.OUT.CC = A44,#99990909#, 'N/A'/ A86:0, 0, -4
Purpose: Verify date value, convert to hexadecimal Used as: INPROC, SEARCHPROC Action numbers: A70, A30, A40, A44, A48, A126 Parallel System Function: $DATEIN Complementary System Procs: $DATE.OUT, $DATEYY.OUT Related System Procs: $DATE, $DATE.IN, $DATE.IN.CC, $GEN.DATE, $SEARCH.DATE, $SEARCH.DATE.CC Error Default: S Error Message: Invalid date Special Character Rules: not applicable
[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.]
$DATEYY(how,century,method,error,msgna)
- 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.
- NA (INCLOSE only) -- This value causes SPIRES to supply the date '9999.09.09' 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 an unknown date when a record is added. You may wish to code the MSGNA parameter as 'NA' in both this and the $DATEYY.OUT proc. [See 2.2.1.]
- an integer from 1 to 99 (the default is 30) -- SPIRES will supply "20" as the century if the two-digit year in the input value is less than this integer, but will supply "19" if it is greater than or equal to this integer. For example, if the integer is 50, then the input date "2/14/95" would be interpreted as a 1995 date, but "2/14/02" would be interpreted as a 2002 date.
- the integer "0" -- SPIRES will supply the current century at input time for the century portion of the year.
- CCYY -- If this literal value is coded, SPIRES will set the error flag if the input value does not contain a four-digit year; in other words, a value like "12/31/99" would cause an error, but "12/31/1999" would not.
- CC19 -- If this literal value is coded, SPIRES will always supply "19" as the century for two-digit years, even into the next century.
- YYMIN -- A symbolic form of the default of 30.
- BIRTH -- A symbolic form of 10. This may change over time.
- 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.
- ACCOUNTING -- This value is the same as CONVERT, but in addition allows the dates "August 32", "August 33" and "August 34" in any given year.
- MSG -- This value specifies that the message "Invalid date" be displayed when the error flag is set and the error level is S, E or W. [See 1.5.2.]
- NA (default = "", i.e., not NA) -- This parameter is a literal parameter. If the NA parameter (for "Not Applicable") appears, the user updating records can supply any of the following values instead of a date: N/A, NA or NONE (case is not significant). Normally, $DATEYY would reject such a value. This parameter is useful when some value must be input because of the occurrence of a $MIN.OCC rule (minimum occurrences) following the $DATEYY proc. If included on a $DATEYY INPROC, the NA parameter should also be coded on the $DATEYY.OUT proc (or other date proc) used to process the element on output. (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.) [See 2.1.6c.]
$DATEYY(how,minyear,method,err,msgna) -- &msgna A&err70:&method,&minyear &how ------------------------------------------------------------------- how Default: "" ADD = "/ A126:2" UPD = "/ A126:3" TRUNC = "/ A44,#0000#,#00#/ A14,#00#" NA = "/ A123,'9999.09.09',1" minyear Default: "30" CC19 = "-1" CCYY = "-4" method Default: "0" CONVERT = "0" VERIFY = "1" ACCOUNTING = "2" EXACT = "4" err Default: "S" msgna Default: "" MSG = "A56,'Invalid date'/" NA = "A40/ A30/ A48:8,'N/A','NA', 'NONE','NA', 'NA','09/09/9999'/" Default: $DATEYY = AS70:0,30
Purpose: Convert hex value to a standard date format Used as: OUTPROC Action Number: A86, A44 Parallel System Functions: $DATEOUT Complementary System Procs: $DATE, $DATE.IN, $DATE.IN.CC Related System Procs: $DATE.OUT, $DATE.OUT.CC Error Default: none Error Message: none Special Character Rules: not applicable
[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.]
$DATEYY.OUT(form,century,case,size,style,NA)
- MONTH -- MONTH DD, CCYY, where MONTH is the month's name or abbreviated name. The "CC" is never suppressed in this form.
- DAY -- DAY MM/DD/CCYY, where DAY is the abbreviated name of the weekday. If the date is unknown, the day field is set to "-----". The CC is suppressed if it matches the "CC" for the current year.
- DAY.MONTH -- DAY MONTH DD, CCYY. This form is a combination of the above two. The CC is never suppressed.
- CCYY -- The year will always be displayed as a four-digit year. (e.g., as 1999 rather than 99)
- YY -- The year will always be displayed as a two-digit year; the two century digits will never be displayed.
- CC19 -- If the year begins with "19", then those two digits will be suppressed; any other century will be displayed. This will remain true even when the current year begins with "20".
- 0 (zero) -- If the year begins with the same two digits as the current year at the time the proc executes, the CC will be suppressed.
- an integer from 1 to 99 -- CC is suppressed whenever the year is greater than or equal to the value of 1900 + this integer and less than the value of 2000 + P3. For example, if the integer is 30, then if the value is a 1997 date, the "19" would be suppressed; if the value is a 2010 date, the "20" would also be suppressed. If no value is specified for this parameter, the default is 30.
- YYMIN -- A symbolic form of the default of 30.
- BIRTH -- A symbolic form of 10. This may change over time.
- UPLOW -- Month and Day fields, if words, are displayed in lowercase with the first letter of each word capitalized.
- NODASH -- signifies that dashes, and slash immediately following a dash, will be removed from values that are not FIXED or CANADIAN forms.
- NODASH.UPLOW or UPLOW.NODASH -- Combination of both of the above.
- SQU -- Multiple blanks in the value are converted to single blanks. As shown in the examples below, these fields each have a standard length of five characters, but most of the values (such as FRI.) do not use five spaces (only TUES. and THUR. do). Hence, such values leave multiple blanks within the value. Coding SQU eliminates these extra blanks.
- FIXED -- All abbreviations for DAY are three characters in length when FIXED is coded. No periods appear. This causes the length of the output value to be fixed for any date when using the DAY parameter. Note that the default is "fixed" in length too, but at a length two characters longer, with the possibility of an extra blank inside the value (see SQU above).
- FULL -- No abbreviations for DAY appear in the output value; they are written out in full, all uppercase (unless UPLOW is specified for the "case" parameter). Also, a comma is added after DAY in the value.
- CANADIAN -- The MM and DD fields are reversed. If only this is specified in the parameter list, the form is "DD-MM-CCYY" (the CC is suppressed, by default, if it matches the CC of the current year). If MONTH is coded for "form", CANADIAN will change the form to DD MONTH CCYY (no suppression of CC). (See the examples below.)
- METRIC -- The basic metric form is "CCYY.MM.DD". If MONTH is also specified in the parameter list, the form is "CCYY MONTH DD". The CC is never suppressed for METRIC.
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.
$DATEYY.OUT(form,minyear,case,size,style,NA) -- &na A86:&form+&style, &case+&size,&minyear --------------------------------------------------------------------- form Default: "0" MONTH = "1" DAY = "2" DAY.MONTH = "3" LONG = "1" DAY.LONG = "3" minyear Default: "30" CC19 = "-1" YY = "-2" CCYY = "-4" case Default: "0" UPLOW.NODASH = "256+8" NODASH.UPLOW = "256+8" NODASH = "256" UPLOW = "8" size Default: "0" FIXED = "4" SQU = "1" FULL = "2" style Default: "0" CANADIAN = "4" METRIC = "8" na Default: "" NA = "A44,#99990909#, 'N/A'/" Default: $DATEYY.OUT = A86:0+0,0+0,30
Purpose: Convert datetime value to hexadecimal Used as: INPROC, SEARCHPROC, INCLOSE Action numbers: A28, A128 Parallel System Function: $DATETIME Complementary System Procs: $DATETIME.OUT Related System Procs: $GEN.DATETIME Error Default: S Error Message: Invalid datetime Special Character Rules: not applicable
$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.
$DATETIME.IN(how,err,MSG)
- ADD (INCLOSE only) -- This value causes SPIRES to supply the current datetime 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 datetime the record was added.
- UPD (INCLOSE only) -- This parameter value causes SPIRES to discard any supplied value for the element, supply the current datetime, and convert it for storage. It is generally used to provide the datetime a record was last updated. [See 1.5.3.]
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.
INPROC = $DATETIME.IN; INPROC = A28:8;
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:
7/1/2001 7/1/01 07/01/01 Sunday, July 1, 2001 Sunday, 1 July 2001 1-7-01 ("Canadian" dates) 2001.7.1 ("metric" dates) The 1st of July in '01 1st day of 7/01 July 2001 7/01 7/--/01 2001 01
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:
today tomorrow yesterday +5 <- five days from today -3 <- three days ago Monday of this week Sunday of last week Sunday of next week 10th of last month last day of this month January 1 of last year 7th of this month +6 <- 7th day of the 6th month from this one September of next year next month this year
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.
$DATETIME.IN(how,err,msg) = &msg A&err28:&how how Default: "8" ADD = "8/ A128:8" UPD = "8/ A128:9" err Default: "S" msg Default: "" msg = "A56,'Invalid datetime'/" Default: $DATETIME.IN = AS28:8
Purpose: Convert hex datetime value to a standard date and time format Used as: OUTPROC Action Number: A76 Parallel System Functions: $DATEOUT Complementary System Procs: $DATETIME.IN Related System Procs: $DATE.OUT Error Default: none Error Message: none Special Character Rules: not applicable
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.
$DATETIME.OUT(style,form,size,case)
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.]
- CANADIAN -- The MM and DD fields are reversed, and dashes replace slashes. If only this is specified in the parameter list, the form is: DD-MM-CCYY.
- METRIC -- The basic metric form is: CCYY-MM-DD.
- MONTH -- MONTH DD, CCYY, where MONTH is the month's name or abbreviated name. CANADIAN style will change the form to: DD MONTH CCYY. METRIC style will change the form to: CCYY MONTH DD.
- DAY -- DAY date, where DAY is the abbreviated name of the weekday. If the date is unknown, the day field is set to "-----". If DAY is specified with METRIC, dashes are replaced by dots in the date portion.
- DAY.MONTH -- DAY MONTH DD, CCYY. This form is a combination of the above two.
- SQU -- Multiple blanks in the value are converted to single blanks. This cosmetic action is useful when MONTH or DAY appears in the output form. As shown in the examples below, these fields each have a standard length of five characters, but some of the values (such as OCT. or FRI.) do not use five spaces. Hence, such values leave multiple blanks within the value. (An extra blank can also occur in the DD field if the date is earlier than the tenth of the month; see the examples.) Coding SQU eliminates these extra blanks.
- FIXED -- All abbreviations for MONTH and DAY are three characters in length when FIXED is coded. No periods appear. This causes the length of the output value to be fixed for any date with any given form containing words.
- FULL -- No abbreviations for MONTH and/or DAY appear in the output value; they are written out in full, all uppercase (unless UPLOW is specified for the "case" parameter). Also, a comma is added after DAY if the requested "form" displays it. Extra blanks are squeezed out.
$DATETIME.OUT(style,form,size,case) = A76:&style+&form+&size &case style Default: "0" CANADIAN = "4" METRIC = "8" form Default: "0" MONTH = "1" DAY = "2" DAY.MONTH = "3" size Default: "0" FIXED = "16" SQU = "0/ A40" FULL = "0/ A48, JAN., JANUARY, FEB., FEBRUARY, AUG., AUGUST, SEPT., SEPTEMBER, OCT., OCTOBER, NOV., NOVEMBER, DEC., DECEMBER, MON., 'MONDAY,', TUES., 'TUESDAY,', WED., 'WEDNESDAY,', THUR., 'THURSDAY,', FRI., 'FRIDAY,', SAT., 'SATURDAY,', SUN., 'SUNDAY,'/ A40" case Default: "" UPLOW = "/ A30:10"
Purpose: Adjust value to have certain number of decimal places Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A55 Parallel System Function: none Complementary System Procs: $PACK.OUT, $DECIMAL.OUT Related System Procs: $EDIT, $UNEDIT, $PRECISION, $PACK, $PACK.TEST, $RANGE Error Default: S Error Message: Invalid decimal value Special Character Rules: not applicable
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.
$DECIMAL(places,error,MSG,PACK)
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.
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.
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.
$DECIMAL(places,err,MSG,PACK) -- &msg &pack A&err55:2,&places --------------------------------------------------------------- places Default: "3" err Default: "S" msg Default: "" MSG = "A56,'Invalid decimal value'/" pack Default: "" PACK = "A&ERR39,0/" Default: $DECIMAL = AS55:2,3
Purpose: Adjust packed decimal to have specified length for indexing Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A55, A36 Parallel System Functions: none Complementary System Procs: $PACK.OUT, $DECIMAL.OUT Related System Procs: $PACK, $DECIMAL, $RANGE Error Default: S Error Message: Invalid decimal value Special Character Rules: not applicable
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).
$DECIMAL.ADJ(length,places,err,PACK,MSG)
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:
$PACK/ $PACK.TEST(GE,0)/ $PACK.TEST(LT,50)/ $DECIMAL.ADJ(4)
For more information about packed decimals in SPIRES, see section 18 of the SPIRES manual "Technical Notes" or EXPLAIN PACKED DECIMALS.
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.
$DECIMAL.ADJ(len,places,err,PACK,MSG) -- &msg &pack A&err55:2,&places/ A&err36:2,#00#,&len --------------------------------------------------------------- len Default: "4" places Default: "3" err Default: "S" pack Default: "" PACK = "A&ERR39,&LEN/" msg Default: "" MSG = "A56,'Invalid decimal value'/" Default: $DECIMAL.ADJ = AS55:2,3/ AS36:2,#00#,4
Purpose: Convert packed decimal value to string having a given number of decimal places Used as: OUTPROC Action Number: A55, A80 Parallel System Functions: $DECIMAL Complementary System Procs: $DECIMAL, $PACK Related System Procs: $PACK.OUT Error Default: S Error Message: none Special Character Rules: not applicable
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.
$DECIMAL.OUT(places,error)
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.
This proc would convert a packed decimal value to a string, with the output value having two decimal places of accuracy:
Stored value Output value 3 3.00 52.152 52.15 52.157 52.16
$DECIMAL.OUT(places,err) -- A&err55:2,&places/ A&err80 -------------------------------------------------------- places Default: "3" err Default: "S" Default: $DECIMAL.OUT = AS55:2,3/ AS80
Purpose: Convert stored symbol to string Used as: OUTPROC Action Number: A75 Parallel System Functions: none Complementary System Procs: $ENCODE Related System Procs: $INCLUDE, $EXCLUDE Error Default: W Error Message: none Special Character Rules: "values" = rule set 3
$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.
$DECODE(values,error)
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.
$DECODE(values,err) -- A&err75,&values ---------------------------------------- values Default: "' '" err Default: "W" Default: $DECODE = AW75,' '
Purpose: Generate default values Used as: INCLOSE Action Number: A123 Parallel System Functions: none Complementary System Procs: none Related System Procs: $MIN.OCC Error Default: D Error Message: none Special Character Rules: "value" = rule set 1
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.
$DEFAULT(value,occ,error)
This proc will provide a value of 'None' if no other value is input for the element.
$DEFAULT(value,occ,err) -- A&err123,'&value',&occ --------------------------------------------------- value Default: "" occ Default: "1" err Default: "" Default: $DEFAULT = A123,'',1
Purpose: Provide default value depending on value of another element Used as: INCLOSE Action Number: A129 Parallel System Functions: none Complementary System Procs: none Related System Procs: $DEFAULT, $PASS.BY, $TEST.ELEM Error Default: S Error Message: none Special Character Rules: "value", "elem" = rule set 1 "list" = rule set 3
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.
$DEFAULT.COND(value,elem,relation,list,NOOCCUR)
- EQ -- is equal to
- NE -- is not equal to
- GT -- is greater than
- LT -- is less than
- GE -- is greater than or equal to
- LE -- is less than or equal to
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.
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".
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.
$DEFAULT.COND(value,elem,relation,list,NOOCCUR) -- AS129:&nooccur+ &relation,&elem, '&value',&list ------------------------------------------------------------------- value Default: "" elem Default: "" relation Default: "4" LT = "1" GT = "2" NE = "3" EQ = "4" LE = "5" GE = "6" list Default: "" nooccur Default: "0" NOOCCUR = "8" Default: $DEFAULT.COND = AS129:&nooccur+&relation,&elem, '&value',&list
Purpose: Discard all values, or discard containing structure Used as: INCLOSE Action Number: A146 Parallel System Function: none Complementary System Procs: none Related System Procs: $MAX.OCC Error Default: D Error Message: none Special Character Rules: not applicable
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.
$DISCARD(what)
- ELEM -- The proc will discard all occurrences of the element currently being processed.
- STR -- The proc will discard the structure containing the element currently being processed. If this is specified but the element is not within a structure (which is a coding mistake), all occurrences of the element that were input will be converted to null but will not be discarded.
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:
STRUCTURE = name; REQUIRED; KEY = key; OPTIONAL; ... ELEMENT = DELETE; INPROC = $DISCARD(STR);
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.
$DISCARD(what) = A146:&what,0 --------------------------------- what Default: "2" ELEM = "2" STR = "4"
Purpose: Convert money value to binary or floating-point Used as: INPROC, SEARCHPROC Action Number: A42 Parallel System Functions: none Complementary System Procs: $DOLLAR.OUT, $EDIT Related System Procs: $INT, $REAL, $UNEDIT Error Default: S Error Message: Invalid dollar value Special Character Rules: not applicable
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.
$DOLLAR(how,error,MSG)
- VERIFY -- The proc will test to see whether the value is in one of the standard money forms above. If it is not, the error flag is set. The allowed range of values is -$999,999,999.99 to $999,999,999.99.
- REAL -- The value is tested as above and then converted to a 4-byte, single-precision floating point value. The allowed range of values is -$2,147,483,647.99 to $2,147,483,647.99.
- INT -- The value is tested and then converted to a 4-byte binary value. The allowed range of values is -$21,474,836.47 to $21,474,836.47.
- VERIFY.SHORT -- The value is tested as above; the value may also be input with only one decimal place specified (i.e., $D.C). The allowed range of values is -$999,999,999.99 to $999,999,999.99.
- REAL.SHORT -- The value is tested as above and converted to a single-precision floating point value; the 4-byte value may be input with only one decimal place specified (i.e., $D.C). The allowed range of values is -$2,147,483,647.99 to $2,147,483,647.99.
- INT.SHORT -- The value is tested as above and converted to a 4-byte binary equivalent; the value may be input with only one decimal place specified (i.e., $D.C). The allowed range of values is -$21,474,836.47 to $21,474,836.47.
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.
$DOLLAR(how,err,MSG) -- &msg A&err42:&how ------------------------------------------- how Default: "6" VERIFY = "0" REAL = "1" INT = "2" VERIFY.SHORT = "4" REAL.SHORT = "5" INT.SHORT = "6" err Default: "S" msg Default: "" MSG = "A56,'Invalid dollar value'/" Default: $DOLLAR = AS42:6
Purpose: Convert binary or floating-point value to money value Used as: OUTPROC Action Number: A81 Parallel System Functions: $EDIT Complementary System Procs: $DOLLAR Related System Procs: $EDIT Error Default: W Error Message: Value too long Special Character Rules: not applicable
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.
$DOLLAR.OUT(how,length,error,MSG)
- REAL -- The value must have been created by $DOLLAR(REAL) or $DOLLAR(REAL.SHORT). If the value cannot be converted within the specified length (see 'length' below), the error flag is set and the value is returned as a series of stars of the specified length. The value may be converted to exponential notation in order to fit in the allotted length.
- REAL.ERR -- The value must have been created by $DOLLAR(REAL) or $DOLLAR(REAL.SHORT). If the value is null the error flag is set. Otherwise, this symbol works exactly like REAL above. The value may be converted to exponential notation in order to fit in the allotted length.
- INT -- The value must have been created by $DOLLAR(INT) or $DOLLAR(INT.SHORT). If the value is null or greater than four bytes long, the error flag is set and the value not converted. If the converted value does not fit into the specified length, the error flag is set, but the value is converted and returned in whatever size is needed.
- INT.FILL -- The value must have been created by $DOLLAR(INT) or $DOLLAR(INT.SHORT). If the value is null or greater than four bytes long, the error flag is set and the value not converted. If the value is less than the specified length, it is padded to the left with zeroes.
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.
Proc $15 $150 $150000 $-15 ----------------------- ----------- ---------- ------------- -------- $DOLLAR.OUT(INT) $15.00 $150.00 $150000.00 $-15.00 $DOLLAR.OUT(INT,6) $15.00 $150.00 $150000.00 ! $-15.00 $DOLLAR.OUT(INT.FILL,6) $0015.00 $0150.00 $150000.00 ! $-015.00 $DOLLAR.OUT(REAL,7) $15.00 $150.00 $1.E+05 $-15.00 $DOLLAR.OUT(REAL,6) $15.00 $150.0 $1E+05 $-15.00 $DOLLAR.OUT(REAL,5) $15.0 $150. $***** ! $-15.0
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.
$DOLLAR.OUT(how,len,err,MSG) -- &msg A&err81:&how,&len -------------------------------------------------------- how Default: "2" REAL = "0" REAL.ERR = "1" INT = "2" INT.FILL = "3" len Default: "15" err Default: "W" msg Default: "" MSG = "A56,'Value too long'/" Default: $DOLLAR.OUT = AW81:2,15
Purpose: Editing packed decimal or binary value against an edit mask Used as: OUTPROC Action Number: A85 Parallel System Functions: $EDIT Complementary System Procs: $UNEDIT Related System Procs: $DOLLAR, $DOLLAR.OUT, $DECIMAL, $PACKED Error Default: D Error Message: none Special Character Rules: "mask" = rule set 1
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.
$EDIT(divisor,mask,type,error)
- INT or BINARY (default) -- The stored value is an integer value.
- PACKED -- The stored value is a packed decimal value.
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.
EDIT MASK '123456' '-123456' '$ZZ,ZZZ.99' '$ 1,234.56' '$ 1,234.56' '+$ZZ,ZZZ.99' '+$ 1,234.56' '-$ 1,234.56' '-$ZZ,ZZZ.99' ' $ 1,234.56' '-$ 1,234.56' '+++++++.99' ' +1234.56' ' -1234.56' '-------.99' ' 1234.56' ' -1234.56' '--,---,---.99' ' 1,234.56' ' -1,234.56' '$99,999.99' '$01,234.56' '$01,234.56' '$**,***.99' '$*1,234.56' '$*1,234.56' '$$$,$$$.99' ' $1,234.56' ' $1,234.56' '$$$,$$$.99CR' ' $1,234.56 ' ' $1,234.56CR' '$$$,$$$.99-' ' $1,234.56 ' ' $1,234.56-' '$$$,$$$.99DB' ' $1,234.56 ' ' $1,234.56DB'
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.
$EDIT(div,mask,type,err) -- A&err85:&type,&div,&mask ------------------------------------------------------ div Default: "2" mask Default: "-$ZZ,ZZZ.99" type Default: "1" PACKED = "2" INT = "1" BINARY = "1" err Default: "" Default: $EDIT = A85:1,2,-$ZZ,ZZZ.99
Purpose: Verify value in list, convert to symbol for storage Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC Action Number: A46 Parallel System Functions: $MATCH Complementary System Procs: $DECODE Related System Procs: $INCLUDE, $EXCLUDE Error Default: S Error Message: none Special Character Rules: "values" = rule set 3
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.
$ENCODE(values,type,error)
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.
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.
$ENCODE(values,type,err) -- A&err46:&type,&values --------------------------------------------------- values Default: "' '" type Default: "1" EXCLUDE = "0" BYTE = "1" VERIFY = "3" err Default: "S" Default: $ENCODE = AS46:1,' '
Purpose: Encrypt values for security Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A60 Parallel System Functions: $DENCODE Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: not applicable
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.]
$ENCRYPT(type)
$ENCRYPT(type) -- A60:&type ----------------------------- type Default: "0" LEN = "8" Default: $ENCRYPT = A60:0
Purpose: Evaluate user-defined expression Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC Action Number: A69 Parallel System Functions: $EVAL Complementary System Procs: none Related System Procs: $CALL Error Default: D Error Message: none Special Character Rules: "expression" = rule set 1
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.
$EVAL(expression,error,p1)
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:
With Userprocs: INPROC = $DATE/ $CALL(GetDays) / $INT; USERDEFS; USERPROC = GetDays; UPROC = SET VAL = $DAYS($UDATE)-$DAYS($VAL); With $EVAL proc: INPROC = $DATE/ $EVAL('$DAYS($UDATE)-$DAYS($VAL)')/ $INT;
$EVAL(exp,err,p1) -- A&err69:&p1,'&exp' ----------------------------------------- exp Default: "$VAL" err Default: "" p1 Default: "0" Default: $EVAL = A69:0,'$VAL'
Purpose: Discard values in list Used as: INPROC, OUTPROC, PASSPROC, SRCPROC Action Number: A46 Parallel System Functions: none Complementary System Procs: none Related System Procs: $INCLUDE, $ENCODE, $DECODE Error Default: D Error Message: none Special Character Rules: "values" = rule set 3
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.
$EXCLUDE(values,type,error)
- COMMON.WORDS -- This parameter value can be coded in place of a list of values. This will substitute a pre-defined list of common words for the user-defined list of values and is often used to exclude common words from word indexes. The words in the list are A, TO, FOR, WERE, WAS, BUT, AND, ARE, THE, AS, OR, AN, AT, BY, IN, OF, ON, AM, BE and IS.
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.
In this example, any value except CAT, DOG and BIRD will be accepted. The values listed would cause a serious error.
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.
$EXCLUDE(values,type,err) -- A&err46:&type,&values ---------------------------------------------------- values Default: "' '" COMMON.WORDS = "A, TO, FOR, WERE, WAS, BUT, AND, ARE, THE, AS, OR, AN, AT, BY, IN, OF, ON, AM, BE, IS" type Default: "0" EXCLUDE = "0" INCLUDE = "1" err Default: "" Default: $EXCLUDE = A46:0,' '
Purpose: Reconvert compressed strings for output Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A58 Parallel System Functions: none Complementary System Procs: $COMPRESS Related System Procs: none Error Default: W Error Message: none Special Character Rules: not applicable
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.
$EXPAND(how,error)
- ALPHA -- Only alphabetic characters, blanks, dashes, commas or apostrophes were translated. Numbers and other special characters in the original value will appear as asterisks.
- NUMERIC -- Any character, punctuation mark or number was translated.
$EXPAND(how,err) -- A&err58:&how ---------------------------------- how Default: "1" ALPHA = "0" NUMERIC = "1" err Default: "W" Default: $EXPAND = AW58:1
Purpose: Retrieve higher or lower value if requested value not indexed Used as: SEARCHPROC Action Number: A15, A16 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: not applicable
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.
$FIND(how)
- LOWER -- The next lower value would be retrieved under the condition that the next lower value matched the first characters in the search value.
- HIGHER -- The next higher value would be retrieved.
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.
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.
$FIND(how) -- A1&how ---------------------- how Default: "6" LOWER = "5" HIGHER = "6" Default: $FIND = A16
Purpose: Test for numeric string of a specified length Used as: INPROC, SEARCHPROC Action Numbers: A22, A23, A49 Parallel System Functions: none Complementary System Procs: none Related System Procs: $INT, $LENGTH Error Default: S Error Message: Value must be "length" digits Special Character Rules: not applicable
$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.
$FIXED.NUM(length,error,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.
$FIXED.NUM(len,err,msgs) -- &msgs A&err22,&len/ A&err23,&len/ A&err49,0123456789 ------------------------------------------------- len Default: "5" err Default: "S" msgs Default: "" MSG = "A56,'Value must be &LEN digits'/" Default: $FIXED.NUM = AS22,5/ AS23,5/ AS49,0123456789
Purpose: Generate value using logged-on account number Used as: INCLOSE Action Number: A127 Parallel System Functions: none Complementary System Procs: none Related System Procs: $GEN.DATE, $GEN.TIME Error Default: none Error Message: none Special Character Rules: not applicable
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.
$GEN.ACCT(how)
- ADD or ONCE -- An element value is generated only when no other value for the element exists.
- UPD or ALWAYS -- The element value is replaced by the logged on account each time the record is updated.
Note: This proc will not change the value if another Inclose rule has generated a value prior to the execution of this proc.
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.
$GEN.ACCT(how) -- A127:&how ----------------------------- how Default: "0" ONCE = "0" ADD = "0" UPD = "1" ALWAYS = "1" Default: $GEN.ACCT = A127:0
Purpose: Generate value using current date Used as: INCLOSE Action Number: A126 Parallel System Functions: none Complementary System Procs: none Related System Procs: $DATE, $DATE.IN, $DATE.OUT Error Default: none Error Message: none Special Character Rules: not applicable
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.
$GEN.DATE(how,century)
- ADD or ONCE -- An element value is generated only when no other value for the element exists.
- UPD or ALWAYS -- The element value is replaced by the current date each time the record is updated.
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:
INPROC = $DATE/ $GEN.DATE(ADD); INPROC = $DATE(ADD);
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:
INPROC = $DATE/ $CALL(TESTDATE)/ $GEN.DATE(ADD);
The following is not allowed:
INPROC = $DATE(ADD)/ $CALL(TESTDATE);
because the ADD parameter on $DATE represents an INCLOSE rule, which may not be followed by a non-INCLOSE INPROC.
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.
$GEN.DATE(how) -- A126:&how+¢ury ----------------------------- how Default: "0" ONCE = "0" ADD = "0" UPD = "1" ALWAYS = "1" century Default: "0" CCYY = "2" Default: $GEN.DATE = A126:0+0
Purpose: Generate datetime value using current date and time Used as: INCLOSE Action Number: A128 Parallel System Functions: none Complementary System Procs: none Related System Procs: $DATETIME.IN Error Default: none Error Message: none Special Character Rules: not applicable
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.]
$GEN.DATETIME(how)
- ADD or ONCE -- An element value is generated only when no other value for the element exists.
- UPD or ALWAYS -- The element value is replaced by the current datetime each time the record is updated.
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:
INPROC = $DATETIME.IN/ $GEN.DATETIME(ADD); INPROC = $DATETIME.IN(ADD);
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:
INPROC = $DATETIME.IN/ $CALL(TESTDATETIME)/ $GEN.DATETIME(ADD);
The following is not allowed:
INPROC = $DATETIME.IN(ADD)/ $CALL(TESTDATETIME);
because the ADD parameter on $DATETIME.IN represents an INCLOSE rule, which may not be followed by a non-INCLOSE INPROC.
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.
$GEN.DATETIME(how) -- A126:&how ----------------------------- how Default: "8" ONCE = "8" ADD = "8" UPD = "9" ALWAYS = "9" Default: $GEN.DATETIME = A126:8
Purpose: Generate value using current time Used as: INCLOSE Action Number: A128 Parallel System Functions: none Complementary System Procs: none Related System Procs: $TIME, $TIME.OUT, $GEN.DATE, $GEN.ACCT Error Default: none Error Message: none Special Character Rules: not applicable
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.
$GEN.TIME(how)
- ADD or ONCE -- The current time is generated only when no other value for the element exists.
- UPD or ALWAYS -- The element value is replaced by the current time each time the record is updated.
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:
INPROC = $TIME(ADD); INPROC = $TIME/ $GEN.TIME(ADD);
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:
INPROC = $TIME/ $CALL(TESTTIME)/ $GEN.TIME(ADD);
The following is not allowed:
INPROC = $TIME(ADD)/ $CALL(TESTTIME);
because the ADD parameter on $TIME represents an INCLOSE rule, which cannot be followed by a non-INCLOSE INPROC.
$GEN.TIME(how) -- A128:&how ----------------------------- how Default: "0" ONCE = "0" ADD = "0" UPD = "1" ALWAYS = "1" Default: $GEN.TIME = A128:0
Purpose: Concatenate value of another element to output value Used as: OUTPROC Action Number: A79 Parallel System Functions: $GETUVAL Complementary System Procs: none Related System Procs: $TEST.OCC, $PUTELEM Error Default: W Error Message: none Special Character Rules: not applicable
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.
$GETELEM(element)
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:
- if the retrieved value is null, then the type of the final value will be the same type as the original value;
- if the original value is null, then the type of the final value will be the same type as the retrieved value;
- if both the original and the retrieved value are non-null strings, the type of the final value will be string;
- if both values are non-null, but neither or only one is type string, then the type of the final value will be hex.
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.)
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.)
$GETELEM(elem) -- A79,&elem ----------------------------- elem Default: "0" Default: $GETELEM = AW79,0
Purpose: Use goal record-type as index Used as: SEARCHPROC Action Number: A10 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: not applicable
$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.
$GOAL.INDEX
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).
GOALREC-NAME = REC01; PTR-ELEM = POINTER; EXTERNAL-NAME = ALBUMS; SEARCHPROC = $INT; PASSPROC = $PASS.LCTR; INDEX-NAME = REC01; SEARCHTERMS = PERFORMER, PERF, P; SEARCHPROC = $GOAL.INDEX/ $SEARCH.SUBF('ALBUMS2',SOLOIST); PASSPROC = $NOPASS; PTR-GROUP = POINTER;
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.
$GOAL.INDEX -- A10
Purpose: Convert string value to hexadecimal Used as: INPROC, SEARCHPROC Action Number: A29 Parallel System Functions: $HEX Complementary System Procs: $HEX.OUT Related System Procs: none Error Default: S Error Message: Invalid hex value Special Character Rules: not applicable
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.
$HEX(length,odd,error,MSG)
- ANY, which allows any size value to be stored. The stored value will be half the length of the original (rounded up to an integer).
- an integer, representing the length of the stored value in bytes. The error flag is set if the length of the stored value would exceed this limit, and the value is truncated, the rightmost characters being retained. If the value is shorter, the original value is padded on the left with zeroes before the conversion.
- ODD.ERR -- A value of an odd length will cause an error.
- NO.ERR -- A value of an odd length will not cause an error.
- MAXIMUM -- The stored value will always be half the length of the original, up to the value of "length", the maximum. If the converted value would be longer than "length", the error flag is set and the value returned is unpredictable.
- EXACT -- The stored value will always be the length specified by "length". If the stored value would exceed the value of "length", the error flag is set and the returned value is unpredictable. If the stored value would be shorter than "length", the value is padded on the left with zeroes before conversion for storage.
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.
$HEX(len,odd,err,MSG) -- &msg A&err29:&odd,&len ------------------------------------------------- len Default: "0" ANY = "0" odd Default: "0" ODD.ERR = "0" NO.ERR = "1" EXACT = "0" MAXIMUM = "1" err Default: "S" msg Default: "" MSG = "A56,'Invalid hex value'/" Default: $HEX = AS29:0,0
Purpose: Convert hexadecimal value to string Used as: OUTPROC Action Number: A74 Parallel System Functions: $STRING Complementary System Procs: $HEX Related System Procs: none Error Default: W Error Message: Value too long Special Character Rules: not applicable
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.
$HEX.OUT(length,PAD,error,MSG)
- ANY -- The converted value can be of any length. In this case, the converted value will be twice as long as the stored value.
- an integer, representing the length of the converted value. If the converted value would be longer than the specified length, the error flag is set but the value is converted anyway.
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.
$HEX.OUT(len,PAD,err,MSG) -- &msg A&err74:&pad,&len ----------------------------------------------------- len Default: "0" ANY = "0" pad Default: "0" PAD = "1" err Default: "W" msg Default: "" MSG = "A56,'Value too long'/" Default: $HEX.OUT = AW74:0,0
Purpose: Retain only values in list Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC Action Number: A46 Parallel System Functions: none Complementary System Procs: none Related System Procs: $EXCLUDE, $ENCODE, $DECODE Error Default: S Error Message: none Special Character Rules: "values" = rule set 3
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.
$INCLUDE(values,type,error)
In this example, only the four values listed would be accepted as element values. Any other value would cause a serious error.
$INCLUDE(values,type,err) -- A&err46:&type,&values ---------------------------------------------------- values Default: "' '" type Default: "3" BYTE = "1" err Default: "S" Default: $INCLUDE = AS46:3,' '
Purpose: Insert string before, after or within value Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A36 Parallel System Functions: none Complementary System Procs: none Related System Procs: $INSETR, $INSETL Error Default: W Error Message: none Special Character Rules: "what" for $INSERT = rule set 1 "what" for $INSERT.HEX = rule set 2
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.
$INSERT(what,how,where,error) $INSERT.HEX(what,how,where,error)
- LEFT -- The character string is to be inserted to the left of the specified character (see "where" below), counting from the left end.
- RIGHT -- The character string is to be inserted to the right of the specified character (see "where" below), counting from the right end.
- END -- The character string is to be inserted at the end of the element value. No "where" parameter value should be specified.
- FRONT -- The character string is to be inserted at the beginning of the element value. No "where" parameter value should be specified.
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.
The string "-" would be inserted to the right of the fifth character in the value counting from the right end, as follows:
4974420 would become 497-4420
If the input value were shorter than five characters, a warning error would occur and the value would have been left unchanged.
A blank (hex 40) would be inserted to the left of the third character in the value, counting from the left end.
$INSERT(what,how,where,err) -- A&err36:&how,'&what',&where ------------------------------------------------------------ what Default: " " how Default: "3" LEFT = "0" AFTER = "0" END = "0" FRONT = "3" RIGHT = "3" BEFORE = "3" where Default: "0" err Default: "W" Default: $INSERT = AW36:3,' ',0
$INSERT.HEX(what,how,where,err) -- A&err36:&how,&what,&where -------------------------------------------------------------- what Default: "#00#" how Default: "3" LEFT = "0" AFTER = "0" END = "0" FRONT = "3" RIGHT = "3" BEFORE = "3" where Default: "0" err Default: "W" Default: $INSERT.HEX = AW36:3,#00#,0
Purpose: Overlay value onto left end of string; left justification Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A36 Parallel System Functions: none Complementary System Procs: none Related System Procs: $INSETR, $INSERT Error Default: W Error Message: none Special Character Rules: "what" = rule set 1
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.
$INSETL(what,length,error)
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.
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".
$INSETL(what,len,err) -- A&err36:1,'&what',&len ------------------------------------------------- what Default: " " len Default: "1" err Default: "W" Default: $INSETL = AW36:1,' ',1
Purpose: Overlay value onto right end of string; right justification Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A36 Parallel System Functions: $INSETR Complementary System Procs: none Related System Procs: $INSETL, $INSERT Error Default: W Error Message: none Special Character Rules: "what" = rule set 1
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.
$INSETR(what,length,error)
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.
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.
$INSETR(what,len,err) -- A&err36:2,'&what',&len ------------------------------------------------- what Default: " " len Default: "1" err Default: "W" Default: $INSETR = AW36:2,' ',1
Purpose: Convert character string to binary Used as: INPROC, SEARCHPROC, INCLOSE Action number: A21 Parallel System Function: $INT Complementary System Procs: $INT.OUT Related System Procs: $RANGE, $DOLLAR, $EDIT, $UNEDIT, $DECIMAL Error Default: S Error Message: Invalid integer value Special Character Rules: not applicable
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).
$INT(length,error,MSG,UNIQUE)
- value -- a number, such as 1, 2, 3 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. SPIRES will allow the input value to be null if 8 is added to any of these numbers (i.e., the values allowed are 1, 2, 3, 4; and 9, 10, 11 and 12). [If you use the "null" form, be sure that no LEN statement is coded for the element; otherwise, blanks (hex 40) will be stored for the "null" value, which would be converted to a number on output.]
- BYTE -- The value is converted to a one-byte value. The value being input can be from 0 to 255. (Note that certain values outside that range can be entered and will be converted without warning to a number from 0 to 255.) To allow null values, use "9" instead (see "value" above).
- 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. To allow null values, use "10" instead (see "value" above).
- 3 -- The value is converted to a three-byte binary value. The minimum value that can be stored is -8,388,608; the maximum is 8,388,607. Some numbers outside this range will be accepted on input and converted without warning to a number within the range. To allow null values, use "11" instead (see "value" above).
- 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. To allow null values, use "12" instead (see "value" above).
- VERIFY -- This parameter value requests that the input value be verified to be an integer value but not be converted. If it is not an integer value, an error is caused. To allow null values, use "8" instead (see "value" above).
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.
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.
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.
$INT(len,err,MSG,UNIQUE) -- &msg A&err21:&len &unique ------------------------------------------------------- len Default: "4" VERIFY = "0" BYTE = "1" HALF = "2" FULL = "4" INT = "4" err Default: "S" msg Default: "" MSG = "A56,'Invalid integer value'/" unique Default: "" UNIQUE = "/A&err125" Default: $INT = AS21:4
Purpose: Convert binary value to character string Used as: OUTPROC Action Number: A71 Parallel System Functions: $STRING Complementary System Procs: $INT Related System Procs: $RANGE Error Default: W Error Message: Value too long Special Character Rules: not applicable
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.
$INT.OUT(length,PAD,error,MSG)
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.
$INT.OUT(len,PAD,err,MSG) -- &msg A&err71:&pad,&len ----------------------------------------------------- len Default: "15" pad Default: "0" PAD = "1" err Default: "W" msg Default: "" MSG = "A56,'Value too long'/" Default: $INT.OUT = AW71:0,15
Purpose: Translate characters for italic character set Used as: OUTPROC Action Number: A43 Parallel System Functions: none Complementary System Procs: none Related System Procs: $BOLD, $BG Error Default: none Error Message: none Special Character Rules: not applicable
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.
$ITALIC -- A43,ABCDEFGHIJKLMNOPQRSTUVWXYZ, #01020304050607080911121314156A1718192223242526272829#/ A43,abcdefghijklmnopqrstuvwxyz, #0A0B0C0D0E0F1A1B1C1D1E1F2A2B2C2D2E2F38393A3B3C3D3E3F#/ A43,'0123456789?!$&',#3031323334353637202100108D9C#/ A43,#4A#,#9D#
Purpose: Verify value is a specified length Used as: INPROC, SEARCHPROC Action Numbers: A22, A23 Parallel System Functions: none Complementary System Procs: none Related System Procs: $MIN.LEN, $MAX.LEN, $TEST.LEN Error Default: S Error Message: Value must be "length" characters Special Character Rules: not applicable
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.
$LENGTH(length,recovery,PAD,error,MSG)
- KEEP.ALL -- The entire value is retained.
- KEEP.FIRST -- Only the first specified number of characters are retained.
- KEEP.LAST -- Only the last specified number of characters are retained.
- DROP.FIRST -- The first specified number of characters are dropped.
- DROP.LAST -- The last specified number of characters are dropped.
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.
This example will reject any value longer or shorter than 5 characters, causing a serious error.
$LENGTH(len,recov,PAD,err,msgs) -- &msgs A&err22:&recov,&len/ A&err23:&pad,&len -------------------------------------------------- len Default: "1" recov Default: "0" KEEP.ALL = "0" KEEP.FIRST = "1" KEEP.LAST = "2" DROP.FIRST = "3" DROP.LAST = "4" pad Default: "0" PAD = "1" err Default: "S" msgs Default: "" MSG = "A56, 'Value must be &len characters'/" Default: $LENGTH = AS22:0,1/ AS23:0,1
Purpose: Manipulate bits in value using logical operator; adjust integer and floating-point values for indexing Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A59 Parallel System Functions: none Complementary System Procs: none Related System Procs: $BITS Error Default: S Error Message: none Special Character Rules: "chars" = rule set 2
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.
This form of the proc is used for manipulating bits in string values.
$LOGICAL(how,chars,error)
- OR -- If this value is specified, each input bit will be "or"ed to its corresponding string bit: if either bit is 1, the result is 1. This is demonstrated in the chart below:
Value bit String bit Resulting bit 0 0 0 0 1 1 1 0 1 1 1 1
- AND -- If this value is specified, then both bits must be 1 for the result to be 1:
Value bit String bit Resulting bit 0 0 0 0 1 0 1 0 0 1 1 1
- XOR ("exclusive OR") -- If this value is specified, then if either bit is 1, but not both, then the result is 1:
Value bit String bit Resulting bit 0 0 0 0 1 1 1 0 1 1 1 0
- BLANK -- A blank character (hex code 40) will be used.
- ZERO -- A "0" (hex code F0) will be used.
- any character string.
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.
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.
$LOGICAL(SIGN,what,error)
- I (the letter "eye", for INPUT) -- SPIRES flips the first bit of "positive" values and flips all bits of "negative" values. This form is used to convert Real values for index storage.
- O (the letter "oh", for OUTPUT) -- SPIRES flips all bits of "positive" values and the top bit of "negative" values. This form is used to reconvert the values for output that were converted by the "I" method.
- FLIP -- SPIRES flips just the top bit of all values. This form is used to convert Integer values for index storage, and later to reconvert them for 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:
$LOGICAL(SIGN,I)
And add this proc to the element's Outproc string, before the conversion of the value to string:
$LOGICAL(SIGN,O)
For integers, the same proc works for both input and output:
$LOGICAL(SIGN,FLIP)
$LOGICAL(how,chars,error) -- A&error59:&how,&chars ---------------------------------------------------- how Default: "1" XOR = "0" OR = "1" AND = "2" SIGN = "3" chars Default: "' '" BLANK = "' '" ZERO = "'0'" error Default: "S" Default: $LOGICAL = AS59:1,' '
Purpose: Verify or replace value with value from another subfile Used as: INPROC, OUTPROC, SRCPROC Action Number: A65 Parallel System Functions: $LOOKSUBF Complementary System Procs: none Related System Procs: $LOOKSUBG, $ENCODE, $INCLUDE, $CHANGE Error Default: S Error Message: none Special Character Rules: "subfile" = rule set 1
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.
$LOOKSUBF(how,subfile,element,error,via)
- VERIFY -- The value input to this proc is unaffected if a record with that value for a key is retrieved. The error flag is set if no record is retrieved.
- NONE.VERIFY -- The error flag is set if a record having that key is retrieved from the accessed subfile (i.e., SPIRES should verify that no record having that key exists in the second subfile). (VERIFY.NONE means the same thing.)
- REPLACE -- The value input to this proc is replaced by the internal value of the first occurrence of the element in the accessed subfile as specified by the "element" parameter (see below). The error flag is set if the named element has no occurrences in the accessed record or if there is no element with that name.
- EXTERNAL -- This symbol is like REPLACE, but the value input to this proc is replaced by the external form of the the first occurrence of the element.
- LCTR -- Coding this symbol indicates that the value input to this proc is a locator; the current record-type is an index record-type. This value is useful in an OUTPROC on the pointer element of an index for REMOVED goal records.
- NODEFQ -- This symbol indicates that the deferred queue of the accessed subfile should not be examined for the latest copy of the record. This value saves one I/O per transaction.
- NODEFQ.LCTR -- This symbol indicates a combination of the two previous ones.
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.
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.
$LOOKSUBF(how,subfile,elem,err,via) -- A&err65:&via+&how, '&subfile','&elem' -------------------------------------------------------------- how Default: "2" NONE.VERIFY = "1" VERIFY.NONE = "1" VERIFY = "2" REPLACE = "3" EXTERNAL = "0" subfile Default: "" elem Default: "" err Default: "S" via Default: "0" LCTR = "4" NODEFQ = "8" NODEFQ.LCTR = "12" Default: $LOOKSUBF = AS65:0+2,'',''
Purpose: Table lookup for value verification or replacement Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC Action Number: A32 Parallel System Functions: $LOOKSUBG Complementary System Procs: none Related System Procs: $LOOKSUBF, $ENCODE, $INCLUDE, $CHANGE Error Default: S Error Message: none Special Character Rules: not applicable
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.
The following syntax applies when $LOOKSUBG is used as an INPROC, OUTPROC or SEARCHPROC:
$LOOKSUBG(how,record,element,error,via)
- VERIFY -- The value of the current element is unaffected if a record with that value for a key is retrieved. The error flag is set if no record is retrieved.
- NONE.VERIFY -- The error flag is set if a record having that key value is retrieved (i.e., SPIRES should verify that no record having that key exists in the second record-type). VERIFY.NONE means the same thing.
- REPLACE -- The value of the current element is replaced by the internal value of the first occurrence of the element in the accessed record as specified by the "element" parameter (see below). The error flag is set if the named element has no occurrences in the accessed record.
- EXTERNAL -- This symbol is like REPLACE, except that the value of the current element is replaced by the external value of the first occurrence of the element in the accessed record.
- KEY -- This value represents the first element in the record, usually the key.
- LCTR -- This value may be used when the second record-type is a REMOVED record-type, in which case, the value is replaced by a locator to the record.
- LCTR -- Coding this symbol for this parameter indicates that the value of the current element is a locator; the current record is an index record-type. This value is useful as an OUTPROC on the pointer element of an index.
- NODEFQ -- This symbol indicates that the deferred queue should not be examined for records of the accessed record-type. This saves one I/O per transaction.
- NODEFQ.LCTR -- This symbol indicates a combination of the two previous ones.
If $LOOKSUBG is used as a PASSPROC, the syntax is simpler:
$LOOKSUBG(how,record,element)
- UPPER -- The retrieved value should be converted to uppercase. Most indexes are designed for uppercase values, so this is the more common choice.
- UPLOW -- The retrieved value is not converted to uppercase.
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.
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.
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.
$LOOKSUBG(how,record,elem,err,via) -- A&err32:&via+&how,&record,&elem --------------------------------------------------------------------- how Default: "2" UPPER = "0" UPLOW = "1" NONE.VERIFY = "1" VERIFY.NONE = "1" VERIFY = "2" REPLACE = "3" EXTERNAL = "0" POINTER = "6" NODEFQ = "10" record Default: "1" GOAL = "1" elem Default: "0" KEY = "0" LCTR = "-1" PTR = "-1" err Default: "S" via Default: "0" LCTR = "4" NODEFQ = "8" NODEFQ.LCTR = "12" Default: $LOOKSUBG = AS32:0+2,1,0
Purpose: Retrieve record data from system subfiles Used as: INPROC, OUTPROC, SRCPROC Action Numbers: A30, A65 Parallel System Functions: $LOOKSYS Complementary System Procs: none Related System Procs: $LOOKSUBF Error Default: S Error Message: none Special Character Rules: rule set 1
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".
$LOOKSYS(file,elem,err,uplow)
In this example, the value of the STATUS element is looked up in the Prism routing file.
$LOOKSYS(file,elem,err,uplow) = &uplow A&err65:0, '!LOOKSYS_&file','&elem' --------------------------------------------------------- file Default: '' elem Default: '' err Default: S uplow Default: A30/ UPLOW = '' Default: $LOOKSYS = A30/ AS65:0,'',''
Purpose: Convert uppercase characters to lowercase Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A30 Parallel System Functions: $CASE Complementary System Procs: $UPPER Related System Procs: $CAP Error Default: none Error Message: none Special Character Rules: not applicable
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.
$LOWER(cap)
- CAP.FIRST -- Capitalize the first character in the value. (If the first character in the value is not a letter, this symbol has no effect.)
- CAP.EACH -- Capitalize the first letter of each word in the value.
For a complete list of possible number-options for 'cap', [EXPLAIN $CASE FUNCTION.]
This proc would affect values as follows:
Input Output JULY 1, 1981 July 1, 1981 1 JULY 1981 1 july 1981 rEVERSE GEAR Reverse gear
$LOWER(cap) -- A30:&cap ------------------------- cap Default: "1" CAP.FIRST = "12" CAP.EACH = "10"
Purpose: Truncate value at given length Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A22 Parallel System Functions: $LSTR Complementary System Procs: $INSERT Related System Procs: $MAX.LEN, $RSTR, $XSTR Error Default: D Error Message: none Special Character Rules: not applicable
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.
$LSTR(length,recov,error)
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.
$LSTR(len,recov,err) -- A&err22:&recov,&len --------------------------------------------- len Default: "1" recov Default: "1" KEEP.ALL = "0" KEEP.FIRST = "1" KEEP.LAST = "2" DROP.FIRST = "3" DISCARD.LAST = "4" DELETE.LAST = "6" DROP.LAST = "6" err Default: "" Default: $LSTR = A22:1,1
Purpose: Verify maximum length of value Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A22 Parallel System Functions: none Complementary System Procs: none Related System Procs: $MIN.LEN, $LENGTH, $LSTR, $TEST.LEN Error Default: S Error Message: Value must not exceed "length" characters Special Character Rules: not applicable
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.
$MAX.LEN(length,recovery,error,MSG)
- KEEP.ALL -- The entire value is retained.
- KEEP.FIRST -- Only the first specified number of characters are retained.
- KEEP.LAST -- Only the last specified number of characters are retained.
- DROP.FIRST -- The first specified number of characters are dropped.
- DROP.LAST -- The last specified number of characters are dropped.
In this example, any element value longer than 25 characters would cause a serious error.
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.
$MAX.LEN(len,recov,err,msgs) -- &msgs A&err22:&recov,&len ------------------------------------------------ len Default: "132" recov Default: "0" KEEP.ALL = "0" KEEP.FIRST = "1" KEEP.LAST = "2" DROP.FIRST = "3" DROP.LAST = "4" err Default: "S" msgs Default: "" MSG = "A56, 'Value must not exceed &LEN characters'/ " Default: $MAX.LEN = AS22:0,132
Purpose: Verify maximum number of occurrences Used as: INCLOSE Action Number: A146 Parallel System Functions: none Complementary System Procs: none Related System Procs: $MIN.OCC, $OCC Error Default: S Error Message: none Special Character Rules: not applicable
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.
$MAX.OCC(occ,recovery,error)
- KEEP.FIRST -- Only the first "occ" occurrences of the element are retained.
- KEEP.LAST -- Only the last "occ" occurrences of the element are retained.
- DROP.ALL -- All of the occurrences of the element are dropped.
- KEEP.ALL -- All of the occurrences of the element are retained.
This proc will count the number of occurrences and, if there are more than four, a serious error will occur.
This proc will count the number of occurrences and, if there are more than three, all occurrences of the element will be dropped.
$MAX.OCC(occ,recov,err) -- A&err146:&recov,&occ ------------------------------------------------- occ Default: "1" recov Default: "3" KEEP.FIRST = "0" KEEP.LAST = "1" DROP.ALL = "2" KEEP.ALL = "3" err Default: "S" Default: $MAX.OCC = AS146:3,1
Purpose: Verify minimum length of value Used as: INPROC, SEARCHPROC Action Number: A23 Parallel System Functions: none Complementary System Procs: none Related System Procs: $MAX.LEN, $LENGTH Error Default: S Error Message: Value must be at least "length" characters Special Character Rules: not applicable
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.
$MIN.LEN(length,PAD,error,MSG)
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.
This proc would reject any value shorter than 5 characters. A serious error would occur.
$MIN.LEN(len,PAD,err,msgs) -- &msgs A&err23:&pad,&len ------------------------------------------------------- len Default: "1" pad Default: "0" PAD = "1" err Default: "S" msgs Default: "" MSG = "A56, 'Value must be at least &len characters'/" Default: $MIN.LEN = AS23:0,1
Purpose: Verify minimum number of occurrences Used as: INCLOSE Action Number: A123 Parallel System Functions: none Complementary System Procs: none Related System Procs: $OCC, $MAX.OCC, $DEFAULT Error Default: S Error Message: none Special Character Rules: "value" = rule set 1
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.
$MIN.OCC(occ,value,error)
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.
$MIN.OCC(occ,value,err) -- A&err123,'&value',&occ --------------------------------------------------- occ Default: "1" value Default: "" err Default: "S" Default: $MIN.OCC = AS123,'',1
Purpose: Provide user-defined error messages for later procs Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A56 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: "message" = rule set 1
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.
$MSG(message)
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.
In this example, error message "Value longer than 12 characters" will be displayed if any subsequent processing rule in the rule string fails.
$MSG(message) -- A56,'&message' --------------------------------- message Default: "Invalid value" Default: $MSG = A56,'Invalid value'
Purpose: Convert personal names to standard format Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A41 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PNAME Error Default: S Error Message: Invalid form of name Special Character Rules: not applicable
This proc will accept name values in any of the following forms:
First middle last,,title Winston Leonard Spencer Churchill,,Sir Last, first middle,title Churchill, Winston Leonard Spencer, Sir Middle last,first,title Leonard Spencer Churchill, Winston, Sir First last,,title Winston Churchill,,Sir Last,first,title Churchill, Winston, Sir Last,,title Churchill,,Sir
(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.
$NAME(order,error,MSG)
- FIRST.LAST -- Values will be converted to: First middle last,,title
- LAST.FIRST -- Values will be converted to: Last, first middle, title
- COMMA -- Any value input with a comma will be left as input. All other values will be converted as with LAST.FIRST.
- FIRST.SEARCH -- Values would be converted as with FIRST.LAST, but SEARCHPROCs would be added to allow truncated name searching, as described above.
- LAST.SEARCH -- Values would be converted as with LAST.FIRST, but the SEARCHPROCs mentioned above would be added.
- COMMA.SEARCH -- Values would be converted as with COMMA, but the SEARCHPROCs mentioned above would be added.
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.
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.
$NAME(order,err,MSG) -- &msg A&err41:&order --------------------------------------------- order Default: "1" FIRST.LAST = "0" LAST.FIRST = "1" COMMA = "2" FIRST.SEARCH = "0/ A11:1,'#'/ A13,' ,'" LAST.SEARCH = "1/ A11:1,'#'/ A13,' ,'" COMMA.SEARCH = "2/ A11:1,'#'/ A13,' ,'" FIRST.SRC = "0/ A11:1,'#'/ A13,' ,'" LAST.SRC = "1/ A11:1,'#'/ A13,' ,'" COMMA.SRC = "2/ A11:1,'#'/ A13,' ,'" err Default: "S" msg Default: "" MSG = "A56,'Invalid form of name'/" Default: $NAME = AS41:1
Purpose: Prevent element value from being passed Used as: PASSPROC Action Number: A169, A47, A52 Parallel System Functions: none Complementary System Procs: none Related System Procs: $DISCARD Error Default: none Error Message: none Special Character Rules: not applicable
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:
INDEX-NAME = REC03; SEARCHTERMS = DEPARTMENT.CODE; SEARCHPROC = $CAP; GOALREC-ELEM = DEPARTMENT.CODE; PASSPROC = $PASS; PTR-GROUP = POINTER; INDEX-NAME = REC03; SEARCHTERMS = DEPARTMENT; SEARCHPROC = $LOOKSUBG(REPLACE,REC02,DEPARTMENT.CODE); GOALREC-ELEM = DEPARTMENT.CODE; PASSPROC = $NOPASS; PTR-GROUP = POINTER;
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:
INDEX-NAME = REC10; SEARCHTERMS = DEPT.CODES; SEARCHPROC = $CAP; GOALREC-ELEM = DEPT.CODE; PASSPROC = $NOPASS; PTR-GROUP = POINTER;
$NOPASS
There are no parameters and no errors can occur.
$NOPASS -- A169:1/ A47:1,1/ A47,1/ A52
Purpose: Delete null values on passing; change value to null Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A52 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: not applicable
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.
$NULL(how)
- MNEM -- The element mnemonic is output.
- ELEM -- The element and mnemonic are not output at all.
- STR -- The element and the remainder of the structure containing the element is not output.
- REC -- The element and the remainder of the record containing the element is not output.
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.
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.
$NULL(how) -- A52:&how ---------------------------------- how Default: "0" MNEM = "0" ELEM = "1" STR = "2" REC = "3" Default: $NULL = A52:0
Purpose: Generate occurrence count of another element Used as: INCLOSE Action Number: A122 Parallel System Functions: none Complementary System Procs: $INT.OUT Related System Procs: $MIN.OCC, $MAX.OCC Error Default: none Error Message: none Special Character Rules: not applicable
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).
$OCC(element)
No errors can occur.
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:
INPROC = $INT(2)/ $OCC(DONATIONS);
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.)
$OCC(elem) -- A122,&elem -------------------------- elem Default: "0" Default: $OCC = A122,0
Purpose: Convert string value to packed decimal Used as: INPROC, SRCPROC Action Number: A39 Parallel System Functions: $PACK Complementary System Procs: $PACK.OUT, $EDIT, $DECIMAL.OUT Related System Procs: $DECIMAL, $WINDOW, $PRECISION, $PACK.TEST, $RANGE, $UNEDIT Error Default: S Error Message: Invalid packed value Special Character Rules: not applicable
$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:
... | d d | d d | d d | d s | exp |
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.
$PACK(type,length,error,MSG,style)
- CHAR -- The value is made up of the following characters: a sign (+ or -) possibly followed by a blank; numerals (0-9) for the "integer" portion; a decimal point; numerals for the "decimal" portion; the letter E (or "e", indicating that what follows is an exponent); a sign for the exponent (+, -- or _); and numerals for the exponent. All parts are optional, but there must be at least one numeral in the value. For example, 103, -65.32, +4E_54 and -7629304 are all legal values. If the value does not match the above description, the error flag is set. Note: Unless INT.ONLY is given as a value for "type" or "style" below, CHAR is in effect, even if you code STRIP or MAXLEN for "type".
- INT.ONLY -- The value may only be a positive or negative integer. No decimal portion or exponent may appear in the value, nor may the value be "infinity". Otherwise, the error flag is set.
- STRIP -- This symbol indicates that trailing zeroes for negative exponent values are removed after the value is adjusted; the exponent is raised accordingly. (By default, trailing zeroes in such cases are left on the value.) For example, the value 3.5000 would first be adjusted to 35000E_4. If STRIP were specified, the value to be stored would be changed to 35E_1. (The value 350.00 would become 350E0.) Each zero stripped raises the exponent by one; as long as the exponent created by this action will be less than or equal to zero, trailing zeroes are removed.
- MAXLEN -- This symbol indicates that the value should be stored in as short a length as possible, but if that length is longer than "length" (see below), the error flag should be set.
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.
$PACK(type,len,err,MSG,style) -- &msg A&err39:&type+&style,&len ----------------------------------------------------------------- type Default: "0" CHAR = "0" INT.ONLY = "1" STRIP = "2" MAXLEN = "4" len Default: "0" MAX = "0" err Default: "S" msg Default: "" MSG = "A56,'Invalid packed value'/" style Default: "0" CHAR = "0" INT.ONLY = "1" STRIP = "2" MAXLEN = "4" Default: $PACK = AS39:0+0,0
Purpose: Convert packed decimal value to string Used as: OUTPROC Action Number: A80 Parallel System Functions: $EDIT Complementary System Procs: $PACK Related System Procs: $EDIT, $DECIMAL, $WINDOW, $PRECISION Error Default: W Error Message: Invalid packed value Special Character Rules: not applicable
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,
Input value (exponential) Decimal-point output 1E_4 0.0001 12345678E_10 0.0012345678 12345E_3 12.345 100E_2 1.00
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:
Exponential format 100E_10 12345E3 -17E_17
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.
$PACK.OUT(strip,error,MSG)
- STRIP -- Leading zeroes are stripped.
- KEEP -- Leading zeroes are retained.
- EXP -- Except for infinity values, the element value will always be displayed in exponential format (with no leading zeroes).
The value, presumably stored as a packed decimal, will be converted to a string value. Leading zeroes will be deleted.
$PACK.OUT(strip,err,MSG) -- &msg A&err80:&strip ------------------------------------------------- strip Default: "0" STRIP = "0" KEEP = "1" EXP = "2" err Default: "W" msg Default: "" MSG = "A56,'Invalid packed value'/" Default: $PACK.OUT = AW80:0
Purpose: Test value (range) of packed decimal value Used as: INPROC, SEARCHPROC Action Number: A67 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PACK, $RANGE Error Default: S Error Message: none Special Character Rules: not applicable
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.
$PACK.TEST(how,value,error)
- EQ or "=" -- for "is equal to".
- NE or "~=" -- for "is not equal to".
- LT or "<" -- for "is less than".
- LE or "<=" -- for "is less than or equal to".
- GT or ">" -- for "is greater than".
- GE or ">=" -- for "is greater than or equal to".
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.
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.
$PACK.TEST(how,val,err) -- A&err67:&how,&val ---------------------------------------------- how Default: "=" EQ = "=" NE = "~=" LE = "<=" LT = "<" GE = ">=" GT = ">" val Default: "0" err Default: "S" Default: $PACK.TEST = AS67:=,0
Purpose: Handle paragraph or section numbers, special hierarchical numeric codes Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A54 Parallel System Functions: none Complementary System Procs: none Related System Procs: $INT, $INT.OUT Error Default: W Error Message: none Special Character Rules: not applicable
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.
$PARAGRAPH(fields,how,error,HALF)
- 0 (zero) -- Trailing zeroes are removed from the converted value; null values are allowed. Thus, "1.2" would be stored in two bytes; "1.2.0" would also be stored in two bytes. If "fields" is 3, both examples would be shorter than the allowed maximum.
- 1 -- All values will have the allowed number of "fields". Trailing zeroes are kept and, in fact, are added if the value would have fewer than the allowed number of "fields". Hence, if "fields" is 3 and "how" is 1, then the value "1.2" would be treated as "1.2.0". A null value would result in the appropriate number of "fields", all zeroes.
- 2 -- This is the same as "0" except that a null result is not possible. That is, a null value is handled as the value "0". Thus, the input value can never be smaller than one field.
- 0 -- Each field will consist of one or more digits.
- 1 -- Each field will consist of two or more fields, inserting leading zeroes as necessary to fill in.
- 2 -- Each field will consist of three or more digits, inserting leading zeroes as necessary to fill in.
- 3 -- Each field will consist of four or more digits, inserting leading zeroes as necessary to fill in.
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.
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.
$PARAGRAPH(fields,how,err,HALF) -- A&err54:&how&half,&fields ---------------------------------------------- fields Default: "1" how Default: "0" err Default: "W" half Default: "" HALF = "+8" Default: $PARAGRAPH = AW54:0,1
Purpose: Fetch values of single element for passing Used as: PASSPROC Action Numbers: A166, A169 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PASS.ELEM Error Default: none Error Message: none Special Character Rules: not applicable
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.
$PASS(type,what,OUT)
- ALPHA or UPPER -- The value will be forced to uppercase. This value is usually chosen if the element values are character strings, such as a name or address index.
- BINARY, NUMERIC or UPLOW -- The value will not be forced to uppercase. This value is usually chosen if the element values are numeric or coded (binary, floating-point or hex strings, for example).
- PHRASE -- If the element value will be passed to the index without being processed by $BREAK or $WORD (both A45) or $PNAME (A38), that is, if the index being passed to is neither a word or name index, then this value should be specified.
- BREAK or WORD -- If the element value will subsequently be processed by $BREAK, $WORD or some other version of A45, this value should be specified.
- NAME -- If the element value will subsequently be processed by $PNAME or some other form of A38, this value should be specified.
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.
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.
The element being passed to the index should not be "forced to uppercase" because it is not a character string.
$PASS(type,what,OUT) -- A&what:&type+&out ---------------------------------- type Default: "0" ALPHA = "0" UPPER = "0" UPLOW = "1" BINARY = "1" NUMERIC = "1" what Default: "169" PHRASE = "169" BREAK = "166" NAME = "166" WORD = "166" out Default: "0" OUT = "8" Default: $PASS = A169:0
Purpose: Pass element depending on value of another element Used as: PASSPROC Action Number: A163 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PASS.COND Error Default: none Error Message: none Special Character Rules: "passer" and "value" = rule set 3
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.
$PASS.BY(passer,element,relation,value)
- EQ -- "is equal to".
- NE -- "is not equal to".
- LT -- "is less than".
- LE -- "is less than or equal to".
- GT -- "is greater than".
- GE -- "is greater than or equal to".
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.
$PASS.BY(passer,elem,relation,value) -- A163:&relation, &value, &elem, &passer ---------------------------------------------------- passer Default: "" elem Default: "" relation Default: "~=" EQ = "=" NE = "~=" LT = "<" LE = "<=" GT = ">" GE = ">=" value Default: "" Default: $PASS.BY = A163:~=,,,
Purpose: Pass element depending on occurrence of another element Used as: PASSPROC Action Number: A168 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PASS.BY Error Default: none Error Message: none Special Character Rules: "elements" = rule set 3
This proc, which follows a $PASS or $PASS.ELEM proc, passes an element value depending on the occurrence or non-occurrence of another element.
$PASS.COND(elements,how)
- OCCUR -- If this value is specified, then the current element value will be passed if the second element has an occurrence. Otherwise, it will not be passed.
- NOOCCUR -- The opposite of OCCUR, this value specifies that the current element should not be passed if the second element has an occurrence. Otherwise, it will be passed.
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.
$PASS.COND(elems,how) -- A168:&how,&elems ------------------------------------------- elems Default: "" how Default: "0" OCCUR = "0" NOOCCUR = "1" Default: $PASS.COND = A168:0,
Purpose: Provide a default value for passing Used as: PASSPROC Action Number: A171 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: "value" = rule set 2
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.
$PASS.DEF(value)
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:
action system procs A32 $LOOKUP A55 $DECIMAL, $DECIMAL.ADJ, $SHIFT, $PRECISION, $WINDOW A59 $LOGICAL A62 $CALL A163 $PASS.BY A162 $PASS.UPPER A168 $PASS.COND
$PASS.DEF(value) -- A171,&value --------------------------------- value Default: "" Default: $PASS.DEF = A171,
Purpose: Pass multiple elements to single index Used as: PASSPROC Action Number: A167 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PASS, $PASS.UPPER Error Default: none Error Message: none Special Character Rules: "elements" = rule set 3
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).
$PASS.ELEM(elements,type,OUT)
- COMPOUND -- This value specifies that the index is a compound index. If so, then $PASS.ELEM(elements,COMPOUND) is the only PASSPROC allowed in the linkage section. (Note: this parameter defines the key of the index record, which should also be defined as FIXED with LEN=2.)
- PHRASE -- This value is coded if all the elements are character strings and they will not be processed later by $WORD, $BREAK, $PNAME or some other form of actions A45 or A38. The values will be converted to uppercase as they are passed.
- BREAK, NAME or WORD -- Any of these is chosen when the element values are being passed to a word or name index. All three have the same meaning for this proc. It is assumed that the values will thus be processed by one of the aforementioned forms of A38 or A45. The values will be converted to uppercase as they are passed.
- UPLOW, BINARY or NUMERIC -- These values function like PHRASE, but values are not converted to uppercase. Elements in integer, floating point or hex form, for instance, should use this value.
- BREAK.NUM -- This value functions like BREAK, but values are not converted to uppercase.
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.
$PASS.ELEM(elems,type,OUT) -- A167:&type&out,&elems --------------------------------------------- elems Default: "" type Default: "1" COMPOUND = "0" PHRASE = "1" BREAK = "2" NAME = "2" WORD = "2" UPLOW = "5" BINARY = "5" NUMERIC = "5" BREAK.NUM = "6" out Default: "" OUT = "+8" Default: $PASS.ELEM = A167:1,
Purpose: Delete delimited strings from passed value Used as: PASSPROC Action Number: A161 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: "start" and "stop" = rule set 2
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.
$PASS.FIELD(start,stop,type)
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:
$PASS.FIELD(start,stop,type)
For "type" ~= 0,
- 1 -- If "type" = 1, then the "start" string is deleted and the "stop" string is retained.
- 2 -- The "start" string is retained and the "stop" string is deleted.
- 3 -- Both "start" and "stop" strings are deleted.
- 4 -- Both "start" and "stop" strings are retained.
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.
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:
Input Value Output Value A/B/C AC A/B/C D/E/F AC DF A/B/C D/E AC D
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.)
$PASS.FIELD(start,stop,type) -- A161:&type,&start,&stop --------------------------------------------------------- start Default: "'/'" SLASH = "'/'" COMMA = "','" stop Default: "" SLASH = "'/'" COMMA = "','" type Default: "0" Default: $PASS.FIELD = A161:0,'/',
Purpose: Fetch the locator for passing Used as: PASSPROC Action Number: A170 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PASS.PTR Error Default: none Error Message: none Special Character Rules: not applicable
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.)
$PASS.LCTR
There are no parameters.
$PASS.LCTR -- A170
Purpose: Pass binary length of fetched element Used as: PASSPROC Action Number: A164 Parallel System Functions: $SIZE Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: none
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.
$PASS.LEN(how)
- BYTE -- The new value will be one byte long. The length of the element value may be from 0 to 255 characters; if it may be longer than that, you should use HALF.
- HALF -- The new value will be two bytes long. The length of the element value may be from 0 to 32,760 bytes long.
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.
$PASS.LEN(how) -- A164:&how ----------------------------- how Default: "1" BYTE = "1" HALF = "2" Default: $PASS.LEN = A164:1
Purpose: Pass nothing; or pass the occurrence number Used as: PASSPROC Action Number: A165 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PARAGRAPH Error Default: none Error Message: none Special Character Rules: not applicable
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:
- On the sub-index PASSPROC following the use of $PNAME (A38) by the previous PASSPROC.
- On a global QUAL-ELEM term that defines the same element as the previous linkage term. A typical case is following the PTR-ELEM term when A169 was used to pass the goal record key as the pointer back. The QUAL-ELEM allows this pointer to be used as a qualifier.
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.]
$PASS.OCC(occ)
- NULL -- This value indicates that no value will be passed, as explained earlier.
- BYTEONE or B1 -- This value indicates that the first counter should be incremented and that the passed value will be a one-byte integer.
- BYTETWO or B2 -- Similar to BYTEONE, this indicates that the second counter should be incremented.
- HALFONE or H1 -- This value indicates that the first counter should be incremented and the passed value will be a two-byte integer, which allows a much larger range of values.
- HALFTWO or H2 -- Similar to HALFONE, this indicates that the second counter should be incremented.
- ELEM -- This value, and the remaining values below, indicate that SPIRES should pass the occurrence number or numbers requested in relation to the last element passed in the current INDEX-NAME section. In particular, this value says that the occurrence number of the element itself should be passed; if the element is within a structure, the occurrence number of the element within the structure will be passed.
- S1 -- This value indicates that the occurrence number of the structure containing the element value just passed should be passed.
- S1.ELEM -- This value indicates that both numbers should be passed (see detail below).
- S2 -- The occurrence number of the structure (S2) containing the structure (S1) containing the element should be passed.
- S2.S1 -- The occurrence numbers of the structure containing the element and the structure containing it should be passed. Note that the occurrence numbers will be in the order in which they are specified by the symbol (i.e., S2, S1, and ELEM).
- S2.S1.ELEM -- The occurrence numbers of the element, the structure containing it, and the structure containing it, should be passed.
- S3 -- The occurrence number of the structure (S3) containing the structure (S2) containing the structure (S1) containing the element.
- S3.S2 and S3.S2.S1 and S3.S2.S1.ELEM -- The rest is up to you!
- PROX1 -- The passed value will be a 1-byte integer representing positional information about the word within the element value whose passing created this sub-index entry. It should only be used if the total number of words being passed to the word index per goal record will be 255 or less.
- PROX2 -- The passed value will be a 2-byte integer representing positional information about the word within the element value whose passing created this sub-index entry. It can support more than 65,000 words being passed to the word index per goal record.
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.
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.
$PASS.OCC(occ) -- A165:&occ ----------------------------- occ Default: "0" NULL = "0" B1 = "1" BYTEONE = "1" B2 = "3" BYTETWO = "3" H1 = "2" HALFONE = "2" H2 = "4" HALFTWO = "4" ELEM = "6" S1 = "7" S1.ELEM = "8" S2 = "9" S2.S1 = "10" S2.S1.ELEM = "11" S3 = "12" S3.S2 = "13" S3.S2.S1 = "14" S3.S2.S1.ELEM = "15" Default: $PASS.OCC = A165:0
Purpose: Convert some elements to uppercase before passing Used as: PASSPROC Action Number: A162 Parallel System Functions: none Complementary System Procs: none Related System Procs: $CAP, $UPPER, $CASE Error Default: none Error Message: none Special Character Rules: "elements" = rule set 3
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.
$PASS.UPPER(elements,type)
- INCLUDE -- The "elements" given are to be converted to uppercase before being indexed; all others in the $PASS.ELEM list should not.
- EXCLUDE -- The "elements" given are not to be converted to uppercase before being indexed; all others in the $PASS.ELEM list should be.
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.
$PASS.UPPER(elems,type) -- A162:&type,&elems ---------------------------------------------- elems Default: "" type Default: "0" INCLUDE = "0" EXCLUDE = "1" Default: $PASS.UPPER = A162:0,
Purpose: Convert value to phonetic code for searching Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC Action Number: A43, A36, A48 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PHONETIC.SEARCH Error Default: none Error Message: none Special Character Rules: not applicable
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.
$PHONETIC
There are no parameters and no errors can occur.
$PHONETIC -- A43,'!$%&''()-=@[]:+*./<>? AEIOUYBFPVCGJKQSXZDTHWLMNR', 'YYYYYYYYYYYYYYYYYYYYYYYYYYY22223333333344ZZ6778'/ A36:3,'X',0/ A48,Z8,8,XY,1,XZ,5,X,,',YY',',1',',YZ',',5'/ A48,Y,,Z,/ A48,222,2, 333,3, 444,4, 666,6, 777,7, 888,8, 22,2,33,3,44,4,66,6,77,7,88,8
Purpose: Convert personal name to phonetic code for searching Used as: SEARCHPROC Action Numbers: A41, A43, A36, A48, A11, A13 Parallel System Functions: none Complementary System Procs: none Related System Procs: $PHONETIC, $NAME Error Default: S Error Message: none Special Character Rules: not applicable
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.
$PHONETIC.SEARCH(order,error)
- FIRST.LAST -- The last name occurs last, i.e., "Huckleberry Hound".
- LAST.FIRST -- The last name occurs first, i.e., "Hound, Huckleberry".
- COMMA -- Any value input with a comma will be processed as input; otherwise, the value is put in LAST.FIRST order.
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.
$PHONETIC.SEARCH(order,err) -- A&err41:&order/ $phonetic/ A11:1,'#'/ A13,' ,' --------------------------------------- order Default: "1" FIRST.LAST = "0" LAST.FIRST = "1" COMMA = "2" err Default: "S" Default: $PHONETIC.SEARCH = AS41:1/ $PHONETIC/ A11:1,'#'/ A13,' ,'
Purpose: Convert personal names for indexing Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A38 Parallel System Functions: none Complementary System Procs: none Related System Procs: $NAME Error Default: D Error Message: none Special Character Rules: not applicable
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.
$PNAME(TRANS,how,error)
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.
- TRUNC (SEARCHPROC only) -- This value allows truncated searching using the pound sign (#) character. See the explanation for the $SEARCH.TRUNC proc for more information about truncated searching.
- SPECIAL (as a SEARCHPROC) -- If this value is specified as part of a Searchproc rule, then SPIRES will not do any special processing for first-name abbreviations. Hence, it will not find records having abbreviations when the search command contains full first names, nor will it find records with full first names when the search command contains abbreviations for them. For example, when SPECIAL is coded, the entries below marked "Yes" indicate that records with those indexed values would be retrieved when the given search value is requested:
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
- SPECIAL (as a PASSPROC) -- If this value is specified as part of a Passproc rule, then during passing, an additional "surname" and "remaining" part will be built if the input value contains one or more commas and more than one non-blank portion of the value precedes the first comma, as in "Vaughan Williams, Ralph". The additional value built will be comprised of the first non-blank portion of the value as the "surname" and all the non-blank portions following the first comma or up to the end of the value (whichever comes first) as the "remaining" part (e.g., the additional value would be "Vaughan" as the surname and "Ralph" as the "remaining" portion.
- 2 (SEARCHPROC only) -- When specified as part of a Searchproc rule, this value will retrieve records only if the search value consists solely of a last name that matches the indexed values, or if the search value exactly matches the indexed values:
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
$PNAME(TRANS,how,err) -- &trans A&err38:&how ---------------------------------------------- trans Default: "" TRANS = "A44,'''',/ A43,-.,' '/" how Default: "0" TRUNC = "0/ A14,#" SPECIAL = "1" err Default: "" Default: $PNAME = A38:0
Purpose: Specify precision of packed decimal values Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A55, A39 Parallel System Functions: $PRECISION Complementary System Procs: none Related System Procs: $PACK, $WINDOW, $DECIMAL, $EDIT Error Default: S Error Message: Invalid decimal value Special Character Rules: not applicable
"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:
Bytes = (Precision + 3) / 2
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).
$PRECISION(digits,error,MSG,PACK)
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).
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.
$PRECISION(digits,err,MSG,PACK) -- &msg &pack A&err55:4,&digits ----------------------------------------------------------------- digits Default: "13" err Default: "S" msg Default: "" MSG = "A56,'Invalid decimal value'/" pack Default: "" PACK = "A&ERR39,0/" Default: $PRECISION = AS55:4,13
Purpose: Support proximity searching, finding words next to or near each other Used as: SEARCHPROC Action Number: A17 Parallel System Functions: none Complementary System Procs: none Related System Procs: $BREAK, $EXCLUDE, $PASS.OCC, $SEARCH.TRUNC Error Default: S Error Message: none Special Character Rules: not applicable
$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".
$PROXIMITY
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:
W N Wn <- n is an integer from 0 to 9999 Nn <- n is an integer from 0 to 9999
$PROXIMITY -- AS17 --------------------
Purpose: Test maximum number of occurrences, move extras to other element Used as: INCLOSE Action Number: A147 Parallel System Functions: none Complementary System Procs: none Related System Procs: $MAX.OCC, $OCC, $REQUIRED Error Default: none Error Message: none Special Character Rules: not applicable
$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.
$PUTELEM(element,occ)
If more than two occurrences are input for the current element, the additional occurrences would be entered as values for EXTRA.DATES.
$PUTELEM(elem,occ) -- A147,&elem,&occ --------------------------------------- elem Default: "1" occ Default: "1" Default: $PUTELEM = A147,1,1
Purpose: Test range of binary or floating point value; test characteristics of packed decimal value Used as: INPROC, SEARCHPROC Action Number: A24, A26 Parallel System Functions: none Complementary System Procs: none Related System Procs: $INT, $REAL, $DOLLAR, $PACK, $DECIMAL, $PACK.TEST Error Default: S Error Message: none Special Character Rules: not applicable
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.)
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:
$RANGE(minimum,maximum,type,error)
- INT -- This indicates that the value to be tested is an integer and was probably converted to binary using the $INT or $DOLLAR proc. If this is used, the minimum value for "minimum" is -2,147,483,647; the maximum value for "maximum" is 2,147,483,647.
- REAL -- This indicates that the value to be tested is a real number and was probably converted to binary using the $REAL proc. If this is coded, the minimum value of "minimum" is -7.237E75; the maximum for "maximum" is 7.237E75.
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:
INPROC = $DOLLAR/ $RANGE(0,10000)
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.
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.
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:
$RANGE(minimum,maximum,type,error)
- DEC -- The range specifies the number of decimal places allowed in the input value. For example, $RANGE(0,2,DEC) means that the input value can have from 0 to 2 decimal places.
- EXP -- The range specifies the range of the exponent allowed for the input value. The maximum allowed range for the exponent of a packed value is -128 to 127.
- MAG -- The range specifies the allowed magnitude of the value. (Magnitude is defined as the sum of the value's exponent and its precision, which is defined below.)
- PRE -- The range specifies the allowed precision of the value. (Precision is defined as the number of digits in the value, beginning with the left-most non-zero digit and ending with the right-most digit, zero or not. For example, the value 14.7830 has a precision of 6. Since that value would be translated to 147830E_4 as a packed value, its magnitude would be 6 + (-4), or 2.)
- SIGN -- The range specifies the allowed sign of the value (i.e., whether the value can be positive or negative.). For this test, "minimum" and "maximum" must be an integer from -2 to 2 as follows:
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.
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.
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.
$RANGE(min,max,type,err) -- A&err2&type,&max,&min --------------------------------------------------- min Default: "0" max Default: "32767" type Default: "4" DEC = "4" EXP = "4:1" MAG = "4:2" PRE = "4:3" SIGN = "4:4" INT = "4" REAL = "6" err Default: "S" Default: $RANGE = AS24,32767,0
Purpose: Convert string value to floating-point Used as: INPROC, SEARCHPROC Action Number: A25 Parallel System Functions: $REAL Complementary System Procs: $REAL.OUT Related System Procs: $RANGE Error Default: S Error Message: Invalid floating-point value Special Character Rules: not applicable
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:
-7.237E75 <-- -5.4E-79 0 5.4E-79 --> 7.237E75
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.
$REAL(type,error,MSG)
- VERIFY -- The value is not converted, but it is verified to be a real number.
- SINGLE -- The value is converted to a single precision result of four bytes.
- DOUBLE -- The value is converted to a double precision result of eight bytes.
$REAL(type,err,MSG) -- &msg A&err25:&type ------------------------------------------- type Default: "1" VERIFY = "0" SINGLE = "1" DOUBLE = "2" err Default: "S" msg Default: "" MSG = "A56,'Invalid floating-point value'/" Default: $REAL = AS25:1
Purpose: Convert floating-point value to string Used as: OUTPROC Action Number: A72 Parallel System Functions: $STRING Complementary System Procs: $REAL Related System Procs: none Error Default: W Error Message: Value too long Special Character Rules: not applicable
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.
$REAL.OUT(type,length,frac,error,MSG)
- CONVERT -- All values are converted.
- NULL -- If a converted value is null, the error flag is set.
- STRIP -- Trailing zero digits in the fraction portion are stripped and the decimal point is stripped if the fraction consists of only zero digits.
- STRIP.NULL -- A combination of STRIP and NULL: both actions are taken.
$REAL.OUT(type,len,frac,err,MSG) -- &msg A&err72:&type,&len,&frac ------------------------------------------------------------------- type Default: "3" CONVERT = "0" NULL = "1" STRIP = "2" STRIP.NULL = "3" len Default: "9" frac Default: "2" err Default: "W" msg Default: "" MSG = "A56,'Value too long'/" Default: $REAL.OUT = AW72:3,9,2
Purpose: Forward search expression(s) to other index(es) Used as: SEARCHPROC Action Number: A7 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: S Error Message: none Special Character Rules: not applicable
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.
$REPARSE(error)
The linkage section for a reparsing index generally looks something like this:
INDEX-NAME = ZIN03; SEARCHTERMS = AT, AUTHOR.TITLE; SEARCHPROC = $CALL(PREP.TO.REPARSE)/ $REPARSE; PASSPROC = $NOPASS; PTR-GROUP = POINTER;
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:
FIND SUBJECT CHINA OR AT BUCK/GOOD EARTH
as if it were
FIND SUBJECT CHINA OR (AUTHOR BUCK AND TITLE GOOD EARTH)
rather than
FIND SUBJECT CHINA OR AUTHOR BUCK AND TITLE GOOD EARTH
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.
$REPARSE(error) -- A&err7 ------------------------- err Default: "S" Default: $REPARSE = AS7
Purpose: Verify/require exact number of occurrences, generate default values Used as: INCLOSE Action Numbers: A123, A146 Parallel System Functions: none Complementary System Procs: none Related System Procs: $MAX.OCC, $MIN.OCC, $DEFAULT Error Default: S Error Message: none Special Character Rules: not applicable
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.
$REQUIRED(occ,value,recovery,error)
- KEEP.FIRST -- Only the first specified number of occurrences are kept.
- KEEP.LAST -- Only the last specified number of occurrences are are kept.
- DROP.ALL -- All occurrences of the element are dropped.
- KEEP.ALL -- All occurrences input are retained.
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.
If more or fewer than two occurrences were input, a serious error would occur and the record would be rejected.
$REQUIRED(occ,value,recov,err) -- A&err123,'&value',&occ/ A&err146:&recov,&occ ----------------------------------------------------------- occ Default: "1" value Default: "" recov Default: "3" KEEP.FIRST = "0" KEEP.LAST = "1" DROP.ALL = "2" KEEP.ALL = "3" err Default: "S" Default: $REQUIRED = AS123,'',1/ AS146:3,1
Purpose: Restore value from temporary storage Used as: INPROC Action Number: A61 Parallel System Functions: none Complementary System Procs: $STORE Related System Procs: none Error Default: S Error Message: none Special Character Rules: not applicable
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.
$RESTORE(more,error)
- HOLD -- The value is retained in the save area for possible copying again later.
- RELEASE -- The save area is released after the value is restored.
$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.
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.
$RESTORE(more,err) -- A&err61:&more ------------------------------------- more Default: "1" HOLD = "1" RELEASE = "2" err Default: "S" Default: $RESTORE = AS61:1
Purpose: Truncate value from the left end Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A22 Parallel System Functions: $RSTR Complementary System Procs: $INSERT Related System Procs: $MAX.LEN, $LSTR, $XSTR Error Default: D Error Message: none Special Character Rules: not applicable
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.
$RSTR(length,recovery,error)
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.
$RSTR(len,recov,err) -- A&err22:&recov,&len --------------------------------------------- len Default: "1" recov Default: "5" KEEP.LAST = "2" DISCARD.FIRST = "3" DROP.FIRST = "5" DELETE.FIRST = "5" err Default: "" Default: $RSTR = A22:5,1
Purpose: Verify date value, convert to hexadecimal Used as: SEARCHPROC Action numbers: A70, A14, A44 (& A40, A30, A48 for $SEARCH.DATE.CC) Parallel System Function: $DATEIN Complementary System Procs: none Related System Procs: $DATE, $DATE.IN, $DATE.IN.CC Error Default: S Error Message: Invalid date Special Character Rules: not applicable
$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 two Searchprocs have the special truncated searching mechanism needed for flexible date searching built in, whereas $DATE needs the TRUNC option to be specified to get the same result;
- $SEARCH.DATE and $SEARCH.DATE.CC can handle turn-of-the-century issues that $DATE cannot. (See the century parameter below.)
The $SEARCH.DATE and $SEARCH.DATE.CC procs differ in these ways:
- Their parms are in a different order. If you want to add century-handling features to a plain $DATE(TRUNC) proc, $SEARCH.DATE.CC is easier to use. But if you have other options coded on $DATE(TRUNC), you may prefer to use $SEARCH.DATE.
- $SEARCH.DATE.CC incorporates NA (Not Applicable) handling into the proc; it is not requested through a separate parameter as it is on $DATE and $SEARCH.DATE.
- The two procs differ in their default handling of 2-character years for input: $SEARCH.DATE will assume the current century is meant, while $SEARCH.DATE.CC will set the error flag if the year is not entered as a 4-character value. But both can be changed.
$SEARCH.DATE(how,NA,error,MSG,century) $SEARCH.DATE.CC(century,how,error,MSG)
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.
- 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.
- ACCOUNTING -- This value is the same as CONVERT, but in addition allows the dates "August 32", "August 33" and "August 34" in any given year.
- ACCTG.EXACT -- This value is a combination of ACCOUNTING and EXACT.
- an integer from 1 to 99 -- SPIRES will supply "20" as the century if the two-digit year in the input value is less than this integer, but will supply "19" if it is greater than or equal to this integer. For example, if the integer is 50, then the input date "2/14/95" would be interpreted as a 1995 date, but "2/14/02" would be interpreted as a 2002 date.
- the integer "0" -- SPIRES will supply the current century at input time for the century portion of the year.
- CCYY -- If this literal value is coded, SPIRES will set the error flag if the input value does not contain a four-digit year; in other words, a value like "12/31/99" would cause an error, but "12/31/1999" would not.
- CC19 -- If this literal value is coded, SPIRES will always supply "19" as the century for two-digit years, even into the next century.
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:
7/1/1954 7/1/54 07/01/54 Thursday, July 1, 1954 Thursday, 1 July 1954 1-7-54 ("Canadian" dates) 1954.7.1 ("metric" dates) The 1st of July in '54 1st day of 7/54 (All of the above would be converted into #19540701#.) July 1954 7/54 7/--/54 (The above three samples would be converted into #19540700#.) 1954 54 (The above two samples would be converted into #19540000#.)
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:
today tomorrow yesterday +5 <- five days from today -3 <- three days ago Monday of this week Friday of last week Sunday of next week 10th of last month last day of this month January 1 of last year 7th of this month +6 <- 7th day of the 6th month from this one September of next year next month this year
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.
$SEARCH.DATE(how,NA,err,MSG,century) -- &msg &na A&err70:&how,¢ury/ A44,#0000#,#00#/ A14,#00# -------------------------------------------------------------------- how Default: "0" CONVERT = "0" VERIFY = "1" ACCOUNTING = "2" EXACT = "4" ACCTG.EXACT = "6" na Default: "" NA = "A40/ A30/ A48:8,'N/A','NA', 'NONE','NA', 'NA','09/09/9999'/" err Default: "S" msg Default: "" MSG = "A56,'Invalid date'/" century Default: "0" CC19 = "-1" CCYY = "-4" Default: $SEARCH.DATE = AS70:0,0/ A44,#0000#,#00#/ A14,#00# $SEARCH.DATE.CC(century,how,err,MSG) -- &msg A40/ A30/ A48:8,'n/ a','na', 'none','na', 'na','09/09/9999'/ A&err70:&how,¢ury/ A44,#0000#,#00#/ A14,#00# -------------------------------------------------------------------- century Default: "-4" CC19 = "-1" CCYY = "-4" how Default: "0" CONVERT = "0" VERIFY = "1" ACCOUNTING = "2" EXACT = "4" ACCTG.EXACT = "6" err Default: "S" msg Default: "" MSG = "A56,'Invalid date'/" Default: $SEARCH.DATE.CC = A40/ A30/ A48:8,'N/A','NA', 'NONE','NA', 'NA','09/09/9999'/ AS70:0,-4/ A44,#0000#,#00#/ A14, #00#
Purpose: Change default logical operator in searching Used as: SEARCHPROC Action Number: A6 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: not applicable
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.
$SEARCH.LOGOP(operator)
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".
$SEARCH.LOGOP(operator) -- A6:&operator -------------------------------------- operator Default: "1" OR = "0" AND = "1" NOT = "2" ANDNOT = "2" TOR = "4" TAND = "5" TNOT = "6" Default: $SEARCH.LOGOP = A6:1
Purpose: Override default search value processing; Keep relational operator as part of value Used as: SEARCHPROC Action Number: A9 Parallel System Functions: none Complementary System Procs: $BREAK, $WORD Related System Procs: none Error Default: none Error Message: none Special Character Rules: not applicable
$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".
$SEARCH.PHRASE(relop)
- WORDS -- The relational operators that are words will be treated as part of the value. Those operators are: BEFORE, AFTER, PREFIX, SUFFIX, WORD, STRING, HAVING, MASK and WITH.
- SYMBOLS -- The non-equality relational operators that are symbols will be treated as part of the value. Those operators are:
> >= < <= ~=
- WORDS.SYMBOLS -- A combination of WORDS and SYMBOLS.
Note that you cannot specify the equality operator ("=" or none).
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.
$SEARCH.PHRASE(relop) -- A9:&relop ------------------------------------ relop Default: "" WORDS = "1" SYMBOLS = "2" WORDS.SYMBOLS = "3"
Purpose: Provide default relational operator for special indexes Used as: SEARCHPROC Action Number: A12 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: none Error Message: none Special Character Rules: not applicable
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.
$SEARCH.QUAL(operator)
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.
$SEARCH.QUAL(operator) -- A12:&operator -------------------------------------- operator Default: "1" EQ = "1" NE = "2" GE = "3" LE = "4" GT = "5" LT = "6" BEFORE = "6" AFTER = "5" WITH = "9" STR = "10" STRING = "10" MASK = "11" HAVING = "12" PREFIX = "13" WORD = "14" SUFFIX = "15" Default: $SEARCH.QUAL = A12:1
Purpose: Process indirect searches of Prism routing files Used as: SEARCHPROC Action Numbers: A8, A9, A10, A36 Parallel System Functions: none Complementary System Procs: none Related System Procs: $LOOKSUBF, $SEARCH.SUBF Error Default: none Error Message: none Special Character Rules: rule set 1
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.
$SEARCH.ROUTE(form-id,'',searchterm,key.index.type,NOCHECK)
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.
$SEARCH.ROUTE(form-id,'',searchterm,key.index.type,NOCHECK) -- A9:3/ A36:3,'&searchterm ',0 / A36:0,' And form.id "&prismid/ &formname"',0 / &key.index.type &indirect.search,elr.ind-search.for.user.lookup,search.route --------------------------------------------------------------------- prismid Default: "" formname Default: "" searchterm Default: "" key.index.type Default: "A10/" SIMPLE = "" GOAL = "A10/" indirect.search Default: "A8:0" NOCHECK = "A8:2" Default: $SEARCH.ROUTE = A9:3/ A36:3,' ',0 / A36:0,' AND FORM.ID "/"',0 / A10/ A8:0,ELR.IND-SEARCH.FOR.USER.LOOKUP,SEARCH.ROUTE
Purpose: Process indirect searches Used as: SEARCHPROC Action Number: A8 Parallel System Functions: none Complementary System Procs: none Related System Procs: $LOOKSUBF Error Default: S Error Message: none Special Character Rules: "subfile" = rule set 1
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.
$SEARCH.SUBF(subfile,searchterm,option,error)
- LASTRULE -- specifies that the current search value should not be processed through the SEARCHPROC rule string coded for the indirect index as an index to the indirect goal. No further SEARCHPROC processing will be done to the search value. (See below.)
- NOCHECK -- specifies that when SPIRES returns from the indirect goal with keys, it will not check the tree of the current subfile to make certain that the record keys exist there. This makes the action more efficient, but is practical only in situations where you know for certain that any keys returned by the indirect search exist in the subfile. (Note, however, that SPIRES will still check the deferred queue of the current subfile for adds and removes; it just will not verify that the other keys are in the tree.)
- $SEARCH.SUBF is not the last proc in the SEARCHPROC string;
- $SEARCH.SUBF is coded in a SEARCHPROC string for anything but a simple index or a goal-index;
- $SEARCH.SUBF is used after $PNAME (action A38), or $BREAK, $BREAK.HEX, or $WORD (A45);
- $SEARCH.SUBF is coded after other SEARCHPROC rules involving truncated search, such as $SEARCH.TRUNC;
- the named subfile or searchterm cannot be found;
- the value processed by $SEARCH.SUBF is null.
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.
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.
$SEARCH.SUBF(subfile,term,option,err) -- A&err8:&option, '&subfile','&term' -------------------------------------------------------------- subfile Default: "" term Default: "" option Default: "0" LASTRULE = "1" NOCHECK = "2" err Default: "S"
Purpose: Allow truncated searching in index Used as: SEARCHPROC Action Number: A14, A11, A13 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: D Error Message: none Special Character Rules: "char" = rule set 2
$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.
$SEARCH.TRUNC(char,how,length,error)
- a character or character string, depending on the value of the "how" parameter. If a special character appears in this value, please see set 2 of the special character set rules. [See 1.4.2.]
- COMMA -- The delimiter is to be a comma.
- BLANK -- The delimiter is to be a blank. This value is only useful if SPECIAL is coded for "how".
- SPECIAL -- The search value will be composed of a string followed by the delimiter character followed by another string. The search result will contain all those values that begin with the first string in the search value and contain the second string somewhere following it (see example below).
- MATCH -- The search will not contain a delimiter character. The search result will contain all values that begin with the search value and continue with one of the characters in "char" (see example below).
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.
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.
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".
$SEARCH.TRUNC(char,how,len,err) -- A&err1&how:&len,&char ------------------------------------------------------- char Default: "#" BLANK = "' '" COMMA = "','" how Default: "4" SPECIAL = "1" MATCH = "3" len Default: "0" err Default: "" Default: $SEARCH.TRUNC = A14:0,#
Purpose: Rotationally shift characters within value Used as: INPROC, OUTPROC, PASSPROC, SEARCHPROC Action Number: A55 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: W Error Message: none Special Character Rules: not applicable
This proc will rotate the characters in a value a specified number of characters in a specified direction.
$SHIFT(length,how,error)
All characters within the value would be shifted 1 space to the left. The value S2K becomes 2KS; the value S4P becomes 4PS.
$SHIFT(len,how,err) -- A&err55:&how,&len ------------------------------------------ len Default: "1" how Default: "0" LEFT = "0" RIGHT = "1" err Default: "W" Default: $SHIFT = AW55:0,1
Purpose: Validate social insurance numbers and convert to binary Used as: INPROC, SEARCHPROC Action Number: A43, A44, A56, A22, A23, A21 Parallel System Functions: none Complementary System Procs: $SIN.OUT Related System Procs: $INT, $SSN Error Default: S Error Messages: SIN not 9 chars Invalid SIN Special Character Rules: not applicable
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.
$SIN(error)
$SIN(err) -- A43,'- ',#FF#/A44,#FF#,/ A56,'SIN not 9 chars'/ A&err22,9/ A&err23,9/ A56,'Invalid SIN'/ A&err21:4 ------------------------------------------------------------------ err Default: "S" Default: $SIN = A43,'- ',#FF#/A44,#FF#,/ A56,'SIN not 9 chars'/ AS22,9/ AS23,9/ A56,'Invalid SIN'/ AS21:4
Purpose: Convert binary value to social insurance number Used as: OUTPROC Action Number: A56, A71, A36 Parallel System Functions: none Complementary System Procs: $SIN Related System Procs: $INT.OUT, $SSN.OUT Error Default: W Error Messages: SIN too long Special Character Rules: not applicable
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.
$SIN.OUT(error)
$SIN.OUT(err) -- A56,'SIN too long'/ A&err71:1,9/ A36,'-',4/ A36,'-',8 -------------------------------------------------------------- err Default: "W" Default: $SIN.OUT = A56,'SIN too long'/ AW71:1,9/ A36,'-',4/ A36,'-',8
Purpose: Sort occurrences of element or structure Used as: INCLOSE Action Number: A138 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: S Error Message: none Special Character Rules: not applicable
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.
$SORT(how,error)
- DESCEND -- Values are sorted in descending order. Non-unique values are accepted.
- ASCEND -- Values are sorted in ascending order. Non-unique values are accepted.
- DESCEND.ELIM -- Values are sorted in descending order. "Extra copies" of non-unique values are eliminated.
- ASCEND.ELIM -- Values are sorted in ascending order. Extra copies of non-unique values are eliminated.
- DESCEND.ERR -- Values are sorted in descending order. Values that are not unique are retained, but the error flag is set.
- ASCEND.ERR -- Values are sorted in ascending order. Values that are not unique are retained, but the error flag is set.
- DESCEND.ELIM.ERR -- Values are sorted in descending order. Extra copies of non-unique values set the error flag, and they are eliminated.
- ASCEND.ELIM.ERR -- Values are sorted in ascending order. Extra copies of non-unique values set the error flag, and they are eliminated.
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.
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.
$SORT(how,err) -- A&err138:&how --------------------------------- how Default: "4" DESCEND = "0" ASCEND = "1" DESCEND.ELIM = "2" ASCEND.ELIM = "3" DESCEND.ERR = "4" ASCEND.ERR = "5" DESCEND.ELIM.ERR = "6" ASCEND.ELIM.ERR = "7" err Default: "S" Default: $SORT = AS138:4
Purpose: Squeeze out extra spaces, delete leading and trailing blanks Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A40 Parallel System Functions: none Complementary System Procs: none Related System Procs: $TRIM Error Default: D Error Message: none Special Character Rules: not applicable
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.
$SQU
There are no parameters, and no errors can occur.
$SQU -- A40
Purpose: Validate social security numbers and convert to binary Used as: INPROC, SEARCHPROC Action Numbers: A44, A40, A56, A22, A23, A21 Parallel System Functions: none Complementary System Procs: $SSN.OUT Related System Procs: $INT, $SIN Error Default: S Error Message: Invalid SSN Special Character Rules: not applicable
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.
$SSN(error,NOMSG)
$SSN(err) -- &nomsg A44,'-',/ A40/ A&err22,9/ A&err23,9/ A&err21:4 --------------------------------------------------------------- err Default: "S" nomsg Default: "A56,'Invalid SSN'/" NOMSG = "" Default: $SSN = A56,'Invalid SSN'/ A44,'-',/ A40/ AS22,9/ AS23,9/ AS21:4
Purpose: Convert binary value to social security number Used as: OUTPROC Action Numbers: A56, A71, A36 Parallel System Functions: none Complementary System Procs: $SSN Related System Procs: $INT.OUT, $SIN.OUT Error Default: W Error Message: SSN too long Special Character Rules: not applicable
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.
$SSN.OUT(error)
error (default = W) -- This symbolic parameter specifies the error level for the proc. [See 1.5.1.]
$SSN.OUT(err) -- A56,'SSN too long'/ A&err71:1,9/ A36,'-',4/ A36,'-',7 -------------------------------------------------------------- err Default: "W" Default: $SSN.OUT = A56,'SSN too long'/ AW71:1,9/ A36,'-',4/ A36,'-',7
Purpose: Save current value temporarily Used as: INPROC Action Number: A61 Parallel System Functions: none Complementary System Procs: $RESTORE Related System Procs: none Error Default: none Error Message: none
$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.
$STORE
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.
$STORE -- A61
Purpose: Separate value into elements of structure, or reverse Used as: INPROC, OUTPROC Action Number: A33 Parallel System Functions: none Complementary System Procs: none Related System Procs: $STRUC.IN, $STRUC.OUT Error Default: D Error Message: none Special Character Rules: "type" = rule set 3
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.)
$STRUC(type,error)
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:
element 1 of the structure = Dietrich (broken on blank) element 2 of the structure = Fischer (broken on '-') element 3 of the structure = Dieskau
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.
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).
$STRUC(type,err) -- A&err33,&type ----------------------------------- type Default: "J'-',X'\'" err Default: "" Default: $STRUC = A33,J'-',X'\'
Purpose: Separate value into elements of structure Used as: INPROC Action Numbers: A44, A33 Parallel System Functions: none Complementary System Procs: $STRUC.OUT Related System Procs: $STRUC Error Default: S Error Message: none Special Character Rules: "separator" = rule set 1
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:
TRANSACTION; DATE = 8/13/81; TIME = 8:45; AMOUNT = -$40.00;
you could enter it like this:
TRANSACTION = 8/13/81,8:45,-$40.00;
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.
$STRUC.IN(type,separator,error)
- any character or character string. If it contains any special characters, please see set 1 of the special character rules. [See 1.4.1.]
- BLANK -- If this value is specified, a single blank space will be the separator.
- COMMA -- If this value is specified, a comma will be the separator.
- SLASH -- If this value is specified, a slash (/) will be the separator.
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:
- no action A45 ($BREAK, $WORD) or A37 may appear in the INPROC;
- any A61 pair ($STORE/$RESTORE) must precede the $STRUC.IN proc, and the $RESTORE proc must clear the storage area.
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.
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.
$STRUC.IN(type,sep,err) -- A44,'&sep','\'/ A&err33,&type ---------------------------------------------------------- type Default: "J'\',X'\'" 2 = "J'\',X'\'" 3 = "J'\',J'\',X'\'" 4 = "J'\',J'\',J'\',X'\'" 5 = "J'\',J'\',J'\',J'\',X'\'" 6 = "J'\',J'\',J'\',J'\',J'\',X'\'" 7 = "J'\',J'\',J'\',J'\',J'\',J'\',X'\'" 8 = "J'\',J'\',J'\',J'\',J'\',J'\',J'\',X'\'" sep Default: ", " BLANK = " " COMMA = "," SLASH = "/" err Default: "S" Default: $STRUC.IN = A44,', ','\'/ AS33,J'\',X'\'
Purpose: Build elements of structure into single value Used as: OUTPROC Action Numbers: A44, A33 Parallel System Functions: none Complementary System Procs: $STRUC.IN Related System Procs: $STRUC Error Default: W Error Message: none Special Character Rules: "separator" = rule set 1
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.)
$STRUC.OUT(type,separator,error)
Possible values for "separator" are:
- a character or character string. If the character string contains any special characters, please see set 1 of the special character set rules. [See 1.4.1.]
- BLANK -- If this value is specified, a blank space will be inserted between each element of the output value.
- COMMA -- If this value is specified, a comma will be inserted between each element of the output value.
- SLASH -- If this value is specified, a slash (/) will be inserted between each element of the output value.
This example would output the four elements of a structure as a single value, with each individual element value separated by hyphens.
$STRUC.OUT(type,sep,err) -- A&err33,&type/ A44,'\','&sep' ----------------------------------------------------------- type Default: "J'\',X'\'" 2 = "J'\',X'\'" 3 = "J'\',J'\',X'\'" 4 = "J'\',J'\',J'\',X'\'" 5 = "J'\',J'\',J'\',J'\',X'\'" 6 = "J'\',J'\',J'\',J'\',J'\',X'\'" 7 = "J'\',J'\',J'\',J'\',J'\',J'\',X'\'" 8 = "J'\',J'\',J'\',J'\',J'\',J'\',J'\',X'\'" sep Default: ", " BLANK = " " COMMA = "," err Default: "W" Default: $STRUC.OUT = AW33,J'\',X'\'/ A44,'\',', '
Purpose: Extract string from within value Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A22 Parallel System Functions: $SUBSTR Complementary System Procs: none Related System Procs: $MAX.LEN Error Default: D Error Message: none Special Character Rules: not applicable
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.
$SUBSTR(skip,length,error)
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.
$SUBSTR(skip,len,err) -- A&err22:3,&skip/ A&err22:1,&len ------------------------------------------------------------ skip Default: "0" len Default: "0" err Default: "" Default: $SUBSTR = A22:3,0/ A22:1,0
Purpose: Verify value is in account-number form; compare value to logged-on account Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A53 Parallel System Functions: none Complementary System Procs: none Related System Procs: $GEN.ACCT Error Default: X (i.e., VD) Error Message: none Special Character Rules: not applicable
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.
$TEST.ACCT(what,error,METACCT)
- ANY -- SPIRES determines whether the first six characters fit the rules for the proper form of an account number. If the value breaks the rules, the error flag is set. The rules are:
- Of the six characters, the 3rd must be a period.
- The 1st and 4th must be alphabetic characters.
- The 2nd, 5th and 6th must be alphanumeric characters.
- GROUP -- This is the same as ANY, but with the additional allowance that the first six characters may be PUBLIC, or may be a "group or community specification"; that is, after alphabetic character 1, any one of the remaining characters and those that follow it in the account number can be periods. If the value breaks any of the rules, the error flag is set.
- LOGON -- SPIRES determines whether the first six characters match the currently logged-on account. If not, the error flag is set.
$TEST.ACCT(what,error,SHORT)
- MNEM -- Only the element mnemonic is output.
- ELEM -- The element is not output.
- STR -- The element and the remainder of the structure containing the element are not output.
- REC -- The element and the remainder of the record containing the element are not output.
- KEEP -- No action is taken, except for the error flag being set.
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.
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.
$TEST.ACCT(what,err,symbol) -- A&err53:&what+&symbol ------------------------------------------------------ what Default: "3" ANY = "1" GROUP = "2" LOGON = "3" MNEM = "0" ELEM = "1" STR = "2" REC = "3" KEEP = "4" err Default: "X" symbol Default: "0" METACCT = "4" SHORT = "8" Default: $TEST.ACCT = AX53:3
Purpose: Compare values with occurrences of another element Used as: INCLOSE Action Number: A133, A134 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: S Error Message: none Special Character Rules: not applicable
$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.
$TEST.ELEM(type,relop,element,error)
- EQ or "=" -- for "is equal to"
- NE or "~=" -- for "is not equal to"
- GT or ">" -- for "is greater than"
- GE or ">=" -- for "is greater than or equal to"
- LT or "<" -- for "is less than"
- LE or ">=" -- for "is less than or equal to"
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.
$TEST.ELEM(type,relop,elem,err) -- A&err13&type:&relop,&elem -------------------------------------------------------------- type Default: "4" LENGTH = "3" VALUE = "4" relop Default: "=" EQ = "=" NE = "~=" LE = "<=" LT = "<" GE = ">=" GT = ">" elem Default: "0" err Default: "S" Default: $TEST.ELEM = AS134:=,0
Purpose: Test length, and include or exclude value based on result Used as: PASSPROC, SEARCHPROC Action Number: A47 Parallel System Functions: none Complementary System Procs: none Related System Procs: $LEN, $MAX.LEN, $MIN.LEN Error Default: D Error Message: none Special Character Rules: not applicable
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.
$TEST.LEN(what,length)
- EX.LE -- All values less than or equal to the length value will be excluded.
- EX.GT -- All values greater than the length value will be excluded.
- IN.LE -- All values less than or equal to the length value will be included.
- IN.GT -- All values greater than the length value will be included.
In this example, only those values whose lengths are greater than five characters will be accepted. Anything shorter will be rejected.
$TEST.LEN(what,len,err) -- A&err47:&what,&len ----------------------------------------------- what Default: "0" EX.LE = "0" EX.GT = "1" IN.LE = "2" IN.GT = "3" len Default: "1" err Default: "" Default: $TEST.LEN = A47:0,1
Purpose: Test for occurrences of another element Used as: INCLOSE Action Number: A131, A132 or A140 Parallel System Functions: none Complementary System Procs: none Related System Procs: $OCC, $MAX.OCC, $MIN.OCC Error Default: S Error Message: none Special Character Rules: not applicable
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.
$TEST.OCC(element,type,error)
- SAME -- The current element must occur the same number of times as the specified element. If not, the error flag is set.
- NEITHER -- If neither the current element nor the specified element occur, then the error flag is set. This will ensure that at least one of the two elements occurs.
- BOTH -- If the specified element has no occurrences, but the current element does, the error flag is set. This guarantees that the current element can occur only if the second element has at least one occurrence. If the current element has no occurrences, no error occurs.
- EITHER -- If both the specified element and the current element occur, the error flag is set. If the current element has no occurrences, no error occurs.
- ONE.ONLY -- If both the specified element and the current element occur, the error flag is set, and the values for the current element are discarded. Note that the error level should be changed to D or W for this discard to have an effect; otherwise the element or record will be discarded anyway. If the current element has no occurrences, no error occurs.
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.
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.
$TEST.OCC(elem,type,err) -- A&err1&type,&elem ----------------------------------------------- elem Default: "0" type Default: "40" SAME = "31" NEITHER = "32" BOTH = "40" EITHER = "40:1" ONE.ONLY = "40:2" err Default: "S" Default: $TEST.OCC = AS140,0
Purpose: Verify uniqueness of occurrences within the record Used as: INCLOSE Action Number: A137 Parallel System Functions: none Complementary System Procs: none Related System Procs: $SORT Error Default: S Error Message: none Special Character Rules: not applicable
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.
$TEST.UNIQUE(element,type,error)
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.
$TEST.UNIQUE(err) -- A&err137 ------------------------------- err Default: "S" Default: $TEST.UNIQUE = AS137
Purpose: Validate time value and convert to hex or binary Used as: INPROC, SEARCHPROC, INCLOSE Action Numbers: A28, A128 Parallel System Functions: $TIMEIN Complementary System Procs: $TIME.OUT Related System Procs: $GEN.TIME Error Default: S Error Message: Invalid time Special Character Rules: not applicable
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.
$TIME(how,error,MSG)
- SECONDS.LAST -- The value is stored as a 2-byte hex value. The input time may be specified as seconds, as minutes and seconds, or as hours, minutes and seconds:
TIME = 3:01:26 FORM = Hours:Minutes:Seconds TIME = 1:26 FORM = Minutes:Seconds TIME = 26 FORM = Seconds
- HOURS.FIRST -- The value is stored as a 2-byte hex value. The time may be specified as hours, as hours and minutes, or as hours, minutes and seconds:
TIME = 3:01:26 FORM = Hours:Minutes:Seconds TIME = 3:01 FORM = Hours:Minutes TIME = 3 FORM = Hours
- INT.SECONDS.LAST -- The value is stored as a 4-byte integer. The input time may be specified as seconds, as minutes and seconds, or as hours, minutes and seconds:
TIME = 3:01:26 FORM = Hours:Minutes:Seconds TIME = 1:26 FORM = Minutes:Seconds TIME = 26 FORM = Seconds
- INT.HOURS.FIRST (or INT, for short) -- The value is stored as a 4-byte integer. The time may be specified as hours, as hours and minutes, or as hours, minutes and seconds:
TIME = 3:01:26 FORM = Hours:Minutes:Seconds TIME = 3:01 FORM = Hours:Minutes TIME = 3 FORM = Hours
- ADD -- This value makes the proc an INCLOSE. It is used as the proc for elements representing the time the record was added to the subfile. When a record is added that contains no value for the element, the current time will be provided (in the form HH:MM:SS) and converted for storage. If the record does contain a value for the element (e.g., when the value comes back when the record is updated), the value will not be changed. [See 1.5.3.] Input values are considered to be in HOURS.FIRST form. They are stored as 2-byte hex values.
- UPD -- This value also makes the proc an INCLOSE if it is used. The current time is provided as the element value, whether or not a value was provided. It is generally used for keeping track of the time that the record was last updated. [See 1.5.3.] The value is stored as a 2-byte hex value.
- INT.ADD -- This value makes the proc an INCLOSE. It is used as the proc for elements representing the time the record was added to the subfile. When a record is added that contains no value for the element, the current time will be provided (in the form HH:MM:SS) and converted for storage. If the record does contain a value for the element (e.g., when the value comes back when the record is updated), the value will not be changed. [See 1.5.3.] Input values are considered to be in HOURS.FIRST form. They are stored as 4-byte integers.
- INT.UPD -- This value also makes the proc an INCLOSE if it is used. The current time is provided as the element value, whether or not a value was provided. It is generally used for keeping track of the time that the record was last updated. [See 1.5.3.] The value is stored as a 4-byte integer.
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.:
Hours, hour, hr, HS ... minutes, minute, Mns ... Seconds, secs, scnds ...
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.
12 days, 11:20:00 PM (valid) 12:11:20:00 PM (invalid)
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.
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.
$TIME(how,err,MSG) -- &msg A&err28:&how ----------------------------------------- how Default: "1" HMS = "0" HM = "1" HMS.ADD = "0/ A128" HM.ADD = "1/ A128" HMS.UPD = "0/ A128:1" HOURS.FIRST = "1" SECONDS.LAST = "0" ADD = "1/ A128" UPD = "0/ A128:1" INT.HOURS.FIRST = "3" INT = "3" INT.SECONDS.LAST = "2" INT.ADD = "3/ A128" INT.UPD = "2/ A128:1" err Default: "S" msg Default: "" MSG = "A56,'Invalid time'/" Default: $TIME = AS28:1
Purpose: Convert hexadecimal or binary value to time format Used as: OUTPROC Action Number: A73 Parallel System Functions: $TIMEOUT Complementary System Procs: $TIME Related System Procs: $GEN.TIME Error Default: none Error Message: none Special Character Rules: not applicable
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.
$TIME.OUT(form,error)
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:
Unit Precision Days 8 Hours 7 Minutes 5 Seconds 3
$TIME.OUT(form,err) -- A&err73:&form -------------------------------------- form Default: "0" COLON.DHMS = "0" COLON.DHM = "1" COLON.DMS = "2" CLOCK.HMS = "3" CLOCK.HM = "4" CLOCK.H = "5" DHMS = "6" DHM = "7" DH = "8" DAYS = "9" HMS = "10" HOURS = "11" MS = "12" MINUTES = "13" SECONDS = "14" NONZERO.DHMS = "15" err Default: "W" Default: $TIME.OUT = AW73:0
Purpose: Convert characters to other characters Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A43 Parallel System Functions: none Complementary System Procs: none Related System Procs: $CHANGE, $CHANGE.HEX, $CHANGE.LIST, $TRANS.NULL Error Default: D Error Message: none Special Character Rules: "input","output" for $TRANS = rule set 1 "input","output" for $TRANS.HEX = rule set 2
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.
$TRANS(input,output,error) $TRANS.HEX(input,output,error)
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.
This example would change the hex character #00# to #40#.
$TRANS(input,output,err) -- A&err43,'&input','&output' -------------------------------------------------------- input Default: "," output Default: " " err Default: "" Default: $TRANS = A43,',',' '
$TRANS.HEX(input,output,err) -- A&err43,&input,&output -------------------------------------------------------- input Default: "','" output Default: "' '" err Default: "" Default: $TRANS.HEX = A43,',',' '
Purpose: Delete characters from the value Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A43, A44 Parallel System Functions: $CHANGE Complementary System Procs: none Related System Procs: $CHANGE, $CHANGE.LIST, $TRANS Error Default: D Error Message: none Special Character Rules: "input" = rule set 1 "trans" = rule set 2
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.
$TRANS.NULL(input,trans,error)
- a character string. If the string of characters contains any special characters, please see set 1 of the special character rules. [See 1.4.1.] Each character in the string will be changed to null.
- SPECIAL -- This symbol represents special characters. The complete list of characters included is shown below in the System Proc Expansion section.
- ALPHA -- All uppercase alphabetic characters will be deleted.
- NUMERIC -- All numerals will be deleted.
- BLANK -- All blanks will be deleted.
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.
$TRANS.NULL(input,trans,err) -- A&err43,'&input',&trans/ A&err44,&trans, ---------------------------------------------------------- input Default: "" SPECIAL = "''""^/\`:,<{[(|)]}>&~=;@!*#$%.+#-_?" ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" NUMERIC = "1234567890" BLANK = " " trans Default: "#FF#" err Default: D Default: $TRANS.NULL = A43,,#FF#/ A44,#FF#,
Purpose: Strip trailing blanks Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A51 Parallel System Functions: $TRIM Complementary System Procs: none Related System Procs: $SQU Error Default: none Error Message: none
$TRIM strips all blanks from the right end of the value.
$TRIM
There are no parameters and no errors can occur.
$TRIM -- A51
Purpose: Translate edited values for input Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A68 Parallel System Functions: $UNEDIT Complementary System Procs: $EDIT Related System Procs: $DOLLAR, $INT, $PACK, $DECIMAL, $REAL Error Default: none Error Message: none Special Character Rules: not applicable
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.
$UNEDIT
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:
Input value Output value $24.00 24.00 $ 5.00cr -5.00 1,462- -1462
$UNEDIT -- A68
Purpose: Augment record key to create a unique value Used as: INPROC Action Number: A35 Parallel System Functions: none Complementary System Procs: none Related System Procs: $AUGMENT Error Default: none Error Message: none Special Character Rules: "character" = rule set 1
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 with character strings, not integers.
- It is used primarily on keys that are strings of variable length.
- No parallel Outproc rule is needed to "reconvert" the augmented portion for display.
- The augmentation is done only when a special augmentation character appears at the end of the input value.
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.
$UNIQUE.KEY(character,type,length)
- BLANK -- If the word BLANK is coded, the augmentation character will be a blank (not recommended).
- COMMA -- If the word COMMA is coded, the augmentation character will be a comma.
- SLASH -- If the word SLASH is coded, the augmentation character will be a slash (/).
- NUM -- Numerals will be used, from 0 to 9.
- ALPHA -- Letters will be used, from A to Z.
- 1 -- 1-character augmentation (0-9, or A-Z)
- 2 -- 2-character augmentation (00-99, or AA-ZZ)
- 3 -- 3-character augmentation (000-999, or AAA-ZZZ)
- 4 -- 4-character augmentation (0000-9999, or AAAA-ZZZZ)
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.
Input key value Stored key value Successfully added --------------- ---------------- ------------------ ABCD ABCD yes ABCD# ABCD000 yes ABCD000 ABCD000 no - already there ABCD# ABCD001 yes ABCD899 ABCD899 yes ABCD# ABCD900 yes ABCD999 ABCD999 yes ABCD# -- no - S438 error ABCD0# ABCD0000 yes
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.
$UNIQUE.KEY(char,type,len) -- A35:&type+&len,'&char' ------------------------------------------------------ char Default: "#" BLANK = " " COMMA = "," SLASH = "/" type Default: "7" ALPHA = "3" NUM = "7" len Default: "1" Default: $UNIQUE.KEY = A35:7+1,'#'
Purpose: Convert lowercase characters to uppercase Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A30 Parallel System Functions: $CAP, $CASE Complementary System Procs: none Related System Procs: $LOWER, $CAP, $CASE Error Default: none Error Message: none Special Character Rules: not applicable
This proc converts all lowercase characters to uppercase.
$UPPER
There are no parameters and no errors can occur.
$UPPER -- A30
Purpose: Verify characters in value are a specific type Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A49 Parallel System Functions: none Complementary System Procs: none Related System Procs: none Error Default: S Error Message: none Special Character Rules: "chars","more" = rule set 1
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.
$VERIFY(type,chars,more,error)
- LIKE -- The characters in the input value must all be in the specified group; if not, the error flag is set.
- UNLIKE -- The characters in the input value must not be in the specified group; if any is, the error flag is set.
- any character string. If special characters are included, see set 1 of the special character rules. [See 1.4.1.] Remember that case is significant if you code your own string.
- ALPHA -- This value represents alphabetic characters. Only uppercase characters are matched, so if the input value may contain lowercase letters, you should precede this proc with a $CAP proc.
- NUMERIC -- This value represents numerals: "1234567890".
- ALPHA.NUMERIC -- This value represents alphabetic and numeric characters. Again, alphabetic characters must be in uppercase to match.
- HEX -- This value represents the characters used to specify hexadecimal values. The allowed characters are "1234567890ABCDEF".
- BLANKS -- This value represents blanks.
- SPECIAL -- This value represents special characters. The characters are: " '"^/\`:,<{[(|)]}>&~=;@!*#$%.+#-_?"
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.
This example would accept only input values containing only alphabetic characters. If the value "BC3" were input, a serious error would occur.
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.
$VERIFY(type,chars,more,err) -- A&err49:&type,'&chars&more' ------------------------------------------------------------- type Default: "0" LIKE = "0" UNLIKE = "1" chars Default: "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ALPHA.NUMERIC = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890" NUMERIC = "1234567890" HEX = "1234567890ABCDEF" BLANKS = " " SPECIAL = " ''"^/\`:,<{[(|)]}>&~=;@!*#$%.+#-_?" more Default: "" ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ALPHA.NUMERIC = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890" NUMERIC = "1234567890" HEX = "1234567890ABCDEF" BLANKS = " " SPECIAL = " ''"^/\`:,<{[(|)]}>&~=;@!*#$%.+#-_?" err Default: "S" Default: $VERIFY = AS49:0,'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
Purpose: Verify characters in substring of value Used as: INPROC Action Number: A66 Parallel System Functions: none Complementary System Procs: none Related System Procs: $VERIFY Error Default: S Error Message: none Special Character Rules: "list" = rule set 3
The $VERIFY.SUBSTR proc is used in either of two ways:
- to verify that a character at a certain column within the input value either matches or does not match a character in a list of characters; or
- to verify that a substring of the value (beginning at a certain column) matches a string in a list of strings.
The "type" parameter determines which way the proc will work.
$VERIFY.SUBSTR(column,how,type,list,error)
- ALPHA -- This value represents alphabetic characters. Only uppercase characters are matched, so if the input value may contain lowercase letters, you should precede this proc with a $CAP proc.
- NUMERIC -- This value represents numerals: "1234567890".
- ALPHA.NUMERIC -- This value represents alphabetic and numeric characters. Again, alphabetic characters must be in uppercase to match.
- HEX -- This value represents the characters used to specify hexadecimal values. The allowed characters are "1234567890ABCDEF".
- BLANKS -- This value represents blanks.
- SPECIAL -- This value represents special characters. The characters are: " '"^/\`:,<{[(|)]}>&~=;@!*#$%.+#-_?"
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.
SPIRES will verify that the third character in the value is an uppercase alphabet character. If it is not, a serious error will occur.
SPIRES will verify that the third character in the value is a period. If it is not, a warning error will occur.
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.
$VERIFY.SUBSTR(col,how,type,list,err) -- A&err66:&how+&type, &col,&list -------------------------------------------------------------- col Default: "1" how Default: "1" UNLIKE = "0" LIKE = "1" type Default: "0" CHAR = "0" STRING = "2" list Default: "'ABCDEFGHIJKLM','NOPQRSTUVWXYZ'" ALPHA = "'ABCDEFGHIJKLM','NOPQRSTUVWXYZ'" ALPHA.NUMERIC = "'ABCDEFGHIJKLM','NOPQRSTUVWXYZ', '1234567890'" NUMERIC = "'1234567890'" HEX = "'1234567890ABCDEF'" BLANK = "' '" SPECIAL = "'"^/\`:,<{[(|)]','}>&~=;@!*$%.?+#', '-_'' '" err Default: "S" Default: $VERIFY.SUBSTR = AS66:1+0,1,'ABCDEFGHIJKLM', 'NOPQRSTUVWXYZ'
Purpose: Limit precision of packed decimal values Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A55, A39 Parallel System Functions: $WINDOW Complementary System Procs: none Related System Procs: $PACK, $PRECISION, $DECIMAL, $EDIT Error Default: S Error Message: Invalid decimal value Special Character Rules: not applicable
"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:
Bytes = (Precision + 3) / 2
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.
$WINDOW(digits,error,MSG,PACK)
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.
$WINDOW(digits,err,MSG,PACK) -- &msg &pack A&err55:5,&digits -------------------------------------------------------------- digits Default: "13" err Default: "S" msg Default: "" MSG = "A56,'Invalid decimal value'/" pack Default: "" PACK = "A&ERR39,0/" Default: $WINDOW = AS55:5,13
Purpose: Separate value into individual occurrences at blanks Used as: INPROC, SEARCHPROC, PASSPROC Action Number: A43, A44, A45 Parallel System Functions: none Complementary System Procs: none Related System Procs: $BREAK, $TEST.LEN, $EXCLUDE Error Default: none Error Message: none Special Character Rules: "chars" = rule set 1
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.
$WORD(chars,BREAK.HYPHEN)
- PASS -- This set of characters consists of almost all special characters on the keyboard, with the exception of the apostrophe and underscore characters, which are treated specially as described above. The list of characters is shown in the "System Proc Expansion" below.
- SEARCH -- This is the same set of special characters as PASS, except that the pound sign, often used in search requests to indicate truncated searching (if allowed by the SEARCHPROC), is not included.
- a character string. You may specify your own set of special characters for this parameter if you want. See set 1 of the special character set rules for details on coding. [See 1.4.1.]
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.
$WORD(chars,hyphen) -- &hyphen A43,'''-','_'/ A44,'_',/ A43,'&chars',' '/ Aw45, ------------------------------------------------- chars Default: ""^/\`:,<{[(|)]}>&~=;@!*$%.?+#" PASS = ""^/\`:,<{[(|)]}>&~=;@!*$%.?+#" SEARCH = ""^/\`:,<{[(|)]}>&~=;@!*$%.?+" hyphen Default: "" BREAK.HYPHEN = "A43,'-',' '/" Default: $WORD = A43,'''-','_'/ A44,'_',/ A43,'"^/\`:, <{[(|)]}>&~=@!*$%.?+#',' '/ AW45,
Purpose: Truncate value Used as: INPROC, OUTPROC, SEARCHPROC, PASSPROC Action Number: A22 Parallel System Functions: $XSTR Complementary System Procs: $INSERT Related System Procs: $MAX.LEN, $LSTR, $RSTR Error Default: D Error Message: none Special Character Rules: not applicable
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.
$XSTR(length,recovery,error)
- KEEP.FIRST (default) -- If the value is longer than the specified number of characters, then the "extra" characters are removed from the right end of the value; also the error flag is set. If the value is the specified length or shorter, the value is left unchanged. (This is the same as the $LSTR proc.)
- KEEP.LAST -- If the value is longer than the specified number of characters, then the "extra" characters are removed from the left end of the value; also the error flag is set. If the value is the specified length or shorter, the value is left unchanged.
- DROP.FIRST or DELETE.FIRST -- The specified number of characters are dropped from the beginning of the value, even if the value is the specified length or shorter; the error flag is not set. (This is the same as the $RSTR proc.)
- DROP.LAST or DELETE.LAST -- The specified number of characters are dropped from the end of the value, even if the value is the specified length or shorter; the error flag is not set.
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.
$XSTR(len,recov,err) -- A&err22:&recov,&len --------------------------------------------- len Default: "1" recov Default: "1" KEEP.ALL = "0" KEEP.FIRST = "1" KEEP.LAST = "2" DISCARD.FIRST = "3" DISCARD.LAST = "4" DROP.FIRST = "5" DROP.LAST = "6" DELETE.FIRST = "5" DELETE.LAST = "6" err Default: "" Default: $XSTR = A22:1,1
Purpose: Test and convert Yes/No values for storage Used as: INPROC, OUTPROC, SEARCHPROC Action Number: A40, A30, A48, A46 Parallel System Functions: none Complementary System Procs: $YESNO.OUT Related System Procs: none Error Default: S Error Message: Value not Yes or No Special Character Rules: not applicable
$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.
$YESNO(error,MSG)
$YESNO(err,MSG) -- A40/ A30/ &msg A48:8,YES,Y, YE,Y, OK,Y, NO,N/ A&err46:3,Y,N ------------------------------------------------------------------ err Default: "S" msg Default: "" MSG = "A56,'Value not Yes or No'/" Default: $YESNO = A40/ A30/ A48:8,YES,Y, YE,Y, OK,Y, NO,N/ AS46:3,Y,N
Purpose: Convert stored Yes/No values for output Used as: OUTPROC Action Number: A48 Parallel System Functions: none Complementary System Procs: $YESNO Related System Procs: none Error Default: W Error Message: none Special Character Rules: not applicable
$YESNO.OUT converts the values Y and N, probably input with the $YESNO proc, to "Yes" or "No" for output.
$YESNO.OUT(error)
$YESNO.OUT(err) -- A&err48,Y,Yes, N,No ---------------------------------------- err Default: "W" Default: $YESNO.OUT = AW48,Y,Yes, N,No
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.
Action System Proc Other Actions ------ ----------- ------------- A6 $SEARCH.LOGOP A7 $REPARSE A8 $SEARCH.ROUTE (A9,A10,A36) A8 $SEARCH.SUBF A9 $SEARCH.PHRASE A9 $SEARCH.ROUTE (A8,A10,A36) A10 $GOAL.INDEX A10 $SEARCH.ROUTE (A8,A9,A36) A11 $SEARCH.TRUNC (A14,A13) A11 $PHONETIC.SEARCH (A41,A43,A36,A48,A13) A12 $SEARCH.QUAL A13 $SEARCH.TRUNC (A14,A11) A13 $PHONETIC.SEARCH (A41,A43,A36,A48,A11) A14 $SEARCH.TRUNC (A11,A13) A14 $DATE (A31,A126) A14 $SEARCH.DATE (A44,A70) A14 $SEARCH.DATE.CC (A30,A40,A44,A48,A70) A15 $FIND (A16) A16 $FIND (A15) A17 $PROXIMITY A21 $INT A21 $SIN (A43,A44,A56,A22,A23) A21 $SSN (A44,A40,A56,A22,A23) A22 $LSTR A22 $MAX.LEN A22 $SUBSTR A22 $LENGTH (A23) A22 $FIXED.NUM (A23,A49) A22 $RSTR A22 $SIN (A43,A44,A56,A23,A21) A22 $SSN (A44,A40,A56,A23,A21) A22 $XSTR A23 $MIN.LEN A23 $LENGTH (A22) A23 $FIXED.NUM (A22,A49) A23 $SIN (A43,A44,A56,A22,A21) A23 $SSN (A44,A40,A56,A22,A21) A24 $RANGE (A26) A25 $REAL A26 $RANGE (A24) A27 $CHECK A28 $TIME (A128) A29 $HEX A30 $CAP A30 $LOOKSYS (A65) A30 $LOWER A30 $UPPER A30 $YESNO (A40,A48,A46) A30 $BG (A48) A30 $DATE.IN.CC (A40,A48,A70) A30 $SEARCH.DATE.CC (A14,A40,A44,A48,A70) A31 $DATE (A14,A126) A32 $LOOKSUBG A33 $STRUC A33 $STRUC.IN (A44) A33 $STRUC.OUT (A44) A35 $AUGMENT A35 $UNIQUE.KEY A36 $ADJUST A36 $DECIMAL.ADJ (A55) A36 $INSERT A36 $INSETL A36 $INSETR A36 $PHONETIC.SEARCH (A41,A43,A48,A11,A13) A36 $PHONETIC (A43,A48) A36 $SEARCH.ROUTE (A8,A9,A10) A36 $SIN.OUT (A56,A71) A36 $SSN.OUT (A56,A71) A38 $PNAME A39 $PACK A39 $PRECISION (A55) A39 $WINDOW (A55) A40 $SQU A40 $YESNO (A30,A48,A46) A40 $SSN (A44,A56,A22,A23,A21) A40 $COMPRESS (A57) A40 $DATE.IN.CC (A30,A48,A70) A40 $SEARCH.DATE.CC (A14,A30,A44,A48,A70) A41 $NAME A41 $PHONETIC.SEARCH (A43,A36,A48,A11,A13) A42 $DOLLAR A43 $BOLD A43 $ITALIC A43 $TRANS A43 $TRANS.HEX A43 $PHONETIC (A36,A48) A43 $PHONETIC.SEARCH (A41,A36,A48,A11,A13) A43 $SIN (A44,A56,A22,A23,A21) A43 $TRANS.NULL (A44) A43 $WORD (A44,A45) A44 $CHANGE A44 $CHANGE.HEX A44 $SEARCH.DATE (A14,A70) A44 $SEARCH.DATE.CC (A14,A30,A40,A48,A70) A44 $STRUC.IN (A33) A44 $STRUC.OUT (A33) A44 $SIN (A43,A56,A22,A23,A21) A44 $SSN (A40,A56,A22,A23,A21) A44 $TRANS.NULL (A43) A44 $WORD (A43,A45) A45 $BREAK A45 $BREAK.HEX A45 $WORD (A43,A44) A46 $ENCODE A46 $EXCLUDE A46 $INCLUDE A46 $YESNO (A30,A40,A48) A47 $TEST.LEN A47 $NOPASS (A169,A52) A48 $CHANGE.LIST A48 $YESNO.OUT A48 $BG (A30) A48 $YESNO (A40,A30,A46) A48 $PHONETIC.SEARCH (A41,A43,A36,A11,A13) A48 $PHONETIC (A43,A36) A48 $DATE.IN.CC (A30,A40,A70) A48 $SEARCH.DATE.CC (A14,A30,A40,A44,A70) A49 $VERIFY A49 $FIXED.NUM (A22,A23) A50 $BITS A51 $TRIM A52 $NULL A52 $NOPASS (A169,A47) A53 $TEST.ACCT A54 $PARAGRAPH A55 $DECIMAL A55 $DECIMAL.ADJ (A36) A55 $SHIFT A55 $PRECISION (A39) A55 $WINDOW (A39) A56 $MSG A56 $SIN (A43,A44,A22,A23,A21) A56 $SIN.OUT (A71,A36) A56 $SSN (A44,A40,A22,A23,A21) A56 $SSN.OUT (A71,A36) A57 $COMPRESS (A40) A58 $EXPAND A59 $LOGICAL A60 $ENCRYPT A61 $RESTORE A61 $STORE A62 $CALL (A124) A65 $LOOKSUBF A65 $LOOKSYS (A30) A66 $VERIFY.SUBSTR A67 $PACK.TEST A68 $UNEDIT A69 $EVAL A70 $DATE.IN A70 $DATE.IN.CC (A40,A30,A48) A70 $SEARCH.DATE (A44,A14) A70 $SEARCH.DATE.CC (A40,A30,A48,A44,A14) A71 $INT.OUT A71 $SIN.OUT (A56,A36) A71 $SSN.OUT (A56,A36) A72 $REAL.OUT A73 $TIME.OUT A74 $HEX.OUT A75 $DECODE A77 $CHECK.OUT A79 $GETELEM A80 $DECIMAL.OUT A80 $PACK.OUT A81 $DOLLAR.OUT A82 $BUILD A85 $EDIT A86 $DATE.OUT A86 $DATE.OUT.CC (A44) A122 $OCC A123 $DEFAULT A123 $MIN.OCC A123 $REQUIRED (A146) A124 $CALL (A62) A125 $CHECK (A27) A125 $INT (A21) A126 $GEN.DATE A126 $DATE (A31,A14) A127 $GEN.ACCT A128 $GEN.TIME A128 $TIME (A28) A129 $DEFAULT.COND A131 $TEST.OCC (A132,A140) A132 $TEST.OCC (A131,A140) A133 $TEST.ELEM (A134) A134 $TEST.ELEM (A133) A137 $TEST.UNIQUE A138 $SORT A140 $TEST.OCC (A131,A132) A146 $MAX.OCC A146 $REQUIRED (A123) A146 $DISCARD A147 $PUTELEM A161 $PASS.FIELD A162 $PASS.UPPER A163 $PASS.BY A164 $PASS.LEN A165 $PASS.OCC A166 $PASS (A169) A167 $PASS.ELEM A168 $PASS.COND A169 $PASS (A166) A169 $NOPASS (A47,A52) A170 $PASS.LCTR A171 $PASS.DEF
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.
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
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
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
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
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
I,O,S $BITS Convert numbers to bits and vice versa I,O,S,P $LOGICAL Manipulate bits in value using logical operator
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, 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
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
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
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
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
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
I,O,S $YESNO Test and convert Yes/No values for storage O $YESNO.OUT Convert stored Yes/No values for output
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
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
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
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
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
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
O $BG Translate characters for banner character set O $BOLD Translate characters for bold character set O $ITALIC Translate characters for italic character set
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
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
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
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.
I,O,S,P $ADJUST Adjust packed decimal value to have a fixed length I,O,S $AUGMENT Augment record key to create a unique value O $BG Translate characters for banner character set I,O,S $BITS Convert numbers to bits and vice versa O $BOLD Translate characters for bold character set 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,O,S,P,IC $CALL Call a user-defined processing rule 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 $CHECK Convert numeric string to binary; verify check digit O $CHECK.OUT Convert binary to character string, append check digit I,O,S $COMPRESS Compress string values to save storage space 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 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 $DECODE Convert stored symbol to string 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 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,O,S $ENCRYPT Encrypt values for security I,O,S,P $EVAL Evaluate user-defined expression I,O,S,P $EXCLUDE Discard values in list I,O,S $EXPAND Reconvert compressed strings for output S $FIND Retrieve higher or lower value if requested value not indexed I, S $FIXED.NUM Test for numeric string of a specified length 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 O $GETELEM Concatenate value of another element to output value I $GOAL.INDEX Use goal record-type as index I, S $HEX Convert string value to hexadecimal O $HEX.OUT Convert hexadecimal value to string 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 I, S $INT Convert character string to binary O $INT.OUT Convert binary value to character string O $ITALIC Translate characters for italic character set I, S $LENGTH Verify value is a specific length I,O,S,P $LOGICAL Manipulate bits in value using logical operator; convert real or integer values for indexing 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 I,O,S $LOWER Convert uppercase characters to lowercase I,O,S,P $LSTR Truncate value at given length I,O,S,P $MAX.LEN Verify maximum length of value IC $MAX.OCC Verify maximum number of occurrences I, S $MIN.LEN Verify minimum length of value IC $MIN.OCC Verify minimum number of occurrences I,O,S $MSG Provide user-defined error messages for later procs I,O,S $NAME Convert personal names to standard format P $NOPASS Prevent element value from being passed I,O,S,P $NULL Delete null values on passing; change value to null IC $OCC Generate occurrence count of another element 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 $PARAGRAPH Handle paragraph numbers, special numeric codes 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 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 indexing I,O,S,P $PRECISION Specify precision of packed decimal values S $PROXIMITY Use for proximity searching, finding words next to or near each other IC $PUTELEM Test maximum number of occurrences, move extras to other element I, S $RANGE Test range of binary or floating point value; test characteristics of packed decimal value I, S $REAL Convert string value to floating-point O $REAL.OUT Convert floating-point value to string S $REPARSE Forward search expression(s) to other indexes IC $REQUIRED Verify exact number of occurrences, generate default values I $RESTORE Restore value from temporary storage I,O,S,P $RSTR Truncate value from left end 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 I,O,S,P $SHIFT Rotationally shift characters within value I, S $SIN Validate social insurance number and convert to binary O $SIN.OUT Convert binary value to social insurance number IC $SORT Sort occurrences of element or structure I,O,S,P $SQU Squeeze out extra spaces, delete leading and trailing blanks and convert to binary I, S $SSN Validate social security number and convert to binary O $SSN.OUT Convert binary value to social security number I $STORE Save current value temporarily 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 I,O,S,P $SUBSTR Extract string from within value I,O,S $TEST.ACCT Verify value is in account-number form; compare value to logged- on account IC $TEST.ELEM Compare values with occurrences of another element S,P $TEST.LEN Test length, and include or exclude value based on result IC $TEST.OCC Test for occurrences of another element 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 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 $UNEDIT Translate edited values for input I $UNIQUE.KEY Augment record key to create a unique value 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,O,S,P $WINDOW Limit precision of packed decimal values I, S,P $WORD Separate value into individual occurrences at blanks I,O,S,P $XSTR Truncate value I,O,S $YESNO Test and convert Yes/No values for storage O $YESNO.OUT Convert stored Yes/No values for output
(The following documents are not SPIRES documents per se, but describe utilities and programs that may be useful in developing SPIRES applications.)
The above documents (except any marked "in preparation") may be obtained through the PUBLISH command on the Forsythe computer at Stanford University. If you do not use SPIRES at Stanford, contact your local system administrator to find out how SPIRES documents are made available there.
SPIRES manuals are updated regularly as changes are made to the system. This does not mean that all manuals are out of date with each new version of SPIRES. The changes to the documentation match those made to SPIRES: they are usually minor and/or transparent. Not having the most current version of a manual may mean you do not have all the most recent information about all the latest features, but the information you do have will usually be accurate.
A public subfile, SPIRES DOC NOTES, contains information about changes to SPIRES manuals. Using this subfile, you can determine whether the manual you have has been updated and if so, how significant those updates are. You need to know the date your manual was published, which is printed at the top of each page. For details on the procedure, issue the command SHOW SUBFILE DESCRIPTION SPIRES DOC NOTES.