iimPlay()

Plays a macro. After the macro has played all options that have been set with the iimSet command are reset. Use iimGetLastExtract to get the extracted text. Upon the next iimPlay() call, internal variables like !TIMEOUT_PAGE and !EXTRACT for instance, will also be reset to their default values.

There are two fundamentally different ways of playing a macro using the iimPlay command. The first is to specify the filename (without the extension) of the macro in the String macro parameter. The other is to generate macro code on-the-fly in your program, preceded by "CODE:", and pass it directly to iimPlay via the String macro parameter (see note below).

Syntax

int ret_code = iimPlay ( String macro [, int timeout] )

Parameters

String macro
Either the macro's filename without the extension, a string holding macro commands or the macro code.

(1) iimPlay ("demo-download") - If you just supply the macro name, iMacros looks for the file in the standard macro folder (as specified in the Options dialog).
(2) iimPlay ("c:\MyMacros\macro1.iim") - Full path*
(3) iimPlay ("Test\macro1") - Relative path* to the iMacros Macros folder
(4) iimPlayCode ("URL GOTO....") (old: iimPlay ("CODE:URL GOTO....") => Code Example, Tips: see note below.

* Backslashes in the path need to be escaped when using Javascript or any other language that requires backslashes in paths to be escaped.
For example: "c:\\MyMacros\\macro1.iim"

int timeout
The optional timeout value, in seconds. If iimPlay does not return before this time span, the Scripting Interface returns a timeout error -3. No extraction data is returned in this case. The default value is 600 seconds. This is the timeout for the overall macro runtime. This value should not be confused with the several timeouts inside a macro. The iimPlay timeout is typically triggered by a browser crash, a browser freeze or if the macro runtime exceeds this value.

Error Handling

iimPlay returns a detailed error code for every problem encountered. Please see the Scripting Interface Return Codes and the general iMacros Error-Codes, which are transmitted via the iimPlay command back to the calling application.

The return codes of iimPlay can not only be used to deal with "big" issues such as web browser crashes etc, but are often simply used to react to missing elements on a website. So if an element is not found on a website, and then the TAG command reports an error, and iimPlay returns this error to the script. Example: If you extract book ISBN numbers, some books may not have an ISBN number and the TAG command reports a "not found" error.

The error codes of iimPlay are exactly the same that you get from the iMacros Browser/IE/Firefox itself. In addition, there there Scripting Interface specific error codes that deal with unexpected errors timeouts or browser crashes.

Examples

Play a macro located in the Macros\ directory of your iMacros installation (Visual Basic Script example):

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimOpen() 
iret = imacros.iimPlay("mymacro")

Play some on-the-fly generated code (Visual Basic Script example):

Dim imacros, iret, mycode, myURL 

myURL = "https://imacros.net"  

mycode = "URL GOTO=" + myURL + vbNewLine 
mycode = mycode + "TAG POS=1 TYPE=A ATTR=TXT:Purchase»"

Set imacros = CreateObject("imacros") 
iret = imacros.iimOpen() 
iret = imacros.iimPlayCode(mycode)

Notes

Relative path

You have the option to use the relative path to the iimPlay command. For example, if your macro is in a subfolder "test" of the iMacros Macros folder, you may use iimPlay("test\yourmacro"). The same is valid for the iMacros for Firefox built-in Javascript Scripting Interface.

CODE:

The recommended method for playing a macro generated on-the-fly is to assign the entire macro to a single string and then use one call to iimPlayCode to play the macro. While it is possible to use multiple calls to iimPlayCode to play each line of your macro separately, keep in mind that each time you call iimPlay or iimPlayCode, all of the iMacros internal variables are reset, and this can produce undesired results if you call each line of your macro this way.
Several commands in a macro generated on-the-fly must be separated by the CR (carriage return) symbol. These are vbNewLine or vbCrLf in Visual Basic or \r\n in C, C++ or C#.
Use the iMacros Editor "Code Generator" (in the File menu) for converting your macro to inline code, or use the standalone iMacros Code Creator (no longer supported but still works well!).

Drop-down list boxes

If you start a macro via iimPlay which contains a TAG TYPE=SELECT... statement and the specified value is not in the drop down list then the iimPlay command returns an -1700 error code. In the corresponding error message (see iimGetErrorText) the maximum index is given. You can use this value, for example, to always select the last entry of a changing drop down list.

Playing iMacros for Firefox Javascript (.js) files

The version of iimPlay provided with the iMacros Enterprise Edition supports the playback of Javascript (.js) scripts in iMacros for Firefox. For example:

ret = iim1.iimOpen("-fx")
ret = iim1.iimPlay("MyScript.js")

The version of iimPlay provided with the built-in Javascript scripting interface in iMacros for Firefox only supports the playback of macro (.iim) files. However, there is a workaround as described in the following forum post:
- How to run 3 .js from one .js without stop?