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

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
13\author{K.\ Stammler}
14\date{27 April 1992}
21\section{General Information}
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.
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.
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.
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.
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.
60\section{The Command Line}
62The command interpreter parses each command line by processing
63two steps:
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}.
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.
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
98\exm{verb par1;par2 ;; par4/SimpleQual par5  par6\ \ /ValuedQual=val}.
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.
108\section{Translation of Expressions}
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+" # $ % _ ^ |+
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
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:
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}.
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}
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}.
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.
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}.
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}.
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.
196\section{Information Entries}
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).
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
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}\
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.
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).
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.
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
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
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
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.
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
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
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}.
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:
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}.
445When you define your own entries, you should make sure that
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}
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}\
468\section{Trace Addressing}
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.
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.
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.
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.
562\cmd{del 4-6,8,11,15-20}\\
563Delete traces number 4, 5, 6, 8, 11, 15, 16, 17, 18, 19, 20.
567\cmd{hide all}\\
568Hide all traces.
572\cmd{display h:all}\\
573Display all hidden traces starting at position 1.
577\cmd{sum \_azimuth(0:180)}\\
578Sum traces whose azimuth value is between 0 and 180$^\circ$.
582\verb'del _comp~(z)'\\
583Delete all traces which are not z--components.
587\cmd{zoom/rel \_station(bji) 2}\\
588Enlarge the amplitude of all traces of station BJI by a factor of 2.
592\cmd{hide \_magnitude(:5.8)}\\
593Hide all traces with a magnitude smaller than 5.8.
597\section{Trace Filtering}
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.
609\subsection{FFT Filters}
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:
630! file WWSSN_SP.FLF
631!      ============
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
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.
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).
703\subsection{Recursive Filters}
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:
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.
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.
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.
728   Output traces of recursive filters usually have high--amplitude
729   numerical noise at their beginning.
731As SH supports both filter types it is up to the user to decide
732which filter is to be preferred in his application.
734The formula used in the recursive filter operations is this:
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}
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.
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:
755! file WWSSN_SP.FLR
756!      ============
758! WWSSN-SP recursive filter
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.
825\subsection{Tabulated Filters}
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.
840A simple example file \exm{TRAPEZ.FLT}\ of a tabulated filter
841is listed below.
844! file TRAPEZ.FLT
845!      ============
847! simple tabulated filter
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
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.
881\subsection{Special Filters}
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.
894Another option is the attenuation of a trace by an attenuation
897   A(\omega) =  e^{ -\frac{1}{2}\omega t^* +
898      i\frac{\omega}{\pi}\ln\frac{\omega}{\omega_N} }
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}.
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.
923\section{Scaling of Amplitudes}
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.
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
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.
956   Changing the zoom factor (\shi{zoom}\ entry) via \cmd{zoom}\
957   command.
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.
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:
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.
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.
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.
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.
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.
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}.
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>}).
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.
1083\section{Command Procedures}
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.
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}.
1108\subsection{A first example}
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}.
1126! file rotex1.shc
1128! version 1 of the 3-dim rotation procedure
1129! K. Stammler, 15-Apr-92
1131del all             ! delete possibly existing traces ...
1132dtw                 ! ... and time window
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
1138return              ! return to parent level
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.
1148\subsection{Command Parameters}
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:
1183! file rotex2.shc
1185! version 2 of the 3-dim rotation procedure
1186! K. Stammler, 15-Apr-92
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
1193del all             ! delete possibly existing traces ...
1194dtw                 ! ... and time window
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
1200return              ! return to parent level
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
1219\subsection{Variables in SH}
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}.
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.
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.
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.
1266! file rotex3.shc
1268! version 3 of the 3-dim rotation procedure
1269! K. Stammler, 16-Apr-92
1271default 1 ;;    input q-file        ! input file
1272default 2 q_out output q-file       ! output file
1274sdef azim                 ! define azimuth variable, no init
1275sdef inci                 ! define angle of incidence, no init
1277del all                   ! delete possibly existing traces ...
1278dtw                       ! ... and time window
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
1286return                    ! return to parent level
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.
1297\subsection{The Command {\tt calc}}
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:
1303   calc <type> <outvar> = <operand1> [<op> <operand2>] [<p>]
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.
1323Valid operators for the type "\exm{i}" (integer) are:
1326   Adds the two operands.
1328   Subtracts \verb+<operand2>+ from \verb+<operand1>+.
1330   Multiplies the two operands.
1332   Divides \verb+<operand1>+ by \verb+<operand2>+ without remainder.
1334   Remainder of the division \verb+<operand1>+ by \verb+<operand2>+.
1339Valid operators for the type "\exm{r}" (real) are:
1342   Adds the two operands.
1344   Subtracts \verb+<operand2>+ from \verb+<operand1>+.
1346   Multiplies the two operands.
1348   Divides \verb+<operand1>+ by \verb+<operand2>+.
1350   Removes the sign of \verb'<operand1>'.  No second operand.
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.
1356   Takes \verb'<operand1>' to the \verb'<operand2>'--th power.
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}.
1367Valid operators for the type "\exm{s}" (string) are:
1370   Concatenation of \verb'<operand1>' and \verb'<operand2>'
1371   with a blank in between.
1373   Extracts the \verb'<operand2>'--th word from \verb'<operand1>'.
1374   Separation characters are blanks and semicolons.
1375   \verb'<operand2>' must be integer.
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.
1385Valid operators for the type "\exm{t}" (time) are:
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.
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.
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).
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"}).
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
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
1447! file rotex4.shc
1449! version 4 of the 3-dim rotation procedure
1450! K. Stammler, 20-Apr-92
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
1457sdef azim                 ! azimuth
1458sdef inci                 ! angle of incidence
1459sdef start                ! start of time window (relative time)
1460sdef end                  ! end of time window (relative time)
1462del all                   ! delete possibly existing traces ...
1463dtw                       ! ... and time window
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
1476return                    ! return to parent level
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.
1492For loop structures SH provides two commands, \cmd{goto}\ and
1493\cmd{if}.  \cmd{goto}\ has the syntax
1495   goto <label>
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
1508The command \cmd{if}\ performs the conditional execution of an
1509instruction.  It's syntax is
1511   if  <e1> <cmp> <e2>  <cmd> [<label>]
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>}.
1521The compare operator \cmd{<cmp>}\ specifies the actual comparison
1522and the type of the expressions \cmd{<e1>}\ and \cmd{<e2>}.  Valid
1523operators are:
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>}
1541With this supplement it is possible to write a command procedure
1542to apply \cmd{rotex4}\ to all q--files listed in a list file.
1545! file rotex5.shc
1547! version 5 of the 3-dim rotation procedure
1548! K. Stammler, 21-Apr-92
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
1556sdef cnt #2                   ! file counter init. to start line
1557sdef qfile                    ! name of current q-file
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
1571return                        ! return to parent level
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}).
1584\subsection{Execution Flags}
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
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}.
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.
1664\subsection{Debugging Tools}
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.
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
1697multi--tasking operating system.  All scratch files of SH start with
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.
1712\section{Internal Variables}
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:
1728   Number of traces in the display window.
1730   Total number of traces in memory.
1732   Return status of the last executed command.  Zero means
1733   successful completion, any other value is an error number.
1735   Current system date and time string.  This is not yet implemented
1736   in all operating systems.
1738   Returns current version of SH.
1740   Returns the lower bound of the current time window (set by command
1741   \cmd{stw}).
1743   Returns the upper bound of the current time window (set by command
1744   \cmd{stw}).
1746   Returns the width of the current time window (set by command
1747   \cmd{stw}).
1749   Returns the lower bound of the current vertical window
1750   (y--window, set by command \cmd{syw}).
1752   Returns the upper bound of the current vertical window
1753   (y--window, set by command \cmd{syw}).
1755   Returns the width of the current vertical window (y--window,
1756   set by command \cmd{syw}).
1758   Returns style block number of the title text lines.  For
1759   additional information about attribute blocks, see section
1760   \ref{sec:AttribBlocks}.
1762   Returns style block number of the trace info text
1764   Returns style block number of the line attributes of zero traces
1766   Returns style block number of the line style of the time axis
1767   and the label text
1769   Returns style block number of the marker lines
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}.
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:
1788   |text|$blank|with|$blank|blanks|
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)}.
1800\section{Output Attributes}
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.
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:
1818   Set line width.  \exm{<value>}\ specifies the line width in
1819   pixels.
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.
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.
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.
1837   Set character font.  \exm{<value>}\ contains the font number.
1839   Set writing mode.  \exm{<value>}\ is either \exm{replace}\ or
1840   \exm{xor}.  \exm{replace}\ is the default mode.
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.
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.
1877\cmd{fct setstyle \$timeaxisstyle linewidth 3}\\
1878Change line width of time axis to thicker lines.
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.
1888\cmd{fct setstyle 3 color \%yellow}\\
1889Set colour of attribute block number 3 to yellow.
1893\cmd{set all attrib 3}\\
1894Use attribute block 3 for all traces on display.
1898\cmd{set 1,4,6 attrib 3}\\
1899Use attribute block 3 for traces 1, 4 and 6.
1903\cmd{set \_magnitude(7.0:) attrib 3}\\
1904Use attribute block 3 for all traces with a magnitude larger than 7.0.
1908\section{SH Paths and Input Files}
1911Many operations like filter input or calling a command procedure
1912require input files.  These input files are searched in the
1913current directory and, if they are not found there, in special
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:[]}\
1923in VMS.  It follows a list of valid directory names and a short
1924description of their content.
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.
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.
1944   Directory of common command procedures.  Procedures in this
1945   directory are available to all users of SH.
1947   Default directory for access to input text files, that means
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.
1952   Filter files of any type (FFT, recursive and tabulated) in this
1953   directory are available to every user of SH.
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.
1959   Directory for input data files like travel time tables
1960   (\exm{.TTT}--files) of various phases.
1965\section{Travel Times}
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.
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:
1990! travel time table for PP-waves
1992! created by Ray Buland's program TTIMES
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    :
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.
2022If the travel time for given distance and depth is requested
2023SH opens the file and reads the header information.  If distance
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.
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}.
2054\cmd{call travel vpp 50.0 0.0 \&tt}\\
2055Computation of pP travel time.  An equivalent command sequence
2056is given below.
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}.
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.
2076! file MARKPHASE.SHC
2078! marks phase on a selected trace
2079! K. Stammler, 27-Apr-92
2081default 1 1    trace number        ! which trace to mark
2082switch capcnv off
2083DEFAULT 2 P    phase name          ! case sensitive prompt
2086sdef tt                            ! output travel time
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
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}.
2106\section{Event Locations and Beams}
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.
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
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.
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.
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:
2200set all t-origin 0
2201shift all time_al
2202beam all 330.0 5.4
2203sum all
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)').
2225\section{Notes for UNIX Versions of SH}
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.
2256Please note, that these peculiarities affect only calls to the
2257operating system (command \cmd{system}).  All other commands
2258behave exactly like in other implementations.
2262% planned sections
2264%\section{Special Commands}
2266%\section{The Startup File}
2268%\section{Installing SH}
2270%\section{Station Locations}
Note: See TracBrowser for help on using the repository browser.