IIapi_setConnectParam() Function—Assign Connection Parameter and Value to a Connection
The IIapi_setConnectParam() function allows the application to assign connection parameters to a connection. These parameters are sent to the server when IIapi_connect() or IIapi_modifyConnect() are called. One parameter and associated value are assigned for each call to IIapi_setConnectParam().
This function creates a new connection handle if called with sc_connHandle set to NULL or an environment handle returned by IIapi_initialize(). The returned connection handle can be used in subsequent calls to assign additional connection parameters to the connection. The connection handle can then be used to call IIapi_connect() to establish the connection to the server with the desired connection parameters. The connection handle is released using IIapi_disconnect() or IIapi_abort().
Once a connection has been established with IIapi_connect(), IIapi_setConnectParam() can be called with the connection handle to assign new connection parameters or to modify the parameters established with IIapi_connect(). Parameters assigned after calling IIapi_connect() are sent to the server by calling IIapi_modifyConnect().
This function has the following syntax:
II_VOID IIapi_setConnectParam (IIAPI_SETCONPRMPARM *setConPrmParm);
typedef struct _IIAPI_SETCONPRMPARM
{
IIAPI_GENPARM sc_genParm;
II_PTR sc_connHandle;
II_LONG sc_paramID;
II_PTR sc_paramValue;
} IIAPI_SETCONPRMPARM;
Note: Only IIAPI_CP_SHARED_SYS_UPDATE is accepted by an Ingres DBMS Server once a connection is established.
This function has the following parameters:
sc_genParm
Type: input and delayed output
sc_connHandle
Type: input and immediate output
Specifies the input and output for a connection handle.
The input is NULL for a new connection associated with the default environment, an environment handle for a new connection associated with the environment, or an existing connection handle.
The output is a connection handle that can be used in subsequent calls to IIapi_setConnectParam() and IIapi_connect().
sc_paramID
Type: input
Specifies the parameter being assigned. For valid parameter ID macros, see the following table.
sc_paramValue
Type: input
Specifies the value of the parameter being assigned. The data type and description of the value associated with each parameter ID are as follows (valid parameter ID macros for the sc_paramID parameter).
IIAPI_CP_APP_ID
Data type: II_CHAR
The role ID of the application. If a role password is required, the parameter value should be specified as “role/password”.
IIAPI_CP_APPLICATION
Data type: II_LONG
Specifies the value for an internal flag used for debugging a corrupted database. This flag is for Ingres internal applications; it must not be used by non-Ingres applications.
IIAPI_CP_CENTURY_BOUNDARY
Data type: II_LONG
Specifies the date century boundary.
IIAPI_CP_CHAR_WIDTH
Data type: II_LONG
Specifies the maximum length of a character (IIAPI_BYTE_TYPE, IIAPI_CHA_TYPE, IIAPI_CHR_TYPE, or IIAPI_VCH_TYPE) data type.
IIAPI_CP_DATE_ALIAS
Data type: II_CHAR
Specifies the actual data type to be used in place of the "date" data type alias. Its value is one of the following:
IIAPI_CPV_INGDATE
IIAPI_CPV_ANSIDATE
IIAPI_CP_DATE_FORMAT
Data type: II_LONG
Specifies the date format. Its value can be one of the following:
IIAPI_CPV_DFRMT_US
IIAPI_CPV_DFRMT_MULTI
IIAPI_CPV_DFRMT_FINNISH
IIAPI_CPV_DFRMT_ISO
IIAPI_CPV_DFRMT_GERMAN
IIAPI_CPV_DFRMT_YMD
IIAPI_CPV_DFRMT_MDY
IIAPI_CPV_DFRMT_DMY
IIAPI_CP_DBMS_PASSWORD
Data type: II_CHAR
Specifies the DBMS password for the user.
IIAPI_CP_DECIMAL_CHAR
Data type: II_CHAR
Specifies the character identifier of decimal data.
IIAPI_CP_EFFECTIVE_USER
Data type: II_CHAR
Specifies the effective user name for the new session.
IIAPI_CP_EXCLUSIVE_LOCK
Data type: II_BOOL
Indicates whether the database should be locked for exclusive use of this application. If it should be locked, this parameter is TRUE; otherwise, it is FALSE.
IIAPI_CP_EXCLUSIVE_SYS_UPDATE
Data type: II_BOOL
Indicates whether the system catalog should be updated with an exclusive lock. If so, this parameter is TRUE; otherwise, it is FALSE.
IIAPI_CP_FLOAT4_PRECISION
Data type: II_LONG
Specifies the precision of a float4 (IIAPI_FLT_TYPE) data type.
IIAPI_CP_FLOAT4_STYLE
Data type: II_CHAR
Specifies the output column format for the four-byte floating-point data type. Its value can be one of the following:
• IIAPI_CPV_EXPONENTIAL-exponential format
• IIAPI_CPV_FLOATF-floating-point format
• IIAPI_CPV_FLOATDEC-floating-point format, decimal alignment not guaranteed
• IIAPI_CPV_FLOATDECALIGN-floating-point format, decimal alignment guaranteed
Default: IIAPI_CPV_FLOATDEC
IIAPI_CP_FLOAT4_WIDTH
Data type: II_LONG
Specifies the length of a float4 (IIAPI_FLT_TYPE) data type.
IIAPI_CP_FLOAT8_PRECISION
Data type: II_LONG
Specifies the precision of a float8 (IIAPI_FLT_TYPE) data type.
IIAPI_CP_FLOAT8_STYLE
Data type: II_CHAR
Specifies the output column format for an eight-byte floating-point data type. Its value can be one of the following:
• IIAPI_CPV_EXPONENTIAL-exponential format
• IIAPI_CPV_FLOATF-floating-point format
• IIAPI_CPV_FLOATDEC-(default) floating-point format, decimal alignment not guaranteed
• IIAPI_CPV_FLOATDECALIGN-floating-point format, decimal alignment guaranteed
Default: IIAPI_CPV_FLOATDEC
IIAPI_CP_FLOAT8_WIDTH
Data type: II_LONG
Specifies the length of a float8 (IIAPI_FLT_TYPE) data type.
IIAPI_CP_GATEWAY_PARM
Data type: II_CHAR
Specifies Enterprise Access parameters. This parameter can be set multiple times.
IIAPI_CP_GROUP_ID
Data type: II_CHAR
Specifies the group ID of the user.
IIAPI_CP_INT1_WIDTH
Data type: II_LONG
Specifies the length of an integer1 (IIAPI_INT_TYPE) data type.
IIAPI_CP_INT2_WIDTH
Data type: II_LONG
Specifies the length of an integer2 (IIAPI_INT_TYPE) data type.
IIAPI_CP_INT4_WIDTH
Data type: II_LONG
Specifies the length of an integer4 (IIAPI_INT_TYPE) data type.
IIAPI_CP_INT8_WIDTH
Data type: II_LONG
Specifies the length of an integer8 (IIAPI_INT_TYPE) data type (ignored if connection level, co_apiLevel, is less than IIAPI_LEVEL_3).
IIAPI_CP_LOGIN_LOCAL
Data type: II_BOOL
Determines how the connection user ID and password are used when a VNODE is included in the target database string. If set to TRUE, the user ID and password are used to locally access the VNODE and the VNODE login information is used to establish the DBMS connection. If set to FALSE, the process user ID is used to access the VNODE and the connection user ID and password are used in place of the VNODE login information to establish the DBMS connection. This parameter is ignored if no VNODE is included in the target database string. The default is FALSE.
IIAPI_CP_MATH_EXCP
Data type: II_CHAR
Specifies the type of error message to be returned because of a numerical overflow/underflow at the server. Its value can be one of the following:
• IIAPI_CPV_RET_FATAL-return fatal message
• IIAPI_CPV_RET_WARN-return warning message
• IIAPI_CPV_RET_IGNORE-ignore exceptions
IIAPI_CP_MISC_PARM
Data type: II_CHAR
Specifies miscellaneous parameters. This parameter can be set multiple times.
IIAPI_CP_MONEY_LORT
Data type: II_LONG
Indicates a leading or trailing money sign. Valid values are one of the following:
• IIAPI_CPU_MONEY_LEAD_SIGN
• IIAPI_CPU_MONEY_TRAIL_SIGN
IIAPI_CP_MONEY_PRECISION
Data type: II_LONG
Specifies the precision of the money (IIAPI_MNY_TYPE) data type.
IIAPI_CP_MONEY_SIGN
Data type: II_CHAR
Specifies the money sign.
IIAPI_CP_NATIVE_LANG
Data type: II_CHAR
Specifies the name of the language used for error reporting. This is converted to a language code prior to sending to the server. Can be set to NULL to obtain the default installation language.
IIAPI_CP_NATIVE_LANG_CODE
Data type: II_LONG
Specifies the language code of the native language used for error reporting. IIAPI_CP_NATIVE_LANG can be used when the language code is not known.
IIAPI_CP_NUMERIC_TREATMENT
Data type: II_CHAR
Specifies the treatment of the numeric literal. Its value can be one of the following:
• IIAPI_CPV_DECASFLOAT-treat decimal literal as float
• IIAPI_CPV_DECASDEC-treat decimal literal as decimal
IIAPI_CP_RESULT_TBL
Data type: II_LONG
Specifies the default result table structure. Its value can be one of the following:
IIAPI_CPV_ISAM
IIAPI_CPV_CISAM
IIAPI_CPV_HEAP
IIAPI_CPV_CHEAP
IIAPI_CPV_BTREE
IIAPI_CPV_CBTREE
IIAPI_CPV_HASH
IIAPI_CPV_CHASH
IIAPI_CP_SECONDARY_INX
Data type: II_LONG
Specifies the default secondary index structure. Its value can be one of the following:
IIAPI_CPV_ISAM
IIAPI_CPV_CISAM
IIAPI_CPV_BTREE
IIAPI_CPV_CBTREE
IIAPI_CPV_HASH
IIAPI_CPV_CHASH
IIAPI_CP_SERVER_TYPE
Data type: II_LONG
Specifies the type of server function desired. Its value can be one of the following:
IIAPI_CPV_SVNORMAL
IIAPI_CPV_MONITOR
IIAPI_CP_SHARED_SYS_UPDATE
Data type: II_BOOL
Indicates whether the system catalog should be updated with a shared lock. If so, this parameter is TRUE; otherwise, it is FALSE.
IIAPI_CP_STRING_TRUNC
Data type: II_CHAR
Specifies the parameters for specifying how to handle truncation when a string value is being inserted into a column that is too short to contain the value. Its value can be one of the following:
• IIAPI_CPV_RET_FATAL-the string is not inserted, an error is issued, and the statement is aborted
• IIAPI_CPV_RET_IGNORE-the string is truncated and inserted. No error or warning is issued
IIAPI_CP_TIMEZONE
Data type: II_CHAR
Specifies the time zone of the application.
IIAPI_CP_TXT_WIDTH
Data type: II_LONG
Specifies the maximum length of a text (IIAPI_TXT_TYPE) data type.
IIAPI_CP_WAIT_LOCK
Data type: II_BOOL
Indicates whether the application is willing to wait for a lock on the database to be released. If so, this parameter is TRUE; otherwise, it is FALSE.