Reference Manual

Pick-list functions

Functions to produce pick-lists are contained in the list.4gl module. The following example shows a typical program stub to produce a simple pick-list:

call listopen('mylist','','','','') returning dummy
call listsetup('mytable','item1,item2',format,'item1','')
while true
call listman() returning action,rowid
case action
when 'enter' ... {edit/view the selected row}
when 'insert' ... {insert a new row}
when 'delete' ... {delete the selected row}
when 'accept' exit while
when 'exit' rowid=null exit while
end case
end while
call listclose()

The pick-list object is initialized with 'listopen' which supplies the pick-list title and displays the appropriately sized and positioned window on the screen. The database criteria are defined with 'listsetup' indicating such things as the database tables and columns, search filters, list order and a formatting string.

User responses are handled by 'listman', which returns some of them for the calling program to handle, along with the current rowid.

Finally, the pick-list object is removed with 'listclose'.

Following are more detailed descriptions of the functions in the pick-list system (ordered by approximate importance):

Listopen

Initializes a pick-list object with a title and displays an appropriate window on the screen.

5 parameters:
Title: A title string or a key into the title text file. More than one title line can be defined in the title text file.
Row: Optional row position of the pick-list window.
Column: Optional column position of the pick-list window.
Height: Optional window height.
Width: Optional window width.

1 return value:
Status: If the operation was successful, the return code is zero.

If the position and size parameters are omitted, they are automatically set. The window width is determined by the title width. The window length is set according to the number of screen lines available. The default window position is in the upper right corner of the screen.

Listsetup

Sets up the database criteria. Scroll cursors are opened and a page is displayed.

6 parameters:
Tables: A list of the tables used in the query (SQL 'from' clause). The first table in the list is considered as the primary table and any rowids subsequently returned are from that table.
Items: A list of items or expressions that will be used in the pick-list (SQL 'select' clause).
Format: An optional formatting string (c style) to indicate how the columns will be presented in the list. E.g. '%-10s' left justifies a string in a ten character space.
Filter: Filter information and table joining information (SQL 'where' clause).
Order: List of items to order by (SQL 'order by' clause).
Position: A value which positions the current window page in the list. The value corresponds to the first order item. E.g. if a list of a thousand lines is ordered by customer name and the position value is 'Zebra' then the starting current page will be near the end of the list.

Listman

Handles user responses to a pick-list object.

2 return values:
Action: A string containing a logical user response that the calling program can act on. Possible responses and typical uses are as follows:
'enter' = Edit or view the current row with a form.
'insert' = Insert a new row with a form (typically the editing form).
'delete' = Delete the current row.
'accept' = Exit the pick-list function returning the row to a calling program.
'exit' = Exit the pick-list function without returning the row.
'filter' = dit the pick-list selection criteria (followed by calling 'listsetup').
'other' = Other operations, perhaps a menu offering some possibilities.
'prevset' = Regenerate the list with the previous logical set of data.
'nextset' = Regenerate the list with the next logical set of data.
Rowid: The rowid of the current pick-list line.

Other user responses like 'help', 'refresh', 'print', 'opsys', cursor movement keys and more are handled automatically within 'listman'.

Listinit

Refresh the list without changing any criteria. This is typically used after the user has edited, deleted or inserted a new row to update the list.

Listclose

Removes the current pick-list object.

Listview

Handles a viewing window that has been created. This is typically used when the user has pressed the logical key 'enter' to view a selected row in window. After the calling program opens the window and display the data, it can call this function to handle standard user inputs. An example of this follows:

... {open form/window}
while not done
... {retrieve and display the information}
while true
call listview('form',rowid,'') returning action,rowid
case action
when 'refresh' exit while
when 'exit'
let done=true
exit while
end case
end while
end while
... {close form/window}

The 'listview' function handles most user responses. The user can page through the pick-list in the viewing window.

3 parameters:
Name: A string value which is used to display a title in the viewing window and to select the appropriate help text.
Rowid: The current rowid.
Text: Message that appears in the viewing window.

2 return values:
Action: A string containing a logical user response that the calling program can act on. Possible responses are and typical uses are as follows:
'exit' = Exit the pick-list function without returning the row.
'other' = Other operations, perhaps a menu offering some possibilities.
'refresh' = Refresh the viewing window (possibly the next/previous row).
Rowid: The rowid to be viewed next.

Listnpage/Listppage

Return the next/previous rowid in the pick-list. These functions are typically used within an input statement in editing windows that are called from a pick-list to be able to page through the pick-list rows.

1 parameter:
Rowid: The current rowid.

1 return value:
Rowid: The next/previous rowid. If there are no rows in that direction, a null is returned.

Listfirst/Listnext/Listprev

Return the first/next/previous rowid in a pick-list. These functions are meant to be used in operations that process the list as a whole, e.g. if the whole list is to be deleted or updated. An example of their usage is as follows:

let rowid=listfirst()
while rowid is not null
... {processing statements}
let rowid=listnext()
end while

1 return value:
Rowid: The rowid of the table row to be processed.

Listhead

Displays title text dynamically. This function can be called after a pick-list has been opened to change title lines.

2 parameters:
Text: The new title text to be displayed.
Line: The title line number affected.

Listsum/Listavg/Listmax/Listmin

Set up aggregate values which appear at the bottom of the pick-list window, e.g. to display the total of an amount column. The aggregate value pertains to the whole list and not just the page.

1 parameters:
Column: The pick-list column number (measured left to right starting with 1).

Listmsg

Sets up a message which is displayed at the bottom right corner of the pick-list window. This is typically used to display additional instructions and options.

1 parameter:
Text: Message text.

Listspitem

Defines special items such as key values that are normally not visible to the user. The rowid is automatically such a special item and does not have to be defined explicitly. These special items appear in a special viewing window when the user enters '#' in a pick-list.

1 parameter
Item: Name of a table column.

Listtransl

Sets up translation methods for columns in a pick-list. This is typically used when the desired format of a column cannot be achieved by the standard-c formatting string. The actual translation method must be contained in a function called 'transl' (an interface function).

2 parameters:
Method: A string value corresponding to a method defined in the 'transl' function.
Column: The pick list column number to be translated or formatted.

Listprinter

Sets up the name of the default printer to be used in the pick-list. This name will then appear in the print dialogue box when the user presses the logical key 'print'.

1 parameter:
Name: The name of the default printer.

Listmarks

Returns a list of rowid values corresponding to pick-list rows that the user has marked with the logical key 'toggle'. The calling program can subsequently use these values for processing.

1 return value:
Rows: A list of rowid values separated by commas (ready for an SQL where clause).