Other Procedural Functions

Analytica User GuideOther Procedural Functions

CurrentDataFolder(folderPath)

Sets the current data folder to folderPath. The current data folder is the folder used by functions that read data files such as ReadTextFile(), WriteTextFile(), and SpreadsheetOpen() when their filename parameter contains no other path. When starting a model, it is the current model folder that contains the model. Specifying a path as a parameter to the function changes the current data folder to that path. If folderPath is omitted, it returns the path to the current data folder.

CurrentModelFolder(folderPath)

Sets the current model folder to folderPath. The current model folder is the folder into which the model (and submodules) are saved, by default. When starting a model, it is the folder containing the model. You can change it by selecting a different folder directly using the folder browser from Save as, or by using this function. If folderPath is omitted, it returns the path to the current model folder.

Evaluate(e)

If e is a text value, Evaluate(e) tries to parse e as an Analytica expression, evaluates it, and returns its value. For example:

Evaluate('10M /10') → 1M

One use for Evaluate(e) is to convert a number formatted as text into a number it can compute with, for example:

Evaluate('1.23456e+10') → 12.3456G

If e is an expression that generates a text value, it evaluates the expression, and then parses and evaluates the resulting text value. For example:

(VAR x := 10; Evaluate(x & "+" & x)) → 20

If e is a number or expression that is not a text value, it just returns its value:

Evaluate(10M /10) → 1M

If e is a text value that is not a valid expression — for example, if it has a syntax error — it returns Null.

Like other functions, it evaluates the parameter as mid (deterministic) or prob (probabilistic), according to the context in which it is called.

Evaluate(e) parses and evaluates text e in a global context. Thus, e cannot refer to local variables, local indexes, or function parameters defined in the definition that uses Evaluate(e). For example, this would give an evaluation error:

Variable A := (VAR r := 99; Evaluate('r^2') )

If e evaluates to a handle before it is passed to the function, then that object is evaluated and its (mid or sample) value is returned.

Evaluate and dependencies

Analytica’s dependency mechanism does not work with variables or functions whose identifiers appear inside the text parameter of Evaluate(). For example, consider:

Variable B := Evaluate("F(A)") Variable C := F(A)

Initially B and C compute the same value. If you then change the definition of function F or variable A, Analytica’s dependency maintenance ensures that C is recomputed when needed using the new definition of F and A. But, B does not know it depends on F and A, so is not recomputed, and can become inconsistent with the new values for F and A. In rare cases, you might intentionally want to break the dependency, in which case Evaluate() is appropriate; otherwise, use it only with care.

EvaluateScript(t)

This function evaluates a text value t as if it was typescript. This can provide access to typescript commands that aren’t available in expressions.

Tip

Avoid using EvaluateScript(t) except from event attributes (OnClick, OnChange or Script), or functions called from event attributes. This minimizes the danger of undermining the no-side effects rule.

GetProcessInfo(item)

Returns information about the current Analytica process from the Windows operating system. There are a large number of recognized values for item, and for a complete list see GetProcess-Info. Some of the possible values for item are:

"Process ID", "Thread ID", "Computer Name", "User Name", "Windows Version", "Command Line", "Total RAM", "Total Virtual", "Free RAM", "Private Bytes".

GetProcessInfo("User Name") → "Drice"

You can also access the value of an environment variable as "item:name".

GetProcessInfo("HOMEPATH”) → "\Users\Drice"

A few options provide information about Analytica’s state:

"User Objects", "Total Objects".

GetProcessInfo("User Objects") → 76

GetRegistryValue(root, subfolder, name)

Reads a value from the Windows system registry. This can be quite useful if you install your Analytica model as part of a larger application, and if your model needs to find certain data files on the user’s computer (for example, for use with ShowPdfFile, ReadTextFile, or RunConsoleProcess). The locations of those files could be stored in the registry by your installer, so that your model knows where to look.

Example

GetRegistryValue("HKEY_CURRENT_USER", "Software/MyCompany/MyProduct", "FileLocation")

IgnoreWarnings(expr)

Evaluates its parameter expr, and returns its value, while suppressing most warnings that might otherwise be displayed during the evaluation. It is useful when you want to evaluate an expression that generates warnings, such as divide by zero, that you know are not important in that context, but you do not want to uncheck the option Show Result Warnings in the Preferences dialog, because you do want to see warnings that might appear in other parts of the model.

IsResultComputed(x)

Returns 1 if the value of x is computed when the function is evaluated. To test whether the sample value of x has been computed, use Sample(IsResultComputed(x)), or to test the mid value use Mid(IsResultComputed(x)).

OpenURL(url)

Opens url in a browser window, using your default browser.

ShowPdfFile(filename)

Opens filename using Adobe Reader or Acrobat if one is installed on this computer and the file is a PDF document. ShowPdfFile is most useful when called from a button script, for example, as a way to provide the user of your model with a way to open a user guide for your model.

Try( expr, catch, errorNum)

Attempts to evaluate and return the result for expr. If an evaluation error occurs directly in expr, or in a User-Defined Function (UDF) called from expr, then catch is evaluated without reporting the error.

Example

Try( COMCreateObject("MSXML"), catch: Null )

Inside the catch expression, you can refer to local variables named ErrorText, ErrorNumber and ErrorLocation, containing information about the error. ErrorLocation contains a handle to the object where the error occurred. You can re-issue the error from within the catch expression by calling ReThrow(). In some cases, you might want to change the error text to your own by calling Error().

You may optionally specify specific error numbers to catch using the errorNum parameter:

Try( COMCreateObject("MSXML"),

errorNum: 42770, 43033, 43034,

catch: Error("You don’t have MSXML installed")

)

To find the error number for the errorNum parameter, set your catch expression to MsgBox(ErrorNumber) and cause the error to occur. Once you have the number or numbers, reset your catch expression as you would like it.

Try() does not suppress or catch warnings. For that, use IgnoreWarnings().