What is Array.opx?
Array.opx is an OPL extension library that lets you use dynamic length string arrays in OPL. Features include adding, inserting and deleting items, finding and sorting.
Array.opx is available for the entire Nokia Communicator range (9210, 9210i, 9300, 9500).
Download Array.opx
You can download Array.opx from the Downloads page.
Usage
To use ARRAY.OPX, use the following statement at the beginning of your OPL application:
INCLUDE "ARRAY.OXH"
NOTE:
ARRAY.OPX functions can cause an OPL runtime error (for example when there is no more memory to add items). Since ARRAY.OPX allocates memory for the items stored in the array, you have to make sure that the memory allocated by the OPX is freed correctly if an error occurs. Failing to correctly release the memory allocated by the Array.opx will cause OPL to crash with an ALLOC error. , The following OPL-example demonstrates how to do this:
PROC TestArray:
LOCAL id&
id&=ArrayNew&:
ONERR FreeArray::
REM Do some stuff with the created array
FreeArray::
REM Make sure the array is freed
ArrayFree(id&)
ENDP
All the functions in Array.opx that take an index parameter or return in an index into the array, come in two flavors; one that returns the index as an integer value and one that returns an index as a long integer value.
The functions that return a long integer always end with an 'L', for example the function ArrayAddItem%: adds an item to the array and returns the index of the position that the entry was added as an integer. ArrayAddItemL&: does exactly the same, but returns the index as a long integer. If the number of items in your array never exceeds the maximum number of integers (32765), it is more memory efficient to use the integer version of the array functions.
Installing ARRAY.OPX
To install Array.opx, double click on the ARRAYOPX.SIS-file in Windows Explorer or copy it to your device and open it from the FileManager application. After this, copy the Array.oxh file to the \SYSTEM\OPL folder on either drive C: or drive D:
Bugs or improvements
If you find any bugs or have further ideas for improvement, please let me know by sending an email to Arjen Broeze or by posting a message in the OPX and OPM support forum.
Documentation of ARRAY.OPX functions
ArrayNew&:
Create a new array and returns a handle to the created array. This handle should be used in subsequent calls to other functions of Array.opx. If the array could not be created, the function will generate an OPL error.
ArrayFree:(arrayId&)
Delete an array previously created with ArrayNew&: and frees all the memory allocated by the array for holding the array items (there is no need to call ArrayClear: before deleting an array).
ArrayClear:(arrayId&)
Deletes all the items in the array and frees the memory allocated for holding the array items.
ArrayAddItem%:(arrayId&,value$)
ArrayAddItemL&:(arrayId&,value$)
Adds an entry to the array. If the array is sorted (see Finding and Sorting), the new entry is inserted into the array sorted, otherwise the new entry is appended at the end.
The function returns the index of the newly added entry or -1 if the entry could not be inserted (see example below).
When you try to add an existing entry to a sorted array, whether or not the entry will be added depends on the setting of the Duplicates flag (see ArraySetDuplicates:). Whether or not an entry is considered as duplicate depends on the setting of the Compare flag (see ArraySetCompare:)
Although ArrayAddItem is very efficient in adding items to a sorted array, if you have to add a lot of items to an array, it is quicker to unset the Sorted flag and resort the array after all the items have been added, like in the following example:
PROC AddLotsOfItems:(array&)
LOCAL i%
ArraySetSorted:(array&, KFalse%) REM Clears the Sorted flag
I%=1
WHILE I%<10000
ArradAddItem%:(array&,"Item number "+NUM$(I%,6))
I%=I%+1
ENDWH
ArraySort:(array%)
ENDP
ArrayInsertItem:(arrayID&,index%,value$)
ArrayInsertItemL:(arrayID&,index&,value$)
Inserts an entry into the array at the position specified by the index% (or index&) parameter. The index must be between 0 and the number of array items-1, otherwise an EOutOfRange error will occur.
ArrayInsertItem: will clear the sort flag of the array, causing subsequent calls to ArrayAddItem%: to append entries to the end of the array. To resort the array, you can use the ArraySort: function.
ArrayReplaceItem:(arrayID&,index%,value$)
ArrayReplaceItemL:(arrayID&,index&,value$)
Replaces the value of the entry at the position specified by the index% (or index&) parameter with value$. The index must be between 0 and the number of array items-1, otherwise an EOutOfRange error will occur.
ArrayReplaceItem: will clear the sort flag of the array, causing subsequent calls to ArrayAddItem%: to append entries to the end of the array. To resort the array, you can use the ArraySort: function.
ArrayDeleteItem:(arrayId&,index%)
ArrayDeleteItemL:(arrayId&,index&)
Deletes the entry at the position specified by the index% (or index&) parameter. The index must be between 0 and the number of array items-1, otherwise an EOutOfRange error will occur.
ArrayItemAt$:(arrayId&,index%)
ArrayItemAtL$:(arrayId&,index&)
Returns the value of the entry at the position specified by the index% (or index&) parameter. The index must be between 0 and the number of array items-1, otherwise an EOutOfRange error will occur.
ArrayItemCount%:(arrayId&)
ArrayItemCountL&:(arrayId&)
Returns the number of entries in the array.
ArrayFind%:(arrayId&,value$)
ArrayFindL&:(arrayId&,value$)
Searches for an entry in the array with the text specified by the value$ parameter. Returns the position of the item if found, -1 otherwise.
How items are compared when searching for a value is determined by the setting of the Compare flag (see ArraySetCompareType:).
ArraySearch%:(arrayId&,startpos%,value$,searchType%)
ArraySearchL&:(arrayId&,startpos%,value$,searchType%)
Searches for an entry in the array with the text specified by the value$ parameter. The function search for either a substring or a string using pattern matching, depending on the value of the searchType% parameter. The search is started at the element specified by startpos% (or startpos&) and returns the index of first item in the array on or after this position that matches the string specified in the value$ parameter. If no match can be found, ArraySearch returns -1.
If the value of the searchType% parameter is set to KArSearchWildcard%, the text specified in the value$ parameter can contain the wildcard characters "*" and "?", where "*" matches zero or more consecutive occurrences of any character and "?" matches a single occurrence of any character.
An example:
PROC FindWithWildcards:(array&)
LOCAL i%
REM start at first element
i%=ArraySearch%:(array&,0,"dr*br*n")
WHILE i%<>-1
REM do something with the found item
REM search for the next item
i%=ArraySearch%:(array&,i%+1,"dr*br*n")
ENDWH
ENDP
If the value of the searchType% parameter is set to KArSearchSubstring%,the function returns the first item on or after startpos% that contains the text specified in the value$ parameter.
How items are compared when searching for a value is determined by the setting of the Compare flag (see ArraySetCompareType:).
ArraySort:(arrayID&)
Sorts the items in the array. How entries are sorted is determined by the value of the Sort flag (see ArraySetSortMode:). How entries are compared during the sorting process is determined by the value of the Compare flag (see ArraySetCompareType:).
ArraySetDuplicates:(arrayId&,duplicates%)
Specifies how to handle adding duplicate entries in sorted arrays. Possible values for the duplicates% parameter are:
| KArDupAllow% | duplicate entries in the array are allowed | |
| KArDupIgnore% | duplicate entries are not added to the array, ArrayAddItem%: will return -1 in this case | |
| KArDupError% | trying to add a duplicate entry to array will result in a KErrAlreadyExists% error |
ArrayGetDuplicates%:(arrayId&)
Returns the current setting of the Duplicates flag.
ArraySetCompareType:(arrayId&,compare%)
Specifies how to compare items when finding, sorting or adding entries to a sorted array. Possible values for the compare% parameter are:
| KArCmpNormal% | A normal (case sensitive) comparison is done between the text data | |
| KArCmpFolded% | The text data is folded for the purpose of the comparison, resulting in a case insensitive search | |
| KArCmpCollated% | Collation rules are applied for the purpose of the comparison (i.e. 'd', 'a' and '`' are considered equal to 'a' during comparion) |
ArrayGetCompareType%:(arrayId&)
Returns the current setting of the Compare flag.
ArraySetSortMode:(arrayId&,sort%)
Specifies how to sort an array. Possible values for the sort% parameter are:
| KArSortAsc% | The array is sorted in ascending order (i.e. A .. Z) | |
| KArSortDes% | The array is sorted in descending order (i.e. Z .. A) |
ArrayGetSortMode%:(arrayId&)
Returns the current setting of the Compare flag.
ArraySetSorted:(arrayId&,sorted%)
Specifies whether the array should be sorted or not. If you specify KTrue% for the sorted% parameter, the Sorted flag for the array is set. The array is sorted only if it was unsorted. If the array is not sorted, ArraySetSorted(array&, KTrue%) produces the same effect as calling ArraySort:(array&).
By specifying KFalse% for the sorted% parameter, the Sorted flag of the array will be cleared (the array will not be unsorted). Subsequent calls to ArrayAddItem%: will append entries to the end of the array.
ArrayGetSorted:(arrayId&)
Returns whether the array is in sorted order.
ARRAY.OXH
REM Array.oxh
REM
REM Copyright (c) 2005 Arjen Broeze. All rights reserved.
REM
CONST KUidOpxArray&=&10204D05
CONST KOpxArrayVersion%=$120
REM Compare flags
CONST KArCmpNormal%=1
CONST KArCmpFolded%=2
CONST KArCmpCollated%=3
REM Sort flags
CONST KArSortAsc%=1 REM Sort Ascending
CONST KArSortDes%=2 REM Sort Descending
REM Duplicates flags
CONST KArDupAllow%=1 REM Allow duplicates
CONST KArDupIgnore%=2 REM Ignore duplicates
CONST KArDupError%=3 REM Duplicates will raise error KErrAlreadyExists%
REM Search type
CONST KArSearchSubstring%=1 REM Searches for substring
CONST KArSearchWildcard%=2 REM Searches for wildcard match
DECLARE OPX Array,KUidOpxArray&,KOpxArrayVersion%
ArrayNew&: :1
ArrayFree:(arrayId&) :2
ArrayClear:(arrayId&) :3
ArraySetDuplicates:(arrayId&,duplicates%) :4
ArrayGetDuplicates%:(arrayId&) :5
ArraySetCompareType:(arrayId&,compare%) :6
ArrayGetCompareType%:(arrayId&) :7
ArraySetSortMode:(arrayId&,sort%) :8
ArrayGetSortMode%:(arrayId&) :9
ArraySetSorted:(arrayId&,sorted%) :10
ArrayGetSorted:(arrayId&) :11
ArrayAddItem%:(arrayId&,value$) :12
ArrayInsertItem:(arrayId&,index%,value$) :13
ArrayReplaceItem:(arrayId&,index%,value$) :14
ArrayDeleteItem:(arrayId&,index%) :15
ArrayItemCount%:(arrayId&) :16
ArrayItemAt$:(arrayId&,index%) :17
ArrayFind%:(arrayId&,value$) :18
ArraySort:(arrayId&) :19
ArraySearch%:(arrayId&,startpos%,value$,searchType%) :20
ArrayAddItemL&:(arrayId&,value$) :21
ArrayInsertItemL:(arrayId&,index&,value$) :22
ArrayReplaceItemL:(arrayId&,index&,value$) :23
ArrayDeleteItemL:(arrayId&,index&) :24
ArrayItemCountL&:(arrayId&) :25
ArrayItemAtL$:(arrayId&,index&) :26
ArrayFindL&:(arrayId&,value$) :27
ArraySearchL&:(arrayId&,startpos&,value$,searchType%) :28
END DECLARE