iimInit()

From iMacros
Jump to: navigation, search

Initializes the Scripting Interface. It opens a new instance of the iMacros Browser, IE or Firefox, or connects to an existing instance (depending on the specified parameters). If the command fails for any reason it returns an error code.


Syntax

int ret_code = iimInit( String commandLine [, boolean openNewBrowser], "", "", "", [, int timeout])

The "" are placeholders for three parameters that are no longer in use (replaced by iimRunner). We keep this format for backward compatibility.

As of iMacros V7.40 and later you can also use the new, simplified iimOpen command:

 int ret_code = iimOpen( String commandLine [, boolean openNewBrowser] [, int timeout])

In some languages you might be able to omit some or all the parameters, but if you would like to input timeout, you will have to include all of them.

Example:

In C# you used to write

iimInit("-ie", true, "", "", "", 300);

but now you can simply write:

iimOpen("-ie", true, 300);

In Delphi

Old:

iimInit ('-ie', true, null, null, null, 300);

New:

iimOpen ('-ie', true, 300);

In VBS can you can simply use

iimOpen("-ie")

or

iimOpen("-ie", true, 300)

You find more code examples for other languages in our Sample Code section.

Parameters

  • String commandLine
    Specifies command line switches. All switches start with a dash (-). Possible switches are:
    • IE Plug-in -ie Starts Internet Explorer instead of the iMacros Browser. Note that the iMacros sidebar needs to be open in IE so that it re-opens automatically when IE is started.
    • Firefox -fx Starts Mozilla Firefox instead of the iMacros Browser. (iMacros for Firefox needs to be installed, see this forum post for important information). Info: If you are using iMacros for Firefox 7.4 or later with an older iMacros version (below V7.5) please download the Firefox Scripting Interface separately.
    • Chrome -cr Starts Google Chrome instead of the iMacros Browser. iMacros for Chrome needs to be installed.
    • -tray Starts the iMacros Browser in tray mode. Note that some browser elements (e. g. Flash) might behave strange when the browser is hidden. In this case we recommend not to use this mode. It is always ok to have iMacros run in the background (=hidden by other windows or other iMacros instances), this does not disturb Flash. CPU usage of iMacros is the same with our without tray mode, it is always exactly the same as Internet Explorer.
    • -silent Starts the iMacros Browser in silent mode, i.e. tray mode without a tray icon.
    • -kioskmode Starts the iMacros Browser with menu, sidebar, and toolbar hidden. This is also a good way to protect macros from displaying during execution and/or being copied.
    • -runner Starts iMacros via the iimRunner tool.
    • -iePrivate" (IE only, so "-ie" must be given, too). This starts IE in "InPrivate" mode, i.e. each instance is separated from another.
    • -key Start iMacros with the specified license key, for example as Player. This ignores any license key that the user might have entered. Currently, this switch is supported in the iMacros Browser and IE. For Firefox, a special registry tweak is available instead (contact tech support for details).
    • -fxProfile MyProfile (FX only). Specifically for Firefox there are also the fxProfile switch. This switch is necessary when running several instances simultaneously, or with iimRunner.
    • -crUserdataDir MyUserDataDir (CR only). Uses Chrome --user-data-dir option. This switch is necessary when running several instances simultaneously, or with iimRunner. Use the full path to an already existent Google Chrome user-data-dir, if the path contains spaces, use double quotes.
  • boolean openNewBrowser
    Specifies whether to create a new iMacros Browser, Firefox or Internet Explorer process.
    If set to false, iMacros Scripting Interface looks around for uncontrolled instances (that is, not connected to a scripting interface) and attaches to any one found. If none is found, it will create a new process and connect to it.
    Default is true.
  • Long timeout
    iimInit waits <timeout> seconds for the iMacros Browser, Firefox or IE to start. Default is 30 seconds. Note that on systems with a heavy CPU load (near or equal 100%) it can take around 30s for a web browser to start. Example: You can change the timeout to 90s with iret = iim1.iimInit ("", true, 90)

Return values

  • 1 Completed ok
  • -1 Could not start the specified web browser
  • -3 Timeout (In the trial version this error can also occur if you do not press the iMacros trial version reminder screen "Continue" button in time. This issue can never occur in the full version.)
  • -6 (only with -runner flag) iimRunner not running. Please start iimRunner.exe first. You find this file in the iMacros program directory.
  • -7 (only with -runner flag) The max. number of allowed iMacros instances is reached. You can change this limit in the iimrunner.xml file. You find this file in the iMacros program directory. This error also occurs if there is no iimrunner.xml file.
  • -9 Failed to connect to Firefox or Chrome, or could not load imtcp.dll, the assembly necessary to remote control iMacros for Firefox and iMacros for Chrome. iimGetLastError should have the complete error message. Please, call iimExit to kill this process if you used iimInit to create it.

For more information see the complete list of Scripting Interface Return Codes.

Note: You should call iimExit always at the end of a loop or task, even if iimInit itself returns an error value and the browser is not started. This way you make sure all is "cleaned up". That is especially useful for running iMacros non-stop for weeks.

Examples

Initialize the Scripting Interface in silent mode (iMacros not visible in taskbar or tray - Visual Basic Script example):

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit("-silent") 

Initialize the Scripting Interface connection to an existing Internet Explorer instance:

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit("-ie", FALSE)

Start Firefox via iimRunner :

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit("-fx -runner")

Start Chrome via iimRunner:

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit("-cr -runner -crUserDataDir=c:\1test\c2")

Important: If the profile path contains blanks, so you should quote it, but because the whole command line is already a quoted string, you have to escape the quotes by using two quotes (in vbs). The whole thing should look like that:

 iret = iim1.iimInit(" -cr -runner -crUserDataDir ""c:\chrome profile""",true)

If your iimInit() is in C#, then use :

 iret = iim1.iimInit("-cr -runner -crUserDataDir \"c:\\chrome profile\", true);

Separate Browser Instances

For some web testing tasks it is important that different browser instances on the same machine do not share cookies.

Example: Assume you are Google and need to test Gmail. Then you may need twenty IE or Firefox instances running on the same machine, but each one logged into a different Gmail account. What iMacros does in instance A with the Gmail account A should not influence the next instance that is logged into Gmail account B.


iMacros achieves this with the following iimInit switches:


iMacros for Internet Explorer

Use the "-iePrivate" switch. Then cookies are not shared between each instance. The IE InPrivate mode is identical to a normal IE instance except that cookies are not stored on the hard drive and thus not shared.


iMacros for Firefox

Please use the "-fxProfile" profile switch. Firefox does not share cookies between different profiles. If you need to have 20 separate Firefox instances, you need to create 20 Firefox profiles.


iMacros for Chrome

Please use the "-crUserDataDir" chrome profile switch. Chrome does not share cookies between different profiles. If you need to have 20 separate Chrome instances, you need to create 20 Chrome profiles.

Note: The crUserDataDir support has just been added recently (V7.36), so it is not yet as thoroughly tested in the wild as the rock-stable automation support for IE and Firefox. Please contact support if you encounter any problems with it the Chrome browser automation.

iMacros Browser

For the iMacros Browser instance separation is not yet available. But you can use iMacros for IE instead.

Related forum post: Best Practices for running Multiple Browser Macros

See Also

64-bit Scripting Interface, iimPlay, iimDisplay, iimExit, iimGetLastError, iimGetLastExtract, iimTakeBrowserScreenshot