Introduction

Almost all of the applications within RockWorks may be accessed, sans RockWorks menus, by placing special commands within an ASCII text file.  The target applications for this capability include;

1. Users who wish to automate repetitive tasks.  Consider a user who monitors wells around 100+ gas stations.  Every quarter, new lab analyses are entered into the Borehole Manager.  A series of contour maps, cross-sections, fence-diagrams, solid-models, and volumetric analyses are then performed for each site.  The RCL provides a means for automating these processes and eliminating the drudgery of navigating through the menus.
    
2. Developers of other applications who wish to use RockWorks as a subroutine library.  For example, let's say that a petroleum database software company would like to add contour maps to their product.  They would accomplish this by adding some code to perform the following operations;
    
   • Export data into a RockWorks-compatible format (e.g. ASCII tab-delimited XYZ).
   • Generate an RCL script to define contouring parameters and necessary commands.
   • Launch RockWorks with a command-line parameter that specifies the script-file name.

   The net result would be a contour map on the screen without the normal RockWorks menus.

   Note that it addition to running applications via an RCL script, it is also possible to display the RockWorks sub-menus.  This is often a more suitable way for third-party developers to use the RockWorks capabilities while providing their users with greater flexibility. 

Launching The RCL Processor

There are four ways to launch the RCL processor;

1. Select the Geological Utilities / Util / Compile RCL File option from within RockWorks and enter the name of the RCL script file that is to be processed.  This might be all that User #1 (see above) might ever need.  For User #2, this method is only suitable for de-bugging scripts.
    
2. Create an RCL file and be sure to save the file with an ".rcl" extension.  Then, use the Windows Explorer program to associate the ".rcl" extension with the RockWorks program.  From now on, whenever you double-click on an RCL file within the Windows Explorer program, that file will be processed by the RCL "engine" within RockWorks.
    
3. Use the Windows / Start / Run option to launch RockWorks with a command line parameter that specifies the name of the RCL script file.
   
   Example:  c:\program files\rockware\rw2002.exe "c:\projects\usgs coal\mycommands.rcl"
   
   Note: Command line parameter must be in enclosed by quotation marks to keep Windows from terminating the command parameter if there's a space in the file path.
    
4. Execute (via the Windows "Shell") the RockWorks program from within another program.  By adding an RCL script file name to the command line parameter, RockWorks will attempt to process the associated file with the RCL engine.

Note (again): Command line parameter must be in enclosed by quotation marks to keep Windows from terminating the command parameter if there's a space in the file path.

The RCL (RockWorks Command Language) has been completely redesigned.  The previous RockWorks/2002 scheme, based on XML (eXtensible Markup Language), proved to be far too complex for casual use.  This new version consists of simple commands preceded by optional parameters.  Unlike the previous version, which only covered a few operations, the new RCL includes commands for almost every RockWorks application.

Table of Contents

RCL Script File Format

RCL commands are stored within tab or space-delimited ASCII files.  A typical command file consists of a series of "DEFINE" statements followed by an "EXECUTE" command.  The DEFINE statements define the parameters that are used by the associated EXECUTE command.  For example, let's say that you wanted to import an ASCII file into the RockWorks Geological Utilities datasheet.  You would begin by defining the name of the ASCII file that is to be imported and then you would execute the ASCII2ATD import program.

Example:

: Import ASCII data into Geological Utilities datasheet : and create contour map. DEFINE:  ASCII2ATD INPUT_FILE XYZ.txt EXECUTE: ASCII2ATD : Create contour map. DEFINE:  EZMAP   X_COLUMN     1 DEFINE:  EZMAP   Y_COLUMN     2 DEFINE:  EZMAP   Z_COLUMN     3 DEFINE:  GENERAL 2D_OUTPUT    EZMAP.RKW EXECUTE: EZMAP

All RCL commands must include a colon as the last character.

Examples:

DEFINE ASCII2ATD INPUT_FILE XYZ.txt <--- BAD (No colon after "DEFINE") DEFINE: ASCII2ATD INPUT_FILE XYZ.txt <--- GOOD (Colon after "DEFINE")

Adding Comments

Blank lines and lines that begin with a colon in the first column are ignored by the RCL engine.  Comment lines are therefore preceded by a colon.

Example:

: Import Data Into Datasheet. DEFINE:  ASCII2ATD INPUT_FILE ASCII XYZ.txt DEFINE:  ASCII2ATD INCLUDES_HEADER  False EXECUTE: ASCII2ATD : Create EZ-Map. DEFINE:  EZMAP   X_COLUMN  1 DEFINE:  EZMAP   Y_COLUMN  2 DEFINE:  EZMAP   Z_COLUMN  3 DEFINE:  GENERAL 2D_OUTPUT EZMAP.RKW EXECUTE: EZMAP : Convert EZ-Map To WMF Format. DEFINE:  RP2D_WMF INPUT_FILE  EZMAP.RKW DEFINE:  RP2D_WMF OUTPUT_FILE EZMAP.WMF EXECUTE: RP2D_WMF : Terminate RockWorks. HALT:

Examples

The RockWorks tutorial folder (My Documents/RockWorks2004/Samples) include several sample RCL script files that are designed to be used in conjunction within the other tutorial files.  Please have a look at one of these files in order to get a feel for what an RCL file looks like.

Creating 2-D & 3-D Diagrams

Creating Two-Dimensional Diagrams

Before executing any procedure that creates two-dimensional diagrams, you must specify the name for the output (RKW graphic) file.  Otherwise,  RockWorks will leave the file name in an "undefined" state thereby producing an error .  This is accomplished by setting the GENERAL,2D_OUTPUT variable;

Example:

DEFINE:  2D_STRUCTURE STRAT_UNIT 1 DEFINE:  2D_STRUCTURE GRID_NAME  Structure01.grd DEFINE:  GENERAL      2D_OUTPUT  Structure01.rkw <--- EXECUTE: 2D_STRUCTURE

Creating Three-Dimensional Diagrams

Before executing any procedure that creates three-dimensional diagrams, you must specify the name for the output (XML graphic) file.  Otherwise,  RockWorks will leave the file name in an "undefined" state thereby producing an error .  This is accomplished by setting the GENERAL,3D_OUTPUT variable;

Example:

DEFINE: GENERAL 3D_OUTPUT Stratigraphy Logs.xml <--- EXECUTE: LOG_FENCE

Table of Contents

Enabling & Disabling Diagram Display

Let's say that you want RockWorks to create a two-dimensional diagram but you don't necessarily want the user to see it (e.g. you intend to overlay the diagram later on with another diagram or you want to export the diagram to a bitmap format and then import it into your program).  This can be accomplished by disabling the automatic display within RockPlot/2D via the GENERAL,2D_DISPLAY setting;

Example:

DEFINE: GENERAL 2D_DISPLAY False

In a similar fashion, the automatic display of three-dimensional diagrams may also be supressed viat the GENERAL,3D_DISPLAY setting.

RCL Commands

The following commands describe what may be entered into an RCL script file.

The DATASHEET Command 

• Purpose:

  • Loads a specified ATD (ASCII Tab-Delimited) file into the Geological Utilities datasheet. 

• Parameters:

  • File Name: Name of ATD file that is to be loaded into the Geological Utilities Datasheet.

• Example:

DATASHEET: Hydrochemistry.atd

Table of Contents

The DEFINE Command

• Purpose: 

  • Define a variable setting (something that would normally be accomplished via a menu). 

• Parameters: 

  • Group Name:

  • Item Name:

  • Variable Setting:

• Example:

DEFINE:  IDATA_SOLID TRACK 1 DEFINE:  IDATA_SOLID NEW_MODEL_NAME Benzene.mod DEFINE:  FENCELOC    SHOW_MAP       False DEFINE:  FENCELOC    STYLE          2 DEFINE:  PROFILE     X1             652660 DEFINE:  PROFILE     Y1             5535000 DEFINE:  PROFILE     X2             653600 DEFINE:  PROFILE     Y2             5535980 DEFINE:  GENERAL     2D_OUTPUT      Benzene Profile.rkw EXECUTE: IDATA_PROFILE

• Comments: 

  • The two-part variable name follows the same syntax as the Windows registry and Windows INI files. 

  • The final item is the actual setting that is to be assigned to a variable.

  Table of Contents

The EXECUTE Command

• Purpose:

  • Launches a RockWorks task (e.g. generating a contour map).

• Parameters:

  • Application Name:  Click here to view a list of available commands.

• Example:

EXECUTE: EZMAP

• Comments:

  • Be sure to define all necessary variables (via the DEFINE) command before listing the EXECUTE command.

Table of Contents

The EXIT Command

• Purpose:

  • The EXIT command will terminate the RCL processing and display the main RockWorks menu.

• Parameters:

  • None.

• Example:

EXIT:

• Comments:

  • If you wish to terminate RockWorks without showing the RockWorks menu, use the HALT command instead.

Table of Contents

The HALT Command

• Purpose:

  • The HALT command will terminate the RCL as well as RockWorks.

• Parameters:

  • None.

• Example:

HALT:

• Comments:

  • If you wish to terminate the RCL process but return to the RockWorks menu, use the EXIT command instead.

Table of Contents

The MENU Command

• Purpose:

  • The MENU command is used to display a RockWorks menu. 

• Parameters:

  • Menu Name:

• Example:

MENU: TERNARY

• Comments:

  • If the user selects the OK option from this menu, the program will perform the appropriate operation.  Conversely, if the user select the Cancel option from within this menu, the RCL scripting will continue without returning to the main RockWorks menu.

The PROJECT Command

• Purpose:

  •  The PROJECT command is used to define the folder (aka directory) in which all of the data is stored. 

• Parameters:

  • Folder Name:

• Example:

PROJECT: C:\SITE_27B

• Comments:

  • It is important that the PROJECT command be listed at the top of the

The PROMPT Command

• Purpose:

  • The PROMPT command is used to display a simple message on the screen.

• Parameters:

  • Caption: The message that will be displayed within the dialog box.

• Example:

PROMPT: Gridding completed.  Press OK to contour the grid.

• Comments:

The RESTORE Command

• Purpose:

  • Restore all menu settings to their original default states.

• Parameters: 

  • None.

• Example:

RESTORE:

• Comments:

  • The defaults values are defined within the Menus.txt file that is stored within the \Program Files\RW2004\Tables folder. 

EXECUTE Command Options

The following table lists the available parameters for the EXECUTE command.

Table of Contents

Troubleshooting

Sample RCL Files

During installation, the RockWorks program creates a folder titled "My Documents\RockWorks2004\Samples).  The folder includes the following sample RCL files that designed to be used in conjunction within the other tutorial files.  The sample RCL files are a great place to start learning RCL by example.

• RCL_01.rcl:

  • Restore all variables to default settings.

  • Disable "Cue Card" help messages.

  • Import ASCII data into Geological Utilities datasheet.

  • Create EZ-Map.

  • Terminate script without killing RockWorks.
     

• RCL_02.rcl: 

  • Restore all variables to default settings.

  • Disable "Cue Card" help messages.

  • Create a contour map depicting the structural elevations (derived from downhole data) along the top of the first unit within the stratigraphy table.
     

• RCL_03.rcl:

  • Restore all variables to default settings.

  • Disable "Cue Card" help messages.

  • Suppress automatic 2D diagram display.

  • Import an ASCII file into the RockWorks Geological Utilities datasheet.

  • Create an "EZ-Map" (without displaying it in RockWorks).

  • Export the final map to a WMF file.

  • Terminate RockWorks.

• RCL_04.rcl

  • Under construction.

Table of Contents

Table of Contents

Question: How can I quickly determine a variable name?

Answer: When viewing a sub-menu, right-clicking on a menu item will present a dialog box that lists the group name and the item name.

In the preceding example, we see that the strip log manual depth label interval has a group name of "LOG" and an item name of "DEPTHBAR_INTERVAL".  If we wanted to change this setting within an RCL file, we would enter the following text;

The program processes this line by reading everything up to the first colon ("DEFINE:").  It then reads the group name ("LOG") and the item name ("SCALE").  Next, it looks up the variable type in a table and determines that the following variable is a real number.  Next, the program removes the leading and trailing spaces from the remaining text ("1 000 000,00").  Finally, it uses the Windows regional settings to convert the text to a real number.

The main reason for supporting space delimiters is readability.  Hand-typed, tab-delimited files look ugly.

Table of Contents