Partager via

Fonction JetRenameColumn

  • Article

S’applique à : Windows | Windows Server

Fonction JetRenameColumn

La fonction JetRenameColumn peut être utilisée pour modifier le nom d’une colonne existante sur une table.

Windows XP:JetRenameColumn est introduit dans Windows XP.

    JET_ERR JET_API JetRenameColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_PCSTR szName,
      __in          JET_PCSTR szNameNew,
      __in          JET_GRBIT grbit
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

szName

Nom actuel de la colonne qui sera renommée.

szNameNew

Nouveau nom de la colonne qui sera renommée.

grbit

Ce paramètre doit être 0.

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_errColumnNotFound

Cette colonne spécifiée n’existe pas pour cette table.

JET_errInvalidName

L’un des noms d’objets spécifiés n’était pas valide. Tous les noms d’objets doivent être conformes au même ensemble de règles. Ces règles sont les suivantes :

  • Les noms d’objets doivent être composés de caractères ASCII.

  • Les noms d’objets doivent comporter au moins un caractère.

  • Les noms d’objets ne peuvent pas dépasser JET_cbNameMost (64) caractères.

  • Les noms d’objets ne peuvent pas commencer par un espace . Les noms d’objets ne peuvent pas contenir de caractères de contrôle ASCII (0x00 via 0x1F).

  • Les noms d’objets ne peuvent pas contenir de point d’exclamation (!), de point (.), de crochet gauche ([) ou de crochet droit (]).

  • Une fois validée, seule la partie de la chaîne jusqu’au premier espace (le cas échéant) sera utilisée pour le nom de l’objet. Cela signifie effectivement que les noms d’objets ne peuvent pas non plus contenir d’espace.

JET_errInvalidParameter

L’un des paramètres fournis contenait une valeur inattendue ou contenait une valeur qui n’était pas logique lorsqu’elle était combinée à la valeur d’un autre paramètre. Cela peut se produire pour JetRenameColumn lorsque :

  • szName a la valeur NULL.

  • szNameNew a la valeur NULL.

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_errInTransaction

Cette opération ne peut être effectuée que lorsque la session ne se trouve pas actuellement à l’intérieur d’une transaction.

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_errSessionSharingViolation

La même session ne peut pas être utilisée pour plusieurs threads en même temps. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.

JET_errTermInProgress

Il n’est pas possible d’effectuer l’opération, car le instance associé à la session est en cours d’arrêt.

JET_errTransReadOnly

Une mise à jour ne peut pas être effectuée à l’intérieur de l’étendue d’une transaction en lecture seule. Une transaction en lecture seule est une transaction qui a été démarrée à l’aide d’un appel à JetBeginTransaction2 avec JET_bitTransactionReadOnly. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.

En cas de réussite, le nom de la colonne spécifiée dans la table associée au curseur est définitivement remplacé par le nouveau nom. Tous les index qui font référence à cette colonne seront également mis à jour.

En cas d’échec, aucune modification de l’état de la base de données ne se produit.

Notes

L’opération de renommage de colonne est inhabituelle car, contrairement à d’autres opérations de schéma, elle n’est pas effectuée en tant que transaction. Lorsqu’une colonne d’une table donnée est renommée dans une session, toute autre session utilisant cette table voit immédiatement la modification, même si elle se trouve dans une transaction qui empêcherait cette session de voir toute autre modification apportée par la session effectuant l’opération de renommage.

L’ID de colonne d’une colonne n’est pas affecté par l’opération de renommage.

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.

Unicode

Implémenté en tant que JetRenameColumnW (Unicode) et JetRenameColumnA (ANSI).

Voir aussi

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction2