# dbr.folios
**dbr.folios.dkl**

Una parte importante en las aplicaciones de gestión es el control de número consecutivos que identifican documentos, por lo tanto, es útil contar con un mecanismo estandarizado para asignar y controlar esos folios.

* ```cdocumentos``` Es una enumeración de los tipos de documentos. P.E. Factura, Contrato, Etc.
* ```blockdocumentos``` Asocia un prefijo (serie) y otras características a una secuencia consecutiva configurable que se relaciona con otras tablas (que representan documentos) y permite generar referencias (cadenas) de identificación
* ```foliosdocumentos``` Es un historial de todos los números (folios) usados que aprovecha las ventajas de los índices del motor de bases de datos para prevenir duplicidades.

### Variables globales
* ```@max_autocode_attemps``` Número de intentos para encontrar un folio disponible.

### id_block
Devuelve la clave primaria correspondiente al block cuya serie y tipo de documento se indican.

```
dbr.folios.id_block::&db,doctype,serie
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `doctype` - Valor referente al tipo de documento.
* `serie` - Valor correspondiente a la serie.

##### Valor de retorno
El valor correspondiente a la clave primaria especificada.

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

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

program
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.folios.dkl"

    ref db = dbr.open("mydb@myappgroup")
    doctype = 6 // Clave primaria de un tipo de documento en la tabla 'cdocumentos'
    block = dbr.folios.id_block(db,doctype,"FA")
}
```


### get_new
Obtiene el siguiente folio para el block indicado

```
dbr.folios.get_new::&db,idblock
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `idblock` - Valor referente al tipo de documento.

##### Valor de retorno
El valor correspondiente al siguiente folio.

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

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

program
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.folios.dkl"

    ref db = dbr.open("mydb@myappgroup")
    block = // ...
    folio = dbr.folios.get_new(db,block)
}
```


### set_new
Establece el folio y retorna su valor si tiene éxito, en caso contrario devuelve cero, debe de estar dentro de una transacción.

```
dbr.folios.set_new::&db,idblock,folio,intentos
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `idblock` - Valor referente al tipo de documento.
* `folio` - Valor referente al folio.
* `intentos` - Valor referente al número de intentos.

##### Valor de retorno
El valor correspondiente al folio, si falla su valor será 0.

##### Excepciones
- Excepciones de bases de datos.
- Se requiere iniciar una transacción de bases de datos.

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

program
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.folios.dkl"

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

    //Establecer el folio indicado o hasta 3 números posteriores si el especificado ya se hubiera usado
    folio=dbr.folios.set_new(db,block,folio,3)
}
```


Consideraciones:

* La función ```dbr.folios.get_new``` devuelve el siguiente folio disponible, pero no puede garantizar que esté disponible cuando se intente consumir ya que otro usuario podría consumirlo (sí, incluso en fracciones de segundo).
* La función ```dbr.folios.set_new``` permite indicar la cantidad máxima de veces (su cuarto parámetro) que se intentará consumir un folio consecutivo al indicado previendo que el solicitado hubiese sido consumido por otro usuario, si indica 1 solo se podrá consumir el que se indique.
* La función ```dbr.folios.set_new``` debe llamarse dentro del contexto de una transacción de bases de datos para asegurar la integridad de los 

## info

```
dbr.folios.info::&db,pk_block, folio
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `idblock` - Valor referente al tipo de documento.
* `folio` - Valor referente al folio.

##### Valor de retorno
Objeto con los siguientes campos(foliosdocumentos), null si no encuentra ningún folio de acuerdo a los parámetros idblock , folio:
```
{
    "sys_pk" : ""
    "sys_guid" : ""
    "cancelado" : ""
    "fecha" : ""
    "folio" : ""
    "block" : ""
}
```

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

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

program
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.folios.dkl"

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

    ref datos_folio=dbr.folios.infor(db,block,folio)
}
```

### autocode.info
Obtiene la información mínima de un auto código.

```
dbr.autocode.info::cad
```

##### Parámetros
* `cad` - Es el valor de una variable que se desee usar para el auto código.

##### Valor de retorno
Objeto con los siguientes campos:
```
{
    "prefix":" Prefijo que tiene el formato(cad)",
    "positions":" Posición que tiene el formato(cad)"
}
```

##### Excepciones
Excepciones del interprete(Devkron).

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

program
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.folios.dkl"

    cad = "0000"
    ref info_code= dbr.autocode.info(cad)
}
```


### autocode.new
Genera la sucesión del auto código.

```
dbr.folios.autocode.new::&db,table,field,&config
```

##### Parámetros
* `db` - Referencia a una conexión de bases de datos.
* `table` - Es el nombre de la tabla que se va manipular.
* `field` - Es el nombre del campo donde se insertará el auto código.
* `config` - Es el valor configurado para el código.

##### Valor de retorno
Un valor para el código que será consecutivo al anterior.

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

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

program
{
    #include "functions.dkh"
    #include "dbr.dkh"
    #include "dbr.folios.dkl"

    config = dbr.autocode.info("0000")
    new_code = dbr.autocode.new(db,table,field,config)
}
```