32

VRoot

La clase VRoot representa a un objeto de Velneo en ejecución. Dispone de funciones para ver o modificar las variables locales y de sistema del objeto, obtener información del objeto (api), transacciones…

theRoot

Velneo nos genera un objeto de la clase VRoot con el nombre theRoot para el objeto principal en ejecución. Veamos algunos ejemplos:

  • Tenemos un formulario con un manejador de evento en lenguaje JavaScript: el objeto theRoot del manejador de evento representa al ejecutor del formulario.

  • Ejecutamos un proceso JavaScript con una acción: el objeto theRoot del proceso representa al ejecutor del proceso en Velneo.

  • Si el objeto es una vista de datos (rejilla, formulario…) estarán disponibles en theRoot las funciones de manejo de interfaz como obtener su vista de datos con la función dataView(), pudiéndose usar las funciones del objeto widget que devuelve.

  • También se pueden obtener otros VRoot, como el de una VMdiView con su función root().

Indice de funciones

De variables locales tipo array

void setVar( String szId, Number index, String szValor )

void setVar( String szId, Number index, Number nValor )

void setVar( String szId, Number index, Boolean bValor )

void setVar( String szId, Number index, DateTime dt )

void setVar( String szId, Number index, Date date )

void setVar( String szId, Number index, Time time )

Date varToDate( String szId, Number index )

DateTime varToDateTime( String szId, Number index )

Number varToDouble( String szId, Number index )

Number varToInt( String szId, Number index )

String varToString( String szId, Number index )

Time varToTime( String szId, Number index )

Del Api del objeto

Number inputType()

VObjectInfo objectInfo()

Number objectType()

Number outputType()

De variables locales

void setVar( String szId, Boolean bValor )

void setVar( String szId, Date date )

void setVar( String szId, DateTime dt )

void setVar( String szId, double dValor )

void setVar( String szId, int nValor )

void setVar( String szId, String szValor )

void setVar( String szId, Time time )

Boolean varToBool( String szId )

Date varToDate( String szId )

DateTime varToDateTime( String szId )

Number varToDouble( String szId )

Number varToInt( String szId )

String varToString( String szId )

Time varToTime( String szId )

De variables de sistema

String clientCachePath()

Number currentPage()

Boolean isAdministrator()

Number lastPage()

Number listPos()

Number listSize()

String userName()

De transacciones

Boolean beginTrans( String szTitulo )

void clientEntertainer()

Boolean commitTrans()

void endProgressBar()

Boolean existTrans()

void initProgressBar()

Boolean rollbackTrans()

Boolean runProcess( String szIdRefProcess )

void setProgress( Number percent )

void setTitle( String szTitle )

De datos

Variant calcFormulaVelneo( szFormula )

Object content()

De vista de datos

VAbstractDataView dataView()

De formulario y lista QML

void LoadAuxModel( String szNameModel )

De lista QML

VModel GetAuxModelFromArray( String szNameModel, Number nIndex )

De JSON

VariantMap registerFromJSON( String szJSON, ImportType nTipoOp, String szTabla, String szIndice)

Enum de tipos de operación

ImportTypeCreateModify : si no existe crea el registro. Si existe, lo modifica.

ImportTypeOnlyCreate : dará de alta un nuevo registro. Sl el JSON incluye el campo ID del registro lo y el contenido inicial del ID de la tabla es "siguiente al último", lo ignorará y creará un nuevo registro con el ID que le corresponda.

ImportTypeOnlyModify: si el registro existe, lo modifica, si no, no hará nada.

Documentación de funciones

Funciones de variables locales tipo array

void setVar( String szId, Number index, String szValor )

Asigna el contenido a una variable local array de tipo alfabética.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

  • szValor: cadena alfabética.

void setVar( String szId, Number index, Number nValor )

Asigna el contenido a una variable local array de tipo numérica.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

  • nValor: número.

void setVar( String szId, Number index, Boolean bValor )

Asigna el contenido a una variable local array de tipo booleana.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

  • bValor: booleano, 0 ó 1, true o false.

void setVar( String szId, Number index, DateTime dt )

Asigna el contenido a una variable local array de tipo tiempo, fecha y hora.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

  • dt: tiempo, fecha y hora.

void setVar( String szId, Number index, Date date )

Asigna el contenido a una variable local array de tipo fecha.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

  • date: fecha.

void setVar( String szId, Number index, Time time )

Asigna el contenido a una variable local array de tipo hora.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

  • time: hora.

Date varToDate( String szId, Number index )

Devuelve el valor de una variable local array de tipo fecha.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

DateTime varToDateTime( String szId, Number index )

Devuelve el valor de una variable local array de tipo tiempo, fecha y hora.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

Number varToDouble( String szId, Number index )

Devuelve el valor de una variable local array de tipo numérica, double.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

Number varToInt( String szId, Number index )

Devuelve el valor de una variable local array de tipo numérica, integer.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

String varToString( String szId, Number index )

Devuelve el valor de una variable local array de tipo alfabética.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

Time varToTime( String szId, Number index )

Devuelve el valor de una variable local array de tipo hora.

Parámetros:

  • szId: identificador de la variable local.

  • index: número de la posición del elemento en el array, el primero elemento es el 0.

Funciones del Api del objeto

Number inputType()

Devuelve el tipo de entrada (ninguno, ficha o lista) del objeto manipulado con la clase VRoot. Ver enum de tipos de entrada/salida en la clase VObjectInfo

VObjectInfo objectInfo()

Devuelve un objeto de la clase VObjectInfo que representa al objeto manipulado.

Number objectType()

Devuelve el tipo del objeto manipulado con la clase VRoot. Ver enum de tipos de objeto en la clase VObjectInfo.

Number outputType()

Devuelve el tipo de salida (ninguno, ficha o lista) del objeto manipulado con la clase VRoot. Ver enum de tipos de entrada/salida en la clase VObjectInfo.

Funciones de variables locales

void setVar( String szId, Boolean bValor )

Asigna el contenido a una variable local de tipo booleana.

Parámetros:

  • szId: identificador de la variable local.

  • bValor: booleano, 0 ó 1, true o false.

void setVar( String szId, Date date )

Asigna el contenido a una variable local de tipo fecha.

Parámetros:

  • szId: identificador de la variable local.

  • date: fecha.

void setVar( String szId, DateTime dt )

Asigna el contenido a una variable local de tipo tiempo, fecha y hora.

Parámetros:

  • szId: identificador de la variable local.

  • dt: tiempo, fecha y hora.

void setVar( String szId, double dValor )

Asigna el contenido a una variable local de tipo numérica, double.

Parámetros:

  • szId: identificador de la variable local.

  • dValor: número con decimales.

void setVar( String szId, int nValor )

Asigna el contenido a una variable local de tipo numérica, integer.

Parámetros:

  • szId: identificador de la variable local.

  • nValor: número entero.

void setVar( String szId, String szValor )

Asigna el contenido a una variable local de tipo alfabética.

Parámetros:

  • szId: identificador de la variable local.

  • szValor: cadena alfabética.

void setVar( String szId, Time time )

Asigna el contenido a una variable local de tipo hora.

Parámetros:

  • szId: identificador de la variable local.

  • time: hora.

Boolean varToBool ( String szId )

Devuelve el valor de una variable local de tipo booleana.

Parámetros:

  • szId: identificador de la variable local.

Date varToDate( String szId )

Devuelve el valor de una variable local de tipo fecha.

Parámetros:

  • szId: identificador de la variable local.

DateTime varToDateTime( String szId )

Devuelve el valor de una variable local de tipo tiempo, fecha y hora.

Parámetros:

  • szId: identificador de la variable local.

Number varToDouble( String szId )

Devuelve el valor de una variable local de tipo numérica, double.

Parámetros:

  • szId: identificador de la variable local.

Number varToInt( String szId )

Devuelve el valor de una variable local de tipo numérica, integer.

Parámetros:

  • szId: identificador de la variable local.

String varToString( String szId )

Devuelve el valor de una variable local de tipo alfabética.

Parámetros:

  • szId: identificador de la variable local.

Time varToTime( String szId )

Devuelve el valor de una variable local de tipo hora.

Parámetros:

  • szId: identificador de la variable local.

Funciones de variables de sistema

String clientCachePath()

Devuelve el path del directorio de caché del cliente.

Number currentPage()

Devuelve la página en curso en un informe.

Boolean isAdministrator()

Devuelve true si el usuario en vAdmin está configurado como supervisor.

Number lastPage()

Devuelve el número total de páginas de un informe.

Number listPos()

Devuelve la posición del registro actual en la lista de registros del objeto.

Number listSize()

Devuelve el número de registros de la lista del objeto.

String userName()

Devuelve el nombre del usuario.

Funciones de transacciones

Boolean beginTrans( String szTitulo )

Inicia una transacción. Devuelve true si la transacción se ha iniciado satisfactoriamente.

Parámetros:

  • szTitulo: título de la transacción que se visualiza en el visor de transacción de vAdmin.

void clientEntertainer()

Con esta función el servidor realiza una notificación al cliente informándole de que el proceso sigue activo y de esta forma se evita que el cliente asuma la finalización del mismo por alcanzar el timeout.

Si desde un cliente ejecutamos un proceso en tercer plano, es decir en el servidor, si la duración del proceso es superior al timeout (actualmente 10 minutos) aunque el proceso continue ejecutándose en el servidor el cliente asume que el proceso ha finalizado de forma anómala al no recibir ninguna información del servidor. Con esta función el programador puede notificar desde el proceso que se está ejecutando en el servidor al cliente evitando que se produzca la desconexión del cliente por llegar al timeout.

Esta función es conveniente usarla en procesos cuya duración sea larga y pueda superar el timeout, de todas formas no debe ejecutarse esta función de forma constante ya que podría afectar al rendimiento del proceso. Una buena práctica sería ejecutar esta función cada determinado número de operaciones cuya duración sea superior a 1 minuto, por ejemplo, e inferior al tiempo de timeout.

Boolean commitTrans()

Finaliza una transacción. Devuelve true si la transacción ha finalizado satisfactoriamente. Al finalizar la transacción se dan por válidas todas las operaciones realizadas en la base de datos.

No es necesario usarla en general, ya que al finalizar el proceso, si hay una transacción abierta, se cierra automáticamente como si se hubiese ejecutado esta función de forma explícita. De hecho, si no es necesario por requerimientos de programación, debemos evitarlo para que ese script se pueda usar en diferentes puntos donde la transacción ya haya sido abierta y no la cierre cuando no deba. En el caso de que se requiera por programación, debemos comprobar previamente que la transacción no exista previamente, ya que entonces no se debe cerrar en el script en curso. Ver la nota siguiente:

En triggers no debemos hacer commit de transacciones ya que es el propio trigger el que gestiona la transacción. Por lo tanto, si tenemos un script que podemos usar en un trigger pero también en otros puntos de nuestra aplicación, deberemos comprobar si ya existe la transacción, sólo si no existe es cuando haremos el commit. Ejemplo: 

var nuevaTrans = false;
var hayTrans = theRoot.existTrans();
if ( hayTrans == false ) 
{
  var nuevaTrans = theRoot.beginTrans( "Nombre transacción" )
}
 
// Se crea una transacción
if ( hayTrans || nuevaTrans )
*/

theRoot.beginTrans( "Alta de tbl2" )
{
 // Se modifican los datos
 reg.setField( "NAME", "name" );

 // Se crea el registro
 reg.addRegister();
}

// Metodo correcto
if ( nuevaTrans )
{
  theRoot.commitTrans();
}

void endProgressBar()

Se oculta la barra de progreso de la barra de estado de la ventana.

Boolean existTrans()

Devuelve true si hay una transacción en curso.

void initProgressBar()

Se visualiza la barra de progreso en la barra de estado de la ventana.

Boolean rollbackTrans()

Aborta una transacción y deshace todas sus operaciones. Devuelve true si todas las operaciones de la transacción se han deshecho satisfactoriamente.

Boolean runProcess( String szIdRefProcess )

Ejecuta un proceso Velneo o JavaScript. Permite los siguientes casos:

  • Si se pasa un proceso sin origen los ejecuta.

  • Si el Root corresponde a un objeto de ficha y el proceso es de ficha lo alimenta con la ficha.

  • Si el Root corresponde a un objeto de lista y el proceso de ficha lo alimenta con la ficha seleccionada de la lista.

  • Si el Root corresponde a un objeto de lista y el proceso es de lista lo alimenta con la lista.

Parámetros:

  • szIdRefProcess: cadena que contiene el identificador referencia del proceso ("Alias_proyecto/ID_proceso").

void setProgress( Number percent )

Se actualiza la barra de progreso que se está visualizando en la barra de estado de la ventana al valor indicado en el porcentaje. Al igual que el porcentaje también es posible cambiar el texto o leyenda que se muestra junto a la barra de progreso con la función setTitle().

Antes de fijar el valor porcentual es necesario mostrar la barra de progreso con la función initProgressBar() y una vez finalizado el proceso se ocultará la barra de progreso con el comando endProgressBar().

Parámetros:

  • percent: número entre 0 y 100 que representa el porcentaje a mostrar en la barra de progreso.

void setTitle( String szTitle )

Cambia el título o leyenda que se muestra al lado de la barra de progreso en la barra de estado de la ventana.

Antes de fijar título o el valor porcentual es necesario mostrar la barra de progreso con la función initProgressBar() y una vez finalizado el proceso se ocultará la barra de progreso con el comando endProgressBar().

Parámetros:

  • szTitle: texto a visualizar junto a la barra de progreso.

Funciones de datos

Variant calcFormulaVelneo( szFormula )

Retorna el valor obtenido de calcular la fórmula de Velneo que indicamos como parámetro.

Parámetro:

  • szFormula: fórmula de Velneo. Se recomienda dar valor entre comillas simples (') para evitar colisiones con entrecomillados (") correspondientes a cadenas en Velneo.

Tendrá como origen, el mismo que theRoot.

Object content()

Devuelve un objeto VRegister, VRegisterList o Nulo en función del origen del objeto representado por VRoot.

Funciones de vista de datos

VAbstractDataView dataView()

Devuelve un objeto de la clase VAbstractDataView que representa el objeto referenciado por VRoot.

Funciones de formulario y lista QML

void LoadAuxModel( String szNameModel )

Carga un modelo auxiliar del modelo principal del QML.

Parámetros:

  • szNameModel: mombre del modelo. Este valor se corresponde con la propiedad "Nombre en QML" del modelo auxiliar.

Funciones de lista QML

VModel GetAuxModelFromArray( String szNameModel, Number nIndex )

Devuelve un modelo auxiliar de los existentes en el array de modelos auxiliares. Esta función se utiliza cuando en el modelo auxiliar se configura la propiedad "Modo de sincronización" con el valor "LISTA: un modelo por cada ítem del modelo principal".

Parámetros:

  • szNameModel: nombre del modelo. Este valor se corresponde con la propiedad "Nombre en QML" del modelo auxiliar.

  • nIndex: número de orden del modelo en el array de modelos. El primero elemento del array es el 0.

De JSON

VariantMap registerFromJSON( String szJSON, ImportType nTipoOp, String szTabla, String szIndice)

Recibe como parámetro un objeto JSON para crear o modificar un registro o una lista de registros, el tipo de operación, la tabla y el índice .

Equivale a los comando de instrucción de proceso crear o modificar ficha desde JSON y crear o modificar lista desde JSON.

Parámetros:

  • szJson: es la cadena con el Json que se va a usar para modificar o dar de alta el registro o los registros. Si el Json representa un array, se iterará e irá creando o modificando por cada elemento del array. Si es un objeto, lo tomará como una ficha.

  • nTipoOp: tipo de operación a realizar en la tabla de destino. Ver enum de tipos de operación.

  • szTabla: idref de la tabla de destino.

  • szIndice: 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.

Devuelve un VariantMap con los siguientes campos:

  • ok: booleano con el retorno de ok.

  • errors: cadena de texto con un objeto JSON con los errores que tiene la sigiuente estructura:

{

velneo_errorCode: 0 si no hay errores generales, o valor en caso de haber un error general. Ver enum de errores de JSON.

velneo_errorString: ““ si errorCode es 0, o mensaje de error en caso de error general

velneo_errorRegistersCount: entero con el tamaño del array de “registers” (0 si es un error general)

velneo_errorRegisters: [] → array de objetos con el que se intento dar el alta o modificar el registro con la información extra de las claves velneo_errorCode y velneo_errorString (como se especifica más arriba).

}

  • register: si se trata de una ficha, devuelve un objeto VRegister con la ficha creada/modificada.

  • registerList: si se trata de una lista, devuelve un objeto VRegisterList con la lista creada/modificada.

Podremos obtener estos campos del VariantMap del modo siguiente:

Ejemplo 1: 

var operacion = theRoot.registerFromJSON( JSON_RECIBIDO, N_TIPO_OP, ID_TABLA, INDICE )
var bOk = operacion.ok;
var errores = operacion.errors;
var lista = new VRegisterList(theRoot);
var lista = operacion.registerList;

Ejemplo 2:

var operacion = theRoot.registerFromJSON( JSON_RECIBIDO, N_TIPO_OP, ID_TABLA, INDICE )
var bOk = operacion["ok"];
var errores = operacion["errors"];
var lista = new VRegisterList(theRoot);
var lista = operacion["registerList"];

Ejemplos

1. Iniciar transacción

if (theRoot.beginTrans("Titulo"))
{
    var bOK = true;
    var szErrMsg = "";

    for( var x=0; bOK && ( x < theRegisterListIn.sizeList() ); x++)
    {
        var registro = theRegisterListIn.readLockingAt(x);
        bOK = registro.isOK();
        if ( bOK )
        {
            registro.setField( "IDCAMPO1", dato );
            registro.setField( "IDCAMPO2", hoy );
            .....
            registro.modify();
            bOK = registro.isOK();
        }
        if ( !bOK )
            szMsg = registro.errorMessage();
    }
    if ( !bOK )
    {
        theRoot.rollbackTrans();
        .... // Mensaje de error
    }
}
else
{
     .... //Mensaje de error
}

2. Múltiples transacciones

// Se crea un registro vacío en memoria y se le asigna la tabla
var reg = new VRegister( theRoot );
reg.setTable( "vbaseUsuariosDat/USR" );

// Se ejecuta un bucle para dar 10 altas en 10 transacciones diferentes
for ( var i=0; i < 10; ++i )
{
    // Se crea una transacción
    if ( theRoot.beginTrans( "Alta de usuario. Transacción " + i ) )
    {
        // Se modifican los datos
        reg.setField( "NAME", "Usuario_" + i );

        // Se crea el registro
        reg.addRegister();

        // Se añaden el registro a la lista de salida
        theRegisterListOut.append( reg );

        // Se cierra la transacción
        theRoot.commitTrans();
    }
}

3. Un manejador de envento de una rejilla duplica los registros de la misma

//Convertimos la lista a JSON
var operacion = theRegisterListIn.toJson( [] );
var bOk = operacion.ok;
var szJson = operacion.json;
var errores = operacion.errors;

//Si se ha generado el JSON procedemos a duplicar la lista
if (bOk)
{
	theRoot.beginTrans("Duplicar lista lista");

	var alta = theRoot.registerFromJson( szJson, VRoot.ImportTypeOnlyCreate, "miapp_dat/ART_M", "ID" );
	var bOkAlta = alta.ok;
	var erroresalta = alta.errors;

	//Mostrar error si no se ha podido llevar a cabo la generación de registros
	if (!bOkAlta)
	{
		alert(erroresalta);
	}
	else{
		theRoot.commitTrans();
	}

}
//Mostrar errores si no se ha podido generar el JSON
else{
	alert(errores);
}

4. Modificar una variable local de un formulario desde un manejador de evento de un subformulario del mismo

//Obtenemos el formulario padre
var formPadre = theRoot.dataView().parentDataView();

//Modificamos la variable local NOM del formulario padre
formPadre.root().setVar("NOM", "Modificada desde el subformulario");

5. Modificar desde un proceso JavaScript un subobjeto variable del proceso

//La variable local declarada en el objeto proceso se llama RETORNO
theRoot.setVar(RETORNO, "Error 45");

6. Modificar variable local desde subformulario a formulario padre

//Obtenemos el formulario padre
var formPadre = theRoot.dataView().parentDataView();

//Modificamos la variable local NOM del formulario padre
formPadre.root().setVar("NOM", "HOLA");

//Forzamos el refresco del formulario padre
formPadre.updateControls();

Última actualización