Ingres CL SR
From Ingres Community Wiki
|
Ingres Compatability Library |
Contents |
Compatibility Library Specification - SR
Abstract
This is the specification of the SR facility provided by the compatibility library.
Revision: 1.1, 15-Nov-1997.
Document History
- Revision 1.1, last modified 15-Nov-1997.
- Converted to HTML.
- Revision 1.0, last modified 3-May-91.
Specification
Introduction
The SR routines perform all the direct file I/O for all sorts. The SR routines have been separated from the DI routines, which perform direct I/O on shared files, to allow easy modification of the sort package without affecting the DI routines. This also provides for special I/O handling to ensure that SORTs perform as fast as possible. It has also been separated out in the hope that the entire sort package can be moved to the CL to provide a better way of implementing specialized sort packages such as the ACCEL sorter with minimal changes to the DBMS code.
Library
CL
Intended Uses
The SR routines are intended for the sole use of the SORT routines in DMF.
Assumptions
The following assumptions apply to the SR routines:
- Files are not shared.
- Files are temporary.
- Should be able to handle variable length I/O. That is, multiple physical blocks can be accessed as a single logical request as long as the logical request is a multiple of the physical block size.
- Sorting I/O must be as efficient as possible.
Concepts
The page size is determined at open. The page size can vary from 4096 to 32768 in powers of 2. The number of pages allocated multiplied by the page size must be a multiple of 32K.
Header File <sr.h>
The header file <sr.h> must be included before using any of the functions provided. The following are also defined.
SR_IO - file context for SR I/O
The SR_IO structure is used to contain all the operating system dependent I/O information required for direct I/O. It is very operating system specific. The memory for this structure is allocated by the caller of the SR routines.
Clients may not interpret the content of this structure. This is an example structure used on VAX/VMS.
typedef struct _SR_IO
{
i4 io_allocated; /* Last allocated disk block. */
i4 io_type; /* Control block identifier. */
#define SR_IO_ASCII_ID 'IOCB'
i4 io_channel; /* VMS channel used for this file */
i4 io_block_size; /* File block size. */
i4 io_log2_blk; /* Log 2 of io_block_size. */
i4 io_blks; /* VMS block per SR block. */
struct
{
i4 str_len; /* Length of described item. */
char *str_str; /* Address of described item. */
} io_fib_desc; /* FIB descriptor. */
char io_fib[32]; /* VMS File Information Block. */
};
Executable Interface
The following functions are provided.
SRclose - closes an SR file
The SRclose routine is used to close a sort file. It will check to ensure the file is open before trying to close. It will also delete it if the delete flag is set to SR_IO_DELETE.
Inputs:
| f | Pointer to the SR file context needed to do I/O. |
| delete_flag | Variable used to indicate if file is to be deleted. Set this flag to SR_IO_DELETE to delete the file. |
Outputs:
| err_code | Pointer to a variable used to return system specific errors. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| SR_BADCLOSE | Error closing file or bad parameters. |
| SR_BADFILE | Bad file context. |
Definition:
STATUS SRclose(f, delete_flag, err_code) SR_IO *f; u_i4 delete_flag; CL_ERR_DESC *err_code;
SRopen - open an SR file
The SRopen routine is used to open a sort file. It will open the file for read or write access on a particular open and will place no locks on the file. If the create_flag is set it will create it and allocate the amount specified. Additional space may be required to accomplish the sort. An unlimited number of extensions must be allowed. You can specify that nothing should be allocated at create time.
Inputs:
| f | Pointer to the SR file context needed to do I/O. |
| path | Pointer to the directory name for the file. |
| pathlength | Length of path name. |
| filename | Pointer to file name. |
| filelength | Length of file name. |
| pagesize | Value indicating size of page in bytes. Must be one of: 4096, 8192, 16384 , 32768. |
| create_flag | Value indicating if creation needed. Set this flag to SR_IO_CREATE to create the file. |
| n | Value indicating number of pages to pre-allocate. |
Outputs:
| f | Updates the file control block. |
| err_code | Pointer to a variable used to return operating system errors. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| SR_BADCREATE | Error creating file. |
| SR_EXCEED_LIMIT | Too many open files, exceeding disk quota or exceeding available disk space. |
Definition:
STATUS SRopen(f, path, pathlength, filename, filelength, pagesize, create_flag, n, err_code) SR_IO *f; char *path; u_i4 pathlength; char *filename; u_i4 filelength; i4 pagesize; u_i4 create_flag; i4 n; CL_ERR_DESC *err_code;
SRread - read a page from an SR file
The SRread routine is used to read pages of a direct access sort file.
Performance may suffer if the page buffer being written is not sufficiently aligned. Memory obtained with MEget_pages is known to be aligned adequately.
Inputs:
| f | Pointer to the SR file context needed to do I/O. |
| page | Value indicating page to read. |
Outputs:
| buf | Pointer to the area to hold page being read. |
| f | Updates the file control block. |
| err_code | Pointer to a variable used to return operating system errors. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| SR_ENDFILE | End of file reached. Should not return ENDFILE on a partial read. |
Definition:
STATUS SRread(f, page, buf, err_code) SR_IO *f; i4 page; char *buf; CL_ERR_DESC *err_code;
SRwrite - write a page to an SR file
The SRwrite routine is used to write pages of a direct access file. To insure that a full page can always be read or written, this routine must always allocate pages using the maximum page size of 32K. Then if the file is created with a size of 8K, but opened with a size of 32K, there will be enough pages allocated to satisfy the last read request even if only 8K of the last page is valid.
Inputs:
| f | Pointer to the SR file context needed to do I/O. |
| page | Value indicating page to write. |
| buf | Pointer to page to write. |
Outputs:
| f | Updates the file control block. |
| err_code | Pointer to a variable used to return operating system errors. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| SR_EXCEED_LIMIT | Exceeding disk quota or exceeding available disk space. |
Definition:
STATUS SRwrite(f, page, buf, err_code) SR_IO *f; i4 page; char *buf; CL_ERR_DESC *err_code;
Example
example()
{
SR_IO srio;
char path[64];
u_i4 l_path;
char buffer[32768];
CL_ERR_DESC sys_err;
i4 i;
/*
** Create a sort file with the following characteristics:
**
** Blocksize = 32768 Bytes
** Preallocate = 8 Blocks
*/
status = SRopen(&srio, path, l_path, "sortwork.inn", (u_i4)12,
(i4)32768, SR_IO_CREATE, 8, &sys_err);
if (status != OK)
error();
/* Write some blocks to the file. */
for (i = 0; i < 10; i++)
{
status = SRwrite(&srio, i, buffer, &sys_err);
if (status != OK)
error();
}
/* Read the blocks back from the file. */
for (i = 0; i < 10; i++)
{
status = SRread(&srio, i, buffer, &sys_err);
if (status != OK)
error();
}
/* Close and delete the file. */
status = SRclose(&srio, SR_IO_DELETE, &sys_err);
if (status != OK)
error();
}
|
Ingres Compatability Library |
