basic.system Function/BASIC Program

basic.system

Command basic.system Function/BASIC Program
Applicable release versions: AP, AP 6.2, R83
Category BASIC Program (486)
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.
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 AP/Unix implementations, system(0) returns the value of "errno" after a C function call. On 6.2 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 1 if the system printer is "on", meaning that a "printer on" statement has been issued or that the program was activated with a (p) option. Otherwise, a 0 (zero) is returned, meaning that output is being directed to the terminal.

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.

5 Returns the current page number.

6 Returns the current line number (Not the "port" number -- the actual print line number).

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 AP, 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 (Pick/BASIC) "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 terminal type-ahead input buffer.

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

16 Returns the current process 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 Pick/BASIC program is data case-sensitive, or 0, if not. The first time a Pick/BASIC program is entered, the Pick/BASIC case flag is set to the current process' case flag. Any subsequent "casing" statement modifies the Pick/BASIC 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 "AP-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 Pick/BASIC 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). (AP 6.0 and higher only).

37 Custom Interrupt Handling in Pick/BASIC. A generalized method is provided by which Pick/BASIC 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 Pick/BASIC, the internal value is ALWAYS set, even if the application is not in Pick/BASIC. 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 AP 6.1 and later.

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

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

41 Returns the Unix Errno variable. (AP releases 6.2.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 AP/Unix implementations, the format returned by system(100) is as follows:

AP/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.
Syntax system(num.expression)
Options
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 Pick/BASIC 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 Pick/BASIC 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
Purpose
Related basic.statements
basic.execute
basic.page
basic.str
basic.%close.apdos
basic.%read.apdos
basic.%write.apdos
basic.matread
basic.onerr
basic.readt
basic.readtl
basic.readv
basic.readtx
basic.readnext
basic.writet
basic.%open.apdos
basic.rewind
basic.weof
tcl.term
tcl.who
basic.casing
basic.execute.unix
active.list
port.number
ue.e070
ue.713c
basic.functions
tcl.config.options
basic.footing
basic.%gethostid
basic.heading
locking.scheme
basic.%putenv
up.input-conversion.fdi
user.exits.introduction
basic.status