RCL Scripting - Overview

( RockWorks Command Language )

Technical Reference

Contents

See also these additional topics:

 

Introduction

If you have an Advanced license of RockWorks, most of the applications within RockWorks may be accessed without using the RockWorks menus, by placing special commands within a 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:
     

    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. 

Table of Contents

Launching The RCL Processor

There are four ways to launch the RCL processor:

  1. Click the Run Script button at the top of the RockWorks program window, 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. Double-click on the name of the RCL script in the RockWorks Project Manager..
     
  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: 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.

Table of Contents

RCL Script File Format

The RCL (RockWorks Command Language) consists of simple commands followed by optional parameters. RCL commands are stored within tab or space-delimited text files. A typical command file consists of a series of "DEFINE" statements followed by an "EXECUTE" command. The DEFINE statements define the program settings that are used by the associated EXECUTE command. For example, let's say that you wanted to import an ASCII file into the RockWorks Utilities datasheet. You would begin by defining the name of the ASCII file that is to be imported and then you would execute the "TXT_2_RU" import program. If you wanted to create a contour map, you would define the mapping options, and then execute the EZMap program.

Example

: Import ASCII data into RockWorks Utilities datasheet
: and create contour map.

DEFINE:  ASCII2ATD INPUT_FILE XYZ.txt
EXECUTE: TXT_2_RU

: Create contour map.

DEFINE:  MAP   X_COLUMN     1
DEFINE:  MAP   Y_COLUMN     2
DEFINE:  MAP   Z_COLUMN     3
DEFINE:  GENERAL OUTPUT_2D    EZMAP.RW2D
EXECUTE: EZMAP

All RCL commands, such as DEFINE and EXECUTE, 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 space 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: TXT_2_RU

: Create EZ-Map.

DEFINE:  MAP   X_COLUMN  1
DEFINE:  MAP   Y_COLUMN  2
DEFINE:  MAP   Z_COLUMN  3
DEFINE:  GENERAL OUTPUT_2D EZMAP.RW2D
EXECUTE: EZMAP

: Convert EZ-Map To PNG Format.

DEFINE:  RP2D_WMF INPUT_FILE  EZMAP.RW2D
DEFINE:  RP2D_WMF OUTPUT_FILE EZMAP.PNG
EXECUTE: RKW2PNG

: Terminate RockWorks.

HALT:

Number Format

While RockWorks allows users to enter real numbers into the borehole database, the Utilities datasheet, and the program menus using their local number format, the program stores all of its menu settings using a U.S. number format (123,456,789.00). Because RCL is a way to automate the menus, your RCL scripts must list real numbers using the U.S. number format. Sorry for any inconvenience to our international users!

Linking RCL Files

This is one of the coolest features - you can create one or more RCL files which list menu settings, then create one or more separate files which actually run the processes. .

Examples

The RockWorks tutorial folder (My Documents\RockWorks17 Data\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.

Table of Contents

RCL Scripts - Help and Automation

Because RockWorks contains thousands of program settings, knowing which ones to include, and how to format them, in an RCL script can be daunting. The best place to start is by restoring the factory default set of variables (see the RESTORE command) and then listing only the changes in the script. From there, you can refer to the actual RockWorks menus themselves to determine which settings to list in your script. There are some tools that can help you; each tool listed below requires running RockWorks interactively.

Menu Summary: All menus in the program contains a "Show RCL" command which creates a text file that lists all of the settings in the current menu. Just click the Menu button at the top of the window and select Show RCL. RockWorks will write RCL-compatible listings of the menu settings in the current window. You can then copy/paste them directly into your own RCL script. Note that this can be a lengthy list - you should define only those settings that are not already stored as defaults through the running of the program, running of previous scripts, or restoring the program defaults. The Show RCL item also offers the option of displaying only the details of the activated menu items - this can also be a good way to trim down the command listing.

Right-Click Menu Settings: You can right-click in any RockWorks menu to see a pop-up window that lists the "group" name and the "parameter" name for that setting. You would use this information with the RCL DEFINE command.

Example

Consider this very basic script which will generate a lithology model in the Borehole Manager. This script defines only the name for the lithology model file to be created, and the RockPlot3D view. All other lithology model options will be pulled from whatever is currently default.


: Create Lithology Model.

DEFINE:  LITHOMOD NEW_MODEL_NAME   Lithomodel.RwMod
DEFINE:  GENERAL  OUTPUT_3D        Lithomodel.Rw3D
EXECUTE: LITH_MODEL

 

The Lithology Model routine has no fewer than 300 individual settings. However, if the current menu defaults are all suitable, you need only list the settings (or file names) that are different for the RCL run.

! Only the graphic file names and the EXECUTE commands are absolutely required.
!! The graphic file names (shown after the "OUTPUT_3D" setting above) are something you must add yourself to the listings - they are not included automatically using the menu summary techniques described here.

Table of Contents

Where to Start - Step by Step

1. Determine which RockWorks menu option(s) you wish to run in the script. For example, if you want to automate the generation of contour maps of multiple columns in a datasheet, this corresponds to the Utlities | Map | Grid-Based Map option.

2. Access that menu option in the program itself and generate an RCL script for the current menu settings. (See Help and Automation, above, for details.) Unless otherwise appropriate, you can usually select "Activated Menu Items" when prompted - this generates a cleaner listing. You can save this file to disk.

3. Determine which settings in the menu option are unique to your script(s). Since the program always stores last-used settings for each menu option, all you need to list in your RCL script is what's different. For example, for a series of contour maps to be created from the same datasheet, you may only need to change the input Z column and the name of the output grid models and maps being created. (e.g. all of the mapping settings remain the same.)

4. Determine which additional commands you need to add to the menu-generated list.

PROJECT:   C:\WORKFOLDER\SITE_A
DATASHEET: WELL_LOCATIONS.RWDAT

DEFINE:  MENU_RESET  GLOBAL   False
DEFINE:  MENU_RESET  PROJECT  True

EXECUTE: menu_reset

DIMENSIONS: 9800 11600 50 9000 10800 50 1000 2400 50

DEFINE: MAP      X_COLUMN  3 
DEFINE: MAP      Y_COLUMN  4
DEFINE: MAP      Z_COLUMN  5
DEFINE: GRIDMAP  NEW_GRID_NAME  isopach1.rwgrd

DEFINE: GENERAL  OUTPUT_2D  isopach1.rw2d
DEFINE: GENERAL  OUTPUT_3D  3d_surface.rw3d

DEFINE: GENERAL  DISPLAY_2D  True

EXECUTE: GRIDMAP

5. Repeat this process for the next contour map or other program operation.

6. Save the text file.

7. Run the script using the Run Script command, or using the other launch options.

Table of Contents

Troubleshooting

RockWorks Execution Log

RockWorks maintains an execution history file that lists various information that may be useful when trying to troubleshoot problems. We typically use this file when trying to diagnose a user problem. The log file is stored within the program's System folder. The file is named "RockWorks_Log.txt". A new version of this file is created every time the program is launched.

Table of Contents

Sample RCL Files

During installation, the RockWorks program creates a folder titled "My Documents\RockWorks17 Data\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.

Please also refer to the Case Studies section of our website for an RCL tutorial.

Table of Contents

Questions & Answers

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 EZ Map Interpolate Edge Points setting has a group name of "EZMAP" and an item name of "INTERPOLATE_EDGE_POINTS". If we wanted to change this setting within an RCL file, we would enter the following text:

DEFINE:  EZMAP  INTERPOLATE_EDGE_POINTS  True

Table of Contents

Question: Can I display a selected RockWorks menu in order to avoid recreating my own version of the menu?

Answer: Yes. The "MENU:" command will activate a RockWorks tree-style sub-menu without displaying the main RockWorks menu.

Table of Contents

Question: Do I need to define every variable when creating RCL scripts?

Answer: No. You should define only the variables that you want to change. This is important because some applications have over 600 variables. We've tried to make good defaults settings, so that you won't need to change too much stuff. For example, you may need to specify which data column contains the geophysical log that you want to plot within a borehole diagram, but you shouldn't need to specify what color and line-style to use for the curve.

Table of Contents

Question: How can I generate a list of variables for a given menu?

Answer: Just click the Menu item at the top of the options window, and select the Show RCL option. RockWorks will write RCL-compatible listings of the menu settings in the current window. You can then copy/paste them directly into your own RCL script. Note that this can be a lengthy list - you should define only those settings that are not already stored as defaults through the running of the program, running of previous scripts, or restoring the program defaults.

Table of Contents

Question: What type of delimiter is used to separate fields within RCL files?

Answer: RCL files may contain either tabs or spaces as delimiters. The main reason for supporting space delimiters is readability. Hand-typed, tab-delimited files look ugly.

Table of Contents

Question: How do I know where the RockWorks17 program is located so that I can launch it from my own program?

Answer: The program path (i.e. where the program resides) and the user folder (i.e. where the program tables and temporary files are stored) are listed within the Windows registry. This provides a means for developers of other software to know where to look when launching RCL (RockWorks Command Language) scripts and where to store temporary files.

The registry path for the RockWorks program is: HKEY_LOCAL_MACHINE\SOFTWARE\RockWare\RockWorks17\FilePath.

Table of Contents

 Back to Using RCL

RockWare home page