Inserir

Insere um novo registro em uma tabela do banco de dados.

Parâmetros

Retorno

Retorna um objeto contendo os campos selecionados da entidade.

O retorno da chave primária (PK) junto com o objeto varia de acordo com o Tipo de PK e o Banco de dados utilizado (Figura 1). 

Assim, quando o tipo de chave primária (PK) é definida como:

• "Auto incremento", ou seja, o banco de dados é quem gera o valor da chave, o retorno ocorrerá apenas ao utilizar os bancos Oracle e Firebird (Figura 1).
• "Nova GUID", ou seja, o servidor (Java) da aplicação é quem gera o valor da chave, o retorno sempre ocorrerá.

Figura 1 - Retorno dos objetos ao utilizar banco de dados e tipo de PK distintos

Compatibilidade

 Servidor

Configuração do bloco

É possível Inserir um registro na tabela do banco de dados de duas formas diferentes, via campos ou por objeto, essa configuração é feita a partir do campo Tipo (destaque 2 da figura 1).

Para configurar o bloco Inserir, clique no símbolo da engrenagem, isso fará com que a janela Configurar Bloco de Programação seja exibida. Após informar a entidade (destaque 1 da figura 1), é possível selecionar os campos que serão usados a partir dos atributos do objeto (Tipo Campos) ou apenas passando o Objeto, nesse caso, não será possível configurar os campos.

Figura 2 - Inserção de dados via campos

1. Entidade: abre a janela de seleção de entidades.
2. Tipo: informa se o bloco será alimentado a partir dos atributos "Campos" da entidade ou a partir do "Objeto".
3. + Novo Campo: clique para adicionar os campos da entidade.
4. Campos: lista de campos adicionados.
5. Botão Excluir: apaga os campos inseridos. Exclua todos os campos para retornar ao tipo "Objeto"

Para saber mais sobre o campo Modo de Consulta, acesse a figura 1.1 da documentação Assistente de consulta.

Exemplo 1 - Inserção via campos

Assim que selecionamos a entidade (destaque 1 da figura 2), o bloco é configurado por padrão com o tipo objeto, para que possamos mudar o tipo para campos, devemos clicar em + Novo campo (destaque 3 da figura 2) para adicionar os campos. Definidos os campos, basta inserir os valores que serão salvos no registro, confira na figura 3.

Figura 3 - Bloco de programação Inserir configurado via campos

Confira abaixo o resultado da inserção. 

Figura 3.1 - Registro sendo exibido na Grade

Exemplo 2 - Inserção via objeto

Além da inserção via campos, também é possível inserir um registro passando um objeto já com seus atributos. No exemplo abaixo estamos criando um objeto a partir do bloco de programação Criar novo objeto.  

Figura 4 - Bloco de programação Inserir configurado via objeto

Confira abaixo o resultado da inserção. 

Figura 4.1 - Registro sendo exibido na Grade

Exemplo 3 - Uso do retorno do bloco

Como o bloco Inserir retorna um objeto do registro passado (ver mais detalhes no tópico Retorno), podemos aproveitar esse retorno para alimentar outra tabela que possui como campo a chave estrangeira (FK) do primeiro objeto.

Nesse exemplo, estamos alimentando a tabela Cliente e, em seguida, a tabela Telefone que possui relacionamento 1toN com Cliente (Figura 5). O Tipo de PK (chaves primárias) das duas tabelas foram configurados como "Nova GUID".

Figura 5 - Relacionamento utilizado nesse exemplo

A função da figura 5.1 demostra o uso dos blocos e seus retornos.

Figura 5.1 - Utilizando o retorno do bloco Inserir

1. A variável "cliente" recebe o retorno do bloco Inserir que alimenta a entidade Cliente.
   • Nesse bloco Inserir não incluímos o campo id, nesse caso, o id foi adicionado automaticamente pelo servidor da aplicação.
2. Usamos o bloco Se faça apenas para fazer uma validação do retorno do primeiro bloco Inserir.
3. A variável "telefone" recebe o retorno do segundo bloco Inserir, onde informamos manualmente o id da entidade Telefone, os campos numero, ehFixo e, no parâmetro cliente, passamos o objeto de retorno do primeiro bloco Inserir.
   • Nesse caso, podemos informar o objeto completo, como fizemos, ou utilizar o bloco Obter campo e informar apenas o id do objeto.
4. Em seguida, imprimimos as variáveis "cliente" e "telefone", com o retorno dos 2 blocos Inserir utilizados.
5. O resultado do passo 4 pode ser visto no Console do depurador.