pick_record()

Purpose

Displays a list of record details from which the user can choose

Old name

#define pick_fill pick_record

Syntax

int pick_record(mapnr, extra_map, error_map,
fetch_item, show_item, save_array, item_size,
choices, flags, ADDITIONAL);

Parameters

int mapnr

Number of map to display list of choices

int extra_map

Map used for title (or 0)

int error_map

Map used when there are no items to display

boolean (*fetch_item)(int)

Pointer to function which fetches items to display

void(*show_item)()

Pointer to function which displays item in the map

void* save_array

Pointer to the workspace area

int item_size

Size of one element of save_array

int choices

The number of items that can be displayed in the map

int flags

Parameter which specifies display attributes

ADDITIONAL

Optional variable for mnemonic map

The parameter flags can be a combination of the following values:

Value

Meaning

DEFAULT

The choice map is displayed and cleared after the user has either selected a record or pressed <Esc>

RETAIN

Stops the display map from being cleared when the record has been selected

NO_DISP

Indicates that the choice map is already on the screen when the pick_record() function is called. The user-defined show_item function is still called to fill in the map unless the value NO_READ is added to the parameter flags

NO_READ

This implies that the save_array has already been filled in, so no initial fetching is required

E_CHOOSE

Tells pick_record() to call the function field_eg_choose() rather than the field_choose() function. In this case, a third parameter is passed to the user-defined function show_item which is called with this parameter set to TRUE as each field receives the input focus. This can be used to display extra information associated with the current option. This feature is used for example by the pick_record() function in the DP4 MAPEDIT utility to display the maps in the menu of maps

ABORT_FUNC_KEYS

If a function key is pressed, the return value of the function pick_record() indicates the function key pressed. The record selected is the one highlighted when the function key was pressed

ABORT_MNEMONICS

This requires an extra parameter to be passed to the function pick_record() that gives the map number of a mnemonic map, which must be on the screen. The mnemonic keys can then be used to exit the pick_record() function. The return value is the corresponding field number of the map. If the parameter flags contains the value ALLOW_NEW, the mnemonic keys are ignored while the cursor is over the 'New record' message. This can be overridden by adding the value NEW_NORMAL to the parameter flags

If the user clicks on the mnemonic map or presses<Enter>, 0 is returned. It is possible to distinguish between the values by examining the selected variable, as in:

• When 0 is returned because <Enter> is pressed, selected is TRUE
• When 0 is returned because of a click on the mnemonic map, selected is FALSE

ALLOW_NEW

This reserves the last field in the display map for a 'NEW RECORD' message which is displayed at all times. Selecting this field or pressing the <Ins> key causes the function pick_record() to return the value INSERT. The user-defined function show_item must include the test:

if (fieldnr >= range)

to decide when the new record message is displayed.

Only the <Ins> and <Enter> keys can select the new record field, and not the function keys, even if ABORT_FUNC_KEYS is used

ALLOW_DELETE

If the <Del> key is pressed, the highlighted record is selected and the function pick_record() returns the value DELETE

NEW_NORMAL

This value is added to the parameter flags when the values ALLOW_NEW and ABORT_MNEMONICS are also added. This enables the pick_record() function to return after a mnemonic key has been pressed while the cursor is over the 'New record' message. You must then save the value of the field that contains this message and compare it with the value of the global variable pk_chosen_field

NO_PICK

Forces the function pick_record() to display only

VIEW_PICK

The user can view records, but cannot choose any

Description

The pick_record() function is a general function for displaying details from several records at once from which the user can select a particular record. It offers a menu-like display, similar to the field_choose() function, but the menu list may be of variable length.

An extra field is used to indicate whether there are more fields below, or above, which can be brought into view by using the cursor keys and the <Pg Up>, <Pg Dn>, <Home> and <End> keys.

To use the pick_record() function, you do the following:

1. Set up the work area for use by pick_record(). This is treated by pick_record() as an array of items describing each record and is pointed to by the parameter save_array. You decide how much information to store in the array, but there must be enough to identify each record uniquely. You might choose to:

• Store the whole record
• Store all the key and all the fields to be displayed for each record
• Store the minimum information to identify the record. This would normally be the primary key or the part of it allowed to vary

Storing the whole record allows you to code the fetch routine without having to define new structures. If you only store the key and not all the fields to be displayed, your show() routine will have to refetch the record

The number of elements in the array is always at least one more than the number of records that can be displayed at once. Element zero is used for reading in records and determining whether there are more items than can be displayed at once. The other elements contain the information to be displayed at the corresponding field

If you wish you can use the same area of memory for all your calls to pick_record(). To do this, define a union containing all the save_arrays required by the calls to pick_record(). In this case, remember that either an "&" is needed before the name of the union or else the correct component of the union is passed (which is an array so the "&" can be omitted)

The structure of the record normally corresponds to the fields to be displayed from the records fetched from the database. Here is a typical record structure, SAVE_CUST, that selects three records from the CUSTOMER record:

struct SAVE_CUST
{
  int cust_nr;
  char cust_name[32];
  char address[4][32];
} save_cust[MAX_CUST + 1];

There is at most MAX_CUST records visible at one time

2. Write the user-defined function for fetching the records, which is passed as the parameter fetch_item. This function is declared as:

boolean fetch_item(int direction)

where direction indicates the direction in which to search the database

The fetch_item function is responsible for fetching records from the database and storing the details to be displayed in the work area pointed to by the parameter save_array. The work area itself is set up in step 1 above. Its name is not fixed; it is called fetch_item here for clarity. You only need to work with the 0th item in the work area

fetch_item is called by the pick_record() function as necessary. Its direction parameter may take one of the values FIRST, NEXT, LAST, PREV or EQUAL

If the direction parameter passed to the function fetch_item is not EQUAL, you fetch a record from the database using this flag (DEPTH or BUT may be added). The fields from the record are then copied into the 0th item of the work area

If the direction parameter passed to the function fetch_item is EQUAL, the information must be copied from the 0th item in the work area to a database record. This record is used in a call to one of the functions rec_fetch_main(), ftch2nd() or rec_fetch()

EQUAL is passed in two situations:

• When the function pick_record() has reached the end of records in one direction and is going to the other end of the list
• Just before the function pick_record() returns, so that the selected record is in memory

A typical fetch_item function is given in the Example section later

3. Write the user-defined function for displaying the records, which is passed as the parameter show_item. This function is declared as:

show_item(int mapnr, int fieldnr)
show_item(int mapnr, int fieldnr, int extra)

where the parameters are:

int mapnr

Same as parameter mapnr to function pick_record()

int fieldnr

The field in which to display the data, and also the index into the work area array containing the information

int extra

Required when the value E_CHOOSE is passed in the pick_record() function's parameter flags. Set to TRUE if extra information is displayed with the fields, or FALSE to display the fields as normal

The show_item function is used to display the record information in the choice list. Its name is not fixed, it is called show_item here for clarity

A typical show_item function contains the following:

map_attach(mapnr,CUST_LINE_MAP,DEFAULT);
show_h(CUST_LINE_MAP,1,save_cust[fieldnr].cust_nr);
  ...
map_glue(m,CUST_LINE_MAP); /* map_glue is needed to
  stop the information displayed from disappearing
  when the cursor is moved */

Two factors which influence the writing of this function are whether a new record message is to be displayed and whether extra information for each field is to be displayed

If you wish to display a 'NEW RECORD' message which the user can select to create a new record, the value ALLOW_NEW must be added to the pick_record() function's parameter flags

The function show_item must then check to see when to display the 'NEW RECORD' message rather than the record details. This is done by adding the following code to the beginning of the show_item function:

if (fieldnr >= range)
{
  show_over(m,fieldnr,NEW_RECORD_MAP);
}
else
...

The parameter extra is used when the value EG_CHOOSE is added to the pick_record() function's parameter flags. This is used to display additional information as the cursor moves to each item. For example, you may not have room to show a complete description for the records, so just display the description for the currently highlighted record at the bottom of the map

4. Write the call to the pick_record() function. Because the function pick_record() has a number of parameters it is normally called indirectly from another function, for example:

int pick_rec()
{
  return pick_record(CUST_BODY_MAP, 0, 
       CUST_ERROR_MAP, fetch_item, show_item,
       save_item, sizeof(struct SAVE_CUST),
       MAX_CUST, ALLOW_NEW|ALLOW_DELETE);
}

5. Create the CUST_BODY_MAP map. This should have:

• MAX_CUST fields for displaying the record details. These fields are highlighted as the user moves between them
• A field 100 for displaying a message such as 'more records below/above'. This field should be 24 characters long

If you wish to use the same display map for different choice functions, you can pass a title map for the choice list in the parameter extra_map. This title map is then displayed in field 101 of the display map.

If you wish to display an error message when no records are fetched (except when the value ALLOW_NEW is included in the parameter flags) it should be passed in the parameter error_map.

The number of records which can be displayed should correspond to the number of records set up for the error message, and should be at least one less than the number created in the work area.

The pick_record() function uses the global variables pk_more_choices, pk_chosen_field, count and range.

The original value of the global variable range is restored when exiting from the function pick_record() so that it can be readily used in data entry functions.

The global variable pk_chosen_field indicates the field number chosen. It is commonly used to attach a map to the chosen record for some data entry processing by the user.

The global variable pk_more_choices indicates which of the 'more' messages in field 100 is to be displayed.

Return values

Return Value

Key Pressed

0

If the <Enter> key is pressed

ESCAPE

If <Esc> is pressed

F<n>

Function key <n> is pressed (used when parameter flags includes the value ABORT_FUNC_KEYS)

PAGE UP

If there are no records

INSERT

If <Ins> is pressed, or <Enter> is pressed over the 'new record' message (used when parameter flags include the values ALLOW_NEW or ABORT_MNEMONICS)

DELETE

If <Del> is pressed (used when parameter flags includes the value ALLOW_DELETE)

The global variable abort_code is always zero after a call to the function pick_record()

See also

field_choose(), show_more(), map_glue()

Example