// drop list related utility functions


    
    // LOOPS SELECT LIST LOOKING FOR A VALUE MATCHING RESTORE VALUE
    // IF FOUND, CHANGES LIST SELECTION (by changing selected index to the index at which the value was matched)
    // SO RESTORED LIST VALUE IS NOW SELECTED
    
    function SetListIndexForValue(listObjId,restoreValue)
    {
       var listOptionsCollection = document.getElementById(listObjId).options;
       var matchValue = restoreValue;
       var optionValue = "";
       var currentListIndex;
       var numListItems = listOptionsCollection.length;
       var matched = false;
       
       for(i=0; i < numListItems; i++)
       {
            optionValue = listOptionsCollection[i].value;
            currentListIndex = i;
            
            if( optionValue == matchValue ) // restore list option found - make selected option and break out for loop
            {
                matched = true;
                document.getElementById(listObjId).selectedIndex = i;
                break;
            }
       }
       
       
       return matched;
       
       // if we have completed for loop without a break, then value could not be restored
//       if( matched == false )
//       {
//            FailedToSetListValueMessage += "<li>failed to restore selected list value for list id = " + listObjId + "</li>";  // TESTING
//            //RestoreFailedCount += 1;
//       }
    }
    
    
       // GET MUILTI SELECT LIST SELECTED VALUES
    // returns an array of selected values (array will be empty/length 0 if no items were selected)
    
    function GetMuiltiSelectListSelectedValues(listObjectId)
    {
        var selectedValuesArray = new Array();
        var muiltiSelectListRef = document.getElementById(listObjectId);
        var numListItems = muiltiSelectListRef.length;
        var itemIsSelected = false;
        
        for(i=0; i < numListItems; i++)
        {
            itemIsSelected = muiltiSelectListRef.options[i].selected;
            
            if( itemIsSelected == true )
            {
                selectedValuesArray.push(muiltiSelectListRef.options[i].value);
            }
        }
        
        return selectedValuesArray;
    
    }