Overview
An inline function is one that is enclosed in parenthesis and placed within a regular SAC command. The inline function is evaluated and its resulting value replaces the function in the SAC command before the command is executed. There are three general classes of inline functions:
- embedded arithmetic functions which begin with a number and have the name of the function embedded in the argument list.
- regular arithmetic functions which begin with the function name and are followed by zero or more arguments.
- character string manipulation functions which begin with the function name and are followed by zero or more arguments.
Inline functions can be placed inside other inline functions. This is refered to as nesting. There is a current limit to this nesting of 10 levels. Macro arguments, blackboard variables, and header variables can be used as arguments to inline functions. They are inserted in inline functions using the same syntax as in regular SAC commands.
Embedded Arithmetic Functions
An embedded arithmetic function is much like (but alas not identical to) the right hand side of a FORTRAN arithmetic statement. It is of the general form:
( number operator number ... )
where number is a numeric value and operator is one of the following arithmetic operators:
+ - * / **
Lets look at a simple example:
SAC> SETBB A (4 + 7 / 3) == > SETBB A 3.666667
Notice that whenever an inline function is found in a command, SAC prints the processed (i.e. evaluated) command to the terminal. This allows you to see the command that was actually executed. This example also illustrates two of the differences between inline functions and FORTRAN statements:
All numbers are treated as real and all arithmetic is done in floating point.
There is no implied precedence among operators. Calculations are done in order from left to right.
In the above example the real numbers 4.0 and 7.0 are first added together and then divided by the real number 3.0 to get the result. Embedded functions can be nested to achieve a different order of computation:
SAC> SETBB A (4 + (7 / 3)) ==> SETBB A 6.333333
In this example the division would be performed first. Also notice the space between the plus sign and the second left parenthesis. This is necessary in order for SAC to parse the command properly. In general it is wise to place spaces around all arguments, operators, and nested parentheses.
Regular Arithmetic Functions
There are currently 20 regular arithmetic functions available. They correspond to the arithmetic functions found in the EVALUATE command. Each of these functions is described below. Some examples are given at the end of this subsection.
| Command | Syntax | Purpose |
|---|---|---|
| ADD | ( ADD v1 v2 ... vn ) | Add (sum) a set of numbers. |
| SINE | ( SINE v) | Take the sine of a number. |
| SUBTRACT | ( SUBTRACT v1 v2 ... vn) | Subtract a set of numbers. |
| ARCSINE | ( ARCSINE v) | Take the arcsine of a number. |
| MULTIPLY | ( MULTIPLY v1 v2 ... vn) | Multiply a set of numbers. |
| COSINE | ( COSINE v) | Take the cosine of a number. |
| DIVIDE | ( DIVIDE v1 v2 ... vn) | Divide a set of numbers. |
| ARCCOSINE | ( ARCCOSINE v) | Take the arccosine of a number. |
| SQRT | ( SQRT v) | Take the square root of a number. |
| TANGENT | ( TANGENT v) | Take the tangent of a number. |
| EXP | ( EXP v) | Exponentiate a number. |
| ARCTANGENT | ( ARCTANGENT v) | Take the arctangent of a number. |
| ALOG | ( ALOG v) | Take the natural logarithm of a number. |
| INTEGER | ( INTEGER v) | Convert a number to an integer. |
| POWER | ( POWER v) | Raise a number to its power of 10. |
| PI | ( PI v) | Return the value of pi. |
| ALOG10 | ( ALOG10 v) | Take the log to base 10 of a number. |
| MAXIMUM | ( MAXIMUM v1 v2 ... vn) | Maximum value of a set of numbers. |
| MINIMUM | ( MINIMUM v1 v2 ... vn) | Minimum value of a set of numbers. |
| ABSOLUTE | ( ABSOLUTE v) | Take the absolute value of a number. |
Lets look at several examples. To normalize a set of data files so that the maximum absolute value of any data point in the set is unity:
SAC> READ FILE1 FILE2 FILE3 FILE4 SAC> SETBB A (MAX &1,DEPMAX &2,DEPMAX &3,DEPMAX &4,DEPMAX) ==> SETBB A 1.87324 SAC> SETBB B (MIN &1,DEPMIN &2,DEPMIN &3,DEPMIN &4,DEPMIN) ==> SETBB B -2.123371 SAC> DIV (MAX %A (ABS %B)) ==> DIV 2.123371
This could have been done in single command, without using intermediate blackboard variables, by nesting the inline functions properly, but this way is more readable. (It also fits on this page better!) In the next example, we need to calculate the tangent of an angle that has already been stored in the blackboard in degrees:
SAC> GETBB ANGLE ANGLE = 45.0 SAC> SETBB VALUE (TAN (DIVIDE (MULTIPLY (PI) %ANGLE%) 180.)) ==> SETBB VALUE 1.00000
Having the name of the function as the first token in the function (called prefix notation) makes it easier for SAC to parse the function. In some cases, especially the arithmetic ones, they are difficult to read. We can rework the above example into a more natural form by intermixing regular (prefix) and embedded arithmetic functions:
SAC> SETBB VALUE (TAN ((PI) * %ANGLE / 180. )) ==> SETBB VALUE 1.00000
Why is the percent sign needed after ANGLE in the first example and is not needed in the second example?
Miscellaneous Arithmetic Functions
There is currently only one miscellaneous arithmetic function, GETTIME, which returns the time offset (in seconds) relative to file begin time, for the first data point meeting the selection criteria.:
GETTIME ( GETTIME MAX|MIN [value])
Returns the time (in seconds) for the first file in memory, of the datapoint having the requested value. If no value is specified, MAX returns the time of the file's first data-point having a value greater than or equal to DEPMAX; MIN returns the time of the file's first data=point having the value less than or equal to DEPMIN. Specifying a value controlls the value of the data-point being searched for.
Lets look at some examples. To return the time in seconds of the first data- point greater than or equal to the file's maximum amplitude, for the file FILE1:
SAC> READ FILE1 FILE2 FILE3 FILE4 SAC> SETBB MAXTIME ( GETTIME MAX ) ==> SETBB MAXTIME 41.87
The file's first data-point having a value greater than or equal to the file's maximum amplitude is located 41.87 seconds into the file.
To locate the time of the first data-point less than or equal to the value 123.45:
SAC> SETBB VALUETIME ( GETTIME MIN 123.45 ) ==> SETBB VALUETIME 37.9
The first data-point in the file having a value less than or equal to 123.45 occurs at 37.9 seconds into the file.
String Functions
There are currently seven string manipulation functions. Each of these functions is described below. Some examples are given at the end of this subsection.
| Command | Syntax | Purpose |
|---|---|---|
| CHANGE | ({CHA}NGE} s1 s2 s3) | Change one text string (s1) to another ( s2) in a third text string ( s3). |
| SUBSTRING | ({SUBS}TRING n1 n2 s) | Return substring with characters n1 through n2 of text string (s). |
| DELETE | ({DEL}ETE s1 s2) | Delete a text string (s1) within another text string (s2). |
| CONCATENATE | ({CONC}ATENATE s1 s2 ... sn}) | Concatenate (i.e., place end to end) one or more text strings. |
| BEFORE | ({BEF}ORE s1 s2) | Return the portion of a text string (s2) that occurs before another text string (s1). |
| REPLY | ({REP}LY s1) | Send a message to the terminal and get a reply. |
| AFTER | ({AFT}ER s1 s2) | Return the portion of a text string (s2) that occurs after another text string (s1). |
The following examples show the use of several of the above functions. To use the station and event names in the title of a plot:
SAC> FUNCGEN SEISMOGRAM SAC> TITLE '(CONCATENATE 'Seismogram of ' &1,KEVNM ' ' &1,KSTNM )' ==> TITLE 'Seismogram of K8108838 CDV'
The previous example shows several features (and potential difficulties) of the inline string functions. This example of the CONCATENATE function has four arguments. The first argument has spaces in it so has to be enclosed in either (single or double) quotes. The second and fourth arguments have no spaces in them so they don't need quotes. The third argument consists of a single space so that the event and station names don't run together. Finally the quotes around the inline function itself are required because of the syntax of the title command.
The next example uses the SUBSTRING function to extract the month of the event and store it into a blackboard variable.:
SAC> FUNCGEN SEISMOGRAM SAC> SETBB MONTH (SUBSTRING 1 3 '&1,KZDATE&') ==> SETBB MONTH MAR
Why are the quotes needed around the header variable KZDATE?
The next example uses the REPLY function to interactively control the processing of a set of data files:
SAC> DO FILE LIST ABC DEF XYZ SAC> READ $FILE SAC> DO J FROM 1 TO 10 SAC> MACRO PROCESSFILE SAC> PLOT SAC> SETBB RESPONSE (REPLY "Enter -1 to stop, 0 for next file, 1 for same file: ") SAC> IF %RESPONSE LE 0 THEN SAC> BREAK SAC> ENDIF SAC> ENDDO SAC> IF %RESPONSE LT 0 THEN SAC> BREAK SAC> ENDIF SAC> ENDDO
The outer do loop reads one file in at a time from a list. The inner loop calls a macro to process this file. The inner loop executes up to 10 times. After each execution of the processing macro, the file is plotted, a message is sent to the terminal, and the reply is saved in a blackboard variable. The first if tests this variable to see if the inner processing loop should be terminated (by executing the BREAK statement) or continued. The second if tests this same variable to see if the loop on each data file should be terminated or continued. If only one if test is needed, the REPLY function could be substituted directly into the if test and a blackboard variable would not be needed.
The next example shows REPLY with a default value:
SAC> SETBB BBDAY (REPLY "Enter the day of the week: [Monday]")
When this function is executed, the quoted string will appear on the screen, prompting the user for input. If the user types a string, SAC will put the string that the user entered into the blackboard variable BBDAY. If the user simply hits return, SAC will put the default value (in this case, the string "Monday") into BBDAY.