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 that begin with a number and have the name of the function embedded in the argument list.
- regular arithmetic functions that begin with the function name and are followed by zero or more arguments.
- character string manipulation functions that 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. Beginning with v 101.6, there is no nesting limits of inline functions. 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 a simple math operation similar to those in any programming language, e.g. FORTRAN, C, etc, and is of the general form:
( number operator number ... )
where number is a numeric value and operator is one of the following arithmetic operators:
+ - * / **
All numbers are treated as real, and all arithmetic is done in double-precision floating point.
In the examples below, echo on is used and redundant output lines are left out.
Here is a simple example:
SAC> SETBB A (4 + 7 / 3) ===> SETBB A 6.33333
Prior to version 101.6, the answer would have been 3.666667 because operations were executed from left to right. Beginning with version 101.6, the FORTRAN heirarchy is used: ** then / then * then + and -. As in FORTRAN, the heirarchy can be changed by using parentheses:
SAC> SETBB A ((4 + 7) / 3) ==> SETBB A 3.66667
Because there are many scripts and macros written before v101.6, expressions with inline functions like the above will give the incorrect answer if there are no specific parentheses. If the new (with v101.6) function MATHOP is called with the option old before lines with inline functions, the precedence rules that held prior to v101.6 will be followed:
SAC> MATHOP OLD SAC> SETBB A (4 + 7 / 3) ===> SETBB A 3.66667
Arithmetic Functions
There are 22 arithmetic functions available. They correspond to the arithmetic functions found in the EVALUATE command. Each of these functions is described in the following table. Examples are then given.
| Command | Syntax | Purpose |
|---|---|---|
| SINE | ( SINE v) | Take the sine of a number. |
| ARCSINE | ( ARCSINE v) | Take the arcsine of a number. |
| COSINE | ( COSINE v) | Take the cosine of a number. |
| ARCCOSINE | ( ARCCOSINE v) | Take the arccosine of a number. |
| TANGENT | ( TANGENT v) | Take the tangent of a number. |
| ARCTANGENT | ( ARCTANGENT v) | Take the arctangent of a number. |
| ADD | ( ADD v1 v2 ... vn ) | v1 + v2 + ... + vn. |
| SUBTRACT | ( SUBTRACT v1 v2 ... vn) | v1 - v2 - ... - vn. |
| MULTIPLY | ( MULTIPLY v1 v2 ... vn) | v1 * v2 * ... * vn. |
| DIVIDE | ( DIVIDE v1 v2 ... vn) | v1 / v2 / ... / vn. |
| SQRT | ( SQRT v) | Take the square root of v (for v > 0). |
| EXP | ( EXP v) | Exponentiate a number. |
| POWER | ( POWER v) | 10 ** v. |
| ALOG | ( ALOG v) | Take the natural logarithm of a number. |
| ALOG10 | ( ALOG10 v) | Take the log to base 10 of a number. |
| INTEGER | ( INTEGER v) | Convert a number to an integer. |
| PI | ( PI ) | Return the value of pi. e.g., 2 * PI |
| 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. |
| GETVAL (1) | ( GETVAL t) | Get value at time t for all files in memory |
| GETVAL (3) | ( GETVAL File N t) | Get value for the Nth file at time t |
| GETTIME | ( GETTIME MAX|MIN [Val]) | See discussion in Example 4 below |
Example 1: Normalize Data
Normalize a set of data files so that the absolute value of the extremum offset in the data set is 1.0:
SAC> fg seismo
SAC> write one.sac
SAC> mul 2.0
SAC> write two.sac
SAC> mul 4.0
SAC> write four.sac
SAC> read one.sac two.sac four.sac
SAC> rtr
SAC> lh depmax depmin
FILE: one.sac - 1
depmax = 1.619626e+00 depmin = -1.470322e+00
FILE: two.sac - 2
depmax = 3.239252e+00 depmin = -2.940643e+00
FILE: four.sac - 3
depmax = 1.295701e+01 depmin = -1.176257e+01
SAC> setbb a (max &1,depmax &2,depmax &3,depmax)
==> setbb a 12.957
SAC> setbb b (min &1,depmin &2,depmin &3,depmin)
==> setbb b -11.7626
SAC> div (max %a (abs %b))
==> div 12.957
SAC> lh depmax depmin
FILE: one.sac - 1
depmax = 1.250000e-01 depmin = -1.134769e-01
ILE: two.sac - 2
depmax = 2.500000e-01 depmin = -2.269538e-01
FILE: four.sac - 3
depmax = 1.000000e+00 depmin = -9.078154e-01
Example 2: Use of GETVAL
SAC> message (getval 10.0) ==> message -0.00011933 -0.000238659 -0.000954636 -0.00011933 -0.000238659 -0.000954636 SAC> message (getval file 1 10.0) ==> message -0.00011933 -0.00011933 SAC> message (getval file 3 10.0) ==> message -0.000954636 -0.000954636 SAC> setbb ab (getval file 2 10.0) ==> setbb ab -0.000238659 SAC> getbb ab ab = -0.000238659 SAC>
Example 3: Simple Calculations
SAC> setbb angle (45) ==> setbb angle 45 SAC> SETBB VALUE (TAN (PI * %ANGLE / 180. )) ==> SETBB VALUE 1
Prior to v101.6, one needed %ANGLE%. With the new parsing system, the trailing % is no longer needed.
Example 4: Use of GETTIME
GETTIME returns the time offset (in seconds) relative to the time reference (O or B) for the first data point meeting the selection criteria.:
( GETTIME MAX|MIN [value] )
If no value is specified, GETTIME MAX returns the time of the file's first data-point having a value equal to DEPMAX and GETTIME MIN returns the time of the file's first data-point having the value equal to DEPMIN. Specifying a value controlls the value of the sought-for data-point.
For example, to set the time in seconds to a blackboard variable of the first data-point equal to the maximum amplitude for the file FILE1:
SAC> READ FILE1 SAC> SETBB MAXTIME ( GETTIME MAX ) ==> SETBB MAXTIME 41.87
The file's maximum amplitude is located at time 41.87 seconds.
To return 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.
Character strings
Prior to v101.6, Blackboard number variables were stored as strings, now they are stored as double-precision variables. In earlier versions, if a (..) appeared in a quoted string, escape character @ was needed to keep the inline parser from treating the expression as a math expression. Although that coding continues to work in 101.6, adding the escape characters is no longer necessary:
SAC> fg seismo SAC> xlabel "Time @(sec@)" ==> xlabel "Time (sec)" SAC> xlabel "Time (sec)" xlabel "Time (sec)" SAC>
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) | Place end to end text strings. with v101.6, not needed and may not give desired result. |
| 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). |
Because of the changes in handling strings in v101.6, code that previously worked will no longr work. For example, to use CONCATENATE to set the station and event names in the title of a plot prior ot v101.6, the following was used:
SAC> FUNCGEN SEISMOGRAM SAC> ECNO ON SAC> TITLE '(CONCATENATE 'Seismogram of ' &1,KEVNM ' ' &1,KSTNM )' old output ==> TITLE 'Seismogram of K8108838 CDV' v101.6 output ==> TITLE "(CONCATENATE " Seismogram of " K8108838 " " CDV )"
The best way to do that in v101.6 is much simpler:
SAC> title "Seismogram of &1,KEVNM &1,KSTNM" title "Seismogram of &1,KEVNM &1,KSTNM" ==> title "Seismogram of K8108838 CDV"
CONCATENATE can still be used, but there is usually a better way.:
SAC> setbb a (CONCATENATE Seismogram of &1,KEVNM &1,KSTNM ) ==> setbb a SeismogramofK8108838CDV SAC> setbb a (CONCATENATE Seismogram' ' of' '' ' &1,KEVNM &1,KSTNM ) ==> setbb a Seismogram of K8108838CDV SAC> > setbb a 'Seismogram of &1,KEVNM &1,KSTNM' ==> setbb a "Seismogram of K8108838 CDV"
The next examples uses the SUBSTRING function.:
SAC> fg seismo SAC> SETBB MONTH (SUBSTRING 1 3 &1,KZDATE) ==> SETBB MONTH MAR SAC> message (substring 1 5 &1,kevnm) ==> message K8108 setbb VAL "1234567890" SAC> message (substring 1 5 %VAL) message (substring 1 5 %VAL) ==> message 12345
The next example uses the REPLY function to control interactively the processing of a set of data files:
DO FILE LIST ABC DEF XYZ
READ $FILE
DO J FROM 1 TO 10
MACRO PROCESSFILE
PLOT
SETBB RESPONSE (REPLY "Enter -1 to stop, 0 for next file, 1 for same file: ")
IF %RESPONSE LE 0
BREAK
ENDIF
ENDDO
IF %RESPONSE LT 0
BREAK
ENDIF
ENDDO
The outer do loop reads in one file 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 were 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.
If one copies a set of SAC commands back into SAC, the copied commands will start with SAC>, which is not a part of the command. The parser will remove a doubled SAC> SAC>, so lines like SAC> SAC> read a.sac will be translated into SAC> read a.sac