Runprogram

Purpose

Executes a call to another operating-system program, optionally returning when the called program has finished execution, to the statement in the calling program that follows the RunProgram statement.

Syntax

RunProgram [[Shell] [Wait] | [[Shell] Background] {program-name} [{program-arguments}]

What It Does

RunProgram runs the program first named in the contents of program-name.  Command arguments that should be passed to the program, should be placed in program-arguments.

If the shell option is included, the command will use the operating system shell to start the program. In Windows Vista and later, this is specifically used to enable to the Vista UAC credential (user consent) prompt when starting programs that require elevated administrator privileges. Note that when the shell option is used, any program arguments must be placed in program-arguments, and cannot be mixed with program-name.

The shell option can also be used to launch a program associated with a specified document/file, without specifying the executable file name. This is often used to open a document, such as a .doc file or .pdf file. In such case the document should be specified instead of program-name.

The shell option must be used with either the wait or background option.

If the wait option is included, execution will return to the running DataFlex program at the line following the RunProgram command, upon termination of the program first named in program-name.

If the background option is included, execution will return to the running DataFlex program at the line following the RunProgram command, immediately after launching of the program first named in program-name.

As of DataFlex 25.0, RunProgram no longer falls back to command prompt calls (comparable to Shell). Note: if your program no longer starts you will have to add the 'Shell' attribute.

• Users that called a .bat file should now do that using 'Shell'.
• Users that depended on capital .EXE,.COM,.BAT behaviors should now do that using 'Shell' in the .bat scenario.

Example

RunProgram wait "TotalHoursForEmployee.exe" "EmployeeId=58"

In this example, RunProgram executes the program TotalHoursForEmployee.exe, which might be another DataFlex program, with argument EmployeeId=58. After TotalHoursForEmployee.exe has completed, execution will return to the calling DataFlex program after the RunProgram line.

String sDocument sWordProc

Move "Word.exe" to sWordProc

Get Value of oCustomer_Document to sDocument

RunProgram Wait sWordProc sDocument

In this example, the program Word.exe is executed with an argument of sDocument (the value of a dbForm object named oCustomer_Document). When the program named in sWordProc has terminated, execution returns to the calling DataFlex program at the command line following the RunProgram command.

String sDocument sWordProc

Move "notepad.exe" to sWordProc

Move "MyNotes.txt" to sDocument

RunProgram Background sWordProc sDocument

In this example, the Windows Notepad program is launched and opens the file MyNotes.txt. Execution in the calling DataFlex program continues immediately at the command line following the RunProgram command.

RunProgram Shell Background "WasAdmin.exe"

In this example, the WebApp Server administrator program is launched using the shell option to enable the operating system to display the UAC credential (user consent) prompt if necessary.

RunProgram Shell Background "document.pdf"

In this example, the shell option is used to open the file document.pdf, it launches the default program associated with the file type extension.

RunProgram can be used to execute calls to any program, including other DataFlex programs or even calling another copy of the same (calling) program.

If you call a program from itself using RunProgram with the background option, it starts another copy of the same program:

RunProgram Background "Order"

If you call a program from itself using RunProgram without the background option, it restarts the program:

RunProgram "Order"

Note that this method will not prompt the user and will ignore all exit validations for things like unsaved changes. If you want those validations to occur, you should send Exit_Application instead.

You could use this method to restart a program and pass parameters to itself (e.g. restart it with different options, user rights, etc.). See the cCommandLine class for reading command line parameters passed to a program.

  Example

Procedure StartNotePad

    Handle hoPanel

    Get Main_Window to hoPanel

    Set View_Mode of hoPanel to Viewmode_Iconize

    RunProgram Wait 'notepad.exe'

    Set View_Mode of hoPanel to Viewmode_Normal

End_Procedure

This example shows how to use the View_Mode property of an Application's main panel to minimize the application while waiting for a RunProgram wait call to another program to complete and then return the application to its previous size. This way the panel of the starting program is minimized and while you can see it in the Windows taskbar you cannot give it the focus.

Notes

• RunProgram will throw error if the calling of the program failed with the following conditions:
• DFERR_STRING_TOO_LONG If the working directory could not be read because it is invalid or too long (4096 characters).
• DFERR_OPERATION_NOT_ALLOWED When using the 'Wait' attribute, should the return code not be retrievable from Windows. In this case StrMark will contain the GetLastError() result.
• DFERR_FILE_NOT_FOUND If the application could not be found.
• DFERR_PERMISSION_DENIED This can occur if the program is not accessible to the current user. Or, if the application requires administrator privileges. The latter of which might now occur in cases like Windows administrator tools like perfom.exe, etc. These cases should now use the 'Shell' attribute.
• DFERR_CORRUPT_FILE This can occur if the manifest file or redirection logic of Windows (Registry) for a given executable is invalid or fails.
• DFERR_CANT_LOAD_DLL Occurs when a dll dependency could not be found, could not be started due to bad coding, or is missing exported functions (thus unable to load).
• DFERR_OPERATION_ABORTED Any unspecified error. In this case StrMark will contain the GetLastError() result.

• If the called program requires elevated administrator privileges, you must use the shell option to successfully launch the program in Windows Vista and later.
• RunProgram can be used to open documents by launching the default program associated with the file extension.
• Although RunProgram can be used to open documents, it will only launch the default program using the default verb, usually “open”. If you need to use any other verb, such as “print”, “edit” etc., you can use the ShellExecute Windows API call. This API call, when used with "print" as the "operation" parameter, will print a document in Windows using the application associated with it in the Windows Registry. Refer to MSDN documentation for information about ShellExecute.
   

// Since ShellExecute is already used in some predefined DataFlex packages,

// this #IFDEF statement will stop interference of this declaration with those

// inthe DataFlex packages.

#IFDEF GET_SHELLEXECUTE

#ELSE

// external function call used in Procedure DoStartDocument

External_Function ShellExecute "ShellExecuteA" shell32.dll ;

    Handle hWnd ;

    String lpOperation ;

    String lpFile ;

    String lpParameters ;

    String lpDirectory ;

    Dword iShowCmd Returns Handle

#ENDIF

// this will perform an operation on a file with the application

// registered in the Windows Registry to print that type of file (via its extension)

// sOperation would be "print" (it could also be "edit" etc).

Procedure DoStartDocument GLOBAL String sOperation String sDocument

    Handle hInstance hWnd

    Get Window_Handle To hWnd

    Move (ShellExecute (hWnd, sOperation, (Trim (sDocument)), '', '', 1)) To hInstance

    // check for errors  -- see the MSDN documentation about ShellExecute for details

    If (hInstance <= 32) Begin

    End

End_Procedure

• If RunProgram wait is executed with only "" as argument, a command prompt window will appear, awaiting input. If such input includes redirection of the output of a DOS program (the > operator), such a command must be a call to the command prompt program (cmd.exe), or the redirect operator will be interpreted as a parameter of the command.
• When RunProgram is executed, any uppercase letters in program-name are converted to lower case automatically. The contents of program-arguments are passed unchanged. Therefore, it’s recommended to always pass program arguments in program-arguments, and not mix program arguments together with the program name. Note also that with the shell option, you cannot mix the program arguments with the program name, all program arguments must be passed in program-arguments separately from program-name.
• If the running DataFlex program was called from another DataFlex program by a chain wait command, RunProgram is executed as though written with wait, and execution returns to the calling DataFlex program. Chain was used frequently in character-mode versions of DataFlex. The chain command is obsolete and should be replaced in all cases by RunProgram.
• After returning from executing RunProgram, a refind of any active tables is performed.
• The maximum length of the {program-name} parameter is 512 characters. This limit does not apply to ShellExecute.