DB2 - Banco de dados - SQLCA - www.cadcobol.com.br


Volta ao Menu Principal


Desenvolvido por DORNELLES Carlos Alberto - Analista de Sistemas - Brasília DF. - cad_cobol@hotmail.com

SQL communication area (SQLCA)
Um SQLCA é uma estrutura ou coleção de variáveis que são atualizadas depois que cada declaração de SQL é executada.
Um programa de aplicação que contém declarações de SQL executáveis tem que conter um SQLCA obrigatoriamente.

Há duas exceções:
  • Um programa que é precompilado com a opção STDSQL(YES) não deve conter um SQLCA.
  • Em alguns casos (como discutido abaixo dentro do Fortran), um programa de Fortran deve conter mais de um SQLCA.
Em todas as linguagens host exceto o REXX, a declaração SQL INCLUDE pode ser usada para prover a declaração do SQLCA.

No COBOL e assembler:
O nome da área de armazenamento deve ser SQLCA.

No PL/I e C:
O nome da estrutura deve ser SQLCA.
Toda declaração SQL executável deve estar dentro da extensão de sua declaração.

Em alguns caso contrário, C é usado para representar as linguagens de programação C/370 e C/C++ para MVS/ESA.

No Fortran:
O nome da COMMON área para as variáveis de INTEGER do SQLCA deve ser SQLCA1;
o nome da COMMON área para as variáveis CHARACTER variáveis devem ser SQLCA2.
Uma definição de SQLCA é requerida para todo subprograma que contém declarações de SQL.
Uma declaração SQLCA também é necessária para o programa principal se o mesmo contém declarações de SQL.

No REXX:
DB2 gera o SQLCA automaticamente.
Um procedimento de REXX não pode usar a declaração INCLUDE.
O REXX SQLCA tem um formato um pouco diferente de SQLCAs dos outros idiomas.
Veja "O REXX SQLCA" na página 929 para informação sobre o REXX SQLCA.



SQL - Structured Query Language - SQLCA - Communication area
Descrição dos campos

A maior parte, COBOL, C, PL/I e Assembler usa os mesmo nomes, e no Fortran os nomes são diferentes.
Porém, há uma instância onde C, PL/I e assembler os nomes são diferentes do COBOL.

Assembler,
COBOL
ou PL/I

C

Fortran

Tipo de dado

Propósito

SQLCAID sqlcaid Not used. CHAR(8) Um "eye catcher" para dumps de armazenamento, contendo o texto 'SQLCA'.
SQLCABC sqlcabc Not used. INTEGER Contém o tamanho do SQLCA: 136.
SQLCODE
(nota 1)
SQLCODE SQLCOD INTEGER Contém o código de retorno do SQL. (nota 2)
Código    Mensagem
0             Execução OK (embora pudesse ter mensagens de advertencias).
positivo
               Execução OK, mas com uma condição de advertência ou outra informação.
negativo
               Condição de erro.
SQLERRML
(nota 3)
sqlerrml
(nota 3)
SQLTXL SMALLINT Indicador do comprimento do SQLERRMC, na faixa de 0 até 70.
SQLERRMC
(nota 3)
sqlerrmc
(nota 3)
SQLTXT VARCHAR(70) Contém um ou mais símbolos, separados por X'FF', que são substituidos por variáveis na descrição das condições de erros.
SQLERRP sqlerrp SQLERP CHAR(8) Provê uma assinatura de produto e, no caso de um erro, gera um diagnóstico com informações, como o nome do módulo que detectou o erro.
Em todos os casos, os primeiros três caráter são 'DSN ' para DB2, OS/390 e z/OS
SQLERRD(1) sqlerrd[0] SQLERR(1) INTEGER Contém o número de linhas da pesquisa em uma tabela quando a posição do cursor for depois da última linha (quer dizer, quando SQLCODE é igual a +100).

SQLERRD(1) também pode conter um código de erro interno.
SQLERRD(2) sqlerrd[1] SQLERR(2) INTEGER Contém o número de linhas da pesquisa em uma tabela quando a posição do cursor for depois da última linha (quer dizer, quando SQLCODE é igual a +100).

SQLERRD(2) também pode conter um código de erro interno.
SQLERRD(3) sqlerrd[2] SQLERR(3) INTEGER Contém o número de linhas afetadas depois de um INSERT, UPDATE E DELETE (mas não linhas deletadas com um DELETE CASCADE).
Seta para 0 (zero) se a declaração SQL falhar, indicando que todas as alteradas executadas foram canceladas.
Seta para -1 para um massa deletada desde uma tabela segmentada ou para uma criada como GLOBAL TEMPORARY TABLE.
Para os sqlcode's -911 e -913, SQLERRD(3) contém o código da razão para o intervalo ou paralisação completa.
SQLERRD(4) sqlerrd[3] SQLERR(4) INTEGER Geralmente, contém timerons, um pequeno valor de ponto flutuante que indica uma estimativa relativa áspera de recursos requeridos (Veja nota 4).
Não reflete uma estimativa do tempo requerida.
Quando estiver preparando a definição de uma declaração de SQL dinamicamente, você pode usar este campo como um indicador do custo relativo da declaração de SQL preparada.
Para uma declaração particular, este número pode variar com mudanças às estatísticas no catálogo.
Também está sujeito a mudança entre liberações de DB2 para OS/390 e z/OS
SQLERRD(5) sqlerrd[4] SQLERR(5) INTEGER Contém a posição ou coluna da sintaxe de erro para uma declaração PREPARE ou EXECUTE IMMEDIATE
SQLERRD(6) sqlerrd[5] SQLERR(6) INTEGER Contém um código de erro interno.
SQLWARN0 SQLWARN0 SQLWRN(0) CHAR(1) Contém um espaço em branco se nenhum outro indicador é fixado a uma condição de advertência (quer dizer, nenhum outro indicador contém um W ou Z).
Contém um W se pelo menos um outro indicador contiver um W ou Z.
SQLWARN1 SQLWARN1 SQLWRN(1) CHAR(1) Contém a W se o valor da coluna foi truncado quando assinado para uma variável host.
Contém um N para um CURSOR non-scrollable e um S para um CURSOR scrollable depois da declaração OPEN CURSOR ou ALLOCATE CURSOR.
SQLWARN2 SQLWARN2 SQLWRN(2) CHAR(1) Contém um W se foram eliminados valores nulos do argumento de uma função de coluna;
não necessariamente fixa para W a função MIN porque seus resultados não são dependentes na eliminação de valores nulos.
SQLWARN3 SQLWARN3 SQLWRN(3) CHAR(1) Contém um W se o número de colunas do resultado for maior que o número de variáveis host.
Contém um Z se menos locators foram providenciados dentro a declaração de ASSOCIATE LOCATORS que o procedimento armazenado retornou.
SQLWARN4 SQLWARN4 SQLWRN(4) CHAR(1) Contém um W se uma delcaração UPDATE ou DELETE preparada não inclui uma cláusula WHERE. Para um CURSOR scrollable, contém um I para um CURSOR insensitivo e S para CURSOR estático sensitivo depois de uma declaração OPEN CURSOR ou ALLOCATE CURSOR; contém um branco se o CURSOR não é scrollable.
SQLWARN5 SQLWARN5 SQLWRN(5) CHAR(1) Contém um W se a declaração de SQL não foi executada porque não é uma declaração de SQL válida em DB2 para OS/390 e z/OS.
Contém um valor de caráter de 1 (sómente leitura), 2 (leitura e deletar), ou 4 (leitura, deletar e atualizar) para refletir a capacidade do cursor depois da declaração OPEN CURSOR ou ALLOCATE CURSOR.
SQLWARN6 SQLWARN6 SQLWRN(6) CHAR(1) Contém um W se a adição de um mês ou duração de ano para um DATE ou TIMESTAMP resultam em um dia inválido (por exemplo, 31 de junho).
Indica que o valor do dia foi mudado para o último dia do mês para fazer o resultado válido.
SQLWARN7 SQLWARN7 SQLWRN(7) CHAR(1) Contém um W se um ou mais digito diferente de zeros foram eliminados da parte fracional do número usado como o operando de um operação de multiplicação ou divisão.
SQLWARN8 SQLWARN8 SQLWRX(1) CHAR(1) Contém um W se um caráter que não pôde ser convertido foi trocado com um caráter substituto.
SQLWARN9 SQLWARN9 SQLWRX(2) CHAR(1) Contém um W se foram ignoradas exceções de aritmética durante um COUNT ou COUNT_BIG.
Contém um Z se o procedimento armazenado retornou múltiplos resultados setados.
SQLWARNA SQLWARNA SQLWRX(3) CHAR(1) Contém um W se pelo menos um campo de caráter do SQLCA ou o SQLDA, nomes ou rótulos são inválidos devido a um erro de conversão de caráter.
SQLSTATE sqlstate SQLSTT CHAR(5) Contém um código de retorno para o resultado da mais recente execução de uma declaração de SQL (Veja nota 5).


Nota:
  1. Quanto a opção STDSQL(YES) do precompilador é usada, SQLCODE é substituído por SQLCADE em SQLCA.
  2. No COBOL, o SQLERRM contem o SQLERRML e SQLERRMC.
    No PL/I e C, a string de tamanho variavel SQLERRM e equivalente ao SQLERRML.
    Em assembler, a área de armazenamento SQLERRM e equivalente ao SQLERRML e SQLERRMC.
    Veja os exemplos para as várias linguagens no "The included SQLCA".
  3. O uso de timerons pode requerer manipulação especial porque eles são valores de ponto flutuante em um array INTEGER.
    No PL/I, por exemplo, você poderia primeiro copiar o valor variável baseada de um BIN FIXED(31) que coincide com uma variável BIN FLOAT(24)
  4. Para as mensagens específicas dos códigos de retorno dos SQLCode's Clique aqui
  5. Para saber a descrição dos valores dos SQLSTATE's Clique aqui

Relacionamos abaixo a descrição do INCLUDE SQLCA em quatro linguagens diferentes:
C O B O L

       01  SQLCA.
           05  SQLCAID             PIC X(8).
           05  SQLCABC             PIC S9(9)     COMP-4.
           05  SQLCODE             PIC S9(9)     COMP-4.
           05  SQLERRM.
               49  SQLERRML        PIC S9(4)     COMP-4.
               49  SQLERRMC        PIC X(70).
           05  SQLERRP             PIC X(8).
           05  SQLERRD             OCCURS 6 TIMES
                                   PIC S9(9)     COMP-4.
           05  SQLWARN.
               10  SQLWARN0        PIC X.
               10  SQLWARN1        PIC X.
               10  SQLWARN2        PIC X.
               10  SQLWARN3        PIC X.
               10  SQLWARN4        PIC X.
               10  SQLWARN5        PIC X.
               10  SQLWARN6        PIC X.
               10  SQLWARN7        PIC X.
           05  SQLEXT. 
               10  SQLWARN8        PIC X.
               10  SQLWARN9        PIC X.
               10  SQLWARNA        PIC X.
               10  SQLSTATE        PIC X(5).
              

A S S E M B L E R

           SQLCA    DS 0F
           SQLCAID  DS CL8        ID
           SQLCABC  DS F          BYTE COUNT
           SQLCODE  DS F          RETURN CODE
           SQLERRM  DS H,CL70     ERR MSG PARMS
           SQLERRP  DS CL8        IMPL-DEPENDENT
           SQLERRD  DS 6F
           SQLWARN  DS 0C         WARNING FLAGS
           SQLWARN0 DS C'W' IF ANY
           SQLWARN1 DS C'W' = WARNING
           SQLWARN2 DS C'W' = WARNING
           SQLWARN3 DS C'W' = WARNING
           SQLWARN4 DS C'W' = WARNING
           SQLWARN5 DS C'W' = WARNING
           SQLWARN6 DS C'W' = WARNING
           SQLWARN7 DS C'W' = WARNING
           SQLEXT   DS 0CL8
           SQLWARN8 DS C
           SQLWARN9 DS C
           SQLWARNA DS C
           SQLSTATE DS CL5
              

C

           #ifndef SQLCODE
           struct sqlca
           {
                  unsigned char sqlcaid[8];
                  long          sqlcabc;
                  long          sqlcode;
                  short         sqlerrml;
                  unsigned char sqlerrmc[70];
                  unsigned char sqlerrp[8];
                  long          sqlerrd[6];
                  unsigned char sqlwarn[11];
                  unsigned char sqlstate[5];
           };
           #define  SQLCODE   sqlca.sqlcode
           #define  SQLWARN0  sqlca.sqlwarn[0]
           #define  SQLWARN1  sqlca.sqlwarn[1]
           #define  SQLWARN2  sqlca.sqlwarn[2]
           #define  SQLWARN3  sqlca.sqlwarn[3]
           #define  SQLWARN4  sqlca.sqlwarn[4]
           #define  SQLWARN5  sqlca.sqlwarn[5]
           #define  SQLWARN6  sqlca.sqlwarn[6]
           #define  SQLWARN7  sqlca.sqlwarn[7]
           #define  SQLWARN8  sqlca.sqlwarn[8]
           #define  SQLWARN9  sqlca.sqlwarn[9]
           #define  SQLWARNA  sqlca.sqlwarn[10]
           #define  SQLSTATE  sqlca.sqlstate
           #endif
           struct sqlca sqlca;
              

F O R T R A N

      **
      *    THE SQL COMMUNICATIONS AREA
      **
           INTEGER     SQLCOD,
          C            SQLERR(6),
          C            SQLTXL*2
           COMMON /SQLCA1/SQLCOD, SQLERR,SQLTXL
           CHARACTER      SQLERP*8,
          C               SQLWRN(0:7)*1,
          C               SQLTXT*70,
          C               SQLEXT*8,
          C               SQLWRX(1:3)*1,
          C               SQLSTT*5
           COMMON /SQLCA2/SQLERP,SQLWRN,SQLTXT,SQLWRX,
          C               SQLSTT
           EQUIVALENCE (SQLWRX,SQLEXT)


© Copyright IBM Corp.


Volta ao Menu Principal