Gbak - Functional Specification

Description

Current gbak (Version 5.1.1 and before) is not able to split the backup file into multiple files nor to restore a database from several files. To be able to do that the separate gsplit utility is required. Gsplit is an utility that works as a filter to write the output of gbak to multiple files. This utility is implemented for UNIX platforms only. The proposal here is to implement split and join functionality within the gbak utility. This functionality will be implemented for all platforms. As result of that, Version 6.0 gbak will be able to split and restore a database from multiple files. Gsplit utility will be no longer shipped with the product.

Another proposal here is to implement a 'service' switch for gbak utility. In case of a 'service' switch the gbak utility uses service manager (administrative APIs) to do backup and restore. In this case we save time on a network communication between client (gbak) and server since all the work is done on the server side. As result of that, we get a significant performance improvement for platforms that do not support a local access.

User Interface/Usability

Syntax:

To back up a database to multiple files (split operation):

gbak [-B] [options] database filename size[k|m|g] [... filename [size[k|m|g]]

It is unnecessary to specify the size of the last file.

To restore a multi-file backup (join operation) to single file:

gbak {-C|-R} [options] filename [... filename]database

To restore a multi-file backup (join operation) to multiple files:

gbak {-C|-R} [options] filename [... filename] primary m secondary1
     [n1 secondary2 [n2]]

To back up a database locally (on the server machine):

gbak [-B] -se [rvice] service_name database filename

To restore a database locally (on the server machine):

gbak {-C|-R} -se[rvice] service_name filename database

Note

The service_name specifies the name of the host (server machine) to connect to and the protocol as follows:

  • TCP/IP hostname:service_mgr
  • SPX hostnane@service_mgr
  • Named Pipes hostnameservice_mgr
  • Local service_mgr

The 'database' and 'filename' specifications refer to a filename relative to the server machine.

Examples

To limit the first backup file, f1.gbk to 200 Megabytes and the second backup file, f2.gbk to 300 Kbytes:

gbak -backup some.gdb f1.gbk 200m f2.gbk 300k f3.gbk

To rejoin the backup files for a restore:

gbak -restore f1.gbk f2.gbk f3.gbk database.gdb

To back up a database on the server typhoon using TCP/IP protocol:

gbak -backup -service typhoon:service_mgr some.gdb file.gbk

Error Messages

  • size specification either missing or incorrect for file <string>.
  • file <string> out of sequence.
  • can't join -- one of the files missing.
  • standard input is not supported when using join operation.
  • backup file <string> might be corrupt.
  • database file specification missing.
  • can't write a header record to file <string>.
  • free disk space exhausted.
  • file size given (n) is less than minimum allowed (m).
  • Warning -- free disk space exhausted for file <string>, the rest of the bytes (n) will be written to file <string>.
  • service name parameter missing.

Requirements and Constraints

  • stdout is not allowed to be used as one of the output files in split operation.
  • stdin is not allowed to be used as one of the input files in join operation.
  • The minimum file size for split and join operation is limited to 2KB.
  • If there is no free disk space left during write operation to the last file specified on the command line, gbak exits with error message (see error message above).
  • The local switch can only be used if backup file will be located on the server machine (see Migration Issues section of the Administration API - Database Maintenance Functional Specification for conditions when backup process can create a remote file).