Função JetSetLS

Aplica-se a: Windows | Windows Server

Função JetSetLS

A função JetSetLS permite que o aplicativo associe um identificador de contexto conhecido como Armazenamento Local a um cursor ou à tabela associada a esse cursor. Esse identificador de contexto pode ser usado pelo aplicativo para armazenar dados auxiliares associados a um cursor ou tabela. Posteriormente, o aplicativo é notificado usando um retorno de chamada de runtime quando o identificador de contexto deve ser liberado. Isso possibilita associar o estado alocado dinamicamente a um cursor ou tabela.

O Windows XP:JetSetLS é introduzido no Windows XP.

    JET_ERR JET_API JetSetLS(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_LS ls,
      __in          JET_GRBIT grbit
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

ls

O identificador de contexto a ser associado ao cursor ou à tabela.

Quando JET_bitLSReset é especificado, o valor real desse parâmetro é ignorado e JET_LSNil é usado.

grbit

Um grupo de bits que contém as opções a serem usadas para essa chamada, que incluem zero ou mais dos seguintes.

Valor	Significado
JET_bitLSCursor	Essa opção indica que o identificador de contexto deve ser associado ao cursor fornecido. Se nem JET_bitLSCursor nem JET_bitLSTable forem especificados, JET_bitLSCursor será presumido. É ilegal usar essa opção com JET_bitLSTable. A operação falhará com JET_errInvalidgrbit se isso for tentado.
JET_bitLSReset	Essa opção indica que o identificador de contexto especificado deve ser ignorado e que o identificador de contexto do objeto escolhido deve ser redefinido para JET_LSNil. É importante observar que essa ação não resultará em um retorno de chamada para limpar o valor anterior do identificador de contexto do objeto escolhido. A limpeza adequada do identificador de contexto anterior pode ser obtida usando JetGetLS com JET_bitLSReset. Consulte JetGetLS para obter mais informações.
JET_bitLSTable	Essa opção indica que o identificador de contexto deve ser associado à tabela associada ao cursor fornecido. É ilegal usar essa opção com JET_bitLSCursor. A operação falhará com JET_errInvalidgrbit se isso for tentado.

Valor Retornado

Essa função retorna o tipo de dados JET_ERR com um dos seguintes códigos de retorno. Para obter mais informações sobre os possíveis erros de ESE, consulte Erros extensíveis do mecanismo de armazenamento e parâmetros de tratamento de erros.

Código de retorno	Descrição
JET_errSuccess	A operação foi concluída com sucesso.
JET_errClientRequestToStopJetService	Não é possível concluir a operação porque todas as atividades na instância associada à sessão cessaram como resultado de uma chamada para JetStopService.
JET_errInvalidgrbit	Uma das opções solicitadas era inválida, usada incorretamente ou não implementada. Isso pode acontecer para JetSetLS quando JET_bitLSCursor e JET_bitLSTable são especificados.
JET_errInstanceUnavailable	Não é possível concluir a operação porque a instância associada à sessão encontrou um erro fatal que exige que o acesso a todos os dados seja revogado para proteger a integridade desses dados. Esse erro só será retornado pelo Windows XP e versões posteriores.
JET_errLSAlreadySet	O identificador de contexto fornecido não pôde ser associado ao objeto solicitado porque ele já tinha um identificador de contexto associado a ele.
JET_errLSCallbackNotSpecified	O identificador de contexto fornecido não pôde ser associado ao objeto solicitado porque o retorno de chamada de runtime não foi configurado para a instância associada à sessão.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
JET_errRestoreInProgress	Não é possível concluir a operação porque uma operação de restauração está em andamento na instância associada à sessão.
JET_errTermInProgress	Não é possível concluir a operação porque a instância associada à sessão está sendo desligada.

Em caso de êxito, o identificador de contexto fornecido foi associado com êxito ao objeto solicitado. Nenhuma alteração no estado do banco de dados ocorrerá.

Em caso de falha, nenhuma alteração no estado do objeto solicitado ocorreu. Nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

O Armazenamento Local de um cursor ou tabela deve ser exibido como um cache volátil. O aplicativo deve primeiro tentar recuperar o identificador de contexto usando JetGetLS. Se o valor não estiver definido (ou seja, é JET_LSNil), o aplicativo deverá criar um novo contexto e carregá-lo no cache usando JetSetLS. O aplicativo pode limpar o cache usando uma chamada para JetGetLS com JET_bitLSReset. Se o mecanismo de banco de dados limpar o cache, um retorno de chamada de runtime será gerado para dar ao aplicativo a chance de limpar esse contexto. O tipo de retorno de chamada será JET_cbtypFreeCursorLS para um identificador de contexto associado a um cursor e JET_cbtypFreeTableLS para um identificador de contexto associado a uma tabela. Em ambos os casos, o identificador de contexto será passado como pvArg1. Confira JET_CALLBACK para obter mais informações.

O retorno de chamada de runtime deve ser configurado corretamente para a instância associada à sessão especificada antes que o Armazenamento Local possa ser usado. Esse retorno de chamada pode ser definido usando JetSetSystemParameter com JET_paramRuntimeCallback. Consulte JetSetSystemParameter e JET_paramRuntimeCallback em Parâmetros do Sistema para obter mais informações.

Requisitos

Requisito	Valor
Cliente	Requer o Windows Vista ou o Windows XP.
Servidor	Requer o Windows Server 2008 ou o Windows Server 2003.
Cabeçalho	Declarado em Esent.h.
Biblioteca	Use ESENT.lib.
DLL	Requer ESENT.dll.

Consulte Também

JET_CALLBACK
JET_ERR
JET_GRBIT
JET_LS
JET_SESID
JET_TABLEID
JetGetLS
JetSetSystemParameter
Parâmetros do sistema