Main Index  PREV  NEXT

Miscellaneous Forms

Overview

It is envisaged that each application will need one copy of each of the following forms. They are included here so that a common pattern can be adopted across different applications.

Show Help Text

Description

This form is activated when the <help> trigger is fired. It will extract help text from the application database and display it in the area provided. This text will either be for the current FIELD (on the calling form) or for the calling FORM itself. The screen title will identify the object (field or form) for which help text is currently being displayed.

When first activated the screen will show the text for the current field.

This form is read only. The text is maintained using function built from the HELPM template.

The component built from this template should be named <application>_HELP where <application> is the name of the application library.

It is possible for help text to be obtained from HTML files instead of the application database. You will need a separate file for each component within your application, and each file name must be the same as the component name. If these HTML files are available you must inform the system of their location by inserting the relevant entry in the assignment file. Please refer to Menu and Security System - Assignment File Settings for more details.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

Help About form

Description

This form is invoked from the HELP ABOUT option on the pulldown menu. It is used to identify which version of the software is being run.

SYSTEM TITLE is obtained from the message file using $text(L_SYSTEM_TITLE)

SYSTEM VERSION and RELEASE DATE are obtained from local constants. These should be updated prior to any release so that it can be confirmed that the release has been installed.

FORM VERSION, FORM NAME and FORM TITLE refer to the individual component that was active at the time this option was invoked.

FORM VERSION should be updated each time a change is made to the form component.

The component built from this template should be named <application>_HELPA where <application> is the name of the application library.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

N/A

Component Variables (Refer to Component Variables)

Maintain Help Text

Description

This form is used to maintain the help text that will be displayed when the HELP form is activated.

Each application should have its own copy of the HELP table in its database so that it can be physically separated from the help text for other applications. This should avoid those situations where a field (column) with the same name has different meanings in different applications.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

Message - Message Object

Description

This component handles the processing of messages which are generated in a self-contained service but displayed in a form. The principles are described in a separate document called Error/Message Handling for self-contained services.

A component of this type already exists as part of the Menu System - it is called MSG_OBJECT.

This component has the following operations:-

• WRITE - add a message.
• RETRIEVE - retrieve outstanding messages from the database.
• READ - pass back messages one at a time for processing in a form component.
• IGNORE - delete a message before it is displayed.
• ERASE - erase all messages that have been displayed.

Buttons

N/A

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

Reload Data from TXT files

Description

This form, and its companion UNLOAD form, will probably not be used in the finished application, but they may prove useful during the development phase for the unloading and reloading of data following a modification to the database. These forms can also be used to re-instate the database to a known condition so that tests can be repeated on the same set of data. An additional use would be the loading of initial data during system installation.

This form can only be used to reload data from TXT files that were created by the UNLOAD function described below. The hierarchy of entities should be the same as those defined in the UNLOAD form so that data can be reloaded in the same sequence as it was unloaded.

The Field List value in each entity's properties must be set to ALL otherwise some fields will not have their values written to the database.

The identity of the file to be loaded is obtained from a standard dialog box which shows the user a series of file names from which a selection can be made. The starting directory for this file box is obtained from a local constant. The user can either select a file or press the CLOSE button to terminate the form.

For each input file the sequence of events is as follows:-

• Extract the data for a single record from the input file. This is a string terminated by a carriage return.
• Extract the entity (table) name and call local procs LP_FIX_ENTITY and LP_FIX_FIELD in case there have been changes to entity and/or field names since the data was extracted.
• Check that the entity name exists within the component structure. This means that data extracted from one application cannot be accidentally loaded into another application (unless they share both entity names and field names).
• Test if a record already exists with the primary key supplied - if it does then delete it and all its subordinate entries. Create a new record using the data from the input file.
• Repeat until all data from the input file has been processed.
• Show the file box so that the user can either select another file or press the CLOSE button.

Note that where an entity is defined as an outer entity in the structure (eg: Entity1 and Entity2 in the above example) it is not affected unless the input file contains a replacement. If an entity which is deleted has inner entities (eg: Entity3 and Entity4 in the above example) then the contents of those inner entities which are related to the outer entity will be deleted. The input file may or may not contain replacements for the inner entities.

Local procs LP_FIX_ENTITY and LP_FIX_FIELD may be amended to cater for changes in the database structure since the data was extracted. This will allow you to deal with changes to entity and/or field names.

Buttons

N/A

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

Unload Data to TXT files

Description

This form is designed to be used only with its companion RELOAD form, as described in the previous section. It creates files in TXT format (which can be viewed and modified using any text editor) rather than in UNIFACE TRX format.

The contents of each database occurrence will be written as a string terminated by a carriage return. Each string will be in the following format:-

ENTITY=<entityname>;field1=value1;field2=value2;.....;fieldn=valuen

All the entities which you wish to extract should be defined within this component. The Field List value in each entity's properties must be set to ALL otherwise some fields will not have their values available for extraction.

If you wish any child entities to be automatically extracted with their associated parents then you must paint them within their parent entities.

All outer entities require an entry in local proc LP_INITIALISE in order to load their names into the selection list. At run time the user can select any number of these outer entities, then press the OK button to perform the extract.

In order for this component to extract the contents of any entity the following code should be inserted into the <read> trigger:-

read

if ($status = 0)
   ; do not forget to set field list to ALL
   call EXTRACT_DATA
   call INNER_ENTITIES($entname)
endif

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

Display Proc Version Numbers

Description

This form is used to display the contents of the procedure library being accessed (usually from a DOL file) to verify that the correct version is being referenced.

PROC NAME identifies the procedure name.

PROC LIBRARY identifies the name of the library containing that procedure, which will either be the library created for that particular application, or the default library (SYSTEM_LIBRARY).

PROC VERSION is the version number for that procedure (starting at 01.000.000). Version numbers for global procs are similar in format to those for forms.

Local proc LP_BUILD_LIST must be amended to include a reference to each global proc within your application library. Global proc BUILD_PROC_LIST will deal with all procs in SYSTEM_LIBRARY.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

http://www.tonymarston.net