The renewal maintenance has officially ended for Progress iMacros effective November 30, 2023.
This Wiki site will also no longer be moderated from the Progress side.
Thank you again for your business and support.
Sincerely, The Progress Team
Difference between revisions of "iimInit()"
(→Syntax) |
m (Text replacement - "http://www.iopus.com/download/imacros-chrome/" to "https://imacros.net/download/") |
||
(43 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
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 [[iimInit()#Return_values|error code]]. | 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 [[iimInit()#Return_values|error code]]. | ||
+ | |||
=== Syntax === | === Syntax === | ||
− | int ret_code = iimInit( String commandLine [, boolean openNewBrowser], "", "", "", [, | + | 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. | 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 [[API_enhancements|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: | Example: | ||
− | In C# you | + | In C# you used to write |
− | iimInit("-ie", | + | iimInit("-ie", true, "", "", "", 300); |
+ | |||
+ | but now you can simply write: | ||
+ | |||
+ | iimOpen("-ie", true, 300); | ||
In Delphi | In Delphi | ||
− | iimInit ( | + | Old: |
+ | |||
+ | iimInit ('-ie', true, null, null, null, 300); | ||
+ | |||
+ | New: | ||
+ | |||
+ | iimOpen ('-ie', true, 300); | ||
In VBS can you can simply use | 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. | You find more code examples for other languages in our [[Sample Code]] section. | ||
Line 28: | Line 49: | ||
*:Specifies command line switches. All switches start with a dash (-). Possible switches are: | *:Specifies command line switches. All switches start with a dash (-). Possible switches are: | ||
** [[Image:Ie-icon.png|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. | ** [[Image:Ie-icon.png|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. | ||
− | ** [[Image:Ff-icon.png|Firefox]] '''''-fx'' Starts Mozilla Firefox instead of the iMacros Browser.''' ([ | + | ** [[Image:Ff-icon.png|Firefox]] '''''-fx'' Starts Mozilla Firefox instead of the iMacros Browser.''' ([https://imacros.net/download/ iMacros for Firefox] needs to be installed, see [https://forum.imacros.net/viewtopic.php?f=8&t=12254 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 [[iimfirefoxconnector.dll|Firefox Scripting Interface]] separately. |
− | ** ''-tray'' Starts the iMacros Browser in tray mode. | + | ** [[Image:Cr-icon.png|Chrome]] '''''-cr'' Starts Google Chrome instead of the iMacros Browser.''' [https://imacros.net/download/ 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. | ** ''-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. | + | ** ''-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. | + | ** ''-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 | + | ** ''-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). | ** ''-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). | ||
− | ** Specifically for Firefox there are also the [ | + | ** ''-fxProfile'' MyProfile (FX only). Specifically for Firefox there are also the [https://forum.imacros.net/viewtopic.php?f=2&t=6163&p=17406#p17406 fxProfile switch]. This switch is necessary when running several instances simultaneously, or with [[iimRunner]]. |
+ | <!--This command is used for running automated tests with various Firefox versions. For IE there is no version switch as there can only be one IE version installed on a system. --> | ||
+ | ** ''-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 | *boolean openNewBrowser | ||
*:Specifies whether to create a new iMacros Browser, Firefox or Internet Explorer process. | *: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 | + | *: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''. | *:Default is ''true''. | ||
*Long timeout | *Long timeout | ||
− | *:iimInit waits <timeout> seconds for the iMacros Browser, Firefox or IE to start. Default is | + | *: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 === | === Return values === | ||
Line 50: | Line 73: | ||
*-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]].) | *-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. | *-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 | + | *-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]]. | 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 [[Web_Testing#Q:_How_can_I_set_up_a_24_hours_a_day.2C_7_days_a_week_.28non-stop.29_operation_with_iMacros.3F|running iMacros non-stop for weeks]]. | ||
=== Examples === | === Examples === | ||
Line 73: | Line 99: | ||
Set imacros = CreateObject("imacros") | Set imacros = CreateObject("imacros") | ||
iret = imacros.iimInit("-fx -runner") | 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 === | === Separate Browser Instances === | ||
Line 84: | Line 124: | ||
− | + | ====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. | 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 [[Clone_Firefox_Profiles|create 20 Firefox profiles]]. | 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 [[Clone_Firefox_Profiles|create 20 Firefox profiles]]. | ||
+ | |||
+ | ====iMacros for Chrome==== | ||
+ | |||
+ | Please use the "-crUserDataDir" [[Chrome_Nags#How_to_create_different_user_profiles|chrome profile switch]]. Chrome does not share cookies between different profiles. If you need to have 20 separate Chrome instances, you need to [[Clone_Chrome_Profiles|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. | For the iMacros Browser instance separation is not yet available. But you can use iMacros for IE instead. | ||
+ | |||
+ | Related forum post: [https://forum.imacros.net/viewtopic.php?uid=14026&f=8&t=12787&start=0#p38017 Best Practices for running Multiple Browser Macros] | ||
=== See Also === | === See Also === | ||
[[x64|64-bit Scripting Interface]], [[iimPlay]], [[iimDisplay]], [[iimExit]], [[iimGetLastError]], [[iimGetLastExtract]], [[iimTakeBrowserScreenshot]] | [[x64|64-bit Scripting Interface]], [[iimPlay]], [[iimDisplay]], [[iimExit]], [[iimGetLastError]], [[iimGetLastExtract]], [[iimTakeBrowserScreenshot]] |
Latest revision as of 09:22, 21 November 2018
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 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.
- -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.
- -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