System (command): Difference between revisions

From BR Wiki
Jump to navigation Jump to search
m (format)
 
(19 intermediate revisions by 5 users not shown)
Line 1: Line 1:
The '''System (SY)''' [[:Category:commands|command]] can do two things:
#Exit BR and return control to the [[operating system]], or
#Perform a '''shell call''' (an operating system command) while BR is active.


The '''System (SY)''' [[:Category:commands|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]].
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.
 
[[image:Sy.jpg]]
[[image:System2.jpg]]
 
==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===


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


Line 20: Line 51:


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.
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==
==Syntax==
[[Image:HELP0062.jpg]]
SYSTEM [<numeric code for OS> | [system-call-flag] <OS command> ]
[[Image:System.png]]


==Defaults==
==Defaults==
Line 41: Line 61:


==Parameters==
==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).
'''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.


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


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


{|
{|
|-valign="top"
|-valign="top"
|width="60"|'''-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.
|width="60"|'''-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$
|-valign="top"
|-valign="top"
|}
|}
Line 55: Line 76:
{|
{|
|-valign="top"
|-valign="top"
|width="60"|'''-M or -m'''||("minimize") flag has been enhanced.
|width="60"|'''-M or -m'''|| Run the program "minimized".
|-valign="top"
|-valign="top"
|width="60"| ||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.
|width="60"| ||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.
Line 63: Line 84:
{|
{|
|-valign="top"
|-valign="top"
|width="60"| ||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.
|width="60"| ||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.
|-valign="top"
|-valign="top"
|}
|}
Line 69: Line 90:
{|
{|
|-valign="top"
|-valign="top"
|width="60"|'''-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.
|width="60"|'''-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.
|-valign="top"
|-valign="top"
|}
|}
Line 75: Line 96:
{|
{|
|-valign="top"
|-valign="top"
|width="60"|'''-@'''||Client Shell Call (default for Windows). If -@ is omitted, on Unix - shell call is performed on the server.
|width="60"|'''-@'''||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.
|-valign="top"
|-valign="top"
|width="60"| ||(search path not implemented  on client)
|width="60"| ||(search path not implemented  on client)
Line 89: Line 110:
{|
{|
|-valign="top"
|-valign="top"
|width="60"|'''-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.
|width="60"|'''-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
For [[OSX]] 10.6 you need


sys -c | (pipe) (shell commands) to make BR Continue after executing the sys -c (continue),
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.
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
We found this today on one of our Macintosh clients that just updated to OSX 10.6.x


|-valign="top"
|-valign="top"
Line 102: Line 122:
{|
{|
|-valign="top"
|-valign="top"
|width="60"|'''-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.
|width="60"|'''-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.
|-valign="top"
|width="60"| ||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.
|-valign="top"
|-valign="top"
|}
|}
Line 154: Line 172:
: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.
: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]].


<noinclude>
<noinclude>

Latest revision as of 02:04, 26 July 2023

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.