Special RCL Commands

If you have an Advanced license for RockWorks, most of the RockWorks program menus can be automated by listing in your RCL script a series of DEFINE: commands, which define assorted menu settings, followed by an EXECUTE: command, to run the actual menu option. We do not document each and every EXECUTE: command which is available in the program - there are too many! Instead, you can quickly see the DEFINE: parameters and the name of the EXECUTE: command for any RockWorks menu option by selecting the Menu | Show RCL option at the top of that program menu. See Help and Automation for details.

There are, however, some RCL processes which are not activated with a standard EXECUTE: command; these Special RCL Commands are described here.

Contents

• The BACKUP Command
• The DATASHEET Command
• The DEFINE Command
• The DIMENSIONS Command
• The EXECUTE Command
• The EXIT Command
• The HALT Command
• The HIDE Command
• The HTML Commands
• The LOAD_DIMENSIONS Command
• The MENU Command
• The PROJECT Command
• The PROMPT Command
• The SAVE_DIMENSIONS Command
• The SOUND Command
• The SQL Command
  
  

See also these additional topics:

• RCL Scripting - Overview
• Important RCL EXECUTE Commands
• Important RCL DEFINE Commands
• RCL Commands - Imports

The BACKUP Command 

• Purpose:
  • This creates a backup copy of the current Borehole Manager database. It is identical to the File | Backup-Database menu option except that a confirmation dialog is not displayed.
  • It compacts the database and performs a full backup.
     
• Parameters:
  • There are none.
     
• Example:

BACKUP:

Table of Contents

The DATASHEET Command 

• Purpose:
  • Loads a specified .RwDat file into the RockWorks Utilities datasheet. 
     
• Parameters:
  • File Name: Name of .RwDat file that is to be loaded into the Datasheet.
     
• Example:

DATASHEET: Hydrochemistry_01.RwDat

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  Benzene DEFINE:  IDATA_SOLID  NEW_MODEL_NAME  Benzene.RwMod DEFINE:  GENERAL      OUTPUT_2D       Benzene Profile.Rw2D 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.
  • The majority of the DEFINE command parameters can be gleaned using the menu summaries, as described in the Overview section. 
    However, note that there are some important "menuless" DEFINE commands you'll need to use, to create 2D and 3D diagrams, to define section and fence locations, etc.  See Important RCL DEFINE Commands.

  Table of Contents

The DIMENSIONS Command

• Purpose:
  •  The DIMENSIONS command is used to define the parameters that would normally be set within the Output Dimensions pane. 
     
• Parameters:
  • X_MIN
  • X_MAX
  • X_SPACING
  • Y_MIN
  • Y_MAX
  • Y_SPACING
  • Z_MIN
  • Z_MAX
  • Z_SPACING
     
• Example:

DIMENSIONS: 9800 11600 50 9000 10800 50 1000 2400 50

• Comments:
  • It is important that the DIMENSIONS command be listed after the PROJECT command, if any.

Table of Contents

The EXECUTE Command

• Purpose:
  • Launches a RockWorks task (e.g. generating a contour map).
     
• Parameters:
  • Application Name:  See RCL Scripts - Help and Automation for easy methods of determining the EXECUTE command for each menu option.
     
• 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 HIDE Command

• Purpose:
  • The Hide command is used only as a command line parameter, designed to hide the status-completion menu that appears whenever an RCL script is being executed.  It has been added for RCL users who are running RockWorks as an engine within interactive web servers with concurrent, multiple-user sessions.  The Hide command has no parameters.
  • The default setting is for the program to display the status messages, meaning that if the /Hide parameter is omitted, the program will display the status dialog.
     
• Parameters:
  • none
     
• Example:
  • This is a command line parameter only.  It is not meant to be listed in a normal RCL script.
  • Here's how you would list the Hide command in the Rockworks command line:
    C:\Program Files\RockWare\RockWorks17\RockWorks17.exe c:\project_27\xsect01.rcl /hide
  • The /Hide parameter is case insensitive (e.g. "/hide" and "/Hide" are ok).
  • Note: There must be at least one space between the name of the RCL file and the /Hide parameter.
  • See Launching the RCL Processor for more command line details.
     

Table of Contents

The HTML Commands

• Purpose:
  • The HTML set of commands is used to list raster output from RCL processes in an HTML file for easy viewing in a web browser or HTML editing program.  This provides a quick method of ensuring that your script ran properly and the output was generated as expected. 
  • It requires that you export the output images to a raster format (JPG, PNG, etc.) for insertion into the HTML document.  Note that not all raster file types are supported by browsers.
  • There are individual commands for starting and ending the HTML file, and for inserting text and graphics.
     
• HTML_START: file name
  • All HTML listings must begin with this command.
  • Parameters:
    • HTML file name to be created
  • Comments:
    • Required
    • All files that contain an HTML_START command must also contain an HTML_END command, listed after the HTML_START command.
       
• HTML_PIC: file name
  • Used to insert a raster image into the HTML file. 
  • Must be accompanied by a parameter that specifies the name of the graphic file that will be added to the HTML script.
  • Parameters:
    • Name of the image file to be inserted into the script.
  • Comments:
    • Images that are displayed within HTML files will be automatically centered relative to the left and right edges of the display.
    • The image file can be any graphic file (e.g. PNG, JPG, etc.) that is compatible with the target browser.
       
• HTML_TEXT: string
  • Used to insert a text label into the HTML file, typically to label a picture.
  • Must be accompanied by a parameter that defines the text label.
  • Parameters:
    • Text string
  • Comments:
    • Text will be automatically centered relative to the left and right edges of the display.
       
• HTML_END:
  • Used to load the designated file (as defined within the HTML_START command) into your default HTML/web browser such as Microsoft's Internet Explorer.
  • Parameters:
    • none
  • Comments:
    • Required.
       
• Example: The following example shows a simple case in which an HTML file titled "Project 27 Report.htm" will be created. A line of text at the top will say "Project 27 Report". A picture (project_27.jpg) will then be displayed, followed by a caption reading "Project 27 Site Map".
   

• HTML_START: Project 27 Report.html HTML_TEXT:  Project 27 Report HTML_PIC:   project_27.jpg HTML_TEXT:  Project 27 Site Map HTML_END:

  Table of Contents

The LOAD_DIMENSIONS Command

• Purpose:
  • This command emulates the functionality of the "Load Output Dimensions From File" option within the Output Dimensions button. 
  • Note: The designated file must be located within the project folder.
  • You can use the SAVE_DIMENSIONS command if you need to save the current dimensions to a file.
  • See also the DIMENSIONS command if you simply want to enter the dimensions values.
     
• Parameters: 
  • The LOAD_DIMENSIONS command has a single parameter, being the name of the text file that contains the new project dimensions.
     
• Example:

• LOAD_DIMENSIONS:  Site_1_dimensions.txt

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 interactively clicks the Process button at the bottom of 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.

  Table of Contents

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 file.

Table of Contents

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.

Table of Contents

The SAVE_DIMENSIONS Command

• Purpose:
  • This command emulates the functionality of the "Save Output Dimensions to File" option within the Ouptut Dimensions button. 
  • The file will be saved within the current project folder.
  • You can use the corresponding LOAD_DIMENSIONS command if you need to load existing, saved dimensions values.
     
• Parameters: 
  • The SAVE_DIMENSIONS command has a single parameter, being the name of the text file in which the current project dimensions will be saved.
     
• Example:

• SAVE_DIMENSIONS:  Site_1_dimensions.txt

Table of Contents

The SOUND Command

• Purpose:
  • This command is used to create notification sounds to let you know when a script has been completely processed - very handy for long scripts!
  • It may also be inserted at various points within a script to let you know how the program is progressing.
     
• Parameters: 
  • The SOUND command has a single parameter, being the name of the sound to be played. There are three sounds available:
    • BASS_NOTE_01 - A single, very-short, bass note.
      
    • CAR_HORN_01 - A very obnoixous sound sure to get your attention, as well as that of everyone else in your office.
    • DROP_CHORD_01 - A pleasant electric piano "drop-chord".
       
• Example:

• SOUND: CAR_HORN_01

Table of Contents

The SQL Command

• Purpose:
  • To allow users to add their own SQL (Structured Query Language) instructions to an RCL script.
     
• Parameters: 
  • An SQL block begins with the "SQL:" command, followed by any number of lines that contain the SQL code. The SQL block is terminated by an "SQL-END:" command.
     
• Example:

SQL: UPDATE [Location] L SET Enabled = -1 WHERE ([Easting] Between 652700 and 653505) AND ([Northing] Between 5535000 and 5535889) SQL-END:

Explanation: The preceding commands will enable only the boreholes within a rectangular region.

• Example:

• SQL: UPDATE PointType INNER JOIN (Location INNER JOIN Point ON Location.BhId = Point.BhId ) ON PointType.PointTypeId = Point.PointTypeId SET Location.Enabled = -1 WHERE (((PointTypeName)="Gamma") AND ((Point.Value)>=0.9)) SQL-END:

  Explanation: The preceding commands will enable on the boreholes where the Gamma values are greater than or equal to 0.9.

• Comments:
  • SQL commands may be used to do anything to the database, including the deletion of the entire database, corruption of the linked records, etc.
  • We strongly recommend using the BACKUP command before implementing an SQL command.
  • Just like fire, the SQL command is very dangerous but also very useful.  Be sure you know what you are doing.

Table of Contents

Important EXECUTE: Commands

Restoring Menu Settings

• Purpose:
  • Restore all current project menu settings to their original default states. This can be a handy way to start a script with a known configuration, and then simply make incremental changes from there. We include this command in most of our sample scripts.
    
    You can also restore global settings, however this requires a program close and restart.
     
• Corresponding menu option: 
  • Preferences | Reset Menu Settings.
    
    
• Parameters: 
  • You can reset either the Global Settings or the Project Settings, or both, to the initial "factory" versions installed with RockWorks. Note that resetting the Global settings requires a program close and restart, which is not very helpful when you're running a script.
     
• Example:

DEFINE: MENU_RESET GLOBAL  False DEFINE: MENU_RESET PROJECT True EXECUTE: menu_reset

• Comments:
  • The factory defaults for all of the project-specific menu settings are stored in a file "menus.txt" which is stored within the \Program Files\RockWare\RockWorks17\Tables folder. 
  • The Global Settings, which will affect all of your projects, are stored in the RockWorks System folder.
  • The Project Settings are stored in "menus.ini" in the current project folder's "\System" sub-folder.

Table of Contents

Linking RCL Files

• Purpose:
  • Run an RCL script from within another script.
    For example, you could create one RCL file that contains only striplog DEFINE: commands, another which contains only cross-section settings, and another which lists the actual cross section EXECUTE commands for your series of cross section diagrams. You can create a single "master" script which calls these component RCL files.
     
• Corresponding menu option: 
  • Run Script
    
    
• Parameters: 
  • RCL file name
  • optional prompt and error settings
     
• Example:

DEFINE: RCL   FILE_NAME   striplog_settings.rcl DEFINE: RCL   IGNORE_PROMPTS      False DEFINE: RCL   SHOW_ERRORS         False DEFINE: RCL   SHOW_ERROR_SUMMARY  True EXECUTE: rcl DEFINE: RCL   FILE_NAME   section_settings.rcl EXECUTE: rcl DEFINE: RCL   FILE_NAME   create_sections.rcl EXECUTE: rcl

• Comments:
  • See the case study and video on the RockWare website for examples of how this works.

Table of Contents

Saving Datasheet Files

• Purpose:
  • Save the current datasheet in the project folder, under a name with an ".RwDat" file name extension.
     
• Corresponding menu option: 
  • File | Save in the RockWorks Utilities
    
    
• Parameters: 
  • RwDat file name
     
• Example:

DEFINE: GENERAL  ATD_FILE_NAME  myfile.rwdat EXECUTE: ru_save

Table of Contents

Scanning Boreholes

• Purpose:
  • Establishes the project dimensions by scanning all of the boreholes or scanning the enabled boreholes. 
    
    
• Corresponding menu option:
  • Scan Boreholes button at the bottom of the program window.
     
• Parameters: 
  • Define whether all boreholes or enabled holes only are to be scanned.
  • Other settings define how the dimensions and node spacing are to be determined.
     
• Examples:

DEFINE: SCAN_LOGS SCAN_ALL_LOGS True EXECUTE: scan_boreholes

• Comments:
  • See also the DIMENSIONS command.

Table of Contents

 Back to RCL Overview

RockWare home page