# system() function

The system() function provides an interface to a number of system
 variables, depending on the requested numeric argument.

## Syntax

```
system(num.exp,{pib})
```

## Parameter(s)

| num.exp | An expression evaluating to a system function code, as listed in the following table of system function codes. |
| --- | --- |

The system function checks on the status of the system function
 specified. The following table lists the system function codes accepted by the
 system function and the significance of the returned values.

 If *num.exp* evaluates to a number not listed in the table, 0 is
 assumed.

| 0 | Context-oriented status information. After a tape-handling error, system(0) returns: |
| --- | --- |
| 1 | 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 (refer to note) |
| 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 could be overwritten by the next statement being run. As such, it should be tested/saved immediately after the statement that set the value. After a readu, readvu, matreadu or filelock statement that contains a locked clause, system(0) returns the port number that has the item locked. The system(0) parameter returns the remote error code if an error occurs during a read or a write. Refer to 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 previous system(0) values. For more mvBase-related information, go to the Additional mvBase SYSTEM(0) information section. | |

| 1 | Returns a 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 when output is sent to the terminal. |
| --- | --- |
| 2 | Returns the current output device page width, as defined by the TCL term command. Note: The update processor decrements the output page width by 1 when used internally and the TCL command prompt uses the update processor. Therefore, getting this value for a line sitting at TCL will show one less than if you are running a BASIC program. |
| 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. Returns 0 if the stack is off. |
| 11 | Checks for an externally-generated active list. For D3: Returns 0 if there is no active list. Returns 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 command to determine if any items were selected. |
| 12 | Returns the system time in milliseconds. |
| 13 | D3: Forces an rqm (terminates timeslice) and returns a 1. Deactivates the process in the scheduling queue until its next turn. |
| mvBase: Returns the number of characters waiting in the user’s type-ahead buffer. | |
| 14 | D3: Returns the number of bytes in the type-ahead input buffer of the current process. Warning: A tight CPU loop condition might occur with inappropriate use of system(14) as a control element. |
| mvBase: Returns the number of characters waiting in the active type-ahead buffer. | |
| 15 | D3: Returns the TCL command options that are in effect.Note: TCL command options are set independently. When system(15) returns options, they are returned in alphabetical order. Thus, run bp myprog (xam would return AMX. This means that numeric options do not make sense within this scheme and are therefore not returned in any discernible manner. For example, using this function where the options are (f2000, would return 02f. We recommend instead using tclread to extract numeric options. |
| mvBase: Returns options used to invoke execution of the current program in the form: options^n^m where: ^ is an attribute mark (CHAR(254)) options are the letter options used n is the first number specified m is the second number specified | |
| 16 | D3: Returns the current process level (push-level). |
| mvBase: Not applicable | |
| 17 | D3: Returns the message numbers (item-IDs) returned by the previous execute statement, separated by attribute marks. |
| mvBase: Not applicable | |
| 18 | D3: Returns the number of ports on the system. |
| mvBase: Returns the user’s process number. | |
| 19 | D3: 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: There is nothing to prevent duplicate values if the system time is changed, such as when Daylight Saving Time is rolled back. |
| mvBase: Returns the account name on which the user is logged in, taken from the SYSTEM Dictionary. | |
| 20 | D3: Returns the most recent spooler entry number generated by the current process. |
| mvBase: Not applicable | |
| 21 | D3: Returns today’s date, in internal format, with a sequential numeric suffix. |
| mvBase: Returns the current process privilege level. | |
| 22 | D3: Returns the port number of the current process. |
| mvBase: Returns the current SP-ASSIGN options, forms queue, and number of copies (separated by attribute marks). | |
| 23 | D3: Returns the current process privilege level. |
| mvBase: Returns the system serial number (if supported). | |
| 24 | D3: Returns 1 if the current process is a phantom. Returns 0 if the current process is not a phantom. |
| mvBase: Returns the maximum frame number on the system. | |
| 25 | D3: Checks for an active secondary list. Returns the number of items in the secondary list. Returns 0 if no secondary list is active. |
| mvBase: Returns the total number of frames in the overflow table. | |
| 26 | D3: Returns 1 if capturing on is in effect. Returns 0 if capturing on is not in effect. |
| mvBase: Returns the number of linked frames in the overflow table. | |
| 27 | D3: Returns 1 if TCL case-sensitivity is in effect for the current process. Returns 0 if TCL case-sensitivity is not in effect for the current process. |
| mvBase: Returns the number of lines configured. | |
| 28 | D3: Returns 1 if the current FlashBASIC or BASIC program is data case-sensitive. Returns 0 if the current FlashBASIC or BASIC program is not data case-sensitive 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 flag from the current process is passed between levels. |
| mvBase: Returns 1 if this is a Phantom process. Returns 0 if this is not a Phantom process. | |
| 29 | D3: Returns 0 if D3-format is in effect (port.num, user-ID, account name). |
| mvBase: Returns the process number of the SAVE process. Returns 0 if there is no complete SAVE currently active. | |
| 30 | D3: Provided for compatibility purposes only. Use system(0) instead to return the pib number. |
| mvBase: Always returns 0. | |
| 31 | D3: Returns the current spooler form queue number most recently assigned with an sp-assign. |
| mvBase: Returns Null. | |
| 32 | D3: Returns the data frame size for the system. |
| mvBase: Returns Status bits from last tape command (8-digit binary number): ```
WRITE PROT:EOT:BOT:EOF:PARITY:NO DATA:NO MEDIA:READY
``` | |
| 33 | D3: Returns the name of the FlashBASIC or BASIC program that called the subroutine. |
| mvBase: Returns 0 if the BREAK key is enabled. Returns 1 if the BREAK key is disabled from BASIC. Returns 2 if the BREAK key is disabled from TCL. Returns 3 if the BREAK key is disabled from both BASIC and TCL. | |
| 34 | D3: Currently not supported and should not be used. |
| mvBase: Returns 0 if RETURN will abort. Returns 1 if RETURN will satisfy a CALL. Returns 2 if RETURN will satisfy a GOSUB. | |
| 35 | D3: Returns the total number of physical ports on the system, excluding phantom ports. Only applicable to the current process. |
| mvBase: Returns the current program line number. | |
| 36 | D3: Returns a nonzero if running a FlashBASIC program. Returns 0 if not running a FlashBASIC program |
| mvBase: Returns the name of the calling program if it is in a subroutine. | |
| 37 | D3: 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: 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 following numbers are valid return codes: |
| 00 | No interrupt has occurred. |
| 03 | Another process sent a message to the current line. |
| 10 | The BREAK key was used. |
| 12 | Escape level push. |
| 13 | Another process executed the Terminal Control Language tcl command on the current line. |
| Other values are undefined and are not reliable. 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. This allows the program to detect that interrupt in real time. This feature has several applications, as shown in the examples. | |
| mvBase: Returns 0 if not in a PROC. Returns 1 if in a PROC. | |
| 38 | D3: 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. | |
| mvBase: Always returns 0. | |
| 39 | D3: Returns a nonzero (usually 1) if the spelling checker is enabled. Returns 0 if the spelling checker is not enabled. |
| mvBase: Returns 1 if HEADING/FOOTING is currently active | |
| 40 | D3: Returns the current tape reel number. Returns -1 if not attached. Only applicable to the current process. |
| mvBase: Returns the name of the program that is currently executing. | |
| 41 | D3: Returns the UNIX errno variable. |
| mvBase: Returns the file system’s base frame. | |
| 42 | D3: Returns error code in decimal. |
| mvBase: Returns the first workspace frame for process zero. | |
| 43 | D3: Returns 0 for an error. |
| mvBase: Returns the first extended workspace frame for process zero. | |
| 44 | D3: Not applicable; returns 0. |
| mvBase: Returns the size of each extended workspace (in frames). | |
| 45 | D3: Returns the name of the currently executing program or subroutine. |
| mvBase: Always returns 0. | |
| 48 | D3: Not applicable. |
| mvBase: Returns the name of the network node. | |
| 50 | D3: Not applicable. |
| mvBase: Returns the version number of this copy of the operating system. | |
| 55 | D3: Not applicable. |
| mvBase: Returns the number of execute levels that can be pushed by this program. | |
| 57 | D3: Not applicable. |
| mvBase: Returns the console process#. Returns -1 is none active. | |
| 58 | D3: Not applicable. |
| mvBase: Returns the foreign language code for this process (E = English). | |
| 59 | Returns 2 when running as an mvBase program. Returns 3 when running as a D3 program. |
| 60 | D3: Not applicable; returns 0. |
| mvBase: Returns the idle time in seconds of the specified process. The syntax is SYSTEM(60, ), where is the target process number. | |
| 100 | D3: 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. |
| mvBase: Not applicable. | |
| 101 | D3: Not applicable. |
| mvBase: Returns the line number of the line linked to the current process. Returns -1 if no line is linked. Note: Tandem will not have any effect. | |
| 102 | D3: Not applicable. |
| mvBase: Returns the current open Spooler print file numbers, in the form: n1^n2^n3^ ... where ^ is an attribute mark (CHAR(254)) and: | |
| n1 | Spooler entry number for print file 0. |
| n2 | Spooler entry number for print file 1. |
| n3 | Spooler entry number for print file 2. |
| and so on. A null entry number (determined by two adjacent attribute marks) signifies that the corresponding print file is available for the current program. | |
| 103 | D3: Not applicable. |
| mvBase: Returns the current Execution level. | |
| 116 | D3: Not applicable. |
| mvBase: Returns 1 if the program was invoked by a Proc. Returns 0 if the program was not invoked by a Proc. | |
| 117 | D3: Not applicable. |
| mvBase: Returns the current system privilege level. Returns 0 if SYS0 (no privileges). Returns 1 if SYS1. Returns 2 if SYS2. Returns 3 if SYS3. | |
| 120 | D3: Not applicable. D3 does not distinguish between cataloged and non-cataloged programs. |
| mvBase: Returns 1 if the current program is cataloged. Returns 0 if the current program is not cataloged. | |
| 121 | Returns the current sp-assign options, in the form: options ^f^c where ^ is an attribute mark (CHAR(254)) and: |
| options | Spooler options currently set. |
| f | Current form queue number. |
| c | Current number of copies set. |
| 126 | D3: Not applicable. |
| mvBase: Returns the system identification number. The output comes from config item in messages. | |

 Note:
 Arguments 4, 5, and 6 can be used only 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.

## Additional mvBase SYSTEM(0) information

The following error codes apply to the READT,
 WRITET, WEOF, and REWIND
 statements:

- 4: Indicates the validity of SYSTEM(0) if the statement was successful.

- 6: Indicates the validity of SYSTEM(0) if the statement was unsuccessful and the ELSE clause was executed.

| | READT | WRITET | WEOF | REWIND |
| --- | --- | --- | --- | --- |
| 0 | 4 | | | |
| 1 | 6 | 6 | 6 | 6 |
| 2 | 6 | | | |
| 3 | | 4 | | |
| 4 | | 4 | | |
| 10 | 4 | | | |
| 11 | | 4 | | |
| 12 | | 4 | | |

- After a LOCKED clause in a READU has been executed, SYSTEM(0) returns the number of the port that has the item locked.

- If the ELSE clause of a LOCK statement is taken, SYSTEM(0) returns the number of the port that has the lock set.

- After a ICONV(date,D) type of conversion, SYSTEM(0) returns: 0 if the conversion worked.

- 1 if the date being converted was invalid.

- After opening a file, SYSTEM(0) returns: 1 if the file is a DF file; 2 if the file is access protected.

- -1 if the file is update protected and is not able to be updated.

- 0 if the file is able to be updated.

- After attempting a READ type statement (except when the LOCKED clause of a READU/MATREADU is active), SYSTEM(0) returns: -1 if the file is update protected.

- 0 if the file is able to be updated.

If the item the user is attempting to read is a binary item that cannot be
 processed using BASIC, the ELSE clause is taken and SYSTEM(0) is set to 10 to
 distinguish this case.

 After failing a CONNECT and taking the ELSE clause, SYSTEM(0) indicates the reason for
 failure:

| -2 | Indicates the port was logged on. |
| --- | --- |
| -3 | Indicates the user was already connected to a different line. |
| -4 | Indicates an invalid line number was specified. |

 Note: A value of 0 or higher is the line number of the port currently connected to the
 line, preventing the user from connecting.

 After failing a WAKEUP and taking the ELSE clause, SYSTEM(0)
 indicates the reason for failure:
| -1 | Indicates the process is already active. |
| --- | --- |
| -2 | Indicates the process is locked. |
| -3 | Indicates the process is not logged on. |
| -4 | Indicates an invalid line number was specified. |
| -5 | Indicates the process is in the system debugger. |

- After a PRINT statement, SYSTEM(0) returns: 0, unless headings or footings are active and the user just entered a character at the end of a page.

- In the previous case, SYSTEM(0) returns the ASCII value of the character entered.In particular, if the user entered the Ctrl+X character, SYSTEM(0) returns 24. If the user pressed Enter, SYSTEM(0) returns 13.

- After a SLEEP statement, SYSTEM(0) returns: -1 if the sleep terminated normally.

- The number of the port that woke up the process.

- If an INPUT statement is terminated by the user entering a control character (Ctrl+CHARS TERMINATE), SYSTEM(0) contains the decimal value of the control character typed.

- If data is entered to an INPUT@ statement with trailing spaces, the spaces are removed and SYSTEM(0) returns a value of 32 to indicate the fact.

- In the ELSE clause of an INPUT statement, SYSTEM(0) returns: -1 if the input timed out.

- The number of the port that woke up the process.

 After a BLOCK or UNBLOCK command, SYSTEM(0)
 returns these values:
| 0 | Indicates the command worked. |
| --- | --- |
| 1 | Indicates a bad line exists within the structure. |
| 2 | Indicates a comma is missing within the structure. |
| 3 | Indicates a bad binary field (more than 6 bytes long) exists. |

 After an ATTACH or DETACH statement, SYSTEM(0)
 returns these values:
| 0 | Indicates the command worked. |
| --- | --- |
| 1 | Indicates an invalid tape type was specified. |
| 2 | Indicates the system does not have the device/unit specified configured. |
| 3 | Indicates the tape unit was not attached, and therefore could not be detached. |
| 4 | Indicates that the tape device/unit is currently being used by someone else, and therefore cannot be attached. |

## Example(s)

**Using system(37)**

 **Example 1**

 When performing an execute command of a UNIX shell command, the UNIX
 command aborts if it gets a break signal (the normal action in UNIX). The following code
 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
```

 **Example 2**

 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.

 **Example 3**

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

 **Example 4**

 The system(37) function also increases the capabilities of D3 in the
 area of inter-process communications. For example, a batch job can poll
 system(37) repeatedly. 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 than 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 it&#39;s cheap and has no side effects.
 *
 * Note that the msg does not work with phantoms, but the "tcl" command does.
```

 **Example 5: 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
```

 **Example 6: 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](https://d3codex.com/pickbasic-flashbasic/percent-gethostid-function/)
- [%putenv() function](https://d3codex.com/pickbasic-flashbasic/percent-putenv-function/)
- [Active list](https://d3codex.com/definitions/active-list/)
- [BASIC functions](https://d3codex.com/pickbasic-flashbasic/basic-functions/)
- [casing statement](https://d3codex.com/pickbasic-flashbasic/casing-statement/)
- [execute statement (UNIX)](https://d3codex.com/pickbasic-flashbasic/execute-statement-unix/)
- [footing statement](https://d3codex.com/pickbasic-flashbasic/footing-statement/)
- [heading statement](https://d3codex.com/pickbasic-flashbasic/heading-statement/)
- [Locking scheme](https://d3codex.com/definitions/locking-scheme/)
- [matread statement](https://d3codex.com/pickbasic-flashbasic/matread-statement/)
- [onerr clause](https://d3codex.com/pickbasic-flashbasic/onerr-clause/)
- [page statement](https://d3codex.com/pickbasic-flashbasic/page-statement/)
- [Port number](https://d3codex.com/definitions/port-number/)
- [readnext statement](https://d3codex.com/pickbasic-flashbasic/readnext-statement/)
- [readt statement](https://d3codex.com/pickbasic-flashbasic/readt-statement/)
- [readtx statement](https://d3codex.com/pickbasic-flashbasic/readtx-statement/)
- [readv statement](https://d3codex.com/pickbasic-flashbasic/readv-statement/)
- [rewind statement](https://d3codex.com/pickbasic-flashbasic/rewind-statement/)
- [Statements and functions](https://d3codex.com/pickbasic-flashbasic/statements-and-functions/)
- [status() function](https://d3codex.com/pickbasic-flashbasic/status-function/)
- [str() function](https://d3codex.com/pickbasic-flashbasic/str-function/)
- [term command](https://d3codex.com/tcl/term-command/)
- [u713c user exit](https://d3codex.com/proc/u713c-user-exit/)
- [ue070 user exit](https://d3codex.com/proc/ue070-user-exit/)
- [User exits](https://d3codex.com/definitions/user-exits/)
- [weof statement](https://d3codex.com/pickbasic-flashbasic/weof-statement/)
- [who command](https://d3codex.com/tcl/who-command/)
- [writet statement](https://d3codex.com/pickbasic-flashbasic/writet-statement/)

---
Source: https://d3codex.com/pickbasic-flashbasic/system-function/ - part of the D3Codex reference.