# dbr.events
**dbr.events.dkl**

Implementa eventos síncronos en el backend facilitando que programas desconocidos entre sí, puedan integrarse y realizar un flujo de operaciones secuencial.

## Identificadores y registro

### register
Registra un script asociado a un identificador de disparador de eventos (sender_id)

```
dbr.events.register::&db,sender_id,include_script
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `sender_id` - Identificador desencadenante.
* `include_script` - Ruta del programa controlador.

##### Valor de retorno
Numérico (booleano): `@true` si se realiza la inserción o `@false` si ya existía un registro previo.

##### Excepciones
Excepciones de bases de datos.

##### Caso de uso
Por ejemplo, suponga un paquete ```mis_compras``` que define el ```sender_id```: ```myshopping``` con los ```event_id```: ```on_add```, ```on_update``` y ```on_cancel``` que se producen cuando se agrega, actualiza o cancela una compra.

Por su parte, cada programa que responde a eventos debe registrar uno o más programas (controladores) asociados a un ```sender_id``` conocido y estar preparado para procesar los ```event_id``` que incluye.

El registro de los controladores de eventos puede realizarse en cualquier momento, pero se sugiere realizarlo desde el programa de instalación del paquete que lo implementa.

##### Ejemplo
```
#include "dkli.dkh"
#!
program 
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.events.dkl"

    ref db = dbr.open("mydb@myappgroup")
    sender_id = "Id conocido de un desencadenador"
    event_handler = "mipaquete/evhandler.dkl" // Programa controlador (responde) a los eventos desencadenados por otro programa

    do dbr.events.register(db,sender_id,event_handler)
}
```


### unregister
Elimina el registro de controlador de eventos.

```
dbr.events.unregister::&db,sender_id,include_script
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `sender_id` - Identificador desencadenante.
* `include_script` - Ruta del programa controlador.

##### Valor de retorno
Ninguno (0)

##### Excepciones
Excepciones de bases de datos.

##### Ejemplo
```
#include "dkli.dkh"
#!
program 
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.events.dkl"

    ref db = dbr.open("mydb@myappgroup")
    sender_id = "Id conocido de un desencadenador"
    event_handler = "mipaquete/evhandler.dkl" // Programa controlador (responde) a los eventos desencadenados por otro programa

    do dbr.events.unregister(db,sender_id,event_handler)
}
```


## Disparo de eventos

### fire
Dispara un evento.

```
dbr.events.fire::&db,sender_id,event,&data
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `sender_id` - Identificador desencadenante.
* `event` - Identificador de un evento.
* `data` - Objeto que contiene información inherente al evento.

##### Valor de retorno
Ninguno (0)

##### Excepciones
Excepciones de bases de datos.

##### Ejemplo
```
#include "dkli.dkh"
#!
program 
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.events.dkl"

    ref db = dbr.open("mydb@myappgroup")
    sender_id = "myshopping"
    event_id = "on_add"

    new data
    {
        @"prop1":"Algún dato inherente al evento"
        // ...
    }

    do dbr.events.fire(db,sender_id,event_id,data)
}
```

## Controlador de eventos

Cuando un programa desencadena un evento se realiza la carga de cada uno de los programas controladores registrados y se les pasa información de contexto a través de una variable global denominada ```@event_context``` que tiene los siguientes campos:

* ```event```. Es una cadena con el identificador del evento desencadenado.
* ```database```. Referencia a una conexión de bases de datos.
* ```eventdata```. Es una referencia a un objeto con información relacionada al evento provista por el desencadenador.

En general, la estructura de un controlador de eventos sería así:
```
#include "dkli.dkh"
#!
program "event handler demo"
{
    #include "functions.dkh"
    #include "dbr.dkh"

    event_id = @event_context<"event">
    ref db = @event_context<"&database">
    ref datos = @event_context<"&eventdata">

    switch event_id
    {
        // Recuerde que los identificadores de eventos son definidos por el desencadenador
        case "id_de_evento1" // Identificador de un evento, por ejemplo: on_add
        {
            // ref l = dbr.list(db,"select * from ....",@null) // Ejemplo de uso de la referencia a la base de datos proporcionada (requiere incluir dbr.dkh)
        }
        case "id_evento2" // Identificador de un evento, por ejemplo: on_update
        {
            // ...
        }
    }
}
```