9.209 SYSTEM_COMMAND

Note: Built-In Function Rules     Usage Options

Executes an operating system command.

Arguments

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req Command Execution option: X = Execute via synchronous process. B = Execute via synchronous process in silent mode. S = Execute via the "system" command interface in a command interpreter window. H = Execute via the "ShellExecute" command interface. A = Execute via asynchronous process. W = Backward compatibility only. Use "S" instead. For IBM i: All options result in synchronous execution of the command. 1 1     2 A Opt Command string part 1 1 256     3 A Opt Command string part 2 1 256     4 A Opt Command string part 3 1 256     5 A Opt Working Directory 1 256

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 N Req Return/Response Code from the operating system. For IBM i: 0 = command successfully executed 1 = command failed to execute successfully. 3 7 0 0

Technical Notes - all platforms

• By using this Built-In Function you are introducing an operating system dependency into your function.
  
  You, the application builder, are totally responsible for doing this, and there is no guarantee, expressed or implied, that anything you do via this Built-In Function is in any way portable across different operating systems (or even versions of the same operating system).

• Do not use this facility to call the X_RUN entry point. It may be used to "start" or "spawn" another X_RUN process, but not to cause it to be recursively invoked.

• As a general rule on a Windows platform, for the Command execution option, try the "X" option first, and if it does not process the command as you require, try the "S" option.
  An overview of the execution options:

• The "X" option is recommended as it performs synchronous execution of the command on all platforms. This causes your LANSA Function to wait while the command executes. The processes created will be fully under the control of Windows Desktop Heap Management – if it is enabled – otherwise, it will use the parent's desktop heap. Note that a return code of 2 implies that the command cannot be found or a dependent DLL cannot be found. On IBM i and Linux, this option is executed the same as the "S" option.
  
  Following is an "X" option example, to invoke a Windows' notepad.exe to display a text file:
  USE BUILTIN(SYSTEM_COMMAND) WITH_ARGS('X' 'notepad.exe' ' ' 'c:\temp\x.txt') TO_GET(#STD_NUM)
  
  "X" option does not start a command interpreter so commands like COPY or DEL are not supported. If you need to use these commands, use the "S" option. For a complete list of these commands on a Windows platform, start a Command Prompt and type "Help".

• The "B" option is the same as the 'X" option, however, the execution is performed in the background and hidden on the Windows platform.
  Use Builtin(SYSTEM_COMMAND) With_Args(B ('c:\temp\x.cmd >> c:\temp\output.txt 2>&1')) To_Get(#STD_NUM)

• The "S" option indicates that the command should be executed as a standard C "system" command. This option starts a command interpreter, so commands like COPY and DEL are supported. For example, use the "S" option to execute a command line:
  USE BUILTIN(SYSTEM_COMMAND) WITH_ARGS('S' 'help.exe > c:\temp\x.txt') TO_GET(#STD_NUM)

• The "H" option is only available in the Windows environment and invokes the operating system linked editor/viewer for the file specified in the following arguments. Thus if command string part 1 contained c:\temp\test.doc then the operating system editor associated with a .doc file (probably MS Word) would be started. Likewise c:\temp\test.htm would probably cause an HTML browser to be started. The editor/viewer is executed asynchronously. For example, the "H" option to display a text file using the system's default application:
  USE BUILTIN(SYSTEM_COMMAND) WITH_ARGS('H' 'c:\temp\x.txt') TO_GET(#STD_NUM)

• The "A" option is the same as the "X" option, except it performs asynchronous execution of the command. It is fully supported on all supported Windows platforms. It has been implemented for other platforms, but it may or may not work as expected and LANSA reserves the right to not address such issues.

• The "W" option exists for backward compatibility. The "S" option should be used for new applications.

Technical Notes - Windows & Linux

• Each operating system has differing rules about commands and about the environments in which they are allowed to be executed.

• It is solely the application builder's responsibility to test that commands are valid, and that they function as expected.

• When an application design has a critical point involving the use of this Built-In Function, make sure it does what you expect it to do before basing an application design around it.

Technical Notes - IBM i

• The operating system command specified must be eligible to be executed via the IBM Execute Command (QCMDEXC) API.

• Commands executed via SYSTEM_COMMAND adopt the authority of the LANSA system owner user profile and the user profile of any other entries in the call stack with USRPRF(*OWNER) as long as the chain is not broken by an entry in the call stack with USEADPAUT(*NO).

     If this does not suit your site security policy, then use this command:

CHGPGM PGM(M@SYEXEC) USRPRF(<your value>) USEADPAUT(<your value>)

     You should check these values after any upgrade to your LANSA system.