Método Append (ADO)

  • Artigo

Adiciona um objeto a uma coleção. Se a coleção for Fields, um objeto Field poderá ser criado antes de ser acrescentado à coleção.

Sintaxe

  
collection.Append object  
fields.Append Name, Type, DefinedSize, Attrib, FieldValue

Parâmetros

collection
Um objeto de coleção.

campos
Uma coleção Fields.

object
Uma variável de objeto que representa o objeto a ser acrescentado.

Nome
Um valor String que contém o nome do novo objeto Field e não deve ser o mesmo nome que qualquer outro objeto em campos.

Tipo
Um valor DataTypeEnum, cujo valor padrão é adEmpty, que especifica o tipo de dados do novo campo. Os seguintes tipos de dados não têm suporte pelo ADO e não devem ser usados ao acrescentar novos campos a um Objeto Recordset (ADO): adIDispatch, adIUnknown e adVariant.

DefinedSize
Opcional. Um valor Long que representa o tamanho definido, em caracteres ou bytes, do novo campo. O valor padrão para esse parâmetro é derivado de Type. Campos com um DefinedSize maior que 255 bytes são tratados como colunas de comprimento variável. O padrão para DefinedSize não é especificado.

Attrib
Opcional. Um valor FieldAttributeEnum, cujo valor padrão é adFldDefault, que especifica atributos para o novo campo. Se esse valor não for especificado, o campo conterá atributos derivados de Type.

FieldValue
Opcional. Uma Variant que representa o valor do novo campo. Se não for especificado, o campo será acrescentado com um valor nulo.

Comentários

Coleção Parâmetros

Você deve definir a propriedade Type de um objeto Parameter antes de anexá-la à coleção Parameters. Se você selecionar um tipo de dados de comprimento variável, também deverá definir a propriedade Size como um valor maior que zero.

Descrever os parâmetros por conta própria minimiza as chamadas para o provedor e, portanto, melhora o desempenho quando você usa procedimentos armazenados ou consultas parametrizadas. No entanto, você deve saber as propriedades dos parâmetros associados ao procedimento armazenado ou à consulta parametrizada que você deseja chamar.

Use o método CreateParameter para criar objetos Parameter com as configurações de propriedade apropriadas e use o método Append para adicioná-los à coleção Parameters. Isso permite que você defina e retorne valores de parâmetro sem precisar chamar o provedor para obter as informações do parâmetro. Se você estiver gravando em um provedor que não fornece informações de parâmetro, deverá usar este método para preencher manualmente a coleção Parameters usando esse método para usar parâmetros.

Coleção Campos

O parâmetro FieldValue só é válido ao adicionar um objeto Field a um objeto Record, não a um objeto Recordset. Com um objeto Record, você pode acrescentar campos e fornecer valores ao mesmo tempo. Com um objeto Recordset, você deve criar campos enquanto o Recordset está fechado e, em seguida, abrir o Recordset e atribuir valores aos campos.

Observação

Para novos objetos Field que foram acrescentados à coleção Fields de um objeto Record, a propriedade Value deve ser definida antes que qualquer outra propriedade Field possa ser especificada. Primeiro, um valor específico para a propriedade Value precisa ter sido atribuído e Update na coleção Fields precisa ter sido chamado. Em seguida, outras propriedades, como Type ou Attributes, podem ser acessadas. Objetos Field dos seguintes tipos de dados (DataTypeEnum) não podem ser anexados à coleção Fields e causarão um erro: adArray, adChapter, adEmpty, adPropVariant e adUserDefined. Além disso, os seguintes tipos de dados não têm suporte pelo ADO: adIDispatch, adIUnknown e adIVariant. Para esses tipos, nenhum erro ocorrerá quando acrescentado, mas o uso pode produzir resultados imprevisíveis, incluindo vazamentos de memória.

Conjunto de registros

Se você não definir a propriedade CursorLocation antes de chamar o método Append, CursorLocation será definido como adUseClient (um valor CursorLocationEnum) automaticamente quando o método Open do objeto Recordset for chamado.

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. Normalmente, esse é o caso quando um objeto Recordset é fabricado com o método CreateRecordset ou atribuído a uma variável de objeto.

Record

Um erro em tempo de execução não ocorrerá se o método Append for chamado na coleção Fields de um registro aberto. O novo campo será adicionado à coleção Fields do objeto Record. Se o Record foi derivado de um Recordset, o novo campo não aparecerá na coleção Fields do objeto Recordset.

Um campo inexistente pode ser criado e acrescentado à coleção Fields atribuindo um valor ao objeto de campo como se já existisse na coleção. A atribuição disparará a criação automática e o acréscimo do objeto Field e, em seguida, a atribuição será concluída.

Depois de acrescentar um Field à coleção Fields de um objeto Record, chame o método Update da coleção Fields para salvar a alteração.

Aplica-se A

Consulte Também

Exemplo dos métodos Append e CreateParameter (VB)
Exemplo dos métodos Append e CreateParameter (VC++)
Método CreateParameter (ADO)
Método Delete (Coleção de campos ADO)
Método Delete (Coleção de parâmetros ADO)
Método Delete (Conjunto de registros ADO)
Método Update