Macros Adabas

Document Sample
Macros Adabas Powered By Docstoc
					Índice
1.       Conceitos                                                                       2
2.       Visão Geral da Macros ADABAS                                                    3
3.       Sintaxe                                                                        11
4.       Convenções                                                                     11
5.       Palavras Reservadas                                                            11
6.       Macros Declarativas                                                            11
7.       Identificação do Usuário USERID / Programa                                     12
8.       Definição de Dados                                                             12
9.       Tipos de ARQ                                                                   13
10.      GRP                                                                            13
11.      CPO                                                                            14
12.      CNT                                                                            18
13.      SUP (SP, |sa|)                                                                 18
14.      Tratamento de Erros                                                            19
14.1.    Erro                                                                           19
14.2.    %@ROTER = ‘myrot’                                                              20
15.      Macros ADABAS                                                                  20
15.1.     ABRIR                                                                         20
15.2.     FECHAR                                                                        20
15.3.     TODOS                                                                         20
15.4.     PRIM                                                                          23
15.5.     Leitura em Seqüencia Lógica de um Descritor                                   23
15.6.     Leitura em Sequência Lógica de um Sub ou Superdescritor                       24
15.7.     Leitura em Sequência Física                                                   24
15.8.     OBTER                                                                         24
15.9.     PROX                                                                          25
15.10.    POR                                                                           25
15.11.    REPOR                                                                         25
15.12.    TIRAR                                                                         25
15.13.    RELCIDD                                                                       25
15.14.    ENDTRA                                                                        26
15.15.    BACTRA                                                                        26
15.16.    CHECKPOINT                                                                    26
15.17.    PARA                                                                          26
15.18.    HISTOGRAMA                                                                    27
15.19.    ERROHISTOGRAMA OHISTOGRAMA                                                    27
15.20.    Exemplo de Uso de Histograma                                                  28
15.21.    NOMEPGM                                                                       28
15.22.    Response Codes Emitidos pela Macro NOMEPGM                                    29
15.23.    Exemplo de Uso de NOMEPGM                                                     29
15.24.    Mecânica de HOLD Através das MACROS                                           29
16.       Processamentos Especiais                                                      30
16.1.     Lista de ISNS em que QTD > QMAX (RSP309)                                      31
16.2.     Uso de RELCID para Listas de ISNS onde QTD > QMAX                             31
16.3.     RESTART Usando ET-VAR                                                         31
16.4.     PRIM com "E" para CICS com RETURN TRANSID                                     33

  ATENÇÃO – Hoje não devem mais ser utilizadas as Macros ADABAS, pois existe o ADASQL.
           Os files lógicos Adabas maiores que 999 somente deverão ser utilizados com a
           linguagem NATURAL e com o ADABAS SQL , sendo que o desenvolvedor pode usar a
           linguagem PLI ou Cobol para acesso/atualização dos registros no DBMS ADABAS. Não
           é possível sua utilização por meio de macros.


                                                                                       -1-
1.   Conceitos
     Para a utilização do ADABAS em programas PL/I há a necessidade de extensa e detalhada
     codificação:
     Das áreas de dados e descritores, que são parametrizados nos FORMAT e RECORD BUFFERS e
     dos comandos básicos, que são parametrizados nos CONTROL, SEARCH e VALUE BUFFERS
     No mercado, utiliza-se um software chamado ADASQL para desenvolver o tratamento de toda esta
     parametrização.
     No REAL, foi desenvolvida pelo Suporte Técnico uma série de macros PL/I, que fazem todo o
     tratamento dos parâmetros do ADABAS, de forma semelhante ao COMMAND LEVEL do CICS,
     antes que o ADASQL estivesse disponível.
     A macros não devem mais ser utilizadas para a programação de programas novos, mas elas existem
     e estão presentes em programas antigos o que justifica esse manual.
     As MACROS PL/I funcionam com base no PRE-PROCESSADOR do PL/I
                                             COMPILAÇÃO PL/I

                                                   FONTE

                                            PREPROCESSADOR

                                          FONTE INTERMEDIÁRIO

                                               COMPILADOR

                                                  OBJETO


     O Pré-processador trata dois tipos de comandos:
     INCLUDES            (copy do COBOL) - são textos utilizados por diversos programas, por exemplo,
                         definições de arquivos, partes comuns de codificação, que são escritos uma
                         única vez e copiados pelos demais programas.

      MACROS             são instruções criadas na instalação, tornando-se praticamente comandos
                         PL/I, que são desdobradas pelo preprocessador a partir de esqueletos de
                         rotinas previamente programados, que são alterados ou complementados em
                         função dos parâmetros passados para a MACRO.
     Com estes recursos, padroniza-se a codificação, procedimentos complexos tornam-se
     transparentes, obtem-se economia de recursos de programação.




                                                                                                 -2-
2.     Visão Geral da Macros ADABAS
2.1.   Inicialmente, teremos uma visão de quais são as funções desempenhadas pelas MACROS ADABAS
       e como utilizamos estas funções em programas PL/I.
       Então, analisaremos mais profundamente quais as opções fornecidas em cada MACRO.
       Existem dois tipos básicos de MACROS ADABAS:
                            1. identificação do usuário do BANCO de DADOS,
        Declarativas        2. definição de áreas de dados e descritores,
                            3. parametrização de alguns procedimentos, p.ex. tratamento de erros.
                            1. utilizadas para realizar as transações (pesquisas, leituras, atualizações e
        Executivas
                                outras atividades) nos arquivos ADABAS.

       As principais MACROS declarativas são:
        USERID           identifica o usuário do BANCO de DADOS
        ARQ              define o FILE a ser utilizado
        CPO              define os campos a serem tratados
                         define os campos com quantidades de ocorrências de campos múltiplos ou
        CNT
                         periódicos (MU / PE)
        SUP              define quais os SUB ou SUPERDESCRITORES a serem utilizados
        FIM              delimita algumas das MACROS citadas
                         define rotinas especiais da aplicação para tratamento de erros nas MACROS e
        ERRO
                         no ADABAS

       As principais MACRO executivas são:
        ABRIR       Inicializa o BANCO de DADOS
        FECHAR Finaliza o BANCO de DADOS
        TODOS
                       TODOS  5 ISN’s 005, 105, 134, 278, 870
                    Pesquisa nas listas invertidas a condição desejada e devolve a quantidade de registros
                    selecionados e uma tabela com seus ISN’s.
                    Observe que esta MACRO NÃO acessa os registros, apenas seleciona os seus ISN’s a
                    partir das listas invertidas.
        PRIM
        PROX             PRIM ->->->->->             005
                          PROX ->->->->->             105
                          PROX ->->->->->             134
                          PROX ->->->->->             278
                          PROX ->->->->->             870
                          PROX ->->->->->             000
                    Localiza nas listas invertidas o primeiro registro que satisfaz a condição desejada e
                    devolve o seu ISN.
                    Observe que esta MACRO NÃO acessa o registro, apenas seleciona o seu ISN a partir
                    das listas invertidas.
                    A MACRO PRIM é utilizada em conjunto com a MACRO ADABAS PROX, que
                    acompanha a ordem especificada na MACRO PRIM e devolve sempre o ISN do
                    próximo registro na sequência.
        De uma forma geral, a MACRO TODOS é mais eficiente para a pesquisa, pois informa todos os
        ISN’s dos registros desejados com um único processo de acesso às listas invertidas.
        Contudo, a quantidade de ISNs obtidos numa pesquisa está restrito a 1000, pois até esta
        quantidade, os processamentos do ADABAS são realizados em memória e a partir daí, utilizando-
        se de áreas auxiliares em disco.
        Para quantidades superiores, deve ser utilizada a MACRO PRIM acompanhada da MACRO
        PROX.




                                                                                                       -3-
OBTER  Acessa os dados do registro indicado por um ISN informado. É utilizada após as
       MACROS TODOS, PRIM ou PROX, quando é necessário o acesso aos dados do
       registro após a pesquisa.
POR    Inclui registros novos no BANCO de DADOS.
REPOR  Atualiza o registro com dados alterados no BANCO de DADOS.
TIRAR  Seleta registros do BANCO de DADOS.
ENDTRA Encerra a transação e efetiva atualiza‡äes no BANCO de DADOS.
BACTRA Encerra a transação mas NÃO efetiva nenhum dos comandos efetuados pela
       transação no BANCO de DADOS.
RELCID Libera recursos do ADABAS utilizados pelo programa de aplicação.

Existem algumas estruturas de programas relacionadas com BANCO de DADOS que são
normalmente utilizadas.

PESQUISAS    Caracterizam-se por processos em que os registros são selecionados pelo
             critério de pesquisa solicitado, de forma randômica, através das listas
             invertidas definidas para o BANCO de DADOS.
             O programa de aplicação pode ou não acessar os dados de cada registro
             selecionado, conforme sua necessidade.
             Diferem de um processo de leitura pois os dados NÃO necessariamente são
             acessados.
             Por exemplo, quando consistimos a inclusão de um novo registro, verificamos
             apenas a existência de um registro com a mesma chave no BANCO de
             DADOS. Neste caso, é realizado APENAS o acesso às listas invertidas.
             São utilizadas a MACRO TODOS ou as MACROS PRIM e PROX, conforme o
             tipo de pesquisa. O acesso aos dados é através da MACRO OBTER.
LEITURAS     Normalmente utilizadas em BATCH, para programas que necessitam acessar
SEQUENCIAIS  grande parte dos registros de um FILE.
             Caracterizam-se por processos baseados em sequências dos registros:
             FÍSICA        Em ordem do armazenamento no próprio FILE no DATA
                           STORAGE, sem acesso às listas invertidas.
                           Por exemplo, para emissão de um relatório global ou para cálculo
                           de aumento de todos os salários.
             DE ISN        Em ordem da sequencia de ISN´s dos registros no FILE, com
                           acesso ao ADDRESS CONVERTOR, contudo sem acesso às
                           listas invertidas.
             LÓGICAS Em ordem da sequência de um determinado descritor do FILE,
                           portanto, através de acesso às listas invertidas.
                           Por exemplo, quando posicionamos um arquivo em determinada
                           agência e acessamos todos os registros dentro desta agência.
             É realizado um posicionamento dentro da sequência utilizada e a partir daí,
             ocorrem acessos sequenciais consecutivos aos registros posteriores.
ATUALIZAÇÕES Após o acesso ao registro, por algum dos criterios já mencionados, seus
             dados são alterados e será efetuado um UPDATE no BANCO de DADOS.
             Existem três MACRO ADABAS utilizadas:
             POR           Para inclusões de registros no Banco de Dados
             REPOR         Para altera‡äes de registros no Banco de Dados
             TIRAR         Para deleções.de registros no Banco de Dados

ATUALIZAÇÕES No On-Line, normalmente teremos uma pesquisa, seguida pelo acesso aos
             dados, sua atualização e o UPDATE no BANCO de DADOS, com uma das
             três MACRO citadas.
             Neste caso, considerando um ambiente multi-user, o programa de aplicação
             deverá ser transacional, se utilizando da mecânica de HOLD para possibilitar
             atualizações concorrentes.
                                                                                            -4-
       Seguem exemplos de programas em PL/I com MACROS ADABAS, com o objetivo de apresentar
       uma visão GERAL e SIMPLIFICADA da sua utilização. Em seguida, serão detalhadas as MACROS.

2.2.   Esquema para Exemplos
                        1   % INCLUDE MAC01 (ADABAS)
                        2     ARQ(pessoal) NUM(94) QMAX(100)     USO(acess)
                        3        CPO(codigo,CO)   UNPK(09)       PESQ
                        4        CPO(nome,NO)     ALFA(40)       PESQ
                        5        CPO(salario,SA) ALFA(40)        PESQ
                        6     FIM;
                        7
                        8     DCL i                 BIN   FIXED(31),
                        9         qtde              BIN   FIXED(31),
                       10         uni_isn           BIN   FIXED(31),
                       11         tab_isn(100)      BIN   FIXED(31) ;
                       12
                       13     ABRIR;
                       14     procedimentos_do_programa
                       15     FECHAR;

         LINHAS                                            EXPLANAÇÃO
              1      Comando para o preprocessador do PL/I inserir o include referente às MACROS
                     ADABAS.
       2-6           Definição, através de MACROS ADABAS, do FILE a ser utilizado e dos campos
                     necessários. Cria os DCL's para os campos código, nome e salário.
       8-10          Definição normal em PL/I de:
                     contador para loop (i).
                     Quantidade de registros (qtde) que foram selecionados por uma MACRO ADABAS
                     TODOS.
                     ISN (uni_isn) de um registro selecionado por uma das MACROS ADABAS PRIM ou
                     PROX ou que ser utilizado por uma das MACROS ADABAS de atualização e
                     deleção.
                     Tabela (array tab_isn) com os ISN's dos registros selecionados por uma MACRO
                     ADABAS TODOS.
                     Nos exemplos seguintes serão codificados apenas os campos efetivamente
                     utilizados.
       13            MACRO ADABAS para inicialização do BANCO de DADOS para este programa.
       14            Procedimentos do programa envolvendo a lógica de utilização das MACROS
                     ADABAS.
       15            MACRO ADABAS para finaliza‡Æo do BANCO de DADOS para este programa.




                                                                                              -5-
2.3.   Pesquisa de um Registro (Obter o salário do funcionário 87654.)
                 1    ARQ(pessoal) NUM(94) QMAX(1) USO(acess)
                 2       CPO(codigo,CO)   UNPK(09)   PESQ
                 3       CPO(nome,NO)     ALFA(40)   PESQ
                 4       CPO(salario,SA) UNPK(11,2) PESQ
                 5    FIM;
                 6
                 7    DCL qtde               BIN FIXED(31),
                 8        tab_isn(1)         BIN FIXED(31) ;
                 9
                10    ABRIR;
                11    TODOS(pessoal) COM(codigo=87654) QTD(qtde) EM(tab_isn);
                12    IF qtde = 0 THEN
                13       CALL funcionario_nao_cadastrado ;
                14    ELSE DO
                15       OBTER(pessoal) DE (tab_isn(1));
                16       CALL procedimentos_da_aplicacao;
                17       END;
                18    FECHAR;

         LINHAS                                          EXPLANAÇÃO
       11            MACRO ADABAS TODOS que pesquisa em PESSOAL o registro com
                     código=87654 e devolve no campo qtde a quantidade de registros encontrados e na
                     tabela tab_isn os seus ISN's, que no nosso caso é 1.
                     Estamos considerando que não existem códigos repetidos (unique key).
                     Observe que a MACRO TODOS não obtém os campos (não lê os registros).
       15            MACRO ADABAS OBTER que acessa o registro indicado pelo ISN contido no campo
                     tab_isn(1) e traz os campos solicitados.
       16            Procedimentos da aplicação para os dados obtidos.

2.4.   Pesquisa de um Grupo de Registros (listar todos os funcionários chamados OLEGARIO)

                 1    ARQ(pessoal) NUM(94) QMAX(100) USO(acess)
                 2       CPO(codigo,CO)   UNPK(09)   PESQ
                 3       CPO(nome,NO)     ALFA(40)   PESQ
                 4       CPO(salario,SA) UNPK(11,2) PESQ
                 5    FIM;
                 7    DCL i               BIN FIXED(31),
                 8         qtde           BIN FIXED(31),
                 9         tab_isn(100)   BIN FIXED(31) ;
                10
                11    ABRIR;
                12    TODOS(pessoal) COM(nome='OLEGARIO') QTD(qtde) EM(tab_isn);
                13    IF qtde = 0 THEN
                14       CALL nenhum_Olegario ;
                15    ELSE DO i = 1 to qtde;
                16       OBTER(pessoal) DE (tab_isn(i));
                17       CALL procedimentos_da_aplicacao;
                18       END;
                19    FECHAR;

         LINHAS                                          EXPLANAÇÃO
       12            MACRO ADABAS TODOS que pesquisa em PESSOAL todos os registros com
                     nome='OLEGARIO' e devolve no campo qtde a quantidade de registros encontrados
                     e na tabela tab_isn os seus ISN's.
                     Estamos considerando que existem nomes repetidos, mas no máximo cem, que é o
                     tamanho da tabela de ISN's (tab_isn).
                     Observe que a MACRO TODOS não obtém os campos (não lê os registros).
       15-18         Loop destinado a acessar todos os registros selecionados
       16            MACRO ADABAS OBTER que acessa o registro indicado pelo ISN contido no campo
                     tab_isn(i) e traz os campos solicitados.
                                                                                                -6-
       17            Procedimentos da aplicação para os dados obtidos.

2.5.   Pesquisa de um Grupo de Registros com Alto Volume(listar todos os funcionários chamados
       JOSE)
                1     ARQ(pessoal) NUM(94) QMAX(1) USO(acess)
                2        CPO(codigo,CO)   UNPK(09)   PESQ
                3        CPO(nome,NO)     ALFA(40)   PESQ
                4        CPO(salario,SA) UNPK(11,2) PESQ
                5     FIM;
                7     DCL uni_isn         BIN FIXED(31),
                9     ABRIR;
               10     PRIM(pessoal) COM(nome='JOSE') ORD(nome) EM(uni_isn);
               11     DO WHILE uni_isn ª= 0
               12       OBTER(pessoal) DE (uni_isn);
               13       CALL procedimentos_da_aplicacao;
               14       PROX(pessoal) ATE (nome='JOSE') EM(uni_isn);
               15       END;
               16     FECHAR;

            LINHAS                                         EXPLANAÇÃO
       10                MACRO ADABAS PRIM que pesquisa em PESSOAL o primeiro registro com
                         nome=JOSE e devolve no campo uni_isn o seu ISN (posiciona no primeiro
                         registro).
                         Estamos considerando que existem muitos nomes repetidos, eventualmente
                         acima de 1000.
                         Observe que a MACRO PRIM não obtém os campos (não lê os registros).
       11-15             Loop destinado a acessar sequencialmente os registros a serem selecionados.
                         Observe que ISN zerado indica fim de pesquisa ou de arquivo.
       12                MACRO ADABAS OBTER que acessa o registro indicado pelo ISN contido no
                         campo uni_isn e traz os campos solicitados.
       13                Procedimentos da aplicação para os dados obtidos.
       14                MACRO ADABAS que posiciona PESSOAL no próximo registro seguindo a
                         sequência iniciada com nome=JOSE e terminando em nome=JOSE e devolve
                         no campo uni_isn o seu ISN.
                         Ao atingir o fim dos registros selecionados, devolve o ISN zerado.
                         Observe que a MACRO PROX não obtém os campos (não lê os registros).

2.6.   Pesquisa de uma Faixa de Registros com Alto Volume(listar todos os funcionários de JOSE a
       MARIA)
                1     ARQ(pessoal) NUM(94) QMAX(1) USO(acess)
                2        CPO(codigo,CO)   UNPK(09)   PESQ
                3        CPO(nome,NO)     ALFA(40)   PESQ
                4        CPO(salario,SA) UNPK(11,2) PESQ
                5     FIM;
                6
                7     DCL uni_isn             BIN FIXED(31),
                8
                9     ABRIR;
               10     PRIM(pessoal) COM(nome='JOSE') ATE(nome='MARIA')
               11       ORD(nome) EM(uni_isn);
               12     DO WHILE uni_isn ª= 0
               13       OBTER(pessoal) DE (uni_isn);
               14       CALL procedimentos_da_aplicacao;
               15       PROX(pessoal) ATE(nome='MARIA') EM(uni_isn);
               16       END;
               17     FECHAR;

         LINHAS                                    EXPLANAÇÃO
       10-11         MACRO ADABAS PRIM que pesquisa em PESSOAL o primeiro registro com
                     nome=JOSE e devolve no campo uni_isn o seu ISN. Observe que a MACRO não
                                                                                                  -7-
                     obtém os campos (não lê os registros).
                     Caso não codificássemos o ATE, poderíamos receber um registro inicial com nome
                     superior a MARIA.
       12-16         Loop destinado a acessar sequencialmente os registros a serem selecionados.
                     Observe que ISN zerado indica fim de pesquisa ou de arquivo.
       13            MACRO ADABAS OBTER que acessa o registro indicado pelo ISN contido no campo
                     uni_isn e traz os campos solicitados.
       14            Procedimentos da aplicação para os dados obtidos.
       15            MACRO ADABAS PROX que posiciona PESSOAL no próximo registro seguindo a
                     sequência iniciada com nome=JOSE e devolve no campo uni_isn o seu ISN.
                     Quando atingir um nome imediatamente superior a 'MARIA', ou o fim do arquivo,
                     devolve o ISN zerado. Observe que a MACRO não obtém os campos (não lê os
                     registros).

2.7.   Leitura de Todo o File do Banco de Dados (gerar arquivo com todos os funcionários)
                 1    ARQ(pessoal) NUM(94) QMAX(1) USO(acess)
                 2       CPO(codigo,CO)   UNPK(09)   PESQ
                 3       CPO(nome,NO)     ALFA(40)   PESQ
                 4       CPO(salario,SA) UNPK(11,2) PESQ
                 5    FIM;
                 6
                 7    DCL uni_isn            BIN FIXED(31),
                 8
                 9    ABRIR;
                10    PRIM(pessoal) ORD('FIS') EM(uni_isn);
                11    DO WHILE uni_isn ¬= 0;
                12      OBTER(pessoal) DE (uni_isn);
                13      CALL procedimentos_da_aplicacao;
                14      PROX(pessoal) EM(uni_isn);
                15      END;
                16    FECHAR;

         LINHAS                                         EXPLANAÇÃO
       10            MACRO ADABAS PRIM que acessa PESSOAL em ordem física, independente tanto
                     da sequência de ISN como de quaisquer sequências lógicas. Observe que a
                     MACRO não obtém os campos (não lê os registros) e que NÃO devem ser
                     codificadas condições (COM, ATE).
       11-15         Loop destinado a acessar sequencialmente os registros. Observe que ISN zerado
                     indica fim de arquivo.
       12            MACRO ADABAS OBTER que acessa o registro indicado pelo ISN contido no campo
                     uni_isn e traz os campos solicitados.
       13            Procedimentos da aplicação para os dados obtidos.
       14            MACRO ADABAS PROX que posiciona PESSOAL no próximo registro seguindo a
                     sequência física e devolve no campo uni_isn o seu ISN.
                     Quando atingir fim de arquivo, devolve o ISN zerado. Observe que a MACRO PROX
                     não obtém os campos (não lê os registros).


2.8.   Leitura de Parte do File do Banco de Dados (gerar arquivo c/ os primeiros 300 funcionários)
                 1    ARQ(pessoal) NUM(94) QMAX(1) USO(acess)
                 2       CPO(codigo,CO)   UNPK(09)   PESQ
                 3       CPO(nome,NO)     ALFA(40)   PESQ
                 4       CPO(salario,SA) UNPK(11,2) PESQ
                 5    FIM;
                 6
                 7    DCL uni_isn            BIN FIXED(31),
                 8
                 9    ABRIR;
                10    DO uni_isn = 1 to 300;
                                                                                                -8-
                 11       OBTER(pessoal) DE (uni_isn);
                 12       CALL procedimentos_da_aplicacao;
                 13       END;
                 14     FECHAR;

          LINHAS                                        EXPLANAÇÃO
        10-13         Loop destinado a acessar por ordem de ISN os registros de 1 a 300.
                      Estamos considerando que existem os 300 registros no BANCO de DADOS. Este
                      processo de leitura raramente é utilizado.
        11            MACRO ADABAS OBTER que acessa o registro indicado pelo ISN contido no campo
                      uni_isn e traz os campos solicitados.
        14            Procedimentos da aplicação para os dados obtidos.

2.9.    Inclusão no On-Line (incluir o funcionário 1233)
                  1     ARQ(pessoal) NUM(94) QMAX(1) USO(alter)
                  2        CPO(codigo,CO)   UNPK(09)   PESQ
                  3        CPO(nome,NO)     ALFA(40)   PESQ
                  4        CPO(salario,SA) UNPK(11,2) PESQ
                  5     FIM;
                  7     DCL qtde            BIN FIXED(31),
                  8          uni_isn        BIN FIXED(31);
                 12     TODOS(pessoal) COM(codigo=1233) QTD(qtde) EM(uni_isn);
                 13     IF qtde ¬= 0 THEN
                 14       CALL procedimentos_de_inclusao_em_duplicata;
                 15     ELSE DO;
                 16       codigo = 1233;
                 17       nome = 'MARAJA';
                 18       salario = 300000;
                 19       POR(pessoal) EM (uni_isn);
                 20       END;
                 21     ENDTRA;

          LINHAS                                          EXPLANAÇÃO
        10            Para aplica‡äes on-line, não se utilizam as MACROS ADABAS ABRIR e FECHAR.
        12            MACRO ADABAS TODOS que pesquisa em PESSOAL o registro com codigo=1233
                      e devolve no campo qtde a quantidade de registros encontrados e em uni_isn o seu
                      ISN, se quantidade maior que 1 o ISN de menor valor.
                      Observe que a MACRO TODOS não obtém os campos (não lê os registros).
        13-14         Tratamento de inclusão em duplicata.
        15-20         Procedimentos de inclusão.
        19            MACRO ADABAS POR grava em PESSOAL o novo reg. e devolve o ISN em uni_isn.
        21            MACRO ADABAS ENDTRA que efetiva as transações no BANCO de DADOS.



2.10.   Alteração no On-Line (alterar o salário do funcionário 1233)
                  1     ARQ(pessoal) NUM(94) QMAX(1) USO(alter)
                  2        CPO(codigo,CO)   UNPK(09)   PESQ
                  3        CPO(nome,NO)     ALFA(40)   PESQ
                  4        CPO(salario,SA) UNPK(11,2) PESQ
                  5     FIM;
                  7     DCL qtde            BIN FIXED(31),
                  8          uni_isn        BIN FIXED(31);
                 11     TODOS(pessoal) COM(codigo=1233) QTD(qtde) EM(uni_isn);
                 12     IF qtde = 0 THEN
                 13       CALL procedimentos_de_funcionario_nao_cadastrado;
                 14     ELSE DO;
                 15       OBTER(pessoal) DE (uni_isn);
                 16       salario = 800000;
                 17       REPOR(pessoal) DE (uni_isn);
                 18       END;
                 19     ENDTRA;
                                                                                                   -9-
          LINHAS                                           EXPLANAÇÃO
        10             Para aplicações on-line, não se utilizam as MACROS ADABAS ABRIR e FECHAR.
        11             MACRO ADABAS TODOS que pesquisa em PESSOAL o registro com codigo=1233
                       e devolve no campo qtde a quantidade de registros encontrados e em uni_isn o seu
                       ISN, mas se quantidade maior que 1 o ISN de menor valor. Observe que a MACRO
                       não obtém os campos (não lê os registros).
        12-13          Procedimentos de funcionário não cadastrado.
        14-18          Procedimentos de alteração.
        14             MACRO ADABAS OBTER que acessa o registro indicado pelo ISN contido no campo
                       uni_isn e traz os campos solicitados.
        17             MACRO ADABAS REPOR que atualiza o registro indicado pelo ISN contido no
                       campo uni_isn com os dados existentes nos campos do programa.
        19             MACRO ADABAS ENDTRA que efetiva as transações no BANCO de DADOS.

2.11.   Deleção no On-Line (deletar o funcionário 1233)
                   1     ARQ(pessoal) NUM(94) QMAX(1) USO(alter)
                   2        CPO(codigo,CO)   UNPK(09)   PESQ
                   3        CPO(nome,NO)     ALFA(40)   PESQ
                   4        CPO(salario,SA) UNPK(11,2) PESQ
                   5     FIM;
                   6
                   7     DCL qtde               BIN FIXED(31),
                   8         uni_isn            BIN FIXED(31);
                   9
                  11     TODOS(pessoal) COM(codigo=1233) QTD(qtde) EM(uni_isn);
                  12     IF qtde = 0 THEN
                  13       CALL procedimentos_de_funcionario_nao_cadastrado;
                  14     ELSE DO;
                  15       TIRAR(pessoal) DE (uni_isn);
                  16       END;
                  17     ENDTRA;

          LINHAS                                           EXPLANAÇÃO
        10             Para aplicações on-line, não se utilizam as MACROS ADABAS ABRIR e FECHAR.
        11             MACRO ADABAS TODOS que pesquisa em PESSOAL todos os registros com
                       codigo=1233 e devolve no campo qtde a quantidade de registros encontrados e em
                       uni_isn o seu ISN, mas se quantidade maior que 1 o ISN de menor valor.
                       Observe que a MACRO TODOS não obtém os campos (não lê os registros).
        12-13          Procedimentos de funcion rio nÆo cadastrado.
        14-16          Procedimentos de deleção.
        16             MACRO ADABAS TIRAR que deleta o registro indicado pelo ISN contido no campo
                       tab_isn(1).
        17             MACRO ADABAS que efetiva as transações no BANCO de DADOS.




3.      Sintaxe

                             Para a utilização das macros é necessário o comando PL/I:
                                            %INCLUDE MAC01(ADABAS);
                                             CUIDADOS IMPORTANTES

            As macros são POSICIONAIS, portanto devem ser utilizadas na ordem da definição
             apresentada.

                                                                                                  - 10 -
        Como uma macro gera diversos comandos de PL/I, as que forem codificadas na saída de uma
         instrução condicional (dentro do IF), deverão estar entre DO e END.
         IF A = 100 THEN DO; ENDTRA; END;
        Não usar ASSIGN com BY NAME para duas estruturas quando ambas definidas para o
         ADABAS, pois existem campos internos com o mesmo nome e que também serão movidos.

4.   Convenções
             |       |
             <       >     um dos termos ou expressÆo deve ser especificado.
             |       |

             <       >     a expressÆo ou termo deve ser especificado.

             |       |     a expressÆo ou termo ‚ opcional.

             . . .         a expressÆo ou termo pode ser repetido.

             (       )     delimita uma expressÆo ou termo.

                 ;         termina uma macro.

5.   Palavras Reservadas
     Em virtude das MACROS terem sido escritas em PL/I as seguintes palavras e expressões não
     poderão ser usadas em programas que usem BANCO de DADOS:
     ABRIR               E                         FECHAR                PROGBAS
     ALFA                EM                        FIM                   PROX
     ALFAV               ENDTRA                    GRP                   QMAX
     ARQ                 ERROABRIR                 IND                   QTD
     ATE                 ERROOBTER                 NOCNT                 RELCID
     BACTRA              ERROPEGAR                 NR                    REPOR
     BFIX                ERROPOR                   NUM                   SOLTAR
     BDADOS              ERROPRIM                  OBTER                 SUP
     CHECKPOINT          ERROPROX                  ORD                   TIRAR
     CNT                 ERROREPOR                 OU                    TODOS
     COM                 ERROTIRAR                 PARA                  UNPK
     CPO                 ERROTODOS                 PEGAR                 UNPKV
     DE                  ETDATA                    PESQ                  USERID
     DFIX                EXC                       POR                   USO
     DIM                 EXEC                      PRIM                  @PROGRAMA
     HISTOGRAMA          NOMEPGM

6.   Macros Declarativas
     Existem três grupos principais:
     1. dirigidas para identificação do usuário ADABAS;
     2. dirigidas para definição da área de dados, DESCRITORES e número de ocorrências em campos
        múltiplos e/ou periódicos. Ou seja, elas definem a interface (control block e demais áreas buffers)
        com o ADABAS.
     3. dirigidas para definição de tratamentos de erros.

7.   Identificação do Usuário USERID / Programa
                          |'literal' |
                 USERID ( |    ou    | ) ;
                          | variavel |




                                                                                                      - 11 -
     Identifica os dados do usuário (ETVAR) que vão ser obtidos por uma MACRO ABRIR ou guardados
     por uma das MACROS CHECKPOINT, ENDTRA ou FECHAR.
     Literal e variável deverão ter um tamanho máximo de 8 bytes.

     Normalmente, codifica-se o nome do programa. Exceção quando mais de um programa ir acessar a
     mesma área.


                       |'literal' |
           @PROGRAMA ( |    ou    | ) ;
                       | variavel |


     É uma variável do programa que deve ser usada para passar à rotina de erro o nome do programa
     para que este seja impresso ou mostrado em terminal.
     Literal e variável deverão ter um tamanho máximo de 8 bytes.
     É MUITO ÚTIL principalmente para programas on-line.

8.   Definição de Dados

                                     ARQ
                                            CPO
                                            CPO
                                            ...
                                            GRP
                                                  CPO
                                                  ...
                                                  CPO
                                            FIM
                                            CPO
                                            ...
                                            CPO
                                            SUP
                                                  CPO
                                                  ...
                                                  CPO
                                            FIM
                                     FIM;

     Podem existir várias declarações de arquivo (MACRO ARQ).
     Cada uma poderá conter vários campos (MACRO CPO), vários grupos de campos (MACRO GRP), e
     vários campos SUB ou SUPERDESCRITORES (MACRO SUP).
     Um grupo de campos (MACRO GRP) poderá conter vários campos (MACRO CPO).
     A declaração de DESCRITORES é efetuada no próprio campo, através da MACRO PESQ.
     As declarações dos SUB ou SUPERDESCRITORES deverão ser as últimas do arquivo.
     As MACROS GRP e SUP devem ser finalizadas pela MACRO FIM. A MACRO ARQ também é
     finalizada pela MACRO FIM, contudo, deverá ser seguida pelo ponto e virgula (FIM;).
     Existem declarações aonde o SÍMBOLO ADABAS é associado ao nome dado à variável ou estrutura
     em PL/I:

     (xr,xa) sendo … ==> AGENCIA_MATRIZ,AL associa AL a AGENCIA_MATRIZ
     Caso xa seja omitido, serão utilizadas as duas primeiras posições de xr.
     NOME_MATRIZ associa NO a NOME_MATRIZ

     NÃO PODEM EXISTIR ESPAÇOS ENTRE 'xr', e 'xa'. Não causará erro de compilação mas causará
     erros de execução.

9.   Tipos de ARQ

                                                                                               - 12 -
                                                             | ALTER |
            ARQ(arq) |BDADOS(ap)| NUM(num) |QMAX(qmax)| USO( < EXCL > ) |NOCNT|
                                                             | ACESS |
                     Dá nome a um arquivo do Banco de Dados e à estrutura que conterá os campos
       ARQ           declarados através da MACRO CPO.
       BDADOS        Sigla padrão de identificação da aplicação no REAL (DI, CN, etc.) do arquivo FILE
                     que est‚ em DB ALTERNATIVO. A sigla pode será informada com ou sem
                     apostrofe (DI ou 'DI')
                     Programas que usam BDADOS exigem os seguintes cartäes DD em seu JOB:

                     //DB#ap0nnDD      DSN=CP.AUXLI(ADAIDnn),DISP=SHR
                  onde nn é o número (DBID) que identifica o BANCO de DADOS ALTERNATIVO
       NUM        Número do arquivo (FILE) do BANCO de DADOS.
       QMAX       Quantidade máxima de registros esperada após uma pesquisa. O limite é 1000.
       USO        Tipo de uso que se vai fazer do arquivo.
                  ALTER        O arquivo vai ser atualizado concorrentemente por vários usuários e
                               requer o uso da MACRO ENDTRA.
                  EXCL         O arquivo vai ser atualizado por um único usuário.
                  ACESS        O arquivo vai ser apenas lido.
                  Esta condiçãoo pode ser alterada dinamicamente através da MACRO executiva
                  PARA.
       NOCNT      Informa às MACROS para NÃO gerarem os campos que contém o número de
                  ocorrências de campos múltiplos e grupos periódicos para esse arquivo.
                  Não utilizar ARQUIVOA = ARQUIVOB, BY NAME (Capítulo “Sintaxe” – item 2.2.)
      ARQ(CADAST) BDADOS(DI) NUM(32) QMAX(200) USO (ACESS)

      Declarar somente os campos que vão ser utilizados pelo programa. Se a atualização de alguns
      campos requer a leitura de outros campos, é melhor declarar o arquivo duas vezes, uma para leitura
      e outra para atualização.


10.   GRP

                                 | NR                           |
                GRP(gr|,ga|)     <                              >
                                 | DIM(d |:d|)      IND(i |-i|) |

       GRP           Nome da estrutura de dados. Gr é o nome pelo qual a estrutura é conhecida pelo
                     programa e ga é o nome pelo qual a estrutura é conhecida pelo ADABAS. Se ga
                     não é informado os dois primeiros caracteres de gr são usados.
                     Não deve ser codificada quando o grupo conter campos múltiplos. Neste caso cada
                     campo deverá ser definido individualmente através da MACRO CPO.
                     Quando declarada, TODOS OS CAMPOS PERTENCENTES AO GRUPO DEVEM
                     SER DECLARADOS.

                     GRP(cadastro,AL) NR
       NR            A estrutura não é repetitiva, ou seja, não é um grupo periódico.


                            GRP(resumo_saldos,AX) DIM(2) IND(1-2)

      Os parâmetros DIM e IND são utilizados quando o grupo é periódico e servem para informar a
      dimensão do ARRAY para o PL/I e quais ocorrências o ADABAS deve acessar. Normalmente,
      sempre são acessadas todas as ocorrências.
      Todos os campos pertencentes a este grupo, quando utilizados no programa PL/I, deverão estar
      subscritados.

                                                                                                   - 13 -
       DIM            Especifica a dimensão de uma estrutura em formato de 'array', ou seja, quantas
                      ocorrências.
                      Pode ser codificada como a quantidade de ocorrências, por exemplo, DIM(5), ou
                      como um intervalo, DIM(1:5), exatamente como no PL/I.
       IND            Especifica quais as ocorrências da estrutura no arquivo, que o ADABAS deve ler ou
                      atualizar.
                      No BANCO de DADOS podem existir dez ocorrências, das quais só interessam ao
                      programa as duas últimas. Neste caso, usaríamos IND(9-10), e especificaríamos
                      duas ocorrências na dimensão, DIM(2) ou DIM(9:10).
                      Caso interessassem as cinco primeiras, usaríamos IND(1-5) e especificaríamos
                      cinco ocorrências na dimensão, DIM(5).

      Quando especificadas, a expansão das MACROS gera um campo BIN FIXED(15), no final do
      ARRAY, que conterá o número total de ocorrências do grupo para o registro acessado.
      Seu nome será o do grupo seguido de '_# No exemplo acima, 'resumo_saldos_#'.

11.   CPO

                                                      |        ALFA (tam)       |
                                                      |        ALFAV(tam)       |
                          |                         | |        DFIX (tam |,dec|)|
             CPO(cp|,ca|) |DIM(d1|,d2|) IND(i1|,i2|)| <                         > |PESQ|
                          |                         | |        UNPK (tam |,dec|)|
                                                      |        UNPKV(tam |,dec|)|
                                                      |        BFIX             |




       CPO      Nome do campo. cp é o nome pelo qual o dado é conhecido pelo programa e ca é o
                nome pelo qual o dado é conhecido pelo ADABAS. Se ca não é informado os dois
                primeiros caracteres de cp são usados.
       DIM      Análoga ao da Macro GRP espesifica a dimensão, ou as duas dimensões, de uma
                estrutura em formato de 'array'. Cada dimensão pode ser codificada como a quantidade
                de ocorrências, por exemplo, DIM(10), ou como um intervalo, DIM(1:10), exatamente
                como no PL/I. No caso de duas dimensões, a primeira, d1, corresponde ao grupo
                periódico e a segunda, d2, ao campo múltiplo contido no periódico. São separadas por
                uma virgula, conforme exemplos:
                DIM   (10,2)
                DIM   (1:10,2)
                DIM   (10,1:2)
                DIM   (1:10,1:2)
       IND      Análoga ao da Macro GRP, especifica quais ocorrências serão lidas ou atualizadas pelo
                ADABAS, em cada uma das dimensões. Pode ser codificada como quantidade, IND(1-5),
                indicando ao ADABAS que as cinco primeiras ocorrências devem ser tratadas, ou como
                intervalo, IND(3-7), indicando que o ADABAS deve tratar da terceira à sétima ocorrência.
                No caso de duas dimensões, o primeiro IND, i1, corresponde ao grupo periódico e o
                segundo, i2, ao campo múltiplo contido no periódico. São separados por uma virgula,
                conforme exemplos:
                DIM   (10,20)                            IND(1-10,1-20)
                DIM   (3,2)     ou   DIM(1:3,2)          IND(6-8,1-2)
                DIM   (10,6)    ou   DIM(10,15:20)       IND(1-10,15-20)
                DIM   (4,6)     ou   DIM(5:8,15:20)      IND(5-8,15-20)
                Quando as MACROS DIM e IND são especificadas, a sua expansão gera um campo BIN
                FIXED(15), no final do ARRAY, que conterá o número total de ocorrências do campo
                para o registro acessado.
                Seu nome será o do campo seguido de '_#'.


                                                                                                    - 14 -
 OBS     Importante quando codificamos um campo múltiplo dentro de um grupo periódico
         devemos colocarmos o ARQ com a opção de NOCNT para evitar a geração do campo
         '_#' que indica o número de ocorrências para campos múltiplos e/ou periódicos.
         A codificação das MACROS ALFA, DFIX, UNPK e BFIX, deve obedecer rigorosamente o
         formato e tamanho dos campos definidos no BANCO de DADOS. Isto porque a MACRO
         definirá no PL/I os campos com as características fornecidas, contudo, solicitará ao
         ADABAS que use o que foi definido na FDT.
         Qualquer divergência causará problemas na execução do programa, como se fosse um
         lay-out definido deslocado.
         As MACROS ALFAV e UNPKV possibilitam a utilização de tamanhos distintos dos
         definidos no BANCO de DADOS, por exemplo, para USERVIEWS.
         ALFA        O campo é alfanumérico.
         ALFAV       O campo é alfanumérico. Utilizado para obter o campo com tamanho
                     diferente do definido para o ADABAS.
         DFIX        O campo é numérico compactado.
         UNPK        O campo é numérico descompactado.
                     O campo é numérico descompactado. Utilizado para obter o campo com
         UNPKV
                     tamanho diferente do definido para o ADABAS.
         BFIX        O campo é binário com 4 bytes.
         PESQ        O campo é uma chave de pesquisa (DESCRITOR).
         Vamos considerar os diversos casos de definições, da situação mais simples à mais
         complexa:


         1.         simples (não múltiplo) isolado
         2.         simples contido em um grupo
         3.         simples contido em um grupo periódico
         4.         simples contido em um grupo periódico, grupo este que não será utilizado no
                    programa e portanto não será definido.
         5.         múltiplo

         6.         múltiplo contido em um grupo
         7.         múltiplo contido em um grupo periódico
         8.         múltiplo contido em um grupo periódico, grupo este que não será utilizado no
                    programa e portanto não será definido.

O seguinte FILE será utilizado como base para os exemplos:
         DB: 50         FILE:   96    CONTCREDITO

         TYL   DB   NAME                                    F LENG S D REMARKS
         ---   --   -------------------------------         - ---- - - -------
           1   AA   loja                                    N    3 N D
           1   AB   codigo_cliente                          N   10 N D

         G 1   G1   pessoa
           2   BA   sobre_nome                              A    20   N   D
           2   BB   primeiro_nome                           A    16   N   D
           2   CA   sexo                                    A     1   N   D
           2   CB   idade                                   N   2.0   N   D

         G 1 GR endereco
           2 CD logradouro                                  A    30 N
         M 2 BC telefone                                    N     8 N

         M 1 AC nome_dependentes                            A    10 N D

         P 1 MC credito
           2 CC cartao_de_credito                           A    18 N D
           2 CL limite_de_credito                           N   4.0 N D
                                                                                                   - 15 -
           P 1 UT utilizacoes
             2 CB saldo_utilizado                       N     4.0 N D
           M 2 DT data_utilizacoes                      N       6 N

Simples (não múltiplo) isolado


           CPO(codigo_cliente,AB)           UNPK(10)        PESQ

           1 pessoal,
             ...
             2 codigo_cliente PIC '9(10)',
             ...

Simples contido em um grupo (Todos os campos pertencentes ao grupo devem ser definidos.)


           GRP(pessoa,G1) NR
              CPO(sobre_nome,BA)                    ALFA(20)       PESQ
              CPO(primeiro_nome,BB)                 ALFA(16)       PESQ
              CPO(sexo,CA)                          ALFA(01)       PESQ
              CPO(idade,CB)                         UNPK(02)       PESQ
              FIM

           1 pessoal,
             ...
             2 pessoa,
               3 sobre_nome CHAR(20)
               3 primeiro_nome CHAR(16)
               3 sexo CHAR(01)
               3 idade PIC '9(02)'
             ...

Simples contido em um grupo periódico (Todos os campos pertencentes ao grupo devem ser
definidos.)

           GRP(credito,MC) DIM(5) IND(1-5)
              CPO(cartao_de_credito,CC)             ALFA(18)       PESQ
              CPO(limite_de_credito,CL)             UNPK(04)       PESQ
              FIM

           1 pessoal,
             ...
             2 credito (5),
               3 cartao_de_credito CHAR(18),
               3 limite_de_credito PIC '9(04)',
             2 credito_#           BIN FIXED(15),
             ...

Simples contido em um grupo periódico, grupo este que não será utilizado no programa e portanto
não será definido.

           CPO(cartao_de_credito,CC) DIM(5) IND(1-5) CHAR(18) PESQ

           1 pessoal,
             ...
             2 cartao_de_credito (5) CHAR(18),
             2 cartao_de_credito_# BIN FIXED(15),
             ...

Múltiplo

           CPO(nome_dependentes,AC) DIM(3) IND(1-3) ALFA(10) PESQ

                                                                                            - 16 -
               1 pessoal,
                 ...
                 2 nome_dependentes (3) CHAR(10),
                 2 nome_dependentes_# BIN FIXED(15),
                 ...

      múltiplo contido em um grupo
                O ADABAS NÃO ACEITA A DECLARAÇÃO DE UM MÚLTIPLO DENTRO DE
                UM ÍTEM DE GRUPO, POIS NÃO TERIA COMO OBTER OS CONTADORES
                E NEM COMO ESPECIFICAR QUAIS OCORRÊNCIAS DEVERIAM SER
                ACESSADAS.
                NESTE CASO, TODOS OS CAMPOS DO GRUPO DEVEM SER DEFINIDOS
                ISOLADAMENTE, COM DIM (D1) e IND (I1), D1=DIMENSÃO DO
                MÚLTIPLO(QUANTAS), I1=OCORRÊNCIAS DO MÚLTIPLO(QUAIS).

      múltiplo contido em um grupo periódico
                O ADABAS NÃO ACEITA A DECLARAÇÃO DE UM MÚLTIPLO DENTRO DE
                UM ÍTEM DE GRUPO, POIS NÃO TERIA COMO OBTER OS CONTADORES
                E NEM COMO ESPECIFICAR QUAIS OCORRÊNCIAS DEVERIAM SER
                ACESSADAS.
                NESTE CASO, TODOS OS CAMPOS DO GRUPO DEVEM SER DEFINIDOS
                ISOLADAMENTE, COM DIM (D1,D2) e IND (I1,I2), D1=DIMENSÃO
                DO PERIÓDICO(QUANTAS), D2=DIMENSÃO DO MÚLTIPLO(QUANTAS),
                I1=OCORRÊNCIAS DO PERIÓDICO(QUAIS) e I2=OCORRÊNCIAS DO
                MÚLTIPLO(QUAIS).

      múltiplo contido em um grupo periódico declarado isoladamente
               ARQ(arq)    NUM(num)    QMAX(qmax)    USO(ACESS)   NOCNT

               CPO(data_utilizacoes,DT) DIM(5,20) IND(1-5,1-20) UNPK(6)

               1 pessoal,
                 ...
                 2 data_utilizacoes (5,20) PIC '9(06)',
                 ...

12.   CNT
                    | cp|,ca| |                       | BFIX      |
               CNT( |         | )      | IND(i1) |    < DFIX(tam) >
                    | gr|,ga| |                       | UNPK(tam) |

      Atualmente, esta MACRO NÃO É MAIS UTILIZADA, existindo para manter compatibilidade com
      versões anteriores das MACROS
      Em versões anteriores das MACROS ADABAS, era necessário solicitar a geração dos contadores de
      ocorrências em campos múltiplos ou periódicos.
      Nome do campo no qual é devolvido o número de ocorrências de um campo múltiplo ou grupo
      periódico. Se IND é usado cp deve ser o nome de um campo múltiplo pertencente a um grupo
      periódico e i1 o número da ocorrência do grupo periódico.

13.   SUP (sp,|sa|)
       SUP            Define um SUB ou SUPERDESCRITOR. sp é o nome pelo qual o SUB ou
                      SUPERDESCRITOR é conhecido pelo programa e sa o nome pelo qual o SUB ou
                      SUPERDESCRITOR é conhecido pelo ADABAS. Se sa não é informado, os dois
                      primeiros caracteres são usados.

      A declaração de SUB ou SUPERDESCRITOR deve ser a última dentro do arquivo e sp deve ser
      único no programa.

      Os programas de aplicação não tem acesso direto aos campos definidos como SUB ou
      SUPERDESCRITOR, que são tratados exclusivamente pelo ADABAS.

                                                                                              - 17 -
          CPO(ageconta,AC)            UNPK(10);           DESCRITOR
          SUP(agencia,AG)
              CPO(age)                UNPK(03)            SUBDESCRITOR
          FIM
          SUP(setor,SE)                                   SUPERDESCRITOR
              CPO(set)                UNPK(03)
              CPO(agen)               UNPK(10)
              FIM

Consideremos os dados acima codificados.
 Ao alterarmos ageconta, o ADABAS se encarregar de:
 * alterar a lista invertida para o DESCRITOR,
 * obter a parte do campo relativa ao SUBDESCRITOR, e alterar a lista invertida correspondente,
 * compor os campos relativos ao SUPERDESCRITOR, e alterar a lista invertida correspondente.

Observe que o programa de aplicação apenas alterou o dado do registro.

A utilidade da MACRO SUP é proporcionar uma definição do SUB ou SUPERDESCRITOR, como
área de trabalho, que será utilizada para comparações, por exemplo, dentro da MACRO TODOS.

Em função disto, não há necessidade de se indicar o SÍMBOLO ADABAS nos campos (MACRO
CPO) que o definem. Sua definição NÃO DEVE conter as MACROS PESQ, DIM e IND.

Dos campos gerados pelas MACROS ADABAS, apenas estes podem ser utilizados pelos programas
de aplicação, conforme as normas do REAL.

Exemplo de uso de SUPERDESCRITOR

        ARQ(ARQX) NUM(99) QMAX(10) USO(ACESS)
           ...
           CPO(NOME)         ALFA(40)
           SUP(AGEORG,AO)
               CPO(AGENCIA)  UNPK(04)
               CPO(ORGAO)    UNPK(03)
           FIM
           SUP(AGEORGX,AO)
               CPO(AGENCIA)  UNPK(04)
               CPO(ORGAO)    UNPK(03)
           FIM
         FIM;

As MACROS geram as seguintes ESTRUTURAS:
       1 ARQX,
       ...
         2 AGEORG@D,
            3 AGENCIA      PIC '9999',
            3 ORGAO        PIC '999',
         2 AGEORGX@D,
            3 AGENCIA      PIC '9999',
            3 ORGAO        PIC '999',
       1 AGEORG@  DEF(AGEORG@D)   CHAR(07),
       1 AGEORGX@ DEF(AGEORGX@D) CHAR(07);

Exemplo de uso de SUBDESCRITOR
        ARQ(ARQX) NUM(99) QMAX(10) USO(ACESS)
        ...
          CPO(NOME)         ALFA(40)
          SUP(MILHAR,ML)
              CPO(SALARIO)  UNPK(05)
          FIM
          SUP(MILHARX,ML)
              CPO(SALARIO)  UNPK(05)
          FIM

                                                                                             - 18 -
                 FIM;

        As MACROS geram as seguintes ESTRUTURAS:
                 1 ARQX,
                   ...
                   2 MILHAR@D,
                       3 SALARIO      PIC '99999',
                   2 MILHARX@D,
                       3 SALARIO      PIC '99999',
                 1 MILHAR@   DEF(MILHAR@D)   CHAR(05),
                 1 MILHARX@ DEF(MILHARX@D) CHAR(05);




14.     Tratamento de Erros

14.1.   Erro

                  ERROinstrucao(arq)      EXEC(proc) ;

                  ABRIR            POR            REPOR
                  OBTER            PRIM           TIRAR
                  PEGAR            PROX           TODOS
                  HISTOGRAMA

        A execução dessa MACRO faz com que a procedure declarada em EXEC receba o controle quando
        houver um response code diferente de zero na MACRO instrução do arquivo declarado em arq.

        Basicamente, DEVEM SER EVITADOS TRATAMENTOS DE ERRO, pois
         1.   A condição de erro acontece, em algumas MACROS, no meio dos procedimentos
              preparados pela expansão, implicando em problemas de lógica.
         2.   Na maioria dos casos, a adequação de parâmetros internos ou externos ao programa
              podem resolver o problema.
                         ERROABRIR EXEC(PROBLEMAS)

                         ERROTODOS(CADAST) EXEC(PROBLEMAS)

        A MACRO ERROABRIR não aceita o parâmetro arq, pois a MACRO ABRIR é global, não existindo
        abertura a nível de FILE.

        Nota:    Atenção com PL/I OPT(2) no tratamento de variáveis dentro da procedure declarada em
                 EXEC, caso estas variáveis tiverem sido definidas na procedure que emitiu a MACRO.


14.2.   %@ROTER = ‘myrot’
        É uma variável do Preprocessador que pode ser usada para alterar o nome da rotina que ganha o
        controle em caso de erro no ADABAS.

15.     Macros ADABAS

15.1.   ABRIR
                 ABRIR    |ETDATA (etvar)| ;

        Essa MACRO gera um comando OPEN para todos os arquivos do Banco de Dados Default,
        declarados no programa.
        Se ETDATA (etvar) é especificado, é OBRIGATÓRIA a codificação do USERID (ver "USERID").


                                                                                                   - 19 -
        Na variável etvar serão devolvidos os últimos dados do usuário guardados por uma das MACROS:
        CHECKPOINT, ENDTRA ou FECHAR. Etvar deve ser uma variável CHAR com no máximo 1800
        bytes.
        Para programas de consulta on-line, ESTA MACRO NÃO DEVE SER UTILIZADA. Ver o MANUAL
        DE NORMAS E INFORMATIVOS TÉCNICOS editado pelo Suporte ao Desenvolvimento.

15.2.   FECHAR
                 FECHAR     | (etvar) | ;
        Essa MACRO gera um comando CLOSE para todos os arquivos do Banco de Dados Default.
        Ela não pode ser emitida se existir Transação Aberta para o DB ALTERNATIVO.

        Se a variável etvar é especificada, seu conteúdo é guardado pelo ADABAS e pode, posteriormente,
        ser obtido por uma MACRO ABRIR.

        ETvar deve ser uma variável CHAR com no máximo 1800 bytes.

        Para programas de consulta on-line, ESTA MACRO NÃO DEVE SER UTILIZADA. Ver o MANUAL
        DE NORMAS E INFORMATIVOS TÉCNICOS editado pela Suporte ao Desenvolvimento.

15.3.   TODOS
                                          |    | ATE (cond)        |EXC (cond)|   |   |
               TODOS (arq)     COM (cond) |    < OU (cond)                        >   |   . . .
                                          |    | E   (cond)                       |   |

                   |                                     |
                   |   ORD (cp |,cp| |,cp| |,DEC|)       |         QTD (q)   EM (v);
                   |                                     |

        Forma da condição
                            | cp |                   |               |
                            <    | >=,=>,<=,=<,=,>,< |       exp     >
                            | sp |                   |               |

        A MACRO gera um comando de pesquisa (Sx) para o arquivo especificado. Em q retorna a
        quantidade de registros que satisfazem a pesquisa e em v a lista dos ISNs desses registros.

        Não realiza nenhuma acesso aos dados, apenas às listas invertidas.

        Usar esta MACRO quando se quer apenas verificar a existência de um registro.
        Caso espere-se encontrar mais de 1000 registros como resultado de uma pesquisa, use as
        MACROS: PRIM e PROX (ver "PRIM").

        EVITAR pesquisas que usem dois ou mais descritores.

         TODOS                       Especifica o arquivo que ser pesquisado.


         As MACROS COM, ATE, EXC, OU e E são utilizadas para definir a pesquisa a ser realizada.

               TODOS(pessoal) COM(salario>10000) QTD(q) EM(v);


                                     Especifica a primeira condição para pesquisa, que poderá ser a
         COM
                                     única.
         QTD                         Na variável especificada é devolvida a quantidade de registros que
                                     satisfazem as condições dadas ou zero se nenhum registro for
                                     encontrado.

                                                                                                     - 20 -
EM    Na variável especificada é devolvida a lista de ISNs dos registros que
      satisfazem as condições dadas.
      Esta variável deve ser declarada como um ARRAY BIN FIXED(31)
      com a dimensão igual ao QMAX especificado para aquele arquivo.
      Declara-se apenas o nome da variável, sem indicação da indexação,
      pois será utilizada como pointer.
      Caso este ARRAY tenha sido definido com um tamanho inferior ao
      QMAX, por exemplo, QMAX=500, ARRAY=300, ocasionara em
      tempo de execução um erro ADABAS (RSP=333 - área de ISN's
      menor que QMAX).

      TODOS(pessoal) COM(salario=10000) ATE(salario=20000)
              QTD(q) EM(v);




ATE   Especifica um limite para a condição imediatamente anterior,
      orientando o ADABAS a tratá-la como um intervalo fechado.
      Neste caso, o único OPERADOR VALIDO é IGUAL.
      O ADABAS acessará a lista invertida buscando o primeiro registro
      com salario >= 10000 e selecionar enquanto o salario for <= 20000.


              TODOS(pessoal) COM(salario=10000)
      ATE(salario=20000)
              EXC(salario=12000) QTD(q) EM(v);

              TODOS(pessoal) COM(salario=10000)
      ATE(salario=20000)
              EXC(salario=12000) ATE(salario=14000) QTD(q)
      EM(v);
EXC   Especifica uma condição para excluir um valor ou um intervalo de
      valores da condição imediatamente anterior. Só pode ser usado após
      o conector ATE e o descritor DEVE SER o mesmo da condição
      anterior.
      Neste caso, o único OPERADOR VALIDO é IGUAL.


              TODOS(pessoal) COM(salario=10000)
      OU(salario=20000)
              QTD(q) EM(v);
OU    Especifica uma condição alternativa para seleção. O descritor DEVE
      SER o mesmo da condição imediatamente anterior.


              TODOS(pessoal) COM(salario=10000)
      E(admissao<8701)
              QTD(q) EM(v);
E     Especifica uma outra condição para a pesquisa, que poderá‚ ser com
      outro campo.
      Neste caso, o ADABAS gera lista de ISN's para cada condição,
      transforma em BIT STRING, faz o AND lógico, e devolve a lista de
      ISN, consumindo consideráveis recursos.


                                                                        - 21 -
                                             TODOS(pessoal) COM(salario=10000)
                                             ORD(nome,idade) QTD(q) EM(v);
         ORD                        As chaves pelas quais os registros vão ser classificados.
                                    EVITAR sua utilização, principalmente se a chave for um SUB ou
                                    SUPERDESCRITOR ou se o arquivo possuir mais de 50.000
                                    registros.
                                    Neste caso, faça uma leitura sem "ORD" e classifique seus registros
                                    através da "ROTINA DBQSRTx" maiores detalhes no "Manual de
                                    Informativo Técnico".
         DEC                        Se a classificação deve ser em ordem decrescente.

        PRECAUÇÃO A leitura de um intervalo de valores deve ser feita utilizando as MACROS COM
                  (cpo=x) ATE (cpo=Y), que orientará o ADABAS a realizar um procedimento com
                  base em INTERVALOS. Por exemplo, COM(nome=JOAO) ATE(nome=MARIA).
                  Não utilizar COM (cpo>=x) E (cpo<=y), que implicará num procedimento baseado na
                  elaboração de uma lista de ISN's para cada condição e em seguida, na
                  INTERSECÇÃO das duas listas, consumindo muito mais recursos.


15.4    PRIM
                 PRIM (arq)   | COM (cond) |E (ISN > exp)| |ATE (cond)|          |
                                    | 'FIS' |
                              ORD (|    cp |) EM (isn);
                                    |   sp |

        A MACRO PRIM permite três opções de leitura:
         em sequência lógica de um DESCRITOR
         em sequência lógica de um SUB ou SUPERDESCRITOR
         Em sequência física.

        Estes parâmetros são comuns a todas as opções:
         PR
                Especifica o arquivo que vai ser posicionado.
         IM
         EM Especifica a variável onde o ISN do registro é passado.

        As MACROS COM, E e ATE são utilizadas para definir a pesquisa a ser realizada.
        As condições declaradas nas MACROS COM devem ser baseadas no mesmo DESCRITOR ou SUB
        ou SUPERDESCRITOR declarado na MACRO ORD.
        As condições declaradas nas MACROS ATE devem ser baseadas no mesmo DESCRITOR
        declarado na MACRO ORD.

15.5.   Leitura em Sequencia Lógica de um Descritor
                 PRIM (arq) | COM (cp = exp) |E (ISN > exp)| |ATE (cp = exp)| |
                              ORD (cp) EM (isn);

        A MACRO PRIM pesquisa a lista invertida especificada pela MACRO ORD, localiza o ISN (número
        interno do ADABAS) do registro que atende às condições solicitadas na MACRO COM, e possibilita
        a leitura sequencial naquela ordem através das MACROS OBTER e PROX.
        Utiliza-se da leitura lógica (L3/L6) com posicionamento (VALUE START) seguida de leituras
        sequenciais (L3/L6).
        Se nenhuma condição é declarada, isto é, não há MACRO COM, o posicionamento é feito no
        primeiro registro do descritor dado em ORD.
        Se a condição dada não for satisfeita é retornado zero na variável isn.
        Observe que as condições devem se utilizar do operador lógico IGUAL (=).
        NÃO É PERMITIDO o uso de campos múltiplos ou pertencente a grupos periódicos nas condições.


                                                                                                    - 22 -
         COM          Especifica uma condição para pesquisa do ISN do registro a partir do qual será
                      iniciada a leitura.
                      Caso não seja especificada a MACRO ATE, a condição definida para a MACRO
                      COM será assumida para final da pesquisa.
         E            Especifica o ISN do registro, dentre os que atendem à condição, a partir do qual
                      será iniciada a leitura sequencial.
                      É utilizado em pesquisas que selecionam muitos registros com uma mesma
                      condição, apresentando diversas telas e exigindo paginação (para frente e para
                      trás, tipo BROWSE), como em um extrato.
                      Sem esta MACRO, receberíamos sempre o primeiro registro que atende a
                      condição, e não o correspondente à página desejada.
         ATE          Especifica uma condição para fim da pesquisa. É válida apenas para
                      DESCRITORES. A MACRO solicita ao ADABAS o posicionamento com base na
                      condição declarada na MACRO COM. Ele devolve o registro solicitado ou o
                      imediatamente superior. A MACRO verifica se o registro recebido não ultrapassa a
                      condição estabelecida em ATE.
         ORD          Especifica o DESCRITOR para controle da sequência de pesquisa e leitura.

15.6.   Leitura em Sequência Lógica de um Sub ou Superdescritor
                 PRIM (arq) | COM (sp >= exp) |E (ISN > exp)| |
                              ORD (sp) EM (isn);

        Funciona de forma análoga à leitura com base em um DESCRITOR. A principal diferença é que a
        MACRO NÃO REALIZARÁ o controle de final de pesquisa (exceto por fim de arquivo), com as
        seguintes implicações:

         1.    Não pode ser declarada a MACRO ATE, portanto, a aplicação deverá programar o controle
               de final de pesquisa.
         2.    Poderá receber logo no primeiro registro um valor superior ao argumento da pesquisa.
         3.    A MACRO PROX correspondente também não poderá ter a MACRO ATE.

        Observe que as condições devem se utilizar do operador MAIOR OU IGUAL ( >= ).
        NÃO É PERMITIDO o uso de campos múltiplos ou pertencente a grupos periódicos nas condições.

         COM         Análogo a opção anterior, exceto por não fazer o controle de fim.
         E           Análogo a opção anterior.
         ORD         Especifica o SUB ou SUPERDESCRITOR para controle da sequência de pesquisa
                     e leitura.
15.7.   Leitura em Sequência Física

                 PRIM (arq) |E (ISN > exp)| ORD ('FIS') EM (isn);

        A MACRO PRIM acessa diretamente o DATA STORAGE, sem consultar as listas invertidas, e
        possibilita a leitura sequencial em ordem física do arquivo através das MACROS OBTER e PROX.
        Trata-se de um acesso otimizado, próprio para processamento BATCH, muito útil para a leitura de
        todos os registros de um arquivo, quando não for necessário obedecer uma sequência lógica.
        Utiliza-se da leitura física (L2/L5) seguida de leituras sequenciais (L2/L5).
        Se nenhum ISN é declarado o posicionamento é feito no primeiro registro do arquivo.
        Ao final do arquivo é retornado zero na variável isn.
        NÃO É PERMITIDA a declaração de condições (MACROS COM e ATE).

         E            Especifica o ISN (exclusive) a partir do qual ser‚ iniciada a leitura.
                      É utilizado para RESTART de programas. Caso não exista no BANCO de DADOS,
                      o ADABAS provocar um ABEND.
         ORD          Especifica leitura física.


                                                                                                   - 23 -
          PRECAUÇÃO        Se houver atualização (mesmo concorrente, por OUTRO PROGRAMA) para o
                           arquivo em questão, existe o perigo de se ler duas ou mais vezes o mesmo
                           registro.

         Isto acontece em duas condições:
         1. quando em leitura em ordem de DESCRITOR ou SUB ou SUPERDESCRITOR, ocorrer uma
              alteração do DESCRITOR, reposicionando o ISN do registro na lista invertida, na parte ainda
              não acessada.
         2. quando em leitura física, se a atualização do registro implicar em expansão física, tal que
              realoque o registro para outro bloco, a ser acessado.

         O processamento SEQUENCIAL de arquivos ADABAS pode gerar problemas de PERFORMANCE.
         Na necessidade da utilização de tal recurso, procure expor o caso ao Suporte ao Desenvolvimento.




15.8.    OBTER
                   OBTER (arq)      DE (isn) ;
          A MACRO lê um registro.
                                                       Especifica o arquivo a ser lido.
          OBTER
          DE                                           Especifica o ISN do registro que ser lido.


15.9.    PROX
               PROX (arq) | ATE (cond) |         EM (isn) ;
                  cond < cp = exp >

         A MACRO posiciona o próximo registro a ser lido por uma MACRO OBTER.
         Se a condição especificada não for satisfeita, a variável especificada no parâmetro EM será zerada.
         Se não for dada nenhuma condição o arquivo será posicionado até o fim e só então a variável isn
         será zerada.

          PROX          Especifica o arquivo a ser posicionado.
          ATE           Especifica a condição de término do posicionamento. Não pode ser usada para
                        SUB ou SUPERDESCRITOR.
          EM            Especifica a variável onde o ISN do registro é passado.


15.10.   POR
                                | EM (isn); |
                  POR (arq)     <           >
                                | DE (isn); |
         A MACRO grava um novo registro no arquivo especificado.

          POR           Especifica o arquivo que vai ser gravado.
          EM            Especifica a variável onde vai ser devolvido o ISN do registro gravado.
          DE            Especifica a variável que contém o ISN do registro a ser gravado.


15.11.   REPOR
                 REPOR (arq)     DE (isn) ;
         A MACRO atualiza um registro do arquivo especificado.

          REPOR         Especifica o arquivo a ser atualizado.
          DE            Especifica o ISN do registro a ser atualizado.

                                                                                                        - 24 -
15.12.   TIRAR
                  TIRAR (arq)    DE (isn) ;
         A MACRO elimina um registro do arquivo especificado.

          TIRAR         Especifica o arquivo do qual o registro vai ser eliminado.
          DE            Especifica a variável que vai conter o ISN do registro a ser eliminado.

15.13.   RELCIDD
                  RELCID |(arq)|;

         A MACRO libera espaço na área interna do ADABAS:
         1. Libera listas de ISN presas.
         2. Encerra leituras sequencias.
         Deve ser usada no final de pgms que não executam a MACRO FECHAR.
         Se arq é especificado, somente as áreas associadas ao arquivo em questão serão liberadas.
         Em caso de pgms que tratam o response code 309 o uso de arq é opcional.

15.14.   ENDTRA
                  ENDTRA |(etvar)|;
         A MACRO termina uma transação lógica. É obrigatório o seu uso quando os arquivos atualizados
         forem declarados com USO(ALTER).
         Se a variável etvar é usada, seu conteúdo é guardado pelo ADABAS.
         Etvar deve ser uma variável CHAR com no máximo 1800 bytes, e só pode ser utilizada para o DB
         DEFAULT.

15.15.   BACTRA
                  BACTRA |(arq)|;
         A MACRO desfaz a transação lógica iniciada após a última execução de uma MACRO ENDTRA.
         Se arq for especificado e existir Transação Aberta para um Banco de Dados, o arquivo dever
         pertencer a esse Banco de Dados.

15.16.   CHECKPOINT
                               | etvar   |
                  CHECKPOINT ( <         > );
                               |'literal'|
         Guarda os dados contidos na variável etvar ou o literal para posterior uso da MACRO ABRIR. É
         obrigat¢rio o uso de USERID.
         Etvar deve ser uma variável CHAR com no máximo 1800 bytes.
         Esta MACRO possue diversas opções, que permitem a alteração dinâmica de algumas declarações.

15.17.   PARA
                               |       | ACESS |   |
                    PARA (arq) | USO ( <       > ) | ;
                               |       | ALTER |   |
         Permite o acesso a um arquivo, controlando quais registros devem ser colocados em HOLD. Muito
         útil quando se pretende realizar uma quantidade significativa de pesquisas ou leituras que implicarão
         em poucas atualizações.

         Deve ser utilizada da seguinte forma:
         1. declarar o arquivo com USO(ALTER).
         2. logo em seguida, declarar PARA(arq) USO(ACCES), fazendo com que as pesquisas e leituras
             NÃO HOLDEM os ISNs.
         3. ao localizar um registro a ser atualizado:

             a. declarar PARA(arq) USO(ALTER),
             b. acessar o registro, portanto colocando-o em HOLD,
             c. atualizar o registro,

                                                                                                        - 25 -
             d. declarar PARA(arq) USO(ACCES).

         Observe que se o arquivo foi declarado como USO(ACCES), não será válido o uso de PARA(arq)
         USO(ALTER).

                              | PEGAR (isn) |
                   PARA (arq) |              | ;
                              | SOLTAR (isn) |

          PEGAR         O ISN do arquivo especificado ser‚ colocado em HOLD.
          SOLTAR        O ISN do arquivo especificado ser liberado do HOLD.


         NOTE BEM     O tempo de transação (TRANSACTION TIME = TT) começa a ser computado pelo
                      ADABAS a partir do momento em que a transação lógica tiver HOLDADO o seu
                      primeiro registro.

         O fato de se usar esta opção da MACRO PARA, NÃO irá posicionar o TT para ZERO.
         O TT será posicionado para zero na execução de uma das seguintes MACROS: FECHAR, BACTRA
         ou ENDTRA. Ver "Mecânica de Hold Através das Macros".

                    PARA (arq) QMAX (qmax) ;
         Altera dinamicamente a quantidade máxima de registros.


15.18.   HISTOGRAMA
                                 | |              |
              HISTOGRAMA (arq)   | COM (cond1) | | ATE (cond2) | QTD (q)
                                 |             | |              |
                  VALOR_EM (v1 |,v2|);
                          | cpo >= exp |
                  cond1    <             >  cpo deve estar declarado como PESQ
                           | sp >= exp |
                  cond2    | cpo = exp |    cpo deve ser o mesmo do cond1 e
                                            cond2

         A MACRO HISTOGRAMA gera um comando de leitura de Listas Invertidas para o arquivo e o
         descritor especificados.

         Em v1 retorna um valor encontrado para o descritor e em "q" a quantidade de registros onde o
         descritor assume esse valor.

         Se o descritor se encontrar em um grupo periódico, a macro retorna em v2 o número da ocorrência.
         HISTOGRAMA Especifica o arquivo cujas Listas Invertidas serão lidas.

          COM            Especifica qual é descritor a ser lido e um valor a partir do qual será iniciada a
                         leitura.
          ATE            Especifica um valor para indicar o fim da leitura.
          QTD            Especifica uma variável onde será devolvida a quantidade de registros onde o
                         descritor assume um valor.
          VALOR_EM       Especifica uma variável onde será devolvido o valor lido para o descritor e,
                         eventualmente uma segunda variável onde será devolvido o número da
                         ocorrência de um grupo periódico onde se encontra esse valor, caso o descritor
                         pertença ao grupo periódico.

15.19.   ERROHISTOGRAMA
              ERROHISTOGRAMA (arq)       EXEC (proc);


                                                                                                         - 26 -
         A procedure declarada em EXEC receber o controle quando houver um "response code" diferente de
         zero na macro HISTOGRAMA para o arquivo declarado em arq.

         Observações
          1.   A macro HISTOGRAMA deverá utilizar uma macro ARQ definida só para seu próprio uso.
          2.   As variáveis da macro VALOR_EM devem ser declaradas como segue:

               *  sempre com formato compatível com o formato declarado para o descritor na macro
                  ARQ.
               * sempre numérica com tamanho de pelo menos 2 dígitos.
          3.   A primeira emissão da macro HISTOGRAMA com determinado descritor deve conter
               obrigatoriamente a macro COM pois é nela que consta a referência ao descritor. Se esta
               condição não for obedecida, o programa receberá um "response code" 60 do ADABAS.
          4.   Ao término da leitura, a macro HISTOGRAMA retorna 0 na variável "q" usada na macro
               QTD.
          5.   Conceito - Listas Invertidas.

         LISTAS INVERTIDAS Tabelas mantidas pelo ADABAS que associam cada valor de cada descritor
                           de cada arquivo à lista de ISN's dos registros onde o descritor assume o
                           valor referenciado.


15.20.   Exemplo de Uso de Histograma
         Exemplo de utilização da macro HISTOGRAMA, desejamos todos os carros da marca "FORD" e que
         tenham as cores compreendidas entre os valores "BACK" e "WHITE".
                    1   ADHISTO: PROC OPTIONS(MAIN);
                    2   %INCLUDE MAC01(ADABAS);
                    3   @PROGRAMA = 'ADHISTO';
                    4   ARQ(AUTOMOBILES) NUM(95) QMAX(100) USO(ACESS)
                    5      CPO(MAKE,AA)         ALFA(20) PESQ
                    6      CPO(COLOR,CA)        ALFA(10) PESQ
                    7      CPO(YEAR,DA)         UNPK(02)
                    8      FIM;
                    9
                   10   ARQ(AUTOMOBILES2) NUM(95) QMAX(100) USO(ACESS)
                   11      CPO(COLOR,CA)        ALFA(10) PESQ
                   12      FIM;
                   13
                   14   DCL     DESCR1          CHAR(10),
                   15   /***    VARIAVEL ONDE   FICARA' O VALOR DO DESCRITOR COLOR ***/
                   16           J               BIN FIXED(31),
                   17           QT1             BIN FIXED(31),
                   18           QT2             BIN FIXED(31),
                   19   /***    QUANTIDADE DE   VEZES QUE OCORRE O VALOR EM DESCR1 ***/
                   20           ISNA(100)       BIN FIXED(31);
                   21   ABRIR;
                   22   HISTOGRAMA (AUTOMOBILES2) COM (COLORH >= 'BLACK')
                   23      ATE (COLORH = 'WHITE') QTD (QT2) VALOR_EM (DESCR1);
                   24   DO WHILE (QT2 ª= 0);
                   25      TODOS (AUTOMOBILES) COM (COLOR = DESCR1) E
                   26             (MAKE = 'FORD') QTD (QT1) EM (ISNA);
                   27      DO J = 1 TO QT1;
                   28          OBTER(AUTOMOBILES) DE(ISNA(J));
                   29          PUT DATA (MAKE, COLOR, YEAR);
                   30      END;
                   31      HISTOGRAMA (AUTOMOBILES2) COM (COLORH >= 'WHITE')
                   32          QTD (QT2) VALOR_EM (DESCR1);
                   33   END;
                   34   FECHAR;
                   35   END ADHISTO;

15.21.   NOMEPGM
               NOMEPGM (PGM);
                                                                                                        - 27 -
         A MACRO identifica o nome do programa que está emitindo comandos ADABAS, evitando assim
         problemas de "direcionamento" por parte do "DBNCF"
         Deve ser usada em:
          1.    Rotinas de uso geral em PL/1, (que utilizam ADABAS), pertencentes a um sistema e que são
                utilizadas por programas de outros sistemas
          2.    Programas PL/1 chamados por programas NATURAL



15.22.   Response Codes Emitidos pela Macro NOMEPGM
         Response codes emitidos por erro de codificação da macro
          1.   RSP 041 - "AN ERROR WAS DETECTED IN THE FORMAT BUFFER"
               Verifique o campo ADDITIONS_2 do CONTROL BLOCK. Ele poderá conter um dos códigos
               a seguir:

               M1       RECORD BUFFER com comprimento menor que 8(oito)
               M2       O campo "DT" (DATA) não é o primeiro campo do FORMAT BUFFER
               M3       DATA INVALIDA - A data deve ser do tipo (AAMMDD) onde AA = ANO (deve ser
                        maior ou igual a 88).
               NOT caso o campo ADDITIONS_2 não contenha um dos códigos acima verifique cada
               A        ítem da lista de itens que podem provocar o "RESPONSE CODE 041".
          2.   RSP 113 - "THE SPECIFIED ISN WAS INVALID"
               Esse response pode ocorrer quando um programa de um sistema tentar alterar/excluir um
               registro de movimentos de outro sistema.
          3.   RSP 201 - "THE PASSWORD SPECIFIED WAS NOT FOUND"
               São duas as situações em que pode ocorrer o response 201:

               1    Programas de um sistema que incluem registros de movimentos de outro sistema.
               2    Inclusão de movimentos não cadastrados.

15.23.   Exemplo de Uso de NOMEPGM
                    1   KBPGM: PROC OPTIONS(MAIN);
                    2   %INCLUDE MAC01(ADABAS);
                    3   @PROGRAMA = 'KBPGM';
                    4   NOMEPGM (KBPGM);
                    5   ARQ(DBMOVIMENTOS) NUM(34) QMAX(1) USO(ACESS)
                    6       CPO(DATA_MOV,DT)         DFIX(07)
                    7       CPO(NOME_MOV,NO)         ALFA(04)
                    8       CPO(XAV_ALFA,XA)         ALFA(20)
                    9       CPO(XAV_NUMER,XN)        UNPK(15)
                   10       CPO(DADOS,DA) DIM(3) IND(1-3)   ALFA(100)
                   11       SUP(XAVE_ALFA,S1)
                   12            CPO(NOME,NO)        ALFA(04)
                   13            CPO(ALFA,XA)        ALFA(20)
                   14       FIM;
                   15       SUP(XAVE_NUM,S2)
                   16            CPO(NOME2,NO)       ALFA(04)
                   17            CPO(NUMER,XN)       UNPK(15)
                   18       FIM;
                   19     FIM;
                   20   ARQ(KBARQUIVO) NUM(170) QMAX(1) USO(ACESS)
                   21       CPO(KBCPO,CA)        ALFA(10) PESQ
                   22       CPO(KBCPO,CA)        ALFA(10) PESQ
                   23       FIM;
                   24   .
                   25   .
                   26   END KBPGM;

15.24.   Mecânica de HOLD Através das MACROS
         O ADABAS permite que dois ou mais usuários atualizem um mesmo arquivo simultaneamente.
                                                                                                    - 28 -
        Para garantir que esses usuários não atualizem um mesmo registro simultaneamente, o ADABAS
        coloca esse registro "HOLD" quando o primeiro usuário o obtém.
        Assim, quando o segundo usuário tentar obtê-lo ficará esperando até que o primeiro usuário o libere.
        Para que um registro fique "HOLD", usando as MACROS, deve-se observar o seguinte:
         1.    O arquivo a que pertence o registro deve estar declarado com USO(ALTER);
         2.    USO(ALTER) deve estar em efeito no momento da execução das MACROS.

        As MACROS que colocam um registro "HOLD" são as seguintes:
         1.  TODOS - O primeiro registro da lista de ISN'S encontrados, no caso, de lista vazia também
             será contabilizado para efeito de registros na "HOLD QUEUE"
         2.  PRIM/PROX - O registro cujo ISN foi encontrado, ou no caso de ISN ZERO, o registro que foi
             usado para teste nas condições das MACROS COM ou ATE;
         3.  OBTER - O registro cujo ISN está sendo especificado, desde que o ISN não seja resultante
             das MACROS PRIM/PROX.
         4.  POR - O registro cujo ISN é especificado, no caso de o usuário estar especificando o ISN, ou
             o registro cujo ISN é devolvido pelo ADABAS;
         5.  TIRAR - O registro cujo ISN é especificado;
         6.  PEGAR - O registro cujo ISN é especificado;

        As MACROS que liberam os registros "HOLD" são as seguintes:
         1.  SOLTAR - O registro cujo ISN é especificado;
         2.  ENDTRA / BACTRA / FECHAR - Todos os registros "HOLDADOS" pelo programa.

        Para programas que atualizam on-line, evitar mandar telas para serem preenchidas no meio de uma
        transação lógica.
        NÃO HOLDAR mais de 100 registros em uma transação.

16      Processamentos Especiais

16.1.   Lista de ISNS em que QTD > QMAX (RSP309)
        Exemplo de tratamento de RESPONSE CODE 309 onde QTD > QMAX. Ser tratada toda a lista de
        ISNs obtida pela pesquisa efetuada pela MACRO TODOS.
                 1     ADTODOS: PROC OPTIONS(MAIN,REENTRANT);
                 2     %INCLUDE MAC01(ADABAS);
                 3     @PROGRAMA = 'ADTODOS';
                 4     ARQ(TESTE) NUM(100) QMAX(10) USO(ACESS)
                 5         CPO(CODIGO,CF)       DFIX(7) PESQ
                 6         CPO(NOME,NO)         ALFA(30)
                 7         CPO(CIDADE,CI)       ALFA(20)
                 8         FIM;
                 9     DCL    ISNV (10)     BIN FIXED(31),
                10            SALVA         BIN FIXED(31) INIT (0),
                11            QTDE          BIN FIXED(31);
                12     ABRIR;
                13     ERROTODOS(TESTE) EXEC(RSP309);
                14     COMECO:
                15     TODOS(TESTE) COM(CODIGO > 1000) QTD(QTDE) EM(ISNV);
                16     IF QTDE > 10 THEN DO;
                17          SALVA = QTDE;
                18          QTDE = 10;
                19          END;
                20     DO I = 1 TO QTDE;
                21         OBTER(TESTE) DE(ISNV(I));
                22         PUT DATA (CODIGO, NOME, CIDADE);
                23         END;
                24     IF SALVA > 10 THEN DO;
                25         SALVA = SALVA - 10;
                26         GO TO COMECO;
                27         END;
                28     RSP309: PROC;
                29         IF @RSP ª= 309 THEN CALL @ROTER;
                                                                                                      - 29 -
                 30          END RSP309;
                 31       FECHAR;
                 32       END ADTODOS;


         10              É IMPORTANTE inicializar o campo salva.
         13              Declaração da rotina destinada a tratar o RESPONSE CODE 309.
         16-19           Rotina para tratar toda a lista de ISN's, em conjuntos de dez ISN's, a cada vez.


16.2.   Uso de RELCID para Listas de ISNS onde QTD > QMAX

        Neste caso quero tratar apenas parte da lista de ISNS resultante da pesquisa.
                  1       ADBPLI: PROC OPTIONS(MAIN);
                  2       %INCLUDE MAC01(ADABAS);
                  3       @PROGRAMA = 'ADBPLI';
                  4       ARQ(PERSONNEL) NUM(94) QMAX(10) USO(ACESS)
                  5          CPO(NAME,BA)   ALFA(20) PESQ
                  6          CPO(FIRST_NAME,BB)   ALFA(15)
                  7          FIM;
                  8       ERROTODOS(PERSONNEL) EXEC(RSP309);
                  9       DCL I BIN FIXED(31),
                 10           ISNV (10) BIN FIXED(31),
                 11           QTDE BIN FIXED(31) ;
                 12       ABRIR;
                 13       TODOS(PERSONNEL) COM (NAME = 'CHAAAAAAAAAAAAAAAAAA')
                 14           ATE (NAME = 'CL999999999999999999')
                 15           QTD(QTDE) EM(ISNV);
                 16       DO I = 1 TO QTDE;
                 17           OBTER(PERSONNEL) DE(ISNV(I));
                 18           PUT SKIP DATA (NAME,FIRST_NAME);
                 19           END;
                 20       RSP309: PROC;
                 21           IF @RSP ª= 309 THEN CALL @ROTER;
                 22           PUT SKIP LIST ('INTERCEPTEI O RSP 309, QTDE=',QTDE);
                 23           RELCID(PERSONNEL);
                 24           QTDE = 10;
                 25           END RSP309;
                 26        FECHAR;
                 27        END ADBPLI;


          LINHAS                                            EXPLANAÇÃO
         8               Declaração da rotina destinada a tratar o RESPONSE CODE 309.
         20-25           Rotina que trata apenas os dez primeiros ISN's da lista, liberando os demais ISN's.
         23              comando para liberação dos resultados e recursos envolvidos na pesquisa efetuada.

16.3.   RESTART Usando ET-VAR
        Este é um caso simples de RESTART, que atende a situações com 'n' arquivos de entrada com
        dados para atualização do DATA BASE, mas que não gravem arquivos sequenciais de saída.
        Para casos mais elaborados, deve ser utilizada a rotina ADRESTAR (ver DOCUMENTAÇÃO
        ESPECÍFICA).

             1        ADENTRA: PROC OPTIONS (MAIN);
             2        %INCLUDE MAC01(ADABAS);
             3        @PROGRAMA = 'ADENTRA';
             4        USERID ('ADENTRA');
             5        ARQ(ARQ1) NUM(10) QMAX(1) USO(ALTER)
             6          CPO(CHAV)        ALFA(10) PESQ
             7          CPO(NOME)        ALFA(20)
             8        FIM;
             9        DCL    MOV     FILE RECORD INPUT ENV(F RECSIZE(30)),
            10             1 REGMOV,

                                                                                                            - 30 -
     11         2 CHAVMOV       CHAR(10),
     12         2 NOMEMOV       CHAR(20),
     13       1 LIDOS          FIXED(09) INIT(0);
     14       1 ISN,QT     BIN FIXED(31);
     15   DCL 1 ET_AREA,
     16         2 TERMINO       CHAR(10) INIT('FIM NORMAL'),
     17         2 QUANTPOR      FIXED(07) INIT(0),
     18         2 QUANTREPOR    FIXED(07) INIT(0),
     19         2 CONTADOR      FIXED(09) INIT(0),
     20         2 CHAVATU       CHAR(10) INIT (' '),
     21       1 ET_AREAD        CHAR(33) DEF AREA;
     22       OPEN FILE(MOV);
     23       ABRIR ETDATA(ET_AREAD);
     24
     25       IF TERMINO = 'ABENDOU' THEN DO;
     26           ON ENDFILE(MOV) GOTO ERRO;
     27           READ FILE(MOV) IGNORE(CONTADOR - 1)
     28           READ FILE(MOV) INTO(REGMOV);
     29           IF CHAVMOV ª= CHAVATU THEN DO;
     30   ERRO:        DISPLAY ('FITA MOV ERRADA');
     31                CALL ABEND;
     33                END;
     34           END;
     35       TERMINO = 'ABENDOU';
     36       ON ENDFILE(MOV) GOTO TERMINA;

 LINHAS                                    EXPLANAÇÃO
4            Identificação do Usuário
5            Observe que o ARQUIVO foi definido como ALTER.
15-21        Definição da ET-VAR com os dados para o restart.
17-19        Definição de acumuladores de registros lidos um para cada arquivo.
23           MACRO para abrir o BANCO de DADOS e ler a ET-VAR.
25-34        Rotina para tratar o restart.
             2
                 identifica se o programa inicia após um ABEND.
             5
             2
                 o arquivo lido não pode acabar antes do ponto guardado na ET-VAR.
             6
             2
                 lê o arquivo ignorando os registros processados anteriormente.
             7
             2
                 verifica se o posicionamento foi efetuado corretamente.
             9
35           marca um campo dentro da ET-VAR indicando que ocorreu algum processamento


     37   LOOP:
     38       READ FILE(MOV) INTO(REGMOV);
     39       LIDOS = LIDOS + 1;
     40       TODOS(ARQ1) COM(CHAV = CHAVMOV) QTD(QT) EM(ISN);
     41       IF QT = 0 THEN DO;
     42           CHAV = CHAVMOV;
     43           NOME = NOMEMOV;
     44           POR(ARQ1) EM(ISN);
     45           QUANTPOR = QUANTPOR + 1;
     46           END;
     47       ELSE DO;
     48           OBTER(ARQ1) DE(ISN);
     49           NOME = NOMEMOV;
     50           REPOR(ARQ1) DE(ISN);
     51           QUANTREPOR = QUANTREPOR + 1;
     52           END;
     53       IF LIDOS > 99 THEN DO;
     54           CONTADOR = CONTADOR + LIDOS;
     55           LIDOS = 0;
     56           CHAVATU = CHAVMOV;
                                                                                    - 31 -
            57                ENDTRA(ET_AREAD);
            58                END;
            59            GOTO LOOP;

         53-58           A cada cem atualizações emite um ENDTRA, para efetivar as atualizações e limpar a
                         HOLD QUEUE.

            60        TERMINA:
            61            CLOSE FILE(MOV);
            62            PUT SKIP DATA(QUANTPOR,QUANTREPOR);
            63            TERMINO = 'FIM NORMAL';
            64            CONTADOR = 0;
            65            CHAVATU = ' ';
            66            FECHAR(ET_AREAD);
            67            END ADENTRA;

         63-67           Prepara a ET-VAR indicando um fim normal.
         64-65           Zera variáveis e chaves.
         66              Finaliza o BANCO de DADOS e grava a ET-VAR.

        Documentar na pasta de produção do Sistema, que em caso de Abend deste programa, o mesmo
        deverá ser reexecutado pois trata-se de programa restartável.

16.4.   PRIM com "E" para CICS com RETURN TRANSID
                  1      DBPGADZ: PROC(P) OPTIONS(MAIN,REENTRANT);
                  2      %INCLUDE MAC01(ADABAS);
                  3      @PROGRAMA = 'DBPGADZ';
                  4       ARQ (AUTO) NUM (95) USO (ACESS)
                  5           CPO (MAKE,AA)           ALFA (20)             PESQ
                  6           CPO (MODEL,AB)          ALFA (20)
                  7           CPO (COLOR,CA)          ALFA (10)
                  8           FIM;
                  9
                 10       DCL      ISN_LIDO             BIN FIXED(31);
                 11
                 12       DCL      P                    POINTER;
                 13       DCL      1 COMABASE           BASED(P),
                 14                  2 ISN_X            BIN FIXED(31),
                 15                  2 VLR_PESQ_CO      CHAR(20);
                 16
                 17       DCL        AREA_SAI CHAR(50);
                 18       DCL      1 AREA_SAI1 BASED(ADDR(AREA_SAI)),
                 19                  2 MAK       CHAR(20),
                 20                  2 MOD       CHAR(20),
                 21                  2 COL       CHAR(10);
                 22
                 23       DCL      1 AREA,
                 24                  2 ISNPRIM    BIN FIXED(31) INIT(0),
                 25                  2 VLRPESQ    CHAR(20) INIT('CITROEN');
                 26
                 27       IF EIBCALEN = 0 THEN DO;
                 28          P= ADDR(AREA);
                 29          END;
                 30
                 31       PRIM (AUTO) COM (MAKE = VLR_PESQ_CO) E (ISN > ISN_X)
                 32          ATE (MAKE = 'CITROENX') ORD (MAKE) EM (ISN_LIDO);

         27-28           Na primeira vez, EIBCALEN é zero.

                 33      IF ISN_LIDO ¬= 0 THEN DO;
                 34
                 35          OBTER (AUTO) DE (ISN_LIDO);
                 36          MAK = MAKE;
                 37          MOD = MODEL;
                 38          COL = COLOR;
                                                                                                     - 32 -
        39
        40      EXEC CICS SEND FROM       (AREA_SAI) LENGTH(50) ERASE;
        41      ISN_X = ISN_LIDO;
        42      VLR_PESQ_CO = MAKE;
        43
        44      EXEC CICS RETURN TRANSID('ADZA')
        45         COMMAREA(COMABASE) LENGTH(24);
        46      END;
        47
        48   EXEC CICS RETURN ;
        49
        50   END DBPGADZ;

41-42        Posicionando o próximo ISN e o novo valor para a condição de pesquisa
             especificada na MACRO PRIM., passados através da COMMAREA.
48           Retorna para iniciar no mesmo terminal a transação ADZA.




                                                                                     - 33 -

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:20
posted:12/7/2011
language:Portuguese
pages:33