Script functions

Script functions

IDA scripts may invoke functions

IDA Modeler provides a list of functions for use in scripts.

Application-specific functions may be defined

• in script modules, using built-in function script-function;
• in compiled Lisp code (.fsl files) loaded by applications;
• in dynamically linked libraries (DLL), see Foreign functions interface.

Built-in script functions:

[The list is not ready yet]

These functions may be used in scripts, both as commands and in expressions. When used in expressions, the keyword :call should be inserted before the function name.

Before a function is called, all arguments are evaluated in the order from left to right.

Functions for working with data objects

(create-document appname doctype [:template file] [:name name] [:show show])

Creates a new IDA system or an auxiliary document. On success, returns the created document. The optional arguments may be given in any order.

(get-document filename [:ref ref-document] [:alt alt-action] [:batch batch] [:fresh fresh] [:cp codepage])

Returns the named IDA system (or document of other type). The document is loaded from named file (if not yet exists in memory). The optional arguments may be given in any order.

(save-document document [file])

Save the document to the given file (or to the document's original place if no file is supplied).

(save-document-as document file [:pack pack])

Save the document to the given file (or to the document's original place file is NIL).
Use pack to change the packing option. Valid values are :Yes, :True, :No, :False and :Auto to keep the old packing option.

(save-copy document [file [save-output]])

Save a copy of the document to the given file (or to a new temporary place if file is NIL or not supplied).
The output files are saved only if save-output is non-NIL.
The function returns the file name.

(close-document document)

Removes the document from memory.

(invoke-model system)

Advances the system to the next level, if such a possibility is implemented in the application.

(revoke-model system)

Removes the advanced level of the system, if such a possibility is implemented in the application.

(assert-data object [level])

Checks the parameter values in the data object using declared ranges and :assert scripts. Stops checking if found an error with level greater than the given one (default 1). Returns the maximal error level.

(assert-exist base [:error level] [:msg-step msg1] [:msg msg2] ref1 …)

Checks that the components referenced by ref1, ... exist in the base object. If not, writes messages msg1 (default "Required component ~S in ~S not found") and msg2 (default "Failed to dereference ~S in ~S") and advance error level to level (default 3). If some of msg1 or msg2 is nil, the corresponding message is not printed.
The arguments msg1 and msg2 may be symbols (instead of strings); in this case the text of the messages is loaded from dictionary (topic *log-messages*).

(add-model parent model-type [option value …])

Inserts a new model of given type into the given parent. The options specify the model's attributes (name, description, role, etc.)

The first argument should be either an instance of a non-atomic data object or a pane showing such an object.

The second argument may be either

;*. a name of an available template (symbol)
;*. a file name (only when inserting to a pane); the file should contain a macro template.

(replace-model object model-type [option value …])

Changes the model type of the given object to a new model type. The options may be used to change the attributes (name, description, role, etc.).

The first argument should be an instance of a non-atomic data object.

The second argument may be

;*. a name of an available template (symbol),
;*. a file name; the file should contain a macro template,
;*. an existing object of desired type (the parameter values are also copied in this case).

(rename object "new-name")

Changes the name of the object

(copy-component object target [if-exists [attr value ...]])

Insert a copy of the object in the target.

The argument if-exists specifies the action to be taken if the target already contains a component with the same name. Possible values:

The attr value ... may be used to modify the attributes of the copy.

(move-component object new-parent)

Moves the object from its old parent to the new-parent.

(bind var to)

Binds a scalar variable or an element of an array variable

The argument to may be

;*. a scalar variable or an element of a vector variable;
;*. a scalar parameter (only if the variable is a scalar; in this case the variable is bound to the own start value and the start value is mapped to the parameter);
;*. a number;
;*. :IV (binding to the start value);
;*. nil (remove the binding).

(plug interface [plug [flag] ])

Defines boundary conditions for variables in unconnected interface or interface reference.

The argument plug may be

The argument flag is used only when the value of plug (either supplied or default) is an interface. It may be a combination of bits (default is 0):

(collections object)

Returns the list of names of component collections defined for the given data object.

(load-resource-from-db scope entity_name name)

Loads the named object from data base and inserts it the given scope object. The entity name in most case is the same as model type of the inserted resource.

Access to values and other attributes

(get-value base ref [default-value])

Returns the value of the parameter (or start value of variable) referenced by ref relative to the given base object. If the referenced object does not exist or it is not a parameter or variable, the function either returns the default value (if supplied) or prints error message and returns NIL.

(get-relevant-value base ref default-value)

Returns the value of the parameter (or start value of variable) referenced by ref relative to the given base object. If the referenced object either does not exist, or it is not a parameter or variable, or it has flag F_IRRELEVANT the function returns the default value.

See also References to data objects and attributes

(get-resource base ref [default])

Returns the resource pointed by the resource parameter referenced by ref relative to the given base object. If the referenced object does not exist or it is not a resource parameter, the function either uses the default (if supplied) or prints error message and returns NIL. The default may be either a resource or a resource name.

See also References to data objects and attributes

(get-slot object ref)

Returns the given component or attribute or component's attribute of the data object. The argument ref is a relative reference from the given object to the required component or attribute.

See also References to data objects and attributes

(:value param)

Returns the presentation form of the value of the parameter (or the variable) param (e.g., translated to the current language).

(actual-value param)
(:actual-value param)

Same as value/:value except the case when the parameter value is :DEFAULT. In this case the expression returns the default value.

(set-value base ref value)
(set-values base ref value ref value ...)

Changes the value of the parameter (or start value of variable) referenced by ref relative to the given base object. Makes all checking and runs all scripts that should run if the value would be edited interactively. The reference ref is either a parameter name or a list of names of nested components and indices.

(set-flag par flag [on])

Sets or clears (if on is nil) the given flag or sum of flags.

(clear-flag par flag)

Equivalent to (set-flag par flag nil).

(set-relevant on par …)

Sets or clears the flags F_IRRELEVANT and F_DISABLED to one or more parameters.

Access to objects

See also References to data objects and attributes.

(parent object)

Returns the parent object (the object containing the given one as a component).

Special cases:

object is a non-empty list (that may denote an element of an array object): returns the parent of the first element in list;

object is a top-level object: returns the IDA application object;

object is not an object: returns NIL;

(component parent name)

Returns the named component or NIL if the parent has no such component.

Special cases:

name = :self: returns parent;

name is a list (name index ...): returns (component index ...);

parent is not an object: returns NIL.

(subcomponent parent name₁ ...)

Applies function component repeatedly.

(is-model model_name object)

Returns non-NIL if the object is an instance of a given type defined in the IDA application

The parameter model_name may also be

- a list of alternative model names;

- (:class class_name) to check object class instead of model type;

- (:eval expr) to apply the script expression for checking. It the expression starts with =, >, >=, <, <=, ==, /=, the construction (:eval ) may be omitted.

(find-model model_name parent)

Returns a component with given model type or NIL if parent has no such component. See is-model for possible values of model_name.

(list-models model_name parent)

Returns the list of all components with given model type. See is-model for possible values of model_name.

(list-model-names model_name parent)

Returns the list of names of all components with given model type. See is-model for possible values of model_name.

(count-models model_name parent)

Returns the number of components with given model type. See is-model for possible values of model_name.

(filter-models model_name list_of_objects)

Returns the list of all objects with given model type in list_of_objects. See is-model for possible values of model_name.

(connected-model model interface_name)

Returns the model connected with given one via named interface. Returns NIL if the interface is not connected or it is an output causal interface.

Simulation

(run-as system case [:hot hot-mode] [:batch batch-mode])

Runs the named simulation of the given system.

The list of simulations (parameter case) is defined in IDA application. If case is NIL, performs the default simulation.

With hot mode the results or the previous simulation are used in the new simulation. The possible values are

The batch mode reduces the interaction with the user during the simulation. The possible values are

(run-simulation system)

Runs (simulates) a mathematical-level system.

(show-results system)

Shows the results of the last simulation

User interface

(ask-for-object)

Asks user for choice of data object. Returns the selected object or NIL if the choice was canceled.

(edit-binding var)

Opens the binding dialog. The parameter var may be either an instance of a scalar interface or variable or an element of an array interface or variable.

Functions for generating reports

(export-form object target_file [option value ... ])

Saves a view of the given object (e.g. a diagram) to a file in graphic format (e.g., to show it in HTML report)

Supported options:

(process-html-form object source_file target_file ((var_name . value) ... ) [mode])

Copies the text from source_file to target_file replacing the names of the listed variables with corresponding values end executing the lines that start with #.

See HTMP-based reports for details. This function may be used for any text files, not only HTML.

Functions for working with object records

These functions work with object records loaded from IDA files. They may be used to modify (upgrade) the records representing data objects before the objects are created.

(lform-find name scope)

Searches for named component in the record scope. The name may be a list; in this case a nested component is searched. Returns the record found or NIL if not found.

(lform-push-component scope component)

Adds the record component at the beginning of the list of components of the record scope.

(lform-tag record)

Returns the object class of the record.

(lform-attribute record [attribute [default]])

Returns the value of the given record's attribute (default :v), If the record has no such attribute, returns the default (or NIL if no default supplied).

(lform-set-attributes record [attribute value ... ])

Replaces or adds the listed attributes.

(lform-set-class scope path class-name)

If the record scope contains a (maybe nested) component specified by path (see lform-find), changes the object class of that component. Otherwise nothing is done.

(lform-rem-attributes record [attribute ...])

Removes the listed attributes from the given record, if such exist.

(lform-remove record)

Marks the record as removed, so it will be ignored when the object will be created

(lform-remove-components scope [name ...])

Removes the named components (maybe nested) if present.

(lform-rename-component scope path new-name)

If the record scope contains a (maybe nested) component specified by path (see lform-find), changes the name of that component. Otherwise nothing is done. /P>

(lform-value scope [path [default [attribute]]])

Returns the value of the given attribute (default :v) of the component specified by path (default the scope itself) of the record scope. If the component is missing or has no such attribute, returns the default (or NIL if no default supplied).

(lform-scale-value scope path scale [attribute [step]])

If the value of the given attribute (default :v) of the component specified by path of the record scope is a number, multiplies it by scale and round to a multiplier of step, if supplied. If the value is an array, scales all elements of the array. If the value is missing or NIL, nothing is done. Otherwise prints an error message.

(lform-add-to-value scope path number [attribute])

If the value of the given attribute (default :v) of the component specified by path of the record scope is a number, adds the number to this value. If the value is an array, adds the number to all elements of the array. If the value is missing or NIL, nothing is done. Otherwise prints an error message.

(lform-sublis-value scope path dict [attribute])

The argument dict is an association list ((key . value) ...). In the value of the given attribute (default :v) of the component specified by path of the record scope (or in value's elements, if the value is an array), replaces all occurrences of key items by the corresponding values.

(lform-set-value scope name value [:class class-name] [:attr attribute])

Changes the value of the given attribute (default :v) of the named component of the record scope. If the component is missing, creates it using the given class-name. This function does not support nested components.

(lform-move record to [attribute value ...])

Moves the record from the current location to the beginning of the list of the components of the record to. Adds new attributes if supplied.

Control and information functions

(script-function name (par1 …) script …)

Defines a function with the given name and parameters. The given script is executed (with the current base object and local variables given as arguments) when the named function is invoked

(external-function return-type name (argtype …) dll-name [entry-name])

Declares an external function. See Foreign functions interface for details.

(inform level source message [arg ...])

Writes the message to the log window (in batch mode to the log file) and advances the error flag to the given level (if it was smaller)

The levels are: 0 – note, 1 – warning, 2 – hopefully fixed error, 3 – error, 4 – fatal error.

The message is either a string or a symbol (in this case the message text is fetched from dictionary file). The message may contain placeholders for arguments (see Lisp FORMAT).

The source is an object to be shown or a script to be executed on user’s request.

If there are objects among the arguments, their names are included in the message.

When the message is shown in the Log window, the objects are shown as active links.

To customize a link, write the corresponding argument as a list of options: (:arg arg key value ...)

To add an extra link and/or text to the message, use an additional argument (:add arg key value ...)

Here are supported keywords:

If no arguments are supplied and source is an object, an extra argument (:add source) is assumed.

The message text may also contain a link in HTML format: <a href=link>text</a> where link is the script to be executed when the link is clicked.

Alternatively a placeholder ~A may be used instead of the link; the link itself is fetched from the corresponding argument arg that should have the format (:link link).

(alert message [icon [arg ...]])
(alert message (:key value ...) [arg ...]])

Displays the message in a pop-up window (in batch mode writes it to the log file).

The message is either a message text (a string enclosed in double quotes) or a message name (a symbol) or a list (message arg …) there arg ... are arguments to be inserted into the window’s title. If the message is a symbol, the message title, text, and button labels are fetched from the dictionary file. The message text and the title may contain placeholders for arguments (see Lisp FORMAT). If there are objects among the arguments, their names are included in the message.

The icon is one of error-icon (the default), warning-icon, question-icon, information-icon, or an icon defined in the application.

The options (given as (:key value ...) may modify the appearance of the message dialog. The options are:

The arguments arg ... are inserted in the message text instead of placeholders. If there are objects among the arguments, their names are included in the message.

The function returns the number of the button clicked on. Hitting Enter is the same as choosing the first button (so 1 is returned). Hitting Escape is the same as choosing the last button.

In batch mode the function writes the message to the log file, advances the error flag depending on the icon used (warning-icon – 1, error-icon – 3) and returns 1.

(help object [topic])

Displays the online help to the given object.

The object may be

;*. A data object. The argument topic specifies the topic as described in .cnx file. See Preparing online help for details;
;*. A window;
;*. A symbolic name of a message. The argument topic should be either inform or alert depending on the message type;
;*. A string – for searching in the index of the online help;
;*. A number – the topic number in the online help file.

Graphical functions

(refresh-symbol model [pane ...])

Rebuilds the model's symbol on the given [or all] schema views. This function should be used after changes of the model's data that affect the appearance of the symbol.

(refresh-conline link1 link2)

Rebuilds the connection line between two links on all schema views. This function should be used after changes of the data that affect the appearance of the connection line

(close-pane [pane])

Closes the view containing the named or the currently active pane.

(set-property item name value)
(property item name [default])

Set and retrieve the value of the named property. The item may be a graphical element, window, a dialog item, a menu item or a symbol.

(def-file-type name pattern [description])

Defines a new file type to be used in the open/save dialog and in ranges of pathname parameters. The name should be a symbol, the pattern is a string containing one or more file pattern separated by ";". The description is a string. Alternatively the description may be stored in the dictionary.