Question & Answer
Question
How can I avoid the overhead of loading reference list fields in ClearQuest records?
Cause
Loading a record can take a long time when the form has many reference list fields or those fields contain many items.
Answer
In IBM Rational ClearQuest, a List View form control displays the records associated with a field whose type is Reference List. One of the primary uses of this control is to display the children in a parent/child relationship.
The Parent/Child control consists of a List View control along with buttons that can be used to add, create new, or remove items from the list. The feature described in this technote applies to the List View control by itself or when part of a Parent/Child control.
The List View control displays the associated reference list in a multi-column format, with selected fields from the referenced records shown in tabular form. The ClearQuest Web client must run a query to load those fields from the referenced fields in order to show them in the List View control. This can take a while, especially when many fields are being shown or when a reference list has many values.
Individual reference list fields can now be configured to be loaded only when the user needs to see the values. When enabled for a field, the web client does not need to run the extra query when loading the record, which results in less time to load the record. The user will see a button in the space where the List View control content would normally be shown. The localized button name is "Load" followed by the name of the reference list field, such as "Load Customers" or "Load Related_Defects". This is similar to how the History field is deferred in a Feature Level 9 database (see technote #1959953).
Enabling
Enabling this feature for reference list fields requires two steps: setting a master property, and specifying which fields are to be enabled by creating a set of folders in the Public Queries workspace.
1. Set the LISTVIEW_QUERY_FOLDER master property to the pathname of a folder in the public workspace. You must create the named folder. This folder is where you will create subfolders that correspond to the names of record types and reference list fields.
2. Determine which reference list fields of what record types you want to be loaded on demand.
2A. For each record type, create a subfolder in the list view folder identified in step 1, and name it the same as the record type. This name must have the same spelling, but is not case sensitive.
2B. Within the record type subfolder created in step 3, create another folder and name it the same as the reference list field of that record type. Create one folder for each reference list field.
The result will be a three-level folder structure, like this:
List-View-Folder/Record-Type-Name/Reference-List-Field-Name
For example, consider a schema with Defect and Escalation record types. Defect has reference list fields Related and Tasks. Escalation has reference list fields Customers and Defects. The following folder structure will enable deferred loading for those fields if the LISTVIEW_QUERY_FOLDER master property is set to "Public Queries/List-Views".
Public Queries/ List Views/
Defect/
Related/
Escalation/
Tasks/Customers/
Defects/
All of these folders are normal workspace folders and may contain queries or other workspace items, although this is not recommended. Any non-folder item will be ignored, and a subfolder will be ignored if it does not correspond to a record type or a field name within that record type. If the folder identified by the LISTVIEW_QUERY_FOLDER does not exist or cannot be read by the user (due to Access Control Lists--workspace ACLs), the feature is effectively disabled for all record types. The Change Management (CM) Server SystemOut.log will contain informational messages if the folder does not exist or cannot be read, or if any of the subfolders do not correspond to record types or fields.
Here is another example where the Customer list of the Defect record type from the DefectTracking schema has been enabled for deferred loading. The master property has been set to "Public Queries/ListView Folder". Here is that folder in the workspace:
Here is the Customer tab of a Defect record showing the "Load customer" button:
Additional Details
The content of the List View Query folder is read as needed within any session that needs to load a record of a particular type. An existing session may need to log out and back in to see any changes within the List View Query folder.
Setting the LISTVIEW_QUERY_FOLDER master property
The LISTVIEW_QUERY_FOLDER master property can be set to apply to all ClearQuest User Databases associated with a Schema Repository or to a specific User Database. A setting for a specific User Database will override the general setting that applies to all User Databases.
Enable the List View query feature for all User Databases:
installutil setmasterproperty <dbset_name> <cq_login> <cq_password> LISTVIEW_QUERY_FOLDER "Public Queries/List Views"
Enable the List View query feature using a different folder in just the SAMPL database:
installutil setmasterproperty <dbset_name> -user_db_name SAMPL <cq_login> <cq_password> LISTVIEW_QUERY_FOLDER "Public Queries/Admin/List Views"
Disable master property
To remove the setting for all databases and the one for the SAMPL database (as set in the previous examples), set the property to an empty string:
All:
installutil setmasterproperty <dbset_name> <cq_login> <cq_password> LISTVIEW_QUERY_FOLDER ""
SAMPL only:
installutil setmasterproperty <dbset_name> -user_db_name SAMPL <cq_login> <cq_password> LISTVIEW_QUERY_FOLDER ""
Related Information
Was this topic helpful?
Document Information
Modified date:
17 June 2018
UID
swg21976572