Insight II




12       Biosym Command Language


Introduction

The Biosym Command Language (BCL) is a full featured scripting language that allows you to add your own commands, menus, and modules to the Insight II program.

BCL macros range from simple collections of existing Insight II commands to complex programs that perform file I/O, Insight II data manipulation, and powerful arithmetic computations. For example, you might want to create a new command that gets a molecule from a file, colors it, and visualizes it in a ball-and-stick representation all in one step. Or you may want to gather data from a group of molecules and generate a table. New commands created with BCL can then be added to existing menus, new menus, or entirely new modules.

Creating Commands

To create a new command with a BCL macro, you create a text file, or start with an existing log file, and describe the new command's name, parameters, parameter block appearance, processing, and output. The BCL macro is then loaded using the File/Source_File command and can be added to a menu with the Custom/Add_To_Pulldown command. Your new command can now be used in the same way as all other Insight II commands.

Creating Pulldown Menus and Modules

To create new menus and modules, simply add Define_Module and Define_Menu statements to the source file. New menus can be added to existing modules, or to new modules, allowing you to create an entire user interface with BCL.

BCL vs. Open Interface

Open Interface (OI) is a Biosym product providing C library functions that let you do everything BCL can do and more. OI programs run faster than BCL macros but are typically larger and more difficult to write and debug. BCL is often used to prototype commands which are then recreated with OI. To learn more about the Open Interface program, consult that program's manual or speak with your Biosym sales representative.

How to Use this Guide

This chapter is divided into three sections. The first section is a series of tutorials to introduce BCL programming. The second section is an overview of the language, broken down by topics, such as File I/O, and Parameter Blocks. The third section is a reference. We recommend that you start with the tutorials, then read the overview, turning to the reference as needed to get complete descriptions.

Examples

More than one hundred BCL macros can be found in the $BIOSYM/gifts directory.

Font Conventions of this Guide


BCL Tutorial

The following tutorials walk you through the creation of BCL macros. The first tutorial, "hello.bcl" starts from scratch, giving step by step instructions for creating, loading, running, and modifying a simple macro. The second tutorial, "myget.bcl" starts with an Insight II log file, then adds parameters. The third tutorial has you enter and run a working example program that shows many of the features of BCL.

Note: If you are unfamiliar with Insight II commands such as Color Molecule, refer to the Viewer tutorials in chapter 2 first.

Tutorial 1: hello.bcl

Create and iteratively modify a simple BCL macro.

1. Create the text file

Start a text editor, such as vi or emacs. Enter the text below and save the file as hello.bcl

Define_Macro hello

Print "Hello BCL World!"

End_Macro

2. Start the Insight II program

Note: we recommend invoking Insight from a separate window, so that you can continue editing your macro and iteratively test it.

3. Load your macro

Select the File/Source_File command.

Type the name of your macro, hello.bcl, and select Execute.

4. Invoke your macro

Move your cursor to the command line and enter the name of the macro: hello

The string "Hello BCL World" is printed to the info area and textport.

If any error messages appeared in the info area during steps 3 or 4, try to fix them during step 5.

5. Fix/Enhance your macro

Edit the file so it appears as shown below, and save it under the same name.

Define_Macro hello sstring Person
Print "Hello to " $Person "from BCL!"
End_Macro

You have added a parameter, called Person of the type sstring. This parameter type holds up to 19 characters. The print statement now outputs whatever name you enter.

6. Reload your macro

Since you modified your macro, you need to reload it. Repeat step 3.

Since you will probably be repeating this step several times, you may wish to use abbreviations (type source hello.bcl) and use history (type !s). Also, you may find it more convenient to work in the textport.

7. Re-invoke your command

Enter hello. At the prompt for Person [no default], enter your name.

8. Add your command to the menu

Select the Custom/Add_To_Pulldown command. Enter hello at the Macro Name prompt, accept the default Pulldown Name, and Execute.

For convenience, we recommend adding this command to the BCL source file. For example, the last line of the hello.bcl file might be:

Add_To_Pulldown hello Custom

The macro is then automatically added to the menu whenever the macro is loaded.

9. Invoke your command from the menu

Select your new Custom/hello command, fill in the name, and Execute.

10. Iterate

Use a text editor to add additional parameters and print statements. Reload and re-invoke your macro from the command line and menu.

Tutorial 2: myget.bcl

Use an Insight II log file to create a simple BCL macro.

1. Invoke Insight II

2. Get a molecule of your choice

3. Color the molecule

Enter the colat command or use the Molecule/Color command to color the molecule.

4. Label the molecule

Use the Molecule/Label command to add labels to the molecule.

5. Quit Insight II

6. Copy the log file, naming the new file myget.bcl

At the shell prompt this can be done as:

cp insight.log myget.bcl

7. Edit the new file

Note that the file contains the commands you invoked in Insight II, preceded by m:, as well as some comments, preceded by pound signs (#). The m: MUST BE DELETED. The comments can be deleted or ignored.

8. Convert to BCL

At the top of the file, add the line Define_Macro myGet. At the bottom, add the line End_Macro followed by the line Add_To_Pulldown myGet Molecule.

9. Invoke Insight II again.

Note that you could have done this entire process without quitting Insight II. This can be accomplished by copying WBLOGFILE, then deleting previous commands from the top of the log file which you did not want.

10. Load the macro

11. Invoke your new File/myGet

Since your new command has no parameters, the command is executed immediately. If an error occurs, try to fix it in the next step.

12. Add parameters

Change the line "Define_Macro myGet" as shown below.

Define_Macro myGet \

Lstring Filename \

Ident Objname

Note that the backslash (\) is the line continuation character.

13. Implement parameters

In the Get Molecule command line, replace the actual filename with $Filename and the actual object name with $objname. The line should appear similar to what is shown below.

Get Molecule PDB System $Filename $Objname

14. Reload and re-invoke

You should now be able to enter a filename and an object name, and have the molecule come up and be automatically colored and labeled.

15. Iterate

Add additional parameters for colors and labels as desired.

Tutorial 3: Working Example

Enter the following program. Note the comment style, indention style, use of spacing and blank lines, and the use of parentheses, braces, and brackets. Iteratively run, debug, and enhance the macro as you see fit.

This macro uses features that are discussed in the Overview section and described in detailed in the Reference section. Note that we have provided this macro as $BIOSYM/gifts/insight/BCL/trace_torsions.bcl.

# Trace_Torsions
# Graph torsion angles along backbone by residue number

Define_Macro Trace_Torsions \
Ident Molecule_Name \
Int Starting_Residue \
Int Ending_Residue

# local variables
Float torsion_value # torsion angle value
Lstring fn # filename
Int presidue # previous residue index
Int cresidue # current residue index
Int nresidue # next residue index
Int nnresidue # next next residue index
Ident CA_presidue, CA_cresidue, \
CA_nresidue, CA_nnresidue # residue names

# initialization
presidue = $Starting_Residue - 1
cresidue = $Starting_Residue
nresidue = $Starting_Residue + 1
nnresidue = $Starting_Residue + 2
fn = trace_torsions.tbl

# add picking
Set_Param_Pick Molecule_Name MOLECULE_NAME

# check input parameters
If ( ($Starting_Residue <= 1) || ($Ending_Residue <= 1) )

Print "Residue number must be greater than 1"
Return
End

If ( ($Starting_Residue > $Ending_Residue) || \
( ($Ending_Residue - $Starting_Residue) < 3) )

Print "Ending_Residue number should be greater than"
Print "Starting_Residue number by at least three."
Return
End

Continued...

# remove trace_torsions file, if present
Bcl_Unix ("/bin/rm -f " // $fn)

# write table description information to file
Write $fn "INSIGHTII V9.5.0 "
Write $fn "DATE: Tue Jan 3 00:00:00 1995\n#\n"
Write $fn "TITLE: Residue Number\n"
Write $fn "MEASUREMENT TYPE: Dimensionless\n"
Write $fn "UNITS OF MEASUREMENT: <no units>\n"
Write $fn "FUNCTION: Residue Number\n#\n"
Write $fn "TITLE: Trace_torsions\n"
Write $fn "MEASUREMENT TYPE: Angle\n"
Write $fn "UNITS OF MEASUREMENT: degrees\n"
Write $fn "FUNCTION: Trace_torsions\n#\n#\n"

# main loop for measuring torsions in protein trace
While ($nresidue < ($Ending_Residue + 3))

CA_presidue = $Molecule_Name//":"//$presidue//":CA"
CA_cresidue = $Molecule_Name//":"//$cresidue//":CA"
CA_nresidue = $Molecule_Name//":"//$nresidue//":CA"
CA_nnresidue = $Molecule_Name//":"//$nnresidue//":CA"


$torsion_value = \
{Dihedral -monitor $CA_nnresidue $CA_nresidue \
$CA_cresidue $CA_presidue}

Write $fn "%5d %11.6f\n" $cresidue $torsion_value

Dihedral Monitor Add -180.00 180.00 green \
$CA_nnresidue $CA_nresidue $CA_cresidue $CA_presidue

presidue = $cresidue
cresidue = $nresidue
nresidue = $nnresidue
nnresidue = $nnresidue + 1

End # end of while loop

# close trace_torsions.tbl file
Close $fn

# load analysis module and draw graph from file
Analysis
Get Graph $fn New_Graph "Residue Number" Trace_torsions None

End_Macro
Add_To_Pulldown Trace_Torsions User


BCL Overview

This section starts with general rules for the BCL language. Functionality is then covered by topic. If you know what you want to do, but not which statements to use, start here. If you know the statement but are not sure of the proper syntax, see the BCL Reference section.

BCL Rules

Parameters

Parameters are arguments to your macro. If your macro is invoked from the command line, the user may type the values for the parameter on the line. If you do not supply arguments, Insight II automatically prompts you with the parameter name. If your macro is invoked from a menu, the parameters appear as widgets in a parameter block window, just like any other Insight II command, including Execute and Cancel buttons.

Parameters can have defaults, value-aids, and picking functions. BCL statements are also available to format the parameter block generated when the macro is invoked from the menu. These are covered later in this section.

It is possible to share any Insight II command parameter with a macro. Thus, Insight II parameter defaults can be inherited by the macro command parameter. See Table 12-5. Insight II Parameter Names on page 10-263 for a list of parameters which are already used in Insight II.

Since parameters are shared with Insight II, you must be careful in choosing parameter names so that they do not unintentionally coincide with existing parameters.

Types

A parameter's type determines what kind of data it can hold and how large it can be. Data validation is built-in, so that if you or another user of your macro enters letters in an Int parameter, the bell rings, a warning message appears and the parameter is cleared. Several additional (Short_) data types are available. These are covered later in this section.

Definition

All parameters must be defined in the Define_Macro statement. Enumers and Llists are filled within the body of the macro with the Def_Enum and Def_List statements. The example BCL code creates the parameter block shown.

Define_Macro All_Parameters \
Int Int_param \
Float Float_param \
Sstring Sstring_param \
Lstring Lstring_param \
Vlstring Vlstring_param \
Logical Logical_param \
Enumer Enumer_param \
Llist Llist_param \
Ident Ident_param \
Coord Coord_param

Def_Enum Enumer_param enum1
Def_Enum Enumer_param enum2
Def_Enum Enumer_param enum3

Def_List Llist_param list1
Def_List Llist_param list2
Def_List Llist_param list3
Def_List Llist_param list4
Size_list Llist_param 3

Variables

Variables temporarily hold data within a macro. Variables should be defined before they are used, otherwise the variable implicitly defined the first time it is used. We recommend defining all variables at the top of the macro, immediately following the Define_Macro statement and its parameter definitions. Macro commands do not share variables with other macros or commands.

Types

Definition

To define a variable, start a statement with a variable type, followed by a comma-separated list of variable names. For example:

Int i, j

Lstring Filename

Arrays
Arrays of variables may be defined as follows:

Sstring AtomList[50]

Pointers
Pointers to variables may be defined. For example:

Sstring *AtomList

These are used with the fetch functions and accessed like arrays.

Accessing Parameters and Variables

The contents of parameters and variables are accessed with a dollar sign. For example the following statement prints out the contents of the FileName parameter:

print $FileName

And the variable i could be printed as

print $i

Coords

You can access coords by x, y, and z values or as a unit.

Coord point

point = 3.0, 2.0, 5.0
Print $point # print x, y, and z
Print $point.x # print only x

Arrays and Pointers

Arrays and pointers are accessed by specifying an index into the array. To print the contents of the first cell of the AtomList array:


print $AtomList[1]

Note that array indexing starts at 1.

Constants

Constants are numbers or strings to be used literally as values. The number -12 is a constant, as is the string "Hello World".

String constants should be enclosed in double quotes.

Constants may be used in expressions and statements as needed. Constants may also be given symbolic names. See the Constant command in the BCL Reference.

Operators

BCL has three types of operators: numerical, string, and logical. See Table 12-2. Operator Precedence on page 10-258 for a complete list and description of operators and their precedence. See Table 12-3. Intrinsic Functions on page 10-260 for a complete list of built-in functions, such as sin() and random().

Expressions

Expressions are collections of parameters, variables, constants, functions, and operators. Expressions can be used in assignment statements and within commands statements. Some examples of expressions include:


$x + 7	        			(simple arithmetic expression) 


$filename // ".pdb"				(string concatenate expression) 


cos ($x) <= cos ($y)				(logical expression)

In Assignment Statements

An assignment statement begins with a variable name, followed by the equal sign (=), then an expression. Some examples of assignment statements include:


first_case = $MoleculeName // ":*"


i = $i + 1

Note that in BCL, variable names are preceded by a $ except on the left hand side of an expression.

In Command Statements

Whenever an expression is embedded in a command, it must be surrounded by parentheses. For example:


get mol pdb ($MoleculeName//".brk") $ObjName

Functions

You can make your own BCL macros that act as functions, which in turn can return values to other macros. The function macros can appear in the same file or separate files, but the function macros must be loaded before they are referenced.

Defining Functions

A function macro has an additional first argument in the Define_Macro statement which specifies what type of value is returned. Functions also have Return statements which actually return a value. Otherwise functions look like any other macro. The example shown below returns a coordinate when called.

Define_Macro Coord Cen_of_Mol Sstring Mol_name
Coord cur_com
...
Return $cur_com
End_Macro

Possible return types include Int, Float, Coord, Sstring, Lstring, Vlstring, and Ident.

Accessing Functions

To access a function written in BCL, enclose the function name and its arguments in curly braces. For example:

mol_cent = {Cen_of_Mol $MoleculeSpec}

Note: some Insight II commands return values and can be used in the same manner.

dist_2 = {Distance abp:132:ca abp:132:c} * 2
angle_value = {Angle abp:132:ca abp:132:c abp:132:o}
center = {XYZ}

See Table 12-4. Insight II Commands that Return a Value on page 10-261 for a complete list of Insight II commands that return values.

Forward Referencing

As mentioned above, functions need to be loaded before they are referenced. One way to do this to put BCL functions in the file above the macro which refers to them. Another solution is to use the Command statement. The Command statement informs BCL that the function is defined elsewhere. For example:

Define_Macro Anim Sstring MoleculeSpec

# forward reference
Command Coord Cen_of_Mol

Coord mol_cent
. . .
mol_cent = {Cen_of_Mol $MoleculeSpec}
. . .
End_Macro

Control Statements

A control statement is used to regulate the execution of statements within a macro. The two primary types of control statements are conditionals, such as If, and loops, such as While.

Conditionals

BCL provides two methods of conditional execution, the If statement and the Switch statement.

If
The BCL If statement is followed by a logical expression enclosed in parentheses. If the expression is logically true, the statements up to its associated End statement are executed. Optionally, an If statement may have an Else statement which also has an associated End. An abbreviated form, ElseIf is also provided. If statements may be nested.

Define_Macro Greeting Sstring str Int a Int b
If ($str = "Hello")
Print "Hi there"
ElseIf ($str = "Bye")
If ($a > 0 && $b > 0)
Print "Goodbye"
End
Else
Print "Not Goodbye"
End
End
End_Macro

Switch
Another way to conditionally execute statements is the Switch statement. A variable is compared with a number of cases and the code within the matching case is executed. If no case matches and a Default case is provided, that block is executed. Each Case must end with a Breaksw statement. The Switch has an associated End.

Define_Macro Greeting Sstring str
Switch $str
Case "Hello":
Print "Hi there"
Breaksw
Case "Bye":
Print "Goodbye"
Breaksw
Default:
Print "You don't say..."
Breaksw
End
End_Macro

Loops

The other type of control statement, the loop, causes the same statements to be executed repeatedly, stopping when a logical test fails. Loops can be created with the While, ForEach, and GoTo statements. The Continue statement jumps control to the top of a While or ForEach loop. The Break statement prematurely terminates a While or ForEach loop. Loops may be nested.

Note: If you run your macro and it loops infinitely, it can be stopped by pressing the <Esc> key.

While
The While statement is a loop with a logical test in parentheses. The While statement has a matching End. The following example also shows the use of the Break statement.

While ($n > 0)
n = $n -1;
If ($n = 7)
Break;
End
End

ForEach
The ForEach loop has two forms: the first iterates through the values of the array; the second increments a counter. Both forms have a matching End statement. Examples of both forms are shown below. The BCL fetch statements used in the examples are discussed in System_Fetch_Assy on page 10-282.

Lstring mol_name, atom, *atom_list
Int count, index

atom_list = {system_fetch_atom $mol_name}
ForEach $atom In $atom_list
Print $atom
End
______________________________________________________

atom_list = {system_fetch_atom $mol_name}
count = sizeof ($atom_list)

Foreach $index From 1 To $count
Print $atom_list[$index]
End

File I/O and Operating System Access

BCL provides statements to read from, and write to, text files. The BCL_Unix statement can also be used to access the file system or perform any operating system command.

Reading from a File

Two BCL statements are available for reading text files. The Fgets statement reads one line at a time. The Read statement reads space-separated tokens.

By Line
Fgets reads a string of characters from a text file and assigns the string to a variable. The maximum number of characters is specified as the second argument to Fgets. Fgets returns zero on failure or end-of-file. Fgets attempts to open the file if it is not already open. Here is a BCL example of the UNIX cat command.

Define_Macro Cat Lstring Catfile
Lstring buff
# open file and get first line
If({Fgets $Catfile 79 $buff})
Printf "%s" $buff
# get remaining lines
While ({Fgets $Catfile 79 $buff})
Printf "%s" $buff
End
Close $Catfile
End
Else
Print "Can't open " $Catfile
End
End_Macro

By Token
The Read statement reads data from a text file and assigns the data to BCL variables for further processing. Text can be read as strings, integers, or floats. Read returns zero on failure or end of file. The read statement attempts to open the file if it is not already open. The Close statement should be used after all reading is complete.

The following example uses the BCL_Unix command to print the owner and modification time fields of the Insight log file.


Define_Macro Last_Run

Sstring access, owner, group, month
Int links, size, day, status

BCL_Unix "ls -l insight.log > /tmp/last_run"
status = {Read "/tmp/last_run" "%s %d %s %s %d %s %d" \
$access $links $owner $group $size $month $day }
Close /tmp/last_run
BCL_Unix "rm /tmp/last_run"

If ($status)
Print "Insight last run here on " \
$month $day " by " $owner
End
Else
Print "Unable to determine when Insight last run"
End
End_Macro

Writing To a File

The BCL Write statement outputs a formatted line of text. The syntax of the Write statement is identical to the Read statement. Write also returns zero on failure. The Close statement should be used after all writing is complete.

The Trace_Torsions.bcl tutorial on page 10-231 shows how this statement can be used to create a text file for use by an Insight command.

Conversion formats, such as %s, can be found in the BCL Reference section under the Read and Write statements.

Parameter Blocks

Several BCL statements are available to enhance the use of your new command. Some are for appearance only. Other statements make it easier to fill in the parameter block by supplying defaults, by providing value-aids, or by picking.

Defaults

Users of your macro appreciate smart default values in your parameters. You can either set the value to some pre-determined constant, or calculate the default with another BCL function.

Setting Defaults
Each parameter type has an associated Set_ command to set the default value of a parameter of that type. See the BCL Reference section for a complete list. The following example sets default values for various data types.

Define_Macro Minimize_New \
Logical Restart_Minimize \
Int Cycles \
Float Gradient_Converge

# Set default values
Set_Boolean Restart_Minimize off
Set_Integer Cycles 20
Set_Real Gradient_Converge 0.001


This is the corresponding parameter block, as it initially appears:

Calculating Defaults
A callback function can be created to calculate default values for parameters. Two types of callbacks are available: Preview_Command and Preview_Function. The first, Preview_Command, is called before the parameter block appears (it is not called for command line invocation). The second, Preview_Function, is associated with a particular parameter and is called whenever the value of that parameter changes, either by a pick, focus change, or explicit <Enter>. Note that only the last callback registered is called.

Callbacks have no arguments and must be defined before they are referenced. Callbacks can access the parameters of the calling macro via the Setv_ and Get_ statements. Setv_ statements set the current value of the parameter from a callback. Get_ statements access the contents of a parameter from a callback, and return a value indicating whether the contents is the current value or a default value. Several other special statements are available for use only in callbacks: Remove_Enum, Test_Boolean, Test_Enum, Setv_Precision, Setv_Focus, and Setv_Trigger.

If a callback changes the state of the system (for example, it creates a temporary file), and you cancel the command, that file is left behind. For this reason, a third callback type called a Cleanup_Command is available.

The following example uses a Preview_Function to calculate a default.

### Preview function for Range macro
# sets High when Low entered

Define_Macro Update_Range
Int val, status

status = {Get_Integer Low val}

If ($status > 0) # Low not empty
Setv_Integer High ($val + 100)
End

End_Macro

### Range Command
Define_Macro Range Int Low Int High

Preview_function Low Update_Range

End_Macro
Add_To_Pulldown Range File

Data Validation

Preview_Function callbacks may also be used to do data validation in parameter blocks. In this example, a callback validates that a Float parameter is positive.

Define_Macro Validate_Size
Int status
Float f

status = {Get_Real Size f}

If ($status > 0 && $f < 0.0)
Print "Size must be positive"
Setv_Real Size 0.0
Setv_Focus Size 0
End

End_Macro

Define_Macro Set_Size Float Size Int Increment
Preview_Function Size Validate_Size
End_macro

Picking

Picking means placing the mouse cursor over a graphical object and clicking the left mouse button. String and ident parameters can be filled by picking. The statement Set_Param_Pick enables picking, and adds a pre-defined value-aid for modifying the pick level and selecting by name. Set_Param_Pick has arguments to specify what level to pick to, such as atom, molecule, or assembly. You may also specify a Screen_Only option to limit Object picks to only Grids, Graphs, or other object types. Here are two examples of the Set_Param_Pick statement, and the associated value-aid:

Define_Macro Check_Mol Ident Mol Sstring Obj
# Molecule picking
Set_Param_Pick Mol Molecule_Spec
# Graph picking
Set_Param_Pick Obj Object_Name Screen_Only Graph

Appearance

You can customize the appearance of a parameter block by using Short_ parameters and by using several BCL statements to affect layout.

Several of the parameter types have Short_ forms. These include: Int, Float, and String. If the Short_ form of the data type is used, the Label and Value widgets appear next to each other and are limited to nine characters each. For example:

Define_Macro Morph \
Short_Int Steps \
Short_String From \
Short_String To

BCL also provides the following statements for enhancing the appearance of a parameter block:

In the following example, the appearance of parameters has been customized.

Define_Macro Style_Demo Int NormalInt Short_Int ShortInt \
Enumer PopupEnum Vlstring HScrollVlstring

Param_Comment NormalInt "A Comment" Center
Param_New_Column PopupEnum
Param_Pack NormalInt
Param_Set_Style PopupEnum PARAM_POPUP
Param_Set_Style HScrollVlstring PARAM_HSCROLL
Def_Enum PopupEnum Value1

Value-Aids

Value-aids provide quick ways for the user to fill in a parameter. The value-aid becomes visible when the parameter associated with it gets keyboard focus. Value-aids include sliders for selecting a float value in a range, palettes for selecting color, and lists for selecting a value. The Place_Valuator, Set_Slider, and Param_Add_File_List statements are used to add built-in value-aids. In the following example, all three types of value-aids are used.

Define_Macro Value_Aids \
Sstring Shade \
Float Temperature \
Vlstring FileName

Place_Valuator Shade Palette Default

Set_Slider Ruler 0.0 500.0
Place_Valuator Temperature Ruler align

Param_Add_File_List FileName "bcl,log"

End_Macro

Conditional Parameters

You may wish to de-activate parameters based on the value of other parameters. For example, if you turn off the Boolean parameter Set_Color, the New_Color parameter should be removed from the parameter block. In this case the New_Color parameter is conditional on the Set_Color parameter. Parameters can be conditional on Boolean and Enumer parameters.

The Condition statement makes a parameter conditional on another parameter, called the control parameter. The syntax allows for multiple conditions logically ANDed and ORed together, as well as NOT logic. The condition statement to have the New_Color parameter active only when the boolean Set_Color parameter is True is:

Condition New_Color Set_Color on off off

The condition statement has five arguments. The first is the conditional parameter and the second is the control parameter. The third argument is the value of the control parameter.

The fourth argument in the Condition statement is for use when you have multiple condition statements for one parameter. In this example on means logically and this condition with the previous condition, whereas off means or. The condition statements to have the Radians parameter active only when the boolean Adjust parameter is True and the enumer Dimension parameter is Angular is:

Condition Radians Adjust on off off
Condition Radians Dimension Angular on off

The fifth argument to the Condition statement is the polarity. If it is on, then the conditional parameter is active if the control parameter does NOT match the value. Therefore, if we also had a Microns parameter, its Condition statements would be:

Condition Microns Adjust on off off
Condition Microns Dimension Angular on on

This means Microns is on when Adjust is True and Dimension is NOT angular.

Accessing Insight II Data

Insight II molecular systems data can be accessed in BCL using Fetch_, Props_, and Cell_ statements. Object identifiers are obtained with Fetch statements. Properties of objects are accessed with Prop_ statements. Spreadsheet cells are accessed with Cell_ statements.

Objects

Fetch functions return arrays of object identifiers that match the specification argument. The returned object identifiers can then be used to refer to an Insight II object in BCL statements. The functions are: System_Fetch_Atom, _Mono, _Mol, _Object, _Sketch, _Assy, and Assy_Fetch_Molecule. The functions return NULL if no objects were found which match the specification argument.

The following example shows atom fetching.

Define_Macro List_Atoms
Ident *atom_list, atom
Int count

atom_list = { System_Fetch_Atom "CRN:29:*" }
count = sizeof($atom_list)
ForEach $atom In $atom_list
Print $atom
End
Print $count "atom(s) found"
End_Macro

The output of the previous example is shown below.

(Executing: List_Atoms User)
CRN:29:N
CRN:29:CA
CRN:29:C
CRN:29:O
CRN:29:CB
CRN:29:CG
CRN:29:CD1
CRN:29:CD2
CRN:29:CE1
CRN:29:CE2
CRN:29:CZ
CRN:29:OH
12 atom(s) found

Properties

BCL macros can access properties from molecular system such as element type, charge, or number of bonds. Properties come in two forms, Function properties, and Attribute properties. Function properties are calculated each time the property is requested. Attribute properties are data stored with individual objects.

Each property is associated with a class of object, such as Atom or Mol, and datatype, such as Int of Str. See the Custom/List_Properties command for a complete list of properties, their classes, and their datatypes.

Once a property is defined, it can be used in Insight II commands such as Molecule/Label and Subset/Define. Properties are also accessible in Spreadsheet formulas.

This section describes properties in four parts: accessing the system properties supplied with Insight II, user defined attribute properties, user defined functional properties, and accessing arrays of properties to increase performance.

System Properties
The BCL function Prop_Get_ returns a property value from an object. The syntax of the statement is:

val = Prop_Get_<datatype> <PropName> <Class> <Object spec>

where datatype is Int, Float, Str, or Bool, and class is Atom, Mono, or Mol. If the property is not set, Prop_Get returns a null value of the appropriate datatype.

The following example shows how to get several pre-defined properties with different datatypes from different classes of objects, and the output from the macro.

Define_Macro Print_Sys_Props
Int bonds, count
Lstring element
Ident atom

# get single properties
count = { Prop_Get_Int Monomer_Count Mol "CRN" }
Printf "Molecule CRN contains %d monomer(s)\n" $count

atom = "CRN:29:OH"
element = { Prop_Get_Str Element Atom $atom}
bonds = { Prop_Get_Int Connection_Count Atom $atom}
Printf "Atom CRN:29:OH is %s with %d bond(s)\n" \
$element $bonds
End_Macro

(Executing: Print_Sys_Props User)
Molecule CRN contains 46 monomer(s)
Atom CRN:29:OH is O with 1 bond(s)

User-Defined Attribute Properties
Attribute properties are values you can store to, and retrieve from, objects. These values are saved with the object when you save your folder. Retrieving user-defined attribute properties is identical to retrieving pre-defined properties, using Prop_Get. Creating user-defined attribute properties is a two step process: first, the property must be registered; second, the property must be set on the object.

Registering user-defined attribute properties is done with the Prop_Register statement. Registration declares the name of the property, the class it applies to, and the datatype it holds. This operation only needs to be done once per session, and occurs automatically when you restore a psv file which has an unregistered property. The Prop_Register statement returns TRUE if either the property was registered successfully, or if it already is registered in the same way. It returns FALSE if the property is registered differently or if registration failed. The syntax to register a property is:

success = { Prop_Register Attr <PropName> <Class> <DataType> }

Setting the user-defined attribute property on an object is done with the Prop_Set statement. The syntax is identical to Prop_Get except its value is passed in, instead of being returned. If the property did not exist on the object, space is allocated the first time the attribute property is set. If necessary, you can check whether a property was set on a particular object with the Prop_Exists statement. Properties can also be removed from the system with Prop_Remove.

The following example registers, sets, and gets a user-defined attribute property. The output is shown below.

Define_Macro Use_Attr_Prop Ident Atom

Lstring strvar
Set_Param_Pick Atom Atom_Spec

If(!{Prop_Register Attr My_String Atom Str})
Printf "Unable to register My_String Property\n"
End

Prop_Set_Str My_String Atom $Atom "Hello world"

If({Prop_Exists My_String Atom $Atom})
strvar = {Prop_Get_Str My_String Atom $Atom}
Printf "Property set to %s\n" $strvar
End

End_Macro

(Executing: Use_Attr_Prop CRN:29:OH)
Property set to Hello world

User-Defined Function Properties
Function properties are calculated each time the property is requested. Like Attribute properties, function properties must be registered with the Prop_Register statement. Unlike attribute properties, function properties have no set function or space allocation, and are not saved in folders.

When you register a function property, you must specify the name of a macro that will be called each time the property is requested with Prop_Get. That macro is called with one parameter; the object specified in the Prop_Get request. The macro must return a value of the type specified when the property was registered.

The Prop_Register statement for function properties has a first argument of Func instead of Attr and a new final argument: the name of the function to call.

success = { Prop_Register Func <PropName> <Class> \

<DataType> <Macro_Func> }

The following example registers a new property macro (if it is not already registered) and defines the macro that is called. The new property, called Owner_Mon, returns a string containing the monomer for an atom.

Prop_Register Func Owner_Mon Atom Str Owner_Mon_Prop

Define_Macro Lstring Owner_Mon_Prop Ident Atom
monlist = { System_Fetch_Mon $Atom }
return $monlist[1]
End_Macro

The following example uses the new Owner_Mon property declared and defined above. Output is shown below.

Define_Macro Print_User_Prop Ident Atom
Ident mon
Set_Param_Pick Atom Atom_Spec

# call new property macro
mon = {Prop_Get_Str Owner_Mon Atom $Atom}
Printf "Monomer for atom %s is %s\n" $atom $mon

End_Macro


(Executing: Print_User_Prop CRN:29:OH)
Monomer for atom CRN:29:OH is CRN:29

Property Arrays
To improve performance, you can get an array of property values with one statement. The Prop_Get_Arr statement returns an array of atom properties from all the atoms in a molecule or monomer. The syntax is the same as Prop_Get, with the addition of two new classes, Mol_Atom and Monomer_Atom. The following example gets the pre-defined mass property of each of the atoms in a molecule, and prints the sum. The output is shown below.

Define_Macro Atom_Mass
Float m, sum, *mass
# get an array of properties
mass = { Prop_Get_Arr_Float Mass Mol_Atom "CRN" }
sum = 0.0
ForEach $m In $mass
sum = $sum + $m
End
Printf "Mass of atoms in CRN: %.2f\n" $sum
End_Macro

(Executing: Atom_Mass)
Mass of atoms in CRN: 4412.97

Spreadsheet Cells

Spreadsheet cells can be accessed with Cell_Get_String, _Int, or _Float. The statement takes one argument of the form Table:row.col, as shown in the example below.

Define_Macro Print_Cell \
Ident Table Int Row Int Col

Ident Cell
Lstring contents

Cell = $Table // ":" // $row // "." // $col
contents = {Cell_Get_String $Cell}
Printf "\n\tTable %s Cell %d %d -- %s\n" \
$Table $row $col $contents
End_Macro

Debugging

If errors occur when you load or run your macro, here are a few debugging suggestions:


BCL Reference

Reserved Symbols

The following words have special meaning in the BCL language and should not be used as names:

Table 12¯1. Reserved Symbols

After   BCL_UNIX   Before  
Break   BreakSw   Case  
Cleanup_Command   Close   Condition  
Constant   Continue   Coord  
Default   Define_Macro   Def_Enum  
Def_Enum_Sorted   Def_Enum_Unique   Def_List  
Def_List_Sorted   Def_List_Unique   Else  
ElseIf   End   End_Macro  
Enumer   Fgets   Float  
ForEach   From   FullScreen  
Get_Boolean   Get_Coord   Get_Enum  
Get_Ident   Get_Integer   Get_List  
Get_Lstring   Get_Real   Get_Sstring  
Get_Vlstring   GoTo   Ident  
If   In   Int  
Logical   Lstring   Param_Add_File_List  
Param_Comment   Param_New_Column   Param_Pack  
Param_Set_Style   Place_Valuator   Preview_Command  
Preview_Function   Print   Printf  
Read   Remove_Enum   Return  
Screen_Update   Setv_Boolean   Setv_Coord  
Setv_Enum   Setv_Focus   Setv_Ident  
Setv_Integer   Setv_List   Setv_Lstring  
Setv_Precision   Setv_Real   Setv_Sstring  
Setv_Trigger   Setv_Vlstring   Set_Boolean  
Set_Coord   Set_Enum   Set_Ident  
Set_Integer   Set_List   Set_Lstring  
Set_Param_pick   Set_Real   Set_Sideblock  
Set_Slider   Set_Sstring   Set_Vlstring  
Short_Ident   Short_Integer   Short_Real  
Short_String   Size_List   Sstring  
Step   Switch   Test_Boolean  
Test_Enum   TextPort   To  
Trigger   Vlstring   Void  
While   Write    

Operator Precedence

In an expression, certain operations have precedence over others. Operations of equal precedence are evaluated left to right. The operations and their precedence are:

Table 12¯2. Operator Precedence

Order

Symbol

Operand Type

Value Type

Comments

1   %   Integer   Integer   Modulo  
1   -(unary)   Integer or Float   Integer or Float   Negate  
2   //   String or other   String   Concatenation, one or both operands must be string  
3   *, /   Integer or Float   Integer or Float   Multiply, Divide  
4   +, -   Integer or Float   Integer or Float   Addition, Subtraction  
5   =, !=, .eq., .ne.   Integer, Float,   String, Coord   Logical   Equal, Not equal  
5   <, >, .lt., .gt.   Integer, Float   Logical   Less than, Greater than  
5   <=, >=, .le., .ge.   Integer, Float   Logical   Less or equal, Greater or equal  
6   ! (unary)   Logical   Logical   Not  
7   &&, .and.   Logical   Logical   And  
8   ||, .or.   Logical   Logical   Or  

Precedence can be overridden with the use of parentheses. For example:

3 + 7 * 4

evaluates to 31, but:

(3 + 7) * 4

yields 40.

Intrinsic Functions

Intrinsic functions are built-in functions provided by BCL. These include common arithmetic and trigonometric functions. They can be used as part of an expression in an assignment statement or as a parameter value in a command statement.

Table 12¯3. Intrinsic Functions

Function

Input Type

Output Type

Remark

acos(x)*   Float   Float    
acosh(x)*   Float   Float    
cos(x)*   Float   Float    
cosh(x)*   Float   Float    
asin(x)*   Float   Float    
asinh(x)*   Float   Float    
sin(x)*   Float   Float    
sinh(x)*   Float   Float    
atan(x)*   Float   Float    
atanh(x)*   Float   Float    
tan(x)*   Float   Float    
tanh(x)*   Float   Float    
exp(x)   Float   Float    
log(x)   Float   Float   Natural log, x > 0  
log10(x)   Float   Float   Log base 10, x >0  
cbrt(x)   Float/Integer   Float    
sqrt(x)   Float/Integer   Float   x >= 0.0  
float(x)   Float/Integer   Float    
abs(x)   Float/Integer   Float/Integer    
int(x)   Float/Integer   Integer    
sizeof(x)   Variable Name   Integer    
rand()   Void   Integer   value: 0 ~ (2**15)-1  
random()   Void   Integer   value: 0 ~ (2**31)-1  

* both the input value and the return value from this function are in radians.

Insight II Commands that Return a Value

The following Insight II commands return a value which can be used in a BCL expression. Refer to on-line help for further information on command syntax.

Table 12¯4

Command

Pulldown/Module

Type

Return Values

Distance   Measure/Viewer   Float   Distance between two atoms  
Angle   Measure/Viewer   Float   Planar angle  
Dihedral   Measure/Viewer   Float   Dihedral angle  
XYZ   Measure/Viewer   Coord   Atom coordinate  
Energy   Measure/Viewer   Float   Energy of a single molecule  
Soak   Assembly/Viewer   Int   Number of molecules added  
Superimpose   Transform/Viewer   Float   rms float  
Get   Molecule/Viewer   Int   1 if successful, 0 otherwise  
Put   Molecule/Viewer   Int   1 if successful, 0 otherwise  
Get   Trajectory/Analysis   Int   Number of trajectory files
loaded  
Animate   Trajectory/Analysis   Int   Number of frames displayed  
Construct_Graph   Trajectory/Analysis   Int   Next graph index  
Intermolecular   Evaluate/Docking   Float   Energy between two molecules  
Compute   Docking_Grid/Docking   Float   Grid energy  
3D_Convert   Sketch/Builder   Int   1 if successful, 0 otherwise  
. Insight II Commands that Return a Value

Insight II Parameter Names

Table 12¯5. Insight II Parameter Names

BCL Statements

Assy_Fetch_Molecule

Returns an array of molecules satisfying the assembly specification argument. See System_Fetch_Assy.

Syntax: Assy_Fetch_Molecule object_spec

Input: object_spec (Ident): object specification for assemblies.

Returns: Array of molecules or NULL.

BCL_UNIX

Execute a UNIX shell command from within a macro.

Syntax: BCL_UNIX unix_command

Input: unix_command (Vlstring): UNIX command string

Example: BCL_UNIX "ls -l *.dat"

Break

Exit a loop. Control jumps to the statement following the end of the loop. Typically placed within conditional code.

Syntax: Break

Cell_Get_Real, Cell_Get_Int, Cell_Get_String

Retrieve the contents of a spreadsheet table cell. Different statements return different data types.

Syntax: Cell_Get_<datatype> table_cell_spec

Input: datatype (Enumer): Float, Int or String

table_cell_spec (Ident): specification of table cell of
the form Table:row.col

Returns: cell contents of specified type

Errors: mismatch type, table not found

Cleanup_Command

Associate a cleanup callback with a macro. The callback is executed when the user cancels either explicitly with the Cancel button or implicitly by selecting another command.

Syntax: Cleanup_Command clean_macro

Input: clean_macro (Sstring): cleanup macro name

Error: macro not found

Close

Close an open file. After reading from or writing to a file, the file should be closed with the Close statement. Failure to close files may cause future read or write requests to fail.

Syntax: Close file_name

Input: file_name (Vlstring): data file opened for either read or write

Error: Specified data file not opened or not found.

Example: close /tmp/list.dat

Command

Declare a macro before it has been defined, to satisfy forward references.

Syntax: Command declarator_type [*]macro_name[, macro_name]

Input: declarator_type(Sstring): parameter type returned
macro_name(Sstring): name of command

Condition

Makes a parameter conditional on the value of another parameter, called the control parameter. The control parameter must be either a boolean or an enumerated type.

Syntax: Condition cond_param control_param pvalue operation polarity

Input: cond_param (Sstring): conditional parameter name
control_param (Sstring): control parameter name
pvalue (Sstring): control parameter value
operation (Logical): off = OR, on = AND
polarity (Logical): off = normal, on = NOT

Error: Missing/Invalid conditional parameter, recursive conditions, reuse of conditional parameter in macro without its control parameter.

Constant

Define a symbolic constant.

Syntax: Constant const_name value

Input: const_name (Sstring): new symbolic name
value: replacement value

Example:

Constant PI 3.14159

sum = $value * PI

Continue

Jump to the top of the loop. Typically placed with conditional code.

Syntax: Continue

Example:

While ($n > 0)

n = $n - 1

# Skip this case, and start from the top

If ($n = 7)

Continue

End

Print $n

End

Define_Macro

Begin definition of a new macro.

Syntax: Define_Macro [return_type] name [param_type param][, ...]

Input: return_type (Sstring): for macro functions, data type returned
name (Sstring): name of new command or function
param_type (Sstring): argument data type
param (Sstring): name of parameter

Define_Menu

Create a new pulldown menu.

Syntax: Define_Menu module_name menu_name

Input: module_name (Sstring): name of module to which new menu will
be added
menu_name (Sstring): name of new menu

Define_Module

Create a new module. A name for the first menu in the module must be specified. The module is placed in the first group of modules in the biochem discipline.

Syntax: Define_Module module_name menu_name

Input: module_name (Sstring): name of new module
menu_name (Sstring): name of first menu in new module

Def_Enum, Def_Enum_Sorted, Def_Enum_Unique

Add values to an Enumer.

Def_Enum: Value is added in the order specified.

Def_Enum_Sorted: Value is added alphabetically.

Def_Enum_Unique: Value is added alphabetically, not added if duplicate.

Syntax: Def_Enum param new_entry
Def_Enum_Sorted param new_entry
Def_Enum_Unique param new_entry

Input: param(Sstring): parameter name
new_entry (Sstring): addition to enum

Error: parameter not found, attempt to define value for system parameter

Def_List, Def_List_Sorted, Def_List_Unique

Add values to a list. May be used in callbacks.

Def_List: Value is added in the order specified.

Def_List_Sorted: Value is added alphabetically.

Def_List_Unique: Value is added alphabetically, not added if duplicate.

Syntax: Def_List param new_entry
Def_List_Sorted param new_entry
Def_List_Unique param new_entry

Input: param (Sstring): parameter name
new_entry (Lstring): addition to list

Error: parameter not found, attempt to define value for system parameter

End_Macro

Stop definition of a new macro.

Syntax: End_Macro

Fgets

Read a string of characters from a file. Reads up to end_of_file, new_line, or specified limit. Attempts to open the file if not already open. Use the Close command when finished reading.

Syntax: Fgets file_name char_count param

Input: file_name (Lstring): data file to read
char_count (Int): maximum number of characters to read.
up to 511 for Vlstring variable
param(Sstring): name of string variable to contain input
data

Returns 1: successfully executed
0: execution failed, or beyond end of file

Error: Invalid param_name, unable to open user file_name

Example: Fgets /tmp/list.data 40 $string

ForEach

Loop through an array or loop by an index.

Syntax: Form 1: Array

ForEach value In valuelist

statements

End

Valuelist is an array and value is of the same type as a member of the array. With each iteration, value is set to the next member of valuelist. The loop ends when valuelist is exhausted.

Form 2: Index

ForEach index From start To stop [Step steps]

statements

End

Where index is an integer parameter, start and stop are integer expressions, step is integer constant with default value 1. The conditional expression is evaluated by verifying index lies between the range specified by start and stop.

FullScreen

Enables or disable FullScreen mode. In FullScreen mode, the graphics window takes over the entire computer screen.

Syntax: FullScreen status

Input: status (Logical ON/OFF): new FullScreen mode

Get_Boolean, Get_Integer, Get_Coord, Get_Real, Get_Sstring, Get_Lstring, Get_Vlstring, Get_Ident, Get_Enum

Used by callback functions to access the value of a parameter or its default.

ONLY AVAILABLE IN CALLBACKS.

Syntax: Get_Boolean param var
Get_Integer param var
Get_Coord param var
Get_Real param var
Get_Sstring param var
Get_Lstring param var
Get_Vlstring param var
Get_Ident param var
Get_Enum param var

Input: param (Sstring): parameter to retrieve
var (Sstring): variable to store value for param
(Note: var must be properly declared based on the
operation to be performed)

Returns: 3: command scope default
2: default
1: value
0: error
-1: empty
-2: emptied by user

Error: parameter is not accessible

Goto

Jump execution to a specified location. Every goto statement needs a matching label followed by a (:), but not every label requires a matching goto statement. Labels are not case sensitive and they are a string of 19 or less characters. Any valid character can be part of a label, e.g., 99999, exit, goodbye, done, begin_.

Syntax: goto label

Input: label (Sstring): name of label

If

Conditionally execute statements up to the associated End statement based on a logical test. If statements may be nested.

Syntax: if (Logical_Test)
statements
End

The If statement can have an optional Else statement, which also has an associated End. If the logical test fails, only statements after the Else statement are executed.

Syntax: If (Logical_Test)
statements
End
Else
statements
End

The ElseIf statement provides an alternate form of the If..Else.. statement. This is useful when a series of tests need to be performed. As soon as one of the tests succeeds, the statements below the test, up to the next test (or end) are executed and control jumps to the statement following the End.

Syntax: If (Logical_Test)
statement
ElseIf (Logical_Test)
statement
End

Make_File_List

Fill a file list value-aid that has already been attached to a parameter. More flexible than Param_Add_File_List. Typically used in callback macros.

Syntax: Make_File_List File_List_Clear value-aid path file_ext

Input: File_List_Clear (Logical): whether to clear value-aid parameter

value-aid (Sstring): value-aid name

path (Lstring): directory path where all files are located

file_ext (Lstring): file extensions to search for,
comma separated

Returns: Number of file names added to the value-aid.

Example: status = {Make_File_List File_List_Clear Files . "bcl,log"}

Message_Print_Error

Display an error dialog with a message that you specify. The dialog has two buttons, "Done" and "Explain". "Done" closes the dialog. "Explain" closes the dialog and opens another dialog that contains additional explanatory text.

Syntax: Message_Print_Error err_text explain_text

Input: err_text(Lstring): error message

explain_text(Lstring): additional explanation

Example: Message_Print_Error "Charge value out of range" \
"Formal charge must be between -6 and 6"

Param_Add_File_List

Attaches a value-aid to a parameter containing a list of files in the current working directory with names ending in the specified suffixes.

Syntax: Param_Add_File_List param suffixes

Input: param (Sstring): name of Lstring or Vlstring param
suffixes (Sstring): comma separated list of extensions

Example: Param_Add_File_List FileName "bcl,log"

Param_Comment

Add a line of text above a parameter in a parameter block.

Syntax: Param_Comment param comment justification

Input: param (Sstring): parameter name
comment (Sstring): text remark
justification (enumer): "Left", "Center", or "Right"

Param_New_Column

Start a new column in the parameter block. The specified parameter is placed at the top of the next column. No check is made if too many columns are created. We recommend that you use a maximum of four columns.

Syntax: Param_New_Column param

Input: param(Sstring): parameter name

Param_Pack

Add a double line beloe the specified parameter.

Syntax: Param_Pack param

Input: param(Sstring): parameter name

Param_Set_Style

Modify the appearance of a parameter in a parameter block. Lists and Enumers may be displayed as popup option menus. Idents, Lstrings and Vlstrings can be displayed as a single scrolling line.

Syntax: Param_Set_Style param style

Input: param(Sstring): parameter name
style(Sstring): PARAM_POPUP or
PARAM_HSCROLL

Errors: mismatched parameter type and style

Place_Valuator

Link a value-aid to a parameter. The Ruler and Palette are two pre-built value-aids.

Syntax: Place_Valuator param value_aid location

Input: param (Sstring): target parameter name
value-aid (Sstring): value-aid name
location (enumer): location (side parameter block only)
Default: normal placement
Top: top of the parameter block
Bottom: bottom of the parameter block

Preview_Command

Attach a callback to be run before the parameter block appears. The callback is a macro with no parameters and no return value. The callback accesses the command's parameters with Get_ and Setv_ statements. Note that only the last callback registered is called.

Syntax: Preview_Command macro

Input: macro (Sstring): callback macro name

Error: command not found or it is not a BCL command

Preview_Function

Associates a callback with a parameter. The callback is called when the parameter's value is changed as a result of picking, focus change, explicit <enter> being pressed, or in response to a prompt in the command line. The callback is a macro with no parameters and no return value. The callback accesses the command's parameters with Get_ and Setv_ statements. Note that only the last callback registered is called.

Syntax: Preview_Function param macro

Input: param (Sstring): parameter associated with callback
macro (Sstring): callback macro name

Error: command not found or it is not a BCL command

Print

The print statement prints an expression to the info area and textport. BCL will attempt to identify and print the expression in an appropriate type.

Syntax: Print expression [expression]

Input: expression (Vlstring): variable, constant, expression

Example Print "index = " $index

Error: Invalid expression

Printf

Formatted print statement. See Write statement for Output Formats.

Syntax: Printf format_string expression [expression]

Input: format_string (Vlstring): user specified format string
expression (Vlstring): variable, constant, expression

Example: Printf "Index = \t%d\nlength = \t%d\n" $index $length

Error: Invalid format string, invalid expression

Prop_Exists

Determine if an Attr property is already assigned to an object.

Syntax: Prop_Exists property class object_spec

Input: property(Sstring): name of attr property
class (Enumer): Class of object that this property can be
applied to: Atom, Monomer, or Mol
object_spec (Ident): Object to test

Returns: 1 if property set, otherwise 0

Example: If ({Prop_Exists MyMarker Mol CRN})

Prop_Get_Arr_Bool, Prop_Get_Arr_Int, Prop_Get_Arr_Float, Prop_Get_Arr_Str

Retrieve an array of property values. Provides better performance than Prop_Get when retrieving properties from all the atoms in a monomer, using class Monomer_Atom, or all the atoms in a molecule, using class Mol_Atom. Property should be pre-defined or registered with Prop_Register. Different statements return different datatypes; you must use the appropriate datatype for the property.

Syntax: Prop_Get_Arr_<datatype> property class object_spec

Input: <datatype>: type of value that will be returned
Bool int
Int int
Float float
Str lstring

property (Sstring): name of property to retrieve

class (Enumer): class of object to retrieve from, either
Mol_Atom or Monomer_Atom

object_spec (Ident): object to retrieve from

Returns: value of property or 0 (or "") if uninitialized

Errors: mis-match datatype, mis-match assignment

Example: # get mass of all atoms in CRN
floatarr = { Prop_Get_Arr_Float Mass Mol_Atom CRN }

Prop_Get_Bool, Prop_Get_Int, Prop_Get_Float, Prop_Get_Str

Retrieve a property value. Property should be pre-defined or registered with Prop_Register. Use Prop_Exists to verify property is available for object. Different statements return different datatypes; you must use the appropriate datatype for the property.

Syntax: Prop_Get_<datatype> property class object_spec

Input: <datatype>: type of value that will be returned
Bool int
Int int
Float float
Str lstring

property (Sstring): name of property to retrieve

class (Enumer): class of object to retrieve from: Atom,
Monomer, or Mol

object_spec (Ident): object to retrieve from

Returns: value of property or 0 (or "") if uninitialized

Errors: property not defined, mis-match datatype, mis-match assignment

Example: strvar = { Prop_Get_Str My_String Atom "CRN:29:OH"}

Prop_Register

Declare a new property. Two types of properties can be declared, Attr and Func. An Attr property can be set and retrieved. A Func property can only be retrieved. Func properties are registered with an additional macro_name argument, which is executed each time the property is requested with Prop_Get. Attr properties are maintained at the molecule level.

Syntax: Prop_Register type property class datatype [ macro_name]

Input: type (Enumer): Attr (r/w) or Func (ro)
property (Sstring): name of new property
class (Enumer): Class of object that this property can be
applied to: Atom, Monomer, or Mol
datatype (Enumer): Bool, Int, Float or Str
macro_name (Sstring): name of macro that will be called
(if this is a Func property)

Returns: 1 if created successfully or if it is already registered the same way
otherwise 0

Example: Prop_Register Func New_Prop Atom Str New_Prop_Macro
Prop_Register Attr MyMarker Mol Bool

Prop_Remove

Remove a user defined property from Insight II. Free all memory used by an Attr property.

Syntax: Prop_Remove property class

Input: property (Sstring): name of new property
class (Enumer): Class of object that this property can be
applied to: Atom, Monomer, or Mol

Returns: 1 on success, otherwise 0

Errors: system property, does not exist

Example: Prop_Remove Marker Base_Object

Prop_Set_Bool, Prop_Set_Int, Prop_Set_Float, Prop_Set_Str

Set an attribute property. Property should be registered with Prop_Register. Different statements set properties with different datatypes; you must use the appropriate datatype for the property.

Syntax: Prop_Set_<datatype> property class object_spec value

Input: <datatype>: type of value that will be returned
Bool int
Int int
Float float
Str lstring

property (Sstring): name of property to set

class (Enumer): class of object to set Atom,
Monomer, or Mol

object_spec (Ident): object to set

value: new value of proper data type

Returns: 1 on success, otherwise 0

Errors: property not registered, mis-match datatype, mis-match assignment

Example: Prop_Set_Str My_String Atom "CRN:29:OH" "Old site"

Read

Reads data from a specified file and assigns the data to variables.

Syntax: Read file_name format_string var [var]

Input: file_name (Vlstring): data file read
format_string (Vlstring): user specified format string
var (Sstring): variable to store value

Returns 1: successfully executed
0: execution failed, or beyond end of file

Example: Read /usr/tmp/input.dat "%d %f" $index $length

Error: Invalid format_string, unable to open user file_name

Input Formats
The format_string in the Read statement is a collection of constants and specifications. Each specification starts with a percent sign (%) followed by the letter s, f, or d. Each specification must have a corresponding variable to store the translated data.

s: string conversion. Any leading white space characters are skipped. Characters are read until an end-of file is reached, or until a white space character is seen. If end-of-file is reached before any non-white space character is seen, the operation is considered failed

f: signed decimal floating-point conversion. Any leading white space characters are skipped. If no digits are read, the value is zero. If the value is too large or too small to be represented as a floating point number, the value is unpredictable. If the value cannot be represented exactly as a floating-point number, the value is truncated.

d: signed decimal conversion. Any leading white space characters are skipped. Characters are read until end-of-file is reached, or until a non-digit character is seen. The characters read are interpreted as a signed decimal number. If no digits are read, the value is zero. If the value expressed by the input is out of range (2**32-1 ~ 2**32), then the value will have an unpredictable results.

Remove_Enum

Clears all entries from an Llist or Enumer parameter.

ONLY AVAILABLE IN CALLBACKS.

Syntax: Remove_Enum param

Input: param(Sstring): parameter name

Error: param is not an enumerated or list type

Return

Exit a macro before End_Macro. Required in function macros to send a value back to calling macro; the argument must match the return type declared in the Define_Macro statement.

Syntax: Return [expression]

Examples: Return # no return value

Return $center # return variable center

Return ($x+$y) # return an expression

Run_Bkgd_Job

Launch a background job. For a complete list of background job facilities, see REF .

Syntax: Run_Bkgd_Job job pathname file_of_files args

Input: job(Sstring): A unique name for the job that is used in the commands in the Background_Job pulldown.

pathname (Lstring): The program to be run. If the directory where the program exists is in your PATH environment variable, then you do not need to specify the directory path to the program. Otherwise, this path specification is needed.

file_of_files (Lstring): The pathname of a file containing a list of files needed by the background job. Each filename should be listed on a separate line. Only needed if running on a remote host, otherwise, specify "None".

args (up to 30 Lstring's): Background job command argument list.

Returns: zero on error

Screen_Update

Sets graphics refresh policy. By default, the graphics are only updated when a macro completes. If Screen_Update is enabled, refreshes take place during execution. Policy remains in effect until reset with another Screen_Update.

Syntax: Screen_Update display_mode

Input: display_mode: (logical) ON/OFF
ON: refresh after each statement
OFF: refresh at end of macro (default)

Setv_Boolean, Setv_Integer, Setv_Coord, Setv_Real, Setv_Sstring, Setv_Lstring, Setv_Vlstring, Setv_Ident, Setv_Enum

Set the current value of a parameter from a callback.

ONLY AVAILABLE IN CALLBACKS.

Syntax: Setv_Boolean param value
Setv_Integer param value
Setv_Coord param value
Setv_Real param value
Setv_Sstring param value
Setv_Lstring param value
Setv_Vlstring param value
Setv_Ident param value
Setv_Enum param value

Input: param (Sstring): parameter name
value: value of appropriate type for param

Setv_Focus

Shift keyboard input focus to a parameter from a callback.

ONLY AVAILABLE IN CALLBACKS.

Syntax: Setv_Focus param index

Input: param (Sstring): parameter name
index (int): Offset (1, 2, or 3) for coord parameters
(0 for other types)

Setv_Precision

Set number of places shown after decimal in float parameter.

ONLY AVAILABLE IN CALLBACKS.

Syntax: Setv_Precision param places

Input: param (Sstring): parameter name
place (int): number of places after the decimal point

Setv_Trigger

Make a parameter the trigger. When the trigger is filled by a pick, value-aid or explicit "Enter", the command executes. See the Trigger statement.

ONLY AVAILABLE IN CALLBACKS.

Syntax: Setv_Trigger param

Input: param (Sstring): parameter name

Set_Boolean, Set_Integer, Set_Coord, Set_Real, Set_Sstring, Set_Lstring, Set_Vlstring, Set_ident, Set_Enum

Set the default value for a parameter.

Syntax: Set_Boolean param value
Set_Integer param value
Set_Coord param value
Set_Real param value
Set_Sstring param value
Set_Lstring param value
Set_Ident param value
Set_Enum param value
Set_List param value

Input: param (Sstring): parameter name
value: value of appropriate type for param

Error: Parameter not found, invalid parameter value

Set_Param_Pick

Add a picking function and related value-aid to parameters. The picking functions enable the parameters to be filled in with the specification of the object the user picks from the screen with the mouse. The value-aids permit selecting from a list of objects.

Syntax: Set_Param_Pick Param Template [Screen_Only Object]

Input: Param (Sstring): parameter name of appropriate type
Template (Sstring): see Picking Templates below
Object (Sstring): see Picking Object below

Picking Templates
The picking function and value-aid provided are determined by the type of the template.

MOLECULE_NAME is used when the parameter specifies the name of a molecule. The attached pick function only picks molecules. The attached value-aid list shows available molecules. The associated parameter must be sstring, lstring, ident, or short_ident type.

MOLECULE_SPEC is used when the parameter specifies the name of a molecule, monomer, or atom. The attached pick function only picks molecules, monomers, or atoms, depending on the value of the associated pick-level value-aid. The attached value-aid list shows available molecules. The associated parameter must be ident or short_ident type.

MOLECULE_ASSEMBLIES is the same as MOLECULE_NAME, except that assemblies may be picked and the attached list includes assemblies. The associated parameter must be ident or short_ident type.

OBJECT_NAME is used when the parameter specifies the name of an object. The attached pick function only picks objects. The attached value-aid list shows available objects. The associated parameter must be sstring, lstring, ident, or short_ident type.

ATOM_SPEC is used when the parameter specifies the name of an atom. The attached pick function only picks atoms. When an atom is picked, the full molecule:residue:atom specification is filled into the parameter. No value-aid is attached to the parameter. The associated parameter must be ident, or short_ident type.

Picking Object
If the Picking Template is OBJECT_NAME, a SCREEN_ONLY object may be specified. This limits object picking to only the type specified. Possible values for Object:

MOLECULE: Molecule type object
ASSEMBLY: Assembly type object
GRAPH: Graph type object
GRID: Grid type object
SPECTRUM: Spectrum type object
CONTOUR: Contour type object
USER_OBJECT: User_Object type object

Set_Rand

Seed the rand() Intrinsic Function random number generator. If set_rand is not called before calling rand (), set_rand will be called automatically with default value of 1 as the seed.

Syntax: Set_Rand starting_seed

Input: starting_seed (int): random generator seed

Error: Invalid starting_seed

Set_Random

Seed the random() Intrinsic Function random number generator. If set_random is not called before calling random (), set_random will be called automatically with default value of 1 as the seed.

Syntax: Set_Random starting_seed

Input: starting_seed (int): random generator seed

Error: Invalid starting_seed

Set_SideBlock

If set to off, display parameter block in multiple columns.

Syntax: Set_Sideblock state

Input: state (Logical):
ON: single column (default)

OFF: multi-column

Set_Slider

Determine the range of a slider value-aid. The start and stop values are floating point and may be positive or negative.

Syntax: Set_Slider valuator_name start stop

Input: valuator_name (Sstring): valuator name
start (float): valuator staring point
stop (float): valuator ending point

Example: Set_Slider Ruler -50.0 50.0

Size_List

Set the number of rows displayed in an Llist parameter. The default is 7. The allowable range is from 3 to 50.

Syntax: Size_List param rows

Input: param(Sstring): Llist parameter name
rows(int): Number of visible entries

Example: Size_List list_param 4

Switch

Conditionally execute code by matching a variable with a case. The switch statement has a matching End statement. Cases can be numeric or alpha-numeric, but must match the type of the Switch variable. Each Case statement has a matching Breaksw statement. An optional Default case may be specified.

Syntax: Switch $variable

Case 1:
statements
Breaksw

Case 2:
statements
Breaksw

Default:
statements
Breaksw

End

System_Fetch_Assy

Returns an array of assemblies satisfying the specification argument.

Syntax: System_Fetch_Assy object_spec

Input: object_spec (Ident): object specification for assemblies.

Returns: Array of assemblies or NULL.

System_Fetch_Atom

Returns an array of atoms satisfying the specification argument.

Syntax: System_Fetch_Atom object_spec

Input: object_spec (Ident): object specification for the atoms.

Returns: Array of atoms or NULL

System_Fetch_Mol

Returns an array of molecules satisfying the specification argument.

Syntax: System_Fetch_Mol object_spec

Input: object_spec (Ident): object specification for molecules.

Returns: Array of molecules or NULL.

System_Fetch_Mono

Returns an array of monomers satisfying the specification argument.

Syntax: System_Fetch_Mono object_spec

Input: object_spec (Ident): object specification for monomers.

Returns: Array of monomers or NULL.

System_Fetch_Object

Returns an array of objects satisfying the specification argument

Syntax: System_Fetch_Object object_spec

Input: object_spec (Ident): object specification.

Returns: Array of objects or NULL.

System_Fetch_Sketch

Returns an array of 2-D molecules satisfying the specification argument.

Syntax: System_Fetch_Sketch object_spec

Input: object_spec (Ident): object specification for 2D molecules.

Returns: Array of 2D molecules or NULL.

Test_Boolean

Convenience function for retrieving the state of a logical parameter from a callback macro.

ONLY AVAILABLE IN CALLBACKS.

Syntax: Test_Boolean param

Input: param(Sstring): logical parameter name

Value: result (int): 1 if ON, else 0

Example: If ({Test_Boolean Set_Color})

Error: param is not a logical type

Test_Enum

Convenience function for comparing an Enumer parameter with a value from a callback macro.

ONLY AVAILABLE IN CALLBACKS.

Syntax: Test_Enum param value

Input: param (Sstring): enumer parameter name
value (Sstring): parameter value

Value: result (int): 1 if equal, else 0

Example: If ({Test_Enum File_Type "PDB"})

Error: param is not an enumerated type
value does not occur in param

Textport

Raise the textport window in the window stack, making it visible. Useful if you are printing multiple lines of output to the textport.

Syntax: Textport display_status

Input: display_status (boolean): ON / OFF
ON: pop the textport
OFF: push the textport (default)

Trigger

Make a parameter the trigger. When the trigger is filled by a pick, value_aid or explicit "Enter", the command executes. If no explicit trigger is set for a macro, the last parameter is the trigger.

Syntax: Trigger param

Input: param (Sstring): parameter name

Example: Trigger index # set parameter <index> as the trigger

Trigger "" # remove trigger parameter

While

Loop until a logical test fails. The While statement has a matching End statement.

Syntax: While (Logical_Test)
statements
End

Write

Formatted write to a text file If the file is not open, Write attempts to open the file. If the file exists, Write appends to the file. If the file does not exist, it will be created.

Both the format string and expression may contain the following escape characters:

\n newline
\t tab
\\ literal backslash
\" literal quote

Syntax: Write file_name format_string expression [expression]

Input: file_name (Vlstring): data file for write
format_string (Vlstring): user specified format string
expression (Vlstring): variable, constant, expression

Value 1: if successfully executed
0: on failure

Error: Invalid format string
Unable to open user file_name
Invalid expression

Output Format
The format_string used by the Printf and Write statements contains constants and specifications to format output. The specifications are percent signs (%) and one of the following character combinations:

[n]s: string conversion. If precision specification n is not given, then the converted value is the sequence of characters in the string up to but not including the terminating null character. If a precision specification n is given, then the converted value will only be the first n characters of the string, or up to but not including the terminating null character, whichever is shorter.

[n.p]f: signed decimal floating-point conversion. The converted value consists of a sequence of decimal digits, possibly with an embedded decimal point. Precision is specified by a number following the decimal point, which is the number of digits that will appear after the decimal point in the output. If the floating-point value cannot be represented exactly in the number of digits produced, the converted value will be the result of rounding the exact floating-point value to the number of decimal places.

[p]d: signed decimal conversion. The converted value consists of a sequence of decimal digits that represent the absolute value of the argument. The converted value will have leading zeros if necessary to satisfy the precision specification.


Index of BCL Statements

Assy_Fetch_Molecule 10-39

BCL_UNIX 10-39

Break 10-39

Cell_Get_Real, Cell_Get_Int, Cell_Get_String 10-39

Cleanup_Command 10-39

Close 10-40

Command 10-40

Condition 10-40

Constant 10-40

Continue 10-41

Def_Enum, Def_Enum_Sorted, Def_Enum_Unique 10-41

Def_List, Def_List_Sorted, Def_List_Unique 10-42

Define_Macro 10-41

Define_Menu 10-41

Define_Module 10-41

End_Macro 10-42

Fgets 10-42

ForEach 10-43

FullScreen 10-43

Get_Boolean, Get_Integer, Get_Coord, Get_Real, Get_Sstring, Get_Lstring,
Get_Vlstring, Get_Ident, Get_Enum 10-43

Goto 10-44

If 10-44

Make_File_List 10-45

Message_Print_Error 10-45

Param_Add_File_List 10-45

Param_Comment 10-45

Param_New_Column 10-46

Param_Pack 10-46

Param_Set_Style 10-46

Place_Valuator 10-46

Preview_Command 10-47

Preview_Function 10-47

Print 10-47

Printf 10-47

Prop_Exists 10-48

Prop_Get_Arr_Bool, Prop_Get_Arr_Int, Prop_Get_Arr_Float,
Prop_Get_Arr_Str 10-48

Prop_Get_Bool, Prop_Get_Int, Prop_Get_Float, Prop_Get_Str 10-48

Prop_Register 10-49

Prop_Remove 10-49

Prop_Set_Bool, Prop_Set_Int, Prop_Set_Float, Prop_Set_Str 10-50

Read 10-50

Remove_Enum 10-51

Return 10-51

Run_Bkgd_Job 10-52

Screen_Update 10-52

Set_Boolean, Set_Integer, Set_Coord, Set_Real, Set_Sstring, Set_Lstring,
Set_Vlstring, Set_ident, Set_Enum 10-53

Set_Param_Pick 10-54

Set_Rand 10-55

Set_Random 10-55

Set_SideBlock 10-55

Set_Slider 10-55

Setv_Boolean, Setv_Integer, Setv_Coord, Setv_Real, Setv_Sstring,
Setv_Lstring, Setv_Vlstring, Setv_Ident, Setv_Enum 10-52

Setv_Focus 10-53

Setv_Precision 10-53

Setv_Trigger 10-53

Size_List 10-56

Switch 10-56

System_Fetch_Assy 10-56

System_Fetch_Atom 10-57

System_Fetch_Mol 10-57

System_Fetch_Mono 10-57

System_Fetch_Object 10-57

System_Fetch_Sketch 10-57

Test_Boolean 10-57

Test_Enum 10-58

Textport 10-58

Trigger 10-58

While 10-59

Write 10-59




Last updated December 17, 1998 at 04:28PM PST.
Copyright © 1998, Molecular Simulations Inc. All rights reserved.