GT.M Database Endian Conversion - UNIX

Technical Bulletin: GT.M Database Endian Conversion - UNIX

Legal Notice

June 14, 2006

Revision History
Revision 1.014 June 2006



                        GT.M Group

                        Fidelity National Information Services, Inc.

                        2 West Liberty Boulevard, Suite 300

                        Malvern, PA  19355, 

                        United States of America

                     



                        GT.M Support: +1 (610) 578-4226 

                        Switchboard: +1 (610) 296-8877 

                        Fax: +1 (484) 595-5101

                        http://www.fis-gtm.com

                        gtmsupport@fnf.com

                    

Table of Contents

Background
Overview
User Interface
MUPIP ENDIANCVT
DSE DUMP -FILEHEADER
Error Messages
Typographical Conventions

Return to top

Background

GT.M is implemented and supported on both little endian and big endian format systems. x86 GNU/Linux and Alpha/AXP Tru64 UNIX and OpenVMS are little endian systems, whereas pSeries AIX, SPARC Solaris and PA-RISC HP-UX are big endian systems. GT.M database files contain binary data in addition to ASCII text. A binary data field could be longer than a byte. For performance considerations, GT.M stores such data in the native format, i.e., data elements are stored in the endian format of the system on which a database is created and used. Therefore, a database file created in a given endian format cannot be used directly on a system of the other endian format. To migrate data from an endian platform to one with a different endian format in prior versions of GT.M, one had to export data into ASCII format with a MUPIP EXTRACT -FORMAT=ZWR on the source platform and import with a MUPIP LOAD on the target platform.

The EXTRACT/LOAD procedure for large databases can be time consuming due to the volume of data that has to be converted from binary to ZWR format (on source) and vice versa (on target). One must also consider the fact that the ASCII extract file can be very large for a large database. Adequate storage is required to support the size of the extract file and the space occupied by the source and target databases. In order to reduce the total time and space it takes to transfer database content from one endian platform to another, it is efficient to convert the endian format in-place for a database and transfer the converted database. GT.M V5.1-000 provides such endian conversion.

Return to top

User Interface

Return to top

MUPIP ENDIANCVT

mupip endiancvt [-outdb <outdb-file>] <db-file>

The command converts a database file from one endian format to the other (BIG to LITTLE or LITTLE to BIG).

Requirements:

  • ENDIANCVT requires standalone access to the database

  • An informational message with the “from” and “to” endian formats is printed as is a confirmation request to perform the conversion. Conversion begins only upon receiving positive confirmation, which is a case insensitive "yes".

<db-file> is required and is the source database for endian conversion. The default is to convert <db-file> in place.

-outdb : Write the converted output to <outdb-file>. In this case, the source database <db-file> is not modified.

<outdb-file> will be exactly the same size as <db-file>. Adequate storage is required for <outdb-file> if endian conversion is to complete successfully.

GT.M on a big endian platform can convert a little endian database into big endian and vice versa; as can GT.M on a little endian platform. Standalone access is required to perform conversion. GT.M (run-time and utilities other than MUPIP ENDIANCVT) on a given endian platform will only open and process databases that are in the same endian format. An attempt to open a database of a format other than the native endian format triggers an error and the database open is aborted.

The source and target platforms for ENDIANCVT must both be UNIX. MUPIP ENDIANCVT does not convert database files created on OpenVMS to UNIX format and vice versa. For transferring OpenVMS database content to UNIX and vice versa, the EXTRACT/LOAD approach must be used. MUPIP ENDIANCVT is not supported on OpenVMS as GT.M databases on OpenVMS are always in little endian format.

MUPIP ENDIANCVT converts database files only. Other files such as global directory, binary extract, and journal files must be created in the native format on the target platform.

Before running endian conversion, ensure that the database does not have any integrity errors. An existing error may be propagated or even exacerbated by endian conversion. Journaling (and replication) must be disabled before performing endian conversion.

If converting in-place, having a backup is strongly recommended since, if the conversion does not complete for any reason, including a software bug, the database will not be recoverable.

Return to top

DSE DUMP -FILEHEADER

The output of DSE DUMP -FILEHEADER now includes the endian format of the database file as follows:

DSE> dump -fileheader

File            /gtm/V51000/mumps.dat
Region          DEFAULT
Date/Time       01-JUN-2006 08:59:46 [$H = 60409,32386]

  Access method                          BG  Global Buffers                1024
  Reserved Bytes                          0  Block size (in bytes)         1024
  Maximum record size                   256  Starting VBN                   129
  Maximum key size                       64  Total blocks            0x00000065
  Null subscripts                     NEVER  Free blocks             0x00000062
  Standard Null Collation             FALSE  Free space              0x00006000
  Last Record Backup     0x0000000000000001  Extension Count                100
  Last Database Backup   0x0000000000000001  Number of local maps             1
  Last Bytestream Backup 0x0000000000000001  Lock space              0x00000028
  In critical section            0x00000000  Timers pending                   0
  Cache freeze id                0x00000000  Flush timer            00:00:01:00
  Freeze match                   0x00000000  Flush trigger                  960
  Current transaction    0x0000000000000001  No. of writes/flush              7
  Maximum TN             0xFFFFFFFFDFFFFFFF  Certified for Upgrade to        V5
  Maximum TN Warn        0xFFFFFFFF5FFFFFFF  Desired DB Format               V5
  Master Bitmap Size                     64  Blocks to Upgrade       0x00000000
  Create in progress                  FALSE  Modified cache blocks            0
  Reference count                         1  Wait Disk                        0
  Journal State                    DISABLED
  Mutex Hard Spin Count                 128  Mutex Sleep Spin Count         128
  Mutex Spin Sleep Time                2048  KILLs in progress                0
  Replication State                     OFF  Region Seqno    0x0000000000000001
  Zqgblmod Seqno         0x0000000000000000  Zqgblmod Trans  0x0000000000000000
  Endian Format                      LITTLE
                        

Return to top

Error Messages

DBENDIAN

Database file xxxx is aaaa endian on a gggg endian system

Severity:

Error

MUPIP/Run Time Error:

This indicates that the database file being opened is in the wrong endian format for the current system. This usually means that the file was copied from another system with the opposite endian format.

Action:

To use the database file on the current system, change the endian format using the MUPIP ENDIANCVT command.

NOENDIANCVT

Unable to convert the endian format of file xxxx due to yyyy

Severity:

Error

MUPIP Error:

One of the requirements for the MUPIP ENDIANCVT command was not met. The problems reported are: “database format is not the current version”, "minor database format is not the current version”, "some blocks are not upgraded to the current version”, "kills in progress", "the database is frozen", "a GT.CM server accessing the database", "recovery was interrupted", "database creation in progress", "wc_blocked is set - rundown needed", "the database is corrupted".

Action:

Resolve the reported conditions and repeat the command.

ENDIANCVT

Converted database file xxxx from yyyy endian to zzzz endian on a wwww endian system

Severity:

Informational

MUPIP Information:

When MUPIP ENDIANCVT has successfully completed, it displays the conversion information. This information includes the database file, its previous endian format, the new endian format, and the endian format that is native to the current system.

Return to top

Typographical Conventions

Command Syntax: UNIX syntax (i.e., lowercase text and "-" for flags/qualifiers) is used throughout this document.

Reference Number: The reference numbers used to track software enhancements and customer support requests appear in parentheses ( ).

Platform Identifier: If a new feature or software enhancement does not apply to all platforms, the relevant platform appears in brackets [ ].

Return to top

For more information, see the GT.M web site.