Execution State

abort

Abandons the current execution and returns to the top level. This predicate is normally used in one of the following two cases:

• when some error condition or exception has occurred and carrying on the computation is of no further use.
• when using the debugger (see Chapter 7).

Currently, all exception handling routines terminate with a call to predicate abort/0, so an exception encountered at some break level other than the top level will return the interpreter at the top level.

The user should be aware of the fact that abort/0 does not close any files which may have been opened. If the program under execution is doing file manipulation using see/1 and tell/1, then strange behavior may occur after the program is aborted and restarted, unless the user manually closes the files.

Aborting closes all incomplete tables (those which may not have a complete set of answers). Closed tables are unaffected, even if the tables were created during the aborted computation.

break

Causes the current execution to be suspended at the beginning of the next call. The interpreter then enters break level 1 and is ready to accept input as if it were at top level. If another call to break/0 is encountered, it moves up to break level 2, and so on. While execution is done at break level $n>0$ the prompt changes to $n$: ?-.

To close a break level and resume the suspended execution, the user can type the the atom end_of_file or the end-of-file character applicable on the system (usually CTRL-d on UNIX systems). Predicate break/0 then succeeds (note in the following example that the calls to break/0 do not succeed), and the execution of the interrupted program is resumed. Alternatively, the suspended execution can be abandoned by calling the standard predicate abort/0, which causes a return to the top level.

An example of break/0 's use is the following:

 		 		     | ?- break. 
 


1: ?- break. 
 


2: ?- end_of_file. 
 

 


yes 


1: ?-     

Entering a break closes all incomplete tables (those which may not have a complete set of answers). Closed tables are unaffected, even if the tables were created during the computation for which the break was entered.

halt

Exits the XSB session regardless of the break level. On exiting the system cpu and elapsed time information is displayed.

prompt(+NewPrompt, ?OldPrompt)

Sets the prompt of the top level interpreter to NewPrompt and returns the old prompt in OldPrompt.

An example of prompt/2 's use is the following:

 		 		     | ?- prompt('Yes master > ', P). 

 


P = | ?- ; 

 


no 


Yes master > fail. 

 


no 


Yes master >     

garbage_collection(+Option)

Sets the system so that subsequent heap garbage collecting will be done according to the specified Option. Option may be the atom none indicating that heap garbage collection is turned off; it may be the atom sliding indicating that sliding garbage collection will be done; or it may be the atom copying indicating that the copying garbage collector will be used.

cputime(-CPU_Time)

Returns the CPU_Time at the time of the call in seconds. The difference between results of successive calls to this predicate can measure the time spent in specific predicates.

statistics

Prints on the current output stream:

• Information about allocation of memory (see Section 3.5) containing the
  • global stack (heap) and local (environment) stack
  • trail and choice point stack
  • SLG subgoal space (tablestack)
  • SLG unification stack
  • SLG completion stack
  • the space occupied by subgoal and answer tables (in the form of tries).
• Current use of the above specified memory areas (allocated/in use/free).
• Information about process cpu and clock time.

Additionally, if the emulator is invoked with the '-s' option (see Section 3.5), information is printed out about

• Maximum use of the memory areas.

The '-s' option slows down the emulator by about 10%.

Example:

     | ?- statistics.

     memory (total)        1873737 bytes:     171317 in use,    1702420 free
        permanent space     169801 bytes
        glob/loc space      786432 bytes:       1080 in use,     785352 free
           global                                152 bytes
           local                                 928 bytes
        trail/cp space      786432 bytes:        436 in use,     785996 free
           trail                                 240 bytes
           choice point                          196 bytes
        SLG subgoal space        0 bytes:          0 in use,          0 free
        SLG unific. space    65536 bytes:          0 in use,      65536 free
        SLG completion       65536 bytes:          0 in use,      65536 free
        SLG trie space           0 bytes:          0 in use,          0 free
        (call+ret. trie          0 bytes,   trie hash tables          0 bytes)

        Maximum stack use: global 224, local 1384, trail 240, cp 492
        Maximum stack use: SLG completion 0.  Max level: 0

          0 Trail unwinds,       0 levels

      0.570 sec. cputime,  5.088 sec. elapsetime

shows how the emulator output looks if it is invoked with the '-s' option (without it the Maximum use line is not shown). Information about the allocation size is provided since the sizes can be changed through emulator options (see Section 3.5).

shell(+SystemCall)

Calls the operating system with the atom SystemCall as argument. It succeeds if SystemCall is executed successfully, otherwise it fails. As a notational convenience, the user can supply SystemCall in the form of a list (something currently not possible for shell/2).

For example, the call:

$\vert$ ?- shell('echo $HOME').

will output in the current output stream of XSB the name of the user's home directory; while the call:

$\vert$ ?- File = 'test.c', shell(['cc -c ', File]).

will call the C compiler to compile the file test.c.

Note that in UNIX systems, since shell/1 is executed by forking off a shell process, it cannot be used, for example, to change the working directory of the interpreter. For that reason the standard predicate cd/1 described below should be used.

shell(+SystemCall, -Result)

Calls the operating system with the atom SystemCall as argument and returns the result of the call in Result. In comparison with shell/1 this predicate always succeeds, even if the SystemCall cannot be successfully executed.

ls

Under UNIX, this command lists in the current output stream the files in the system's current directory if it can do so. If so, it succeeds. It is the same as shell('ls -F', 0).

cd(+Dir)

Under UNIX and Windows, this predicate changes the interpreter's working directory to Dir. If the directory specified does not exist or is not a directory, or the user does not have execute permission for that directory, predicate cd/1 simply fails raising no permission error.

Exceptions:

instantiation_error

Dir is not instantiated at the time of call.

type_error

Dir is not an atom.

edit(+Module)

Provided that the environment variable EDITOR has been set, and the system is executing under UNIX, a call to edit(foo) will call the default editor on the file named foo.P. The argument to edit/1, should be instantiated, it can be an absolute or a relative file name, but it should not contain the suffix .P. Users can also set their preferred options of calling the default editor by setting an environment variable named EDITOR_OPTIONS.

Examples of possible uses of predicate edit/1 are:

1. If the environment variables have been set as follows:

   
   	        setenv EDITOR /usr/ucb/vi
   	        setenv EDITOR_OPTIONS -l
   

   a call like:

   
   	        | ?- edit(foo).
   

   will call the vi editor in the mode where left and right parentheses and curly brackets are checked for balance for the file foo.P in the current working directory.
2. If, on the other hand, they have been set as follows:

   
   	        setenv EDITOR /usr/local/bin/emacs
   	        setenv EDITOR_OPTIONS -r
   

   a call like:

   
   	        | ?- edit('~/foo').
   

   will call the emacs editor in reverse video for the file foo.P in user's home directory.