The Write class contains the basic methods needed to write structured reports and text files of various sorts using binary information. It is used very extensively by the tool during every phase of its operation and is fully exposed via gmSL. Ultimately, at any given point in time, only one coded output report can be written at one time. More...

Static Public Member Functions
static void	ChangeMargin (int delta)
	When authoring the tool does not attempt to reproduce the leading white space in the source code; rather, it keeps track of the margin nesting level via the "p" and "q" escape characters in the surface patterns or via calls to this method and then uses this margin level times the indentation width specified via the Select Indent property to determine the number of leading blanks or tabs to add. More...

static void	Character (char charValue)
	This method appends the ASCII character whose display code is specified by charValue to the current output record. No actual write occurs at this time. More...

static void	Character (int charValue)

static void	Character (string charValue)

static void	CloseFile ()
	The CloseFile method closes the selected unit and any physical file associated with that unit. Upon completion, unit 1, the unit associated with the Execute.Output method, becomes the selected unit. More...

static int	CloseStream ()
	In the toolc authored records are stored in text buffers within the current storage area. The CloseStream method closes the currently open text buffer and returns its integer handle. This handle must be saved by the caller to be used later to either reopen the text buffer or to physically write it to a file. If writes are currently being sent directly to the file specified in the Output statement, then this method does nothing. More...

static void	ControlString (string strValue, int nString)
	The ControlString method enters a control string at the back of the record. Normally, the write classr does not examine the actual strings that it is asked to display; however, character strings containing codes that are not in the normal ASCII range are often encountered by the various portation tools. This method replaces these with escape sequences. More...

static void	Field (string strValue, int nString, int iField)
	Ultimately each method that adds characters to a record is said to be "writing a field" at the back of the record of the selected unit. Characters can be entered into fields either free-form, or left-justified in a fixed-width field with a white space to the right, or right-justified in a fixed-width field with white space to the left. The field method is the lowest level utility within the Write class. It performs the writing of a field. No actual write occurs at this time. More...

static string	GetFileName ()
	The GetFileName method returns the name of the current output file. More...

static void	Integer (int iValue, int iField=0)
	The Integer method appends the base 10 display form of iValue in a specified field of characters to the current output record. No actual write occurs at this time. No special formatting flags are available. More...

static void	Line (string text)
	The Line method appends all characters from the parameter to the current output record and then writes the result either to the currently open text buffer or to the file specified in the Output statement. No formatting is applied to the string. More...

static void	NText (string strValue, int nString)
	The NText method appends the initial characters from a string to the current output record. No actual write occurs at this time. No formatting is applied to the string. More...

static void	OpenFile (int unit, string fileName, bool statusNew, OutStyle syntax)
	There are 5 totally independent file structures that may be in use. Initially only 1 of these, unit 1, is active. It is managed via the gmPL Output statement. Internally, the tool uses unit 5 as a scratch output file. This unit is never left open outside of a given task within the process. The other units are available as needed. Each file has a physical file associated with it, which is either a named file or the Standard Output file. At any given point in time only one file unit is active, unit 1 is always the default, and all write operations are performed on that unit. The term "selected unit" is used to refer to the currently active one. The OpenFile method is used to connect one of these units to a named file which is either created as a new file or is opened for append access for an existing file. The file unit is then exactly like a file opened via the gmPL Output statement which uses unit 1. More...

static int	OpenStream ()
	By default records are written to the physical file associated with the selected unit; however, in many cases what is needed is an internal representation of what is to be written to the file. This representation, referred to as a text stream, can then be saved, edited, audited, and perhaps eventually physically written to a file. At any point in time, the selected unit is either writing to its physical file or to a text stream. During its life a file unit can spawn as many text streams as desired, but can only process one at a time. The OpenStream method creates such a text buffer and makes it the current output stream. All subsequent writes will go to this stream until it is closed. At which point the current output stream will revert to the file specified in the Output statement. More...

static void	Pattern (string PatString, int nPattern, string Parameters)
	The Pattern method enters a pattern string starting at the current location in into the current output record using editing directives within the string along with parameters defined in a separate semicolon-delimited string. No actual write occurs at this time. Directives within the pattern string are enclosed in % signs. The following are recognized. "%%" enter a percent sign. "%USR_VERSION%" enters the platform specified user version identifier. "%PRM_VERSION%" enters the platform specified system version identifier. "%PRM_BUILDID%" enters the platform build signature string. "%DATE%" enters the current date using the currently selected formatting options. "%TIME%" enters the current time using currently selected formatting options. "%envname%" enters the value of environment variable envname. It must begin with an alphabetic character and may contain no more than 31 characters. "%nd" enters the nth (1-based) parameter string More...

static void	Record ()
	The Record method completes the authoring of the current output record and then writes the result either to the currently open text buffer or to the file specified in the Output statement. The steps performed before the write include: first, special codes that are used to represent single and double quotes in either escaped or un escaped form must be converted to the final form required by the target language; second, if the echo translation flag is set then the current margin nesting level and the record are written to the log file; third, if the author is writing ASP code then the record must be checked for a transition into or out or VBSCRIPT; and fourth, if the record is longer that the Select MaxOutputWidth value then it is broken into multiple records using the conventions of the target language. More...

static int	Select (int unit)
	The Select method selects one the available write structures as the current unit. All successive write support will be performed by this unit until another call to this method is made or until the unit is closed. Note that this method only selects the unit it does not open its output channels or change it in any way. More...

static void	SetIndentation (int indent, int offset)
	The SetIndentation method sets the indentation widths for the current output stream. There are two width values: indent which specifies the number of spaces to indent per indentation level (a value of zero means use tabs); and offset which is used when a record is longer than the desired line-width. The following line can be set off this many additional spaces. When an output file is first created, the default indent value is the Select Indent property and the default offset value is zero. When a text buffer is opened the initial values are the values from the current output file. The values specified here take immediate effect and can be changed within the same write sequence. More...

static void	SetOutputStyle (OutStyle style)
	The SetOutputStyle method sets the output style for the current write support unit. More...

static void	Text (string strValue)
	The Text method appends all characters from its string parametere to the current output record. No actual write occurs at this time. No formatting is applied to the string. More...

static string	Clear ()
	The Clear method clears the current output record. In many complex output situations it is often desireable to nest the output support utilities so that complex outputs can be nested within each other or can be constructed with independent sets of logic. This method makes this possible. Rather than writing the current output record and thus clearing its internal buffers so that another record can be written, this method clears the internal buffers and returns the content of the buffer More...

Detailed Description

The Write class contains the basic methods needed to write structured reports and text files of various sorts using binary information. It is used very extensively by the tool during every phase of its operation and is fully exposed via gmSL. Ultimately, at any given point in time, only one coded output report can be written at one time.

Member Function Documentation

◆ ChangeMargin()

static void gmslLibrary.Services.Write.ChangeMargin ( int delta )

static

When authoring the tool does not attempt to reproduce the leading white space in the source code; rather, it keeps track of the margin nesting level via the "p" and "q" escape characters in the surface patterns or via calls to this method and then uses this margin level times the indentation width specified via the Select Indent property to determine the number of leading blanks or tabs to add.

Parameters

delta This method adds the value of delta to the current margin level. If delta is negative, the indentation will be decreased, and if it is positive, the indentation will be increased. If the computed margin level ends up being negative, it is set back to zero.

◆ Character()

static void gmslLibrary.Services.Write.Character ( char charValue )

static

This method appends the ASCII character whose display code is specified by charValue to the current output record. No actual write occurs at this time.

Parameters

charValue The charValue parameter specifies the character to be appended if it is of type char; it is the ASCII value of the character to be written if it is integer; and its first character is written if it is of type string.

◆ Clear()

static string gmslLibrary.Services.Write.Clear ( )

static

The Clear method clears the current output record. In many complex output situations it is often desireable to nest the output support utilities so that complex outputs can be nested within each other or can be constructed with independent sets of logic. This method makes this possible. Rather than writing the current output record and thus clearing its internal buffers so that another record can be written, this method clears the internal buffers and returns the content of the buffer

Returns: The content of the outpur buffer before it was cleared.

◆ CloseFile()

static void gmslLibrary.Services.Write.CloseFile ( )

static

The CloseFile method closes the selected unit and any physical file associated with that unit. Upon completion, unit 1, the unit associated with the Execute.Output method, becomes the selected unit.

◆ CloseStream()

static int gmslLibrary.Services.Write.CloseStream ( )

static

In the toolc authored records are stored in text buffers within the current storage area. The CloseStream method closes the currently open text buffer and returns its integer handle. This handle must be saved by the caller to be used later to either reopen the text buffer or to physically write it to a file. If writes are currently being sent directly to the file specified in the Output statement, then this method does nothing.

Returns: The method returns the integer handle to the text buffer that has been closed.

◆ ControlString()

static void gmslLibrary.Services.Write.ControlString	(	string	strValue,
		int	nString
	)

static

The ControlString method enters a control string at the back of the record. Normally, the write classr does not examine the actual strings that it is asked to display; however, character strings containing codes that are not in the normal ASCII range are often encountered by the various portation tools. This method replaces these with escape sequences.

Parameters

strValue	contains the actual characters to be entered into the output record.
nString	specifies the number of characters from the start of the string to be entered. If it is zero, then the entire string is entered.

◆ Field()

static void gmslLibrary.Services.Write.Field	(	string	strValue,
		int	nString,
		int	iField
	)

static

Ultimately each method that adds characters to a record is said to be "writing a field" at the back of the record of the selected unit. Characters can be entered into fields either free-form, or left-justified in a fixed-width field with a white space to the right, or right-justified in a fixed-width field with white space to the left. The field method is the lowest level utility within the Write class. It performs the writing of a field. No actual write occurs at this time.

Parameters

strValue	Within that field the content of strValue may be preceded or followed by white space.
nString	specifies the number of characters from strValue that are to be used.
iField	specifies how the characters from strValue should be entered. A value of 0 simply appends the characters to the current content of the output record. A value of +n right justifies the characters in a field n characters wide appended to the back of the current record. A value of -n left justifies the characters in a field n characters wide appended to the back of the current record.

◆ GetFileName()

static string gmslLibrary.Services.Write.GetFileName ( )

static

The GetFileName method returns the name of the current output file.

◆ Integer()

static void gmslLibrary.Services.Write.Integer	(	int	iValue,
		int	iField = `0`
	)

static

The Integer method appends the base 10 display form of iValue in a specified field of characters to the current output record. No actual write occurs at this time. No special formatting flags are available.

Parameters

iValue specifies the value to be displayed.

iField specifies how the characters from the display form of iValue should be entered. A value of 0 simply appends the characters to the current content of the output record. A value of +n right justifies the characters in a field n characters wide appended to the back of the current record. A value of -n left justifies the characters in a field n characters wide appended to the back of the current record.

◆ Line()

static void gmslLibrary.Services.Write.Line ( string text )

static

The Line method appends all characters from the parameter to the current output record and then writes the result either to the currently open text buffer or to the file specified in the Output statement. No formatting is applied to the string.

Parameters

text	contains the string being added to the record.

◆ NText()

static void gmslLibrary.Services.Write.NText	(	string	strValue,
		int	nString
	)

static

The NText method appends the initial characters from a string to the current output record. No actual write occurs at this time. No formatting is applied to the string.

Parameters

strValue	contains the string whose initial characters are to be displayed.
nString	specifies the number of initial characters to be displayed. Note that care must be taken that this value does not exceed the length of string. Since gmSL supports a string type, this method is rarely needed.

◆ OpenFile()

static void gmslLibrary.Services.Write.OpenFile	(	int	unit,
		string	fileName,
		bool	statusNew,
		OutStyle	syntax
	)

static

There are 5 totally independent file structures that may be in use. Initially only 1 of these, unit 1, is active. It is managed via the gmPL Output statement. Internally, the tool uses unit 5 as a scratch output file. This unit is never left open outside of a given task within the process. The other units are available as needed. Each file has a physical file associated with it, which is either a named file or the Standard Output file. At any given point in time only one file unit is active, unit 1 is always the default, and all write operations are performed on that unit. The term "selected unit" is used to refer to the currently active one. The OpenFile method is used to connect one of these units to a named file which is either created as a new file or is opened for append access for an existing file. The file unit is then exactly like a file opened via the gmPL Output statement which uses unit 1.

Parameters

unit	The unit parameter specifies which file unit is to be used. It must be a value between 1 and 5.
fileName	The fileName parameter is the name of the file to be opened.
statusNew	The statusNew parameter, if true, requests that a new file be created as opposed to opening an existing file for append access.
syntax	The syntax parameter specifies the output style to be used when producing tabular reports. They can be produced in one of three styles: Tabbed simple tab delimited; Text text tabular; or Html html tabular.

◆ OpenStream()

static int gmslLibrary.Services.Write.OpenStream ( )

static

By default records are written to the physical file associated with the selected unit; however, in many cases what is needed is an internal representation of what is to be written to the file. This representation, referred to as a text stream, can then be saved, edited, audited, and perhaps eventually physically written to a file. At any point in time, the selected unit is either writing to its physical file or to a text stream. During its life a file unit can spawn as many text streams as desired, but can only process one at a time. The OpenStream method creates such a text buffer and makes it the current output stream. All subsequent writes will go to this stream until it is closed. At which point the current output stream will revert to the file specified in the Output statement.

◆ Pattern()

static void gmslLibrary.Services.Write.Pattern	(	string	PatString,
		int	nPattern,
		string	Parameters
	)

static

The Pattern method enters a pattern string starting at the current location in into the current output record using editing directives within the string along with parameters defined in a separate semicolon-delimited string. No actual write occurs at this time. Directives within the pattern string are enclosed in % signs. The following are recognized. "%%" enter a percent sign. "%USR_VERSION%" enters the platform specified user version identifier. "%PRM_VERSION%" enters the platform specified system version identifier. "%PRM_BUILDID%" enters the platform build signature string. "%DATE%" enters the current date using the currently selected formatting options. "%TIME%" enters the current time using currently selected formatting options. "%envname%" enters the value of environment variable envname. It must begin with an alphabetic character and may contain no more than 31 characters. "%nd" enters the nth (1-based) parameter string

Parameters

PatString	contains the pattern string.
nPattern	specifies the number of initial character within the pattern string to use. If zero, the entire string is used.
Parameters	Parameters contains a semicolon-delimited string containing parameters referenced via their number. If the PatString contains no such references it may be empty.

◆ Record()

static void gmslLibrary.Services.Write.Record ( )

static

The Record method completes the authoring of the current output record and then writes the result either to the currently open text buffer or to the file specified in the Output statement. The steps performed before the write include: first, special codes that are used to represent single and double quotes in either escaped or un escaped form must be converted to the final form required by the target language; second, if the echo translation flag is set then the current margin nesting level and the record are written to the log file; third, if the author is writing ASP code then the record must be checked for a transition into or out or VBSCRIPT; and fourth, if the record is longer that the Select MaxOutputWidth value then it is broken into multiple records using the conventions of the target language.

◆ Select()

static int gmslLibrary.Services.Write.Select ( int unit )

static

The Select method selects one the available write structures as the current unit. All successive write support will be performed by this unit until another call to this method is made or until the unit is closed. Note that this method only selects the unit it does not open its output channels or change it in any way.

Parameters

unit The unit parameter is the unit sequence number of the desired write structure. It must have a value between 1 and 5. Note that unit 1 is connected to the gmPL Output statement and should be used with care. Unit 5 is used by the tool as a temporary scratch unit – not open between tasks – and should only be used in the same way here.

◆ SetIndentation()

static void gmslLibrary.Services.Write.SetIndentation	(	int	indent,
		int	offset
	)

static

The SetIndentation method sets the indentation widths for the current output stream. There are two width values: indent which specifies the number of spaces to indent per indentation level (a value of zero means use tabs); and offset which is used when a record is longer than the desired line-width. The following line can be set off this many additional spaces. When an output file is first created, the default indent value is the Select Indent property and the default offset value is zero. When a text buffer is opened the initial values are the values from the current output file. The values specified here take immediate effect and can be changed within the same write sequence.

Parameters

indent	specifies the indent value.
offset	specifies the offset value.

◆ SetOutputStyle()

static void gmslLibrary.Services.Write.SetOutputStyle ( OutStyle style )

static

The SetOutputStyle method sets the output style for the current write support unit.

Parameters

style The style parameter specifies the output style to be used when producing tabular reports. They can be produced in one of three styles: Tabbed simple tab delimited; Text text tabular; or Html html tabular.

◆ Text()

static void gmslLibrary.Services.Write.Text ( string strValue )

static

The Text method appends all characters from its string parametere to the current output record. No actual write occurs at this time. No formatting is applied to the string.

Parameters

strValue contains the string to be appended.

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

C:/gmProducts/gmStudio_dev/src/gmslAPI/gmslLibrary/Write.cs

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ChangeMargin()

◆ Character()

◆ Clear()

◆ CloseFile()

◆ CloseStream()

◆ ControlString()

◆ Field()

◆ GetFileName()

◆ Integer()

◆ Line()

◆ NText()

◆ OpenFile()

◆ OpenStream()

◆ Pattern()

◆ Record()

◆ Select()

◆ SetIndentation()

◆ SetOutputStyle()

◆ Text()