O objeto Field

Cada objeto Field geralmente corresponde a uma coluna em uma tabela de banco de dados. No entanto, um Field também pode representar um ponteiro para outro Recordset, chamado de capítulo. As exceções, como as colunas de capítulo, serão abordadas mais adiante neste guia.

Use a propriedade Value dos objetos Field para definir ou retornar os dados do registro atual. Dependendo da funcionalidade exposta pelo provedor, algumas coleções, métodos ou propriedades de um objeto Field podem não estar disponíveis.

Com as coleções, os métodos e as propriedades de um objeto Field, você pode fazer o seguinte:

• Retorna o nome de um campo usando a propriedade Name.

• Ver ou alterar os dados no campo usando a propriedade Value. Value é a propriedade padrão do objeto Field.

• Retornar as características básicas de um campo usando as propriedades Type, Precision e NumericScale.

• Retornar o tamanho declarado de um campo usando a propriedade DefinedSize.

• Retornar o tamanho real dos dados em determinado campo usando a propriedade ActualSize.

• Determinar os tipos de funcionalidade com suporte em determinado campo usando a propriedade Attributes e a coleção Properties.

• Processar os valores dos campos que contêm dados de caracteres longos ou binários longos usando os métodos AppendChunk e GetChunk.

Resolver discrepâncias nos valores de campo durante a atualização em lote usando as propriedades OriginalValue e UnderlyingValue se o provedor dá suporte a atualizações em lote.

Como descrever um campo

Os tópicos a seguir discutirão as propriedades do objeto Field que representam informações que descrevem o próprio objeto Field, ou seja, metadados sobre o campo. Essas informações podem ser usadas para determinar muito sobre o esquema do Recordset. Essas propriedades incluem Type, DefinedSize e ActualSize, Name e NumericScale e Precision.

Como descobrir o tipo de dados

A propriedade Type indica o tipo de dados do campo. As constantes enumeradas de tipo de dados com suporte no ADO são descritas em DataTypeEnum na Referência do Programador do ADO.

Para tipos numéricos de ponto flutuante, como adNumeric, você pode obter mais informações. A propriedade NumericScale indica quantos dígitos à direita do ponto decimal serão usados para representar valores para o Field. A propriedade Precision especifica o número máximo de dígitos usados para representar valores para o Field.

Como determinar o tamanho do campo

Use a propriedade DefinedSize para determinar a capacidade de dados de um objeto Field.

Use a propriedade ActualSize para retornar o comprimento real do valor de um objeto Field. Para todos os campos, a propriedade ActualSize é somente leitura. Se o ADO não puder determinar o comprimento do valor do objeto Field, a propriedade ActualSize retornará adUnknown.

As propriedades DefinedSize e ActualSize têm propósitos diferentes. Por exemplo, considere um objeto Field com o tipo declarado adVarChar e o valor da propriedade DefinedSize igual a 50, contendo um só caractere. O valor da propriedade ActualSize retornado é o comprimento em bytes do caractere único.

Como determinar o conteúdo do campo

O identificador da coluna da fonte de dados é representado pela propriedade Name do Field. A propriedade Value do objeto Field retorna ou define o conteúdo de dados real do campo. Essa é a propriedade padrão.

Para alterar os dados em um campo, defina a propriedade Value como um novo valor do tipo correto. O tipo de cursor precisa dar suporte a atualizações para alterar o conteúdo de um campo. A validação do banco de dados não é feita aqui no modo de lote. Portanto, você precisará verificar se há erros ao chamar UpdateBatch nesse caso. Alguns provedores também dão suporte às propriedades UnderlyingValue e OriginalValue do objeto ADO Field para ajudar você a resolver conflitos quando você tentar fazer atualizações em lotes. Para obter detalhes sobre como resolver esses conflitos, confira Como editar os dados.

Como obter mais informações sobre os campos

Os objetos ADO têm dois tipos de propriedades: internas e dinâmicas. Até este ponto, somente as propriedades internas do objeto Field foram abordadas.

As propriedades internas são as propriedades implementadas no ADO e imediatamente disponíveis para qualquer novo objeto, por meio da sintaxe MyObject.Property. Elas não são exibidas como objetos Property na coleção Properties de um objeto.

As propriedades dinâmicas são definidas pelo provedor de dados subjacente e são exibidas na coleção Properties do objeto ADO apropriado. Por exemplo, uma propriedade específica do provedor pode indicar se um objeto Recordset dá suporte a transações ou atualização. Essas propriedades adicionais serão exibidas como objetos Property na coleção Properties do objeto Recordset. As propriedades dinâmicas só podem ser referenciadas por meio da coleção com a sintaxe MyObject.Properties(0) ou MyObject.Properties("Name").

Não é possível excluir nenhum tipo de propriedade.

Um objeto Property dinâmico tem quatro propriedades internas próprias:

• A propriedade Name é uma cadeia de caracteres que identifica a propriedade.

• A propriedade Type é um inteiro que especifica o tipo de dados de propriedade.

• A propriedade Value é uma variante que contém a configuração da propriedade. Value é a propriedade padrão de um objeto Property.

• A propriedade Attributes é um valor Long que indica as características da propriedade específicas do provedor.

A coleção Properties do objeto Field contém metadados adicionais sobre o campo. O conteúdo dessa coleção varia conforme o provedor. O exemplo de código a seguir examina a coleção Properties do exemplo de Recordset apresentado no início desta seção. Primeiro, ele examina o conteúdo da coleção. Esse código usa o Provedor OLE DB para SQL Server, de modo que a coleção Properties contenha informações relevantes para esse provedor.

'BeginFieldProps  
    Dim objProp As ADODB.Property  
  
    For intLoop = 0 To (objFields.Count - 1)  
        Debug.Print objFields.Item(intLoop).Name  
  
        For Each objProp In objFields(intLoop).Properties  
            Debug.Print vbTab & objProp.Name & " = " & objProp.Value  
        Next objProp  
    Next intLoop  
'EndFieldProps  

Como lidar com os dados binários

Use o método AppendChunk em um objeto Field para preenchê-lo com os dados de caracteres ou binários longos. Em situações em que a memória do sistema é limitada, use o método AppendChunk para processar valores longos em partes em vez da totalidade.

Se o bit adFldLong da propriedade Attributes de um objeto Field for definido como True, você poderá usar o método AppendChunk nesse campo.

A primeira chamada AppendChunk em um objeto Field grava dados no campo, substituindo os dados existentes. As chamadas AppendChunk seguintes os adicionam aos dados existentes. Se você estiver acrescentando dados a um campo e definir ou ler o valor de outro campo no registro atual, o ADO vai pressupor que você tenha terminado de acrescentar dados ao primeiro campo. Se você chamar o método AppendChunk no primeiro campo novamente, o ADO interpretará a chamada como uma nova operação AppendChunk e substituirá os dados existentes. O acesso de campos em outros objetos Recordset que não são clones do primeiro objeto Recordset não interromperá as operações de AppendChunk.

Use o método GetChunk em um objeto Field para recuperar parte ou todos os dados de caracteres ou binários longos. Em situações em que a memória do sistema é limitada, use o método GetChunk para processar valores longos em partes em vez da totalidade.

Os dados que uma chamada GetChunk retorna são atribuídos à variável. Se Size for maior que os dados restantes, o método GetChunk retornará apenas os dados restantes sem a variável de preenchimento com espaços vazios. Se o campo estiver vazio, o método GetChunk retornará um valor nulo.

Cada chamada GetChunk seguinte recupera dados que começam do ponto em que a chamada GetChunk anterior parou. No entanto, se você estiver recuperando dados de um campo e definir ou ler o valor de outro campo no registro atual, o ADO vai pressupor que você tenha terminado de recuperar os dados do primeiro campo. Se você chamar o método GetChunk no primeiro campo novamente, o ADO interpretará a chamada como uma nova operação GetChunk e começará a ler partindo do início dos dados. O acesso de campos em outros objetos Recordset que não são clones do primeiro objeto Recordset não interromperá as operações de GetChunk.

Se o bit adFldLong da propriedade Attributes de um objeto Field for definido como True, você poderá usar o método GetChunk nesse campo.

Se não houver nenhum registro atual quando você usar o método GetChunk ou AppendChunk em um objeto Field, ocorrerá o erro 3021 (nenhum registro atual).

Para ver um exemplo de como usar esses métodos para processar dados binários, confira os exemplos do Método AppendChunk e do Método GetChunk na Referência do Programador do ADO.