Fonction JetSetLS

S’applique à : Windows | Windows Server

Fonction JetSetLS

La fonction JetSetLS permet à l’application d’associer un handle de contexte appelé Stockage local à un curseur ou à la table associée à ce curseur. Ce handle de contexte peut être utilisé par l’application pour stocker des données auxiliaires associées à un curseur ou à une table. L’application est ensuite avertie à l’aide d’un rappel du runtime lorsque le handle de contexte doit être libéré. Cela permet d’associer un état alloué dynamiquement à un curseur ou à une table.

Windows XP:JetSetLS est introduit dans Windows XP.

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

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

ls

Handle de contexte à associer au curseur ou à la table.

Lorsque JET_bitLSReset est spécifié, la valeur réelle de ce paramètre est ignorée et JET_LSNil est utilisé.

grbit

Groupe de bits contenant les options à utiliser pour cet appel, qui incluent zéro ou plusieurs des éléments suivants.

Valeur	Signification
JET_bitLSCursor	Cette option indique que le handle de contexte doit être associé au curseur donné. Si ni JET_bitLSCursor ni JET_bitLSTable n’est spécifié, JET_bitLSCursor est présumé. Il n’est pas possible d’utiliser cette option avec JET_bitLSTable. L’opération échoue avec JET_errInvalidgrbit si cette opération est tentée.
JET_bitLSReset	Cette option indique que le handle de contexte spécifié doit être ignoré et que le handle de contexte de l’objet choisi doit être réinitialisé à JET_LSNil. Il est important de noter que cette action n’entraîne pas de rappel pour nettoyer la valeur précédente du handle de contexte pour l’objet choisi. Un nettoyage correct du handle de contexte précédent peut être effectué à l’aide de JetGetLS avec JET_bitLSReset. Pour plus d’informations, consultez JetGetLS .
JET_bitLSTable	Cette option indique que le handle de contexte doit être associé à la table associée au curseur donné. Il n’est pas possible d’utiliser cette option avec JET_bitLSCursor. L’opération échoue avec JET_errInvalidgrbit si cette opération est tentée.

Valeur renvoyée

Cette fonction retourne le type de données JET_ERR avec l’un des codes de retour suivants. Pour plus d’informations sur les erreurs ESE possibles, consultez Erreurs du moteur de stockage extensible et Paramètres de gestion des erreurs.

Code de retour	Description
JET_errSuccess	L’opération s’est terminée avec succès.
JET_errClientRequestToStopJetService	Il n’est pas possible d’effectuer l’opération, car toutes les activités sur le instance associées à la session ont cessé à la suite d’un appel à JetStopService.
JET_errInvalidgrbit	L’une des options demandées n’était pas valide, utilisée de manière incorrecte ou non implémentée. Cela peut se produire pour JetSetLS lorsque JET_bitLSCursor et JET_bitLSTable sont tous deux spécifiés.
JET_errInstanceUnavailable	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session a rencontré une erreur irrécupérable qui exige que l’accès à toutes les données soit révoqué pour protéger l’intégrité de ces données. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errLSAlreadySet	Le handle de contexte donné n’a pas pu être associé à l’objet demandé, car un handle de contexte lui était déjà associé.
JET_errLSCallbackNotSpecified	Le handle de contexte donné n’a pas pu être associé à l’objet demandé, car le rappel du runtime n’a pas été configuré pour le instance associé à la session.
JET_errNotInitialized	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session n’a pas encore été initialisé.
JET_errRestoreInProgress	Il n’est pas possible d’effectuer l’opération, car une opération de restauration est en cours sur le instance associé à la session.
JET_errTermInProgress	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session est en cours d’arrêt.

En cas de réussite, le handle de contexte donné a été correctement associé à l’objet demandé. Aucune modification de l’état de la base de données ne se produira.

En cas d’échec, aucune modification de l’état de l’objet demandé ne s’est produite. Aucune modification de l’état de la base de données ne se produira.

Notes

Le stockage local d’un curseur ou d’une table doit être vu comme un cache volatile. L’application doit d’abord essayer de récupérer le handle de contexte à l’aide de JetGetLS. Si la valeur n’est pas définie (c’est-à-dire qu’elle est JET_LSNil), l’application doit créer un nouveau contexte et le charger dans le cache à l’aide de JetSetLS. L’application peut vider le cache à l’aide d’un appel à JetGetLS avec JET_bitLSReset. Si le moteur de base de données vide le cache, un rappel du runtime est généré pour permettre à l’application de nettoyer ce contexte. Le type de rappel sera JET_cbtypFreeCursorLS pour un handle de contexte associé à un curseur et JET_cbtypFreeTableLS pour un handle de contexte associé à une table. Dans les deux cas, le handle de contexte est passé en tant que pvArg1. Pour plus d’informations, consultez JET_CALLBACK .

Le rappel du runtime doit être correctement configuré pour le instance associé à la session donnée avant que le stockage local puisse être utilisé. Ce rappel peut être défini à l’aide de JetSetSystemParameter avec JET_paramRuntimeCallback. Pour plus d’informations, consultez JetSetSystemParameter et JET_paramRuntimeCallback dans Paramètres système.

Spécifications

Condition requise	Valeur
Client	Nécessite Windows Vista ou Windows XP.
Serveur	Nécessite Windows Server 2008 ou Windows Server 2003.
En-tête	Déclaré dans Esent.h.
Bibliothèque	Utilisez ESENT.lib.
DLL	Nécessite ESENT.dll.

Voir aussi

JET_CALLBACK
JET_ERR
JET_GRBIT
JET_LS
JET_SESID
JET_TABLEID
JetGetLs
JetSetSystemParameter
Paramètres système