template_banner.gif Main Index  PREV  NEXT

Valid HTML 4.01!   Valid CSS!

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.

warning_symbol.gif 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



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

CT_LIST1.gif

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$):-

info_symbol.gif 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:

Buttons

CLOSE Exit and return to the parent form.
CLEAR Clear the current screen contents and place the cursor in the profile area.
RETRIEVE Retrieve a new set of details from the database using the selection criteria defined in the profile area.
FULL PROFILE Activate the SELECT 1 form specified by '$SELECT_TRAN$=form' element.

Contents

Bound Objects

Source Entity Source Field Target Entity Target Field
ACTION_BAR.INF CLOSE ACTION_BAR.INF CLOSE
  CLEAR   CLEAR
  RETRIEVE   RETRIEVE
COLUMN_BAR.INF FIRST COLUMN_BAR.INF  
  LAST    
RETRIEVE_PROFILE FIRST    
  LAST    
MAIN FIRST    
  LAST    
NAVIGATION_BAR FIRST    
  LAST    

Local Constants (Refer to Local Constants)

Name Expression Description
FORM_VERSION 01.000.000 To be incremented each time the component is changed.
KEYFIELDS_EXTRA   When a parameter string for child components is constructed it will by default only include primary key items. If additional items are required the item names should be defined here. If more than one item is required the names must be separated by GOLD-semicolon.
MULTI_TRAN   If a Multi-Purpose transaction is used as a child form its name must be identified here so that the contents of this form can be cleared and re-read following the termination of that child form.

Component Variables (Refer to Component Variables)

Name Description
FORM_VERSION  
PARAMS  
READ_COUNT  
PROFILE  
AUTO_RETRIEVE If this is set to 'Y' the component will perform an automatic <retrieve> upon initial entry.
SELECT_TRAN This identifies the component to be activated if the FULL PROFILE button is pressed.
CLEAR_NOT_ALLOWED If this is set to TRUE then the <CLEAR> and <RETRIEVE> triggers will be inoperative.

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

CT_LIST2.gif

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:-

Prompt sequence:

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 popup_button.gif. If the component variable $CHANGE_ALLOWED$ is set to 'N' this option will not be available.

Contents

Bound Objects

Source Entity Source Field Target Entity Target Field
ACTION_BAR.INF CLOSE ACTION_BAR.INF CLOSE
  CLEAR   CLEAR
COLUMN_BAR.INF FIRST COLUMN_BAR.INF  
  LAST    
ONE FIRST    
MANY FIRST    
  LAST    
NAVIGATION_BAR FIRST    
  LAST    

Local Constants (Refer to Local Constants)

Name Expression Description
FORM_VERSION 01.000.000 To be incremented each time the component is changed.
MULTI_TRAN   If a Multi-Purpose transaction is used as a child form its name must be identified here so that the contents of this form can be cleared and re-read following the termination of that child form. This may also be defined as an indexed list if more than one child form is involved.

Component Variables (Refer to Component Variables)

Name Description
FORM_VERSION  
PARAMS  
CHANGE_ALLOWED 'Y' or 'N'. Default is 'N'.
READ_COUNT  

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

CT_LIST3.gif

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:-

Prompt sequence:

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 popup_button.gif. If the component variable $CHANGE_ALLOWED$ is set to 'N' this option will not be available.

Contents

Bound Objects

Source Entity Source Field Target Entity Target Field
ACTION_BAR.INF CLOSE ACTION_BAR.INF CLOSE
  CLEAR   CLEAR
COLUMN_BAR.INF FIRST COLUMN_BAR.INF  
  LAST    
ONE FIRST    
MANY FIRST    
  LAST    

Local Constants (Refer to Local Constants)

Name Expression Description
FORM_VERSION 01.000.000 To be incremented each time the component is changed.

Component Variables (Refer to Component Variables)

Name Description
FORM_VERSION  
PARAMS  
CHANGE_ALLOWED 'Y' or 'N'. Default is 'N'.
READ_COUNT  

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

CT_LIST4.gif

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.

info_symbol.gif 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

CLOSE Exit and return to the parent form.

Contents

Bound Objects

Source Entity Source Field Target Entity Target Field
ACTION_BAR.INF CLOSE ACTION_BAR.INF CLOSE
MAIN FIRST    
  LAST    
NAVIGATION_BAR FIRST    
  LAST    

Local Constants (Refer to Local Constants)

Name Expression Description
FORM_VERSION 01.000.000 To be incremented each time the component is changed.
MULTI_TRAN   If a Multi-Purpose transaction is used as a child form its name must be identified here so that the contents of this form can be cleared and re-read following the termination of that child form.

Component Variables (Refer to Component Variables)

Name Description
FORM_VERSION  
PARAMS  
READ_COUNT  
DTD_NAME This is only used in the LOAD_STREAM operation. It identifies the DTD name which is required to load the XML stream created by the parent form. This can either be defined in local proc LP_INITIALISE or defined in the Extra Parameters area in the Menu database.
$SORT_SPEC$ This is only used in the LOAD_STREAM operation. It is a list of field names separated by commas. By default the sort will be performed in ascending sequence, but this can be altered by appending the keyword ':desc' to any fieldname, as in the following example:
field1:desc,field2:asc,field3,field4

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

CT_LIST5.gif

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

list_Image001.gif

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

CLOSE Exit and return to the parent form.

Contents

Bound Objects

Source Entity Source Field Target Entity Target Field
ACTION_BAR.INF CLOSE ACTION_BAR.INF CLOSE
ONE(A) FIRST    
ONE(B) FIRST    
MANY FIRST    
  LAST    
NAVIGATION_BAR FIRST    
  LAST    

Local Constants (Refer to Local Constants)

Name Expression Description
FORM_VERSION 01.000.000 To be incremented each time the component is changed.
MULTI_TRAN   If a Multi-Purpose transaction is used as a child form its name must be identified here so that the contents of this form can be cleared and re-read following the termination of that child form. This may also be defined as an indexed list if more than one child form is involved.

Component Variables (Refer to Component Variables)

Name Description
FORM_VERSION  
PARAMS  
READ_COUNT  

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

CT_LIST6.gif

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

CLOSE Exit and return to the parent form.

Contents

Bound Objects

Source Entity Source Field Target Entity Target Field
ACTION_BAR.INF CLOSE ACTION_BAR.INF CLOSE
OUTER FIRST    
INNER FIRST    
  LAST    

Local Constants (Refer to Local Constants)

Name Expression Description
FORM_VERSION 01.000.000 To be incremented each time the component is changed.

Component Variables (Refer to Component Variables)

Name Description
FORM_VERSION  
PARAMS  
READ_COUNT  

copyright.gif http://www.tonymarston.net