Using the RockWare Command Language (RCL)

Run Script

Overview
Menu Options
Step-by-Step Summary
 

Overview

If you have an Advanced license of RockWorks, most of the applications within RockWorks may be accessed, without displaying RockWorks menus, by placing special commands within a text file.  The target applications for this capability include:

• 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.
   
• 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. RockWorks MDB format).
  • 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.

There are several ways to launch the RCL processor:

1. Start RockWorks, click the Run Script button on the main 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 RCL file name 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.

This discussion focuses on the first option listed above, whereby the RCL script is run from the RockWorks Run Script menu.  Please refer to the RCL Technical Information for additional RCL documentation.

! Individual RockWorks menus can also be saved to and loaded from RCL for backup purposes, available to users of all levels of the program.  See RockWorks Menu Settings for details.

! Some of the RCL variables and execute commands have changed since RockWorks16.  If you have scripts written for that version, you'll want to activate the Show Error Summary option, described below.

Menu Options

If you access the RCL using the RockWorks Run Script button, in the upper-right corner of the main program window, you will see the following prompts.

• RCL File: Click here to browse for the text file that lists the RCL commands.
• Ignore Prompts: Insert a check here to ignore any prompts the program may display.
• Show Errors as They are Encountered: Check this if you want the program to display error messages as they are encountered during the running of an RCL script (interrupting the session).
• Show Error Summary on Completion: Check this if you want the program to display a report that lists all of the errors that were encountered after an RCL script file has been processed. The report will be automatically opened within the RockWorks text editor.

Step-by-Step Summary

1. Create your RCL script file in a text editor such as Notepad.
2. Launch RockWorks and open the Project Folder in which the RCL file is saved.
3. Click the Run Script button in the upper-right corner of the main RockWorks program window.
4. Enter the requested menu settings, listed above.
5. Click the Process button to continue.
   
   The program will read the command listing in the RCL file and perform the indicated operations.
    
6. If you've activated Show Errors as They are Encountered, and if an error is encountered, the script execution will be suspended and an error message will be displayed. At this point, you have the option to ignore the error and continue with the script processing or abort (cancel) the RCL processing altogether.
   
   If you've activated Show Error Summary on Completion, and if errors occurred, the program will display a text report on the screen of these errors.
    

See also: RCL Technical Information

RockWare home page