# mco_backup_create
RT

Create a backup record of the database.

### For an overview see page Incremental Online Backup in C

### Prototype

        void mco_backup_create(	/*IN*/ mco_db_h con,
                        /*IN*/ char const* file_name,
                        /*IN*/ char const* label,
                        /*IN*/ mco_backup_type type,
                        /*IN*/ int compression_level,
                        /*IN*/ char const* cipher,
                        /*IN*/ char* err_buf,
                        /*IN-OUT*/ unsigned int * err_buf_sz)

### Arguments

`con`
A database connection used to create the backup record
`file_name`
The name of the backup file where the backup record will be created
`label`
The backup's label
`type`

The type of backup record; one of the following:

        typedef enum {
            MCO_BACKUP_TYPE_SNAPSHOT,
            MCO_BACKUP_TYPE_INCREMENTAL,
            MCO_BACKUP_TYPE_AUTO
        } mco_backup_type;

where `type` has the following effect:

- `MCO_BACKUP_TYPE_SNAPSHOT` — An image of the entire database; must be done at least once
- `MCO_BACKUP_TYPE_INCREMENTAL` — A partial image of the database. Contains only differences in the database content between two consecutive backup records.
- `MCO_BACKUP_TYPE_AUTO` — Automatic selection of a snapshot or incremental record depending on the content of the backup file. If there is no snapshot in the file yet the backup process will create one; otherwise a partial backup record is created

`compression_level`
An optional backup compression level (1 to 9; 1 indicates the fastest, but the lowest compression level). Use 0 to disable compression.
`cipher`
An optional cipher to encrypt the backup
`err_buf`
A buffer for error description
`err_buf_sz`
On input this specifies the size of `err_buf`. On return it contains the number of characters written into the buffer. If `err_buf_sz` is null the routine returns `MCO_E_ILLEGAL_PARAM`.

### Description

This function creates a backup record of the database. The record can be full (a snapshot) or partial (an incremental record) depending on the `type` specified. Note that it is necessary to have at least one snapshot in a backup file. The backup process does not block database processing so the application is allowed to run transactions normally while the backup is in progress. The backup process blocks the database for only a short period of time when the normal data processing is paused or after a set number of transactions as specified by the backup parameters `backup_min_pages` and `backup_max_passes` passed to `mco_db_open_dev()` on database creation. (See the Incremental Backup and Restore page for further details.)

### Return Codes

`MCO_S_OK`
The backup was successful
`MCO_E_ILLEGAL_PARAM`
The label argument exceeds the maximum length allowed (`MCO_MAX_BACKUP_LABEL_SIZE`)
`MCO_E_DISK_OPEN`
Could not open the backup file
`MCO_E_DISK_SEEK`
The file system `fseek()` failed, probably due to backup file integrity failure
`MCO_E_DISK_VERSION_MISMATCH`
Incremental backup cannot be performed because the backup file doesn't contain a previous backup image

### Example

        {
            mco_db_h con;
            MCO_RET rc;
            char * filename = “backup.bak”;
            char label[MAX_LABEL_SIZE;
            int duration_msec = 1000;
            int msec;

            do
            {
                rc = mco_db_connect( db_name, &con );
                if ( MCO_S_OK == rc )
                {
                    msec = (int)MCO_SYSTEM_GET_CURRENT_TIME_MSEC();
                    sprintf(label, "Backup at %d msec", msec);

                    /* backup the database */
                    rc = mco_backup_create( con, filename, label,
                            MCO_BACKUP_TYPE_AUTO, 1, 0, 0);
                    sleep_msec(duration_msec);
                    mco_db_disconnect(con);
                }
            } while (rc == MCO_S_OK && !stop);
        }

### Files

Header file:
mco.h
Source file:
mcobackup.c
Library:
libmcobackup.a