jsClient: Uso del wrapper JavaScript

Cuando nuestra aplicación no requiera de una bases de datos

Si la aplicación de cliente remoto no requiere del apoyo de una base de datos, la aplicación deberá unirse con la librería dbNoSQL. Esta proporciona el código auxiliar necesario para el correcto funcionamiento de cualesquiera otras funciones del dispositivo. En éste caso, cualquier intento de usar el "objeto SQL" del jsClient fallará.

 

El Wrapper y JavaScript

La wrapper incluye un WebView, que a su vez, aloja una aplicación JavaScript. La aplicación se inicializa mediante el archivo config.xml suministrado y que informa a al wrapper sobre cual es la página HTML desde donde cargar la aplicación.

El wrapper puede ser configurado para que se conecte a Omnis sólo con propósitos de testeo. Esto se logra a través de la opción de menú “Test Form” de Omnis Developer. El wrapper también proporciona acceso independiente al dispositivo remoto, con funciones específicas para el control del GPS, la cámara o la interfaz de audio (consulte el manual para obtener más información sobre cómo acceder a las funciones del dispositivo).

Para permitir el uso de éstas operaciones sin necesidad de conexión alguna con un servidor, el WebView deberá ejecuta secuencias de comandos locales, es decir que deberán estar contenidas en métodos que sólo pueden ser ejecutados del lado del cliente. Antes de compilar su aplicación, tendremos que personalizar el archivo config.xml de modo que pueda cumplir con éste propósito.

Cuando el cliente opera en el modo “on-line” se hará uso del parámetro URL del archivo de configuración, para cargar el “remote-form”, pero cuando es ejecutado en modo sin conexión, (modo “off-line”) los parámetros de configuración son utilizados únicamente para (si así se desea) actualizar su copia local de la aplicación o bien para ejecutar localmente los “remote-form”.

 

El wrapper para iOS

El wrapper iOS, incorpora tres modos de uso, para según la base de datos local a soportar. Estos son:  

OmnisJSWrapper            No hay soporte para base de datos local.
OmnisJSWrapper_SQLite     Se utiliza SQLite como soporte de base de datos local.
                          Sincronización con un servidor Omnis.
OmnisJSWrapper_UltraLite  Se utiliza UltraLite como soporte de base de datos local.
                          Sincronización con un servidor MobiLink.

 

 

Un apunte sobre UltraLite 

Deberá tenerse en cuenta que debido a restricciones de licencia, no es posible incluir como tal, el archivo "libulrt.a" del que depende UltraLite, lo que significa que cada vez que se desee incluir una nueva versión de UltraLite, tendremos que incluir este archivo manualmente. Para hacer esto, deberemos primero instalar SQLAnywhere 12, después y sobre el directorio ultralite/iphone de la instalación SQLAnywhere12, podremos encontrar el código fuente, etc., y un archivo léeme que nos guiará a través del proceso de construcción. (TigerLogic no proporciona ningún tipo de soporte sobre la compilación de este archivo).

Una vez construido el fichero "libulrt.a" (bien sea para su uso con el dispositivo o con un simulador), tendremos que situarlo sobre la carpeta correspondiente (-iphoneos o -iphonesimulator) bajo el directorio dbInterface del wrapper.

Los ficheros del wrapper

El código fuente de los diferentes wrapper's ya no se incluye junto con Omnis. Deberán descargarse desde el sitio web de Omnis: www.tigerlogic.com/omnis. Los archivos ZIP contienen los ficheros config.xml, junto con el resto de archivos que lo conforman. Existen diferentes notas técnicas disponibles en el sitio web Omnis, sobre el uso y la personalización de los wrapper's, como, por ejemplo las siguientes:

• TNJS0001: “Building & Customizing the Android Wrapper App
”
• TNJS0002: “Building & Customizing the iOS Wrapper App”

• TNJS0004: “Building & Customizing the BlackBerry Wrapper App”

El proceso de compilación para cada plataforma se describe en la respectivas notas técnicas.

jsClient: El objeto SQL (Sincronización con SQLite)

Si queremos hacer uso de SQLite en modo “off-line” y sincronizar una base de datos SQLite desde el dispositivo del cliente en lugar de usar Sybase UltraLite. Tendremos que tener en cuenta que dicha  sincronización está apoyada en bases de datos SQLite creadas al efecto e instaladas en el dispositivo cliente, estas guardan las tablas del usuario, así como información sobre el estado de la sincronización. El “SQLite Synchronization Server” utiliza estas tablas para pasar los datos a/de cada sincronización y para reenviar las solicitudes de sincronización. El proceso de sincronización SQLite es descrito en el manual “SQLite Synchronization Server”, puede ser descargado desde el sitio web Omnis: http://www.tigerlogic.com/omnis/download

Para poder utilizar el objeto de base de datos SQLite, en lugar del objeto UltraLite, la aplicación del dispositivo móvil, deberá estar unida a la librería dbSQLite en lugar de la dbUltraLite.

Aparte de esto, el funcionamiento y uso del objeto de SQL es esencialmente el mismo. Ta sólo los parámetros de inicialización difieren ligeramente, tal y como se muestra a continuación.

$syncinit()

Do oSQL.$syncinit(syncParams) Returns id

El módulo de SQLite actualmente reconoce los siguientes parámetros:

Username    Nombre de usuario de sincronización

            (definido en el servidor de sincronización)

Password    Contraseña de usuario de sincronización

            (definido en el servidor de sincronización)

HostString  URL del servidor de sincronización SQLite Omnis Web.

Timeout     Tiempo de espera en segundos para las operaciones

            de sincronización.

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $syncinit()).

Ejemplo: 

Do config.$define(Username,Password,HostString,Timeout)
             ;; se define mediante el uso de variables locales
Do config.$assigncols('Usuario1','xxxxxx','http://192.168.0.10:7001/ultra?OmnisClass=rtSync&OmnisLibrary=SyncServer',5)
Do oSQL.$syncinit(config) Returns id

Consulte el manual de la "SQLite Synchronization Server" para obtener más información sobre el diseño, implementación y uso del servidor de sincronización. Si lo desa podrá descargar su manual desde la página web Omnis (www.tigerlogic.com/omnis).

jsClient: El objeto SQL (Sincronización de la base de datos)

El objeto SQL proporciona dos métodos adicionales que facilitan la sincronización dinámica con otro servidor. En caso de usarse una base de datos UltraLite, será necesario disponer de conexión con un servidor Sybase Mobilink. Disponible con SQLAnywhere 12.01

Consulte la Guía de usuario en http://download.sybase.com/pdfdocs/awg0901e/dbmlen9.pdf para obtener más información sobre las siguientes cuestiones:

• Configuración del servidor MobiLink sincronización.
• Configuración de usuarios MobiLink, tablas y secuencias de comandos.
• Creación de una base de datos consolidada e instalación de las tablas del sistema Mobilink.

La guía del usuario también proporciona un útil tutorial de primeros pasos. Como guía de inicio rápido, lea las lecciones 1-5 del tutorial indicado a continuación, deberá llegar a un punto en el que usted pueda probar la sincronización con soltura:

http://dcx.sybase.com/1201/en/mlstart/ml-sc-tutorial.html

 

$syncinit()

Do oSQL.$syncinit(syncParams) Returns id

Inicializa la sincronización contra un servidor MobiLink. Los parámetros de sincronización son específicos para cada implementación y son suministrados a través de una variable de tipo row. Si la sincronización inicial tiene éxito, también se ejecutará un 'sync' inicial. Ver $sync() para más detalles.

El módulo UltraLite actualmente reconoce los siguientes parámetros:

Username         Nombre del usuario de sincronización MobiLink.
Password         Contraseña del usuario MobiLink, si es necesaria. 

NewPassword      Permite al usuario MobiLink cambiar su contraseña por otra, si así

                 se indica en NewPassword.
Version          Determina qué versión del script de sincronización se utilizará

                 en las diversas acciones.
Stream           Determina el protocolo de red que se utilizará, por ejemplo: tcpip
StreamParams     Permite especificar parámetros adicionales de conexión,

                 específicos del protocolo en uso, por ejemplo: host
Publications     Lista las publicaciones MobiLink suscritas por el usuario.
AdditionalParams Una cadena en la forma nombre=valor; Especificando parámetros

                 adicionales.
Ping             Si es usado, permite conformar que hay comunicación con el

                 servidor Mobilink. No se produce la sincronización.
UploadOnly       Si es usado, indica que no se permitirán descargas sobre CDB, sólo

                 se procesaran las subidas de archivos.
DownloadOnly     Si es usado, indica que no se permitirán subidas en el CDB,

                 sólo se permitirán las descargas. 

ResumePartialDownload   Si es usado, UltraLite únicamente reanudará cualquier

                        descarga fallida. No se permitirán subidas.  

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $syncinit()).

Ejemplo:

        Calculate config as row(Username,Version,Stream,StreamParams)
                ;; se define mediante el uso de variables locales
        Do config.$assigncols('ml_ventas','default','tcpip','host=192.168.0. 10')
        Do oSQL.$syncinit(config) Returns id  

$sync()

Do oSQL.$sync() Returns id

Una vez que la sincronización haya sido iniciada mediante $syncinit(), el método $sync() se encargará de realizar la sincronización "ad-hoc" entre la base de datos (UltraLite) y el servidor de sincronización (MobiLink). Si es necesario modificar los parámetros de sincronización, podrá invocarse al método $syncinit() en su lugar, ya que con esto también se lleva a cabo.

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $sync()).

jsClient: El objeto SQL ($execute(), $selecttables(), $selectcolumns() y $selectindexes())

$execute()

Do oSQL.$execute(cSQL) Returns id
 

Permite la ejecución de una sentencia SQL de la que no se espera la devolución de un conjunto de resultados, deberá usarse únicamente para la ejecución de comandos administrativos DDL, tales como CREATE, DROP y ALTER.

• cSQL es la sentencia SQL a ejecutar. No está soportado el uso de notación “bind”.

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $execute()).

 
Los siguientes pueden ser utilizados para obtener “meta-datos” de la base de datos:

$selecttables()

Do oSQL.$selecttables() Returns id

Devuelve los nombres de tablas definidas en la base de datos local.

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $selecttables()).
• Lista de una columna, conteniendo el TableName de cada tabla en la base de datos local.

$selectcolumns()

Do oSQL.$selectcolumns(NombreTabla) Returns id

Devuelve el nombre y tipo de las columnas en la tabla especificada.

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $selectcolumns()).

• Una lista que describe la definición de columnas en la tabla, con las siguiente columnas:

ColumnName  Nombre de la columna en la tabla.
SqlType     Nombre que corresponde al tipo de datos SQL en la columna.
ColumnSize  Tamaño definido en variables de tipo CHAR y BINARY.
Precision   Precisión numérica en columnas de tipo numérico.

            Será 0 para los demás tipos.
Scale       Escala numérica en columnas de tipo numérico.

            Cero para los demás tipos.
Default     Valor predeterminado asignado a la columna, cuando se creó la tabla.

$selectindexes()

Do oSQL.$selectindexes(NombreTabla) Returns id

Devuelve, información sobre las columnas de tipo índice en la tabla especificada.

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $selectindexes()).

• Una lista que describe la definición de índices para la tabla especificada, con las siguientes columnas:

IndexName     Nombre del índice.
ColumnNames   Lista separada por comas, con los nombres de las columnas 

              utilizadas por el índice.
PrimaryKey    KTrue si el índice ha sido creado con la cláusula PRIMARY KEY
Unique        KTrue si el índice ha sido creado con la cláusula UNIQUE.

jsClient: El objeto SQL ($delete() y $update())

$delete() 

 

Do oSQL.$delete(cSQL,row) Returns id
Elimina cero o más filas de una tabla de la base de datos.

• cSQL es la instrucción delete. La cual puede ser escrita a mano, u obtenida como resultado de la ejecución de un $delete() sobre una clase “schema”. cSQL puede referenciar variables en la forma @[nombre_columna], donde nombre_columna es el nombre de una columna incluida en row.

• row, contiene los valores que podrán ser referenciados mediante notación “bind”.

Al concluir, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $delete()). 

 

$update() 

 

Do oSQL.$update(cSQL,newRow,oldRow) Returns id
Actualiza cero o más filas de una tabla de la base de datos.

• cSQL es la instrucción de actualización. Podrá ser escrita a mano, u obtenida como resultado de la ejecución de un $update sobre una clase “schema”. cSQL permite referenciar variables en la forma @[$nombre_columna], donde nombre_columna es el nombre de una columna contenida en newRow o en oldRow. Si la variable es referenciada en la cláusula SET, se esperará que la columna esté incluida en newRow, pero si se está usando en la cláusula WHERE, deberá estar incluida en oldRow.

• newRow, es la row que contiene los nuevos valores y que podrán ser referenciados mediante notación “bind”, es decir, los que se especifican en la cláusula SET.

• oldRow, es la row que contiene los valores anteriores y que pueden ser referenciados mediante notación “bind”, es decir, los que pueden ser usados en la cláusula WHERE.

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $update()).

jsClient: El objeto SQL ($fetch() y $insert())

$fetch()

Do oSQL.$fetch(selectfetchid,iFetchCap) Returns id

Obtiene cero o más filas del conjunto de resultados generado mediante un $selectfetch() anterior.

• selectfetchid es el id retornado por el $selectfetch().
• iFetchCap es el número de filas devueltas.

En este caso, el ID devuelto será el mismo. Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retorno el $selectfetch)
• Una lista conteniendo cero o más filas del conjunto de resultados.

$insert()

Do oSQL.$insert(cSQL,listorrow) Returns id

Inserta una o más filas en una tabla de la base de datos.

• cSQL es la instrucción de inserción. Puede ser escrita a mano, u obtenida como resultado de la ejecución de un $insert sobre una clase “schema”. cSQL puede contener referencias a variables mediante la notación @[$nombre_columna], donde nombre_columna es el nombre de una columna incluida en listorrow.

• listorrow, es una variable de tipo “list” o “row” que contiene los datos a insertar.

Al finalizar, se invocará el método $sqldone() pasando los siguientes parámetros:

• El ID de la solicitud (el mismo que retornó el $insert()).

Ejemplo:
Do oSQL.$insert("INSERT INTO producto (nombre,cantidad) VALUES (@[colNomb],@[colCant])”,lBindVars) Returns IDinsert