L_STATUS

Retrieve the status of a list

xcall L_STATUS(list_id[, flags, ...])

Arguments

list_id

The ID of the list to retrieve information for. (n)

flags

(optional) One or more of the information request flags and its return values shown in the table below. (n)

Discussion

L_STATUS provides the only reliable means of obtaining information about the current state of a list. Attempts to retrieve or infer such information by other means may have unpredictable results. For instance, you might think that the placement of an associated input window could help you obtain the current item’s location within the visible list. However, this assumption might not always be true. (To keep the input window’s movement to a minimum, the window may not always be synchronized with the current item.)

Each information request flag, as shown in the table below, must be followed by its argument field(s). You can specify a maximum of 40 information request flags and return value fields in one call to L_STATUS.

Information request flags
Request flag and return values	Description
D_LABTRSN, reason	Returns the code that indicates the reason for aborting. See the tools.def file. (n)
D_LACTIVEX, list_typ	Returns true (1) if the list is an ActiveX Toolkit list; otherwise, returns false (0). (n)
D_LATBOTTOM, bottom_flag	Returns true (1) if the user is at the bottom of the list (with no more to load at the bottom); otherwise, returns false (0). (n)
D_LATPGBOT, pgbot_flag	Returns true (1) if the user is at the bottom of the page; otherwise, returns false (0). (n)
D_LATPGTOP, pgtop_flag	Returns true (1) if the user is at the top of the page; otherwise, returns false (0). (n)
D_LATTOP, top_flag	Returns true (1) if the user is at the top of the list (with no more to load at the top); otherwise, returns false (0). (n)
D_LAXCTRL, axlist_id	Returns the ID of the ActiveX control used for a list if the list is an ActiveX Toolkit list; otherwise, returns false (0). (n)
D_LCOLSIZED, resized	Returns true (1) if one or more columns in the list have been resized by the user and the list is an ActiveX list; otherwise returns false (0). (n)
D_LCTRID, container_id	Returns the list container window ID. (n)
D_LCURITM, current_item	Returns the current item number. (n)
D_LDATALEN, data_len	Returns the length of the data area passed to L_CREATE, or 0 if no data area was passed. (n)
D_LDISITEM, disable_flag	Returns true (1) if the current item in the list is disabled; otherwise, returns false (0). (n)
D_LENABLED, enabled_flag	Returns true (1) if the list is enabled; otherwise, returns false (0). (n)
D_LFINDCASE, case	Indicates whether the search is case sensitive or case insensitive. See the tools.def file. (n)
D_LFINDCURR, test_current	Indicates whether the current item will be tested as part of the search. See the tools.def file. (n)
D_LFINDDIR, direction	Returns the current direction in which to search. See the tools.def file. (n)
D_LFINDLEN, data_length	Returns the length of the area to search. (n)
D_LFINDPOS, data_position	Returns the current position of the area to search. (n)
D_LFINDSOURCE, find_source	Indicates the area to search, where find_source is D_LFND_DATA to search non-window data or D_LFND_DISPLAY to search display data (associated input window). (n)
D_LFINDSTR, data_string	Returns search string last supplied to L_FINDSPEC. (a)
D_LFINDSTRLEN, string_len	Returns length of last search string supplied to L_FINDSPEC. (n)
D_LFINDTYPE, find_type	Returns current type of search for a find operation. See the tools.def file. (n)
D_LFOUND, found_flag	Returns true (1) if the last D_LFIND request was successful; otherwise, false (0). (n)
D_LFTRID, ftr_win_id	Returns the ID of the window used internally by Toolkit for the list footer. (n)
D_LFTRLNS, #ftr_lns	Returns the number of footer lines in the list. (n)
D_LFTRSTATIC, ftr_static	Returns true (1) if footers are static; otherwise returns false (0). (n)
D_LGETEVENTS, method_set	Returns the method set ID for a list or a value of 0 if there is no method set for the list. (n)
D_LHDRID, hdr_win_id	Returns the ID of the window used internally by Toolkit for the list header. (n)
D_LHDRLNS, #hdr_lns	Returns the number of header lines in the list. (n)
D_LHDRSTATIC, hdr_static	Returns true (1) if headers are static; otherwise returns false (0). (n)
D_LHEIGHT, height	Returns the height of the list as the number of visible items. See the tools.def file. (n)
D_LINPID, input_id	Returns the ID of the input window. (n)
D_LLASTITM, last_item	Returns the highest item number loaded. (n)
D_LLOADSTATE, end, state	Returns the load state for an end (top or bottom) of the list. See D_LLOADSTATE for details.
D_LMETHOD, methodtype, method	Returns the name or address for a list method, or the ID for the %UWNDEVENTS_METHOD set. See D_LMETHOD for details.
D_LNULL, null_flag	Returns true (1) if the current item is null; otherwise, returns false (0). (n)
D_LONENABLED, onenable_flag	Indicates whether the current item as well as the list as a whole, are enabled. See the tools.def file. (n)
D_LPLACED, placed_flag	Returns true (1) if the list is placed; otherwise, returns false (0). (n)
D_LPLACEMENT, row, col	Returns the list row (relative to the screen body) where the list is placed, and the column where the list is placed. (n)
D_LPRISTINE, data, pris_flag	Indicates whether the input window and data buffer are in their initial state. See D_LPRISTINE for details.
D_LQAVAIL, requests	Returns the number of requests that can be added to the request queue via L_QUEUE before the limit of 20 is exceeded. Requests will be one less than the number of requests that can be submitted (because L_PROCESS/L_SELECT use one entry). In other words, if there are three requests in the queue, requests will be returned as 16, though you can actually submit 17 requests. (n)
D_LROW, item_row	Returns the current item’s row number, which specifies the item’s position in the currently visible set of rows. (n)
D_LSTATE, state	Returns a value indicating the state of the list. See D_LSTATE for details. (n)

D_LLOADSTATE

D_LLOADSTATE, end, state

D_LLOADSTATE returns the load state for an end (top or bottom) of the list.

End is one of the following (defined in tools.def): (n)

D_LLOADBOT	Return the load state for the bottom of the list.
D_LLOADTOP	Return the load state for the top of the list.

State is returned as one of the following (defined in tools.def): (n)

DLS_BEGIN	Loading has not begun.
DLS_DONE	Received D_LEOF at the specified end.
DLS_FULL	No more items are needed at this time.
DLS_LOAD	Loading is in progress.

D_LMETHOD

D_LMETHOD, methodtype, method

D_LMETHOD returns the name or address for a list method, or the ID for the %UWNDEVENTS_METHOD set.

Methodtype is one of the following (defined in tools.def): (n)

D_ARRIVE	Return the arrive method name or address.
D_LDBLCLK	Return the double-click method name or address.
D_LLEAVE	Return the leave method name or address.
D_LLOAD	Return the load method name or address.
D_LWNDEVENT	Return the %UWNDEVENTS_METHOD set ID.

Method returns the name of the method if the argument is a or the address of the method if it is n for all methodtypes except D_LWNDEVENT, for which it returns the ID of the %UWNDEVENTS_METHOD. (Method is treated as n for D_LWNDEVENT, so if it is declared a, the ID is returned as a decimal value.) (a or n)

D_LPRISTINE

D_LPRISTINE, data, pris_flag

D_LPRISTINE indicates whether the input window and data buffer are in their initial state, that is, the state they were in when L_CREATE was called.

Data is the data buffer, supplied by the calling routine, rather than returned to it. Data is required here if the data argument was also passed to L_CREATE when the list was created. If data is passed here but was not passed to L_CREATE, a fatal error occurs. (a)

Pris_flag returns true (1) if the data buffer and input window are in their initial state; otherwise, it returns false (0). (n)

D_LSTATE

D_LSTATE, state

D_LSTATE returns one of the following, indicating the state of the list (defined in tools.def): (n)

D_LNORMAL	List is in normal state.
D_LMAXIMIZED	List is maximized.
D_LMINIMIZED	List is minimized.
D_LHIDDEN	List is hidden.

Examples

The following example retrieves the placement values and placement status of the list whose ID is stored in order_lst.

xcall l_status(order_lst, D_LPLACEMENT, row, column, D_LPLACED, placed)

The next example returns the reason for the abort flag, returned from a previous call to L_PROCESS, on the list whose ID is stored in mylst.

xcall l_status(mylst, D_LABTRSN, abort_code)

The next example submits a FIND request to the list processor and then calls L_STATUS to determine whether the FIND was successful. The find status is returned in found.

xcall l_findspec(lstid, fname)
req = D_LFIND                             ;Submit a FIND request
xcall l_process(lstid, req, data)         ;Process the request
xcall l_status(lstid, D_LFOUND, found)     ;Was it found?
if(.not.found)
  xcall u_message("Item not found")