gmSCCharacterClass

The Character Service Class

The service class Character processes character strings in various ways. Internally, this class assumes that all character strings are sequences of 8-bit unsigned bytes — i.e. with values in the range 0-255. Though not required all current implementations of this class use ASCII or UTF-8 variable length encoding and the descriptions of the methods assume that encoding. Internally the character values have character type flags associated with them as follows:

Flag	Description
UpperCaseFlag	The character is an upper case letter. This flag is normally restricted to the non extended ASCII characters.
LowerCaseFlag	The character is a lower case letter. This flag is normally restricted to the non extended ASCII characters.
IdentFlag	The character may begin and/or be within identifiers in the source language. Characters like the percent sign or dollar sign are often included as well as alphabetic-like characters in the 128-255 extended range.
NumberFlag	This flag applies only to the 10 digit characters 0 - 9.
SpecialFlag	This flag is used to mark those characters that make up the special character set of the source language. These characters will typically have token values associated with them as well.
WhiteSpace	This flag marks the white space characters, normally blank and tab.
QuoteFlag	This flag marks those characters used by the target language to enclose quoted strings. It may well include both the single and double quote and might as well include quotes in the 128-255 extended range.

The field Character_ErrorCode

Prototype

 extern int Character_ErrorCode;
 extern int Character_Ihist;
 extern int Character_Ndec;

The Character_ErrorCode field is used to record errors that occur doing character processing operations. In addition there are two additional fields that supply support information. The Character_Ihist specifies the particular position with a string that contains a bad character which string conversion operations are being performed. The Character_Ndec specifies the number of explicit decimal digits used when a string is being converted to a decimal value. The actual error codes are as follows:

ErrorCode	Description
CharacterError_WrongDec	A string had the wrong number of decimal places
CharacterError_BadDigits	A string contained a bad character relative to a conversion
CharacterError_MissingValue	A string was missing a value during a date/time conversion
CharacterError_BadMonth	A string contained an illegal month value
CharacterError_BadDay	A string contained an illegal day value
CharacterError_BadYear	A string contained an illegal year value
CharacterError_BadTimeSeparator	A string contained an illegal time separation character

The field Character_Separator

Prototype

extern int Character_Separator

The Character_Separator field specifies the character use to separate the parameter substrings used by the editing methods. Its default value is a semi-colon.

The method Character_ApplyTemplate

Prototype

int Character_ApplyTemplate(char* format,char* ident,int nIdent,char* buffer);

The Character_ApplyTemplate method applies a template string to an identifier to form a new identifier. The template string uses the embedded “%1d” notation to mark the position where the identifier is to be inserted. A template like “%1d_RowIndex” when applied to an identifier “myRecord” would produce “myRecord_RowIndex”. Note that the use of the %nd notation makes these templates compatible with the language surface form strings. The parameters are:

Parameter	Description
format	Contains the patterned template as described above. It must be null-terminated.
ident	Contains the identifier used with the template. It need not be null-terminated and its length must be specified.
nIdent	Specifies the length of the identifier.
buffer	Receives the newly formed identifier.

The method returns the length of the identifier.

The method Character_Compare

Prototype

int Character_Compare(CONST char* string1,CONST char* string2,int nCompare);

The Character_Compare method does a case-insensitive comparison between two character vectors. This is a bounded comparison. The null-character is treated exactly like any other special character. If all characters within the specified range are identical, up to case distinctions, then the method returns a zero. If two characters within the specified range disagree, then the value of the character in the first vector minus that in the second vector is returned. The parameters are:

Parameter	Description
string1	Contains the first character vector in the comparison.
string2	Contains the second character vector in the comparison.
nCompare	Specifies the number of characters to be compared.

Note that the characters within the strings are retrieved and compared as byte values in the range 0 to 255.

The method Character_CompareStrings

Prototype

int Character_CompareStrings(char *string1,char *string2);

The Character_CompareStrings method does a case-insensitive comparison between two character strings. If all characters within the two strings are identical, up to case distinctions, then the method returns a zero. If two characters within the specified strings disagree, then the value of the character in the first string minus that in the second string is returned. The parameters are:

Parameter	Description
string1	Contains the first character string in the comparison.
string2	Contains the second character string in the comparison.

Note the string characters are retrieved here and compared as byte values (0 to 255).

The method Character_DigitValue

Prototype

int Character_DigitValue(int charValue);

The Character_DigitValue method returns the value of a character digit. For the actual numeric digits this is the value of that digit. For lowercase alphabetic characters it is the sequence number of the letter in the alphabet. For uppercase alphabetic characters it is the value of the corresponding lowercase letter. For some special characters if is a token type value for that character. For all other characters it is zero. The parameter is:

Parameter	Description
charValue	specifies the value of the character being tested. It must be between 0 and 255.

The method Character_DoubleDisplay

Prototype

int Character_DoubleDisplay(char* fiocrec,double value);

The Character_DoubleDisplay method converts a double precision value into a free-form display without any additional direction from the caller. Based on the value being displayed it selects the most appropriate display format for it. The parameters are:

Parameter	Description
fiocrec	Receives display form of the value.
value	Specifies the value to be displayed.

The method returns the length in characters of the formed display.

The method Character_EditString

Prototype

int Character_EditString(CONST char* pattern,int nPattern,char* buffer,char* params,int patChar);

The Character_EditString method forms a character string based on an input pattern string that specifies how the target string is to be formed. The editing pattern consists of characters that are simply copied into the result string and directive identifiers. These directive identifiers are marked by a leading pattern character — usually a percent sign(%) or dollar sign($). The following are identifiers that are recognized (this assumes % is the pattern character):

Directive	Meaning
%%	Enter a percent sign
%PRM_VERSION%	Platform specified system version identifier
%PRM_BUILDID%	Platform build signature string
%DATE%	Current date using currently selected formatting options
%TIME%	Current time using currently selected formatting options
%nd	Enter the nth (1-based) parameter string

Note that the use of the %nd notation makes these patterns compatible with the language surface form strings. Its parameters are:

Parameter	Description
pattern	Contains the patterned editing specification as described above. It must be null-terminated only if the nPattern parameter is zero.
nPattern	Specifies the length of the editing string. If it is zero, then the editing string is assumed to be null-terminated and its length is computed accordingly.
buffer	Receives the edited string. It is null-terminated. This method does not check to make certain that the buffer is large enough to contain the result.
params	Contains an optional Character_Separator-delimited character string specifying the parameter strings to be used. If the edit strings contains no references to parameter strings then this parameter may be NULL. If a given reference parameter is missing, then no entry is made for it. Note that Character_Separator is normally a semicolon.
patChar	Specifies the character used to mark the directive identifiers. It is typically % or $.

The method returns the number of characters entered into the character result buffer not counting the terminating null.

The method Character_FindFirst

Prototype

int Character_FindFirst(char* source,int length,CONST char* substr);

The Character_FindFirst method finds the first occurrence of substring in a string starting at the front of the string. All character comparisons are case insensitive. It returns when it finds a first occurrence or when it reaches the end of the string. Its parameters are:

Parameter	Description
source	Contains the string which is being searched.
length	Specifies the length of the search range or zero, which indicates that the entire string is to be searched.
substr	Contains the substring which is being searched for.

If all characters within the substring are identical to a sequence of characters within the string, up to case distinctions, then the method returns the position, relative to one, of the start of the matching sequence in the string. If no matching sequence can be located in the string, then a zero is returned.

The method Character_FindLast

Prototype

int Character_FindLast(char* String,int nString,CONST char* Substring);

The Character_FindLast method attempts to find a substring within a string starting at the back of the string. All character comparisons are case insensitive. The method returns when it finds a last occurrence or when it reaches the front of the string. Its parameters are:

Parameter	Description
String	Contains the string being searched.
nString	Specifies the length of the string or zero if the string is null-terminated.
Substring	contains the substring being searched for. It must be null-terminated.

The method Character_FromDate

Prototype

int Character_FromDate(int date,char* String);

The Character_FromDate method converts a date value into a string. The format used is either mm/dd/yy or yyyy/mm/dd depending upon the YearMonthDay display flag. Its parameters are:

Parameter	Description
date	Contains the relative Julian date value to be displayed.
String	returns the display form of the date in null-terminated form.

The method returns the length of the date display.

The method Character_FromDateTime

Prototype

int Character_FromDateTime(longlong datetime,char* String);

The Character_FromDateTime method converts a date/time value into a string by simply displaying the date component in yyyy/mm/dd form followed by the time component in hh:mm form. Its parameters are:

Parameter	Description
datetime	Specifies the actual date/time value to be displayed in Julian seconds.
String	Receives the display form of the date/time value in null-terminated form.

The method returns the length of the date/time display.

The method Character_FromDouble

Prototype

void Character_FromDouble(double val,int ndig,int* pdecpt,int* psign, char* dspdig);

The Character_FromDouble method converts a double precision floating point value into a raw character form. ANSI C expects that all conversions of floating point values to string be performed via the “sprintf” service. Though this can be done, most generalized applications, prefer to perform their own editing operations, and require only a raw conversion be performed. Its parameters are:

Parameter	Description
val	Specifies the value to be converted to character form.
ndig	Specifies the number of digits to produce. Precisely this many digits are produced.
pdecpt	returns the position of decimal point with respect to the beginning of the string.
psign	returns zero if the value was non-negative else it returns one if the value was negative.
dspdig	Receives the string produced. It contains precisely ndig digits followed by a null-byte.

If the number of digits in val exceeds ndig then the last digit is rounded. If the number of digits is less that ndig then it is padded with zeros.

The method Character_FromLong

Prototype

int Character_FromLong(longlong Value,char* String,int nDecimal);

The Character_FromLong method converts a long integer 8-byte value into a character string. Its parameters are:

Parameter	Description
Value	Specifies the value to be converted.
String	Receives the character representation of the value in null-terminated string form.
nDecimal	Specifies the number of assumed decimal places in the value.

The method returns the length of the character representation, not counting the null.

The method Character_FromShort

Prototype

int Character_FromShort(int Value,char* String,int nDecimal);

The Character_FromShort method converts a short integer 4-byte value into a character string. Its parameters are:

Parameter	Description
Value	Specifies the value to be converted.
String	Receives the character representation of the value in null-terminated string form.
nDecimal	Specifies the number of assumed decimal places in the value.

The method returns the length of the character representation, not counting the null.

The method Character_FromTime

Prototype

int Character_FromTime(int TimeValue,char* String);

The Character_FromTime method converts a time value into a string. The default used is hh:mm:ss, with the leading “h” blanked out if possible. The hour value is shown in 24-hour form. The seconds value is omitted if the OmitSeconds display flag is set. The time value itself is computed via the formula 3600*hour + 60*minute + second, in other words it is the number of seconds since midnight. Its parameters are:

Parameter	Description
TimeValue	specifies the actual time value to be displayed in the form described above.
String	Receives the display form of the time in null-terminated form.

The method returns the length of the time display.

The method Character_Hexidecimal

Prototype

int Character_HexiDecimal(ULONG Value,char* String,int base);

The Character_HexiDecimal method converts an unsigned integer value into a character string using hexadecimal, decimal, octal, or binary notation. Note that the decimal, octal, and binary notation digits are simply subsets of the hexadecimal digits. Its parameters are:

Parameter	Description
Value	Specifies the value to be converted.
String	Receives the string representation in the appropriate base.
base	Specifies the base to be used — 2, 8, 10, or 16.

The method returns length of the character representation, not counting the null.

The method Character_Insert

Prototype

int Character_Insert(char* source,int iStart,char* subStr,char* buffer);

The Character_Insert method inserts a substring into a base string starting at a zero-based offset. Its parameters are:

Parameter	Description
source	Contains base string that receives the substring
iStart	Specifies the zero-based offset in the base string where the insertion is to begin
subStr	Contains substring being inserted
buffer	Receives the result of the insertion

The method returns the length of the result string.

The method Character_IsControl

Prototype

int Character_IsControl(int charValue);

The Character_IsControl method tests for control characters. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested

The method returns a nonzero value if a character value is below 32 or above 127, else it returns zero. It does not use character type flags and will report extended identifier characters as being control characters.

The method Character_IsDigit

Prototype

int Character_IsDigit(int charValue);

The Character_IsDigit method tests for numeric digits. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns a nonzero value if a character is a digit else it return zero.

The method Character_IsIdent

Prototype

int Character_IsIdent(int charValue);

The Character_IsIdent method tests for identifier characters. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns a nonzero value if a character is a possible identifier character else it returns zero. It does use character type flags and will report extended identifier characters as being identifiers.

The method Character_IsLetter

Prototype

int Character_IsLetter(int charValue);

The Character_IsLetter method tests for alphabetic characters. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns a nonzero value if a character is an alphabetic, upper or lower case, character; else it returns zero.

The method Character_IsLower

Prototype

int Character_IsLower(int charValue);

The Character_IsLower method tests for lower case alphabetic characters. Since this test is typically made to do a case conversion, it returns the equivalent upper case value. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns the equivalent non-zero upper case value of the character if it is lower case; else it returns zero.

The method Character_IsUpper

Prototype

int Character_IsUpper(int charValue);

The Character_IsUpper method tests for upper case alphabetic characters. Since this test is typically made to do a case conversion, it returns the equivalent lower case value. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns the equivalent non-zero lower case value of the character if it is upper case; else it returns zero.

The method Character_IsNothing

Prototype

int Character_IsNothing(int charValue);

The Character_IsNothing method tests for characters with no special use. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns a nonzero value if a character has no purpose flags associated with it and it is in the range 0 to 255; else it returns zero.

The method Character_IsQuote

Prototype

int Character_IsQuote(int charValue);

The method Character_IsQuote tests for quote characters. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns a nonzero value if the character is a quote character; else it returns zero.

The method Character_IsSpecial

Prototype

int Character_IsSpecial(int charValue);

The Character_IsSpecial method tests for special characters. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns a nonzero value if the character is a special character; else it returns zero.

The method Character_HasSpecial

Prototype

int Character_HasSpecial(int charValue);

The Character_HasSpecial method tests for the special character value. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character whose value is wanted. It may be signed or unsigned.

The method returns the special character value if the character is a special character; else it returns zero.

The method Character_IsWhiteSpace

Prototype

int Character_IsWhiteSpace(int charValue);

The Character_IsWhiteSpace method tests for whitespace characters. Its parameter is:

Parameter	Description
charValue	specifies the ASCII value of the character being tested. It may be signed or unsigned.

The method returns a nonzero value if the character is whitespace; else it returns zero.

The method Character_Remove

Prototype

int Character_Remove(char* strValue, int iStart, int length, char* buffer);

The Character_Remove method forms a new string by removing a specified number of characters from a string starting at a zero-based offset into the string. Its parameters are:

Parameter	Description
strValue	Contains the string from which characters are to be removed. It must be null-terminated.
iStart	Specifies the zero-based offset of the first character to be removed.
length	Specifies the number of characters to be removed.
buffer	Receives the newly formed string in null-terminated form.

The method returns the length of the new string.

The method Character_Replace

Prototype

int Character_Replace(char* source,char* oldStr,char* newStr, char* buffer);

The Character_Replace method forms a new string from an existing one in which all occurrences of a specified substring have been replace by a new substring. Its parameters are:

Parameter	Description
source	Contains the original string to be modified. It must be null-terminated.
oldStr	Contains the substring whose occurrences are to be replaced. It must be null-terminated.
newStr	Contains the replacing substring. It must be null-terminated.
buffer	Receives the new string in null-terminated form.

The method returns the length of the new string.

The method Character_RoundValue

Prototype

int Character_RoundValue(char* dspdig,int ndigit,int length);

The Character_RoundValue method truncates and rounds a numeric string of digits. It modifies the content of that digit string and returns the carry value from the round. If the input string consists of a sequence of “999..” such that all become rounded to zero, then the output string will contain “100…” and the method will return a value of 1; else it will return a value of 0. Its parameters are:

Parameter	Description
dspdig	Contains the string of numeric digits to be rounded. It may contain only numeric digits. It need not be null-terminated.
ndigit	Specifies the number of digits desired in the rounded result.
length	Specifies the total number of digits in the string as input.

The method returns a one or a zero as described above.

The method Character_SetIdent

Prototype

int Character_SetIdent(int charValue,int status);

The Character_SetIdent method sets a character as an identifier character. Its parameters are:

Parameter	Description
charValue	specifies the ASCII value of the character being set. It may be signed or unsigned. If it is not in the range 0 to 255, then the method does nothing.
status	Specifies the status to be set. If it is nonzero, the IdentFlag is turned on for the character, else it is turned off.

The method returns the previous identifier status of the character.

The method Character_SetQuote

Prototype

int Character_SetQuote(int charValue,int status);

The Character_SetQuote method sets a character as a quote character. Its parameters are:

Parameter	Description
charValue	specifies the ASCII value of the character being set. It may be signed or unsigned. If it is not in the range 0 to 255, then the method does nothing.
status	Specifies the status to be set. If it is nonzero, the QuoteFlag is turned on for the character, else it is turned off.

The method returns the previous quote status of the character.

The method Character_SetSpecial

Prototype

int Character_SetSpecial(int charValue,int status);

The Character_SetSpecial method sets a character as a special character. Its parameters are:

Parameter	Description
charValue	specifies the ASCII value of the character being set. It may be signed or unsigned. If it is not in the range 0 to 255, then the method does nothing.
status	Specifies the status to be set. If it is nonzero, the SpecialFlag is turned on for the character, else all status flags are turned off.

The method returns the previous special status of the character.

The method Character_Shiftleft

Prototype

void Character_ShiftLeft(char* String, int nShift);

The Character_ShifLeft method shifts a null-terminated character string left a specified number of positions; thus removing the characters that are overwritten. The most common error in using this method involves forgetting that the string must be null-terminated. Its parameters are:

Parameter	Description
String	Contains the string to be shifted in null-terminated form and receives the shifted string.
nShift	Specifies the number of positions to shift.

The method Character_ShiftRight

Prototype

void Character_ShiftRight(char* String, int nShift, int fill);

The Character_ShiftRight method shifts a character string right a specified number of places. The spaces thus created are set equal to the specified fill character. This method is typically used during the detailed editing of displays during various numeric conversions. The most common error in using this service involves forgetting that the string must be null-terminated. Its parameters are:

Parameter	Description
String	Contains the string to be shifted and receives the shifted string.
nShift	Specifies the number of positions to shift.
fill	Specifies the fill character to be used.

The method Character_ShortFromHex

Prototype

int Character_ShortFromHex(char* String,int Length);

The Character_ShortFromHex method converts an alphanumeric string in hexadecimal notation to a short integer 4-byte value. The actual computation of the value is done using a longlong internal value. If the string is longer than 7 characters and begins with “8”, then it is assumed to be negative. Its parameters are:

Parameter	Description
String	Contains the hexadecimal value to be determined. This string is assumed to be null-terminated only if the length parameter is zero.
Length	Specifies the length of the string representation or zero.

The method returns the computed short value. If the representation is not well-formed, it returns the value as computed when a problem character is encountered.

The method Character_ShortFromOctal

Prototype

int Character_ShortFromOctal(char* String,int Length);

The Character_ShortFromOctal method converts an alphanumeric string to an octal short integer 4-byte value. Its parameters are:

Parameter	Description
String	Contains the integer value to be determined.
Length	Specifies the number of characters in the string.

The method returns the computed integer value.

The method Character_ShortFromString

Prototype

int Character_ShortFromString(char** StringPtr,int blank);

The Character_ShortFromString method extracts a short integer 4-byte value from a string. It converts an alphanumeric string to an integer value via a pointer to a pointer to a string. That pointer is then updated to point to the position beyond the end of the integer representation. Its parameters are:

Parameter	Description
StringPtr	Specifies to the location of a pointer to the start of the string. This location is updated to point immediately beyond the last character of the integer value.
blank	Contains the blanks convention to be used. If it has a value of zero, then blanks terminate the string like any other non-numeric character; if positive, then blanks are simply ignored; and if negative, then blanks have the value of “zero”.

The method updates the string pointer and returns the computed integer value.

The method Character_Substr

Prototype

int Character_Substr(char* strValue,int iStart,int length,char* buffer);

The Character_Substr method forms a new string by extracting a substring from a supplied one. Its parameters are:

Parameter	Description
strValue	Contains the supplied source string. It need be null-terminated only if the specified substring length is less than or equal to zero,
iStart	Specifies the starting offset in the source string, relative to zero, of the start of the substring.
length	Specifies the desired length of the substring. If it is negative or zero, then it is added to the length of the source string to determine its final value.
buffer	Receives the new string in null-terminated form.

The method returns the length of the new string.

The method Character_ToDate

Prototype

int Character_ToDate(char* String,int nString);

The Character_ToDate method converts a variety of date-formats into an integer Julian date value. The five formats recognized are:

Seq	Format
1	mm/dd/year
2	mm-dd-year
3	Mon dd year
4	dd Mon year
5	yyy-mm-dd

Where:

Symbol	Description
dd	is a one or two digit day value
mm	is a one or two digit month value
Mon	is one of the standard 3-letter abbreviations of a month — Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec. Note that case is ignored.
year	is a two-digit or four-digit year value. Two-digit values are assumed to be in the 1900s if they are less than the cross-over value; otherwise they are assumed to be in the 2000s. The current setting for this value is 60.

The date value itself is computed as the number of days since the Julian day zero, by default December 31, 1967 (see the DateTime service class for details). Its parameters are:

Parameter	Description
String	Contains the date to be computed in string form. It need not be null-terminated.
nString	Specifies the length of the date string.

The method returns the integer value of the date computed as described above.

The method Character_ToDateTime

Prototype

longlong Character_ToDateTime(char* String,int nString);

The Character_ToDateTime method converts a date/time string into a long value equal to the number of seconds since the Julian day zero, by default December 31, 1967 (see the DateTime service class for details). The format is a valid date followed by whitespace followed by a valid time. See the methods Character_ToDate and Character_ToTime for a description of these valid formats. Its parameters are:

Parameter	Description
String	Contains the date/time string to be converted.
nString	Specifies the length of the string.

The method returns the long 8-byte integer value of date/time computed as described above.

The method Character_ToDouble

Prototype

double Character_ToDouble(char *str,int nstr);

The Character_ToDouble method converts an alphanumeric string containing a number in scientific notation to a double precision floating point value. The string can contain optional leading blanks, an integer part, a fractional part, and an exponent part. The integer part consists of an optional sign followed by zero or more decimal digits. The fractional part is a decimal point followed by zero or more decimal digits. The exponent part consists of an ‘E’, ‘e’, ‘D’, ‘d’, ‘Q’, or ‘q’ followed by an optional sign and a sequence of decimal digits. Its parameters are:

Parameter	Description
str	Contains the alphanumeric string to be converted. It need not be null-terminated.
nstr	Specifies the number of characters in the string.

The method returns the double precision value of the string.

The method Character_ToLong

Prototype

longlong Character_ToLong(char* String,int nString,int nDecimal);

The Character_ToLong method obtains a long value from a character string. It converts an alphanumeric string to a long integer 8-byte value. If the string contains no decimal point the value is increased by the power of ten indicated. If the string contains decimal places then they must match the number specified. Note that this method accepts negative value representations; however, a leading minus sign must be used. Its parameters are:

Parameter	Description
String	Contains the integer value to be determined. This string is assumed to be null-terminated only if the nString parameter is zero.
nString	Specifies the length of the string representation. If this is zero, then the String parameter is assumed to encompass the value and to be null-terminated.
nDecimal	Specifies the number of assumed decimal places in the value. The string must contain either no decimal places or exactly this many decimal places.

The method returns the computed long value. If the representation was not well-formed, then an error code is set that may be retrieved via the Character_ErrorCode field. The error codes set by this method are:

Code	Meaning
CharacterError_WrongDec	The string had the wrong number of decimal places
CharacterError_BadDigits	The string contained non-numeric digits

The method Character_ToLower

Prototype

void Character_ToLower(char* String,int ns);

The Character_ToLower method forces the case of any alphabetic characters contained in a specified string to be lower-case. Characters that are not alphabetic or that already have lower-case are not changed. Its parameters are:

Parameter	Description
String	Contains the characters to be converted and receives the converted characters. It is not assumed to be null-terminated.
ns	Specifies the number of characters to be considered for conversion.

The method Character_ToShort

Prototype

int Character_ToShort(char* String,int nString,int nDecimal);

The Character_ToShort method obtains a short value from a character string. It converts an alphanumeric string to a short integer 4-byte value. If the string contains no decimal point the value is increased by the power of ten indicated. If the string contains decimal places then they must match the number specified. Note that this method accepts negative value representations; however, a leading minus sign must be used. Its parameters are:

Parameter	Description
String	Contains the integer value to be determined. It is assumed to be null-terminated only if the nString parameter is zero.
nString	Specifies the length of the string representation. If this is zero, then the String parameter is assumed to encompass the value and to be null-terminated.
nDecimal	Specifies the number of assumed decimal places in the value. The string must contain either no decimal places or exactly this many decimal places.

The method returns the computed short 4-byte integer value. If the representation was not well-formed, then an error code is set that may be retrieved via the Character_ErrorCode field. The error codes set by this method are:

Code	Meaning
CharacterError_WrongDec	The string had the wrong number of decimal places
CharacterError_BadDigits	The string contained non-numeric digits

The method Character_ToTime

Prototype

int Character_ToTime(char* String,int nString);

The Character_ToTime method converts a time string into an integer value equal to the number of seconds since midnight. The two formats recognized are:

Seq	Format
1	hh:mm:ss
2	hh:mm

Where:

Symbol	Meaning
hh	is a one or two digit hour value
mm	is a one or two digit minute value
ss	is a one or two digit second value

If ss is omitted, a value of 0 is assumed. Its parameters are:

Parameter	Description
String	Contains the time to be computed.
nString	Specifies the length of the time string.

The method returns the value of time computed as described above. If the representation was not well-formed, then an error code is set than may be retrieved via the Character_ErrorCode field. The error codes set by this method are:

Code	Meaning
CharacterError_BadDigits	The string contained non-numeric digits
CharacterError_BadTimeSeparator	The values were not separated by colons.

The method Character_ToUpper

Prototype

void Character_ToUpper(char* String,int ns);

The Character_ToUpper method forces the case of any alphabetic characters contained in a specified string to be upper-case. Characters that are not alphabetic or that already have upper-case are not changed. Its parameters are:

Parameter	Description
String	Contains the characters to be converted and receives the converted characters. It is not assumed to be null-terminated.
ns	Specifies the number of characters to be considered for conversion.

The method Character_Unpack

Prototype

int Character_Unpack(UBYTE* strValue,int nStrValue,int iStart,char* buffer);

The Character_Unpack method extracts a specified string from a set of strings packed into a single string instance. Its parameters are:

Parameter	Description
strValue	Contains the packed set of strings.
nStrValue	specifies the length of the packed string.
iStart	Specifies the index relative to one of the desired string.
buffer	Receives the unpacked string.

The method returns the length of the unpacked string.