System (command)

The System (SY) command either exits BR and returns control to the operating system or performs an operating system command while BR is active. System can be executed from READY mode, from a procedure file, or with the Execute statement.

Comments and Examples

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.

Another use of the SYSTEM command is to pass an executable string back to the operating system while BR remains active (but dormant) in the background. In the following example, the SYSTEM command passes a DOS BACKUP command to the operating system. Upon completion of the BACKUP command, BR will be reentered and will continue from where it left off.

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

When the next version (with the asterisk) of the same command is used, BR restores its own screen upon re-entry:

SYSTEM *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 FILE$(0)(1:3)="CON:" THEN EXECUTE "SYSTEM DIR" :!ELSE EXECUTE "SYSTEM ls -al /usr/BR"

Syntax

File:HELP0062.jpg

Defaults

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

2) Do not restore screen.

Parameters

"num-constant" |parameter sets the value of the operating system return code (accessed using ERRORLEVEL in DOS batch files, and through the $? substitution in Linux shell programming).

"string-expr" |parameter is an operating system command which BR passes back to the operating system for execution. If the result of the command requires no operator action, BR is immediately reentered. Since BR is active during the entire process, all variable values and memory remain the same. When the "string-expr" parameter is preceded by an asterisk, the BR screen is restored upon re-entry.

Additional Flags that 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 4500+) 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.

-M or -m	("minimize") flag has been enhanced.
	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. 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.

-@	Client Shell Call (default for Windows). If -@ is omitted, on Unix - 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

("continue") Windows launches 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) to 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. We found this today on one of our Macintosh clients that just updated to OSX 10.6.x

-r	("restore") Windows always performs shell in a separate window. (Unix ignores shell standard out data) If -r is omitted. then Unix forwards standard out and stdin data to and from the client window.
	Restores screen after running command on all systems. In windows, the screen is always restored, so this flag is essentially ignored. This is the same as sys *command. The newer syntax is more readable and preferred.

-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.