RTI_LIST Function
Description
RTI_LIST is a utility function to make list handling easier and more consistent. It supports the following commands:
Syntax
rslt = RTI_LIST(command, listID, param1, param2, param3, param4)
Parameters
The function has the following parameters:
| Command | Description |
|---|---|
| READ | Read an existing list. listID should be the name of the list – if the list is stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). If the list is broken into multiple parts, the READ command will concatenate them together. If PARAM1 is set to “1”, the list is deleted after reading. The list that is read is returned as the value of the function call. |
| DELETE | Deletes the specified list. This is a “wrapper” around a call to DELETE_SAVE_SELECT. listID should be the name of the list – if the list is stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). The return value of the function call is null. |
| WRITE | Takes the dynamic array passed in as PARAM1 and writes it (as a saved list) to the list named in listID. If you wish to store the list in a table other than SYSLISTS, you may specify the listID in the format “tablename listname” (without quotes). The return value of the function call is null. |
| ACTIVATE | Read the list specified in listID and turn it into an active select list. This is a “wrapper” around a call to ACTIVATE_SAVE_SELECT or MAKE.LIST. ListID can be a dynamic array (@FM delimited), or the name of the list – if the list is stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). By default, this will activate the list to cursor 0. If a different cursor is desired, this may be specified in PARAM1. The return value of the function call is null. |
| SAVE | Saves the currently active list as a record in a table. This is a “wrapper” around a call to SAVE_SELECT. listID should be the name of the list – if the list is to be stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). The return value of the function call is null. |
| UNION | Joins two select lists together removing duplicates between the two. listID and PARAM1 specify the two lists to be joined. They each may be a dynamic array (@FM delimited), or the name of a list record – if the list is stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). If the resulting list should be sorted, specify “1” in PARAM2. If desired, specify the name of the list to store the resulting list to in PARAM3 – if the list is to be stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). The resulting list will be returned as the value of the function, and (if PARAM3 is not a list ID) in PARAM3. |
| INTERSECT | Returns a list made up of the items where two select lists “overlap”. listID and PARAM1 specify the two lists to be compared. They each may be a dynamic array (@FM delimited), or the name of a list record – if the list is stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). If the resulting list should be sorted, specify “1” in PARAM2. If desired, specify the name of the list to store the resulting list to in PARAM3 – if the list is to be stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). The resulting list will be returned as the value of the function, and (if PARAM3 is not a list ID) in PARAM3. |
| DIFFERENCE | Returns a list made up of the items found only in one of two select lists. listID and PARAM1 specify the two lists to be compared. They each may be a dynamic array (@FM delimited), or the name of a list record – if the list is stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). If the resulting list should be sorted, specify “1” in PARAM2. If desired, specify the name of the list to store the resulting list to in PARAM3 – if the list is to be stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). The resulting list will be returned as the value of the function, and (if PARAM3 is not a list ID) in PARAM3. |
| DISTINCT | Returns a list where any duplicate values have been removed. This is a “wrapper” around RTI_DISTINCTLIST. listID may be either a dynamic array (@FM delimited) or the name of the source list – if the list is stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). If desired, specify the name of the list to store the resulting list to in PARAM1 – if the list is to be stored in a table other than SYSLISTS, then this may be in the format “tablename listname” (without quotes). The resulting list will be returned as the value of the function, and (if PARAM1 is not a list ID) in PARAM1. |
| TOCURSOR | Activates a list (passed as a dynamic array, or from a saved list, or from an already active list) to a specified cursor. listID may be either a dynamic array (@FM delimited), or null (to use the list currently active), or the name of a list record – if the list is stored in a table other than SYSLISTS, then this may be in the format “tablename listname”. PARAM1 specifies the cursor to activate the list to (default is cursor 0). If listID is null, then PARAM2 optionally specifies the cursor to take the active list from (default is cursor 0). The return value of the function call is null. |
| FROMCURSOR | Saves an active list. listID may be either null or the name of the list to save – if the list is to be stored in a table other than SYSLISTS, this may be in the format “tablename listname” (without quotes). PARAM1 is the cursor number to take the list from (default is cursor 0). The list of IDs from the active list is returned as the value of the function and (if listID is not null) saved to the specified list name. |