# Ejecutar programas de consola Los programas de consola son tareas que se ejecutan una vez y terminan: reportes, importaciones, sincronizaciones, procesos programados con `cron` o el Programador de tareas, instaladores. Esta página explica cómo ejecutarlos con `dkl`, todas sus opciones, cómo recibe el programa sus propios parámetros y qué significan los códigos de salida. ## Sintaxis ```text dkl programa.dkl [opciones] ejecuta un programa (la extensión .dkl se puede omitir) dkl -fastcgi [configuracion.json] servidor FastCGI (vea Servidor FastCGI) dkl -license muestra la licencia instalada dkl -crypto origen [destino] [codificación] [traza] cifra un archivo fuente ``` El primer argumento es la ruta del programa; las opciones van después y todas son opcionales. Sin argumentos, `dkl` muestra una ayuda breve. ```bash dkl /opt/tareas/reporte.dkl -hide-log ``` ```powershell dkl "C:\mis programas\reporte.dkl" -hide-log ``` ## Opciones de ejecución | Opción | Efecto | |---|---| | `-hide-log` | no imprime la bitácora (`Iniciado…`, `ID de ejecución…`, `Terminado…` y la duración) | | `-hide-output` | no imprime en la consola la salida declarativa del programa | | `-ninja` | `-hide-log` y `-hide-output` juntos: no muestra nada en la consola | | `-hide-critical` | oculta también los mensajes críticos de la bitácora | | `-output:archivo` | escribe la salida declarativa en un archivo; `@id` en el nombre se reemplaza por el id de ejecución. En 2.0 acepta rutas absolutas de Windows (`-output:C:\salida\x.html`) | | `-log:archivo` | escribe la bitácora en un archivo (también acepta rutas con `:`) | | `-id:valor` | id de la ejecución; si no se indica, Devkron genera un GUID | | `-encoding:valor` | codificación de los fuentes y de `-output:`: `utf8`, `utf8bom`, `default`, `unicode`, `utf32`, `ascii`, `utf7`, `not-set`. Si no se indica, la de la consola para la pantalla y UTF-8 con BOM para el archivo de salida | | `-parse` | analiza el programa y muestra el árbol XML **sin ejecutar** la parte imperativa; sirve para validar la sintaxis | | `-deps` o `-scandeps` | muestra los archivos que el programa incluye con `#include` (y si se encontraron), sin ejecutar | | `-skip-not-found-includes` | ignora los `#include` de archivos que no existen | | `-skip-all-includes` | ignora todos los `#include` | | `-stepbystep` | ejecución paso a paso para depurar (vea abajo) | | `-debugfile:archivo` | con `-stepbystep`, se detiene solo en las sentencias de ese archivo | | `-culture es-MX` o `-culture:es-MX` | cultura de **presentación** (`format`, `date_str`…); vea [Cultura](/es/devkron/2.0/migracion/cultura.md). Nueva en 2.0 | | `-compile` | compila el programa a código nativo antes de ejecutarlo y lo guarda en la caché. Nueva en 2.0. Vea [Compilación de programas DKL](/es/devkron/2.0/instalacion/compilacion.md) | | `-native-cache-dir:ruta` | carpeta de la caché de compilados. Nueva en 2.0 | | `-tree-output` | salida como árbol (apaga la salida directa; solo para diagnóstico). Nueva en 2.0 | | `-tree-cache` | caché del árbol analizado en memoria (útil si el proceso ejecuta el mismo archivo varias veces con `runscript` o `include`). Nueva en 2.0 | | `-tree-cache-dir:ruta` | caché persistente del árbol en esa carpeta. Nueva en 2.0 | | `-repeat N`, `-parallel M`, `-mutate …` | **solo para pruebas del motor**: ejecuta el programa N veces en el mismo proceso, con M hilos | Las opciones con valor se escriben pegadas con `:` (`-output:salida.xml`); si el valor tiene espacios, entrecomille la opción completa: `"-output:C:\mis salidas\x.xml"`. ### Ejemplos Ver solo la salida del programa: ```bash dkl hola.dkl -hide-log ``` ```text Hola mundo ``` Guardar la salida XML en un archivo con el id de ejecución en el nombre, sin mostrar nada: ```bash dkl personas.dkl -ninja -id:corrida01 "-output:/var/reportes/salida-@id.xml" ``` Genera `/var/reportes/salida-corrida01.xml`. Validar la sintaxis sin ejecutar: ```bash dkl programa.dkl -parse -hide-log ``` Con un error de sintaxis muestra, por ejemplo: ```text {110} Error de sintaxis [programa.dkl] [110] - No se encontró el símbolo de cierre de la expresión o bloque de definición[Ln= 4] ``` En 2.0 `-parse` termina con código de salida **1** si encontró errores, así que se puede usar en scripts de validación. Recuerde que el número de línea de los errores puede estar desfasado: revise también las líneas cercanas. Ver de qué archivos depende un programa: ```bash dkl inc2.dkl -deps -hide-log ``` ```text dkli.dkh /opt/devkron/dkli.dkh Founded (1) inc2.dkl functions.dkh /opt/devkron/functions.dkh Founded (1) inc2.dkl falta.dkh falta.dkh Not found (1) inc2.dkl ``` ## Parámetros propios del programa El programa recibe la línea de comandos completa (su propio nombre, las opciones de `dkl` y cualquier argumento suyo) en `_get(@_run_settings, "Arguments")`. Lo más práctico es `commandline(separador)` de `functions.dkh`, que la convierte en un registro: ```dkl #include "dkli.dkh" #! program "argumentos" { #include "functions.dkh" #include "serialize.dkh" ref args = commandline(":") do print(to.json(args)) cliente = field.dstr(args, "-cliente", "(sin cliente)") do print("Cliente: " + cliente) } ``` ```bash dkl args.dkl -hide-log -cliente:C-001 -culture es-MX ``` ```text {"args.dkl":"","-hide-log":"","-cliente":"C-001"} Cliente: C-001 ``` `-culture`, `-compile`, `-native-cache-dir:`, `-tree-output`, `-tree-cache` y `-tree-cache-dir:` los consume `dkl` y no llegan al programa. Use nombres propios que no choquen con las opciones de la tabla (por ejemplo `-cliente:`, `-fecha:`). `@_run_settings` es un objeto, no un registro: `@@(@_run_settings, "&Arguments")` devuelve una referencia nula. Si necesita otro separador o leer la lista directamente, use `_get` y `from.args`, que es lo que hace `commandline`: ```dkl ref args = from.args(_get(@_run_settings, "&Arguments"), "=") archivo = @@(args, "$archivo") ``` Con `dkl prog.dkl archivo=a.xml modo=prueba`, `args` queda como `{"prog.dkl":"","archivo":"a.xml","modo":"prueba"}` (más las opciones de `dkl` que no consume, como `-hide-log`). ## Códigos de salida | Código | Cuándo | |---|---| | `0` | el programa terminó bien, también si un error se capturó con `exception` | | `1` | error no manejado, error de sintaxis, archivo inexistente o argumento inválido | En 1.x `dkl` terminaba siempre con 0. Con 2.0, `cron`, los scripts y el Programador de tareas ya pueden detectar fallas: ```bash #!/bin/sh cd /opt/tareas || exit 1 DEVKRON_CULTURE=es-MX /opt/devkron/dkl importar.dkl -hide-log >> /var/log/importar.log 2>&1 || echo "falló la importación" | mail -s "Error" soporte@ejemplo.com ``` ## Tareas programadas - Ejecute la tarea **desde la carpeta de sus datos** o use rutas absolutas: las rutas relativas del programa, `connections.xml` y `devkron.license` se buscan en el directorio de trabajo. - Fije la cultura de presentación, porque el entorno de `cron` no suele tener `LANG`: `DEVKRON_CULTURE=es-MX` o `-culture es-MX`. - La tarea corre con el usuario de `cron`; si usa la compilación nativa (`-compile`), ese usuario tiene su propia caché y su llave (no comparte compilados con el servicio FastCGI; no es un error). Ejemplo de `crontab` que corre un reporte todos los días a las 6:15: ```text 15 6 * * * cd /opt/tareas && DEVKRON_CULTURE=es-MX /opt/devkron/dkl reporte.dkl -hide-log >> /var/log/reporte.log 2>&1 ``` ## Depuración paso a paso Con `-stepbystep`, `dkl` se detiene antes de cada sentencia, muestra el archivo y la línea, y espera un comando: ```bash dkl reporte.dkl -hide-log -stepbystep -debugfile:reporte.dkl ``` ```text reporte.dkl Siguiente línea:8::dkli-ref Introduzca comando de depuración (*-Tabla de objetos,@-Variables globales, !-Variables locales, para continuar presione ENTER) ``` | Comando | Muestra | |---|---| | `*` | la tabla de objetos | | `@` | las variables globales | | `!` | las variables locales | | ENTER | continúa a la siguiente sentencia | Sin `-debugfile:` también se detiene dentro de las bibliotecas incluidas (`functions.dkh`…), lo que rara vez es útil. ## Cifrar el código fuente `dkl -crypto` genera una versión cifrada de un archivo fuente para distribuirlo sin su código legible. Se ejecuta igual que el original: ```bash dkl -crypto hola.dkl dkl hola.dkl.crypto -hide-log ``` ```text Archivo cifrado: hola.dkl.crypto Hola mundo ``` | Argumento | Uso | |---|---| | `origen` | archivo a cifrar | | `destino` | archivo de salida; si se omite, el mismo nombre con `.crypto` | | `codificación` | codificación del archivo de origen (`utf8` por omisión, `unicode`…) | | `traza` | texto de hasta 32 caracteres que se guarda dentro del archivo cifrado (por ejemplo, para identificar a qué cliente se entregó) | El cifrado de 2.0 es compatible con el de 1.x. Tómelo como una **ofuscación**: impide leer el código a simple vista, pero no protege secretos; no ponga contraseñas en el código fuente. ## Licencia y consola - `dkl -license` muestra la licencia del archivo `devkron.license` del **directorio actual**; vea [Licencia](/es/devkron/2.0/instalacion/licencia.md). - Los programas de consola no requieren licencia. La licencia solo limita el número de instancias simultáneas de `dkl`. ## Errores típicos | Síntoma | Causa | Solución | |---|---|---| | `No se pudo encontrar el archivo: x.dkl` | ruta incorrecta | ruta completa o ejecutar desde la carpeta del programa | | `{9999} … No se puede encontrar el archivo falta.dkh` | un `#include` no existe en la carpeta del programa, en `#path` ni junto a `dkl` | corrija la ruta o copie la biblioteca junto a `dkl` | | `Too many Instances, check license.` | ya hay otra instancia de `dkl` y la licencia no permite más | espere a que termine la otra o revise las instancias de la licencia | | la salida tiene acentos extraños en la consola de Windows | la consola usa otra página de códigos | `-encoding:utf8` o `chcp 65001` antes de ejecutar | | un número sale con coma decimal en un archivo de datos | `format` usa la cultura de presentación | para datos use `str(x)`; `format` solo para lo que lee una persona ([Cultura](/es/devkron/2.0/migracion/cultura.md)) |