String Manipulation

Return to Main Page


$Quote

Description

This statement inserts the ' character.

Syntax

FUNCTION $Quote: '''';

BooleanFormat

Description

Inspects and alters the display format for Boolean values.

Syntax

FUNCTION BooleanFormat [ ( VAL format: INTEGER ) ] : INTEGER;

Argument Notes

Argument Name Description
format If provided, this argument replaces the default format

Notes

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.

Example

VARIABLES
 oldFormat: INTEGER;
ACTIONS
 oldFormat:= BooleanFormat(BitOr($FmtBoolYesNo, $FmtLeftJustify));
 ...
 BooleanFormat(oldFormat);
END;

See Also


Char

Description

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.

Syntax

FUNCTION Char (VAL code: INTEGER): STRING;

Argument Notes

Argument Name Description
code Integer representing an ASCII value

Example

VARIABLES
s: STRING;
ACTIONS
s:=Char(255);

See Also

CharCode


CharCode

Description

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.

Syntax

FUNCTION CharCode (VAL str: STRING): INTEGER;

Argument Notes

Argument Name Description
str This is any string

Notes

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.

Example

i := CharCode('A'); (* i = 65 *)

See Also

Char


IntegerFormat

Description

Inspects and alters the text format of integer values.

Syntax

FUNCTION IntegerFormat [ ( VAL format: INTEGER ) ] : INTEGER;

Argument Notes

Argument Name Description
format If provided, this argument replaces the default format

Notes

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.

Example

VARIABLES
oldFormat: INTEGER;
ACTIONS
oldFormat := IntegerFormat(BitOr(IntegerFormat, $FmtIntSigned));
 -- Prepend the sign to all integers.
 ...
 IntegerFormat(oldFormat);
END;

Return Codes

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.

See Also

For an explanation of display formats, see Data Type Format Flags.


RealFormat

Description

Inspects or alters the default text format for real values.

Syntax

FUNCTION RealFormat [ ( VAL format: INTEGER ) ] : INTEGER;

Argument Notes

Argument Name Description
format If provided, this argument replaces the default format

Notes

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.

Example

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 Codes

Return Code Description
Any Current real format if no argument was specified; old real format if an argument was provided.

See Also

For more information, see Data Type Format Flags.


StrCopy

Description

Returns a substring from a string expression.

Syntax

FUNCTION StrCopy (VAL source: STRING, VAL start [, length]: INTEGER): STRING;

Argument Notes

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.

Notes

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.

Example

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' *)

StrDecrypt

Description

Decrypts a string encrypted by StrEncrypt with the given key value.

Syntax

FUNCTION StrDecrypt (VAL Source: STRING, VAL Key: INTEGER): STRING; 

Caution: Incorrect strings return the wrong integer key passes to StrDecrypt.

Argument Notes

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

Notes

The encryption algorithm of StrDecrypt and StrEncrypt is not particularly secure, but is acceptable for non-critical encryptions.

Example

(*
 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 Codes

Return Code Description
Decrypted String Successful completion
$Unknown The call to StrDecrypt failed

See Also

StrEncrypt


StrDelete

Description

Deletes a substring from a string.

Syntax

FUNCTION StrDelete (VAL source:string,
                    VAL start: Integer,
                    VAL length: Integer):string

Argument Notes

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.

Notes

StrDelete returns a copy of the source string with a specified range of characters removed. The source string is not affected.

Example

VARIABLES
s: STRING;
ACTIONS
s:=StrDelete('F:\ADVISOR\DATA.DAT',1,11);
(* s = 'DATA.DAT' *)

Return Codes

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.


StrEncrypt

Description

Encrypts a string into an unreadable format using an integer key.

Syntax

FUNCTION StrEncrypt (VAL Source: STRING, VAL Key: INTEGER): STRING;

Argument Notes

Argument Name Description
Source The string that needs to be encrypted
Key An integer value used as the secret key when encrypting a string

Notes

The encryption algorithm of StrDecrypt and StrEncrypt is not particularly secure, but is acceptable for non-critical encryptions.

Example

(* 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 Codes

Return Code Description
$Unknown The call to StrEncrypt failed

See Also

StrDecrypt


StringFormat

Description

Inspects or alters the default string formatting options.

Syntax

FUNCTION StringFormat [ ( VAL format: INTEGER ) ] : INTEGER;

Argument Notes

Argument Name Description
format If provided, this argument replaces the default format

Notes

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.

Example

VARIABLES
 oldFormat: INTEGER;
ACTIONS
 oldFormat := StringFormat($FmtLeftJustify);
 ...
 StringFormat(oldFormat);
END;

Return Codes

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) ;

See Also

For an explanation of display formats, see the Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide.


StrInsert

Description

Inserts a substring into a string.

Syntax

FUNCTION StrInsert (VAL source, substring: STRING,
 VAL start: INTEGER): STRING;

Argument Notes

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.

Notes

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.

Example

VARIABLES
s: STRING;
ACTIONS
s:=StrInsert('F:\DATA.TXT','\ADVISOR',3);
(* s = 'F:\ADVISOR\DATA.TXT' *)

Return Codes

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.


StrLength

Description

Returns the length of a string.

Syntax

FUNCTION StrLength (VAL str: STRING): INTEGER;

Argument Notes

Argument Name Description
string A string expression whose length is to be calculated

Notes

StrLength returns an integer indicating the number of characters in the input expression. Returns $Unknown if the string is $Unknown.

Example

VARIABLES
i: INTEGER;
path,fileName: STRING;
ACTIONS
path:='F:\EADVISOR';
fileName:='KMLRUN.EXE';
i:=StrLength(path & '\' & fileName);
(* i = 22 *)

Return Codes

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

StrLoad

Description

Loads a string from a string table in a .df file created by the Interface Designer.

Syntax

FUNCTION StrLoad (VAL formspec: STRING): STRING;

Argument Notes

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.

Notes

If the string cannot be found or the file cannot be found, the result of the function call is $Unknown.

Example

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;

StrLower

Description

Converts a string to lowercase.

Syntax

FUNCTION StrLower (VAL str: STRING): STRING;

Argument Notes

Argument Name Description
str A string expression

Example

VARIABLES
s: STRING;
ACTIONS
s:=StrLower('F:\MYFILE.TXT');
(* s = 'f:\myfile.txt' *)

Return Codes

StrLower returns a copy of the input string in which every uppercase character has been converted to lowercase. The input string is unchanged.

See Also

StrUpper


StrLTrim

Description

Trims leading spaces, tabs, and new line characters from a string.

Syntax

FUNCTION StrLTrim (VAL str: STRING): STRING;

Argument Notes

Argument Name Description
str A string expression

Example

VARIABLES
s: STRING;
ACTIONS
s:=StrLTrim('F:\DATA.TXT');
(* s = 'F:\DATA.TXT' *)

Return Codes

Returns a copy of the input string with all leading spaces, tabs, and new line characters removed. The input string is not changed.

See Also

StrTrim


StrMatch

Description

Searches a string for a substring pattern.

Syntax

FUNCTION StrMatch (VAL source, VAL pattern: STRING): BOOLEAN;

Caution: The search is not case-sensitive.

Argument Notes

Argument Name Description
source A string expression to be searched.
pattern A string expression optionally containing wildcards such as ? and *.

Notes

StrMatch compares the source string with the pattern. The pattern may contain wildcards:

The match is not case-sensitive.

Example

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;

Return Codes

StrMatch returns TRUE if the source and pattern strings match and FALSE otherwise.


StrPos

Description

Finds the position of a substring in a string,

Syntax

FUNCTION StrPos (VAL source, VAL substring: STRING): INTEGER;

Argument Notes

Argument Name Description
source A string expected to contain the substring
Substring A string of characters in the source string

Notes

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.

Example

VARIABLES
i: INTEGER;
ACTIONS
i:=StrPos(F:\DATA\MYFILE.DAT','\');
(* i = 3 *)

Return Codes

Return Code Description
0 The substring is not found
-1 The source string is unknown
-2 The substring is unknown

See Also

StrToken


StrReplaceTerms

Description

Replaces term designations within a source string with the appropriate terminology values.

Syntax

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 Notes

Argument Name Description
source A string containing zero or more embedded term designations.

Notes

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.

Example

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'.

Return Codes

StrReplaceTerms returns the modified string. If the source string is unknown, StrReplaceTerms returns $Unknown.


StrToken

Description

Destructively tokenizes a string.

Syntax

FUNCTION StrToken (REF source: STRING,
                   VAL delimiters: STRING): STRING;

Argument Notes

Argument Name Description
source A string variable to be tokenized
delimiters A string containing one or more delimiting characters

Notes

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.

Example

WHILE NOT FEnd (inputFile) DO
 FReadLn (inputFile, inputLine);
 column := 0;
 WHILE (token := StrToken (inputLine,'')) <> ''DO
 ProcessEntry (token, column :=column +1);
 END;
END;

Return Codes

This function returns $Unknown if either the source string or the delimited string is unknown.

See Also

StrPos


StrTrim

Description

Removes trailing white space from a string.

Syntax

FUNCTION StrTrim (VAL str: STRING): STRING;

Argument Notes

Argument Name Description
str A string expression

Notes

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.

Example

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]);

Return Codes

StrTrim returns a copy of an input string with all trailing white space (spaces, tabs, new lines) removed.

See Also

StrLTrim


StrUpper

Description

Returns an uppercase copy of a string.

Syntax

FUNCTION StrUpper (VAL str: STRING): STRING;

Argument Notes

Argument Name Description
str A string expression

Notes

StrUpper returns a copy of the input string with all lowercase characters converted to uppercase. The input string is unchanged.

Example

VARIABLES
s: STRING;
ACTIONS
s:=StrUpper('f:\data\myfile.txt');
(* s = 'F:\DATA\MYFILE.TXT' *)

Return Codes

StrUpper returns a copy of the input string with all lowercase characters converted to uppercase.

See Also

StrLower


Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Return to Main Page

Copyright