Purpose

SYSTEM (or the ‘!’ prefix to the kernel command prompt), allows a program to be executed from PROIV. 
 

Syntax

RC = SYSTEM(statement)
 

Operation

RC is a scratch variable containing a return code indicating the status, success or failure, of the call itself  (and not the success or failure of any program called).  
statement is the statement to be passed to the Operating System, or a variable containing the statement. Literal values must be enclosed in single or double quotes (' or ").
 

Remarks

The value of the return code depends upon the Operating System; usually a return code of 0 (zero) indicates success.

This command is typically used to invoke an externally defined program; when the external program has finished, control can be returned to PROIV. The command string must be a literal surrounded by quotes. Any command within the quotes must be an operating system level command according to the current platform.

For use with the Windows Client, there are three special keywords that can be used at the beginning of the SYSTEM command statement:  

GUI:  means that the O/S command will call upon the Client machine.  Excluding this means that the O/S command will be executed from the server.

WINDOWS:  means that the program being executed is a Windows application.  This causes the Client to directly pass the command line as specified (minus any of these three keywords, if specified) to the Windows API “WinExec" (for Win16) or “CreateProcess" (for Win32) to execute. The default is to prefix the value of the “comspec" environment variable to the command and pass this to the above APIs to execute.

ASYNC:  means to run the specified program asynchronously.  The SYSTEM command will return immediately (without waiting for the command to complete) with its return status only indicating whether the WinExec/CreateProcess API returned a fail code.  Default is to run command synchronously (wait for completion, and return the exit code from the program).  

If used, these keywords must appear at the start of the command, in uppercase, with a single space separating each keyword. They must appear in the order specified above.  

For example, to run Windows Notepad synchronously:    
#RC = SYSTEM(“GUI WINDOWS NOTEPAD.EXE")

To run the command asynchronously:    
#RC = SYSTEM(“GUI WINDOWS ASYNC NOTEPAD")   

You can use the same syntax as above from the kernel command prompt
!GUI WINDOWS ASYNC NOTEPAD   

The kernel only looks for the keyword “Windows", which means “send the rest of the command line to the Client to execute".  Therefore, Windows must appear first. (The kernel looks for the string “Windows" as the first 4 characters (it must be upper case, with the fourth character being a space). The rest of the command line ordering and any limitations of upper case, extra spaces, etc., is up to the Client.  The Windows Client insists that WIN appears before ASYNC and also needs the keywords in upper case with no extra spaces.

For Win32, as an alternative to ASYNC, “start" can be used as a command prefix.  The Windows Start command executes a program in a separate Window, which can use the CMD.EXE built in command START to run a command asynchronously under NT:

For example, the above ASYNC command line becomes:  "!cmd /c start notepad")  

See also SYSTEM-CRT
 

Example 1

This command calls program prog1:   #RC = SYSTEM("prog1")  
 

Example 2

This command copies the contents of filea to fileb:   #ST = SYSTEM("copy filea fileb")   
 

Example 3

This command copies the contents of a file specified by the scratch variable $FILEA, to fileb:   #ST = SYSTEM("copy " + $FILEA + " fileb")
 

Example 4

This is a System call to server machine   #STAT = System(“<command>“)   
This is a System call to Client machine:   #STAT = System(“GUI <command>“)   
 

Example 5

This is a System call to a Windows application:   #STAT = System(“WINDOWS <command>“)   
 

Example 6

This System call executes the command using older versions (prior to version 127) of the MFC GUI:
#STAT = System(“/C <command>“)   

The actual O/S command is dependent on the shell command processor used., e.g. in Windows NT (CMD.EXE).  This is specified by ‘comspec’ in the .ini file Environment settings.

A ‘/C’ or ‘/K’ should be supplied in order for the command shell to execute a command.
 

Example 7

If no explicit path is defined:

On the server machine: looks in the WINXX directory (where the service is running).  

On the Client machine: looks in the Client Installation directory (where the service is running).