Main Index  PREV  NEXT

List Forms

Overview

This type of form is used to display multiple occurrences of an entity. It shows summary details only, one entry per line. It does not allow any updates, but a series of navigation buttons will provide access to other forms that should be able to add, update or delete occurrences of the entity.

As the number of database occurrences that may be retrieved within this type of function is potentially very large the RDBMS may employ a stepped hitlist. If a child form that is launched attempts to construct another hitlist on the same database table there will be a conflict. To deal with this situation the following options are available: DEFAULT - If the hitlist in the parent process is incomplete (ie: there are entries that match the current retrieve profile that have yet to be retrieved from the database) then all unfetched occurrences will be retrieved. NOTE THAT FOR LARGE DATABASE TABLES THIS COULD RESULT IN A SIGNIFICANT DELAY. DROP HITLIST - Drop the hitlist at the current point for the named entity in the parent process. If the current hitlist is incomplete then all unfetched occurrences will be dropped and will no longer be available in the current operation - the user will have to perform a <clear> followed by a <retrieve> in order to build a new hitlist. NEW DATABASE PATH - Open up another database path for the child process, thus avoiding any conflicts. NOTE THAT THIS WILL RESULT IN MULTIPLE DATABASE OPENS FOR A SINGLE USER. The required option can be defined on a form-by-form basis - please refer to the section titled Child Properties in the Menu and Security System User Guide for more details.

Specifying a read limit for large hitlists

To avoid the possibility of a session being suspended for a significant period of time due to the retrieval of a large number of occurrences, these functions include code to interrupt the retrieve after a certain number of entries have been read into the form's structure. The actual number can be set using the read_limit=n parameter in the [logicals] section of the assignment file. Each time the limit is reached the user will be presented with a dialog box requiring a YES or NO response. If NO is selected the retrieve will be terminated at this point, and all remaining entries in the hitlist will be dropped. If YES is selected the retrieve will continue until the limit is reached again.

The code which does this goes in the <read> trigger of the repeated entity:-

read

if ($status = 0)
   call CHK_READ_COUNT($read_count$, $$read_limit)
   #include STD:FATAL_ERROR
endif

Additional functionality available with LIST forms

• A LIST form is usually the parent in a group of forms known as a forms family. Please refer to A group of Single-Purpose functions and Menu and Security System User Guide - Form Families for more details.
• If the form has navigation buttons from which you can activate instances of child forms the behaviour of these child forms is affected by the REFRESH CHILDREN option. Please refer to Menu and Security System User Guide - Interaction between Non-Modal Forms for more details. The code which does this goes in the <occ. gets focus> trigger of the repeated entity:-

  if ($$refresh_children & !$empty)
     call LP_PRIMARY_KEY
     call REFRESH_CHILDREN
  endif
  

• If the LIST form accepts a retrieve profile from the parent form it is possible to specify selection criteria in the transaction definitions in the Menu database. Please refer to Menu and Security System User Guide - Extra Parameters for more details. It is also possible to create different transactions for the same LIST component but with different selection criteria. Please refer to Menu and Security System User Guide - Component Identities for more details.

List 1 - list occurrences, with profile area, with navigation bar

Description

For an overview of all List forms please go here.

Upon initial entry this form has the following options (determined by the contents of $AUTO_RETRIEVE$):-

• Perform an automatic retrieve using the contents of the profile area (usually null).
• Do not perform an automatic retrieve, but wait for the user to press the RETRIEVE button.

Although the profile area is usually empty, it is possible to define values in the Extra Parameters field on the Menu database that will be loaded into the profile area by standard proc code within the <exec> trigger.

The profile area is limited to fields that are contained on the outer (main) entity.

Prompt sequence:

• If no data has been retrieved the prompt sequence will be Profile area then Action bar, excluding the Data area and Navigation bar.
• If data has been retrieved then the prompt sequence will be Data area, Navigation bar, then Action bar, excluding the Profile area.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

List 2 - list MANY in a ONE-to-MANY, with navigation bar

Description

For an overview of all List forms please go here.

This type of function is used in a ONE-to-MANY relationship where only those occurrences of MANY that are related to the occurrence of ONE can be displayed.

The action performed upon initial entry depends on the existence of a parameter being passed from the parent form:-

• If the parameter contains the primary key for an occurrence of the ONE entity will be retrieved, followed by any associated occurrences of the MANY entity. The cursor will be positioned on the first occurrence of the MANY entity.
• If no parameter is passed the function will not be able to perform an automatic retrieve. The cursor will be positioned on the first field of the ONE entity, and the user must select an occurrence of the ONE entity (using a popup) before any occurrences of the MANY entity can be retrieved.

Prompt sequence:

• If an occurrence of the ONE entity has not been retrieved the prompt sequence will be the ONE entity then the Action bar, excluding the MANY entity and the Navigation bar.
• If data has been retrieved then the prompt sequence will be the MANY entity, Navigation bar, then Action bar, but excluding the ONE entity.

Buttons

CLOSE	Exit and return to the parent form.
CLEAR	Clear the current screen contents and place the cursor on the ONE entity. A new occurrence can be selected by clicking on the popup button . If the component variable $CHANGE_ALLOWED$ is set to 'N' this option will not be available.

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

List 3 - list MANY in a ONE-to-MANY, without navigation bar

Description

For an overview of all List forms please go here.

This type of function is used in a ONE-to-MANY relationship where only those occurrences of MANY that are related to the occurrence of ONE can be displayed. There are no navigation buttons therefore no child components can be activated.

The action performed upon initial entry depends on the existence of a parameter being passed from the parent form:-

• If the parameter contains the primary key for an occurrence of the ONE entity will be retrieved, followed by any associated occurrences of the MANY entity. The cursor will be positioned on the first occurrence of the MANY entity.
• If no parameter is passed the function will not be able to perform an automatic retrieve. The cursor will be positioned on the first field of the ONE entity, and the user must select an occurrence of the ONE entity (using a popup) before any occurrences of the MANY entity can be retrieved.

Prompt sequence:

• If an occurrence of the ONE entity has not been retrieved the prompt sequence will be the ONE entity then the Action bar, but excluding the MANY entity.
• If data has been retrieved then the prompt sequence will be the MANY entity, then Action bar, but excluding the ONE entity.

Buttons

CLOSE	Exit and return to the parent form.
CLEAR	Clear the current screen contents and place the cursor on the ONE entity. A new occurrence can be selected by clicking on the popup button . If the component variable $CHANGE_ALLOWED$ is set to 'N' this option will not be available.

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

List 4 - list occurrences, without profile area, with navigation bar

Description

For an overview of all List forms please go here.

This function is similar to LIST 1, but does not contain any selection criteria as this is handled by the parent form (see SELECT 1).

Upon initial entry this function will perform an automatic retrieve using the profile passed down from the parent form. If this is a null string (ie: the previous form was a menu), then all available entries will be selected. If no entries are found a warning message will be issued.

This function has a custom operation called LOAD_STREAM for use by a parent form of type SELECT 2. In this combination the parent form will construct an XML stream of entries which it has retrieved, then pass this stream to the custom operation. The contents of this XML stream will be loaded into the component, then sorted according to the specification found in $SORT_SPEC$.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

List 5 - list MANY in a ONE-to-MANY-to-ONE, with navigation bar

Description

For an overview of all List forms please go here.

This type of function is used in a ONE(a)-to-MANY-to-ONE(b) relationship where it is possible to have multiple occurrences of MANY for each combination of ONE(a) and ONE(b), as shown in Figure 1.

Figure 1 - ONE(A)-to-MANY-to-ONE(B) relationship

There may be a different occurrence of MANY covering a different date range, for example. In this form it is required that only one occurrence of MANY be shown (either the first, the last, or the one with the current date). An option on the navigation bar may provide the ability to view the remaining occurrences of MANY. It is possible for an occurrence of MANY not to exist yet, in which case the values for ONE(a) and ONE(b) will still be shown, with the values for MANY being blank. An option on the navigation bar may provide the ability to create occurrences of MANY.

Upon initial entry the function will retrieve an occurrence of the ONE(a) entity using the primary key passed down by the parent form, then retrieve all associated occurrences of the ONE(b) entity, followed by the MANY entity.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

List 6 - list a ONE-to-MANY with multiple occurrences of ONE

Description

For an overview of all List forms please go here.

This type of function is used in a ONE-to-MANY relationship where only those occurrences of MANY that are related to the occurrence of ONE (OUTER) can be displayed, and where it is possible to retrieve multiple occurrences of the ONE entity. In this arrangement the ONE and MANY entities are referred to as OUTER and INNER respectively.

Upon initial entry the function will retrieve occurrences of the OUTER entity using whatever profile is passed down by the parent form. If no profile is passed then all available occurrences of OUTER will be selected. For each occurrence of OUTER all associated occurrences of INNER will be retrieved.

There are scroll bars for both the OUTER and INNER entities.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

http://www.tonymarston.net