# VSqlDatabase

Este clase representa la conexión con una base de datos externa.

Dispone de funciones para conexión y obtención de información, además de la ejecución de sentencias SQL.

Requiere importarla previamente a su uso:

importClass ( "VSqlDatabase" );

## Funciones

**Constructor**

| Retorno      | Función                         |
| ------------ | ------------------------------- |
| VSqlDatabase | [VSqlDatabase](#vsqldatabase)() |

**De conexión**

| Retorno | Función                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| void    | [close](#close)()                                                                                                               |
| void    | [configure](#configure)( String szPluginDriver, String szNombreDSN, String szOpcionesConexion, String szServidor, int nPuerto ) |
| Array   | [drivers](#drivers)()                                                                                                           |
| Boolean | [open](#open)( String szUsuario, String szContraseña )                                                                          |

**De estado**

| Retorno | Función                           |
| ------- | --------------------------------- |
| Boolean | [isActive](#isactive)()           |
| Boolean | [isForwardOnly](#isforwardonly)() |
| Boolean | [isOpen](#isopen)()               |

**De sentencias SQL**

| Retorno | Función                                                                   |
| ------- | ------------------------------------------------------------------------- |
| Boolean | [executeSQL](#executesql)( String szSQL, Boolean bForwardOnly )           |
| Variant | [getColumn](#getcolumn)( int nNumCol )                                    |
| Variant | [getColumn](#variant-getcolumn-string-sznombrecol-)( String szNombreCol ) |
| Number  | [getColumnCount](#getcolumncount)()                                       |
| String  | [getColumnName](#getcolumnname)( Number nNumCol)                          |
| String  | [getLastError](#getlasterror)()                                           |
| void    | [goAfterLastRecord](#goafterlastrecord)()                                 |
| Boolean | [goBeforeFirstRecord](#gobeforefirstrecord)()                             |
| Boolean | [nextRegister](#nextregister)()                                           |
| Number  | [numRows](#numrows)()                                                     |

**De tablas**

| Retorno | Función                        |
| ------- | ------------------------------ |
| Array   | [tables](#tables)( int nTipo ) |

**De campos**

| Retorno | Función                                                                  |
| ------- | ------------------------------------------------------------------------ |
| Number  | [fieldCount](#fieldcount)( String szTabla )                              |
| String  | [fieldDefaultValue](#fielddefaultvalue)( String szTabla, Number nIndex ) |
| Boolean | [fieldIsAutoValue](#fieldisautovalue)( String szTabla, Number nIndex )   |
| Number  | [fieldLength](#fieldlength)( String szTabla, Number nIndex )             |
| String  | [fieldName](#fieldname)( String szTabla, Number nIndex )                 |
| Number  | [fieldPrecision](#fieldprecision)( String szTabla, Number nIndex )       |
| Number  | [fieldType](#fieldtype)( String szTabla, int nIndex )                    |

**De índice primario**

| Retorno | Función                                                                       |
| ------- | ----------------------------------------------------------------------------- |
| Number  | [primaryIndexFieldCount](#primaryindexfieldcount)( String szTabla )           |
| String  | [primaryIndexFieldName](#primaryindexfieldname)( String szTabla, int nIndex ) |
| String  | [primaryIndexName](#primaryindexname)( String szTabla )                       |

## Enumeraciones

**Tipos de campo**

* Invalid = Desconocido
* Bool = Booleano
* Int = Entero
* UInt = Entero sin signo
* LongLong = LongLong
* ULongLong = LongLong sin signo
* Double = Double
* Char = Char
* Map = Map
* List = List
* String = String
* StringList = StringList
* ByteArray = ByteArray
* Date = Fecha
* Time = Hora
* DateTime = Tiempo
* Pixmap = Mapa de píxeles
* Image = Imagen
* Bitmap = Mapa de bits
* BitArray = BitArray

**Tipos de tabla**

* 0x01 = Todas las tablas visibles por el usuario
* 0x02 = Todas las tablas internas usadas por la base de datos
* 0x04 = Todas las vistas visibles para el usuario
* 0xff = Todas las anteriores

## Documentación de funciones

### Constructor

#### VSqlDatabase VSqlDatabase() <a href="#vsqldatabase" id="vsqldatabase"></a>

Construye un conector para acceder a una base de datos externa.

Requiere importarla previamente a su uso:

importClass ( "VSqlDatabase" );

### Funciones de conexión

#### void close() <a href="#close" id="close"></a>

Cierra la conexión con la base de datos actual. Debemos abrirla de nuevo para continuar trabajando con la base de datos.

#### void configure( String szPluginDriver, String szNombreDSN, String szOpcionesConexion, String szServidor, int nPuerto ) <a href="#configure" id="configure"></a>

Configura la conexión con la base de datos externa según los parámetros especificados.

Parámetros:

* szPluginDriver: cadena entre comillas o comas simples con el identificador del plugin de driver usado.
* szNombreDSN: nombre o DSN de la base de datos.
* szOpcionesConexion: opciones de conexión de la base de datos (Opcional)
* szServidor: servidor de la base de datos a la que nos vamos a conectar (Opcional)
* nPuerto: puerto usado por la base de datos (Opcional)

Nota:

Si hemos configurado en el DSN el resto de parámetros requeridos para la conexión, no es necesario cumplimentar los parámetros opcionales. En Linux y Mac, el driver en el DSN para ODBC debe ser la senda la propia librería del driver.

No todos los plugins de drivers están disponibles, dependerán del sistema operativo. La función drivers() nos devolverá los plugins disponibles para el ejecutable de entre los siguientes:

"QODBC" Open Database Connectivity (ODBC) 2.0 - Microsoft SQL Server y otros drivers ODBC compatibles

"QODBC3" Open Database Connectivity (ODBC) 3.0 - Microsoft SQL Server y otros drivers ODBC compatibles

"QDB2" IBM DB2 (versión 7.1 y superiores)

"QIBASE" Borland InterBase y Firebird

"QMYSQL" MySQL 5.X

"QMYSQL3" MySQL 3.X

"QOCI" Oracle Call Interface Driver (versiones 9 y superiores)

"QPSQL" PostgreSQL (versiones 7.3 y superiores)

"QPSQL7" PostgreSQL (versiones 6 y 7)

"QSQLITE" SQLite versión 3

"QSQLITE2" SQLite versión 2

En general, el acceso a bases de datos SQLite es el mejor soportado en todas las plataformas, Oracle vía OCI, PosgreSQL y MySQL a través de ODBC o con driver nativo están bastante soportados en Windows y Linux. En cuanto al resto de drivers y sistemas operativos, depende de la calidad de los drivers existentes en cada sistema operativo.

Ejemplos de DSN para ODBC:

Para Windows:

nombreDSN

DSN=nombreDSN

Para Linux y Mac:

Driver={/usr/local/lib/libmyodbc5a.so};Server=[www.dominio.com;Port=3306;Database=nombreBaseDatos;Uid=nombreUsuario;Pwd=contraseña](http://www.dominio.com;Port=3306;Database=nombreBaseDatos;Uid=nombreUsuario;Pwd=contraseña);

Opciones de conexión:

ODBC

SQL\_ATTR\_ACCESS\_MODE

SQL\_ATTR\_LOGIN\_TIMEOUT

SQL\_ATTR\_CONNECTION\_TIMEOUT

SQL\_ATTR\_CURRENT\_CATALOG

SQL\_ATTR\_METADATA\_ID

SQL\_ATTR\_PACKET\_SIZE

SQL\_ATTR\_TRACEFILE

SQL\_ATTR\_TRACE

SQL\_ATTR\_CONNECTION\_POOLING

SQL\_ATTR\_ODBC\_VERSION

MySQL

CLIENT\_COMPRESS

CLIENT\_FOUND\_ROWS

CLIENT\_IGNORE\_SPACE

CLIENT\_SSL

CLIENT\_ODBC

CLIENT\_NO\_SCHEMA

CLIENT\_INTERACTIVE

UNIX\_SOCKET

MYSQL\_OPT\_RECONNECT

MYSQL\_OPT\_CONNECT\_TIMEOUT

MYSQL\_OPT\_READ\_TIMEOUT

MYSQL\_OPT\_WRITE\_TIMEOUT

PostgreSQL

connect\_timeout

options

tty

requiressl

service

DB2

SQL\_ATTR\_ACCESS\_MODE

SQL\_ATTR\_LOGIN\_TIMEOUT

OCI

OCI\_ATTR\_PREFETCH\_ROWS

OCI\_ATTR\_PREFETCH\_MEMORY

SQLite

QSQLITE\_BUSY\_TIMEOUT

QSQLITE\_OPEN\_READONLY

QSQLITE\_OPEN\_URI

QSQLITE\_ENABLE\_SHARED\_CACHE

Interbase

ISC\_DPB\_LC\_CTYPE

ISC\_DPB\_SQL\_ROLE\_NAME

Ej. de uso:

CLIENT\_SSL=1;CLIENT\_IGNORE\_SPACE=1;

#### Array drivers() <a href="#drivers" id="drivers"></a>

Devuelve en un array la lista de plugins de driver disponibles para el ejecutable.

#### Boolean open( String szUsuario, String szContraseña ) <a href="#open" id="open"></a>

Abre la base de datos externa.

Parámetros:

* szUsuario: nombre del usuario (Opcional)
* szContraseña: contraseña del usuario (Opcional)

> **Nota**: si hemos configurado en el DSN el resto de parámetros requeridos para la conexión, no es necesario cumplimentar los parámetros opcionales.

### Funciones de estado

#### Boolean isActive() <a href="#isactive" id="isactive"></a>

Devuelve true si la sentencia SQL continúa en ejecución, false si no es así.

#### Boolean isForwardOnly() <a href="#isforwardonly" id="isforwardonly"></a>

Devuelve true si sólo es posible navegar hacia adelante por los resultados, false si no es así.

#### Boolean isOpen() <a href="#isopen" id="isopen"></a>

Devuelve true si la conexión con la base de datos ya está establecida, false si no es así.

### Funciones de sentencias SQL

#### Boolean executeSQL( String szSQL, Boolean bForwardOnly ) <a href="#executesql" id="executesql"></a>

Ejecuta la sentencia SQL contra la base de datos. Retorna true si ha podido ejecutar la sentencia de forma correcta y false si ha habido algún error.

Parámetros:

* szSQL: sentencia SQL
* bForwardOnly: determina que se sólo se avanzará en los resultados

#### Variant getColumn( int nNumCol ) <a href="#getcolumn" id="getcolumn"></a>

Devuelve el valor de la columna cuyo index pasamos como parámetro.

Parámetros:

* nNumCol: index de la columna

#### Variant getColumn( String szNombreCol )

Devuelve el valor de la columna cuyo nombre pasamos como parámetro.

Parámetros:

* szNombreCol: nombre de la columna

#### Number getColumnCount() <a href="#getcolumncount" id="getcolumncount"></a>

Devuelve el número de columnas obtenidas en la sentencia SQL.

#### String getColumnName( Number nNumCol) <a href="#getcolumnname" id="getcolumnname"></a>

Devuelve el nombre de la columna cuyo index pasamos como parámetro.

Parámetros:

* nNumCol: index de la columna

#### String getLastError() <a href="#getlasterror" id="getlasterror"></a>

Devuelve el último mensaje de error generado.

#### void goAfterLastRecord() <a href="#goafterlastrecord" id="goafterlastrecord"></a>

Avanza hasta el final de la lista resultante.

#### Boolean goBeforeFirstRecord() <a href="#gobeforefirstrecord" id="gobeforefirstrecord"></a>

Vuelve al principio de la lista resultante.

#### Boolean nextRegister() <a href="#nextregister" id="nextregister"></a>

Avanza al siguiente registro.

#### Number numRows() <a href="#numrows" id="numrows"></a>

Retorna el número de filas afectadas por la sentencia SQL que hemos ejecutado, si la base de datos externa lo admite, lo que no sucede para todos los casos.

> **Nota**: en el caso de una SELECT debemos usar el retorno de la función nextRegister() para saber si debemos seguir recorriendo la lista resultante ya que generalmente no se retorna número de registros afectados.

### Funciones de tablas

#### Array tables( int nTipo ) <a href="#tables" id="tables"></a>

Devuelve un array con los nombres de las tablas que tiene la base de datos en función del tipo que indicamos como parámetro.

Parámetros:

* nTipo: ver enum de tipos de tabla

### Funciones de campos

#### Number fieldCount( String szTabla ) <a href="#fieldcount" id="fieldcount"></a>

Devuelve el número de campos que tiene la tabla cuyo nombre pasamos como parámetro.

Parámetros:

* szTabla: nombre de la tabla

#### String fieldDefaultValue( String szTabla, Number nIndex ) <a href="#fielddefaultvalue" id="fielddefaultvalue"></a>

#### Boolean fieldIsAutoValue( String szTabla, Number nIndex ) <a href="#fieldisautovalue" id="fieldisautovalue"></a>

Devuelve true si el campo tiene valor automático (auto-incremento)

Parámetros:

* szTabla: nombre de la tabla
* nIndex: posición de la parte del índice

#### Number fieldLength( String szTabla, Number nIndex ) <a href="#fieldlength" id="fieldlength"></a>

Devuelve la longitud del campo.

Parámetros:

* szTabla: nombre de la tabla
* nIndex: posición de la parte del índice

> **Nota**: en función del driver utilizado, la información que devuelve puede resultar distinta. Por ejemplo, un campo de tipo VARCHAR en MySQL se muestra con la longitud definida en la base de datos a través del driver ODBC, el tamaño de la cadena, pero a través del driver nativo la longitud retorna el número de bytes que ocupa. Por ejemplo: si es latin1 será del mismo tamaño, pero si es utf-8 será del triple, ya que este formato permite cadenas de hasta 3 bytes por carácter.

#### String fieldName( String szTabla, Number nIndex ) <a href="#fieldname" id="fieldname"></a>

Devuelve el nombre del campo.

Parámetros:

* szTabla: nombre de la tabla
* nIndex: posición de la parte del índice

#### Number fieldPrecision( String szTabla, Number nIndex ) <a href="#fieldprecision" id="fieldprecision"></a>

Devuelve la precisión del campo cuando es de tipo numérico.

Parámetros:

* szTabla: nombre de la tabla
* nIndex: posición de la parte del índice

#### Number fieldType( String szTabla, int nIndex ) <a href="#fieldtype" id="fieldtype"></a>

Devuelve el tipo de campo.

Parámetros:

* szTabla: nombre de la tabla
* nIndex: posición de la parte del índice

Ver enum para los tipos de campo.

> **Nota**: en función del driver utilizado, la información puede mostrarse distinta. Por ejemplo, un campo de tipo VARCHAR en MySQL se muestra como VSqlDatabase.String a través del driver ODBC, pero a través del driver nativo se muestra como VSqlDatabase.ByteArray cuando el cotejamiento está establecido como UTF-8Bin, por ejemplo.

### Funciones de índice primario

#### Number primaryIndexFieldCount( String szTabla ) <a href="#primaryindexfieldcount" id="primaryindexfieldcount"></a>

Retorna el número de campos que componen el índice primario de la tabla que pasamos como parámetro.

Parámetros:

* szTabla: nombre de la tabla

#### String primaryIndexFieldName( String szTabla, int nIndex ) <a href="#primaryindexfieldname" id="primaryindexfieldname"></a>

Devuelve el campo de la parte del índice primario de la tabla cuyo nombre pasamos como parámetro.

Parámetros:

* szTabla: nombre de la tabla
* nIndex: posición de la parte del índice

#### String primaryIndexName( String szTabla ) <a href="#primaryindexname" id="primaryindexname"></a>

Devuelve el nombre del índice primario de la tabla cuyo nombre pasamos como parámetro.

Parámetros:

* szTabla: nombre de la tabla

## Ejemplos

### Ejemplo de lectura de base de datos

```javascript
importClass( "VSqlDatabase" );

// Importación de datos
function importDB(odbcdriver, odbcdsn, usuario, contraseña, servidor, puerto, opciones )
{
    var bdExterna = new VSqlDatabase();


    if ( bdExterna )
    {
        bdExterna.configure( odbcdriver, odbcdsn, opciones, servidor, puerto );
        var bOpen = bdExterna.open( usuario, contraseña );

        if ( bOpen )
        {
            var aszTablas = bdExterna.tables( 1 ); // Todas las tablas visibles para el usuario

            if ( aszTablas.length )
            {
                // Recorremos las tablas
                for (var i=0 ; i < aszTablas.length ; ++i)
                {    
                    var szTabla = aszTablas[i];

                    bdExterna.executeSQL( "select * from `" + szTabla + "`" );

                    // Obtenemos las cabeceras
                    var aszColumnas = [];
                    var nCampos = bdExterna.fieldCount( szTabla );

                    for (var nColumna=0; nColumna < nCampos; ++nColumna )
                        aszColumnas[nColumna] = bdExterna.getColumnName(nColumna).toUpperCase();

                    //  Contendrá los datos de la tabla
                    var tablaDatos = [];

                    // Recorremos los registros obtenidos en la búsqueda
                    while ( bdExterna.nextRegister() )
                    {    
                        var registro = {}

                        // Asignamos cada campo
                        for ( var nColumna=0; nColumna < nCampos; ++nColumna )
                            registro[aszColumnas[nColumna]] = bdExterna.getColumn( nColumna )

                        // Guardamos la información del registro
                        tablaDatos.push( registro );                    
                    }
                }
            }
            else
            {
                alert( "No se han encontrado tablas. " + bdExterna.getLastError() );
                return false;
            }    

            // Cerramos la conexión
            bdExterna.close();
        }
        else
        {
            alert( "No se ha podido abrir la base de datos. " + bdExterna.getLastError() );
            return false;
        }
    }
    else
    {
        alert( "No se ha podido conectar la base de datos. " + bdExterna.getLastError() );
        return false;
    }

    return true;
}
```