ph_run1 PowerHome formula function
Description
Uses a C# process control to execute/open files with a variety of options including launching as a specific user. 
Syntax
ph_run1 (as_appl)
ph_run1 (as_appl, al_timeout)
ph_run1 (as_appl, al_timeout, ai_flags)
ph_run1 (as_appl, as_arg, as_currdir, al_timeout, ai_flags)
ph_run1 ( as_appl, as_arg, as_currdir, as_user, as_pass, al_timeout, ai_flags )
Argument Description
as_appl String. The application, file, or hyperlink you wish to launch or open
as_arg String. Optional arguments to be passed on the command line to application in as_appl. Use an empty string "" if you have no arguments
as_currdir String. Set the current default directory for the process that is launched. Use an empty string "" if you don't wish to change the default directory
as_user String. An optional username to launch the process under. To use the current user that PowerHome is running under, use an empty string ""
as_pass String. An optional password for the as_user parameter to launch the process under. If you are not launching as a specific user, set this parameter to empty string ""
al_timeout Long. The number of milliseconds to wait for the process to finish if launching the process synchronously. Use 0 to wait indefinitely until the process finishes. If the function syntax you're using includes the ai_flags parameter it must have the value 64 added to it for this parameter to have any effect.
ai_flags Integer. A flags parameter that controls how the process or file is to be launched.  Individual options are added together. See Usage below for details
Return value
Long. If the process is launched asynchronously, the return value will be 0 if the function is successful and -1 if the function failed. If a -2 is returned, an exception occurred. You can retrieve the details of the exception by immediately calling the ph_lasterrorstring( ) function (note that the ph_lasterror( ) function is NOT updated by this function). If the function is launched synchronously, then the return value will be the exitcode generated by the process that was launched.
Usage
Use this function to launch/execute/open files, hyperlinks, and programs with a variety of options including launching as a specific user, hidden, without a visible window, etc. This single function with it's various overloads and options can effectively replace the following PowerHome functions: ph_run( ), ph_runasuser( ), ph_runasuser1( ), ph_runsync( ), and ph_runsync1( ) and will be deprecated at a later date.

Below are the values available for the ai_flags parameter. Add each value together for each desired option. See notes below as some options together will not work:

  • 0 - Window Style Normal
  • 1 - Window Style Maximized
  • 2 - Window Style Minimized
  • 4 - Window Style Hidden
  • 8 - Create No Window
  • 16 - Use Shell Execute
  • 32 - Hide Window after opening
  • 64 - Wait for process to finish

  • For the first 4 options (values 0, 1, 2, 4), you should choose only 1 value as the Window Style can only have one state. If you do add more than one Window Style value together, the higher value will win.
  • Option value 4 (Window Style Hidden) has no effect unless you also include option value 16 (Use Shell Execute). Similarly, option value 8 (Create No Window) has no effect if option value 16 (Use Shell Execute).
  • If the goal is to have the process window completely hidden, you need to have the ai_flags parameter contain both 4 + 16 or contain just 8 without 16. Using the 4 + 16 option has a higher success rate of hiding the window instead of just using 8 alone. Both methods will hide a cmd.exe window.
  • Option value 32 (Hide Window after opening) will work either with option 16 or without but the window will briefly flash open before being hidden.
  • If you wish to open a non-executable file or hyperlink using the default application assigned to the type, you must include option value 16 (Use Shell Execute)
  • if you have a process execute as a specific user and provide values for the as_user and as_pass parameters, you must NOT include option value 16 (Use Shell Execute). If you do, an exception will occur resulting in a return value of -2
  • Option value 8 (Create No Window) has no effect if option value 16 (Use Shell Execute) is included -OR- if you specify a userid and password to run the process as a specific user. If you need to run the process as a different user, the closest you can get to hiding the window is to include option value 32 (Hide Window after opening). You'll get a brief flash but the window will be immediately hidden

    The first four function overloads are detailed below:

  • ph_run1 (as_appl) - Supplies an empty string for the as_args, as_currdir, as_user, and as_pass parameters. The ai_flags parameter is 16 and al_timeout is 0
  • ph_run1 (as_appl, al_timeout) - Supplies an empty string for the as_args, as_currdir, as_user, and as_pass parameters. The ai_flags parameter is 80 (16 + 64)
  • ph_run1 (as_appl, al_timeout, ai_flags) - Supplies an empty string for the as_args, as_currdir, as_user, and as_pass parameters
  • ph_run1 (as_appl, as_arg, as_currdir, al_timeout, ai_flags) - Supplies an empty string for the as_user and as_pass parameters
    • Examples
    The following examples demonstrate typical syntax/usage for this function.
    • ph_run1("http://www.google.com") - Returns 0 if successful. This example opens the default browser and launches the www.google.com website. This works because the ai_flags parameter for this overload is 16
    • ph_run1("c:\powerhome\phtest.bat") - Returns 0 if successful. This example opens a cmd.exe window and then launches the phtest.bat batch file. The window will be visible. 
    • ph_run1("c:\powerhome\phtest.bat",0,4 + 16) - Returns 0 if successful. This example is the same as the previous one except that the window will be hidden
    • ph_run1("cmd.exe","c:\powerhome\phtest.bat","",0,8) - Returns 0 if successful. This example is basically the same as the previous one except that "Use Shell Execute" is not used. Because shell execute is not used, we cant directly open the batch file and instead have to pass it as an argument to cmd.exe
    • ph_run1("c:\powerhome\phtest.bat","","","","",2000,4 + 16 + 64) - Opens cmd.exe as a hidden window and executes the phtest.bat batch file. PowerHome will wait for the batch file to terminate and will return the exitcode from the batch file if one is supplied. If the batch file does not complete within 2 seconds, control is returned to PowerHome and a -2 (exception) will be returned. If ph_lasterrorstring( ) is called, it will state that the process did not yet finish. Note that the as_args, as_currdir, as_user, and as_pass parameters are all blank so we could have used one of the function overloads