API string encoding switch

Purpose

API	Parameter Name	Name prior to V12.6.0
C	CPXPARAM_Read_APIEncoding	CPX_PARAM_APIENCODING
C++	IloCplex::Param::Read::APIEncoding	APIEncoding
Java	not in this API	not in this API
.NET	not in this API	not in this API
OPL	not in this API	not in this API
Python	not in this API	not in this API
MATLAB	Cplex.Param.read.apiencoding	read.apiencoding
Interactive	not in this component	not in this component
Identifier	1130	1130

Description

Specifies which encoding (also known as the code page) that CPLEX uses to represent strings. That is, this parameter tells CPLEX which characters to expect as input and how to represent as output such strings as the name of a model, of a variable, of a constraint. If, for example, your application uses an accent in the name of a model, an umlaut in the name of a variable, or a Chinese character for the name of a constraint, then this parameter is of interest to you.

Note:

This parameter has no effect on IBM CPLEX Optimizer for z/OS, where only EBCDIC IBM-1047 encoding is available.

Which features does this parameter govern?

Generally, this parameter impacts names, such as the name of a model, the names of variables, the names of constraints, and other modeling elements. Also CPLEX respects this parameter (in the application programming interfaces (APIs) where the parameter is available) when CPLEX provides information (such as a log, a warning, an error message) on an output stream.

In the Callable Library (C API), this parameter specifies the encoding in which CPLEX passes a string to a function destination added to a channel by means of the routine CPXaddfuncdest.

In the C++ API, this parameter specifies the encoding of streams accessed by the methods setWarning and setOut. CPLEX also encodes exceptions according to the value of this parameter.

This parameter is not available in the Python API where CPLEX relies on the native encoding.

This parameter is not available in the C#.NET API where CPLEX relies on the native encoding.

This parameter is not available in the Java API where CPLEX relies on the native encoding.

For a brief description of the advantages of UTF-8, see the topic Selecting an encoding in the CPLEX User’s Manual.

Which values does this parameter accept?

This parameter accepts a string specifying the user’s choice of encoding, such as UTF-8, ISO-8859-1, US-ASCII, and so forth.

An asterisk (*) is an acceptable value in some situations. This wildcard instructs CPLEX to use the default converter according to the protocols and standards of International Components for Unicode (ICU). In other words, CPLEX calls ICU with a NULL encoding. When ICU is called with a NULL encoding (as in this case), ICU takes the name of the encoding from the terminal where the application started.

Other acceptable values of this parameter depend on the API.

In the Callable Library (C API), this parameter accepts any string that is the name of a valid code page supported by CPLEX. For example, UTF-8 is a multi-byte encoding that is an acceptable value for this parameter; it encompasses the ASCII character set; it does not allow valid characters to include a NULL byte.

For a complete list of valid strings that are the name of an encoding (that is, the name of a code page), consult the web site of a standards organization such as:
In the C++ API, the value of this parameter must be the name of an encoding that is a superset of ASCII. For example, ASCII is a subset of the encoding or code page UTF-8, so UTF-8 is an acceptable value for this parameter. Likewise, ASCII is a subset of ISO-8859-1, also known as Latin-1, so ISO-8859-1 is an acceptable value for this parameter. However, the code page UTF-16 is not acceptable, nor is UTF-32 because both allow valid characters that contain a NULL byte.

What is the default value of this parameter?

The default value of this parameter depends on the API.

In the C API, the default value is the string ISO-8859-1 (also known as Latin-1).
In the C++ API, the default value is the string ISO-8859-1 (also known as Latin-1).
In the CPLEX for MATLAB APIs, the default value is the asterisk (*).

The encoding ISO-8859-1 is a superset of the familiar ASCII encoding, so it supports many widely used character sets. However, this default encoding cannot represent multi-byte character sets, such as Chinese, Japanese, Korean, Vietnamese, or Indian characters, for example. If you want to represent a character set that requires multiple bytes per character, then a better choice for the value of this parameter is UTF-8.

If you change the value of this parameter, you must verify that your choice is compatible with the file encoding switch (CPXPARAM_Read_FileEncoding, FileEncoding). In fact, the encoding or code page specified by the API encoding parameter must be a subset of the encoding or code page specified by the file encoding parameter. For example, if the value of the file encoding parameter is UTF-8, then US-ASCII is an acceptable value of the API encoding parameter because US-ASCII is a subset of UTF-8. For examples of the hazards of incompatible choices of the encoding parameters, see the topic Selecting an encoding in the CPLEX User’s Manual.

What about errors?

In situations where CPLEX encounters a string, such as content in a file, that is not compatible with the specified encoding, the behavior is not defined. Because of the incompatibility, CPLEX silently converts the string to an inappropriate character of the specified encoding, or CPLEX raises the error 1235 CPXERR_ENCODING_CONVERSION. For an example of why such unpredictable behavior occurs, see the topic Selecting an encoding in the CPLEX User’s Manual.

Values

valid string for the name of an encoding (code page) that is a superset of ASCII; default: ISO-8859-1 or empty string.