gmslAPI  0.1
gmslAPI: An API for Developing Upgrade Solutions using Great Migrations Technology
gmslLibrary.Services.Text Class Reference

The class Text contains those methods needed to manage ordered sequences of text records, numbered from 1 to n. The typical retrieval pattern for text sequences is that they are first positioned to a certain record in the sequence and then a series of records is accessed from there. The algorithm used is optimal for moving forward through a sequence records once a starting location has been established. As such, the general approach differs from those for "normal" sequences in that the notion of a "current record" or "cursor" is used. The sequence is positioned on a record and that current record can then be manipulated. In addition to optimizing the traversal through the records, the approach also optimizes the storage and changing of records. The individual records are stored in fixed sized blocks in long memory. When a record in inserted into the stream or when the size of a record is changed only the block containing the record needs to be repositioned, not the entire stream. Finally, each text record in the stream consists of two parts: a fixed length component called the "record associated information" followed by the remaining text part, simply called the "record". More...

Public Member Functions

 Text (int iRoot)
 The Text constructor with a single integer parameter opens an existing text sequence stored in the currently selected storage area. More...
 
 Text (int storage, int nrai)
 The Text constructor with two integer parameters creates an empty text sequence. /summary> param name="storage"> The parameter storage specifies the handle for the storage area to contain the stext. If it is zero, then the stream will be allocated to a memory based storage area which will not persist when the instance is closed.
 
string Access (ref int nRecord, ref int rai)
 The string method Access retrieves the current record within the text sequence. It also optionally obtains the length, and record associated information for that record. More...
 
string Access (ref int rai)
 
string Access ()
 
void Close ()
 The method Close method closes a text sequence and saves its control information in its root property vector. More...
 
int Current ()
 The Current method returns the current position number withing the stream. This is a value between one and the maximum number of records. More...
 
void Delete ()
 The Delete method deletes the current record from the specified text stream. If the block containing the record is emptied, it is logically deleted – i.e. returned to the long memory area for reuse More...
 
bool Increment (int delta=1)
 The Increment method increments or decrements the current record number by the amount specified. It does not go beyond the front or back of the stream. More...
 
int Insert (string record, int rai)
 The method Insert inserts a record into the text sequence immediately after the current record. Each record is preceded by its fixed-length record associated information. Note that zero length records may be inserted. These generate record associated information storage, but no actual record storage space. More...
 
int Insert (string record)
 
int Maximum ()
 The Maximum method returns the maximum value of any record number – i.e. the the number of records currently stored in the sequence. This is because records are logically renumbered whenever a record is added or deleted. More...
 
int Position (int curRecord)
 The Position method positions the stream on the indicated record number, a value between one and the number of records in the sequence. More...
 
void Write (int fileRoot, int margin)
 The Write method writes the content of a text stream buffer to the current output file. More...
 

Public Attributes

int handle = 0
 

Detailed Description

The class Text contains those methods needed to manage ordered sequences of text records, numbered from 1 to n. The typical retrieval pattern for text sequences is that they are first positioned to a certain record in the sequence and then a series of records is accessed from there. The algorithm used is optimal for moving forward through a sequence records once a starting location has been established. As such, the general approach differs from those for "normal" sequences in that the notion of a "current record" or "cursor" is used. The sequence is positioned on a record and that current record can then be manipulated. In addition to optimizing the traversal through the records, the approach also optimizes the storage and changing of records. The individual records are stored in fixed sized blocks in long memory. When a record in inserted into the stream or when the size of a record is changed only the block containing the record needs to be repositioned, not the entire stream. Finally, each text record in the stream consists of two parts: a fixed length component called the "record associated information" followed by the remaining text part, simply called the "record".

Constructor & Destructor Documentation

◆ Text()

gmslLibrary.Services.Text.Text ( int  iRoot)

The Text constructor with a single integer parameter opens an existing text sequence stored in the currently selected storage area.

The parameter iRoot is the root offset off or the text sequence control block.

Member Function Documentation

◆ Access()

string gmslLibrary.Services.Text.Access ( ref int  nRecord,
ref int  rai 
)

The string method Access retrieves the current record within the text sequence. It also optionally obtains the length, and record associated information for that record.

Parameters
nRecordIf included in the arguments, this integer returns the length of the record as stored. In this implementation, this will always be equal to the length of the string returned. It should be considered deprecated.
raiIf included in the arguments, this integer returns the record associated information for the current record.
Returns
The method returns the string stored at the current location in the text sequence. It might be empty.

◆ Close()

void gmslLibrary.Services.Text.Close ( )

The method Close method closes a text sequence and saves its control information in its root property vector.

◆ Current()

int gmslLibrary.Services.Text.Current ( )

The Current method returns the current position number withing the stream. This is a value between one and the maximum number of records.

Returns
This method returns the current position number in the text sequence.

◆ Delete()

void gmslLibrary.Services.Text.Delete ( )

The Delete method deletes the current record from the specified text stream. If the block containing the record is emptied, it is logically deleted – i.e. returned to the long memory area for reuse

◆ Increment()

bool gmslLibrary.Services.Text.Increment ( int  delta = 1)

The Increment method increments or decrements the current record number by the amount specified. It does not go beyond the front or back of the stream.

Parameters
deltaThe delta paramter specifies the number of lines to be moved. A positive value increments the position and a negative value decrements it. If it is omitted, a value of one is used.
Returns
If the move is successfull a true is returned; else a false is returned.

◆ Insert()

int gmslLibrary.Services.Text.Insert ( string  record,
int  rai 
)

The method Insert inserts a record into the text sequence immediately after the current record. Each record is preceded by its fixed-length record associated information. Note that zero length records may be inserted. These generate record associated information storage, but no actual record storage space.

Parameters
recordContains the actual record to be inserted.
raiIn included, this argument contains the record associated information. If not includes a value of zero is used.
Returns
This method returns a one, if no room could be found for the record; and a zero if all went well.

◆ Maximum()

int gmslLibrary.Services.Text.Maximum ( )

The Maximum method returns the maximum value of any record number – i.e. the the number of records currently stored in the sequence. This is because records are logically renumbered whenever a record is added or deleted.

Returns
This method returns the number of records in the text sequence.

◆ Position()

int gmslLibrary.Services.Text.Position ( int  curRecord)

The Position method positions the stream on the indicated record number, a value between one and the number of records in the sequence.

specifies the number of the desired record.

Returns
This method returns a zero if the positioning was successfull; else it returns one.

◆ Write()

void gmslLibrary.Services.Text.Write ( int  fileRoot,
int  margin 
)

The Write method writes the content of a text stream buffer to the current output file.

Parameters
fileRootThe fileRoot parameter is the root offset of the symbol to which the text stream belongs. It may simply be zero. If nonzero, it is used to log this message"SYSERR#6067: Text storage malformed for ..." in case the text stream is malformed.
marginThe margin parameter is the starting indentation margin to be used while writing the text stream. When the toolc writes text streams it does not insert any leading white space to show marginal indentation; rather it simply records the margin level for each line aas record associated information. It is when the text stream is actually written that the margin level times the indentation width white space is actually applied to the front of the record. When doing this, the value of margin is added to the margin value recorded for each line.

The documentation for this class was generated from the following file: