Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Operating System Interface

Return to Main Page


SysCallProgram

Description

Calls a program.

Syntax

FUNCTION SysCallProgram(VAL commandLine: STRING [VAL arg: STRING ... ]): INTEGER;

Argument Notes

Argument Name Description
commandLine A string expression which contains the name of an executable program to be called. If the name is unqualified, the PATH is searched for the program.
arg The command line arguments for the program being called. Each argument must be of type STRING.

Notes

SysCallProgram can only be used to start a program.

Example

KNOWLEDGEBASE Make;
ROUTINES
 PROCEDURE MakeKB( VAL argList: LIST OF STRING );
PRIVATE
ROUTINES
EVENT ErrorEvent IS
ACTIONS
 WHEN $Event IS $MsgLabel THEN
 SysCallProgram( 'aseedit.exe',
 $EventParm( 2, STRING ) );
 END;
END;
PROCEDURE MakeKB( VAL argList: LIST OF STRING ) IS
VARIABLES
 whdl: WINDOW;
 hdlSession: SESSION;
 fileName: STRING;
ACTIONS
 (* If no file is specified on the command line prompt for one *)
 IF ListLength( argList ) = 0 THEN
 IF WinFileDialog($Desktop, fileName, '*.kb', 0, 0,
 'File to parse?', $FileDlgCenter +
 $FileDlgOpen ) <1
 THEN
 Exit;
 END;
 fileName := StrDelete( fileName, StrLength ( fileName )- 2, 3 );
 ListInsert( argList, fileName );
END;
FOR argList DO
 fileName := argList[ $CURRENT ];
 (* Display Progress window *)
 WinCreateScrollWindow($Desktop, whdl, $NullHandler,
                       0, 0, 30, 4, 'Parsing', $Helvetica, 14,
                       BitOr($WinTitle, $WinBorder,
                       $WinAutoPos,$WinSYsMenu ));
 WinWriteLN( whdl, fileName );
(* Create a session for the Application Software-Script Parser. The session is
 created invisible. An error file in the IDE format is
 requested *)
 SysCallProgram('kp.exe', '/IDE', '/e', fileName.&:ERR',
                fileName);
 SendMessage( whdl, $MsgClose );
 IF FExists( fileName & '.ERR' ) THEN (* Test for error file *)
            WinCreateHyperViewer($Desktop, whdl, '',
            ErrorEvent, 0, 0, 0, 0,
            fileName & '.ERR',
            BitOr($WinTitle, $WinBorder,
 $WinAutoPos, $WinAutoSize, $WinSysMenu,
 $WinReSize ));
 SendMessage( whdl, $MsgOpenFile, fileName & '.ERR',
 fileName, $HyperNoWordWrap );
 WinWait( whdl );
 END;
 END;
END;

Return Codes

Return Code Description
1 Success
-2 Unknown value
-3 Insufficient memory

See Also


SysCreateSession

Description

Starts a program in a new session as a child of the calling session.

Syntax

FUNCTION SysCreateSession(REF hdlSession: SESSION,
                          VAL program, argList: STRING,
                          VAL xLoc, yLoc, width,
                          height, style: INTEGER): INTEGER;

Caution: All sessions created by an application are terminated when the application terminates.

Argument Notes

Argument Name Description
hdlSession The session handle of the newly created session is returned. If the session is not created, the handle is set to $Unknown.
program The name of the program to execute. If the program is not in the PATH, a fully-qualified name must be specified.
argList All command line arguments for the program being called.
xLoc The X location of the upper left corner of the new session. Not all programs support positioning.
yLoc The Y location of the upper left corner of the new session. Not all programs support positioning.
width The width of the new session. Not all programs support positioning.
height The height of the new session. Not all programs support positioning.
style Style flags that control the behavior of the new session. Any of the following flags may be combined to form the style:
  • $SessionBackground - the $SessionBackground creates in the background. It does not receive focus upon creation.
  • $SessionInvisible - the $SessionInvisible creates invisibly.
  • $SessionAutoPosition - $SessionAutoPosition positions the session on the screen, ignoring the size and location parameters.

Notes

The argument list must be known in order for this function to work. If there are no arguments, you should pass in a 0-length string ('').

Note: Do not pass in $Unknown.

From OS/2, a full-screen Windows session may be created by specifying COMMAND.COM as the program and /c win <progname> as the arguments.

Window Sizing Parameters

In OS/2, many Presentation Manager applications set their own window size when they are started. If this is the case, the xLoc, yLoc, xLen, and yLen parameters are ignored.

The xLoc, yLoc, xLen, and yLen parameters are not used in Windows. In Windows, all sessions are created assuming $SessionAutoPosition for these styles.

Example

KNOWLEDGEBASE Make;
ROUTINES
 PROCEDURE MakeKB( VAL argList: LIST OF STRING );
PRIVATE
ROUTINES
EVENT ErrorEvent IS
ACTIONS
 WHEN $Event IS $MsgLabel THEN
SysCallProgram( 'aseedit.exe', $EventParm( 2, STRING ) );
 END;
END;
PROCEDURE MakeKB( VAL argList: LIST OF STRING ) IS
VARIABLES
 whdl: WINDOW;
 hdlSession: SESSION;
 fileName: STRING;
ACTIONS
 (* If no file is specified on the command line prompt for one *)
 IF ListLength( argList ) = 0 THEN
 IF WinFileDialog( $Desktop, fileName, '*.kb',
                  0, 0, 'File to parse?',
                  $FileDlgCenter + $FileDlgOpen ) <1
 THEN
 Exit;
 END;
 fileName := StrDelete( fileName, StrLength
 ( fileName ) - 2, 3 );
 ListInsert( argList, fileName );
 END;



 FOR argList DO
 fileName := argList[ $CURRENT ];
 (* Display Progress window *)
 WinCreateScrollWindow($Desktop, whdl, $NullHandler,
                       0, 0, 30, 4,
                       'Parsing', $Helvetica, 14,
                       BitOr( $WinTitle, $WinBorder,
                       $WinAutoPos,$WinSYsMenu ));
 WinWriteLN( whdl,fileName );
(* Create a session for the Application Software-Script parser. The session is *)
(* created invisibly. An error file in the IDE format *)
(* is requested *)
SysCreateSession( hdlsession, 'kp.exe','/IDE /e' &
                 fileName & '.ERR ' & fileName,
                 0, 0, 0, 0, $SessionInvisible );
 SysWaitSession( hdlSession ); 
(* Close progress window when parser is finished *)
 SendMessage( whdl, $MsgClose );
 IF FExists( fileName & '.ERR' ) THEN
(* Test for error file *)
 WinCreateHyperViewer( $Desktop, whdl, '',
                      ErrorEvent, 0, 0, 0, 0,
                      fileName & '.ERR',
                      BitOr($WinTitle, $WinBorder,
                      $WinAutoPos, $WinAutoSize,
                      $WinSysMenu, $WinReSize ));
 SendMessage( whdl, $MsgOpenFile, fileName & '.ERR',
             fileName, $HyperNoWordWrap );
             WinWait( whdl );
 END;
 END;
END;

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value
-4 The session could not be created

See Also


SysDelay

Description

Causes execution to pause for n milliseconds.

Syntax

FUNCTION SysDelay(VAL time: INTEGER): INTEGER;

Argument Notes

Argument Name Description
time Duration of delay in milliseconds

Example

KNOWLEDGEBASE Tone;
ROUTINES
PROCEDURE ToneExample;
PRIVATE
ROUTINES
PROCEDURE ToneExample IS
ACTIONS
 SysTone( 440, 100 );
 SysDelay( 50 );
 SysTone( 440, 100 );
 SysDelay( 50 );
 SysTone( 440, 100 );
 SysDelay( 50 );
 SysTone( 300, 400 );
END;

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value

See Also


SysGetClipboard

Description

Gets a string from the system clipboard.

Syntax

FUNCTION SysGetClipboard(REF clipBoard: STRING): INTEGER;

Argument Notes

Argument Name Description
clipBoard Returns the value of the system clipboard. If there is no text in the clipboard, this is set to $Unknown

Example

KNOWLEDGEBASE Clip;
CONSTANTS
 MENU_REFRESH IS 101;
 MENU_EXIT IS 102;
ROUTINES
 PROCEDURE ClipView;
PRIVATE
CONSTANTS
 menuList IS { '~File', '~Refresh', 'e~xit', '' }: LIST OF
STRING;
ROUTINES
(* ******** EDITOR EVENT HANDLER ******** *)
EVENT ClipboardEvent( REF clipBoard: STRING ) IS
ACTIONS
 WHEN $Event IS $MsgCreate THEN
 WinSetMenuBar( $Handle, menuList );
 SysGetClipboard( clipBoard );
 WinWrite( $Handle, clipBoard );
 ELSWHEN $MsgMenu THEN (* Menu Message *)
 WHEN $MenuSelection IS MENU_REFRESH THEN
 SysGetClipboard( clipBoard );
 WinCLear( $Handle );
 WinWrite( $Handle, clipBoard );
 ELSWHEN MENU_EXIT THEN
 SendMessage( $Handle, $MsgClose );
 END;
 END;
END;
PROCEDURE ClipView IS
VARIABLES
 whdl: WINDOW;
 result: INTEGER;
ACTIONS
 result := WinCreateScrollWindow( $Desktop, whdl,
                                 ClipboardEvent{''}, 0, 0, 0, 0,
                                 'KML Clipboard viewer', '', 10,
                                 BitOr($WinBorder, $WinTitle,
                                 $WinResize, $WinSysMenu,
                                 $WinMenu, $WinAutoPos,
                                 $WinAutoSize, $WinVScroll,
                                 $WinHScroll, $WinTaskList ))
                                 IF result < 1 THEN
                                 WinMessageBox( $Desktop, 'Error', $mbok + $MBIconError,
                                 'Open failed' & result );
 END;
 WinWait( whdl );
END;

Return Codes

Return Code Description
1 Successful completion
0 The clipboard is empty
-3 Insufficient memory
-10 One of the operating system calls to access the clipboard failed

See Also


SysGetContext

Description

Completes the fields of the referenced context record with information about the current operating environment.

Syntax

FUNCTION SysGetContext (REF context: $SystemContext): INTEGER;

Argument Notes

Argument Name Description
context A variable of type $SystemContext

Notes

$SystemContext is a RECORD type declared in the system knowledgebase kml.kb. The declaration of $SystemContext is:

$SystemContext IS RECORD
 operatingSystem: String;
 ASEVersion: String;
 VendorOSName: String:
 VendorOSVersion: String;
 FreeMemory: Integer:
 FreeResources: Integer:
 NLSInfo: $SystemNlsInfo;
END;

Descriptions for the fields used with $SystemContext follow.

Field Description
operatingSystem Windows, OS/2, or UNIX.
ASEVersion Currently 5.0.
VendorOSName The vendor's full name for the workstation's operating system. This field differs from the $SystemContext operatingSystem field in that it contains the actual name of the operating system, such as 'Microsoft Windows 95,' instead of an identifier.
VendorOSVersion The vendor's version number for the workstation's operating system. It is possible for this field to be unknown if:
  • The version number cannot be determined with reasonable accuracy (as is the case in Microsoft Windows NT).
  • The version number of the operating system is part of the operating system's name.
FreeMemory The operating system's current estimate of the amount of free memory (both physical and virtual) available at the time the SysGetContext call is made. The value returned is expressed in kilobytes (KB).
FreeResources This field contains the operating system's current estimate of the amount of free resources available at the time the SysGetContext call is made. It is possible for this field to be unknown if the operating system does not support this concept (as is the case with OS/2).
NlsInfo National Language Support Information. See the description of the $SystemNlsInfo record below.


The record returned by SysGetContext includes the following National Language Support (NLS) information:

$SystemNlsInfo IS RECORD
 CountryCode: Integer;
 CurrencySymbol: String;
 CurrencyBefore: Boolean;
 DateFourDigitYear: Boolean;
 DateOrdering: String;
 DateSeparator: String;
 DecimalSeparator: String;
 DecimalLeadingZero: Boolean;
 NumCurrencyDecimalDigits: Integer;
 NumCurrencyExtraSpaces: Integer;
 NumericGroupSeparator: String;
 NumRealDecimalDigits: Integer;
 TimeSeparator: String;
Field Description
CountryCode The country code of the host machine
CurrencyBefore Whether the currency symbol is displayed before or after the numeric

TRUE - Currency symbol is placed before the number

FALSE - Currency symbol is placed after the number

CurrencySymbol Currency symbol of the host machine
DateFourDigitYear Whether the native date format has a two or four-digit year.

TRUE = Date is formatted as 1999

FALSE = Date is formatted as 99

DateOrdering A format string like MM/DD/YY
DateSeparator The character used to separate the day, month, and year values of a date
DecimalSeparator The character used to separate a number from the decimal part
DecimalLeadingZero Whether decimal numbers less than 1 require a leading zero (for example, 0.123 or .123)
IntlCurrencySymbol Currency symbol used internationally where the correct character may not always be available
LocaleId The current locale of the host machine.
NumCurrencyDecimalDigit The number of digits commonly used to the left of the decimal
NumCurrencyExtraSpaces The number of spaces to insert between a currency symbol and numeric
NumericGroupSeparator The character used to group digits in large numbers (in other words, the thousands separator)
NumRealDecimalDigits The number of digits to be displayed when showing real numbers (for example, 3.14159 or 3.14)
TimeSeparator The character used to separate hour, minutes, and seconds

The $SystemContext RECORD used by this function has a new field named GMTBias. This is the difference between local time and the equivalent
GMT Time in seconds. This value is normally retrieved from the host operating system, but it can also be set manually using SysSetGMTDiff.

Entry Field Properties

The Text Box page of this dialog box includes a new checkbox labeled "Convert to/from GMT". This box can only be checked for entry fields that contain a Time or Date pattern. By checking this box, you indicate that you want Tivoli Service Desk Developer's Toolkit to automatically localize (see SysLocalizeTime) the time or date provided.

Multi-Column List Box Properties

The Columns tab of this dialog box includes a new checkbox labeled "Convert to/from GMT". This box can be set individually for each
column in the MCLB. It should only be set for columns that will contain a value of type DATE or TIME.

Pairing date/time fields in controls

When using the Convert to/from GMT checkboxes for entry fields and MCLB columns (as described above) you must observe a simple
naming convention in order for the conversion to work.

For each time field that is marked for GMT conversion a corresponding date field must also be marked. These two fields must be associated with each other using a naming convention (see the documentation for SysLocalizeTime and SysGlobalizeTime for more
information).

The time and date fields must have control names that end in "_TIME" and "_DATE" respectively. All other preceding parts of the name must be identical. Here are some examples:

Time Field Control Name Date Field Control Name Validity
----------------------- ----------------------- --------
START_TIME START_DATE Correct
MY_BIRTH_TIME MY_BIRTH_DATE Corrent
MYBIRTHTIME MYBIRTHDATE Incorrect
THE_TIME_ENDS THE_DATE_ENDS Incorrect

If the two fields are not paired properly, the conversion may not occur.

See Also

Return Code Description
1 Successful completion
-2 The context parameter contained an invalid reference

SysGetEnvironment

Description

The SysGetEnvironment function searches an environment list, provided by the operating system, for a string that matches the given key. When the key is found, SysGetEnvironment returns the string associated with that key.

Syntax

FUNCTION SysGetEnvironment (VAL key: STRING): STRING;

Argument Notes

Argument Name Description
key The key for which to search

Notes

If the environment list does not contain an entry that matches the given key, $Unknown is returned.

Example

IF UNKNOWN (fileName := SysGetEnvironment ('CONFIG')) THEN
            CreateDefaultConfigFile;\
END;
ConfigFile :=FOpen (fileName);

Return Codes

When the key is found, SysGetEnvironment returns the string associated with that key.

See Also

SysSetEnvironment


SysGetTaskList

Description

Queries the system for a list of all active tasks.

Syntax

FUNCTION SysGetTaskList(REF taskList: LIST OF $TASKRECORD): INTEGER;

Cautions

Note: The system session commands can only be used for sessions created by the calling session.

OS/2 imposes limitations on messages sent to windows belonging to different processes. For more information on these limitations, see your OS/2 system programming documentation.

Argument Notes

Argument Name Description
taskList This argument must be a list variable of the system-defined record type $TASKRECORD. $TASKRECORD is defined in system knowledgebase kml.kb as:
$TASKRECORD IS
 title: STRING;
 hWindow: WINDOW;
 hSession: SESSION;
 hProcess: PROCESS;
END;

Notes

SysGetTaskList returns the task records from each of the open sessions, including sessions that are not TSD Script sessions. Each task record contains the title text from the top-level window in its corresponding session.

Example

KNOWLEDGEBASE Tasks;
ROUTINES
 FUNCTION SelectTask( VAL taskName: STRING ): BOOLEAN;
PRIVATE
ROUTINES
FUNCTION SelectTask( VAL taskName: STRING ): BOOLEAN IS
VARIABLES
 taskList: LIST OF $TASKRECORD; 
(* $TASKRECORD is system-
 defined *)
ACTIONS
 IF SysGetTaskList( taskList ) <= 0 THEN EXIT FALSE;
 END;
 FOR taskList DO (* Search list for task name *)
 IF taskList[ $CURRENT ].title = taskName THEN
 SysSelectTask( taskList[ $CURRENT ] );
 EXIT TRUE;
 END;
 END;
 EXIT FALSE;
END;

Return Codes

Return Code Description
any Returns the task records from each of the open sessions, including sessions that are not TSD Script sessions. Each task record contains the title text from the top-level window in its corresponding session. See Notes for differences between OS/2 and Windows.
-2 Unknown value.
-3 Insufficient memory.

See Also

SysSelectTask


SysOSShell

Description

Creates a new command processor session.

Syntax

FUNCTION SysOSShell(VAL commandLine: STRING): INTEGER;

Cautions

In OS/2, shells started by SysOSShell are terminated when the TSD Script application (the parent session) terminates.

Argument Notes

Argument Name Description
commandLine The command executed by the command processor. An empty string creates a new command prompt.

Notes

In OS/2, SysOSShell starts a session running the shell specified by the COMSPEC environment variable. (This is usually the OS/2 command processor, cmd.exe.) The argument to SysOSShell is passed to the shell as its command line. The shell started by SysOSShell executes asynchronously to the calling process.

In UNIX, the command given as an argument is executed directly as one of the following:

SysOSShell launches the /usr/bin/X11/xterm program (/usr/openwin/bin/xterm for Sun machines). This may be overridden by setting the SAI_XTERM variable to a program which can be found in the PATH environment or a program with a fully-qualified path. (SAI_XTERM must be in the user's environment before running the TSD Script program which calls SysOSShell.)

In Windows, SysOSShell does the following:

There are two arguments, /C and /K, that are used to run the shell from a command line. /C executes the executes the command and closes the shell. /K executes the command and leaves the shell open. These arguments are not applicable to UNIX.

Example

KNOWLEDGEBASE OSShell;
ROUTINES
PROCEDURE OSShellExample;
PRIVATE
ROUTINES
PROCEDURE OSShellExample IS
ACTIONS
 (* /C or /K is required to run an external command for
 Windows or OS/2 *)
 SysOSShell( '/C aseedit' );
 (* Child sessions end when parent session is terminated *)
 WinMessageBox( $Desktop, 'Cancel', $mbok, '' );
END;

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value

See Also

For more information on cmd.exe, see the OS/2 documentation.

For more information on command.com, see the help system for DOS.


SysSelectSession

Description

Selects a session and gives it the focus.

Syntax

FUNCTION SysSelectSession(VAL hdlSession: SESSION): INTEGER;

Argument Notes

Argument Name Description
hdlSession Handle of the selected session to

Notes

An OS/2 session must have a window with the $WinTaskList style in order to be able to be selected. Sessions that are not displayed in the task list cannot be selected. The session must have been created by the calling session. In UNIX, this function simply returns 1 (success) without attempting to select a session.

Example

KNOWLEDGEBASE Make2;
ROUTINES
 PROCEDURE MakeKB( VAL argList: LIST OF STRING );
PRIVATE
VARIABLES
 hdlSessionEdit: SESSION;
ROUTINES
EVENT ErrorEvent IS
ACTIONS
 WHEN $Event IS $MsgLabel THEN
 IF SysSelectSession( hdlSessionEdit ) < 1 THEN
 SysCreateSession( hdlSessionEdit, 'vi.exe',
                  $EventParm(2, STRING ),
                  0, 0, 0, 0, $SessionAutoPosition );
 END;
 END;
END;
PROCEDURE MakeKB( VAL argList: LIST OF STRING ) IS
VARIABLES
 whdl: WINDOW;
 hdlSession: SESSION;
 fileName: STRING;
ACTIONS
 (* If no file is specified on the command line prompt for one *)
 IF ListLength( argList ) = 0 THEN
 IF WinFileDialog( $Desktop, fileName, '*.kb', 0, 0,
                  'File to parse?', $FileDlgCenter +
                  $FileDlgOpen ) < 1
 THEN
 Exit;
 END;
 fileName := StrDelete( fileName, StrLength
                       (fileName) - 2, 3 );
 ListInsert( argList, fileName );
 END;
 FOR argList DO
 fileName := argList[ $CURRENT ];
 (* Display Progress window *)
 WinCreateScrollWindow( $Desktop, whdl, $NullHandler,
                       0, 0, 30, 4, 'Parsing', $Helvetica, 14,
                       BitOr($WinTitle, $WinBorder,
                       $WinAutoPos, $WinSYsMenu ));
 WinWrIteLN( whdl, fileName );
(* Create a session for the Application Software-Script parser.
The session is created invisible.An error file in the IDE format *)
(* is requested *)
 SysCreateSession( hdlSession, 'kp.exe', '/IDE /e' &
                  fileName & '.ERR ' & fileName, 0, 0, 0, 0,
                  $SessionInvisible );
 SysWaitSession( hdlSession );
 (* Close progress window when parser is finished *)
 SendMessage( whdl, $MsgClose );
 IF FExists( fileName & '.ERR' ) THEN
(* Test for error file *)
 WinCreateHyperViewer($Desktop, whdl, '',
                      ErrorEvent, 0, 0, 0, 0,
                      fileName & '.ERR',
                      BitOr( $WinTitle, $WinBorder,
                      $WinAutoPos, $WinAutoSize,
                      $WinSysMenu, $WinReSize ));
 SendMessage( whdl, $MsgOpenFile,
             fileName & '.ERR',
             fileName,
 $HyperNoWordWrap );
 WinWait( whdl );
 END;
 END; (* end of FOR*)
END; (* end of make KB*)

Return Codes

Return Code Description
1 Successful completion.
-2 Unknown value.
-369 The session handle does not reference a valid session.
-460 The calling process is not the parent of the session. A session may only be selected by the process that created it.

See Also


SysSelectTask

Description

Activates a selected task.

Syntax

FUNCTION SysSelectTask(VAL task: $TASKRECORD): INTEGER;

Argument Notes

Argument Name Description
task This argument must be of the system-defined record type $TASKRECORD. $TASKRECORD is defined in system knowledgebase kml.kb as:
$TASKRECORD IS title: STRING;hWindow:
WINDOW; hSession: SESSION;
hProcess: PROCESS; END;

The fields of the record must have been set by SysGetTaskList.

Example

KNOWLEDGEBASE Tasks;
ROUTINES
 FUNCTION SelectTask( VAL taskName: STRING ): BOOLEAN;
PRIVATE
ROUTINES
FUNCTION SelectTask( VAL taskName: STRING ): BOOLEAN IS
VARIABLES
 taskList: LIST OF $TASKRECORD;
(* $TASKRECORD is system-defined *)
ACTIONS
 IF SysGetTaskList( taskList ) <= 0 THEN
 EXIT FALSE;
 END;
 FOR taskList DO (* Search list for task name *)
 IF taskList[ $CURRENT ].title = taskName THEN
 SysSelectTask (taskList[ $CURRENT ] );
 EXIT TRUE;
 END;
 END;
 EXIT FALSE;
END;

Return Codes

Return Code Description
1 Successful completion.
-2 Unknown value.
-10 A request failed for an operating system service that was required to complete the function. Likely causes are invalid values as arguments to the statement, or system resource limitations.

See Also

SysGetTaskList


SysSetClipboard

Description

Sets the string value of the system clipboard.

Syntax

FUNCTION SysSetClipboard(VAL clipBoard: STRING): INTEGER;

Argument Notes

Argument Name Description
clipBoard The new value replaces any previous values of the clipboard.

Example

KNOWLEDGEBASE SetClip;
ROUTINES
 PROCEDURE SetClipBoard( VAL clipBoard: LIST OF STRING );
PRIVATE
ROUTINES
PROCEDURE SetClipBoard( VAL clipBoard: LIST OF STRING ) IS
VARIABLES
 clipBoardString: STRING;
ACTIONS
 clipBoardString := '';
 FOR clipBoard DO
 clipBoardString := clipBoardString & ' ' & clipBoard[
                    $CURRENT ];
 END;
 SysSetClipboard( clipBoardString );
END;

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value
-3 Insufficient memory
-10 One of the operating system operations required to access the clipboard failed

See Also

SysGetClipboard


SysSetEnvironment

Description

Adds an entry to (or alters an entry in) the environment list provided by the operating system, so that the new value (if any) is associated with the given key.

Syntax

FUNCTION SysSetEnvironment (VAL key: STRING [, VAL newValue: STRING]): INTEGER;

Cautions

DOS and OS/2 do not make a copy of a string passed into the environment list. Rather, they use the string that is passed into the environment list directly. This has two ramifications in terms of memory usage:

Argument Notes

Argument Name Description
key The key string in the environment list
newValue The new string to be associated with the key

Notes

The SysSetEnvironment function associates the new value with the given key in the environment list, or removes the given key and its associated value if the newValue argument is omitted.

The exact nature of the environment list depends on the operating system. However, an environment list is typically copied from a parent process to a child process and is destroyed when the child process terminates.

An environment variable set via SysSetEnvironment should return the new value, and should be copied to child processes started by the calls, SysCallProgram, SysCreateSession and SysOSShell. The variable is not copied back into the environment from which the Tivoli Service Desk Developer's Toolkit run-time system started.

Note: If newValue is not provided, the specified environment variable is "unset."

Example

IF SQLSelectInto ('SELECT ICONS FROM DIRECTORIES',
 iconPATHPATHPATHPATH)
 >= 1 AND
 StrPos (globalPath := SysGetEnvironment ('PATH'), iconPath)
 = 0
THEN
 SysSetEnvironment ('PATH', globalPath & ';' & iconPath);
END;

Return Codes

Return Code Description
1 Successful completion
-10 Operating system call failed

See Also


SysSetGMTDiff

Description

Normally, the Tivoli Service Desk Developer's Toolkit internals query the host operating system to get the difference between the local time and Greenwich Mean Time (GMT). This function can be used to set the difference manually and override the native value.

Syntax

FUNCTION SysSetGMTDiff( VAL NewDiff : Integer
 [, $Seconds | $Minutes | $Hours]) : INTEGER;

Argument Notes

Argument Description
NewDiff This is the new difference between GMT and the local time. The number specified will be added to a local time to make a GMT time. For example, the default GMT difference for New York is +5 hours. The GMT difference for Cairo is -2 hours. The valid range for an argument is -12 hours <= NewDiff <= +12 hours.
Units The units used to specify the difference.

Return Codes

Return Code Description
1 Success
-1 Invalid difference was specified

Example

KNOWLEDGEBASE GMTTest;
ROUTINES
Procedure Proc1;
PRIVATE
ROUTINES
Procedure Proc1 IS
VARIABLES
 whdl : Window;
 r : $SystemContext;
 t : TIME;
 d : DATE;
 nRC : Integer;
 ACTIONS
 WinCreateScrollWindow($Desktop, whdl, $NullHandler, 15,10,80,20, 'Stuff',
                       $SystemMonospaced, 10, $WinDefaultStyle);
 --Set the GMT bias to something funky. This is the equivalent of
 --the GMT Moscow...
 nRC := SysSetGMTDiff(-3, $hours);
 WinWriteLn(whdl, 'SysSetGMTDiff returned: ' & nRC);
 --Retrieve the GMT bias which should now be -3 hours (but specified in
 --seconds) and display it
 SysGetContext(r);
 WinWriteLn(whdl, 'GMT Bias = ' & r.GMTBias);
 --I picked this time and date at random
 t := {01,07,07}:TIME;
 d := {07,07,1993}:DATE;
 WinWriteLn(whdl, 'Before globalization: ' & d & ' ' & t );
 --Globalize the time and display it
 SysGlobalizeTime(t, d);
 WinWriteLn(whdl, 'After globalization: ' & d & ' ' & t );
 --Localize it again and display it (this should be the same as "before
 --globalization"
 SysLocalizeTime(t, d);
 WinWriteLn(whdl, 'After localization: ' & d & ' ' & t );
 WinWait(whdl);
 END;

See Also


SysSetReturnCode

Description

Sets the integer value that the TSD Script interpreter returns to the UNIX command shell or DOS window on successful exit. The interpreter returns 1 if SysSetReturnCode is not used.

Syntax

FUNCTION SysSetReturnCode(VAL Code: INTEGER]):INTEGER;

Caution: If the TSD Script Interpreter encounters a fatal error and exits, it overrides any values set by SysSetReturnCode.

Argument Notes

Argument Name Description
code The code to return to the command shell or DOS window

Notes

The value passed by the last call is used if this function is called multiple times.

Note: Do not confuse this function with the TSD Script RETURN statement which sets the value returned by an TSD Script function.

Example

PROCEDURE DeepThought IS
ACTIONS
 SysDelay(1000000);
 SysSetReturnCode(42);
END;

Return Codes

Return Code Description
1 Successful completion
-10 Operating system call failed

See Also


SysStopSession

Description

Stops an active session.

Syntax

FUNCTION SysStopSession(VAL hdlSession: SESSION): INTEGER;

Argument Notes

Argument Name Description
hdlSession Handle of the session to be stopped. The session must be started by the calling program

Example

KNOWLEDGEBASE Make;
ROUTINES
 PROCEDURE SessionExp( VAL argList: LIST OF STRING );
PRIVATE
ROUTINES
PROCEDURE MakeKB( VAL argList: LIST OF STRING ) IS
VARIABLES
 whdl: WINDOW;
 hdlSession: SESSION;
 fileName: STRING;
ACTIONS
 SysCreateSession( hdlSession, argList[1], argList[2],
                  0, 0, 0, 0, $SessionAutoPos );
 SysStopSession( hdlSession );
END;

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value
-369 The handle does not reference a valid session. The session may no longer exist
-460 The calling process is not the parent of the session. A process may only stop a session that it created

See Also


SysTone

Description

Emits a tone from the system speaker.

Syntax

FUNCTION SysTone(VAL frequency: INTEGER, VAL duration: INTEGER
                 ): INTEGER;

Argument Notes

Argument Name Description
frequency The frequency in hertz of the tone that sounds
duration The duration of the tone in milliseconds

Notes

In Windows 98, the duration and frequency default to the system sound.

Example

KNOWLEDGEBASE Tone;
ROUTINES
PROCEDURE ToneExample;
PRIVATE
ROUTINES
PROCEDURE ToneExample IS
ACTIONS
 SysTone( 440, 100 );
 SysDelay( 50 );
 SysTone( 440, 100 );
 SysDelay( 50 );
 SysTone( 440, 100 );
 SysDelay( 50 );
 SysTone( 300, 400 );
END;

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value

See Also

SysDelay


SysWaitSession

Description

Waits for a session to terminate.

Syntax

FUNCTION SysWaitSession(VAL hdlSession: SESSION): INTEGER;

Caution: Session waits stack. This means that the most recent call to SysWaitSession must return before any preceding calls return, even if the session being waited on has terminated.

Argument Notes

Argument Name Description
hdlSession Handle of the session for which to wait. The session must be started by the calling process

Example

KNOWLEDGEBASE Make;
ROUTINES
 PROCEDURE MakeKB( VAL argList: LIST OF STRING );
PRIVATE
ROUTINES
EVENT ErrorEvent IS
ACTIONS
 WHEN $Event IS $MsgLabel THEN
SysCallProgram( 'aseedit.exe', $EventParm( 2, STRING ) );
 END;
END;
PROCEDURE MakeKB( VAL argList: LIST OF STRING ) IS
VARIABLES
 whdl: WINDOW;
 hdlSession: SESSION;
 fileName: STRING;
ACTIONS
(* If no file is specified on the command line prompt for one *)
 IF ListLength( argList ) = 0 THEN
 IF WinFileDialog( $Desktop, fileName, '*.kb', 0, 0,
                  'File to parse?', $FileDlgCenter +
                  $FileDlgOpen ) <1

 THEN
 Exit;
 END;
 fileName := StrDelete( fileName,

 StrLength( fileName ) - 2, 3 );
 ListInsert( argList, fileName );
 END;
 FOR argList DO
 fileName := argList[ $CURRENT ];
 (* Display Progress window *)
 WinCreateScrollWindow( $Desktop, whdl, $NullHandler,
                       0, 0, 30, 4, 'Parsing', $Helvetica, 14,
                       BitOr( $WinTitle, $WinBorder,
                       $WinAutoPos, $WinSYsMenu ));
 WinWriteLN( whdl, fileName );
(* Create a session for the Application Software-Script parser. The session is
 created invisible. An error file in the IDE format is *)
(* requested *)
 SysCreateSession( hdlSession, 'kp.exe', '/IDE
                  /e' & fileName & '.ERR ' & fileName,
                  0, 0, 0, 0, $SessionInvisible );
 SysWaitSession( hdlSession );
(* Close progress window when parser is finished *)
 SendMessage( whdl, $MsgClose );
 IF FExists( fileName & '.ERR' ) THEN
(* Test for error file *)
 WinCreateHyperViewer( $Desktop, whdl, '',
                      ErrorEvent, 0, 0, 0, 0,
                      fileName & '.ERR',
                      BitOr( $WinTitle, $WinBorder,
                      $WinAutoPos, $WinAutoSize,
                      $WinSysMenu, (* created
                      invisible. An error file
                      in the IDE format is requested
                      *) $WinReSize ));
 SendMessage( whdl, $MsgOpenFile, fileName & '.ERR',
 fileName, $HyperNoWordWrap );
 WinWait( whdl );
 END;
 END; (* end of FOR*)
END; (* end of make KB*)

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value

See Also


SysYield

Description

Blocks the current thread of execution until all messages in the queue are dispatched.

Syntax

FUNCTION SysYield

Notes

SysYield is useful if the user interface of the application needs to reflect messages generated by a processor intensive function.

See Also

SysDelay


SysGlobalizeTime

Description

Given a variable of type time that is assumed to be a local time, this function adjusts it to the equivalent GMT time. A date must also be supplied in case the adjustment affects it too.

Syntax

FUNCTION SysGlobalizeTime(REF t : TIME, REF d : DATE) : INTEGER;

Argument Notes

Argument Description
t This is the time to be globalized
d This value must be supplied. If adjusting the given time rolls over into the next (or previous day) the date is adjusted to reflect
that. SysGlobalizeTime should *always* be used on a date/time pair.

Return Codes

Return Code Description
1 Success
-1 Unknown date or time supplied

Example

Please see the example for SysSetGMTDiff.

See Also


SysLocalizeTime

Description

Given a variable of type time that is assumed to be a GMT time, this function adjusts it to the local time. A date must also be supplied in case the adjustment affects it too.

Syntax

FUNCTION SysLocalizeTime(REF t : TIME, REF d : DATE) : INTEGER;

Argument Notes

Argument Description
t This is the time to be localized
d This value must be supplied. If adjusting the given time rolls over into the next (or previous day) the date is adjusted to reflect that. SysLocalizeTime should always be used on a date/time pair.

Return Codes

Return Code Description
1 Success
-1 Unknown date or time supplied

Example

Please see the example for SysSetGMTDiff.

See Also


Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Return to Main Page

Copyright