# source:SH_SHM/trunk/doc/sh.tex@373

Revision 16, 102.4 KB checked in by marcus, 14 years ago (diff)

r1 | svn | 2007-12-13 11:10:29 +0100 (Do, 13 Dez 2007) | 2 lines

Initial import

Line
1\documentstyle[a4]{article}
2
3\input{deflist}
4\newcommand{\exm}[1]{{\tt #1}}    % example
5\newcommand{\cmd}[1]{{\tt #1}}    % command verb
6\newcommand{\shi}[1]{{\sc #1}}    % SH identifier
7\newcommand{\sht}[1]{{\sc #1}}    % SH type
8
9\begin{document}
10
11
12\title{SeismicHandler}
13\author{K.\ Stammler}
14\date{27 April 1992}
15
16\maketitle
17
18\tableofcontents
19
20
21\section{General Information}
22
23SeismicHandler (SH) is a tool for analysing digital seismograms.
24It can be used for the analysis of earthquake records as well as for
25examining seismogram sections in refraction seismology.  The program
26was developed during the work at my PhD at the SZGRF in Erlangen.
27Excluding graphic interfaces it now consists of roughly 40,000 lines
28of source code, written in ANSI C.  The current version was developed
29on ATARI ST/TT and has been exported to a MicroVAX and to Sun
30computers, so the portability should be guaranteed.
31
32The program uses dynamic storage allocation.  The length of the traces
33SH can hold in memory is limited only by the RAM size of the computer.
34The maximum number of traces in memory is currently limited to 300.
35Trace editing functions such as spike removal, baseline correction
36or polynomial interpolation are available.
37
38Although SH will run on a Tektronix terminal, it can more conveniently
39be used on a window system.  Currently implemented window graphics
40interfaces are X--Window (tested on VAX and SUN), VWS (VAX/VMS window
41system) and GEM (ATARI).  On a window system you have at least two
42different windows, one dialog window for entering commands and a
43second for graphic output.  SH is able to handle up to seven windows,
44but you will rarely use more than three.  It is, for example,
45convenient to open a separate window for particle motion diagrams.
46
47The user interface of SH is a command language designed specifically
48for processing seismic data.  Command lines are typed in interactively
49or may be read from a file (command procedure).  Dialog boxes,
50pop--up or pull--down menues have not been implemented due to the
51incompatibility of different graphics interfaces.
52
53There is a help text available for each SH command.  It can be
54requested interactively by the \cmd{help}\ command.  If you create
55new commands you can update the help library just by adding a help
56text file to the help directory.
57
58
59
60\section{The Command Line}
61
62The command interpreter parses each command line by processing
63two steps:
64\begin{enumerate}
65\item split up the command line in words using blanks, semicolons
66      and slashes
67      as terminators.  Words are separated either by one or
68      more blanks or by a single semicolon or by a single
69      semicolon and additional blanks or by a slash which may be
70      preceded by blanks.  Two consecutive semicolons
71      or two semicolons with only blanks in between denote an
72      empty word.
73\item translation of each word.  A description of the translation
74      process is given in section \ref{sec:Translation}.
75\end{enumerate}
76All words which were separated by a slash ("/"), are identified
77as qualifiers (see below).
78Qualifiers are treated separately and do not count as parameters.
79Besides these qualifiers the first word is regarded as the command
80verb, the others as parameters numbered from 1 to N.  N ranges
81from zero to fifteen.  Empty words (see above) result in
82an empty parameter.  Note that the first parameter can
83be separated from the verb by a semicolon as well.  That means
84if you want to pass an empty first parameter and a second
85parameter \exm{par}\ to a command verb \exm{verb}, you have to
86type \exm{verb;;par} and {\em not} \exm{verb;par}, where \exm{par}\
87is regarded as the first parameter.
88
89Qualifiers are most often used as switches, using their presence
90as one state of the switch, their absence as the other.  Such simple
91qualifiers \exm{/SimpleQual}\ consist of the slash ("/") and
92the name of the qualifier.  However, on some commands you may
93pass valued qualifiers \exm{/ValuedQual=value}.  The value
94\exm{value}\ is appended to the valued qualifier with a "="-character
95in between.  There is a maximum number of 5 qualifiers per command
96permitted.  A complicated example of a command line is
97
98\exm{verb par1;par2 ;; par4/SimpleQual par5  par6\ \ /ValuedQual=val}.
99
100\noindent
101The exclamation character "!" is regarded as the end of the
102command line.  Any characters following it are ignored and may be
103used as a comment on the command line.  A command line beginning
104with the exclamation character is equivalent to an empty line.
105
106
107
108\section{Translation of Expressions}
109\label{sec:Translation}
110
111As it was mentioned in the previous section, the command parser
112translates each word of the given command line if possible.
113The translation process is applied if the word starts with one
114of the following non--alphanumeric characters:
115\verb+" # $% _ ^ |+ 116 117The "\verb+|+"--characters are used for concatenation of 118subexpressions, which may be translated itself before. The 119construction \exm{|<sub1>|<sub2>|<sub3>|}, for example, results in a 120concatenation of the three subexpressions \exm{<sub1>}, 121\exm{<sub2>} and \exm{<sub3>}. There is a maximum of 10 122subexpressions which can be concatenated within one command 123line. 124 125All others of the previously listed characters require either 126an indexed or a non--indexed name to follow. A non--indexed 127name is just a string of alphanumeric characters \exm{<name>}, 128an indexed name consists besides the name an index string 129in paranthesis \exm{<name>(<index>)}. Now follows a list of 130valid translatable expressions: 131 132\begin{description} 133\item[\exm{"<name>}] 134 Expression is replaced by the current value 135 of the local or global variable \exm{<name>}. See 136 section \ref{sec:Variables}\ for detailed information 137 about variables in SH. \exm{<name>}\ must be a defined 138 variable name. See command \cmd{sdef}. 139\item[\exm{\#<name>}] 140 If \exm{<name>}\ is a number between 1 141 and 15 the expression is replaced by the value of the 142 \exm{<name>}--th parameter passed to the current command 143 procedure (see section \ref{sec:CmdProc}). If \exm{<name>}\ 144 equals the string \exm{params}\ it is replaced by the total 145 number of parameters passed to the command procedure. Any 146 other expression accesses qualifiers of the command line which 147 called the current procedure. For example, the word 148 \exm{\#example}\ is replaced by 149 \begin{itemize} 150 \item the string \verb+_EXISTSNOT_+ if the qualifier 151 \exm{/example}\ was not specified. 152 \item the string \verb+_NOVALUE_+ if the qualifier 153 \exm{/example}\ was specified without value. 154 \item the value \exm{qualvalue}\ if a valued qualifier 155 \exm{/example=qualvalue}\ was specified. 156 \end{itemize} 157\item[\exm{\$<name>}]
158   This evaluates internal variables.  An example
159   is \exm{\$dsptrcs}\ which returns the current number of traces 160 on the display. A complete list of all internal variables is 161 given in section \ref{sec:InternVar}. 162\item[\exm{\%<file>(<line>)}] 163 Returns the \exm{<line>}--th line of the text file 164 \exm{<file>}. If the parantheses and \exm{<line>}\ are omitted 165 the first line of \exm{<file>}\ is returned. A value of 0 for 166 \exm{<line>}\ returns the total number of lines in \exm{<file>}. 167 If the file extension is 168 not specified it is assumed to be \exm{.stx} which is the 169 default extension for SH text output files (\cmd{echo} command). 170 Please make sure that the text file doesn't contain lines 171 longer than 132 characters. Otherwise the line counting won't 172 be correct. 173\item[\exm{$^\wedge$<info>(<trace>)}] 174 Returns the value of the info entry \exm{<info>}\ of the 175 \exm{<trace>}--th trace on display (counting from bottum up). 176 If the trace number and the parantheses are omitted the first 177 trace is accessed. As an example, the expression 178 \verb+^delta(3)+ is replaced by the sample distance 179 of the third trace on display. For detailed information about 180 info entries see section \ref{sec:InfoEntries}. 181\item[\exm{\_<info>(<start>:<end>)}] 182 Such an expression is translated only if it is found in place 183 of a trace list parameter. It selects all traces which have 184 an \exm{<info>}--value between \exm{<start>}\ and \exm{<end>}. 185 A more detailed explanation is given in section \ref{sec:TraceAdr}. 186\end{description} 187 188In an indexed name both subexpressions (\exm{<name>}\ and 189\exm{<index>}) itself can be of the above (non--indexed) type. As 190an example, the expression \exm{\%\#1("cnt)}\ is replaced by the 191line number \exm{cnt}\ of a text file, whose name is passed as the 192first parameter to the current command procedure. 193 194 195 196\section{Information Entries} 197\label{sec:InfoEntries} 198 199Usually there is a lot of information about a seismogram besides 200the sample data itself. Some examples are the {\em length} of 201the trace, the {\em sample distance}, the recording {\em station} 202and {\em component} name. All these information values and many more 203can be stored in the q--files, the preferred data format of SH. 204The two most convenient issues of SH concerning the q--file format 205are (i)~the accessibility for reading and writing of each of these 206information values through SH by descriptive names and (ii)~the 207possibility of defining your own information entries for the 208q--files (including their names). 209 210To use the information entries you don't have to know much about 211the q--file format, but you should know a little about how SH 212accesses them. The most important thing about information 213entries in q--files is, that they have a type (called \shi{q--type}) 214and a number (called \shi{q--number}). For your convenience 215there is a 216name assigned to each information entry (called \shi{infoname}), which 217SH can translate into \shi{q--type}\ and \shi{q--number}\ to 218identify the 219information uniquely. But there is a problem concerning the 220execution speed. If SH would read the Q-file header on each 221read--access to any of the information entries, this would slow 222down the program drastically. A write--access is even worse, because 223SH would have to rewrite the whole Q--header file. For this reason 224SH stores frequently used information entries for each trace in 225memory. That means that every \shi{infoname}\ does not only point to 226a \shi{q--type}\ and a \shi{q--number}, but as well to a type 227(called \shi{sh--type}) 228and an index (called \shi{sh--index}) in memory. The 229\shi{sh--index}\ 230is different from q--number, because the \shi{sh--index}\ 231controls whether 232or not the information entry is stored in memory (see below). 233So you can change the set of information entries hold in 234memory by changing 235their \shi{sh-index}\ numbers without changing the \shi{q--number}s. 236It is necessary to distinct between \shi{q--type}\ and \shi{sh--type}, 237because there exist more \shi{sh--type}s than \shi{q--type}s. 238That means, some \shi{sh--type}s do not exist on q--file and are 239converted to an existing \shi{q--type}\ to store it on q--file. For 240example the \shi{sh--type}\ \sht{time}\ is stored as a \sht{string}\ 241\shi{q--type}. 242 243On a read--access to an information value SH translates the 244given \shi{infoname}\ to \shi{sh--type}\ and \shi{sh--index}. 245By the value of \shi{sh--index}\ SH can tell whether the information 246is hold in memory. If this is the case, SH takes the information 247found in memory, it doesn't touch the information in the 248q--file. If the information is not found in memory, SH determines 249\shi{q--type}\ and \shi{q--number} and reads it from q--file. 250 251Any write--access (command \cmd{set}) to information values changes 252only values in memory by default. If the information is not found 253in memory, SH doesn't change anything. Only on explicit request 254(command \cmd{set/file}) SH changes information entries on file 255(and in memory if it is there as well). 256 257Some information entries do not exist on q--file but are hold 258in memory. 259These entries are created when the trace is read or generated 260in any other way. This is useful, for example, for entries like 261minimum and maximum amplitude of a trace or any information concerning 262the display, like time origin, vertical position, display attributes, 263normalization factors and so on. 264 265As already mentioned, the \shi{sh--index}\ controls the storage type of 266the information entry. There were mentioned three storage types of 267entries. These are the frequently used information 268entries stored in q--file {\em and} hold in memory (called 269\shi{auto--load}\ 270entries, because they are loaded automatically into memory when 271a trace is read in), the rather slow accessible entries stored 272in q--files only (called \shi{file--only}\ entries) and the temporary 273information entries, which are hold in memory only (called 274\shi{mem--only}\ entries). For each \shi{sh--type}\ there is 275a different but 276fixed number of entries (called \shi{maxmem}) which can be hold 277in memory. 278This number includes the \shi{mem--only}\ entries which are predefined 279and cannot (or at least should not) be changed. Therefore remains 280a smaller number (called \shi{maxauto}) of \shi{auto--load}\ 281entries which 282are definable by the user. In detail the index structure is 283like this: all entries with an \shi{sh--index}\ ranging from 0 to 284\shi{maxauto}-1 are \shi{auto--load}\ entries, all entries from 285\shi{maxauto}\ to 286\shi{maxmem}-1 are \shi{mem--only}\ entries, all entries greater or 287equal 288to \shi{maxmem}\ are \shi{file--only}\ entries. Note that SH 289supports only 290\shi{sh--index}\ numbers smaller than a number \shi{maxfile}. 291The values of the numbers \shi{maxauto}, \shi{maxmem}\ and 292\shi{maxfile}\ 293for each entry type and all currently defined information 294entries including their \shi{sh--index}\ and \shi{q--number}\ 295can be listed 296by the SH command \exm{entry list outfile.txt}. Then a file 297\exm{outfile.txt}\ is created and typed on the current output 298window of SH. 299 300Remember that the \shi{sh--index}\ 301is an SH--internal number and does not appear in q--files in 302any way. For the identification of an entry, only the 303\shi{q--number}\ is decisive. This allows you to change the set of 304entries which are used as \shi{auto--load}\ from one SH session to 305another. 306 307Now follows a complete list of all available entry types 308(all are valid as \shi{sh--type}s and most of them are valid 309\shi{q--type}s) 310\begin{deflist}{\sht{integer}} 311\item[\sht{long}] \shi{sh--type}\ and \shi{q--type}. 32--bit signed 312 integer value. 313\item[\sht{integer}] \shi{sh--type}\ and \shi{q--type}. 314 16--bit signed integer value. 315\item[\sht{byte}] \shi{sh--type}\ only, its converted to 316 \sht{integer}\ type on q--files. 8--bit signed integer 317 value. 318\item[\sht{real}] \shi{sh--type}\ and \shi{q--type}. Real number 319 in floating point or exponential format. 320\item[\sht{string}] \shi{sh--type}\ and \shi{q--type}. Character 321 string containing any printable character except 322 tilde ("\verb+~+"). 323\item[\sht{char}] \shi{sh--type}\ and \shi{q--type}. Single 324 printable character (no tilde "\verb+~+" permitted). 325\item[\sht{time}] \shi{sh--type}\ only, its converted to 326 \sht{string}\ type on q--files. 327 Absolute time specification, containing date and time.\\ 328 Example: 23--JUN--1989\_23:30:00.000 329\item[\sht{flag}] \shi{sh--type}\ only, its converted to \sht{char}\ 330 type on q--files. Two--valued entry, possible values 331 are \exm{yes}\ and \exm{no}. 332\end{deflist} 333 334Since you can create your own information entries, there are 335predefined only the entries which are internally used by SH. 336You should not change the \shi{sh--index}\ or the \shi{q--number}\ 337of any 338of these predefined entries, even if you can. If you do so, 339you will slow down the program (in the best case) or crash 340it (the worst case). 341This is a complete list of the predefined entries: 342\begin{deflist}{\shi{reduction}} 343 \item[\shi{length}] \shi{auto--load}, \shi{sh--type}\ and \shi{q--type}\ 344 \sht{long}, 345 \shi{q--number} 1. Length of trace in 346 number of samples. 347 \item[\shi{alloc}] \shi{mem--only}, \shi{sh--type}\ \sht{long}. 348 Size of allocated memory for the trace in units of samples. 349 Usually this is the same as LENGTH. 350 \item[\shi{dspfst}] \shi{mem--only}, \shi{sh--type}\ \sht{long}. 351 Index number of first sample inside the current display 352 window. Controlled by commands \cmd{STW}\ and \cmd{DTW}. 353 \item[\shi{dspcnt}] \shi{mem--only}, \shi{sh--type}\ \sht{long}. 354 Number of samples inside the current display window. 355 Controlled by commands \cmd{STW}\ and \cmd{DTW}. 356 \item[\shi{recno}] \shi{mem--only}, \shi{sh--type}\ \sht{integer}. 357 If the trace is read from a q--file, this entry contains 358 the position number of the trace inside the file, otherwise 359 the entry value is zero. 360 \item[\shi{attrib}] 361 \shi{mem--only}, \shi{sh--type}\ \sht{integer}. 362 Number of the display attribute block for the trace. 363 A display attribute block controls the output attributes 364 of traces like colour, line width and line style {\em and} 365 the output attributes of text like colour, size, font and 366 text effects. For details about attribute blocks see 367 section \ref{sec:AttribBlocks}. The number of available 368 attribute blocks depends on the implemented graphics package. 369 The default attribute block is 0. 370 \item[\shi{reduction}] 371 \shi{mem--only}, \shi{sh--type}\ \sht{integer}. 372 Reduction factor for trace plotting. Reduces number of 373 samples on display and increases output speed. If, for 374 example, the reduction factor is 3, every third point of 375 the trace is plotted. The default value of the reduction 376 is 1, that means every point is plotted. 377 \item[\shi{delta}] 378 \shi{auto--load}, \shi{sh--type}\ and \shi{q--type}\ \sht{real}, 379 \shi{q--number}\ 0. Usually this is the 380 sample distance in seconds. 381 \item[\shi{maxval}] 382 \shi{mem--only}, \shi{sh--type}\ \sht{real}. 383 Value of the maximum sample of the whole trace. Determined 384 automatically when the trace is read and after every trace 385 manipulation. 386 \item[\shi{minval}] 387 \shi{mem--only}, \shi{sh--type}\ \sht{real}. 388 Value of the minimum sample of the whole trace. Determined 389 automatically when the trace is read and after every trace 390 manipulation. 391 \item[\shi{norm}] 392 \shi{mem--only}, \shi{sh--type}\ \sht{real}. 393 Normalization factor. Determined automatically before 394 each redraw, depending on the selected normalisation mode 395 (see command \cmd{norm}). 396 \item[\shi{zoom}] 397 \shi{mem--only}, \shi{sh--type}\ \sht{real}. 398 Zoom factor entered by user via command \cmd{zoom}. Default value 399 is 1. The total amplification factor of the trace is 400 the product of \cmd{norm}\ and \cmd{zoom}. 401 \item[\shi{t-origin}] 402 \shi{mem--only}, \shi{sh--type}\ \sht{real}. 403 Horizontal position of trace. Given in the same units 404 as \exm{delta}. Controlled by commands \cmd{shift} and 405 \cmd{al}, \cmd{beam}\ and others. 406 \item[\shi{s-origin}] 407 \shi{mem--only}, \shi{sh--type}\ \sht{real}. 408 Vertical position of trace. Determined automatically before 409 each redraw. Computation algorithm can be modifed with 410 \cmd{yinfo}\ command. 411 \item[\shi{weight}] 412 \shi{mem--only}, \shi{sh--type}\ \sht{real}. 413 Weight of trace when used in a \cmd{sum}\ command. Default 414 value is 1. 415 \item[\shi{comment}] 416 \shi{auto--load}, \shi{sh--type}\ and \shi{q--type}\ \sht{string}, 417 \shi{q--number}\ 0. Comment line on trace. 418 \item[\shi{station}] 419 \shi{auto--load}, \shi{sh--type}\ and \shi{q--type}\ \sht{string}, 420 \shi{q--number}\ 1. Station code of 421 recording station. 422 \item[\shi{file}] 423 \shi{mem--only}, \shi{sh--type}\ \sht{string}. 424 Name of input file of trace. If the trace is generated 425 in SH the string is copied from a parent trace if possible, 426 otherwise it remains empty. 427 \item[\shi{comp}] 428 \shi{auto--load}, \shi{sh--type}\ and \shi{q--type}\ \sht{char}, 429 \shi{q--number}\ 0. Component of 430 recording station. 431 \item[\shi{start}] 432 \shi{auto--load}, \shi{sh--type}\ \sht{time}, \shi{q--type}\ string, 433 \shi{q--number}\ 21. Start date and time 434 of record. 435 \item[\shi{modif}] 436 \shi{mem--only}, \shi{sh--type}\ \sht{flag}. 437 If the trace is modified since read in from q--file, this 438 flag is set to \exm{yes}, otherwise its \exm{no}. 439 \item[\shi{fromq}] 440 \shi{mem--only}, \shi{sh--type}\ \sht{flag}. 441 If the trace is read from a q--file this flag is set to 442 \exm{yes}, otherwise its \exm{no}. 443\end{deflist} 444 445When you define your own entries, you should make sure that 446\begin{itemize} 447\item the \shi{q--number}\ is not used by another already defined 448 entry (this is not checked by SH !) 449\item the \shi{q--number}\ is not greater or equal to \shi{maxfile} 450\item the \shi{sh--index}\ is not used by another already defined 451 entry (this is checked) 452\item the \shi{sh--index}\ is not that of a \shi{mem--only}\ entry, 453 that means it should not be inside the range from 454 \shi{maxauto}\ to \shi{maxmem}-1 455\item the \shi{sh--index} is not greater or equal to \shi{maxfile} 456\end{itemize} 457Usually additional entries are defined within the startup command 458file of SH \cmd{shstrtup}. To get a complete list of the currently 459defined entries, their \shi{sh--index}\ numbers and their 460\shi{q--number}s, enter the command \exm{entry list outfile.txt}, 461which creates a file \exm{outfile.txt}\ and types it on the current 462output window. To define entries use the command \cmd{entry define}. 463See \cmd{help entry}\ for detailed information about the \cmd{entry}\ 464command. 465 466 467 468\section{Trace Addressing} 469\label{sec:TraceAdr} 470 471Many commands require a list of traces as input parameter. Then 472you will usually specify a number of traces of the current display. 473The traces are addressed by their position number inside the 474display window. The positions are counted from the bottom up to 475the top, starting at 1. By default, the position numbers are 476displayed on the left side of each trace, where the name of the 477recording station and the component are given as well. But this 478trace labelling can be changed (command \cmd{trctxt}) and so the 479trace numbering is not necessarily visible. Let's use the 480command \cmd{del}\ as an example. You may use the following 481list expressions in place of any parameter of type \cmd{trace list}\ 482(the parameter type is always given in the help text to each 483command). The delete command \cmd{del}\ takes only one parameter 484which is the list of traces to be deleted. Suppose you want to 485delete the bottom trace only. This is done by \cmd{del 1}. After 486execution the display is redrawn automatically (if the display 487redraw is enabled) without the deleted first trace. The bottom 488trace which had position number 2 before the delete command, now 489got the position number 1. It is possible to specify a set of 490traces by a list of position numbers, separated by commas. For 491example, to delete the first, third and fifth trace, the command 492is \cmd{del 1,3,5}. A block of consecutive numbers can be specified 493by the first and last number of the block, separated by a hyphen. 494So the command \cmd{del 1-6}\ deletes the first 6 traces on the 495display. Blocks and lists may be combined which means \cmd{del 4961-3,7-9,14-16}\ is a valid command and deletes the traces with 497the position numbers 1, 2, 3, 7, 8, 9, 14, 15, 16. Please keep 498in mind, that any such expression must not contain blanks, because 499otherwise the command parser would regard the expression as more 500than one parameter and the parameter passing won't be correct. 501To select all traces of the display window, use the expression 502\cmd{all}, which means \cmd{del all}\ deletes all displayed traces. 503 504It is possible to change the order of the traces on display by 505the \cmd{display}\ command. For example, \cmd{display 3 1}\ puts 506trace number 3 to the bottom by changing it's position to 1. 507Also valid is \cmd{display 7-9 3}, which takes the traces at the 508positions 7 to 9 and inserts them at positions 3 to 5. 509 510Sometimes it is useful to remove traces from the display and 511keep them in memory. Then the traces can be redisplayed later 512without reading them from file again (which takes time and you need 513to remember the filename) or without computing them again, if the 514traces are not read from file directly. The command is 515\cmd{hide <list>}. \cmd{<list>}\ may be any trace list parameter 516as described above. Then the traces specified in \cmd{<list>}\ 517are hidden, they are not displayed any more. They are redisplayed 518by the \cmd{display}\ command. But since the traces are not 519visible, they don't have a position number which is usually needed 520for addressing. Therefore a special expression \cmd{h:all}\ is 521defined which includes all hidden traces. The command \cmd{display 522h:all 3}\ displays all hidden traces starting at position number 3. 523The second parameter may be omitted. It is then assumed to be 1. 524With this command all of the hidden traces are redisplayed. To 525redisplay only a subset, you need an expression which is explained 526in the following. 527 528There exists a possibility to select a subset of all traces in 529memory which match a condition given for a specified info entry. 530A range for this info entry is selected and all traces which have 531an info entry within this range are put on the list. The general 532syntax of such an expression is \cmd{\_<info>(<start>:<end>)}. 533\cmd{<info>}\ is the name of the info entry. \cmd{<start>}\ and 534\cmd{<end>}\ specify the limits of the value range. As an example, 535let's assume that you want to display only traces which have an 536epicentral distance between 30$^\circ$and 50$^\circ$. First 537all traces must be hidden, using \cmd{hide all}. Then redisplay 538all traces matching the given condition \cmd{display \_distance(30:50)}. 539Traces which don't have a \cmd{distance}--value at all, are not 540put on the list as well as all traces whose distance value is out of 541the specified range. If the lower bound \cmd{<start>}\ is not 542specified, all traces with a distance smaller than 50$^\circ$are 543selected (\cmd{display \_distance(:50)}). The same holds for the 544upper bound \cmd{<end>}, \cmd{display \_distance(30:)}\ displays 545traces with a distance larger than 30$^\circ$. The expression 546\cmd{\_distance(30)}\ selects traces which have a distance value 547of exactly 30$^\circ$. For real--valued entries this is usually 548senseless, but for other entry types like \shi{string}\ or 549\shi{char}\ or \shi{time}\ it may be useful. So the command 550\cmd{display \_comp(z)}\ displays only z--components. But notice 551that SH converts the command line to uppercase letters by default. 552This is important for string and character comparisons. You can 553negate the selection conditions by putting a "\verb'~'"--character 554after the info entry name. This means, the expression 555\verb'_distance~(30:50)'\ selects all traces whose distance value 556is {\em not\/} in the range between 30$^\circ$and 50$^\circ$. 557Some instructive examples of commands using list expressions are 558given below. 559\smallskip 560 561\noindent 562\cmd{del 4-6,8,11,15-20}\\ 563Delete traces number 4, 5, 6, 8, 11, 15, 16, 17, 18, 19, 20. 564\smallskip 565 566\noindent 567\cmd{hide all}\\ 568Hide all traces. 569\smallskip 570 571\noindent 572\cmd{display h:all}\\ 573Display all hidden traces starting at position 1. 574\smallskip 575 576\noindent 577\cmd{sum \_azimuth(0:180)}\\ 578Sum traces whose azimuth value is between 0 and 180$^\circ$. 579\smallskip 580 581\noindent 582\verb'del _comp~(z)'\\ 583Delete all traces which are not z--components. 584\smallskip 585 586\noindent 587\cmd{zoom/rel \_station(bji) 2}\\ 588Enlarge the amplitude of all traces of station BJI by a factor of 2. 589\smallskip 590 591\noindent 592\cmd{hide \_magnitude(:5.8)}\\ 593Hide all traces with a magnitude smaller than 5.8. 594 595 596 597\section{Trace Filtering} 598 599Application of filters is a very important step in analysing 600seismic traces. It is performed in almost any case of data 601processing. For this reason the related commands are explained 602here in more detail in addition to the interactive help texts. 603SH knows three different kind of filters: FFT--filters, 604recursive filters and tabulated filters. Besides these SH 605can perform operations related to filtering, like 606Hilbert--transformation, attenuation and computation of minimum delay 607signals from given signals or autocorrelations. 608 609\subsection{FFT Filters} 610 611This is the most common way of trace filtering. A copy of the trace 612is transformed into frequency domain using the FFT (Fast Fourier 613Transformation) algorithm. If the number of samples is not a 614power of 2, zeroes are appended to the trace automatically. 615In the frequency domain the trace is multiplied by the filter 616function which is given as poles and zeroes (In detail, the 617trace is multiplied with the first zero, then divided by the 618first pole, then multiplied with the second zero, then divided 619by the second pole and so on until all zeroes and all poles 620are used). After this process the trace is transformed back 621into time domain and displayed on screen (if the redraw is 622enabled). SH stores the currently used filter (or a cascade of 623filters) in memory. That means, before applying the filter operation 624you have to read in an FFT filter file, containing poles and zeroes 625and a normalization factor. This is a text file which you can 626create with any text editor or with utility programs. An example of 627such a filter file is given here: 628 629\begin{verbatim} 630! file WWSSN_SP.FLF 631! ============ 632! 633! WWSSN-LP FFT filter (including GRF restitution) 634! H(s) = ( P(s,h0,w0) / P(s,h1,w1) ) * ( w2*w2 / P(s,h2,w2) ) 635! where P(s,h,w) := s*s + 2*h*w*s + w*w 636! h0 = 0.707, t0 = 2*pi/w0 = 20.0 637! h1 = 0.67, t1 = 2*pi/w1 = 1.05 638! h2 = 0.55, t2 = 2*pi/w2 = 0.75 639! 6401357913578 6411 64270.18385353 6432 644(-0.2221106,-0.2221777) 645(-0.2221106,0.2221777) 6464 647(-4.009271,-4.442279) 648(-4.009271,4.442279) 649(-4.607669,-6.996659) 650(-4.607669,6.996659) 651\end{verbatim} 652 653\noindent 654At the beginning of the file may be (better: should be) comment 655lines. Comment lines start with an exclamation sign "\exm{!}" (no 656preceding blanks !). The first line after the comments is a magic 657number and must be \exm{1357913578}. This identifies the file 658to be an SH filter file. The next line is another ID number, 659specifying the filter type. For FFT filter files this is \exm{1}. 660The next line contains a normalization constant which is multiplied 661to the filtered trace. Then follows, again in a separate line, the 662number of zeroes of the filter. In the example file two zeroes are 663given. A pair of complex conjugated zeroes counts as two 664zeroes and both of them must be specified in consecutive, separate 665lines. The real and imaginary part are separated by a comma and 666enclosed in parantheses. Even real numbers must be entered in this 667format. The poles are given similarly. First the number 668of poles, then the complex poles in separate lines. Please note 669that blank lines are not permitted at any place in the file. 670 671The given filter is a simulation filter for a WWSSN--SP seismomemter 672which needs a velocity--proportional record of an STS--1 instrument 673as input. The filter file \exm{WWSSN\_SP.FLF}\ is read into memory 674by the command \cmd{fili f wwssn\_sp}. The default extension 675\exm{.FLF}\ may be omitted. The filter files are searched in 676the current directory and in the filter library (see section 677\ref{sec:SHLibs}\ about default paths in SH). The \exm{f}\ as 678second parameter denotes that the file contains an FFT filter. It 679is possible to specify more than one filter file on this command. 680For example, the input \cmd{fili f f1 f2 f3}\ reads in the three 681FFT files \exm{F1.FLF}, \exm{F2.FLF}\ and \exm{F3.FLF}. The 682filters are applied to the trace one after the other (filter 683cascade). If the qualifier \exm{/compress}\ is specified, all 684filters are concatenated to a single filter and zero--valued 685poles and zeroes are shortened if possible (non--zero values are 686not shortened, I'm sorry for this). Once the filter (cascade) is 687read in, it remains in memory until another \cmd{fili}--command 688replaces it. Each filter process uses the filter(s) 689read in by the most recent \cmd{fili}--command. To apply the 690filter to the first three traces on display, type in 691\exm{filter f 1-3}. Again, the \exm{f}--parameter denotes an FFT 692filter process. After execution of this command, three new traces 693appear on top of the display containing the filter output. 694FFT filters are quite slow if the input traces are very long 695(several ten thousands of samples). It is possible to set a time 696window for the filter process. If you want to filter only the 697time window between 50 and 350 seconds (relative to the time 698axis), enter \cmd{filter f 1-3 50 350}. By default, that means 699without parameters 3 and 4, the whole trace is filtered (not 700only the part inside the display window). 701 702 703\subsection{Recursive Filters} 704 705Recursive filters have the advantage that they are faster on long 706traces than FFT filters. The reason is, that output samples are 707computed as linear combinations of already existing samples of the 708input and the output trace. Thus the computation time grows 709proportional to the number of samples$N$, while the FFT filters 710grow proportional to$N\log N$. On the other hand, recursive filters 711have some deficiencies as well. These are mainly: 712\begin{itemize} 713\item 714 Usually it takes more time to determine the recursive filter 715 coefficients than the poles and zeroes for a given transfer 716 function. Particularly if the poles and zeroes are given, 717 an FFT filter can be written down immediately, while a recursive 718 filter needs a considerable amount of brainwork. 719\item 720 The filter coefficients depend on the sample rate. Such a 721 recursive filter can be applied only to traces of a fixed 722 sample rate. 723\item 724 On very long--period filters, where many samples are involved 725 to compute a new output sample, recursive filters tend to 726 numerical instabilities. 727\item 728 Output traces of recursive filters usually have high--amplitude 729 numerical noise at their beginning. 730\end{itemize} 731As SH supports both filter types it is up to the user to decide 732which filter is to be preferred in his application. 733 734The formula used in the recursive filter operations is this: 735$736 r_n = a_0 f_n + a_1 f_{n-1} + \ldots + a_k f_{n-k} - 737 b_1 r_{n-1} - b_2 r_{n-2} - \ldots - b_l r_{n-l} 738$ 739where the$a_i, i=0,\ldots,k$and the$b_j, j=1,\ldots,l$are the 740filter coefficients. The input trace is given by the$f$'s and 741the output trace by the$r$'s. This means, the current output 742sample$r_n$is determined by the current input sample$f_n$, 743$k$previous input samples and$l$previous output samples. 744The first$k$output samples access input samples with indices 745smaller than zero, which are not known. These are assumed to 746be zero. This is the reason for the numerical noise at the beginning 747of the output trace. 748 749An SH recursive filter file can contain one or more recursive 750filters. The whole filter file is read in by the command 751\cmd{fili}. An example file \exm{WWSSN\_SP.FLR}\ of a 752WWSSN-SP filter is given here: 753 754\begin{verbatim} 755! file WWSSN_SP.FLR 756! ============ 757! 758! WWSSN-SP recursive filter 759! 7601357913578 7613 7620.05 7631.0 7643 7651.011167 766-1.999877 7670.9889559 7683 7691.224691 770-1.954563 7710.8207457 772@ 7733 7740.05 7751.0 7763 7774.5180295e-2 7789.0360589e-2 7794.5180295e-2 7803 7811.278993 782-1.909639 7830.8113681 784\end{verbatim} 785 786It again needs as input velocity--proportional records of an STS--1 787instrument. The first lines beginning with "\exm{!}" are comment 788lines and are ignored by SH (but not by the human reader of the 789file !). The first line after the comments must be the magic number 790\exm{1357913578}. The next line contains the ID number of 791recursive filters and is \exm{3}. This is followed by the 792sample distance (in sec) of the coefficients. SH stores this value 793and permits the user to apply this filter only to traces of this 794sample rate. The next line is a normalization number and is 795usually 1. Then the number of$a$--coefficients is specified, which 796is \exm{3}\ in the example file. That means, this number is followed 797by 3 coefficients, namely$a_0$,$a_1$and$a_2$. The same holds 798for the$b$--coefficients. The example file gives three$b$'s, 799$b_0$,$b_1$and$b_2$. Please note that in the filter file 800a$b_0$must be specified which does not appear in the above 801formula (in fact, this is the coefficient of the$r_n$on the left 802side of the equation). SH eliminates$b_0$after reading the 803file by dividing all$a_i, i=0,\ldots,k$and$b_j, j=1,\ldots,l$by 804$b_0$. After the 805coefficient$b_2$, the first filter in the example file ends. 806The next line contains the separation character "\verb'@'", 807indicating that another recursive filter is appended. The second 808filter starts with the ID number \exm{3}\ for recursive filters 809(there is no more magic number). Then, again, follows the 810sample distance, the normalization, the$a$--coefficients and 811the$b$--coefficients. This example file contains a cascade 812of two recursive filters. You can use up to 5 filters in one 813file. The command \cmd{fili r wwssn\_sp}\ reads the whole filter 814file into memory. The default extension \exm{.FLR}\ may be 815omitted. Recursive filters of a previous 816\cmd{fili}--command are replaced by this cascade (FFT filters 817are not affected by this command). The command \cmd{filter r all}\ 818applies the filter cascade to all of the traces on display. 819The result traces are appended to the top of the display. As 820for FFT filters you can specify a time window by optional 821parameters (number 3 and 4). These denote the lower and upper 822bound of the window (in sec) relative to the time axis. 823 824 825\subsection{Tabulated Filters} 826 827Sometimes a transfer function may be given as a tabulated function 828instead of poles and zeroes or it is desirable to create an 829acausal filter in the frequency domain. In such cases you can 830use the tabulated filters of SH. This is a text file containing 831the tabulated values of amplitude and phase transfer functions. 832These tabulated values may be non--equidistant. 833The filter process is performed similar to the FFT filters. 834A copy of the input trace in transformed to the frequency domain 835and each frequency sample is multiplied by an interpolated value 836of the tabulated filter. The amplitude and phase function of 837the filter are both linearly interpolated. The filtered trace 838is transformed back to the time domain and displayed on screen. 839 840A simple example file \exm{TRAPEZ.FLT}\ of a tabulated filter 841is listed below. 842 843\begin{verbatim} 844! file TRAPEZ.FLT 845! ============ 846! 847! simple tabulated filter 848! 8491357913578 8502 8516 8520.0 0.0 0.0 8530.02 0.0 0.0 8540.03 1.0 0.0 8550.3 1.0 0.0 8560.5 0.0 0.0 857100.0 0.0 0.0 858\end{verbatim} 859 860The first lines with a "\exm{!}"--character in the first column 861are comments. The first line after the comments is the well--known 862magic number \exm{1357913578}. It is followed by the ID number 863\exm{2}\ of tabulated filters. The next line contains the number 864of tabulated filter values (here \exm{6}). Then follows one line 865for each point in the frequency domain. Every line consists of 866three numbers. First the frequency in Hz, then the amplitude 867function and at last the phase function. The example shows a 868trapezoidal amplitude function and a zero phase function. The 869transfer function is flat (amplitude 1) between 0.03\,Hz and 0.3\,Hz. 870Designing such a filter you should make sure that the tabulated 871function covers at least the area in frequency domain which is 872used by the input trace, that is from zero to the nyquist 873frequency. If you fail to do so the filter command will abort 874with an error message. The filter file is read in with the 875command \cmd{fili t trapez}. The default extension \cmd{.FLT}\ 876may be omitted. The filter operation is done by \cmd{filter t <list>}, 877where \cmd{<list>}\ denotes any trace list. As for the other filters 878you can specify a time window in optional parameters number 3 and 4. 879 880 881\subsection{Special Filters} 882 883SH knows some other filter operations which are used sometimes. 884The Hilbert transformation is one of them. It is applied with 885the command \cmd{filter h <list>}, where \cmd{<list>}\ may be any 886trace list like \cmd{4-6}\ or \cmd{2}\ or \cmd{all}. As for any 887other filter commands, the input traces remain unchanged and the 888new output traces are appended to the top of the window. You can 889restrict this operation to a time window if you specify the lower 890and upper bound (in sec, relative to the time axis) as parameter 891numbers 3 and 4, respectively. 892\smallskip 893 894Another option is the attenuation of a trace by an attenuation 895operator 896$897 A(\omega) = e^{ -\frac{1}{2}\omega t^* + 898 i\frac{\omega}{\pi}\ln\frac{\omega}{\omega_N} } 899$ 900where$t^*$is the attenuation parameter and$\omega_N$is the 901Nyquist frequency.$t^*$is passed to the command as parameter 902number 5. If you don't want to set a time window for the operation, 903then you have to enter empty parameters 3 and 4. The command to 904attenuate the first three traces on display by a$t^*$of 0.5\,s is 905\cmd{filter a 1-3;;;0.5}. 906\smallskip 907 908One option related to filter operations remains to be mentioned 909in this section. It is the computation of a minimum delay signal. 910Input is either an arbitrary time 911signal or an autocorrelation. If a time signal is given, the 912command is \cmd{filter m <list>;;;<shift>}, for an autocorrelation 913it is \cmd{filter c <list>;;;<shift>}. \exm{<list>}\ is a trace 914list like \exm{4-6}\ or \exm{all}\ and \exm{<shift>}\ is a time 915shift in s by which the output trace is shifted to the right. 916If you specify 0 for the \exm{<shift>}\ parameter then 917the signal on the output trace starts exactly at the beginning of 918the trace which is not very convenient in most cases. Of course, 919it is possible to enter a time window in parameters 3 and 4 as 920in the other filter commands. 921 922 923\section{Scaling of Amplitudes} 924 925If more than one trace is in the display window of SH one has to 926consider, how to relate the individual trace amplitudes. If the 927records of a 3--component seismometer or traces of a station array 928are displayed, everyone prefers to have the same amplification 929factors for each trace. This makes sure that the true amplitude 930ratios are shown. In other cases where several records of the 931same event from globally distributed stations are displayed or 932where filtered and unfiltered waveforms are to be compared, it is 933often more convenient to have the scaling in such a way that each 934trace is plotted with the same amplitude. Also it may be desirable 935sometimes to amplify a subset of the displayed traces in amplitude. 936SH can manage each of these problems, there exist quite a few 937commands to manipulate the trace amplitudes. This section describes 938how to use this subset of commands. 939 940It is useful to know a bit about how SH determines the actual 941display amplitudes. Each trace has two temporary info entries 942(\shi{mem-only}\ type, see section \ref{sec:InfoEntries}), called 943\shi{norm}\ and \shi{zoom}. The display amplitude results as 944the product of the seismogram amplitude (this is given by the 945sample values) and these two real numbers. The \shi{norm}\ entry is 946determined by SH before each redraw, depending on the current 947active normalization mode. The \shi{zoom}\ entry is set by the 948user. Thus exist three different ways to manipulate the trace 949amplitudes: 950\begin{enumerate} 951\item 952 Changing the normalization mode using the \cmd{norm}\ command. 953 This tells SH how to determine the normalization factor 954 (\shi{norm}\ entry) for each trace. 955\item 956 Changing the zoom factor (\shi{zoom}\ entry) via \cmd{zoom}\ 957 command. 958\item 959 Changing the sample values of the trace (commands \cmd{trcfct} and 960 \cmd{unit}). This is somewhat problematic if this is done only 961 for reasons of the trace display, because it really changes your 962 traces. If you sum these traces at a later time, they may have 963 the wrong weights. If you write the traces to a file, the 964 amplitude changes are saved as well. Therefore you should prefer 965 the commands \cmd{norm}\ and \cmd{zoom}. The entries \shi{norm}\ 966 and \shi{zoom}\ are temporary and are not saved in an output file. 967 Also, these entries don't have any influence on operations with 968 the traces, they affect the display only. 969\end{enumerate} 970 971\noindent 972{\bf point 1:} 973The normalization mode is changed by the \cmd{norm}\ command. This 974command accepts only one parameter, which must be one out of a set 975of five short strings: 976\begin{deflist}{\exm{aw}} 977\item[\exm{af}] 978 The normalization factor is the same for each trace and is 979 determined as half of the reciprocal value of the maximum 980 sample (without sign) of all displayed traces on their total 981 length (not only inside the displayed window) using the info 982 entries \shi{maxval}\ and \shi{minval}. That means, 983 all traces are normalized to the maximum value on all traces 984 within their full length. 985\item[\exm{aw}] 986 Here the normalization factor also is the same for each trace, 987 but the maximum value is determined only within the displayed 988 window. The traces are normalized to the maximum value on all 989 traces within the displayed window. Since the determination 990 of the maximum value is done before each redraw and since the 991 info entries \shi{maxval}\ and \shi{minval}\ cannot be used 992 here, this normalization mode may slow down the program 993 considerably, if long traces are to be searched. 994\item[\exm{sf}] 995 The normalization is determined for each trace separately as 996 half of the reciprocal value of the maximum sample (without sign) 997 on it's full length (not only inside the displayed window) 998 using the info entries \shi{maxval}\ and \shi{minval}. 999 That means, all traces have the same display amplitude, if the 1000 \shi{zoom}--factors are identical. 1001\item[\exm{sw}] 1002 Normalization is again determined separately, but now inside 1003 the current display window, resulting in equal display amplitudes 1004 for traces with the same zoom factor. Since the determination 1005 of the maximum value is done before each redraw and since the 1006 info entries \shi{maxval}\ and \shi{minval}\ cannot be used 1007 here, this normalization mode may slow down the program 1008 considerably, if long traces are to be searched. 1009\item[\exm{c}] 1010 All normalization factors are set to 1. This is useful for 1011 applications, where different plots must have the same 1012 amplitude scale. In all other modes the normalization depends 1013 on the sample amplitudes of the traces on display. If you make 1014 plots of two different data sets you cannot compare the amplitudes 1015 between the plots. This problem is solved, if you use the 1016 \exm{c}--mode and if you always set the same zoom factor and 1017 if you have always the same number of traces on display. But 1018 after switching to the \cmd{c}--mode, you have to be aware that 1019 the display amplitudes may look like zero (if the sample amplitudes 1020 are very small) or may be immense (for big sample amplitudes). 1021 In any case you have to find out appropriate zoom factors by 1022 yourself. 1023\end{deflist} 1024The modes \exm{af}\ and \exm{sf}\ sometimes confuse users, if 1025large amplitudes exist outside the display window. In this case 1026the display amplitudes of some or all traces are very small. 1027This can be checked either by deleting the time window or by 1028switching to the modes \exm{aw}\ or \exm{sw}. But keep in mind 1029that the latter modes can slow down the program if you deal with 1030long traces. The default mode (if not changed in the setup file) 1031is \exm{af}. 1032\smallskip 1033 1034{\bf point 2:} 1035The zoom factor is changed via the \cmd{zoom}\ command. The syntax 1036is \cmd{zoom <list> <factor>}. Since there is a \exm{<list>}\ 1037parameter, it is possible to scale the traces independently. 1038\exm{<factor>}\ is copied to the \shi{zoom}\ entry of the specified 1039traces. It remains there until it is explicitely changed. 1040Since the value is copied to the entry, a command \cmd{zoom 1 2} 1041doesn't change anything, if the first trace is already zoomed 1042by a factor of 2. But it is possible to enter relative factors 1043as well. This is done by \cmd{zoom/rel 1 2}, which magnifies the 1044display amplitude of the first trace by a factor of 2, no 1045matter what the zoom factor currently is. Traces which are created 1046by SH operations and which are appended to the top of the display, 1047get a default zoom factor which is usually 1. This means, if all 1048traces on the display have a zoom factor of 5 and a new trace is 1049created, this appears to be relatively small, because of the default 1050zoom factor of 1. However, with the command 1051\cmd{zoom/default <list> <factor>} you can change the default zoom 1052factor (and the zoom factor of the traces in \exm{<list>}). 1053 1054{\bf point 3:} 1055If all else fails (or seems to be too inconvenient) the samples 1056itself can be multiplied by a factor. But as it is mentioned 1057above, this might result in problems in future operations on 1058such traces. You have always to keep in mind that these traces 1059do not have the original sample values any more. A subset 1060\exm{<list>}\ of traces can be multiplied by a number \exm{<r>}, 1061using the command \cmd{trcfct <list> mul <r>}. On the display 1062amplitudes this will have the same effect as 1063\cmd{zoom/rel <list> <r>}. Therefore this command isn't really 1064necessary for reasons of display. More convenient is the 1065\cmd{unit}\ command. It determines the absolute maximum (without 1066sign) of a given list of traces and within a given time window. 1067This maximum is set to 1 and all other samples of the specified 1068traces are normalized with respect to this absolute maximum 1069(the sign remains untouched). A typical application is, if there 1070are two or more three--component sets of records on the screen, 1071with large amplitude differences between the sets. With 1072\cmd{unit}\ each set can get the maximum sample amplitude of 1. 1073This way the sets can be compared without loosing information 1074about the relative amplitudes within a set. The syntax of the 1075\cmd{unit}\ command is \cmd{unit <list> <lo> <hi>}. \exm{<list>}\ 1076specifies the set of traces to be normalized together. 1077\exm{<lo>}\ and \exm{<hi>}\ contain the lower and upper bound 1078of the time window in s (relative to the time axis) where to look 1079for the absolute maximum. If these parameters are omitted, the 1080full traces are used. 1081 1082 1083\section{Command Procedures} 1084\label{sec:CmdProc} 1085 1086The ability of SH to process command procedures is one of it's 1087most important features. Most of SH's internal commands 1088operate on a rather low level. Therefore SH is very flexible 1089and can be used for many different and quite special purposes. 1090On the other hand, more complex operations consist of several 1091basic instructions and require a considerable amount of keyboard 1092input. For the convenience of the user it is therefore often 1093necessary to combine these low--level instructions and create 1094more elaborate commands. Thus the user interface is optimized 1095for the solution of particular data processing problems. 1096 1097A command procedure is an editable text file. Each line of 1098this file holds a single SH command (and/or comments). The 1099commands are processed sequentially until the \cmd{return}\ 1100command is found. This terminates the execution of the current 1101procedure and returns to the parent command level which is either 1102the interactive level or another command procedure. The end of 1103file also terminates execution but it creates an error message 1104and returns to the interactive level in any case. The command 1105procedure is called by the name of the command file without 1106extension which is assumed to be \exm{.SHC}. 1107 1108\subsection{A first example} 1109 1110The usage of command procedures will be explained here by 1111developing an example file which will get more complex step 1112by step. The purpose of this command file is to perform a 11133--dimensional rotation from the recording Z,N,E--coordinate system 1114to the local ray system of the P--wave, called L,Q,T--system. 1115This rotation needs two angles, the azimuth and the angle of 1116incidence. For the first example let's assume that there exists 1117a q--file named \exm{q\_exm}\ which contains a three component 1118record with the components Z, N and E at the file positions 1, 2 1119and 3, respectively. The azimuth and angle of incidence are 1120known. Let their values be 207.2$^\circ$and 19.5$^\circ$, 1121respectively. The following procedure \cmd{rotex1}\ reads in the 1122traces, rotates them and writes the result to an output q-file, 1123named \exm{q\_out}. 1124 1125\begin{verbatim} 1126! file rotex1.shc 1127! 1128! version 1 of the 3-dim rotation procedure 1129! K. Stammler, 15-Apr-92 1130 1131del all ! delete possibly existing traces ... 1132dtw ! ... and time window 1133 1134read q_exm 1-3 ! read in Z,N,E components 1135rot 1-3 207.2 19.5 ! rotate, create three new traces 1136write q_out 4-6 ! write result traces to output q-file 1137 1138return ! return to parent level 1139\end{verbatim} 1140 1141After entering the command \cmd{rotex1}\ this procedure is executed 1142if SH can find the command file. SH looks for the file 1143\exm{rotex1.shc}\ in the current directory and in a common 1144command directory. Of course, the q--file \exm{q\_exm}\ has to 1145be in your current directory, otherwise you have to specify the 1146directory explicitely. 1147 1148\subsection{Command Parameters} 1149 1150In practice the above command procedure is not very useful, 1151because the azimuth and angle of incidence are given as fixed 1152values in the file. These angles are usually different for 1153each event. Instead of changing the text each time, it is 1154much more convenient to pass these values as parameters to 1155the procedure. In the command procedure the parameter number 1156\exm{N}\ is accessed by the expression \exm{\#N}. So the rotation 1157command \exm{rot 1-3 207.2 19.5}\ of the procedure should be 1158replaced by \exm{rot 1-3 \#1 \#2}. Then the procedure works fine as 1159long as the user passes the azimuth as the first parameter and 1160the angle of incidence as the second. But imagine the case that 1161the user can't remember the order of the parameters or doesn't 1162know the parameters at all. In particular for more complex 1163procedures with five or ten parameters this problem would be even 1164worse. Guessing parameters is very tedious and annoying. 1165Therefore a command is implemented which prompts the user for 1166the parameters if he wants to. Besides that this command 1167assigns default values to parameters which are left empty in 1168the calling command line. For this reason the command is called 1169\cmd{default}. The first parameter of the \cmd{default}--command 1170specifies the number of the parameter, the second contains the 1171default value. If this is empty, no default value is assigned. 1172All following parameters are used as a prompt text if the user 1173is to be prompted for input. If the command procedure is called 1174without any parameters (not even an empty parameter) all parameters 1175of the procedure are prompted using the given prompt text of the 1176\cmd{default}--command. If the user specifies at least one parameter 1177(even if it is empty), no parameter is prompted. Instead, every 1178empty or not specified parameter gets its default value from 1179the \cmd{default}--command. The updated version of the rotation 1180procedure now looks like this: 1181 1182\begin{verbatim} 1183! file rotex2.shc 1184! 1185! version 2 of the 3-dim rotation procedure 1186! K. Stammler, 15-Apr-92 1187 1188default 1 ;; input q-file ! input file 1189default 2 ;; azimuth ! no default for azimuth 1190default 3 0. angle of incidence ! default 0 for incidence 1191default 4 q_out output q-file ! output file 1192 1193del all ! delete possibly existing traces ... 1194dtw ! ... and time window 1195 1196read #1 1-3 ! read in Z,N,E components 1197rot 1-3 #2 #3 ! rotate, create three new traces 1198write #4 4-6 ! write result traces to output q-file 1199 1200return ! return to parent level 1201\end{verbatim} 1202 1203The command line \exm{rotex2 q\_ex 207.2 19.5 q\_out}\ is now equivalent 1204to the first version of the procedure \exm{rotex1}. If you enter 1205\exm{rotex2 q\_ex 207.2}, the angle of incidence defaults to 0 and 1206the output file defaults to \exm{q\_out}\ without 1207any prompting. The plain command \exm{rotex2}\ without 1208parameters let SH prompt you for all of the parameters in the 1209specified order, using the prompts given in the \cmd{default}\ 1210command. At the third and fourth parameter, 1211additionally to the prompt text, a default value is offered. 1212You can accept it just by hitting the return key, otherwise you 1213have to enter another value. You should use the 1214\cmd{default}--command on every parameter in order to supply 1215the user with information texts about the parameters. If you do 1216so, the command procedure behaves exactly like an internal 1217command. 1218 1219\subsection{Variables in SH} 1220\label{sec:Variables} 1221 1222The recent version of the rotation procedure is not really a 1223big improvement for the user. He still needs to know the rotation 1224angles for each event and has to pass it to the command 1225procedure. SH can determine these rotation angles with the 1226command \cmd{mdir}. But variables are needed to store the 1227results of \cmd{mdir}\ and to pass them to \cmd{rot}. 1228 1229The concept of variables in SH is similar to other programming 1230languages. There exist global and local variables. Local 1231variables are visible only inside the command procedure where 1232they were defined. The local variables are deleted when the 1233procedure is terminated. Global variables are visible in any 1234command level, that means in all command procedures and in the 1235interactive level. In order to keep a good programming style 1236there shouldn't be defined too many global variables (as in any other 1237language). Usually the four predefined global variables are 1238sufficient. Their names are \exm{g1}, \exm{g2}, \exm{g3}\ and 1239\exm{ret}. These variables are needed only to store return values of 1240command procedures. 1241 1242All variables must be defined. Any access to an undefined variable 1243results in an error message. The definition command is \cmd{sdef} 1244(symbol definition). The first parameter is the name of the 1245variable to be defined. An optional second parameter specifies 1246its initial value. By default the defined variables are local. 1247For a global definition the qualifier \cmd{/global}\ is required. 1248SH variables have no type. That means in a variable you can store 1249any information, like integers, floating point numbers, strings and 1250others. SH does not check any type information, so you have to be 1251aware of what you are doing. In fact, any values are stored as 1252strings and are converted internally if necessary. To assign 1253a value to a variable, it has to be passed to a command which 1254returns an output value. In this case a \cmd{\&}--character has 1255to be placed in front of the variable name, to indicate a write 1256access. A read access to a variable is made by a preceding 1257\cmd{"}--character. The command parser assumes that any word 1258in the command line beginning with a double quote is a defined 1259variable and replaces the expression by its current value. 1260 1261Now follows version 3 of the rotation procedure 1262which let the user select a time window to determine the rotation 1263angles via \cmd{mdir}--command. 1264 1265\begin{verbatim} 1266! file rotex3.shc 1267! 1268! version 3 of the 3-dim rotation procedure 1269! K. Stammler, 16-Apr-92 1270 1271default 1 ;; input q-file ! input file 1272default 2 q_out output q-file ! output file 1273 1274sdef azim ! define azimuth variable, no init 1275sdef inci ! define angle of incidence, no init 1276 1277del all ! delete possibly existing traces ... 1278dtw ! ... and time window 1279 1280read #1 1-3 ! read in Z,N,E components 1281echo select time window ! message to the user 1282mdir 1-3 *;;&azim &inci ! determine angles from time window 1283rot 1-3 "azim "inci ! rotate, create three new traces 1284write #2 4-6 ! write result traces to output q-file 1285 1286return ! return to parent level 1287\end{verbatim} 1288 1289In earlier versions of SH \cmd{mdir}\ won't work properly inside 1290a command procedures if the time window is user--selected 1291(\verb+*+--parameter). In this case two additional variables 1292holding begin and end of the time window must be defined. Their 1293values are assigned using the command \cmd{time} twice (example: 1294\verb+time;;&start+). The window bounds must be passed to the 1295command \cmd{mdir}\ by these variables. 1296 1297\subsection{The Command {\tt calc}} 1298 1299An important command for assigning values to variables is \cmd{calc}. 1300It performs simple numerical computations as well as text and time 1301manipulations. The general syntax is: 1302\begin{verbatim} 1303 calc <type> <outvar> = <operand1> [<op> <operand2>] [<p>] 1304\end{verbatim} 1305This fixed structure allows only one operation per command line. 1306Here the same syntax rules hold as for any other command. That 1307means in particular that the "\cmd{=}" character and the operator 1308\cmd{<op>}\ are treated as ordinary parameters which must be 1309separated by blanks (or semicolons) from the preceding and following 1310expressions. \verb+<type>+ specifies the type of the operation. 1311This is necessary, because all variables can have any type and 1312SH needs to know whether there is to compute an integer addition 1313or a floating point addition or a string concatenation, for example. 1314\verb+<outfile>+ gives the name of the variable (preceding the 1315\exm{\&} character) where to store the result of the operation. 1316If only one operand is specified the instruction performs a plain 1317assignment of the value of \verb+<operand1>+ to \verb+<outvar>+. 1318\verb+<p>+ is an additional parameter which is used only in a 1319few special operations. 1320\bigskip 1321 1322\noindent 1323Valid operators for the type "\exm{i}" (integer) are: 1324\begin{deflist}{\exm{cnv\_julian}} 1325\item[\exm{+}] 1326 Adds the two operands. 1327\item[\exm{-}] 1328 Subtracts \verb+<operand2>+ from \verb+<operand1>+. 1329\item[\exm{*}] 1330 Multiplies the two operands. 1331\item[\exm{div}] 1332 Divides \verb+<operand1>+ by \verb+<operand2>+ without remainder. 1333\item[\exm{mod}] 1334 Remainder of the division \verb+<operand1>+ by \verb+<operand2>+. 1335\end{deflist} 1336\bigskip 1337 1338\noindent 1339Valid operators for the type "\exm{r}" (real) are: 1340\begin{deflist}{\exm{cnv\_julian}} 1341\item[\exm{+}] 1342 Adds the two operands. 1343\item[\exm{-}] 1344 Subtracts \verb+<operand2>+ from \verb+<operand1>+. 1345\item[\exm{*}] 1346 Multiplies the two operands. 1347\item[\exm{div}] 1348 Divides \verb+<operand1>+ by \verb+<operand2>+. 1349\item[\exm{abs}] 1350 Removes the sign of \verb'<operand1>'. No second operand. 1351\item[\exm{arctan2}] 1352 Computes the arc tangens of \verb'<operand1>/<operand2>' in 1353 degrees. Works correct even if \verb'<operand2>' is equal or 1354 close to zero. 1355\item[\exm{power}] 1356 Takes \verb'<operand1>' to the \verb'<operand2>'--th power. 1357\end{deflist} 1358Additionally there exist a number of single argument functions. 1359The argument is specified by \verb'<operand1>', \verb'<operand2>' 1360must be empty. All trigonometric functions (and their inverse) 1361work with degrees as input (output). A complete list of the 1362functions is \exm{sin, cos, tan, arcsin, arccos, arctan, 1363sinh, cosh, tanh, exp, log, ln, sqrt}. 1364\bigskip 1365 1366\noindent 1367Valid operators for the type "\exm{s}" (string) are: 1368\begin{deflist}{\exm{cnv\_julian}} 1369\item[\exm{+}] 1370 Concatenation of \verb'<operand1>' and \verb'<operand2>' 1371 with a blank in between. 1372\item[\exm{parse}] 1373 Extracts the \verb'<operand2>'--th word from \verb'<operand1>'. 1374 Separation characters are blanks and semicolons. 1375 \verb'<operand2>' must be integer. 1376\item[\exm{extract}] 1377 Extracts \verb'<p>' characters from the string \verb'<operand1>' 1378 starting at position \verb'<operand2>'. The first character 1379 of \verb'<operand1>' has number 1 (not 0). \verb'<operand2>' and 1380 \verb'<p>' must be integer. 1381\end{deflist} 1382\bigskip 1383 1384\noindent 1385Valid operators for the type "\exm{t}" (time) are: 1386\begin{deflist}{\exm{cnv\_julian}} 1387\item[\exm{tdiff}] 1388 Computes the difference of two absolute time values 1389 \verb'<operand1>' and \verb'<operand2>'. The difference is 1390 given in seconds and stored as a floating point number. 1391\item[\exm{tadd}] 1392 Adds \verb'<operand2>' seconds to the absolute time value 1393 \verb'<operand1>'. \verb'<operand2>' must be a floating point 1394 number, negative numbers are accepted. The result is again an 1395 absolute time value. 1396\item[\exm{cnv\_julian}] 1397 Converts the day number \verb'<operand2>' of the year 1398 \verb'<operand1>' into day and month. The two output integers 1399 are stored in \verb'<outvar>' separated by a blank. 1400 Both operands must be integer (in an appropriate range). 1401\item[\exm{make\_time}] 1402 Converts an absolute time string in numeric format (examples: 1403 \cmd{"30,\-12,\-85,\-5,\-30,\-20,\-5"}\ or 1404 \cmd{"85/12/30/5/30/20/5"}) 1405 to the standard format of absolute time 1406 (\cmd{"30-DEC-1985\_5:30:20.005"}). 1407\end{deflist} 1408\bigskip 1409 1410\noindent 1411Examples: 1412\begin{verbatim} 1413 calc i &cnt = "cnt + 1 ! increments counter cnt 1414 calc r &num = "a * "b ! multiplies two floating points 1415 calc r &num = "x sqrt ! takes square root of x 1416 calc s &str = "str parse 1 ! keeps first word only in str 1417 calc s &str = "x extract 5 3 ! extracts chars 5 to 7 from x 1418 calc t &dif = ^p-onset(3) tdiff ^start(3) 1419 ! computes time offset of P onset 1420 ! relative to start of trace 3 1421\end{verbatim} 1422 1423With this command the rotation procedure can run completely 1424without user interaction. Supposition is, however, that the 1425P--wave onset is inserted to the q--file header. There exists 1426a predefined info entry, called \exm{p-onset}. It should contain 1427the absolute time of the P onset. The user still has to select 1428the P--wave times for all his events like in the previous versions 1429of the procedure, but now he has to do it only once. Moreover, this 1430process is decoupled from the rotation procedure and the gathered 1431information can be used for other applications as well. The 1432insertion of the onset time is done by two commands if the event 1433is already on screen. The command \cmd{time \&g1}\ let the user 1434select the onset time by graphic cursor and stores the result 1435in the (global) variable \cmd{g1}\ which is predefined. Of course, 1436you can use any other variable as well. The second command is 1437\cmd{set/file all p-onset "g1}, which inserts the determined time 1438to the headers of all traces on display. For details see command 1439\cmd{set}. Another info entry used in the command procedure is the 1440start time of the trace. 1441This is also an absolute time, the name of this (predefined) entry 1442is \cmd{start}. Now follows the automated version 4 of the rotation 1443procedure. It writes the L--, Q-- and T--components to separate 1444files. 1445 1446\begin{verbatim} 1447! file rotex4.shc 1448! 1449! version 4 of the 3-dim rotation procedure 1450! K. Stammler, 20-Apr-92 1451 1452default 1 ;; input q-file ! input file 1453default 2 q_out output q-file prefix ! output file prefix 1454default 3 2. window width (sec) ! time window for 1455 ! determining angles 1456 1457sdef azim ! azimuth 1458sdef inci ! angle of incidence 1459sdef start ! start of time window (relative time) 1460sdef end ! end of time window (relative time) 1461 1462del all ! delete possibly existing traces ... 1463dtw ! ... and time window 1464 1465read #1 1-3 ! read in Z,N,E components 1466calc t &start = ^p-onset(1) tdiff ^start(1) 1467 ! determine relative time of P-onset 1468calc r &end = "start + #3 ! get end of time window 1469mdir 1-3 "start "end &azim &inci 1470 ! determine angles in computed window 1471rot 1-3 "azim "inci ! rotate, create three new traces 1472write |#2|_l| 4 ! write L-component to L-file 1473write |#2|_q| 5 ! write Q-component to Q-file 1474write |#2|_t| 6 ! write T-component to T-file 1475 1476return ! return to parent level 1477\end{verbatim} 1478 1479 1480\subsection{Loops} 1481 1482Version 4 of the rotation procedure is already well developed. 1483It enables the user to process several 3--component records. But 1484suppose he has 100 events stored on q--files. He would have to 1485type in 100 similar command lines. Even if he would write 1486a command procedure calling \cmd{rotex4}\ 100 times, he would have 1487to insert the 100 file names to the procedure text. It is more 1488convenient to store the 100 file names in a separate file (this 1489may be created with a directory command redirected to a file) and 1490process all files in a command loop. 1491 1492For loop structures SH provides two commands, \cmd{goto}\ and 1493\cmd{if}. \cmd{goto}\ has the syntax 1494\begin{verbatim} 1495 goto <label> 1496\end{verbatim} 1497This command requests SH to jump to the specified label 1498\exm{<label>}. \exm{<label>}\ is a text string with a colon 1499":" at the end. SH looks for this label inside the current 1500command procedure. If the qualifier \exm{/forward}\ is specified 1501it starts looking at the current position, otherwise it rewinds 1502the command file before searching. A label is any text string at 1503the beginning of a command line that ends with a colon. Labels are 1504ignored in ordinary execution of command procedures. They only serve 1505as jump addresses. Label lines must not contain any executable 1506commands. 1507 1508The command \cmd{if}\ performs the conditional execution of an 1509instruction. It's syntax is 1510\begin{verbatim} 1511 if <e1> <cmp> <e2> <cmd> [<label>] 1512\end{verbatim} 1513The sequence \cmd{<e1> <cmd> <e2>}\ is a compare operation between 1514two expressions \cmd{<e1>}\ and \cmd{<e2>}\ with a compare 1515operator \cmd{<cmp>}. If the result of this comparison is true, 1516the instruction \cmd{<cmd>}\ is executed. Only two SH instructions 1517are permitted in place of \cmd{<cmd>}, namely \cmd{return}\ and 1518\cmd{goto}. \cmd{return}\ terminates the current command 1519procedure and \cmd{goto}\ jumps to a specified label \cmd{<label>}. 1520 1521The compare operator \cmd{<cmp>}\ specifies the actual comparison 1522and the type of the expressions \cmd{<e1>}\ and \cmd{<e2>}. Valid 1523operators are: 1524\begin{description} 1525\item[\exm{eqi}] \ integer comparison, \cmd{<e1>} is equal to \cmd{<e2>} 1526\item[\exm{nei}] \ integer comparison, \cmd{<e1>} is not equal to \cmd{<e2>} 1527\item[\exm{lei}] \ integer comparison, \cmd{<e1>} is less or equal \cmd{<e2>} 1528\item[\exm{lti}] \ integer comparison, \cmd{<e1>} is less than \cmd{<e2>} 1529\item[\exm{gei}] \ integer comparison, \cmd{<e1>} is greater or equal \cmd{<e2>} 1530\item[\exm{gti}] \ integer comparison, \cmd{<e1>} is greater than \cmd{<e2>} 1531\item[\exm{eqr}] \ float comparison, \cmd{<e1>} is equal to \cmd{<e2>} 1532\item[\exm{ner}] \ float comparison, \cmd{<e1>} is not equal to \cmd{<e2>} 1533\item[\exm{ler}] \ float comparison, \cmd{<e1>} is less or equal \cmd{<e2>} 1534\item[\exm{ltr}] \ float comparison, \cmd{<e1>} is less than \cmd{<e2>} 1535\item[\exm{ger}] \ float comparison, \cmd{<e1>} is greater or equal \cmd{<e2>} 1536\item[\exm{gtr}] \ float comparison, \cmd{<e1>} is greater than \cmd{<e2>} 1537\item[\exm{eqs}] \ string comparison, \cmd{<e1>} is equal to \cmd{<e2>} 1538\item[\exm{nes}] \ string comparison, \cmd{<e1>} is not equal to \cmd{<e2>} 1539\end{description} 1540 1541With this supplement it is possible to write a command procedure 1542to apply \cmd{rotex4}\ to all q--files listed in a list file. 1543 1544\begin{verbatim} 1545! file rotex5.shc 1546! 1547! version 5 of the 3-dim rotation procedure 1548! K. Stammler, 21-Apr-92 1549 1550default 1 ;; q-file list ! name of list file 1551default 2 1 first file ! first file to process 1552default 3 %#1(0) last file ! last file, default is last line 1553default 4 q_out output file ! output file prefix 1554default 5 2. time window ! width of window 1555 1556sdef cnt #2 ! file counter init. to start line 1557sdef qfile ! name of current q-file 1558 1559nr ! switch off redraw, incr. speed 1560loop_start: ! start of loop (only label) 1561 if "cnt gti #3 goto/forward loop_exit: 1562 ! exit if counter exceeds last file 1563 calc s &qfile = %#1("cnt) ! get current q-file from list 1564 echo processing file "qfile! message to the user 1565 rotex4 "qfile #4 #5 ! call rotex4 1566 calc i &cnt = "cnt + 1 ! increment counter 1567goto loop_start: ! repeat loop 1568loop_exit: ! loop exit 1569rd ! switch on redraw again 1570 1571return ! return to parent level 1572\end{verbatim} 1573 1574This example file also demonstrates nesting of command procedures, 1575because this procedure, \cmd{rotex5}, calls another procedure, 1576\cmd{rotex4}. Nesting is permitted up to a level of nine calls, 1577which is very likely sufficient in all applications. In the 1578above example the \cmd{nr}\ command switches off the automatic 1579redraw, which increases execution speed. But don't forget to 1580switch it on again (\cmd{rd}). 1581 1582 1583 1584\subsection{Execution Flags} 1585\label{sec:ExecFlags} 1586 1587Execution flags control some details in the processing of a 1588command procedure (some affect the interactive level as well). 1589Examples are the suppression of error 1590messages, abortion of procedures on errors and tracing through 1591a procedure. Such features can be switched on and off by the 1592\cmd{switch}\ command. It's syntax is \cmd{switch <flag> <on/off>}. 1593\exm{<flag>}\ is the name of the execution flag and \exm{<on/off>}\ 1594is either \exm{on}\ or \exm{off}. A list of all flags is given 1595below: 1596 1597\begin{deflist}{\exm{cmderrstop}} 1598\item[\exm{cmderrstop}] X--flag. 1599 Controls whether the command procedure is aborted on errors. 1600 If it is switched on, SH returns to the interactive level 1601 after displaying the error message. Usually this option is 1602 switched on. After such an error the command procedure should 1603 be corrected. Be careful in switching off this flag, because 1604 you may get lot of messages of subsequent errors. In the worst 1605 case you may create an infinite loop in the command procedure 1606 and you will have to abort SH in a very crude way. 1607 Default is \exm{on}. 1608\item[\exm{sherrstop}] A--flag (Abort). 1609 Controls whether SH is terminated after an error occurred. This 1610 is useful only if SH is executed in batch mode. Default is 1611 \exm{off}. 1612\item[\exm{verify}] V--flag. 1613 Controls whether a verification of each command is printed before 1614 it is executed. With this option the translation of the command 1615 lines can be checked, since the command is printed after 1616 the translation process. Default is \exm{off}. 1617\item[\exm{echo}] E--flag. 1618 Controls whether all commands are echoed (without translation) 1619 before execution. Default is \exm{off}. 1620\item[\exm{step}] T--flag (Trace). 1621 Controls whether SH prompts the user for keyboard input 1622 (\exm{<Return>}--key) before each command. Useful in 1623 combination with V--flag. Default is \exm{off}. 1624\item[\exm{protocol}] P--flag. 1625 Controls whether the interactive commands of the user are logged 1626 in the protocol file of SH. Default is \exm{on}. 1627\item[\exm{capcnv}] C--flag. 1628 Controls whether each input character is converted to uppercase. 1629 Default is \exm{on}. 1630\item[\exm{noerrmsg}] Q--flag (Quiet). 1631 If this switch is on, no error messages (and no warning bell) 1632 is printed. Useful in combination with X--flag if possibly 1633 occurring errors are handled by the command procedure. 1634 Default is \exm{off}. 1635\item[\exm{chatty}] I--flag (Info). 1636 Some commands give an explaining text if this flag is switched 1637 on (like command \cmd{sum}). This info text may be switched off 1638 if the internal structure of the command procedure should be 1639 hidden from the user. Default is \exm{on}. 1640\end{deflist} 1641 1642By default, the switches are changed only locally within the 1643current command procedure. The flags are reset when the procedure 1644terminates. To change flags globally, the qualifier \exm{/global}\ 1645must be entered on the \cmd{switch}\ command. Then the switches 1646remain in the specified state until they are changed again by a 1647\cmd{switch/global}\ command. Besides the \exm{switch}\ command 1648there exists another method 1649to change the flags. When a command procedure is called, valued 1650qualifiers \exm{/flags}, \exm{/flags+}\ or \exm{/flags-}\ may 1651be applied. The value of the qualifier is a string consisting 1652of one or more flag characters. The flag characters are given 1653in the above list. \exm{/flags}\ sets all specified flags to 1654\exm{on}, all others to \exm{off}. \exm{/flags+}\ sets all 1655specified flags to \exm{on}, all others remain unchanged. 1656\exm{/flags-}\ set all specified flags to \exm{off}, all others 1657remain unchanged. The flags are changed only locally within the 1658called command procedure, unless the \exm{/global}\ qualifier 1659is also specified. With the \exm{/global}\ qualifier the 1660changes affect all child levels of the called procedure. 1661 1662 1663 1664\subsection{Debugging Tools} 1665 1666Most of the execution flags mentioned in the last section are not 1667very important for most users. But two of them are very useful 1668if a command procedure contains a mistake which must be 1669detected. With the V--flag all translated commands can be listed 1670in the dialog window. Usually the last command before the 1671error message caused the error. In some more complicated cases 1672the whole procedure must be traced step by step. Additionally 1673to the V--flag, the T--flag lets the user check each command 1674carefully by prompting for keyboard input (\exm{<Return>}--key) 1675before each command. If you want to debug the command procedure 1676\exm{bugproc}, you have to enter \cmd{bugproc/flags+=v}. 1677Possibly existing command parameters can be passed as usual: 1678\cmd{bugproc/flags+=v p1 p2}. This call enables the command 1679verification. If you want to switch on trace mode as well, the 1680command is \cmd{bugproc/flags+=vt}. The flags are set only in 1681\exm{bugproc}, if \exm{bugproc}\ calls another command procedure, 1682this is processed without verifying and trace mode. To make SH 1683tracing all child levels as well, type in 1684\cmd{bugproc/flags+=vt/global}. If the error is detected, 1685it may be tedious to continue tracing until the procedure 1686terminates. An input of "\verb'@'" terminates tracing (and 1687the command procedure). Of course, the V-- and T--flags may 1688be set by the \cmd{switch}\ command as well, but then you have 1689to change the text of the command procedure. 1690 1691In general when a command procedured is aborted by an error a 1692{\em status report file\/} is created in the SH scratch directory. 1693The file name is a concatenation of the SH Session ID and the 1694string \exm{ERR.STX}. The Session ID always starts with 1695\exm{SH}\ or \exm{SH\$}\ or \exm{SH\_}, followed by a random number.
1696The random number is necessary to make each SH session ID unique on a
1698the Session ID string to avoid interference of different SH
1699sessions with each other.  The same holds for the status report files.
1700A typical name for a status file on VMS is \exm{SH\$2354\_ERR.STX}. 1701It contains error number, error message and the calling chain 1702(all levels) of the command procedures including the line 1703numbers where the error occurred. Also given are the execution 1704flags, all defined local (named {\em symbols set 0\/}) and global 1705(named {\em symbols set 1\/}) variables and all parameters and 1706qualifiers passed to the procedure. This information is very 1707helpful for debugging command procedures. 1708 1709 1710 1711 1712\section{Internal Variables} 1713\label{sec:InternVar} 1714 1715Internal variables are a bit different from the local and global 1716variables that the user can define with \cmd{sdef}. They are 1717a fixed set and are defined internally by SH. Also they do not 1718contain information about traces as the trace info entries do. 1719Internal variables are read--only for the user. Some of them 1720reflect SH status parameters, like \exm{\$dsptrcs}\ or
1721\exm{\$tottrcs}, others contain fixed values, like all the character 1722variables (\exm{\$blank}, \exm{\$dollar}, \ldots). All names 1723start with a "\exm{\$}"--character and are replaced by the command
1724interpreter by it's current value.  A complete list is:
1725
1726\begin{deflist}{\exm{\$timeaxisstyle}} 1727\item[\exm{\$dsptrcs}]
1728   Number of traces in the display window.
1729\item[\exm{\$tottrcs}] 1730 Total number of traces in memory. 1731\item[\exm{\$status}]
1732   Return status of the last executed command.  Zero means
1733   successful completion, any other value is an error number.
1734\item[\exm{\$systime}] 1735 Current system date and time string. This is not yet implemented 1736 in all operating systems. 1737\item[\exm{\$version}]
1738   Returns current version of SH.
1739\item[\exm{\$dsp\_x}] 1740 Returns the lower bound of the current time window (set by command 1741 \cmd{stw}). 1742\item[\exm{\$dsp\_xmax}]
1743   Returns the upper bound of the current time window (set by command
1744   \cmd{stw}).
1745\item[\exm{\$dsp\_w}] 1746 Returns the width of the current time window (set by command 1747 \cmd{stw}). 1748\item[\exm{\$dsp\_y}]
1749   Returns the lower bound of the current vertical window
1750   (y--window, set by command \cmd{syw}).
1751\item[\exm{\$dsp\_ymax}] 1752 Returns the upper bound of the current vertical window 1753 (y--window, set by command \cmd{syw}). 1754\item[\exm{\$dsp\_h}]
1755   Returns the width of the current vertical window (y--window,
1756   set by command \cmd{syw}).
1757\item[\exm{\$titlestyle}] 1758 Returns style block number of the title text lines. For 1759 additional information about attribute blocks, see section 1760 \ref{sec:AttribBlocks}. 1761\item[\exm{\$trcinfostyle}]
1762   Returns style block number of the trace info text
1763\item[\exm{\$zerotrcstyle}] 1764 Returns style block number of the line attributes of zero traces 1765\item[\exm{\$timeaxisstyle}]
1766   Returns style block number of the line style of the time axis
1767   and the label text
1768\item[\exm{\$markstyle}] 1769 Returns style block number of the marker lines 1770\item[\exm{\$x}]
1771   This is a special variable, pointing to the currently drawn
1772   trace on the display.  It is useful only in connection with
1773   the command \cmd{trctxt}.
1774\end{deflist}
1775
1776\noindent
1777Additionally there exist character values which return special
1778characters.  These variables may be indexed, like info entries.
1779The index number in parantheses is interpreted as a repeat counter.
1780For example, the expression \exm{\$blank(10)}\ returns a string 1781of ten blanks. You need the \exm{\$blank}\ variable if you want
1782to pass a string parameter which contains blanks.  If you would
1783specify the blanks in the parameter directly, SH wouldn't regard
1784the string as a single parameter and the parameters would be passed
1785incorrectly.  The correct parameter specification of an example
1786parameter "\exm{text with blanks}" is:
1787\begin{verbatim}
1788   |text|$blank|with|$blank|blanks|
1789\end{verbatim}
1790Besides \exm{\$blank}\ other special characters are available. 1791The names are self--explaining, here follows only a list of their 1792names: \exm{\$exclamation, \$quotes, \$dollar, \$percent, 1793\$hat, \$bar, \$slash, \$number}. You can create any ASCII 1794character with a \exm{\$hexchar??}--expression.  The two
1795question marks stand for the two digits of the character's
1796ASCII code (hexadecimal).  For example, two consecutive horizontal
1797tabulators are created by \exm{\$hexchar09(2)}. 1798 1799 1800\section{Output Attributes} 1801\label{sec:AttribBlocks} 1802 1803Every output, text or lines, to the graphics window of SH is 1804controlled by attribute blocks. An attribute block stores 1805information, how thick a line is drawn, which line style and 1806which colour is used. Also it determines the text attributes 1807like character height, font and colour. There are several 1808attribute blocks available, the exact number depends on the 1809actual graphics interface (at least 10). Most of these blocks 1810are for free use, but some are reserved for special output items. 1811 1812To change an entry in an attribute block you have to use the 1813command \cmd{fct setstyle <block> <item> <value>}. \cmd{<block>}\ 1814specifies the attribute block number, \cmd{<item>}\ the item to 1815be changed and \cmd{<value>}\ it's new value. Valid items are: 1816\begin{deflist}{\exm{linestyle}} 1817\item[\exm{linewidth}] 1818 Set line width. \exm{<value>}\ specifies the line width in 1819 pixels. 1820\item[\exm{linestyle}] 1821 Set line style. \exm{<value>}\ is an integer number specifying 1822 the line style. Default style is 0 (continuous line). All 1823 other styles are dashed or dotted lines. 1824\item[\exm{color}] 1825 Set line colour. \exm{<value>}\ is an expression defining the 1826 colour. In X--Window and VWS there must be specified three 1827 real numbers between 0 and 1, separated by commans (no blanks). 1828 These numbers are the red, green and blue fractions of the 1829 output colour. Usually, there are colour files \exm{RED.STX}, 1830 \exm{YELLOW.STX}\, \exm{GREEN.STX}\ and so on in the 1831 \exm{globals}--directory of SH. 1832\item[\exm{charsize}] 1833 Set the size of characters. \exm{<value>}\ specifies the 1834 character height in units of window height. For example, the 1835 labelling of the time axis has usually the size 0.02. 1836\item[\exm{font}] 1837 Set character font. \exm{<value>}\ contains the font number. 1838\item[\exm{wrmode}] 1839 Set writing mode. \exm{<value>}\ is either \exm{replace}\ or 1840 \exm{xor}. \exm{replace}\ is the default mode. 1841\end{deflist} 1842 1843As mentioned above, some attribute blocks are reserved for special 1844use. The actual numbers of these blocks may be different in each 1845implementation and they may change in future versions of SH. 1846Therefore are internal variables defined, which contain the attribute 1847block numbers of various output items. A complete list of these 1848internal variables can be found in section \ref{sec:InternVar}. An 1849example is \exm{\$markstyle}, which is the style block number of
1850the vertical trace markers (lines) and their labelling (text).
1851Usually the marker lines are red (on coloured screens).  If you
1852want to change the line width to five pixels, you have to enter
1853\cmd{fct setstyle \$markstyle linewidth 5}. All following 1854markers are then thick red lines. Of course, you can change 1855the colour to blue: \cmd{fct setstyle \$markstyle color \%blue}.
1856In this command the colour expression is read from the file
1857\exm{BLUE.STX}\ in the \exm{globals}\ directory of SH.  Such colour
1858files exist for the most common colours.  It is possible to
1859add other colour files if necessary.
1860
1861The traces on display do not have fixed attribute blocks.  By
1862default, they use block number 0 for output.  All traces have
1863an info entry, called \exm{attrib}, which contains the current
1864block number.  So each trace can use a different attribute
1865block if it is necessary and if enough blocks are available.
1866The entry value is changed by the \cmd{set}\ command, as any
1867other info entry.  To change the colour of the traces 4-6 to red,
1868you need two commands.  First set an attribute block (for example
1869number 1) to red colour: \cmd{fct setstyle 1 color \%red}.  Then
1870assign this block to the selected traces: \cmd{set 4-6 attrib 1}.
1871After the next redraw (command \exm{rd}), these traces will be
1872displayed in red colour.  At the end of this section some
1873examples are given.
1874\smallskip
1875
1876\noindent
1877\cmd{fct setstyle \$timeaxisstyle linewidth 3}\\ 1878Change line width of time axis to thicker lines. 1879\smallskip 1880 1881\noindent 1882\cmd{fct setstyle \$markstyle wrmode xor}\\
1883Change trace markers to XOR--mode.  Now the markers can be removed
1884if they are drawn a second time at the same position.
1885\smallskip
1886
1887\noindent
1888\cmd{fct setstyle 3 color \%yellow}\\
1889Set colour of attribute block number 3 to yellow.
1890\smallskip
1891
1892\noindent
1893\cmd{set all attrib 3}\\
1894Use attribute block 3 for all traces on display.
1895\smallskip
1896
1897\noindent
1898\cmd{set 1,4,6 attrib 3}\\
1899Use attribute block 3 for traces 1, 4 and 6.
1900\smallskip
1901
1902\noindent
1903\cmd{set \_magnitude(7.0:) attrib 3}\\
1904Use attribute block 3 for all traces with a magnitude larger than 7.0.
1905
1906
1907
1908\section{SH Paths and Input Files}
1909\label{sec:SHLibs}
1910
1911Many operations like filter input or calling a command procedure
1912require input files.  These input files are searched in the
1914default directories.  SH knows several separate directories for
1915help files, for command procedures, filters and others.  The actual
1916paths are usually defined in the startup file of SH.  It is very
1917unlikely that they have to be changed after SH is installed
1918properly, nevertheless it is useful to explain the path commands
1919here.  The command syntax is \cmd{fct path <name> <dir>}.
1920\cmd{<name>}\ specifies the name of the directory to be set and
1921\cmd{<dir>}\ contains the actual path.  Examples for \cmd{<path>}\
1922are \exm{/home/sh/filter/}\ in UNIX and \cmd{disk1:[main.sh.command]}\
1923in VMS.  It follows a list of valid directory names and a short
1924description of their content.
1925
1926\begin{deflist}{\exm{command}}
1927\item[\exm{scratch}]
1928   Directory for scratch output files like hardcopy files, protocol
1929   files, error files and so on.  This directory must not be changed
1930   within a command procedure, because otherwise the status flags
1931   and local parameters of the parent command level cannot be restored
1932   properly.  This is due to the fact, that when a command procedure
1933   is called, the status, local variables and parameters of the parent
1934   level are saved to a temporary file in the scratch directory
1935   (\exm{.SSV}--files).  If the scratch directory is changed within
1936   this procedure this file cannot be found any more after the
1937   procedure has terminated.
1938\item[\exm{help}]
1939   Contains all help files about built--in commands and command
1940   procedures.  Help files have the extension \exm{.HLP}.  New files
1941   can be added to this directory if new command procedures are to
1942   be documented.
1943\item[\exm{command}]
1944   Directory of common command procedures.  Procedures in this
1945   directory are available to all users of SH.
1946\item[\exm{globals}]
1948   if the file \exm{text.stx}\ in an expression \exm{\%text("cnt)}\
1949   cannot be found in the current directory, it is searched in this
1950   directory.
1951\item[\exm{filter}]
1952   Filter files of any type (FFT, recursive and tabulated) in this
1953   directory are available to every user of SH.
1954\item[\exm{errors}]
1955   Contains the error messages of SH.  The corresponding text of an
1956   error number 1820, for example, is found in the file
1957   \exm{ERR\_1800.MSG}\ in line 20.
1958\item[\exm{inputs}]
1959   Directory for input data files like travel time tables
1960   (\exm{.TTT}--files) of various phases.
1961\end{deflist}
1962
1963
1964
1965\section{Travel Times}
1966
1967There is a utility routine implemented in SH to read travel times
1968of various phases from travel time tables.  These travel times may
1969be used to mark the theoretical arrival times in the seismograms.
1970The travel time tables are assumed to be in the \exm{input}\
1971directory of SH.  This default directory may be changed by the
1972command \cmd{fct tt\_table <path>}, where \cmd{<path>}\ contains
1973the actual directory path of the travel time tables.  Of course,
1974the tables have to be in a special format.
1975
1976Each seismic phase is stored in a separate file, called
1977\exm{.TTT}--file.  The name of the file is given by the name
1978of the phase (for example \exm{P.TTT}\ for P--phases or
1979\exm{PKP.TTT}\ for PKP--phases).  Since many operating systems are
1980not case--sensitive, phases like pP or PcP need a special
1981convention.  All lowercase letters in the phase names are converted
1982to uppercase with a preceding "V"--character.  That means,
1983the travel times of the phase PcP are read from a file
1984\exm{PVCP.TTT}, pP from \exm{VPP.TTT}\ and so on.  In extreme
1985cases like Pdiff (\exm{PVDVIVFVF.TTT}) this is a bit clumsy, but
1986this doesn't happen too often.  The \exm{.TTT}--files itself
1987are ASCII files of the following format:
1988
1989\begin{verbatim}
1990! travel time table for PP-waves
1991!
1992! created by Ray Buland's program TTIMES
1993TTT
1994distance bounds
199527.0 180.0
1996depth steps
199715 0.0 50.0 100.0 150.0 200.0 250.0 300.0 350.0 ...
1998 27.0 000000 000000 000000 391.70 388.42 385.42 382.77 380.48 ...
1999 28.0 000000 409.94 406.33 402.81 399.53 396.53 393.87 391.57 ...
2000 29.0 426.71 421.05 417.44 413.92 410.64 407.63 404.96 402.65 ...
2001 30.0 437.82 432.16 428.55 425.02 421.73 418.72 416.04 413.71 ...
2002 31.0 448.93 443.27 439.65 436.12 432.82 429.79 427.10 424.75 ...
2003    :
2004    :
2005\end{verbatim}
2006
2007The first lines beginning with "\exm{!}" are ignored by SH.  The
2008first line after the comments contains an identification string
2009\exm{TTT}\ (uppercase letters).  The next line after this is
2010ignored and is used for comments.  The following line specifies
2011the distance bounds in which valid travel time information is
2012available in the file.  Then follows again a comment line.  The
2013next information is the number $N$ of depth steps (\exm{15}\ in the
2014example file).  Then the depth values (in km) of all $N$ depths must
2015be specified.  After this header information the travel time data
2016are listed.  Each line contains travel times of one epicentral
2017distance.  The distance value in degrees is the first number
2018in the line.  It is followed by $N$ travel times in seconds, one
2019for each depth step defined above.  Travel time of illegal
2020combinations of depth and distance are given as zeroes.
2021
2022If the travel time for given distance and depth is requested
2024or depth are out of range the routine is aborted and an error message
2025is displayed.  Otherwise SH scans all lines until the distance found
2026is greater than the requested distance (it doesn't check EOF,
2027so the distance bounds of the header must be definitely correct).
2028It takes this and the previous line and interpolates the travel
2029times linearly in distance and depth.  The resulting time is returned.
2030To call the travel time utility, enter the command
2031\cmd{call travel <phase> <distance> <depth> <result>}.  \cmd{<phase>}\
2032specifies the seismic phase.  If the name contains lowercase letters,
2033you have to use the "V"--convention or you turn off the automatic
2034case conversion (then you have to enter uppercase commands and
2035keywords).  \cmd{<distance>}\ and \cmd{<depth>}\ are the distance
2036and depth of the event in degrees and km, respectively.  \cmd{<result>}
2037is the name of the output variable (with a preceding
2038"\exm{\&}"--character) where to store the resulting travel time.
2039
2040\noindent
2041Examples:
2042\smallskip
2043
2044\noindent
2045\cmd{call travel p 98.0 33.0 \&tt}\\
2046After this call the variable \exm{tt}\ contains the resulting
2047travel time of P (\exm{tt}\ must be a defined variable).  It may be
2048used in subsequent commands as input.  To inspect the variable
2049use the \cmd{echo}\ command as for any other expression:
2050\cmd{echo "tt}.
2051\smallskip
2052
2053\noindent
2054\cmd{call travel vpp 50.0 0.0 \&tt}\\
2055Computation of pP travel time.  An equivalent command sequence
2056is given below.
2057\smallskip
2058
2059\noindent
2060\cmd{switch capcnv off}\\
2061\cmd{CALL TRAVEL pP 50.0 0.0 \&TT}\\
2062\cmd{SWITCH CAPCNV ON}\\
2063Returns also pP travel time in variable \exm{tt}.
2064\smallskip
2065
2066A short command procedure \exm{markphase.shc}\ explains how
2067theoretical arrival times of an arbitrary phase are marked
2068on a seismogram.  Supposition is that the trace is read from
2069a q--file with given informations about origin time (entry
2070\exm{origin}), distance (entry \exm{distance}) and depth
2071(entry \exm{depth}).  If this is not the case, additional parameters
2072to the command procedure must be defined, supplying it with the
2073requested information.
2074
2075\begin{verbatim}
2076! file MARKPHASE.SHC
2077!
2078! marks phase on a selected trace
2079! K. Stammler, 27-Apr-92
2080!
2081default 1 1    trace number        ! which trace to mark
2082switch capcnv off
2083DEFAULT 2 P    phase name          ! case sensitive prompt
2084SWITCH CAPCNV ON
2085
2086sdef tt                            ! output travel time
2087
2088call travel #2 ^distance(#1) ^depth(#1) &tt
2089                                   ! compute travel time
2090calc t &tt = ^origin(#1) tadd "tt  ! get absolute arrival time
2091mark/abs/label=#2 #1 "tt           ! mark time position
2092
2093return
2094\end{verbatim}
2095
2096Important is that the second parameter is only case--sensitive
2097if the procedure is called without parameters and all parameters
2098are prompted.  A call like \cmd{markphase 1 PcP}\ won't work,
2099because first the command parser converts all letters to uppercase
2100and then passes the parameters to the procedure \cmd{markphase}.
2101In this case you have to use the "V"--convention: \cmd{markphase
21021 pvcp}.
2103
2104
2105
2106\section{Event Locations and Beams}
2107
2108If data from a station array are available, SH is able to determine
2109azimuth and slowness of a selected phase.  Conversely, it computes
2110beam traces if azimuth and slowness are given.  These operations
2111need to know at which stations the individual seismograms are
2112recorded and where the stations are located.  The first information
2113is easy to get, because there exists a predefined info entry
2114\exm{station}\ specifying the recording station.  The second part,
2115the location of the stations is independend from individual
2116seismograms and is therefore not available in info entries.  SH
2117uses a special text file which lists station information for
2118many different stations.  This file is accessed if one of the
2119above operations (commands \cmd{locate}\ and \cmd{beam}) is
2120performed.  If it is not found, the operation is aborted.  To tell
2121SH where to find the location file, use the command
2122\cmd{fct locfile <file>}.  \cmd{<file>}\ specifies the complete
2123filename including path and extension.  An example file
2124\exm{statloc.dat}\ shows the format of such a file.
2125
2126\begin{verbatim}
2127GRA1 +49.6918877 +11.2217202 1 -21.923 +37.862   Graefenb...
2128GRB1 +49.3913475 +11.6519526 1  +9.085  +4.308   Graefenb...
2129GRC1 +48.9961681 +11.5213504 1  -0.775 -39.662   Graefenb...
2130GRA2 +49.6552079 +11.3594439 1 -11.985 +33.668   Graefenb...
2131GRA3 +49.7622038 +11.3186951 1 -14.815 +45.618   Graefenb...
2132GRA4 +49.5654029 +11.4358711 1  -6.575 +23.668   Graefenb...
2133GRB2 +49.2709252 +11.6699661 1 +10.145  -9.162   Graefenb...
2134GRB3 +49.3435419 +11.8059826 1 +20.165  -1.112   Graefenb...
2135GRB4 +49.4689373 +11.5608463 1  +2.445 +12.858   Graefenb...
2136GRB5 +49.1121310 +11.6767332 1 +10.785 -26.972   Graefenb...
2137GRC2 +48.8675675 +11.3755426 1 -11.595 -53.902   Graefenb...
2138GRC3 +48.8901739 +11.5858216 1  +3.805 -51.472   Graefenb...
2139GRC4 +49.0867465 +11.5262720 1  -0.355 -29.602   Graefenb...
2140WET  +49.14      +12.88      0   0.      0.      FRG, Wetzell
2141BFO  +48.3        +8.3       0   0.      0.      FRG, Black F...
2142HAM  +53.46       +9.92      0   0.      0.      FRG, Hamburg
2143CLZ  +51.8       +10.4       0   0.      0.      FRG, Clausthal
2144BRL  +52.2       +13.5       0   0.      0.      FRG, Berlin
2145FUR  +48.16      +11.28      0   0.      0.      FRG, Fuerst...
2146TNS  +50.22       +8.45      0   0.      0.      FRG, Taunus
2147\end{verbatim}
2148
2149Each line contains one station, starting with the name of the
2150station (usually in uppercase letters), the latitude and the
2151longitude in degrees.  The next number is an array ID code (integer),
2152followed by two floating point numbers specifying the relative
2153array positions of the stations in km.  All following text in the
2154line may be used as a comment.  Please make sure that no line exceeds
2155the length of 132 characters.  By the array ID code the stations
2156can be grouped to arrays.  Each array must have a unique array
2157number (is \exm{1}\ for the GRF--array in the example file).
2158Stations which do not belong to an array must get the array code 0.
2159Each array station must also have relative coordinates (these are
2160the last two numbers in the line).  Stations with an array code
2161of 0 may have zero values for the relative coordinates.
2162The command \cmd{locate}\ uses the relative positioning rather
2163than latitude and longitude if all traces passed are recorded
2164at the same station array (which means all have the same non--zero
2165array code).  This can be prevented by specifying the
2166\exm{/noarray}--qualifier on the \cmd{locate}\ command.
2167
2168To compute azimuth and slowness of a phase, \cmd{locate}\ needs it's
2169travel time differences at each station.  If you just enter
2170\cmd{locate}\ (or \cmd{locate/noarray}) you have to pick the phase
2171at each station by graphic cursor (exit the selection by
2172pressing the "\exm{E}"--key).  \cmd{locate}\ uses the plain
2173time differences between the picks, it does not account for
2174time--shifted traces.  So please make sure that all traces are
2175correctly positioned in time with reference to each other.  If all
2176traces have the same start time, this can be achieved by resetting
2177all time shifts to zero by the command \cmd{set all t-origin 0}.
2178If the traces have different start times you need the additional
2179command \cmd{shift all time\_al}\ to align the traces in time.
2180The results of the computation are displayed on screen or are
2181copied to output variables if specified.  The general syntax is
2182\cmd{locate <list> <azim> <inci> <azim-err> <inci-err>}.  The
2183first parameter \cmd{<list>}\ is not used in this computation
2184mode and should be empty.  All other parameters specify output
2185variables to store results.
2186
2187The \cmd{beam}\ command acts inversely and applies time shifts
2188to the traces, determined from the station locations and from
2189given slowness and azimuth.  The calling syntax is
2190\cmd{beam <list> <azimuth> <slowness>}.  \cmd{<list>}\ specifies
2191which traces are shifted (typically \cmd{all}) and \cmd{<azimuth>}\
2192and \cmd{<slowness>}\ are the (back--)azimuth in degrees and
2193slowness in s/deg.  \cmd{beam}\ applies relative shifts, like the
2194\cmd{shift}\ command.  If you apply \cmd{beam}\ twice you get
2195twice the time shift at each trace.  To align traces in time
2196before the \cmd{beam}\ command, apply the commands given above.
2197To obtain a beam trace you have to sum the \cmd{beam}ed traces.
2198A typical command sequence is:
2199\begin{verbatim}
2200set all t-origin 0
2201shift all time_al
2202beam all 330.0 5.4
2203sum all
2204\end{verbatim}
2205It creates the beam trace on top of the display.  If this beam
2206process is applied for many different slownesses at a fixed
2207azimuth (or reversely for a set of azimuths at a fixed slowness)
2208you get many summation traces which are comparable to a vespagram.
2209This is what the library routine \cmd{vespa}\ does.  The parameters
2210are \cmd{vespa <slo-start> <slo-end> <slo-step> <azimuth> <power>}.
2211\cmd{<slo-start>}\ and \cmd{<slo-end>}\ specify the slowness
2212interval, the step size is given by \cmd{<slo-step>}.  For each
2213slowness step one beam trace is computed.  The fixed azimuth is given
2214in \cmd{<azimuth>}.  \cmd{<power>}\ determines the order of the
2215$N$-th Root Process applied in the summation.  The \cmd{vespa}\
2216command uses all traces on display for beaming.  After execution
2217the input traces are hidden, on display are the resulting beam
2218traces.  The info entry \cmd{comment}\ contains the actual
2219slowness value for each trace.  It is convenient to change the
2220trace info text to the \exm{comment}--entry (command
2221\verb'trctxt ^comment($x)'). 2222 2223 2224 2225\section{Notes for UNIX Versions of SH} 2226 2227The SH program was originally developed on ATARI ST/TT computers 2228running TOS as operating system and GEM as graphics interface. 2229Since most parts of SH are written machine--independend it was quite 2230easy to export the program to VAX/VMS (after implementation of 2231a VWS and an X--Window interface). The implementation on UNIX, 2232however, shows some peculiarities. This is mainly due to two 2233features of UNIX, namely the occurrence of slashes "/" in filenames 2234and case--sensivity. The slashes are used in SH (as in VMS) to 2235indicate command qualifiers (like the hyphen in UNIX). Therefore 2236in calls to the operating system cannot be used any slashes. 2237This is very annoying if filenames have to be passed. This 2238problem can be solved by the use of the internal variable 2239\exm{\$slash}\ (see section \ref{sec:InternVar}) in combination
2240with concatenation expressions (\verb'|$slash|home|$slash|sh|$slash|'\ 2241instead of \exm{/home/sh/}). This is very clumsy sometimes as you 2242can see in the example. Another possibility is to change the 2243qualifier character to a backslash "$\backslash\$".  Then you can
2244use slashes without problems, but all existing command procedures
2245in the library must be changed in this way.  I admit that both
2246solutions are not perfect.
2247Similar problems arise concerning the case--sensitivity of UNIX.
2248By default, SH converts every input line to uppercase letters
2249before translating it.  This automatic case conversion can be
2250switched off (see section \ref{sec:ExecFlags}), but then you have
2251to enter all command verbs and keywords in uppercase letters.
2252This is also not a convenient solution of this problem.  I'm
2253still thinking about these things and I hope I can optimize the
2254UNIX interface in the near future.
2255
2256Please note, that these peculiarities affect only calls to the
2257operating system (command \cmd{system}).  All other commands
2258behave exactly like in other implementations.
2259
2260
2261
2262% planned sections
2263%
2264%\section{Special Commands}
2265%
2266%\section{The Startup File}
2267%
2268%\section{Installing SH}
2269%
2270%\section{Station Locations}
2271
2272\end{document}
Note: See TracBrowser for help on using the repository browser.