FactSage 7.0 (2015)
All the macro files stored in the /Macro folder have been checked with FactSage 7.0 and the files updated where necessary.
If you unfamiliar with macro processing go to the Reactants Window, click on 'File > Macro processing > Run macro > Macros Directory ...' and select EquiEx_SET_Variables.mac.
If you want to see the hidden generated information when you load and run one of your saved Equi*.dat files then select EquiEx_List_Results.mac and specify the Equi*.dat file.
For an example of how to open and interact (read and write) with an Excel Worksheet (.Xls and .xlsx files) and a Text Spreadsheet then select EquiEx_Xls_Simple_IO.mac.
For a complete list of examples click on 'File > Macro processing > Macro Processing - Examples ...'.
1. New Organisation and Documentation
|
The Macro Processing program has been reorganised, terminology has been simplified,
new commands and functions have been introduced,
and new documents have been added.
Examples of the new commands and functions are given in the macro EquiEx_New_in_7.0.mac. The system $Variables have been integrated into $Functions. This has no effect on the macro files. Compressed multi-word terminology for commands and functions such as SHELLEXECUTE SHOWLASTPD $FILESHORTDIR etc. have been expanded into SHELL_EXECUTE SHOW_LAST_PD $FILE_SHORT_DIR etc. in order to improve readability. The changes are backward compatible - i.e. the old terminology still works. A new document, Macro Processing - Summary, has been added to the menu. This summarizes all the macro variables, functions and commands that are available in macro processing. A new document, Macro Processing - Examples, has been added to the menu. This lists the examples and introduces all the Equilib macro files (EquiEx*.mac) that are stored in the Macros folder (typically 'c:\FactSage\Macros\'). |
|
2. New Commands
|
2.1 DEBUG
The new command DEBUG /ON 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 Macro 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.
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
// The DEBUG commands are a debugging aid
// and have no effect on the macro processing.
The screenshot shows the 'DEBUG Macro Window' that is displayed by the macro EquiEx_New_in_7.0.mac. |
|
2.2 DIM, REDIM
DIM is new in 7.0 and is identical to VARIABLE. It is now possible to declare a 2-dimensional array using DIM (or VARIABLE).
If a variable array has are already been declared, it can be re-dimensioned by using the new REDIM.
DIM %A %B(4) %C(2,3) // Declares %A, %B(1) %B(2) %B(3) %B(4),
// %C(1,1) %C(1,2) %C(1,3) %C(2,1) %C(2,2) %C(2,3)
REDIM %A(0:2,2) // Re-dimensions %A as %A(0,1) %A(0,2) %A(1,1) %A(1,2) %A(2,1) %A(2,2)
2.3 Defining tabular values
%total = $E_sMs$ // total number of product species
DIM %mole(%total) %activity(%total)
// 1. Define the tabular values of activity and moles one at a time
%1 = 1 TO %total
%activity(%1) = $E_sa%1$ // or $E_sa(%1)$. Note () aids in the readability.
%mole(%1) = $E_sm%1$ // or $E_sm(%1)$
%1 LOOP
// 2. More efficient way:
%activity(1:%total) = $E_sa(1:%total)$ // or $E_sa()$ or $E_sa$
%mole(1:%total) = $E_sm(1:%total)$ // or $E_sm()$ or $E_sm$
// 3. Simpler way:
%activity() = $E_sa()$ // () is useful since it denotes dimensioned variables.
%mole() = $E_sm()$ // ...
// 4. Simplest way:
%activity = $E_sa$ // This is OK but without () it is difficult to read or debug.
%mole = $E_sm$ // ...
2.4 Manipulating the definition of thermochemical $..$ variables
'(' and ')' can be inserted into the thermochemical $..$ variable to improve readability.
For example, in the following lines %act refers to the calculated activity of product species 4 and %gram refers to the number of grams of element (component) 2 in mixture (solution) 3.
DIM %Index1(10) %act %gram %Index1() = $ENUM(1) // %Index1(1) = 1 ... %Index1(4) = 4 ... %Index1(10) = 10 %2 = 4 %act = $E_sa4$ // activity of product species 4 %act = $E_sa4:4$ %act = $E_sa(4:4)$ %act = $E_sa%2$ %act = $E_sa(%2)$ %act = $E_sa%Index1(4)$ %act = $E_sa(%Index1(4))$ %act = $E_sa(%Index1(%2))$ %act = $E_(sa)((%Index1(%2)))$ %5 = 2 %6 = 3 %gram = $E_e2_mg3$ // grams of element 2 in mixture 3 %gram = $E_e%5_mg%6$ %gram = $E_e2_mg(3)$ %gram = $E_e%5_mg(%6)$ %gram = $E_e(%Index1(2))_mg(%Index1(3))$2.5 OLE commands for Text Spreadsheets
An Excel Worksheet is stored in the well-known *.Xls and *Xlsx Spreadsheet files supported by Microsoft. When programming with Excel files there are numerous ways the data stored in the cells of the spreadsheet can be processed, manipulated, plotted etc. By means of Object Linking and Embedding, OLE, you can use an Equilib macro to interact with an Excel Worksheet that may already be open in another application, in which case both applications will be able to share the same work space.
In FactSage 7.0 it is also possible to create an OLE link with a Text Spreadsheet that is stored in a *.txt or *.tab text file. This type of link 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) with Excel Worksheets and/or Text Spreadsheets.
All the current OLE commands and options for an Excel Worksheet (e.g. CLOSE, QUIT, CELLS, COLUMNS, ROWS, RANGE, GOTO, AUTOFIT, BOLD TRUE, CENTER, LEFT, RIGHT, CLEAR, COLOR, FONTSTYLE, HEIGHT, SIZE, WIDTH, etc.) also work for the Text Spreadsheet. In a macro to change an Excel Worksheet to a Text Spreadsheet in most cases you only need to replace the initial OLEn declaration as shown next.
OLEn: OLEn 'ExcelFileName' ['Sheet-Name'] // Create an OLE link (n = 1 to 9) with an Excel Worksheet stored in an Excel Spreadsheet file (*.xls,*.xlsx). // ex: OLE1 MyExcel.xlsx Input - creates a link to the 'Input' Worksheet 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.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.
3. New $Variable functions
The new array functions $ARRAY_DIM(), $ARRAY_COUNT(), $ARRAY_LBOUND() and $ARRAY_UBOUND():
DIM %A %B(4) %C(2,3) $ARRAY_DIM(%1) // => 0 : %1 is not an array $ARRAY_DIM(%B) // => 1 : %B() is a 1-dimensional array $ARRAY_DIM(%C) // => 2 : %C() is a 2-dimensional array $ARRAY_COUNT(%B) // => 4 : %B has 4 members - %B(1) %B(2) %B(3) %B(4) $ARRAY_COUNT(%C) // => 6 : %C has 6 members - %C(1,1) %C(1,2) %C(1,3) %C(2,1) %C(2,2) %C(2,3) $ARRAY_LBOUND(%B) // => 1 : lower limit of dimension - %B(1) $ARRAY_LBOUND(%C) // => 1 : lower limit of first dimension - %C(1,*) $ARRAY_LBOUND(%C 1) // => 1 : lower limit of first dimension - %C(1,*) $ARRAY_LBOUND(%C 2) // => 1 : lower limit of second dimension - %C(*,1) $ARRAY_UBOUND(%B) // => 4 : upper limit of dimension - %B(4) $ARRAY_UBOUND(%C) // => 2 : upper limit of first dimension - %C(2,*) $ARRAY_UBOUND(%C 1) // => 2 : upper limit of first dimension - %C(2,*) $ARRAY_UBOUND(%C 2) // => 3 : upper limit of second dimension - %C(*,3)The new $ENUM() function to enumerate the members of a user-defined array - $ENUM( 'start' ['step'] )
DIM %B(4) %C(2,3) %B() = $ENUM(1) // => %B(1) = 1, %B(2) = 2, %B(3) = 3, %B(4) = 1 %B() = $ENUM(0 -2) // => %B(1) = 0, %B(2) = -2, %B(3) = -4, %B(4) = -6 %C() = $ENUM(0) // => %C(1,1) = 0, %C(1,2) = 1, ... %C(2,2) = 4, %C(2,3) = 5New $TIME() functions to post the run time -
$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
4. User-defined $Functions and Procedures
In FactSage 7.0 it is now possible to program user-defined FUNCTIONS (e.g. $Function('arguments') and PROCEDURES (e.g. CALL SUBROUTINES) . The FUNCTIONS and PROCEDURES are listed at the end of the macro FUNCTIONS ... END FUNCTIONS and PROCEDURES ... END PROCEDURES) and may be executed from anyway with the macro.
FUNCTIONS
// The format of a user-defined function is :
// FUNCTION $'function name'('input parameters')
// - $'function name name' is any alphanumeric description starting with $.
// - 'input parameters' 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'('input parameters')
// - 'procedure name' is any alphanumeric description
// - 'input parameters' 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
