ExecDos plug-in: Difference between revisions

From NSIS Wiki
Jump to navigationJump to search
No edit summary
No edit summary
Line 12: Line 12:
# it works out of section - for .onInit check outs;
# it works out of section - for .onInit check outs;
# multithreading - allows to run few applications at the same time.
# multithreading - allows to run few applications at the same time.
Plug-in puts stdout/log to stack or log file (if valid file name defined in the command line) instead of 'detailed' installer window like nsExec does, output size is limited with disk free space only. Maximum input (stdin) string size (i.e. plug-in second parameter) is up to 8kB in the special NSIS build, 1 kB otherwise. The same with output lines length if /TOSTACK option defined.<br>
Plug-in can put application output to log file, 'detailed' installer window, any other text window, to installer stack or calls script function to handle every line. Maximum input (stdin) string size (i.e. plug-in second parameter) is up to 8kB in the special NSIS build, 1 kB otherwise. The same with output lines length if target is not a file.<br>
'exec' return code depends on the execution mode: application exit code for sync mode and control thread handle for async one. Handle required for 'wait' - it helps to understand what application exit to wait for. If stack is not used between 'exec' and 'wait', both Pop after 'exec' and 'wait' parameter may be skipped - handle just sits in the stack.
'exec' return code depends on the execution mode: application exit code for sync mode and control thread handle for async one. Handle required for 'wait' - it helps to understand what application exit to wait for. If stack is not used between 'exec' and 'wait', both Pop after 'exec' and 'wait' parameter may be skipped - handle just sits in the stack.


== Syntax ==
== Syntax ==
=== "exec" DLL function ===
=== "exec" function ===
<highlight-nsis>
<highlight-nsis>
ExecDos::exec [/NOUNLOAD /ASYNC] [/TOSTACK] [/DETAILED] [/TIMEOUT=xxx] application_to_run [stdin_string] [log_file_name]
ExecDos::exec [/NOUNLOAD /ASYNC] /TOSTACK | /DETAILED | /TOWINDOW | /TOFUNC] [/TIMEOUT=xxx] [/ENDFUNC=func] application_to_run [stdin_string] [log_file_name | window | function]
</highlight-nsis>
</highlight-nsis>
: Executes console application.
: Executes console application.
Line 29: Line 29:
; DETAILED
; DETAILED
: puts output to installer' DetailedView window.
: puts output to installer' DetailedView window.
 
; TOWINDOW
: adds output lines to target window. Edit, RichEdit, ListView and ListBox supported
; TOFUNC
: pushes output lines to installer stack and calls script function
; application_to_run
; application_to_run
: application to run.
: application to run.
Line 36: Line 39:
; log_file_name
; log_file_name
: file where to put app's stdout (optional, but use "" if stack is not empty)
: file where to put app's stdout (optional, but use "" if stack is not empty)
; window
: output window handle
; function
: script function pointer


=== "wait" DLL function ===
=== "wait" function ===
<highlight-nsis>ExecDos::wait handle</highlight-nsis>
<highlight-nsis>ExecDos::wait handle</highlight-nsis>
: Waits for process exit.
: Waits for process exit.
; handle
; handle
: Control thread handle returned by 'exec' call in the /ASYNC mode.
: Control thread handle returned by 'exec' call in the /ASYNC mode.
=== "isdone" function ===
<highlight-nsis>ExecDos::isdone handle</highlight-nsis>
: checks thread is running. Returns 1 if application have exited, 0 if still running, -1 on error. /ASYNC mode only.
; handle
: Control thread handle returned by 'exec' call.


== Example ==
== Example ==
Line 72: Line 85:
</pre>
</pre>
'''Telnet and ssh''' Plug-in doesn't work with applications requiring terminal emulation.
'''Telnet and ssh''' Plug-in doesn't work with applications requiring terminal emulation.
/TOFUNC option and isdone function added by Afrow UK


[[Category:Plugins]]
[[Category:Plugins]]

Revision as of 18:26, 30 July 2007

Author: Takhir (talk, contrib)


Links

Download:
ExecDos.zip (40 KB)
Forum thread

Description

Plug-in works with console applications - creates hidden child process with redirected i/o. Compare to nsExec has four add-ons:

  1. string parameter that serves as stdin for running application - may be useful if you want to give login/password to running application;
  2. sync/async (background) process launch option - async is good for long running applications;
  3. it works out of section - for .onInit check outs;
  4. multithreading - allows to run few applications at the same time.

Plug-in can put application output to log file, 'detailed' installer window, any other text window, to installer stack or calls script function to handle every line. Maximum input (stdin) string size (i.e. plug-in second parameter) is up to 8kB in the special NSIS build, 1 kB otherwise. The same with output lines length if target is not a file.
'exec' return code depends on the execution mode: application exit code for sync mode and control thread handle for async one. Handle required for 'wait' - it helps to understand what application exit to wait for. If stack is not used between 'exec' and 'wait', both Pop after 'exec' and 'wait' parameter may be skipped - handle just sits in the stack.

Syntax

"exec" function

ExecDos::exec [/NOUNLOAD /ASYNC] /TOSTACK | /DETAILED | /TOWINDOW | /TOFUNC] [/TIMEOUT=xxx] [/ENDFUNC=func] application_to_run [stdin_string] [log_file_name | window | function]
Executes console application.
ASYNC
Not waits for process exit. Use 'wait' call if you want to get exit code. (/NOUNLOAD is mandatory!)
TIMEOUT
TOTAL execution time, milliseconds, for example /TIMEOUT=10000. Default is big enough. Short timeouts may cause app to be terminated.
TOSTACK
pushes output to stack instead of log_file (do not use log_file_name parameter with this option). May be confusing if few apps puts lines to stack in the async mode.
DETAILED
puts output to installer' DetailedView window.
TOWINDOW
adds output lines to target window. Edit, RichEdit, ListView and ListBox supported
TOFUNC
pushes output lines to installer stack and calls script function
application_to_run
application to run.
stdin_string
all that application can get from stdin (optional, use "" if stack is not empty)
log_file_name
file where to put app's stdout (optional, but use "" if stack is not empty)
window
output window handle
function
script function pointer

"wait" function

ExecDos::wait handle
Waits for process exit.
handle
Control thread handle returned by 'exec' call in the /ASYNC mode.

"isdone" function

ExecDos::isdone handle
checks thread is running. Returns 1 if application have exited, 0 if still running, -1 on error. /ASYNC mode only.
handle
Control thread handle returned by 'exec' call.

Example

Sync execution:

ExecDos::exec /TIMEOUT=2000 "$EXEDIR\consApp.exe" "test_login$\ntest_pwd$\n" "$EXEDIR\execdos.log"
Pop $0 # return value
MessageBox MB_OK "Exit code $0"

Async execution:

ExecDos::exec /NOUNLOAD /ASYNC "$EXEDIR\consApp.exe" "test_login$\ntest_pwd$\n" "$EXEDIR\execdos.log"
Pop $0 # thread handle for wait
# you can add some installation code here to execute while application is running.
ExecDos::wait $0
Pop $0 # return value
MessageBox MB_OK "Exit code $0"

BAT files specifics. On some of Win98 systems where "Close on exit" option is not set for DOS apps it was found

that after batch execution was finished (and installer continue it's job) hidden window still remains in the system

as "winoldapp". Following two lines solve the problem

@echo off
# place your code here
cls

Telnet and ssh Plug-in doesn't work with applications requiring terminal emulation.

/TOFUNC option and isdone function added by Afrow UK