LIST_Q

Syntax

Example

Description/Remarks

LIST_Q
connection_number
,
"title",
"SQL_statement",
"optional_position",
"optional_text"

 

LIST_Q 1,
"Available Templates",
"Select * from TEMPLATE"

This example would return a list of template names read from the data file.

LIST_Q 1,
"Available Templates",
"Select Trim(NAME) + ‘,’
+ FILENAME
from TEMPLATE"

This example would return a list of template names and their file name separated by commas.

LIST_Q 1,
"Pick an option",
"Select * from TEMPLATE",
"S", "Go back",
"E", "Exit template",
"E", "Exit system"

This example would return a list of template names with optional items in the list.  The first item in the list would be "Go back" followed by the list of templates.  The last two items in the list would be "Exit template" and "Exit system".

LIST_Q 1,
"Pick an option",
"Select * from TEMPLATE",
"B", "Go back",
"B", "Exit template",
"B", "Exit system"

This example would return a list of template names and three extra buttons beneath the list. The three buttons would be displayed in the following order: "Go back", "Exit template", and "Exit system".

 

NOTE: You can use an unlimited number of "optional_position" and "optional_text" parameters.

You can also use multiple "S" and multiple "B" parameters.

This command executes an SQL statement and displays a list of the values from the first column of all rows in the SQL query result set, as well as values you may specify with "optional_position" and "optional_text" parameters.

Alternately, this command can be used with an empty string ("") for the "SQL_statement" parameter, to display a list containing only the values you specify with "optional_position" and "optional_text" parameters.

 

The "title" parameter sets the list title displayed above the list.

You may add buttons to the list window, regardless of the contents of the list.

This command returns either the value determined by the LIST_OPT command or an identifier for the button clicked by the operator.

When listing the results of an SQL query result set, the LIST_Q command will function correctly only if a connection has already been established with Q_CONNECT. Only the first column of the SQL query result set will be displayed in the list. To display the contents of multiple columns as distinct entries in the list, use the SelectColumns keyword. If there is an error, the listbox will display the error information.

When the "SQL_statement" parameter is an empty string (""), the LIST_Q command will function correctly even if a connection has not been established with Q_CONNECT.

The "optional_position" and "optional_text" must be used together:

  • When "optional_position" is set to "S" for start of list or "E" for end of list, the "optional_text" is placed in the list at that position.

  • When "optional_position" is set to "S", you can change the window caption by setting the "optional_text" to "TITLE::new_title"

  • When "optional_position" is set to "B" for an additional button, the "optional_text" becomes the caption for that button.  The button will be displayed between the list and the OK button.

    If the "optional_text" for the button caption is blank, the button will not be displayed.

    Multiple buttons will be arranged according to the order in which they appear in the formula. Two consecutive buttons with short captions may be placed on the same row. To arrange a button on its own row; increase the length of the caption by adding spaces or other characters to the "optional_text" parameter.

    If the user clicks one of these buttons, the LIST_Q command returns the string value " Btn:n", where n is the number of the button clicked.  Clicking one of these buttons will also note which items have been selected in the list and will use them to set the value of MySVar "LQ_Btn_Value" (for a single-select list) or MySArr "LQ_Btn_Array" (for a multiple-select list).  For example, clicking the first button returns the value " Btn:1" and sets the value of MySVar "LQ_Btn_Value" or MySArr "LQ_Btn_Array" to the selected list item(s).

    If the user clicks the OK button, the values in MySVar "LQ_Btn_Value" and MySArr "LQ_Btn_Array" will be cleared and the LIST_Q command will return the value determined by the LIST_OPT command.

  • When "optional_position" is set to "B", you can change the label on the OK button by setting the "optional_text" to "OK::new_label".

    This renamed button will still function as the OK button, but it will now be displayed with the label you have specified.

  • When "optional_position" is set to "B", you can change the label on the CANCEL button by setting the "optional_text" to "CANCEL::new_label".

    This renamed button will still function as the CANCEL button, but it will now be displayed with the label you have specified.

  • When "optional_position" is set to "A" for an array, the "optional_text" becomes the name of the string array that will be filled with all the items selected by the user. You can later use the MYSARR command to retrieve these values from the array.

    The array will be reset, so that all indexes are blank, before the user-selected items are added to it. The first selected item will be placed in index_number 1 of the array, the second item in index_number 2, and so on. If the user selected nothing, all indexes of the array will be blank.

    The user may select multiple items in the list, and the LIST_OPT 5 setting is ignored.

More than one optional entry may be used.

The screen containing the list will correctly size itself based on the contents of the SQL query result set and any "optional_text" items added to the list.

You can use the LIST_OPT command to modify display settings for the screen containing the list.

LIST_Q
connection_number
,
"title",
"SelectColumns
col1
, col2, col3
From table",
"optional_position", "optional_text"

LIST_Q 1,
"Choose one:",
"SelectColumns
StdVar1, StdVar2,
StdVar3, StdVar4
From VSTDS
Where PartNo =
'Service calls%'"

This displays a list of the standard variables for all standards that begin with 'Service calls'.  If there are two standards that begin with this text, then this list will contain eight values as follows:

  1. Standard variable 1
    (1st standard)

  2. Standard variable 2
    (1st standard)

  3. Standard variable 3
    (1st standard)

  4. Standard variable 4
    (1st standard)

  5. Standard variable 1
    (2nd standard)

  6. Standard variable 2
    (2nd standard)

  7. Standard variable 3
    (2nd standard)

  8. Standard variable 4
    (2nd standard)

When used with the keyword "SelectColumns" in the SQL_statement portion of the formula, the list displayed to the data entry operator will contain the specified column values from all rows of the query result set.

LIST_Q
connection_number
,
"title",
"PROCESS[process_name]",
"optional_position",
"optional_text"

LIST_Q 1,
"Pick a defect",
"PROCESS[B-MIXING]"

This displays a list of defects for process B-MIXING.  

Additional options can also be added to the start and end of the list, as shown in the following example:

LIST_Q 1,
"Pick a defect",
"PROCESS[B-MIXING]",
"S", "Go Back",
"E", "Exit"

When used with the keyword "PROCESS[process_name]" in the SQL_statement portion of the formula, the list displayed to the data entry operator will contain the defects associated with the specified process_name.

Even though a connection_number is required in the command syntax, LIST_Q with the PROCESS[process_name] option will automatically access the connection and table name information used to log in to the SPC Data Entry module.

Error conditions that are trapped and return specific messages in the list are:

  • No defects for process = "No defects found for process"

  • Process doesn't exist = "process process_name does not exist"

  • Table doesn't exist  = "Table table_name not found or missing from ddf file"

  • Any other error = "Unable to read defects from database"

If changes are made to the list of defects for any process, these changes will be reflected the next time the SPC Data Entry module is launched.

LIST_Q
connection_number
,
"title",
"array[array_name]",
"optional_position",
"optional_text"

LIST_Q 1,
"Pick a file",
"array[MyList]"

This displays a list of all the values stored in MySArr "MyList" 

Additional options can also be added to the start and end of the list, as shown in the following example:

LIST_Q 1,
"Pick a file",
"array[MyList]",
"S", "Go Back",
"E", "Exit"

When used with the keyword "array[array_name]" in the SQL_statement portion of the formula, the list displayed to the data entry operator will contain all the values in the MySArr specified by array_name.

Even though a connection_number is required in the command syntax, LIST_Q with the "array[array_name]" option will not use the connection.

 

Values in the list are sorted in order from lowest to highest index. They are not sorted based on the value.