begriffs open source - ai-pg/blob - full-docs/txt/sql-createconversion.txt

   1
   2 CREATE CONVERSION
   3
   4    CREATE CONVERSION — define a new encoding conversion
   5
   6 Synopsis
   7
   8 CREATE [ DEFAULT ] CONVERSION name
   9     FOR source_encoding TO dest_encoding FROM function_name
  10
  11 Description
  12
  13    CREATE CONVERSION defines a new conversion between two character set
  14    encodings.
  15
  16    Conversions that are marked DEFAULT can be used for automatic encoding
  17    conversion between client and server. To support that usage, two
  18    conversions, from encoding A to B and from encoding B to A, must be
  19    defined.
  20
  21    To be able to create a conversion, you must have EXECUTE privilege on
  22    the function and CREATE privilege on the destination schema.
  23
  24 Parameters
  25
  26    DEFAULT
  27           The DEFAULT clause indicates that this conversion is the default
  28           for this particular source to destination encoding. There should
  29           be only one default encoding in a schema for the encoding pair.
  30
  31    name
  32           The name of the conversion. The conversion name can be
  33           schema-qualified. If it is not, the conversion is defined in the
  34           current schema. The conversion name must be unique within a
  35           schema.
  36
  37    source_encoding
  38           The source encoding name.
  39
  40    dest_encoding
  41           The destination encoding name.
  42
  43    function_name
  44           The function used to perform the conversion. The function name
  45           can be schema-qualified. If it is not, the function will be
  46           looked up in the path.
  47
  48           The function must have the following signature:
  49
  50 conv_proc(
  51     integer,  -- source encoding ID
  52     integer,  -- destination encoding ID
  53     cstring,  -- source string (null terminated C string)
  54     internal, -- destination (fill with a null terminated C string)
  55     integer,  -- source string length
  56     boolean   -- if true, don't throw an error if conversion fails
  57 ) RETURNS integer;
  58
  59           The return value is the number of source bytes that were
  60           successfully converted. If the last argument is false, the
  61           function must throw an error on invalid input, and the return
  62           value is always equal to the source string length.
  63
  64 Notes
  65
  66    Neither the source nor the destination encoding can be SQL_ASCII, as
  67    the server's behavior for cases involving the SQL_ASCII “encoding” is
  68    hard-wired.
  69
  70    Use DROP CONVERSION to remove user-defined conversions.
  71
  72    The privileges required to create a conversion might be changed in a
  73    future release.
  74
  75 Examples
  76
  77    To create a conversion from encoding UTF8 to LATIN1 using myfunc:
  78 CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;
  79
  80 Compatibility
  81
  82    CREATE CONVERSION is a PostgreSQL extension. There is no CREATE
  83    CONVERSION statement in the SQL standard, but a CREATE TRANSLATION
  84    statement that is very similar in purpose and syntax.
  85
  86 See Also
  87
  88    ALTER CONVERSION, CREATE FUNCTION, DROP CONVERSION