<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h2 class="title">
      <a name="adding-character-set">
      </a>
      12.13 Adding a Character Set
     </h2>
    </div>
   </div>
  </div>
  <div class="toc">
   <dl class="toc">
    <dt>
     <span class="section">
      <a href="character-arrays.html">
       12.13.1 Character Definition Arrays
      </a>
     </span>
    </dt>
    <dt>
     <span class="section">
      <a href="string-collating.html">
       12.13.2 String Collating Support for Complex Character Sets
      </a>
     </span>
    </dt>
    <dt>
     <span class="section">
      <a href="multibyte-characters.html">
       12.13.3 Multi-Byte Character Support for Complex Character Sets
      </a>
     </span>
    </dt>
   </dl>
  </div>
  <a class="indexterm" name="idm46045215437088">
  </a>
  <a class="indexterm" name="idm46045215435600">
  </a>
  <p>
   This section discusses the procedure for adding a character set to
      MySQL. The proper procedure depends on whether the character set
      is simple or complex:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      If the character set does not need special string collating
          routines for sorting and does not need multibyte character
          support, it is simple.
     </p>
    </li>
    <li class="listitem">
     <p>
      If the character set needs either of those features, it is
          complex.
     </p>
    </li>
   </ul>
  </div>
  <p>
   For example,
   <code class="literal">
    greek
   </code>
   and
   <code class="literal">
    swe7
   </code>
   are simple character sets, whereas
   <code class="literal">
    big5
   </code>
   and
   <code class="literal">
    czech
   </code>
   are complex character sets.
  </p>
  <p>
   To use the following instructions, you must have a MySQL source
      distribution. In the instructions,
   <em class="replaceable">
    <code>
     MYSET
    </code>
   </em>
   represents the name of the
      character set that you want to add.
  </p>
  <div class="orderedlist">
   <ol class="orderedlist" type="1">
    <li class="listitem">
     <p>
      Add a
      <code class="literal">
       &lt;charset&gt;
      </code>
      element for
      <em class="replaceable">
       <code>
        MYSET
       </code>
      </em>
      to the
      <code class="filename">
       sql/share/charsets/Index.xml
      </code>
      file. Use
          the existing contents in the file as a guide to adding new
          contents. A partial listing for the
      <code class="literal">
       latin1
      </code>
      <code class="literal">
       &lt;charset&gt;
      </code>
      element follows:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-xml"><div class="docs-select-all right" id="sa56234711"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-xml"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>charset</span> <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>latin1<span class="token punctuation">"</span></span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>family</span><span class="token punctuation">&gt;</span></span>Western<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>family</span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>description</span><span class="token punctuation">&gt;</span></span>cp1252 West European<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>description</span><span class="token punctuation">&gt;</span></span>
  ...
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>collation</span> <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>latin1_swedish_ci<span class="token punctuation">"</span></span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>8<span class="token punctuation">"</span></span> <span class="token attr-name">order</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Finnish, Swedish<span class="token punctuation">"</span></span><span class="token punctuation">&gt;</span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>flag</span><span class="token punctuation">&gt;</span></span>primary<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>flag</span><span class="token punctuation">&gt;</span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>flag</span><span class="token punctuation">&gt;</span></span>compiled<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>flag</span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>collation</span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>collation</span> <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>latin1_danish_ci<span class="token punctuation">"</span></span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>15<span class="token punctuation">"</span></span> <span class="token attr-name">order</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Danish<span class="token punctuation">"</span></span><span class="token punctuation">/&gt;</span></span>
  ...
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>collation</span> <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>latin1_bin<span class="token punctuation">"</span></span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>47<span class="token punctuation">"</span></span> <span class="token attr-name">order</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Binary<span class="token punctuation">"</span></span><span class="token punctuation">&gt;</span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>flag</span><span class="token punctuation">&gt;</span></span>binary<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>flag</span><span class="token punctuation">&gt;</span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>flag</span><span class="token punctuation">&gt;</span></span>compiled<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>flag</span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>collation</span><span class="token punctuation">&gt;</span></span>
  ...
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>charset</span><span class="token punctuation">&gt;</span></span></code></pre>
     </div>
     <p>
      The
      <code class="literal">
       &lt;charset&gt;
      </code>
      element must list all
          the collations for the character set. These must include at
          least a binary collation and a default (primary) collation.
          The default collation is often named using a suffix of
      <code class="literal">
       general_ci
      </code>
      (general, case-insensitive). It
          is possible for the binary collation to be the default
          collation, but usually they are different. The default
          collation should have a
      <code class="literal">
       primary
      </code>
      flag. The
          binary collation should have a
      <code class="literal">
       binary
      </code>
      flag.
     </p>
     <p>
      You must assign a unique ID number to each collation. The
          range of IDs from 1024 to 2047 is reserved for user-defined
          collations. To find the maximum of the currently used
          collation IDs, use this query:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa95566446"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">SELECT</span> <span class="token function">MAX</span><span class="token punctuation">(</span>ID<span class="token punctuation">)</span> <span class="token keyword">FROM</span> INFORMATION_SCHEMA<span class="token punctuation">.</span>COLLATIONS<span class="token punctuation">;</span></code></pre>
     </div>
    </li>
    <li class="listitem">
     <p>
      This step depends on whether you are adding a simple or
          complex character set. A simple character set requires only a
          configuration file, whereas a complex character set requires C
          source file that defines collation functions, multibyte
          functions, or both.
     </p>
     <p>
      For a simple character set, create a configuration file,
      <code class="filename">
       <em class="replaceable">
        <code>
         MYSET
        </code>
       </em>
       .xml
      </code>
      ,
          that describes the character set properties. Create this file
          in the
      <code class="filename">
       sql/share/charsets
      </code>
      directory. You
          can use a copy of
      <code class="filename">
       latin1.xml
      </code>
      as the basis
          for this file. The syntax for the file is very simple:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: disc; ">
       <li class="listitem">
        <p>
         Comments are written as ordinary XML comments
              (
         <code class="literal">
          &lt;!--
          <em class="replaceable">
           <code>
            text
           </code>
          </em>
          --&gt;
         </code>
         ).
        </p>
       </li>
       <li class="listitem">
        <p>
         Words within
         <code class="literal">
          &lt;map&gt;
         </code>
         array elements
              are separated by arbitrary amounts of whitespace.
        </p>
       </li>
       <li class="listitem">
        <p>
         Each word within
         <code class="literal">
          &lt;map&gt;
         </code>
         array
              elements must be a number in hexadecimal format.
        </p>
       </li>
       <li class="listitem">
        <p>
         The
         <code class="literal">
          &lt;map&gt;
         </code>
         array element for the
         <code class="literal">
          &lt;ctype&gt;
         </code>
         element has 257 words.
              The other
         <code class="literal">
          &lt;map&gt;
         </code>
         array elements
              after that have 256 words. See
         <a class="xref" href="character-arrays.html" title="12.13.1 Character Definition Arrays">
          Section 12.13.1, “Character Definition Arrays”
         </a>
         .
        </p>
       </li>
       <li class="listitem">
        <p>
         For each collation listed in the
         <code class="literal">
          &lt;charset&gt;
         </code>
         element for the
              character set in
         <code class="filename">
          Index.xml
         </code>
         ,
         <code class="filename">
          <em class="replaceable">
           <code>
            MYSET
           </code>
          </em>
          .xml
         </code>
         must contain a
         <code class="literal">
          &lt;collation&gt;
         </code>
         element that defines the character ordering.
        </p>
       </li>
      </ul>
     </div>
     <p>
      For a complex character set, create a C source file that
          describes the character set properties and defines the support
          routines necessary to properly perform operations on the
          character set:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: disc; ">
       <li class="listitem">
        <p>
         Create the file
         <code class="filename">
          ctype-
          <em class="replaceable">
           <code>
            MYSET
           </code>
          </em>
          .c
         </code>
         in the
         <code class="filename">
          strings
         </code>
         directory. Look at one
              of the existing
         <code class="filename">
          ctype-*.c
         </code>
         files (such
              as
         <code class="filename">
          ctype-big5.c
         </code>
         ) to see what needs to
              be defined. The arrays in your file must have names like
         <code class="literal">
          ctype_
          <em class="replaceable">
           <code>
            MYSET
           </code>
          </em>
         </code>
         ,
         <code class="literal">
          to_lower_
          <em class="replaceable">
           <code>
            MYSET
           </code>
          </em>
         </code>
         ,
              and so on. These correspond to the arrays for a simple
              character set. See
         <a class="xref" href="character-arrays.html" title="12.13.1 Character Definition Arrays">
          Section 12.13.1, “Character Definition Arrays”
         </a>
         .
        </p>
       </li>
       <li class="listitem">
        <p>
         For each
         <code class="literal">
          &lt;collation&gt;
         </code>
         element
              listed in the
         <code class="literal">
          &lt;charset&gt;
         </code>
         element
              for the character set in
         <code class="filename">
          Index.xml
         </code>
         ,
              the
         <code class="filename">
          ctype-
          <em class="replaceable">
           <code>
            MYSET
           </code>
          </em>
          .c
         </code>
         file must provide an implementation of the collation.
        </p>
       </li>
       <li class="listitem">
        <p>
         If the character set requires string collating functions,
              see
         <a class="xref" href="string-collating.html" title="12.13.2 String Collating Support for Complex Character Sets">
          Section 12.13.2, “String Collating Support for Complex Character Sets”
         </a>
         .
        </p>
       </li>
       <li class="listitem">
        <p>
         If the character set requires multibyte character support,
              see
         <a class="xref" href="multibyte-characters.html" title="12.13.3 Multi-Byte Character Support for Complex Character Sets">
          Section 12.13.3, “Multi-Byte Character Support for Complex Character Sets”
         </a>
         .
        </p>
       </li>
      </ul>
     </div>
    </li>
    <li class="listitem">
     <p>
      Modify the configuration information. Use the existing
          configuration information as a guide to adding information for
      <em class="replaceable">
       <code>
        MYSYS
       </code>
      </em>
      . The example here assumes
          that the character set has default and binary collations, but
          more lines are needed if
      <em class="replaceable">
       <code>
        MYSET
       </code>
      </em>
      has
          additional collations.
     </p>
     <div class="orderedlist">
      <ol class="orderedlist" type="a">
       <li class="listitem">
        <p>
         Edit
         <code class="filename">
          mysys/charset-def.c
         </code>
         , and
         <span class="quote">
          “
          <span class="quote">
           register
          </span>
          ”
         </span>
         the collations for the new
              character set.
        </p>
        <p>
         Add these lines to the
         <span class="quote">
          “
          <span class="quote">
           declaration
          </span>
          ”
         </span>
         section:
        </p>
        <div class="copytoclipboard-wrapper">
         <pre class="programlisting language-c"><div class="docs-select-all right" id="sa4645318"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-c"><span class="token macro property">#<span class="token directive keyword">ifdef</span> HAVE_CHARSET_<em class="replaceable">MYSET</em></span>
<span class="token keyword">extern</span> CHARSET_INFO my_charset_<em class="replaceable">MYSET</em>_general_ci<span class="token punctuation">;</span>
<span class="token keyword">extern</span> CHARSET_INFO my_charset_<em class="replaceable">MYSET</em>_bin<span class="token punctuation">;</span>
<span class="token macro property">#<span class="token directive keyword">endif</span></span></code></pre>
        </div>
        <p>
         Add these lines to the
         <span class="quote">
          “
          <span class="quote">
           registration
          </span>
          ”
         </span>
         section:
        </p>
        <div class="copytoclipboard-wrapper">
         <pre class="programlisting language-c"><div class="docs-select-all right" id="sa15107332"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-c"><span class="token macro property">#<span class="token directive keyword">ifdef</span> HAVE_CHARSET_<em class="replaceable">MYSET</em></span>
  <span class="token function">add_compiled_collation</span><span class="token punctuation">(</span><span class="token operator">&amp;</span>my_charset_<em class="replaceable">MYSET</em>_general_ci<span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token function">add_compiled_collation</span><span class="token punctuation">(</span><span class="token operator">&amp;</span>my_charset_<em class="replaceable">MYSET</em>_bin<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token macro property">#<span class="token directive keyword">endif</span></span></code></pre>
        </div>
       </li>
       <li class="listitem">
        <p>
         If the character set uses
         <code class="filename">
          ctype-
          <em class="replaceable">
           <code>
            MYSET
           </code>
          </em>
          .c
         </code>
         ,
              edit
         <code class="filename">
          strings/CMakeLists.txt
         </code>
         and add
         <code class="filename">
          ctype-
          <em class="replaceable">
           <code>
            MYSET
           </code>
          </em>
          .c
         </code>
         to the definition of the
         <code class="literal">
          STRINGS_SOURCES
         </code>
         variable.
        </p>
       </li>
       <li class="listitem">
        <p>
         Edit
         <code class="filename">
          cmake/character_sets.cmake
         </code>
         :
        </p>
        <div class="orderedlist">
         <ol class="orderedlist" type="i">
          <li class="listitem">
           <p>
            Add
            <em class="replaceable">
             <code>
              MYSET
             </code>
            </em>
            to the value of
                  with
            <code class="literal">
             CHARSETS_AVAILABLE
            </code>
            in
                  alphabetic order.
           </p>
          </li>
          <li class="listitem">
           <p>
            Add
            <em class="replaceable">
             <code>
              MYSET
             </code>
            </em>
            to the value of
            <code class="literal">
             CHARSETS_COMPLEX
            </code>
            in alphabetic
                  order. This is needed even for simple character sets,
                  so that
            <span class="command">
             <strong>
              CMake
             </strong>
            </span>
            can recognize
            <a class="link" href="source-configuration-options.html#option_cmake_default_charset">
             <code class="option">
              -DDEFAULT_CHARSET=
              <em class="replaceable">
               <code>
                MYSET
               </code>
              </em>
             </code>
            </a>
            .
           </p>
          </li>
         </ol>
        </div>
       </li>
      </ol>
     </div>
    </li>
    <li class="listitem">
     <p>
      Reconfigure, recompile, and test.
     </p>
    </li>
   </ol>
  </div>
 </div>
 <br/>
</div>
