CREATE CONVERSION

Description

Defines a new conversion between two character set encodings. This function is for internal use only. You are advised not to use it.

Precautions

• The DEFAULT parameter indicates that the conversion between the source encoding and the target encoding is executed by default between the client and the server. To support this usage, bidirectional conversion must be defined, that is, both conversion from A to B and conversion from B to A are supported.
• To perform conversion, you must have the EXECUTE permission on function and the CREATE permission on the target schema.
• SQL_ASCII cannot be used for either source encoding or target encoding because the server behavior is hardwired when SQL_ASCII "encoding" is involved.
• You can remove user-defined conversions using DROP CONVERSION.

Syntax

CREATE [ DEFAULT ] CONVERSION name
    FOR 'source_encoding' TO 'dest_encoding' FROM function_name;

Parameters

• DEFAULT

  Specifies that the conversion is the default conversion from the source encoding to the target encoding. There should be only one default conversion for each encoding pair in a schema.

• name

  Specifies the name of the conversion, which can be restricted by the schema. If not restricted by a schema, the conversion is defined in the current schema. The conversion name must be unique in a schema.

• source_encoding

  Source encoding name.

• dest_encoding

  Target encoding name.

• function_name

  Function used for conversion. A function name can be restricted by a schema. If not, the function is found in the path. The return value of the function is the number of bytes that are successfully converted.

  The function must be in the following format:

  conv_proc(     
       integer,  -- Source encoding ID
       integer,  -- Target encoding ID
       cstring, -- Source character string (a null-terminated C character string)
       internal,-- Target (filled with a null-terminated C character string)
       integer  -- Length of the source string
  ) RETURNS void;