LLOAD_METHOD

Perform list item “load” processing

subroutine LLOAD_METHOD
 a_listid               ,n
 a_request              ,n
 a_data                 ,a
 a_inpid                ,n
 a_disabled             ,n
 a_itemindex            ,n
 a_methoddata1          ,any
      .
      .
      .
 a_methoddata20         ,any

Arguments

a_listid

The ID of the list. (n)

a_request

The load request. (n)

LLOAD_METHOD can accept the flags:

D_LLOADBOT = Load next item at end.

D_LLOADTOP = Load next item at beginning.

LLOAD_METHOD can return these flags:

(unchanged) = Load request satisfied.

D_LEOF = No more items.

a_data

(optional) The data associated with the item. (a)

a_inpid

The ID of the associated input window. (n)

a_disabled

(optional) The true/false flag that indicates whether to disable the item. (n)

a_itemindex

The index of the item desired. (n)

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. (any)

Discussion

LLOAD_METHOD is a subroutine that you write and name. L_PROCESS calls it when it needs to load new items into the list.

You can register the LLOAD_METHOD using the .LISTCLASS script command, or the L_CLASS or L_METHOD subroutines.

If registered, LLOAD_METHOD must either be contained within the current program image or reside in an executable library (ELB) that was either linked to or opened with OPENELB.

Your LLOAD_METHOD subroutine cannot contain any calls, direct or indirect, to L_PROCESS, L_RESTART, or L_DATA.

If a load method is not specified, L_PROCESS will use the default method, which is to return to the caller when new items are needed.

At minimum, your LLOAD_METHOD subroutine should do the following:

If there are any more items to be retrieved at the indicated end of the known list, do all the following:

Display the item into the input window whose ID is a_inpid.
If passed, load a_data with the corresponding list item data.
If passed, set the a_disabled flag to true if the item should be disabled. It is always false upon entry.
Leave a_request unchanged.

If there are no more items to be loaded, set a_request to D_LEOF.

Return.

Note that the a_data and a_disabled arguments are not necessarily the same variables originally passed to L_PROCESS or L_SELECT. These arguments may be a copy. Thus, always set the argument, rather than any global you may be using.

The argument a_itemindex is provided as a reference. It contains the ordinal index of the next item to be loaded for a list. If your program loads the list from the bottom only, this index will be accurate. If your program allows loading from the top, the accuracy of a_itemindex depends on the accuracy of the value passed as the last argument for L_CREATE. Note the following:

If you are using an ActiveX Toolkit list, Toolkit must pre-fetch list items for the Spread control (which is the ActiveX control used for ActiveX Toolkit lists).
Your program should never depend on the timing of load method invocations for specific items. If that level of control is needed, change the load method to load no items, and use D_LAPPEND option for L_PROCESS to add items as needed.
Do not change the value of a_itemindex.

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to I_INPUT or L_INPUT. They are passed, in turn, directly to LLOAD_METHOD. This enables you to communicate additional information to LLOAD_METHOD.

Toolkit passes the method data arguments to the current list processing routine (L_PROCESS, L_INPUT, or L_SELECT) and to the list methods. Thus, if you pass data arguments to one list processing routine, to ensure these arguments are always available, you must pass them to all the list processing routines.

We don’t recommend using %M_SIGNAL in list load methods. Because of the way Toolkit synchronizes menu entry signaling, Toolkit may not execute %M_SIGNAL calls in list load methods.

When using an ActiveX Toolkit list, it’s possible for the list load method to be called without the 20 additional data arguments being passed (a_methoddata1 to a_methoddata20). This can happen immediately after the list is created if the next update occurs prior to entering a list input routine. The update causes the load method to be called, and because Toolkit doesn’t have access to the method data arguments, it can’t pass them.

See also

Overloading UI Toolkit routines for more information on creating this subroutine
Appendix D: Methods

Examples

The following load method filters out unwanted records before displaying one into the list.

subroutine load_method
       a_listid     ,n
       a_request    ,n
       a_data       ,a
       a_inpid      ,n
       a_disabled   ,n
       a_itemindex  ,n
.align
static record
       filchn       ,i4          ;Channel of file being loaded into list
record data                      ;Input data record
       group all_fields      ,a
           tag_field         ,a5
           other_fields      ,a100
       endgroup
.define TAGVAL      ,"ABC"       ;Example tag value
proc
       if (.not. filchn)
          xcall u_open(filchn, "i:i", "filename")
       ;Perform tag processing
       ;Read until we get a record we want to display
       while (tag_field .ne. TAGVAL) do
         reads(filchn, data, eof) [err=eof]
       a_data = data
       xcall i_display(a_inpid, "*CURR*", data)
       xreturn
eof,
       ;This is the last piece of data.
       a_request = D_LEOF
       ;We want to re-load the list from scratch next time.
       clear filchn
       xreturn
endsubroutine