System (command)

The System (SY) command can do two things:

1. Exit BR and return control to the operating system, or
2. Perform a shell call (an operating system command) while BR is active.

System can be executed from READY mode, from a procedure file, or with the Execute statement.

Using SYSTEM to exit BR

Entering SYSTEM or it's short form, SY into the command line while in ready mode will exit BR. The same can be done using an Execute Statement or a procedure file. If the SYSTEM command is followed by a single number the system exits and passes the number to the OS as a BR return exit value.

Optionally, SYSTEM LOGOFF may be used when in client server to clear the login credentials. The next time client server is started, the user will be requested to enter their credentials.

Using SYSTEM to send commands to the operating system

Comments and Examples

One use of the SYSTEM command is to run a program. In the following example, the SYSTEM command runs a program called BACKUP. By default, the BR program waits until the called program has finished running, and then continues where it left off. The syntax includes the SYSTEM keyword and then the OS command, which in this case is the program name and location of the data to handle.

SYSTEM BACKUP C:\\*.DAT A: /S

When the same command is used with an asterisk preceding the program name, BACKUP, the BR program restores its own screen upon re-entry:

SYSTEM * BACKUP C:\\*.DAT A: /S

Furthermore, when the same command is used with one or more system-call-flags (described below) preceding the program name the functionality of the system call is augmented. Note that the OS command flags often need to be right after the program name and ahead of the OS command parameters. But they can also appear after the OS command parameters:

SYSTEM -s * BACKUP C:\\*.DAT A: /S

The statement below tests to see what type of operating system the program is running on, then executes the appropriate SYSTEM command for the operating system:

00100 IF WBPLATFORM$="WINDOWS" THEN EXECUTE "SYSTEM DIR" ELSE EXECUTE "SYSTEM ls -al /usr/BR"

Using Batch Files with System Exits

One use of the System command is to pass a return code to the host operating system as it permanently exits from BR. In the following example, a DOS batch file tests the return code (ERRORLEVEL) and performs a specific action according to its value.

BR PROC START
IF ERRORLEVEL 101 GOTO BADERROR
IF ERRORLEVEL 100 GOTO BACKUP
IF ERRORLEVEL 99 GOTO FORMAT
GOTO DONE
:BACKUP
BACKUPBR
:FORMAT
FORMAT A:
BRSTART
:BADERROR
ECHO BAD ERROR RETURN CODE >100
:DONE

If the command SYSTEM 100 were used to exit from BR while the above batch file was active, DOS would start a back-up procedure as soon as the BR exit was complete.

Syntax

SYSTEM [<numeric code for OS> | [system-call-flag] <OS command> ]

Defaults

1) Return control to the operating system with a return code of zero.

2) Do not restore screen.

Parameters

Code returned to OS parameter sets the value of the operating system return code which may be accessed using ERRORLEVEL in DOS batch files, and through the $? substitution in a Linux shell.

OS command parameter is an operating system command which BR passes to the operating system for execution. If the result of the command requires no operator action, BR is immediately reentered after the command finishes execution. Since BR is active during the entire process, all variable values and memory remain the same. When the OS command parameter is preceded by an asterisk, the BR screen is restored upon re-entry. The OS command parameter must be a string variable or a string enclosed in quotes.

System Call Flags

System Call Flags can alter the behavior of the shell call as follows:

-E or -e

"Errors" indicates that any Operating System errors returned from the shell should be reported (as error 4300). Otherwise shell call operating errors are ignored. Occasionally Windows returns error values for fairly nominal exceptions. So the -e is provided as an error return sensitivity level flag. Further information can be obtained by querying SYSERR or SYSERR$

-M or -m	Run the program "minimized".
	If a lower case m is specified, the process or program runs in a DOS command shell without displaying the DOS window, but with a corresponding icon on the task bar (effectively running the shelled process/program "minimized") This is only applicable in Windows. It is ignored on all other systems. If -m is omitted, the shelled program will open in a separate application window.

If an upper case M is specified, the same thing happens except the task does not appear on the taskbar. It runs invisibly. Furthermore SPOOLCMD calls use lowercase m.

-s	Server Shell Call (this is the default for Unix). If -s is omitted on Windows, then this shell call is performed on the client.

-@	If using Client Server, then it runs the program on the client. Client Shell Call is the default for Windows. If -@ is omitted, on Unix the shell call is performed on the server.
	(search path not implemented on client)

Note- Ctrl-] ALWAYS performs a DOS shell call on the client.

-c

The main program "continues" to run while running the called one. Windows launches the task and resumes BR operation where it left off. For Unix, the command is framed with NOHUP and &. If -c is omitted, then the shell call waits til the process is finished (up to the # seconds specified in SHELL LIMITS) before returning to BR. For OSX 10.6 you need sys -c | (pipe) Shell commands with a pipe make BR Continue after executing the sys -c (continue), if you do not insert the | pipe, then the script does not run under Br 4.18 and up. This was found on a Macintosh client that just updated to OSX 10.6.x

-r	Restores screen after running the command. Windows always performs a shell call in a separate window, so this flag is essentially ignored. This is the same as sys *command. If -r is omitted. then Unix forwards standard out and stdin data to and from the client window.

-w

("without shell") When a Windows application is called, use a -w flag to tell BR not to call COMMAND.COM, but to call the application directly. It must be a program (i.e. "exe") and not a script. The Search Path is used ON SERVER only (if no slashes). This option does NOT open a DOS window. It does not use Bourne shell. It enables unfiltered return values. A Timeout or Ctrl-A kills the process. If -w is omitted, then a timeout or Ctrl-A does NOT kill the process, which can leave orphans.

Note- Currently -w is ignored in Unix standard models.

blank

Application standard output is forwarded to the client. However the Bourne shell is utilized to initiate the process. The shelled program CAN be an executable script.

-p	("Page Standard Output") - This option applies to Unix server only. If -p is omitted, then output goes to screen without pausing

-t9999

Wait up to the specified number of seconds (for client server only). If -t is omitted, wait the number of seconds specified in the SHELL LIMIT statement (see BRConfig.sys chapter for more information on SHELL LIMIT)

Technical Considerations

1) Simultaneous pressing of the Ctrl key and the right- bracket (]) key has the same effect as the SYSTEM command's shell call, except that no command string is automatically executed upon access to the operating system. Pressing of these keys causes BR immediately access the operating system and display the system prompt. Between each operating system operation, a message about what action is required to return to BR will be displayed.

2) Too frequent or careless use of the SYSTEM command can make it more difficult to move your program to a new operating system. ADS strongly recommends the use of the FILE$ function in programs and procedures which access the resident operating system. This function allows programs to test the type of operating system before proceeding with a system-dependent sequence of commands. While the FILE$ function can always be programmed in at a later date, you may be able to save a great deal of time and recoding by placing it in programs as they are written.

3) When the system call (either Ctrl-] or the SYSTEM command) starts and then exits a secondary software program before returning to BR, the CODE function will reflect any return code that the secondary program has passed to the operating system. As soon as BR is reactivated, the value of CODE can be tested to Verify whether or not the secondary program was successful. This is currently valid for Linux versions of BR only.

4) BR passes all quotation marks within or surrounding the "string-expr" parameter back to the operating system.

5) The screen may be cleared on some Linux terminals when the SYSTEM call is completed. If this is undesirable, see Terminal Considerations for a possible remedy.

6) BR now searches PATHs during Windows shell call.

7) Shell calls to Windows applications are no longer maximized.

8) System calls -M -W -C -R now operate like their corresponding lower case flags. This case sensitivity had been suppressed to allow passing the flags to DOS, but that made the rules too obscure.

9) Concerning Unix shell calls, the following flag combinations are prevented-

-W and -C

-R and -C

-W and -R

In other words Without Shell, Restore Screen, and Continue are mutually exclusive options. If more than one is specified at a time, error 2222 is generated.

For disambiguation purposes, also see System Parameter.