Return to Main Page
This statement inserts the ' character.
FUNCTION $Quote: '''';
Inspects and alters the display format for Boolean values.
FUNCTION BooleanFormat [ ( VAL format: INTEGER ) ] : INTEGER;
Argument Name | Description |
format | If provided, this argument replaces the default format |
This function inspects and alters the default format used whenever a value of this type is converted into a text form.
If called with no argument, BooleanFormat returns the existing default Boolean display format. If an argument is provided, that value replaces the current default, and the old format is returned.
See the Notes section of the WinWrite statement for an explanation of display formats.
VARIABLES
oldFormat: INTEGER; ACTIONS oldFormat:= BooleanFormat(BitOr($FmtBoolYesNo, $FmtLeftJustify));
...
BooleanFormat(oldFormat); END;
Converts an ASCII character code (code point value) to a one-character string. The actual appearance of this string can vary, depending on the currently active code page. For information on code pages, see your operating system documentation.
FUNCTION Char (VAL code: INTEGER): STRING;
Argument Name | Description |
code | Integer representing an ASCII value |
VARIABLES s: STRING; ACTIONS s:=Char(255);
CharCode
Returns the ASCII character code (code point value) of the first character in a character string. The numeric value of the code point that is returned for a given character representation can vary, depending on the currently selected code page. For information on code pages, see your operating system documentation.
FUNCTION CharCode (VAL str: STRING): INTEGER;
Argument Name | Description |
str | This is any string |
The str argument is treated as a one-character string. If you insert a multi-character string, the ASCII character code of the first character in the string is returned.
i := CharCode('A'); (* i = 65 *)
Char
Inspects and alters the text format of integer values.
FUNCTION IntegerFormat [ ( VAL format: INTEGER ) ] : INTEGER;
Argument Name | Description |
format | If provided, this argument replaces the default format |
This function inspects and alters the default format used whenever a value of this type is converted into a text form.
If called with no argument, IntegerFormat returns the default. If an argument is provided, that value replaces the current default, and the previous default is returned.
VARIABLES oldFormat: INTEGER; ACTIONS oldFormat := IntegerFormat(BitOr(IntegerFormat, $FmtIntSigned)); -- Prepend the sign to all integers.
...
IntegerFormat(oldFormat); END;
IntegerFormat does not return any codes. Like the value returned by StringFormat, the value returned by IntegerFormat is the previous value of the format flag's bit-array. The value can be treated as an integer because TSD Script lacks a bit-array type. The sign of the value has no significance.
For an explanation of display formats, see Data Type Format Flags.
Inspects or alters the default text format for real values.
FUNCTION RealFormat [ ( VAL format: INTEGER ) ] : INTEGER;
Argument Name | Description |
format | If provided, this argument replaces the default format |
This function inspects and alters the default format used whenever a value of this type is being converted into a text form. If called with no argument, it returns the existing default. If an argument is provided, that value becomes the default. The original default is returned.
CONSTANTS sigDigits IS 2; -- Two digits to the right of the decimal. VARIABLES oldFormat: INTEGER; ACTIONS oldFormat := RealFormat(BitOr($FmtRealGroupedWithComma, sigDigits));
...
RealFormat(oldFormat); END;
Return Code | Description |
Any | Current real format if no argument was specified; old real format if an argument was provided. |
For more information, see Data Type Format Flags.
Returns a substring from a string expression.
FUNCTION StrCopy (VAL source: STRING, VAL start [, length]: INTEGER): STRING;
Argument Name | Description |
source | The string expression from which a substring is to be copied. |
start | The 1-based index of the first character to be copied. If the start value is less than 1, StrCopy fails and returns an unknown value. If the start value is greater than the length of the string, StrCopy returns an empty string. |
length | The number of characters to copy to the new string. If length is less than 0, StrCopy returns $Unknown. If length is greater than the available characters, all available characters are copied. |
StrCopy copies length characters from the source string and returns them. Copying begins with the character at the start position. If the start position is greater than the number of characters in the string, an empty string is returned.
VARIABLES drive,path,fileName: STRING; ACTIONS drive:=StrCopy('F:\ADVISOR\DATA\LOCATION.FLD',1,2); (* drive = 'F:'); path:=StrCopy('F:\ADVISOR\DATA\LOCATION.FLD',3,13); (* path = '\ADVISOR\DATA'): fileName:=StrCopy('F:\ADVISOR\DATA\LOCATION.FLD',17,12); (* fileName = 'LOCATION.FLD' *)
Decrypts a string encrypted by StrEncrypt with the given key value.
FUNCTION StrDecrypt (VAL Source: STRING, VAL Key: INTEGER): STRING;
Caution: Incorrect strings return the wrong integer key passes to StrDecrypt.
Argument Name | Description |
Source | The string that was previously encrypted with a call to StrEncrypt |
Key | An integer value to use as the secret key when decrypting the string |
The encryption algorithm of StrDecrypt and StrEncrypt is not particularly secure, but is acceptable for non-critical encryptions.
(* Function FCryptReadIn: This funciton reads an encrypted string from a file and decrypts it.
*)
FUNCTION FCryptReadIn(VAL Key:Integer, VAL fhdl:FILE):STRING IS
VARIABLES TmpStr: STRING;
ACTIONS FReadLn(fhdl, TmpStr); $Result:=StrDecrypt(TmpStr,Key);
END;
Return Code | Description |
Decrypted String | Successful completion |
$Unknown | The call to StrDecrypt failed |
StrEncrypt
Deletes a substring from a string.
FUNCTION StrDelete (VAL source:string, VAL start: Integer, VAL length: Integer):string
Argument Name | Description |
source | The string from which the substring is deleted. |
start | The location to begin deleting characters from. If the start value is less than 0, the deletion fails and $Unknown is returned. If the start value is greater than the length, no characters are deleted and the original string is returned. |
length | The number of characters to delete. If length is less than 0, StrDelete fails and $Unknown is returned. |
StrDelete returns a copy of the source string with a specified range of characters removed. The source string is not affected.
VARIABLES s: STRING; ACTIONS s:=StrDelete('F:\ADVISOR\DATA.DAT',1,11); (* s = 'DATA.DAT' *)
StrDelete returns a copy of the input string with the specified range of characters removed. If there is any kind of error in the input arguments, it returns $Unknown.
Encrypts a string into an unreadable format using an integer key.
FUNCTION StrEncrypt (VAL Source: STRING, VAL Key: INTEGER): STRING;
Argument Name | Description |
Source | The string that needs to be encrypted |
Key | An integer value used as the secret key when encrypting a string |
The encryption algorithm of StrDecrypt and StrEncrypt is not particularly secure, but is acceptable for non-critical encryptions.
(* Function FCryptWriteIn: This funciton writes a string to a file in an encrypted form.*)
FUNCTION FCryptWriteIn(VAL Str:String, VAL Key:Integer, VAL fhdl:FILE):INTEGER IS
ACTIONS $Result:=FWriteLn(fhdl, StrEncrypt(Str,Key));
END;
Return Code | Description |
$Unknown | The call to StrEncrypt failed |
StrDecrypt
Inspects or alters the default string formatting options.
FUNCTION StringFormat [ ( VAL format: INTEGER ) ] : INTEGER;
Argument Name | Description |
format | If provided, this argument replaces the default format |
This function is used to inspect and alter the default format used whenever a value of this type is converted into a text form.
If called with no argument, it returns the existing default. If an argument is provided, that value becomes the new default. The previous default is returned.
VARIABLES oldFormat: INTEGER; ACTIONS oldFormat := StringFormat($FmtLeftJustify); ... StringFormat(oldFormat); END;
StringFormat returns the previous value of the string format bit array. This return value can be passed back to StringFormat later. For example:
oldFormat :=StringFormat (newFormat); ... --output some strings ... StringFormat (oldFormat) ;
For an explanation of display formats, see the Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide.
Inserts a substring into a string.
FUNCTION StrInsert (VAL source, substring: STRING, VAL start: INTEGER): STRING;
Argument Name | Description |
source | The string into which the substring is inserted. |
substring | The string to insert into the source string. |
start | The location where the substring is inserted into the target. If the start location is less than 1, StrInsert fails and $Unknown is returned. If the start location is greater than the length of the target string, the substring is appended to the end of the target string. |
StrInsert inserts a substring into a source string at a given position. The insert takes place so the first character in the inserted substring ends at the index indicated by the position.
Note: The spliced string is returned as the result of StrInsert with the input strings unchanged.
VARIABLES s: STRING; ACTIONS s:=StrInsert('F:\DATA.TXT','\ADVISOR',3); (* s = 'F:\ADVISOR\DATA.TXT' *)
StrInsert returns a copy of the target string with the substring inserted, beginning at the given index. If any kind of error is encountered in the arguments, the statement returns $Unknown.
Returns the length of a string.
FUNCTION StrLength (VAL str: STRING): INTEGER;
Argument Name | Description |
string | A string expression whose length is to be calculated |
StrLength returns an integer indicating the number of characters in the input expression. Returns $Unknown if the string is $Unknown.
VARIABLES i: INTEGER; path,fileName: STRING; ACTIONS path:='F:\EADVISOR'; fileName:='KMLRUN.EXE'; i:=StrLength(path & '\' & fileName); (* i = 22 *)
Return Code | Description |
> = 0 | An integer that indicates the number of characters in the input expression |
$Unknown | If the string is $Unknown, so is the return value |
Loads a string from a string table in a .df file created by the Interface Designer.
FUNCTION StrLoad (VAL formspec: STRING): STRING;
Argument Name | Description |
formspec | A form specification of the format 'file[res_name]' where file is the name of a .dfc file and res_name is the name of the string resource in the string table. |
If the string cannot be found or the file cannot be found, the result of the function call is $Unknown.
KNOWLEDGEBASE test;
ROUTINES PROCEDURE Main;
PRIVATE
ROUTINES
PROCEDURE Main IS VARIABLES x: STRING; ACTIONS x := StrLoad('test[test_string]'); WinMessageBox($Desktop, 'Information', $MBOK, 'The string is ' & x); END;
Converts a string to lowercase.
FUNCTION StrLower (VAL str: STRING): STRING;
Argument Name | Description |
str | A string expression |
VARIABLES s: STRING; ACTIONS s:=StrLower('F:\MYFILE.TXT'); (* s = 'f:\myfile.txt' *)
StrLower returns a copy of the input string in which every uppercase character has been converted to lowercase. The input string is unchanged.
StrUpper
Trims leading spaces, tabs, and new line characters from a string.
FUNCTION StrLTrim (VAL str: STRING): STRING;
Argument Name | Description |
str | A string expression |
VARIABLES s: STRING; ACTIONS s:=StrLTrim('F:\DATA.TXT'); (* s = 'F:\DATA.TXT' *)
Returns a copy of the input string with all leading spaces, tabs, and new line characters removed. The input string is not changed.
StrTrim
Searches a string for a substring pattern.
FUNCTION StrMatch (VAL source, VAL pattern: STRING): BOOLEAN;
Caution: The search is not case-sensitive.
Argument Name | Description |
source | A string expression to be searched. |
pattern | A string expression optionally containing wildcards such as ? and *. |
StrMatch compares the source string with the pattern. The pattern may contain wildcards:
The match is not case-sensitive.
VARIABLES f: FILE; l: LIST OF STRING; match: LIST OF STRING; ACTIONS FOpen(f,'MYFILE.TXT',$Read); FReadText(f,l); FClose(f); FOR l DO IF StrMatch(l[$Current],'*printer*') THEN ListInsert(match,l[$Current]); END;
StrMatch returns TRUE if the source and pattern strings match and FALSE otherwise.
Finds the position of a substring in a string,
FUNCTION StrPos (VAL source, VAL substring: STRING): INTEGER;
Argument Name | Description |
source | A string expected to contain the substring |
Substring | A string of characters in the source string |
StrPos does a case-insensitive scan from the beginning of the input string until it finds the target string. If the target is found, StrPos returns the index in the input string where the match occurred. Otherwise it returns zero.
VARIABLES i: INTEGER; ACTIONS i:=StrPos(F:\DATA\MYFILE.DAT','\'); (* i = 3 *)
Return Code | Description |
0 | The substring is not found |
-1 | The source string is unknown |
-2 | The substring is unknown |
StrToken
Replaces term designations within a source string with the appropriate terminology values.
FUNCTION StrReplaceTerms (VAL source: STRING): STRING;
Caution: If the named variable does not exist, or if its value cannot be converted into a string, a warning box appears and the term designation is not replaced in the result string.
Argument Name | Description |
source | A string containing zero or more embedded term designations. |
A term designation is an embedded substring with the form:
{{KNOWLEDGEBASE:VARIABLE}}
where KNOWLEDGEBASE is the name of a knowledgebase, and VARIABLE is the name of a variable declared in the outermost scope of that knowledgebase. The named variable does not have to be declared in the public section of the knowledgebase.
All such forms embedded in the source string are replaced by the value of the named variable. The source string is not modified by this function.
msg := StrReplaceTerms( 'The {{GLOBALS:T_CALLER}} has no open {{GLOBALS:T_PROBLEMS}}.'); -- T_CALLER and T_PROBLEMS from GLOBALS.KB contain 'caller' -- and 'problems' respectively, or synonyms such as 'customer' -- and 'inquires'.
StrReplaceTerms returns the modified string. If the source string is unknown, StrReplaceTerms returns $Unknown.
Destructively tokenizes a string.
FUNCTION StrToken (REF source: STRING, VAL delimiters: STRING): STRING;
Argument Name | Description |
source | A string variable to be tokenized |
delimiters | A string containing one or more delimiting characters |
The StrToken function divides the entire character set into two disjoint subsets: characters that are members of tokens (the token set) and those that are not members of tokens (the delimiting set). When you call StrToken on a known source string, this statement does the following:
As a result of this process, the source string becomes shorter each time this function is called, eventually becoming an empty string. When no more tokens exist in the source string, StrToken returns the empty string.
WHILE NOT FEnd (inputFile) DO FReadLn (inputFile, inputLine); column := 0; WHILE (token := StrToken (inputLine,'')) <> ''DO ProcessEntry (token, column :=column +1); END; END;
This function returns $Unknown if either the source string or the delimited string is unknown.
StrPos
Removes trailing white space from a string.
FUNCTION StrTrim (VAL str: STRING): STRING;
Argument Name | Description |
str | A string expression |
StrTrim takes a string as input and returns a copy of that string with all trailing white space (spaces, tabs, new lines) removed. The input string is not affected.
VARIABLES f: FILE; l: LIST OF STRING; ACTIONS FOpen(f,'DATA.TXT',$Read); FReadText(f,l); FClose(f); FOR l DO l[$Current]:=StrTrim(l[$Current]);
StrTrim returns a copy of an input string with all trailing white space (spaces, tabs, new lines) removed.
StrLTrim
Returns an uppercase copy of a string.
FUNCTION StrUpper (VAL str: STRING): STRING;
Argument Name | Description |
str | A string expression |
StrUpper returns a copy of the input string with all lowercase characters converted to uppercase. The input string is unchanged.
VARIABLES s: STRING; ACTIONS s:=StrUpper('f:\data\myfile.txt'); (* s = 'F:\DATA\MYFILE.TXT' *)
StrUpper returns a copy of the input string with all lowercase characters converted to uppercase.
StrLower
Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference