sqleseti()--Set Client Information

 #include <sqlenv.h>

 SQL_API_RCsqleseti(unsigned short RDBNameLen, 
                    char *RDBName, 
                    unsigned short NumItems, 
                    struct sqle_client_info *Client_Info, 
                    void *Sqlca);

The sqleseti() API permits an application to set client information associated with a specific connection, provided that a connection already exists.

By using this API, the application server can pass the client's user ID, workstation information, program information, and other accounting information to the DB2^® server. The default value for the special registers is the empty string.

The application can choose not to specify a relational database name. If a relational database name is not specified, any client information will be set for all existing, as well as future, connections.

This API can be used to establish values before a connection to a database, or it can be used to set or modify the values after a connection has been established. If a database connection does not exist when this API is called, the information will be cached globally and applied to all new connections established.

Parameters

RDBNameLen

(Input) A 2-byte unsigned integer representing the length in bytes of the relational database name.

RDBName

(Input) A pointer to a string containing the relational database name.

NumItems

(Input) Number of client information entries being modified. The minimum value is 1.

Client_Info

(Input) A pointer to an array of NumItems sqle_client_info structures, each containing a type field indicating which value to set, the length of that value, and a pointer to the new value.

Sqlca

(Output) This is used for returning diagnostic information. It includes the SQLCODE variable, indicating whether an error has occurred. If SQLCODE has a value of 0 after a call to this API, the function was successful.

If multiple errors occur, only the first error will get returned in the SQL communications area.

The API caller should have this space declared in the program that calls this API. This parameter is considered output because the API uses the space to pass back information. The format of the structure is standard and can be included by using the INCLUDE SQLCA statement in an SQL program. It is described more completely in the SQL programming and DB2 for IBM^® i SQL reference topic collections.

Authorities

None.

sqle_client_info Structure

The following table shows the format for the sqle_client_info structure. For detailed descriptions of the fields in the table, see Field Descriptions.

Field Descriptions

Reserved. Reserved field. It must be initialized to 0x00.

SQLE-client-info length. Length of the SQLE-client_info value. The length can be between zero and the maximum length defined for the type. A length of zero indicates a null value.

SQLE-client-info type. Type of the SQLE-client-info value. The valid types follow.

SQLE-client-info value. Pointer to an application-allocated buffer that contains the specified value.

Return Value

0

sqleseti() was successful.

value

sqleseti() was not successful. value is set to indicate the error condition. The value may correspond to an SQLCODE; for example, -487 corresponds to SQL0487.

To display the message description for the SQLCODE, use this command: DSPMSGD RANGE(SQL0487) MSGF(QSQLMSG)

Error Messages

Usage Notes

This API is used to set the CLIENT_ACCTNG, CLIENT_APPLNAME, CLIENT_PROGRAMID, CLIENT_USERID, and CLIENT_WRKSTNNAME SQL special registers. Each SQL special register is independent of each other and can be set in any combination or individually.

If a relational database name was provided, a connection to the relational database name must already exist, and all connections to that relational database name will inherit the changes. The information will be retained until the connection for that relational database name is broken. If a relational database name was not provided, settings for all existing connections will be changed, and any future connections will inherit the changes. The information will be retained until the program ends.

Any data value that exceeds the maximum supported size after conversion to the database code page will be truncated before being stored at the server.

This support is nontransactional; commit and rollback have no effect on the special register values.

All valid sqle_client_info entries will be processed. The appropriate failure message will be sent for each input sqle_client_info entry that is not valid. If multiple input entries are not valid, the SQLCODE will be set to the first entry that is not valid.

When using DRDA^®, the SQL special register values will be set on the application server (AS) and not the application requestor (AR).

See the DB2 for i SQL reference topic collection for more information about the supported special registers.

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

/*********************************************************/
/* To compile program:                                   */
/* CRTSQLCI OBJ(QGPL/SETIXMP) SRCFILE(QGPL/QCSRC)        */ 
/* COMMIT(*NONE) RDB(*NONE) OBJTYPE(*MODULE)             */            
/* OUTPUT(*PRINT) DBGVIEW(*SOURCE)                       */      
/*                                                       */  
/* To bind program:                                      */                             
/* CRTPGM PGM(QGPL/SETIXMP)                              */                    
/* MODULE(QGPL/SETIXMP) ACTGRP(*CALLER)                  */           
/*                                                       */
/* To invoke program:                                    */                                  
/* Call QGPL/SETIXMP                                     */
/*                                                       */
/*********************************************************/
#include <sys/types.h>
#include <fcntl.h>
#include <stdio.h>
#include <sqlenv.h>
#include <unistd.h>

int main(int argc, char **argv)
{
  int             rc;
  char val1[] = "This is my Client Userid information"; 
  char val2[] = "This is my Client Workstation information"; 
  char val3[] = "This is my Client Applname information"; 
  char val4[] = "This is my Client Acctng information"; 
  char val5[] = "This is my Client ProgramId information"; 
  sqle_client_info_t *clientInfo_p;
  sqle_client_info_t clientInfo[5];
  EXEC SQL  INCLUDE SQLCA;

  memset(clientInfo[0].reserved,0,12);
  memset(clientInfo[1].reserved,0,12);
  memset(clientInfo[2].reserved,0,12);
  memset(clientInfo[3].reserved,0,12);
  memset(clientInfo[4].reserved,0,12);

  clientInfo[0].type = 1;
  clientInfo[0].length = strlen(val1);
  clientInfo[0].pValue = val1;
  clientInfo[1].type = 2;
  clientInfo[1].length = strlen(val2);
  clientInfo[1].pValue = val2;
  clientInfo[2].type = 3;
  clientInfo[2].length = strlen(val3);
  clientInfo[2].pValue = val3;
  clientInfo[3].type = 4;
  clientInfo[3].length = strlen(val4);
  clientInfo[3].pValue = val4;
  clientInfo[4].type = 5;
  clientInfo[4].length = strlen(val5);
  clientInfo[4].pValue = val5;
  clientInfo_p = &clientInfo[0];
  rc=sqleseti(0, NULL, 5, clientInfo_p, &sqlca);

  if (rc==0) {
    printf("sqleseti() call successful\n");
  }
  else {
    printf("sqleseti() failed with %d, SQLCODE=%d, SQLSTATE=%s\n", 
            rc, sqlca.sqlcode, sqlca.sqlstate);
  }
  return;
}

[ Back to top | Database and File APIs | APIs by category ]