Book of Scripts. Volume 1

 A Collection of Scripts for use with HyperChem.

By Ronald Starkey

The objective of this Book of Scripts is to provide you with several script schemes and working scripts. Many of the scripts can be used as is, but it is hoped that you will be motivated to modify these scripts to meet you individual needs. The focus of the collection is lecture presentation scripts. HyperChem is very useful as a lecture presentation tool and many of the scripts are designed to augment this function. This ‘book’ has much in common with a cookbook. It is a collection of script recipes and recipe ideas. After some experience ‘cooking’ scripts you will want to modify a script recipe to your particular tastes. Also, like a cookbook, you will not have to read the book from start to finish. Just use the sections that you have an interest in. There will be some scripts that you do not need, or do not have a taste for. Others you may find will become a staple of your script diet.

This BookOfScripts covers both HCL (HyperChem Command Language) and TCL (Tool Command Language) scripts. It is not the intention of this book to repeat the material covering scripting that is already in the HyperChem manuals. The HyperChem manuals cover HCL scripts quite extensively. In particular you may find the Scripts and DDE chapter in the HyperChem Reference Manual helpful for writing HCL scripts. The HyperChem Chemist’s Developer Kit Manual has a useful discussion of both HCL and TCL scripts. HCL script commands can easily be accessed in the Scripts & DDE section of the HyperChem Help system: Help / Script & DDE.

It is assumed that you have some experience with HCL scripts and want to expand the scope of your use of scripts. The HCL scripts in this book are designed to show you some of the power of HCL scripting, and perhaps give you new ideas that can be used in your scripts. Some are fully developed working HCL scripts, called demos in the book, that have been used in either a lecture format by faculty teaching Organic Chemistry, or by individual students.

The book also covers TCL scripts, and uses the TK (ToolKit) extensions of TCL to display graphics windows. Most of the TCL scripts included in this collection are subroutine script utilities that are designed to be called from a HCL script. There is less need for you to modify the TCL scripts in the BookOfScripts script collection. They are more general utility scripts that are designed so that the specific operation of them can be controlled by the calling HCL script. This control is exerted by the values of the parameters that are passed from the HCL script to the TCL subroutine script. As a consequence of the general utility nature of the TCL scripts, there is little discussion of TCL script writing in this book. The operation of the TCL scripts is described, but there is not a through discussion of the TCL language. There are many good references, see the HyperChem manuals, that cover the TCL language in great detail. Only one of the TCL script systems, gif_anim.tcl, which can be used to produce animations in a TK graphics window, will require you to edit (or write) a TCL script.

Although most all the scripts in the book are designed primarily for use in an instructional lecture/presentation setting, several of the script systems lend themselves individual student use. Most of the examples used in the scripts are organic structures and have been used in Organic Chemistry instruction. A few of the scripts in the collection are inorganic and biochemical structure based. It is hoped that the organic structure examples can serve a starting point for extensions to additional inorganic or biochemistry applications.

The collection of scripts contains both utility and demonstration scripts. There are a number of scripts that are designed to just show what a particular scripting technique can do and how you can make a script do it. For example, the saving and restoring of HyperChem state variables using a HCL script is illustrated by simple scripts showing the technique.

HyperChem release requirements

The oldest release of HyperChem that is supported by these scripts is HyperChem 5.0. Most of the scripts in the collection will run on any release of HyperChem 5.0 or later. A few of the scripts require HyperChem 7 (or later). HyperChem 7 is required for scripts that utilize annotation features. Release 7 is the first that has script control of annotations. Scripts featuring annotations are all found in the BookOfScripts\hcl\Annotate\ and BookOfScripts\hcl-tcl\Annotate\ folders. The text file, in the Rich Text Format (.rtf), found in each folder will indicate which release of HyperChem is suitable for running the scripts in that folder. This Rich Text Format text file can be opened by any word processor. WordPad is a suitable word processor for this purpose.

Organization

If there is a theme in this collection of scripts it is the use of sub routine scripts to perform tasks that are repeated frequently or would require a considerable amount of code to execute, in particular the use of TCL scripts that are called from HCL scripts. Many of the HCL scripts in the BookOfScripts\hcl folder use HCL subroutine scripts to perform molecular rotations or bond rotations. All of the scripts in the BookOfScripts\hcl-tcl folder are designed as HCL scripts that call TCL (tool command language) subroutine scripts. Examples of the function of these TCL subroutine scripts include molecular view rotations, and bond rotations. The other subroutine scripts that are called from a HCL script are TCL/TK scripts. These are TCL scripts that take advantage of TK (toolkit) graphics capabilities. Examples of the TCL/TK subroutine scripts function include the display of graphics images (gif files), graphics animations, dialog boxes for Yes/No queries, and bond rotation dialog boxes. See the HyperChem Chemist’s Developer Kit Manual for more information on TCL scripts

HCL and TCL scripts discussion

Script file name extensions.

HCL scripts will have filenames xxxx.scr and TCL scripts yyyy.tcl.

Remark statements.

HCL scripts use ‘;’ (the semicolon) as the first character in a line to indicate a remark line. Whatever follows a ‘;’ will not be executed by the script.

TCL scripts use ‘#’ (the pound sign) as the first character to indicate a remark. Everything listed on a line after the # is not executed by the TCL script.

Variables in HCL and TCL.

All variables in TCL are strings. To use a numeric value of the string you must evaluate the TCL string by using either ‘$variable’ or ‘exp string’.

Structure.

HCL is a linear command list, with no control structure. A HCL script is a text file that is read and executed line by line in order of the line listing.

Comparison of HCL and TCL.

TCL has control features such as while-loops and if-statements that are not available in HCL. This makes TCL a powerful tool that can be used in conjunction with HCL scripts. The TCL interpreter, included in HyperChem 5.0 and later, has the TK (Tool Kit) extension that allows the display of graphics, such as dialog box windows, on the screen. See the HyperChem Chemist’s Developer Kit Manual for more information on HCL and TCL/TK scripts. TCL is a case-sensitive language while HCL commands are not case-sensitive.

HCL in TCL.

All HCL commands are embedded in TCL and any operation that can be performed in a HCL script can be done in a TCL script. The two TCL commands that allow HCL command execution are hcExec and hcQuery. The statement hcExec will execute a specified HCL command in a TCL script. For example a TCL script may contain this line to instruct HyperChem to perform a geometry optimization:

hcExec “do-optimization”

The TCL statement hcQuery will query HyperChem for a variable. If a TCL script has the following line, the value of x will be set to ‘black’ if the HyperChem window color is black: TCL

set x [hcQuery window-color]

Why call TCL from HCL?

The emphasis on using TCL scripts as support subroutine scripts (off-spring scripts) for HCL scripts is a feature of the BookOfScripts. The philosophy behind this approach is an attempt to combine the power of TCL scripts with the ease of construction of HCL scripts. In particular, if the HCL scripts are composed using the HyperChem Script Editor. The Script Editor facilitates script writing because it allows a script author to paste commands into a script from a list of available commands, and to execute a script line-by-line. Both these features make debugging a HCL script much easier. The Script Editor is included with HyperChem 6 and HyperChem 7, and is available for HyperChem 5.x with the Chem Plus add-in.

Passing parameters from HCL to TCL.

The subroutine script design of most of the TCL scripts in this collection requires that parameters be passed from the controlling (parent) HCL script to the offspring TCL script to provide specific instructions to the TCL script. This is accomplished by using variables known as HyperChem State Variables or HSVs. In many examples used in this script collection the user defined variables are used instead of the standard HSVs used by HyperChem. An example of a standard HSV is window-color. A HCL script could request the value of window-color (window-color ?) to obtain the value of the window-color HSV. Or, a HCL script could define a value for the HSV window-color (window-color blue). If a non-standard HSV is used it first must be declared and then usually defined. For example lets use the variable name ‘title’, which is not a standard HSV name. We would first have to be declared and then defined as shown in the next two lines:

    declare-string title

    title = “BookOfScripts”

After this declaration and definition we can now use it as a normal HyperChem HSV.

If a HCL script uses the statement

    title ?

it is a query for the value and the value returned will be ‘BookOfScripts’.

More importantly for the TCL subroutine script applications we can now use the value of the HSV in a TCL script. For example if a TCL script had the statement

    set t [hcQuery title]

we can now use the value of ‘t’ (which was set to be BookOfScripts) in that TCL script.  See the HyperChem Reference Manual for more details on HSVs.

Calling a TCL script from a HCL script

Just as a HCL script can call another HCL script, HCL scripts can call TCL scripts. The command for calling a HCL script is:

read-script filename.scr

To call a TCL script form a HCL script use the command:

read-tcl-script  filename.tcl

After the subroutine script (the called script or off-spring script) is done, control is returned to the calling script (the parent HCL or TCL script) and execution of the parent script is resume.

Using the scripts in the BookOfScripts.

Install the contents of the BookOfScripts to a sub folder of HyperChem named  BookOfScripts. For example if you are using HyperChem 7, you could copy all the folders, and all the files of each folder, to the HyperChem folder: Hyper7\BookOfScripts.

To use the scripts in the BooksOfScripts1\Chem-tcl folder you will have to perform an additional step. The files in the BookOfScripts\Chem-tcl folder will have to be copied to the HyperChem program folder. With HyperChem 7 this would be c:\Hyper7\program\. See the readme.rft file in the BookOfScripts\Chem-tcl folder for more information.

Scripts in the BookOfScripts are divided into four major categories:

The HCL, HCL-TCL, and TCL folders each have subfolders that group the scripts by utility. Each of these subfolders has a documentation file in the Rich Text Format (.rtf) that provides details on the use and operation of the scripts in the subfolder. These documentation files can be opened by most word processors, such as MS WordPad. In addition, each script (either HCL or TCL) has many remark lines that provide some insight into the operation of that particular script.

Opening HCL and TCL scripts.

Scripts are usually opened from the HyperChem menu bar ‘Script’ selection. The sequence is Script / Open script… and selection of the folder containing the script file, and script file type (HyperChem Command Language or Tool Command Language) from the Run Script dialog window. HCL scripts have the filename extension ‘*.scr’ and TCL scripts use ‘*.tcl’ for the filename extension.

The collection of scripts works best if a particular script and the associated files needed by that script are all in the same folder on the computers hard drive. For example if a HCL script has a command to open a hin file, or call a TCL subroutine script, that hin file or TCL script should be in the same folder as the HCL script. A HCL command referring to stored files defaults to the folder that contains the running HCL script. If you wish to place associated files in other folders you will have specify in the HCL script the folder where that files is located.

Script directory

A complete listing of the scripts, in the BookOfScripts follows. A brief summary of the function of each script and its location in the BookOfScripts is also provided.

Listing A.      Arranged by folder where script is stored.

The scripts are divided into four categories by file type.

1.  Chem-tcl

The chem.tcl file system the choice of HSVs (executed by the chem.scr script) when the HyperChem program is opened. The HyperChem manuals discuss the use of chem.scr to customize HyperChem.  If a HCL script named chem.scr is located in the HyperChem  \program\  folder that script will be executed when the HyperChem program is opened. The chem.tcl system, if installed in the \program\ folder, allows for the selection of alternative chem.scr HCL scripts (either chem1.scr or chem2.scr) when HyperChem is opened. For information on how to use the chem.tcl system see the readme.rtf file found in the BookOfScripts\Chem-tcl\ folder.

2.  HCL scripts

HCL scripts that serve as demos of what HCL scripts can do, or utilities that can be used to perform routine tasks in a semi-automated fashion. These scripts can be found in subfolders of  the BookOfScritps1\hcl\ folder.

3.  HCL-TCL scripts

Script operation that is controlled by a HCL script, but calls TCL scripts to perform some operations or display TK windows. These scripts are in sub folders of BookOfScritps1\hcl-tcl\.

4.  TCL scripts

Listing B.    Scripts Arranged by function.

The scripts are divided into categories by script function.

 The scripts are divided into three categories: 1. Lecture presentation scripts, 2. Example scripts, and  3. Utility scripts. The location of the script in the BookOfScripts is listed after the brief description of the script.

 1.  Lecture Presentation Scripts.

Scripts for presentations.

2.  Example Scripts. 

Illustrates script techniques.