Executar comandos CL do IBM i a partir de um shell SSH/PASE: system, qsh e armadilhas de CCSID

Objetivo

Executar um comando CL do IBM i a partir de uma sessão SSH no PASE (Portable Application Solutions Environment), capturar de forma confiável a saída e o status de saída e evitar surpresas com EBCDIC/ASCII.

Pré-requisitos

• Acesso SSH ao sistema IBM i (SSHD iniciado; para a inicialização automática, veja o artigo sobre software de código aberto no IBM i).
• Saber se o comando CL de destino gera saída em spool, uma mensagem de escape ou texto simples.

Passos

1. Em uma chamada SSH não interativa, execute um único comando CL com o utilitário system do PASE, passando o comando CL entre aspas como uma única string:

   ssh -T user@ibmi-host 'system "DSPMSG QSYSOPR"'
   

   system é o utilitário do PASE para invocar comandos do IBM i. Por padrão, a saída em spool que o comando produz e as mensagens que ele envia são gravadas na saída padrão ou no erro padrão, que o SSH repassa ao shell chamador, e system termina com código diferente de zero quando o comando CL termina com uma mensagem de escape.
2. Para um comando que exige especificamente o ambiente Qshell (QSH) (alguns utilitários, como o db2 do Qshell, existem apenas lá), execute-o de forma não interativa com system "QSH CMD('...')" (QSH é um alias de STRQSH), em vez de abrir uma sessão Qshell interativa, que não é adequada para chamadores não supervisionados.
3. Capture o status de saída a partir do $? do shell depois que a chamada ssh retornar. No caso de QSH CMD(...), o Qshell também envia a mensagem QSH0005 quando o processo do comando termina normalmente, com o respectivo status de saída, e QSH0006 se ele terminou por sinal. Definir a variável de ambiente QIBM_QSH_CMD_ESCAPE_MSG como Y transforma uma saída diferente de zero em uma mensagem de escape, de modo que system (e os chamadores CL) percebam a falha; consulte o job log se $? sozinho for ambíguo.
4. Antes de confiar byte a byte na saída de texto, confirme o CCSID do job (DSPJOB OPTION(*DFNA) mostra o conjunto de caracteres codificados e o CCSID padrão). Jobs CL trabalham em EBCDIC; o PASE é baseado em ASCII. Os utilitários system e Qshell convertem os dados na entrada, na saída e no erro padrão, e um CCSID de job igual a 65535 ("sem conversão", o valor de QCCSID na instalação padrão) é uma causa frequente de caracteres corrompidos. Arquivos dentro de QSYS.LIB não podem ser criados com um CCSID ASCII pelo sistema de arquivos integrado (IFS); por isso, dados lidos diretamente de QSYS.LIB com uma ferramenta do PASE, como cat, chegam no CCSID EBCDIC do membro e precisam de conversão explícita.

Resultado esperado

A saída de um único comando e um código de saída/retorno confiável, sem abrir uma sessão 5250 ou Qshell interativa a cada chamada.

Limites e base de verificação

O comportamento descrito aqui segue as páginas do IBM Support citadas, escritas para versões IBM i 7.x; verifique os IDs de mensagem e os padrões exatos na versão de destino antes de depender deles em um pipeline não supervisionado. Não se alega nenhum experimento ou medição.