The tools have been divided into two levels.  For the most part, the application should only call tools in the upper level.  The lower level tools do not perform complete tasks, but are only intended to be called by the upper level tools.

When using the various library functions (other than SGL_CreateLibrary) SGL_UseLibrary should be called first.  Then other function calls may then be made to access and manipulate the database.  When access is complete, a call must be made to SGL_TermLibUse.

3.1 SGL Database Structure

The database header structure defines most of the data in the actual library header.  Lengths of fields have not been included in the structure as they can be easily calculated.  There is only one header for each library.  The SGL_Header structure follows:

char version[3]; library version number
char security_classification; header classification
char *codeword; header codeword
char *library_name; comments on library name
long number_of_records; number of records in library
char *comments; header comments
long extended_data_length; length in bytes of extended data
char *extended_data; extended data

Currently, the version field should contain "001", the current version of SGL.  Available security classifications include (U)nclassified, (C)onfidential, (S)ecret, (T)op secret, and (R)estricted.  (These correspond to the equivalent field in NITF.)  The codeword field is fixed size at P_SGLHCODE_SIZE ASCII characters, plus null-terminator.  (It also corresponds to an NITF field.)

The library_name and comments fields are ASCII strings, and their lengths are determined by null terminators.  Library_Name is required, and is limited to P_SGLHNAME_MAX characters.  Comments may contain multiple lines (separated by newline characters, '\n'), and are limited to P_SGLHCLEN_MAX characters.  The extended data field is non-ASCII, and its length is specified by the previous field, limited to P_SGLHUDDL_MAX bytes.

The information for each symbol is not stored in memory but is read as required.  The SGL_Record structure follows:

char *record_name; record name (symbol name)
char record_type[3]; type of data
char security_classification; record classification
char *codeword; record codeword
char deletion_flag; set if record is considered deleted
char *comments; record comments
long extended_data_length; length in bytes of extended data
char *extended_data; extended data
long record_data_length; length in bytes of record data
char *record_data; record data

The record_name and comments fields are ASCII strings, and their lengths are determined by null terminators.  Record_name is required, and is limited to P_SGLSNAMELEN_ MAX characters.  Comments may contain multiple lines (separated by newline characters, '\n'), and are limited to P_SGLSCLEN_MAX characters.

Available security classifications include (U)nclassified, (C)onfidential, (S)ecret, (T)op secret, and (R)estricted.  (These correspond to the equivalent field in NITF.)  The codeword field is fixed size at P_SGLSCODE_SIZE ASCII characters, plus null-terminator.  (It also corresponds to an NITF field.)  The extended data and record data fields are non-ASCII, and their lengths are specified by their preceding fields, limited to P_SGLSUDDL_MAX and P_SGLSCGMLEN_MAX bytes respectively.

3.2 SGL Index Structure

The index file is used to quickly access the records in the database file.  Each database file has its own index file associated with it.  The information in the index file is a header followed by information for each record in the database file.  The existence of the index file, and the associated structures, will likely be transparent to the application.

The information in the index file is stored in ASCII and converted to numeric values.  There is only one index header per index file.  As entries are added to the database file (via the high-level tools) the index file structure is adjusted so that the records are quickly locatable, and easily retrievable in ascending order.  The index file entries arranged in a tree structure (a 2-3 tree).  The SGL_IndexHeader structure follows:

long number_of_records; number of records in database file
long root_record; index number for root record of tree

Each record in the database file also has a record in the index file.  The related records pointers as well as the byte offset are stored as ASCII in the file, and converted to numeric values when stored in the structure.  The byte offset value is the number of bytes from the beginning of the database file to the beginning of the symbol data.  The SGL_IndexRecord structure follows:

char record_name[P_SGLSNAM_SIZE+1];
record name
long parent_record; pointer to parent record (moving towards the root)
long sibling_record; pointer to sibling record, if any, at the current tree level
long left_child_record; pointer to top node of sub-tree less than the current record
long right_child_record; pointer to top node of sub-tree greater than the current record
long record_offset; byte offset from beginning of the database file
long this_record_index; index of the current record (This is not stored in the database, but has been put in the structure for convenience.)

Note that the index file is a sophisticated structure.  In the future this structure could be modified to support a different structure, for better efficiency, without impacting the Database structure itself.  It is therefore encouraged that application code avoid referring to the index structures, or calling the index specific tools, (all in the middle and lower levels,) as these interfaces are at risk of changing.

3.3 SGL File Pointer Structure

The file pointer structure is the entity passed to all toolkit calls in the same library access session, for the same library.  It consists of file pointers for the database and index files, the current library name in use, and an index used for searching for multiple records.  The SGL_FilePtrs structure follows:

FILE *database_file_ptr; pointer for database file
FILE *index_file_ptr; pointer for index file
char *lib_file_name; current library file name without path or extension.
long last_record_index; last record index accessed in search

In general, an application will declare a pointer to this structure, to be allocated by SGL_UseLibrary, but will not directly access any of the individual fields, save possibly the lib_file_name.

4. SGL Toolkit Functions

The SGL Toolkit contains the following source files, which will be described in later sections:

sgladirc.c
sgladrec.c
sglcrlib.c
sglcrtix.c
sgldlrec.c
sgldmpdb.c
sglexist.c
sglfndrc.c
sglfrhdr.c
sglfrrec.c
sglixoff.c
sgllog.c
sglpath.c
sglpklib.c
sglpos.c
sglrbyna.c
sglrbynu.c
sglrdhdr.c
sglrdihd.c
sglrdirc.c
sglrdrec.c
sglrthdr.c
sglrtrec.c
sglsrch.c
sgltrmus.c
sgltrvrs.c
sglundel.c
sgluphdr.c
sgluprec.c
sgluselb.c
sglwrhdr.c
sglwrihd.c
sglwrirc.c
sglwrrec.c

The SGL Toolkit contains the following source include files,:

sglproto.h Contains all the function prototypes.

sglparams.h Contains all the parameter constants and error codes.

sglstruc.h Contains all the structure definitions.

SGL_BuildFullPathName sglpath.c Construct full path name from file name and file type

SGL_CreateLibrary sglcrlib.c Create the database and index file given the database header

SGL_DeleteRecord sgldlrec.c Marks the record as deleted in the database file

SGL_DumpDataBase sgldmpdb.c Write all database record information to an ascii output file

SGL_FindNextRecordByName sglfndrc.c Finds the first/next record in the database that matches a given pattern, and a given deletion flag

SGL_FreeHeader sglfrhdr.c Deallocates (frees) memory allocated for the SGL_Header structure

SGL_FreeRecord sglfrrec.c Deallocates (frees) memory allocated for the SGL_Record structure

SGL_PackLibrary sglpklib.c Rebuilds the database file in sorted order by record name.  All records marked for deletion are deleted.

SGL_RetrieveHeader sglrthdr.c Retrieves the database header

SGL_RetrieveRecord sglrtrec.c Retrieves a record not marked as deleted from the database file by record name

SGL_TermLibUse sgltrmus.c Closes database and index files and frees the file pointer structure

SGL_UndeleteRecord sglundel.c Re-activates a record that has been marked for deletion.

SGL_UpdateHeader sgluphdr.c Updates the database and index file with a new database header.  This takes a long time as it entails rebuilding the database.  All records marked for deletion are deleted.

SGL_UpdateRecord sgluprec.c Updates an existing record in the database file.  The old record, if present, will be marked for deletion, and the new one will be added to the end of the file.  If no old record exists, this is not an error and the new record is simply added.

SGL_UseLibrary sgluselb.c Given a library name, opens database and index files and returns the file pointer structure for use in function calls

4.1.1. SGL_BuildFullPathName Function

The SGL_BuildFullPathName function constructs the full path name from the path name, file name and file type.

Function Prototype in:

#include "sglproto.h"

void SGL_BuildFullPathName( char *filename,
char *type,
char *path )

Input Arguments:

filename Filename (without file type and path)
type File type (i.e. SGL, SIX, TMP etc.)

Output Arguments:

path Full file name with path, filename and file type

Returns:

None

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

char filename[P_SGLSNAM_SIZE+1];
char type[3];
char path[P_SGLFULLLIBNAME_MAX];

status = SGL_BuildFullPathName( filename, type, path );

4.1.2. SGL_CreateLibrary Function

The SGL_CreateLibrary function creates the database and index file.

Function Prototype in:

#include "sglproto.h"

short SGL_CreateLibrary( char *library_name,
SGL_Header *sgl_header )

Input Arguments:

library_name name of database file (without path and file type).
sgl_header database header to be written to the new database file.

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM Invalid passed argument or structure field
P_SGL_FILEERROR Error on open
P_SGL_MALLOC_ERROR Error allocating memory for file pointer structure or database file name

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
char library_name[P_SGLSNAM_SIZE+1];
SGL_Header *sgl_header;

status = SGL_CreateLibrary( library_name, sgl_header );

4.1.3. SGL_DeleteRecord Function

The SGL_DeleteRecord function deletes a record from the database file.

Function Prototype in:

#include "sglproto.h"

short int SGL_DeleteRecord ( SGL_FilePtrs *library_ptr,
char *record_name )

Input Arguments:

library_ptr file pointer structure (contains database and index file pointers)
record_name record name to delete

Output Arguments:

None

Returns:

P_SGL_SUCCESS Function completed successfully
P_SGL_FILE_PTR_NULL File pointer is NULL
P_SGL_NOTFOUND Search record not found in database
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning database file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
char record_name[P_SGLSNAM_SIZE+1];
SGL_FilePtrs *file_ptr;

status = SGL_DeleteRecord( file_ptr, record_name );

4.1.4. SGL_DumpDataBase Function

The SGL_DumpDataBase function writes all the database records to an output file.

Function Prototype in:

#include "sglproto.h"

short SGL_DumpDataBase( SGL_FilePtrs *library_ptr,
char *output_file )

Input Arguments:

library_ptr Database and index file pointers
output_file Output file name without path or extension

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM Bad byte data offset value
P_SGL_FILEERROR Error opening index file
P_SGL_FILE_PTR_NULL Error reading database file header
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning file
P_SGL_WRITE_ERROR fwrite error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
SGL_FilePtrs *library_ptr
char output_file[P_SGLLIBFULLNAME_MAX+1];

status = SGL_DumpDataBase( library_ptr, output_file );

4.1.5. SGL_FindNextRecordByName Function

The SGL_FindNextRecordByName function finds the next record in the database that matches a given pattern.  It can find only deleted records or only active records or both.  At no time will it ever match any but the most recent version of a given record.

Function Prototype in:

#include "sglproto.h"

short SGL_FindNextRecordByName( SGL_FilePtrs *library_ptr,
short new_search,
char[3] record_type_mask,
char *record_mask,
char del_flag,
char *name_found )

Input Arguments:

library_ptr database and index file pointers
new_search set to TRUE the first time the function is called for a given pattern search thereafter it is set to FALSE
record_type_mask 3 character record type to search for.  Any position containing '*' is wild-carded
record_mask pattern (with wild cards) to search for.  Allowed strings
include: *, STRING, STRING*, and *STRING
del_flag What value to match in the delete flag; acceptable values are 'N', 'Y', or 'L' for both (latest)

Output Arguments:

name_found search pattern found

Returns:

P_SGL_SUCCESS Function completed successfully
P_SGL_BADPARAM New search should be TRUE for a new pattern search or FALSE for a continuing pattern search - this was not the case.  An invalid or bad data offset values was passed to SGL_PositionFile.
P_SGL_NOTFOUND For first call, no record found matching specification
P_SGL_EOF For subsequent calls, no more records found matching specification
P_SGL_FILE_PTR_NULL Database or index file pointer is NULL
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

SGL_FilePtrs *file_ptr;
char record_type_mask[3];
short new_search;
char record_mask[P_SGLSNAM_SIZE+1];
char name_found[P_SGLSNAM_SIZE+1];
short status;

status = SGL_FindNextRecordByName( file_ptr,
new_search,
record_type_mask,
record_mask,
P_SGL_FIND_DELETED_RECORDS,
name_found );

4.1.6. SGL_FreeHeader Function

The SGL_FreeHeader function frees the SGL_Header structure.

Function Prototype in:

#include "sglproto.h"

void SGL_FreeHeader( SGL_Header **header )

Input Arguments:

header Pointer to database file header structure

Output Arguments:

header Pointer is nullified on return.

Returns:

None

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

SGL_Header *header = NULL;

SGL_FreeHeader( &header );

4.1.7. SGL_FreeRecord Function

The SGL_FreeRecord function frees the SGL_Record structure.

Function Prototype in:

#include "sglproto.h"

void SGL_FreeRecord SGL_Record **rec )

Input Arguments:

rec Pointer to database file record structure

Output Arguments:

rec Pointer is nullified on return.

Returns:

None

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

SGL_Record *rec = NULL;

SGL_FreeRecord( &rec );

4.1.8. SGL_PackLibrary Function

The SGL_PackLibrary function rebuilds the database file in sorted order by record name.  All records marked as deleted are truly deleted.

Function Prototype in:

#include "sglproto.h"

short SGL_PackLibrary( SGL_FilePtrs **library_ptr )

Input Arguments:

library_ptrs Database and index file pointers

Output Arguments:

None

Returns:

P_SGL_SUCCESS Function completed successfully
P_SGL_FILE_PTR_NULL Database and index file pointers cannot be NULL
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR File positioning error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
SGL_FilePtrs *library_ptr;

status = SGL_PackLibrary( &library_ptr );

4.1.9. SGL_RetrieveHeader Function

The SGL_RetrieveHeader function retrieves the database header.

Function Prototype in:

#include "sglproto.h"

SGL_Header *SGL_RetrieveHeader( SGL_FilePtrs *library_ptr )

Input Arguments:

library_ptr Database and index file pointers

Output Arguments:

(See Returns)

Returns:

SGL_Header if success or NULL if unsuccessful

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

SGL_FilePtrs *file_ptr;
SGL_Header *database_header;

database_header = SGL_RetrieveHeader( file_ptr );

4.1.10. SGL_RetrieveRecord Function

The SGL_RetrieveRecord function retrieves a database Record.

Function Prototype in:

#include "sglproto.h"

SGL_Record *SGL_RetrieveRecord( SGL_FilePtrs *library_ptr ,
char record_name )

Input Arguments:

library_ptr Database and index file pointers
record_name Database record to retrieve

Output Arguments:

(See Returns)

Returns:

SGL_Record if success or NULL if unsuccessful

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

SGL_FilePtrs *file_ptr;
SGL_Record *database_record;
char record_name[P_SGLSNAM_SIZE+1];

database_record = SGL_RetrieveRecord( file_ptr, record_name );

4.1.11. SGL_TermLibUse Function

The SGL_TermLibUse function closes the database and index files and frees the file pointer structure, nullifying it.

Function Prototype in:

#include "sglproto.h"

short int SGL_TermLibUse ( SGL_FilePtrs **library_ptr )

Input Arguments:

library_ptr file pointer structure

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILE_PTR_NULL Input file pointers were NULL

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
SGL_Fileptrs *file_ptr;

status = SGL_TermLibUse( &file_ptr );

4.1.12. SGL_UndeleteRecord Function

The SGL_UndeleteRecord function reactivates a record from the database file that has been marked for deletion.

Function Prototype in:

#include "sglproto.h"

short int SGL_UndeleteRecord ( SGL_FilePtrs *library_ptr,
char *record_name )

Input Arguments:

library_ptr file pointer structure (contains database and index file pointers)
record_name record name to undelete

Output Arguments:

None

Returns:

P_SGL_SUCCESS Function completed successfully
P_SGL_FILE_PTR_NULL File pointer is NULL
P_SGL_NOTFOUND Search record not found in database, or found but already active
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning database file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
char record_name[P_SGLSNAM_SIZE+1];
SGL_FilePtrs *file_ptr;

status = SGL_UndeleteRecord( file_ptr, record_name );

4.1.13. SGL_UpdateHeader Function

The SGL_UpdateHeader function updates the database and index files with a new database header.  This entails rewriting the database and index.

Function Prototype in:

#include "sglproto.h"

short SGL_UpdateHeader ( SGL_FilePtrs **library_ptr ,
SGL_Header *database_header )

Input Arguments:

library_ptr Database and index file pointer structure
database_header New database header

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM Invalid passed argument or structure field
P_SGL_FILEERROR Error opening files
P_SGL_FILE_PTR_NULL Input file pointers were NULL
P_SGL_MALLOC_ERROR Error allocating memory
P_SGL_READ_ERROR fread error
P_SGL_WRITE_ERROR fwrite error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
SGL_FilePtrs *file_ptr;
SGL_Header *database_header

status = SGL_UpdateHeader( &file_ptr, database_header );

4.1.14. SGL_UpdateRecord Function

The SGL_UpdateRecord function updates the database and index files with a new database record.  If a record with the same name already exists, the new record will replace it.

Function Prototype in:

#include "sglproto.h"

short SGL_UpdateRecord ( SGL_FilePtrs *library_ptr ,
SGL_Record *database_record )

Input Arguments:

library_ptr Database and index file pointer structure
database_record New or updated database record

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM Database record name cannot have a "*" in it this is reserved for a wild card token or bad byte data offset value
P_SGL_FTELL_ERROR File position error
P_SGL_NOTFOUND Could not find a given record name in the database file
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR File positioning error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
SGL_FilePtrs *file_ptr;
SGL_Record *database_record;

status = SGL_UpdateRecord( file_ptr, database_record );

4.1.15. SGL_UseLibrary Function

The SGL_UseLibrary function opens an existing database and index file and assigns the file pointers to the file pointer structure.

Function Prototype in:

#include "sglproto.h"

SGL_FilePtrs *SGL_UseLibrary( char *library_name )

Input Arguments:

library_name name of database file (without path and file type)

Output Arguments:

(See Returns)

Returns:

SGL_FilePtrs if success or NULL if unsuccessful

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

char library_name[P_SGLSNAM_SIZE+1];
SGL_FilePtr *file_ptr;

file_ptr = SGL_UseLibrary( library_name );

SGL_AddIndexRecord sgladirc.c Add an index record to the index file

SGL_AddRecord sgladrec.c Add a record to the database file

SGL_CreateIndexFile sglcrtix.c Create an index file from the database file and generate index records based on existing database records

SGL_DoesFileExist sglexist.c Check to see if a given file, by path, exists
SGL_IndexOffset sglixoff.c For a given index record calculates the byte offset from the beginning of the index file

SGL_LogMessage sgllog.c Writes a date stamped message of type status, warning, or error, to the SGL.log file.

SGL_PositionFile sglpos.c Positions the file at the given byte offset, or the beginning or end of the file

SGL_ReadHeader sglrdhdr.c Allocates and reads the SGL_Header structure (which is the database header)

SGL_ReadIndexHeader sglrdihd.c Reads the SGL_IndexHeader structure from the index file

SGL_ReadIndexRecord sglrdirc.c Read the SGL_IndexRecord structure from the index file

SGL_ReadIndexRecordByName Read an index file record given its record
sglrbyna.c name

SGL_ReadIndexRecordByNumber Read an index file record given its record
sglrbynu.c number

SGL_ReadRecord sglrdrec.c Allocates and reads the SGL_Record structure

SGL_SearchByName sglsrch.c Search the index file structure for the first record whose name begins with a specified string.

SGL_TraverseIndex sgltrvrs.c Given an index record originally returned from SGL_SearchByName, traverse to the index record which alphabetically succeeds it.
SGL_WriteHeader sglwrhdr.c Writes the SGL_Header structure at the beginning of the database file

SGL_WriteIndexHeader sglwrihd.c Writes the SGL_IndexHeader structure to the index file

SGL_WriteIndexRecord sglwrirc.c Writes the SGL_IndexRecord structure to the index file

SGL_WriteRecord sglwrrec.c Writes the SGL_Record structure to the database file

4.2.1. SGL_AddIndexRecord Function

The SGL_AddIndexRecord function adds an index record to the index file.  It determines its proper position in the tree, and places it there, updating other tree nodes to properly point to it.

Function Prototype in:

#include "sglproto.h"

short SGL_AddIndexRecord( FILE *index_file,
SGL_IndexRecord add_record )

Input Arguments:

index_file Index file pointer
add_record Index record to write to the index file

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM Bad data offset value or index record number
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning index file
P_SGL_WRITE_ERROR fwrite error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *index_file;
SGL_IndexRecord add_record;

status = SGL_AddIndexRecord( index_file, add_record );

4.2.2. SGL_AddRecord Function

The SGL_AddRecord function writes the SGL_Record structure to the database file.

Function Prototype in:

#include "sglproto.h"

short SGL_AddRecord( FILE *database_file,
SGL_Record *add_record )

Input Arguments:

database_file Database file pointer
add_record Database record to write (add) to the database file

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILEERROR Error positioning the database file
P_SGL_WRITE_ERROR fwrite error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *database_file;
SGL_Record *add_record;

status = SGL_AddRecord( database_file, add_record );

4.2.3. SGL_CreateIndexFile Function

The SGL_CreateIndexFile function creates an index file from the database file.

Function Prototype in:

#include "sglproto.h"

short SGL_CreateIndexFile( FILE *database_file_ptr,
char *lib_file_name );

Input Arguments:

database_file_ptr Database file pointer
lib_file_name Name of the library file

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILEERROR Error opening index file
P_SGL_FILE_PTR_NULL Error reading database file header
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning index file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *database_file_ptr;
char lib_file_name[P_SGLLIBFILENAME_MAX+1];

status = SGL_CreateIndexFile( database_file_ptr, lib_file_name );

4.2.4. SGL_DoesFileExist Function

The SGL_DoesFileExist function checks if a given file exists by opening the file.

Function Prototype in:

#include "sglproto.h"

short SGL_DoesFileExist( char *file_name )

Input Arguments:

file_name Filename of file to check if it exists

Output Arguments:

None

Returns:

P_SGL_SUCCESS The file exists (could be opened)
P_SGL_LIBNOEXIST The file does not exist (could not be opened)

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
char file_name[P_SGLLIBFULLNAME_MAX+1];

status = SGL_DoesFileExist( file_name );

4.2.5. SGL_IndexOffSet Function

The SGL_IndexOffSet function calculates the byte offset from the beginning of the index file for a given record.

Function Prototype in:

#include "sglproto.h"

short SGL_IndexOffSet( long record_number, long *byte_offset )

Input Arguments:

record_number Index record number to read

Output Arguments:

byte_offset Byte offset of index record number

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM record_number is <= 0

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
long record_number;
long byte_offset

status = SGL_IndexOffSet( record_number, &byte_offset );

4.2.6. SGL_LogMessage Function

The SGL_LogMessage function writes a status, warning or error message to the file SGL.log in the current directory.

Function Prototype in:

#include "sglproto.h"

short SGL_LogMessage( short message_type, char *routine_name, char *message)

Input Arguments:

message_type Severity of message being logged.  Values are P_STATUS, P_WARNING, P_ERROR.
routine_name SGL routine reporting the error.
message Text of the message being logged.

Output Arguments:

NONE

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILEERROR Could not open log file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

#define THISROUTINE "SGL_ThisRoutineName"
short status;
char message[133];

sprintf(message, "This is an error message");
status = SGL_LogMessage(P_ERROR, THISROUTINE, message);

4.2.7. SGL_PositionFile Function

The SGL_PositionFile function positions the file at the given byte offset.

Function Prototype in:

#include "sglproto.h"

short SGL_PositionFile( FILE *file_pointer, long position )

Input Arguments:

file_pointer File pointer for file to position
position Absolute byte offset in file.  Alternately you may use SGL_BOF (beginning of file) or SGL_EOF (end of file).

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILE_PTR_NULL No file pointer was passed to the routine
P_SGL_BADPARAM Bad byte offset value
P_SGL_SEEK_ERROR Error positioning file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *file_ptr;
long position;

status = SGL_PositionFile( file_ptr, position );

status = SGL_PositionFile( file_ptr, SGL_BOF );

status = SGL_PositionFile( file_ptr, SGL_EOF );

4.2.8. SGL_ReadHeader Function

The SGL_ReadHeader function allocates and reads the SGL_Header structure (which is the database header).

Function Prototype in:

#include "sglproto.h"

SGL_Header *SGL_ReadHeader( FILE *database_file, long *header_length )

Input Arguments:

database_file Database file pointer

Output Arguments:

header_length Length of database header

Returns:

SGL_Header structure if successful or NULL if unsuccessful

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

SGL_Header *database_header;
FILE *database_file;
long header_length;

database_header = SGL_ReadHeader( database_file, &header_length );

4.2.9. SGL_ReadIndexHeader Function

The SGL_ReadIndexHeader function reads the SGL_IndexHeader structure from the index file.

Function Prototype in:

#include "sglproto.h"

short SGL_ReadIndexHeader( FILE *index_file,
SGL_IndexHeader *read_record )

Input Arguments:

index_file Index file pointer

Output Arguments:

read_record Index header read from the index file

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM Bad byte data offset value
P_SGL_FILE_PTR_NULL Index file pointer cannot be NULL
P_SGL_SEEK_ERROR Error positioning index file
P_SGL_READ_ERROR fread error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *index_file;
SGL_IndexHeader read_record;

status = SGL_ReadIndexHeader( index_file, &read_record );

4.2.10. SGL_ReadIndexRecord Function

The SGL_ReadIndexRecord function reads the SGL_IndexRecord structure from the index file.

Function Prototype in:

#include "sglproto.h"

short SGL_ReadIndexRecord( FILE *index_file,
SGL_IndexRecord *read_record )

Input Arguments:

index_file Index file pointer

Output Arguments:

read_record Index record read from the index file

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILE_PTR_NULL Index file pointer cannot be NULL
P_SGL_READ_ERROR fread error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *index_file;
SGL_IndexRecord read_record;

status = SGL_ReadIndexRecord( index_file, &read_record );

4.2.11. SGL_ReadIndexRecordByName Function

The SGL_ReadIndexRecordByName function reads an index record by record name.  t can verify that the record being read is not deleted, or that it is deleted.

Function Prototype in:

#include "sglproto.h"

short SGL_ReadIndexRecordByName( SGL_FilePtrs *file_ptr,
char *record_name,
char del_flag,
SGL_IndexRecord *read_record );

Input Arguments:

file_ptr Database and index file pointers
record_name Record name to read record from index file
del_flag What value to expect in the delete flag; acceptable values are 'N', 'Y', or 'L' for either (latest)

Output Arguments:

read_record Record read from index file

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM Bad byte data offset value
P_SGL_FILE_PTR_NULL Database and index file pointers cannot be NULL
P_SGL_NOTFOUND Record name not found in database file, or found with wrong deletion state
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
SGL_FilePtrs *file_ptr;
char record_name[P_SGLSNAMELEN_MAX+1];
SGL_IndexRecord read_record;

status = SGL_ReadIndexRecordByName( file_ptr, record_name,
P_SGL_FIND_NORMAL_RECORDS,
&read_record );

4.2.12. SGL_ReadIndexRecordByNumber Function

The SGL_ReadIndexRecordByNumber function reads an index record by index record number.

Function Prototype in:

#include "sglproto.h"

short SGL_ReadIndexRecordByNumber(FILE *index_file,
long record_number,
SGL_IndexRecord *read_record );

Input Arguments:

index_file Index file pointer
record_number Index record number of record to retrieve from the index file

Output Arguments:

read_record Record read from index file

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_BADPARAM Bad byte data offset value
P_SGL_FILE_PTR_NULL Database and index file pointers cannot be NULL
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
long record_number;
FILE *index_file;
SGL_IndexRecord read_record;

status = SGL_ReadIndexRecordByNumber(
index_file,
record_number,
&read_record );

4.2.13. SGL_ReadRecord Function

The SGL_ReadRecord function allocates and reads the SGL_Record structure from the database file.

Function Prototype in:

#include "sglproto.h"

SGL_Record *SGL_ReadRecord( FILE *database_file,
long *record_length )

Input Arguments:

database_file Pointer to the database file

Output Arguments:

record_length Length in bytes of record read from the database file

Returns:

NULL if error occurred, otherwise SGL_Record structure.

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

FILE *database_file;
long record_length;
SGL_Record *database_record;

database_record = SGL_ReadRecord( database_file, &record_length );

4.2.14. SGL_SearchByName Function

The SGL_SearchByName function reads and returns the first index record, alphabetically, which begins with a specified string.  For an exact match, the string can be the full P_SGLSNAM_SIZE characters long.  To return the first index record in the entire index, the string can be empty.

Function Prototype in:

#include "sglproto.h"

short SGL_SearchByName( FILE *index_file,
char *search_string,
SGL_IndexRecord *found_record );

Input Arguments:

index_file Index file pointer
search_string Beginning of record name to search for

Output Arguments:

found_record Matching record read from index file

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_NOTFOUND No record found matching specified string
P_SGL_FILE_PTR_NULL Database and index file pointers cannot be NULL
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *index_file;
char search_string[];
SGL_IndexRecord found_record;

status = SGL_SearchByName(
index_file,
search_string,
&found_record );

4.2.15. SGL_TraverseIndex Function

The SGL_TraverseIndex function reads and returns the index record which alphabetically succeeds the one passed in.

Function Prototype in:

#include "sglproto.h"

short SGL_TraverseIndex( FILE *index_file,
SGL_IndexRecord *index_record );

Input Arguments:

index_file Index file pointer
index_record Index record structure to be succeeded

Output Arguments:

index_record Resulting record being returned.  Note that whether or not a successor is found, this buffer, also an input parameter, will be overwritten.

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_EOF No more records to traverse.  The one passed in was alphabetically the last.
P_SGL_FILE_PTR_NULL Database and index file pointers cannot be NULL
P_SGL_READ_ERROR fread error
P_SGL_SEEK_ERROR Error positioning file

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
SGL_FilePtrs *index_file;
SGL_IndexRecord read_record;

status = SGL_TraverseIndex(index_file,
&read_record );

4.2.16. SGL_WriteHeader Function

The SGL_WriteHeader function writes the SGL_Header structure at the beginning of the database file.

Function Prototype in:

#include "sglproto.h"

short SGL_WriteHeader( FILE *database_file,
SGL_Header *write_record )

Input Arguments:

database_file Pointer to database file
write_record Database header to be written to the new database file.

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILE_PTR_NULL Database file pointer cannot be NULL
P_SGL_MEM_NOT_ALLOCATED Memory not allocated for write_record
P_SGL_SEEK_ERROR fseek error from SGL_PositionFile
P_SGL_WRITE_ERROR fwrite error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *database_file;
SGL_Header *write_record;

status = SGL_WriteHeader( database_file, write_record );

4.2.17. SGL_WriteIndexHeader Function

The SGL_WriteIndexHeader function writes the SGL_IndexHeader structure to the index file.

Function Prototype in:

#include "sglproto.h"

short SGL_WriteIndexHeader( FILE *index_file,
SGL_IndexHeader *write_record )

Input Arguments:

index_file Index file pointer
write_record Index header to write to index file

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILE_PTR_NULL Index file pointer cannot be NULL
P_SGL_SEEK_ERROR Error positioning index file
P_SGL_WRITE_ERROR fwrite error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *index_file;
SGL_IndexHeader write_record;

status = SGL_WriteIndexHeader( index_file, &write_record );

4.2.18. SGL_WriteIndexRecord Function

The SGL_WriteIndexRecord function writes the SGL_IndexRecord structure to the index file.

Function Prototype in:

#include "sglproto.h"

short SGL_WriteIndexRecord( FILE *index_file,
SGL_IndexRecord *write_record )

Input Arguments:

index_file Index file pointer
write_record Index record to write to index file

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILE_PTR_NULL Index file pointer cannot be NULL
P_SGL_WRITE_ERROR fwrite error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *index_file;
SGL_IndexRecord write_record;

status = SGL_WriteIndexRecord( index_file, &write_record );

4.2.19. SGL_WriteRecord Function

The SGL_WriteRecord function writes the SGL_Record structure to the database file.

Function Prototype in:

#include "sglproto.h"

short SGL_WriteRecord( FILE *database_file,
SGL_Record *write_record )

Input Arguments:

database_file Database file pointer
write_record Database record to write to the database file

Output Arguments:

None

Returns:

P_SGL_SUCCESS The function completed successfully
P_SGL_FILE_PTR_NULL Database file pointer cannot be NULL
P_SGL_WRITE_ERROR fwrite error

Sample Usage:

#include "sglparam.h"
#include "sglproto.h"
#include "sglstruc.h"

short status;
FILE *database_file;
SGL_Record *write_record;

status = SGL_WriteRecord( database_file, write_record);

Appendix A: SGL_TOOL

The purpose of this appendix is to describe SGL_TOOL, a utility that provides a non-graphical interface to the SGL toolkit.  It was written to run specifically on a PC, with limited memory and graphical capabilities.  However, it should run on any other ANSI compliant system.

Compilation and Linkage

A make file is available for generating the SGL library and the SGL_TOOL process.  The library can then be linked with any other application program.

Running the SGL_TOOL

You will first need to set up an environment variable, SGLLIBPATH, to the directory which contains or will contain your SGL database files.  Then run the SGL tool by typing SGL_TOOL.  The following display will then appear.

------------------------------------------------------------ -------------------
| No Current Library File
| No Current Record
------------------------------------------------------------ -------------------
| Commands:
| (C)reate a library
| use (L)ibrary
| (T)erminate library use
| display (H)eader
| (M)odify header
| (V)iew all record names
| (G)et record by name
| get (N)ext record by name
| (A)dd a record
| (U)pdate record
| (D)elete record
| (R)estore (undelete) record
| (P)ack library
| (O)utput library dump
| (Q)uit
------------------------------------------------------------ -------------------
Enter Selection:

The top box contains three lines.  The first specifies which library, if any, is currently opened.  The second specifies which record, if any, was last read and is available for update.  The third line contains a status message pertaining to the most recent operation.  If this line is empty, the most recent operation completed successfully.

The bottom box contains the list of commands available.  To choose a function, type in the specified letter, in lower or upper case.  Note that most of the commands will not be available unless a library has been opened, using use (L)ibrary.  The following is a brief explanation of each command.

(C)reate a library - Prompts for library file name and all library header fields, and then calls SGL_CreateLibrary.  This function can (and probably should) be selected with no library currently active.  It will not open the library, so use (L)ibrary must be called separately.

use (L)ibrary - Prompts for library file name, and then calls SGL_UseLibrary to open the library.  The remainder of the functions may now be selected.

(T)erminate library use - Closes the currently opened library.  Also deallocates any residual structures.  The remainder of the functions are now deactivated.

display (H)eader - Retrieves the header from the currently opened library (using SGL_RetrieveHeader), and displays the contents.

(M)odify header - Retrieves the header from the currently opened library (using SGL_RetrieveHeader), and then prompts for potential new values for all the fields.  Then calls SGL_UpdateHeader to rebuild the database with the modified library header.  Note that any records in the database marked as deleted will be cleaned out at this time.

(V)iew all record names - Prints out the list of record names contained in the currently opened library that match a wildcard specification, and deletion flag.  It does this by repeatedly calling SGL_FindNextRecordByName until no more data is returned.  The deletion flag may be set to 'Y' for deleted, 'N' for not deleted (normal), or 'L' for both (actually latest).

(G)et record by name - Retrieves a record based on the prompted record name which can be a wildcard specification.  It matches the specification using SGL_FindNextRecordByName.  It then calls SGL_RetrieveRecord.  The record fields are then displayed to the screen.  The user then has the option of outputting the record_data contents to an external file.  Subsequently selecting get (N)ext record by name will retrieve and display the next record meeting the wildcard specification.

get (N)ext record by name - Retrieves the next record based on the wildcard specified in a required previous invocation of (G)et record by name.  If another record meets the specification, it will be displayed in the same way as in the previous function.  If no more records meet the specification, such will be indicated.

(A)dd a record - Add a new record to the database.  The user is prompted for all the fields contained in the record.  The record is then added using the SGL_UpdateRecord call.  Note that if a record of the same record_name already exists, it will be replaced by the new record, without notification.

(U)pdate record - Updates the last record retrieved in the database. This function requires a previous invocation of (G)et record by name or get (N)ext record by name.  The user is prompted to change any of the current field values.  Then SGL_UpdateRecord is called to update the record.  Note that if the user specifies to change the record name, either a different record will be updated, or a new record added, and the original record will be left unaltered.

(D)elete record - The user is prompted for the name of the record.  The record is then deleted with SGL_DeleteRecord.

(R)estore (undelete) record - The user is prompted for the name of the record.  The record is then deleted with SGL_DeleteRecord.

(P)ack library - Causes the library to be rebuilt with a call to SGL_PackLibrary.  Any records marked as deleted will be cleaned out.

(O)utput library dump - This function generates a listing of the contents of the current library into an ASCII dump file.  It prompts for the name of the file (without path or extension), and then calls SGL_DumpDataBase.  The file will be placed in the SGLLIBPATH directory.

(Q)uit - Closes the library if opened, deallocates any residual structures, and then terminates the program.
Appendix B: 2/3 Trees; An Explanation of the SGL Index File Scheme

The index records for the SGL database are stored in a structure known as a 2/3 Tree.  This tree contains cells consisting of either 1 or 2 nodes.  If a cell contains 1 node, it contains 2 branches.  If a cell contains 2 nodes, it contains 3 branches.  However, if a cell is a leaf cell, it has no branches, regardless of whether it contains 1 or 2 nodes.  All nodes under the left branch of a cell are sequentially less than the left node or only node within the cell.  All elements under the right branch are greater than the right node or only node.  For a cell with 2 nodes, the left node is less than the right node, and all nodes under the middle branch are sequentially between the two cell nodes.  The following figure shows an example 2/3 tree.

The house cell is the root of the tree. Its left branch is topped with cell Fence1, and its right branch with cell Restaurant/Truck1.  The 5 Leaf cells include Bush/Car, Fence2, Ice Cream Stand, Tree, and Truck2/Water Tower.

An important feature of a 2/3 tree is that it is always balanced.  While the distribution of one-node vs. two-node cells may be random, or weighted (even severely) to one side, the depth of all leaf cells within the tree is the same.  The balance of the 2/3 tree is maintained by the insertion algorithm.  As nodes are added to the tree, its height will increase, but it grows from the top (the root), not from the leaves.  At the bottom of the tree (the leaves) the tree only grows wider, not down.

To add a node to the tree, do the following.  Starting at the root, compare the node to the current cell, and follow down the appropriate branch.  Keep comparing and descending.