SYSTEM

SYSTEM

SWAP Index Level TA
Syntax SYSTEM( num.expression )
Category BASIC
Type Function
Description provides an interface to a number of system variables, depending upon the requested numeric argument, as shown below:

0  Context-oriented status information.

After a tape-handling error, system(0) returns:

1  if not attached.
2  null variable.
3  attempt to write null string.
4  (not used).
5  EOT encountered.
6  tape write protected.
7  tape unit not ready.
8  unrecoverable parity error.
9  block transfer error.
10  binary item read (see note below).
11  record truncated.
12  unrecoverable write error.
13  unrecoverable read error.
14  no tape media inserted.
15  tape subsystem not ready.

After a "readu", "readvu" and "matreadu" statement which contains a "locked" clause, system(0) returns the port.number that has the item locked.

Value 10 actually has nothing to do with tape and is relevent to all "read"-type statements. It is set when an "indirect" (or "pointer") item is read.

On D3/Unix implementations, system(0) returns the value of "errno" after a C function call.  On release 7.0  and above, this is no longer supported and system(41) should be used instead.

All statements which allow the "onerr" clause provide a "hook" to system(0). See "onerr" for examples.

1  Returns code number specifying the destination of the output.
0  The output will be sent to the terminal
1  The output will be sent to the system printer. This indicates that a "printer on" statement was issued or that the program was activated with the (P) option.

2  Returns the current output device page width as defined by the "term" command.

3  Returns the current output device page length as defined by the "term" command.

4  Returns the number of lines remaining to print on the current page, based on the current terminal characteristics previously defined with the "term" command. Note: use of the @(row,col) function will not change this value.

5  Returns the current page number. Note: use of the @(row,col) function will not change this value.

6  Returns the current line number (Not the "port" number -- the actual print line number). Note: use of the @(row,col) function will not change this value.

7  Returns the terminal "type" code, as defined by the "term" command.

8  Returns the block size at which the tape was last attached.

9  Returns the current cpu millisecond count.

10  Checks the current stack (ston) condition. Returns 1 (one) if the stack is on, or 0 (zero), if not.

11  Checks for an externally-generated active list.

In R83, it returns "0" if there is no active list, or "1" (one) if an active list exists.

In D3, it returns "0" if there is no active list, or "n" (the actual number of items selected), if an active list exists.

This has nothing to do with the internal (FlashBASIC) "select" statement, which requires a "readnext" to determine if any items were selected. See the "readnext" and "select" statements for additional warnings on using system(11).

12  Returns the system time in milliseconds.

13  Forces an rqm (terminates timeslice) and returns a 1. Deactivates the process in the scheduling queue until its next turn.

14  Returns the number of bytes in the type-ahead input buffer of the current process.

15  Returns the TCL verb option{s} that are in effect.

16  Returns the current process level (push-level).

17  Returns the message numbers (item-ids) returned by the previous "execute" statement, separated by attribute marks.

18  Returns the number of ports on the system.

19  Returns a unique item-id consisting of the current system date in internal format, followed immediately by the current system time in seconds. If more than one item-id is generated in a second, an alpha character is appended to the item-id.

20  Returns the most recent Spooler entry number generated by the current process.

21  Returns today's date in internal format with a sequential numeric suffix.

22  Returns the port.number of the current process.

23  Returns the current process privilege level. (In R83, this returns 1 if the current process has a "sys2" privilege level, otherwise it returns 0 (zero).)

24  Returns 1 if the current process is a phantom. Otherwise it returns 0 (zero).

25  Checks for an active secondary list. Returns the number of items in the secondary list, or 0 (zero) if no secondary list is active.

26  Returns 1 if "capturing on" is in effect. Otherwise, it returns 0 (zero).

27  Returns 1 if TCL case-sensitivity is in effect for the current process. Otherwise, it returns 0 (zero). (see "casing").

28  Returns 1 if the current FlashBASIC program is data case-sensitive, or 0, if not. The first time a FlashBASIC program is entered, the FlashBASIC case flag is set to the current process' case flag. Any subsequent "casing" statement modifies the FlashBASIC flag but not the current process' flag. Only the current process' flag is passed between levels. (see "basic" and "compile" commands).

29  Returns 1 if R83-format 'who' is in effect (port.number, account name, user-id) or 0 (zero) if "D3-format" is in effect (port.number, user-id, account name). See the "who" verb for options. (Note that in R83, there was no user-id.)

30  Returns the port.number of the process which has the item locked. (see "locked").

31  Returns the current Spooler form queue number most recently assigned with an "sp-assign".

32  Returns the data frame size for the system.

33  Returns the name of the FlashBASIC program which called the subroutine.

34  Is currently not supported and should not be used.

35  Returns the total number of physical ports on the system, excluding phantom ports.

36  Returns a non-zero if running a FlashBASIC program, otherwise, it returns a 0 (zero). (release 6.0 and higher only).

37  Custom Interrupt Handling in FlashBASIC. A generalized method is provided by which FlashBASIC applications may handle the break key or any other type of interrupt in a special manner. This function returns the value of an internal location indicating the last interrupt processed and then clears that location. Note that although the only way to poll this value is with the system(37) function in FlashBASIC, the internal value is ALWAYS set, even if the application is not in FlashBASIC. The following numbers are valid return codes:

00  No interrupt has occured
03  Another process sent a message to the current line
10  The break key was hit
12  Escape level push
13  Another process TCL'd the current line

Other values are undefined and should not be relied upon.

The system(37) function has only one limitation in that if a process is waiting at input, the user must type a key before the application can poll the interrupt status. All other operations, including sleep, will complete immediately after a break allowing the program to detect that interrupt in real time. This feature has several applications. See the 'Example' section below.

38  Returns the system identification and options. A string with four attributes as follows is returned:

host ^ chip ^ imp ^ opt

host   : Underlying host operating system (decimal).
chip   : Processor chip code (decimal).
imp    : Implementation code (decimal).
opt    : Option string (one character per option)

The values of each field are defined in the include "dm,bp,includes sysid.inc" which should be included in programs using this function. Available on release 6.1 and later.

39  Returns a non-zero (usually 1) if the spelling checker is enabled, or 0 if it is not. (release 5.2.5 and higher only).

40  Returns the current tape reel number, or -1 if not attached. (release 7.0 and higher only).

41  Returns the Unix Errno variable. (release 7.0 and higher only).

100 Returns the system identification:

system;filename:name;release; version;hardware; date

system : The system name, which may contain spaces.
filename : Configuration file name.
name : Contents of the 'name' statement in the configuration file.
release : The current release level.
version : The current version level.
hardware : The type of hardware.
date : The date of the release.

On D3/Unix implementations, the format returned by system(100) is as follows:

D3/Unix: system; o/s name; filename:name; release; version; hardware; boot monitor version; date

system The system name, which may contain spaces.
o /s name "SCO", "AIX", etc.
filename Configuration file name.
name Contents of the 'name' statement in the configuration file.
release Unix system release.
version Unix system version.
hardware Machine hardware name, or serial number.
boot monitor version The release level of the monitor.
date Boot monitor date.
Options
See Also statements & functions EXECUTE PAGE STR %READ (AP/DOS)   MATREAD ONERR READT READTL READV READTX READNEXT WRITET REWIND WEOF term who CASING EXECUTE (D3/Unix) active list port.number ue070 u713c functions config options FOOTING %GETHOSTID HEADING locking scheme %PUTENV input-conversion user exits STATUS
Example 1)  system(37):

When doing an "execute" of a Unix shell command, the Unix command will simply abort if it gets a break signal (the normal action in Unix). The following code will sense that a break has occured and reexecute the Unix instruction, giving the appearance of a standard Pick break-and-continue capability:

do.unix:
x = system(37); * Clear the interrupt value
execute "!exec find / -name ap - print"
if system(37) = 10 then goto do.unix; * Break - Return, reexecute

Another useful application is for a FlashBASIC program to mimic the behavior of the Update processor's interrupt handling and redraw the screen background if it senses an interrupt. For example:

gosub refresh
open "data"
select
loop
readnext id else exit
read rec from id
name = rec<1>
balance = rec<2>
balance = balance + 50
print @(20,2):name
print @(20,3):balance
if system(37) then gosub refresh; * Screen might be hosed
repeat
stop
refresh:
* Draw the background
print @(-1)
print @(10,1):"Processing Accounts"
print @(10,2):"Name:"
print @(10,3):"Balance:"
return

By using the system(37) in conjunction with the "break off" statement, a FlashBASIC program can implement its own signal handler. For example, assume a user wishes to update many items in a file, but he or she wants this done atomically, i.e. either all the items in the file must be updated or none of the items must be updated. This is a simple form of transaction bracketing and can be implemented on previous releases by simply turning off the break key. However, this method has the disadvantage of not being able to interrupt the process. The system(37) capability provides the ability to offer a "controlled" interrupt allowing the user to continue, or back out of all changes made so far. This routine could be expanded to allow other operations provided it didn't turn the break key on (which would cause the system to catch the break and push a level, allowing the user to type "end"). The example is as follows:

break off
x = system(37);* clear previous signals
max = 2000
dim xx(max)
for i = 1 to max
readu xx(i) from i
writeu "abc" on i
if system(37) = 10 then gosub interrupt; * break key hit
next i
* Release the locks
for i = 1 to max
release i
next i
stop
interrupt:
print "Interrupted"
print "Processed ":i:" items"
print "C)ontinue or Q)uit without modifying file:":
in x
print
x = char(x)
if x = "q" then
* Change the items back to the way they were
max = i
for i = 1 to max
* note that write will release the locks along the way
write xx(i) on i
next i
stop
end
return

Finally, system(37) increases the capabilities of Pick in the area of interprocess communications. For example, a batch job can poll system(37) repeatedly and when it senses an interrupt, it can either simply send a message indicating its progress, or do some other, more complex action by reading a command item from a file. Note that using the system(37) is much more efficient that reading commands and writing status output for every item. An example is as follows:

xx = system(37);* clear status
open "data"
for i = 1 to 100000
* In a real program, there should be more work done in the main loop.
* Otherwise, the system(37) becomes comparatively more expensive.
write "abc" on i
if system(37) then execute "msg !0 Processed ":i:" items."
next i
stop

* "z" the preceeding program and then type the following
* tcl (line#) (user) who
*
* The actual command executed is unimportant.  The who command is a
*   good candidate since its cheap and has no side effects.
*
* Note that the msg does NOT work with phantoms, but the "tcl" command
*   will.
*

2)  system(38):
include dm,bp,includes sysid.inc
imp=system(38)
if imp<sys$host>=sys$unix then
* Running on Unix implementation
n=%open( "myfile, O$RDONLY)
....
end

3)  system(100):

crt system(100)
AP/UNIX: RS6000;AIX;pick0:PROD0;2;3;000047311000;6.0.0.M0;27 May 1992
Warnings Arguments 4,5,6 may only be used in conjunction with the "heading", "footing", and page statements within a FlashBASIC program.  They are invalidated whenever a FlashBASIC program uses an @() function.

R83 implementations only support "system" arguments 1 through 17, and system(100), which returns the R83 release level, version and version date.
Compatibility D3 7.0 AP R83
SWAP Index Level TA