system() Function

The system() function provides an interface to a number of system variables, depending upon the requested numeric argument, as shown below:

Syntax

system(num.exp)

Parameter(s)

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

End of tape 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.

The system(0) value is transient and may be overwritten by the next statement being run. As such, it should be tested/saved immediately after the statement which set it.

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

system(0) returns the remote error code if an error occurs during a read or a write. See your UNIX documentation for more information on remote error codes returned by system(0).

Value 10 is not related to tape but is relevant to all read-type statements. It is set when a binary item is read.

All statements that allow the onerr clause are set to one of the above system(0) values.

1

Returns code number specifying the destination of the output.

Returns 1 when output is sent to the system printer. This indicates that a printer on statement was issued or that the program was activated with the p option.

Returns 0 otherwise and output is sent to the terminal.

2

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

3

Returns the current output device page length as defined by the TCL 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 TCL term command.

NOTE—Use of the @(row,col) function does not change this value.

5

Returns the current page number.

NOTE—Use of the @(row,col) function does not change this value.

6

Returns the current line number (Not the port number, but the actual print line number).

NOTE—Use of the @(row,col) function does not change this value.

7

Returns the terminal type code, as defined by the TCL 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 if the stack is on, or 0, if not.

11

Checks for an externally-generated active list.

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 is not related to the internal FlashBASIC or BASIC select statement, which requires a readnext to determine if any items were selected.

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.

WARNING—A tight CPU loop condition may occur with inappropriate use of system(14) as a control element.  

15

Returns the TCL command options 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.

NOTE— 32760 is the maximum number of unique item-IDs returned per second. This limit is not imposed in FlashBASIC.

NOTE— There is nothing to prevent the collision of duplicate values if the system time is changed, such as when Daylight Saving Time is rolled back.

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.

24

Returns 1 if the current process is a phantom. Otherwise it returns 0.

25

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

26

Returns 1 if capturing on is in effect. Otherwise, it returns 0.

27

Returns 1 if TCL case-sensitivity is in effect for the current process. Otherwise, it returns 0.

28

Returns 1 if the current FlashBASIC or BASIC program is data case-sensitive, or 0, if not. The first time a FlashBASIC or BASIC program is entered, the FlashBASIC or BASIC case flag is set to the current process’ case flag. Any subsequent casing statement modifies the FlashBASIC or BASIC flag but not the current process’ flag. Only the current process’ flag is passed between levels.

29

Returns 0 if D3-format is in effect (port.num, user-ID, account name).

30

Provided for compatibility purposes only. Use system(0) instead to return the pib number.

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 or BASIC program that called the subroutine.

34

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 nonzero if running a FlashBASIC program, otherwise, it returns a 0.

37

Custom Interrupt Handling in FlashBASIC or BASIC. A generalized method is provided by which FlashBASIC or BASIC applications can 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 or BASIC, the internal value is always set, even if the application is not in FlashBASIC. The numbers below are valid return codes:

00

No interrupt has occurred.

03

Another process sent a message to the current line.

10

The BREAK key was hit.

12

Escape level push.

13

Another process executed the Terminal Control Language tcl command on 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, complete immediately after a break allowing the program to detect that interrupt in real time. This feature has several applications. See the examples 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.

39

Returns a nonzero (usually 1) if the spelling checker is enabled, or 0 if it is not.

40

Returns the current tape reel number, or -1 if not attached.

41

Returns the UNIX errno variable.

42

Error code in decimal.

43

Returns 0 for an error, 1 if the system status is OK.

45

Returns the name of the currently executing program or subroutine.

100

Returns the system identification.

For UNIX:

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

system

System name, which can contain spaces.

o/s name

AIX, Windows, and so on.

filename

Configuration file name.

name

Contents of the name command in the configuration file.

release

UNIX system release.

version

UNIX system version.

hardware

Machine hardware name, or serial number.

boot monitor version

Release level of the monitor.

date

Boot monitor date.

For Windows:

system;o/s name;vme name;o/s version;o/s release;boot monitor version; date

system

System name, which can contain spaces.

o/s name

AIX, Windows, and so on.

vme name

Contents of the name command in the configuration file.

o/s release

Current release level.

o/s version

Current version level.

boot monitor version

Type of hardware.

date

Date of the release.

 

NOTE

Arguments 4,5,6 can only be used in conjunction with the heading, footing, and page statements within a FlashBASIC or BASIC program. They are invalidated whenever a FlashBASIC or BASIC program uses an @() function.

Example(s)

Using system(37) 

When performing an execute of a UNIX shell command, the UNIX command aborts if it gets a break signal (the normal action in UNIX). The code below determines that a break has occurred and re-executes the UNIX instruction, giving the appearance of a standard D3 break-and-continue capability:

do.unix:

* Clear the interrupt value

x = system(37)

execute "!exec find / -name ap - print"

* Break - return, reexecute

if system(37) = 10 then goto do.unix

Another useful application is for a FlashBASIC or 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 display might be changed

repeat

stop

refresh:

* Draw the background

print @(-1)

print @(10,1):"Processing Accounts"

print @(10,2):"Name:"

print @(10,3):"Balance:"

return

By using system(37) in conjunction with the break off statement, a FlashBASIC or BASIC program can implement its own signal handler. For example, assume a user wants to update many items in a file, but wants this done atomically. Either all the items in the file must be updated or none of the items must be updated. This is a form of transaction bracketing and can be implemented on previous releases by 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 that have been made. This routine could be expanded to allow other operations provided it did not turn the BREAK key on (which causes the system to catch the break and push a level, allowing the user to type end). For example:

break off

* clear previous signals

x = system(37)

max = 2000

dim xx(max)

for i = 1 to max

readu xx(i) from i

writeu "abc" on i

* break key hit

if system(37) = 10 then gosub interrupt

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 releases the locks along the way

write xx(i) on i

next i

stop

end

return

Finally, system(37) increases the capabilities of D3 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 send a message indicating its progress, or perform some other, more complex action by reading a command item from a file. Note that using system(37) is much more efficient that reading statements and writing status output for every item. For example:

* clear status

xx = system(37)

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 preceding program and then type the following

* tcl (line#) (user) who

*

* The actual command executed is unimportant. The who command is a good candidate because its cheap and has no side effects.

*

* Note that the msg does not work with phantoms, but the "tcl" command does.

Using 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

Using system(100) 

crt system(100)

D3UNIX:RS6000;AIX;pick0:prod0;2;3;000047311000;6.0.0.m0;27 May 2001

See Also

%gethostid() Function, %putenv() Function, Active List, casing Statement, execute Statement, footing Statement, BASIC Functions, heading Statement, Locking Scheme, matread Statement, onerr Clause, page Statement, Port Number, readnext Statement, readt Statement, readtx Statement, readv Statement, rewind Statement, Statements and Functions, status() Function, str() Function, term Command, u713c User Exit, ue070 User Exit, User Exits, weof Statement, who Command, writet Statement