Global lists

The global initer and global lists work together to generate lists for the Service Manager system.

Global lists are stored in the system and are available to any application. Use the global lists tool to add a combo box to a form that displays a list of values, based on a table in your database. For example, set your combo box DisplayList value to $G.time.zones, and the system displays a drop-down list of time zones from the tzfile file.

The global initer builds lists of records from the database. Generally, these lists are used to fill the drop-down lists in combo boxes on display forms. Examples of common lists include a list of all operators in the system, all Incident categories in the system, or all assignment groups on file.

The Startup Lists global list stores all the global lists where the build.startup field equals true. The global list is in the listrepository file. During logon, the system checks the listrepository entry and builds all global lists in this file. If the global list file changes, the Startup Lists global list is marked as expired and rebuilds the next time the lister background process runs. This updates the listrepository record.

Note: Since the lister background process does not run continually, there may be a slight delay between the time a global list changes and when it appears in the listrepository record.

The global initer consists of two parts:

• A server side element which generates and packages lists according to a user-defined schedule.
• A client-side requester which queries lists from the server and places them into client-side memory.

Lister

To build a dynamic list, generate a list definition block. The background scheduler (lister) wakes up every sixty seconds to search for obsolete lists and uses list definition blocks to generate new lists, which are then stored in the list repository.

Once lister has built a list on the server, multiple clients can request and share the same list without each client having to build its own copy. This method of building lists improves system speed and helps server-side performance.

Note: Lister variables can be defined for scalar type fields only and not for array fields.

Global initer considerations

• For performance considerations of the Service Manager server, a global list should contain no more than 2800 individual elements. Exceeding this limit may degrade the server performance.
• The total size of the globallist record, which contains the full lists, cannot exceed the logical file limit set for the system.
• The sort field must be a key on the table which is used to generate the list.
• No matter what you set as the reset time, the server initer can only refresh the lists once every time its scheduler wakes up. Thus, if you have a list with reset time = 5 seconds and the scheduler runs every 60 seconds then the list will actually refresh every 60 seconds.

Returning a list to your client

Use one of the following methods to return a particular list, or set of lists, to an Service Manager client:

• Build a list on startup.
• Configure the lists with Format Control.

Configuring lists with Format Control

Use Format Control to ask for a list only when a specific form is displayed. This procedure is most efficient when the form defined is not displayed frequently.

Access a list record

1. Click Tailoring > Tailoring Tools > Global Lists.

2. Enter optional search criteria, and then click Search.

   A global list of definitions opens.

3. To create a new list, click Add.
4. If you edit an existing list, click Save.
5. Click OK.

Bind a list to a form

Lists are bound to the forms they serve. The global variables are applied in Forms Designer.

1. Click Tailoring > Forms Designer.

2. Type the name of the form you wish to modify in the Form field of the Forms Designer dialog box.

   For example, type: contact.detail.subform. This is the name of the subform used by problem.template.open.g, problem.template.update.g, and problem.template.close.g to display contact information.

3. Click Search.

   The contact detail subform opens.

4. Click Design.
5. Add a combo box with a label called Time Zones to the form, using the following values:
   
   

   Field	Value
   Input	time.zones
   ValueList	$G.time.zones
   DisplayList	$G.time.zones

   
   

6. Wait for lister to refresh the time.zones global list, or go to the list definition panel ( Tailoring > Tailoring Tools > Global Lists) and reset the refresh time.

   Note: If you leave the DisplayList value blank, the contents of the ValueList will be used for both lists.

Build lists on startup

The Build List on Startup option, if enabled for a global list, does not initiate a "rebuild" of the list at user login, but simply makes the current list available to a new logged-in user.

If a global list has a "Filename" and "Limiting SQL" defined, to automatically rebuild the list when something is changed in the source file, the lister background process must be running.

A global list is rebuilt on either of these actions:

• A user clicks the Rebuild Global List option (the current and new user sessions get the new list)
• The lister process is running against this global list (whose expiration time must be in the past)

Use the following procedure to set the globallists record to build on startup.

1. Click Tailoring > Database Manager.
2. Type globallists in the Table field of the Database Manager dialog box, and then click Search.
3. In the List Name field, type the name of the list you want to view. For this example, type time.zones.

4. Click Search.

   The time.zones file opens.

5. Select Build List on Startup?.
6. Click Save.
7. Open an incident record to view the new field.

Configure lists with Format Control

1. Determine the base name of the form, which you added to your list.
2. Click Tailoring > Format Control.

3. Type the base name of the form in the Name field.

   For this example, create a new record for the form problem.template.update.

   Note: If you add a combo box to a subform, attach the Format Control record to any base form using that subform. (Do not attach the Format Control record to the subform itself.)

4. Click Search.
5. If a Format Control record does not exist for your form, create one. Click New.
6. Click Subroutines in the form, or select it from the More Actions menu.
7. Select Show Expanded Form from the More Actions menu.
8. Scroll to the first empty section and set up a Subroutine call using the following values:
   
   

   Parameter	Value
   Application name	apm.global.initer
   Names/Values	See next table
   Before	true
   Display	true

   
   

   Names	Values	Definition
   names	{"time.zones"}	Array of lists to be moved
   name	create	Action to perform (create lists)

   
   

9. Click Save to save changes to an existing record.

   Caution: If you are attempting to add a new record from an existing record, make sure that you do not click Save because doing so will replace the existing record with the new record. If you are adding a new record, click Add.

10. Click Add to add a new record.

This Format Control record returns the time.zones list to all incident records displaying the Contact Detail tab, regardless of mode.

Calling the apm.global.initer several times from Format Control will not slow the system appreciably. The system automatically keeps track of what lists are already on the client and will not recover them unnecessarily; however, if you want the Global Initer to reassemble the list regardless, invoke it with the refresh parameter (rather than the create value listed in the above). called with the refresh parameter, the Global Initer returns all the lists passed to the names array, even if they are already in client memory.

Determine if a scheduler record exists

1. Click Tailoring > Database Manager.
2. Type schedule in the Form field of the Database Manager dialog box.
3. Press Enter or click Search.
4. Open schedule from the record list (double-click the record or click Enter). A blank Schedule File record is displayed.
5. Type List Runner in the Name field.
6. Click Search.
   If a record is found, it will open for viewing and editing.

Determine if the regen cycle is realistic

1. Click Tailoring > Database Manager.
2. Type apm.global.list.entry in the Form field of the Database Manager dialog box.
3. Click Search.
   A blank record from the globallists file is displayed.
4. Click Search.
5. Select the list you want to regenerate from the Record list.
6. Check the value in the Regen Every field.
   Use a short time interval for lists that change frequently and a longer interval for lists that change only occasionally.

Determine when a list was last regenerated

1. Click Tailoring > Database Manager.
2. Type apm.global.list.entry in the Form field of the Database Manager dialog box.
3. Click Search.
   A blank record from the globallists file opens.
4. Click Search.
5. Select the list you want to regenerate from the Record list displayed.
6. Check the value in the Expiration field to see when the list was last regenerated.

Move a Global List to a client

To move a global list into client side memory, you call a routine called apm.global.initer.

This routine accepts two parameters:

• An array containing the name of the lists that you want.
• A keyword, either create or refresh.

When apm.global.initer is invoked with the refresh parameter, it collects the newest version of its list from the server, whether that list already exists in the client’s memory space. If invoked with the create parameter, it collects a list from the server only if a copy does not already exist.

If you are programming in RAD, you can invoke apm.global.initer directly from your code. If you are using the Global Initer to fill combo boxes for display on a form, you can invoke the Global Initer as a subroutine using Format Control for the format in question.

Regenerate all lists

If none of the troubleshooting steps to this point have succeeded in regenerating your list, you should regenerate all the lists in the system. This procedure makes all the lists in the system obsolete and enables you to update the entire file.

1. Click Tailoring > Database Manager.
2. Select Administration Mode.
3. Type apm.global.list.entry in the Form field.

4. Click Search.

   A blank search form from the globallists file opens.

5. Click Search to display a list of lists.
6. Click Mass Update.

7. Click Simple Update.

   A blank form opens. This form is identical in appearance to the lister record, but contains different option buttons.

8. In the Expiration field, change the date to any date in the past. You can either type the date and time, or select a date from the calendar.

9. Click Execute.

   The expiration date of all the lists in the globallists file is reset.

10. Return to the home menu.
11. Type *aapm.server.initer in the command line.
12. Press Enter.

13. Log off Service Manager, and then log back on.

    All the lists in the system are regenerated whether they are actually obsolete.

Regenerate obsolete lists

If you perform all the troubleshooting steps and the system still does not display the most current version of your list, regenerate all the obsolete lists in the system. For a large system with numerous obsolete lists, this procedure may take a few minutes.

You can change the expiration date of a list to a date in the past prior to regenerating, in order to force regeneration.

Note: If the expiration date of your list has not passed, the list will not be flagged as obsolete, and therefore not regenerated.

To regenerate obsolete lists:

1. Type *aapm.server.initer in the command line.
   Running this application will force the system to regenerate all obsolete lists.
2. Log off Service Manager, and then log back on.

Start the server side component of the global initer

The server side component of the Global Initer consists of a routine called apm.server.initer. A background scheduler called lister has been defined to run apm.server.initer.

If lister did not start with the system:

1. Click System Status on the System Navigator.

   The System Status utility opens.

2. Click Start Scheduler.

3. Double-click lister.startup.

   Every sixty seconds, lister checks and refreshes any global lists that have passed their reset time.

See a complete list of all the global lists on my system

1. Click Tailoring > Database Manager.
2. Type globallists in the Table field of the Database Manager dialog box.

3. Click Search.

   A blank search form from the globallists file is displayed.

4. Click Search.

   A list of all the global lists opens. You can scroll through the complete list of records.

Verify lister status and configuration

1. Click System Status in the System Navigator.
2. Check to see if lister appears in the list of processes running on your system.
3. If lister in not on the list, click Start Scheduler.

4. Double-click lister.startup in the Startup Record list to start the program.

   Note: Double-click startup to start all processes.

View changes to a list

1. Click Tailoring > Database Manager.
2. Type globallists in the Table field of the Database Manager dialog box.

3. Click Search.

   A blank record from the globallists file is displayed.

4. Click Search.
5. Select the list you want to view from the Record list.
6. Check that the changes appear.