|
@@ -60,7 +60,7 @@ data is paged into memory as needed and the requested data is returned to
|
|
|
the caller.
|
|
|
|
|
|
\note All routines and global variables in this library, documented
|
|
|
-or undocumented, start with the prefix \c segment_. To avoid name
|
|
|
+or undocumented, start with the prefix \c Segment_. To avoid name
|
|
|
conflicts, programmers should not create variables or routines in their own
|
|
|
modules which use this prefix.
|
|
|
|
|
@@ -86,7 +86,7 @@ be initialized before any data can be transferred to the segment file.
|
|
|
This can be done with the <I>Segment Library</I> routine:
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_open(SEGMENT *SEG, char *fname, off_t nrows, off_t ncols,
|
|
|
+<I>int Segment_open(SEGMENT *SEG, char *fname, off_t nrows, off_t ncols,
|
|
|
int srows, int scols, int len, int nseg)</I>, open a new segment structure.
|
|
|
<P>
|
|
|
A new file with full path name <B>fname</B> will be created and
|
|
@@ -94,8 +94,8 @@ This can be done with the <I>Segment Library</I> routine:
|
|
|
<B>nrows</B> and <B>ncols</B>. The segments consist of <B>srows</B> by
|
|
|
<B>scols</B>. The data items have length <B>len</B> bytes. The number
|
|
|
of segments to be retained in memory is given by <B>nseg</B>. This
|
|
|
- routine calls segment_format() and segment_init(), see below. If
|
|
|
- segment_open() is used, the routines segment_format() and segment_init()
|
|
|
+ routine calls Segment_format() and Segment_init(), see below. If
|
|
|
+ Segment_open() is used, the routines Segment_format() and Segment_init()
|
|
|
must not be used.
|
|
|
<P>
|
|
|
Return codes are: 1 ok; else a negative number between -1 and -6 encoding
|
|
@@ -106,7 +106,7 @@ Alternatively, the first step is to create a file which is properly
|
|
|
formatted for use by the <I>Segment Library</I> routines:
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_format (int fd, int nrows, off_t ncols,off_t srows, int scols,
|
|
|
+<I>int Segment_format (int fd, int nrows, off_t ncols,off_t srows, int scols,
|
|
|
int len)</I>, format a segment file
|
|
|
<P>
|
|
|
The segmentation routines require a disk file to be used for paging
|
|
@@ -130,17 +130,17 @@ Return codes are: 1 ok; else -1 could not seek or write <I>fd</I>, or -3
|
|
|
|
|
|
<P>
|
|
|
The next step is to initialize a SEGMENT structure to be associated with a
|
|
|
-segment file formatted by segment_format().
|
|
|
+segment file formatted by Segment_format().
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_init (SEGMENT *seg, int fd, int nsegs)</I>, initialize segment
|
|
|
+<I>int Segment_init (SEGMENT *seg, int fd, int nsegs)</I>, initialize segment
|
|
|
structure
|
|
|
<P>
|
|
|
Initializes the <B>seg</B> structure. The file on <B>fd</B> is
|
|
|
- a segment file created by segment_format() and must be open for
|
|
|
+ a segment file created by Segment_format() and must be open for
|
|
|
reading and writing. The segment file configuration parameters <I>nrows,
|
|
|
ncols, srows, scols</I>, and <I>len</I>, as written to the file by
|
|
|
- <I>segment_format</I>, are read from the file and stored in the
|
|
|
+ <I>Segment_format</I>, are read from the file and stored in the
|
|
|
<B>seg</B> structure. <B>Nsegs</B> specifies the number of segments that
|
|
|
will be retained in memory. The minimum value allowed is 1.
|
|
|
|
|
@@ -154,12 +154,12 @@ Return codes are: 1 if ok; else -1 could not seek or read segment file, or -2
|
|
|
Then data can be written from another file to the segment file row by row:
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_put_row (SEGMENT *seg, char *buf, int row)</I>, write row to
|
|
|
+<I>int Segment_put_row (SEGMENT *seg, char *buf, int row)</I>, write row to
|
|
|
segment file
|
|
|
<P>
|
|
|
Transfers nonsegmented matrix data, row by row, into a segment
|
|
|
file. <B>Seg</B> is the segment structure that was configured from a call
|
|
|
- to segment_init(). <B>Buf</B> should contain <I>ncols*len</I>
|
|
|
+ to Segment_init(). <B>Buf</B> should contain <I>ncols*len</I>
|
|
|
bytes of data to be transferred to the segment file. <B>Row</B> specifies
|
|
|
the row from the data matrix being transferred.
|
|
|
|
|
@@ -170,7 +170,7 @@ Return codes are: 1 if ok; else -1 could not seek or write segment file.
|
|
|
Then data can be read or written to the segment file randomly:
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_get (SEGMENT *seg, char *value, int row, int col)</I>, get value
|
|
|
+<I>int Segment_get (SEGMENT *seg, char *value, int row, int col)</I>, get value
|
|
|
from segment file
|
|
|
<P>
|
|
|
Provides random read access to the segmented data. It gets
|
|
@@ -182,7 +182,7 @@ Then data can be read or written to the segment file randomly:
|
|
|
Return codes are: 1 if ok; else -1 could not seek or read segment file.
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_put (SEGMENT *seg, char *value, int row, int col)</I>, put
|
|
|
+<I>int Segment_put (SEGMENT *seg, char *value, int row, int col)</I>, put
|
|
|
value to segment file
|
|
|
<P>
|
|
|
Provides random write access to the segmented data. It
|
|
@@ -202,24 +202,24 @@ After random reading and writing is finished, the pending updates must be
|
|
|
flushed to disk:
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_flush (SEGMENT *seg)</I>, flush pending updates to disk
|
|
|
+<I>int Segment_flush (SEGMENT *seg)</I>, flush pending updates to disk
|
|
|
<P>
|
|
|
- Forces all pending updates generated by segment_put() to be
|
|
|
+ Forces all pending updates generated by Segment_put() to be
|
|
|
written to the segment file <B>seg.</B> Must be called after the final
|
|
|
- segment_put() to force all pending updates to disk. Must also be called
|
|
|
- before the first call to segment_get_row().
|
|
|
+ Segment_put() to force all pending updates to disk. Must also be called
|
|
|
+ before the first call to Segment_get_row().
|
|
|
|
|
|
<P>
|
|
|
Now the data in segment file can be read row by row and transferred to a normal
|
|
|
sequential data file:
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_get_row (SEGMENT *seg, char *buf, int row)</I>, read row from
|
|
|
+<I>int Segment_get_row (SEGMENT *seg, char *buf, int row)</I>, read row from
|
|
|
segment file
|
|
|
<P>
|
|
|
Transfers data from a segment file, row by row, into memory
|
|
|
(which can then be written to a regular matrix file) . <B>Seg</B> is the
|
|
|
- segment structure that was configured from a call to segment_init().
|
|
|
+ segment structure that was configured from a call to Segment_init().
|
|
|
<B>Buf</B> will be filled with <I>ncols*len</I> bytes of data
|
|
|
corresponding to the <B>row</B> in the data matrix.
|
|
|
|
|
@@ -230,11 +230,11 @@ Return codes are: 1 if ok; else -1 could not seek or read segment file.
|
|
|
Finally, memory allocated in the SEGMENT structure is freed:
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_release (SEGMENT *seg)</I>, free allocated memory
|
|
|
+<I>int Segment_release (SEGMENT *seg)</I>, free allocated memory
|
|
|
<P>
|
|
|
Releases the allocated memory associated with the segment file
|
|
|
<B>seg.</B> Does not close the file. Does not flush the data which may
|
|
|
- be pending from previous segment_put() calls.
|
|
|
+ be pending from previous Segment_put() calls.
|
|
|
|
|
|
<P>
|
|
|
|
|
@@ -242,9 +242,9 @@ The following routine both deletes the segment file and releases allocated
|
|
|
memory:
|
|
|
|
|
|
<P>
|
|
|
-<I>int segment_close (SEGMENT *seg)</I>, close segment structure
|
|
|
+<I>int Segment_close (SEGMENT *seg)</I>, close segment structure
|
|
|
<P>
|
|
|
- Deletes the segment file and uses segment_release() to release the
|
|
|
+ Deletes the segment file and uses Segment_release() to release the
|
|
|
allocated memory. No further cleaing up is required.
|
|
|
|
|
|
<P>
|
|
@@ -260,7 +260,7 @@ at once:
|
|
|
\code
|
|
|
SEGMENT seg;
|
|
|
|
|
|
-segment_open (&seg, G_tempfile(), nrows, ncols, srows, scols, sizeof(int), nseg);
|
|
|
+Segment_open (&seg, G_tempfile(), nrows, ncols, srows, scols, sizeof(int), nseg);
|
|
|
\endcode
|
|
|
|
|
|
Alternatively, the first step is the creation and formatting of a segment
|
|
@@ -270,7 +270,7 @@ file. A file is created, formatted and then closed:
|
|
|
\code
|
|
|
fd = creat (file, 0666);
|
|
|
|
|
|
-segment_format (fd, nrows, ncols, srows, scols, sizeof(int));
|
|
|
+Segment_format (fd, nrows, ncols, srows, scols, sizeof(int));
|
|
|
|
|
|
close(fd);
|
|
|
\endcode
|
|
@@ -286,7 +286,7 @@ file format. The segment file is reopened for read and write and initialized:
|
|
|
SEGMENT seg;
|
|
|
|
|
|
fd = open (file, O_RDWR);
|
|
|
-segment_init (&seg, fd, nseg);
|
|
|
+Segment_init (&seg, fd, nseg);
|
|
|
\endcode
|
|
|
|
|
|
<P>
|
|
@@ -299,7 +299,7 @@ for (row = 0; row < nrows; row++)
|
|
|
{
|
|
|
// code to get original matrix data for row into buf
|
|
|
|
|
|
- segment_put_row (&seg, buf, row);
|
|
|
+ Segment_put_row (&seg, buf, row);
|
|
|
}
|
|
|
\endcode
|
|
|
|
|
@@ -307,11 +307,11 @@ for (row = 0; row < nrows; row++)
|
|
|
<P>
|
|
|
Of course if the intention is only to add new values rather than update existing
|
|
|
values, the step which transfers data from the original matrix to the segment
|
|
|
-file, using segment_put_row(), could be omitted, since
|
|
|
-segment_format() will fill the segment file with zeros.
|
|
|
+file, using Segment_put_row(), could be omitted, since
|
|
|
+Segment_format() will fill the segment file with zeros.
|
|
|
|
|
|
<P>
|
|
|
-The data can now be accessed directly using segment_get(). For example,
|
|
|
+The data can now be accessed directly using Segment_get(). For example,
|
|
|
to get the value at a given row and column:
|
|
|
|
|
|
\code
|
|
@@ -319,11 +319,11 @@ int value;
|
|
|
|
|
|
SEGMENT seg;
|
|
|
|
|
|
-segment_get (&seg, &value, row, col);
|
|
|
+Segment_get (&seg, &value, row, col);
|
|
|
\endcode
|
|
|
|
|
|
<P>
|
|
|
-Similarly segment_put() can be used to change data values in the
|
|
|
+Similarly Segment_put() can be used to change data values in the
|
|
|
segment file:
|
|
|
|
|
|
|
|
@@ -334,16 +334,16 @@ SEGMENT seg;
|
|
|
|
|
|
value = 10;
|
|
|
|
|
|
-segment_put (&seg, &value, row, col);
|
|
|
+Segment_put (&seg, &value, row, col);
|
|
|
\endcode
|
|
|
|
|
|
|
|
|
\warning It is an easy mistake to pass a value directly to
|
|
|
-segment_put(). The following should be avoided:
|
|
|
+Segment_put(). The following should be avoided:
|
|
|
|
|
|
|
|
|
\code
|
|
|
-segment_put (&seg, 10, row, col); // this will not work
|
|
|
+Segment_put (&seg, 10, row, col); // this will not work
|
|
|
\endcode
|
|
|
|
|
|
<P>
|
|
@@ -353,11 +353,11 @@ follows:
|
|
|
|
|
|
|
|
|
\code
|
|
|
-segment_flush (&seg);
|
|
|
+Segment_flush (&seg);
|
|
|
|
|
|
for (row = 0; row < nrows; row++)
|
|
|
{
|
|
|
- segment_get_row (&seg, buf, row);
|
|
|
+ Segment_get_row (&seg, buf, row);
|
|
|
|
|
|
// code to put buf into a matrix data file for row
|
|
|
}
|
|
@@ -369,7 +369,7 @@ released and the file closed:
|
|
|
|
|
|
|
|
|
\code
|
|
|
-segment_release (&seg);
|
|
|
+Segment_release (&seg);
|
|
|
|
|
|
close (fd);
|
|
|
\endcode
|