.TH GMT_SHELL_FUNCTIONS.SH 1gmt "Feb 27 2014" "GMT 4.5.13 (SVN)" "Generic Mapping Tools"
.SH NAME
gmt_shell_functions.sh \- Practical functions to be used in GMT bourne shell scripts
.SH SYNOPSIS
\fBgmt_init_tmpdir\fP
.br
\fBgmt_remove_tmpdir\fP
.br
\fBgmt_clean_up\fP [\fIprefix\fP]
.br
\fBgmt_message\fP \fImessage\fP
.br
\fBgmt_abort\fP \fImessage\fP
.br
\fBgmt_nrecords\fP \fIfile(s)\fP
.br
\fBgmt_nfields\fP \fIstring\fP
.br
\fBgmt_get_field\fP \fIstring\fP
.br
\fBgmt_get_region\fP \fIfile(s)\fP [\fIoptions\fP]
.br
\fBgmt_get_gridregion\fP \fIfile\fP [\fIoptions\fP]
.br
\fBgmt_get_map_width\fP \fB\-R\fP \fB\-J\fP
.br
\fBgmt_get_map_height\fP \fB\-R\fP \fB\-J\fP
.br
\fBgmt_set_psfile\fP \fIfile\fP
.br
\fBgmt_set_framename\fP \fIprefix framenumber\fP
.br
\fBgmt_set_framenext\fP \fIframenumber\fP
.SH DESCRIPTION
\fBgmt_shell_functions.sh\fP provides a set of functions to Bourne (again) shell scripts in support
of \fBGMT\fP.
The calling shell script should include the following line, before the functions can be used:
.br
.sp
\fB. gmt_shell_functions.sh\fP
.br
.sp
Once included in a shell script, \fBgmt_shell_functions.sh\fP allows \fBGMT\fP users to
do some scripting more easily than otherwise. The functions made available are:
.TP
.B gmt_init_tmpdir
Creates a temporary directory in \fB/tmp\fP or (when defined) in the directory specified by the
environment variable \fBTMPDIR\fP. The name of the temporary directory is returned as environment
variable \fBGMT_TMPDIR\fP. This function also causes \fBGMT\fP to run in `isolation mode', i.e., all
temporary files will be created in \fBGMT_TMPDIR\fP and the \.gmtdefaults file will not be adjusted.
.TP
.B gmt_remove_tmpdir
Removes the temporary directory and unsets the \fBGMT_TMPDIR\fP environment variable.
.TP
.B gmt_cleanup
Remove all files and directories in which the current process number is part of the file name.
If the optional \fIprefix\fP is given then we also delete all files and directories that begins
with the given prefix.
.TP
.B gmt_message
Send a message to standard error.
.TP
.B gmt_abort
Send a message to standard error and exit the shell.
.TP
.B gmt_nrecords
Returns the total number of lines in \fIfile(s)\fP
.TP
.B gmt_nfields
Returns the number of fields or words in \fIstring\fP
.TP
.B gmt_get_field
Returns the given \fIfield\fP in a \fIstring\fP. Must pass \fIstring\fP between double quotes to
preserve it as one item.
.TP
.B gmt_get_region
Returns the region in the form w/e/s/n based on the data in table \fIfile(s)\fP. Optionally add
-I\fIdx\fP/\fIdy\fP to round off the answer.
.TP
.B gmt_get_gridregion
Returns the region in the form w/e/s/n based on the header of a grid \fIfile\fP. Optionally add
-I\fIdx\fP/\fIdy\fP to round off the answer.
.TP
.B gmt_map_width
Expects the user to give the desired \fB-R \-J\fP settings and returns the map width in
the current measurement unit.
.TP
.B gmt_map_height
Expects the user to give the desired \fB-R \-J\fP settings and returns the map height in
the current measurement unit.
.TP
.B gmt_set_psfile
Create the output \fIPostScript\fP file name based on the base name of a given file (usually the script name
\fB$0\fP).
.TP
.B gmt_set_framename
Returns a lexically ordered filename stem (i.e., no extension) given the file prefix and the current frame number,
using a width of 6 for the integer including leading zeros.  Useful when
creating animations and lexically sorted filenames are required.
.TP
.B gmt_set_framenext
Accepts the current frame integer counter and returns the next integer counter.
.SH NOTES
.br
1. These functions only work in the bourne shell (\fBsh\fP) and their derivatives (like \fBash\fP,
\fBbash\fP, \fBksh\fP and \fBzsh\fP).
These functions do not work in the C shell (\fBcsh\fP) or their derivatives (like \fBtcsh\fP), and
cannot be used in DOS batch scripts either.
.br
2. \fBgmt_shell_functions.sh\fP were first introduced in \fBGMT\fP version 4.2.2 and have since been
regularly expanded with other practical scripting short-cuts. If you want to suggest other functions,
please do so by mailing to the GMT mailing list: gmt-help@lists.hawaii.edu.
.SH "SEE ALSO"
.IR GMT (1),
.IR sh (1),
.IR bash (1),
.IR minmax (1),
.IR grdinfo (1)