SQLCA - SQL área de comunicação

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).

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


           #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)