Macro Processing Manual - FactSage 6.3

1. Introduction2. Macro   Commands 3. Saving the Equilib file4. Creating a Macro File5. Running the Macro File6. Macro Variables, Functions and Commands7. Equilib Macro Files8. Phase Diagram Macro Files9. Applications10. Batch Processing - Running Equilib in the Background11. Summary of All Macro Variables, Functions and Commands

          1. Introduction

This advanced feature is 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 use 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 1234CALC // and calculate the equilibrium.SAVE EQUI1234.TXT // Save results in EQUI1234.TxtSHOW EQUI1234.TAB // Save results & display spreadsheet EQUI1234.tabSHOW EQUI1234.XML // Save results & display in XML formatSAVE 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 1234comments: '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.DATCALC   SHOW EQUI1234.TXT SHOW EQUI1234.FIG SHOW EQUI1234.TABSHOW EQUI1234.XMLEND

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

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

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)  '$variable' - denotes a system variable (date, time, ...) that cannot be modified by you'$variable$' - denotes a computed or defined thermochemical variable'$function()' - denotes a system function (with arguments) for manipulating strings, formatting output and mathematical functions        (temperature, activity, moles,. ..) that cannot be modified by you    [] denotes optional.() denotes alternatives (or arguments of a $function() ).    

6.1 Macro Variables - %variables, %DIR, %1, %2, ... %9 with ASK and ASKOK

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 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:

VARIABLE '%var1' '%var2' '%var3' '%var4' // Use VARIABLE 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

Examples:

VARIABLE %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, ASKOK:

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

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

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 ASKOK Do you wish to keep My Files directory as %Path\? // if he agrees then %1 = 'OK' else '0'

%DIR:

// %DIR is the default directory and it is automatically defined by the // program. You may reset the value of %DIR.

%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 // 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 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 thenSAVE %Path\Mytext.Txt // save results in 'C:\My Files\MyText.txt'.

6.3 Macro $Functions

a) String manipulation - $ASC, $CHR, $LCASE, $UCASE, $LEFT, $RIGHT, $MID, $REPLACEb) Output formatting - $FORMATE, $FORMATF, $FORMATG, $FORMATIc) Mathematical functions - $ABS, $EXP, $LN, $LOG10, $FIX, $INT, $RND, $RNDINT, $MIN, $MAX, $MINI, $MAXI, $MEAN, $MEDIAN, $SORTDEC, $SORTDECI, $SORTINC, $SORTINCId) Mathematical expressions - $MATHe) File manipulation - $EXIST, $FILEDIR, $FILENAME, $SCANDIR f) Chemical functions - $ELEMENT, $MOLWT, $CONSTANT,

Macro $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 $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, $RNDINT, $MIN, $MAX, $MINI, $MAXI, $MEAN, $MEDIAN, $SORTDEC, $SORTDECI, $SORTINC, $SORTINCI

Simple mathematical functions with one or more arguments - combined expressions 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. // $RDN(0,1) -> random floating point number in the range 0 to 1 // $RDN(1,100.234) -> random floating point number in the range 1 to 100.234

$RNDINT('min' 'max') // Random integer number in the range min to max, where min >= 0 and max > min. // $RDNINT(0 10) -> random integer number in the range 0 to 10 // $RDNINT(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 manipulation - $EXIST, $FILEDIR, $FILENAME, $SCANDIR

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

$FILEDIR('long file name') // Directory of a long file name // $FILEDIR(C:\FactSage\Figures\CaO_SiO2.fig) -> 'C:\FactSage\Figures\' $FILENAME('long file name') // File name of a long file name // $FILENAME(C:\FactSage\Figures\CaO_SiO2.fig) -> 'CaO_SiO2.fig'

$SCANDIR: is similar to the Dir function in many software languages. There are two modes in using $SCANDIR. 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. $SCANDIR('file-mask') // Initiates the scan and returns the number of files or '0' if no files are found.$SCANDIR() // Lists the name of first file in the list.$SCANDIR() // Lists the name of 2nd file in the list.$SCANDIR() // and so on. '0' denotes when all files have been listed.

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

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

$ELEMENTNAME('value') // convert atomic number to an element // $ELEMENTNAME(26) -> 'Fe'$ELEMENTNUMBER('name') // convert an element to an atomic number // $ELEMENTNAME(Fe) -> '26' $ELEMENTMASS('name' or 'value') // convert an element to an atomic mass // $ELEMENTMASS(26) -> '55.847' $ELEMENTMASS(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

6.3 Macro Commands  - 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:  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 ....ENDIFGOTO 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:  branched program flow - IF...THEN ... ENDIF and DOCASE ... ENDCASE

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 ENDELSE // try again. GOTO TOPENDIF // 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 %variableCASE '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 ... etcCASE 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 fileDOCASE %1

CASE 1 // The CASE statement has a fixed value (not %var) %2 = EQUILIB.TXT CASE 2 %2 = EQUILIB.RESCASE 3 %2 = EQUILIB.XLSCASE -1 // Quit. GOTO END CASE ELSE // Invalid, try again. GOTO TOPENDDO // EndSAVE %2 // Save the file.

DOCASE Example 2:

DO CASE %1CASE 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 .. DOEND statements not not permitted// that is, a DOCASE .. DOEND can NOT contain another DOCASE .. ENDDO. // Also, the CASE statement can NOT contain a %variable.

6.6 Macro Commands - Advanced Features: ERROROFF, ERRORON, RUNMACRO, SHELL, SHELLEXECUTE, SHELLWAIT, WAIT, PAUSE, WRITE, WRITEINI, APPEND;    Variables: $COMMAND, $RETVAL ERROROFF, ERRORON:

ERROROFF // suppress error handling (see ERRORON) - use with caution!ERRORON // resume error handling (see ERROROFF) - 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 $MACROSDIR\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 ...

SHELLEXECUTE:

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

Example:%4 = C:\Dummy\ SHELLEXECUTE %4MyText.Txt // Open C:\Dummy\MyText.txt with Notepad or Wordpad etc.SHELLEXECUTE %4MyText.Doc // Open C:\Dummy\MyText.txt with WordSHELLEXECUTE %4MyText.Xls // Open C:\Dummy\MyText.txt with ExcelSHELLEXECUTE %4MyText.Xlm // Open C:\Dummy\MyText.xlm with Fact-XLM

SHELLWAIT:

SHELLWAIT 'string' // Execute command and wait until done. // Return values are stored in $RETVAL.Example:SHELLWAIT 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 continueWAIT 'number' // wait 'number' seconds before continuing

Example:PAUSE 10 // processing waits 10 seconds and then proceeds (same as WAIT 10)

WRITE, APPEND, APPEND FILENAME:

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 fileAPPEND 'TextFileName1' FILENAME 'TextFileName2' // Append file 2 to the end of file 1.

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'. WRITEINI:

WRITEINI 'IniFile' 'Section' 'Variable' 'Value' // variable value written to *.ini file (see READINI)

6.7 Macro Commands for Reading Files - READ, CLOSE, REWIND %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.

%var READINI 'IniFileName' 'Section' 'Variable' 'Default' // %var value read from *.ini file (see WRITEINI)

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.txtDELETE MyText.Txt // Deletes file C:\FactSage\MyText.txt // if default directory %DIR is C:\FactSage\6.9 Macro Commands for Excel Worksheets - linking via OLEn

This advanced feature permits Object Linking and Embedding (OLE) with an Excel worksheet.  A simple example is given in the macro file 'EquiEx_Xls_Simple_IO.mac' and a more complicated one in 'EquiEx_CH4-O2-c.mac'.

OLE permits you 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.  The Equilib macro processing enables you to create up to 9 simultaneous dynamic links (OLE1 to OLE9). OLEn:

OLEn 'ExcelFileName' ['Sheet-Name'] // Create an OLE link (n = 1 to 9) with an Excel Worksheet // Some PCs may prefer that the worksheet be already open.

OLEn CELLS ALL CLEAR // clear all cells in the WorkSheetOLEn CELLS ALL AUTOFIT // auto fit column width for all cellsOLEn CELLS ALL WIDTH 'value' // set all columns to a common widthOLEn CELLS ALL HEIGHT 'value' // set all rows to a common heightOLEn COLUMNS 'F:F' CLEAR (or AUTOFIT or WIDTH 'value' or HEIGHT 'value') // format columns - see 'CELLS'OLEn ROWS '2:3' CLEAR (or ...) // format rows - see 'CELLS'OLEn NAME 'NAME' CLEAR (or ...) // format a name - see 'CELLS'OLEn RANGE 'B1:C4' CLEAR (or ...) // format a range - see 'CELLS'

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 & col 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 & col or range).

NAME OLEn CLEAR 'name' // clear the contents of a range name in the worksheetNAME OLEn DELETE 'name' // delete the range name in the worksheetNAME OLEn NEW 'name' 'An' 'Bn:Cm' ('RnCm:RiCj') // define a new range name in the worksheet6.10 Macro System variables - $variables -   $BLANK, $COMMAND, $DATE, $FSDIR, $HWND, $PAGES, $RETVAL, $TIME, etc.

$Variables are fixed by the system and cannot be changed. $BLANK // ' ' (white space) - used in WRITE commands $CHEMSAGEDIR\ // ChemSage directory, typically 'c:\FactSage\CHEMSAGE\'$COMMAND // optional command line set by RUNMACRO 'file.mac' [command] $DATE // current date $EXAMPLESDIR\ // examples directory, typically 'c:\FactSage\EXAMPLES\'$FACTDATADIR\ // database directory, typically 'c:\FactSage\FACTDATA\'$FACTHELPDIR\ // help directory, typically 'c:\FactSage\FACTHELP\'$FACTSAGEDIR\ // directory where FACTWIN.INI resides - same as $FSDIR$FALSE // 0 (zero). Ex: 'IF $EXIST('file name') = $FALSE THEN GOTO END'$FIGURESDIR\ // figures directory, typically 'c:\FactSage\FIGURES\'$FSDIR // directory where FACTWIN.INI resides - same as $FACTSAGEDIR\$F90IODIR\ // fortran I/O directory, typically 'c:\FactSage\F90IO\'$HWND // handle of current application$MACFILE // full name of the current macro file $MACROSDIR\ // macros directory, typically 'c:\FactSage\MACROS\'$PAGES // number of pages in last calculation $RETVAL // shell process returned value - see 'SHELLWAIT'$TEMPDIR\ // temporary directory - environment variable defined by Windows$TIME // current time$TRUE // 1 (one). Ex: 'IF $EXIST('file name') = $TRUE THEN'

Example:WRITE c:\Dummy\Summary.txt Calculation completed at $TIME, $DATE // Writes current time and date into file 'c:\Dummy\Summary.txt' // ex: 'Calculation completed at 10:27:14 AM, 20-01-2003'6.11 Macro Display Commands: REM, SHOW, HIDE, HIDEMACRO 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'.

HIDEMACRO // 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 text file on the screen6.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 (introduced in FactSage 5.4.1 and 5.5) is given in the macro file 'EquiEx_List_Thermo.mac'. The thermochemical variables are listed at the end of this manual.

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). An example of the SET command is given in the macro file 'EquiEx_SET_Variables.mac'.

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 FINAL A (B T P Z) 'value' // Redefine final <A>, <B>, T, P or Z (entensive property value).SET FINAL Z H (V G S C) // Redefine variable Z (entensive property variable) as Delta H (V G S or Cp).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 SPECIES 'chemical_formula' ACT (LOGACT) 'value' ['value2' 'value3'] // Redefine a species activity (or Log10(a))

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 VALUESET COLOR VALUE 'Value' // value (typically T) in the range 'MinValue' 'MaxValue' - see SET COLOR LIMITS

SET TITLE 'String' // Phase diagram titleSET SUBTITLE 'String' // Phase diagram subtitle

SET SELECT GAS (or LIQUID AQUEOUS SOLID) + (or - !) [NICK [SPECIES]] // + to add, - to remove, ! for domant (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]]

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

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 thenSET SELECT SOLUTION - FToxid-SLAGA SiO2 // unselect (drop) SiO2 from this FToxid-SLAGA phase.The output format commands SET OUTPUT define the display in the Results Window

SET OUTPUT FORMAT FACT CHEMSAGE // FACT and then ChemSage format SET OUTPUT FORMAT CHEMSAGE FACT // ChemSage and then FACT formatSET OUTPUT FORMAT FACT // FACT format onlySET OUTPUT FORMAT FACT CHEMSAGE // ChemSage format onlyFor phase diagram calculations the SET command can be used to redefine parameters and variables that are normally defined in the Parameters Window and in the Variables Window

SET PARAMETERS DISPLAY FULLSCREEN 0 (or 1) // 0 is off (false) and 1 is on (true)SET PARAMETERS DISPLAY COLOR 0 (or 1) SET PARAMETERS DISPLAY TITLE 0 (or 1) SET PARAMETERS DISPLAY SUBTITLE 0 (or 1)

SET PARAMETERS SHOW STATUS 0 (or 1)SET PARAMETERS SHOW TIELINES 0 (or 1)SET PARAMETERS SHOW WARNING 0 (or 1)SET PARAMETERS SHOW LABELS 0 (or 1)

SET PARAMETERS LABELS LABELSIZE '1-9'SET PARAMETERS LABELS LABELCOLOR 'color' (or '0-15') // 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 15SET PARAMETERS LABELS BOLD 0 (or 1)SET PARAMETERS LABELS ITALIC 0 (or 1)SET PARAMETERS LABELS UNDERLINE 0 (or 1)SET PARAMETERS LABELS LINEWIDTH '1-20' // i.e. 0.1 - 2.0 mms SET PARAMETERS LABELS LINECOLOR 'color' (or '0-15') // ex: RED (or 9)SET PARAMETERS LABELS ALWAYS 0 (or 1)

SET PARAMETERS POLYTHERMAL TMINMAX 0 (or 1)SET PARAMETERS POLYTHERMAL COMPOSITIONS 0 (or 1)SET PARAMETERS POLYTHERMAL PHASES 0 (or 1)SET PARAMETERS POLYTHERMAL NUMBER 0 (or 1)SET PARAMETERS POLYTHERMAL COLOR 0 (or 1) 'color' (or '0-15')

SET VARIABLES T MAX 'value' // Maximim temperatureSET VARIABLES T MIN (or CONSTANT) 'value' // Minimum (or constant) temperatureSET VARIABLES T STEP 'value' // Step in temperature (polythermal projection)SET VARIABLES T DEFINE 0 (or 1)'

SET VARIABLES P MAX 'value' // Maximim pressureSET VARIABLES P MIN (or CONSTANT) 'value' // Minimum (or constant) pressure

SET VARIABLES A1 MAX 'value' // Maximim chemical potential #1 - log10(a1) or RTln(a1)SET VARIABLES A1 MIN (or CONSTANT) 'value' // Minimmm 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' // Maximim composition #1SET VARIABLES C1 MIN (or CONSTANT) 'value' // Minimmm composition #1SET VARIABLES C2 (or C3 or ... ) etc. // Composition #2 (or #3 or ... ) etc.6.13 Macro Windows Commands:  LOGOFF, REBOOT, SHUTDOWNWINDOWS LOGOFF // Quit all applications and logoff the PCWINDOWS REBOOT // Quit all applications and reboot the PCWINDOWS SHUTDOWN // Quit all applications and shutdown the PC

Example: LOAD EQUI9999.DAT // Load an Equilib fileCALC // calculateSAVE EQUI1234.TXT // save the resultsWINDOWS SHUTDOWN // then quit FactSage (and any other appliactions) // and turn off the PC when done.END6.14 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' // Use Viewer to display the figure. // Unlike Figure, Viewer can display many figures at the same time.

Examples:

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

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 prepared to show of 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 (introduced in FactSage 5.4.1 and 5.5) 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 - FactSage 5.3.1 (2004-10-21)REM ======================REMREM Loads Equilib file Ex_CH4-O2, calculates and displays results. %DIR = $FSDIR // Set user default directory to FactSage directory.

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 - FactSage 5.3 (2004-06-25)REM ======================REMREM 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 9999IF %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 IgnorePageIF %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 - FactSage 5.3 (2004-06-25)REM ======================REMREM 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*.txtSAVE %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 1IF %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 FilesThe 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  Macro File EquilExample_4.mac

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

You will also need to edit the text file 'Equilib4.txt'  Contents of EquiExample_4.mac:

REM File EquiExample_4.mac - FactSage 5.3 (2004-06-22)REM ======================REMREM This macro runs Equilib in the background. REM It gets the contents of the first word of a text fileREM Equilib4.txt that tells it the number of the file to open.REM This operation is repeated every 5 seconds until the first line inREM Equilib4.txt is '0' in which case it quits the macro processing. %DIR %DIR ASK Enter the default directory for EQUI*.DAT files: // Default directory for all the files.

%9 %DIR ASK Enter the directory where results will be stored: // This will be the same as %DIR unless the user // specifies other wise.

%2 0 // %2 is given the initial value '0' - see later on. MARK Cycle // Beginning of the loop - see 'GOTO Cycle' later on.

%1 Equilib4.txt READ LINEWORD 1 1 // Read Equilib file number from file // Equilib4.txt, ex: '1234'.IF %1 = 0 GOTO END // Quit if file number is '0' or file empty.

IF %1 = %2 GOTO Bottom // Ignore if same file number as last time.%2 %1 // Store the file number in %2.

%3 equi%1.dat GET // Read first line of equi%1.dat and store in %3.IF %3 = 0 GOTO END // Quit if file equi%1.dat does not exist.

OPEN equi%1.dat // Load file equi%1.dat from default directoryCALC // and then calculate.

%4 %9Equi%1.txt // %4 is the name of the results save file, // ex: 'c:\FactSage\Equi1234.txt'SAVE %4 // and then save it.

MARK Bottom // A marker - see 'GOTO Bottom'WAIT 5 // Pause for 5 secondsGOTO Cycle // and then repeat the cycle.

END // Terminate macro processing.

7.5 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 (introduced in FactSage 5.4.1 and 5.5) 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 save it in a figure (*.fig) and bitmap (*.bmp) file.

Contents of PhasExample_1.mac:

REM File PhasExample_1.mac - FactSage 5.3 (2004-06-22)REM ======================REMREM Loads Phase Diagram File %1, calculates and REM saves in .fig file

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

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

HIDE // Hide the windows

OPEN PHAS%1.DAT // Load file PHAS*.DATCALC // 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:

This is a basic Phase Diagram macro file and is analogous to the Equilib EquExample_1.mac file.

Other analogous files can easily 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 - FactSage 5.3 (2004-06-22)REM ======================REM This macro processes all the PHAS*.dat files REM where * = %1 to %LAST (in the range 1 to 9999).REM You are prompted to enter the default directory (%DIR), and REM to enter the first (%1) and last (%LAST) file numbers.REM 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, %TIME, %DATE, %RETVAL,

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

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

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

SAVE %RESULTS.phas%1.fig // Save figure output in phas*.figPRINTOFF // Suppress listing in the Macro Window

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

%1 STEP // Increase file number %1 by 1. // Note, 'STEP' only works with the %1 to %9 variables.

IF %1 <= %LAST GOTO Top // and cycle if not > last file.

END // Terminate macro processing.

8.1 More Phase Diagram Macro Files

PhaseEx_Al-Mg-Sr-liquidus.mac loads the file PhaseEx_Al-Mg-Sr-liquidus.dat and calculates the liquidus at various isothermal sections.

PhasEx_Superimpose_Figs.mac displays and superimposes several *.fig files used in conjunction with PhaseEx_Al-Mg-Sr-liquidus.mac.

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 exampleSHELLWAIT %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 SHELLWAIT 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:

The batch *.bat file must be stored in the default FactSage directory (typically c:\FactSage\) This FactSage directory must contain an authorized standalone version of FactSage - it will NOT

work on a client version on a network installation. The macro *.mac file being loaded must exist.

Only one batch file can be run at a given time and the regular Equilib (Phase Diagram) module cannot be run at the same time.

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

11. Summary of All Macro Variables, Functions and Commands

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 system variable (date, time, ...) that cannot be modified by you      ex: $DATE  $FSDIR  $HWND  $RETVAL  $TIME

'$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 system function (with arguments) for manipulating strings, formatting output and mathematical functions      ex: $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.() denotes alternatives (or arguments of a $function() ).

Summary of Macro $Variables:

$Variables are fixed by the system and cannot be changed. $BLANK // ' ' (white space) - used in WRITE commands $CHEMSAGEDIR\ // ChemSage directory, typically 'c:\FactSage\CHEMSAGE\'$DATE // current date $EXAMPLESDIR\ // examples directory, typically 'c:\FactSage\EXAMPLES\'$FACTDATADIR\ // database directory, typically 'c:\FactSage\FACTDATA\'$FACTHELPDIR\ // help directory, typically 'c:\FactSage\FACTHELP\'$FACTSAGEDIR\ // directory where FACTWIN.INI resides - same as $FSDIR$FALSE // 0 (zero). Ex: 'IF $EXIST('file name') = $FALSE THEN GOTO END'$FIGURESDIR\ // figures directory, typically 'c:\FactSage\FIGURES\'$FSDIR // directory where FACTWIN.INI resides - same as $FACTSAGEDIR\$F90IODIR\ // fortran I/O directory, typically 'c:\FactSage\F90IO\'

$HWND // handle of current application$MACFILE // full name of the current macro file $MACROSDIR\ // macros directory, typically 'c:\FactSage\MACROS\'$PAGES // number of pages in last calculation $RETVAL // shell process returned value - see 'SHELLWAIT'$TRUE // 1 (one). Ex: 'IF $EXIST('file name') = $TRUE THEN'$TIME // current timeSummary of Thermochemical $Variables

- the thermochemical variables are listed at the end.

Summary of Macro %Variables and associated commands:

%DIR // default directory%TITLE // title of current application

%var = 'value' // set the value of a %variable%var = 'value' ASK 'prompt' // ask for the VALUE (default IS 'VALUE')

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

%var = FACTOR 'value' // factors (multiplies) %variable by 'value' (see STEP) // i.e. %variable = %variable x 'value' // Same as '%var = $MATH(%var * 'value')'%var = GETMESSAGE // wait for value sent in message (SendMessage)%var = HWND 'Title' // variable value is handle of application 'title'%var = READINI 'IniFile' 'Section' 'Variable' 'Default' // variable value read from *.ini file (see WRITEINI)%var = STEP ['value'] // steps (adds) %variable by +1 (or by "value') (see FACTOR) // i.e. %variable = %variable + 'value' (default 1) // Same as '%var = $MATH(%var + 1)'Summary of $Functions:

$ABS('value1') // Absolute value // ex: $ABS(-1.2) -> 1.2

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

$CHR('value') // Character from its ascii value. // ex: $CHR(48) -> '1' ; $CHR(65) -> 'A' ; $CHR(97) -> 'a' $CONSTANT('gas constant') // Gas constants: Rgas-cal Rgas-J Rgas-L-atm // ex: $CONSTANT(Rgas-J) -> '8.31451' J/mol-K

$CONSTANT('unit1/unit2') // Unit conversion. List of units:- // 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 // ex: $CONSTANT(g/lb) -> '453.59237' g/lb $ELEMENTNAME('value') // convert atomic number to an element // ex: $ELEMENTNAME(26) -> 'Fe'$ELEMENTNUMBER('name') // convert an element to an atomic number // ex: $ELEMENTNAME(Fe) -> '26' $ELEMENTMASS('name' or 'value') // convert an element to an atomic mass // ex: $ELEMENTMASS(26) -> '55.847' $ELEMENTMASS(Fe) -> '55.847'

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

$EXP('value1') // ex: $EXP(100) -> 2.68811...E+43

$FILEDIR('long file name') // Directory of a long file name // ex: $FILEDIR(C:\FactSage\Figures\CaO_SiO2.fig) -> 'C:\FactSage\Figures\' $FILENAME('long file name') // File name of a long file name // ex: $FILENAME(C:\FactSage\Figures\CaO_SiO2.fig) -> 'CaO_SiO2.fig' $FORMATA( 'm' 'string') // Am character format // ex: $FORMATA( 12 Hello) -> ' Hello World'$FORMATE( 'm' 'n' 'value') // Em.n scientific format // ex: $FORMATE( 12 4 1.2345678) -> ' 0.1234E+01'$FORMATF( 'm' 'n' 'value') // Fm.n numerical format // ex: $FORMATF( 12 4 1.2345678) -> ' 1.2345'$FORMATG( 'm' 'n' 'value') // Gm.n general format // ex: $FORMATG( 12 4 1.2345678) -> ' 1.2345' // ex: $FORMATG( 12 4 123.45678e20) -> ' 1.2345e+22'$FORMATI( 'm' 'value'

// Im integer format // ex: $FORMATI( 12 1.2345678) -> ' 1'

$FIX('value1') // ex: $FIX(4.2) -> 4 // ex: $FIX(-4.2) -> -4 $INT('value1') // ex: $INT(4.2) -> 4 // ex: $INT(-4.2) -> -5 $LCASE('string') // Lower case characters of 'string'.$LEFT('value' 'string') // 'value' left characters of trimmed 'string'.$LEN('string') // length of trimmed string // ex: LEN I Love U -> 8$LN('value1') // ex: $LN(100) -> 4.60517...$LOG10('value1') // ex: $LOG10(100) -> 2

$MATH('mathematical expression') // mixed mathematical expression can include 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.666666...$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.3673...

$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

$MID('value1' 'value2' 'string') // starting at character 'value1' returns //'value2' characters of trimmed 'string' // ex: MID 3 5 I Love U -> 'Love'

$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

$MOD('value1' 'value2') // Modulus (or remainder) operator divides value1 by value2 // (rounding floating-point numbers to integers) and returns only the remainder as result. // $MOD(22,10) -> '2' // $MOD(19.1, 6.7) -> '4' (i.e. 19 modulus 7)

$MOLWT('species') // Molecular weight of a chemical species // $MOLWT(H2O) -> '18.01528'

$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'

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

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

$RIGHT('value' 'string') // 'value' right characters of trimmed 'string'.

$SCANDIR('File-Mask') // Initiates the scan and returns the number of files or '0' if no files are found.$SCANDIR() // Lists the name of first file in the list.$SCANDIR() // Lists the name of 2nd file in the list.$SCANDIR() // and so on. '0' denotes when all files have been listed.

$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' $SQRT('value1') // ex: $SQRT(100) -> 10$TRIM('string') // Remove leading & trailing blanks$UCASE('string') // Upper case characters of 'string'.

Summary of OLE commands - exchange with a cell (or range) in an Excel spreadsheet:

OLEn 'ExcelFileName' ['Sheet-Name'] // Create an OLE link (n = 1 to 9) with an Excel Worksheet // Some PCs may prefer that the worksheet be already open.

OLEn CELLS ALL CLEAR // clear all cells in the WorkSheetOLEn CELLS ALL AUTOFIT // autofit column width for all cellsOLEn CELLS ALL WIDTH 'value' // set all columns to a common widthOLEn CELLS ALL HEIGHT 'value' // set all rows to a common heightOLEn COLUMNS 'F:F' CLEAR (or AUTOFIT or WIDTH 'value' or HEIGHT 'value') // format columns - see 'CELLS'OLEn ROWS '2:3' CLEAR (or ...) // format rows - see 'CELLS'OLEn NAME 'NAME' CLEAR (or ...) // format a name - see 'CELLS'OLEn RANGE 'B1:C4' CLEAR (or ...) // format a range - see 'CELLS'

OLEn GOTO 'RnCm' // put focus on this cell (scroll until the cell is visible)

%var = OLEn READ 'An' ('RnCm' 'An:Bm' 'RnCm:RiCj' 'name') // variable value(s) read from cell (or row & col 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 & col or range).

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

Summary of Macro Commands - single lines:

APPEND 'FileName' 'string' // Append 'string' to end of a text file 'FileName' (see WRITE)APPEND 'FileName1' FILENAME 'FileName2' // Append file 'FileName2' to end of text file 'FileName1'

CALC // press the module 'Calculate >>' buttonCAPTION 'string' // set macro window captionCLOSE 'Filename' // used with READ - go to beginning of fileCOPY 'Source' 'Target' // copy .txt, .res, .tab, .xls, .fig files

DELETE 'FileName' // delete .txt, .res, .tab .xls, .fig files // (same as KILL)

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

END // last line in the macro fileEXIT // quit (see TERMINATE)

FIGURE 'Filename1.fig' // display the figure stored in .fig file (see VIEWER)FIGURE 'Filename2.fig' SUPERIMPOSE // superimpose a figure on to previous one

HIDE // hide FactSage moduleHIDEMACRO // hide the macro window (see SHOWMACRO)IF 'Value1' = [< > =< >= <>] 'Value2' GOTO 'mark' // 'IF' statement has 6 words (also see IF ... THEN ... ENDIF)

INSERT 'FileName' // insert text 'FileName' into current macro.INSERT GETMESSAGE // waits & inserts message (SendMessage) into current macro.

KILL 'FileName' // delete .txt, .res, .tab .xls, .fig files // (same as DELETE) LOADONLY // create SGMX files without calculating.LOG 'Filename' // log session in file (default macro.log)MARK 'word' // a marker - used with GOTO 'word'

MSGBOX 'string' // post a messageMSGBOX FILENAME 'Filename' // post contents of a file

NAME 'Source' 'Target' // rename .txt, .res, .tab .xls, .fig filesOPEN 'FileName' // open (load) EQUI*.DAT, PHAS*.DAT files

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

PAUSE // issue prompt to resume or quit processingPAUSE 'value' // wait 'value' seconds (same as WAIT 'value')

PRINTOFF // suppress listing in the macro windowPRINTON // resume listing in the macro window

POSTMESSAGE 'TargetHwnd' 'string' // post message in another applicationPOSTMESSAGE 'TargetHwnd' FILENAME 'Filename' // post file contents in another application.QUIT // exitREM 'string' // comments line in the macro windowREWIND 'Filename' // used with READ - go to top of file.RUNMACRO 'filename.mac' [command] // quit the current application and run a new macro (optional command line).

SAVE 'Equi*.RES' // save results in a *.RES file accessible by module RESULTSSAVE 'Name.FIG' // save figure in a *.FIG file accessible by module FIGURESAVE 'Name.TAB' // save spreadsheet in a text *.TAB file.SAVE 'Name.XLS' ['Sheet-Name'] [/SWAP] ['top-left-cell'] // save in excel spreadsheet *.XLS file. // - 'Sheet-Name' is an optional word // - /SWAP to exchange rows and columns // - 'top-left-cell' is the top left cell (default 'A1').

SAVE 'name.XML' // save spreadsheet in a *.XML file. SAVE 'MIXT*.DAT' GAS (LIQUIDS SOLIDS SOLUTIONS 'phase-name') // save results in a MIXT*.DAT stream

SENDMESSAGE 'TargetHwnd' 'string' // send message to another applicationSENDMESSAGE 'TargetHwnd' FILENAME 'Filename' // send file contents to another applic.

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 VALUESET COLOR VALUE 'Value' // value (typically T) in the range 'MinValue' 'MaxValue' - see SET COLOR LIMITS

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

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') MASS (T P) 'mass' ('temperature' 'pressure') // define a reactant mass (T or P)SET REACTANT '[stream]' MASS (T P) 'mass' ('temperature' 'pressure') // define reactant input stream mass (T or P)SET REACTANT ALL MASS (T P) 'mass#1' (T#1 P#1) 'mass#2' (T#2 P#2) .... // define all reactant masses (T's or P's)

SET SELECT COMPOUND + (or - !) [NICK [SPECIES]]SET SELECT SOLUTION + (or - !) [NICK-Phase [SPECIES]]SET SELECT GAS (or LIQUID AQUEOUS SOLID) + (or - !) [NICK [SPECIES]] // + to add, - to remove, ! for domant (metastable). // NICK is the database 4-6 letter nickname. // Species is the chemical formula.

SET SPECIES 'chemical_formula' ACT [or LOGACT] 'value' ('value2' 'value3') // redefine a species activity (or Log10(a))SET SUBTITLE 'String' // phase diagram subtitleSET TITLE 'String' // phase diagram titleSET UNITS TK (TC TF) ATM (BAR PSI PA) J (CAL BTU KWH) // define units

SHELL 'CommandLine' // shell commandSHELLEXECUTE 'string' // open a .doc, .fig, .txt, .xls, etc. file in the default Windows application.SHELLWAIT 'CommandLine' // shell and wait for return value $RETVAL

SHOW 'FileName' // show .txt, .res, .tab, .xls, .fig files // and wait until 'GO' button is pressed.SHOWGO 'FileName' // same as SHOW but keep going (no pause)SHOWLASTPD // show last phase digram.SHOWMACRO // show the macro window (see HIDEMACRO)

STEP 'variable' 'value' // increments 'variable' by 'value'STOP // press the macro 'STOP' buttonTERMINATE // quit and then terminate the module (see QUIT)

TIME 'FileName' // stores current time in a text file // - same as WRITE 'FileName' $TIME VARIABLE '%Var1' '%Var2' .. // declare user variables. First character must be '%' // ex: %PAGE %My.Directory. %My.File %Path\ (note '.' and '\' visual for effect) // All user variables have an initial a default value = '0'.VARIABLE '%Var1(n)' '%Var2(m)' '%Var2(n:m)' // declare user tabular variables (dimensions). // ex: %My.Files(2) (i.e variables %My.Files(1) and %My.Files(2)) // Ex: %X(0:2) (i.e variables %X(0), %X(1) and %X(2)) // All user tabular variables have an initial default value = '0'.

VIEWER 'Filename1.fig' // view the figure stored in .fig file (see FIGURE) // Unlike Figure, Viewer can display many figures at the same time.

WAIT // issues prompt to resume or to quitWAIT 'Value1' // pauses 'Value1' seconds (same as PAUSE 'value1')

WINDOWS LOGOFF // quit all applications and logoff the PCWINDOWS REBOOT // quit all applications and reboot the PCWINDOWS SHUTDOWN // quit all applications and shutdown the PC

WRITE 'FileName' 'string' // store 'string' in 'FileName', see APPENDWRITEINI 'IniFile' 'Section' 'Variable' 'Value' // variable value written to *.ini file (see READINI)

WUFE 'FileName' // Wait Until 'FileName' Exists (used to control events)WUME HWND 'Message' // Wait Until 'Message' from HWND[0] exists

Summary of Macro Commands - multiple lines:

Simple LOOP%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 LOOPs%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.

IF...ENDIFIF '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

DOCASE ... ENDDODOCASE %var // The first statement defines the %variableCASE '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 ... etcCASE ELSE // Optional CASE ELSE - if none of the above are true ...ENDDO // ENDDO statement must be present

Summary of Thermochemical, Chemical and Physical $Variables$:   $E_*$, $M_*$, $R_*$, $U_*$

Thermochemical variables are case sensitive and system dependent.  They are defined by the Equi*.dat (or Phas*.dat) file or calculated during the equilibrium calculation ('CALC') and cannot be modified by you (except by editing the Equi*.dat or Phas*.dat file) - see the 'SET' macro command for the thermochemical variables that you can modify.  

An example of the common thermochemical variables is given in the macro file 'EquiEx_List_Results.mac'   A complete example of most calculated thermochemical variables including solution intregral 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'.

Legend: - note, all thermochemical variables are case sensitive.

A = Alpha

a = activityB = BetaC = Cp heat capacityc = compound (pure substance) or molar cpD = data sourceE = extended name (data source and name)e = elements (+ electron phases) i.e. componentsF = total Gibbs free energyf = molar Gibbs free energyg = gramsh = molar enthalpyH = total enthalpyi = integerj = integerl = lbsM = maximum number (total)m = mixture (solution)N = Namen = molesP = Pressureq = quantity (amount) - see input reactantR = Raoultian activity coefficient (gamma) - a = R.Xr = reactantT = temperatureV = VolumeS = entropys = species or molar entropyX = mole fractionx = excessU = unitsV = volumeW = Weight %w = molecular weightZ = atomic number

Input Reactant Values: $R_?*$ : ? = g, l, M, N, n, q, T, P, w, Z; * = 1 - 48.

$R_M$ = number of reactants$R_g*$ = grams of reactant *$R_l*$ = lbs of reactant *$R_N*$ = Name (chemical formula) of reactant *$R_n*$ = moles of reactant *$R_q*$ = quantity (amount) of reactant *$R_T*$ = Temperature of reactant *$R_P*$ = Pressure of reactant *$R_w*$ = molecular weight of reactant *

$R_ei_N$ = element i (1 - 32 or 48) name (chemical symbol)$R_ei_Z$ = element i (1 - 32 or 48) atomic number (0 - 99)$R_ei_w$ = element i (1 - 32 or 48) atomic weight$R_ei_n$ = total moles of element i (1 - 32 or 48) in all reactants$R_ei_g$ = total grams of element i (1 - 32 or 48) in all reactants$R_ei_n*$ = input moles of element i (1 - 32 or 48) in reactant *$R_ei_g*$ = input grams of element i (1 - 32 or 48) in reactant *

Global and Menu Window Values: $M_M?$ - maximum number : ? = e, i, m, p, r, s

$M_Me$ = total elements (+ electron phases) i.e. components$M_Mi$ = total number of species in solutions$M_Mm$ = total number mixtures (solutions)$M_Mp$ = total number of pure compounds$M_Mr$ = total number of reactants$M_Ms$ = total number of species = $M_Mi$ + M_Mp$$M_Mm*$ = total number of species in mixture * = 1 - 40

Units: $U_U?$ or $E_U?$ : ? = E, M, P, T, V

$U_UE$ = units of energy : 'J' 'cal' 'Btu' or 'kWh'$U_UM$ = units of mass : 'mole' 'gram' or 'ft3'$U_UP$ = units of pressure : 'bar' 'atm' 'psi' or 'Pa'$U_UT$ = units of temperature : 'K' 'C' or 'F'$U_UV$ = units of volume : 'litre' or 'ft3'

$E_UE$ = units of energy etc...

Extensive Property Values: $E_E?$ ; ? = A, B, C, F, G, H, P, S, T, V

$E_EA$ = Alpha (4 decimal places)$E_Ea$ = Alpha (free format)$E_EB$ = Beta$E_EC$ = Cp heat capacity$E_EF$ = Gibbs Free Energy$E_EG$ = Gibbs Free Energy$E_EH$ = Enthalpy$E_EP$ = Pressure$E_ES$ = Entropy$E_ET$ = Temperature (2 decimal places)$E_Et$ = Temperature (free format)$E_EV$ = Volume

Elements: $E_ei_*$ - elements (components) i = 1 - 32; * = g, N, n, w, Z

$E_ei_N$ = element i name (chemical symbol)$E_ei_Z$ = $E_ei_Z$ = element i atomic number (0 - 99)$E_ei_w$ = $E_ei_w$ = element i atomic weight$E_ei_mn*$ = total moles of element i in product mixture *$E_ei_mg*$ = total grams of element i in product mixture *$E_ei_sn*$ = total moles of element i in product species *$E_ei_sg*$ = total grams of element i in product species *

Species: $E_s?*$ - product species * = 1 - 700 (or 1500); ? = a, D, d, E, f, g, h, l, N, n, R, s, W, w, X ...

$E_sa*$ = species activity$E_sD*$ = species data source$E_sd*$ = species density (g/l) - compounds only$E_sE*$ = species extended name (data source and name)$E_sf*$ = species partial molar Gibbs free energy G $E_sg*$ = species grams$E_sh*$ = species partial molar H $E_sl*$ = species lbs$E_sN*$ = species name$E_sn*$ = species moles$E_sR*$ = species Raoultian activity coefficient (gamma)

$E_ss*$ = species partial molar S $E_sW*$ = species wt.%$E_sw*$ = species molecular weight$E_sX*$ = species mole fraction

$E_si_?$ = species code number 1 - 700 (or 1500), ? = species name (or extended name)

$E_s0f*$ = species partial molar standard state (zero) G $E_s0h*$ = species partial molar standard state (zero) H $E_s0s*$ = species partial molar standard state (zero) S

$E_sxf*$ = species partial molar excess G $E_sxh*$ = species partial molar excess H $E_sxs*$ = species partial molar excess S

$E_sMc$ = number of compound species$E_sMn$ = number of solution species$E_sMs$ = number of species = $E_sMp$ + $E_sMc$

Solutions: $E_m?$ - product solutions (mixtures) * = 1 - 40; ? = a, D, E, g, m, N, n, ...

$E_ma*$ = mixture activity$E_mD*$ = mixture data source$E_mE*$ = mixture extended name (data source and name)$E_mg*$ = mixture grams$E_Mm*$ = total number of species in mixture $E_mN*$ = mixture name, 1 is always 'GAS'$E_mn*$ = mixture moles

$E_mC*$ = mixture integral total Cp $E_mF*$ = mixture integral total G $E_mH*$ = mixture integral total H $E_mS*$ = mixture integral total S $E_mV*$ = mixture integral total V

$E_mc*$ = mixture integral molar Cp $E_mf*$ = mixture integral molar G $E_mh*$ = mixture integral molar H $E_ms*$ = mixture integral molar S $E_mv*$ = mixture integral molar V

$E_mi_?$ = mixture code number 1 - 40, ? = mixture name (or extended name)

$E_mxf*$ = mixture integral molar excess G $E_mxh*$ = mixture integral molar excess H $E_mxs*$ = mixture integral molar excess S

$E_mxF*$ = mixture integral total excess G $E_mxH*$ = mixture integral total excess H $E_mxS*$ = mixture integral total excess S

Solution Chemical and Physical Properties: $E_CP*_..$ : product solution (mixture) code number * = 1 - 40

$E_CP*_Evolts$ = aqueous Eh

$E_CP*_pH$ = aqueous pH$E_CP*_total_molality$ = total solute molality$E_CP*_ionic_strength$ = ionc strength$E_CP*_osmotic_coeff$ = osmotic coefficient$E_CP*_magnetic_moment$ = magnetic moment$E_CP*_Curie_T$ = Curie temperature$E_CP*_viscosity$ = viscosity$E_CP*_surface_tension$ = surface tension$E_CP*_thermal_cond$ = thermal conductivity$E_CP*_electrical_cond$ = electrical conductivity$E_CP*_surface_energy$ = surface energy$E_CP*_emissivity$ = emissivity$E_CP*_density$ = density$E_CP*_thermal_expan$ = thermal_expansivity$E_CP*_bulk_modulus$ = bulk_modulus$E_CP*_Grueneisen$ = Grueneisen$E_CP*_a_lattice$ = lattice parameter a$E_CP*_c_lattice$ = lattice parameter c

Miscellaneous:

$E_OK$ = 'OK' if calculation successful, else 'NotOK' (follows CALC)

Christopher W. BaleCRCT, May 2012

(End  Macro Processing - FactSage 6.3)