Utilisation des valeurs de longueur et d’indicateur

  • Article

La mémoire tampon de longueur/indicateur est utilisée pour passer la longueur d’octet des données dans la mémoire tampon de données ou un indicateur spécial tel que SQL_NULL_DATA, ce qui indique que les données sont NULL. Selon la fonction dans laquelle elle est utilisée, une mémoire tampon de longueur/indicateur est définie comme sqlinteGER ou SQLSMALLINT. Par conséquent, un seul argument est nécessaire pour le décrire. Si la mémoire tampon de données est une mémoire tampon d’entrée non définie, cet argument contient la longueur d’octet des données elle-même ou une valeur d’indicateur. Il est souvent nommé StrLen_or_Ind ou un nom similaire. Par exemple, le code suivant appelle SQLPutData pour passer une mémoire tampon pleine de données ; la longueur d’octet (ValueLen) est transmise directement, car la mémoire tampon de données (ValuePtr) est une mémoire tampon d’entrée.

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLen;  
  
// Call local function to place data in ValuePtr. In ValueLen, return the  
// number of bytes of data placed in ValuePtr. If there is not enough  
// data, this will be less than 50.  
FillBuffer(ValuePtr, sizeof(ValuePtr), &ValueLen);  
  
// Call SQLPutData to send the data to the driver.  
SQLPutData(hstmt, ValuePtr, ValueLen);

Si la mémoire tampon de données est une mémoire tampon d’entrée différée, une mémoire tampon de sortie non redéfinie ou une mémoire tampon de sortie, l’argument contient l’adresse de la mémoire tampon de longueur/indicateur. Il est souvent nommé StrLen_or_IndPtr ou un nom similaire. Par exemple, le code suivant appelle SQLGetData pour récupérer une mémoire tampon pleine de données ; la longueur d’octet est retournée à l’application dans la mémoire tampon de longueur/indicateur (ValueLenOrInd), dont l’adresse est passée à SQLGetData , car la mémoire tampon de données correspondante (ValuePtr) est une mémoire tampon de sortie non définie.

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLenOrInd;  
SQLGetData(hstmt, 1, SQL_C_CHAR, ValuePtr, sizeof(ValuePtr), &ValueLenOrInd);

Sauf s’il est spécifiquement interdit, un argument de mémoire tampon de longueur/indicateur peut être 0 (si une entrée non définie) ou un pointeur Null (si la sortie ou l’entrée différée). Pour les mémoires tampons d’entrée, le pilote ignore la longueur d’octet des données. Cette opération renvoie une erreur lors de la transmission de données de longueur variable, mais est courante lors de la transmission de données non null, de longueur fixe, car aucune longueur ni valeur d’indicateur n’est nécessaire. Pour les mémoires tampons de sortie, le pilote ne retourne pas la longueur d’octet des données ou une valeur d’indicateur. Il s’agit d’une erreur si les données retournées par le pilote sont NULL, mais sont courantes lors de la récupération de données de longueur fixe, non nullables, car aucune longueur ni valeur d’indicateur n’est nécessaire.

Comme lorsque l’adresse d’une mémoire tampon de données différée est transmise au pilote, l’adresse d’une mémoire tampon de longueur/d’indicateur différée doit rester valide tant que la mémoire tampon n’est pas liée.

Les longueurs suivantes sont valides en tant que valeurs de longueur/indicateur :

  • n, où n> 0.

  • SQL_NTS. Une chaîne envoyée au pilote dans la mémoire tampon de données correspondante est terminée par null ; il s’agit d’un moyen pratique pour les programmeurs C de passer des chaînes sans avoir à calculer leur longueur d’octet. Cette valeur est légale uniquement lorsque l’application envoie des données au pilote. Lorsque le pilote retourne des données à l’application, il retourne toujours la longueur d’octet réelle des données.

Les valeurs suivantes sont valides en tant que valeurs de longueur/indicateur. SQL_NULL_DATA est stocké dans le champ de descripteur SQL_DESC_INDICATOR_PTR ; toutes les autres valeurs sont stockées dans le champ de descripteur SQL_DESC_OCTET_LENGTH_PTR.

  • SQL_NULL_DATA. Les données sont une valeur de données NULL et la valeur dans la mémoire tampon de données correspondante est ignorée. Cette valeur est légale uniquement pour les données SQL envoyées ou récupérées à partir du pilote.

  • SQL_DATA_AT_EXEC. La mémoire tampon de données ne contient aucune donnée. Au lieu de cela, les données sont envoyées avec SQLPutData lorsque l’instruction est exécutée ou lorsque SQLBulkOperations ou SQLSetPos est appelé. Cette valeur est légale uniquement pour les données SQL envoyées au pilote. Pour plus d’informations, consultez SQLBindParameter, SQLBulkOperations et SQLSetPos.

  • Résultat de la macro SQL_LEN_DATA_AT_EXEC(length). Cette valeur est similaire à SQL_DATA_AT_EXEC. Pour plus d’informations, consultez Envoi de données longues.

  • SQL_NO_TOTAL. Le pilote ne peut pas déterminer le nombre d’octets de données longues toujours disponibles pour retourner dans une mémoire tampon de sortie. Cette valeur est légale uniquement pour les données SQL récupérées à partir du pilote.

  • SQL_DEFAULT_PARAM. Une procédure consiste à utiliser la valeur par défaut d’un paramètre d’entrée dans une procédure au lieu de la valeur dans la mémoire tampon de données correspondante.

  • SQL_COLUMN_IGNORE. SQLBulkOperations ou SQLSetPos consiste à ignorer la valeur dans la mémoire tampon de données. Lors de la mise à jour d’une ligne de données par un appel à SQLBulkOperations ou SQLSetPos, la valeur de colonne n’est pas modifiée. Lors de l’insertion d’une nouvelle ligne de données par un appel à SQLBulkOperations, la valeur de colonne est définie sur sa valeur par défaut ou, si la colonne n’a pas de valeur par défaut, sur NULL.