Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference
Return to Main Page
Returns the currently allocated length of an array.
FUNCTION ArrayLength (VAL arr: ARRAY OF ANY): INTEGER;
Argument Name | Description |
arr | The array whose length is to be determined |
TSD Script arrays are resizable at run time. The SetArrayLength statement changes the size of any array. ArrayLength can be used at any time to determine how many elements an array can currently hold.
VARIABLES i: INTEGER; a[10]: ARRAY OF INTEGER;
ACTIONS ... SetArrayLength(a,100); ... i:=ArrayLength(a);
Set ArrayLength
Deletes an item from a list.
PROCEDURE ListDelete (REF lst: LIST OF ANY [, VAL idx: integer | $FIRST | $CURRENT | $LAST ] );
Argument Name | Description |
lst | A list parameter from which an element is to be deleted. |
idx | The element specifier must either be an integer index or one of the special symbols: $FIRST, $CURRENT of $LAST. If the element specifier is omitted from the call, it defaults to $CURRENT. |
The ListDelete function deletes the element at the given index from the given list. The index may be specified either numerically or via any of the special symbols $FIRST, $LAST, or $CURRENT.
If the index is omitted altogether, it defaults to $CURRENT. If the deleted element was the current element, the following element becomes current. If there is no following element, however, the preceding element becomes current.
ListSetPos(requestList, $FIRST); REPEAT IF requestList[$CURRENT].cost > costLimit THEN ListDelete(requestList, $CURRENT); END; UNTIL ListNext(requestList) < 0;
Return Code | Description |
1 | Successful completion |
-1 | The first argument could not be evaluated |
-2 | Index expression unknown |
-3 | Insufficient memory |
-4 | Index out-of-bounds |
Searches for a value in a list.
FUNCTION ListFind (REF lst: LIST OF T, VAL item: T): BOOLEAN;
Argument Name | Description |
lst | A list variable to be searched |
item | An expression of the same type as the list element type |
ListFind scans the indicated list, from the beginning, in search of a value that matches the indicated expression. If an element has the same value as the expression, ListFind returns TRUE and makes the matching element current. If no match is found, ListFind returns FALSE and leaves the list's current element unchanged.
Note: ListFind is case-insensitive relative to lists of strings.
ListFind works with lists of records as well as with lists of simple types. It performs a field-by-field comparison to determine record equality.
VARIABLES employeeList: LIST OF STRING;
ACTIONS IF ListFind(employeeList,'SMITH') THEN PrintEmployee(employeeList[$Current]); ...
Return Code | Description |
TRUE | Element found |
FALSE | Element not found |
$UNKNOWN | If argument from the LIST is invalid |
ListSort
Inserts one or more new elements into a list.
FUNCTION ListInsert (REF lst: LIST OF T, VAL item: [LIST OF] T, $BEFORE|$AFTER] ): INTEGER;
Argument Name | Description |
lst | A list variable into which a new element is to be inserted. |
item | Either an expression of the same type or the list of the same type. |
$BEFORE, $AFTER | An optional argument which can be used to indicate where the new value is
to be inserted in the list:
If omitted, $AFTER is assumed. |
The ListInsert function can be used to add a new element to a list or to insert one list into another. Insertion is always relative to the current element. By default, the new element or list is inserted after the current element.
If an individual element is inserted, it becomes the new current element. ListInsert returns the number of elements inserted.
VARIABLES name1:={'Tom','Dick','Harry'}: LIST OF STRING;
ACTION (* list pointer starts off at 1 - 'Tom' *) ListInsert(name1,'Mary',$Before); (* now name1 = 'Mary', 'Tom', 'Dick', 'Harry' * name2:={'Charlotte','Herman'}: LIST OF STRING; ListInsert(name1,name2,$After); (* now name1 = 'Mary','Charlotte','Herman','Tom','Dick','Harry' *)
Return Code | Description |
Greater than or equal to zero |
The number of elements inserted into the list can be any value greater than or equal to zero. It is possible to insert a list without checking to see whether it is empty, and if it is empty, the return code is zero. |
-1 | Unable to evaluate list argument. This error code indicates that there is no actual list associated with the given argument. This could occur if the argument referenced a list-typed record field, which was itself a member of a list of records, and the index given for that outer list was out of bounds. |
-2 | Second argument was unknown. |
Returns the number of elements in a list.
FUNCTION ListLength (VAL lst: LIST OF ANY): INTEGER;
Caution: If the list expression cannot be evaluated (for example, if an error occurs) ListLength returns $Unknown.
Argument Name | Description |
lst | A list variable whose length needs to be determined |
ListLength returns an integer that indicates how many elements are currently stored in the list.
VARIABLES a: ARRAY OF STRING; lis: LIST OF STRING; f: FILE;
ACTIONS (* read a text file into a list of strings *) FOpen(f,'DATA.TXT',$Read); FReadText(f,lis); FClose(f); (* make the array the same length as the list *) SetArrayLength(a,ListLength(lis)); (* copy the strings from the list into the array *)
FOR lis DO a[ListGetPos(lis)]:=lis[$Current]; END; (* get rid of the list *) SetUnknown(lis);
Return Code | Description |
Greater than or equal to zero |
Success. Returns the number of elements in the list. |
$Unknown | There are no negative return codes. If an error occurs during the evaluation of the list argument, ListLength returns $Unknown. |
Moves the current pointer to the next element in the list.
FUNCTION ListNext (REF lst: LIST OF ANY): INTEGER;
Argument Name | Description |
lst | A list variable whose current element is to be advanced. |
ListNext can be used to advance the current element pointer within a list. If a next element exists, ListNext moves the current element pointer there and returns its index. If not, ListNext leaves the current element pointer unchanged and returns a negative two (-2).
VARIABLES lis: LIST OF STRING;
ACTIONS lis:={'Tom','Dick','Harry'}: LIST OF STRING; (* list pointer starts off at 1 - 'Tom' *) ListNext(lis); (* now current pointer is at 2 - 'Dick' *) ListNext(lis); (* now current pointer is at 3 - 'Harry' *) ListNext(lis); (* still at 'Harry' but ListNext returned a -2 *)
Return Code | Description |
Greater than zero | Index of the current element pointer after it was moved by the ListNext statement. |
-1 | The first argument is non-existent. |
-2 | The current element is the last element. |
Removes the first element from a list and returns it as a result.
FUNCTION ListPop (REF lst: LIST OF T): T;
Argument Name | Description |
list | A list variable to be treated as a stack. |
ListPop and ListPush can be used to create a stack data structure. ListPop removes the first element from the list and returns it as its result. If the list is empty, ListPop returns $Unknown. The list's current pointer is unchanged unless it originally pointed to the first element. In that case, it is moved to point to the new first element.
VARIABLES myStack: LIST OF STRING; name: STRING;
ACTIONS ListPush(myStack, 'Harry'); -- myStack is { 'Harry' } ListPush(myStack, 'Dick'); -- myStack is { 'Dick', 'Harry' } ListPush(myStack, 'Tom'); -- myStack is { 'Tom', 'Dick', 'Harry' } name := ListPop(myStack); -- myStack is { 'Dick', 'Harry' } and name is 'Tom' name := ListPop(myStack); -- myStack is { 'Harry' } and name is 'Dick' name := ListPop(myStack); -- myStack is UNKNOWN and name is 'Harry' name := ListPop(myStack); -- myStack is UNKNOWN and name is UNKNOWN
ListPop removes the first element from the given list and returns it. If the list is empty, ListPop returns $Unknown.
Returns the index of the current element of a list.
FUNCTION ListPos (REF lst: LIST OF ANY): INTEGER;
Argument Name | Description |
lst | A list variable whose current element's index is to be determined |
ListPos returns the index of the current element of a list. If the list is empty, ListPos returns 0.
VARIABLES lis{ 'Tom', 'Dick', 'Harry' }: LIST OF STRING; i: INTEGER;
ACTIONS -- list pointer starts off at 1 - 'Tom' i:=ListPos(lis); -- i = 1 ListSetPos(lis,3); i:=ListPos(lis); -- i = 3 ListPrev(lis); -- i = 2
Return Code | Description |
Greater than zero | Current list position |
0 | List is empty |
$UNKNOWN | If the argument for the LIST is invalid |
ListSetPos
Moves the current list pointer to the previous element.
FUNCTION ListPrev (REF lst: LIST OF ANY): INTEGER;
Argument Name | Description |
lst | A list variable whose current pointer is to be moved backwards. |
ListPrev is used to move backward through a list. If the current index is 2 or greater, ListPrev moves the current pointer to the previous element and returns the index of that element. If the current pointer is at the beginning of the list, ListPrev leaves it unchanged and returns a value of -2.
VARIABLES lis: LIST OF STRING;
ACTIONS (* list pointer starts off at 1 - 'Tom' *) ListSetPos(lis,3); (* now current pointer is at 3 - 'Harry' *) ListPrev(lis); (* now current pointer is at 2 - 'Dick' *) ListPrev(lis); (* now current pointer is at 1 - 'Tom' *) ListPrev(lis); (* still at 'Tom' but ListPrev returned a -2 *)
Return Code | Description |
any | The index of the current element is returned on successful completion |
-1 | Failure to evaluate the first argument |
-2 | There is no previous element |
Inserts a new element at the beginning of a list.
FUNCTION ListPush (REF lst: LIST OF T, VAL item: T): INTEGER;
Argument Name | Description |
lst | A list variable treated as a stack |
item | An expression of the same type as the list |
The ListPush function is used in conjunction with the ListPop function to
implement a stack data structure. ListPush inserts a new item at the beginning of a
list.
The current element of the list is not effected by the ListPush function unless the
list was empty. In that case, the new element becomes current.
VARIABLES myStack: LIST OF STRING; name: STRING;
ACTIONS ListPush(myStack, 'Harry'); -- myStack is { 'Harry' } ListPush(myStack, 'Dick'); -- myStack is { 'Dick', 'Harry' } ListPush(myStack, 'Tom'); -- myStack is { 'Tom', 'Dick', 'Harry' } name := ListPop(myStack); -- myStack is { 'Dick', 'Harry' } and name is 'Tom name := ListPop(myStack); -- myStack is { 'Harry' } and name is 'Dick' name := ListPop(myStack) -- myStack is UNKNOWN and name is 'Harry' name := ListPop(myStack); -- myStack is UNKNOWN and name is UNKNOWN
Return Code | Description |
Greater than zero | The new length of the list is returned if the function is successful |
-1 | Failure to evaluate the first argument successfully |
Makes the specified element the current element.
FUNCTION ListSetPos (REF lst: LIST OF ANY, VAL index:
INTEGER | $FIRST | $LAST): INTEGER;
Argument Name | Description |
lst | A list variable whose current pointer is to be moved |
index | Either a numeric expression or one of the symbols $FIRST or $LAST |
ListSetPos can be used to change the position of the current pointer of a list. It takes a list variable and either an integer index between 1 and the current list length, or $FIRST (same as 1), or $LAST (same as ListLength (list)). In any case, the index of the current position is returned.
VARIABLES lis{ 'Tom', 'Dick', 'Harry' }: LIST OF STRING; i: INTEGER;
ACTIONS -- list pointer starts off at 1 - 'Tom' i:=ListPos(lis); -- i = 1 ListSetPos(lis,3); i:=ListPos(lis); -- i = 3 ListPrev(lis); -- i = 2
Return Code | Description |
index | The index of the current position is returned when the operation is successful |
-1 | Evaluation of the first argument failed |
-2 | The specified index is unknown |
-3 | Insufficient memory |
ListPos
Sorts a list.
FUNCTION ListSort (REF lst: LIST OF ANY): INTEGER;
Argument Name | Description |
lst | A list variable to be sorted |
ListSort sorts the indicated list in ascending order. If a list of records is passed, the first record field is used as the primary sort key, the second field is the secondary sort key, and so on.
VARIABLES lis{ 'Tom', 'Dick', 'Harry' }: LIST OF STRING;
ACTIONS ListSort(lis); -- now lis = 'Dick', 'Harry', 'Tom'
Return Code | Description |
1 | Successful completion |
-1 | The evaluation of the first argument failed |
ListFind
Changes the number of elements an array can hold.
FUNCTION SetArrayLength (REF arr: ARRAY OF ANY, VAL len: INTEGER): INTEGER;
Argument Name | Description |
arr | An array variable whose length is to be changed |
len | The number of elements that the array is to hold |
The SetArrayLength function alters the length of an Script array. If the length increases, the values of all existing elements remain with new elements initialized to the default value of their type (usually $Unknown). If the length decreases, elements with indices of len+1 and higher are discarded.
VARIABLES a: ARRAY OF STRING; l: LIST OF STRING; f: FILE;
ACTIONS (* read a text file into a list of strings *) FOpen(f,'DATA.TXT',$Read); FReadText(f,l); FClose(f); (* make the array the same length as the list *) SetArrayLength(a,ListLength(l)); (* copy the strings from the list into the array *) FOR l DO a[ListGetPos(l)]:=l[$Current]; END; (* get rid of the list *) SetUnknown(l);
Return Code | Description |
Greater than or equal to zero | New length of the array. It is possible to set the array length to zero, in which case the return value is zero. |
-1 | Unknown array. |
-2 | Unknown size argument. |
-3 | Insufficient memory. |
ArrayLength
Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference