CODEPAGE-CONVERT function

Converts a string value from one code page to another.

Syntax


CODEPAGE-CONVERT ( `source-string` [ , `target-codepage` [ , `source-codepage` ] ] )

source-string

A CHARACTER or LONGCHAR expression to be converted.

target-codepage

A character-string expression that evaluates to the name of a code page. The returned character value is relative to target-codepage. The name that you specify must be a valid code page name available in the DLC/convmap.cp file (a binary file that contains all of the tables that ABL uses for character management). If you supply a non-valid name, the CODEPAGE-CONVERT function returns the Unknown value (?). Before returning a character value, the CODEPAGE-CONVERT function converts source-string from source-codepage to target-codepage. If you do not specify target-codepage, no code page conversions occur.

source-codepage

A character-string expression that evaluates to the name of a code page. The source-codepage specifies the name of the code page to which source-string is relative. The name that you specify must be a valid code page name available in the DLC/convmap.cp file. If you supply a non-valid name, the CODEPAGE-CONVERT function returns the Unknown value (?). The default value of source-codepage is the value of CHARSET attribute of the SESSION handle.

If source-string is a LONGCHAR variable, the source-codepage argument is not valid. In this case, the code page of the LONGCHAR variable is used as the source code page.

Example

This example assumes that the native code page of r-codpag.p is ibm850. It is written so that its embedded text strings are always converted to the internal code page of the ABL session (SESSION:CHARSET).

r-codpag.p
DEFINE VARIABLE cp850string AS CHARACTER NO-UNDO INITIAL "text with umlaut (ä)". DEFINE VARIABLE charsetstring AS CHARACTER NO-UNDO. charsetstring = CODEPAGE-CONVERT(cp850string, SESSION:CHARSET, "ibm850"). FOR EACH Item NO-LOCK: IF LOOKUP(charsetstring, Item.CatDescription) > 0 THEN DISPLAY Item.ItemName. END.

r-codpag.p

DEFINE VARIABLE cp850string   AS CHARACTER NO-UNDO 
  INITIAL "text with umlaut (ä)". 
DEFINE VARIABLE charsetstring AS CHARACTER NO-UNDO. 
charsetstring = CODEPAGE-CONVERT(cp850string, SESSION:CHARSET, "ibm850"). 
FOR EACH Item NO-LOCK: 
  IF LOOKUP(charsetstring, Item.CatDescription) > 0 THEN 
    DISPLAY Item.ItemName. 
END.

Notes

The CODEPAGE-CONVERT function returns the corresponding character string in the specified code page. By default, the value of SESSION:CHARSET is iso8859-1. You can set a different internal code page by specifying the Internal Code Page (-cpinternal) parameter. For more information, see OpenEdge Development: Internationalizing Applications and OpenEdge Deployment: Startup Command and Parameter Reference.

This function is especially useful if you plan to run a procedure in an ABL session in which the SESSION:CHARSET code page is different from the native code page of the procedure.

When you write procedures with ABL, you must use 7-bit (that is, ASCII) characters for field names and variable names. But you can use 8-bit and multi-byte characters, including Unicode, for data values such as character strings and constants. Thus, a procedure written and compiled on a system using one code page can be run on a system using another code page as long as you convert all embedded character strings to the internal code page. Using CODEPAGE-CONVERT as shown in the example allows your procedures to be virtually code page independent.