# Qrtz

qrtz is the processing language for hybrixd. It is used to handle routing requests. Each routing request spawns a process that follows qrtz steps to a result, or a failure.

A qrtz command always consists of 4 characters. The parameters are separated by spaces:

`head parameter1 parameter2 ...`

## Recipe

Recipes are JSON files that contain parameters and qrtz methods for asset handling, data source queries or actionable engines. A recipe, depending on what it does, fits in one of three categories: asset, source, or engine.

A source-recipe in principle contains only methods to query read-only data sources.

An engine-recipe contains methods to perform actions based on incoming data, business logic and often interfaces with other programming languages.

An asset-recipe contains methods to query value-related ledger or cryptocurrency API's. It returns path options to the hybrixd routing engine for users or machines to perform actions like, for example, querying the balance of an address.

The categories above make it easier to recognize the functionality of a recipe instantly, and analyze it from the proper context. Source and engine recipes are interpreted identically by the scheduler. However, they are available through separate paths: `/source` and `/engine`. Asset recipes are specifically tailored to be used in the context of decentralized banking and are available through the routing path: `/asset`.

## Data flow

Every step in a qrtz recipe has the potential to alter the data of the process in which the script is running. Process data is available by using the dollar sign `$`. It is also available as input to every new process step. It behaves like a variable in qrtz in that it can be read anywhere. However, the difference with a variable is that the data of the process can be changed by every step of the process. The design consideration is that this coaxes you to design your qrtz script with a concise data flow in mind.

Here is an example of some qrtz steps and the resulting data flow.

    data 'Hello dog!'       // data 'Hello dog!'    - set the data of the process
    drop -4                 // data 'Hello '        - drops the last 4 characters
    repl ' ' ' world!'       // data 'Hello world!'  - replaces the ' '  (space) by ' world!'

## Variables and scopes

`$` the main stream variable it is the output of the previous step. Use `$$` to escape the dollar sign (for example in regular expressions).

`$variable` Retrieve a property from the recipe scope (read only)or process scope if no recipe variable is found.

`$local::variable` Use a local scope (maintained between all processes spawned from the same recipe).

`$otherRecipe::variable` the recipe scope of another recipe (read-only)

`${.property}` To retrieve a sub properties of objects and arrays. For example: if data is `{a:{b:1}}}` then `${.a.b}` will return `1`

## Debugging

qrtz processes flow can be analyzed using the debug tool. These are only available to node operators with root access.

### CLI debugging

Adding the `-d` flag to a cli api call will provide the debug output. This will illustrate the programe flow of all subprocesses and steps.

    $ ./hybrixd /a/dummy/balance/wrongaddress -d
    pid: 1575447893066808
    .      ╻ /asset/dummy/balance/wrongaddress                 "Invalid address wrongaddress"
    .0     ┗┳ call validate/$1                                 "invalid"
    .0.0    ┣┳ /asset/dummy/validate/wrongaddress              "invalid"
    .0.0.0  ┃┗┳ data '$addressRegex'                           "^_dummyaddress_$"
    .0.0.1  ┃ ┣ flow 'undefined' 1 3                           "^_dummyaddress_$"
    .0.0.2  ┃ ┣ rout '/source/wavalidator/$symbol/$1'          null
    .0.0.3  ┃ ┣ done                                           null
    .0.0.4  ┃ ┣ data '$1'                                      "wrongaddress"
    .0.0.5  ┃ ┣ regx '$addressRegex' 1 2                       "wrongaddress"
    .0.0.6  ┃ ┣ done valid                                     null
    .0.0.7  ┃ ┗ done invalid                                   "invalid"
    .1      ┣ flow valid 2 1                                   "invalid"
    .2      ┣ fail "Invalid address $1"                        "Invalid address wrongaddress"
    .3      ┣ data '$1'                                        null
    .4      ┣ flow _dummyaddress_ 2 1                          null
    .5      ┣ stop 1,'Error: invalid address!'                 null
    .6      ┣ pass '10000.00000000'                            null
    .7      ┣ form                                             null
    .8      ┣ done                                             null

`
- $variables
- @labels
- Process steps that contain errors.
- Process steps that have not been executed.
`

### Using the Browser debug interface

An interactive debug interface is available through:

http://localhost:1111/proc/debug

This interface is similar to the cli interface but includes live updated progress views.

## Shell

qrtz can be ran as a shell and interactive mode.

`./qrtz` Start qrtz in interactive mode

`cat data ./qrtz -i` or `./qrtz < cat data` Pipe data to interactive mode

`qrtz script.qrtz $1 $2` or `./qrtz -s script.qrtz $1 $2` Execute script with command parameters 1,2

`qrtz $1 $2 < cat script.qrtz` or `cat script.qrtz | qrtz $1 $2` Execute script provided trough pipe with command parameters 1,2

### Script Example

Create a file `script.qrtz` with the following content:

    data "hello $1"
    done

Then use the following to execute:

`./qrtz script.qrtz "world"`

This results in:

`hello world`

By adding a "shebang" the file can be made into a qrtz executable:

    #!/$QRTZ_HOME/qrtz
    data "hello $1"
    done

Then use the following to execute:

`./script.qrtz "world"`

### Interactive Shell Example

    $ ./qrtz
    > data "hello world"
    hello world
    > quit
    $

Pass command line parameters:

    $ ./qrtz universe
    > data "hello $1"
    hello universe
    > quit
    $

## Reference