Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference
Return to Main Page
Returns a string containing the common character used to separate directory names in fully qualified file names. In Windows and OS/2, this is a backward slash ('\'). In UNIX, it is a forward slash ('/').
FUNCTION $DirSeprStr : STRING;
This function is useful for parsing fully qualified file names and directory names.
(* Function MakeFilename assembles a fully qualified filename given a list of directory names, a basename, and an extension.*)
FUNCTION MakeFilename(VAL Dir : LIST OF STRING, VAL Base : STRING, VAL Ext : STRING) : STRING IS
ACTIONS
$Result := '';
FOR Dir DO $Result := $Result & $DirSeprStr & Dir[$CURRENT]; END;
$Result := $Result & $DirSeprStr & Base & '.' & Ext; END;
$PathSeprStr
Returns a string containing the control characters used by the native operating system to indicate an end-of-line in a file. In Windows and OS/2, this string consists of the "carriage return" (ASCII 13) and "line feed" (ASCII 10) characters. In UNIX, this string consists of a "line feed" character.
FUNCTION $Newline : STRING;
Caution: When transferring files between operating systems, remember that the
native operating system might be expecting a different
end-of-line string than is in your file. If this occurs, your file may appear
misformatted.
This function is useful for writing formatted text to a file. The TSD Script function, FWriteLn, automatically appends the native end-of-line string to all lines written to a file.
(* Function WriteDates: This function writes a list of dates to a file with only one date per line. It returns the number of dates written.*)
FUNCTION WriteDates(VAL Dates : LIST OF DATE, VAL fhdl : FILE) : INTEGER IS
ACTIONS
$Result := 0; FOR Dates DO FWrite(fhdl, Dates[$CURRENT]); FWrite(fhdl, $NewLine); $Result := $Result + 1; END; END;
Returns a string containing the character used to separate directory names in paths containing multiple directory names. This is a semi-colon (';') in Windows and OS/2 and a colon (':') in UNIX.
FUNCTION $PathSeprStr: STRING;
This function is useful for parsing search paths.
(* Function MakePath assembles a complete path from a list of directories. *)
FUNCTION MakePath ( VAL Dirs : LIST OF STRING )
: STRING IS
ACTIONS $Result := '';
FOR Dirs DO $Result := $Result & Dirs[$CURRENT] & $PathSeprStr; END; END;
$DirSeprStr
Closes an open file.
FUNCTION FClose (VAL fHdl: FILE): INTEGER;
Argument Name | Description |
fHdl | The handle of an open file to be closed |
The FClose function causes the given file to be flushed (if it was open for output) and closed.
FUNCTION MakeLogEntry (VAL entry: STRING): INTEGER IS
CONSTANTS logFileName IS 'LOGFILE.TXT'; expirationLimit IS 30;
VARIABLES logFile: FILE; files: $DirectoryList;
ACTIONS IF FExists(logFileName) THEN FGetDirectory(logFileName, files); IF DateDif($Today, files[1].modificationDate) > expirationLimit THEN FErase(logFileName); END; END; IF FOpen(logFile, logFileName, $Append) < 0 THEN $Result := -1; ELSIF FWrite(logFile, $Today & ' ' & $Now & ': ' & entry) < 0 THEN $Result := -2; ELSIF FClose(logFile) > 0 THEN EXIT 1; END; FClose(logFile); END;
Return Code | Description |
1 | Successful completion. |
-1 | Operation failed. |
-2 | Unknown file argument. |
-6 | Invalid handle. |
FOpen
Indicates whether the open file is at the end of file.
FUNCTION FEnd (VALUE fHdl: FILE): BOOLEAN;
Caution: If the file argument is unknown, FEnd returns an unknown value.
Argument Name | Description |
fHdl | An expression yielding a handle to the file to be tested. |
The FEnd function returns TRUE if the given file is open for reading but is currently positioned at the end of the file (nothing more can be read). When FEnd returns FALSE, there is at least one more unread character in the file.
VARIABLES inFile: FILE; line: STRING;
ACTIONS FOpen(inFile,'EMPLOYEES.TXT',$Read); WHILE NOT FEnd(inFile) DO IF FReadLn(inFile,line) = 1 THEN GoProcess(line); END; END;
Return Code | Description |
TRUE | The given file is currently positioned at its end-of-file marker (in other words, there is no more input pending from the file). |
$Unknown | The argument evaluated to $Unknown. |
FALSE | The given file is not currently positioned at its end-of-file marker (in other words, input is pending). |
Erases a file.
FUNCTION FErase (VAL fileName: STRING): INTEGER;
Caution: The behavior of this function is undefined if the named file is open.
Argument Name | Description |
fileName | The name of the file to be erased |
The FErase function causes the file with the given name to be erased. Any subsequent attempt to open the file using the previous name fails.
FUNCTION MakeLogEntry (VAL entry: STRING): INTEGER IS CONSTANTS logFileName IS 'LOGFILE.TXT'; expirationLimit IS 30;
VARIABLES logFile: FILE; files: $DirectoryList;
ACTIONS IF FExists(logFileName) THEN FGetDirectory(logFileName, files); IF DateDif($Today, files[1].modificationDate) > expirationLimit THEN FErase(logFileName); END; END; IF FOpen(logFile, logFileName, $Append) < 0 THEN $Result := -1; ELSIF FWrite(logFile, $Today & ' ' & $Now & ': ' & entry) < 0 THEN $Result := -2; ELSIF FClose(logFile) > 0 THEN EXIT 1; END; FClose(logFile); END;
Return Code | Description |
1 | Successful completion |
-1 | Operation failed |
-2 | Unknown file argument |
FOpen
Tests for the existence of a file.
FUNCTION FExists (VAL fileName: STRING): BOOLEAN;
Argument Name | Description |
fileName | A string expression yielding a valid file name. |
If FExists ("C:\MYFILE.DAT") THEN DoProcessFile; ELSE DoCreateFile; END;
Return Code | Description |
TRUE | File exists |
FALSE | File does not exist |
Gets the native file system attributes associated with the given file.
FUNCTION FGetAttributes (VAL filename: STRING, REF attributes: INTEGER ) : INTEGER
Argument Name | Description |
filename | Full path to the file |
attributes | This parameter is altered to list the attributes of the given file. The
attributes that may be ordered together in the attributes variable are:
|
The following describes FGetAttributes attribute flags.
Attribute | Windows & OS/2 | UNIX |
$FILENOPRIVS | File is read-only | File is not readable, writeable, or executable |
$FILEREADABLE | File is not read-only | File is readable |
$FILEWRITEABLE | None | File is writeable |
$FILEEXECUTABLE | None | File is executable |
$FILEHIDDEN | File is hidden | None |
See example for FSetAttributes.
Return Code | Description |
1 | Successful completion |
-1 | Operation failed |
-2 | Argument unknown |
FSetAttributes
Creates a directory listing.
FUNCTION FGetDirectory(VAL pattern: STRING, REF directoryList: LIST OF $DIRECTORYRECORD) : INTEGER;
Argument Name | Description |
pattern | The pattern specifying which files are included in the directory listing. The * and ? wild card characters may be used. All files and directories whose names match the pattern are returned in the directory list. |
directoryList | This parameter must be a variable of type $DirectoryRecord. The definition is shown in the Notes section. |
$DirectoryRecord is a RECORD type declared in the system knowledgebase kml.kb. The declaration of $DirectoryRecord is:
$DirectoryRecord IS RECORD filename : STRING; fullname : STRING; filesize : INTEGER; modificationdate : DATE; modificationtime : TIME; isDirectory : BOOLEAN; readOnly : BOOLEAN; flags : INTEGER; END;
The following are field descriptions for $DirectoryRecord:
Name | Description |
fileName | The name of a file with extension. |
fullName | The full path filename. |
filesize | The size of a file in bytes. |
modificationDate | The date a file was last changed. |
modificationTime | The time a file was last changed. |
isDirectory | Indicates if this is a file or subdirectory. |
readOnly | Indicates if a file is writeable or not. |
flags | The file attributes. |
The flags field returns the flags set by the operating system and is platform-dependent. See your operating system documentation for flag meanings.
KNOWLEDGEBASE DirList; ROUTINES PROCEDURE TestDirectory(VAL pattern: LIST OF STRING);
PRIVATE ROUTINES PROCEDURE TestDirectory(VAL pattern: LIST OF STRING) IS
VARIABLES whdl: WINDOW; dirList: LIST OF $DIRECTORYRECORD;
ACTIONS WinCreateScrollWindow($Desktop,whdl, $NullHandler,0,0,60,0, pattern[1], $SystemMonospaced,10, $WinBorder + $WinTitle + $WinResize + $WinMinMax + $WinTaskList + $WinAutoSize + $WinHScroll + $WinVScroll + $WinSysMenu + $WinAutoPos);
FGetDirectory(pattern[1],dirList); ListSort(dirList); FOR dirList DO WinWrite(whdl,dirList[$CURRENT].fileName); WinGoToXY(whdl,20,WinY(whdl)); WinWrite(whdl,dirList[$CURRENT].fileSize); WinGoToXY(whdl,30,WinY(whdl)); WinWrite(whdl,dirList[$CURRENT].modificationDate); WinGoToXY(whdl,40,WinY(whdl)); WinWrite(whdl,dirList[$CURRENT].modificationTime); WinGoToXY(whdl,50,WinY(whdl)); IF dirList[$CURRENT].isDirectory THEN WinWrite(whdl,'Directory '); END; IF dirList[$CURRENT].readOnly THEN WinWrite(whdl,'Read only'); END; WinWriteLN(whdl); END; WinWait(whdl); END (* Test Directory *);
Return Code | Description |
Greater than or equal to zero | A non-negative value returned by FGetDirectory is the number of entries (files) in that directory. |
-1 | The directory request failed. The drive specified in the pattern may not exist or it may be unreadable. |
-2 | Unknown value. |
Opens a file.
FUNCTION FOpen (REF fHdl: File, VAL name: String [,$READ|$CREATE|$APPEND] ): Integer;
Argument Name | Description |
fHdl | This parameter is altered to refer to the opened file. If the FOpen operation fails, the parameter is set to $Unknown. |
name | An absolute or relative PATH to the file being opened. |
$READ $CREATE $APPEND |
Mode designation. The default is $READ. |
The FOpen function opens the text file with the given name in the given mode and associates it with the given fHdl value. If no mode argument is given, the default is $READ.
Tip: FOpen fails if the specified file is already open. The return value in this case is -1.
TSD Script does not support random access text files, so there is no way to read from and write to the same file without closing and reopening it with the appropriate mode between operations.
FUNCTION MakeLogEntry (VAL entry: STRING): INTEGER IS CONSTANTS logFileName IS 'LOGFILE.TXT'; expirationLimit IS 30;
VARIABLES logFile: FILE; files: $DirectoryList;
ACTIONS IF FExists(logFileName) THEN FGetDirectory(logFileName, files); IF DateDif($Today, files[1].modificationDate) > expirationLimit THEN FErase(logFileName); END; END; IF FOpen(logFile, logFileName, $Append) < 0 THEN $Result := -1; ELSIF FWrite(logFile, $Today & ' ' & $Now & ': ' & entry) < 0 THEN $Result := -2; ELSIF FClose(logFile) > 0 THEN EXIT 1; END; FClose(logFile); END;
Return Code | Description |
1 | Successful completion. |
-1 | The operation failed at the operating system level. This is returned if the specified file is already open. |
-2 | Unknown file name. |
Reads simple values from an open file and assigns them to the referenced variables.
FUNCTION FRead (VAL fHdl: FILE [, REF var: ANY SIMPLE TYPE...] ) : INTEGER;
Caution: Strings consume all input to the end of the line. Inserting input arguments after a string argument causes FRead to fail.
Argument Name | Description |
fHdl | A file handle set by a previous call to FOpen. FOpen must have been called in $READ mode. |
var | Zero or more assignable expressions (ones that may legally appear on the left side of an assignment operation). |
The FRead function reads simple values (such as BOOLEAN, INTEGER, REAL, STRING, TIME, and DATE) from the given file and assigns them to the associated variables from its argument list until values have been read for all of the given arguments.
The following table shows the formats in which FRead expects to read values:
Format | Description |
BOOLEAN | Either TRUE or FALSE. |
INTEGER | A sequence of decimal digits (0-9) interpreted as a decimal integer. The sequence '0x' or '0X' followed by one or more hexadecimal digits (0-9, A-F, or a-f) is interpreted as a hexadecimal integer. Either form may optionally be preceded by a '+' or '-' sign. |
REAL | A sequence of decimal digits (0-9) that may be preceded by a '+' or '-' sign. The sequence may be followed by a decimal point and one or more decimal digits, which may be followed by an exponent part. The exponent part consists of an 'E' or 'e', followed by an optional sign and one to three decimal digits. |
STRING | Any characters up to the end of the line. FRead does not read past the end of the line. |
TIME | A sequence in the format hh:mm:ss, where hh, mm, and ss are one or two decimal digits. |
DATE | A sequence in the format mm/dd/yy, where mm, dd, and
yy are one or two decimal digits. The FRead function terminates if either of
the following occurs:
|
Read Termination
If the read operation terminates, it does not process any further input. An error code is returned. Any arguments for which values have not been read are left unaltered by this error condition. Arguments for which values are successfully read are updated.
If a call to FRead terminates because the end of line was encountered, all subsequent calls to FRead fail without reading any values until the FReadLn function is called to advance to the next line.
White Space Delimiters
Wherever possible, the values in the input file should be delimited by one or more white space characters (spaces and tabs). However, under some circumstances, values may not require any delimiting characters.
For example, a REAL and a BOOLEAN value do not require intervening white space, since the characters that begin or end a BOOLEAN value cannot legally appear at either end of a real value, and vice versa.
PROCEDURE PlayTune (VAL fileName: STRING) IS VARIABLES toneFile: FILE; delay, frequency, duration: INTEGER;
ACTIONS IF FOpen(toneFile, fileName) 0 THEN EXIT; END;
WHILE FRead(toneFile, delay, frequency, duration) 0 DO SysDelay(delay); SysTone(frequency, duration); END; FClose(toneFile); END;
Return Code | Description |
1 | Successful completion |
-1 | Operation failed (conversion failure or premature end of line) |
-2 | Unknown file |
-4 | File not open |
-5 | End of file encountered |
-6 | Invalid handle. |
Reads one line of input from an open file, assigning the constituent simple values to the referenced variables.
FUNCTION FReadLn (VAL fHdl: FILE [, REF var: ANY SIMPLE TYPE... ] ): INTEGER;
Caution: Strings consume all input to the end of line. Therefore, providing input arguments after a string argument causes FReadLn to fail.
Argument Name | Description |
fHdl | A file handle set by a previous call to FOpen. FOpen must have been called in $READ mode. |
var | Zero or more assignable expressions. Assignable expressions appear on the left side of an assignment operation. |
The FReadLn function reads simple values (BOOLEAN, INTEGER, REAL, STRING, TIME, and DATE) from a file and assigns them all the associated variables from its argument list. Any characters remaining on the input line, including characters that designate the end of line, are discarded.
The following table shows the formats in which FReadLn expects to read values:
Format | Description |
BOOLEAN | Either TRUE or FALSE. |
INTEGER | A sequence of decimal digits (0-9) interpreted as a decimal integer. The sequence '0x' or '0X' followed by one or more hexadecimal digits (0-9, A-F, or a-f) is interpreted as a hexadecimal integer. Either form may optionally be preceded by a '+' or '-' sign. |
REAL | A sequence of decimal digits (0-9) that may be preceded by a '+' or '-' sign. The sequence may be followed by a decimal point and one or more decimal digits, which may be followed by an exponent part. The exponent part consists of an 'E' or 'e', followed by an optional sign and one to three decimal digits. |
STRING | Any characters up to the end of the line. FRead does not read past the end of the line. |
TIME | A sequence in the format hh:mm:ss, where hh, mm, and ss are one or two decimal digits. |
DATE | A sequence in the format mm/dd/yy, where mm, dd, and
yy are one or two decimal digits. The FRead function terminates if either of
the following occurs:
|
Termination
If the end of a line is reached before values are read for all of the given arguments, or if a value is read which cannot be converted into the appropriate type for the associated parameter, the read operation terminates without processing any further input (including the end of line designator).
Note: An error code is returned. Any arguments for which values have not been
read are left unaltered by this error condition.
Arguments for which values were successfully read are updated.
White Space Delimiters
Wherever possible, the values in the input file should be delimited by one or more white space characters (spaces and tabs). However, under some circumstances, values may not require any delimiting characters.
For example, a REAL and a BOOLEAN value do not require intervening white space, since the characters which begin or end a BOOLEAN value cannot legally appear at either end of a real value, and vice versa.
VARIABLES lineNumber{ 0 }: INTEGER; scriptFile, logFile: FILE; msgTime, actualTime: TIME; index, msgId: INTEGER; data: STRING;
ACTIONS IF FOpen(scriptFile, 'SCRIPT.TXT') < 0 THEN EXIT FAILCODE; END; IF FOpen(logFile, 'SCRIPT.LOG', $CREATE) < 0 THEN FClose(scriptFile); EXIT FAILCODE; END; WHILE NOT FEnd(scriptFile) DO lineNumber := lineNumber + 1; IF FReadLn(scriptFile, msgTime, index, msgId, data) <1 THEN FWriteLn(logFile, 'Invalid entry on line #' & lineNumber); ELSE SysDelay(TimeDif(msgTime, $Now) * 1000); actualTime := $Now; SendMsg(g_WindowArray[index], msgId, data); FWriteLn(logFile, actualTime & ': Sent ' & msgId & ' ' & $Quote & data & $Quote & ' to window #' & index); END; END; EXIT SUCCESSCODE; END;
Return Code | Description |
1 | Successful completion |
-1 | Operation failed (conversion failure or premature end of line) |
-2 | Unknown file |
-4 | File not open |
-5 | End of file encountered |
-6 | Invalid handle. |
Reads a file into a list of strings.
FUNCTION FReadText (VAL fHdl: FILE, REF lst: LIST OF STRING):INTEGER;
Argument Name | Description |
fHdl | Returns a handle to a file in that parameter |
lst | A list variable (string) whose contents are replaced by the contents of the file |
FReadText reads the contents of the file into a list of strings, one line per list element. If values are read from the file since it was opened, and before the call to FReadText, the remaining input is read.
Note: On successful completion, FReadText returns the number of lines successfully read.
KNOWLEDGEBASE Scroll; CONSTANTS MENU_OPEN IS 101; MENU_EXIT IS 102; MENU_LIST IS {'~File','~Open','E~xit',''}: LIST OF STRING;
TYPES EditorData IS RECORD statusLine: STRING; lines: LIST OF STRING; END;
ROUTINES PROCEDURE FileView;
PRIVATE ROUTINES EVENT EditorEvent(REF editorData: EditorData) IS ROUTINES PROCEDURE ProcessMainMenu(VALUE selection: INTEGER) IS VARIABLES fileName: STRING; editFile: FILE; result: INTEGER; ACTIONS WHEN selection IS MENU_OPEN THEN WinFileDialog($Handle,fileName,'*.KB',5,5, 'Select file to edit',0); IF FOpen(editFile,fileName,$Read) > 0 THEN FReadText(editFile,editorData.lines); FClose(editFile); editorData.statusLine := ' File: ' & fileName; WinClear($Handle); WinWriteLN($Handle,editorData.lines); PostMessage($Handle,$MsgPaintStatus); ELSWHEN MENU_EXIT THEN SendMessage($Handle,$MsgClose); END; END; END (* Process Main Menu *); ACTIONS WHEN $Event IS $MsgCreate THEN WinSetMenuBar($Handle, menuList); editorData.statusLine := 'File:'; ELSWHEN $MsgMenu THEN ProcessMainMenu($MenuSelection); ELSWHEN $MsgPaintStatus THEN (* Status Bar *) WinClear($Handle); WinWrite($Handle,editorData.statusLine); END; END (* Editor Event *); PROCEDURE FileView IS VARIABLES whdl: WINDOW; ACTIONS WinCreateScrollWindow($Desktop,whdl,EditorEvent,0,0,0,0, 'KML File viewer', $SystemMonospaced,10, BitOr($WinBorder,$WinTitle, $WinResize, $WinSysMenu, $WinMenu,$WinStatus, $WinAutoPos,$WinAutoSize, $WinVScroll,$WinHScroll, $WinTaskList)); WinWait(whdl); END (* File View *);
Return Code | Description |
Greater than zero | Success. Returns the number of bytes read. |
-1 | Unknown argument. |
-2 | Operation failed. |
-4 | File not open. |
-6 | Invalid handle. |
Sets the operating system level file attributes associated with the given file.
FUNCTION FSetAttributes (VAL filename: STRING, VAL attributes: INTEGER ): INTEGER
Argument Name | Description |
filename | Full path to the file |
attributes | This parameter is the list of the attributes to set on the given file.
The attributes that may be ordered together in the attributes variable are
|
The following describes FSetAttributes attribute flags.
Attribute | Meaning in Windows & OS/2 | UNIX |
$FILENOPRIVS | File is read-only | File is not readable, writeable, or executable |
$FILEREADABLE | File is not read-only | File is readable |
$FILEWRITEABLE | None | File is writeable |
$FILEEXECUTABLE | None | File is executable |
$FILEHIDDEN | File is hidden | None |
PROCEDURE MakeFileReadOnly IS
VARIABLES attributes : INTEGER; retval : INTEGER;
ACTIONS -- Get the current attributes retval := FGetAttributes('c:\sai\ea\mylog.txt', attributes); IF ( retval <> 1 ) THEN -- Handle the error' END; -- Turn on read-only attribute and apply retval := FSetAttributes('c:\sai\ea\mylog.txt', BitOr($FileReadOnly, attributes) ); END;
Return Code | Description |
1 | Successful completion |
-1 | Operation failed |
-2 | Argument unknown |
FGetAttributes
Writes formatted data to a file.
FUNCTION FWrite (VAL fHdl: FILE, VAL data: [LIST OF] STRING) : INTEGER;
Caution: No new line (end of line) character is written by FWrite at the completion of the output operation.
Argument Name | Description |
fHdl | A file variable set by a previous call to FOpen with the $Create or $Append write mode flag. |
data | A string expression (or a list of strings) that is to be written to the indicated file. |
The FWrite function writes simple values to the given file with no surrounding separator or terminator characters. Formatting of the output text may be accomplished through the use of the string formatting and concatenation operators ( : and & ).
FUNCTION MakeLogEntry (VAL entry: STRING): INTEGER IS CONSTANTS logFileName IS 'LOGFILE.TXT'; expirationLimit IS 30; VARIABLES logFile: FILE; files: $DirectoryList; ACTIONS IF FExists(logFileName) THEN FGetDirectory(logFileName, files); IF DateDif($Today, files[1].modificationDate) > expirationLimit THEN FErase(logFileName); END; END; IF FOpen(logFile, logFileName, $Append) < 0 THEN $Result := -1; ELSIF FWrite(logFile, $Today & ' ' & $Now & ': ' & entry) < 0 THEN $Result := -2; ELSIF FClose(logFile) > 0 THEN EXIT 1; END; FClose(logFile); END;
Return Code | Description |
>=0 | 0 - empty string was given as argument to the function, only carriage
return was written to the file n - positive number >0 which represents the number of lines written to the file |
-1 | Unknown argument |
-2 | Operation failed |
-4 | File not open |
-6 | Invalid handle |
Writes one line of formatted data to a file.
FUNCTION FWriteLn (VAL fHdl: FILE, VAL data: [LIST OF] STRING): INTEGER;
Argument Name | Description |
fHdl | A file variable set by a previous call to FOpen with a file mode of either $Create or $Append. |
data | A string expression or list of strings that are written out to the indicated file at the current file position. |
Like FWrite, the FWriteLn function writes simple values into a text file. FWriteLn differs from FWrite in that it outputs an end of line character after it has written its argument values (equivalent to $NewLine).
FUNCTION MakeLogEntry (VAL entry: STRING): INTEGER IS CONSTANTS logFileName IS 'LOGFILE.TXT'; expirationLimit IS 30; VARIABLES logFile: FILE; files: $DirectoryList; ACTIONS IF FExists(logFileName) THEN FGetDirectory(logFileName, files); IF DateDif($Today, files[1].modificationDate) > expirationLimit THEN FErase(logFileName); END; END; IF FOpen(logFile, logFileName, $Append) < 0 THEN $Result := -1; ELSIF FWriteLn(logFile, $Today & ' ' & $Now & ': ' & entry) < 0 THEN $Result := -2; ELSIF FClose(logFile) > 0 THEN EXIT 1; END; FClose(logFile); END;
Return Code | Description |
>=0 | 0 - empty string was given as argument to the function, only carriage
return was written to the file n - positive number >0 which represents the number of lines written to the file |
-1 | Unknown argument. |
-2 | Operation failed. |
-4 | File not open. |
-6 | Invalid handle. |
This function allows you to load and display a help file, such as WinHelp, IPF help (for OS/2), or HTML for all platforms. HelpOpen invokes the requested help file and displays the section name specified, the Help on Help section, or the Contents section.
For HTML help, the environment variable, "WebBrowser," must be specified. If this variable is not set, Windows uses the default browser, and UNIX and OS/2 use Netscape Navigator. If a relative URL is specified, the URL becomes an absolute URL by pre-pending the SAI_ROOT environment variable in native mode, or by pre-pending the Applet codebase when applications are enabled for web use.
FUNCTION HelpOpen( VAL whdl: WINDOW, VAL filename: String, [VAL section: STRING]): INTEGER;
Argument Name | Description |
whdl | This variable is the window handle of the parent window. |
filename | The file name of the help file that is to be opened. This variable can
contain information in one of the following formats:
|
section | The topic of the help file to display. This variable can be the name of
the section or one of the following two string constants:
|
The HelpOpen function starts the help file system and opens the help file to the specified section using the given file name and section. If the function is unsuccessful, the appropriate error code is returned.
KNOWLEDGEBASE HLPEXPL; CONSTANTS HLP IS 'C:\TEST.HLP'; VARIABLES ret: Integer; ROUTINES PROCEDURE TestHelp; PRIVATE ROUTINES PROCEDURE TestHelp IS VARIABLES ACTIONS ret := HelpOpen( $Desktop, HLP, $OSHelpOnHelp); If ret < 1 THEN WinMessageBox($Desktop, 'Help File Read Error', BitOr($MBOK , $MBIconInformation), 'Unknown error reading data from the help file.'); END; -- Test Help -- END OF HLPEXPL.KB
Return Code | Description |
1 | Successful completion. |
-1 | Unknown argument. |
-2 | The operation failed at the operating system level. |
-3 | Insufficient memory. |
-4 | The operation failed at the operating system level. This value is returned if the section parameter contains an unknown value. |
-5 | The help file system initialization failed. |
-6 | The help file system window association failed. |
-7 | The help file system object creation failed. |
-8 | The help file system was unable to display the file. |
This function reads data from an initialization file. It allows you to store and retrieve information in platform-native initialization files.
FUNCTION IniRead(REF rVal: [ STRING | INTEGER | BOOLEAN ], VAL filename: STRING, VAL section: STRING, VAL item: STRING, default: [STRING| INTEGER | BOOLEAN], [VAL filetype: STRING] ): INTEGER;
Argument Name | Description |
rVal | This variable can be a STRING, an INTEGER, or a BOOLEAN. It receives data read from the .ini file. |
filename | The file name of the .ini file that is to be read. This variable can
contain information in one of the following formats:
|
section | The section of the .ini file from which information is to be read. |
item | The item in the section of the .ini file from which information is to be read. |
default | This variable can be a STRING, an INTEGER, or a BOOLEAN. It contains the default data for rVal if the item being read cannot be found. |
The IniRead function reads the item from the initialization section using the given item, section, and name of the file. If the Item does not exist, the default value is placed in rVal.
KNOWLEDGEBASE EXPL; CONSTANTS INI IS 'C:\TEST.INI';
TYPES IniRecord IS Record Filename:String; FileSection:String; FileItem:String; ItemDefault:String; ItemRVal:String; ItemSData:String; ListSection: List of String; END;
VARIABLES Settings: IniRecord; ret: Integer;
ROUTINES PROCEDURE Read_From_Ini; PROCEDURE TestIni;
PRIVATE ROUTINES PROCEDURE Scan_From_Ini IS VARIABLES fh: FILE; ACTIONS ret := IniRead(Settings.ItemRVal, Settings.Filename, Settings.FileSection, Settings.FileItem, Settings.ItemDefault); if ret < 1 THEN WinMessageBox($Desktop, 'Ini File Read Error', $MBOK + MBIconInformation, 'Unknown error reading data from the file.'); END; END; -- Read from file PROCEDURE TestIni IS
ACTIONS Settings.Filename := INI; Settings.FileSection := 'section'; Settings.FileItem := 'item'; Settings.ItemDefault := 'default'; Settings.ItemSData := 'data'; Scan_From_Ini; WinMessageBox($Desktop, 'Status', $MBOK + MBIconInformation, 'Procedure was successful if no file error messages were reported.'); END; END
Return Code | Description |
1 | Successful completion |
-1 | Unknown argument |
-2 | The operation failed at the operating system level |
-5 | File not found |
This function obtains a list of items from a particular section of the initialization file.
FUNCTION IniScan(REF rVal: List of String, VAL filename: String, Val section: String, [Val filetype: String] ): Integer;
Argument Name | Description |
rVal | This variable is of type List of String. It receives a list of data read from the .ini file. |
filename | The file name of the .ini file to be read. This variable can contain
information in one of the following formats:
|
section | The section of the .ini file from which information is to be read. |
The IniScan function reads a list of items from the initialization section, using the given section and name of the file. If items do not exist, the appropriate error code is returned.
KNOWLEDGEBASE EXPL;
CONSTANTS INI IS 'C:\TEST.INI';
TYPES IniRecord IS Record Filename:String; FileSection:String; FileItem:String; ItemDefault:String; ItemRVal:String; ItemSData:String; ListSection: List of String; END;
VARIABLES Settings: IniRecord; ret: Integer;
ROUTINES PROCEDURE Scan_From_Ini; PROCEDURE TestIni;
PRIVATE
ROUTINES PROCEDURE Scan_From_Ini IS
VARIABLES fh: FILE; ACTIONS ret := IniScan(Settings.ListSection, Settings.Filename, Settings.FileSection); if ret < 1 THEN WinMessageBox($Desktop, 'Ini File Read Error', $MBOK + MBIconInformation, 'Unknown error reading data from the file.'); END; END; -- Scan from file
PROCEDURE TestIni IS VARIABLES
ACTIONS Settings.Filename := INI; Settings.FileSection := 'section'; Settings.FileItem := 'item'; Settings.ItemDefault := 'default'; Settings.ItemSData := 'data'; Scan_From_Ini;
WinMessageBox($Desktop, 'Status', $MBOK + MBIconInformation, 'Procedure was successful if no file error messages were reported.');
END;
Return Code | Description |
1 | Successful completion |
-1 | Unknown argument |
-2 | The operation failed at the operating system level |
-4 | No creation. The operating system was unable to create the requested object. One possible cause is that a parent window handle references a window that no longer exists. |
This function writes data to an initialization file.
FUNCTION IniWrite(Val filename: String, Val section: String, Val item: String, Val data:[String | Integer | Boolean ], ): Integer;
Argument Name | Description |
filename | The file name of the .ini file to which the data is written. This
variable can contain information in one of the following formats:
|
section | The section of the .ini file to which information is to be written. |
item | The item in the section of the .ini file to which information is written. |
data | This variable can be a STRING, an INTEGER, or a BOOLEAN. It contains the data written for the item of the specified section. |
The IniWrite function writes the item and data to the initialization section using the given item, section, and name of the file. If the item exists, its value is overwritten in the file.
KNOWLEDGEBASE EXPL;
CONSTANTS INI IS 'C:\TEST.INI';
TYPES IniRecord IS Record Filename:String; FileSection:String; FileItem:String; ItemDefault:String; ItemRVal:String; ItemSData:String; ListSection: List of String; END;
VARIABLES Settings: IniRecord; ret: Integer;
ROUTINES PROCEDURE Write_To_Ini; PROCEDURE TestIni;
PRIVATE ROUTINES
PROCEDURE Write_To_Ini IS VARIABLES fh: FILE; ACTIONS ret := IniWrite(Settings.Filename, Settings.FileItem, Settings.ItemSData); if ret < 1 THEN WinMessageBox($Desktop, 'Ini File Read Error', $MBOK + MBIconInformation, 'Unknown error reading data from the file.'); END; END; -- Write to file
PROCEDURE TestIni IS
VARIABLES
ACTIONS Settings.Filename := INI; Settings.FileSection := 'section'; Settings.FileItem := 'item'; Settings.ItemDefault := 'default'; Settings.ItemSData := 'data';
Write_To_Ini;
WinMessageBox($Desktop, 'Status', $MBOK + MBIconInformation, 'Procedure was successful if no file error messages were reported.');
END; -- END OF EXPL.KB
Return Code | Description |
1 | Successful completion |
-1 | Unknown argument |
-2 | The operation failed at the operating system level |
Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference
Return to Main Page