Qué es QSH o Qshell y cómo sacarle partido en IBM i

Si trabajas con IBM i (el antiguo AS/400) tarde o temprano te encontrarás con QSH o Qshell, el intérprete de comandos tipo Unix que viene integrado en el sistema. Mucha gente lo ha visto de pasada, sobre todo al pelearse con el IFS o con tareas de WebSphere, pero no siempre se tiene claro qué es exactamente ni hasta dónde puede llegar.

En este artículo vamos a desgranar con calma qué es QSH/Qshell, para qué sirve en IBM i y cómo puede ayudarte tanto en automatización de tareas (por ejemplo, listar ficheros del IFS y volcarlos a un archivo físico) como en escenarios más complejos donde entran en juego Java, WebSphere o incluso iSeries Access for Web. Lo haremos con un lenguaje cercano, sin rollos teóricos innecesarios, pero entrando al detalle técnico para que de verdad te resulte útil.

Qué es QSH o Qshell en IBM i

Cuando hablamos de QSH o Qshell nos referimos al intérprete de órdenes tipo shell POSIX que IBM incluye en IBM i. Es, dicho pronto y mal, un “shell al estilo Unix” que vive dentro del sistema y que te permite lanzar comandos muy similares a los que usarías en Linux (como ls, cd, etc.) sobre el entorno de IBM i.

Este entorno forma parte de lo que IBM denomina i5/OS PASE (Portable Application Solutions Environment), una capa que proporciona utilidades y programas compatibles con estándares POSIX y X/Open. Gracias a PASE, Qshell puede ofrecer un conjunto bastante amplio de herramientas que se comportan de forma muy parecida a lo que encontrarías en un sistema Unix clásico.

En la práctica, Qshell actúa como puente entre el mundo tradicional de IBM i (bibliotecas, archivos físicos, CL) y el mundo más “moderno” o abierto de directorios, rutas del IFS y comandos estilo Unix. Esto abre la puerta a soluciones muy flexibles, sobre todo cuando mezclas comandos shell con programas CL o RPG.

Es importante tener claro que Qshell no es un juguete ni una curiosidad: se integra profundamente con IBM i y se apoya en las APIs del sistema. De hecho, muchas utilidades del propio IBM i o de productos asociados (como WebSphere o herramientas Java) funcionan sobre PASE, aprovechando ese mismo ecosistema.

QSH dentro del entorno i5/OS PASE

El entorno PASE es el responsable de ofrecer en IBM i programas que siguen estándares POSIX y X/Open. Qshell, como intérprete POSIX, forma parte de este conjunto y se beneficia de todas las librerías y herramientas que PASE pone a disposición.

Cuando arrancas Qshell, estás lanzando un intérprete que ejecuta comandos y programas como si estuvieras en un pequeño Unix dentro de IBM i. Esto incluye cosas tan básicas como trabajar con rutas del IFS mediante “/directorio/subdirectorio”, usar tuberías, redirecciones y scripts sencillos.

IBM mantiene documentación bastante completa sobre Qshell y PASE en su IBM Knowledge Center. Si quieres ver todas las posibilidades, opciones de comandos y particularidades según la versión de sistema (por ejemplo V6.1), lo ideal es que consultes el manual de la versión exacta de IBM i que tengas instalada.

Además, dentro de este entorno se engancha también todo lo relacionado con Java, servidores de aplicaciones como WebSphere y utilidades asociadas. Muchas veces, cuando ves mensajes de error o avisos relacionados con QSH0006 o QSH0007, en el fondo están ocurriendo cosas en PASE o en Java que afectan al funcionamiento del shell o de los procesos que lanza.

Ejemplo práctico: listar archivos del IFS con QSH y CL

Uno de los usos más prácticos (y habituales) de Qshell en entornos IBM i reales es el de trabajar con el IFS para listar ficheros y volcar esa información a un archivo físico que luego podamos procesar desde CL, RPG u otros programas.

Imagina que tienes una carpeta del IFS, por ejemplo /FTP, donde se van depositando ficheros con extensión .cbs. Quieres obtener, en un archivo físico de una librería, la relación completa de todos esos archivos, incluso de los que estén en subdirectorios, para poder tratarlos después uno a uno.

Una forma muy sencilla de hacerlo es combinando unas pocas sentencias CL con un comando Qshell que use la orden ls -R para listar recursivamente. La idea es:

1. Crear un archivo físico donde vas a volcar el resultado:

CRTPF FILE(LIBRERIA/ARCHIVO) RCDLEN(1024)

Con esto generas un PF con registro suficientemente grande (por ejemplo, 1024 bytes de longitud) donde se guardará cada línea devuelta por el comando ls que lance Qshell. Si el archivo ya existiera, podrías controlar el error con un MONMSG para que no reviente el proceso.

A continuación puedes añadir:

MONMSG MSGID(CPF0000)

De esta forma, si la creación del archivo falla por cualquier motivo, atrapas el mensaje genérico y puedes decidir qué hacer (aunque en el ejemplo básico simplemente se ignora el problema).

El siguiente paso es montar en una variable de CL el comando que quieres ejecutar en Qshell. Algo así:

2. Preparar el comando shell que quieres lanzar, por ejemplo:

CHGVAR VAR(&CMD) VALUE(‘ls -R /FTP/*.cbs > /qsys.lib/libreria.lib/archivo.file/archivo.mbr’)

Aquí ocurre lo interesante: estás diciendo que se ejecute ls -R sobre la ruta /FTP para listar todos los ficheros que cumplan el patrón *.cbs, y además rediriges la salida estándar al miembro ARCHIVO del archivo físico LIBRERIA/ARCHIVO usando la sintaxis del IFS /qsys.lib/…. Así, Qshell se ocupa de hacer la lista y volcarla directamente al PF.

Una vez definido el comando, solo falta lanzarlo dentro de Qshell:

3. Ejecutar el comando en Qshell con:

STRQSH CMD(&CMD)

El comando STRQSH inicia una sesión Qshell y ejecuta el contenido de la variable &CMD. Desde el punto de vista del usuario de CL, es una forma bastante cómoda de “abrir” el mundo POSIX durante un momento, hacer el trabajo y volver a CL.

Para rematar, puedes controlar posibles errores que lance Qshell con algo como:

MONMSG MSGID(CPF0000 QSH0006 QSH0007) EXEC(DO)
(TRATAMIENTO DE ERRORES)
ENDDO

De esta forma, si se produce un problema genérico del sistema (CPF0000) o alguno de los errores típicos de Qshell (QSH0006, QSH0007), entras en un bloque de tratamiento de errores donde podrías, por ejemplo, registrar el fallo, enviar un mensaje al operador o tomar decisiones según el código devuelto.

Si todo va bien, el intérprete Qshell habrá dejado en el archivo físico LIBRERIA/ARCHIVO la relación completa de ficheros .cbs encontrados, lista que luego podrás procesar desde otro programa CL o RPG. Este enfoque demuestra lo potente que resulta combinar CL tradicional con comandos Qshell para tareas puntuales que, de otro modo, serían bastante más engorrosas.

Posibilidades y potencia de Qshell más allá del ejemplo

El ejemplo anterior solo rasca la superficie: Qshell acepta un montón de parámetros y comandos, tanto propios como heredados del mundo Unix. En el caso de ls, puedes jugar con opciones como -R para recursividad, formatos de listado, filtros, etc. Pero eso es solo la parte más visible.

En general, Qshell te permite construir soluciones ligeras y puntuales a problemas del día a día: mover ficheros en el IFS, generar listados, concatenar salidas mediante tuberías, automatizar pequeñas tareas de mantenimiento, o incluso servir como capa intermedia entre procesos batch y aplicaciones externas.

Una ventaja enorme es que puedes invocar Qshell desde CL (con STRQSH), mezclarlo con comandos de sistema y mantener la lógica principal en programas de IBM i, mientras delegas en el shell las operaciones de estilo Unix que resulten más cómodas de escribir allí.

Si necesitas profundizar en todas las opciones disponibles, IBM ofrece documentaciones específicas para cada versión de sistema. En el IBM Knowledge Center de la versión 6.1, por ejemplo, encontrarás detalles de cada comando, sus parámetros, ejemplos de uso y notas sobre compatibilidad. Lo ideal es que consultes esa referencia para descubrir nuevas utilidades que quizá ya tienes instaladas y no estás aprovechando.

Hay que tener presente que Qshell no es la única opción de entorno tipo Unix en IBM i (existe también el entorno QP2TERM y el soporte de PASE más “puro”), pero sí es uno de los más accesibles para administradores y desarrolladores que vienen del mundo CL o RPG y quieren empezar a explotar el IFS y las herramientas POSIX sin demasiada complicación.

Escritura de scripts y parámetros en Qshell

Además de lanzar comandos sueltos, con Qshell puedes escribir tus propios scripts que se comportan de forma similar a los de un shell clásico. Estos scripts pueden recibir parámetros, utilizar variables y componer comandos dinámicamente, lo que te permite automatizar tareas repetitivas sin rehacer el código cada vez.

En un script Qshell, los argumentos que recibe se asignan a variables especiales: $1 para el primer parámetro, $2 para el segundo, y así hasta un máximo de 255 parámetros. Es decir, cuando ejecutas un script pasando varios valores, dentro del propio script puedes usarlos para construir rutas, nombres de archivo o cualquier otra cosa que necesites.

Por ejemplo, podrías tener un script que reciba como primer parámetro el nombre de un comando a ejecutar y que lo muestre antes de lanzarlo. Algo tan sencillo como:

echo $1
$1 # ejecuta la orden contenida en el primer parámetro

Este pequeño ejemplo ilustra cómo un script puede actuar como “envoltorio” de otros comandos, añadiendo lógica adicional (por ejemplo, validaciones o trazas) antes de ejecutar la orden real.

Para asignar valores a los parámetros dentro del script, puedes usar el comando set. Por ejemplo:

set v1 v2 # asigna v1 a $1 y v2 a $2

Así, sin necesidad de llamar de nuevo al script desde fuera, puedes reorganizar los valores que vas a manejar internamente. Esto es útil cuando quieres, por ejemplo, redefinir el orden de los argumentos o preparar valores por defecto.

Otro comando interesante es shift, que desplaza los parámetros hacia la izquierda: $1 desaparece, $2 pasa a ser $1, $3 se convierte en $2, y así sucesivamente. Es una técnica clásica en scripting para recorrer listas de argumentos uno tras otro, quitando el primero cada vez que lo procesas.

Además, dispones de la variable $0, que contiene el nombre del script en sí. Esto te permite, por ejemplo, mostrar mensajes de ayuda que incluyan el nombre real del script sin tener que escribirlo a mano o adaptar el comportamiento según cómo haya sido invocado.

En conjunto, estas posibilidades convierten a Qshell en una herramienta muy flexible para montar pequeños automatismos que trabajan sobre el IFS, llaman a comandos del sistema o integran procesos de IBM i con aplicaciones de fuera.

Relación de Qshell con WebSphere, Java y uso de memoria

Aunque Qshell se vea muchas veces solo como un intérprete de comandos para el IFS, en la realidad del día a día en IBM i aparece también muy ligado al entorno Java y a servidores de aplicaciones como WebSphere. Esto se nota sobre todo cuando empiezan a aparecer mensajes de sistema relacionados con uso de memoria o heap de Java.

En entornos donde se utiliza iSeries Access for Web (IWA), desplegado sobre WebSphere (por ejemplo un WAS 6.1), es habitual encontrarse con mensajes del tipo:

JAVA USED 95% OF THE GC HEAP.
USED HEAP SIZE(KB) AND MAX HEAP(KB): 249049 262144.

Este tipo de avisos suelen originarse en el servidor WebSphere (no directamente en Qshell), pero pueden ir acompañados de mensajes relacionados con PASE o con procesos que se lanzan desde o hacia Qshell. En esencia, lo que te está diciendo el sistema es que la JVM está muy cerca de agotar la memoria de heap, y que conviene ajustar la configuración antes de que el servidor caiga con un error OutOfMemory.

IBM introdujo este tipo de mensajes precisamente para que el administrador tenga un aviso previo antes de que el servidor de aplicaciones se venga abajo. De esta manera, cuando recibes estos avisos repetidos es un síntoma claro de que debes revisar los parámetros de heap máximo asignados a la JVM donde corre IWA o el portal asociado.

En algunos casos reales, administradores han detectado que, incluso con un portal aparentemente sin usuarios conectados, se seguían generando 2 o 3 mensajes de heap casi lleno al día. Esto suele deberse a procesos internos de la aplicación, tareas en segundo plano o fugas de memoria que mantienen vivo el uso de heap aunque no haya carga de usuarios.

Además, se han dado situaciones en las que resultaba difícil incluso acceder a la consola administrativa vía web para modificar parámetros como el tamaño mínimo y máximo de la JVM, porque determinados portlets fallaban (“petaban”) cuando intentabas abrir pantallas de configuración.

Una estrategia que se ha mostrado útil consiste en reiniciar completamente el entorno (servidor, WebSphere, portal, etc.), esperar a que todo vuelva a un estado estable, y entonces entrar a la consola administrativa para revisar la configuración de memoria. Hay casos en los que los campos de heap mínimo y máximo aparecían en blanco, confiando en valores por defecto, lo que no siempre es adecuado para entornos con cierta carga.

Tras conseguir acceder, algunos administradores han optado por definir, por ejemplo, un heap mínimo de 512 MB y un máximo de 1024 MB (simplemente como valores de prueba) para ver si el comportamiento del sistema mejora y se reducen los mensajes de aviso. Es importante, eso sí, adaptar estos valores a la memoria disponible en el propio IBM i y al tipo de carga que soporta el servidor.

En todo este contexto, aunque los mensajes específicos sobre “JAVA USED 95% OF THE GC HEAP” sean propios de WebSphere, el entorno PASE y Qshell pueden estar implicados indirectamente, ya que muchas herramientas y scripts lanzan procesos Java o interactúan con servicios desplegados en el mismo servidor.

Ajustes de WebSphere, IWA y versiones en IBM i V6R1

Cuando te enfrentas a problemas de rendimiento o memoria en entornos como iSeries Access for Web (IWA) sobre IBM i V6R1, es clave tener claros algunos puntos sobre versiones y compatibilidad con WebSphere, porque aquí es donde confluyen Qshell, PASE, Java y la configuración de servidores.

Para empezar, es recomendable comprobar qué versión exacta de iSeries Access for Web tienes instalada. Esto suele poder verificarse consultando la página especial /webaccess/iWAInfo que expone la propia aplicación. Desde ahí verás el nivel actual de IWA.

En el caso concreto de IBM i V6.1, ha existido una actualización importante identificada con el número de PTF SI44342, que corresponde a la última versión disponible para esa release. Mantener IWA actualizado a ese nivel (o al vigente en tu entorno) puede solucionar muchos problemas de estabilidad o memoria que se han ido corrigiendo con el tiempo.

Por otro lado, cuando se habla de “portal” en este contexto, conviene distinguir si te refieres exactamente a IWA (iSeries Access for Web) o a un WebSphere Portal completo. Aunque ambos pueden convivir en IBM i, su configuración y sus necesidades de memoria no son las mismas, y los síntomas de fallo (portlets que no cargan, mensajes de error, lentitud extrema) pueden confundirse si no se tiene claro qué producto estás tocando.

Un aspecto clave es sobre qué tipo de servidor está desplegado IWA: puede ser un WebSphere Application Server 6.1, 7.0, un portal o un servidor interno. Los parámetros de la JVM varían según el tipo de servidor, la versión concreta y también el tipo de máquina virtual Java utilizada (por ejemplo, la clásica “classic” o la J9 más moderna).

Cuando empiezas a ver constantemente mensajes de heap casi lleno, además de revisar los parámetros de memoria, conviene plantearse si no te falta aplicar PTF adicionales o incluso una actualización de versión del propio portal o de WebSphere. En IBM i V6R1 existe un límite hasta el que puedes subir de versión de iWAS, por lo que es recomendable verificar en la documentación oficial cuál es la combinación soportada más reciente para tu release.

Resumiendo esta parte: si tu entorno IBM i V6R1 con IWA 6.1 desplegado en WebSphere te empieza a dar guerra con la memoria, debes revisar en bloque configuración de heap, nivel de PTF de IWA, versión exacta de WebSphere y tipo de JVM. Solo así tendrás una foto completa del problema y podrás ajustar de forma adecuada sin limitarte a reinicios puntuales.

Todo esto se relaciona indirectamente con Qshell en el sentido de que, a través de scripts y comandos en el entorno PASE, puedes monitorizar procesos, lanzar tareas auxiliares o incluso automatizar operaciones de mantenimiento que ayuden a mantener el servidor en forma, desde la limpieza de ficheros en el IFS hasta la generación de listados de logs para análisis.

A lo largo de este recorrido hemos visto cómo Qshell se integra en IBM i como un intérprete POSIX que amplía las capacidades del sistema, permitiendo desde tareas tan sencillas como listar ficheros del IFS y volcar la salida a un archivo físico, hasta actuar como pieza más dentro de entornos complejos con Java y WebSphere. Aprovechar QSH pasa por entender bien su papel dentro de PASE, familiarizarse con comandos como ls, set o shift, y no tener miedo a combinarlo con CL y herramientas clásicas de IBM i; con ese enfoque, Qshell se convierte en un aliado muy potente tanto para el administrador como para el desarrollador que quiere exprimir al máximo la plataforma.