See also
Important Script Definitions
As described in the Using RockWorks Command Scripts topic, program automation offers users great flexibility in creating program output (models, diagrams, reports) without having to navigate the menus. In RockWorks20 there are two ways to automate processing:
Because RockWorks contains thousands of program settings, knowing which ones to include, and how to format them, in a Command Script can be daunting. So, let's start at the most basic - here are the simple steps to take to create a Command Script and run it to generate program output.
If you follow these steps it means you are running a Command Script just like you would run a Playlist. That is certainly fine. However, the true power of scripting is to look under the hood at the contents to streamline the process. Both playlist files (.RwPlaylist) and command script files (.RwCmd) are text in format and are fully editable by you. With caution...
When you add a program to the RockWorks Playlist, what gets saved there is the name of the program and every setting within the program window. Every setting, even if that item is not activated for processing or plotting. The playlist "recording" for a contour map, for example, might be 800 lines long.
So then let's say you want to generate 20 contaminant contour maps, for quarterly samplings over 5 years, then the playlist file would be 16,000 lines long. Yikes! There is no limit to the length of the script, but consider how difficult it would be to make editing changes to a file that long.
The general idea behind command scripts is to list all of the required settings at the beginning of the script, and then, for subsequent programs, just list what changes for those items. In our map example, all program gridding and contour map settings would be listed for Map 1. For Map 2, you might only need to list the sampling date, the name of the output grid model, the title for the map, and the name of the output graphic file. The entirety of the script for Map 2 might be less than 10 lines total, becoming much easier to navigate.
Compare the following examples. The first is an excerpt from a command script for the first contaminant map, created directly from the Playlist. It is comprised of 837 lines (we cut out the middle 700 lines or so).
This next example is the command script for the second contaminant map. It includes comments (discussed below), the required EXECUTE and END commands (highlighted here and discussed below) and only 5 other settings which changed from the first map.
Once you know the simple syntax of what is required, it becomes very easy to create iterations of your RockWorks jobs.
RockWorks Command Scripts consist of simple commands followed by optional parameters which establish the settings for a particular program. The files are text in format, editable by any text editor, such as Windows Notepad.
Execute, Settings, End
A typical Command Script file consists of an "EXECUTE" command which states to the program to be run, followed on the next line(s) by any number of program setting definitions. At the end of the block, for that program, is an "END" command. You can list multiple blocks such as this within the Command Script, for each program action you wish to do.
You don't need to memorize all of the names of the commands or settings. Since you will generate the Command Script from a playlist, everything will be recorded for you. And we mean EVERYTHING - all of the settings for all of the programs, regardless of whether the item is being included in the output. Part of the point of learning about Command Scripts is what you do need, and what you don't.
Here's an example of a really simple program block which will automate the import of a text file into the RockWorks Datasheet. You would begin by defining the name of that import program using "EXECUTE". On the next line you define the name of the text file that is to be imported, and close out on the last line with the "END" command. You can use spaces or tab characters to separate the items within a single line.
: Import text data into RockWorks Datasheet
EXECUTE: 1 TXT2RU_CMD Import Text File
TXT2ATD INPUT_FILE XYZ.txt
END: TXT2RU_CMD
The EXECUTE command is followed by:
EXECUTE 1 TXT2RU_CMD <--- BAD (No colon after "EXECUTE")
EXECUTE: 1 TXT2RU_CMD <--- GOOD (Colon after "EXECUTE")
If you export your script from the Playlist Editor, this will be included automatically. For your reference, the name of most programs can be seen when you hover your mouse over the title bar at the top of the program window. Then just add the "_CMD".
Adding Comments
Blank lines and lines that begin with a colon in the first space are ignored by the Command Script engine. Comment lines are therefore started with a colon. They can be a helpful way to describe the program blocks.
: Import Data Into Datasheet.
EXECUTE: 1 TXT2RU_CMD Import Text File
TXT2ATD INPUT_FILE XYZ.txt
TXT2ATD INCLUDES_HEADER 0
END: TXT2RU_CMD
: Create Triangulation Contour Map.
EXECUTE: 1 TRICON_CMD XYZ to 2D Contours
MAP X_COLUMN 2
MAP Y_COLUMN 3
MAP Z_COLUMN 4
COLORFILL_2D COLORFILL_INCLUDE
TRICON OUTPUT_2D_FILE Triconmap.Rw2D
END: TRICON_CMD
RockWorks Command Scripts - Other Commands
Here are some other handy commands to note for use in a command script. Like the EXECUTE and END commands, they must be followed immediately by a colon (":"), then by a "1" or "0" for enabled, or disabled.
Load a Datasheet
Use this command to load a datasheet for processing. List the name of the RwDat file after the enabled/disabled flag.
DATASHEET: 1 Maps_Surface_Geochemisty.rwdat
Pause the script
Use this command to pause the script and display a message. The user must then click OK to continue. The pause message is entered after the enable/disabled flag ("1" or "0").
PAUSE: 1 Import is Complete
The SQL Command
Use this command to add your own SQL (Structured Query Language) instructions to a script. 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.
In this example the command will enable only the boreholes within a rectangular region.
SQL:
UPDATE [Location] L
SET Enabled = -1
WHERE ([Easting] Between 652700 and 653505) AND ([Northing] Between 5535000 and 5535889)
SQL-END:In this example the command will enable on the boreholes where the Gamma values are greater than or equal to 0.9.
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: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.
Terminate the RockWorks program
Use this command to close RockWorks when the script is complete.
TERMINATE: 1 Terminate RockWorks
Import Borehole Data via the BM_EXCHANGE Command
Use this command in conjunction with an import template to import data from an Excel file or a text file into the borehole database.
: This is an example of the Excel import
EXECUTE: 1 XLS2BM_CMD Import Boreholes from Excel
BM_EXCHANGE TEMPLATE import_template.xml
END: XLS2BM_CMD: This is an example of the text import
EXECUTE: 1 TXT2BM_CMD Import Boreholes from Text
BM_EXCHANGE TEMPLATE import_template.xml
END: TXT2BM_CMDThe XML template can be created in the import menus. Use the menu-based wizards to lay out the field mappings of your Excel or Text files to the RockWorks database fields. Then save these as a "template" which RockWorks saves as an XML file. Once you have the layout set up, they can be modified easily in a text editor for subsequent files that you import via Command Scripts. (See Importing Excel Data).
Other variables you can set for the Excel and text importers:
: This is an example of the Excel import.
: You could substitute "TXT2BM_CMD" for the text import version.
EXECUTE: 1 XLS2BM_CMD Import Boreholes from Excel
BM_EXCHANGE TEMPLATE import_template.xml
: ------------
: overwrite options
BM_EXCHANGE REPLACE_MODE 0
: 0 = Skip, 1 = Create New, 2 = Replace, 3 = Update
: ------------
: multiply depths
BM_EXCHANGE MULTIPLY_DEPTHS 1
: 0 = false, 1 = true
BM_EXCHANGE DEPTH_MULTIPLIER 3.28
: ------------
: does the import file contain column titles, true is assumed
BM_EXCHANGE INCLUDE_COLUMN_TITLES 1
: 0 = false, 1 = true
: ------------
: import file names, if not included in the XML template
: Excel file name
BM_EXCHANGE XLS_FILE_NAME import.xlsx
: Text file name
BM_EXCHANGE REPORT_NAME import.txt
: ------------
END: XLS2BM_CMD
During installation, the RockWorks program creates a folder titled "My Documents\RockWorks Data\Samples". The folder includes the following sample command files that designed to be used in conjunction within the other tutorial files. The sample command scripts are a great place to start learning scripting by example.
RockWorks Execution History
RockWorks maintains an execution history list 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 displayed in the Execution History program tab. Use the Save button to save the file for reference.
Question: Do I need to define every variable when creating command scripts?
Answer: No. You should define only the variables that you want to change. This is important because some applications have over 600 variables. You might start the script by resetting factory defaults. 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.
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.
Question: What type of delimiter is used to separate fields within command script files?
Answer: Command script 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.
Question: How do I know where the RockWorks20 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\RockWorks20\FilePath.
Number Format
While RockWorks allows users to enter real numbers into the borehole database, the 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 the command scripts are a way to automate the menus, they must list real numbers using the U.S. number format.
Similarly, users can enter dates into the RockWorks program using their local date format. But in command scripts, you must use a U.S. date format. Sorry for any inconvenience to our international users!
Linking Command Script Files
This is one of the coolest features - you can create one or more RwCmd files which list menu settings, then create one or more separate files which actually run the processes.
Back to Using RockWorks Command Scripts
