Controlador DB2 for i (AS/400)

Esta documentación explica la implementación del controlador DB2 for i y cómo los parámetros de conexión se corresponden con los campos de la interfaz de usuario en la aplicación Gigantic.

Parámetros de Conexión

En la lista de controladores aparece como DB2 iSeries. Qué campos se usan depende del modo de conexión.

Modos de Conexión

El controlador puede llegar al IBM i de cuatro formas. El modo se elige en el campo Modo de backend, en la sección General del formulario del tap o del sink, justo debajo de Driver. El campo solo aparece cuando el controlador es DB2 iSeries.

Los taps y sinks nuevos empiezan con JS400. Un datasource guardado sin modo, como uno creado antes de que existiera el campo, también usa js400. Una clave mode en Parámetros Personalizados tiene prioridad sobre el campo, porque los Parámetros Personalizados se aplican al final.

JS400

Es el modo por defecto. Gigantics habla directamente con el IBM i mediante js400, una adaptación a JavaScript de JTOpen, así que no hay que instalar nada en el host de Gigantics y no se carga ningún módulo nativo.

• Inicia sesión a través de los servidores de host del IBM i. Sus puertos se obtienen del port mapper (puerto 449); si el port mapper no responde, usa los puertos estándar, 8476 para el inicio de sesión y 8471 para el servidor de base de datos.
• El campo Puerto indica el puerto del servidor de host de base de datos, por ejemplo cuando escucha en un puerto propio. Si se deja en 446 (o 947), los puertos DRDA, o vacío, no se usa y el puerto lo obtiene el port mapper. El inicio de sesión siempre pasa por el port mapper o por el puerto 8476.
• Indica secure: true en Parámetros Personalizados para conectar con TLS (puertos estándar 9476 y 9471).
• Por defecto lee en bloques de 8.000 filas y escribe en lotes de 16.000 filas.

Elígelo salvo que tengas un motivo para usar otro modo.

ODBC

Gigantics se conecta a través del IBM i Access ODBC Driver con el módulo odbc de Node.js.

• El host de Gigantics necesita el IBM i Access ODBC Driver (de IBM i Access Client Solutions) registrado con el nombre IBM i Access ODBC Driver, un gestor de controladores ODBC (unixODBC en Linux) y el módulo odbc, que es una dependencia opcional de Gigantics. Si falta el módulo, las conexiones en este modo fallan.
• El controlador ODBC también llega al IBM i a través de los servidores de host y el port mapper. El controlador no tiene palabra clave de puerto, así que el campo Puerto no se usa: un valor distinto de 446, 8471 o 9471 solo deja un aviso en el log (ver Formato de Cadena de Conexión).
• Las palabras clave ODBC adicionales se indican en el Parámetro Personalizado connectionString.

Elígelo cuando tu organización ya usa el IBM i Access ODBC Driver y quiere que Gigantics pase por él.

IBM-DB

Gigantics se conecta con el módulo ibm_db, el controlador CLI de IBM, por DRDA al Puerto indicado (446 por defecto).

• Conectar desde Linux, Windows o macOS a DB2 for i con ibm_db requiere una licencia de DB2 Connect, igual que con DB2 for z/OS. Sin ella el servidor responde con SQL1598N. Ver Requisitos de Licencia DB2 z/OS.
• Las palabras clave CLI adicionales se indican en el Parámetro Personalizado connectionString.

Elígelo cuando solo se puede llegar al puerto DRDA del IBM i, por ejemplo a través de un túnel SSH, y tienes una licencia de DB2 Connect.

SSH

Gigantics abre una conexión SSH con el IBM i y hace el trabajo allí con mandatos del IBM i. No se instala nada en el host de Gigantics y no hace falta abrir ningún puerto de base de datos, solo SSH.

Al elegir este modo, el formulario cambia:

En el modo SSH no aparece la casilla de túnel ¿Habilitar SSH?. El usuario y la contraseña SSH son el Nombre de usuario y la Contraseña de la sección Autenticación.

Cómo funciona:

• El SQL (metadatos, DDL, lecturas filtradas) se ejecuta en una única sesión qsh -c "db2 -t -i" que se mantiene abierta mientras dura la conexión.
• Una tabla se lee en bloques de números relativos de registro: CPYF ... FROMRCD() TORCD() copia cada bloque a un fichero temporal en la misma librería (su nombre empieza por DB y se borra tras cada bloque), CPYTOIMPF lo exporta a un fichero CSV en la Ruta temporal remota, compress lo comprime y SFTP lo trae a Gigantics. El tamaño del bloque es batchSize (65.536 filas). Los bloques abarcan todos los registros del fichero, también los de filas borradas (NUMBER_ROWS más NUMBER_DELETED_ROWS de QSYS2.SYSTABLESTAT), así que se leen también las filas que hay después de las borradas. Un bloque que solo tiene filas borradas se salta.
• Una lectura con filtro, orden, selección de columnas o consulta personalizada se ejecuta en cambio como SQL en la sesión db2. Sus filas se pasan adelante a medida que la sesión las imprime, y la sesión se detiene mientras esperan a escribirse, así que el resultado no se guarda en memoria.
• Una carga escribe ficheros CSV en el host de Gigantics, los comprime, los sube por SFTP, ejecuta uncompress y los carga con CPYFRMIMPF.
• Una carga que vacía la tabla copia su primer lote con MBROPT(*REPLACE) y el resto con MBROPT(*ADD). Una carga append copia todos los lotes con MBROPT(*ADD), así que las filas que ya había en el fichero se conservan.
• Las cargas update y merge copian cada lote a un duplicado del fichero en QTEMP y ejecutan un MERGE desde él. Un update cambia solo las filas que ya existen; un merge además inserta las nuevas (WHEN NOT MATCHED THEN INSERT).
• Las fechas y horas se escriben en los formatos que CPYFRMIMPF lee por defecto: las columnas DATE como YYYY-MM-DD, las TIME como HH.MM.SS y las TIMESTAMP como YYYY-MM-DD-HH.MM.SS.ffffff. Un valor con zona horaria se escribe en UTC.

En el IBM i, el usuario necesita:

• el servidor SSH en marcha y un shell que pueda ejecutar qsh, db2, system, compress y uncompress;
• autoridad para crear y borrar ficheros en la librería que se lee (CPYF ... CRTFILE(*YES) y DLTF) y para ejecutar CPYTOIMPF y CPYFRMIMPF;
• permiso de escritura en la Ruta temporal remota.

Elígelo cuando el IBM i solo tiene SSH abierto.

Diferencias entre Modos

En el modo SSH las tablas se leen con un único cursor y se cargan de una vez. Ver Tablas Grandes y Reanudación.

Detalles Técnicos

El controlador DB2 for i elige una de cuatro implementaciones al conectar, según el modo de conexión: js400 (por defecto), odbc, ibmdb o ssh.

Aspectos técnicos clave:

• El agrupamiento de conexiones se soporta mediante la bandera pooled en la configuración (en todos los modos salvo ssh)
• La selección de esquema/librería es crítica y afecta a toda la generación de consultas
• El controlador utiliza tablas del sistema QSYS2 para la extracción de metadatos (SYSTABLES, SYSCOLUMNS2, SYSINDEXES)
• La gestión de restricciones se implementa usando procedimientos del sistema como QSYS2.CREATE_CONSTRAINT_INFO
• Se soportan capacidades de registro (journaling) y bloqueo específicas de IBM i

Cuando el túnel SSH está habilitado, las conexiones se establecen primero a través del túnel antes de conectarse al servidor DB2 for i.

Formato de Cadena de Conexión

Solo los modos odbc e ibmdb construyen una cadena de conexión. El modo js400 pasa el host, el usuario, la contraseña y el puerto del servidor de host de base de datos a js400, y el modo ssh abre una sesión SSH.

En el modo odbc, con el IBM i Access ODBC Driver:

DRIVER={IBM i Access ODBC Driver};SYSTEM=[host];DATABASE=[database];CCSID=1208;UserID=[user];Password=[password];[connectionString]

La cadena ODBC no lleva puerto: el IBM i Access ODBC Driver no tiene palabra clave de puerto, y se conecta al servidor de host de base de datos (8471, o 9471 con TLS) que encuentra en la tabla de servicios o a través del port mapper. El campo Puerto no se usa; un valor distinto de 446, 8471 o 9471 deja un aviso en el log. DATABASE se omite cuando el campo Base de datos está vacío.

En el modo ibmdb, con ibm_db:

HOSTNAME=[host];DATABASE=[database];PORT=[port];CURRENTSCHEMA=[schema];UID=[user];PWD=[password];[connectionString]

DATABASE, PORT y CURRENTSCHEMA se omiten cuando están vacíos. En los dos modos, [connectionString] es el Parámetro Personalizado connectionString, añadido tal cual.

Opciones de Autenticación

DB2 for i soporta varios tipos de autenticación:

Soporte de Túnel SSH

El controlador DB2 for i soporta túneles SSH para acceso seguro a bases de datos detrás de firewalls o en redes privadas. Para información detallada sobre la configuración de túneles SSH, por favor consulte la documentación de Túneles SSH.

El túnel reenvía un único puerto, el del campo Puerto. Solo el modo ibmdb se conecta únicamente por ese puerto, así que usa el túnel con IBM-DB. El modo js400 se conecta al servidor de base de datos por ese puerto, pero inicia sesión a través del port mapper y del servidor de inicio de sesión, que el túnel no reenvía. El modo odbc no tiene puerto que indicar. En el modo ssh la opción de túnel no aparece: la conexión ya es SSH.

Endpoints de API Utilizados

Las conexiones DB2 for i se utilizan principalmente en:

• Creación de Tap (descubrimiento de fuente de datos)
• Creación de Sink (destino de datos para datos anonimizados)
• Ejecución de Pipeline (extracción y carga de datos)

Tablas Grandes y Reanudación

Esta sección recoge solo lo propio de DB2 for i. Cómo funcionan la reanudación, los rangos paralelos y las estimaciones de filas en todos los controladores se explica en Bases de datos grandes.

El controlador funciona en uno de los cuatro modos descritos en Modos de Conexión: js400 (por defecto), odbc, ibmdb y ssh. Lo que sigue vale para js400, odbc e ibmdb. En el modo ssh (ficheros CSV por SFTP) las tablas se leen con un único cursor y se cargan de una vez, así que no se reanudan ni se dividen en rangos.

Lectura

• Las tablas se leen por bloques ordenados por la clave primaria (de QSYS2.SYSCST), de modo que un job que se detiene se reanuda tras la última clave que guardó. Un fichero sin restricción de clave primaria se lee con un único cursor y empieza de nuevo si el job se detiene: no se usa el número relativo de registro.
• Todas las columnas de la clave primaria deben ser SMALLINT, INTEGER, BIGINT o de texto. No se usa una clave con alguna columna DECIMAL o NUMERIC, habituales en ficheros físicos antiguos, aunque no tenga decimales.

Rangos Paralelos y Estimación de Filas

• Solo se cortan rangos para una clave de una única columna entera, repartida a partes iguales entre su mínimo y su máximo.
• No hay estimación de filas en vivo: el número de filas guardado en el modelo (NUMBER_ROWS de QSYS2.SYSTABLESTAT cuando se escaneó) decide cuántos rangos se cortan. Vuelve a escanear el modelo cuando una tabla crezca mucho.
• En los modos js400 e ibmdb, las cargas update y merge preparan las filas en una tabla de sesión, así que una tabla que se carga en DB2 for i por update o merge se lee en un único flujo.

Carga

• Durante la carga, las restricciones de los ficheros que las tienen se desactivan con CHGPFCST ... CST(*ALL) STATE(*DISABLED) y se vuelven a activar con STATE(*ENABLED) al terminar. No se anotan: si un job muere, siguen desactivadas hasta que termine otra carga de esos ficheros o se activen a mano.
• Los triggers siguen activos.
• En los modos js400 e ibmdb, las cargas update y merge comparan todas las columnas de una clave primaria compuesta.

Permisos

Para un sink DB2 for i, el usuario necesita autoridad para ejecutar CHGPFCST sobre los ficheros cargados mediante QSYS2.QCMDEXC.

Parámetros Personalizados

El controlador DB2 for i soporta parámetros personalizados adicionales que pueden especificarse en formato YAML para ajustar finamente el comportamiento de conexión, agrupamiento y otras opciones avanzadas. Cada modo lee sus propias claves; las claves que un modo no lee se ignoran.

Parámetros para Todos los Modos

mode: js400        # js400, odbc, ibmdb o ssh. Tiene prioridad sobre el campo Modo de backend
ddlTimeout: 30     # Segundos permitidos para extraer el DDL de una tabla
journal: MYLIB/MYJRN  # Journal con el que se inicia el registro de una tabla que se creó
                      # sin él (modos js400, ibmdb y ssh)

Parámetros del Modo JS400

secure: true       # Conectar con TLS
timeout: 60000     # Tiempo de espera de conexión en milisegundos
fetchSize: 8000    # Filas por bloque al leer
writeBatchSize: 16000  # Filas por lote al escribir
blockSize: 512     # Tamaño del bloque de lectura en KB
pooled: true       # Usar un grupo de conexiones (hasta 10)

Parámetros del Modo ODBC

connectionString: "BLOCKSIZE=512;COMPRESSION=1"  # Palabras clave añadidas a la cadena ODBC
connectParams:     # Opciones que se pasan al grupo de conexiones de odbc
  connectionTimeout: 30
  loginTimeout: 30
batchSize: 60000   # Filas por lote de lectura
writeBatchSize: 1000  # Filas por lote de escritura
pooled: true

Parámetros del Modo IBM-DB

connectionString: "SECURITY=SSL"  # Palabras clave añadidas a la cadena CLI
batchSize: 8000    # Filas por lote de lectura y de escritura
pooled: true

Parámetros del Modo SSH

batchSize: 65536     # Filas por bloque CPYF al leer y por fichero CSV al escribir
readBatchProcs: 1    # Bloques que se descargan a la vez
writeBatchProcs: 1   # Ficheros CSV que se suben y cargan a la vez

Ejemplos de Configuraciones

Configuración Básica

pooled: true

Configuración TLS (modo JS400)

secure: true

Configuración Avanzada con Optimización de Rendimiento (modo JS400)

fetchSize: 16000
writeBatchSize: 16000
blockSize: 512
ddlTimeout: 300
pooled: true