Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

List and Array Manipulation

Return to Main Page


ArrayLength

Description

Returns the currently allocated length of an array.

Syntax

FUNCTION ArrayLength (VAL arr: ARRAY OF ANY): INTEGER;

Argument Notes

Argument Name Description
arr The array whose length is to be determined

Notes

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.

Example

VARIABLES
 i: INTEGER;
 a[10]: ARRAY OF INTEGER;
ACTIONS
 ...
 SetArrayLength(a,100);
 ...
 i:=ArrayLength(a);

See Also

Set ArrayLength


ListDelete

Description

Deletes an item from a list.

Syntax

PROCEDURE ListDelete (REF lst: LIST OF ANY [,
                      VAL idx: integer | $FIRST |
                      $CURRENT | $LAST ] );

Argument Notes

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.

Notes

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.

Example

ListSetPos(requestList, $FIRST);
REPEAT
 IF requestList[$CURRENT].cost > costLimit THEN
 ListDelete(requestList, $CURRENT);
 END;
UNTIL ListNext(requestList) < 0;

Return Codes

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

See Also


ListFind

Description

Searches for a value in a list.

Syntax

FUNCTION ListFind (REF lst: LIST OF T, VAL item: T): BOOLEAN;

Argument Notes

Argument Name Description
lst A list variable to be searched
item An expression of the same type as the list element type

Notes

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.

Example

VARIABLES
 employeeList: LIST OF STRING;
ACTIONS
 IF ListFind(employeeList,'SMITH') THEN
 PrintEmployee(employeeList[$Current]);
 ...

Return Codes

Return Code Description
TRUE Element found
FALSE Element not found
$UNKNOWN If argument from the LIST is invalid

See Also

ListSort


ListInsert

Description

Inserts one or more new elements into a list.

Syntax

FUNCTION ListInsert (REF lst: LIST OF T,
                     VAL item: [LIST OF] T,
                     $BEFORE|$AFTER] ): INTEGER;

Argument Notes

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:
  • $BEFORE is used if the new element is to be inserted before the current element.
  • $AFTER is used if the new element is to be inserted after the current element.

If omitted, $AFTER is assumed.

Notes

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.

Example

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 Codes

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.

See Also


ListLength

Description

Returns the number of elements in a list.

Syntax

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 Notes

Argument Name Description
lst A list variable whose length needs to be determined

Notes

ListLength returns an integer that indicates how many elements are currently stored in the list.

Example

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 Codes

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.

See Also


ListNext

Description

Moves the current pointer to the next element in the list.

Syntax

FUNCTION ListNext (REF lst: LIST OF ANY): INTEGER;

Argument Notes

Argument Name Description
lst A list variable whose current element is to be advanced.

Notes

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

Example

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 Codes

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.

See Also


ListPop

Description

Removes the first element from a list and returns it as a result.

Syntax

FUNCTION ListPop (REF lst: LIST OF T): T;

Argument Notes

Argument Name Description
list A list variable to be treated as a stack.

Notes

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.

Example

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 Codes

ListPop removes the first element from the given list and returns it. If the list is empty, ListPop returns $Unknown.

See Also


ListPos

Description

Returns the index of the current element of a list.

Syntax

FUNCTION ListPos (REF lst: LIST OF ANY): INTEGER;

Argument Notes

Argument Name Description
lst A list variable whose current element's index is to be determined

Notes

ListPos returns the index of the current element of a list. If the list is empty, ListPos returns 0.

Example

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 Codes

Return Code Description
Greater than zero Current list position
0 List is empty
$UNKNOWN If the argument for the LIST is invalid

See Also

ListSetPos


ListPrev

Description

Moves the current list pointer to the previous element.

Syntax

FUNCTION ListPrev (REF lst: LIST OF ANY): INTEGER;

Argument Notes

Argument Name Description
lst A list variable whose current pointer is to be moved backwards.

Notes

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.

Example

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 Codes

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

See Also


ListPush

Description

Inserts a new element at the beginning of a list.

Syntax

FUNCTION ListPush (REF lst: LIST OF T, VAL item: T): INTEGER;

Argument Notes

Argument Name Description
lst A list variable treated as a stack
item An expression of the same type as the list

Notes

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.

Example

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 Codes

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

See Also


ListSetPos

Description

Makes the specified element the current element.

Syntax

FUNCTION ListSetPos (REF lst: LIST OF ANY, VAL index:
INTEGER | $FIRST | $LAST): INTEGER;

Argument Notes

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

Notes

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.

Example

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 Codes

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

See Also

ListPos


ListSort

Description

Sorts a list.

Syntax

FUNCTION ListSort (REF lst: LIST OF ANY): INTEGER;

Argument Notes

Argument Name Description
lst A list variable to be sorted

Notes

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.

Example

 VARIABLES
 lis{ 'Tom', 'Dick', 'Harry' }: LIST OF STRING;
 ACTIONS
 ListSort(lis);
 -- now lis = 'Dick', 'Harry', 'Tom'

Return Codes

Return Code Description
1 Successful completion
-1 The evaluation of the first argument failed

See Also

ListFind


SetArrayLength

Description

Changes the number of elements an array can hold.

Syntax

FUNCTION SetArrayLength (REF arr: ARRAY OF ANY,
                         VAL len: INTEGER): INTEGER;

Argument Notes

Argument Name Description
arr An array variable whose length is to be changed
len The number of elements that the array is to hold

Notes

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.

Example

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 Codes

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.

See Also

ArrayLength


Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Return to Main Page

Copyright