Fichas

Conjunto de comandos de proceso que permite interactuar con una ficha de una tabla y sus campos. Este tipo de comandos solamente estarán accesibles en aquellas líneas de proceso cuyo origen sea una ficha de una tabla.

¿Ha cambiado la ficha?

Comando de instrucción del grupo Ficha y campos que comprueba si ha cambiado o no cualquier campo de una ficha de una tabla.

Origen de la instrucción: ficha de la tabla en curso.

Destino del subproceso: ninguno.

Parámetros

Identificador de variable local booleana de retorno de ok

variable local de tipo booleano que recogerá si el registro ha cambiado (1) o no (0).

Funcionalidad

Este comando devuelve en una variable local booleana si la ficha actual ha cambiado (1) o no (0).

Comentarios

La variable local booleana de retorno podrá ser tanto una ya existente como una nueva.

Este comando compara el contenido que tiene el registro en memoria con contenido que tenía al abrir la ficha.

Si se trata de un alta de ficha, detectará que ha habido cambios si algún campo no está vacío.

Si se trata de una modificación, la comparación se hará con el valor que tenga esa ficha en disco.

Si se desea utilizar este comando en un evento de tabla debería ser usando en el evento previo y no en el posterior. El motivo es que en el evento posterior la ficha ya ha sido guardada en disco, por lo que el valor de la misma en memoria y el valor guardado en disco ya será el mismo.

Ejemplo

Verificamos si ha cambiado algún campo de la ficha en curso mostrando un mensaje durante 3 segundos.

¿Ha cambiado la ficha? ( CAMBIA )
If ( CAMBIA )
    Mensaje ( "El registro ha cambiado", Información, 3, "Aviso" )

Alta de ficha

Comando de instrucción del grupo Ficha y campos que crea un nuevo registro en una tabla.

Origen de la instrucción: cualquiera.

Destino del subproceso: la ficha creada.

Parámetros

Manejador de ficha

Manejador de la ficha a crear.

Funcionalidad

Este comando de instrucción añade una nueva ficha a una tabla. El contenido de la misma ha de ser establecido previamente con el comando de instrucción Crear nueva ficha en memoria o el comando Crear copia de ficha en memoria, que es donde se habrá declarado el manejador usado como parámetro. Este comando de instrucción genera un subproceso cuyo origen será la ficha generada.

Comentarios

Requerimiento fundamental es que la ficha a grabar haya sido inicializada previamente dentro del mismo proceso mediante el comando Crear nueva ficha en memoria o el comando Crear copia de ficha en memoria, que es donde se declara el manejador solicitado en el primer parámetro.

El subproceso de este comando es ejecutado una vez la ficha haya sido guardada en disco. Si por el motivo que sea la ficha no ha podido ser grabada, el subproceso no será ejecutado.

Ejemplo

Damos de alta un sector de actividad utilizando la instrucción Crear nueva ficha en memoria, asignando el valor al campo NAME de la tabla SEC_ACT_M (Sectores de actividad) dando de alta la ficha con la instrucción Alta de ficha. Posteriormente nos muestra en número del ID asignado a la ficha que hemos creado.

Crear nueva ficha en memoria ( alta.SEC_ACT_M, SEC_ACT_M@ejemplo_dat )
    Modificar campo ( NAME, "Alta de sector ejemplo" )
Alta de ficha ( alta.SEC_ACT_M )
    Mensaje ( "Se ha creado el sector de actividad con el ID: " + #ID, Información, ,  )

Crear copia de ficha en memoria

Comando de instrucción del grupo Ficha y campos que crea una copia en memoria de una ficha de la tabla en curso.

Origen de la instrucción: ficha de la tabla en curso.

Destino del subproceso: ninguno.

Parámetros

Manejador de ficha

Identificador o manejador que queremos dar a la ficha para poder referenciarla a lo largo del proceso.

Funcionalidad

Crea una copia en memoria de una ficha de la tabla en curso. Esta copia será local al proceso.

Comentarios

Las modificaciones que se realicen en la ficha copiada en memoria afectarán solamente a ésta, no a la ficha de origen.

Podremos procesar y/o modificar la copia generada en memoria mediante el comando de instrucción Procesar ficha en memoria, en el que la ficha será identificada con el manejador declarado en su parámetro.

Podremos crear una nueva ficha a partir de la copia creada en memoria mediante el comando de Alta de ficha, al igual que en el caso anterior, en este comando la ficha será referenciada con el manejador declarado en su parámetro.

A tener en cuenta sobre los campos de tipo objeto

Cuando declaramos un campo de tipo objeto, el objeto no es guardado en la tabla, sino en un fichero aparte llamado contenedor. En la tabla lo que se guarda es un enlace a ese objeto del contenedor.

Por lo tanto, si creamos una copia de ficha en memoria sin tocar los objetos, lo que haremos será copiar esas referencias al objeto, no el objeto en sí.

Por lo tanto, los dos registros (el original y el duplicado) apuntarán al mismo objeto.

Esto quiere decir que si en el registro 1 modifico la imagen, por ejemplo, también se modificará en el registro 2, pues ambos están apuntando al mismo objeto del contenedor.

Realmente lo recomendable sería hacer lo siguiente:

1) Si no se desean duplicar los objetos: antes de dar de alta la ficha, procesarla y limpiar los campos objeto:

Crear copia de ficha Procesar ficha en memoria Limpiar campo objeto Alta de ficha

2) Si se desean duplicar los objetos:

Entonces lo recomendable es usar el comando Tubo de ficha en lugar de hacerlo mediante el uso de este comando.

Ejemplo

Creamos un nuevo pedido partiendo del pedido en curso modificando la fecha del nuevo pedido con la fecha actual del sistema.

Crear copia de ficha en memoria ( copia_PED_G )
Procesar ficha en memoria ( copia_PED_G )
    Modificar campo ( FCH, currentDate() )
Alta de ficha ( copia_PED_G )
    Mensaje ( "Se ha creado el pedido ID: " + #ID, Información, ,  )

Crear nueva ficha en memoria

Comando de instrucción del grupo Ficha y campos que crea en memoria una ficha de una tabla concreta.

Origen de la instrucción: cualquiera.

Destino del subproceso: ficha de la tabla indicada en sus parámetros.

Parámetros

Manejador de ficha

Identificador o manejador que queremos dar a la ficha para poder referenciarla a lo largo del proceso.

Identificador de tabla

Identificador de la tabla en la que se desea crear la ficha en memoria.

Funcionalidad

Crea en memoria una ficha de la tabla especificada en los parámetros. Esta copia será local al proceso. Este comando genera un subproceso cuyo origen será la ficha creada. En él podremos editar su contenido.

Comentarios

Podremos procesar la ficha generada en memoria a lo largo del proceso mediante el comando de instrucción Procesar ficha en memoria, en el que la ficha será identificada con el manejador declarado en su parámetro.

Esta ficha será local al proceso, por lo que será destruida al finalizar el mismo.

Si queremos crear una ficha en la misma tabla a partir de la ficha generada en memoria usaremos el comando de Alta de ficha, al igual que en el caso anterior, en este comando la ficha será referenciada con el manejador declarado en su parámetro.

Si queremos programar un bucle para dar de alta varias fichas en la misma tabla, debemos tener en cuenta que el comando crear nueva ficha en memoria debe ser usado dentro del bucle y no fuera.

Ejemplo de bucle incorrecto:

Ejemplo de bucle correcto:

Si el comando lo usamos fuera del bucle y la tabla tiene definidas actualizaciones a otras tablas, si ejecutamos el proceso en tercer plano (en el servidor) sucede que cuando procesamos la ficha en memoria siempre estemos procesando el mismo registro en memoria y eso genera los efectos de que sólo dispare actualizaciones el primer registro generado, ya que el resto asume que son modificaciones del mismo.

Cuando lo ejecutamos en primer o 2º plano (en local) funciona correctamente, porque realmente la ficha se ha de construir en el servidor para cada alta.

Por lo tanto, para asegurarnos el correcto funcionamiento del comando en todos los planos de ejecución, siempre lo incluiremos dentro del bucle.

Los contenidos iniciales de los campos de la ficha se calcularán en el plano donde se ejecute este comando de instrucción de proceso.

Ejemplo

Damos de alta un sector de actividad utilizando la instrucción Crear nueva ficha en memoria, asignando el valor al campo NAME de la tabla SEC_ACT_M (Sectores de actividad) dando de alta la ficha con la instrucción Alta de ficha.

Crear nueva ficha en memoria ( alta.SEC_ACT_M, SEC_ACT_M@ejemplo_dat )
    Modificar campo ( NAME, "Alta de sector ejemplo" )
Alta de ficha ( alta.SEC_ACT_M )

Crear o modificar ficha desde JSON

Comando de instruccíon de proceso que nos permite, o bien modificar, o bien dar de alta una nueva ficha en una tabla a partir de un json.

Origen de la instrucción: ninguno.

Destino del subproceso: ficha de la tabla de destino.

Parámetros

Fórmula de dato

Expresión fórmula con el json a importar, directamente como texto literal o variable local alfabética, variable global alfabética o campo alfabético u objeto texto.

Tipo de operación

Tipo de operación a realizar en la tabla de destino. Los valores posibles son:

  • Alta o modificación: si el registro no existe lo dará de alta en la tabla, si existe, lo modificará.

  • Solo alta: dará de alta un nuevo registro. Sl el JSON incluye el campo ID del registro lo ignorará y creará un nuevo registro con el ID que le corresponda. Así que es una buena alternativa al tubo de ficha.

  • Solo modificación: si el registro existe, lo modifica, si no, no hará nada.

Tabla

En este parámetro seleccionaremos la tabla de destino.

Identificador de índice:

Este parámetro solo es necesario si en la operación permitida está incluida la modificación, en cuyo caso especificaremos un índice de clave única que permita localizar el registro.

Identificador de variable local alfabética de retorno de ok (opcional)

Identificador de una variable local de tipo booleano que devolverá 1 si todo está correcto y 0 si hay errores.

Identificador de variable local booleana de retorno de ok (opcional)

Variable booleana con la que se devuelve un 1 si se ha podido realizar el alta o modificación, o un 0 si no se ha podido realizar el alta o modificación.

Identificador de variable local alfabética de retorno de mensaje de error (opcional)

Identificador de una variable local de tipo alfabético en la que se retornará un JSON con el código de error y el mensaje del error con los errores encontrados. Si no hay errores devolverá el JSON siguiente: {'velneo_errorCode':0,'velneo_errorString':''}. Ver enum de errores de JSON/CSV.

Funcionalidad

A partir de un JSON, permite o bien crear un nuevo registro de una tabla, o bien modificar un registro existente.

Comentarios

Este comando de instrucción de proceso tiene el fin de facilitarnos el traspaso de información, de registros de tablas, entre aplicaciones. Nos permite duplicar o actualizar información entre aplicaciones o dentro de la propia aplicación, de forma sencilla, con el fin de dotar a nuestras aplicaciones de un sistema sencillo de exportación e importación de información usando JSON.

El comando no es case sensitive. Se hace un tratamiento de las claves que convierte a Identificador cualquier clave, permitiendo aceptar como claves tanto identificadores case insensitive como valores con símbolos no permitidos (como espacios) en los nombres.

En el JSON los campos no están ordenados, así que debemos tenerlo en cuenta para cuando existen contenidos iniciales .

Para ese caso, se recomienda o bien quitar las claves y valores correspondientes del JSON antes de emplearlo, o bien modificar posteriormente los campos de los que dependen contenidos iniciales usando las funciones JSON para obtener los valores.

Los objetos no permiten repetición de claves (debido a que su posición realmente es irrelevante) .

Una estructura de objeto se representa con un par de llaves {} que contendrán cero o más pares de nombre/valor (o miembros). Un nombre es una cadena. Un signo de dos puntos : va detrás de cada nombre, separando el nombre del valor. Una coma , separa un valor del nombre siguiente. Los nombres dentro de un objeto DEBEN ser únicos.

Los posible errores son:

  • No se puede dar de alta el registro porque ya existe en alguno de los índices de clave única. (si es solo alta pero ya existe en alguno de los índices de clave única).

  • No es posible modificar el registro porque no se encuentra (Si el tipo de operación es solo modificación y no se encuentra el registro) .

  • El campo %1 que está en el índice %2 no existe en el JSON.

  • El campo destino %1 no existe en la tabla.

  • El valor %1 a asignar al campo %2 no es válido.

Ejemplo

Un manejador de evento que duplica la ficha que estamos editando en un formulario:

Rem ( Generamos el JSON con la ficha de origen )
Generar JSON desde ficha ( , SZ_JSON, BOK, ERROR )
If ( BOK )
    Rem ( Generamos una nueva ficha a partir del JSON generado )
    Crear o modificar ficha desde JSON ( SZ_JSON, Solo alta, ARTICULOS@miapp, ID, BOK, ERROR_ALTA )
        Libre
    If ( !BOK )
        Mensaje ( "No se ha podido crear la nueva ficha. Error: " + ERROR_ALTA, Información, ,  )
Else
    Mensaje ( "No se ha podido generar el JSON de origen. Error: " + ERROR, Información, ,  )

Proceso que da de alta o modifica un artículo a partir de un JSON que hemos copiado previamente en el portapapeles:

Rem ( Leemos el contenido del portapapeles )
Portapapeles: Get texto ( SZ_JSON,  )
Rem ( Creamos/modificamos ficha con los datos del JSON )
Crear o modificar ficha desde JSON ( SZ_JSON, Alta o modificación, ARTICULOS@Json pruebas, ID, BOK, ERROR )
    Libre
If ( !BOK )
    Mensaje ( "No se ha poddo completar la operación. Error: " + ERROR, Información, ,  )

Generar JSON desde ficha

Comando de instrucción de proceso que convierte un registro de una tabla en un objeto JSON en base al estándar RFC-4627 debidamente, permitiendo definir si se incluyen todos o algunos campos.

Origen de la instrucción: ficha de la tabla en curso.

Destino del subproceso: ninguno.

Parámetros

Fórmula de dato

Expresión fórmula con los campos a incluir, debemos especificar cada campo con la función de campo getID, separando cada campo por una coma. Ejemplo:

"" + #ID:getID() + "," + #NAME:getID()

Si lo dejamos vacío, generará el json con todos los campos.

Identificador de variable local alfabética de retorno

Identificador de una variable local de tipo alfabético donde se retornará el JSON.

Identificador de variable local alfabética de retorno de ok (opcional)

Identificador de una variable local de tipo booleano que devolverá 1 si todo está correcto y 0 si hay errores.

Identificador de variable local alfabética de retorno de mensaje de error (opcional)

Identificador de una variable local de tipo alfabético en la que se retornará la descripción de los errores encontrados. Si no hay errores quedará vacía.

Funcionalidad

Convierte un registro de una tabla en un objeto JSON debidamente, permitiendo definir si se incluyen todos o algunos campos y retorna el resultado en una variable local.

Comentarios

A tener en cuenta respecto a los campos a los datos a exportar :

Los campos fórmula de cualquier tipo sí se exportan.

Los campos de tipos objeto texto, textos enriquecido, fórmula, se exportan tal cual están.

Los campos objeto dibujo y binario se exportan en base64.

Los campos numéricos se exportan con separador de punto decimal y sin separador de miles.

Los campos fecha se exportan en formato YYYY-MM-DD.

Los campos hora se exportan en formato HH:MM:SS.

Los campos tiempo se exportan en formato YYYY-MM-DDTHH:MM:SS:ZZZ

Los booleanos se exportar como true/false .

No se exportan los campos de tipo puntero indirecto real o virtual, singular de plural por índice o posición y los hermanos contiguos.

Ejemplos

En un manejador de evento de un formulario generamos un JSON con los todos los campos de la tabla y lo guardamos en una variable local alfabética llamada SZ_JSON:

Generar JSON desde ficha ( , SZ_JSON, BOK, SZ_ERROR )

En un manejador de evento de un formulario generamos un JSON con los siguientes campos de la tabla: ID, NAME y MAE y lo guardamos en una variable local alfabética llamada SZ_JSON:

Generar JSON desde ficha ( "" + #ID:getID() +"," + #NAME:getID() +"," + #MAE:getID(), SZ_JSON, BOK, SZ_ERROR )

Un proceso que genera un JSON con facturas y líneas de factura

Rem ( Inicialización de variables )
Set ( JSON_RESULTANTE, "" )
Libre
Rem ( Cargamos las facturas )
Cargar lista ( FACTURAS@miapp_dat, ID, , , ,  )
    Rem ( Por cada factura se crea un JSON )
    Recorrer lista solo lectura
        Generar JSON desde ficha ( , JSON_FICHA, OK, ERROR )
        Set ( ARRAY_PLURAL, "" )
        Libre
        Rem ( Se cargan las líneas de la factura )
        Cargar plurales ( LINEAS_FACTURAS )
            Recorrer lista solo lectura
                Rem ( Se genera un json con cada línea y se añade a un array )
                Generar JSON desde ficha ( , JSON_FICHA_PLURAL, OK, ERROR )
                Set ( ARRAY_PLURAL, jsonAddToArray(ARRAY_PLURAL, JSON_FICHA_PLURAL, "object") )
        Rem ( Se compone el JSON con los maestros y los arrays de los plurales )
        Set ( JSON_RESULTANTE, jsonAddToArray(JSON_RESULTANTE, jsonAddToObject(JSON_FICHA, "PLURAL", ARRAY_PLURAL, "array"), "object") )
        Libre
        Rem ( Le damos formato indentado al JSON resultante )
        Set ( JSON_RESULTANTE, jsonFormat(JSON_RESULTANTE, 0 ) )

Leer ficha de maestro

Comando de instrucción del grupo Ficha y campos que permite leer la ficha de un maestro de la ficha en curso.

Origen de la instrucción: ficha de la tabla en curso.

Destino del subproceso: ficha del maestro de la ficha de origen.

Parámetros

Identificador de campo

Identificador de un campo de la tabla en curso enlazado a maestro.

Funcionalidad

Lee la ficha del maestro del campo enlazado seleccionado y crea un subproceso cuyo origen es la ficha del maestro leído.

Comentarios

El subproceso que crea este comando solamente se ejecutará si se ha cargado un maestro. Si la ficha no tiene maestro asociado, no será ejecutado.

El subproceso generado es de sólo lectura, por lo tanto, ningún cambio que se haga en el mismo será guardado en la base de datos.

Si se quiere editar el maestro para su modificación habrá que usar el comando de instrucción Modificar ficha de maestro.

Ejemplo

Leemos el pedido con ID 20 mostrando el número total de pedidos que se encuentra en la ficha del cliente.

Cargar lista ( PED_G@velneo_vTutor_dat, ID, 20, , ,  )
    Seleccionar ficha por posición ( 1 )
    Leer ficha seleccionada
        Leer ficha de maestro ( CLT )
            Mensaje ( "Número de pedidos totales del cliente: " + #TOT_PED, Información, ,  )

Modificar campos desde JSON

Comando de instrucción de proceso que permite modificar el valor de múltiples campos de un registro a partir de los datos contenidos en un objeto JSON que debe cumplir el estándar RFC-4627.

Origen de la instrucción: ficha de la tabla en curso.

Destino del subproceso: ninguno.

Parámetros

Fórmula de dato

Expresión fórmula con el JSON de origen. Puede ser un dato constante, un campo, una variable...

Identificador de variable local alfabética de retorno de ok (opcional)

Identificador de una variable local de tipo booleano que devolverá 1 si han modificado los campos y 0 si hay errores.

Identificador de variable local alfabética de retorno de mensaje de error (opcional)

Identificador de una variable local de tipo alfabético en la que se retornará la descripción de los errores encontrados. Si no hay errores quedará vacía.

Funcionalidad

Comando de instrucción de proceso que permite modificar el valor de múltiples campos de un registro a partir de los datos contenidos en un objeto JSON. Tras la modificación de todos los campos se ejecutará una sola vez el cálculo de contenidos iniciales.

Comentarios

Se pueden importar todos los campos excepto los de tipo puntero indirecto real o virtual, singular de plural por índice o posición y los hermanos contiguos.

Posibles errores:

  • El campo destino %1 no existe en la tabla.

  • El valor %1 a asignar al campo %2 no es válido. (Fechas válidas, números válidos, etc).

  • Error de formato JSON: %1 (error devuelto por el sistema referente a la sintaxis del JSON).

  • Error de formato JSON: no es un objeto.

Ejemplo

En un manejador de evento de un formulario pedimos al cliente que seleccione un fichero de texto en disco que contiene un JSON, lo procesa y luego modificar los campos con su contenido:

Rem ( Pedimos al usuario que seleccione el fichero a importar )
Ventana de selección de fichero ( FILE, BOK, "*.txt", "" )
If ( BOK )
    Rem ( Inicializar la variable donde se compondrá el JSON )
    Set ( SZ_JSON, "" )
    Libre
    Rem ( Abrimos y recorremos el fichero )
    Fichero: Abrir ( file, FILE, Solo lectura, BOK, .Ninguno )
        Set ( BCONTINUAR, 1 )
        For ( CONTADOR, 0, BCONTINUAR, 1 )
            Fichero: Leer línea ( file, SZ_LINEA, BCONTINUAR )
            If ( BCONTINUAR )
                Set ( SZ_JSON, "" + SZ_JSON + SZ_LINEA )
Rem ( Si todo está correcto, modificamos campos con el JSON )
If ( !isEmpty(SZ_JSON) )
    Modificar campos desde JSON ( SZ_JSON, BOK,  )

Modificar ficha de maestro

Comando de instrucción del grupo Ficha y campos que permite acceder a la ficha de un maestro de la ficha en curso en modo lectura/escritura.

Origen de la instrucción: ficha de la tabla en curso.

Destino del subproceso: ficha del maestro de la ficha de origen.

Parámetros

Identificador de campo

Identificador de un campo de la tabla en curso enlazado a maestro.

Funcionalidad

Accede a la ficha del maestro del campo enlazado seleccionado y crea un subproceso cuyo origen es la ficha del maestro editado.

Comentarios

El subproceso generado es de lectura/escritura, por lo tanto, todas las modificaciones realizadas en la ficha serán guardadas en disco.

Si el subproceso no es ejecutado será indicativo de que la ficha está siendo bloqueada en modo lectura/escritura por otra tarea.

Si se quiere acceder al maestro en modo de sólo lectura habrá que usar el comando de instrucción Leer ficha de maestro.

Ejemplo

Desde la ficha en curso de un pedido modificamos el campo total de pedidos de la ficha del cliente, la última fecha y la última hora en la que se realizó el último pedido.

Rem ( Nos encontramos en el origen ficha de un pedido )
Modificar ficha de maestro ( CLT )
    Modificar campo ( TOT_PED, #TOT_PED + 1 )
    Modificar campo ( FCH, currentDate() )
    Modificar campo ( HOR, currentTime() )

Procesar ficha en memoria

Comando de instrucción del grupo Ficha y campos que permite procesar una ficha local al proceso creada previamente mediante un comando Crear nueva ficha en memoria o el comando Crear copia de ficha en memoria.

Origen de la instrucción: cualquiera.

Destino del subproceso: ficha a editar.

Parámetros

Manejador de ficha

Identificador o manejador dado a la ficha mediante la ejecución previa de los comandos Crear nueva ficha en memoria o Crear copia de ficha en memoria.

Funcionalidad

Permite procesar una ficha local al proceso creada previamente mediante los comandos Crear nueva ficha en memoria o Crear copia de ficha en memoria. Este comando genera un subproceso cuyo origen será la ficha asociada al manejador indicado en sus parámetros.

Comentarios

Esta ficha en memoria será local al proceso, por lo que será destruida al finalizar el mismo.

Si queremos crear una ficha en la misma tabla a partir de la ficha generada en memoria usaremos el comando de Alta de ficha, en este comando la ficha será referenciada con el manejador declarado en su parámetro.

Este comando de instrucción también puede ser usado en procesos que vayan a ser ejecutados como evento drop en un objeto de lista, como por ejemplo, rejilla. Permitirá conocer la ficha sobre la que se ha efectuado el drop en una acción de drag & drop. En este caso la ficha no tendrá que ser creada previamente en el proceso mediante los comandos crear nueva ficha en memoria o crear copia de ficha en memoria, simplemente desplegaremos el combo box del parámetro Manejador de ficha y seleccionaremos el valor Ficha drop.

Ejemplo

Creamos un nuevo pedido partiendo del pedido en curso modificando la fecha del nuevo pedido con la fecha actual del sistema mostrando el ID del registro creado.

Crear copia de ficha en memoria ( copia_PED_G )
Procesar ficha en memoria ( copia_PED_G )
    Modificar campo ( FCH, currentDate() )
Alta de ficha ( copia_PED_G )
    Mensaje ( "Se ha creado el pedido con el ID: " + #ID, Información, ,  )

Última actualización