entity.lock( )

4D v18

entity.lock( )

Descrição

O método entity.lock( ) põe um bloqueio pessimista(*) no registro referenciado pela entidade. O bloqueio é estabelecido para um registro e todas as referências de entidade no processo atual.

(*)Para saber mais, veja a página Trancar Entidades.

Outros processos vão enxergar este registro como bloqueado (a propriedade result.success vai conter false se tentarem bloquear a mesma entidade usando este método). Só metodos executados em sessão "locking" são permitidos para editar e salvar os atributos da entidade. A entidade pode ser carregada em apenas-leitura por outtras sessões, mas eles não poderão entrar e salvar valores.

Um registro bloqueado será desbloqueado

quando o método unlock() for chamado em uma entidade correspondente no mesmo processo
automaticamente, quando não for mais referenciada por qualquer entidade na memória. Por exemplo, se o bloqueio for posto apenas em uma única referência local da entidade, a entidade é desbloqueada quando o método terminar. Enquanto existir referências da entidade na memória, o registro permanece bloqueado.

Como padrão, se o parâmetro modo for omitido, o método vai retornar um erro (ver abaixo) se a mesma entidade for modificada (ou seja, o carimbo -stamp tiver mudado) por outro processo ou usuário enquanto isso.
Senão, pode passar a opção dk reload if stamp changed no parâmetro modo: neste caso, nenhum erro é retornado e a entidade é recarregada quando a stamp tiver sido mudada (se a entidade ainda existir e a chave primária ainda for a mesma)

Resultado

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

Propriedade		Tipo	Descrição
success		booleano	true se a ação de salvar tiver sucesso (ou se a entidade já estiver bloqueada no processo atual), do contrário false.
			*Disponível só se for utilizada a opção* dk reload if stamp changed:
wasReloaded		booleano	true se a entidade foi recarregada com êxito, do contrário 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 só 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
	user_name	texto	Nome de usuário de sessão na máquina
	user4d_alias	text	Nome ou alias do usuário 4D
	user4d_id	texto	Nome de usuário no diretório do banco de dados 4D
	host_name	texto	Nome da máquina
	task_name	texto	Nome do processo
	client_version	texto
			Disponível só em caso de erro grave (chave primária já existe, disco cheio...):
errors		coleção de objetos
	message	texto	Mensagem de erro
	component signature	texto	Assinatura do componente interno (por exemplo, "dmbg" representa o componente do banco de dados)
	errCode	number	Código de erro

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

Constante	Valor	Comentário
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

Exemplo com erro:

 C_OBJECT($employee;$status)

 $employee:=ds.Employee.get(716)

 $status:=$employee.lock()

 Case of

    :($status.success)

       ALERT("You have locked "+$employee.firstName+" "+$employee.lastName)

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

       ALERT($status.statusText)

 End case

Exemplo 2

Exemplo com a opção dk reload if stamp changed :

 C_OBJECT($employee;$status)

 

 $employee:=ds.Employee.get(717)

 $status:=$employee.lock(dk reload if stamp changed)

 Case of

    :($status.success)

       ALERT("You have locked "+$employee.firstName+" "+$employee.lastName)

    :($status.status=dk status entity does not exist anymore)

       ALERT($status.statusText)

 End case

Ver também

entity.unlock( )