Paradigm MAPLAN Manual

Paradigm™ Rock & Fluid Canvas™ 2009 | Epos® 4.0 MapLan/VolLan 2-1

2MapLan/VolLan

Contents

MapLan/VolLan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Maplan/VolLan Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Starting MapLan/VolLan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Program Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Features of MapLan/VolLan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Working with Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Create a New Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Inserting Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Open an Existing Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Save a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Delete a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Running Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Edit Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Tools Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Command Line Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Exit MapLan/VolLan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Program Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Program Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Declaration Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Initialization Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Processing Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15End Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Source File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Statement Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Variable Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

MapLan/VolLan 2-2Paradigm™ Rock & Fluid Canvas™ 2009 | Epos® 4.0

Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Program Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20dowhile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23perform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Frame Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26File Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29User Defined - Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Logical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Numeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37String Related . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Regression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Ask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

External Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Compilation and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Future Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65


Maplan/VolLan Basics

Overview

MapLan/VolLan (an acronym for Map/Volume Language) is Paradigm’s grid/volume processing language.

This online help is a guide to writing programs in MapLan/VolLan and is designed for users who wish to develop their own modules for grid/volume processing and database access. It also describes MapLan/VolLan functions which may be used in expressions (e.g., tp_evaluate).

A C compiler must be available in order to develop programs using MapLan/VolLan. See "System Requirements" in the Introduction of the Geolog 6.7.1 Installation Guide for information regarding which C compiler is required on each of the supported platforms.

Starting MapLan/VolLan

MapLan/VolLan programs can be created via the program development interface, mui_loglan.MapLan/VolLan programs can also be created using a text editor.


Program Development

Introduction

MapLan/VolLan is a fully functional programming language which is written, compiled and executed within Epos. It is used for the creation and maintenance of grid/volume analysis algorithms that can be applied to Epos data.

Features of MapLan/VolLan

• Multi-step and multi-loop programming logic, including subroutines and one dimensional arrays.

• Point or row-based processing.

• Performance of calculations such as summations and averages over multiple data frames.

• Direct control of input and output data sources and destinations.

• Read from and write to external ASCII files.

MapLan/VolLan manages access to Epos grid/volume files. There are a wide range of operators, functions and control commands or functions within MapLan/VolLan so that almost any process can be applied to Epos data.

As an example of MapLan/VolLan programming, following is a simple program to calculate density porosity from bulk density:

dowhile GET_FRAME ()DPHI = (RHOMA - RHOB) / (RHOMA - RHOF)

call PUT_FRAME ()enddo

end

PROGRAM: RHOB2PHI Calculates DPHI from RHOB

INPUT RHOB G/CC /* Bulk Density

RHOMA G/CC /* Matrix grain density

RHOF G/CC /* Fluid density

OUTPUT DPHI V/V /* Density porosity

RHOMA G/CC /* Matrix grain density

RHOF G/CC /* Fluid density

START:


Working with Programs

A MapLan/VolLan program actually consists of three files:

<program>.lls and <program> are maintained by mui_loglan. <program>.info is used by the Module Launcher to display its screen and to control the information it passes to the MapLan/VolLan application.

The MapLan/VolLan window is divided into two sections: Input/Output and Source.

Fig. 1: The MapLan window

<program>.lls containing the MapLan/VolLan source code

<program> compiled binary executable, and

<program>.info containing the definitions of the program arguments and details of external libraries, etc.


Fig. 2: The VoLan window

Input/Output

Data types, data sources and units. Defines program variables and the interface used when the program is executed. This information is saved as <program_name>.info when the file is saved. New variables are created using the Insert menu.

Inserted variables are displayed in table format—see The Module Launcher for information on using tables.

Source

Defines the processing of inputs and outputs carried out by the program, using MapLan/VolLan statements, functions, etc. Text is entered using the keyboard. Source code, including inputs and outputs and program documentation, is saved as <program_name>.lls when the file is saved.


Create a New Program

A new program is created by first providing a name and other details about the new program in the MapLan/VolLan Details dialog box.

To create a new program

1. Start MapLan/VolLan (see Starting MapLan/VolLan).

2. Select MapLan/VolLan > New from the menu of the MapLan/VolLan window to display the MapLan/VolLan Details dialog box (see Fig. 3).

3. After selecting OK in the MapLan/VolLan Details dialog box, the Source section of the MapLan/VolLan window displays a basic program template for frame processing (see Fig. 3).

Fig. 3: MapLan Details dialog box

These details can be revised at a later date by selecting Edit > Properties.

Inserting Variables

Program inputs and outputs are inserted by using the Insert menu and selecting the type of input/output variable to insert. The name of the variable is entered in the dialog box that appears.

Table 2-1: Input Options for Maplan/VolLan Details Dialog Box

Field Description

Program The name of the new program.

Description A brief description of the program.

Detail Description, etc. Program documentation or users’ guide (see Fig 3 for an example).


Input/Output

When the name of a new variable has been specified, an entry is created in the Input/Output section of the MapLan/VolLan window. Details of the variable are then added (e.g., units, default value, description, etc.).

The Input/Output section of the MapLan/VolLan window is in table format—see The Module Launcher for further information on using this format. The contents of the table are stored in the <program>.info file. This file is used by the Module Launcher to construct the graphical user interface (GUI) for the program. The table below describes the components of the variable.

Table 2-2: Components of Variables in Input/Output Section

Field Description

Location The location of input/outputs: constant or grid.

Mode The mode of input/outputs: input, output, input-output or local.

Name The name given to the input/output.

Type Usually one of REAL, DOUBLE, LOGICAL or ALPHA.

Default Default value or grid name to assign to the variable.


Another component, List, is available which, when used, displays a list of valid options in a Combo Box (Field). The value entered in this field is executed as a command which should return the list of options, one per line.

The List component is not available in the MapLan/VolLan window but can be entered into the .info file.

Open an Existing Program

• Select MapLan/VolLan > Open to open the File Select Dialog Box to locate and select an existing program to be modified.

Save a Program

• Use the MapLan/VolLan > Save and MapLan/VolLan > Save As menu items to save new programs, or a modified program with a new name, to the currently open project’s maplan/vollan directory (unless otherwise specified).

Delete a Program

• Select MapLan/VolLan > Delete to open the File Select Dialog Box to locate and select a program to delete.

Properties

• Select Edit > Properties to open the MapLan/VolLan Details dialog box to modify the descriptions and/or specified layout of a program.

Comment Descriptive comment.

Validation Validation of the input/output. The validation string for a numeric value may have one of the following forms:StringMeaningv1:v2 v1 <= value <= v2, missing not allowed.v1:v2,-v1 <= value <= v2, missing allowed.v1<v2v1 < value < v2, missing not allowed.v1<v2,-v1 < value < v2, missing allowed.v1,v2[,...] value == v1 or v2 [or ...]. This option causes a list selection button to be displayed by the Launcher when the field is selected. If one of the values in the list is “-” missing is allowed, and if “?” is present any other entry is also valid.The validation string for an alpha value must have the following form:v1,v2[,...]value == v1 or v2 [or ...]. This option causes a list selection button to be displayed by the Launcher when the field is selected. If one of the values in the list is “-” missing is allowed, and if “?” is present any other entry is also valid. If the list entries are in consistent case (e.g., all lower, edit, or upper), then an entered value will be converted to that case.For a file, the validation string may be “READ” (in which case the file must be readable) or “WRITE” (in which case the file must be writable if it exists, or the file’s directory must be writable if the file does not exist. Irrespective of any validation, the entered data must be a valid filename.

Table 2-2: Components of Variables in Input/Output Section (Continued)

Field Description


Running Commands

• Select Project > Run to run a command, script or module within the MapLan/VolLan window. See Running Commands for further details.

Edit Menu

Use the Edit menu to make changes to the description of the MapLan/VolLan program, and specify options for compiling and linking.

Tools Menu

MapLan/VolLan tools on the Tools menu are used once program coding has been completed.

Properties Displays details of the program's name, description and documentation.

Externals Used to specify the path names for included files and directories, external libraries and directories, external objects, and the Linker used to load the compiled program.

MapLan/VolLan programs are converted to C language and compiled to produce an executable module. This requires a C compiler in your environment. The environment variable MIN_CC defines the C compiler to be used.

Code Starts the editor specified by the environment variable MIN_EDITOR to edit the MapLan/VolLan code. If a compile error has previously occurred, the editor will be started pointing to the line containing the first error.

The editor must start up in a new window, and the mui_loglan window is blocked until the editor exits. If no editor is specified by the environment variable, "xterm vi" is used. Emacs (usually /usr/local/bin/emacs) is a good choice.

Compile Compiles the program. Error messages are displayed in the message area of the MapLan/VolLan window. Requires an ANSI-C compiler.

Windows NT requires Microsoft Visual C++ version 4, 5 or 6. The installation path cannot contain spaces (except for the "Program Files" section).

Sort Sorts Input/Output variables by location.

Sort By Name Sorts Input/Output variables by location and name.


NOTE When installing the C compiler for Windows, do not use spaces in the path name (except in the "Program Files" section).

Command Line Programs

MapLan/VolLan programs can be developed and compiled outside of the GUI provided in Epos applications. Relevant commands are as follows.

loglan_compile

Compile and link a MapLan/VolLan program. This runs loglan_to_c and module_generate, compiles the files and then links them to produce an executable.

Options:

loglan_to_c

MapLan/VolLan to C converter.

Options:

module_generate

Module source code generator.

Options:

Site Install After compiling the mapLan/volLan, select this option to install the mapLan/volLan to the site area to make it available to all users.

[PROGRAM = File] - program name

[CC = String] -compiler to use

[CCLD = String] - linker to use

[OBJS = String] - extra objects to load

[INCDIRS = String] - list of directories for included files

[LIBDIRS = String] - list of directories for external libraries

[EXTLIBS = String] - list of external libraries to be searched

[PROGRAM = File] - MapLan/VolLan program to convert to C

[MODULE_NAME = File] - module for code generation.

[UPDATE_INFO = Logical] - logical (false) re-write .info file flag.


Exit MapLan/VolLan

Select MapLan/VolLan > Exit to close the MapLan/VolLan window. The File Modified dialog box will be displayed to enable any unsaved changes to be saved or discarded.


Program Syntax

Program Structure

MapLan/VolLan programs consist of the following sections:

Depending on the purpose of a program, some elements will not be required. For example, a program that only utilizes data from the constants area will not need to GET or PUT frames, nor require the dowhile-enddo structure.

Declaration Section

This section does not appear if using mui_loglan to edit MapLan/VolLan programs, however, it is saved in the source file.

There are three classes of variables, INPUT, LOCAL and OUTPUT, which can store numeric or character data. Variables can be declared as both INPUT and OUTPUT, for example where a grid is modified by the MapLan/VolLan program and then saved to the database.

Variable Names

A variable name must start with an alphabetic character and every other character must be alphabetic, a digit, or an underscore ( _ ). The maximum length of a local variable name (and of the PROGRAM name) is 63 characters, while for input and output variables the length of the name should be no greater than 13. All variable names are converted to lower case when the program is converted to C. In mui_loglan, local variables in the input/output window will be in lower case and all others in uppercase. In the Source section, any case may be used. A variable name may not be a reserved word. The reserved words are:

Section Structure Use

Declaration Section Declare variables used in the program:

INPUTLOCALOUTPUT

Input variablesLocal variablesOutput variables

Initialization Section Initialize variables and perform calculations not related to frame-by-frame processing:

START Start of program codePre frame-by-frame processing

Processing Section Do grid processing; usually in sequential data frame order:

dowhileGET_FRAME()

Inputs each data frame in turnFrame-by-frame processing

call PUT_FRAMEenddo

Outputs data framesEnd of per frame processingPost frame-by-frame processing

End Section end Marks the end of the program.

Subroutines Written to perform specific processing. Perform statements.


and, by, call, divide, do, dowhile, else, elseif, end, enddo, endfor, endif, eq, false, file_in, file_out for, ge, goto, gt, if, le, lt, minus, missing, multiply, ne, not, or, perform, plus, program, raise, result, return, then, start, to, true, uminus and until.

Names which are reserved words in the C language have an underscore suffix added, so the use of names which consist of a C reserved word followed by an underscore should be avoided, since a conflict could occur if the reserved word itself is also used. The reserved words in the C language are:

argc, argv, auto, break, case, char, const, continue, default, do, double, else, enum, envp, extern, float, for, goto, if, int, long, main, register, return, short, signed, sizeof, static, struct, switch, typedef, union, unsigned, void, volatile, and while.

Names which conflict with functions defined in the system include files string.h and math.h may NOT be used. These functions incude:

acosh, alog, asinh, atan, atan2, atan2f, atanf, atanh, atof, atof, cabs, cbrt, ceil, ceilf, clog, copysign, cos, cosf, cosh, coshf, dlog, drand48, drem,erand48, erf, erfc, exp, expf, expm1, expm1f, fabs, fabsf, facos, fasin, fatan,fatan2, fcabs, fceil, fcos, fcosh, fexp, fexpm1, ffloor, ffs, fhypot, finite,flog, flog10, flog1p, floor, floorf, fmod, fmodf, frexp, fsin, fsinh, fsqrt,ftan, ftanh, ftrunc, gamma, hypot, hypotf, initstate, j0, j1, jn, jrand48,lcong48, ldexp, log, log10, log10f, log1p, log1pf, log2, logb, logf, lrand48,matherr, memccpy, memchr, memcmp, memcpy, memmove, memset, modf, modff, mrand48, nextafter, nrand48, pow, powf, rand, random, remainder, rint, scalb,seed48, setstate, sin, sinf, sinh, sinhf, sqrt, sqrtf, srand, srand48, srandom,strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, strdup, strerror, strlen, strncasecmp, strncat, strncmp, strncpy, strpbrk, strrchr, strspn,strstr, strtod, strtok, strtok_r, strxfrm, tan, tanf, tanh, tanhf, trunc,truncf, y0, y1, yn, and zlog.

The use of variable names of the form grid attribute"_"name should be avoided. The defined gridgridattributes are:

name, units, type, min, max, mean, stddev, count, miss, top, bottom, date, user, comment, sr, repeat and frames.

Input Variables

INPUT variables are extracted from the Epos files by the module launcher and passed to the MapLan/VolLan program in a table pipe when the MapLan/VolLan program is executed. They may be grids or volumes.

An example of input variable declarations:

Local Variables

LOCAL variables are temporary variables that are assigned values within a program but are never written to the database. These may be intermediate calculations or flags used to indicate a particular action. LOCAL variables are useful for breaking down complex algorithms into simpler components.

INPUT GR api /* GAMMA RAY GRID DATA

CAL in. /* CALIPER GRID

MUDWT g/cc /* Mud Weight

KCLMUD kppm /* KCl conc in Drilling Mud

SURFACE_ELEVATION

/* Ground Level Elevation


Numeric and alpha local variables may be arrays. Arrays in MapLan/VolLan are one dimensional; multidimensional arrays are not supported.

An example of local variable declarations:

Output Variables

OUTPUT variables are written to the output table pipe by the MapLan/VolLan program and stored in Epos by the module launcher.

An example of output variable declarations:

Initialization Section

The initialization section of a MapLan/VolLan program is indicated by a START: statement and contains any program code to:

• initialize variables.

• perform calculations not related to frame-by-frame processing.

When a data frame is read, all input variables are set to the values contained in the current frame. Variables obtained from constants or interval parameters will also be re-initialized. All output variables will be set to MISSING.

Processing Section

The Processing section comprises:

• specific MapLan/VolLan statements;

• operators, functions and subroutines;

• user defined subroutine calls.

The iteration to GET, PROCESS and PUT each data frame is controlled by the construct:

dowhile . . . . . . . enddo

GET is performed by the logical function GET_FRAME()

LOCAL ttpos /* Tool position

tsiz /* Tool size

grcorfactor /* Corr Factor for GAMMA RAY

coalflag logical /* COAL FLAG

array[5] /* Array, numeric with 5 elements

OUTPUT

GR /* Gamma Ray corrected for Borehole Size

RATIO_GR /* Actual Ratio from the Correction Chart

GRTOOL alpha.8 /* Gamma tool type


PUT is performed by the call to the function PUT_FRAME()

Processing is performed by statements between the GET_FRAME() and the PUT_FRAME().

For example:

Any operations to be performed after all the data has been processed are entered after the enddo statement but before the end statement.

End Section

end marks the end of the program. Local subroutines used within the program appear after the end statement.

Source File Format

Continuation Character

If the last character on a source line is a tilde (~), then the next line is a continuation of the current line.

For example:

a = a + 9 - ~ b

is treated as if it were:

a = a + 9 - b

The continuation character cannot split a token over more than one line.

Comments

A slash and an asterisk (/*) and all following characters up to the end of a line are ignored by the compiler.

For example:

/*/* increment value number 1/*

START:

dowhile GET_FRAME() /* Fetch next data frame

/* Water Saturation using Ratio Method

SW = (RO / RT) ** (1 / N)

CALL PUT_FRAME /* Put or write data frame

enddo

end


this_val_01 = this_val_01 + 1 /* increment value 1

Statement Separators

A number of statements may appear on one line if they are separated by semicolons (;).

For example:

a = 1 ; b = 1 ; c = 1do ; PERFORM calcite ; until c > 10

Statement separators should be used with restraint because it is easy to obscure program logic when multiple statements are on the same line. They are useful for initializing similar or repetitious data.

For example:

Operators

MapLan/VolLan provides standard logical and arithmetic operators. When an expression is being evaluated, the operators are evaluated in the following order:

1. Exponentiation (**)

2. Unary minus (-)

3. Multiplication (*) and division (/)

4. Addition (+) and subtraction (-)

5. Concatenation (//)

6. Relational operators (<, <=, >, >=, <>, ==)

7. Logical NOT (^,\\)

8. Logical AND (&)

9. Logical OR (|)

10. All other operators and functions.

NOTE If an arithmetic subexpression contains only integers, it will be evaluated using integer arithmetic (this is a standard rule of the C language). Hence:2.5 + 1 / 2 gives the result 2.5, since "1 / 2" in integer division is zero.

For example:

• -2**2 will evaluate to -4, as the 2**2 is evaluated first, result is 4, and then the unary minus is performed to give the final result of -4.

RMA_SS=2.65; NPHI_SS=-0.015; DTMA_SS=55.6 /* Sandstone

RMA_LS=2.71; NPHI_LS=0.000; DTMA_LS=49.0 /* Limestone

RMA_DM=2.87; NPHI_DM=0.025; DTMA_DM=44.0 /* Dolomite

RMA_SD=3.89; NPHI_SD=0.120; DTMA_SD=47.0 /* Siderite


• Parentheses may be used in an expression to alter the normal order of evaluation. For example: (-2)**2 will evaluate to 4.

Operators of equal priority (refer to (3), (4) and (6) above) are evaluated from left to right within an expression.

For example:

• 5*2 + 6/2 - 9*6/3 + 4

is evaluated as (((5 * 2) + (6 / 2)) - ((9 * 6) / 3)) + 4 which evaluates to -1.

Variable Types

Alpha Variables

Alpha variables have an alpha string value and are defined using the following syntax:

The units alpha.num specify the maximum number of characters which may be assigned to the variable. Any characters beyond num will be truncated. The default length (if the "*num" is omitted) is 4. The maximum length is 72 for INPUT/OUTPUT variables and 1024 for LOCAL variables.

For example:

Logical Variables

Logical variables may have the values TRUE or FALSE and are useful for flags, switches or toggles.

For example:

Logical variables are stored as 0 if FALSE and 1 if TRUE.

Grid Name Type Comment

Grid alpha*num /* General case

Variable Type Comment

NEUT_TOOL alpha*10 /* Neutron Tool Type, e.g., CNL, SNP

MATRIX alpha /* Matrix, e.g., LIME, SAND, DOL

LITH alpha*8 /* Lith patterns e.g., SS, ST, SH,

Variable Type Comment

Test logical /* logical grid type

HCCOR logical /* carry out hydrocarbon corrections


Numeric Variables

Any variable which is not declared Alpha or Logical is numeric. Numeric variables are usually of type REAL or DOUBLE, although INTEGER and other types are also supported. A complete listing of data type values can be found in the file datatypes.h in the installation directory /include/common.

Array Variables

MapLan/VolLan supports the use of one dimensional array variables; multi-dimensional arrays are not supported.

Array variables may be of type numeric, logical, or, for local variables, string. An array variable is declared by suffixing the name with the repeat count in square brackets.

For example:

sarray[5] alpha.10

Single array elements may be accessed by following the array name with an index enclosed in square brackets [ ].

For example:

numarray[2] = numarray[i-2] + 15.602numarray[3] = SIN (numarray[2]) + 180

When a function requires an array argument, the index is used to indicate which part of an array to pass.

For example:

result = FUNCTION (numarray[5], 23)

passes the array numarray starting at element 5.

Constants

Some frequently used constants have been predefined. These are used in the same way as normal variables except that their values may not be altered.

The constant MISSING has some special properties:

• if used in an arithmetic expression, that expression will evaluate to MISSING.

• in the case of arithmetically incorrect expressions (e.g., divide by 0), the result will be MISSING.

For the purposes of the functions LT, GT, LE, and GE, TRUE is considered to be greater than FALSE. TRUE equals 1.0 and FALSE equals 0.0.

For example:

CONSTANT VALUE

MISSING Uninitialized numeric value.

PI 3.141592653589793238

TRUE The logical value TRUE.

FALSE The logical value FALSE.


CIRCLE_AREA = PI * RADIUS ** 2if (GR == MISSING) then

GR_COR = MISSING else

GR_COR = RHOF * (1-EXP (-0.09 * CALI) + 0.64 endifMYLOGICAL = TRUEYOURLOGICAL = FALSEif (MYLOGICAL & YOURLOGICAL) then

/* Both conditions true process option A

elseif (YOURLOGICAL)|(MYLOGICAL) then /* Either condition true.process option B

else/* Both conditions FALSE process option C

endif

Program Control

do

do is a post-tested loop which terminates when the condition evaluates to TRUE. The statements within the body of the loop are always evaluated at least once.

do<statements>

until <condition is true>

For example:

docount = count + 1bottom = bottom + stepgap = top - bottom until (gap <= step) | (count == 100)

The loop terminates when gap is less than or equal to step or count reaches 100.

dowhile

dowhile is a pre-tested loop which terminates when the condition evaluates to FALSE. If the condition evaluates to FALSE the first time, the statements in the loop body are never executed.

dowhile <condition><statements>

enddo


For example:

dowhile count <= 50COUNT = count + incperform WASHOUT

enddo

The body of this loop is executed until the value of count exceeds 50.

for

for is a pre-tested loop which terminates when:

• The value of a variable is greater than the final value, if the step is positive.

• The value of a variable is less than the final value, if the step is negative.

for variable = <initial> to <final> by <step> do<statements>endfor

• If loop termination occurs the first time the variable is checked, the statements in the loop are not executed. The step is optional. If omitted, the step value defaults to 1. In this case the for line would appear as:

for variable = initial to final do

The variables used in the initial, final and step statements may be altered in the body of the loop. When the loop is terminated, the loop variable retains the value which caused the termination condition to fail.

For example:

for index = 1 to 10 doa = a + index - 1

endfor

The loop executes exactly 10 times and leaves index with a value of 11.

for index = 0.5 to 9.25 by 0.5 doendfor

The loop executes 18 times with index values of 0.5, 1, 1.5, etc. leaving index with a value of 9.5.

goto

The goto statement transfers program execution to the specified label, defined by a line containing only the label followed by a colon. As a general rule, the goto construct should be avoided since its use can easily obscure program logic. The required functionality can usually be achieved in a structured way using do...until, dowhile...enddo, for...endfor or if...elseif...endif constructs.

goto <label name>

For example:


A goto must not branch into a block structured program element at a level below that of the goto. This prevents the user from inadvertently jumping into the middle of an if block or a for loop, etc. The block structured program elements into which a goto must not branch are:

• if...elseif...endif..

• dowhile...enddo

• do...until

• for...endfor

For example, the following program is illegal because it is branching into an IF block at a lower level:

goto MIDDLEif <condition> then

MIDDLE:<statements>

endif

However, the following program fragment is legal as the goto is branching to a label in a block which contains the goto.

if <condition> thenMIDDLE:<statements>goto MIDDLE

endif

The following program is also legal as the goto is branching to a label in a higher level block:

if <condition> thenMIDDLE:do

endif

A goto statement must not use the same label as a perform statement. For example, the following program is illegal as the same label is used by both a goto and a perform statement:

goto FRED

<statements>

goto FINISH /* transfers control to FINISH:

<statements> /* these statements are skipped

FINISH:

<statements> /* these statements are executed

<statements> /* execute these statements

goto MIDDLE /* back to before the start of the do

/* loop, but still within this

/* if block.

until <condition>


<statements>perform FREDFRED:

if

MapLan/VolLan provides an if structure as follows:

There may be zero or many else if statements. There may be zero or one else statement. If there are elseif and else statements, the else statement must come after the last elseif statement.

For example:

/* this is a valid block-if statement.if a > b then

c = 1; d = 1/* executed when a is greater than belseif a == b then

c = d /* executed when a is equal to belseif a < b then

c = 0; d = 0 /* executed when a is less than bendif/* this is a valid block-if statement.if (a > b) & allok then

/* executed when a > b and allok is TRUE.c = 500

else/* executed for all other cases.goto EXIT

endif/* this is a valid block-if statement. if c >= d then

c = 10 /* executed when c is greater than or/* equal to d

endif/* this is an invalid block-if statement because the else/* statement must come after the last elseif statement.if c > 67.2 then

c = 20 else

if <logical-expression> then

<statements>

elseif <logical-expressionthen

<statements>

else

<statements>

endif


d = c elseif e > maxline thenc = d endif

perform

MapLan/VolLan provides local subroutines which may be performed any number of times from anywhere in the program, or from any other local subroutine. A perform statement must not reference a label used by a GOTO statement.

The structure is:

perform LABEL_NAME<main program statements>endLABEL_NAME:<subroutine statements>return

Variables used in local subroutines are global to the main program. Variables used in the main program may be used or altered in local subroutines and vice versa.

For example:

end

A program terminates when the end statement is executed or when the physical end of the program is reached. If there are local subroutines, there must be an end statement at the end of the main program, before the first subroutine label. If there are no local subroutines, it is not necessary to have an end statement at the end of the main program.

<statements>

perform SUBA /* transfer control to label SUBA:

<statements> /* returns from SUBA to here

perform SUBB /* transfer control to label SUBB:

end /* returns from SUBB to here and stops

SUBA:

<statements> /* start of SUBA

perform SUBB /* transfers control to label SUBB:

return /* returns from SUBB to here

/* then returns back to the line

/* after the perform SUBA

SUBB:

<statements> /* SUBB statements

return /* returns back to the line

/* after the perform SUBB


For example, the following program is legal:

The following program is illegal, as there is no end statement between the program body and the first local subroutine.

<statements>perform SUBASUBA: <statements>return

<statements>

perform SUBA /* transfers control to label SUBA:

end /* program stops here

SUBA:

<statements> /* SUBA statements

return /* return control to statement after

/* perform SUBA


Functions

Introduction

A MapLan/VolLan function may be called in three ways:

1. call function ( arguments )

2. function ( arguments )

3. variable = function ( arguments )

If the function has no arguments, the parentheses must still be used. If the function has more than one argument, the arguments are separated by commas. A function may be used anywhere a variable of the same type as the function is used. For example, a logical function may be used in a dowhile, and a numeric function in an assignment statement. If either of the first two forms of function call is used, the function result is ignored. Spaces inside function parentheses are ignored by the compiler and make programs easier to read.

Frame Control

GET_FRAME

logical = GET_FRAME ( )

GET_FRAME is a logical function which reads the next frame of data and returns TRUE if that frame exists in the input dataset. If no more frames exist, the function returns FALSE. This function is usually used in a dowhile statement to process the entire input. When a frame of data is successfully read, all input variables except those whose location is parameter, will be assigned the values from the current frame, and all output grids will be set to MISSING.

The dowhile GET_FRAME ()] statement (or an equivalent construct) must be present in a program where frame-by-frame calculations are made. Brackets () must follow as these indicate that a function and not a variable is being used.

POS_FRAME

logical = POS_FRAME ( n )

Positions to frame n in the input file and reads the record. If n is less than or equal to 1, the first record in the input file will be read and the function will return TRUE. If n is greater than the number of records in the file, the function returns FALSE and the input variables will be undefined. SKIP_FRAME ( -2 ) will then position to the last record.

The symbolic constants TOP_DATA and END_DATA may be used to position to the top and end of the file respectively. For example:

call POS_FRAME ( TOP_DATA )


POS_REFERENCE

logical = POS_REFERENCE ( value )

Positions to and reads the first record in the file with a vertical reference greater than or equal to that specified. If no such value is found, the function will return FALSE and SKIP_FRAME ( -2 ) may be used to read the last record. Otherwise, the function returns TRUE.

The vertical reference grid is passed to the MapLan/VolLan module by the launcher from the reference grid in the input data.

PUT_FRAME

logical = PUT_FRAME ( )

The PUT_FRAME function writes all the input-output and output-only variables defined in the program to the output tp. This function would generally be called at the end of the loop dealing with the frame by frame processing of data. The enddo statement corresponding to the dowhile GET_FRAME () normally follows the PUT_FRAME call. The function always returns TRUE.

REWIND

logical = REWIND ( )

Positions to the beginning of the input so that the next GET_FRAME call will read the first frame of data. The function always returns TRUE.

call REWIND () call GET_FRAME ()

is the same as:

call POS_FRAME ( TOP_DATA )

Following is an example using dowhile GET_FRAME (), call POS_FRAME, call PUT_FRAME, DO UNTIL ^GET_FRAME and ENDDO:


START:

/* This code module sums all RHOB values, rewinds to the top and then writes/* a new grid but all values greater than one standard deviation from the mean/* are rejected.

/* Initialize.x = 0s = 0n = 0

dowhile GET_FRAME ()

/* Don't process missing values.if ( RHOB <> MISSING ) then

/* Summation.x = RHOB + x/* Sum all the values.s = RHOB * RHOB + s /* Sum the squares of the values.n = n + 1/* Sum the number of frames

endif enddomean = x / n/* Calculate mean./* Calculate standard deviation.std = SQRT ( ( n * s - x ** 2 ) / ( n * ( n -1 ) ) ) /* Rewind to the top, read records and reject values.POS_FRAME ( TOP_DATA )

do /* Read data until the last frame.if ( ABS ( RHOB - mean ) > std ) then

/* Reject values one standard deviation from the mean and/* write to a new grid so that the original is preserved.RHOB_STD = MISSING else RHOB_STD = RHOB endif PUT_FRAME ()

until ^ GET_FRAME ()/* Do until GET_FRAME () is false.

end/* Program END (Main Program)

/* Local Subroutines may follow this section


SKIP_FRAME

logical = SKIP_FRAME ( n )

Skips n frames in an input file and reads the next record. If n is negative, preceding frames may be read. For example, SKIP_FRAME ( -2 ) will re-read the previous frame. If n is -1, the current frame will be re-read.

If attempting to skip to before the beginning of the file, the first record in the file will be read and the function will return TRUE. If attempting to skip past the last record in the file, the function will return FALSE and the contents of the input variables are undefined. SKIP_FRAME ( -2 ) may then be used to position to the last input record.

CONGETN

numeric = CONGETN ( name, default )

Returns the value of a numeric constant; arguments as for CONGETL except that "default" is a numeric variable, expression, or constant. If the constant exists but cannot be decoded as a number, an error occurs and the program aborts. For example:

bit_size = CONGETN ( 'BIT', 6.5 )

where 'BIT' is the constant name and 6.5 is the default.

CONGETS

alpha = CONGETS ( name, default )

Returns the value of an alpha constant; arguments as for CONGETN except that "default" is an alpha variable, expression, or constant. For example:

formation = CONGETS ( 'FORMN', 'Nappamerri' )

where 'FORMN' is the constant name and 'Nappamerri' is the default returned if the constant is not defined.

File Input/Output

FCLOSE

logical = FCLOSE ( unit )

All files opened with FOPEN must be closed with FCLOSE. The unit argument may be either a unit number passed to a call to FOPEN, or the flag 0, which indicates that all open files are to be closed. The function returns TRUE if the file was successfully closed.

Normally, an FCLOSE ( 0 ) at the end of the program is sufficient; however, the limit of 20 files open at any time may require that specific files should be closed at strategic points in the program to allow other files to be opened.


FILEDELETE

logical = FILEDELETE ( name )

Deletes the given file; always returns TRUE, and errors are not reported.

FILEEXISTS

logical = FILEEXISTS ( name )

Returns TRUE if the file whose name is the value of the alpha variable, expression, or constant "name" exists.

FILEVALID

logical = FILEVALID (name)

Returns TRUE if the passed "name" is a valid filename; note that the name may not contain a directory separator.

FILEFIX

alpha = FILEFIX (name)

Returns a string containing the passed "name" with characters which are invalid in a filename replaced by "!" for directory separators and "_" for all other characters.

FOPEN

logical = FOPEN ( mode, filename, unit )

Opens an ordinary sequential file for use by FREAD, FWRITE and FCLOSE. Returns FALSE if the open failed. Up to 20 files may be open at a time, each identified by a unique unit value. Open files must be closed with FCLOSE when completed. The arguments are used as follows:

• "mode"

A string defining the file usage. Valid values are:

— 'read'

The file is to be read by FREAD. The first call to FREAD will return the first record in the file; subsequent calls to FREAD will read the following records in the file.

— 'write'

The file is to be written to by FWRITE. If the file already exists, the function will fail and return FALSE.

— 'owrite'

The file is to be written to by FWRITE. If the file already exists, it will be overwritten.

— 'awrite'

The file is to be written to by FWRITE. If the file already exists, it will be appended to.

• "filename"


A string defining the name of the file to be opened. This name may be generated by a call to if a temporary or scratch file is being created. No case conversion is performed.

• "unit"

A positive integer to identify this file in calls to FREAD, FWRITE, and FCLOSE. The unit must not be in use.

If the FOPEN call fails, an error message indicating the cause of the error is issued. FOPEN call failure may be caused by the following:

• file does not exist when trying to open for read mode;

• user does not have the operating system read/write access;

• invalid file name (depends on the operating system being used).

Some examples of the use of FOPEN are:

To open an external data file to be processed:

if ( ^FOPEN ( 'read', 'mydata', 1 ) ) then /* the open failed goto ENDER

endif

To open a dump file for writing calculation results:

DUMP_OPN = FOPEN ( 'write', 'dumpfile', 2 )

If "dumpfile" already exists, the function returns FALSE and the file will not be opened.

FREAD

alpha = FREAD ( unit )

Reads the next record from a sequential file opened by a call to FOPEN. The unit argument must be the same value as the unit argument passed to the FOPEN call for this file. The string returned is the record read. If there are no records left in the file, the string is set to the characters EOF to signal end of file.

The following processes an entire data file:

record = FREAD ( 1 ) dowhile record <> 'EOF'

perform process_recordrecord = FREAD ( 1 )

enddo

The following are useful routines for manipulation of data fields in records:

INDEX, NDECODE, SUBSTRING, TOKEN, TRIM.


FWRITE

logical = FWRITE ( "unit", "string" )

Writes a record to a sequential file opened by a call to FOPEN. The "unit" argument must have the same value as the unit argument passed to the FOPEN call for this file. If an error occurs during the write, an error message is displayed and the function result is FALSE.

The following writes the generated data record to the file opened by FOPEN associated with Unit 5:

record = recname //' '// zone_name //' '// ENCODE ('{N}', depth) OK = FWRITE (5, record)

TMPFILE

pathname = TMPFILE ( directory )

Generates a file name within the specified directory such that the file with the generated name will not already exist. If the passed name is blank, the file name is in the directory specified by the environment variable MINTMP; otherwise the returned name will include the specified directory.

The file name generated may be used in a call to FOPEN and is useful for temporary files to hold intermediate results of calculations, etc.

file = TMPFILE ( 'tmpdir' )

Or

file = TMPFILE ( '' )

User Defined - Macros

A macro is a single or multi-line expression. Essentially, macros provide the ability to create re-usable code. This is facilitated by allowing parameter substitution. Macros may be nested so one macro may call another. However, a macro may not call itself (no recursion) and no variable within the macro should have the same name as the macro. Macro expressions may include any valid constructs, calls to other Epos functions and calls to other macros. Macro expansion is performed when the MapLan/VolLan program is compiled. Because of this, a MapLan/VolLan program must be recompiled when a macro which it uses is changed.

When a macro is used in a MapLan/VolLan program, the text of the macro is directly, with parameter substitution, copied into the program.

The following macro sets the coal flag according to the sonic reading:

MACRO SET_COAL ( SONIC, COAL )if ( SONIC > 95.0 ) then

COAL = 1.0else

COAL = MISSING endif

This macro may be called by the MapLan/VolLan program, as illustrated below:

dowhile GET_FRAME () SET_COAL (dt, coal )/* insert multi-line macrocall PUT_FRAME()


enddoend

Because macros are a directly substituted into the MapLan/VolLan code, the program could become longer than necessary if a particular macro is used frequently. This may be avoided by using the macro in a local function.

The structure could be:

dowhile GET_FRAME ()perform SUBCOALcall PUT_FRAME ()enddo

endSUBCOAL:

SET_COAL ( dt, coal ) return

Logical

AND or &

logical = logical_exp1 & logical_exp2

Or

logical = AND ( logical_exp1, logical_exp2 )

where logical_exp1 and logical_exp2 are variables, expressions, or constants of type logical. Returns the logical ANDing of the two logical arguments—i.e., TRUE if both arguments are TRUE; otherwise FALSE. This is used to create complex logical expressions from simple logical expressions. The resulting value will be TRUE only if ALL of the simpler logical expressions evaluate to TRUE.

good_hole = ( caliper < 10 ) & ( drho < 0.2 ) & ~( rhob > 2.1 ) & good_phi

will set good_hole to TRUE only if all of the bracketed expressions evaluate to TRUE and the logical variable good_phi has a value of TRUE.

EQ or ==

logical = exp1 == exp2

Or

logical = EQ ( exp1, exp2 )

where exp1 and exp2 are variables, expressions, or constants of any type, though both must be of the same type. Returns TRUE if exp1 is equal to exp2; otherwise, it returns FALSE. For numeric arguments, a tolerance of 0.000005 is used. The function returns TRUE if the expressions are numeric and both values are MISSING.

For alpha arguments, trailing spaces are ignored.

big = 500


small = 200same = big == small

will set same to FALSE, as 500 is not equal to 200.

GE or >=

logical = exp1 >= exp2

Or

logical = GE ( exp1, exp2 )

where exp1 and exp2 are variables, expressions, or constants of any type, though both must be of the same type. Returns TRUE if exp1 is greater than or equal to exp2; otherwise it returns FALSE. For numeric arguments, a tolerance of 0.000005 is used. The function returns FALSE if the expressions are numeric and either value is MISSING.

water_level = -250.625viable = water_level >= -300

will set viable to TRUE, as -250.625 is greater than -300. viable will be TRUE for all values of water_level down to and including -300.

GT or >

logical = exp1 > exp2

Or

logical = GT ( exp1, exp2 )

where exp1 and exp2 are variables, expressions, or constants of any type, though both must be of the same type. Returns TRUE if exp1 is greater than exp2; otherwise it returns FALSE. The function returns FALSE if the expressions are numeric and either value is MISSING.

grid_1 = 5 > 250

will set grid_1 to FALSE, as 5 is not greater than 250.

LE or <=

logical = exp1 <= exp2

Or

logical = LE ( exp1, exp2 )

where exp1 and exp2 are variables, expressions, or constants of any type, though both must be of the same type. Returns TRUE if exp1 is less than or equal to exp2; otherwise, it returns FALSE. For numeric arguments, a tolerance of 0.000005 is used. The function returns FALSE if the expressions are numeric and either value is MISSING.

iterate = 0.01difference = 0.5do

r1 = root1


perform ESTROOT root2 = r2 difference = root2 - ( root1 + root2 ) / 2

until ( iterate <= difference )

Iterate will always be less that difference until the root1 and root2 are closer than 0.01 and thus the DO...UNTIL will continue to loop. In practice it would be wise to add a test to ensure that the roots actually converge otherwise the program will never exit the loop.

LT or <

logical = exp1 < exp2

Or

logical = LT ( exp1, exp2 )

where exp1 and exp2 are variables, expressions, or constants of any type, though both must be of the same type. Returns TRUE if exp1 is less than exp2; otherwise returns FALSE. The function returns FALSE if the expressions are numeric and either value is MISSING.

current_val = 200high_val = 5 < current_val

will set high_val to TRUE, as 5 is less than 200.

MISS

logical = MISS ( numeric_exp )

Returns TRUE if the numeric expression evaluates to MISSING; otherwise returns FALSE. This function is equivalent to "logical = numeric_exp == MISSING"

NE or <>

logical = exp1 <> exp2

Or

logical = NE ( exp1, exp2 )

where exp1 and exp2 are variables, expressions, or constants of any type, though both must be of the same type. Returns TRUE if exp1 is not equal to exp2; otherwise, it returns FALSE. For numeric arguments, a tolerance of 0.000005 is used and the function returns TRUE if either (but not both) values are MISSING. For alpha arguments, trailing spaces are ignored.

surface_elevation = 345measuremet_ref = 340rt_not_ground = surface_elevation <> measurement_ref

NOT or ^ or \\

logical = ^ logical_exp

Or


logical = \\ logical_exp

Or

logical = NOT ( logical_exp )

Returns TRUE if the argument is FALSE, or FALSE if the argument is TRUE.

local_l[1] = TRUElocal_l[2] = ^ local_l[1]

will set local_l[2] to FALSE.

this_side = TRUEother_side = ^ THIS_SIDE

will set other_side to FALSE.

OR or |

logical = logical_exp1 | logical_exp2

Or

logical = OR ( logical_exp1, logical_exp2 )

where exp1 and exp2 are variables, expressions, or constants of type logical. Returns the logical ORing of the two logical arguments—TRUE unless both of the arguments are FALSE. This is useful for combining the results of simple logical expressions into more complex expressions. The resulting value will be TRUE if ANY of the simpler logical expressions evaluate to TRUE.

will set stop_calculations to TRUE if one or more of the bracketed expressions evaluate to TRUE, or if the logical variable error_flag has a value of TRUE.

OUTSIDE

logical = OUTSIDE ( exp1, exp2, exp3 )

where exp1, exp2, and exp3 are numeric variables, expressions, or constants. exp2 and exp3 define a range of values. The function result is TRUE if exp1 is outside that range, or if any of the expressions has the value MISSING.

OUTSIDE ( SLOPE ( 'TOPO' ), -2, 2 )

The following will set report to FALSE:

top = 15bottom = 195 depth = 16 report = OUTSIDE ( depth, top, bottom )

Or

REPORT = OUTSIDE ( depth, 16, 20 )

stop_calculations = ( loop_counter >=50 ) |~

( control_char == 'Q' ) | error_flag


The following will set report to TRUE.

REPORT = OUTSIDE ( 1, bottom, top )

RANGE

logical = RANGE ( exp1, exp2, exp3 )

where exp1, exp2, and exp3 are numeric variables, expressions, or constants. exp2 and exp3 define a range of values. The function result is TRUE if exp1 is within that range, or is equal to exp2 or exp3. The result is FALSE if any of the expressions has the value MISSING.

The following will set process to TRUE:

top = 15bottom = 195 depth = 16process = RANGE ( depth, top, bottom )

Or

process = RANGE ( depth, bottom, top )

Or

process = RANGE ( 17, top, bottom )

The following will set process to FALSE:

process = RANGE ( 12, top, bottom )

TABLE

logical = TABLE ( search_string, table )

where search_string is a string to be searched for table is an alphanumeric containing a list of strings. The function returns TRUE if the search string exists in the table as a space delimited string.

For example,

TABLE ( 'test', 'test1 test2 test3' )

returns FALSE

TABLE ( 'test3', 'test1 test2 test3' )

returns TRUE

Numeric

ABS

numeric = ABS ( exp )

Returns the absolute value of the argument.

bottom = 1012top = 10.3


height = ABS ( top - bottom )

will set height to 1001.7 as that is the absolute value of -1001.7. It will always be positive.

ACOS

numeric = ACOS ( exp )

Returns the angle whose cosine is the passed argument. The angle returned is expressed in degrees (not radians).

ASIN

numeric = ASIN ( exp )

Returns the angle whose sine is the passed argument. The angle returned is expressed in degrees (not radians).

ATAN

numeric = ATAN ( exp )

Returns the angle whose tangent is the passed argument. The angle returned is expressed in degrees (not radians).

ATAN2

numeric = ATAN2 ( exp1, exp2 )

The result is the arctangent of exp1 / exp2, and is:

• positive if exp1 is positive;

• negative if exp1 is negative;

• 0 if exp1 is 0 and exp2 is positive;

• 180 if exp1 is 0 and exp2 is negative; 90 (or -90) if exp2 is 0.

An error message is generated if exp1 and exp2 are both 0.

The angle returned is expressed in degrees (not radians).

COS

numeric = COS ( exp )

Returns the cosine of the angle represented by the argument in degrees (not radians).

DIVIDE or /

numeric = exp1 / exp2

Or


numeric = DIVIDE ( exp1, exp2 )

Returns the result of dividing exp2 into exp1.

If both exp1 and exp2 are integers, the expression will be evaluated in integer mode, otherwise the evaluation will be performed in real mode. For example:

4 / 5 is 0, while 4.0 / 5 is 0.8.

DROUND

numeric = DROUND ( exp1, exp2 )

Returns the value of exp1 rounded to exp2 decimal places or MISSING if either argument is MISSING.

EXP

numeric = EXP ( exp )

Returns e raised to the value of exp.

FTEST

numeric = FTEST ( f, v1, v2 )

F-Distribution Probability Function

where:

The returned value is the probability corresponding to the passed F-ratio.

IFC

numeric = IFC ( logical_exp, exp1, exp2 )

Returns the value of exp1 if the logical is TRUE; otherwise, returns the value of exp2.

INT

numeric = INT ( exp )

Truncates the decimal part from the value of exp; returns MISSING if the argument is MISSING.

f is a numeric containing the F ratio;

v1 is a numeric containing the degrees of freedom for the first sample (numerator);

v2 is a numeric containing the degrees of freedom for the second sample (denominator).


LIMIT

numeric = LIMIT ( exp, min, max )

where all the arguments are numeric. If the first argument is MISSING, the functions returns MISSING. Otherwise, the functions result will be "min" if exp<min, "max" if exp>max, and otherwise "exp". A MISSING value for either "min" or "max" will be ignored. For example:

LIMIT (4, MISSING,2)

returns 2.

GRID

numeric = GRID ( exp )

Returns the natural logarithm of the argument, or MISSING if the argument is less than or equal to zero.

GRID10

numeric = GRID10 ( exp )

Returns the logarithm to base 10 of exp, or MISSING if the argument is less than or equal to zero.

MAX or |>

numeric = exp1 |> exp2

Or

numeric = MAX ( exp1, exp2 )

If any argument is MISSING, the result is MISSING. Returns the maximum (greater) of the two numeric arguments. When called as a function, MAX may have up to 10 arguments. For example:

numeric = MAX ( exp1, exp2, exp3, exp4, exp5 )phi_sonic = 0.15pxnd = 0.17phit = 0.18phi = MAX ( 0.001, phi_sonic, pxnd, phit )

will set phi to 0.18 as that is the largest value in the argument list.

MIN or |<

numeric = exp1 |< exp2

Or

numeric = MIN ( exp1, exp2 )

If any argument is MISSING, the result is MISSING. Returns the minimum (lesser) of the two numeric arguments when used as an operator. When called as a function, MIN may have up to 10 arguments. For example:

numeric = MIN ( exp1, exp2 )


numeric = MIN ( exp1, exp2, exp3, exp4, exp5 )vsh_gr = 0.15vsh_nd = 0.17vsh_mn = 0.18vsh_min = MIN ( vsh_gr, vsh_nd, vsh_mn )

will set vsh_mn to 0.15, as that is the smallest value in the argument list.

MINUS or -

numeric = exp1 - exp2

Or

numeric = MINUS ( exp1, exp2 )

Returns the result of subtracting the second argument from the first.

MOD

numeric = MOD ( exp1, exp2 )

Returns the remainder when exp1 is divided by exp2.

remainder = MOD ( 112.5, 10 )

will set remainder to 2.5, the remainder after dividing 112.5 by 10.

MULTIPLY or *

numeric = exp1 * exp2

Or

numeric = MULTIPLY ( exp1, exp2 )

Returns the result of multiplying the two numeric arguments.

NINT

numeric = NINT (exp)

Returns the nearest integer to the argument or MISSING if the argument is missing.

NONMISS

numeric = NONMISS ( exp1, exp2 )

Returns the first non MISSING value in the argument list, or MISSING if the values of all the arguments are MISSING. Up to 10 arguments may be specified. For example:

numeric = NONMISS ( exp1, exp2, exp3, exp4, exp5 )


PLUS or +

numeric = exp1 + exp2

Or

numeric = PLUS ( exp1, exp2 )

Returns the result of adding the two arguments.

RAISE or **

numeric = exp1 ** exp2

Or

numeric = RAISE ( exp1, exp2 )

Returns exp1 raised to the power of exp2.

RANDOM

numeric = RANDOM ( exp1, exp2 )

Returns a uniform random number within the range defined by the two arguments.

RANNORMAL

numeric = RANNORMAL ( mean, sd )

The RANNORMAL function will generate a random number sequence with a Gaussian distribution. For example, the following will generate a grid with random values from a caliper grid:

randomgrid = RANNORMAL ( mean_cali, stddev_cali )

ROUND

numeric = ROUND ( exp1, exp2 )

Returns the value of exp1 rounded to exp2 significant figures, or MISSING if either argument is MISSING.

SIGN

numeric = SIGN ( exp1, exp2 )

Returns the value of exp1 with the sign of exp2.

temp = -256.33flip_5 = SIGN ( 5, temp )

will set flip_5 to -5 as temp is a negative number.


SIN

numeric = SIN ( exp )

Returns the sine of the angle represented by the argument in degrees (not radians).

SQRT

numeric = SQRT ( exp1 )

Returns the square root of exp1, or MISSING if the argument is negative.

TAN

numeric = TAN ( exp )

Returns the tangent of the angle represented by the argument in degrees (not radians).

UMINUS or -

numeric = -exp

Or

numeric = UMINUS ( exp )

Returns -1 multiplied by the argument.

String Related

CONCAT or //

string = string_exp1 // string_exp2

Or

string = CONCAT ( string_exp1, string_exp2 )

Returns the concatenation of string_exp1 followed by string_exp2. When called as a function, CONCAT may have up to 10 arguments. For example:

string = CONCAT ( s_exp1, s_exp2, s_exp3, s_exp4 )today = 'MONDAY' surname = 'SMITH' firstname = 'JOHN'report_line = CONCAT ( 'DAY: ',today, '. WORKER WAS: ',~ firstname, surname )

will set report_line to 'DAY: MONDAY. WORKER WAS: JOHN SMITH'

ENCODE

alpha = ENCODE ( format, expression )

Or


alpha = CONVERT ( format, expression )

Converts the numeric or logical argument to a string. The format argument is a string in which to embed the numeric or logical argument. An '{N}' in the format is replaced by the value of the numeric argument and an '{L}' is replaced by the value of a logical argument.

A logical argument is returned as either TRUE or FALSE. The N format may have the form {N[width][.decimals][#]} where "width" is optional and specifies the number of decimal places. If "#" is used, leading zeroes are not suppressed.

value = 20result_str = CONVERT ( 'There are {N} seams', value )result_1 = CONVERT ( 'There are {N6.2#} seams', value)

would set results_str to:

'There are 20 seams'

and would set results_1 to:

'There are 020.00 seams'

Similarly:

avail = FALSE detail_line = CONVERT ( 'Sectors available: {L}', avail )

would set detail_line to: 'Sectors available: FALSE'

IFCS

string = IFCS ( logical_exp, str1, str2 )

Returns the value of str1 if the logical expression is TRUE; otherwise, returns the value of str2.

local_s = IFCS ( depth > 500, 'Red', 'Blue' )

will set local_s to 'Red' if depth is greater than 500; otherwise, local_s will be set to 'Blue'.

INDEX

numeric = INDEX ( str1, str2 )

Returns the character position within str1 at which str2 starts, or 0 if str2 does not exist in str1.

instring = 'TODAYS VALUE IS $112.46' dollar_pos = INDEX ( instring, '$' )

will set dollar_pos to 17.

This can be useful for string manipulations, such as:

out_string ='TOTAL OUTPUT TODAY IS' // ~ SUBSTRING ( INSTRING, DOLLAR_POS, 7 )

which sets out_string to 'TOTAL OUTPUT TODAY IS $112.46'


LDECODE

logical = LDECODE ( string_exp )

Decodes the string expression into a logical value. If the string expression evaluates to the TRUE or YES, the result of the function is TRUE. Otherwise, the result function is FALSE.

This is the reverse of the ENCODE or CONVERT function and is useful for decoding strings made up by ENCODE or CONVERT.

lstr = 'TRUE'logic = LDECODE ( lstr )

Will set logic to TRUE.

lstr = 'TRUE, FALSE, FALSE, TRUE, TRUE'lend = 0; strt = 1for i = 1 to 5 do tmpstr = SUBSTRING ( lstr, strt, LEN ( TRIM ( lstr ) ) - lend )

/* End of next logical.lend = INDEX ( tmpstr,',' ) + strt - 2larray[i] = LDECODE ( SUBSTRING ( lstr, strt, lend ) ) /* Start of next logical.strt = lend + 2

endfor

Sets the array of logicals array to the values indicated by the string LSTR.

LEN

numeric = LEN ( string_exp )

Returns the number of characters in the string argument.

LEN returns the defined length of a string variable, not the number of characters which have been assigned to that variable.

The LEN of a literal character string is the number of characters between the outside single quotes minus half of the number of single quotes inside the string. Refer also to TRIM.

str_len = LEN ( 'ABC' )

will set str_len to 3.

str_len = LEN ('DON''T')

will set str_len to 5, as the '' inside the outer quotes represents one quote.

LOCASE

string = LOCASE ( string_exp )

Converts the string expression to lower case. This is useful when comparing input data from different sources which are not case sensitive.

if ( LOCASE ( FREAD ( 1 ) ) == 'zone20') then/* The record just read is converted to zone20

See Also


"UPCASE".

NDECODE

numeric = NDECODE ( string_exp )

Decodes the string expression into a numeric value. The result is MISSING if the string is blank or not a valid number. This is the reverse of the ENCODE or CONVERT function and is useful for decoding strings made up by ENCODE or CONVERT.

nstr = '1.3469'num = NDECODE ( nstr ) + 5

Will set num to 6.3469.

NUMSTR

alpha = NUMSTR ( number )

Converts a number into a string variable. A numeric precision of 13 digits is used.

SCALE_APPLY

numeric = SCALE_APPLY ( to_linear, type_code, value )

Applies a scale conversion where to_linear is a logical. If its value is TRUE, the passed numeric value is converted from the specified scale type to a linear scale, while if it has the value FALSE, the passed value is converted to the specified scale type. type_code is a numeric as returned by SCALE_APPLY. If invalid, MISSING is returned. value is the number to be scaled.

The following formulae are used:

SCALE_CODE

numeric = SCALE_CODE ( scale_string )

Return a scale code corresponding to the passed scale string. The returned value may then be used as an argument to SCALE_APPLY, where scale_string is one of:

Scale type To linear

LINEAR value value

LOGARITHMIC GRID10 ( value ) 10 value

HYPERBOLIC 1/value 1/value

MAGNOLIA 1/value2

Linear Linear scale

Logarithmic Logarithmic scale

Hyperbolic Hyperbolic scale

Magnolia Magnolia scale

1 value


STRNUM

numeric = STRNUM ( string )

Converts a string to a number. The function returns MISSING if the string is blank or not a valid number.

SUBSTRING

alpha = SUBSTRING ( string_exp, exp1, exp2 )

The string returned is made up from the characters in the argument string starting at the nth character in the argument string (where n is the value of exp1). exp2 is the number of characters transferred from the argument string to the result string. For example:

my_str = SUBSTRING ( 'DONKEY', 2, 3 )

gives 'my_str' the value of 'ONK'.

TOKEN

alpha = TOKEN ( string_exp, n )

Selects n'th token from a string of tokens, where the tokens are delimited by spaces.

Useful when unpacking fixed format records. For example:

record = FREAD ( 1 )recno = TOKEN ( record, 1 ) name = TOKEN ( record, 2 ) count = NDECODE ( TOKEN ( record, 4 ) )

If there are fewer than "n" tokens in the string, the result is blank.

TRIM

string = TRIM ( string_exp )

Truncates trailing blanks from the argument string.

This is useful when accessing a string variable where only a small part of the allocated space for that string variable has been used. For instance:

if string_var has been declared as ALPHA.10 but contains the string "FRED" then

string_var//' was here.'

would result in "FRED was here.", while

TRIM (string_var)//' was here.'

would give "FRED was here."

In this case, LEN ( TRIM ( string_var ) ) is 4, the number of characters in the string FRED, regardless of how large string_var is defined to be.


UPCASE

string = UPCASE ( string_exp )

Converts the string expression to uppercase. This is useful when comparing input data from different sources which are not case sensitive.

UPCASE ( 'Taglu20' )

results in the value 'TAGLU20'

WILDCARD

logical = WILDCARD ( regex, match_string )

Performs a regular expression match.

The function returns TRUE if the match_string matches the regular expression. The passed expression is a standard UNIX regular expression, with the following changes (made to simplify filename matching):

'*' is replaced by '.*'

'.' is replaced by '\\.'

'?' is replaced by '.'

'^' is inserted at the beginning of the string

'$' is inserted at the end of the string.

The maximum length of the expression is 32 characters.

For example:

WILDCARD ( '*.*', 'anything' )

returns TRUE

WILDCARD ( '*.tmp', 'a.tmp.1' )

returns FALSE

Regression

The MapLan/VolLan regression functions use arrays which must be declared in the MapLan/VolLan program. The sizes of these arrays are:

SUM_SIZE = (nval+1)*(nval+2)+1 (Size of the regression sums array)

INV_SIZE = (nval+1)*(nval+1) (Size of the inverted sums work array)

BS_SIZE = (1+nval) (Size of the coefficients array)

where nval is the number of independent variables. Unless otherwise specified, all arguments are numeric and are not modified by the functions.

NOTE To run any MR_GET... functions, MR_STATISTICS needs to be run first.


MR_APPLY

This function returns the value of the dependent variable calculated by applying the regression coeficients to the passed point.

double = MR_APPLY ( nval, vals, bs )

where:

MR_BACKELIM

Multiple regression with backward elimination solver.

This function returns false if the regression cannot be solved. It solves the regression equations and then attempts to eliminate independent variables for which the usage code is not "Always" and whose removal does not cause the significance level to fall below that specified. Any independent variable removed from the regression will have its coefficient returned as zero.

logical = MR_BACKELIM ( level, nval, sums, usage, suminv, bs )

where:

MR_GET_COR

Returns the correlation matrix.

call MR_GET_COR ( cor )

where:

nval is the number of independent variables;

vals is an array of size nval containing the values of the independent variables;

bs is an array of size BS_SIZE containing the values of the regression coefficients as returned by MR_SOLVE.

level is the regression significance level;


sums is an array of size SUM_SIZE (as passed to MR_INIT and MR_VALUE) containing the regression sums;

usage is an array of size BS_SIZE containing the variable usage keys (see the description of MR_USAGE_CODE for details);

suminv is an array of size INV_SIZE; on return it contains the inverted regression matrix;

bs is an array of size BS_SIZE and returns the values of the regression coefficients (see the description of the MR_SOLVE for details).


MR_GET_COV

Returns the variance-covariance matrix.

call MR_GET_COV ( cov )

where:

MR_GET_DEV

Returns the standard deviation for each variable.

call MR_GET_DEV ( dev )

where:

MR_GET_DFD

Returns the degrees of freedom for deviation (number of points - 1 - number of independent variables).

numeric = MR_GET_DFD ()

MR_GET_DFR

Returns the degrees of freedom for regression (number of independent variables).

cor is a numeric array of size nval*(nval+1); on return, the first nval elements contain the correlations of the first independent variable against the independent variables, the second nval elements contain the correlations of the second independent variable against the independent variables, etc., and the last nval elements (nval2 + 1) to (nval2 + nval) contain the correlations of the dependent variable against the dependent variables.

cov is a numeric array of size (nval+1) * (nval+1); on return it contains the variance-covariance matri, in the order "independent variables", "dependent variables".

dev is a numeric array of size BS_SIZE; on return the first nval values contain the standard deviations for the independent variables and dev[nval+1] contains the standard deviation for the dependent variable.


numeric = MR_GET_DFR ()

MR_GET_DFT

Returns the degrees of freedom for total (number of points - 1).

numeric = MR_GET_DFT ()

MR_GET_F

Returns the F ratio

numeric = MR_GET_F ()

MR_GET_MEAN

Returns the mean for each variable.

call MR_GET_MEAN ( mean )

where:

MR_GET_MND

Returns the mean square due to deviations

numeric = MR_GET_MND ()

MR_GET_MNR

Returns the mean square due to regression

mean is a numeric array of size BS_SIZE; on return the first nval values contain the means for the independent variables and mean[nval+1] contains the mean for the dependent variable.

mean squared due to regressionmean squared due to deviation---------------------------------------------------------------------------

sum of squares due to deviationsnumber of points-1-number of independent variables------------------------------------------------------------------------------------------------------------------------------

sum of squares due to regressionnumber of independent variables------------------------------------------------------------------------------


numeric = MR_GET_MNR ()

MR_GET_MSD

Returns the square root of the mean square due to deviations.

numeric = MR_GET_MSD ()

MR_GET_R

Returns the coefficient of multiple correlation .

numeric = MR_GET_R ()

MR_GET_R2

Returns the goodness of fit or coefficient of multiple determination

numeric = MR_GET_R2 ()

MR_GET_RA

Returns the adjusted coefficient of multiple correlation .

numeric = MR_GET_RA ()

MR_GET_RA2

Returns the adjusted goodness of fit or adjusted coefficient of multiple determination .

numeric = MR_GET_RA2 ()

MR_GET_SSD

Returns the sum of squares due to deviations

R2

R2 sum of sqares due to regression

sum of squares due to deviation----------------------------------------------------------------------------

Ra2

Ra2

yi yiˆ–

2

i 1=

n


numeric = MR_GET_SSD ()

MR_GET_SSR

Returns the sum of squares due to regression

numeric = MR_GET_SSR ()

MR_GET_SST

Returns the total sum of squares.

numeric = MR_GET_SST ()

MR_GET_SXX

Returns SXX for each variable

call MR_GET_SXX ( sxx )

where:

MR_GET_VAR

Returns the variance for each variable.

call MR_GET_VAR ( var )

where:

sxx is a numeric array of size nval+2; on return it contains SXX for each variable. sxx[1] returns the value for the constant term (so this will always be 1.0), sxx[2] to sxx[nval+1] return the values for the independent variables, and sxx[nval+2] returns the value for the dependent variable.

yi y– 2

i 1=

n

yi y– 2

i 1=

n

xi x– 2

i 1=

n


MR_INIT

This function initializes the sums array and the count of values. These are used in subsequent calls to the other regression routines.

call MR_INIT ( nval, count, sums )

where:

Any number of regression analyses may be performed simultaneously, but there must be one MR_INIT call for each analysis, and each one must use different variables for the three arguments.

MR_SOLVE

Multiple regression solver.

logical = MR_SOLVE ( nval, sums, suminv, bs )

where:

The function returns false if the regression cannot be solved.

var is a numeric array of size BS_SIZE; on return the first nval values contain the variances for the independent variables and var[nval+1] contains the variance for the dependent variable.


count is the number of points used in the regression;

sums is an array of size SUM_SIZE, used as a work area.

count is returned as zero, and the sums array is returned with all zero values.

nval is the number of independent variables



bs is an array of size BS_SIZE and returns the values of the regression coefficients. bs[1] is the constant term, bs[2] is the coefficient of the first independent variable, etc


MR_STATISTICS

This function must be called before any of the MR_GETxxx statistics query functions are called. The regression statistics are calculated and stored for use by the MR_GETxxx query functions. Note that since this function calls MR_SOLVE, a separate call is not required.

call MR_STATISTICS ( nval, sums, suminv, bs )

where:

MR_USAGE_CODE

Convert a usage string into a numeric usage code.

numeric = MR_USAGE_CODE ( usage_string )

where:

MR_VALUE

Add another point to regression sums.

call MR_VALUE ( nval, vals, weight, count, sums )

where:




bs is an array of size BS_SIZE and returns the values of the regression coefficients. bs[1] is the constant term, bs[2] is the coefficient of the first independent variable, etc

usage_string is an alpha variable or constant containing the text form of the usage code; it must be "Always" or "Significant". The numeric code is passed to MR_BACKELIM.


vals is an array of size BS_SIZE, containing the values for the current point; weight is the weighting factor to be applied to this point;


The first nval elements of the vals argument are the independent variables; the dependent variable is passed in element [nval+1] of vals.

Miscellaneous

DEGTODMS

dms_string = DEGTODMS ( flag, degrees )

Returns a degrees, minutes and seconds string from the passed decimal degrees. The format of the result depends on the value of flag as follows:

where:

For example:

counter1 = 105.1003591667DEGTODMS ( 'full', counter1 )returns: 105 6' 1.2390012001"DEGTODMS ( 'abbrev', counter1 )returns: 105 6 1.2930012001DEGTODMS ('survey', counter1)returns: 105.060129300120

count is modified and is the updated count of the number of points in the regression;

sums is an array of size SUM_SIZE (as passed to MR_INIT) and is modified with the updated regression sums. It should be the array that was passed to MR_INIT.

Flag DMS Format

'abbrev' DDD MM SS.SSSS

'survey' DDD.MMSSSSSS

'full' or neither of above DDD MM' SS.SSSS"

DDD represents the whole number of degrees;

MM (or MM') represents the whole number of minutes;

SS.SSSS (or SS.SSSS" or SSSSSS) represents the seconds. The SSSSSS format has an implied decimal point following the first 'SS'.


DISPLAY_ERROR

call DISPLAY_ERROR ( message )

Display an error message. This function displays the passed message and causes the MapLan/VolLan program to abort with an error condition.

DISPLAY_MESSAGE

call DISPLAY_MESSAGE ( message )

Display a message. This function displays the passed message.

DMSTODEG

DEGREES = DMSTODEG ( dms_string )

Converts a degrees, minutes and seconds string to decimal degrees. The dms_string may be one of the following three formats:

DD MM SS.SSSS

DDD MM' SS.SSSS"

DDD.MMSSSSS

where:

For example:

counter1 = DMSTODEG ('105.0601293')counter1 = DMSTODEG ('105 6 1.293')counter1 = DMSTODEG ('105 6" 1.293"')

are equivalent, and all would set counter1 to 105.1003591667 degrees.

Refer to the DEGTODMS for converting numeric degrees to a degrees, minutes and seconds string.

RAINBOW

string = RAINBOW ( value, min, max )

Returns an RGB color of the form "#rrggbb", where "rr", "gg", and "bb" are 2 digit hexadecimal numbers representing the red, green, and blue values, respectively.

where:

DDD represents the whole number of degrees;

MM (or MM') represents the whole number of minutes;

SS.SSSS (or SS.SSSS" or SSSSSS) represents the seconds. The SSSSSS format assumes that there is a decimal place following the first 'SS'.

value is the number whose color is to be returned;


If the passed value is less than or equal to the minimum, blue (#0000ff) is returned. If it is greater than or equal to the maximum, red (#ff0000) is returned. Intermediate values return results such that colors corresponding to a rainbow are produced.

SYSTEM

logical = SYSTEM ( command )

Executes the operating system command. This may be useful for making copies of files, invoking editors or other programs, or any other operating system task which would be difficult to perform within a MapLan/VolLan program. The function returns TRUE if the command executed successfully (i.e., had a return value of zero).

Ask

The action of the Ask functions depends upon whether the environment variable MIN_DIALOGS is defined. If it is not, the default value is returned. If it is defined, a dialog window is created with the default value displayed, and the entered value is returned.

ASKL

logical = ASKL ( prompt_string, default )

where:

ASKLIT

string = ASKLIT ( prompt_string, default )

where:

ASKN

numeric = ASKN ( prompt_string, default )

where:

min is a numeric specifying the lower limit;

max is a numeric specifying the upper limit.

prompt_string is a string containing the prompt to be displayed

default is a logical containing the default value to be returned


default is a string containing the default value to be returned.


ASKS

string = ASKS ( prompt_string, default )

where:

ASKS differs from ASKLIT in that it returns only the first token in the entered string.

Status

This group of functions returns information about the execution status of a MapLan/VolLan module.

EXIT_STATUS

Sets the exit status for the MapLan/VolLan module.

call EXIT_STATUS ( status )

where:

FINISH

logical = FINISH ()

Returns TRUE if no more frames of data remain to be processed by the MapLan/VolLan module.

START

logical = START ()

Returns TRUE if no frames of data have yet been processed by the MapLan/VolLan module.


default is a numeric containing the default value to be returned.


default is a string containing the default value to be returned.

status is a numeric specifying the return code of the MapLan/VolLan module. If the status is non-zero, the module will display a "terminated with errors" message.


External Functions

Overview

External functions may be called from within a MapLan/VolLan program. Because the MapLan/VolLan program is converted to C, it is easier if the external function is also written in this language, although Fortran may also be called if the argument passing mechanism is compatible.

Compilation and Linking

Files containing compiled external functions are passed to loglan_compile by the OBJS or EXTLIBS arguments.

If these are defined using mui_loglan, they will be automatically passed to maplan_compile when the MapLan/VolLan program is compiled. The OBJS parameter ("External Objects" in mui_maplan) is a space separated list of files to be linked with the MapLan/VolLan program. Each entry in the list is used as follows:

• If a directory is supplied, the entry (suffixed with ".o" if no extension is supplied) is added to the list of files to be linked.

• If the entry does not contain a directory, "./loglan" is used, and the extension is checked. If the extension is non-blank and is not ".c" or ".f", the entry will be used as specified. If the extension is ".c" or ".f", the source file will be compiled and the resultant file will be used. If the extension is blank, a source file (C or Fortran) will be compiled if either the source file is newer than the corresponding object file, or the corresponding object file does not exist; the object file is then added to the list of files to be linked.

Example

The following is an example of a MapLan/VolLan program which uses an external function:

PROGRAM: EXTTESTINPUT

GRID_IN LOCAL OUTPUT

GRID_OUT1, GRID_OUT2START:.cc_begin extern double ufunc ( double in_grid, double* out_grid );.cc_enddowhile GET_FRAME ()

.cc_begin grid_out1 = ufunc ( grid_in, &grid_out2 );.cc_end

call PUT_FRAME ()enddo


end

Future Changes

It is proposed that in a future release of Geolog, this procedure will be simplified. The module which translates MapLan/VolLan code to C will have the ability to process a header file containing the prototypes for external functions. This will eliminate the need to use C mode directly and allow the external function to be called directly from MapLan/VolLan. The above example would then become:

#include <ext_header.h> START:dowhile GET_FRAME ()

log_out1 = ufunc ( grid_in, grid_out2 ); call PUT_FRAME ()enddoend


Expressions

Overview

This section is a guide to expressions which are used to evaluate results in grid expressions, evaluate modules, etc. The functions are described in detail in the section on Functions.

Functions

Logical

Relational

Numeric

AND & AND(a,b) or a & b

NOT ^ \\ NOT(exp) or ^(exp) or \\(exp)

OUTSIDE OUTSIDE(value, min, max)Specifies a range outside min and max for attribute a.

OR OR(a,b) or a | b

RANGE RANGE(value, min, max) Specifies a range between min and max for attribute a.

WILDCARD WILDCARD ( "AA*BB*", "AA" ) Returns true if the second string matches the wildcard given as the first string.

EQ == EQ(a,b) or a == b

GE >= GE(a,b) or a >= b

GT > GT(a,b) or a > b

LE <= LE(a,b) or a <= b

LT < LT(a,b) or a < b

MISS MISS(exp)

NE <> NE(a,b) or a <> b

ABS ABS(a)

ACOS ACOS(a)

ASIN ASIN(a)

ATAN ATAN(a)

ATAN2 ATAN2(a,b)


String

COS COS(a)

DIVIDE / DIVIDE(a,b) or a / b

DROUND DROUND(a)

EXP EXP(a)e**a

IFC IFC(logical,a,b)

INT INT(a)

LIMIT LIMIT(VALUE, MIN, MAX)

GRID GRID(a)base e

GRID10 GRID10(a)base 10

MAX |> MAX(a,b) or a |> b

MIN |< MIN(a,b) or a |< b

MINUS - MINUS(a,b) or a - b

MOD MOD(a,b)

MULTIPLY * MULTIPLY(a,b) or a * b

NINT NINT(a)

NONMISS NONMISS(a,b,c...d) max 10 args

PLUS + PLUS(a,b) or a + b

RAISE ** RAISE(a,n) or a**n

RANDOM RANDOM(min,max)

RANNORMAL RANNORMAL(mean,std_dev)

ROUND ROUND(a)

SIGN SIGN(a,b)

SIN SIN(a)

SQRT SQRT(a)

TAN TAN(a)

UMINUS - UMINUS(a) or -a

CONCAT // CONCAT(str1,str2) str1 // str2

CONVERT CONVERT(format,exp1)

IFCS IFCS(logical,str1,str2)

INDEX INDEX(str1,str2)

LDECODE LDECODE(string)

LOCASE LOCASE(string)

NDECODE NDECODE(string)

NUMSTR NUMSTR(number)

RAINBOW color = RAINBOW ( number, min, max )

STRNUM STRNUM(string)

SUBSTRING SUBSTRING(string,p1,p2)


TABLE TABLE ( "string1", "string2" )

TOKEN TOKEN(string,n)

TRIM TRIM(string)

UPCASE UPCASE(string)


Index

Cconstants

predefined in MapLan/VolLan 19control statements in MapLan/VolLan 20creating modules using MapLan/VolLan 3

Ddevelop MapLan/VolLan modules 3

Eexpressions

guide 62

Lline control in MapLan/VolLan 16logs

analysis algorithms, programming language for 4

MMapLan 3MapLan/VolLan

control statements 20database access management 4expressions guide 62functions, methods of calling 26input variables 14line control 16local variables 14modules, methods of creating 3output variables 15predefined constants 19program structure 13variable names 13

Maplan/VolLanaritmetic and logical operators 17

methodsof calling MapLan/VolLan functions 26of creating MapLan/VolLan modules 3

moduleswriting MapLan/VolLan 3

Pprogram

structure of MapLan/VolLan 13writing in MapLan/VolLan 3


Vvariables

MapLan/VolLan input 14MapLan/VolLan local 14MapLan/VolLan output 15names in MapLan/VolLan 13

VolLan 3

Documents

Paradigm MAPLAN Manual