Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

File Handling

Return to Main Page


$DirSeprStr

Description

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 ('/').

Syntax

FUNCTION $DirSeprStr : STRING;

Notes

This function is useful for parsing fully qualified file names and directory names.

Example

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

See Also

$PathSeprStr


$NewLine

Description

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.

Syntax

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.

Notes

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.

Example

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

$PathSeprStr

Description

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.

Syntax

FUNCTION $PathSeprStr: STRING;

Notes

This function is useful for parsing search paths.

Example

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

See Also

$DirSeprStr


FClose

Description

Closes an open file.

Syntax

FUNCTION FClose (VAL fHdl: FILE): INTEGER;

Argument Notes

Argument Name Description
fHdl The handle of an open file to be closed

Notes

The FClose function causes the given file to be flushed (if it was open for output) and closed.

Example

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 Codes

Return Code Description
1 Successful completion.
-1 Operation failed.
-2 Unknown file argument.
-6 Invalid handle.

See Also

FOpen


FEnd

Description

Indicates whether the open file is at the end of file.

Syntax

FUNCTION FEnd (VALUE fHdl: FILE): BOOLEAN;

Caution: If the file argument is unknown, FEnd returns an unknown value.

Argument Notes

Argument Name Description
fHdl An expression yielding a handle to the file to be tested.

Notes

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.

Example

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 Codes

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

See Also


FErase

Description

Erases a file.

Syntax

FUNCTION FErase (VAL fileName: STRING): INTEGER;

Caution: The behavior of this function is undefined if the named file is open.

Argument Notes

Argument Name Description
fileName The name of the file to be erased

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion
-1 Operation failed
-2 Unknown file argument

See Also

FOpen


FExists

Description

Tests for the existence of a file.

Syntax

FUNCTION FExists (VAL fileName: STRING): BOOLEAN;

Argument Notes

Argument Name Description
fileName A string expression yielding a valid file name.

Example

If FExists ("C:\MYFILE.DAT") THEN
 DoProcessFile;
ELSE
 DoCreateFile;
END;

Return Codes

Return Code Description
TRUE File exists
FALSE File does not exist

See Also


FGetAttributes

Description

Gets the native file system attributes associated with the given file.

Syntax

FUNCTION FGetAttributes (VAL filename: STRING,
 REF attributes: INTEGER ) : INTEGER

Argument Notes

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:
  • $FILENOPRIVS
  • $FILEREADABLE
  • $FILEWRITEABLE
  • $FILEEXECUTABLE
  • $FILEHIDDEN

Notes

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

Example

See example for FSetAttributes.

Return Codes

Return Code Description
1 Successful completion
-1 Operation failed
-2 Argument unknown

See Also

FSetAttributes


FGetDirectory

Description

Creates a directory listing.

Syntax

FUNCTION FGetDirectory(VAL pattern: STRING, REF
 directoryList: LIST OF $DIRECTORYRECORD)
 : INTEGER;

Argument Notes

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.

Notes

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

Example

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 Codes

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.

See Also


FOpen

Description

Opens a file.

Syntax

FUNCTION FOpen (REF fHdl: File, VAL name: String
 [,$READ|$CREATE|$APPEND] ): Integer;

Argument Notes

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.

Notes

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.

Example

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 Codes

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.

See Also


FRead

Description

Reads simple values from an open file and assigns them to the referenced variables.

Syntax

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 Notes

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

Notes

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:
  • The end of the file or the end of the line is reached before values have been read for all the given arguments
  • A value is read that cannot be converted into the appropriate type for the associated parameter

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.

Example

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 Codes

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.

See Also


FReadLn

Description

Reads one line of input from an open file, assigning the constituent simple values to the referenced variables.

Syntax

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 Notes

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.

Notes

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:
  • The end of the file or the end of the line is reached before values have been read for all the given arguments
  • A value is read that cannot be converted into the appropriate type for the associated parameter

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.

Example

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 Codes

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.

See Also


FReadText

Description

Reads a file into a list of strings.

Syntax

FUNCTION FReadText (VAL fHdl: FILE, REF lst: LIST OF STRING):INTEGER;

Argument Notes

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

Notes

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.

Example

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 Codes

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.

FSetAttributes

Description

Sets the operating system level file attributes associated with the given file.

Syntax

FUNCTION FSetAttributes (VAL filename: STRING,
 VAL attributes: INTEGER ): INTEGER

Argument Notes

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
  • $FILENOPRIVS
  • $FILEREADABLE
  • $FILEWRITEABLE
  • $FILEEXECUTABLE
  • $FILEHIDDEN.

Notes

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

Example

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 Codes

Return Code Description
1 Successful completion
-1 Operation failed
-2 Argument unknown

See Also

FGetAttributes


FWrite

Description

Writes formatted data to a file.

Syntax

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 Notes

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.

Notes

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 & ).

Example

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 Codes

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

See Also


FWriteLn

Description

Writes one line of formatted data to a file.

Syntax

FUNCTION FWriteLn (VAL fHdl: FILE, VAL data: [LIST OF] STRING): INTEGER;

Argument Notes

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.

Notes

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

Example

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 Codes

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.

See Also


HelpOpen

Description

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.

Syntax

FUNCTION HelpOpen( VAL whdl: WINDOW, VAL filename: String,
 [VAL section: STRING]): INTEGER;

Argument Notes

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:
  • File name with the full path to the file (fully-qualified file name).
  • File name without the path. The platform's system directory is used as the location of the file.
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:
  • String constant $OSHelpOnHelp specifies that the default help on help is to be displayed.
  • String constant $OSHelpContents specifies that the help contents are displayed.

Notes

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.

Example

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 Codes

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.

IniRead

Description

This function reads data from an initialization file. It allows you to store and retrieve information in platform-native initialization files.

Syntax

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 Notes

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:
  • File name with the full path to the file.
  • File name without the path. The platform's system directory is used as the location of the file.
  • String constant $OSIni or $SAIni, which are the locations of the operating-system specific .ini file or the Softart.ini file, respectively.
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.

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion
-1 Unknown argument
-2 The operation failed at the operating system level
-5 File not found

See Also


IniScan

Description

This function obtains a list of items from a particular section of the initialization file.

Syntax

FUNCTION IniScan(REF rVal: List of String,
                 VAL filename: String,
                 Val section: String, [Val filetype:
                 String] ): Integer;

Argument Notes

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:
  • File name with the full path to the file.
  • File name without the path. The platform's system directory would be used as the location of the file.
  • String constant $OSIni or $SAIni, which are the locations of the operating-system specific .ini file or the Softart.ini file respectively.
section The section of the .ini file from which information is to be read.

Notes

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.

Example

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 Codes

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.

See Also


IniWrite

Description

This function writes data to an initialization file.

Syntax

FUNCTION IniWrite(Val filename: String,
                  Val section: String,
                  Val item: String,
                  Val data:[String | Integer | Boolean ],
                  ): Integer;

Argument Notes

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:
  • File name with the full path to the file.
  • File name without the path. The platform's system directory would be used as the location of the file.
  • String constant $OSIni or $SAIni, which are the locations of the operating-system specific .ini file or the Softart.ini file respectively.
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.

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion
-1 Unknown argument
-2 The operation failed at the operating system level

See Also


Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Return to Main Page

Copyright