# dbr.vars

**dbr.vars.dkl**

Ofrece funciones para administrar variables alojadas en la base de datos, 
las variables globales son pares clave/valor disponibles para todos los programas 
(internamente se almacenan en la tabla globalvar en la base de datos).

### set
Establece una variable global

```
dbr.vars.set::&db,varname,value
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `varname` - Es el nombre de la variable.
* `value` - Es el valor de la variable.

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

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

##### Ejemplo

```
#include "dkli.dkh"
#!

program "Ejemplo"
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    namespace "dbr.vars"

    ref db = dbr.open("mydb@myappgroup")
    do set(db,"nombre_variable", "valor_variable")
}
```


### db_id
Obtiene y establece si no se ha establecido previamente, 
un identificador único que puede usarse para comparar dos conexiones 
y determinar si corresponden a la misma base de datos.

```
dbr.vars.db_id::&db
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.

##### Valor de retorno
Un identificador de la base de datos enviada.

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

##### Ejemplo

```
#include "dkli.dkh"
#!

program "Ejemplo"
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    namespace "dbr.vars"

    ref db = dbr.open("mydb@myappgroup")
    do db_id(db)
}
```


### userid
Devuelve una cadena con el id del usuario conectado a la base de datos.

```
dbr.vars.userid::&db
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.

##### Valor de retorno
Cadena con el id del usuario.

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

##### Ejemplo

```
#include "dkli.dkh"
#!

program "Ejemplo"
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    namespace "dbr.vars"

    ref db = dbr.open("mydb@myappgroup")
    do userid(db)
}
```


### getall
Devuelve una referencia a un registro que contiene todas las variables globales.

```
dbr.vars.getall::&db
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.

##### Valor de retorno
Una lista con todas las variables globales.
```
[
    {
        "varname":"Nombre de la variable",
        "varvalue":"Valor de la variable"
    },
    ...
]
```

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

##### Ejemplo

```
#include "dkli.dkh"
#!

program "Ejemplo"
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    namespace "dbr.vars"

    ref db = dbr.open("mydb@myappgroup")
    ref variables = getall(db)
}
```

### getallwhere
Devuelve un array con los registros que contiene todas las variables globales que coinciden con la expresión de filtro dada.

```
dbr.vars.getallwhere::&db,where,&p
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `where` - Es el nombre del campo donde se desea realizar un filtro o condiciones.
* `p` - Son los parámetros que se desean aplicar para el filtro o condición.

##### Valor de retorno
Una lista con las variables globales filtradas.
```
[
    {
        "varname":"Nombre de la variable",
        "varvalue":"Valor de la variable"
    },
    ...
]
```

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

##### Ejemplo

```
#include "dkli.dkh"
#!

program "Ejemplo"
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    namespace "dbr.vars"

    ref db = dbr.open("mydb@myappgroup")
    ref variables = getallwhere(db,"ref_varcat=@categoria",params)
}
```


### get
Devuelve el valor de una variable encontrada por el nombre.

```
dbr.vars.get::&db,varname
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `varname` - Es el identificador del valor de una variable a obtener.

##### Valor de retorno
Devuelve el valor de la variable, si no existe será una cadena vacía.

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

##### Ejemplo

```
#include "dkli.dkh"
#!

program "Ejemplo"
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    namespace "dbr.vars"

    ref db = dbr.open("mydb@myappgroup")
    value = get(db,"FXCA047")
}
```

### getd
Devuelve el valor de una variable con valor predeterminado.

```
dbr.vars.getd::&db,varname,default
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `varname` - Nombre de la variable a obtener.
* `default` - Valor predeterminado de retorno si no existe `varname`.

##### Valor de retorno
Devuelve el valor de la variable, si no existe será un valor predeterminado indicado.

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

##### Ejemplo

```
#include "dkli.dkh"
#!

program "Ejemplo"
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "dbr.vars.dkl"
    namespace "dbr.vars"

    ref db = dbr.open("mydb@myappgroup")
    value = getd(db,"FXCA047","0000")
}
```

### categories.set
Crea el registro de una categoría de variables de configuración.

```
categories.set::&db,id,caption,help,parent
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `id` - Identificador de la categoría.
* `caption` - Es el nombre de la categoría.
* `help` - Información adicional o de ayuda sobre la categoría.
* `parent` - ID de la categoría padre o vacío para establecer que no tiene una categoría padre.

##### Valor de retorno
Sin valor de retorno

##### Excepciones
Excepciones de bases de datos.
Las variables duplicadas son ignoradas.

##### Ejemplo

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

    ref db = dbr.open("mydb@myappgroup")

    // Categoría
    do dbr.vars.categories.set(db,"cat01","Category one","Test category","")
}
```

### define
Crea el registro de una variable de configuración (globalvar)

```
dbr.vars.define::&db,&vardata,catid
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `vardata` - Referencia a un objeto con la información de la notificación a registrarse. Campos:
    - `varname`: (string) Nombre de la variable
    - `vardefault`: (string, opcional) Valor por defecto
    - `varvalue`: (string, opcional) Valor
    - `varcaption`: (string, opcional) Etiqueta de la variable
    - `varhelp`: (string, opcional) Ayuda o información adicional sobre la variable
    - `vartype`: (string, opcional) Tipo de dato: string,integer,decimal,bool,date,datetime,time
    - `varinput`: (object, opcional) Objeto con especificaciones al tipo de control de entrada, [ver definición de control](https://docs.induxsoft.net/es/productos/v12/devops/packs/dbext/var-control-def.md).
    - `userenable`: (bool, opcional) true/false, activo para un usuario especifico, debe estar registrado en la tabla `uservarval`.
* `catid` - ID de la categoría (varcategory) a la que pertenecerá la variable o vacío para no relacionarla a ninguna categoría.

##### Valor de retorno
Sin valor de retorno

##### Excepciones
Excepciones de bases de datos.
Las variables duplicadas son ignoradas

##### Ejemplo

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

    ref db = dbr.open("mydb@myappgroup")

    // Categoría
    do dbr.vars.categories.set(db,"cat01","Category one","Test category","")

    // Variable global
    new vardata
    {
        @"varname": "var01"
        @"vardefault": "12345"
        @"varvalue": "10"
        @"varcaption": "Variable one"
        @"varhelp": "This var is for testing"
        @"vartype": "string"
        member "varinput"
        {
            @"control":"text"
        }
    }
    do dbr.vars.define(db,vardata,"cat01")
}
```

## ImportList
Se encarga de insertar un nuevo registro en la
tabla de la base de datos indicada(tname). 
Asegura la integridad y manejo de errores.

```
dbr.vars.ImportList
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `list` - Lista de datos con las columnas de acuerdo a la tabal(tname).
* `tname` - Nombre de la tabla de base de datos.

##### Valor de retorno
Sin valor de retorno

##### Excepciones
Excepciones de bases de datos.
Las variables duplicadas son ignoradas

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

    ref db = dbr.open("mydb@myappgroup")

    // Variable global
    new vardata
    {
        @"varname": "var01"
        @"vardefault": "12345"
        @"varvalue": "10"
        @"varcaption": "Variable one"
        @"varhelp": "This var is for testing"
        @"vartype": "string"
    }
    ref list=list.create()

    do list.add(list,vardata)

    do dbr.vars.ImportList(db,list,"globalvar")
}
```

## ImportListDkt
Se encarga de insertar un nuevo registro desde archivos con extensión .dkt(tabla de Devrkon) en la
tabla de la base de datos indicada. 
Asegura la integridad y manejo de errores.

```
dbr.vars.ImportListDkt
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `lfiles` - Lista con los nombre de los archivos.
* `dir_path` - directorio en donde se encuentran los archivos .dkt.

##### Valor de retorno
Sin valor de retorno

##### Excepciones
- Excepciones de bases de datos.
- No se encontró el archivo: nombre del archivo.

Las variables duplicadas son ignoradas.

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

    ref db = dbr.open("mydb@myappgroup")

    // lista de archivos
    ref lfiles=from.json('
        [
            "archivo1.dkt",
            "archivo2.dkt",
            "archivo3.dkt"
        ]
    ')

    dir_path="/mi_directorio/archivos_dkt/"

    do dbr.vars.ImportListDkt(db,lfiles,dir_path)
}
```

## ImportPrivs
Importa todos los privilegios específicos definidos en el parámetro `list`. 

```
dbr.vars.ImportPrivs
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `list` - Lista de los permisos.

##### Valor de retorno
Sin valor de retorno

##### Excepciones
Excepciones de bases de datos.
Las variables duplicadas son ignoradas

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

    ref db = dbr.open("mydb@myappgroup")

    // lista de permisos
    ref list=from.json('
        [
            {
                "itemid":"privd001",
                "description":"Ejemplo 1",
                "itemparent":"id del privilegio padre (opcional)"
            }
        ]
    ')

    do dbr.vars.ImportPrivs(db,list)
}
```