TOTVSTEC

Árvore de páginas

Realiza a inclusão de registros em blocos, tornando o processo muito mais rápido.

Sintaxe

TCDBInsert( < cTable >, < cCols >, < aData > )

Parâmetros

Nome

Tipo

Descrição

Obrigatório

Referência

cTable

caractere

Indica o nome da tabela onde ocorrerá a inserção de dados

X


cCols

caractere

Lista de campos (separados por vírgula) que será atualizados

X


aData

vetor

Array de dados que serão incluídos nos campos listados em cCols

X


Retorno

Nome

Tipo

Descrição

nRet

numérico

Valor numérico informando o resultado da execução da função.
  - Maior ou igual a 0 (zero), sucesso na execução.
  - Menor que 0 (zero), erro na execução.

Atenção

Esta função não está disponível para uso com RPODB=SQLITE.

Observações

  • Caso a instrução seja executada sem conexão ativa, uma ocorrência de Warning é gerada no console do server: Warning - TCDBInsert - statement ignored - No connection.
  • Caso a quantidade de colunas de aData seja diferente da lista de campos em cCols, uma ocorrência de erro é gerada e a thread abortada: Error - TCDBInsert - Number of columns does not match field list ( Row X )
  • Caso um tipo de dado não suportado seja informado em aData, uma ocorrência de erro é gerada e a thread abortada: Error - TCDBInsert - Unexpected Element Type ( Row X Column Y )
  • Caso o parâmetro cCols esteja vazio, uma ocorrência de erro é gerada e a thread abortada: Error - TCDBInsert - Invalid Empty Field List
  • Caso o array aData esteja vazio, uma ocorrência de erro é gerada e a thread abortada: Error - TCDBInsert - Invalid Empty Data Array
  • Caso o array aData tenha tamanho superior ao suportado pela configuração MaxStringSize, uma ocorrência de erro é gerada e a thread abortada: TC_DBInsert - Data length greater than the MaxStringSize configuration.
  • O cenário ideal de uso desta função são processos de criação de base de dados, onde os novos registros não sejam inseridos por múltiplos processos – a execução da TCDBInsert com outras operações de inserção concorrente, principalmente em tabelas que não utilizam o controle de numeração automática do RECNO pelo Banco de Dados, está sujeita a falha por violação da chave primária de regisrtro.
  • Em tabelas que utilizam o recurso de recno incremental, o campo R_E_C_N_O_ não deve ser informado.
    Para tabelas que não utilizam este recurso, é necessário tratar o campo R_E_C_N_O_.**
  • A partir do DBAccess Build 20191119, não é mais necessário informar o campo R_E_C_N_O_.

Exemplos

user function test()

  local cTable := "T1"
  local aStru := {}
  local aRow  := {}
  local aIns  := {}
  local nI

  TCLink()

  if TCCanOpen(cTable)
    TCDelFile(cTable)
  endif

  aAdd(aStru,{"T1_CPOC","C",10,0})
  aAdd(aStru,{"T1_CPOD","D", 8,0})
 
  DBCreate(cTable,aStru,"TOPCONN")
 
  For nI := 1 to 1000

    aRow := Array( len(aStru) + 1 )
    aRow[1] := "Lin" + cValToChar(nI)
    aRow[2] := date() + nI
    aRow[3] := nI
    
    aadd( aIns , aRow )
     
    if len(aIns) >= 200

      if ( TCDBInsert(cTable,"T1_CPOC,T1_CPOD,R_E_C_N_O_",aIns) ) < 0
        UserException(tcSQLError())
      endif
      
      asize(aIns,0)
    endif

  Next
 
  DBUseArea(.T., "TOPCONN", cTable, (cTable), .F., .F.)
  DBGoTo(500)
  
  conout('| T1_CPOC   : ' + Alltrim((cTable)->T1_CPOC) + ' |' )
  conout('| R_E_C_N_O_: ' + cValToChar(recno()) + '    |' )

  DBCloseArea()
  TCUnLink()
 
return
  • Sem rótulos