Data Conversion Rules
This section describes the data conversions that occur when you use the SQL and LDAP data accessors. It provides the rules you need to specify variable types in your scripts, external databases, and data conversion files.
A single data variable can be represented differently in a script, a data accessor, and an external database. You must configure all three components correctly so that Steel-Belted Radius Carrier can perform the correct data conversions. Improper configuration can cause data corruption or runtime errors.
The SQL or LDAP schema determines how data are stored in external databases. Use the [VariableTypes] section of the LDAP or SQL data accessor .gen file to specify the corresponding data types for input and output container variables. You must also use the appropriate JavaScript syntax in your scripts.
The maximum integer value supported during data conversion is 2,147,483,647 (0x7FFFFFFF). To retrieve an integer value greater than the maximum value from the database, the output container variable should be configured as string in the [VariableTypes] section of the .gen file and the keyword Number should be used in your script to convert the string to integer. For an example configuration, see Example 4.
Output Container
Output Container
SQL and LDAP data accessor plug-ins require that output container variables map to database columns of type string. When the DataAccessor.Execute() function is called, the result strings returned from the database are parsed according to the respective output container variable types declared in the data accessor configuration (.gen) file. The parsed data values are stored in the output container.
Subsequently, when the DataAccessor.GetOutputVariable() function is called, a second conversion is performed. Output container variables of type integer are returned to the script as JavaScript integer data. All other output container variable types are returned as strings. To avoid unnecessary data conversions, output container variables that refer to integer data should be declared as integer in the [VariableTypes] section of the .gen file. All other output container variables should be declared as string.
It is legal, but inefficient, to declare an output container variable to be a type other than integer or string. For example, if an output container variable is declared to be type ipaddress, when the data accessor executes, the string representation of the address in the database must first be converted to a binary IP address structure, then when the script retrieves the value from the output container, the binary IP address must be converted back to a string representation. This conversion process wastes a significant amount of computing resources.
Attempting to map an output container variable to a non-string database column causes a runtime error when the data accessor is executed regardless of the variable type declaration in the .gen file.
Input Container
Input Container
Data conversions are not performed when data are passed from the script to the input container, and from the input container to the database. Input container variables might refer to string, numeric, or binary column data in the database. The data types must all match across the script, the .gen file, and the database schema.
In most cases, the only input container variable types used with the JavaScript API (and the corresponding database column types) are integer and string. Other data types can be stored in the input container by coding the binary data directly as unformatted JavaScript strings using the standard String.fromCharCode() function. You are responsible for programming the binary coding correctly.
Examples
Examples
The examples in this section refer to SQL database queries, tables, and columns, but can apply to LDAP searches, records, and tables.
Example 1
Example 1
When DataAccessor.SetInputVariable() is called for an integer variable, the JavaScript API can determine how to convert the supplied argument. For example, the following .gen file configuration declares an input container variable Count of type integer:
Both of these statements result in the correct integer data type being passed to the Count variable in the SQL query:
In this example, the index column in the database must also be of integer type to match the Count input container variable. If not, a type mismatch error occurs when the plug-in attempts to execute the SQL statement.
Example 2
Example 2
Represent types other than integer as strings. In this configuration file, the ipaddress column in database table bar contains IP address values represented as formatted strings. The input container variable IP-Address is declared as a string in the .gen file; and in the call to DataAccessor.SetInputVariable(), the argument value is also passed as a string.
The .gen file configuration is as follows:
The .jsi file configuration is as follows:
You can change the .gen file to make IP-Address a binary (ipaddress) input container variable.
Then the script might have to pass the data to SetInputVariable() as an integer or unformatted binary string.
or:
Because the container variable ip-address is declared as type ipaddress, the data accessor expects the input container data to be in a binary format appropriate to the type and passes it along unchanged to the database. The definition of the database address column must be changed to an appropriate binary type.
Example 3
Example 3
This example shows how to retrieve an IP address value from the database. Because column IP-Address is mapped to an output container variable, the database schema must declare IP-Address to be of string type.
The .gen file configuration is as follows:
The .jsi file configuration is as follows:
Similar results can be generated by declaring output container variable IP-Address to be of type ipaddress. As noted, this causes the data value to be converted to a binary form internal to the data accessor, but wastes some computing resources.
Example 4
Example 4
This example explains how to retrieve an integer value that is greater than the maximum value 2,147,483,647 (0x7FFFFFFF). In this example, the output container variable is mapped to the database column User-ID of type integer. The variable User-ID is declared as string in the .gen file, because the User-ID value stored in the database is greater than the maximum integer value. In the script, the Number keyword is used to convert the string back to integer.
The following syntax also works in cases where the size of the integer may be unknown.
The .gen file configuration is as follows:
The .jsi file configuration is as follows:
Supported Data Types and Conversions
Supported Data Types and Conversions
Table 137 lists supported data types and conversions for input container variables.
Table 137: Data Types and Conversions for Input Container Variables
Input Container Variable Type | JavaScript Type | Database Type |
|---|---|---|
Integer | Integer, String | Integer |
String | String | String |
| Unformatted Binary String (not recommended) | <Binary Type> |
The JavaScript Type column refers to the JavaScript variable types to be passed to the DataAccessor.SetInputVariable() function for each input container variable type.
We recommend that you not configure the .gen file with input container variables of these types:
IPv4 Address
IPv6 Address
IPv6 Prefix
IPv6 Interface
Time
Instead, represent these data types as formatted strings within the script, the data accessor, and the database.
Table 138 lists supported data types and conversions for output container variables.
Table 138: Data Types and Conversions for Output Container Variables
Output Container Variable Type | JavaScript Type | Database Type |
|---|---|---|
Integer | Integer | String |
String | String | String |
| Type-Specific Formatted String | String |
Time | Time-String ( yyyy/mm/dd [hh[:mm[:ss]]] ) | String |
All columns and fields referred to by output container variables must contain string data. Integer output container variables are returned to the script as JavaScript integers. All other types are converted to formatted JavaScript strings.