# Runtime

The functions for working with a virtual machine during script execution are described here.

* [error( int id, str text, anytype pars... )](#error-int-id-str-text-anytype-pars)
* [ErrID( error err ) int](#errid-error-err-int)
* [ErrText( error err ) str](#errtext-error-err-str)
* [ErrTrace( error err ) arr.trace](#errtrace-error-err-arr-trace)
* [exit( int code )](#exit-int-code)
* [Progress( int id inc )](#progress-int-id-inc)
* [ProgressEnd( int id )](#progressend-int-id)
* [ProgressStart( int total ptype, str src dest ) int](#progressstart-int-total-ptype-str-src-dest-int)
* [Trace() arr.trace](#trace-arr-trace)

## Types

### trace

The *trace* type is used to store information about the called function and has the following fields:

* **str Path** - filename
* **str Entry** - current function
* **str Func** - called function
* **int Line** - the line in the source code
* **int Pos** - the position in the line where the function was called

## Functions

### error(int id, str text, anytype pars...)

The *error* function throws a custom runtime error.

* *id* - the identifier of the error,
* *text* - the text of the error,
* *pars* - optional parameters. If they are specified, then *text* must contain an appropriate template

  as in [Format](https://gentee.github.io/stdlib/string#formatstr-s-anytype-args-str) function.

```go
    error(10, `Error message %{ 10 }`)
    error(10, `Error message %d`, 10)
```

### ErrID(error err) int

The *ErrID* function returns the identifier of the *err* error. This function can be used inside **try-catch** statement for error handling.

```go
run {
  try {
    .....
    error(101, `oooops`)
  }
  catch err {
    if ErrID(err) == 101 {
      recover
    } elif ErrID(err) < 100 {
      retry
    }
  }
}
```

### ErrText(error err) str

The *ErrText* function returns the text of the *err* error. This function can be used inside **try-catch** statement for error handling.

### ErrTrace(error err) arr.trace

The *ErrTrace* function returns the stack of called functions at the moment when the *err* error occurs. This function can be used inside **try-catch** statement for error handling.

### exit(int code)

The *exit* function terminates the script. The function can be called in any thread. The script returns the value of *code*.

```go
func ok(int par) int {
  if par == 0 : exit(0)
  return 3 * par
}
run int {
  int sum
  for i in 10..-10 {
    sum += ok(i)
  }
  return sum
}
```

### Progress( int id inc )

The *Progress* function increases the process counter by the value of parameter *inc*. *id* is the progress bar identifier returned by the *ProgressStart* function. The *Progress* function calls Go function *ProgressFunc* which must be defined in the settings when the script starts.

```go
  int total = 200
  int prog = ProgressStart(total, 100, `counter`, ``)
  for i in 1...5 {
    Progress(prog, 40)
  }
  ProgressEnd(prog)
```

### ProgressEnd( int id )

The *ProgressEnd* function removes the process counter with the *id* identifier.

### ProgressStart( int total ptype, str src dest ) int

The *ProgressStart* function creates a process counter and returns its identifier. *total* is the maximum counter value. *ptype* - counter type, can be any number. *src* is the name of the source. *dest* is the name of the target. The functions for working with the progress bar do not display anything, they call the *ProgressFunc* function, which should be defined in [settings](https://docs.gentee.org/golang/reference) when running the script. In the *ProgressFunc* function you can display the state of the process in a way that is convenient for you. After you have finished working with this counter you must call *ProgressEnd* to delete it.

### Trace() arr.trace

The *Trace* function returns a stack of called functions.