Introduction | New User | Analysis | Graphics | Macros | Inline Functions |
Blackboard | Input-Output |Data Format (part 1) | Data Format (part 2) |
Appendix | Application Programmer Interface (API) | API How To
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:
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.
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:
u: SETBB A (4 + 7 / 3)
s: == > SETBB A 3.666667
Notice that whenever an inline function is found in a command, SAC2000 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:
u: SETBB A (4 + (7 / 3))
s: ==> 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 SAC2000 to parse the command properly.
In general it is wise to place spaces around all arguments, operators, and
nested parentheses.
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.
| ADD SYNTAX: ( ADD v1 v2 ... vn) PURPOSE: Add (sum) a set of numbers. |
SINE SYNTAX: ( SINE v) PURPOSE: Take the sine of a number. |
| SUBTRACT SYNTAX: ( SUBTRACT v1 v2 ... vn) PURPOSE: Subtract a set of numbers. |
ARCSINE SYNTAX: ( ARCøSINE v) PURPOSE: Take the arcsine of a number. |
| MULTIPLY SYNTAX: ( MULTIPLY v1 v2 ... vn) PURPOSE: Multiply a set of numbers. |
COSINE SYNTAX: ( COSINE v) PURPOSE: Take the cosine of a number. |
| DIVIDE SYNTAX: ( DIVIDE v1 v2 ... vn) PURPOSE: Divide a set of numbers. |
ARCCOSINE SYNTAX: ( ARCøCOSINE v) PURPOSE: Take the arccosine of a number. |
| SQRT SYNTAX: ( SQRT v) PURPOSE: Take the square root of a number. |
TANGENT SYNTAX: ( TANGENT v) PURPOSE: Take the tangent of a number. |
| EXP SYNTAX: ( EXP v) PURPOSE: Exponentiate a number. |
ARCTANGENT SYNTAX: ( ARCøTANGENT v) PURPOSE: Take the arctangent of a number. |
| ALOG SYNTAX: ( ALOG v) PURPOSE: Take the natural logarithm of a number. |
INTEGER SYNTAX: ( INTEGER v) PURPOSE: Convert a number to an integer. |
| POWER SYNTAX: ( POWER v) PURPOSE: Raise a number to its power of 10. |
PI SYNTAX: ( PI v) PURPOSE: Return the value of pi. |
| ALOG10 SYNTAX: ( ALOG10 v) PURPOSE: Take the log to base 10 of a number. |
MAXIMUM SYNTAX: ( MAXIMUM v1 v2 ... vn) PURPOSE: Compute the maximum value of a set of numbers. |
| MINIMUM SYNTAX: ( MINIMUM v1 v2 ... vn) PURPOSE: Compute the minimum value of a set of numbers. |
ABSOLUTE SYNTAX: ( & #248;ABSOLUTE v) PURPOSE: 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:
u: READ FILE1 FILE2 FILE3 FILE4
u: SETBB A (MAX &1,DEPMAX &2,DEPMAX &3,DEPMAX
&4,DEPMAX)
s: ==> SETBB A 1.87324
u: SETBB B (MIN &1,DEPMIN &2,DEPMIN &3,DEPMIN
&4,DEPMIN)
s: ==> SETBB B -2.123371
u: DIV (MAX %A (ABS %B))
s: ==> 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:
u: GETBB ANGLE
s: ANGLE = 45.0
u: SETBB VALUE (TAN (DIVIDE (MULTIPLY (PI) %ANGLE%) 180.))
s: ==> SETBB VALUE 1.00000
Having the name of the function as the first token in the function
(called prefix notation) makes it easier for SAC2000 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:
u: SETBB VALUE (TAN ((PI) * %ANGLE / 180. ))
s: ==> SETBB VALUE 1.00000
Why is the percent sign needed after ANGLE in the first example
and is not needed in the second example?
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
SYNTAX: ( GETTIME MAX|MIN [value])
PURPOSE: 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:
u: READ FILE1 FILE2 FILE3 FILE4
u: SETBB MAXTIME ( GETTIME MAX )
s: ==> 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:
u: SETBB VALUETIME ( GETTIME MIN 123.45 )
s: ==> 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.
There are currently seven string manipulation functions. Each
of these functions is described below. Some examples are given
at the end of this subsection.
| CHANGE SYNTAX: ({CHA}NGE} s1 s2 s3) PURPOSE: Change one text string (s1) to another ( s2) in a third text string ( s3). |
SUBSTRING SYNTAX: ({SUBS}TRING n1 n2 s) PURPOSE: Return substring with characters n1 through n2 of text string (s). |
| DELETE SYNTAX: ({DEL}ETE s1 s2) PURPOSE: Delete a text string (s1) within another text string (s2). |
CONCATENATE SYNTAX: ({CONC}ATENATE s1 s2 ... sn}) PURPOSE: Concatenate (i.e., place end to end) one or more text strings. |
| BEFORE SYNTAX: ({BEF}ORE s1 s2) PURPOSE: Return the portion of a text string (s2) that occurs before another text string (s1). |
REPLY SYNTAX: ({REP}LY s1) PURPOSE: Send a message to the terminal and get a reply. |
| AFTER SYNTAX: ({AFT}ER s1 s2) PURPOSE: 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:
{u:} FUNCGEN SEISMOGRAM
{u:} TITLE '(CONCATENATE 'Seismogram of ' &1,KEVNM ' ' &1,KSTNM
)'
{s:} ==> 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.
{u:} FUNCGEN SEISMOGRAM
{u:} SETBB MONTH (SUBSTRING 1 3 '&1,KZDATE&')
{s:} ==> 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:
{u:} DO FILE LIST ABC DEF XYZ
{u:} _ READ \$FILE
{u:} _ DO J FROM 1 TO 10
{u:} ___ MACRO PROCESSFILE
{u:} ___ PLOT
{u:} ___ SETBB RESPONSE (REPLY "Enter -1 to stop, 0 for
next file,
___ 1 for same file: ")
{u:} ___ IF \%RESPONSE LE 0 THEN
{u:} _____ BREAK
{u:} ___ ENDIF
{u:} _ ENDDO
{u:} _ IF \%RESPONSE LT 0 THEN
{u:} ___ BREAK
{u:} _ ENDIF
{u:} 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:
{u:} 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, SAC2000 will put the string that the user entered into the blackboard variable BBDAY. If the user simply hits return, SAC2000 will put the default value (in this case, the string "Monday") into BBDAY.
This page maintained by:
peterg@llnl.gov -- Peter Goldstein
LLNL Disclaimer
8/12/98
UCRL-MA-112836