entity.save( )

4D v19.8

entity.save( )


entity.save ( {modo} ) -> Resultado

Parâmetro	Tipo	Descrição
modo	Inteiro longo	dk auto merge: Ativa o modo de fusão automático
Resultado	Objeto	Resultado da operação de salvar

Descrição

O método entity.save( ) salva as mudanças realizadas na entidade na tabela relacionada com sua dataClass. Deve chamar a este método depois de criar ou modificar uma entidade se quiser salvar as mudanças realizadas nela.

A operação de salvar é executada apenas se tiver sido "tocado" ao menos um atributo de entidade (ver os métodos entity.touched( ) e entity.touchedAttributes( )). Do contrário, o método não faz nada (não se chama ao ativador).

Em uma aplicação multi-usuário o multiprocesso, o método entity.save( ) é executado sob um mecanismo de "bloqueio otimista", enquanto que um carimbo de bloqueio interno se incrementa automaticamente cada vez que se guarda o registro. Para saber mais, veja Trancar Entidades.

Como padrão, se o parâmetro modo for omitido, o método devolverá um erro (ver abaixo) sempre que a mesma entidade tenha sido modificada por outro processo ou usuário enquanto isso, sejam quais forem os atributos modificados.
Do contrario, pode passar a opção dk auto merge no parâmetro modo: quando o modo de fusão automatica estiver habilitado, uma modificação realizada por outro processo/usuário na mesma entidade mas em um atributo diferente não criará um erro. Os dados resultantes salvados na entidade serão a combinação (a "fusão") de todas as modificações não concorrentes (se forem aplicadas modificações ao mesmo atributo, a operação de salvar falha e se devolve um erro, mesmo com o modo de fusão automatica).

Nota: o modo de fusão automatica não está disponível para os atributos de tipo imagem, objeto e texto quando forem armazenadas fora do registro. As mudanças concorrentes nestes atributos criarão um erro dk status stamp has changed.

Resultado

O objeto devolvido por entity.save( ) contém as propriedades abaixo:

Propriedade		Tipo	Descrição
success		booleano	true se a ação de salvar for um sucesso, do contrário, false
			*Disponível apenas se for utilizada a opção dk auto merge:*
autoMerged		booleano	true se for realizado uma fusão automatica, em caso contrario, false.
			*Disponível só em caso de erro:*
status(*)		número	Código de erro, ver abaixo
statusText(*)		texto	Descrição do erro, ver abaixo
			*Disponível apenas no caso de erro de bloqueio pessimista:*
lockKindText		texto	"Bloqueado por registro"
lockInfo		objeto	Informação sobre a origem do bloqueio
	task_id	número	ID do processo
	user4d_alias	texto	Alias de usuario definido com SET USER ALIAS, ou então o nome de usuario no diretório do banco de dados. 4D
	user_name	texto	Nome de usuário de sessão na máquina
	user4d_id	texto	Nome de usuário 4D (só disponível em bancos binários 4D)
	host_name	texto	Nome da máquina
	task_name	texto	Nome do processo
	client_version	texto
			Disponível apenas no caso de erro grave (erro grave ao tentar duplicar uma chave primária, disco cheio ...):
errors		coleção de objetos
	message	texto	Mensagem de erro
	componentSignature	texto	assinatura do componente interno (por exemplo, "dmbg" representa o componente do banco de dados)
	errCode	número	Código de erro

(*) Os valores abaixo podem ser devolvidos nas propriedades status e statusText o objeto Resultado em caso de erro:

Constante	Valor	Comentário
dk status automerge failed	6	(Só se a opção dk auto merge for usada) A opção automática de fusão falha quando salvar a entidade Texto de estado associado: "Falha de fusão automática - Auto merge failed"
dk status entity does not exist anymore	5	A entidade não existe mais nos dados. Esse erro pode ocorrer nos casos abaixo: a entidade foi suprimida (a stamp - carimbo - foi mudada e o espaço de memória agora está livre) a entidade foi suprimida e substituída por outra com outra chave primária (a stamp - carimbo - foi mudada e a nova entidade agora usa o espaço de memória). Quando usar entity.drop( ), este erro pode ser retornado quando a opção dk force drop if stamp changed for usada. Quando usar entity.lock( ), este erro pode ser retornado quando a opção dk reload if stamp changed for usada Texto de estado associado: "Entity does not exist anymore" - (a entidade não existe mais)
dk status locked	3	A entidade é bloqueada por um bloqueio pessimista Texto de estado associado: "Already locked" - já bloqueado
dk status serious error	4	Um erro sério é um erro de baixo nível de banco de dados (por exemplo, chave duplicada), um erro de hardware, etc Texto associado de estado: "Other error" - outro erro
dk status stamp has changed	2	O valor do stamp (carimbo marcador) da entidade não corresponde ao da entidade armazenada nos dados (bloqueio otimista). com entity.save( ): erro apenas se a opção dk auto merge não for usada com entity.drop( ): erro apenas se a opção dk force drop if stamp changed não for usada com entity.lock( ): erro apenas se a opção dk reload if stamp changed não for usada Texto de estado associado: "Stamp has changed" - carimbo marcador foi modificado

Exemplo 1

Criar uma nova entidade:

 C_OBJECT($status;$employee)

 $employee:=ds.Employee.new()

 $employee.firstName:="Mary"

 $employee.lastName:="Smith"

 $status:=$employee.save()

 If($status.success)

    ALERT("Employee created")

 End if

Exemplo 2

Atualizar uma entidade sem a opção dk auto merge:

 C_OBJECT($status;$employees;$employee)

 $employees:=ds.Employee.query("lastName=:1";"Smith")

 $employee:=$employees.first()

 $employee.lastName:="Mac Arthur"

 $status:=$employee.save()

 Case of

    :($status.success)

       ALERT("Employee updated")

    :($status.status=dk status stamp has changed)

       ALERT($status.statusText)

 End case

Exemplo 3

Atualizar uma entidade com a opção dk auto merge:

 C_OBJECT($status;$employees;$employee)

 

 $employees:=ds.Employee.query("lastName=:1";"Smith")

 $employee:=$employees.first()

 $employee.lastName:="Mac Arthur"

 $status:=$employee.save(dk auto merge)

 Case of

    :($status.success)

       ALERT("Employee updated")

    :($status.status=dk status automerge failed)

       ALERT($status.statusText)

 End case

Ver também

entity.drop( )
entity.getStamp( )
entity.isNew( )