Specialized System Tools and Utilities
Using cvendian for Byte Order Conversion
This chapter describes a utility to convert the byte order of an InterSystems database for migration between Big-endian and Little-endian platforms. It also provides an option to report on the byte order of a given database.
InterSystems provides a utility to convert the byte order of an InterSystems database from Big-endian (that is, most-significant byte first) to Little-endian (that is, least-significant byte first), and vice versa. It is called cvendian
, for c
. This is useful when moving a database among platforms of the two types. It also provides an option to report on the byte order of a given database.
Never use this utility on a mounted database. Always take the database offline before using this utility on it.
You can run cvendian
on either the system that has the files to be converted or the system that will be using the converted files.
For example, to convert a database from a Little-endian to a Big-endian system, you can perform the conversion on the Little-endian system and then transfer the database to the Big-endian system, or you can transfer the file first, and then convert it.
This utility does not work for backup and journal files. You must restore databases on a platform of the same endian, move the restored databases to the different endian platform, and then use the cvendian
utility to convert the databases.
To convert a database, the process is:
Make a copy of your database files, because the utility replaces the source files with the converted files.
Enter the name of the directory in which the database is
stored. For a multi-volume database, enter the name of the
primary volume's directory, even if you want to relabel a
secondary volume. For a multi-volume legacy 2K database, you
should enter the name of the secondary volume directory if
you need to relabel it.
With the cvendian
endian utility, you can specify the desired byte order, or you can report the current byte order without conversion. Use the following syntax:
argument is one of the following:
convert the database to Big-endian
convert the database to Little-endian
report the byte order of the database
You can shorten the options to their initial letter. If this is a conversion request (-big
), and the database already has the specified byte order, the utility displays a warning message and stops processing.
If you do not provide the option
argument, the utility converts the database from the existing byte order to the other byte order. It is recommended, however, that you use the option
argument is the file to convert, and can include a complete pathname.
The utility performs the following actions:
Auto-detects the byte order of the database
Displays endian information and other information
Displays a message indicating success or failure
For example, suppose you are converting a database for use on Solaris SPARC from Windows XP. Because SPARC and Intel have incompatible data representations, you must convert from Little-endian (for Intel) to Big-endian (for SPARC). The output from running cvendian
on the Windows system before moving the file to the Solaris system looks similar to this:
C:\CacheSys\Bin>cvendian -big c:\temp\solarisdb\cache.dat
This database is little-endian.
This database has a block size of 8192 bytes.
This database has 1 volume and 1 map.
The last block in the primary volume is 18176.
Original manager directory is c:\temp\solarisdb\
No extension volumes.
Done converting c:\temp\solarisdb\cache.dat to big-endian
You can now move the converted database file to the Solaris system.