LLOAD_METHOD
Perform list item “load” processing
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
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:
1. | 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.
2. | If there are no more items to be loaded, set a_request to D_LEOF. |
3. | 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