Macro Processing Manual - FactSage 7.1

1. Introduction
2. Macro Commands
3. Saving the Equilib file
4. Creating a Macro File
5. Running the Macro File

6. Macro Variables, Functions and Commands
7. Equilib Macro Files
8. Phase Diagram Macro Files
9. Applications
10. Batch Processing - Running Equilib in the Background

11. Summary of All Macro Variables, Functions and Commands
1. Introduction

Macro Processing is an advanced feature intended for experienced users.  It enables you to run Equilib (or Phase Diagram) automatically as a background job and execute commands stored in a macro (*.mac) file.  The macro processor can load an Equilib (Phase Diagram) file, calculate the equilibrium (Phase Diagram), store the results (figure) in various formats, go on to the next file, and so on.  It is useful for treating large and lengthy calculations during your absence (e.g. overnight, weekend) and can also be used for special applications that are not easily performed within the Equilib (Phase Diagram) modules.

For example you can use the macro to read input reactant amounts, select the species, define the product T and P, etc. from say an Excel spreadsheet, perform the usual Equilib calculation, then direct the results to a text file, Excel spreadsheet, etc. in any format you define.

As a simple example of Macro processing go to the Equilib Reactants Window and click on 'File > Macro processing > Edit Macro ..' and click on the 'Macros Directory'. Select the file EquiEx_List_Results.mac. This is an example of a macro file used in Macro processing.

Now run the macro - in the Reactants Window click on 'File > Macro processing > Run Macro ..'. When asked questions use the default answers. When done look at the output in the Equilib Results Window and compare with the text file (Dummy.txt) that you see in the background.

You may display the results for any of your stored Equilib calculations - simply provide the full file name (ex: c:\FactSage\EQUI1234.dat) when asked to 'Enter the name of an Equilib file' .

2. Macro Commands

A macro file has 4 principal commands: OPEN, CALC, SAVE and SHOW

For Equilib calculations you can open (OPEN) a previously stored system (EQUI*.dat file), calculate (CALC) the equilibrium, and then save (SAVE or SHOW) the results in a results (*.res), text (*.txt), figure (*.fig), tabular (*.tab), Excel (*.xls) file and Xml (*.xml) files.

For Phase Diagram calculations the same OPEN and CALC commands are available, but the results must to stored (SAVE and SHOW) in a figure (*.fig) file.  
 
Because macro processing is mainly used in Equilib calculations, most of this article deals with the Equilib module.  Examples of Phase Diagram macro files are given at the end - see 8. Phase Diagram Macro Files.

The following 7 lines illustrate the contents of a simple Equilib macro file - comments following '//' are ignored in the macro processing:


OPEN EQUI1234.DAT       // Load the Equilib File 1234
CALC                    // and calculate the equilibrium.
SAVE EQUI1234.TXT       // Save results in EQUI1234.Txt
SHOW EQUI1234.TAB       // Save results & display spreadsheet EQUI1234.tab
SHOW EQUI1234.XML       // Save results & display in XML format
SAVE MIXT1234.DAT GAS   // Save computed gas phase in a MIXT*.DAT stream 
END                     // Terminate the macro processing.

3. Saving the Equilib file

Before you create and run a macro you need a valid Equilib calculation stored in an EQUI*.DAT file. For simplicity we will use the same Equilib example that is already stored on your PC.  

Load the Equilib file 'Slide Show Example #6':
- in the Reactants (or Menu) Window, click on 'File > Directories ..>
Slide Show Example' and then load File 006 'Adiabatic flame ...'
  
This is a simple <1-A> CH4(g) + <A> O2(g) flame temperature calculation.  

Note the following:
Reactants Window:
        - 'initial conditions' is checked and the initial T(K) = 298.15.
Menu Window:
- possible products are an ideal gas phase and pure solids
- <A> varies from 0 to 1.0 in steps of 0.05 (i.e. 21 calculations)
- the product T(K) is not specified (i.e. it will be calculated)
- the reaction is adiabatic - Delta H = 0.

Click on 'Calculate >>' and this generates a Results Window with 21 pages.   Note the maximum product T(K) (approx. 3060 K) is at <A> = 0.65 (page 14) since this corresponds to the predominant stoichiometric reaction:   1 CH4 + 2 O2 -> 2 H2O + CO2.

Create a plot of T(K) versus <A>:
- in the Results Window click on 'Output > Plot > Plot Results'.
- in the Results Processor Window:
       Axes frame: click on 'Axes'
        select Y-Variable -> T(K)  (max = 3250, min = 300)
select X-Variable -> Alpha (max = 1, min = 0)
    Graph frame: click on 'Plot'
If you wish you can change the axes and type of figure.
Note you can save the Figure (click on 'File > Save as ..>)
Close the Figure and Plot Windows when finished.

Create an Equilib Results spreadsheet:  
- in the Results Window click on 'Output > Save or Print > Save or Print as ... '
Output Frame:
- select 'Open Spreadsheet', click on 'Spreadsheet setup ..'.
      Spreadsheet Setup:
        System Properties:  (3) -Page-, <Alpha>, T(K)
Species: Select..   (5) O2(g), H2O(g), CO(g), CO2(g), C(s)
Species Properties: (2) Mole and activity.
If you wish you can change the spreadsheet setup.
Click on 'OK' to close the Spreadsheet Setup
    Click on 'OK' to close the Output Frame and create a spreadsheet.
Note you can save the spreadsheet (click on 'File > Save as ...')
Close the Equilib Results spreadsheet when finished.

Return to the Equilib Menu Window.  

Now you are going to save the system in an Equi*.dat file - but first make sure that your default directory is the same as the FactSage directory. For example, click on the drop-down menu 'Help > FactSage version, directories ...' and check the FactSage directory is the same as My Files directory, typically c:\factSage - to change click on 'File > Directories > Change ...' .

Save in the file Equi1234.dat:
- click on 'File > Save as > '
specify: File 1234
comments: 'Adiabatic flame temperature'
Click on 'Open' and you should see File 1234 ' Adiabatic flame ...'

All the above operations can be performed by a simple Macro File as follows.



4. Creating a Macro File

Create a new macro file called 'MyMacro.mac':
     Go to the Reactants Window.
Click on 'File > Macro processing > Edit macro ..> .. 'MyMacro.mac'
       and open a new file 'MyMacro.mac'

Copy and paste the following 7 lines into 'MyMacro.mac'


OPEN EQUI1234.DAT
CALC  
SHOW EQUI1234.TXT
SHOW EQUI1234.FIG
SHOW EQUI1234.TAB
SHOW EQUI1234.XML
END


and save when you are finished.



5. Running the Macro File


Run the Macro 'MyMacro.mac':
       Go to the Reactants Window.
       Click on 'File > Macro processing > Run macro ..>  'MyMacro.mac'.
       and then click on 'OK'.  

When finished check the contents of the newly created EQUI1234.txt, .fig and .tab files.



6. Macro Variables, Functions and Commands
6.1 Macro variables %Variables - simple %variables, %DIR, %1, %2, ... %9, VARIABLE, DIM, ASK, ASK_OK, ASK_BROWSE
6.2 Macro functions $Functions - for string manipulation, output formatting, mathematical functions & expressions, file managing
6.3 Macro commands for increments and cycles - STEP, FACTOR, LOOP
6.4 Macro commands for simple program flow - MARK, GOTO, IF ... GOTO and END
6.5 Macro commands for branched program flow - IF ... THEN ... ENDIF, DOCASE ... ENDDO

6.6 Macro commands for advanced features - ERROR_OFF, ERROR_ON, RUNMACRO, SHELL, SHELL_EXECUTE, SHELL_WAIT ...
6.7 Macro commands for reading and writing text and ini files - READ, WRITE, APPEND, TABS ...
6.8 Macro commands for manipulating files - COPY, NAME and KILL
6.9 Macro commands for Excel Worksheets and Text Spreadsheets - linking via OLEn
6.10 Macro user-defined $Functions and Procedures - FUNCTIONS ... END FUNCTIONS, PROCEDURES ... END PROCEDURES

6.11 Macro 1-D and 2-D %Variables - tables and arrays, REDIM, $ENUM
6.12 Macro thermochemical variables - $variables$, SET
6.13 Macro SET Commands - for data search and options, reactants, species selection, output formatting, plotting, etc.
6.14 Macro Windows commands - LOG_OFF, REBOOT, SHUTDOWN
6.15 Macro display commands - REM, SHOW, HIDE, HIDE_MACRO and MSGBOX

6.16 Macro Phase Diagram commands - FIGURE, SUPERIMPOSE, VIEWER
6.17 Macro Debugging commands - DEBUG /ON, DEBUG 'caption', DEBUG /DEL

In addition to the four principal commands (OPEN, CALC, SHOW and SAVE) other commands, functions and variables are available.

1. Notes:

'word' 
is a character string (use " " if there are spaces)
       2 examples:   c:\FactSage    "c:\FactSage\My  Results"

'number' is a integer, floating point or scientific number
       5 examples:    0    -101   12.34   1.234e-10   -5.678e+100  

'string' is one or more words separated by spaces
       1 example:   this is a string

'%variable' (or %var for short) is a word starting with the '%' character and denotes a variable to which you can assign a value (word, string, number)
     ex: %1 %2 ... %9  %DIR  or user-defined variable (see VARIABLE).

'$variable$' - denotes a computed or defined thermochemical variable (temperature, activity, moles,. ..) that cannot be modified by you
      ex: $E_ET$  (temperature),  $E_sn2$ (moles of species 2),   $R_q3$ (quantity of reactant 3)

'$function' - denotes a function for displaying system values, manipulating strings, formatting output and mathematical functions, etc.
      ex: $DATE     $FORMATE(12,4,1.2345678)     $MATH((5!-(2-5)^2)/(sqr(abs(2^4-3^5)))    $LOG10(1.234e-10)     $EXIST(My.dat)

[] denotes optional.
      ex: %var = 'FirstValue' TO 'LastValue' [STEP 'IncrementValue']
         %1 = 1 TO 10      %2 = 1 TO 10 STEP 2


() denotes alternatives.
      ex: SET ESTIMATE T (P V ALPHA) 'value'
         SET ESTIMATE T 1000      SET ESTIMATE ALPHA 0.5


6.1 Macro %Variables - simple %variables, %DIR, %1, %2, ... %9, VARIABLE, DIM, ASK, ASK_OK, ASK_BROWSE


Any word starting with the '%' character is called %variable (or %var for short).  For example %1, %2 ... %9 are nine %variables recognized by the program.  You can assign a value (word, string or number) to a %variable.  %DIR is reserved for the default directory.   Other %variables may be declared at the beginning of the program by the VARIABLE or DIM statement.

Macro variables may be embedded in the macro processing.   For example if the value of the variable %DIR is c:\MyDir\, the value of %1 is Output , then the command
     SAVE %DIR%1.dat      is the same as     SAVE c:\MyDir\Output.dat

VARIABLE, DIM :

VARIABLE '%var1' '%var2' '%var3' '%var4'
          // Use VARIABLE or DIM to declare the list of variables in
          // addition to %DIR, %1 ... %9. 
%var  =  'value' 
          // This is how you assign a value (i.e. word, string, number)
          // to %var. Use quotes "" if 'value' contains spaces.  
          // The '=' is optional
          // Use REDIM (see later on) to modify and redeclare a list of variables.

Examples:

DIM  %Path\ %ResultsDir %Page %TextFile
                        // Declare 4 variables. "\" is for visual effect

%Page = 2               // %Page is '2'.

%Path\ = "C:\My Files\" // %Path\ is 'C:\My Files\'

%ResultsDir = "C:\My Files\My Results\"  
                        // %ResultsDir is 'C:\My Files\My Results\'

%ResultsDir = "%Path\My Results\"         
                        // %ResultsDir is 'C:\My Files\My Results\'
                        // - same value as the previous line.

%TextFile = %Path\Input.txt   
                        // %TextFile is 'C:\My Files\Input.txt'         

ASK, ASK_OK, ASK_BROWSE:

%var  =  'value' ASK 'description'  
             // Ask the user for the value of %var 
             // - the default value is 'value'.  

%var  =  ASK_OK 'question or statement'  
             // Ask the user to agree by clicking on an 'OK' button
             // - the result is 'OK' or '0'

%var  =  'default file name' ASK_BROWSE 'file masks | filters' 'statement'  
             // Ask the user to enter a file name using the Windows browser
             // - the result is the name of the file

Examples:

%Path\ = "C:\My Files\" ASK Enter the name of My Files directory 
             // Ask user for the value of %Path\ 
             // - the default is 'C:\My Files\'
%1 ASK_OK Do you wish to keep My Files directory as %Path\? 
             // if he agrees then %1 = 'OK' else '0'

%1 = "C:\Factsage\Equi1.dat" ASK_BROWSE "(Equi*.dat)|Equi*.dat" "Select any Equi*.dat file "
             // Ask user to select an Equi*.dat file - the default is C:\Factsage\Equi1.dat
             // %1 is the name of the file he enters

%DIR:
  // %DIR is the default directory or folder and it is automatically defined by the program.
  // You may change the value of %DIR. Directory and folder are the same thing.

%DIR  =  'string' // Set the default directory for all the files.
%DIR  =  'string' ASK 'description'
                  // Ask for the directory - default setting is 'string'
%DIR  =  $FSDIR   // set default directory to the FactSage directory $FACTSAGE_DIR\
                  // where FACTWIN.INI resides (typically C:\FactSage\)

Examples:
%DIR = C:\MyFiles\  // The default file directory is 'c:\MyFiles\'
                    // hence, 'OPEN EQUI1234.DAT' is the same as
                    //        'OPEN %DirEQUI1234.DAT' and
                    //        'OPEN C:\MyFiles\EQUI1234.DAT'.

%DIR  =  $FSDIR     // $FSDIR or $FACTSAGE_DIR\ is the FactSage directory.
                    // In most cases the default directory %DIR is now 'C:\FactSage\'

%DIR = %DIR ASK Enter the default directory for all files:   
       // Ask for the directory - default setting is the current value

%DIR = "c:\My Dir\" ASK Enter the default directory for the files:   
       // Ask for the directory - default setting is 'c:\My Dir\'.

OPEN Equi1.dat         // Open Equilib file in default directory DIR%
CALC                   // calculate the equilibrium, and then
SAVE %Path\Mytext.Txt  // save results in 'C:\My Files\MyText.txt'.

6.2 Macro $Functions

a) String manipulation
- $ASC, $CHR, $LCASE, $UCASE, $LEFT, $RIGHT, $MID, $REPLACE

b) Output formatting
- $FORMATE, $FORMATF, $FORMATG, $FORMATI

c) Mathematical functions
- $ABS, $EXP, $LN, $LOG10, $FIX, $INT, $RND, $RND_INT, $MIN, $MAX, $MINI, $MAXI, $MEAN, $MEDIAN, $SORTDEC, $SORTDECI, $SORTINC, $SORTINCI

d) Mathematical expressions
- $MATH

e) File managing
- $EXIST, $FILE_DIR, $FILE_SHORTDIR, $FILE_NAME, $FILE_BYTES, $SCAN_DIR

f) Chemical functions
- $ELEMENT, $MOLWT, $CONSTANT

g) System functions
- $BLANK, $CHEMSAGE_DIR\, $COMMAND, etc.

Most $Functions have arguments contained within the parentheses, (). The arguments are separated by spaces or commas and may be a %variable, a thermochemical $variable$, but not another $function. A $function may appear anywhere on the line (except at the beginning which contains either a %variable or macro command) and the line may have several $functions.

An example of most $functions is given in the macro file EquiEx_List_Functions.mac.

a) String manipulation - $ASC, $CHR, $LCASE, $UCASE, $LEFT, $RIGHT, $MID, $REPLACE


$ASC('character')                // Ascii value of a character. 
                                 // $ASC(1) -> 48 ; $ASC(A) -> 65 ; $ASC(a) -> 97

$CHR('value')                    // Character from its ascii value.
                                 // $CHR(48) -> '1' ; $CHR(65) -> 'A' ; $CHR(97) -> 'a'

$LCASE('string')                 // Lower case characters of 'string'. 
                                 // $LCASE(I Love You)   -> 'i love you'

$UCASE('string')                 // Upper case characters of 'string'.
                                 // $UCASE(I Love You)   -> 'I LOVE YOU'

$LEFT('value','string')          // 'value' left characters of trimmed 'string'
                                 // $LEFT(3,I Love You)  -> 'I L'

$RIGHT('value','string')         // 'value' right characters of trimmed 'string'.
                                 // $RIGHT(3,I Love You) -> 'You'

$MID('value1','value2','string') // starting at character 'value1' it returns 
                                 // 'value2' characters of trimmed 'string'.
                                 // $MID(3,4, I Love U ) -> 'Love'

$REPLACE('string','old','new')   // in 'string' replace all occurences of 'old' by 'new'
                                 // $REPLACE(your house and your dog,your,my)
                                 // -> 'my house and my dog'
b) Output formatting - $FORMATA, $FORMATE, $FORMATF, $FORMATG, $FORMATI

See EquiEx_List_Functions.mac for examples of $FORMATA, $FORMATE, $FORMATF, $FORMATG and $FORMATI

   
$FORMATA('m' 'string')    // Am character format
                          // $FORMATA(12 Hello World)        -> ' Hello World'
                          // $FORMATA(12        Hello World) -> '       Hello'

$FORMATE('m' 'n' 'value') // Em.n scientific format
                          // $FORMATE(12,4,1.2345678)    -> '  0.1234E+01'

$FORMATF('m' 'n' 'value') // Fm.n numerical format
                          // $FORMATF(12 4 1.2345678)    -> '      1.2345'

$FORMATG('m' 'n' 'value') // Gm.n general format
                          // $FORMATG(12,4,1.2345678)    -> '      1.2345'
                          // $FORMATG(12,4,123.45678e20) -> '  1.2345e+22'

$FORMATI('m' 'value')     // Im   integer format
                          // $FORMATI(12,1.2345678)      -> '           1'

Examples:

c) Mathematical functions - $ABS, $EXP, $LN, $LOG10, $FIX, $INT, $RND, $RND_INT, $MIN, $MAX, $MINI, $MAXI, $MEAN, $MEDIAN, $SORTDEC, $SORTDECI, $SORTINC, $SORTINCI

Simple mathematical functions with one or more arguments - combined or embedded expressions (ex: $ABS($LN('value')) are not permitted.
$ABS('value')     // Absolute value - abs()
                  // $ABS(-1.2)    -> 1.2    
$EXP('value')     // Exponential (or antilogarithm) value - exp()
                  // $EXP(100)     -> 2.68811...E+43  
$LN('value')      // Natural logarithm - ln()
                  // $LN(100)      -> 4.60517...
$LOG10('value')   // Logarithm to base 10 - log10()
                  // $LOG10(100)   -> 2
$INT('value')     // Integer portion of a number
                  // $INT(4.2)     ->  4  
                  // $INT(-4.2)    -> -5  
$FIX('value')     // First negative integer greater than or equal to the number
                  // $FIX(4.2)     ->  4  
                  // $FIX(-4.2)    -> -4  

$RND('min' 'max')
        // Random floating point number in the range min to max, where min >= 0 and max > min.
        // $RND(0,1)         ->  random floating point number in the range 0 to 1  
        // $RND(1,100.234)   ->  random floating point number in the range 1 to 100.234  

$RND_INT('min' 'max')
        // Random integer number in the range min to max, where min >= 0 and max > min.
        // $RNDINT(0 10)     ->  random integer number in the range 0 to 10  
        // $RNDINT(1 100)    ->  random integer number in the range 1 to 100  

$MIN('value1' 'value2' ...)        // Minimum value in the list
$MINI('value1' 'value2' ...)       // Item that has the minimum value in the list
        // $MIN(0,-1.5,2,3)  ->  -1.5
        // $MINI(0,-1.5,2,3) ->  2

$MAX('value1' 'value2' ...)        // Maximum value in the list
$MAXI('value1' 'value2' ...)       // Item that has the maximum value in the list
        // $MAX(0 -1.5 2 3)  ->  3
        // $MAXI(0 -1.5 2 3) ->  4

$MEAN('value1' 'value2' ...)       // Average value in the list
$MEDIAN('value1' 'value2' ...)     // Median value in the list
        // $MEAN(1 15 2)     ->  6
        // $MEDIAN(1 15 2)   ->  2
        
$SORTDEC('value1' 'value2' ...)    // Sort list by decreasing values
$SORTDECI('value1' 'value2' ...)   // Indexes of the sorted items
        // $SORTDEC(1.5 100 50 -50)   ->  '100 50 1.5 -50'
        // $SORTDECI(1.5 100 50 -50)  ->  ' 2  3  1    4'
$SORTINC('value1' 'value2' ...)    // Sort list by increasing values
$SORTINCI('value1' 'value2' ...)   // Indexes of the sorted items
        // $SORTINC(1.5 100 50 -50)   ->  '-50  1.5  50  100'
        // $SORTINCI(1.5 100 50 -50)  ->  ' 4   1    3   2'
Example:
VARIABLE %X(4) %Y(4) %I(4)
%X = 1.5 100 50 -50  // %X(1)=1.5 %X(2)=100 %X(3)=50 %X(4)=-50
%Y = $SORTINC(%X)    // %Y(1)=-50 %Y(2)=1.5 %Y(3)=50 %Y(4)=100 
%I = $SORTINCI(%X)   // %I(1)=4   %I(2)=1   %I(3)=3  %I(4)=2 

d) Mathematical expressions - $MATH()

This versatile function enables you to enter a mixed expression that includes the operators, + - / * ^ \, as well the common functions abs(), ln(), log10(), exp(), cos(), sin(), tan(), acos(), asin(), atan(), fix(), int(), sqr(), cbr() and fact().

$MATH(2 - 3)                    // -> -1 
$MATH(2 * 3)                    // -> 6
$MATH(5 / 3)                    // -> 1.66666666666667
$MATH(5 \ 3)                    // -> 1
$MATH(3 ^ 4)                    // -> 81
$MATH(28-3*9+2^4/16)            // -> 2.  Same as $MATH((28 - (3*9) + (2^4)/16))
$MATH(240/fact(5))              // -> 2.  Same as $MATH(100/5!)
$MATH(cos(100)^2 + sin(100)^2)  // -> 1.  Same as (cos(100))^2 + (sin(100))^2
$MATH(log10(100))               // -> 2.  Same as $MATH(ln(100)/ln(10))
$MATH((5!-(2-5)^2)/(sqr(abs(2^4-3^5))) // ->  7.36732875875969

Example:
VARIABLE %RGas %TC %Po2 %DG0 
%Rgas = $CONSTANT(RGAS-J)    // Gas constant J/mol-K
%TC  = 1000
%Keq = 1e-5
%DG0 = $MATH(-%Rgas * (TC+273.15) * ln(%Keq)) 
                             // DG(zero) = -RTln(Keq)  J/mol 

e) File managing - $EXIST, $FILE_DIR, $FILE_SHORTDIR, $FILE_NAME, $FILE_BYTES, $SCAN_DIR

 
$EXIST('file name')       // If the file exists then $EXIST = 1 (i.e. true) else 0

$FILE_DIR('long file name')  
            // Long name of parent folder 
            // $FILE_DIR(C:\FactSage\Figures\CaO_SiO2.fig)  -> 'C:\FactSage\Figures\'  
$FILE_SHORTDIR('long file name') 
            // Short name of parent folder
            // $FILE_SHORTDIR(C:\FactSage\Figures\CaO_SiO2.fig) -> 'Figures\'
$FILE_NAME('long file name') 
            // File name of a long file name 
            // $FILE_NAME(C:\FactSage\Figures\CaO_SiO2.fig) -> 'CaO_SiO2.fig'
$FILE_BYTES('file name') 
            // Size of file in bytes
            // $FILE_BYTES(C:\FactSage\Figures\CaO_SiO2.fig) ->  '19127'
$SCAN_DIR: is similar to the Dir function in other software languages. There are two modes in using $SCAN_DIR. First with a file name mask (such *.txt, My*.fig etc.) to initiate the function and return the number of files. Then without the mask to list the short name of each files, one at a time.
$SCAN_DIR('file-mask')
            // Initiates the scan and returns the number of files or '0' if no files are found.
$SCAN_DIR()  // Lists the name of first file in the list.
$SCAN_DIR()  // Lists the name of 2nd file in the list.
$SCAN_DIR()  // and so on. '0' denotes when all files have been listed.

Example:
%1 = $SCAN_DIR(c:\FactSage\Figures\*.fig) 
        // Initiate a scan of all c:\FactSage\Figures\*.fig files.
%1 = $SCAN_DIR()  
        // Return the short name of the first file. 
%1 = $SCAN_DIR()  
        // Return the short name of the next file, and so on, until '0' when done. 

f) Chemical functions - $ELEMENT..(), $MOLWT(), $CONSTANT()

$ELEMENT_NAME('value')           // convert atomic number to an element 
                                // $ELEMENT_NAME(26) -> 'Fe'
$ELEMENT_NUMBER('name')          // convert an element to an atomic number
                                // $ELEMENT_NAME(Fe) -> '26' 
$ELEMENT_MASS('name' or 'value') // convert an element to an atomic mass
                                // $ELEMENT_MASS(26) -> '55.847'  $ELEMENT_MASS(Fe) -> '55.847'
$MOLWT('species')               // Molecular weight of a chemical species
                                // $MOLWT(H2O) -> '18.01528'
$CONSTANT('gas constant')  $CONSTANT('unit1/unit2')         
     // Gas constants and unit conversion. List of gas constants and units:-
     // Gas constant: Rgas-cal Rgas-J Rgas-L-atm
     // Energy:       J kJ mJ cal kcal Mcal Btu kWh 
     // Pressure:     bar Pa kPa atm psi mmHg torr 
     // Mass:         g gm kg tonne lb 
     // Volume:       L liter litre cc cm3 ml m3 dl CuFt Ft3 
     // $CONSTANT(Rgas-J) ->  '8.31451'     J/mol-K
     // $CONSTANT(g/lb)   ->  '453.59237'   g/lb

g) System functions - $BLANK, $CHEMSAGE_DIR\, $COMMAND, etc.

$BLANK                // ' ' (white space) - used in WRITE commands 
$CHEMSAGE_DIR\        // chemSage directory, typically 'c:\FactSage\CHEMSAGE\'
$COMMAND              // optional command line set by RUNMACRO 'file.mac' [command] 
$DATE                 // current date 
$EXAMPLES_DIR\        // examples directory, typically 'c:\FactSage\EXAMPLES\'
$FACTDATA_DIR\        // database directory, typically 'c:\FactSage\FACTDATA\'
$FACTHELP_DIR\        // help directory, typically 'c:\FactSage\FACTHELP\'
$FACTSAGE_DIR\        // directory where FACTWIN.INI resides - same as $FSDIR
$FALSE                // 0 (zero). Ex: 'IF $EXIST('file name') = $FALSE THEN GOTO END'
$FIGURES_DIR\         // figures directory, typically 'c:\FactSage\FIGURES\'
$FSDIR                // directory where FACTWIN.INI resides - same as $FACTSAGE_DIR\
$F90IO_DIR\           // fortran I/O directory, typically 'c:\FactSage\F90IO\'
$HWND                 // handle of current application
$MACFILE              // full name of the current macro file 
$MACROS_DIR\          // macros directory, typically 'c:\FactSage\MACROS\'
$PAGES                // number of pages in last calculation 
$RETVAL               // shell process returned value - see 'SHELL_WAIT'
$TEMP_DIR\            // temporary directory - environment variable defined by Windows
$TIME                 // current time
$TIME_RUN             // time passed (hh:mm:ss) since the start
$TIME_RUN_SECS        // time passed (seconds) since the start
$TIME_INTERVAL        // time passed (hh:mm:ss) since last call to $TIME_INTERVAL 
$TIME_INTERVAL_SECS   // time passed (seconds) since last call to $TIME_INTERVAL_SECS
$TRUE                 // 1 (one). Ex: 'IF $EXIST('file name') = $TRUE THEN'

  6.3 Macro commands for increments and cycles - STEP, FACTOR, LOOP
  
STEP :
   %var  =  STEP ['value'] 
              // steps up (adds) numerical %var by 'value' (default 1).  
              // i.e. %var = %var + 'value' (default 1).  Same as %var = %MATH(%var + 'value')
Examples:
%3 =  4       // %3 has the value '4' 
%3 STEP -2    // new %3 = current %3 - 2  (= 4 - 2 -> '2'). Same as %3 = %MATH(%3-2)
%3 STEP       // new %3 = current %3 + 1  (= 2 + 1 -> '3'). Same as %3 = %MATH(%3+1)

FACTOR :  
     %var  =  FACTOR 'value'    
                 // factors (multiplies) numerical %variable by 'value'
                 // i.e. %var = %var x 'value'.   Same as %var = $MATH(%var * 'value')
Example:
%4 =  10         // %4 has the value '10'
%4 = FACTOR 0.5  // new %4 = current %4 x 0.5   (i.e. %4 = '5')
                 // Same as %4 = $MATH(%4*0.5)  
LOOP : 
     // Simple LOOP in %var:  
%var  = 'FirstValue' TO 'LastValue' [STEP 'IncrementValue']
   (macro lines)  
%var LOOP // End of loop.  If %var line <> 'LastValue'
          // then go back to beginning, redefine %var and repeat.
          // A %var LOOP is always executed at least once ('FirstValue'). 
          // If STEP is undefined then '1' is assumed.  

   // Nested (embedded) LOOPs are permitted: 
%var1  = 'FirstValue1' TO 'LastValue1' [STEP 'IncrementValue1']
   %var2  = 'FirstValue2' TO 'LastValue2' [STEP 'IncrementValue2']
      %var3  = 'FirstValue3' TO 'LastValue3' [STEP 'IncrementValue3']
         (macro lines)  
      %var3 LOOP         // End of %var3 loop.
   %var2 LOOP            // End of %var2 loop.
%var1 LOOP               // End of %var1 loop.

Examples:
%3 =  2 TO 6 STEP 0.5    // %3 has 9 values:  2 2.5 3 3.5  ... 6  
   (macro lines)         // These lines will be executed 9 times
   ...                   // unless they contain a GOTO statement. 
%3 LOOP                  

%3 =  2 TO 4             // %3 has 3 values: 2 3 and 4  
   %4 = 1 TO -1 STEP -2  // %4 has 2 values: 1 and -1 
     (macro lines)       // These lines will be executed 6 times
     ...                 // unless they contain a GOTO statement. 
   %4 LOOP
%3 LOOP  
  
6.4 Macro commands for simple program flow: MARK, GOTO, IF... GOTO and END

These commands control the program flow within the macro.
MARK:

MARK 'word'    // a marker used with GOTO 'word'.
               // A MARK statement cannot be inside IF ....ENDIF
               // nor in a LOOP or DOCASE.  

GOTO:

GOTO 'word'    // jump to the line MARK 'word'.
               // A GOTO statement cannot be inside IF ....ENDIF
GOTO END       // jump to the end i.e. quit.

IF ... GOTO: (simple operator)

IF 'value1' '?' 'value2' GOTO 'word'  
          // An IF...GOTO line must have 6 words separated by spaces. 
          // Word #1 must be IF and word #5 must be GOTO. 
          // IF statement - if true go to line MARK 'word'.
          // Word #3, '?', must be one of the 6 logical operators:
          //   =   <   >   <>   <=   >=
Examples:
MARK Top  // A marker called 'Top'
   (macro lines) 
IF %3 < 10 GOTO Top 
          // If the value of %3 is less than 10 then jump to the 
          // line 'MARK Top'.
          // Note '%3<10' is undecodable (no spaces).

END:

END       // End of the macro processing.
          // All comments after 'END' are ignored .
Example:
GOTO END  // Jump to the end i.e. quit.

IF ... GOTO: (multiple operators AND or OR)

IF 'val1' '?' 'val2' OR  'val3' '? ' 'val4' OR ...  GOTO 'mark'
          // One or more 'OR' operators are permitted.

IF 'val1' '?' 'val2' AND 'val3' '? ' 'val4' AND ... GOTO 'mark'
          // One or more 'AND' operators are permitted.
          
Examples:
IF 1% < 1 OR %1 > 100 GOTO END
          // If %1 is outside the range 1 - 100 then go to the END

IF 1% >= 1 AND 1% <= 10 AND %2 > %1 GOTO TOP
          // If %1 is within the range 1 - 10 and %2 is greater than %1
          // then jump to the line MARK TOP

IF 1% > 1 AND 1% < 10 OR %2 > %1 GOTO TOP
          // Error! Mixed AND with OR is NOT permitted.

6.5 Macro Commands for branched program flow: IF...THEN ... ENDIF, DOCASE ... ENDDO

These commands offer multiple options to the program flow within the macro.
IF ... THEN to ENDIF: 

IF 'value1' '?' 'value2' THEN      // The first statement, '?' may
   (macro lines)                   // contain 'AND' or 'OR' operators.
   ...
ELSEIF 'va1ue3' '?' 'value4' THEN  // One or more ELSEIF statements
   (macro lines)                   // are optional.
   ...
ELSE                               // One ELSE statement is optional.
   (macro lines)
   ...
ENDIF                              // ENDIF statement must be present

Example:

MARK TOP
%1 0 ASK Enter the file number (1 to 9999), enter 0 to QUIT.
                 // Prompt the user to enter the file number, %1

IF %1 >= 1 AND % 1 <= 9999 THEN // if %1 is in the range 1 to 9999
   OPEN EQUI%1.DAT              // then open the Equi file 
   CALC                         // and calculate 
   SAVE EQUI%1.TXT              // and save
   GOTO TOP                     // and repeat.
ELSEIF %1 = 0 THEN              // i.e. %1 is 0 so quit
   GOTO END
ELSE                            // try again. 
   GOTO TOP
ENDIF
    
// Note: nested IF statements not permitted
// that is, an IF .. ENDIF can NOT contain another IF .. ENDIF
// or contain an IF ..... GOTO ... 

DOCASE ... CASE to ENDDO:

DOCASE %var    // The first statement defines the %variable
CASE 'val1' ['val2' 'val3' ...]
               // If %var has value 'val1' (or 'val2' or 'val3'..)        
   ...         // execute these macro lines.
CASE 'val4' ['val5' 'val6' ...] 
               // If %var has any one of these values      
   ...         // execute these macro lines.
CASE 'val1' TO 'val2' 
               // If %var is in the range 'val1' to 'val2'       
   ...         // execute these macro lines.
CASE IS 'operator' 'val1' // where operator is one of < > <> >= or <= .  
               // If %var satisfies the condition 
   ...         // execute these macro lines.
CASE  ... etc
CASE ELSE      // Optional CASE ELSE - if none of the above are true
    ...
ENDDO          // ENDDO statement must be present

DOCASE Example 1:

MARK TOP
%1 = 0 ASK Do you want 1 text, 2 results or 3 xls file (enter 1 to 3) or -1 to quit.
                 // Prompt the user to enter the type of file
DOCASE %1
CASE 1           // The CASE statement has a fixed value (not %var)
   %2 = EQUILIB.TXT 
CASE 2
   %2 = EQUILIB.RES
CASE 3
   %2 = EQUILIB.XLS
CASE -1          // Quit.
   GOTO END 
CASE ELSE        // Invalid, try again. 
   GOTO TOP
ENDDO            // End
SAVE %2          // Save the file.

DOCASE Example 2:

DO CASE %1
CASE 0 1 2       // If %1 has the value 0, 1 or 2
   (macro lines) 
CASE 3 TO 50.5   // If %1 is in the range 3 to 50.5
   (macro lines) 
CASE IS <= -100  // If %1 is less than or equal to -100
   (macro lines) 
CASE IS <> 1000  // If %1 is not equal to 1000
   (macro lines) 
CASE ELSE        
   (macro lines)
ENDDO             

// Notes:  Nested DOCASE .. ENDDO statements not not permitted
// that is, a DOCASE .. ENDDO can NOT contain another DOCASE .. ENDDO. 
// Also, the CASE statement can NOT contain a %variable.

6.6 Macro commands for advanced features: ERROR_OFF, ERROR_ON, RUNMACRO, SHELL, SHELL_EXECUTE, SHELL_WAIT, WAIT, PAUSE, WRITE, APPEND;    Variables: $COMMAND, $RETVAL
ERROR_OFF, ERROR_ON:

ERROR_OFF  or  ERROROFF  // suppress error handling (see ERROR_ON) - use with caution!
ERROR_ON   or  ERRORON   // resume error handling (see ERROR_OFF) - this is the default setting.

RUNMACRO:

RUNMACRO 'filename.mac' [command] // Quit the current application and run a new macro 
                                  // and define an optional command line (see $COMMAND)

Example:
RUNMACRO $MACROS_DIR\PhasEx_Superimpose_Figs.mac  %Path\%Name 
              // Quit current macro, load PhasEx_Superimpose_Figs.mac located in 
              // the Macros directory and pass the command %Path\%Name  (see $COMMAND)   
              // - this example is stored in PhasEx_Al-Mg-Sr-liquidus.mac

SHELL:

SHELL 'string' // Execute commands stored in the 'string'. 

Example:
%4 = C:\Dummy\
SHELL Notepad %4MyText.Txt 
               // Open C:\Dummy\MyText.txt with Notepad.
Example:
SHELL %4MyBat.bat [%6] [%7] ...
               // Runs the batch file c:\Dummy\MyBat.bat 
               // with optional words %6, %7 ... 

SHELL_EXECUTE:

SHELL_EXECUTE 'filename'// Open doc, fig, txt, xls, etc. file in the default Windows application.

Example:
%4 = C:\Dummy\  
SHELL_EXECUTE %4MyText.Txt  // Open C:\Dummy\MyText.txt with Notepad or WordPad etc.
SHELL_EXECUTE %4MyText.Doc  // Open C:\Dummy\MyText.txt with Word
SHELL_EXECUTE %4MyText.Xls  // Open C:\Dummy\MyText.txt with Excel
SHELL_EXECUTE %4MyText.Xlm  // Open C:\Dummy\MyText.xlm with Fact-XLM

SHELL_WAIT:

SHELL_WAIT 'string' // Execute command and wait until done.
                    // Return values are stored in $RETVAL.
Example:
SHELL_WAIT MyExec.exe // Run MyExec.exe and wait. 
                      // When done store the return value in $RETVAL.

WAIT: (or PAUSE)

WAIT           // wait for the user to click 'OK' to continue
WAIT 'number'  // wait 'number' seconds before continuing

Example:
PAUSE 2.5      // processing waits 2.5 seconds and then proceeds (same as WAIT 2.5)
         
PAGE_KEEP, PAGE_NEW:

PAGE_KEEP  or  PAGEKEEP   
               // Keep results from previous CALC(s) 
               // and append current CALC results as new pages.
PAGE_NEW  or  PAGENEW 
               // (Default setting) - negates option  PAGE_KEEP

POST_MESSAGE, SEND_MESSAGE:

POST_MESSAGE 'TargetHwnd' 'string'  or  POSTMESSAGE ...
               // post message in another application
POST_MESSAGE 'TargetHwnd' FILENAME 'Filename'
               // post file contents in another application.

SEND_MESSAGE 'TargetHwnd' 'string'  or  SENDMESSAGE ...
               // send message to another application
SEND_MESSAGE 'TargetHwnd' FILENAME 'Filename'
               // send file contents to another application.

LOAD_ONLY:

LOAD_ONLY  or  LOADONLY
              // loads (opens) Equi*.dat (or Phas*.dat) without calculating.  Units $R_*$, Database $D*$, 
              // Reactant $U_*$ and Menu $M_*$ Window variables are defined (but not Equilibrium $E_?*$)

6.7 Macro commands for reading and writing text & ini files - READ, CLOSE, REWIND, WRITE, APPEND, APPEND FILENAME, VIEWTEXT FILENAME, TAB_LINE, TAB_WORD, TAB_COL, TAB_JUSTIFY
Reading text files - READ, CONTENTS, LINE, WORD, WORDLINE, CLOSE, REWIND, VIEWTEXT

%var = 'TextFileName' READ  
           // variable is the line read from the text file
           // If file is missing or line is empty then %var = '0'.
%var = 'TextFileName' READ CONTENTS
           // variable is text file contents including {CR} {Tab} etc.
%var = 'TextFileName' READ LINE
           // variable is the line read from the file (same as READ)
%var = 'TextFileName' READ LINE 'n'
           // variable is line 'n' of the file ('1' is the first line)
           //- next READ (or READ LINE or READ WORD) is foe line 'n+1'
%var = 'TextFileName' READ WORD
           // variable is first word of the line read from the file
%var = 'TextFileName' READ WORD 'm'
           // variable is word 'm' (1 - 9) of the line from the file
           // - 'READ WORD' is the same as 'READ WORD 1'
%var = 'TextFileName' READ WORDLINE 'm' 'n'
           // variable is word m of line n in the text file
%var = ' TextFileName ' READ LINEWORD 'n' 'm'
           // variable is word m of line n in the text file

CLOSE 'string'          // Used with READ - the next READ goes back and reads 
REWIND 'string'         // line 1 from 'string'.  REWIND is the same as CLOSE.
VIEWTEXT 'Filename.txt' // display the contents of a text file

Writing text files - WRITE, APPEND, APPEND FILENAME, TAB_LINE, TAB_WORD, TAB_COL, TAB_JUSTIFY:

WRITE 'TextFileName' 'string' // Store 'string' in the text file
             // - any current contents will be replaced. 
APPEND 'TextFileName' 'string' 
             // Write 'string' to the end of the text file
APPEND 'TextFileName1' FILENAME 'TextFileName2' 
             // Append file 2 to the end of file 1.

APPEND 'TextFileName' TAB_LINE(=)  
             // - underline title (previous line) with a '=' (or other character - * ~ etc.)  
APPEND 'TextFileName' TAB_WORD(-) 
             // - underline words (previous line) with a '-' (or other character = * ~ etc.) separated by spaces

APPEND 'TextFileName' TAB_COL('value 1' 'value 2' 'value 3' ....) 
             // Sets tabs for all subsequent APPEND %FILE output - useful for aligning tabular output
APPEND 'TextFileName' TAB_JUSTIFY(<)  
             // Left-justify words for all subsequent APPEND %FILE output.
             // TAB_JUSTIFY(>) - right justify all words, TAB_JUSTIFY(^) - center all words
             // TAB_JUSTIFY(^ < ^ > ...) - mixed mode, one tab per word. 
APPEND 'TextFileName' TAB_COL(0) 
             // Cancel tabs.
Examples:
APPEND c:\Dummy\Summary.txt Return value from MyExec.exe is $RETVAL
      // and append ex: 'Return value from MyExec.exe is O'
APPEND c:\Dummy\Summary.txt FILENAME MyText.Txt
      // and append to the end of 'c:\Dummy\Summary.txt' the contents 
      // of the file 'MyText.txt'.

APPEND 'file' TAB_COL(5 10 20 35)  
             // In 'file' set tabs at columns 5, 10, 20, 35 ...
APPEND 'file' 1 2 3 4  
             //    1    2         3              4                    
APPEND 'file' 1.1 22.2 333.3 4444.4  
             //    1.1  22.2      333.3          4444.4
APPEND 'file' TAB_COL(0)  
             // Cancel tabular output
             // See EQUIEx_TABS.mac for examples of TAB_LINE(), TAB_WORD(), TAB_COL() and TAB_JUSTIFY().

Ini files - READ_INI, WRITEINI

%var READ_INI 'IniFileName' 'Section' 'Variable' 'Default'
                // %var value read from *.ini file (see WRITEINI)
                
WRITEINI 'IniFile' 'Section' 'Variable' 'Value'
                // %var value written to *.ini file

6.8 Macro commands for manipulating files - COPY, NAME and KILL

These commands are for manipulating files such as .txt, .res, .tab, .xls, .fig and .xml types.
COPY:

COPY 'FileName1' 'FileName2'  
        // Copy file 'FileName1' to file 'FileName2'
        // - 'FileName2' must be one of .txt, .res, .tab, .xls, . fig or .xml. 
        // Warning, if 'FileName2' already exists it will be replaced. 

Example:
%4   C:\Dummy\
COPY %4MyText.Txt Copy.txt 
        // Copy C:\Dummy\MyText.txt to C:\FactSage\Copy.txt 

NAME: (or RENAME)

NAME 'FileName1' 'FileName2'  
        // Rename 'FileName1' as file 'FileName2'
        // - 'FileName2' must be one of .txt, .res, .tab, .xls, .fig or .xml
        // Warning, if file 'FileName2' already exists it will be replaced. 

Example:
%4   C:\Dummy\
RENAME %4MyText.Txt NewName.txt 
        // Copies C:\Dummy\MyText.txt to C:\FactSage\NewName.txt 
        // if default directory %DIR is C:\FactSage\
        // and then deletes C:\Dummy\MyText.txt.

KILL: (or DELETE)

KILL 'FileName1'           
        // Delete 'FileName1' 
        // - 'FileName1' must be one of .txt, .res, .tab, .xls or .fig. 
        // Wild cards (* and ? e.g. KILL EQUI*.DAT) are not permitted. 

Examples: 
%4   C:\Dummy\
KILL %4MyText.Txt     // Deletes file C:\Dummy\MyText.txt
DELETE   MyText.Txt   // Deletes file C:\FactSage\MyText.txt 
                      // if default directory %DIR is C:\FactSage\
6.9 Macro commands for Excel Worksheets and Text Spreadsheets - linking via OLEn

An Excel Worksheet is stored in the well-known *.Xls and *Xlsx Worksheet files supported by Microsoft. When programming with Excell files there are a multitude of ways the data stored in the cells of the spreadsheet can be processed, manipulated, plotted etc. By means of Object Linking and Embedding (OLE) you can use the macro to interact with an Excel Worksheet that may already be open in another application, in which case both applications will be able to share the same work space.  

A Text Spreadsheet (introduced in FactSage 7.0) is stored in a *.txt or *.tab ascii file. It offers simplicity and speed when compared with the Excel Worksheet. There are often situations where the Text Spreadsheet is preferred to the Excel Worksheet especially in cases where data are simply being posted or manually entered. However data in a Text Spreadsheet cannot be shared with other applications nor can the data be manipulated by the Excel functions.

The Equilib macro processing enables you to create up to 9 simultaneous dynamic links (OLE1 to OLE9) This advanced feature permits Object Linking and Embedding (OLE) with an Excel Worksheet and/or Text Spreadsheet. A simple example is given in the macro file EquiEx_Xls_Simple_IO.mac (this example is expanded in FactSage 7) and a more complicated one in EquiEx_CH4-O2-c.mac.

OLEn:

OLEn 'ExcelFileName' ['Sheet-Name']
   // Create an OLE link (n = 1 to 9) with an Excel Worksheet stored in an Excel Worksheet file (*.xls,*.xlsx).
   // ex: 'OLE1 MyExcel.xlsx  Input'  - creates a link to the 'Input' Spreadsheet of the Excel file.
   
OLEn 'TextFileName' ['Sheet-Name']
   // Create an OLE link (n = 1 to 9) with a Text Spreadsheet stored in an ascii file (*.txt,*.tab).
   // ex: 'OLE1 MyText.txt  Input'  - creates a link to the 'Input' Spreadsheet of the Text file.
   // You can create more links with different Worksheets in different Text files .
   // ex: 'OLE2 MyMoreText.tab  Output'  - creates a second link to the 'Output' Text Spreadsheet. 
   
   // Many of the following commands are shown in EquiEx_Xls_Simple_IO.mac located in the /Macros folder.
    
OLEn CLOSE                       // close the Spreadsheet; you will be prompted to save
OLEn CLOSE SAVE                  // close and save the Spreadsheet without prompting 
OLEn CLOSE SAVE 'ExcelFileName'  // close and save Excel Worksheet in a different *.xls or *.xlsx file
OLEn CLOSE SAVE 'TextFileName'   // close and save Text Spreadsheet in a different *.txt or *.gab file
OLEn QUIT                        // close the Spreadsheet without saving  

OLEn CELLS     ALL   'options'   // apply options to all cells in the Worksheet
OLEn COLUMNS  'F:F'  'options'   // apply options to column F
OLEn ROWS     '2:3'  'options'   // apply options to rows 2 and 3   
OLEn RANGE  'B1:C4'  'options'   // apply options to a range B1:C4 or R1C2:R4C3
OLEn NAME    'NAME'  'options'   // apply options to a range name  

    //  List of 'options' for both Excel Worksheets and Text Spreadsheets :
AUTOFIT                  // auto fit column width
                         // ex: 'OLE1 CELLS ALL AUTOFIT' auto fits all cells in the Spreadsheet  
BOLD TRUE (FALSE)        // Bold text - TRUE is default.   BOLD may be replaced by: 
                         // ITALIC, SHADOW, STRIKETHROUGH, SUBSCRIPT, SUPERSCRIPT or UNDERLINE 
                         // ex: OLE1 ROWS 2:3 UNDERLINE  
CENTER (LEFT RIGHT)      // alignment of contents in each cell 
CLEAR                    // clear the contents in each cell 
COLOR 'color'            // text color where 'color' is one of  BLACK, MAROON, GREEN,  
                         // OLIVE, NAVY, PURPLE, TEAL, GRAY, SILVER, RED, LIME, YELLOW, BLUE, FUSHIA, AQUA or WHITE
COLOR RGB(i,j,k)         // RGB color where i, j and k in the range 0 - 255
                         // ex: 'OLE1 RANGE A1:C:4 COLOR RGB(0,0,255)'   - same as 'COLOR BLUE'
FONTSTYLE 'font style'   // font style ex: 'Bold_Italic' - use _ for spaces
                         // ex: 'OLE1 RANGE R1C1:R3:C3 FONTSTYLE Times_New_Roman'  
HEIGHT 'value'           // set rows to a common height
SIZE   'value'           // set font size to a commo value
WIDTH  'value'           // set columns to a common width

OLEn GOTO  'RnCm'  
   // put focus on this cell - scroll vertically and horizontally if necessary.
   // ex: 'OLEn GOTO R22C33' makes sure cell at row 22 column 33 is visible on the screen

%var  =   OLEn READ 'An' ('RnCm' 'An:Bm' 'RnCm:RiCj' 'name')
   // variable value(s) read from cell (or row & column or range).
   // ex:  B5  R5C6  B5:D10  R5C2:R10C4 RangeName
%var  =   OLEn WRITE 'An' ('RnCm' 'An:Bm' 'RnCm:RiCj' 'name')
   // variable value(s) written to cell (or row & column or range).

NAME      OLEn CLEAR  'name'
   // clear the contents of a range name in the Spreadsheet
NAME      OLEn DELETE 'name'
   // delete the range name in the Spreadsheet
NAME      OLEn NEW    'name' 'An' 'Bn:Cm' ('RnCm:RiCj')
   // define a new range name in the Spreadsheet

ERROR_OFF  or  ERROROFF       
  // Suppress error handling (also see ERROR_ON) - use with caution !
  // This is not an OLE command but it is very useful in OLE processing.  Minor link errors are often posted during 
  // dynamic interaction with the Excel Worksheet.  This command simply suppresses the offending error messages.   
6.10 Macro user-defined $Functions and Procedures - FUNCTIONS ... END FUNCTIONS, PROCEDURES ... END PROCEDURES

It is possible to program user-defined FUNCTIONS (e.g. $Function('arguments') and PROCEDURES (e.g. CALL SUBROUTINES) .

All the %variables used in the subroutines must be declared (VARIABLE or DIM) at the beginning of the macro. The subroutines (PROCEDUREs) are called (CALL) within the main body of the macro. A user-defined $function or subroutine cannot call another user-defined $function or subroutine.

The FUNCTIONS and PROCEDURES are listed at the end of the macro - FUNCTIONS ... END FUNCTIONS and PROCEDURES ... END PROCEDURES.

FUNCTIONS
  //  The format of a user-defined function is :
  //  FUNCTION $'function name'('arguments') 
  //     - $'function name name' is any alphanumeric description starting with $.
  //     - 'arguments' are values passed from the main body.   
  //  ....macro lines (where 'output variables' are defined)
  //  $'function name' = 'value' (where the value of function is defined)
  //  END FUNCTION  

  FUNCTION $My-Whatever(arg1 arg2 ...)
     ... macro lines
     $My-Whatever = 'value'
  END FUNCTION
 
  FUNCTION $My-Another(arg1 arg2 ...)
     ... macro lines
     $My-Another = 'value'
  END FUNCTION

END FUNCTIONS  

PROCEDURES
  //  The format of a procedure is :
  //  'procedure name'('argumentss') 
  //      - 'procedure name' is any alphanumeric description
  //      - 'arguments' are values are defined in the main body.   
  //  ... macro lines where 'output variables' are defined)
  //  END  'procedure name'
   
  SUB_CheckDim(%A)   
   .... (macro lines)
  END SUB_CheckDim  

  SUB_Another(C%)   
   .... (macro lines)
  END SUB_Another  

END PROCEDURES
Examples of user-defined functions and procedures are presented in EquiEx_New_in_7.0.mac and EquiEx_Functions_and_Procedures.mac stored in the Macros folder.

The following example is extracted from EquiEx_Functions_and_Procedures.mac. In the macro we scan the figures (and macros) folder and return the number (%Scan_number) of *.fig (and *.mac) files. In addition the size (%Scan_big_size) and name (%Scan_big_name) of the largest file in the folder are determined.


REM Extracted from EquiEx_Functions_and_Procedures.mac  FactSage 7 
REM                ===================================
REM Example of Calling (CALL) subroutines (PROCEDURES)  
REM 
// Declare (VARIABLE or DIM) all %Variables.  
DIM %Scan_mask %Scan_folder\ %File %Scan_number %Scan_big_name %Scan_big_size    
   // For improved readability the %Variables in the Sub_SCAN_Files() subroutine are all called %Scan_*.   
DIM %Size %ShortName %FullName %Folder_mask %Display 

%DIR  = $FSDIR  // Set user default directory to the FactSage directory $FACTSAGE_DIR\

%Folder_mask = $FIGURES_DIR\*.fig// ex: C:\Factsage\Figures\*.fig 
                                  // $FIGURES_DIR\ is the reserved $Function for the FactSage figures folder

CALL Sub_SCAN_Files(%Folder_mask) // First call to procedure Sub_SCAN_Files - see PROCEDURES at end of macro file. 

// Display the results in real time. 
MSGBOX In $FIGURES_DIR\ there are %Scan_number *.fig files. _ _The largest is %Scan_big_name _at %Scan_big_size bytes.

%Folder_mask = $MACROS_DIR\*.mac  // ex: C:\Factsage\MACROS\*.mac
                                  // $MACROS_DIR\ is the reserved $Function for the FactSage macros folder

CALL Sub_SCAN_Files(%Folder_mask) // Second call to procedure Sub_SCAN_Files - see PROCEDURES at end of macro file. 

// Display the results in real time.
MSGBOX In $MACROS_DIR\ there are %Scan_number *.mac files. _ _The largest is %Scan_big_name _at %Scan_big_size bytes.

PROCEDURES                  // PROCEDURES ... END PROCEDURES are placed at the end of the macro and 
                            // contain the subroutines called in the main body.
  //  The format of a procedure is :
  //  'procedure name'('input parameters') // 'procedure name' is any alphanumeric description
  //                                       // 'input parameters' are values are passed from the main body.   
  //  (macro lines where 'output variables' are defined)
  //  END  'procedure name'
  
  Sub_SCAN_Files(%Scan_mask)   // Sub_SCAN_Files is the name of the subroutine (PROCEDURE) being called (CALL).
                               // The prefix 'Sub_' is used to improve readability but it is not essential. 
                               // %Scan_mask is the input parameter. More than one parameter may be specified.  
     // 'Sub_SCAN_Files' scans '%Scan_mask' and returns:  the number of files (%Scan_number),  
     // the size (%Scan_big_size) and the name (%Scan_big_name) of the largest file .
     
     %Scan_folder\ = $FILE_DIR(%Scan_mask)      // Parent directory of mask ex: c:\FactSage\Figures\
     %Scan_big_size   =  0                     // Reset the size
     %Scan_big_name   =  0                     // Reset the file name
     
     %Scan_number = $SCAN_DIR(%Scan_mask)      // Initiate scan ex: $SCAN_DIR(c:\FactSage\Figures\*.fig)
                                               // and return %Scan_number - the number of files located  
     
     IF %Scan_number = 0 GOTO EndOfSub_SCAN_Files  // See MARK EndOfSub_SCAN_Files 
     
     %File = 1 TO %Scan_number            // Scan folder for each file 
        %ShortName = $SCAN_DIR()          // Return the short name of the file. 
        %FullName  = %Scan_folder\%ShortName
        %Size = $FILE_BYTES(%FullName)     // Size (bytes) of the File. $FILE_BYTES is a reserved $FUNCTION.
        
        IF %Scan_big_size < %Size  THEN   // Check for the largest file size.
           %Scan_big_size = %Size
           %Scan_big_name = %FullName 
        ENDIF         
     %File LOOP             
     
     MARK EndOfSub_SCAN_Files   
  END Sub_SCAN_Files     // End of PROCEDURE Sub_SCAN_Files 
  
END PROCEDURES           // End of all PROCEDUREs
END
6.11 Macro 1-D and 2-D %Variables - tables and arrays, REDIM, $ARRAY_DIM(), _COUNT(), _LBOUND(), _UBOUND(), $ENUM
DIM %A %B(2) %C(-2:2) %D(1,3) %E(0:1,2:4) // DIM or VARIABLE - declaration of single, 1-D and 2-D variables (arrays)
   // %A          -> %A            
   // %B(2)       -> %B(1)   %B(2) 
   // %C(-2:2)    -> %C(-2)  %C(-1)  %C(0)   %C(1)   %C(2)
   // %D(1,3)     -> %D(1)   %D(2)   %D(3)
   // %E(0:1,2:4) -> %E(0,2) %E(0,3) %E(0,4) %E(1,2) %E(1,3) %E(1,4)

$ARRAY_DIM, $ARRAY_COUNT, $ARRAY_LBOUND, $ARRAY_UBOUND

%1 = $ARRAY_DIM(%A)    // -> 0 - no dimension single variable
%1 = $ARRAY_DIM(%B)    // -> 1 - 1-D array
%1 = $ARRAY_DIM(%E)    // -> 2 - 2-D array
%1 = $ARRAY_COUNT(%A)  // -> 1 - single member 
%1 = $ARRAY_COUNT(%E)  // -> 5 - multi-member
%1 = $ARRAY_LBOUND(%C) // -> %C(-2) - lower bound or first member
%1 = $ARRAY_UBOUND(%E) // -> %E(1,4) - upper bound or last member 

REDIM

REDIM %variable    
    // Same as DIM except if the %variable already exists it becomes redimensioned.
REDIM %A(2) %B(5)    
    // %A single variable converted to a 1-D array - %A(2) -> %A(1), %A(2) 
    // %B(2) replaced by %B(5) -> %B(1), %B(2) ... %B(5) 

$ENUM

%var-array = $ENUM('starting value') 
              // function to enumerate the members of an array
%D = $ENUM(0) // %D(1) = 0, %D(2) = 1, %D(3) = 2 
%E = $ENUM(1) // %E(0,2) = 1, %E(0,3) = 2, %E(0,4) = 3 ... %E(1,4) = 6
Examples of 1-D and 2-D arrays are given in EquiEx_New_in_7.0.mac located in the Macros folder.

6.12 Macro thermochemical variables - $variables$, SET

$variables$ variables are system dependent thermochemical variables that are defined by the Equi*.dat (or Phas*.dat) file or calculated during the equilibrium calculation.   An example of common thermochemical variables is given in the macro file EquiEx_List_Results.mac. A complete example of most calculated thermochemical variables including solution integral and partial properties and component lists is given in the macro file EquiEx_List_Thermo.mac. The thermochemical variables are listed in Summary of All Macro Variables, Functions and Commands ....

The SET command is used to redefine input reactants (delete or add), initial amounts, system units and the final conditions and species selection that are initially defined in the Equi*.dat (or Phas*.dat) file.  You can even change the type of calculation.  For example if in the stored Equi*.dat file Delta(H) = 0 and P =1 (and T is undefined - adiabatic calculation), then you can define the values T and P (and set Delta(H) undefined - isothermal calculation). Examples of SET commands are given in the macro file EquiEx_SET_Variables.mac. A complete list of SET commands follows in section 6.13.


SET COLOR 'RedValue' 'GreenValue' 'BlueValue' 
                   // RGB format 0 - 255 (color in Figure or Phase Diagram)
SET COLOR LIMITS 'MinValue' 'MaxValue' 
                   // Lower and upper values (typically T) - used with SET COLOR VALUE
SET COLOR VALUE 'Value' 
                   // value (typically T) in the range 'MinValue' 'MaxValue' - see SET COLOR LIMITS 

SET DATASEARCH GION (NOGION AQUA NOAQUA CXHY MINS1)     
                            // include/exclude gaseous ions, include/exclude aqueous species, 
                            // CxHy value, min. solution components (1 or 2)

SET ESTIMATE T (P V ALPHA) 'value' // Redefine estimate of final T, P, V or ALPHA.

SET FINAL A (B T P Z) 'value' // Redefine final <A>, <B>, T, P or Z (extensive property value).
SET FINAL Z H (V G S C)       // Redefine variable Z (extensive property variable) as Delta H (V G S or Cp).

SET PARAMETERS DISPLAY SHOW (OUTPUT PRINT DILUTE LABELS ISOT POLYTHERMAL)
                           // Redefine variables in the Parameters Window.
                           // See 6.13 for the complete List of SET PARAMETERS Commands
                           
SET REACTANT DEL 'reactant#' ('chemical_formula' or '[stream]')     
                            // Delete (remove) an existing reactant  
SET REACTANT ADD 'chemical_formula' or '[stream]' ['phase_name'  ['steam_#'] ]     
                            // Add a new reactant (compound species or stream) 
SET REACTANT 'reactant#' ('chemical_formula' or '[stream]') MASS (T P) 'mass' ('temperature' 'pressure')
                            // Redefine input reactant (or stream) mass (T or P)

SET SELECT GAS (or LIQUID AQUEOUS SOLID) + (or - !) [NICK [SPECIES]]
                            // + to add, - to remove, ! for dormant (metastable).
                            // NICK is the database 4-6 letter nickname.
                            // Species is the chemical formula.
SET SELECT COMPOUND + (or - !) [NICK [SPECIES]]
SET SELECT SOLUTION + (or - !) [NICK-Phase [SPECIES]]
SET SPECIES 'chemical_formula' ACTIVITY (or ACT or LOGACT) 'value' ['value2' 'value3'] // Define equilibrium activity or log10(activity) values(s) of an 'ACTIVITY species'. // For a range define 3 values - 'first last increment' . SET SPECIES ADD ACTIVITY 'chemical_formula(state)' 'compound_database' // Identify a new 'ACTIVITY species'. SET SPECIES DEL ACTIVITY 'chemical_formula' 'compound_database' // Drop an 'ACTIVITY species'. // Example of ACTIVIY commands is in EquiEx_CH4-O2_Activity.mac (new in 7.1) located in the the /Macros folder. SET SUBTITLE 'String' // Phase diagram subtitle SET TITLE 'String' // Phase diagram title SET UNITS TK (TC TF) ATM (BAR PSI PA) J (CAL BTU KWH) X (% LB) // Redefine units T, P, energy and mass units. // Note the mass units: X = moles, % = grams, LB = lbs. SET VDP ON (OFF) // Include (exclude) the 'VdP' term.
6.13 Macro SET Commands - for data search and options, reactants, species selection, output formatting, plotting, etc.

Data Search Window - commands of SET DATASEARCH commands :

SET DATASEARCH GION (NOGION)       // include (exclude) gaseous ions (plasmas)
SET DATASEARCH AQUA (NOAQUA)       // include (exclude) aqueous species
SET DATASEARCH CXHY 'value 1-99'   // CxHy .. maximum value of x in organic molecules
SET DATASEARCH MINS1 (MINS2)       // minimum number of solution components is 1 (2)

Reactants Window - examples of SET REACTANT: 

SET REACTANT DEL  2                // Delete Reactant 3
SET REACTANT DEL  CH4              // Delete Reactant CH4
SET REACTANT ADD  C2H6 gas         // Add new reactant C2H6(g)      
SET REACTANT ADD  SO3  liquid   #2 // Add new reactant SO3(l) as steam #2
SET REACTANT ADD  C    solid-1  #3 // Add new reactant C(s) as steam #3
SET REACTANT SO3  MASS 0.1         // Amount of reactant SO3
SET REACTANT C2H6 T    400         // Temperature of reactant C2H6 and others in same stream

Species and phase selection - examples of SET SELECT:
 
SET SELECT GAS      + ELEM               // Select all gas species from ELEM database.
SET SELECT COMPOUND ! SGTE Fe // Make all SGTE Fe compound species metastable. SET SELECT SOLUTION + FToxid-SLAGA // Select the FToxid-SLAGA solution phase, and then
SET SELECT SOLUTION - FToxid-SLAGA SiO2 // unselect (drop) SiO2 from this FToxid-SLAGA phase. Menu Window : - list of SET CALCULATE and SET VARIABLES commands SET EQUILIBRIUM NORMAL // normal equilibrium calculation - default setting SET EQUILIBRIUM TRANSITIONS // normal and phase transitions - only meaningful within a range of T (or alpha A etc.) SET EQUILIBRIUM TRANSITIONSONLY // only calculate the equilibrium phase transitions within a range of T (or alpha A etc. SET EQUILIBRIUM OPEN // open calculation - only meaningful if input alpha A step has been specified SET VARIABLES T MAX 'value' // Maximum temperature SET VARIABLES T MIN (or CONSTANT) 'value' // Minimum (or constant) temperature SET VARIABLES T STEP 'value' // Step in temperature (polythermal projection) SET VARIABLES T DEFINE ON (OFF)' SET VARIABLES P MAX 'value' // Maximum pressure SET VARIABLES P MIN (or CONSTANT) 'value' // Minimum (or constant) pressure SET VARIABLES A1 MAX 'value' // Maximum chemical potential #1 - log10(a1) or RTln(a1) SET VARIABLES A1 MIN (or CONSTANT) 'value' // Minimum chemical potential #1 - log10(a1) or RTln(a1) SET VARIABLES A2 (or A3 or ... ) etc. // Chemical potential #2 (or #3 or ... ) etc. SET VARIABLES C1 MAX 'value' // Maximum composition #1 SET VARIABLES C1 MIN (or CONSTANT) 'value' // Minimum composition #1 SET VARIABLES C2 (or C3 or ... ) etc. // Composition #2 (or #3 or ... ) etc. Output Window - list of SET OUTPUT commands : SET OUTPUT FORMAT FACT CHEMSAGE // FACT and then ChemSage format SET OUTPUT FORMAT CHEMSAGE FACT // ChemSage and then FACT format SET OUTPUT FORMAT FACT // FACT format only SET OUTPUT FORMAT CHEMSAGE // ChemSage format only SET OUTPUT FORMAT KEEP // The change in the output format is permanent. // When the macro processing is finished the display returns to the former setting unless KEEP is employed. Parameters Window - note that ON (or OFF) may be replaced by 1 (or 0) - list of SET PARAMETERS PRINT commands to control the output in the Output Window : SET PARAMETERS PRINT CUTOFF 'limit' // lower limit for activities and concentrations SET PARAMETERS PRINT BONDS ON (OFF) // display bond fractions SET PARAMETERS PRINT STABLE ON (OFF) SET PARAMETERS PRINT DATA NEVER (ALWAYS ONLY) // NEVER display the name(s) of the database(s) // ALWAYS display the name(s) of the database(s) // ONLY display the name(s) of the database(s) if there is more than one compound or one solution database SET PARAMETERS PRINT [KEEP] // The change in the output format is permanent. // When the macro processing is finished the output returns to the former setting unless KEEP is employed. - List of SET PARAMETERS TARGET limits : SET PARAMETERS TARGET T (P V ALPHA) 'minimum' 'maximum' // set target limits // note TARGET ALPHA limits are fixed at '1.0e-5' and '1' SET PARAMETERS TARGET DEFAULT // return all target limits to default settings - List of SET PARAMETERS DISPLAY, SHOW, LABELS and POLYTHERMAL commands used in Figure for phase diagram calculations : SET PARAMETERS DISPLAY FULLSCREEN (COLOR TITLE SUBTITLE) ON (OFF) // set phase diagram screen display options SET PARAMETERS SHOW STATUS (TIELINES WARNING LABELS) ON (OFF) // set phase diagram output options SET PARAMETERS LABELS LABELSIZE '1-9' SET PARAMETERS LABELS LABELCOLOR 'color' (or '0-15') // set phase diagram label colors // colors BLACK MAROON GREEN OLIVE NAVY PURPLE TEAL GRAY SIVER RED LIME YELLOW BLUE FUSHIA AQUA WHITE // 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 SET PARAMETERS LABELS BOLD (ITALIC UNDERLINE) ON (OFF) // set phase diagram label properties SET PARAMETERS LABELS LINEWIDTH '1-20' // set phase diagram label width 0.1 - 2.0 mms SET PARAMETERS LABELS LINECOLOR 'color' (or '0-15') // set phase diagram line color SET PARAMETERS LABELS ALWAYS (ONLY SHOWS) ON (OFF) // set phase diagram label display SET PARAMETERS LABELS CHEMICAL (NUMERICAL DEFAULT) // set phase diagram label format SET PARAMETERS ISOT COLOR (COLORTBAR BYPHASE TVALUE TUNITS PHASE) ON (OFF) // set phase diagram isothermal display properties SET PARAMETERS POLYTHERMAL LISTTMINMAX (LISTINTCOMPOSITIONS LABELSURFACE LABELINTNORT) ON (OFF) // set phase diagram polythermal display properties SET PARAMETERS POLYTHERMAL DISPLAYFIGURE (DISPLAYPAGE DISPLAYBOTH) // set phase diagram polythermal display properties SET PARAMETERS POLYTHERMAL LABELINTN (LABELINTT) // set phase diagram polythermal display properties font color="#FF0000">SET PARAMETERS POLYTHERMAL LABELINTPOINT ON (OFF)
// set phase diagram polythermal display properties SET PARAMETERS POLYTHERMAL NORTCOLOR 'color' (or '0-15') // set phase diagram polythermal display properties SET PARAMETERS POLYTHERMAL POINTCOLOR 'color' (or '0-15') // set phase diagram polythermal display properties
Post Processor and Plot Species Selection Windows - SET PLOT commands for the Post Processor Windows :
- An example of plotting Equilib figures is given in the macro file EquiEx_CH4-O2_Figure.mac 
stored in the Macros folder. 

SET PLOT AXIS/CAPTION/LABELS/DISPLAY/SELECT 'options'                 

SET PLOT AXIS Y-AXIS (X-AXIS) 'property'  'function'  'minimum' 'maximum' 'step'
     // where 'property' is one of:  n X gram % alpha T P Cp G V H V S or page
     // where 'function' is one of:  Y log10(Y) ln(Y) exp(Y) or 1/Y

SET PLOT CAPTION TITLE    'title'           // figure title
SET PLOT CAPTION SUBTITLE 'sub-title'       // and subtitle
SET PLOT CAPTION Y-TITLE (X-TITLE) ' title' // axes captions

SET PLOT CAPTION LABEL 'X' 'Y'  'label #1'  // coordinates and user-defined label     
SET PLOT CAPTION LABEL 'X' 'Y'  'label #2'   
SET PLOT CAPTION LABEL  .... etc.            

SET PLOT DISPLAY COLOR        ON (OFF)      // color (or B/W)      
SET PLOT DISPLAY COLORS  9 12 2 ...         // color numbers 0 - 14     
SET PLOT DISPLAY COLORS  RED BLUE GREEN ... // color names BLACK MAROON ... AQUA
            // colors  BLACK MAROON GREEN OLIVE  NAVY PURPLE TEAL GRAY SIVER RED LIME YELLOW  BLUE FUSHIA AQUA 
            //           0     1      2     3      4    5      6    7    8    9   10    11     12    13    14   

SET PLOT DISPLAY REACTANTS    ON (OFF)      // list reactants in the title   (if CAPTION TITLE not set) 
SET PLOT DISPLAY FILE_NAME    ON (OFF)      // list soyurce file in subtitle (if CAPTION SUBTITLE not set)

SET PLOT DISPLAY SOURCE       ON (OFF)      // include data source in species label 
SET PLOT DISPLAY PHASE        ON (OFF)      // include phase name in species label  
SET PLOT DISPLAY NAME         ON (OFF)      // include species name in species label  

SET PLOT LABELS  SIZE  2 (2 - 24)           // size of labels  
SET PLOT LABELS  NO    2 (1 - 9)            // number of labels per plotted line line            
SET PLOT LABELS  CHEMICAL (INTEGER or NONE) // type of label       
SET PLOT LABELS  OFFSET       ON (OFF)      // offset labels above their coordinates 
       
SET PLOT SELECT  CLEAR                      // clear current species salection
SET PLOT SELECT  MASS    MOLE (GRAM)        // mass units
SET PLOT SELECT  ORDER   INTEGER (MASS FRACTION or ACTIVITY) 
            // order with respect to integer or mass ...  
SET PLOT SELECT  TOP     1 (2 ...)          // select top species as defined in ORDER
SET PLOT SELECT  IGNORE  ON (OFF)           // ignore species and phase that have no mass 
SET PLOT SELECT  STABLE  PHASE (LIQUID SOLID SOLUTION) 
            // select all stable phases (ALL S TABLE PURE LIQUIDS ...)  
SET PLOT SELECT  SPECIES 2 5 8              // select species 2 5 and 8
6.14 Macro Windows commands - LOG_OFF, REBOOT, SHUTDOWN
WINDOWS LOGOFF       // Quit all applications and logoff the PC
WINDOWS REBOOT       // Quit all applications and reboot the PC
WINDOWS SHUTDOWN     // Quit all applications and shutdown the PC

Example:    
LOAD EQUI9999.DAT    // Load an Equilib file
CALC                 // calculate
SAVE EQUI1234.TXT    // save the results
WINDOWS SHUTDOWN     // then quit FactSage (and any other appliactions)
                     // and turn off the PC when done.
END
6.15 Macro display commands - REM, SHOW, HIDE, HIDE_MACRO and MSGBOX
 
These commands control the visual display - they have no effect on the macro processing.

REM 'string'  // A remark - line of comments in the Macro Window

HIDE          // FactSage windows will become hidden  
              // - same effect as clicking on Macro 'Hide'.

HIDE_MACRO    // Macro Window will become hidden (minimized)  

SHOW          // FactSage windows will become visible
              // - same effect as clicking on Macro 'Show'.

MSGBOX 'string'             // post a message on the screen

MSGBOX FILENAME 'Filename' // post contents of a small text file on the screen

VIEWTEXT 'Filename.txt'    // post contents of a large text file on the screen
6.16 Macro Phase Diagram commands FIGURE, SUPERIMPOSE, VIEWER

FIGURE 'Filename1.fig'  // Display the figure stored in the .fig file 
FIGURE 'Filename2.fig' SUPERIMPOSE
                        // Superimpose this figure on the previous one.

VIEWER 'Filename1.fig'  or  VIEWFIG  or  VIEWFIGURE  ... 
                        // Use Viewer to display the figure.
                        // Unlike Figure, Viewer can display many figures at the same time.

Examples:

%1 = PHASEx_Al-Mg-Sr-liquidus
FIGURE %DIR%1a.fig  // Display c:\FactSage\PHASEx_Al-Mg-Sr-liquidusa.fig
FIGURE %DIR%1b.fig SUPERIMPOSE
                    // Superimpose c:\FactSage\PHASEx_Al-Mg-Sr-liquidusb.fig
FIGURE %DIR%1c.fig SUPERIMPOSE
                    // Superimpose c:\FactSage\PHASEx_Al-Mg-Sr-liquidusc.fig

6.17 Macro Debugging commands - DEBUG /ON, DEBUG 'caption', DEBUG /DEL

The command 'DEBUG /ON' (new in FactSage 7.0) activates the debug mode and displays the 'DEBUG Macro Window' which lists the current values of all user-defined %variables.

Each time a DEBUG command is issued the debug Window is updated with the current values. It is hoped that this will become a valuable tool in macro processing development.

As an example, load and run the macro file EquiEx_New_in_7.0.mac that is stored in the Macros folder.

       // The DEBUG commands are a debugging aid and have no effect on the macro processing. 
DEBUG /ON                  // Activates the 'DEBUG Macro Window' 
DEBUG /OFF                 // Deactivates the debug mode - this is the default setting.
DEBUG 'caption'            // Lists current values of all %VARIABLES - 'caption' is the display heading
DEBUG /DEL %var1 %var2 ... // Drops %VARIABLES from the debug list

7. Equilib Macro Files

There are several Equilib macro (Equi*.mac) files stored in the Macros directory  -  in the Reactants Window click on 'File > Macro processing > Edit macro ..> Macros directory ...'.    The files may be listed but they should not be modified.

The macro files EquiExample_1.mac to EquiExample_4.mac show increasing levels of difficulty.

The three macro files EquiEx_CH4-O2-a.mac, EquiEx_CH4-O2-b.mac and EquiEx_CH4-O2-c.mac are examples that are demonstrate IF ..THEN, DOCASE... ENDDO, and OLE linking (both read and write) with an open Excel Worksheet.

An example of common thermochemical variables is given in the macro file EquiEx_List_Results.mac. A complete example of most calculated thermochemical variables including solution integral and partial properties and component lists is given in the macro file EquiEx_List_Thermo.mac.

It is recommended that you try the EquiEx_CH4-O2.mac macros only after you have studied the following EquiExample*.mac macros.



7.1  Macro File EquiExample_1.mac


Edit the macro file EquiExample_1.mac:
       Go to the Reactants Window.
       Click on 'File > Macro processing > Edit macro ..>  Macros directory  ..>  EquiExample_1.mac
       and open the file EquiExample_1.mac


Contents of EquiExample_1.mac:


REM File EquiExample_1.mac
REM ======================
REM
REM Loads Equilib file Ex_CH4-O2, calculates and displays results.
 
%DIR  = $FSDIR          // Set user default directory to FactSage directory $FACTSAGE_DIR\

OPEN EQUIEx_CH4-O2.DAT  // Load Equilib file 

CALC               // and calculate the equilibrium.

SHOW Equilib.txt   // Save in Equilib.txt and display the output. 
SHOW Equilib.tab   // Save in Equilib.tab and display the tabular spreadsheet. 
SHOW Equilib.xml   // Save in Equilib.xml and display in xml format. 

END                // End of the macro processing.
Notes on EquiExample_1.mac:

Now run the macro EquiExample_1.mac:
       Go to the Reactants Window.
       Click on 'File > Macro processing > Run macro ..>  Macros directory  ..>  EquiExample_1.mac
       and open the file EquiExample_1.mac


7.2  Macro File EquiExample_2.mac

Edit the macro file EquiExample_2.mac:
       Go to the Reactants Window.
       Click on 'File > Macro processing > Edit macro ..>  Macros directory  ..>  EquiExample_2.mac
       and open the file EquiExample_2.mac


Contents of EquiExample_2.mac:

REM File EquiExample_2.mac
REM ======================
REM
REM Macro that prompts you to enter input file and output page numbers.

                        //Ask user for default directory name:
%DIR %DIR ASK Enter the name of the default directory:

MARK Begin              // A marker - see 'GOTO Begin' later on.

%1 0 ASK Enter Equilib file number (1 to 9999) _- or 'Cancel' to quit.
                  // Ask user to define %1.  Note ' _' for a new line.
                  // Ex:  %1 = 1234
                  // Cancel returns the default value (0 in this case)
 
IF %1 < 1 GOTO Bottom      // %1 must be in the range 1 to 9999
IF %1 > 9999 GOTO Bottom   // - see 'MARK Bottom' at the end.

OPEN EQUI%1.DAT // Ex: Open file 'C:\FactSage\EQUI1234.DAT'
CALC            // and then calculate the equilibrium.

SHOW EQUI%1.TXT // Ex: save in 'C:\FactSage\EQUI1234.TXT' and display.

IF $PAGES < 2 GOTO IgnorePage 
                // $PAGES is the number of equilibrium Results pages

REM  - Prompt for the page number.
%2  0 ASK  There are $PAGES pages of results.  _ _
           Enter the results page number (1 - $PAGES)  _
           or enter 0 (Cancel) if none are to be displayed.
                // Ex:   %2 = 14.  Note ' _' to continue on next line. 
                // Cancel returns the default value (0 in this case).

IF %2 < 1 GOTO IgnorePage
IF %2 > $PAGES GOTO IgnorePage

SHOW EQUIP%2.TXT %2  // Ex: save page 14 in 'C:\FactSage\EQUIP14.TXT'. 
MARK IgnorePage       

HIDE                 // Hide Equilib windows. Same as clicking 'Hide'.
GOTO Begin           // Cycle through the macro again.            

MARK Bottom          // See ' ... GOTO Bottom'.
END 
Notes on EquiExample_2.mac:

After CALC you could add one or more of the following
(replace SAVE by SHOW if you also wish to display the file):


  SAVE EQUI%1.TXT  [Page]  // save output in a *.TXT file.  
                           // Page (optional integer) is a integer
  SAVE EQUI%1.RES          // save results in a *.RES file.
  SAVE EQUI%1.FIG          // save figure in a *.FIG file.
  SAVE EQUI%1.TAB          // save spreadsheet in a *.TAB file.
  SAVE EQUI%1.XLS  ['Sheet-Name'] [/SWAP] ['top-left-cell'] 
                           // save spreadsheet in a *.XLS file. 
  SAVE EQUI%1.XML          // save spreadsheet in a *.XML file. 
  SAVE MIXT%1.DAT GAS [comments]        
                           // save computed gas phase in a MIXT*.DAT stream 
Now run the macro EquiExample_2.mac:
       Go to the Reactants Window.
       Click on 'File > Macro processing > Run macro ..>  Macros directory  ..>  EquiExample_3.mac
       and open the file EquiExample_3.mac

Enter 1234 when prompted for the file number.
Enter 14 when prompted for the page number - this should display the results corresponding to <A> = 0.65.



7.3 Macro File EquiExample_3.mac


Edit the macro file EquiExample_3.mac:
       Go to the Reactants Window.
       Click on 'File > Macro processing > Edit macro ..>  Macros directory  ..>  EquiExample_3.mac
       and open the file EquiExample_3.mac


Contents of EquiExample_3.mac:

REM File EquiExample_3.mac
REM ======================
REM
REM This macro processes all the EQUI*.dat files where * = %First to %Last.
REM You are prompted to enter the %First and %Last values.
REM The output results are stored in EQUI*.TXT and EQUI*.RES 

HIDE                   // Hide the Equilib windows.
                       // - this speeds up the processing.

VARIABLE %Results %First %Last  // Declare user variables 

%DIR  %DIR ASK Enter the default directory for the files:   
                       // Default directory for all the files.
%Results %DIR ASK Enter the directory where results will be stored:   
                       // This will be the same as %DIR unless 
                       // the user specifies other wise

%First 1    ASK  Enter the first (minimum) Equilib file number (1 to 9999).   
                       // Ask for the first file %First (default 1)

%Last 10   ASK  Enter the last (maximum) Equilib file number. 
                       // Ask for the last file %Last (default 10)

IF %First < 1 OR %Last > 9999 OR %Last < %First GOTO END
                       // Check if file numbers are OK

%1 %First              // %1 is the first file 

MARK Top               // A marker - see 'GOTO Top' later on.

%3 equi%1.dat READ     // Read the first word and store in %3.
IF %3 = 0 GOTO NextOne // Go to line 'MARK NextOne' if file 
                       // equi%1.dat empty or does not exist.

OPEN equi%1.dat        // Load the file from the default directory 
CALC                   // and then calculate.  

SAVE %ResultsEqui%1.txt     // Save text output in equi*.txt
SAVE %ResultsEqui%1.res     // Save results in equi*.res - this file will 
                            // be accessible from the Results module.

MARK NextOne             // A marker - see 'GOTO NextOne'. 

%1 STEP 1                // Increase file number %1 by 1
IF %1 <= %Last GOTO Top  // and cycle if not last file.

END                      // Terminate macro processing.
Notes on EquiExample_3.mac:

EQUI*.DAT Files
  If the file equi%1.dat is not found then the line 'OPEN equi%1.dat' will be ignored as well as any subsequent commands CALC, SAVE and SHOW. But this should be taken care of in the 'IF %3 = 0 GOTO NextOne' command.

*.RES Files
The results file equi%1.res in the line 'SAVE equi%1.res' should not be re-named.  When results (*.res) files are processed by the FactSage Results and Figure modules they are expecting a file name of this format (equi*.res).   Other formats would not be recognized by Results and Figure.

Other Files - *.TXT. *.FIG, *.XLS and *.TAB
  The text file equi%1.txt in the line 'SAVE equi%1.txt' could be any text file say 'SAVE MyTextOutput.txt'.   This is true for the other (non *.res) files - *.FIG, *.XLS and *.TAB.
  
Now run the Macro EquiExample_3.mac:
       Go to the Reactants Window.
       Click on 'File > Macro processing > Run macro ..>  EquiExample_3.mac.
       This will run the macro EquiExample_3.mac

Enter say 1230 when asked for the first file number and
1240 when asked for the last file number.

File 1234 exists, but the others may not and you will see what happens.


7.4 More Equilib Macro Files


The three macro files EquiEx_CH4-O2-a.mac, EquiEx_CH4-O2-b.mac and EquiEx_CH4-O2-c.mac are examples that are prepared to show examples of IF ..THEN, DOCASE... ENDDO, and OLE exchange (both read and write) with an open Excel Worksheet.   Note that macro file EquiEx_CH4-O2-c.dat is quite challenging.

An example of displaying calculated common thermochemical variables is given in the macro file EquiEx_List_Results.mac  - see $Thermochemical Variables ($E_*$, $R_*$) at the bottom.

A complete example of most calculated thermochemical variables including solution integral and partial properties and component lists is given in the macro file EquiEx_List_Thermo.mac.

An example of the 'SET' command is given in the macro file EquiEx_SET_Variables.mac.


8. Phase Diagram Macro Files


Run the Phase Diagram  module. Edit the macro file PhasExample_1.mac:
       Go to the Components Window.
       Click on 'File > Macro processing > Edit macro ..>  Macros directory  ..>  PhasExample_1.mac
       and open the file PhasExample_1.mac

This macro demonstrates how to calculate a Phase Diagram and display the figure (*.fig).


Contents of PhasExample_1.mac:

    
REM File PhasExample_1.mac
REM ======================
REM
REM Loads Phase Diagram File %1, calculates and 
REM saves in .fig file

%DIR  = $FSDIR     // Set user default directory to FactSage directory $FACTSAGE_DIR\

%1 1 ASK Enter the Phase Diagram file number (1-9999) or name

IF $EXIST(PHAS%1.DAT) = 0 GOTO END  // Quit if phase diagram file empty or not found

HIDE               // Hide the windows

OPEN PHAS%1.DAT    // Load file PHAS*.DAT
CALC               // and calculate the phase diagram.
SAVE PHAS%1.FIG    // Save in PHAS*.FIG 

SHOW               // Show the windows

FIGURE PHAS%1.FIG  // Display via Figure module

END                // End of the macro processing.
Notes on PhasExample_1.mac:

PhasExample_1.mac is a basic Phase Diagram macro file and is analogous to the Equilib EquiExample_1.mac file.

Other analogous files can be created.  For example the following file PhasExample_3.mac is very similar to EquiExample_3.mac



Contents of PhasExample_3.mac:

REM File PhasExample_3.mac
REM ======================
REM This macro processes all the PHAS*.dat files where * = %1 to %LAST (in the range 1 to 9999).
REM You are prompted to enter the default directory (%DIR), and to enter the first (%1) and last
REM (%LAST) file numbers.  The calculated output results are stored in PHAS*.FIG 

VARIABLE %LAST %Results\  // Declare user-defined %variables. 
       // The '.' in '%Results\' is simply to improve readability.
       // No need to declare reserved variables %1 to %9.
                   
%DIR  %DIR ASK Enter the default directory for the files:   
       // Set default directory for all the files.  
       // Note %DIR is a reserved %variable - others are %1 ... %9.

%Results\ %DIR ASK Enter the directory where results will be stored:   
                       // This will be the same as %DIR unless 
                       // the user specifies otherwise

%1 1   ASK  Enter the first (minimum) file number (1 to 9999).   
                       // Ask for the first file %1 (default 1)
%LAST 10   ASK  Enter the last (maximum) file number. 
                       // Ask for the last file %LAST (default 10)

MARK Top               // A marker - see 'GOTO Top' later on.

IF $EXIST(phas%1.dat) = 0 GOTO NextOne    .
                       // $EXIST(): 1 file exists, 0 not exist.
                       // Go to line 'MARK NextOne' if phas%1.dat does not exist.

PRINT_ON               // Show listing in the Macro Window
OPEN phas%1.dat        // Load the file from the default directory 
CALC                   // and then calculate.  

SAVE %Results\phas%1.fig  // Save figure output in phas*.fig
                          // that can be read by Figure & Viewer.

SAVE %Results\phas%1.bmp  // Save figure output in phas*.bmp bitmap file
                          // that can be imported into Word and Power Point.

PRINT_OFF                 // Suppress listing in the Macro Window

MARK NextOne              // A marker - see 'GOTO NextOne'. 

%1 STEP     // Increase file number %1 by 1.  Same as %1 = $MATH(%1 + 1)

IF %1 <= %LAST GOTO Top   // Do again if not > last file.

END                       // Terminate macro processing.

9. Applications


At the CRCT in Montreal we employ macro processing in several ways.  

A major application is in Quality Control to check current calculations against previous ones. Clearly in FactSage program development we wish to know when a program starts giving a different (possibly incorrect) answer, or if a particular calculation is starting to take longer.  For example all the results and execution times of many different calculations for a wide variety of applications are stored in one big log file.  The log file is then compared with a standard file from previous calculations.   Since the size of the file may be large (>1,000,000 lines) it is compared by running the batch file compare.bat.

Contents of compare.bat (1 line):
fc /c /n /w %1 %2 > differ.log

fc is a Microsoft Windows program installed on most PCs - enter 'fc /? ' for information about fc and its switches (/c, /n, /w, etc.).  
  
To compare 2 files, say old.txt with new.txt, enter the command:

compare   old.txt   new.txt

Such a command could be stored in the macro - for example
SHELL_WAIT %DIRcompare.bat   %DIRold.txt   %DIRnew.txt

Any differences between the 2 files are written to the text file differ.log

Another application is in optimization.  Mixing parameters in the solution database Solution.dat are changed in systematic manner and the results of Equilib calculations (stored in a *.res file) are compared with experimental data.   By summing the differences between calculated and experiment values (liquidus temperature, activity data, enthalpies, etc.) and comparing with previous calculations, a new (hopefully improved) parameter is written in the database and the calculations repeated.  The macro uses SHELL_WAIT command and the $RETVAL parameter and it has less than 10 lines - the strategy and optimization processing is performed in a separate program (written in C++).



10. Batch Processing - Running Equilib in the Background

With a standalone version of FactSage (the PC has a dongle) it is possible to run Equilib (or Phase Diagram) macro processing without first calling FactSage. This is done by running a *.bat file that contains a call to process the macro file within the Equilib (Phase Diagram) module.

A sample .bat file Run_Equilib.bat (Run_PhaseDiagram.bat) is located in the FactSage directory. This example loads and runs the macro file Macros\EquiEx_SET_Variables.mac.


In order to successfully run the batch file the following conditions must be respected:

When the macro processing is finished the Equilib module being run is then closed.

11. Summary of All Macro Variables, Functions and Commands ....


Christopher W. Bale
CRCT, 2017

(End  Macro Processing - FactSage 7.1)