A coleção Field
A coleção Fields é uma das coleções intrínsecas do ADO. Uma coleção é um conjunto ordenado de itens que podem ser referenciados como uma unidade. Para obter mais informações sobre as coleções do ADO, confira O modelo de objeto do ADO.
A coleção Fields contém um objeto Field para cada campo (coluna) no Recordset. Como todas as coleções do ADO, ela tem as propriedades Count e Item, bem como os métodos Append e Refresh. Também tem métodos CancelUpdate, Delete, Resync e Update, que não estão disponíveis para outras coleções do ADO.
Como examinar a coleção Fields
Considere a coleção Fields do Recordset de exemplo introduzido nesta seção. O Recordset de exemplo foi derivado da instrução SQL
SELECT ProductID, ProductName, UnitPrice FROM Products WHERE CategoryID = 7
Portanto, você deve descobrir que a coleção Recordset Fields contém três campos.
'BeginWalkFields
Dim objFields As ADODB.Fields
Dim intLoop As Integer
objRs.Open strSQL, strConnStr, adOpenForwardOnly, adLockReadOnly, adCmdText
Set objFields = objRs.Fields
For intLoop = 0 To (objFields.Count - 1)
Debug.Print objFields.Item(intLoop).Name
Next
'EndWalkFields
Esse código apenas determina o número de objetos Field na coleção Fields usando a propriedade Count e faz um loop pela coleção, retornando o valor da propriedade Name para cada objeto Field. Você pode usar muito mais propriedades Field para obter informações sobre um campo. Para obter mais informações sobre como consultar um Field, confira O objeto Field.
Como contar colunas
Como era de se esperar, a propriedade Count retorna o número real de objetos Field na coleção Fields. Como a numeração dos membros de uma coleção começa com zero, você deve sempre codificar os loops começando com o membro zero e terminando com o valor da propriedade Count menos 1. Se você estiver usando o Microsoft Visual Basic e quiser fazer um loop pelos membros de uma coleção sem verificar a propriedade Count, use o comando For Each...Next.
Se a propriedade Count for zero, não haverá objetos na coleção.
Como acessar o campo
Assim como acontece com qualquer coleção do ADO, a propriedade Item é a propriedade padrão da coleção. Ela retorna o objeto Field individual especificado pelo nome ou pelo índice transmitido a ela. Portanto, as seguintes instruções são equivalentes ao Recordset de exemplo:
objField = objRecordset.Fields.Item("ProductID")
objField = objRecordset.Fields("ProductID")
objField = objRecordset.Fields.Item(0)
objField = objRecordset.Fields(0)
Se esses métodos são equivalentes, qual é o melhor? Depende. O uso de um índice para recuperar um Field da coleção é mais rápido porque ele acessa o Field diretamente sem precisar executar uma pesquisa de cadeia de caracteres. Por outro lado, a ordem de Fields dentro da coleção precisa ser conhecida e, se a ordem for alterada, a referência ao índice Fields precisará ser alterada onde quer que ela ocorra. Embora um pouco mais lento, o uso do nome do Field é mais flexível porque não depende da ordem dos Fields na coleção.
Como usar o método Refresh
Ao contrário de algumas outras coleções do ADO, o uso do método Refresh na coleção Fields não tem efeito visível. Para recuperar alterações da estrutura de banco de dados subjacente, você precisa usar o método Requery ou se o objeto Recordset não der suporte a indicadores, o método MoveFirst, que fará com que o comando seja executado no provedor novamente.
Como adicionar campos a um conjunto de registros
O método Append é usado para adicionar campos a um Recordset.
Use o método Append para fabricar um Recordset por meio de programação sem abrir uma conexão com uma fonte de dados. Um erro em tempo de execução ocorrerá se o método Append for chamado na coleção Fields de um Recordset aberto ou em um Recordset em que a propriedade ActiveConnection foi definida. Você pode acrescentar campos apenas a um Recordset que não está aberto e que ainda não foi conectado a uma fonte de dados. No entanto, para especificar valores para os Fields recém-acrescentados, o Recordset precisa primeiro ser aberto.
Em geral, os desenvolvedores precisam ter um lugar para armazenar temporariamente alguns dados ou querem que alguns dados atuem como se viessem de um servidor para que eles possam participar da associação de dados em uma interface do usuário. O ADO (em conjunto com o Serviço de Cursor da Microsoft para OLE DB) permite que o desenvolvedor crie um objeto Recordset vazio especificando as informações de coluna e chamando Open. No exemplo a seguir, três novos campos são acrescentados a um novo objeto Recordset. Em seguida, o Recordset é aberto, dois novos registros são adicionados e o Recordset é mantido em um arquivo. (Para obter mais informações sobre a persistência de Recordset, confira Como atualizar e persistir dados.)
'BeginFabricate
Dim objRs As ADODB.Recordset
Set objRs = New ADODB.Recordset
With objRs.Fields
.Append "StudentID", adChar, 11, adFldUpdatable
.Append "FullName", adVarChar, 50, adFldUpdatable
.Append "PhoneNmbr", adVarChar, 20, adFldUpdatable
End With
With objRs
.Open
.AddNew
.Fields(0) = "123-45-6789"
.Fields(1) = "John Doe"
.Fields(2) = "(425) 555-5555"
.Update
.AddNew
.Fields(0) = "123-45-6780"
.Fields(1) = "Jane Doe"
.Fields(2) = "(615) 555-1212"
.Update
End With
objRs.Save App.Path & "FabriTest.adtg", adPersistADTG
objRs.Close
'EndFabricate
O uso do método Fields Append é diferente entre o objeto Recordset e o objeto Record. Para obter mais informações sobre o objeto Record, confira Registros e fluxos.