Método Append (ADO)

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

Sintaxe

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

Parâmetros

da coleção
Um objeto de coleção.

campos
Uma coleção Fields.

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

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

tipo
Um valor DataTypeEnum, cujo valor padrão é adEmpty, que especifica o tipo de dados do novo campo. Os tipos de dados a seguir não são compatíveis com o ADO e não devem ser usados ao acrescentar novos campos a um do objetoRecordset (ADO): adIDispatch, adIUnknown, adVariant.

DefinedSize
Opcional. Um valor long que representa o tamanho definido, em caracteres ou bytes, do novo campo. O valor padrão desse parâmetro é derivado de Type. Campos que têm 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. Um Variant que representa o valor do novo campo. Se não for especificado, o campo será acrescentado com um valor nulo.

Observações

Coleção Parameters

Você deve definir a propriedade Type de um objeto Parameter antes de anexá-la à coleção parâmetros. 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 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 deseja chamar.

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

Coleção Fields

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 do conjunto de registros estiver fechado e, em seguida, abrir o conjunto de registros e atribuir valores aos campos.

Nota

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 deve ter sido atribuído e atualização na coleção Fields chamada. Em seguida, outras propriedades, como Type ou Attributes podem ser acessadas. Field objetos dos seguintes tipos de dados (DataTypeEnum) não podem ser acrescentados à coleção Campos e causarão um erro: adArrayadChapter, adEmpty, adPropVariant e adUserDefined. Além disso, não há suporte para os seguintes tipos de dados pelo ADO: adIDispatch, adIUnknowne 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 CursorLocationEnum valor) 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 uma recordset aberta ou em um Recordset em que a propriedade ActiveConnection foi definida. Você só pode acrescentar campos a um conjunto de registros que não está aberto e 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.

Registro

Um erro em tempo de execução não ocorrerá se o método Append for chamado na coleção campos de de um de registro deaberto. O novo campo será adicionado à coleção Fields do objeto Record. Se a de Registro for derivada de uma 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 campo de à coleção Fields de um objeto Record, chame o método Update da coleção Campos para salvar a alteração.

Aplica-se a

• da Coleção Fields (ADO)
• da Coleção de Parâmetros (ADO)

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 ADO Fields)
Método Delete (Coleção de Parâmetros do ADO)
do Método de Exclusão (Conjunto de Registros do ADO)
método Update