Macro Processing Manual - FactSage 6.

3
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 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 CALC SAVE SHOW SHOW SAVE END

EQUI1234.DAT EQUI1234.TXT EQUI1234.TAB EQUI1234.XML MIXT1234.DAT GAS

// // // // // // //

Load the Equilib File 1234 and calculate the equilibrium. Save results in EQUI1234.Txt Save results & display spreadsheet EQUI1234.tab Save results & display in XML format Save computed gas phase in a MIXT*.DAT stream 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 CALC SHOW SHOW SHOW SHOW END EQUI1234.DAT EQUI1234.TXT EQUI1234.FIG EQUI1234.TAB EQUI1234.XML

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 %Page = 2 %Path\ %ResultsDir %Page %TextFile // Declare 4 variables. "\" is for visual effect // %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'. ASKOK 'question or statement' // Ask the user to agree by clicking on an 'OK' button //- the results is 'OK' or '0'

%var

Examples: %Path\ = "C:\My // // %1 ASKOK Do you // %DIR: // %DIR is the default directory and it is automatically defined by the // program. You may reset the value of %DIR. %DIR %DIR %DIR = = = 'string' // Set the default directory for all the files. 'string' ASK 'description' // Ask for the directory - default setting is 'string' $FSDIR // set default directory to the FactSage directory // where FACTWIN.INI resides (typically C:\FactSage\) // The default file directory is 'c:\MyFiles\' // hence, 'OPEN EQUI1234.DAT' is the same as // 'OPEN %DirEQUI1234.DAT' and // 'OPEN C:\MyFiles\EQUI1234.DAT'. // $FSDIR is the FactSage directory. // In most cases the default directory %DIR is now Files\" ASK Enter the name of My Files directory Ask user for the value of %Path\ - the default is 'C:\My Files\' wish to keep My Files directory as %Path\? if he agrees then %1 = 'OK' else '0'

Examples: %DIR = C:\MyFiles\

%DIR

$FSDIR

'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 CALC SAVE %Path\Mytext.Txt // Open Equilib file in default directory DIR% // calculate the equilibrium, and then // save results in 'C:\My Files\MyText.txt'.

6.3 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, $RNDINT, $MIN, $MAX, $MINI, $MAXI, $MEAN, $MEDIAN, $SORTDEC, $SORTDECI, $SORTINC, $SORTINCI d) Mathematical expressions - $MATH e) 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') > 97 $CHR('value') $CHR(97) -> 'a' $LCASE('string') $UCASE('string') $LEFT('value','string') 'string' $RIGHT('value','string') 'string'.

// Ascii value of a character. // $ASC(1) -> 48 ; $ASC(A) -> 65 ; $ASC(a) // Character from its ascii value. // $CHR(48) -> '1' ; $CHR(65) -> 'A' ; // Lower case characters of 'string'. // $LCASE(I Love You) -> 'i love you' // Upper case characters of 'string'. // $UCASE(I Love You) -> 'I LOVE YOU' // 'value' left characters of trimmed // $LEFT(3,I Love You) -> 'I L'

// 'value' right characters of trimmed // $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') 'old' by 'new' // in 'string' replace all occurences of

// $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) $FORMATF('m' 'n' 'value') // Fm.n numerical format // $FORMATF(12 4 1.2345678)

-> ' -> '

0.1234E+01' 1.2345' 1.2345' 1.2345e+22' 1'

$FORMATG('m' 'n' 'value') // Gm.n general format // $FORMATG(12,4,1.2345678) -> ' // $FORMATG(12,4,123.45678e20) -> ' $FORMATI('m' 'value') Examples: // Im integer format // $FORMATI(12,1.2345678) -> '

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

$MAX('value1' 'value2' ...) $MAXI('value1' 'value2' ...) list // $MAX(0 -1.5 2 3) -> // $MAXI(0 -1.5 2 3) -> $MEAN('value1' 'value2' ...) $MEDIAN('value1' 'value2' ...) // $MEAN(1 15 2) -> // $MEDIAN(1 15 2) ->

// Maximum value in the list // Item that has the maximum value in the 3 4 // Average value in the list // Median value in the list 6 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) e) File manipulation - $EXIST, $FILEDIR, $FILENAME, $SCANDIR

J/mol

$EXIST('file name') else 0

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

$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 (macro lines) ... %3 LOOP %3 = 2 TO 4 %4 = 1 TO -1 STEP -2 (macro lines) ... %4 LOOP %3 LOOP // %3 has 9 values: 2 2.5 3 3.5 ... 6 // These lines will be executed 9 times // unless they contain a GOTO statement. // // // // %3 has 3 values: 2 3 and 4 %4 has 2 values: 1 and -1 These lines will be executed 6 times unless they contain a GOTO statement.

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' GOTO END // jump to the line MARK 'word'. // A GOTO statement cannot be inside IF ....ENDIF // 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 Example: GOTO END // End of the macro processing. // All comments after 'END' are ignored . // 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 (macro lines) // The first statement, '?' may // contain 'AND' or 'OR' operators.

... ELSEIF 'va1ue3' '?' 'value4' THEN (macro lines) ... ELSE (macro lines) ... ENDIF Example:

// One or more ELSEIF statements // are optional. // One ELSE statement is optional. // ENDIF statement must be present

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 // %2 = EQUILIB.TXT CASE 2 %2 = EQUILIB.RES CASE 3 %2 = EQUILIB.XLS CASE -1 // GOTO END CASE ELSE // GOTO TOP ENDDO // SAVE %2 // DOCASE Example 2: DO CASE %1 CASE 0 1 2 (macro lines) CASE 3 TO 50.5 (macro lines) CASE IS <= -100 (macro lines) CASE IS <> 1000 (macro lines) CASE ELSE (macro lines) ENDDO

The CASE statement has a fixed value (not %var)

Quit. Invalid, try again. End Save the file.

// If %1 has the value 0, 1 or 2 // If %1 is in the range 3 to 50.5 // If %1 is less than or equal to -100 // If %1 is not equal to 1000

// 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 ERRORON 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 // suppress error handling (see ERRORON) - use with caution! // resume error handling (see ERROROFF) - this is the default

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 Wordpad etc. SHELLEXECUTE %4MyText.Doc SHELLEXECUTE %4MyText.Xls SHELLEXECUTE %4MyText.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 'number' Example: PAUSE 10 10) // wait for the user to click 'OK' to continue // wait 'number' seconds before continuing // processing waits 10 seconds and then proceeds (same as WAIT

// Open C:\Dummy\MyText.txt with Notepad or // Open C:\Dummy\MyText.txt with Word // Open C:\Dummy\MyText.txt with Excel // Open C:\Dummy\MyText.xlm with Fact-XLM

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 file APPEND '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 DELETE MyText.Txt

// Deletes file C:\Dummy\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 OLEn OLEn OLEn OLEn CLEAR // AUTOFIT // WIDTH 'value' // HEIGHT 'value' // CLEAR (or AUTOFIT // OLEn ROWS '2:3' CLEAR (or ...) // OLEn NAME 'NAME' CLEAR (or ...) // OLEn RANGE 'B1:C4' CLEAR (or ...) // CELLS ALL CELLS ALL CELLS ALL CELLS ALL COLUMNS 'F:F' clear all cells in the WorkSheet auto fit column width for all cells set all columns to a common width set all rows to a common height or WIDTH 'value' or HEIGHT 'value') format columns - see 'CELLS' format rows - see 'CELLS' format a name - see 'CELLS' 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 worksheet NAME OLEn DELETE 'name' // delete the range name in the worksheet NAME OLEn NEW 'name' 'An' 'Bn:Cm' ('RnCm:RiCj') // define a new range name in the worksheet 6.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' HIDE HIDEMACRO // A remark - line of comments in the Macro Window // FactSage windows will become hidden // - same effect as clicking on Macro 'Hide'. // Macro Window will become hidden (minimized)

SHOW

// FactSage windows will become visible // - same effect as clicking on Macro 'Show'. // post a message on the screen

MSGBOX 'string'

MSGBOX FILENAME 'Filename' // post contents of a text file on the screen 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 (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 VALUE SET COLOR VALUE 'Value' // value (typically T) in the range 'MinValue' 'MaxValue' - see SET COLOR LIMITS

SET TITLE 'String' SET SUBTITLE 'String'

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

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. 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 format SET OUTPUT FORMAT FACT // FACT format only SET OUTPUT FORMAT FACT CHEMSAGE // ChemSage format only For 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 (true) SET PARAMETERS SET PARAMETERS SET PARAMETERS SET SET SET SET PARAMETERS PARAMETERS PARAMETERS PARAMETERS DISPLAY FULLSCREEN 0 (or 1) // 0 is off (false) and 1 is on DISPLAY COLOR DISPLAY TITLE DISPLAY SUBTITLE SHOW SHOW SHOW SHOW STATUS TIELINES WARNING LABELS 0 0 0 0 0 (or 1) 0 (or 1) 0 (or 1) (or (or (or (or 1) 1) 1) 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 15

SET SET SET SET SET SET SET SET SET SET SET

PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS

LABELS LABELS LABELS LABELS LABELS LABELS

BOLD ITALIC UNDERLINE LINEWIDTH LINECOLOR ALWAYS

0 (or 1) 0 (or 1) 0 (or 1) '1-20' // i.e. 0.1 - 2.0 mms 'color' (or '0-15') // ex: RED (or 9) 0 (or 1) 0 0 0 0 0 (or (or (or (or (or 1) 1) 1) 1) 1) 'color' (or '0-15')

POLYTHERMAL POLYTHERMAL POLYTHERMAL POLYTHERMAL POLYTHERMAL

TMINMAX COMPOSITIONS PHASES NUMBER COLOR

SET VARIABLES SET VARIABLES temperature SET VARIABLES projection) SET VARIABLES

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

SET VARIABLES P MAX 'value' // Maximim pressure SET 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 #1 SET VARIABLES C1 MIN (or CONSTANT) 'value' // Minimmm composition #1 SET VARIABLES C2 (or C3 or ... ) etc. // Composition #2 (or #3 or ... ) etc. 6.13 Macro Windows Commands: LOGOFF, 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 CALC SAVE EQUI1234.TXT WINDOWS SHUTDOWN // // // // // Load an Equilib file calculate save the results then quit FactSage (and any other appliactions) and turn off the PC when done.

END 6.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' the same time. Examples: // Use Viewer to display the figure. // Unlike Figure, Viewer can display many figures at

%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 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 ====================== REM REM Loads Equilib file Ex_CH4-O2, calculates and displays results. %DIR = $FSDIR // Set user default directory to FactSage directory. // Load Equilib file

OPEN EQUIEx_CH4-O2.DAT CALC SHOW Equilib.txt SHOW Equilib.tab spreadsheet. SHOW Equilib.xml END

// and calculate the equilibrium. // Save in Equilib.txt and display the output. // Save in Equilib.tab and display the tabular // Save in Equilib.xml and display in xml format. // 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 ====================== 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 IF %1 > 9999 GOTO Bottom // %1 must be in the range 1 to 9999 // - 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 MARK IgnorePage HIDE GOTO Begin // Ex: save page 14 in 'C:\FactSage\EQUIP14.TXT'. // Hide Equilib windows. Same as clicking 'Hide'. // 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 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 SAVE EQUI%1.TXT [Page]

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 REM REM REM REM REM HIDE File EquiExample_3.mac - FactSage 5.3 (2004-06-25) ====================== This macro processes all the EQUI*.dat files where * = %First to %Last. You are prompted to enter the %First and %Last values. The output results are stored in EQUI*.TXT and EQUI*.RES // Hide the Equilib windows. // - this speeds up the processing. // Declare user variables

VARIABLE %Results %First %Last %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 %Last 10

ASK ASK

Enter the first (minimum) Equilib file number (1 to 9999). // Ask for the first file %First (default 1) 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 MARK Top // %1 is the first file // 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 CALC SAVE %ResultsEqui%1.txt SAVE %ResultsEqui%1.res MARK NextOne %1 STEP 1 IF %1 <= %Last GOTO Top // Load the file from the default directory // and then calculate. // Save text output in equi*.txt // Save results in equi*.res - this file will // be accessible from the Results module. // A marker - see 'GOTO NextOne'. // Increase file number %1 by 1 // 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 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 REM REM REM REM REM REM REM %DIR File EquiExample_4.mac - FactSage 5.3 (2004-06-22) ====================== This macro runs Equilib in the background. It gets the contents of the first word of a text file Equilib4.txt that tells it the number of the file to open. This operation is repeated every 5 seconds until the first line in Equilib4.txt is '0' in which case it quits the macro processing. %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 MARK Cycle // %2 is given the initial value '0' - see later on. // 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 IF %3 = 0 GOTO END OPEN equi%1.dat CALC %4 %9Equi%1.txt SAVE %4 MARK Bottom WAIT 5 GOTO Cycle END // Read first line of equi%1.dat and store in %3. // Quit if file equi%1.dat does not exist. // Load file equi%1.dat from default directory // and then calculate. // %4 is the name of the results save file, // ex: 'c:\FactSage\Equi1234.txt' // and then save it. // A marker - see 'GOTO Bottom' // Pause for 5 seconds // and then repeat the cycle. // 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 REM REM REM REM

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

%1 1 ASK Enter the Phase Diagram file number (1-9999) or name $EXIST PHAS%1.DAT IF $EXIST = 0 GOTO END // Quit if phase diagram file empty or not found HIDE OPEN PHAS%1.DAT CALC SAVE PHAS%1.FIG SHOW FIGURE PHAS%1.FIG // Hide the windows // Load file PHAS*.DAT // and calculate the phase diagram. // Save in PHAS*.FIG // Show the windows // 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 REM REM REM REM REM REM File PhasExample_3.mac - FactSage 5.3 (2004-06-22) ====================== This macro processes all the PHAS*.dat files where * = %1 to %LAST (in the range 1 to 9999). You are prompted to enter the default directory (%DIR), and to enter the first (%1) and last (%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, %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) ASK Enter the last (maximum) file number. // Ask for the last file %LAST (default 10) // A marker - see 'GOTO Top' later on.

%LAST 10 MARK Top

%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 OPEN phas%1.dat CALC // Show listing in the Macro Window // Load the file from the default directory // and then calculate. // Save figure output in phas*.fig // Suppress listing in the Macro Window // A marker - see 'GOTO NextOne'. // Increase file number %1 by 1. // Note, 'STEP' only works with the %1 to %9 variables. // and cycle if not > last file. // Terminate macro processing.

SAVE %RESULTS.phas%1.fig PRINTOFF MARK NextOne %1 STEP

IF %1 <= %LAST GOTO Top END

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 example SHELLWAIT %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.234e10) $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 time Summary of Thermochemical $Variables - the thermochemical variables are listed at the end. Summary of Macro %Variables and associated commands: %DIR %TITLE %var %var %var %var %var %var %var %var = = = = = = = = // default directory // title of current application 'value' // set the value of a %variable 'value' ASK 'prompt' // ask for the VALUE (default IS 'VALUE') 'FileName' READ // variable is the line read from the file 'FileName' READ CONTENTS // variable is contents of the text file // including {CR} {Tab} etc. 'FileName' READ LINE // variable is the line read from the text // file (same as READ) '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' 'FileName' READ WORD // variable is first word of the line read from the text file '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' 'FileName' READ WORDLINE 'm' 'n' // variable is word m of line n in the text file 'FileName' READ LINEWORD 'n' 'm' // variable is word m of line n in the text file FACTOR 'value' // factors (multiplies) %variable by 'value' (see STEP) // i.e. %variable = %variable x 'value' // Same as '%var = $MATH(%var * 'value')' GETMESSAGE // wait for value sent in message (SendMessage) HWND 'Title' // variable value is handle of application 'title'

%var %var %var

= = =

%var %var

= =

%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') // ex: $ABS(-1.2) -> // Absolute value 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) $FORMATE( 'm' 'n' 'value') // Em.n scientific format

-> ' Hello World'

// ex: $FORMATE( 12 4 1.2345678) -> $FORMATF( 'm' 'n' 'value') // Fm.n numerical format // ex: $FORMATF( 12 4 1.2345678) -> $FORMATG( 'm' 'n' 'value') // Gm.n general format // ex: $FORMATG( 12 4 1.2345678) // ex: $FORMATG( 12 4 123.45678e20) $FORMATI( 'm' 'value' // Im integer format // ex: $FORMATI( 12 1.2345678) ->

' '

0.1234E+01' 1.2345' 1.2345' 1.2345e+22' 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' ...) $MAXI('value1' 'value2' ...) list // $MAX(0 -1.5 2 3) -> // $MAXI(0 -1.5 2 3) -> // Maximum value in the list // Item that has the maximum value in the 3 4

$MID('value1' 'value2' 'string') // starting at character 'value1' returns //'value2' characters of trimmed 'string'

// ex: MID 3 5

I Love U

-> 'Love' // Minimum value in the list // Item that has the minimum value in the -1.5 2

$MIN('value1' 'value2' ...) $MINI('value1' 'value2' ...) list // $MIN(0,-1.5,2,3) -> // $MINI(0,-1.5,2,3) ->

$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 OLEn OLEn OLEn OLEn CLEAR // AUTOFIT // WIDTH 'value' // HEIGHT 'value' // CLEAR (or AUTOFIT // OLEn ROWS '2:3' CLEAR (or ...) // OLEn NAME 'NAME' CLEAR (or ...) // OLEn RANGE 'B1:C4' CLEAR (or ...) // OLEn GOTO 'RnCm' cell is visible) %var // // %var // = OLEn variable ex: B5 = OLEn variable CELLS ALL CELLS ALL CELLS ALL CELLS ALL COLUMNS 'F:F' clear all cells in the WorkSheet autofit column width for all cells set all columns to a common width set all rows to a common height or WIDTH 'value' or HEIGHT 'value') format columns - see 'CELLS' format rows - see 'CELLS' format a name - see 'CELLS' format a range - see 'CELLS'

// put focus on this cell (scroll until the

READ 'An' ('RnCm' 'An:Bm' 'RnCm:RiCj' 'name') value(s) read from cell (or row & col or range). R5C6 B5:D10 R5C2:R10C4 RangeName WRITE 'An' ('RnCm' 'An:Bm' 'RnCm:RiCj' 'name') value(s) written to cell (or row & col or range).

NAME OLEn CLEAR 'name' // clear the contents of a range name in the worksheet NAME OLEn DELETE 'name' // delete the range name in the worksheet NAME 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 CAPTION 'string' CLOSE 'Filename' COPY 'Source' 'Target' DELETE 'FileName' // // // // press the module set macro window used with READ copy .txt, .res, 'Calculate >>' button caption go to beginning of file .tab, .xls, .fig files

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

ERROROFF with caution! ERRORON the default setting. END EXIT

// suppress error handling (see ERRORON) - use // resume error handling (see ERROROFF) - this is // last line in the macro file // 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 HIDEMACRO IF 'Value1' = [< THEN ... ENDIF) INSERT 'FileName' // insert text 'FileName' into current macro. INSERT GETMESSAGE // waits & inserts message (SendMessage) into current macro. KILL 'FileName' LOADONLY LOG 'Filename' MARK 'word' MSGBOX 'string' MSGBOX FILENAME 'Filename' NAME 'Source' 'Target' OPEN 'FileName' PAGEKEEP PAGENEW PAUSE PAUSE 'value' PRINTOFF PRINTON // // // // // delete .txt, .res, .tab .xls, .fig files (same as DELETE) create SGMX files without calculating. log session in file (default macro.log) a marker - used with GOTO 'word' // hide FactSage module // hide the macro window (see SHOWMACRO) >= <>] 'Value2' GOTO 'mark' // 'IF' statement has 6 words (also see IF ...

>

=<

// post a message // post contents of a file // rename .txt, .res, .tab .xls, .fig files // open (load) EQUI*.DAT, PHAS*.DAT files

// Keep results from previous CALC(s) and // append current CALC results as new pages. // (Default setting) - negates option PAGEKEEP // issue prompt to resume or quit processing // wait 'value' seconds (same as WAIT 'value') // suppress listing in the macro window // resume listing in the macro window

POSTMESSAGE 'TargetHwnd' 'string' // post message in another application POSTMESSAGE 'TargetHwnd' FILENAME 'Filename' // post file contents in another application. QUIT // exit REM 'string' // comments line in the macro window REWIND '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 RESULTS SAVE 'Name.FIG' // save figure in a *.FIG file accessible by module FIGURE SAVE '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 application SENDMESSAGE '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 VALUE SET 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 subtitle SET TITLE 'String' // phase diagram title SET UNITS TK (TC TF) ATM (BAR PSI PA) J (CAL BTU KWH) // define units SHELL 'CommandLine' // shell command SHELLEXECUTE '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' SHOWGO 'FileName' SHOWLASTPD SHOWMACRO STEP 'variable' 'value' STOP TERMINATE TIME 'FileName' // // // // // show .txt, .res, .tab, .xls, .fig files and wait until 'GO' button is pressed. same as SHOW but keep going (no pause) show last phase digram. show the macro window (see HIDEMACRO)

// increments 'variable' by 'value' // press the macro 'STOP' button // quit and then terminate the module (see QUIT) // 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' FIGURE) at the same time. WAIT WAIT 'Value1' 'value1') WINDOWS LOGOFF WINDOWS REBOOT WINDOWS SHUTDOWN // issues prompt to resume or to quit // pauses 'Value1' seconds (same as PAUSE // quit all applications and logoff the PC // quit all applications and reboot the PC // quit all applications and shutdown the PC // view the figure stored in .fig file (see // Unlike Figure, Viewer can display many figures

WRITE 'FileName' 'string' // store 'string' in 'FileName', see APPEND WRITEINI 'IniFile' 'Section' 'Variable' 'Value' // variable value written to *.ini file (see READINI) WUFE 'FileName' events) WUME HWND 'Message' // Wait Until 'FileName' Exists (used to control // 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...ENDIF IF 'value1' '?' 'value2' THEN (macro lines) ... ELSEIF 'va1ue3' '?' 'value4' THEN (macro lines) ... ELSE (macro lines) ... ENDIF // The first statement, '?' may // contain 'AND' or 'OR' operators. // One or more ELSEIF statements // are optional. // One ELSE statement is optional. // ENDIF statement must be present

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

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 a B C c D E e F f g h H i j l M m N n P q R r T V S s X x U V W w Z = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = Alpha activity Beta Cp heat capacity compound (pure substance) or molar cp data source extended name (data source and name) elements (+ electron phases) i.e. components total Gibbs free energy molar Gibbs free energy grams molar enthalpy total enthalpy integer integer lbs maximum number (total) mixture (solution) Name moles Pressure quantity (amount) - see input reactant Raoultian activity coefficient (gamma) - a = R.X reactant temperature Volume entropy species or molar entropy mole fraction excess units volume Weight % molecular weight atomic number * = 1 -

Input Reactant Values: $R_?*$ : ? = g, l, M, N, n, q, T, P, w, Z; 48. $R_M$ $R_g*$ $R_l*$ $R_N*$ $R_n*$ $R_q*$ $R_T*$ $R_P*$ = = = = = = = = number of reactants grams of reactant * lbs of reactant * Name (chemical formula) of reactant * moles of reactant * quantity (amount) of reactant * Temperature of reactant * 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$ $M_Mi$ $M_Mm$ $M_Mp$ $M_Mr$ $M_Ms$ $M_Mm*$ = = = = = = total elements (+ electron phases) i.e. components total number of species in solutions total number mixtures (solutions) total number of pure compounds total number of reactants total number of species = $M_Mi$ + M_Mp$ = total number of species in mixture * = 1 - 40

Units: $U_U?$ or $E_U?$ : ? = E, M, P, T, V $U_UE$ $U_UM$ $U_UP$ $U_UT$ $U_UV$ = = = = = units units units units units of of of of of energy mass pressure temperature volume : : : : : 'J' 'cal' 'Btu' or 'kWh' 'mole' 'gram' or 'ft3' 'bar' 'atm' 'psi' or 'Pa' 'K' 'C' or 'F' '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$ $E_Ea$ $E_EB$ $E_EC$ $E_EF$ $E_EG$ $E_EH$ $E_EP$ $E_ES$ $E_ET$ $E_Et$ $E_EV$ = = = = = = = = = = = = Alpha (4 decimal places) Alpha (free format) Beta Cp heat capacity Gibbs Free Energy Gibbs Free Energy Enthalpy Pressure Entropy Temperature (2 decimal places) Temperature (free format) 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*$ $E_sD*$ $E_sd*$ $E_sE*$ $E_sf*$ $E_sg*$ $E_sh*$ $E_sl*$ $E_sN*$ $E_sn*$ $E_sR*$ $E_ss*$ $E_sW*$ $E_sw*$ $E_sX*$

= = = = = = = = = = = = = = =

species species species species species species species species species species species species species species species

activity data source density (g/l) - compounds only extended name (data source and name) partial molar Gibbs free energy G grams partial molar H lbs name moles Raoultian activity coefficient (gamma) partial molar S wt.% molecular weight 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*$ $E_mD*$ $E_mE*$ $E_mg*$ $E_Mm*$ $E_mN*$ $E_mn*$ $E_mC*$ $E_mF*$ $E_mH*$ $E_mS*$ $E_mV*$ $E_mc*$ $E_mf*$ $E_mh*$ $E_ms*$ $E_mv*$ = = = = = = = = = = = = = = = = = mixture activity mixture data source mixture extended name (data source and name) mixture grams total number of species in mixture mixture name, 1 is always 'GAS' mixture moles mixture mixture mixture mixture mixture mixture mixture mixture mixture mixture integral integral integral integral integral integral integral integral integral integral total total total total total molar molar molar molar molar Cp G H S V Cp G H S 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$ $E_CP*_pH$ $E_CP*_total_molality$ $E_CP*_ionic_strength$ $E_CP*_osmotic_coeff$ $E_CP*_magnetic_moment$ $E_CP*_Curie_T$ $E_CP*_viscosity$ $E_CP*_surface_tension$ $E_CP*_thermal_cond$ $E_CP*_electrical_cond$ $E_CP*_surface_energy$ $E_CP*_emissivity$ $E_CP*_density$ $E_CP*_thermal_expan$ $E_CP*_bulk_modulus$ $E_CP*_Grueneisen$ $E_CP*_a_lattice$ $E_CP*_c_lattice$ Miscellaneous: $E_OK$ = 'OK' if calculation successful, else 'NotOK' (follows CALC) Christopher W. Bale CRCT, May 2012 (End Macro Processing - FactSage 6.3) = = = = = = = = = = = = = = = = = = = aqueous Eh aqueous pH total solute molality ionc strength osmotic coefficient magnetic moment Curie temperature viscosity surface tension thermal conductivity electrical conductivity surface energy emissivity density thermal_expansivity bulk_modulus Grueneisen lattice parameter a lattice parameter c