Método append (ADO)

Aplica-se ao: Access 2013, Office 2013

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

Sintaxe

coleção. Objeto acréscimo

campos. Nome do anexo, tipo, definedsize, attrib, FieldValue

Parâmetros

Parâmetro	Descrição
collection	Um objeto de coleção.
fields	A 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 deve ser diferente de qualquer outro nome de objeto em fields.
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 aceitos pelo ADO e não devem ser usados no acréscimo de novos campos a um Recordset: adIDispatch, adIUnknown, adVariant.
DefinedSize	Opcional. Um valor Long que representa o tamanho definido, em caracteres ou bytes, do novo campo. O valor padrão deste parâmetro é derivado de Type. Campos com DefinedSize maior que 255 bytes e tratados como colunas de comprimento variável. (O DefinedSize padrão não é especificado.)
Attrib	Opcional. Um valor FieldAttributeEnum, cujo valor padrão é adFldDefault, que especifica os atributos do novo campo. Se esse valor não for especificado, o campo conterá os atributos derivados de Type.
FieldValue	Opcional. Um Variant que representa o valor do novo campo. Se nenhum valor for especificado, o campo será acrescentado com um valor nulo.

Comentários

Coleção Parameters

Defina a propriedade Type de um objeto Parameter antes de acrescentá-la à coleção Parameters. Se selecionar um tipo de dados de comprimento variável, defina também a propriedade Size para um valor maior que zero.

Você conseguirá diminuir as chamadas para o provedor ao descrever sozinho os parâmetros, melhorando consequentemente o desempenho com a utilização de procedimentos armazenados ou consultas com parâmetros. Entretanto, é necessário que você conheça as propriedades dos parâmetros associados ao procedimento armazenado ou à consulta com parâmetros a ser chamada.

Use o método CreateParameter para criar objetos Parameter com as configurações de propriedade adequadas e use o método Append para adicioná-los à coleção Parameters. Isso permitirá definir e retornar valores de parâmetro sem que seja necessário chamar o provedor para as informações de parâmetro. Se estiver criando em um provedor que não fornece informações de parâmetro, use esse método para preencher manualmente a coleção Parameters e usar parâmetros.

Coleção Fields

O parâmetro FieldValue somente é válido na adição de um objeto Field a um objeto Record, e não a um objeto Recordset. Com um objeto Record, você poderá acrescentar campos e fornecer valores simultaneamente. Com um objeto Recordset, você deverá criar campos enquanto Recordset estiver 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 deverá ser definida antes que qualquer outra propriedade Field seja especificada. Primeiro, um valor específico para a propriedade Value deve ser atribuído e o método Update deve ser chamado na coleção Fields. Assim, outras propriedades, como Type ou Attributes, poderão ser acessadas.

Os objetos Field dos seguintes tipos de dados (DataTypeEnum) não podem ser acrescentados à coleção Fields, caso contrário, causarão erro: adArray, adChapter, adEmpty, adPropVariant e adUserDefined. Os seguintes tipos de dados também não são aceitos pelo ADO: adIDispatch, adIUnknown e adIVariant. Para esses tipos, não ocorrerá erro quando eles forem acrescentados, mas o uso poderá produzir resultados inesperados, 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 automaticamente como adUseClient (valor CursorLocationEnum) quando o método Open do objeto Recordset for chamado.

Um erro de 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ê só pode acrescentar campos a um Recordset 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.

Gravar

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

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

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