Synopsis: 

       result=array_srchset(array_name,search_order,value,set_value)

Arguments:

       array_name - The array name as previouslydefined by a call to array_dim()

       search_order - Search order (-1 for bottom up, -3 for search next)

       value - The value to search for in the array

       set_value - The vlaue to set the element to that matched the search for value

Description:   This function allows for a one-dimensional array to be searched for a particular value and if an entry is found that matches the given value then that element is set to the new set_value value.       Note that only one-dimensional arrays are supported by this function.      The search order defines how the array is to be searched and can be set to one of the following values:

       -1 -  Search for the first entry from the bottom up that matches the value

       -2 - Top down search (NOT CURRENTLY SUPPORTED)

       -3 - Search for then next match starting from the last match found

       -4 - search for the previous value (NOT CURRENTLY SUPPORTED)

       

If -1 is specified then the search will always begin at element 0 of  the index of the array and then cycle through the last index of the array until the end of the array is reached looking for a match for the specified value.    

IF -2 is specified then the last position where a match was found will be remembered and the next time the function is call the search will continue from that position and then wrap around to the beginning again.

The function will return the index number of the element that matches the value specified by the value argument.  otherwise it will return -1.

This function is often used for maintaining resources where it is necessary to search for and set an array element in a single atomic operation.

For example:

       // Create a one dimensional array

       x=array_dim("RESOURCE",100,1);

       

       // Search for the first element that has a blank string and set it to 1

       index=array_srchset("RESOURCE",-1,"",1);

       if(index >= 0)

           // we have found a free resource in the array (and it is now set to 1 to mark it as busy..

               ... etc

       endif

                       

Returns:     Returns the index where a match was found or -1 is no match was found