16 list processing function for installshield internal library functions
The list is used to save relevant information groups. In InstallShield, there are two types of lists: string lists and digital lists. Provides two sets of functions to handle the list: each process. The list function ends with "ITEM" handles a list. A list of strings with a list function ending with "String". You can't use the digital list function to use the character string list, and vice versa. Below is a function of processing a list in a mount script.
ListAdditem
Add one list.
ListAddstring
Add a string to a list.
Listcount
Returns the number of strings or numerical elements in a specified list.
Listcreate
Create a new string or numeric list.
ListCurrentItem
Returns the current item in a list.
Listcurrentstring
Returns the current string in a list.
ListdeeteItem
Delete the current item in a list.
ListdeeteString
Delete the current string in a list.
Listdestroy
Eliminate a list.
ListfindItem
Enables the specified item to become the current project in a digital list.
Listfindstring
Make the specified item into the current item in a string list.
ListgetfirstITEM
Retrieve the first element from a numeric list.
ListGetfirststring
Retrieve the first element from a list of strings.
ListGetNextItem
Retrieve the elements after the current element from a numeric list.
ListgetnextString
Retrieve the elements after the current element from a string list.
Listreadfromfile
Read a text file to a list.
ListSetCurrentItem
Set the current elements in a digital list.
ListSetCurrentstring
Set the current elements in a string list.
ListsetInDex
Use a claim to set the current element of a list.
ListwrittoFile
Write a string list to a file.
16.1 ListAdditem
Syntax: ListAdditem (ListID, Nitem, NPLAG);
Description: The ListAdditem function adds a numeric element to the front or back of the current element in a numeric list. To traverse a list, first call ListGetFirstITITEM to get the first element of the list; then call ListGetNextItem until you reach the list. To make one of the specific elements in the list a current element, call ListSetIndex.
parameter:
ListID
Specify the name of a digital list. The list identified by the ListID must have been initialized by the listCreate function.
NITEM
Specifies the numerical elements to be added to the list.
NPLACEMENTFLAG
Specifies where to place and currently related NIITEMs. New elements can be before or after the current element. One of the following predefined constants in this parameter location:
After: Add new elements to the current element in the list.
Before: Adding new elements before the current element in the list.
return value:
0: ListAdditem successfully adds an element to a numeric list.
<0: ListAdditem failed to add an element to a list of numbers.
annotation:
· ListAddItem only works on a list of digital.
16.2 ListAddstring
Syntax: ListAddString (ListID, Szstring, NPLACEments);
Description: The ListAddString function adds a string to a string before or after the current element in the list. To traverse a list, first call ListGetFirstITITEM to get the first element of the list; then call ListGetNextItem until you reach the list. To make one of the specific elements in the list becomes a current element, call ListSetIndex. parameter:
ListID
Specify the name of a string list. The list identified by the ListID must have been initialized by the listCreate function.
Szstring
Specifies the string added to the list.
NPLACEMENTFLAG
Specifies where placed and current elements associated with Szstring. The new string can be before or after the current element. One of the following predefined constants in this parameter location:
After: After adding a new string to the current element in the list.
Before: Adding a new string before the current element in the list.
return value:
0: ListAddString Successfully Adds a string to the list.
<0: ListAddString Fails to add a string to the list.
annotation:
· ListAddString is only working in a string list.
16.3 ListCount
Grammar: Listcount (ListID);
Description: The ListCount function returns the number of elements in a list.
parameter:
ListID
Specifies the name of a string or numeric list.
return value:
> = 0: The number of items in the list.
<0: ListCount Fails to determine the number of elements in the list.
annotation:
· This function works in a string and a list of numbers.
16.4 ListCreate
Syntax: listcreate (nListType);
Description: The ListCreate function creates an empty string or a digital list. Remember a list that cannot include two types of elements. InstallShield offers different function groups to work in a list of characters and a list of numbers. You must not use the ID of a numeric list to use the character string list function, and vice versa. The list function ends with "ITEM" handles a list. A list of strings with a list function ending with "String".
When you no longer need a list, you can use the listDestroy function to eliminate the list. Each list has a pointer to identify the current element of an element. Different list functions reposition the current elements of the list. When you call any list of table functions, you must pass a valid ID of the list. Determine the function creation list successfully. Otherwise, all list functions fail because of invalid list.
parameter:
NLISTTYPE
Specifies the list type to create. One of the following predefined constants in this parameter location:
Numberlist: Specify a list of numbers.
StringList: Specify a string list.
return value;
ListID: The ID of the newly created empty list. You must use this ID whenever you want to use the list in other installshield list functions. You must detect the variable and confirm that the function does not return List_null.
List_null (-1): Indicates that installshield failed to create a list. That is a result of a serious memory problem, this is a very few cases. It may be difficult to continue installation when there is such a memory problem.
annotation:
· When you pass a valid list ID, you must create the list using ListCreat when you need a function of a list. You can create any list in a script. A list may contain any elements. The only restriction is the size of effective idle memory.
16.5 ListCurrentItem
Syntax: ListCurrentItem (ListID, NVItem);
Description: The ListCurrentItem function retrieves the current element from the digital list specified by the listID.
parameter:
ListID
Specify a list of numbers.
NVItem
Returns the value of the current element in the list.
return value;
0: Indicates that the function has successfully retrieves the current element in a numeric list.
<0: Indicates that the function failed to retrieve the current element in a digital list.
END_OF_LIST (1): Indicates that the list is empty and there is no current element.
annotation:
· This function is only working on a list of numbers.
· You can also use the listGetfirstITEM and ListGetNextItem functions to traverse the list and make any elements as the current element.
16.6 ListCurrentstring
Syntax: ListCurrentString (ListID, SVString);
Description: The ListCurrentString function retrieves the current element from the list list specified by the listID.
parameter:
ListID
Specify a list of strings.
Svstring
Returns the value of the list of current elements.
return value:
0: Indicates that the function successfully retrieves the current element in a string list.
<0: Indicates that the function cannot retrieve the current element in a string list.
END_OF_LIST (1): Indicates that the list is empty and there is no current element.
annotation:
· This function is only working on a string list.
· You can also use the listGetFirstString and ListGetNextString functions to traverse the list and make any elements as the current element.
16.7 ListDeleteItem
Syntax: ListdeeteItem (ListID);
Description: The ListDeleteItem function removes the current element from the numeric list you specified in ListID.
parameter:
ListID
Specifies a list of digital lists from which the current element is deleted.
return value:
0: Indicates that the function successfully deletes the current element from a numeric list.
<0: Indicates that the function failed to delete the current element from a digital list.
END_OF_LIST (1): Indicates that the list is empty and there is no current element.
annotation:
See the annotation of the ListCurrentItem.
16.8 ListdeeteString
Syntax: ListDelectedString (ListID);
Description: The ListDeleteString function removes the current element from the list of strings you specified in ListID.
parameter:
ListID
Specifies a list of strings from which the current element is deleted.
return value:
0: Indicates that the function successfully deletes the current element from a string list.
<0: Indicates that the function failed to delete the current element from a string list.
END_OF_LIST (1): Indicates that the list is empty and there is no current element.
annotation:
See the annotation of ListCurrentString.
16.9 ListDestroy
Grammar: ListDestroy (ListID);
Description: The ListDestroy function eliminates the content and list of a list itself. Use this function to delete a list or numeric list specified by a listID.
parameter:
ListID
Specify a list or numeric list to be eliminated.
return value:
0: Indicates that the function successfully eliminated the list and remove it from memory.
<0: Indicates that the function failed to eliminate a list.
annotation:
· This function can act both in a list of strings, or a digital list. Once a list is eliminated, do not use the ListID in any list function.
· Eliminate all lists you created when you no longer need or when you install the script. When you eliminate a list, you release all memory contacting the list.
16.10 ListFindItem
Syntax: ListFindItem (ListID, NItem);
Description: The ListFindItem function looks for a specific element in a digital list, starting from the current element and continues from that point. If you want to find the list header, use the ListGetFirstItem function. When ListFindItem finds an element, it becomes the current element of the list. parameter:
ListID
Specifies the list of digits to look up.
NITEM
Specifies the item to find in the list.
return value:
0: Indicates that the function successfully found the required elements.
<0: Indicates an error prevention function to find the specified list. For example, an error will occur if the list specified by ListID does not exist.
END_OF_LIST (1): Indicates that installshield finds the list of the list but does not find the required elements.
annotation:
· This function is only working on a list of numbers.
16.11 ListFindString
Syntax: ListFindString (ListId, Szstring);
Description: The listFindString function looks for a specific element in a string list, starting from the current element and continues from that point. If you want to start searching from the list, use the listGetfirststring function. When ListFindString finds an element, it becomes the current element of the list.
This function is case sensitive to a string comparison.
parameter:
ListID
Specifies the list of strings to look for.
Szstring
Specifies the string to find in the list. When you find the string, InstallShield performs a case-sensitive comparison.
return value:
0: Indicates that the function successfully found the required elements.
<0: Indicates an error prevention function to find the specified list. For example, an error will occur if the list specified by ListID does not exist.
END_OF_LIST (1): Indicates that installshield finds the list of the list but does not find the required elements.
annotation:
· This function is only working on a string list.
16.12 ListGetFirstITEM
Syntax: ListGetfirstITEM (ListID, NVItem);
Description: The ListGetFirstITEM function retrieves the first element from a numeric list. The first item becomes the current element in the list.
parameter:
ListID
Specifies a list of numbers to retrieve their first element.
NVItem
Returns the first element of the numeric list.
return value:
0: Indicates that the function successfully retrieves the first element of a numeric list.
-1: Indicates that an error prevention function retrieves the first element in a numeric list.
END_OF_LIST (1): Indicates that the list is empty.
annotation:
· This function is only working on a list of numbers.
16.13 ListGetFirststring
Syntax: ListGetfirstString (ListID, SVString);
Note: The listGetFirstString function retrieves the first element from a string list. The first item becomes the current element in the list.
parameter:
ListID
Specifies a list of strings to retrieve their first element.
Svstring
Returns the first element of the string list.
return value:
0: Indicates that the function successfully retrieves the first element of a string list.
-1: Indicates that an error prevention function retrieves the first element in a string list.
END_OF_LIST (1): Indicates that the list is empty.
annotation:
· This function is only working on a string list.
16.14 ListGetNextItem
Syntax: ListGetNextitem (ListID, NVItem);
Description: The ListGetNextItem function retrieves items after the current element in a numeric list. The retrieved item becomes the current element in the list. parameter:
ListID
Specifies a list of digital lists to be retrieved from the next element.
NVItem
Returns a project that follows the current element in the numeric list. The project becomes the current element in the list.
return value:
0: Indicates that the function successfully retrieves the elements after the current element in a digital list.
-1: Indicates that an error prevention function retrieves a specified element in a numeric list.
END_OF_LIST (1): Indicates that the current project is the last element in the list.
annotation:
· This function is only working on a list of numbers.
16.15 ListGetNextString
Syntax: ListGetNextString (ListID, SvString);
Description: The ListGetNextString function retrieves items after the current element in a string list. The retrieved item becomes the current element in the list.
parameter:
ListID
Specifies a list of strings to retrieve the next element.
Svstring
Returns a project that follows the current element in the numeric list. The project becomes the current element in the list.
return value:
0: Indicates that the function successfully retrieves the elements after the current element in a string list.
-1: Indicates that an error block function retrieves a specified element in a string list.
END_OF_LIST (1): Indicates that the current project is the last element in the list.
annotation:
· This function is only working on a string list.
16.16 ListReadFromFile
Syntax: ListreadFromFile (ListID, SZFILE);
Description: The listFromFile function reads a text file to a list. Once you put a text file into a list, you can use it in the installation to use different functions, such as displaying a README file at the end of the installation or writing a string list to the disk with ListWrittoFile.
This function allows you to easily put the entire file into a list instead of creating a list item.
parameter:
ListID
Returns a list of reads a row from the file specified by SZFile. The list identified by the ListID must have been initialized by ListCreat.
SZFile
Specifies the full qualification of the file that will be read into the list.
return value:
0: Indicates that the function successfully reads the text line in a file into a list.
<0: Indicates that the function failed to read the text line in a file into a list.
annotation:
This function detects a commissioning of each string and uses these characters as the delimiter of each element in the list.
· This function only acts on a string list and text file.
16.17 ListSetCurrentItem
Syntax: ListSetCurrentItem (ListID, NItem);
Description: The ListSetCurrentItem function assigns NITEM's value to the current element in a numeric list.
parameter:
ListID
Specifies the name of its current element to be updated. The list identified by the ListID must be initialized by ListCreat.
NITEM
Specifies the numeric value of the current element to be replaced.
return value:
0: Indicates that the function successfully updates the current element in the numeric list.
<0: Indicates that the function failed to update the current element in the numeric list.
END_OF_LIST (1): Indicates that the list is empty.
annotation:
· This function is only working on a list of numbers.
16.18 ListSetCurrentstring
Syntax: ListSetcurrentstring (ListID, Szstring);
Description: The listSetCurrentString function assigns the value of szstring to the current element in a string list.
parameter:
ListID
Specify the name of the string list of its current elements to be updated. The list identified by the ListID must be initialized by ListCreat. Szstring
Specifies the string value of the current element to be replaced.
return value:
0: Indicates that the function successfully updates the current element in the string list.
<0: Indicates that the function failed to update the current elements in the string list. The usual reason for this error is that the subscript is outside the range of effective list elements.
annotation:
· This function is only working on a string list.
16.19 ListSetIndex
Grammar: ListSetIndex (ListID, NINDEX);
Description: The ListSetIndex function uses a subscript to specify a specific element in a string list or a numeric list as the current element. You can also use a constant to retrieve an element in a list or a head or tail that jumps to the list. Access the item in the list by using the subscript, you can process the numeric list or string list as a queue.
The number of subscripts starts with 0. For example, if you enter 5 in the parameter NINDEX, the items in the sixth physical location in the list becomes the current element. Use ListCurrentItem and ListCurrentString to retrieve the value of the current element.
parameter:
ListID
Specifies the name of the string list or numeric list to be set to be set.
Nindex
Specify the number of elements you want to set to the current element. The list elements start counting from 0. One of the parameter values or one of the following predefined constants is transmitted:
ListFirst: Move the first element to the list.
Listlast: Move the last element of the list.
ListNext: Move the next element to the list.
ListpRev: Move to the previous element of the list.
return value:
0: Indicates that the function successfully updates the current element in the list.
<0: Indicates that the function has not updated the current element in the list.
END_OF_LIST (1): Indicates that the subscript is outside the range of effective list elements.
annotation:
· After you set the indexed element for the current element, you can use the ListCurrentItem or ListCurrentString function in the script to retrieve the value of the index (current) item.
· This function can operate on a string list and a digital list.
16.20 ListwrittoFile
Syntax: ListwrittoFile (ListID, SZFileName);
Description: The listwritetofile function writes a string list to a text file. Each string is displayed in a row separated in a text file.
parameter:
ListID
Specify the string name written in a text file.
SZFileName
Specifies the full qualification of the file to which you want to write a string list. If the file does not exist, it is created. If the file already exists, it is modified.
return value:
0: The function is successful.
<0: The function failed.
