Ingres CL CK
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - CK
Abstract
This is the specification of the CK facility provided by the compatibility library for checkpointing database files.
Revision: 1.0, 2-Jan-91
Document History
- Revision 1.0, last modified 2-Jan-91.
Specification
Introduction
The CK routines perform backups of DI type files. The CK routines are separate from the DI routines partly out of past history and partly because of the function. These routines allow a DI directory of files to be copied to backup storage on disk or offline media such as tape. Such offline media may require human intervention to complete the operation. The directory of files can be restored from the archive image created in the previous step.
Library
CL
Intended Uses
The CK routines are intended for the sole use of the checkpoint and rollforward routines in DMF.
Assumptions
It must be possible for both database processes and the checkpoint writing process to be able to read, and the DBMS to write DI files at the same time.
While a directory is being restored, no other program should use files in the directory. Access can be coordinated through LK.
A file must be restored to the same directory from which it was saved.
The CL routines CKsave and CKrestore must provide the ability to write directly to offline archival media.
CKbegin() and CKend() are to be used to bracket all archival operations. These routines are primarily used to allow operator intervention for handling removeable media, but should be used to bracket disk-based archive operations also. CKend() should still be called, even if the operation fails.
The CKsave() implementation must not block concurrent access to database files; exclusively locking would defeat the purpose of online backup--allowing ``normal transactions to run while online backup is processing.
Definitions
| archive | The output of a CKsave call is a named entity containing the contents of all files in the DI directory that was saved. The filenames are also saved in the save file. The format should be whatever works most efficiently for host operating system. A database backup will consist of a archive file for each Ingres location the database resides on. |
| checkpoint directory | File directory used to contain a disk-based archive. |
Concepts
The CK routines must remember the original name given to each file written to a CK save file. The file is recreated with the same name by the CK restoration routine.
Both the VMS and Unix implementations of CK use a template file, which allows for specialized customizations of the save/restore processing. Implementors of CK should consider adopting this scheme, as it has proved flexible and convenient.
Some implementations of CK support simultaneous save or restore of multiple database locations. That is, the CKsave or CKrestore operations are accumulated internally and performed at CKend time. Client code should be aware of this and should make no restrictions on this behavior (e.g., client code should not introduce any dependencies on performing the save or restore operations in any particular order).
Header File <ck.h>
The header file <ck.h> must be included before using any of the functions provided.
Executable Interface
The following functions are provided.
CKbegin - begin checkpointing of a database
Inform CK that checkpoints are about to be written or read from a device. This allows some kind of operator intervention and the ability to deal properly with some tape drives.
Inputs:
| type | The type of output device. |
| Either CK_DISK_FILE or CK_TAPE_FILE. | |
| ckp_path | Pointer to checkpoint path. |
| ckp_l_path | Length of checkpoint path. |
| numlocs | number of locations begin checkpointed |
Outputs:
| sys_err | Reason for error return. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CK_BAD_PARAM | File name too long, or bad type. |
| CK_FILENOTFOUND | The "checkpoint template file could not be found. |
Definition:
STATUS CKbegin(type, oper, ckp_path, ckp_l_path, numlocs, sys_err) u_i4 type; char oper; char *ckp_path; u_i4 ckp_l_path; u_i4 numlocs; CL_ERR_DESC *sys_err;
CKdelete - delete a disk-based CK archive
This routine deletes a disk-based CK archive.
Inputs:
| path | Pointer to path. |
| l_path | Length of path. |
| filename | Pointer to file name. |
| l_filename | Length of file name. |
Outputs:
| sys_err | Reason for error return. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CK_NOTFOUND | |
| CK_BADPATH | |
| CK_BAD_PARAM | File name too long, or bad type. |
| CK_BADDELETE |
Definition:
STATUS CKdelete(path, l_path, filename, l_filename, sys_err) char *path; u_i4 l_path; char *filename; u_i4 l_filename; CL_ERR_DESC *sys_err;
CKdircreate - create a disk-based checkpoint directory
The CKdircreate will take a path name and directory name and create a directory in this location.
Inputs:
| path | Pointer to the path name. |
| pathlength | Length of path name. |
| dirname | Pointer to the directory name. |
| dirlength | Length of directory name. |
Outputs:
| err_code | Pointer to a variable used to return operating system errors. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CK_BAD_DIR | Path specification error. |
| CK_BAD_PARAM | Parameter(s) in error. |
| CK_EXISTS | Already exists. |
| CK_DIR_NOT_FOUND | Path not found. |
Definition:
STATUS CKdircreate(path, pathlength, dirname, dirlength, err_code) char *path; u_i4 pathlength; char *dirname; u_i4 dirlength; CL_ERR_DESC *err_code;
CKdirdelete - delete a disk-based checkpoint directory
The CKdirdelete routine is used to delete a direct access directory. The name of the directory to delete should be specified as path and dirname, where dirname does not include a type qualifier or version and the path does not include the directory name (which it normally does for other DI calls). The directory name may be converted to a filename of the directory and use DIdelete to delete it. This call should fail with CK_BAD_DELETE if any files still exists in the directory.
Inputs:
| path | Pointer to the area containing the path name for this directory. |
| pathlength | Length of path name. |
| dirname | Pointer to the area containing the directory name. |
| dirlength | Length of directory. |
Outputs:
| err_code | Pointer to a variable used to return operating system errors. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CK_DIR_NOT_FOUND | Path not found. |
| CK_NOT_FOUND | File not found. |
| CK_BAD_PARAM | Parameter(s) in error. |
| CK_BAD_DELETE | Error trying to delete directory. |
Definition:
STATUS
CKdirdelete(path, pathlength, dirname, dirlength, err_code) char *path; u_i4 pathlength; char *dirname; u_i4 dirlength; CL_ERR_DESC *err_code;
CKend - end checkpoint operations on a database
Inform CK that checkpointing of a database have concluded.
Inputs:
| type | The type of output device. | Either CK_DISK_FILE or CK_TAPE_FILE. | |
| oper | Operation: 'B'=begin, 'E'=end, 'W'=work | ||
| ckp_path | Pointer to checkpoint path. | ||
| ckp_l_path | Length of checkpoint path. |
Outputs:
| sys_err | Reason for error return. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CK_BAD_PARAM | File name too long, or bad type. |
| any other | operating system specific error that can be looked up in the error message file. |
Definition:
STATUS CKend(type, oper, ckp_path, ckp_l_path, sys_err) u_i4 type; char oper; char *ckp_path; u_i4 ckp_l_path; CL_ERR_DESC *sys_err;
CKlistfile - list all files in a checkpoint directory
The CKlistfile routine will list all files that exist in the directory(path) specified. This routine expects as input a function to call for each file found. This insures that all resources tied up by this routine will eventually be freed. The files are not listed in any specific order. The function passed to this routine must return OK if it wants to continue with more files, or a value not equal to OK if it wants to stop listing. If the function returns anything but OK, then CKlistfile will return CK_BADLIST. The function must have the following call format:
STATUS funct_name(arg_list, filename, filelength, err_code) PTR arg_list; Pointer to argument list char *filename; Pointer to directory name. u_i4 filelength; Length of directory name. CL_ERR_DESC *err_code; Pointer to operating system err codes (if applicable).
Inputs:
| path | Pointer to the path name. |
| pathlength | Length of path name. |
| fnct | Function to pass the directory entries to. |
| arg_list | Pointer to function argument list. |
Outputs:
| err_code | Pointer to a variable used to return operating system errors. |
Returns:
| Never returns OK. | |
| CK_BAD_DIR | Path specification error. |
| CK_END_FILE | Error returned from client handler or all files listed. |
| CK_BAD_PARAM | Parameter(s) in error. |
| CK_DIR_NOT_FOUND | Path not found. |
| CK_BAD_LIST | Error trying to list objects. |
Definition:
STATUS CKlistfile(path, pathlength, func, arg_list, err_code) char *path; u_i4 pathlength; STATUS (*func)(); PTR arg_list; CL_ERR_DESC *err_code;
CKrestore - restore DI directory from a checkpoint archive
This routine takes a CKsave archive, containing a set of DI files and restores all the files in the save file to the given DI directory. Exiting files in the directory which are not being restored are not removed.
Inputs:
| ckp_path | Pointer to ckp file path. |
| ckp_l_path | Length of ckp file path. |
| ckp_file | Pointer to ckp file name. |
| ckp_l_file | Length of ckp file name. |
| type | Checkpoint device type. Either CK_DISK_FILE or CK_TAPE_FILE. |
| di_path | Pointer to DI path. |
| di_l_path | Length of DI path. |
Outputs:
| sys_err | Reason for error status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CK_BAD_PARAM | File name too long, or bad type. |
| Any operating system specific error that can be looked up in the error message file. |
Definition:
STATUS CKrestore(ckp_path, ckp_l_path, ckp_file, ckp_l_file, type, di_path, di_l_path, sys_err) char *ckp_path; u_i4 ckp_l_path; char *ckp_file; u_i4 ckp_l_file; u_i4 type; char *di_path; u_i4 di_l_path; CL_ERR_DESC *sys_err;
CKsave - save a DI directory into a checkpoint archive
This routine takes a directory of DI files, and writes them to a single archive. There is no checking of the DI files, a bulk copy is performed.
The CKsave() implementation must not block concurrent access to database files; exclusively locking would defeat the purpose of online backup--allowing "normal transactions to run while online backup is processing.
Inputs:
| di_path | Pointer to DI directory path. |
| di_l_path | Length of DI directory path. |
| type | The type of output device. |
| Either CK_DISK_FILE or CK_TAPE_FILE. | |
| ckp_path | Pointer to checkpoint path. |
| ckp_l_path | Length of checkpoint path. |
| ckp_file | Pointer to checkpoint file name. |
| ckp_l_file | Length of checkpoint file name. |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CK_BAD_PARAM | File name too long, or bad type. |
| any other | Any operating system specific error that can be looked up in the error message file. |
Definition:
STATUS CKsave(di_path, di_l_path, type, ckp_path, ckp_l_path, ckp_file, ckp_l_file, sys_err) char *di_path; u_i4 di_l_path; u_i4 type; char *ckp_path; u_i4 ckp_l_path; char *ckp_file; u_i4 ckp_l_file; CL_ERR_DESC *sys_err;
Examples
Here are a few typical calls.
/* Call the checkpoint routine. */
status = CKsave(&ext->ext_entry[i].physical,
ext->ext_entry[i].phys_length, CK_DISK_FILE,
&dcb->dcb_ckp->physical,
dcb->dcb_ckp->phys_length,
&filename, sizeof(filename), &sys_err);
if (status != OK)
{
ule_format(status, &sys_err, ULE_LOG, 0, 0, 0, err_code);
*err_code = E_DM1101_CPP_WRITE_ERROR;
return (E_DB_ERROR);
}
/* Call the checkpoint routine. */
status = CKrestore(&dcb->dcb_ckp->physical,
dcb->dcb_ckp->phys_length, &filename, sizeof(filename),
CK_DISK_FILE, &dcb->dcb_root->physical,
dcb->dcb_root->phys_length, &sys_err);
if (status != OK)
{
ule_format(status, &sys_err, ULE_LOG, 0, 0, 0, err_code);
*err_code = E_DM1101_CPP_WRITE_ERROR;
return (E_DB_ERROR);
}
|
Ingres Compatability Library |
