Construir um Serviço RESTful no CICS com PHP

Página 2 de 10  Opções de documento Código de amostra Classificar este tutorial Ajude-nos a melhorar este conteúdo

Configurando o Aplicativo Library no CICS

Esta seção descreve as tarefas administrativas necessárias para instalar o aplicativo LIBRARY de amostra no CICS, e descreve o uso da interface de COMMAREA para o programa a partir de um cliente. Esta interface é necessária para gravar um script PHP que acessa o programa.

Etapas para Configurar o Aplicativo Library

O aplicativo Library requer a criação e preenchimento de um arquivo VSAM e a compilação de um programa COBOL. Também são necessárias definições de recursos do CICS para o arquivo e programa. Estas etapas são descritas mais detalhadamente a seguir. É presumido algum conhecimento de procedimentos de configuração do CICS.

Não é fornecido nenhum mecanismo para invocar o programa LIBRARY, exceto através do PHP, conforme descrito posteriormente neste artigo, embora seja possível desenvolver um. Portanto, há uma oportunidade limitada para verificar a instalação correta do Arquivo e do Programa, e por isso, as instruções de configuração sugerem que o arquivo seja aberto e o programa carregado manualmente usando CEMT para verificar estas definições.

Criando e Definindo o Arquivo VSAM

O programa de biblioteca de exemplo requer um VSAM KSDS para manter o conteúdo do catálogo da biblioteca. O arquivo library/jcl/LIBFILE no archive de código fornecido contém uma JCL de amostra para excluir e recriar o conjunto de dados necessário, e preenchê-lo com dados iniciais apropriados. Esta JCL precisa ser transferida para um local apropriado no sistema z/OS® , e modificada da seguinte forma:

• Substitua o cartão de TAREFA para seu ambiente.
• Substitua todas as instâncias do nome do conjunto de dados (P8BUILD.CICS650.LIBRARY.LIBFILE) por um nome do conjunto de dados apropriado para seu sistema. O nome escolhido é necessário posteriormente para a definição de FILE CICS.
• Opcionalmente, edite os dados iniciais para a biblioteca, tomando cuidado para preservar a consistência e integridade (consulte a nota abaixo).

As etapas a seguir concluem a criação e definição do arquivo VSAM:

1. Submeta a LIBFILE JCL conforme modificada acima, e verifique se a execução foi bem-sucedida.
2. Efetue login no CICS e crie uma definição de CICS FILE usando CEDA (ou outro mecanismo) com os seguintes atributos:
   
   Tabela 1. Atributos a serem usados ao criar a definição de VSAM FILE
   
   

   Atributo	Valor
   FILE	LIBFILE
   GROUP	LIBRARY
   DSName	<Conforme especificado em LIBFILE JCL>
   RECORD FORMAT	F
   ADD	Yes
   BROWSE	Yes
   DELETE	Yes
   READ	Yes
   UPDATE	Yes

   
   
   
3. Instale a definição de LIBFILE e verifique se foi bem-sucedida.
4. Opcionalmente, usando CEMT ou, de outra maneira, abra LIBFILE e verifique se ele foi aberto com êxito:

   CEMT SET FILE(LIBFILE) OPEN

   
   

   Esta etapa é sugerida para verificar se o arquivo foi criado e definido corretamente, porque é possível a verificação limitada da configuração.

Compilando e Definindo o Programa COBOL

O código de origem para o aplicativo LIBRARY está no arquivo library/cobol/LIBRARY, e a JCL de amostra para compilá-lo está no arquivo library/jcl/LIBCOBOL, ambos no arquivo archive de código de amostra fornecido com este artigo. Estes arquivos devem ser transferidos para locais apropriados em seu sistema z/OS e a LIBCOBOL JCL deve ser modificada conforme descrito a seguir. A versão fornecida é a seguinte:

//LIBCOBOL JOB USER=P8BUILD,CLASS=A,MSGCLASS=A,NOTIFY=&SYSUID
// JCLLIB ORDER=CTS320.CICS650.SDFHPROC
//COMPCOB EXEC DFHZITCL,
//        PROGLIB=P8BUILD.CICS650.LOAD,
//        LNGPRFX=PP.COBOL390.V340,
//        CBLPARM=('NODYNAM,LIB,ADATA,RENT',  COMPILER OPTIONS
//          'CICS(''COBOL2,SP'')'),       TRANSLATOR OPTIONS
//        INDEX=CTS320.CICS650,
//        LIBPRFX=PP.ADLE370.ZOS190,
//        DSCTLIB=P8BUILD.CICS650.COPY
//COBOL.SYSIN  DD DSN=P8BUILD.CICS650.COBOL(LIBRARY),DISP=SHR
//COBOL.SYSADATA DD DSN=P8BUILD.CICS650.COBADATA(LIBRARY),
//        DISP=SHR
//LKED.SYSIN DD *
   NAME LIBRARY(R)
/*

As mudanças necessárias são as seguintes:

• Forneça um cartão de TAREFA apropriado.
• Altere todos os nomes e prefixos do conjunto de dados conforme apropriado para a instalação do z/OS e do CICS.
• Certifique-se de que a definição de COBOL.SYSADATA DD aponte para um membro de um PDS com registros de comprimento variável, que seja apropriado para conter a saída ADATA. Consulte a documentação do compilador COBOL para obter detalhes adicionais.

As etapas a seguir concluem a compilação e instalação do programa LIBRARY:

1. Submeta a LIBCOBOL JCL conforme modificada acima, e verifique se a execução foi bem-sucedida.
2. Efetue login no CICS e crie uma definição de CICS PROGRAM usando CEDA (ou outro mecanismo) com os seguintes atributos:
   
   Tabela 2. Atributos de CICS PROGRAM
   
   

   Atributo	Valor
   PROGRAM	LIBRARY
   GROUP	LIBRARY
   Language	COBOL

   
   
   
3. Instale a definição do programa LIBRARY e verifique se foi bem-sucedida.
4. Opcionalmente, usando CEMT ou, de outra maneira, execute NEWCOPY no programa LIBRARY e verifique se ele é carregado:

   CEMT SET PROGRAM(LIBRARY) NEWCOPY

   
   

   Esta etapa é sugerida para verificar se o programa foi compilado e definido corretamente, porque é possível uma verificação limitada da configuração.

Como Usar o Aplicativo COBOL Library

A convenção para um programa CICS COMMAREA é que, quando ele é invocado, uma área de armazenamento é passada para o programa contendo dados de entrada, às vezes, incluindo uma indicação da operação que deve ser executada. Na conclusão do processamento, a área de armazenamento é sobrescrita com dados de saída e códigos de resposta da operação. O formato da área de armazenamento de COMMAREA geralmente é definido em um COBOL copybook, que está incluído no programa de destino e em seus responsáveis pela chamada.

Para usar um programa CICS desse tipo, é necessário não apenas conhecer o formato de COMMAREA esperado pelo programa para entrada e saída, mas também as operações suportadas e os dados de entrada e saída e códigos de resposta esperados. No CA1S, a tarefa de construir e interpretar a estrutura de dados de COMMAREA é executada pelas classes de registro geradas pelo JZOS. No entanto, o programador de PHP é responsável por configurar os campos necessários na entrada e por extrair os dados apropriados na saída, usando as APIs geradas pelo JZOS.

O aplicativo Library de exemplo fornecido segue este modelo padrão e, portanto, o programador de PHP precisa de detalhes do uso da interface de COMMAREA, além das classes de registro do JZOS geradas, para invocar o programa Library corretamente a partir de um script PHP.

Formato de COMMAREA de Library

O formato de COMMAREA usado pelo programa de biblioteca é definido pela seguinte definição de dados COBOL:

      01 DFHCOMMAREA. 
     *    LIBRARY COMMAREA structure
          03 LIB-REQUEST-TYPE          PIC X(6). 
          03 LIB-RETURN-CODE           PIC 9(2). 
          03 LIB-ITEM-COUNT            PIC 9(4). 
          03 LIB-BOOK-ITEM OCCURS 24 TIMES. 
              05 BOOK-ITEM-REF          PIC 9(4). 
              05 BOOK-TITLE             PIC X(20). 
              05 BOOK-AUTHOR            PIC X(20). 
              05 BOOK-LOAN-STATUS       PIC 9(2). 
                 88 BOOK-ONLOAN VALUE 1.
                 88 BOOK-UNLENT VALUE 0.
              05 BOOK-BORROWER          PIC X(20). 
              05 FILLER                 PIC X(14).

A ferramenta do gerador de registro do JZOS, descrita posteriormente, converte a definição mostrada na Listagem 2 em APIs que podem ser usadas a partir do PHP para obter e configurar campos na COMMAREA. Há um mapeamento intuitivo entre os nomes de campos usados em COBOL e os métodos de PHP para que estes possam estar relacionados uns com os outros.

Uso do Programa Library

Somente o conhecimento do formato de COMMAREA esperado pelo programa CICS de destino é insuficiente para permitir que o programa seja invocado corretamente. Também é necessário ter informações de uso para o programa, por exemplo, quais operações são suportadas pelo programa, como isto é especificado na COMMAREA, e as outras entradas e saídas para cada operação, juntamente com possíveis resultados e respostas. Estas informações de uso para o programa de biblioteca são fornecidas na Tabela 3 para referência.

Como os scripts PHP de amostra para chamar o aplicativo de biblioteca são fornecidos com este artigo, não é necessário usar estas informações para a configuração inicial, mas elas são necessárias para entender, modificar ou reimplementar os scripts.

LIB-REQUEST-TYPE é um campo de texto de 6 caracteres que determina a operação a ser executada pelo programa Library, e deve ser configurado como um dos seguintes valores antes de chamar o programa:

Na devolução, o programa Library configura LIB-RETURN-CODE como um valor numérico de dois dígitos, dependendo do resultado da operação solicitada:

Os tipos de pedidos e códigos de retorno disponíveis são definidos em uma seção de dados de nível 01 (LIBRARY-CONSTANTS) no programa de biblioteca, o que significa que eles podem ser disponibilizados para um script PHP usando o gerador de registro do JZOS, de forma semelhante à seção de dados de COMMAREA.

Em geral, o programador de PHP precisará de informações equivalentes às informações da Tabela 4 para cada programa CICS a ser chamado a partir do PHP e, geralmente, elas serão fornecidas em um formato apropriado pelo programador do CICS responsável por manter o programa.

Voltar para parte superior

	Página 2 de 10