system() function

Syntax

 system(num.exp,{pib})

Parameter(s)

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.

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.

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

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