IIapi_setEnvParam() Function--Assign an Environment Parameter and Value in Environment Handle
The IIapi_setEnvParam() function allows the application to override the default environment logical settings established by the IIapi_initialize() for a specific environment handle.
Settings for environment parameters, which correspond to connection parameters, are used as the default connection parameter values unless specifically overridden by IIapi_setConnectParam().
Environment parameters also affect the conversions performed by IIapi_formatData() and control interactions between OpenAPI and the application.
This function has the following syntax:
II_VOID IIapi_setEnvParam (IIAPI_SETENVPRMPARM *setEnvPrmParm);
typedef struct _IIAPI_SETENVPRMPARAM
{
II_PTR se_envHandle;
II_LONG se_paramID
II_PTR se_paramValue
IIAPI_STATUS se_status
} IIAPI_SETENVPRMPARM;
This function has the following parameters:
se_envHandle
Type: input
Specifies the environment handle for the parameter being assigned.
se_paramID
Type: input
Specifies the parameter being assigned. For valid parameter ID macros, see the following list.
se_paramValue
Type: input
Specifies the value of the parameter being assigned. For the data type and description of the value associated with each parameter ID, see the following list.
se_status
Type: output
Specifies the status of the function upon its return. Its value is one of the following:
IIAPI_ST_SUCCESS
IIAPI_ST_FAILURE
IIAPI_ST_NOT_INITIALIZED
IIAPI_ST_INVALID_HANDLE
The following table lists valid parameter ID macros for the se_paramID parameter:
IIAPI_EP_CHAR_WIDTH
Data type: II_LONG
Specifies the maximum length of a character data type (IIAPI_BYTE_TYPE, IIAPI_CHA_TYPE, IIAPI_CHR_TYPE, IIAPI_VCH_TYPE).
IIAPI_EP_TXT_WIDTH
Data type: II_LONG
Specifies the maximum length of a text data type (IIAPI_TXT_TYPE).
IIAPI_EP_INT1_WIDTH
Data type: II_LONG
Specifies the length of an integer1 data type (IIAPI_INT_TYPE).
IIAPI_EP_INT2_WIDTH
Data type: II_LONG
Specifies the length of an integer2 data type (IIAPI_INT_TYPE).
IIAPI_EP_INT4_WIDTH
Data type: II_LONG
Specifies the length of an integer4 data type (IIAPI_INT_TYPE).
IIAPI_EP_FLOAT4_WIDTH
Data type: II_LONG
Specifies the length of a float4 data type (IIAPI_FLT_TYPE).
IIAPI_EP_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_EP_FLOAT8_WIDTH
Data type: II_LONG
Specifies the length of a float8 data type (IIAPI_FLT_TYPE).
IIAPI_EP_FLOAT4_PRECISION
Data type: II_LONG
Specifies the precision of a float4 data type (IIAPI_FLT_TYPE).
IIAPI_EP_FLOAT8_PRECISION
Data type: II_LONG
Specifies the precision of a float8 data type (IIAPI_FLT_TYPE).
IIAPI_EP_MONEY_PRECISION
Data type: II_LONG
Specifies the precision of a money data type (IIAPI_MNY_TYPE).
IIAPI_EP_FLOAT4_STYLE
Data type: II_CHAR
Specifies the format style of a float4 data type (IIAPI_FLT_TYPE).
IIAPI_EP_FLOAT8_STYLE
Data type: II_CHAR
Specifies the format style of a float8 data type (IIAPI_FLT_TYPE).
IIAPI_EP_NUMERIC_TREATMENT
Data type: II_CHAR
Specifies the treatment of the numeric literal. Its value is one of the following:
• IIAPI_EPV_DECASFLOAT
• IIAPI_EPV_DECASDEC
IIAPI_EP_MONEY_SIGN
Data type: II_CHAR
Specifies the money sign of an IIAPI_MNY_TYPE data type.
• IIAPI_EP_MONEY_LORT
Data type: II_LONG
Specifies the leading or trailing money sign. Its value is one of the following:
• IIAPI_CPU_MONEY_LEAD_SIGN
• IIAPI_CPU_MONEY_TRAIL_SIGN
IIAPI_EP_DECIMAL_CHAR
Data type: II_CHAR
Specifies the decimal character.
IIAPI_EP_MATH_EXCP
Data type: II_CHAR
Specifies the treatment of math exceptions. Its value is one of the following:
IIAPI_EPV_RET_FATAL
IIAPI_EPV_RET_WARN
IIAPI_EPV_RET_IGNORE
IIAPI_EP_STRING_TRUNC
Data type: II_CHAR
Specifies the truncation of strings.
IIAPI_EP_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_EPV_INGDATE
IIAPI_EPV_ANSIDATE
IIAPI_EP_DATE_FORMAT
Data type: II_LONG
Specifies the date format. Its value is one of the following:
IIAPI_EPV_DFRMT_US
IIAPI_EPV_DFRMT_MULT
IIAPI_EPV_DFRMT_FINNISH
IIAPI_EPV_DFRMT_ISO
IIAPI_EPV_DFRMT_GERMAN
IIAPI_EPV_DFRMT_YMD
IIAPI_EPV_DFRMT_MDY
IIAPI_EPV_DFRMT_DMY
IIAPI_EP_TIMEZONE
Data type: II_CHAR
Specifies the name of the time zone.
IIAPI_EP_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 it to the server.
IIAPI_EP_NATIVE_LANG_CODE
Data type: II_LONG
Specifies the language code of the native language used for error reporting. IIAPI_EP_NATIVE_LANG can be used when the language code is not known.
IIAPI_EP_CENTURY_BOUNDARY
Data type: II_LONG
Specifies the date century boundary.
IIAPI_EP_SEGMENT_LEN
Data type: II_LONG
Specifies the value used as the ds_length value when describing a BLOB column using IIapi_getDescriptor(), and will therefore be used as the segment length when retrieving a BLOB using IIapi_getColumns().
IIAPI_EP_TRACE_FUNC
Data type: II_PTR
IIAPI_EP_EVENT_FUNC
Data type: II_PTR
IIAPI_EP_CAN_PROMPT
Data type: II_PTR
More information:
Environment Parameter IIAPI_EP_CAN_PROMPT
An application can set IIAPI_EP_CAN_PROMPT in the IIapi_setEnvParam() function by providing the address of an application function to call back. OpenAPI invokes this application function to receive a reply from the application for the prompt message from the server using the following C structure:
typedef struct _IIAPI_PROMPTPARM
{
II_PTR pd_envHandle;
II_PTR pd_connHandle;
II_LONG pd_flags;
II_LONG pd_timeout;
II_UINT2 pd_msg_len;
II_CHAR *pd_message;
II_UINT2 pd_max_reply;
II_LONG pd_rep_flags;
II_UINT2 pd_rep_len;
II_CHAR *pd_reply;
} IIAPI_PROMPTPARM;
The syntax of the application function is as follows:
II_VOID promptFunc(IIAPI_PROMPTPARM *parm);
The application must invoke IIapi_setEnvParam() by setting se_paramID to IIAPI_EP_CAN_PROMPT and se_paramValue to the address of an application-supplied function that matches the calling sequence of the promptFunc() template function shown.
The IIAPI_PROMPTPARM parameters are described in the following table:
pd_envHandle
Type: input
Specifies the environment handle associated with the connection. It is NULL if the connection belongs to the default environment associated with IIAPI_VERSION_1 applications.
pd_connHandle
Type: input
Specifies the connection handle identifying the connection.
pd_flags
Type: input
Specifies the prompt flags. Its value is one of the following:
• IIAPI_PR_NOECHO
• IIAPI_PR_TIMEOUT
IIAPI_PR_NOECHO will be set if user input should not be echoed, generally indicating a request for a password. IIAPI_PR_TIMEOUT will be set if the pd_timeout parameter has a valid value.
pd_timeout
Type: input
Specifies the maximum time, in seconds, to wait for user input. Ignore this parameter if IIAPI_PR_TIMEOUT is not set in pd_flags.
Support for timeouts is platform-dependent.
pd_msg_len
Type: input
Specifies the length of the prompt message in pd_message.
pd_message
Type: input
Specifies the message to be displayed when prompting for user input.
pd_max_reply
Type: input
Specifies the maximum length of user input to be returned in pd_reply.
pd_rep_flags
Type: output
Specifies the response flags. The valid value is IIAPI_REPLY_TIMEOUT. Set this value if timeout occurred waiting for user response. (See IIAPI_PR_TIMEOUT in the pd_flags description.)
pd_rep_len
Type: output
Specifies the length of the user response in pd_reply.
pd_reply
Type: output
Specifies the user response.
Environment Parameter IIAPI_EP_TRACE_FUNC
An application can set IIAPI_EP_TRACE_FUNC in the IIapi_setEnvParam() function by providing an address of an application function to call back. OpenAPI invokes this application function to send trace information from the server to the application using the following C structure:
typedef struct _IIAPI_TRACEPARM
{
II_PTR tr_envHandle;
II_PTR tr_connHandle;
II_INT4 tr_length;
II_CHAR *tr_message;
} IIAPI_TRACEPARM;
The syntax of the application function is as follows:
II_VOID traceFunc(IIAPI_PROMPTPARM *parm);
The application must invoke IIapi_setEnvParam() by providing se_paramID to be IIAPI_EP_TRACE_FUNC and se_paramValue to the address of an application-supplied function that matches the calling sequence of the traceFunc() function template shown in this section.
The IIAPI_TRACEPARM parameters are described in the following table:
tr_envHandle
Type: input
Specifies the environment handle associated with the connection. It is NULL if the connection belongs to the default environment associated with IIAPI_VERSION_1 applications.
tr_connHandle
Type: input
Specifies the connection handle identifying the connection.
tr_length
Type: input
Specifies the length of the output trace message in tr_message.
tr_message
Type: input
Specifies the output trace message.
Trace output can also be directed to a file. For more information, see
II_API_SET environment variable (see
II_API_SET).
Environment Parameter IIAPI_EP_EVENT_FUNC
An application can set IIAPI_EP_EVENT_FUNC in the IIapi_setEnvParam() function by providing an address of an application function to callback. OpenAPI invokes this application function to send information on database events which failed to match an existing OpenAPI event handle (and would otherwise be ignored) to the application using the following C structure:
typedef struct _IIAPI_EVENTPARM
{
II_PTR ev_envHandle;
II_PTR ev_connHandle;
II_CHAR *ev_eventName;
II_CHAR *ev_eventOwner;
II_CHAR *ev_eventDB;
IIAPI_DATAVALUE ev_eventTime;
} IIAPI_EVENTPARM;
The syntax of the application function is as follows:
II_VOID eventFunc(IIAPI_EVENTPARM *parm);
The application must invoke IIapi_setEnvParam() by providing sc_paramID to be IIAPI_EP_EVENT_FUNC and sc_paramValue to the address of an application-supplied function that matches the calling sequence of the eventFunc() function template shown in this section.
The IIAPI_EVENTPARM parameters are described in the following table:
ev_envHandle
Type: input
Specifies the environment handle associated with the connection. It is NULL if the connection is associated with the default environment assigned to IIAPI_VERSION_1 applications.
ev_connHandle
Type: input
Specifies the connection handle identifying the connection.
ev_eventName
Type: input
Specifies the name of the database event.
ev_eventOwner
Type: input
Specifies the owner of the database event.
ev_eventDB
Type: input
Specifies the name of the database that raised the event.
ev_eventTime
Type: input
Specifies the time the event occurred, stored as an IIAPI_DTE_TYPE data value.