# batch.v12

**batch.v12.dkl**

Ofrece funciones para crear trabajos en específico y grupos de trabajos, así como también gestión y monitoreo de trabajos.

Facilita controlar y compartir la información de procesos que se ejecutan desatendidos a petición de programas o usuarios.

### Requisitos para utilizar BATCH V12
Para utilizar  BATCH v12 asegúrate de tener instalado el paquete BATCH en tu entorno, esto es fundamental para acceder a todas las funcionalidades y características que ofrece batch v12.

### Uso de BATCH V12

* Incluir la librería batch.v12.dkl:
	En el lugar donde desees utilizar BATCH V12, asegúrate de importar la librería bacth.v12.dkl. Esto te permitirá acceder a todas las funciones y métodos disponibles.

## Funciones disponibles en batch.v12.dkl

### batch.openDB
Crea una referencia hacia la base de datos de acuerdo a la variable global `@batchDB`.

```
batch.local.batch.openDB::
```

##### Valor de retorno
Una referencia de una base de datos.

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

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

program "Ejemplo"
{
    ref database = batch.openDB()
}
```



### batch.loadContextByToken
Devuelve datos específicos de acuerdo al token del trabajo.

```
batch.local.batch.loadContextByToken::@db,token
```

##### Parámetros
* `db` - Es una referencia a la base de datos en uso.
* `token` - Representa el sys_guid de la tabla job. Este valor es crucial para identificar y gestionar el trabajo específico.

##### Valor de retorno
Datos de retorno relevante sobre el trabajo en curso. Aquí están los detalles:
```
@batch_context
{
    credentials: Un objeto que almacena las credenciales necesarias para acceder al grupo de trabajos. Incluye
    {
        "group":"grupo de trabajos",
        "apikey":"clave de api"
    },
    "group": El nombre del grupo de trabajos.
    "apikey": La clave de API necesaria para autenticarse.
    params: Un objeto que contiene los parámetros de entrada para el trabajo. Pueden variar según el contexto y los requisitos específicos
    {
    },
    job: Un objeto que describe el trabajo en sí
    {
        "group_id": El sys_guid del grupo de trabajos.
        "group_name": El nombre del grupo de trabajos.
        "program": El nombre del programa que se ejecutará.
        "token": El token único asignado al trabajo.
        "created": La marca de tiempo del servidor cuando se creó el trabajo.
        "timeout": El tiempo de vigencia del trabajo.
        "progress_type": La forma en que se reporta el progreso (por ejemplo, mediante iteraciones).
        "steps": La cantidad de iteraciones si progress_type es igual a 2.
        "owner": El ID del usuario propietario del trabajo.
        "start_date": La fecha y hora de inicio del trabajo.
        "end_date": La fecha y hora del final del rango de tiempo si el trabajo ya ha terminado.
        "status": El estado actual del trabajo.
    }
	result: Aquí deberás asignar el resultado específico del trabajo una vez que se complete. Puede ser cualquier dato relevante generado por el proceso.
}
```

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

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

program "Ejemplo"
{
    #include "dbr.dkh"
    
    ref db = dbr.open("mydb@myappgroup")

    ref context = batch.loadContextByToken(db,token_del_trabajo)
}
```



### batch.create
Crea un nuevo trabajo en BATCH.

```
batch.local.batch.create::&db,&data
```

##### Parámetros
* `db` - Es una referencia a la base de datos en uso.
* `data` - Un objeto que contiene los datos que se insertarán en el nuevo trabajo.

##### Valor de retorno
Todos los datos del nuevo trabajo creado, estos pueden incluir información relevante sobre el trabajo, como su identificador, estado, fecha de creación y otros detalles específicos.

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

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

program "Ejemplo"
{
    #include "dbr.dkh"
    
    ref db = dbr.open("mydb@myappgroup")

    new data
    {
        // datos correspondiente al trabajo
    }

    ref datos_nuevos = batch.create(db,data)
}
```

<span style="color:red; font-weight:bold">Nota importante</span>

Si el programa indicado existe en la ubicación correspondiente, batch.create se encargará de ejecutarlo y de reportar su proceso. Asegúrate de verificar la existencia y ubicación del programa antes de ejecutar la función.



### batch.filter_jobs
Devuelve los trabajos que coincidan con un filtro dado.

```
batch.local.batch.filter_jobs::&db,&parameters
```

##### Parámetros
* `db` - Es una referencia a la base de datos en uso.
* `parameters` - Un objeto que contiene los parámetros con los que se filtrarán los trabajos, pueden ser los siguientes:
    * `owner` - Dueño del trabajo
    * `start_date` - Fecha de inicio
    * `end_date` - Fecha fin
    * `status` - Estado del trabajo
    * `program` - Programa del trabajo
    * `limit` - Si se omite se asume como límite 100

##### Valor de retorno
Todos los trabajos filtrados por los parámetros dados.

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

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

program "Ejemplo"
{
    #include "dbr.dkh"
    
    ref db = dbr.open("mydb@myappgroup")

    new parameters
    {
        @"program":fecturar.dkl
        @"limit":20
    }

    ref trabajos = batch.filter_jobs(db,parameters)
}
```



### batch.update
Actualiza un trabajo en BATCH.

```
batch.local.batch.update::&db,&data
```

##### Parámetros
* `db` - Es una referencia a la base de datos en uso.
* `data` - Es un objeto que contiene los datos a actualizar, incluyendo el token (sys_guid job).
Solo se pueden modificar los siguientes campos:
    * `jstatus`
    * `percentage`
    * `progress_type`

##### Valor de retorno
Los datos del trabajo especificado.

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

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

program "Ejemplo"
{
    #include "dbr.dkh"
    
    ref db = dbr.open("mydb@myappgroup")

    new data
    {
        // campos que seran actualizados
    }

    ref trabajo = batch.update(db,data)
}
```

##### Nota
Un trabajo puede actualizarse considerando los siguientes puntos:
* No se puede poner en pausa si ya ha concluido o ha sido cancelado.
* Se considera terminado con errores si excede su tiempo de vida.
* No es posible cancelar un trabajo que ya ha finalizado.



### batch.start
Ejecuta el programa batch.run que es encargado de ejecutar el trabajo especificado.

```
batch.local.batch.start::&context
```

##### Parámetros
* `context` - Es un objeto que contiene datos relacionados con el trabajo. La estructura de este objeto es similar a la que devuelve la función batch.loadContextByToken.

##### Valor de retorno
El resultado en forma de cadena, de acuerdo con el tiempo que tarda en finalizar el programa batch.run, así como con la variable global `@wait_program`.
Es importante considerar estos elementos al utilizar la función.

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

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

program "Ejemplo"
{
    #include "dbr.dkh"
    
    ref db = dbr.open("mydb@myappgroup")

    ref context = batch.loadContextByToken(db,token_del_trabajo)
    res = batch.start(context)
}
```



### batch.registerJobsGroup
Registra un nuevo grupo de trabajo.

```
batch.local.batch.registerJobsGroup::&db,&data
```

##### Parámetros
* `db` - Es una referencia a la base de datos en uso.
* `data` - Es un objeto que contiene los datos a insertar en la tabla correspondiente.

##### Valor de retorno
Los datos del nuevo grupo agregado. Si el grupo ya existe, devuelve sus datos según el campo name.

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


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

program "Ejemplo"
{
    #include "dbr.dkh"
    
    ref db = dbr.open("mydb@myappgroup")

    new data
    {
        @"name": "minuevogrupodetrabajo"
        @"apikey":"Digestión MD5 de la contraseña del grupo de trabajo"
    }

    ref nuevo_grupo = batch.registerJobsGroup(db,data)
}
```



### batch.removeJobsGroup
Elimina un grupo de trabajo de acuerdo al parámetro name.

```
batch.local.batch.removeJobsGroup::&db,name
```

##### Parámetros
* `db` - Es una referencia a la base de datos en uso.
* `name` - Es el nombre del grupo de trabajo.

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

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

##### Ejemplo
```
do batch.removeJobsGroup(database,"minuevogrupodetrabajo")
```



### batch.listJobsGroup
Devuelve todos los grupos de trabajo.

```
batch.local.batch.listJobsGroup::&db
```

##### Parámetros
* `db` - Es una referencia a la base de datos en uso.

##### Valor de retorno
Una lista con todos los grupos de trabajo existentes.

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

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

program "Ejemplo"
{
    #include "dbr.dkh"
    
    ref db = dbr.open("mydb@myappgroup")

    ref lista_grupos_de_trabajos = batch.listJobsGroup(db)
}
```



### batch.addTask
Crea un archivo en una carpeta especificada.

```
batch.local.batch.addTask::groupidOrname,progname,dklcode
```

##### Parámetros
* `groupidOrname` - Es el nombre de la carpeta donde se creará el archivo.
* `progname` - Es el nombre del archivo a crear.
* `dklcode` - Es el contenido del archivo a crear.

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

##### Excepciones
Ninguna

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

program "Ejemplo"
{
    do batch.addTask("test1", "nombrearchivo.dkl", contenido_dklcode)
}
```



### batch.updateTask
Actualiza un archivo de una carpeta especificada.

```
batch.local.batch.updateTask::groupidOrname,progname,dklcode
```

##### Parámetros
* `groupidOrname` - Es el nombre de la carpeta donde se actualizará el archivo.
* `progname` - Es el nombre del archivo a editar.
* `dklcode` - Es el contenido del archivo a editar.

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

##### Excepciones
Ninguna

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

program "Ejemplo"
{
    do batch.updateTask("test1", "nombrearchivo.dkl", contenido_dklcode)
}
```



### batch.removeTask
Elimina un archivo de una carpeta especificada.

```
batch.local.batch.removeTask::groupidOrname,progname
```

##### Parámetros
* `groupidOrname` - Es el nombre de la carpeta donde se eliminará el archivo.
* `progname` - Es el nombre del archivo a eliminar.

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

##### Excepciones
Ninguna

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

program "Ejemplo"
{
    do batch.removeTask("test1", "nombrearchivo.dkl")
}
```



### batch.listTask
Devuelve todos los archivos que se encuentren dentro de una carpeta especificada.

```
batch.local.batch.listTask::groupidOrname
```

##### Parámetros
* `groupidOrname` - Es el nombre de la carpeta donde se obtendrán los archivos.

##### Valor de retorno
Una lista con todos los archivos existentes.

##### Excepciones
Ninguna

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

program "Ejemplo"
{
    ref list = batch.listTask("test1")
}
```



### Ejemplo de cómo utilizar algunas funciones

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

program "Ejemplo"
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"
    #include "batch.v12.dkl"
	
    ref db = dbr.open("midb@miappgroup")
	
    // Variables globales de batch
    ref @batchDB = db
	
    new data
    {
        @"name": "minuevogrupodetrabajo"
        @"apikey": "827ccb0eea8a706c4c34a16891f84e7b"
    }

    ref nuevo_grupo = batch.registerJobsGroup(db,data)
	
    new params
    {
        @"cantidad": 1000
    }

    new nuevo_trabajo
    {
        @"jp_ref": @@(nuevo_grupo,"#sys_pk") //sys_pk grupo de trabajo
        @"program": "test_insert.dkl"
        @"jstatus": 0 //solicitado
        @"progress_type": 1
        @"params*": params
    }

    @wait_program = @false // No esperar a que el programa termine
    ref trabajo_creado = batch.create(db,nuevo_trabajo) // Se encargará de crear el grupo y verificar si el programa indicado existe, si es asi, lanzará el programa
	
    // Volver a lanzar el programa
	
    ref context = batch.loadContextByToken(db,@@(trabajo_creado,"sys_guid"))
	
    @wait_program = @true // Esperar a que el programa termine
    res = batch.start(context)
	
    do print(res)	
}
```



## v12.cron.dkl

Es un programa que se encarga de ejecutar todas las tareas programadas según su configuración.
En otras palabras, actúa como un planificador de tareas que automatiza la ejecución de acciones en momentos específicos o de acuerdo a intervalos predefinidos.
Su función es asegurar que las tareas se realicen de manera puntual y eficiente.

## Uso de v12.cron.dkl

El programa v12.cron.dkl se ejecuta mediante línea de comandos. 
Esto significa que debes abrir una terminal o consola en tu sistema y escribir los comandos necesarios para iniciar las tareas programadas.
Si tienes alguna tarea específica que deseas automatizar, 
asegúrate de proporcionar los comandos adecuados en la línea de comandos para que v12.cron.dkl realice las acciones según lo previsto.

##### Comando
```
v12.cron.dkl "db=qname" "tag (opcional)"
```

<span style="color:red; font-weight:bold">Nota importante</span>

Una vez que el programa v12.cron.dkl se inicie,  no debes esperar resultados inmediatos, ya que estará en ejecución de manera continua.

Si deseas detenerlo, deberás matar el proceso para que v12.cron.dkl deje de ejecutarse. 
**¡Ten en cuenta esta consideración mientras trabajas con él!**