The Collation command-line utility dbcollat extracts a collation (sorting sequence) into a file suitable for creating a database using a custom collation.
The file that is produced by dbcollat can be modified and used with Sybase Central or with the COLLATION option of CREATE DATABASE to create a new database with a custom collation.
Exit codes are 0 (success) or non-zero (failure).
You must change the label on the following line in the collation file. If you do not, the custom collation will conflict with the original collation on which it is based.
Collation label (name)
If you wish to create a custom collation but have not yet created a database, you should extract a collation from the sample database.
For more information on custom collating sequences, see Chapter 11, “International Languages and Character Sets” of the Sybase IQ System Administration Guide.
dbcollat [options] output-file
The following table lists the available options for the dbcollat utility.
Option |
Description |
|---|---|
-c "keyword=value; ..." |
Supply database connection parameters |
-d filename |
Convert definition file to INSERT statement with collation mapping placed in mapping-file |
-e |
Include empty mappings |
-o filename |
Log messages to a file |
-q |
Quiet mode — do not print messages |
-v |
Show version of IQ software. |
-x |
Use hex for extended characters (7F-FF) |
-y |
Replace file without confirmation |
-z col-seq |
Specify collating sequence label |
This utility accepts @filename parameters.
Connection parameters (-c) For a description of the connection parameters, see Chapter 4, “Connection and Communication Parameters” in the Sybase IQ System Administration Guide. If the connection parameters are not specified, connection parameters from the SQLCONNECT environment variable are used, if set.
For example, the following Windows command extracts a collation
file from the asiqdemo database
running on the sample_server server,
and connects as user ID DBA with
password SQL:
dbcollat -c "eng=sample_server;dbn=asiqdemo;uid=DBA;pwd=SQL" c:\sample\col
Convert the definition file to an INSERT statement (-d) When a database is created, the collation is inserted into the SYS.SYSCOLLATION system table. A mapping from the collation to character sets and Sybase TDS collations is also inserted into the SYS.SYSCOLLATIONMAPPINGS system table. This collation is selected from the set of provided collations in the collseqs.sql file or from the custom collations in the custom.sql file in the scripts subdirectory of your Sybase IQ installation directory.
For more information about the SYSCOLLATIONMAPPINGS system table, see “SYSCOLLATIONMAPPINGS system table” in Sybase IQ Reference Manual.
Custom collations are added to the custom.sql script.
The -d option converts the
collation file that you edited into an INSERT statement
that can be copied into custom.sql.
For example, you can use the -d option with the dbcollat command as follows:
dbcollat -d coll-defn-file custom-file
The coll-defn-file is read and parsed as a collation definition. Output is written to custom-file. The custom-file contents must be added to custom.sql.
For more information about creating a custom collation using the –d option, see “Creating a custom collation” in Sybase IQ System Administration Guide.
Include empty mappings (-e) Normally, collations don't specify the actual value that a character is to sort to. Instead, each line of the collation sorts to one position higher than the previous line. However, older collations have gaps between some sort positions. Normally, the Collation utility skips the gaps and writes the next line with an explicit sort-position. This option causes the Collation utility to write empty mappings (consisting of just a colon (:)) for each line in the gap.
Log messages to file (-o) Write output messages to the named file.
Operate quietly (-q) Do not display messages on a window.
Show version (-v) Display the IQ version number.
Use hexadecimal for extended characters [7F to FF] (-x) Extended single-byte characters (whose value is greater than hex 7F) may or may not appear correctly on your screen, depending on whether or not the code page in use on your computer is the same as the code page of the collation you are extracting. This option causes the Collation utility to write any character to hex 7F or above as a two-digit hexadecimal number, in the form \xdd. For example:
\x80, \xFE
Without the –x option, only characters from hex 00 to hex 1F, hex 7F and hex FF are written in hexadecimal form.
Operate without confirming actions (-y) Choosing this option automatically replaces an existing collation file without prompting for confirmation.
Specify
collating sequence label (-z) Specify the label of the collation to be extracted.
The names of the collation sequences can be found by executing the
following command: dbinit -1.
If this option is not specified, then the Collation utility extracts
the collation being used by the database. For more information about
collations, see “Understanding
collations” in Chapter 11, “International
Languages and Character Sets” in Sybase IQ System Administration Guide.
If the -z option is specified with one of the available collation labels, then dbcollat does not connect to a database. Otherwise, it connects to a database and extracts the collation of that database. If the collation label does not match the collation label of the database, an error is returned.
If -z is not specified, the default collation is used. Normal ASCII (binary) ordering is used for the lower 128 characters. For the upper 128 characters (also called the extended characters), any character that is an accented form of a letter in the lower 128 are sorted to the same position as the unaccented form. The determination of whether or not an extended character is an accented letter is based upon code page 850 (multilingual code page).
For a list of available collation labels, see “Supplied and recommended collations” in Chapter 11, “International Languages and Character Sets” in Sybase IQ System Administration Guide.
The following Windows command extracts a collation file from the asiqdemo database running on the sample_server server, and connects as user ID DBA with password SQL:
dbcollat -c "eng=sample_server;dbn=asiqdemo;uid=DBA;pwd=SQL" c:\sample\col
The following command uses the -z option of dbcollat to extract the details of collation 850:
dbcollat -c "uid=DBA;pwd=SQL;eng=sample_server" -z 850 c:\sample\col
For more information on custom collating sequences, see Chapter 11, “International Languages and Character Sets” of the Sybase IQ System Administration Guide.
