Page tree
Skip to end of metadata
Go to start of metadata

Define uma nova tabela ou um novo arquivo do tipo tabela e sua estrutura (campos).

Sintaxe

DBCreate( < cName >, < aStruct >, [ cDriver ] )

Parâmetros

Nome

Tipo

Descrição

Obrigatório

Referência

cName

caractere

Indica o nome da tabela que será criada. Dependendo da RDD utilizada é possível informar a pasta onde a tabela será criada que por padrão é a pasta inicial do ambiente configurado (StartPath).

X

 

aStruct

vetor

Indica o array que contém as informações dos campos que serão utilizados para criar a tabela.

X

 

cDriver

caractere

Indica a RDD (Replaceable Database Driver) que será utilizada para criar a tabela que por padrão é o driver de que gerencia tabelas locais (localFiles).

 

 

Observações

A seguir, observe a relação de erros mais comuns:

Mensagem

Descrição

Tipo

DBCreate - Database files can only be created on the server

O nome do arquivo não pode conter a unidade de disco, pois, por convenção, o mesmo seria criado na máquina onde o cliente remoto está sendo executado.

Erro Fatal

DBCreate - Invalid empty filename

O nome do arquivo não foi especificado.

Erro

DBCreate - Fields name cannot be 'DATA'

DATA é uma palavra reservada e seu uso não é suportado por aquela RDD ou por aquele SGBD.

Erro

DBCreate - The length of fields name must be at most 10

O nome do campo não pode ter mais de 10 caracteres.

Erro

DBCreate - Fields name must be defined

O nome do campo não foi definido.

Erro

DBCreate - Fields type is not defined

O tipo do campo não foi definido.

Erro

DBCreate - Invalid fileds type

O tipo do campo é diferente de 'C', 'D', 'L', 'M' e 'N'.

Erro

DBCreate - Invalid numeric field format

O formato para campo numérico utilizado é inválido.
Considerando 'len' o tamanho total do campo numérico e 'dec' o número de decimais, esse erro irá ocorrer quando:

  • (len = 1).and.(dec <> 0), ou seja, se o tamanho total for 1, o campo não pode ter decimais.
  • (len > 1).and.(len < dec + 2), ou seja, se o tamanho total for maior que 1, o mesmo deve ser maior que o número de decimais mais 2, para comportar o separador de decimais e ter pelo menos um algarismo na parte inteira.

Erro

Warning - DBCreate - field name will be truncated to 10 characters

O nome do campo possui mais de 10 caracteres e somente os 10 primeiros caracteres serão considerados.

Warning

DBCreate - Warning - Fields order has changed in file: Memo fields must be in the end of table in Ctree or Btrieve driver

A ordem dos campos foi alterada, os campos do tipo Memo foram movidos para o final da tabela.

Warning

As mensagens do tipo Erro encerram o programa com uma ocorrência de erro recuperável (possível de ser recuperada usando ErrorBlock ou SysErrorBlock). As mensagens do tipo Erro Fatal encerram o programa com uma ocorrência de erro não recuperável. As mensagens do tipo Warning não encerram o programa.

Importante

Para obter mais informações sobre erros decorrentes de permissões e direitos na pasta em que se está tentando criar o arquivo ou por algum problema no banco de dados, consulte as mensagens do servidor de aplicação e do banco de dados.

As mensagens de erro retornadas por esta função podem conter detalhes específicos da RDD em uso, estes detalhes são importantes para um diagnóstico adequado em caso de não-conformidade ao executar a instrução.

Independente da causa, uma falha na criação da tabela gera uma ocorrência crítica de erro AdvPL, que interrompe o programa/aplicação.

RDDs que podem ser utilizados:

  • CTREECDX: c-tree
  • DBFCDX: RDD indicada no arquivo de configuração do servidor de aplicação através da chave LocalFiles.
  • DBFCDXADS: ADS Local
  • DBFCDXAX: ADS Server
  • DBFCDXTTS: mantido por compatibilidade e possui o mesmo comportamento do RDD DBFCDX, utilize o RDD DBFCDX.
  • TOPCONN: RDD para uso com bancos de dados relacionais.
  • SQLITE_SYS: RDD para uso com banco de dados SQLite, com persistência de tabelas, mesmo depois de fechar a conexão (disponível a partir do Protheus 12).
  • SQLITE_TMP: RDD para uso com banco de dados SQLite, com tabelas em disco, removidas automaticamente ao final da conexão (disponível a partir do Protheus 12).
  • SQLITE_MEM: RDD para uso com banco de dados SQLite, com tabelas em memória, liberadas automaticamente ao final da conexão (disponível a partir do Protheus 12).

Limites

Cada RDD tem diferenciados limites com relação:

  • Quantidade de campos.
  • Tamanho máximo de header (soma dos tamanhos dos campos na estrutura).
  • Precisão numérica máxima, onde alguns dos limites estão implícitos na linguagem, outros implícitos na RDD e outros implícitos no SGBD utilizado.

Limites convencionados para o desenvolvimento de aplicações portáveis em AdvPL

Uma das características do AdvPL mais importante, e enfatizada no desenvolvimento de aplicações, é a portabilidade da solução para diferentes ambientes, plataformas e SGBDs com alterações mínimas no código-fonte AdvPL. Para procurar manter estas premissas no desenvolvimento de uma solução, é prudente respeitar alguns limites no desenvolvimento de aplicações.

As definições de uma tabela de dados envolvem o número de colunas da tabela, tamanho do registro (a soma do tamanho de todas as colunas), tamanhos máximos para cada campo, bem como as definções de índices da tabela, e para cada uma destas definições, existe um limite. Os limites abaixo convencionados são contemplados por todas as RDDs implementadas:

Limites convencionados

Limite

Número de campos por tabela

<= 256

Tamanho do registro

<= 7000 Bytes

Quantidade de índices por tabela

<= 15

Quantidade de campos por chave de índice

<= 14

Tamanho do registro da expressão de índice

<= 140 Bytes (*)

Tamanho máximo de um campo "C" (Caractere)

<= 254 Bytes

Tamanho máximo de um campo "M" (Memo)

<= 64 KB (**)

(*) O limite de 140 bytes para registro de expressão de índice foi convencionado devido à limitação do driver ADS (Local e/ou Server), onde a criação de uma expressão de índice com chave maior que 140 bytes pode ocasionar ocorrência de erro ADS 7022 - Maximum index levels exceeded, após suscessivas inclusões de registros na tabela.

(**) Com o uso da RDD TOPCONN, mediante parametrização específica no TOTVS Application Server (Servidor de Aplicação), é possível expandir o limite de armazenamento e recuperação de dados de campos "M" (Memo) para até 1 MB.

Mensagens de advertência

A tabela criada respeita a ordem dos campos especificado no array de parâmetro contendo a estrutura, exceto quando um ou mais campos do tipo "M" (MEMO) sejam especificados na estrutura, e os campos MEMO não sejam os últimos campos do array de estruturas, e a RDD utilizada for "CTREECDX" ou "DBFCDX" com o ambiente configurado para usar c-tree (Local e/ou Server) para controle de tabelas locais. Neste caso, a função emite uma mensagem de advertência e automaticamente coloca todos os campos do tipo "M" no final da estrutura definida.

Exemplos

#INCLUDE "TOTVS.CH"
User Function Exemplo()
  Local aEstrutura := { ;
                        { 'Cod'  , 'N',  3, 0 }, ;
                        { 'Nome' , 'C', 10, 0 }, ;
                        { 'Idade', 'N',  3, 0 }, ;
                        { 'Nasc' , 'D',  8, 0 }, ;
                        { 'Pagto', 'N',  7, 2 }  ;
                      }
  // Cria a tabela com a RDD corrente
  DBCREATE( '\teste\tst.dbf', aEstrutura )
  USE '\teste\tst.dbf' VIA 'DBFCDX' NEW
Return
  • No labels