1. Introduction1. 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
12. What's New in Macro Processing
For example you can use the macro to read input reactant amounts, select the species, define the product T and P, etc. from say an Excel spreadsheet, perform the usual Equilib calculation, then direct the results to a text file, Excel spreadsheet, etc. in any format you define.
As a simple example of Macro processing go to the Equilib Reactants Window and click on 'File > Macro processing > Edit Macro ..' and click on the 'Macros Directory'. Select the file EquiEx_List_Results.mac. This is an example of a macro file used in Macro processing.
Now run the macro - in the Reactants Window click on 'File > Macro processing > Run Macro ..'. When asked questions use the default answers. When done look at the output in the Equilib Results Window and compare with the text file (Dummy.txt) that you see in the background.
You may display the results
for any of your stored Equilib calculations - simply provide the
full file name (ex: c:\FactSage\EQUI1234.dat) when asked to
'Enter the name of an Equilib file'
.
2. Macro
Commands
A macro file has 4 principal commands: OPEN,
CALC, SAVE and SHOW
For Equilib calculations you can open (OPEN) a previously stored system
(EQUI*.dat file), calculate (CALC) the equilibrium, and then save (SAVE or
SHOW) the results in a results (*.res), text (*.txt), figure (*.fig), tabular
(*.tab), Excel (*.xls) file and Xml (*.xml) files.
For Phase Diagram calculations the same OPEN and CALC commands are
available, but the results must to stored (SAVE and SHOW) in a figure (*.fig)
file.
Because macro processing is mainly used in Equilib calculations, most
of this article deals with the Equilib module. Examples
of Phase Diagram macro files are given at the end - see 8.
Phase Diagram Macro Files.
The following 7 lines illustrate the contents of a simple Equilib macro file
- comments following '//' are ignored in the macro processing:
OPEN EQUI1234.DAT // Load the Equilib File 1234 CALC // and calculate the equilibrium. SAVE EQUI1234.TXT // Save results in EQUI1234.Txt SHOW EQUI1234.TAB // Save results & display spreadsheet EQUI1234.tab SHOW EQUI1234.XML // Save results & display in XML format SAVE MIXT1234.DAT GAS // Save computed gas phase in a MIXT*.DAT stream END // Terminate the macro processing.
6.1 Macro variables %Variables - simple %variables, %DIR, %1, %2, ... %9, VARIABLE, DIM, ASK, ASK_OK, ASK_BROWSEIn addition to the four principal commands (OPEN, CALC, SHOW and SAVE) other commands, functions and variables are available.
6.2 Macro functions $Functions - for string manipulation, output formatting, mathematical functions & expressions, file managing
6.3 Macro commands for increments and cycles - STEP, FACTOR, LOOP
6.4 Macro commands for simple program flow - MARK, GOTO, IF ... GOTO and END
6.5 Macro commands for branched program flow - IF ... THEN ... ENDIF, DOCASE ... ENDDO
6.6 Macro commands for advanced features - ERROR_OFF, ERROR_ON, RUNMACRO, SHELL, SHELL_EXECUTE, SHELL_WAIT ...
6.7 Macro commands for reading and writing text and ini files - READ, WRITE, APPEND, TABS ...
6.8 Macro commands for manipulating files - COPY, NAME and KILL
6.9 Macro commands for Excel Worksheets and Text Spreadsheets - linking via OLEn
6.10 Macro user-defined $Functions and Procedures - FUNCTIONS ... END FUNCTIONS, PROCEDURES ... END PROCEDURES
6.11 Macro 1-D and 2-D %Variables - tables and arrays, REDIM, $ENUM
6.12 Macro thermochemical variables - $variables$, SET
6.13 Macro SET Commands - for data search and options, reactants, species selection, output formatting, plotting, etc.
6.14 Macro Windows commands - LOG_OFF, REBOOT, SHUTDOWN
6.15 Macro display commands - REM, SHOW, HIDE, HIDE_MACRO and MSGBOX
6.16 Macro Phase Diagram commands - FIGURE, SUPERIMPOSE, VIEWER
6.17 Macro Debugging commands - DEBUG /ON, DEBUG 'caption', DEBUG /DEL
VARIABLE, DIM :
VARIABLE '%var1' '%var2' '%var3' '%var4'
// Use VARIABLE or DIM to declare the list of variables in addition to %DIR, %1 ... %9.
// ex: 'DIM %PAGE %My.Directory. %My.File %Path\\' (note '.' and '\' for visual effect)
// All user variables have an initial default value = '0'.
// It is not necessary to declare %1 %2.. %9 - they are already are declared for you.
// All %variables must be unique and non-ambiguous - avoid short names
// - for example %P is not permitted since it can be confused with DIM %PAGE.
// Note DIM %12 is not permitted since it can be confused with %1.
%var = 'value'
// This is how you assign a value (i.e. word, string, number) to %Var.
// Use quotes "" if 'value' contains spaces.
// The '=' is optional
// Use REDIM (see later on) to modify and redeclare a list of variables.
Examples:
DIM %Path\ %ResultsDir %Page %TextFile
// Declare 4 variables. "\" is for visual effect
%Page = 2 // %Page is '2'.
%Path\ = "C:\My Files\" // %Path\ is 'C:\My Files\'
%ResultsDir = "C:\My Files\My Results\"
// %ResultsDir is 'C:\My Files\My Results\'
%ResultsDir = "%Path\My Results\"
// %ResultsDir is 'C:\My Files\My Results\'
// - same value as the previous line.
%TextFile = %Path\Input.txt
// %TextFile is 'C:\My Files\Input.txt'
ASK, ASK_OK, ASK_BROWSE:
%var = 'value' ASK 'description'
// Ask the user for the value of %var
// - the default value is 'value'.
%var = ASK_OK 'question or statement'
// Ask the user to agree by clicking on an 'OK' button
// - the result is 'OK' or '0'
%var = 'default file name' ASK_BROWSE 'file masks | filters' 'statement'
// Ask the user to enter a file name using the Windows browser
// - the result is the name of the file
Examples:
%Path\ = "C:\My Files\" ASK Enter the name of My Files directory
// Ask user for the value of %Path\
// - the default is 'C:\My Files\'
%1 ASK_OK Do you wish to keep My Files directory as %Path\?
// if he agrees then %1 = 'OK' else '0'
%1 = "C:\Factsage\Equi1.dat" ASK_BROWSE "(Equi*.dat)|Equi*.dat" "Select any Equi*.dat file "
// Ask user to select an Equi*.dat file - the default is C:\Factsage\Equi1.dat
// %1 is the name of the file he enters
%DIR:
// %DIR is the default directory or folder and it is automatically defined by the program.
// You may change the value of %DIR. Directory and folder are the same thing.
%DIR = 'string' // Set the default directory for all the files.
%DIR = 'string' ASK 'description'
// Ask for the directory - default setting is 'string'
%DIR = $FSDIR // set default directory to the FactSage directory $FACTSAGE_DIR\
// where FACTWIN.INI resides (typically C:\FactSage\)
Examples:
%DIR = C:\MyFiles\ // The default file directory is 'c:\MyFiles\'
// hence, 'OPEN EQUI1234.DAT' is the same as
// 'OPEN %DirEQUI1234.DAT' and
// 'OPEN C:\MyFiles\EQUI1234.DAT'.
%DIR = $FSDIR // $FSDIR or $FACTSAGE_DIR\ is the FactSage directory.
// In most cases the default directory %DIR is now 'C:\FactSage\'
%DIR = %DIR ASK Enter the default directory for all files:
// Ask for the directory - default setting is the current value
%DIR = "c:\My Dir\" ASK Enter the default directory for the files:
// Ask for the directory - default setting is 'c:\My Dir\'.
OPEN Equi1.dat // Open Equilib file in default directory DIR%
CALC // calculate the equilibrium, and then
SAVE %Path\Mytext.Txt // save results in 'C:\My Files\MyText.txt'.
6.2 Macro $Functions
b) Output formatting
c) Mathematical functions
d) Mathematical expressions
e) File managing
f) Chemical functions
g) System functions
a) String manipulation
- $ASC, $CHR, $LCASE, $UCASE, $LEFT, $RIGHT, $MID, $REPLACE
- $FORMATE, $FORMATF, $FORMATG, $FORMATI
- $ABS, $EXP, $LN, $LOG10, $FIX, $INT, $RND, $RND_INT, $MIN, $MAX, $MINI, $MAXI, $MEAN, $MEDIAN, $SORTDEC, $SORTDECI, $SORTINC, $SORTINCI
- $MATH
- $EXIST, $FILE_DIR, $FILE_SHORTDIR, $FILE_NAME, $FILE_BYTES, $SCAN_DIR
- $ELEMENT, $MOLWT, $CONSTANT
- $BLANK, $CHEMSAGE_DIR\, $COMMAND, etc.
Most $Functions have arguments
contained within the parentheses, (). The arguments are separated by spaces
or commas and may be a %variable, a thermochemical $variable$, but not another
$function.
A $function may appear anywhere on the line (except at the beginning which contains
either a %variable or macro command) and the line may have several $functions.
An example of most $functions is given in the macro file EquiEx_List_Functions.mac.
a) String manipulation - $ASC, $CHR, $LCASE, $UCASE, $LEFT, $RIGHT, $MID, $REPLACE
$ASC('character') // Ascii value of a character.
// $ASC(1) -> 48 ; $ASC(A) -> 65 ; $ASC(a) -> 97
$CHR('value') // Character from its ascii value.
// $CHR(48) -> '1' ; $CHR(65) -> 'A' ; $CHR(97) -> 'a'
$LCASE('string') // Lower case characters of 'string'.
// $LCASE(I Love You) -> 'i love you'
$UCASE('string') // Upper case characters of 'string'.
// $UCASE(I Love You) -> 'I LOVE YOU'
$LEFT('value','string') // 'value' left characters of trimmed 'string'
// $LEFT(3,I Love You) -> 'I L'
$RIGHT('value','string') // 'value' right characters of trimmed 'string'.
// $RIGHT(3,I Love You) -> 'You'
$MID('value1','value2','string') // starting at character 'value1' it returns
// 'value2' characters of trimmed 'string'.
// $MID(3,4, I Love U ) -> 'Love'
$REPLACE('string','old','new') // in 'string' replace all occurences of 'old' by 'new'
// $REPLACE(your house and your dog,your,my)
// -> 'my house and my dog'
b) Output formatting - $FORMATA, $FORMATE, $FORMATF, $FORMATG, $FORMATI
See EquiEx_List_Functions.mac for examples of $FORMATA, $FORMATE, $FORMATF, $FORMATG and $FORMATI
$FORMATA('m' 'string') // Am character format
// $FORMATA(12 Hello World) -> ' Hello World'
// $FORMATA(12 Hello World) -> ' Hello'
$FORMATE('m' 'n' 'value') // Em.n scientific format
// $FORMATE(12,4,1.2345678) -> ' 0.1234E+01'
$FORMATF('m' 'n' 'value') // Fm.n numerical format
// $FORMATF(12 4 1.2345678) -> ' 1.2345'
$FORMATG('m' 'n' 'value') // Gm.n general format
// $FORMATG(12,4,1.2345678) -> ' 1.2345'
// $FORMATG(12,4,123.45678e20) -> ' 1.2345e+22'
$FORMATI('m' 'value') // Im integer format
// $FORMATI(12,1.2345678) -> ' 1'
Examples:
c) Mathematical functions - $ABS, $EXP, $LN, $LOG10, $FIX, $INT,
$RND, $RND_INT, $MIN, $MAX, $MINI, $MAXI, $MEAN, $MEDIAN, $SORTDEC, $SORTDECI, $SORTINC, $SORTINCI$ABS('value') // Absolute value - abs()
// $ABS(-1.2) -> 1.2
$EXP('value') // Exponential (or antilogarithm) value - exp()
// $EXP(100) -> 2.68811...E+43
$LN('value') // Natural logarithm - ln()
// $LN(100) -> 4.60517...
$LOG10('value') // Logarithm to base 10 - log10()
// $LOG10(100) -> 2
$INT('value') // Integer portion of a number
// $INT(4.2) -> 4
// $INT(-4.2) -> -5
$FIX('value') // First negative integer greater than or equal to the number
// $FIX(4.2) -> 4
// $FIX(-4.2) -> -4
$RND('min' 'max')
// Random floating point number in the range min to max, where min >= 0 and max > min.
// $RND(0,1) -> random floating point number in the range 0 to 1
// $RND(1,100.234) -> random floating point number in the range 1 to 100.234
$RND_INT('min' 'max')
// Random integer number in the range min to max, where min >= 0 and max > min.
// $RNDINT(0 10) -> random integer number in the range 0 to 10
// $RNDINT(1 100) -> random integer number in the range 1 to 100
$MIN('value1' 'value2' ...) // Minimum value in the list
$MINI('value1' 'value2' ...) // Item that has the minimum value in the list
// $MIN(0,-1.5,2,3) -> -1.5
// $MINI(0,-1.5,2,3) -> 2
$MAX('value1' 'value2' ...) // Maximum value in the list
$MAXI('value1' 'value2' ...) // Item that has the maximum value in the list
// $MAX(0 -1.5 2 3) -> 3
// $MAXI(0 -1.5 2 3) -> 4
$MEAN('value1' 'value2' ...) // Average value in the list
$MEDIAN('value1' 'value2' ...) // Median value in the list
// $MEAN(1 15 2) -> 6
// $MEDIAN(1 15 2) -> 2
$SORTDEC('value1' 'value2' ...) // Sort list by decreasing values
$SORTDECI('value1' 'value2' ...) // Indexes of the sorted items
// $SORTDEC(1.5 100 50 -50) -> '100 50 1.5 -50'
// $SORTDECI(1.5 100 50 -50) -> ' 2 3 1 4'
$SORTINC('value1' 'value2' ...) // Sort list by increasing values
$SORTINCI('value1' 'value2' ...) // Indexes of the sorted items
// $SORTINC(1.5 100 50 -50) -> '-50 1.5 50 100'
// $SORTINCI(1.5 100 50 -50) -> ' 4 1 3 2'
Example:
VARIABLE %X(4) %Y(4) %I(4)
%X = 1.5 100 50 -50 // %X(1)=1.5 %X(2)=100 %X(3)=50 %X(4)=-50
%Y = $SORTINC(%X) // %Y(1)=-50 %Y(2)=1.5 %Y(3)=50 %Y(4)=100
%I = $SORTINCI(%X) // %I(1)=4 %I(2)=1 %I(3)=3 %I(4)=2
d) Mathematical expressions - $MATH()
This versatile function enables you to enter a mixed expression that includes the operators, + - / * ^ \, as well the common functions abs(), ln(), log10(), exp(), cos(), sin(), tan(), acos(), asin(), atan(), fix(), int(), sqr(), cbr() and fact().
$MATH(2 - 3) // -> -1
$MATH(2 * 3) // -> 6
$MATH(5 / 3) // -> 1.66666666666667
$MATH(5 \ 3) // -> 1
$MATH(3 ^ 4) // -> 81
$MATH(28-3*9+2^4/16) // -> 2. Same as $MATH((28 - (3*9) + (2^4)/16))
$MATH(240/fact(5)) // -> 2. Same as $MATH(100/5!)
$MATH(cos(100)^2 + sin(100)^2) // -> 1. Same as (cos(100))^2 + (sin(100))^2
$MATH(log10(100)) // -> 2. Same as $MATH(ln(100)/ln(10))
$MATH((5!-(2-5)^2)/(sqr(abs(2^4-3^5))) // -> 7.36732875875969
Example:
VARIABLE %RGas %TC %Po2 %DG0
%Rgas = $CONSTANT(RGAS-J) // Gas constant J/mol-K
%TC = 1000
%Keq = 1e-5
%DG0 = $MATH(-%Rgas * (TC+273.15) * ln(%Keq))
// DG(zero) = -RTln(Keq) J/mol
e) File managing - $EXIST, $FILE_DIR, $FILE_SHORTDIR, $FILE_NAME, $FILE_BYTES, $SCAN_DIR
$EXIST('file name') // If the file exists then $EXIST = 1 (i.e. true) else 0
$FILE_DIR('long file name')
// Long name of parent folder
// $FILE_DIR(C:\FactSage\Figures\CaO_SiO2.fig) -> 'C:\FactSage\Figures\'
$FILE_SHORTDIR('long file name')
// Short name of parent folder
// $FILE_SHORTDIR(C:\FactSage\Figures\CaO_SiO2.fig) -> 'Figures\'
$FILE_NAME('long file name')
// File name of a long file name
// $FILE_NAME(C:\FactSage\Figures\CaO_SiO2.fig) -> 'CaO_SiO2.fig'
$FILE_BYTES('file name')
// Size of file in bytes
// $FILE_BYTES(C:\FactSage\Figures\CaO_SiO2.fig) -> '19127'
$SCAN_DIR: is
similar to the Dir function in other software languages. There are two modes
in using $SCAN_DIR. First with a file name mask (such *.txt, My*.fig etc.) to
initiate the function and return the number of files. Then without the mask
to list the short name of each files, one at a time.
$SCAN_DIR('file-mask')
// Initiates the scan and returns the number of files or '0' if no files are found.
$SCAN_DIR() // Lists the name of first file in the list.
$SCAN_DIR() // Lists the name of 2nd file in the list.
$SCAN_DIR() // and so on. '0' denotes when all files have been listed.
Example:
%1 = $SCAN_DIR(c:\FactSage\Figures\*.fig)
// Initiate a scan of all c:\FactSage\Figures\*.fig files.
%1 = $SCAN_DIR()
// Return the short name of the first file.
%1 = $SCAN_DIR()
// Return the short name of the next file, and so on, until '0' when done.
f) Chemical functions - $ELEMENT..(), $MOLWT(), $CONSTANT()
$ELEMENT_NAME('value') // convert atomic number to an element
// $ELEMENT_NAME(26) -> 'Fe'
$ELEMENT_NUMBER('name') // convert an element to an atomic number
// $ELEMENT_NAME(Fe) -> '26'
$ELEMENT_MASS('name' or 'value') // convert an element to an atomic mass
// $ELEMENT_MASS(26) -> '55.847' $ELEMENT_MASS(Fe) -> '55.847'
$MOLWT('species') // Molecular weight of a chemical species
// $MOLWT(H2O) -> '18.01528'
$CONSTANT('gas constant') $CONSTANT('unit1/unit2')
// Gas constants and unit conversion. List of gas constants and units:-
// Gas constant: Rgas-cal Rgas-J Rgas-L-atm
// Energy: J kJ mJ cal kcal Mcal Btu kWh
// Pressure: bar Pa kPa atm psi mmHg torr
// Mass: g gm kg tonne lb
// Volume: L liter litre cc cm3 ml m3 dl CuFt Ft3
// $CONSTANT(Rgas-J) -> '8.31451' J/mol-K
// $CONSTANT(g/lb) -> '453.59237' g/lb
g) System functions - $BLANK, $CHEMSAGE_DIR\, $COMMAND, etc.
$BLANK // ' ' (white space) - used in WRITE commands
$CHEMSAGE_DIR\ // chemSage directory, typically 'c:\FactSage\CHEMSAGE\'
$COMMAND // optional command line set by RUNMACRO 'file.mac' [command]
$DATE // current date
$EXAMPLES_DIR\ // examples directory, typically 'c:\FactSage\EXAMPLES\'
$FACTDATA_DIR\ // database directory, typically 'c:\FactSage\FACTDATA\'
$FACTHELP_DIR\ // help directory, typically 'c:\FactSage\FACTHELP\'
$FACTSAGE_DIR\ // directory where FACTWIN.INI resides - same as $FSDIR
$FALSE // 0 (zero). Ex: 'IF $EXIST('file name') = $FALSE THEN GOTO END'
$FIGURES_DIR\ // figures directory, typically 'c:\FactSage\FIGURES\'
$FSDIR // directory where FACTWIN.INI resides - same as $FACTSAGE_DIR\
$F90IO_DIR\ // fortran I/O directory, typically 'c:\FactSage\F90IO\'
$HWND // handle of current application
$MACFILE // full name of the current macro file
$MACROS_DIR\ // macros directory, typically 'c:\FactSage\MACROS\'
$PAGES // number of pages in last calculation
$RETVAL // shell process returned value - see 'SHELL_WAIT'
$TEMP_DIR\ // temporary directory - environment variable defined by Windows
$TIME // current time
$TIME_RUN // time passed (hh:mm:ss) since the start
$TIME_RUN_SECS // time passed (seconds) since the start
$TIME_INTERVAL // time passed (hh:mm:ss) since last call to $TIME_INTERVAL
$TIME_INTERVAL_SECS // time passed (seconds) since last call to $TIME_INTERVAL_SECS
$TRUE // 1 (one). Ex: 'IF $EXIST('file name') = $TRUE THEN'
6.3 Macro commands for increments and cycles - STEP, FACTOR, LOOP
STEP :
%var = STEP ['value']
// steps up (adds) numerical %var by 'value' (default 1).
// i.e. %var = %var + 'value' (default 1). Same as %var = %MATH(%var + 'value')
Examples:
%3 = 4 // %3 has the value '4'
%3 STEP -2 // new %3 = current %3 - 2 (= 4 - 2 -> '2'). Same as %3 = %MATH(%3-2)
%3 STEP // new %3 = current %3 + 1 (= 2 + 1 -> '3'). Same as %3 = %MATH(%3+1)
FACTOR :
%var = FACTOR 'value'
// factors (multiplies) numerical %variable by 'value'
// i.e. %var = %var x 'value'. Same as %var = $MATH(%var * 'value')
Example:
%4 = 10 // %4 has the value '10'
%4 = FACTOR 0.5 // new %4 = current %4 x 0.5 (i.e. %4 = '5')
// Same as %4 = $MATH(%4*0.5)
LOOP :
// Simple LOOP in %var:
%var = 'FirstValue' TO 'LastValue' [STEP 'IncrementValue']
(macro lines)
%var LOOP // End of loop. If %var line <> 'LastValue'
// then go back to beginning, redefine %var and repeat.
// A %var LOOP is always executed at least once ('FirstValue').
// If STEP is undefined then '1' is assumed.
// Nested (embedded) LOOPs are permitted:
%var1 = 'FirstValue1' TO 'LastValue1' [STEP 'IncrementValue1']
%var2 = 'FirstValue2' TO 'LastValue2' [STEP 'IncrementValue2']
%var3 = 'FirstValue3' TO 'LastValue3' [STEP 'IncrementValue3']
(macro lines)
%var3 LOOP // End of %var3 loop.
%var2 LOOP // End of %var2 loop.
%var1 LOOP // End of %var1 loop.
Examples:
%3 = 2 TO 6 STEP 0.5 // %3 has 9 values: 2 2.5 3 3.5 ... 6
(macro lines) // These lines will be executed 9 times
... // unless they contain a GOTO statement.
%3 LOOP
%3 = 2 TO 4 // %3 has 3 values: 2 3 and 4
%4 = 1 TO -1 STEP -2 // %4 has 2 values: 1 and -1
(macro lines) // These lines will be executed 6 times
... // unless they contain a GOTO statement.
%4 LOOP
%3 LOOP
6.4 Macro commands for simple program flow: MARK, GOTO, IF... GOTO and ENDMARK:
MARK 'word' // a marker used with GOTO 'word'.
// A MARK statement cannot be inside IF ....ENDIF
// nor in a LOOP or DOCASE.
GOTO:
GOTO 'word' // jump to the line MARK 'word'.
// A GOTO statement cannot be inside IF ....ENDIF
GOTO END // jump to the end i.e. quit.
IF ... GOTO: (simple operator)
IF 'value1' '?' 'value2' GOTO 'word'
// An IF...GOTO line must have 6 words separated by spaces.
// Word #1 must be IF and word #5 must be GOTO.
// IF statement - if true go to line MARK 'word'.
// Word #3, '?', must be one of the 6 logical operators:
// = < > <> <= >=
Examples:
MARK Top // A marker called 'Top'
(macro lines)
IF %3 < 10 GOTO Top
// If the value of %3 is less than 10 then jump to the
// line 'MARK Top'.
// Note '%3<10' is undecodable (no spaces).
END:
END // End of the macro processing.
// All comments after 'END' are ignored .
Example:
GOTO END // Jump to the end i.e. quit.
IF ... GOTO: (multiple operators AND or OR)
IF 'val1' '?' 'val2' OR 'val3' '? ' 'val4' OR ... GOTO 'mark'
// One or more 'OR' operators are permitted.
IF 'val1' '?' 'val2' AND 'val3' '? ' 'val4' AND ... GOTO 'mark'
// One or more 'AND' operators are permitted.
Examples:
IF 1% < 1 OR %1 > 100 GOTO END
// If %1 is outside the range 1 - 100 then go to the END
IF 1% >= 1 AND 1% <= 10 AND %2 > %1 GOTO TOP
// If %1 is within the range 1 - 10 and %2 is greater than %1
// then jump to the line MARK TOP
IF 1% > 1 AND 1% < 10 OR %2 > %1 GOTO TOP
// Error! Mixed AND with OR is NOT permitted.
IF ... THEN to ENDIF:
IF 'value1' '?' 'value2' THEN // The first statement, '?' may
(macro lines) // contain 'AND' or 'OR' operators.
...
ELSEIF 'va1ue3' '?' 'value4' THEN // One or more ELSEIF statements
(macro lines) // are optional.
...
ELSE // One ELSE statement is optional.
(macro lines)
...
ENDIF // ENDIF statement must be present
Example:
MARK TOP
%1 0 ASK Enter the file number (1 to 9999), enter 0 to QUIT.
// Prompt the user to enter the file number, %1
IF %1 >= 1 AND % 1 <= 9999 THEN // if %1 is in the range 1 to 9999
OPEN EQUI%1.DAT // then open the Equi file
CALC // and calculate
SAVE EQUI%1.TXT // and save
GOTO TOP // and repeat.
ELSEIF %1 = 0 THEN // i.e. %1 is 0 so quit
GOTO END
ELSE // try again.
GOTO TOP
ENDIF
// Note: nested IF statements not permitted
// that is, an IF .. ENDIF can NOT contain another IF .. ENDIF
// or contain an IF ..... GOTO ...
DOCASE ... CASE to ENDDO:
DOCASE %var // The first statement defines the %variable
CASE 'val1' ['val2' 'val3' ...]
// If %var has value 'val1' (or 'val2' or 'val3'..)
... // execute these macro lines.
CASE 'val4' ['val5' 'val6' ...]
// If %var has any one of these values
... // execute these macro lines.
CASE 'val1' TO 'val2'
// If %var is in the range 'val1' to 'val2'
... // execute these macro lines.
CASE IS 'operator' 'val1' // where operator is one of < > <> >= or <= .
// If %var satisfies the condition
... // execute these macro lines.
CASE ... etc
CASE ELSE // Optional CASE ELSE - if none of the above are true
...
ENDDO // ENDDO statement must be present
DOCASE Example 1:
MARK TOP
%1 = 0 ASK Do you want 1 text, 2 results or 3 xls file (enter 1 to 3) or -1 to quit.
// Prompt the user to enter the type of file
DOCASE %1
CASE 1 // The CASE statement has a fixed value (not %var)
%2 = EQUILIB.TXT
CASE 2
%2 = EQUILIB.RES
CASE 3
%2 = EQUILIB.XLS
CASE -1 // Quit.
GOTO END
CASE ELSE // Invalid, try again.
GOTO TOP
ENDDO // End
SAVE %2 // Save the file.
DOCASE Example 2:
DO CASE %1
CASE 0 1 2 // If %1 has the value 0, 1 or 2
(macro lines)
CASE 3 TO 50.5 // If %1 is in the range 3 to 50.5
(macro lines)
CASE IS <= -100 // If %1 is less than or equal to -100
(macro lines)
CASE IS <> 1000 // If %1 is not equal to 1000
(macro lines)
CASE ELSE
(macro lines)
ENDDO
// Notes: Nested DOCASE .. ENDDO statements not not permitted
// that is, a DOCASE .. ENDDO can NOT contain another DOCASE .. ENDDO.
// Also, the CASE statement can NOT contain a %variable.
ERROR_OFF, ERROR_ON:
ERROR_OFF or ERROROFF // suppress error handling (see ERROR_ON) - use with caution!
ERROR_ON or ERRORON // resume error handling (see ERROR_OFF) - this is the default setting.
RUNMACRO:
RUNMACRO 'filename.mac' [command] // Quit the current application and run a new macro
// and define an optional command line (see $COMMAND)
Example:
RUNMACRO $MACROS_DIR\PhasEx_Superimpose_Figs.mac %Path\%Name
// Quit current macro, load PhasEx_Superimpose_Figs.mac located in
// the Macros directory and pass the command %Path\%Name (see $COMMAND)
// - this example is stored in PhasEx_Al-Mg-Sr-liquidus.mac
SHELL:
SHELL 'string' // Execute commands stored in the 'string'.
Example:
%4 = C:\Dummy\
SHELL Notepad %4MyText.Txt
// Open C:\Dummy\MyText.txt with Notepad.
Example:
SHELL %4MyBat.bat [%6] [%7] ...
// Runs the batch file c:\Dummy\MyBat.bat
// with optional words %6, %7 ...
SHELL_EXECUTE:
SHELL_EXECUTE 'filename'// Open doc, fig, txt, xls, etc. file in the default Windows application.
Example:
%4 = C:\Dummy\
SHELL_EXECUTE %4MyText.Txt // Open C:\Dummy\MyText.txt with Notepad or WordPad etc.
SHELL_EXECUTE %4MyText.Doc // Open C:\Dummy\MyText.txt with Word
SHELL_EXECUTE %4MyText.Xls // Open C:\Dummy\MyText.txt with Excel
SHELL_EXECUTE %4MyText.Xlm // Open C:\Dummy\MyText.xlm with Fact-XLM
SHELL_WAIT:
SHELL_WAIT 'string' // Execute command and wait until done.
// Return values are stored in $RETVAL.
Example:
SHELL_WAIT MyExec.exe // Run MyExec.exe and wait.
// When done store the return value in $RETVAL.
WAIT: (or PAUSE)
WAIT // wait for the user to click 'OK' to continue
WAIT 'number' // wait 'number' seconds before continuing
Example:
PAUSE 2.5 // processing waits 2.5 seconds and then proceeds (same as WAIT 2.5)
PAGE_KEEP, PAGE_NEW:
PAGE_KEEP or PAGEKEEP
// Keep results from previous CALC(s)
// and append current CALC results as new pages.
PAGE_NEW or PAGENEW
// (Default setting) - negates option PAGE_KEEP
POST_MESSAGE, SEND_MESSAGE:
POST_MESSAGE 'TargetHwnd' 'string' or POSTMESSAGE ...
// post message in another application
POST_MESSAGE 'TargetHwnd' FILENAME 'Filename'
// post file contents in another application.
SEND_MESSAGE 'TargetHwnd' 'string' or SENDMESSAGE ...
// send message to another application
SEND_MESSAGE 'TargetHwnd' FILENAME 'Filename'
// send file contents to another application.
LOAD_ONLY:
LOAD_ONLY or LOADONLY
// loads (opens) Equi*.dat (or Phas*.dat) without calculating. Units $R_*$, Database $D*$,
// Reactant $U_*$ and Menu $M_*$ Window variables are defined (but not Equilibrium $E_?*$)
Reading text files - READ, CONTENTS, LINE, WORD, WORDLINE, CLOSE, REWIND, VIEWTEXT
%var = 'TextFileName' READ
// variable is the line read from the text file
// If file is missing or line is empty then %var = '0'.
%var = 'TextFileName' READ CONTENTS
// variable is text file contents including {CR} {Tab} etc.
%var = 'TextFileName' READ LINE
// variable is the line read from the file (same as READ)
%var = 'TextFileName' READ LINECOUNT
// variable is the number of lines in the file
%var = 'TextFileName' READ LINE 'n'
// variable is line 'n' of the file ('1' is the first line)
//- next READ (or READ LINE or READ WORD) is foe line 'n+1'
%var = 'TextFileName' READ WORD
// variable is first word of the line read from the file
%var = 'TextFileName' READ WORD 'm'
// variable is word 'm' (1 - 9) of the line from the file
// - 'READ WORD' is the same as 'READ WORD 1'
%var = 'TextFileName' READ WORDLINE 'm' 'n'
// variable is word m of line n in the text file
%var = 'TextFileName' READ LINEWORD 'n' 'm'
// variable is word m of line n in the text file
CLOSE 'string' // Used with READ - the next READ goes back and reads
REWIND 'string' // line 1 from 'string'. REWIND is the same as CLOSE.
VIEWTEXT 'Filename.txt' // display the contents of a text file
Writing text files - WRITE, WRITELINE, APPEND, APPEND FILENAME, TAB_LINE, TAB_WORD, TAB_COL, TAB_JUSTIFY:
WRITE 'TextFileName' 'string' // Store 'string' in the text file
// - any current contents will be replaced.
WRITELINE 'TextFileName' 'n' 'string' // Write 'string' to line 'n' of the text file
// - the line will be replaced.
APPEND 'TextFileName' 'string'
// Write 'string' to the end of the text file
APPEND 'TextFileName1' FILENAME 'TextFileName2'
// Append file 2 to the end of file 1.
APPEND 'TextFileName' TAB_LINE(=)
// - underline title (previous line) with a '=' (or other character - * ~ etc.)
APPEND 'TextFileName' TAB_WORD(-)
// - underline words (previous line) with a '-' (or other character = * ~ etc.) separated by spaces
APPEND 'TextFileName' TAB_COL('value 1' 'value 2' 'value 3' ....)
// Sets tabs for all subsequent APPEND %FILE output - useful for aligning tabular output
APPEND 'TextFileName' TAB_JUSTIFY(<)
// Left-justify words for all subsequent APPEND %FILE output.
// TAB_JUSTIFY(>) - right justify all words, TAB_JUSTIFY(^) - center all words
// TAB_JUSTIFY(^ < ^ > ...) - mixed mode, one tab per word.
APPEND 'TextFileName' TAB_COL(0)
// Cancel tabs.
Examples:
APPEND c:\Dummy\Summary.txt Return value from MyExec.exe is $RETVAL
// and append ex: 'Return value from MyExec.exe is O'
APPEND c:\Dummy\Summary.txt FILENAME MyText.Txt
// and append to the end of 'c:\Dummy\Summary.txt' the contents
// of the file 'MyText.txt'.
APPEND 'file' TAB_COL(5 10 20 35)
// In 'file' set tabs at columns 5, 10, 20, 35 ...
APPEND 'file' 1 2 3 4
// 1 2 3 4
APPEND 'file' 1.1 22.2 333.3 4444.4
// 1.1 22.2 333.3 4444.4
APPEND 'file' TAB_COL(0)
// Cancel tabular output
// See EQUIEx_TABS.mac for examples of TAB_LINE(), TAB_WORD(), TAB_COL() and TAB_JUSTIFY().
Ini files - READ_INI, WRITEINI
%var READ_INI 'IniFileName' 'Section' 'Variable' 'Default'
// %var value read from *.ini file (see WRITEINI)
WRITEINI 'IniFile' 'Section' 'Variable' 'Value'
// %var value written to *.ini file
COPY:
COPY 'FileName1' 'FileName2'
// Copy file 'FileName1' to file 'FileName2'
// - 'FileName2' must be one of .txt, .res, .tab, .xls, . fig or .xml.
// Warning, if 'FileName2' already exists it will be replaced.
Example:
%4 C:\Dummy\
COPY %4MyText.Txt Copy.txt
// Copy C:\Dummy\MyText.txt to C:\FactSage\Copy.txt
NAME: (or RENAME)
NAME 'FileName1' 'FileName2'
// Rename 'FileName1' as file 'FileName2'
// - 'FileName2' must be one of .txt, .res, .tab, .xls, .fig or .xml
// Warning, if file 'FileName2' already exists it will be replaced.
Example:
%4 C:\Dummy\
RENAME %4MyText.Txt NewName.txt
// Copies C:\Dummy\MyText.txt to C:\FactSage\NewName.txt
// if default directory %DIR is C:\FactSage\
// and then deletes C:\Dummy\MyText.txt.
KILL: (or DELETE)
KILL 'FileName1'
// Delete 'FileName1'
// - 'FileName1' must be one of .txt, .res, .tab, .xls or .fig.
// Wild cards (* and ? e.g. KILL EQUI*.DAT) are not permitted.
Examples:
%4 C:\Dummy\
KILL %4MyText.Txt // Deletes file C:\Dummy\MyText.txt
DELETE MyText.Txt // Deletes file C:\FactSage\MyText.txt
// if default directory %DIR is C:\FactSage\
6.9 Macro commands for Excel Worksheets and Text Spreadsheets - linking via OLEnA Text Spreadsheet (introduced in FactSage 7.0) is stored in a *.txt or *.tab ascii file. It offers simplicity and speed when compared with the Excel Worksheet. There are often situations where the Text Spreadsheet is preferred to the Excel Worksheet especially in cases where data are simply being posted or manually entered. However data in a Text Spreadsheet cannot be shared with other applications nor can the data be manipulated by the Excel functions.
The Equilib macro processing enables you to create up to 9 simultaneous dynamic links (OLE1 to OLE9)
This advanced feature permits Object Linking and Embedding (OLE)
with an Excel Worksheet and/or Text Spreadsheet.
A simple example is given in the macro file
EquiEx_Xls_Simple_IO.mac (this example is expanded in FactSage 7)
and a more complicated one in EquiEx_CH4-O2-c.mac.
OLEn:
OLEn 'ExcelFileName' ['Sheet-Name']
// Create an OLE link (n = 1 to 9) with an Excel Worksheet stored in an Excel Worksheet file (*.xls,*.xlsx).
// ex: 'OLE1 MyExcel.xlsx Input' - creates a link to the 'Input' Spreadsheet of the Excel file.
OLEn 'TextFileName' ['Sheet-Name']
// Create an OLE link (n = 1 to 9) with a Text Spreadsheet stored in an ascii file (*.txt,*.tab).
// ex: 'OLE1 MyText.txt Input' - creates a link to the 'Input' Spreadsheet of the Text file.
// You can create more links with different Worksheets in different Text files .
// ex: 'OLE2 MyMoreText.tab Output' - creates a second link to the 'Output' Text Spreadsheet.
// Many of the following commands are shown in EquiEx_Xls_Simple_IO.mac located in the /Macros folder.
OLEn CLOSE // close the Spreadsheet; you will be prompted to save
OLEn CLOSE SAVE // close and save the Spreadsheet without prompting
OLEn CLOSE SAVE 'ExcelFileName' // close and save Excel Worksheet in a different *.xls or *.xlsx file
OLEn CLOSE SAVE 'TextFileName' // close and save Text Spreadsheet in a different *.txt or *.tab file
OLEn QUIT // close the Spreadsheet without saving
OLEn CELLS ALL 'options' // apply options to all cells in the Worksheet
OLEn COLUMNS 'F:F' 'options' // apply options to column F
OLEn ROWS '2:3' 'options' // apply options to rows 2 and 3
OLEn RANGE 'B1:C4' 'options' // apply options to a range B1:C4 or R1C2:R4C3
OLEn NAME 'NAME' 'options' // apply options to a range name
// List of 'options' for both Excel Worksheets and Text Spreadsheets :
AUTOFIT // auto fit column width
// ex: 'OLE1 CELLS ALL AUTOFIT' auto fits all cells in the Spreadsheet
BOLD TRUE (FALSE) // Bold text - TRUE is default. BOLD may be replaced by:
// ITALIC, SHADOW, STRIKETHROUGH, SUBSCRIPT, SUPERSCRIPT or UNDERLINE
// ex: OLE1 ROWS 2:3 UNDERLINE
CENTER (LEFT RIGHT) // alignment of contents in each cell
CLEAR // clear the contents in each cell
COLOR 'color' // text color where 'color' is one of BLACK, MAROON, GREEN,
// OLIVE, NAVY, PURPLE, TEAL, GRAY, SILVER, RED, LIME, YELLOW, BLUE, FUSHIA, AQUA or WHITE
COLOR RGB(i,j,k) // RGB color where i, j and k in the range 0 - 255
// ex: 'OLE1 RANGE A1:C:4 COLOR RGB(0,0,255)' - same as 'COLOR BLUE'
FONTSTYLE 'font style' // font style ex: 'Bold_Italic' - use _ for spaces
// ex: 'OLE1 RANGE R1C1:R3:C3 FONTSTYLE Times_New_Roman'
HEIGHT 'value' // set rows to a common height
SIZE 'value' // set font size to a commo value
WIDTH 'value' // set columns to a common width
OLEn GOTO 'RnCm'
// put focus on this cell - scroll vertically and horizontally if necessary.
// ex: 'OLEn GOTO R22C33' makes sure cell at row 22 column 33 is visible on the screen
%var OLEn READ 'An' ('RnCm' 'An:Bm' 'RnCm:RiCj' 'name')
// variable value(s) read from cell (or row & column or range).
// ex: B5 R5C6 B5:D10 R5C2:R10C4 RangeName
%var OLEn WRITE 'An' ('RnCm' 'An:Bm' 'RnCm:RiCj' 'name')
// variable value(s) written to cell (or row & column or range).
NAME OLEn CLEAR 'name'
// clear the contents of a range name in the Spreadsheet
NAME OLEn DELETE 'name'
// delete the range name in the Spreadsheet
NAME OLEn NEW 'name' 'An' 'Bn:Cm' ('RnCm:RiCj')
// define a new range name in the Spreadsheet
ERROR_OFF or ERROROFF
// Suppress error handling (also see ERROR_ON) - use with caution !
// This is not an OLE command but it is very useful in OLE processing. Minor link errors are often posted during
// dynamic interaction with the Excel Worksheet. This command simply suppresses the offending error messages.
6.10 Macro user-defined $Functions and Procedures - FUNCTIONS ... END FUNCTIONS, PROCEDURES ... END PROCEDURES
It is possible to program user-defined FUNCTIONS
(e.g. $Function('arguments') and PROCEDURES (e.g. CALL SUBROUTINES) .
All the %variables used in the subroutines must be declared (VARIABLE or DIM) at the beginning of the macro.
The subroutines (PROCEDUREs) are called (CALL) within the main body of the macro.
A user-defined $function or subroutine cannot call another user-defined $function or subroutine.
The FUNCTIONS and PROCEDURES
are listed at the end of the macro -
FUNCTIONS ... END FUNCTIONS and
PROCEDURES ... END PROCEDURES.
FUNCTIONS
// The format of a user-defined function is :
// FUNCTION $'function name'('arguments')
// - $'function name name' is any alphanumeric description starting with $.
// - 'arguments' are values passed from the main body.
// ....macro lines (where 'output variables' are defined)
// $'function name' = 'value' (where the value of function is defined)
// END FUNCTION
FUNCTION $My-Whatever(arg1 arg2 ...)
... macro lines
$My-Whatever = 'value'
END FUNCTION
FUNCTION $My-Another(arg1 arg2 ...)
... macro lines
$My-Another = 'value'
END FUNCTION
END FUNCTIONS
PROCEDURES
// The format of a procedure is :
// 'procedure name'('argumentss')
// - 'procedure name' is any alphanumeric description
// - 'arguments' are values are defined in the main body.
// ... macro lines where 'output variables' are defined)
// END 'procedure name'
SUB_CheckDim(%A)
.... (macro lines)
END SUB_CheckDim
SUB_Another(C%)
.... (macro lines)
END SUB_Another
END PROCEDURES
Examples of user-defined functions and procedures are presented in
EquiEx_New_in_7.0.mac and EquiEx_Functions_and_Procedures.mac stored in the Macros folder.
The following example is extracted from EquiEx_Functions_and_Procedures.mac. In the macro we scan the figures (and macros) folder and return the number (%Scan_number) of *.fig (and *.mac) files. In addition the size (%Scan_big_size) and name (%Scan_big_name) of the largest file in the folder are determined.
REM Extracted from EquiEx_Functions_and_Procedures.mac FactSage 7
REM ===================================
REM Example of Calling (CALL) subroutines (PROCEDURES)
REM
// Declare (VARIABLE or DIM) all %Variables.
DIM %Scan_mask %Scan_folder\ %File %Scan_number %Scan_big_name %Scan_big_size
// For improved readability the %Variables in the Sub_SCAN_Files() subroutine are all called %Scan_*.
DIM %Size %ShortName %FullName %Folder_mask %Display
%DIR = $FSDIR // Set user default directory to the FactSage directory $FACTSAGE_DIR\
%Folder_mask = $FIGURES_DIR\*.fig// ex: C:\Factsage\Figures\*.fig
// $FIGURES_DIR\ is the reserved $Function for the FactSage figures folder
CALL Sub_SCAN_Files(%Folder_mask) // First call to procedure Sub_SCAN_Files - see PROCEDURES at end of macro file.
// Display the results in real time.
MSGBOX In $FIGURES_DIR\ there are %Scan_number *.fig files. _ _The largest is %Scan_big_name _at %Scan_big_size bytes.
%Folder_mask = $MACROS_DIR\*.mac // ex: C:\Factsage\MACROS\*.mac
// $MACROS_DIR\ is the reserved $Function for the FactSage macros folder
CALL Sub_SCAN_Files(%Folder_mask) // Second call to procedure Sub_SCAN_Files - see PROCEDURES at end of macro file.
// Display the results in real time.
MSGBOX In $MACROS_DIR\ there are %Scan_number *.mac files. _ _The largest is %Scan_big_name _at %Scan_big_size bytes.
PROCEDURES // PROCEDURES ... END PROCEDURES are placed at the end of the macro and
// contain the subroutines called in the main body.
// The format of a procedure is :
// 'procedure name'('input parameters') // 'procedure name' is any alphanumeric description
// // 'input parameters' are values are passed from the main body.
// (macro lines where 'output variables' are defined)
// END 'procedure name'
Sub_SCAN_Files(%Scan_mask) // Sub_SCAN_Files is the name of the subroutine (PROCEDURE) being called (CALL).
// The prefix 'Sub_' is used to improve readability but it is not essential.
// %Scan_mask is the input parameter. More than one parameter may be specified.
// 'Sub_SCAN_Files' scans '%Scan_mask' and returns: the number of files (%Scan_number),
// the size (%Scan_big_size) and the name (%Scan_big_name) of the largest file .
%Scan_folder\ = $FILE_DIR(%Scan_mask) // Parent directory of mask ex: c:\FactSage\Figures\
%Scan_big_size = 0 // Reset the size
%Scan_big_name = 0 // Reset the file name
%Scan_number = $SCAN_DIR(%Scan_mask) // Initiate scan ex: $SCAN_DIR(c:\FactSage\Figures\*.fig)
// and return %Scan_number - the number of files located
IF %Scan_number = 0 GOTO EndOfSub_SCAN_Files // See MARK EndOfSub_SCAN_Files
%File = 1 TO %Scan_number // Scan folder for each file
%ShortName = $SCAN_DIR() // Return the short name of the file.
%FullName = %Scan_folder\%ShortName
%Size = $FILE_BYTES(%FullName) // Size (bytes) of the File. $FILE_BYTES is a reserved $FUNCTION.
IF %Scan_big_size < %Size THEN // Check for the largest file size.
%Scan_big_size = %Size
%Scan_big_name = %FullName
ENDIF
%File LOOP
MARK EndOfSub_SCAN_Files
END Sub_SCAN_Files // End of PROCEDURE Sub_SCAN_Files
END PROCEDURES // End of all PROCEDUREs
END
6.11 Macro 1-D and 2-D %Variables - tables and arrays, REDIM, $ARRAY_DIM(), _COUNT(), _LBOUND(), _UBOUND(), $ENUM
DIM %A %B(2) %C(-2:2) %D(1,3) %E(0:1,2:4) // DIM or VARIABLE - declaration of single, 1-D and 2-D variables (arrays)
// %A -> %A
// %B(2) -> %B(1) %B(2)
// %C(-2:2) -> %C(-2) %C(-1) %C(0) %C(1) %C(2)
// %D(1,3) -> %D(1) %D(2) %D(3)
// %E(0:1,2:4) -> %E(0,2) %E(0,3) %E(0,4) %E(1,2) %E(1,3) %E(1,4)
$ARRAY_DIM, $ARRAY_COUNT, $ARRAY_LBOUND, $ARRAY_UBOUND
%1 = $ARRAY_DIM(%A) // -> 0 - no dimension single variable
%1 = $ARRAY_DIM(%B) // -> 1 - 1-D array
%1 = $ARRAY_DIM(%E) // -> 2 - 2-D array
%1 = $ARRAY_COUNT(%A) // -> 1 - single member
%1 = $ARRAY_COUNT(%E) // -> 5 - multi-member
%1 = $ARRAY_LBOUND(%C) // -> %C(-2) - lower bound or first member
%1 = $ARRAY_UBOUND(%E) // -> %E(1,4) - upper bound or last member
REDIM
REDIM %variable
// Same as DIM except if the %variable already exists it becomes redimensioned.
REDIM %A(2) %B(5)
// %A single variable converted to a 1-D array - %A(2) -> %A(1), %A(2)
// %B(2) replaced by %B(5) -> %B(1), %B(2) ... %B(5)
$ENUM
%var-array = $ENUM('starting value')
// function to enumerate the members of an array
%D = $ENUM(0) // %D(1) = 0, %D(2) = 1, %D(3) = 2
%E = $ENUM(1) // %E(0,2) = 1, %E(0,3) = 2, %E(0,4) = 3 ... %E(1,4) = 6
Examples of 1-D and 2-D arrays are given in
EquiEx_New_in_7.0.mac located in the Macros folder.
6.12 Macro thermochemical variables - $variables$, SET
$variables$ variables
are system dependent thermochemical variables that are defined by the Equi*.dat
(or Phas*.dat) file or calculated during the equilibrium calculation.
An example of common thermochemical variables
is given in the macro file EquiEx_List_Results.mac. A complete example of
most calculated thermochemical variables including solution integral and partial
properties and component lists is given in the
macro file EquiEx_List_Thermo.mac. The thermochemical variables are
listed in
Summary of All Macro Variables, Functions and Commands ....
The SET command is used to redefine input reactants (delete or add),
initial amounts, system units and the final conditions and species selection that are initially
defined in the Equi*.dat (or Phas*.dat) file. You can even change
the type of calculation. For example if in the stored Equi*.dat file
Delta(H) = 0 and P =1 (and T is undefined - adiabatic calculation),
then you can define the values T and P (and set Delta(H) undefined - isothermal calculation).
Examples of SET commands are given in the macro file EquiEx_SET_Variables.mac.
A complete list of SET commands follows in section 6.13.
SET COLOR 'RedValue' 'GreenValue' 'BlueValue'
// RGB format 0 - 255 (color in Figure or Phase Diagram)
SET COLOR LIMITS 'MinValue' 'MaxValue'
// Lower and upper values (typically T) - used with SET COLOR VALUE
SET COLOR VALUE 'Value'
// value (typically T) in the range 'MinValue' 'MaxValue' - see SET COLOR LIMITS
SET DATASEARCH GION (NOGION AQUA NOAQUA CXHY MINS1)
// include/exclude gaseous ions, include/exclude aqueous species,
// CxHy value, min. solution components (1 or 2)
SET ESTIMATE T (P V ALPHA) 'value' // Redefine estimate of final T, P, V or ALPHA.
SET FINAL A (B T P Z) 'value' // Redefine final <A>, <B>, T, P or Z (extensive property value).
SET FINAL Z H (V G S C) // Redefine variable Z (extensive property variable) as Delta H (V G S or Cp).
SET PAGE 'value' // Access page 'value' after multiple pages of results have been calculated.
// See Example EquiEx_Set_Page.mac located in the /Macros folder.
SET PARAMETERS DISPLAY SHOW (OUTPUT PRINT DILUTE LABELS ISOT POLYTHERMAL)
// Redefine variables in the Parameters Window.
// See 6.13 for the complete List of SET PARAMETERS Commands
SET REACTANT DEL 'reactant#' ('chemical_formula' or '[stream]')
// Delete (remove) an existing reactant
SET REACTANT ADD 'chemical_formula' or '[stream]' ['phase_name' ['steam_#'] ]
// Add a new reactant (compound species or stream)
SET REACTANT 'reactant#' ('chemical_formula' or '[stream]') MASS (T P) 'mass' ('temperature' 'pressure')
// Redefine input reactant (or stream) mass (T or P)
SET SELECT GAS (or LIQUID AQUEOUS SOLID) + (or - !) [NICK [SPECIES]]
// + to add, - to remove, ! for dormant (metastable).
// NICK is the database 4-6 letter nickname.
// Species is the chemical formula.
SET SELECT COMPOUND + (or - !) [NICK [SPECIES]]
SET SELECT SOLUTION + (or - !) [NICK-Phase [SPECIES]]
SET SPECIES 'chemical_formula' ACTIVITY (or ACT or LOGACT) 'value' ['value2' 'value3']
// Define equilibrium activity or log10(activity) values(s) of an 'ACTIVITY species'.
// For a range define 3 values - 'first last increment' .
SET SPECIES ADD ACTIVITY 'chemical_formula(state)' 'compound_database'
// Identify a new 'ACTIVITY species'.
SET SPECIES DEL ACTIVITY 'chemical_formula' 'compound_database'
// Drop an 'ACTIVITY species'.
// Example of ACTIVIY commands is in EquiEx_CH4-O2_Activity.mac (new in 7.1) located in the /Macros folder.
SET SUBTITLE 'String' // Phase diagram subtitle
SET TITLE 'String' // Phase diagram title
SET UNITS TK (TC TF) ATM (BAR PSI PA) J (CAL BTU KWH) X (% LB)
// Redefine units T, P, energy and mass units.
// Note the mass units: X = moles, % = grams, LB = lbs.
SET VDP ON (OFF) // Include (exclude) the 'VdP' term.
6.13 Macro SET Commands - for data search and options, reactants, species selection, output formatting, plotting, etc.
Data Search Window - commands of SET DATASEARCH commands : SET DATASEARCH GION (NOGION) // include (exclude) gaseous ions (plasmas) SET DATASEARCH AQUA (NOAQUA) // include (exclude) aqueous species SET DATASEARCH CXHY 'value 1-99' // CxHy .. maximum value of x in organic molecules SET DATASEARCH MINS1 (MINS2) // minimum number of solution components is 1 (2) Reactants Window - examples of SET REACTANT: SET REACTANT DEL 2 // Delete Reactant 3 SET REACTANT DEL CH4 // Delete Reactant CH4 SET REACTANT ADD C2H6 gas // Add new reactant C2H6(g) SET REACTANT ADD SO3 liquid #2 // Add new reactant SO3(l) as steam #2 SET REACTANT ADD C solid-1 #3 // Add new reactant C(s) as steam #3 SET REACTANT SO3 MASS 0.1 // Amount of reactant SO3 SET REACTANT C2H6 T 400 // Temperature of reactant C2H6 and others in same stream Species and phase selection - examples of SET SELECT: SET SELECT GAS + ELEM // Select all gas species from ELEM database.
SET SELECT COMPOUND ! SGTE Fe // Make all SGTE Fe compound species metastable. SET SELECT SOLUTION + FToxid-SLAGA // Select the FToxid-SLAGA solution phase, and then
SET SELECT SOLUTION - FToxid-SLAGA SiO2 // unselect (drop) SiO2 from this FToxid-SLAGA phase. Menu Window : - list of SET CALCULATE and SET VARIABLES commands SET EQUILIBRIUM NORMAL // normal equilibrium calculation - default setting SET EQUILIBRIUM TRANSITIONS // normal and phase transitions - only meaningful within a range of T (or alpha A etc.) SET EQUILIBRIUM TRANSITIONSONLY // only calculate the equilibrium phase transitions within a range of T (or alpha A etc. SET EQUILIBRIUM OPEN // open calculation - only meaningful if input alpha A step has been specified SET VARIABLES T MAX 'value' // Maximum temperature SET VARIABLES T MIN (or CONSTANT) 'value' // Minimum (or constant) temperature SET VARIABLES T STEP 'value' // Step in temperature (polythermal projection) SET VARIABLES T DEFINE ON (OFF)' SET VARIABLES P MAX 'value' // Maximum pressure SET VARIABLES P MIN (or CONSTANT) 'value' // Minimum (or constant) pressure SET VARIABLES A1 MAX 'value' // Maximum chemical potential #1 - log10(a1) or RTln(a1) SET VARIABLES A1 MIN (or CONSTANT) 'value' // Minimum chemical potential #1 - log10(a1) or RTln(a1) SET VARIABLES A2 (or A3 or ... ) etc. // Chemical potential #2 (or #3 or ... ) etc. SET VARIABLES C1 MAX 'value' // Maximum composition #1 SET VARIABLES C1 MIN (or CONSTANT) 'value' // Minimum composition #1 SET VARIABLES C2 (or C3 or ... ) etc. // Composition #2 (or #3 or ... ) etc. Output Window - SET PAGE and list of SET OUTPUT commands : SET PAGE 'value' // Access page 'value' after multiple pages of results have been calculated. // See Example EquiEx_Set_Page.mac located in the /Macros folder. SET OUTPUT FORMAT FACT CHEMSAGE // FACT and then ChemSage format SET OUTPUT FORMAT CHEMSAGE FACT // ChemSage and then FACT format SET OUTPUT FORMAT FACT // FACT format only SET OUTPUT FORMAT CHEMSAGE // ChemSage format only SET OUTPUT FORMAT KEEP // The change in the output format is permanent. // When the macro processing is finished the display returns to the former setting unless KEEP is employed. Parameters Window - note that ON (or OFF) may be replaced by 1 (or 0) - list of SET PARAMETERS PRINT commands to control the output in the Output Window : SET PARAMETERS PRINT CUTOFF 'limit' // lower limit for activities and concentrations SET PARAMETERS PRINT BONDS ON (OFF) // display bond fractions SET PARAMETERS PRINT STABLE ON (OFF) SET PARAMETERS PRINT DATA NEVER (ALWAYS ONLY) // NEVER display the name(s) of the database(s) // ALWAYS display the name(s) of the database(s) // ONLY display the name(s) of the database(s) if there is more than one compound or one solution database SET PARAMETERS PRINT [KEEP] // The change in the output format is permanent. // When the macro processing is finished the output returns to the former setting unless KEEP is employed. - List of SET PARAMETERS TARGET limits : SET PARAMETERS TARGET T (P V ALPHA) 'minimum' 'maximum' // set target limits // note TARGET ALPHA limits are fixed at '1.0e-5' and '1' SET PARAMETERS TARGET DEFAULT // return all target limits to default settings - List of SET PARAMETERS DISPLAY, SHOW, LABELS and POLYTHERMAL commands used in Figure for phase diagram calculations : SET PARAMETERS DISPLAY FULLSCREEN (COLOR TITLE SUBTITLE) ON (OFF) // set phase diagram screen display options SET PARAMETERS SHOW STATUS (TIELINES WARNING LABELS) ON (OFF) // set phase diagram output options SET PARAMETERS LABELS LABELSIZE '1-9' SET PARAMETERS LABELS LABELCOLOR 'color' (or '0-15') // set phase diagram label colors // colors BLACK MAROON GREEN OLIVE NAVY PURPLE TEAL GRAY SIVER RED LIME YELLOW BLUE FUSHIA AQUA WHITE // 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 SET PARAMETERS LABELS BOLD (ITALIC UNDERLINE) ON (OFF) // set phase diagram label properties SET PARAMETERS LABELS LINEWIDTH '1-20' // set phase diagram label width 0.1 - 2.0 mms SET PARAMETERS LABELS LINECOLOR 'color' (or '0-15') // set phase diagram line color SET PARAMETERS LABELS ALWAYS (ONLY SHOWS) ON (OFF) // set phase diagram label display SET PARAMETERS LABELS CHEMICAL (NUMERICAL DEFAULT) // set phase diagram label format SET PARAMETERS ISOT COLOR (COLORTBAR BYPHASE TVALUE TUNITS PHASE) ON (OFF) // set phase diagram isothermal display properties SET PARAMETERS POLYTHERMAL LISTTMINMAX (LISTINTCOMPOSITIONS LABELSURFACE LABELINTNORT) ON (OFF) // set phase diagram polythermal display properties SET PARAMETERS POLYTHERMAL DISPLAYFIGURE (DISPLAYPAGE DISPLAYBOTH) // set phase diagram polythermal display properties SET PARAMETERS POLYTHERMAL LABELINTN (LABELINTT) // set phase diagram polythermal display properties font color="#FF0000">SET PARAMETERS POLYTHERMAL LABELINTPOINT ON (OFF) // set phase diagram polythermal display properties SET PARAMETERS POLYTHERMAL NORTCOLOR 'color' (or '0-15') // set phase diagram polythermal display properties SET PARAMETERS POLYTHERMAL POINTCOLOR 'color' (or '0-15') // set phase diagram polythermal display properties
Post Processor and Plot Species Selection Windows - SET PLOT commands for the Post Processor Windows :
- An example of plotting Equilib figures is given in the macro file EquiEx_CH4-O2_Figure.mac
stored in the Macros folder.
SET PLOT AXIS/CAPTION/LABELS/DISPLAY/SELECT 'options'
SET PLOT AXIS Y-AXIS (X-AXIS) 'property' 'function' 'minimum' 'maximum' 'step'
// where 'property' is one of: n X gram % alpha T P Cp G V H V S or page
// where 'function' is one of: Y log10(Y) ln(Y) exp(Y) or 1/Y
SET PLOT CAPTION TITLE 'title' // figure title
SET PLOT CAPTION SUBTITLE 'sub-title' // and subtitle
SET PLOT CAPTION Y-TITLE (X-TITLE) ' title' // axes captions
SET PLOT CAPTION LABEL 'X' 'Y' 'label #1' // coordinates and user-defined label
SET PLOT CAPTION LABEL 'X' 'Y' 'label #2'
SET PLOT CAPTION LABEL .... etc.
SET PLOT DISPLAY COLOR ON (OFF) // color (or B/W)
SET PLOT DISPLAY COLORS 9 12 2 ... // color numbers 0 - 14
SET PLOT DISPLAY COLORS RED BLUE GREEN ... // color names BLACK MAROON ... AQUA
// colors BLACK MAROON GREEN OLIVE NAVY PURPLE TEAL GRAY SIVER RED LIME YELLOW BLUE FUSHIA AQUA
// 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
SET PLOT DISPLAY REACTANTS ON (OFF) // list reactants in the title (if CAPTION TITLE not set)
SET PLOT DISPLAY FILE_NAME ON (OFF) // list soyurce file in subtitle (if CAPTION SUBTITLE not set)
SET PLOT DISPLAY SOURCE ON (OFF) // include data source in species label
SET PLOT DISPLAY PHASE ON (OFF) // include phase name in species label
SET PLOT DISPLAY NAME ON (OFF) // include species name in species label
SET PLOT LABELS SIZE 2 (2 - 24) // size of labels
SET PLOT LABELS NO 2 (1 - 9) // number of labels per plotted line line
SET PLOT LABELS CHEMICAL (INTEGER or NONE) // type of label
SET PLOT LABELS OFFSET ON (OFF) // offset labels above their coordinates
SET PLOT SELECT CLEAR // clear current species salection
SET PLOT SELECT MASS MOLE (GRAM) // mass units
SET PLOT SELECT ORDER INTEGER (MASS FRACTION or ACTIVITY)
// order with respect to integer or mass ...
SET PLOT SELECT TOP 1 (2 ...) // select top species as defined in ORDER
SET PLOT SELECT IGNORE ON (OFF) // ignore species and phase that have no mass
SET PLOT SELECT STABLE PHASE (LIQUID SOLID SOLUTION)
// select all stable phases (ALL S TABLE PURE LIQUIDS ...)
SET PLOT SELECT SPECIES 2 5 8 // select species 2 5 and 8
6.14 Macro Windows commands - LOG_OFF, REBOOT, SHUTDOWNWINDOWS LOGOFF // Quit all applications and logoff the PC
WINDOWS REBOOT // Quit all applications and reboot the PC
WINDOWS SHUTDOWN // Quit all applications and shutdown the PC
Example:
LOAD EQUI9999.DAT // Load an Equilib file
CALC // calculate
SAVE EQUI1234.TXT // save the results
WINDOWS SHUTDOWN // then quit FactSage (and any other appliactions)
// and turn off the PC when done.
END
6.15 Macro display commands - REM, SHOW, HIDE, HIDE_MACRO and MSGBOX
REM 'string' // A remark - line of comments in the Macro Window
HIDE // FactSage windows will become hidden
// - same effect as clicking on Macro 'Hide'.
HIDE_MACRO // Macro Window will become hidden (minimized)
SHOW // FactSage windows will become visible
// - same effect as clicking on Macro 'Show'.
MSGBOX 'string' // post a message on the screen
MSGBOX FILENAME 'Filename' // post contents of a small text file on the screen
VIEWTEXT 'Filename.txt' // post contents of a large text file on the screen
6.16 Macro Phase Diagram commands FIGURE,
SUPERIMPOSE, VIEWER
FIGURE 'Filename1.fig' // Display the figure stored in the .fig file
FIGURE 'Filename2.fig' SUPERIMPOSE
// Superimpose this figure on the previous one.
VIEWER 'Filename1.fig' or VIEWFIG or VIEWFIGURE ...
// Use Viewer to display the figure.
// Unlike Figure, Viewer can display many figures at the same time.
Examples:
%1 = PHASEx_Al-Mg-Sr-liquidus
FIGURE %DIR%1a.fig // Display c:\FactSage\PHASEx_Al-Mg-Sr-liquidusa.fig
FIGURE %DIR%1b.fig SUPERIMPOSE
// Superimpose c:\FactSage\PHASEx_Al-Mg-Sr-liquidusb.fig
FIGURE %DIR%1c.fig SUPERIMPOSE
// Superimpose c:\FactSage\PHASEx_Al-Mg-Sr-liquidusc.fig
6.17 Macro Debugging commands
- DEBUG /ON, DEBUG 'caption', DEBUG /DEL
The command 'DEBUG /ON' (new in FactSage 7.0) activates the debug mode and displays the 'DEBUG Macro Window'
which lists the current values of all user-defined %variables.
Each time a DEBUG command is issued the debug Window is updated with the current values.
It is hoped that this will become a valuable tool in macro processing development.
As an example, load and run the macro file EquiEx_New_in_7.0.mac that is stored in the Macros folder.
// The DEBUG commands are a debugging aid and have no effect on the macro processing. DEBUG /ON // Activates the 'DEBUG Macro Window' DEBUG /OFF // Deactivates the debug mode - this is the default setting. DEBUG 'caption' // Lists current values of all %VARIABLES - 'caption' is the display heading DEBUG /DEL %var1 %var2 ... // Drops %VARIABLES from the debug list
REM File EquiExample_1.mac REM ====================== REM REM Loads Equilib file Ex_CH4-O2, calculates and displays results. %DIR = $FSDIR // Set user default directory to FactSage directory $FACTSAGE_DIR\ OPEN EQUIEx_CH4-O2.DAT // Load Equilib file CALC // and calculate the equilibrium. SHOW Equilib.txt // Save in Equilib.txt and display the output. SHOW Equilib.tab // Save in Equilib.tab and display the tabular spreadsheet. SHOW Equilib.xml // Save in Equilib.xml and display in xml format. END // End of the macro processing.Notes on EquiExample_1.mac:
REM File EquiExample_2.mac
REM ======================
REM
REM Macro that prompts you to enter input file and output page numbers.
//Ask user for default directory name:
%DIR %DIR ASK Enter the name of the default directory:
MARK Begin // A marker - see 'GOTO Begin' later on.
%1 0 ASK Enter Equilib file number (1 to 9999) _- or 'Cancel' to quit.
// Ask user to define %1. Note ' _' for a new line.
// Ex: %1 = 1234
// Cancel returns the default value (0 in this case)
IF %1 < 1 GOTO Bottom // %1 must be in the range 1 to 9999
IF %1 > 9999 GOTO Bottom // - see 'MARK Bottom' at the end.
OPEN EQUI%1.DAT // Ex: Open file 'C:\FactSage\EQUI1234.DAT'
CALC // and then calculate the equilibrium.
SHOW EQUI%1.TXT // Ex: save in 'C:\FactSage\EQUI1234.TXT' and display.
IF $PAGES < 2 GOTO IgnorePage
// $PAGES is the number of equilibrium Results pages
REM - Prompt for the page number.
%2 0 ASK There are $PAGES pages of results. _ _
Enter the results page number (1 - $PAGES) _
or enter 0 (Cancel) if none are to be displayed.
// Ex: %2 = 14. Note ' _' to continue on next line.
// Cancel returns the default value (0 in this case).
IF %2 < 1 GOTO IgnorePage
IF %2 > $PAGES GOTO IgnorePage
SHOW EQUIP%2.TXT %2 // Ex: save page 14 in 'C:\FactSage\EQUIP14.TXT'.
MARK IgnorePage
HIDE // Hide Equilib windows. Same as clicking 'Hide'.
GOTO Begin // Cycle through the macro again.
MARK Bottom // See ' ... GOTO Bottom'.
END
Notes
on EquiExample_2.mac:
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:
REM File EquiExample_3.mac
REM ======================
REM
REM This macro processes all the EQUI*.dat files where * = %First to %Last.
REM You are prompted to enter the %First and %Last values.
REM The output results are stored in EQUI*.TXT and EQUI*.RES
HIDE // Hide the Equilib windows.
// - this speeds up the processing.
VARIABLE %Results %First %Last // Declare user variables
%DIR %DIR ASK Enter the default directory for the files:
// Default directory for all the files.
%Results %DIR ASK Enter the directory where results will be stored:
// This will be the same as %DIR unless
// the user specifies other wise
%First 1 ASK Enter the first (minimum) Equilib file number (1 to 9999).
// Ask for the first file %First (default 1)
%Last 10 ASK Enter the last (maximum) Equilib file number.
// Ask for the last file %Last (default 10)
IF %First < 1 OR %Last > 9999 OR %Last < %First GOTO END
// Check if file numbers are OK
%1 %First // %1 is the first file
MARK Top // A marker - see 'GOTO Top' later on.
%3 equi%1.dat READ // Read the first word and store in %3.
IF %3 = 0 GOTO NextOne // Go to line 'MARK NextOne' if file
// equi%1.dat empty or does not exist.
OPEN equi%1.dat // Load the file from the default directory
CALC // and then calculate.
SAVE %ResultsEqui%1.txt // Save text output in equi*.txt
SAVE %ResultsEqui%1.res // Save results in equi*.res - this file will
// be accessible from the Results module.
MARK NextOne // A marker - see 'GOTO NextOne'.
%1 STEP 1 // Increase file number %1 by 1
IF %1 <= %Last GOTO Top // and cycle if not last file.
END // Terminate macro processing.
Notes on EquiExample_3.mac: 7.4 More
Equilib Macro Files
The three macro files EquiEx_CH4-O2-a.mac,
EquiEx_CH4-O2-b.mac and EquiEx_CH4-O2-c.mac are examples that are prepared
to show examples of IF ..THEN, DOCASE... ENDDO, and OLE exchange (both read and write)
with an open Excel Worksheet. Note that macro file EquiEx_CH4-O2-c.dat
is quite challenging.
An example of displaying calculated common thermochemical variables is given
in the macro file EquiEx_List_Results.mac - see $Thermochemical
Variables ($E_*$, $R_*$) at the bottom.
A complete example of most calculated thermochemical variables including solution
integral and partial properties and component lists is given in the macro file EquiEx_List_Thermo.mac.
An example of the 'SET' command is given in the macro file EquiEx_SET_Variables.mac.
8.
Phase Diagram Macro Files
Run the Phase Diagram module.
Edit the macro file PhasExample_1.mac:
Go to the Components Window.
Click on 'File > Macro processing
> Edit macro ..> Macros directory ..> PhasExample_1.mac
and open the file PhasExample_1.mac
This macro demonstrates how to calculate a Phase Diagram and display the
figure (*.fig).
Contents of PhasExample_1.mac:
REM File PhasExample_1.mac REM ====================== REM REM Loads Phase Diagram File %1, calculates and REM saves in .fig file %DIR = $FSDIR // Set user default directory to FactSage directory $FACTSAGE_DIR\ %1 1 ASK Enter the Phase Diagram file number (1-9999) or name IF $EXIST(PHAS%1.DAT) = 0 GOTO END // Quit if phase diagram file empty or not found HIDE // Hide the windows OPEN PHAS%1.DAT // Load file PHAS*.DAT CALC // and calculate the phase diagram. SAVE PHAS%1.FIG // Save in PHAS*.FIG SHOW // Show the windows FIGURE PHAS%1.FIG // Display via Figure module END // End of the macro processing.Notes on PhasExample_1.mac:
REM File PhasExample_3.mac
REM ======================
REM This macro processes all the PHAS*.dat files where * = %1 to %LAST (in the range 1 to 9999).
REM You are prompted to enter the default directory (%DIR), and to enter the first (%1) and last
REM (%LAST) file numbers. The calculated output results are stored in PHAS*.FIG
VARIABLE %LAST %Results\ // Declare user-defined %variables.
// The '.' in '%Results\' is simply to improve readability.
// No need to declare reserved variables %1 to %9.
%DIR %DIR ASK Enter the default directory for the files:
// Set default directory for all the files.
// Note %DIR is a reserved %variable - others are %1 ... %9.
%Results\ %DIR ASK Enter the directory where results will be stored:
// This will be the same as %DIR unless
// the user specifies otherwise
%1 1 ASK Enter the first (minimum) file number (1 to 9999).
// Ask for the first file %1 (default 1)
%LAST 10 ASK Enter the last (maximum) file number.
// Ask for the last file %LAST (default 10)
MARK Top // A marker - see 'GOTO Top' later on.
IF $EXIST(phas%1.dat) = 0 GOTO NextOne .
// $EXIST(): 1 file exists, 0 not exist.
// Go to line 'MARK NextOne' if phas%1.dat does not exist.
PRINT_ON // Show listing in the Macro Window
OPEN phas%1.dat // Load the file from the default directory
CALC // and then calculate.
SAVE %Results\phas%1.fig // Save figure output in phas*.fig
// that can be read by Figure & Viewer.
SAVE %Results\phas%1.bmp // Save figure output in phas*.bmp bitmap file
// that can be imported into Word and Power Point.
PRINT_OFF // Suppress listing in the Macro Window
MARK NextOne // A marker - see 'GOTO NextOne'.
%1 STEP // Increase file number %1 by 1. Same as %1 = $MATH(%1 + 1)
IF %1 <= %LAST GOTO Top // Do again if not > last file.
END // Terminate macro processing.
Such a command could be stored
in the macro - for example
SHELL_WAIT
%DIRcompare.bat %DIRold.txt %DIRnew.txt
Any differences between the 2 files
are written to the text file differ.log
Another application is in optimization. Mixing parameters in the
solution database Solution.dat are changed in systematic manner and
the results of Equilib calculations (stored in a *.res file) are compared
with experimental data. By summing the differences between calculated
and experiment values (liquidus temperature, activity data, enthalpies, etc.)
and comparing with previous calculations, a new (hopefully improved) parameter
is written in the database and the calculations repeated. The macro
uses SHELL_WAIT command and the $RETVAL parameter and it has less than 10 lines
- the strategy and optimization processing is performed in a separate program
(written in C++).
10.
Batch Processing - Running Equilib in the Background
With a standalone version of FactSage (the PC has a dongle) it is possible to run Equilib
(or Phase Diagram) macro processing without first calling FactSage.
This is done by running a *.bat file that contains a call to process
the macro file within the Equilib (Phase Diagram) module.
A sample .bat file Run_Equilib.bat (Run_PhaseDiagram.bat) is located in the FactSage directory.
This example loads and runs the macro file Macros\EquiEx_SET_Variables.mac.
In order to successfully run the batch file the following conditions must be respected:
When the macro processing is finished the Equilib module being run is then closed.
11. Summary of All Macro Variables, Functions and Commands ....