name: Sdb

synopsis:

g++ [flags ...] sdb ... -l /isip/tools/lib/$ISIP_BINARY/lib_shell.a

#include <Sdb.h>

~Sdb();
Sdb();
boolean gotoNext();
boolean gotoFirst;
boolean getName(Filename& arg) const;
boolean transformName(Filename& output_file, const Filename& input_file);

quick start:

Sdb sdb;
String line(L"run_me.exe file1.sof file2.sof file3.sof file4.sof file5.sof");
CommandLine cmdl(sdb);
cmdl.parse(line);

Filename tmp_name1;
Filename tmp_name2;

sdb.gotoFirst();
sdb.getName(tmp_name1);

sdb.gotoNext();
sdb.gotoNext();
sdb.getName(tmp_name2);

description:

The Sdb (Signal data base) class provides a means of managing signal files and Sdb files.

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"Sdb";

define filename translation constants:

static const String Sdb::DEF_OUT_DIR = L"";

define i/o related constants:

static const String DEF_PARAM = L"files";

define indicators for if an entry is a list or a plain file:

static const String LIST_FILE_MARKER = L"(list) ";

static const String LIST_FILE_OPTION = L"list";

default values and arguments:

static const long DEF_LOOKAHEAD = 10;

static const long DEF_DIR_PRES = Filename::DEF_DIR_PRES;

error codes:

error code indicating general Sdb class error:

static const long ERR = 45300;

static const long ERR_NOTSDB = 45301;

protected data:

define a list for user-specified files: the corresponding flag specifies whether the file is a list

DoubleLinkedList< Pair<Filename, Boolean> > files_d;

define a queue for iterating through the files: this queues up flat files

Queue<Filename> queue_d;

define stacks for: (1) open Sof files, (2) Sdb objects within the files, and (3) how manny elements are left in the current object (only used in binary mode)

Stack<WSof> fps_d;

Stack<Long> tags_d;

Stack<Long> nums_d;

define the lookahead parameter:

long lookahead_d;

define a startup flag: are we at the begining of processing?

boolean at_first_d;

define an output directory specification:

String output_directory_d;

define the number of directories to preserve:

Long dir_pres_d;

define a new filename extension to use:

String output_extension_d;

define a new filename base to use:

String output_basename_d;

define a new filename suffix to use:

String output_suffix_d;

define a static debug level for all objects of this class:
```
static Integral::DEBUG debug_level_d;
```
define the Memory Manager:
```
static MemoryManager mgr_d;
```

required public methods:

static methods:

static const String& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods:

static setDebug(Integral::DEBUG level);

boolean debug(const unichar* message) const;

destructor/ constructor(s):
```
~Sdb();
```
```
Sdb();
```

assign methods:

the assign method is omitted since there is no need to copy the Sdb object

operator= methods:
```
these methods are private
```

i/o methods:

long sofSize() const;

boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);

boolean write(Sof& sof, long tag, const String& name = CLASS_NAME) const;

boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false););

boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

equality methods:
```
boolean eq(const Sdb& arg) const;
```

memory management methods:

static void* operator new(size_t size);

static void* operator new[](size_t size);

static void operator delete(void* ptr);

static void operator delete[](void* ptr);

static boolean setGrowSize(long grow_size);

boolean clear(Integral::CMODE cmode = Integral::DEF_CMODE);

class-specific public methods:

append methods:

boolean append(const Filename& arg);

boolean append(const String& arg);

boolean append(const unichar* arg);

file access and transformation methods:

boolean gotoFirst();

boolean gotoNext();

boolean transformName(Filename& output_file, const Filename& input_file);

get and set methods:

boolean getName(Filename& arg);

long length();

boolean setOutputDirectory(const String& new_dir);

const String& getOutputDirectory() const;

boolean setDirPresLevel(const String& new_pres_level);

const String& getDirPresLevel() const;

boolean setOutputExtension(const String& new_ext);

const String& getOutputExtension() const;

boolean setOutputBasename(const String& new_basename);

const String& getOutputBasename() const;

boolean setOutputSuffix(const String& new_suffix);

const String& getOutputSuffix() const;

query methods:

static boolean isSdb(const Filename& arg, const String& obj_name = CLASS_NAME);

static boolean isSdb(Sof& arg, const String& obj_name = CLASS_NAME);

private methods:

constructors: the copy constructor is private since there is no need to copy the Sdb object

Sdb(const Sdb& arg);

operator= methods: this method is private since there is no need to copy the Sdb object

Sdb& operator= (const Sdb& arg);

iterate methods: for the given filename currently at the mark, this function will test to see if the file is an Sof file containing an Sdb object, if it is, then the data will be read and each entry in this list will be inserted in place of the given filename. If the given filename is not such a file list, the filename itself will be inserted into the Sdb list. While this may sound inefficient, this will actually pre-fetch all data files to be processed
```
long iterate();
```
parse methods: Sdb objects do not follow the name = value language handled by SofParser, so a customized parser is required. the input to this method is a single line of text from a file, the output is a filename
```
boolean parse(Filename& output, boolean& is_list, String& input);
```
method helpful for debugging: iterate through both objects and see if they lead to the same files.
```
boolean sameFiles(Sdb& arg);
```

friend classes:

friend class CommandLine;

examples:

This is a quick example of Sdb's append method. For a complete example of Sdb's primary operation, see the second example in the shell class introduction.

// isip include files
//
#include <CommandLine.h>
#include <String.h>
#include <Sdb.h>

// main program starts here
//
int main(int argc, const char **argv) {

  // create an Sdb object and parse the commandline
  // to add the files to the doubleLinkedList
  //
  Sdb sdb;
  String line(L"run_me.exe file1.sof file2.sof");
  CommandLine cmdl(sdb);
  cmdl.parse(line);

  // add another file to the doubleLinkedList
  //
  sdb.append(L"file3.sof");
       
  // output the sdb doubleLinkedList with
  // the standard debug method
  //
  sdb.debug(L"sdb debug");
  
  // exit gracefully
  //
  return true;
}

notes:

the WSof class is a specialization of the Wrapper class that defines the copy constructor and assign methods to error. This is needed since Sof objects cannot be copied.