Gsplit

Purpose

A database can now be backed up to disk regardless of the file size limitation imposed by the operating system. GSPLIT is a new InterBase utility designed to support GBAK. GBAK functionality now includes the ability to read from stdin and write to stdout. Utilizing this functionality, GSPLIT allows the operator to split the backup file created by GBAK into several files. GSPLIT is also used to restore a database from several files.

Feature Description

GSPLIT Syntax:

gsplit [[-split <filename> <size> {k|m|g} [<size> {k|m|g}...]]
  | [[-join <filename> [<filename>…]]
-split used to split the database into files during backup
-join used to join a set of files during restore.
<filename>

one or more filenames, to a maximum of 9999, are defined to contain the backup files.

While it is not a requirement, it is recommended that the files containing backups be named with the .gdk extension.

<size>{k|m|g}
file size specification. The minimum file size is 1 megabyte. The numeric file size is prefixed by a size indicator. If the size indicator is omitted, the numeric is interpreted as bytes and must be greater than 1,024,000 bytes (1 meg). The file size specification can be omitted for the last filename. The size of the last file will vary with the amount data left after the previous files are created.

Size indicators:

k = kilobytes: the number specified must be greater than 1024.
m = megabytes
g = gigabits

GSPLIT -join requires the <filename> argument(s) listed in the order created during backup. Maximum filename length is 27 bytes.

Using GBAK with GSPLIT:

To back up a database using both utilities, output from GBAK is directed to stdout and piped to GSPLIT. To restore from a set of files created by GSPLIT the files are joined together using GSPLIT and piped to GBAK which accepts the data from stdin. In both cases, stdin and stdout take the place of the .gbk file which GBAK would normally use to produce a backup and to restore from that backup file. The backup may be thought of as a data stream which is simply placed on stdout or stdin so that GSPLIT can manipulate the data—in one case splitting the stream and in the other joining it together again.

Syntax:

Backup:
gbak {-t | -b} <database file>.gdb stdout |
gsplit -split <file> <size> >{k | m| g} [<file> <size> {k|m|g}…]

Restore:
gsplit -join <file> [<file>…] | gbak {-r | -c} stdin <database file>.gdb

Examples:

Backup: To restore a database, output from GSPLIT is piped to GBAK. GBAK is directed to accept input from stdin:

gbak -backup big.gbd stdout | gsplit -split foo1.gdk 1g foo2.gdk 1g foo3.gdk

Restore:

gsplit -join foo1 foo2 foo3 | gbak -replace stdin big.gdb

Compression

The UNIX utilities compress and uncompress can be used on the command line with GSPLIT. For example, to backup a database and compress the files:

gbak -backup big.gbd stdout | compress | gsplit -split foo1.gdk 1g foo2.gdk 1g foo3.gdk

Or:

gbak -backup big.gdb stdout | compress > big.gbk.Z

To restore the compressed files use:

gsplit -join foo1 foo2 foo3 | uncompress | gbak -replace stdin big.gdb

Or:

uncompress -c big.gbk.Z | gbak -r stdin newbig.gdb

Functional Changes

GSPLIT Processing: Command Line options

GSPLIT will process command line option parameters one at a time until no more exist and will take the following action:

  1. Issues an error message when mixing "-split" with "-join" or vise-versa.
  2. Issues an error message when detecting file name followed by another file name during "-split" option parameters processing.
  3. Issues an error message when detecting file size specification followed by another file size specification during "-split" option parameters processing.
  4. Issues an error message when detecting invalid file size indicator suffix during "-split" option parameters processing.
  5. Issues an error message when detecting file size specification is less than 1 Megabyte during "-split" option parameters processing.

GSPLIT processing: SPLIT operation

GSPLIT will process the stream accepted from stdout, and it will produce one backup file one at a time until no more backup file specifications remain

  1. Allocates an 16K I/O buffer
  2. Reads 16K of data from standard input file at a time
  3. Writes out the header record sets the file size equal to file size specified - length of header record.
  4. Writes as much input data to backup file as file size indicated
  5. If the disk is full then writes remaining data into subsequent backup files. (this does not make sense unless files are on another device)
  6. Go back to step 2 until finished reading all the input data from stdout
  7. Issues an error message when the disk is full and there is remaining data to be written out.

GSPLIT processing: JOIN operation:

GSPLIT will process backup files one at a time until no more backup files exist to be joined. The joined file is automatically put on stdout so that it may be received by GBAK as data using stdin. The data can then be interpreted by GBAK as a valid database backup file (.gbk).

  1. Reads backup header record from backup file
  2. Validates backup header record and issues error message if problem. reads the rest of the data from backup file
  3. Writes data to standard output file
  4. Go back to step 1