What is Visual Basic Generator?

Related Topics

The Visual Basic Generator generates fully-functional, data-oriented Visual Basic applications, based on module and database design specifications recorded in the repository.

The main input to the generation process is a module design specification recorded through the Design Editor component of Oracle Designer. This records the tables and columns used by the module, the links between them, and detailed information on how the module uses the data.

The Generator also uses templates and preferences to encourage a standard look and feel in generated applications. It either creates a new Visual Basic project, or adds/replaces files in an existing project.

Each generated application comprises one or more windows, each of which contains one or more zones through which data can be queried or manipulated. These generated applications can be loaded into the Visual Basic design environment from where runtime executables can be built, or further refinements can be made.

Generated applications can use either Oracle Objects for OLE or the Visual Basic Data Access Objects (DAO) programming interface to interact with the database.


How Visual Basic Generator works

Related Topics

Module design

When you generate a Visual Basic module, you specify a repository module definition on which it is to be based. This module design information provides the main input to the generation process.

A zone is created for each module component in the module and a control is created for each item in the module component. Much of the generated interface is driven from the properties of these items; for example, prompts, display types, layout styles, and so on.

Database design

Database design information is used to determine what server error handling is required, and what derivation logic is needed for the generated controls (such as unique sequence numbers).

Template information

Templates determine the look and feel of the forms, zones, dialogs, frames, and controls that make up the generated Visual Basic application. They are defined as a Visual Basic project, and hence are created or modified using the Visual Basic design environment.

A set of standard templates is shipped with the product. You can also create your own. Each generated control or form is based on a corresponding template control or form defined within the template project.

Preference information

Preferences act on several areas of generation. In particular, they determine some of the basic layout issues and also have a general influence over the end user interface.

Illustration: How a Visual Basic project Is generated

*  Library and Template Projects can be stored in the repository or in the filesystem

** Generated VB projects can be uploaded to the repository


About generated Visual Basic applications

Related Topics

From the module design specification, Visual Basic Generator creates a set of Visual Basic files which at runtime display a series of linked forms. These forms are made up of one or more standard zones and dialogs. This diagram illustrates the relationship between these different types of forms:

The complete set of forms shown in this example is not always generated. The appearance, content and sequence of forms determined by the module design specification. For example,

•	master-detail zones may appear on the same or separate windows.

•	a Query dialog may not be required.

•	a Property sheet dialog is not required when the layout style of the zone is 'Form '


About windows and zones in Visual Basic applications

Related Topics

Each generated Visual Basic application typically comprises one or more Visual Basic forms (or windows), and each generated form has one or more zones. The mapping of a single module to one or more Visual Basic forms is defined visually, using a module data diagram in Design Editor.

A zone is generated from a module component and it is the interface through which database records are queried, updated, created, and deleted. A module component is based on a specific table (base table) but may also use other tables to provide lookup information. For example, an OrderLineItems zone might be based on the LINE_ITEMS table, but might also use the PRODUCTS table to provide lookup information on the product description and price.

Module components may be linked via master-detail relationships; these relationships may occur within a single module, or may span different modules.

Links between modules may be set up, such that a zone may be related to another zone in another form sourced from another module.

Generated code coordinates the way that master and detail zones interact. For example, a detail zone is disabled unless a valid master record is present.

Here is a typical form containing two zones:

These windows and zones were generated from the module illustrated below:


About zone layout styles in Visual Basic applications

Related Topics

Each individual zone is laid out according to one of four layout styles. These styles determine the overall layout of a particular zone in the generated Visual Basic application and they are defined using the Layout Style property.

The layout styles are:

Context	A query-only view of a single record is displayed, chosen from a list of values (LOV) dialog box. A separate property sheet dialog is used to edit the record, or to add a new record. About
Form	A single record is displayed. Browse buttons allow movement between records or directly to a specific record. About
List	A list box displays the set of queried records. A separate property sheet dialog is used to edit the record or add a new record. About
List/Form	Similar to the Form style, except that a list box displays the set of queried records alongside a single-record view of the currently selected record. About


About control groups in Visual Basic applications

Related Topics

Within a zone or property sheet dialog, one or more controls may be grouped together visually. How

Grouped controls are placed within a frame control as illustrated below. This example illustrates two control groups: Salary Details and Phone Numbers.

If an item group is suitably marked, it is placed in the zone's stacking area. About

Layout preferences

The layout of controls within a control group is determined by a set of control group preferences.

By default, controls within a group are laid out vertically and the end of the controls are aligned. However, you can modify these preference to customize the layout, if required. How

Default template form

The overall appearance and layout of a control group is determined by the CGTGMainGroup template form. About


About stacking areas in Visual Basic applications

Related Topics

A stacking area can be created within a zone or property sheet dialog, comprising two or more stacked frames. Each stacked frame contains either a stacked item group or a stacked detail zone.

The stacked frames are all created the same size and in the same position within the zone. Only one stacked frame is visible within a zone at any one time. The user chooses which stacked frame is to be visible by selecting a tab (SSTab control). For example:

Alternatively, a stacking area can be implemented using a radio group. For example:

To place an item group within a zone's stacking area, simply mark the group 'Stacked' and then set the Use tab control for stacking areas (USETAB) preference to determine whether tabs or radio groups are used. How

To incorporate a detail module component in the stacking area of its master module component, create a popup layout item around it on the module diagram. How

Customization

The control group layout preferences do not apply to stacked groups. To customize the layout of stacked groups use the zone layout preferences. About

To change the entire look and feel of stacked control groups, modify the default templates CGTGStackSelector and CGTGStackedGroup. About


About property sheet dialogs in Visual Basic applications

Related Topics

Context and List style zones do not allow data to be edited directly in the main window, instead they use a property sheet dialog to create, view and modify records. The dialog is displayed when the user clicks on the zone's View or Add buttons.

Controls on a property sheet dialog

Property sheet dialogs display the set of controls that map to a single record. A property sheet dialog may contain item groups and these groups may be stacked.

The layout of controls on a property sheet dialog can be customized using preferences. About

Buttons on a property sheet dialog

The default captions for buttons on a property sheet dialog are:

OK	Dismisses the dialog, committing any updates to the database.
Cancel	Dismisses the dialog, discarding any updates to the database.
Undo	Discards pending changes, leaving the dialog open.
Apply Now	Saves pending changes to the database, leaving the dialog open.
Close	For query-only zones, a single Close button is generated to dismiss the dialog.
Property sheet dialogs are typically displayed as modal dialogs. However, they can be displayed modeless in some circumstances.

Default template form

The appearance and layout of the property sheet dialog is determined by the CGTWPsd template form. The size of the template form determines the maximum allowed property sheet dialog size.


About query dialogs in Visual Basic applications

Related Topics

Query dialogs can be generated for List, Form and List/Form zones. How

Note:	Context zones use an LOV dialog.

A query dialog is a modal window that allows a user to define search criteria to be incorporated when executing a query against a particular zone. It is displayed when a user clicks on a zone's Query button.

Controls on a query dialog

Query dialogs display the set of controls derived from items marked 'Query' in the module design. If no such items are defined, no query dialog is created and an unrestricted query is performed instead. This may be appropriate for a detail query that is automatically restricted by the chosen master record.

To allow for range searching, a pair of From/To controls can be created for items based on DATE or NUMERIC columns. The Range Search property of the item determines this behavior.

Buttons on a query dialog

The default captions for buttons on a query dialog are:

OK	Passes control back to the main form where the query is executed, based on the given criteria.
Cancel	Dismisses the dialog and passes control back to the main form without performing any action.
Clear	Clears all the controls, ready for the user to enter a new query.
New	Opens a dialog that allows you to enter a new record (only displayed if the application allows insert operations).
Default template form

The appearance and layout of the query dialog is determined by the CGTWQd template form.


About list of value (LOV) dialogs in Visual Basic applications

Related Topics

A List of Values (LOV) dialog is generated for foreign key lookup controls used for data entry. The LOV lets the user choose the value from a list and (if there is any associated lookup table usage) any related lookup values are populated as the user leaves the foreign key control.

LOVs are also generated for enterable lookup controls, where the associated foreign key control is non-enterable. In this case the non-enterable foreign key value is populated as the user leaves the enterable lookup control.

The foreign key control (if enterable), or the enterable lookup control, is always displayed in the LOV. Non-enterable lookup controls can also be included if the Display lookup item in List of Values (ITMDLV) property of the item is set to 'Y'. In the example below a single item (Manager) is displayed in the LOV:

Querying lookup LOVs

The LOV may be implemented as a 'long list'. This means that prior to displaying the LOV dialog, the user can specify a search value that is then applied to the corresponding column in the SQL sent to the server. This reduces the number of rows displayed in the List and the time taken to bring up the LOV.

A long list is created if the column has no dependent columns and the Filter records before display in LOV (RECFLT) preference is set to 'Y'.

In some circumstances you may want the LOV dialog to display all the rows automatically and in this case the additional query dialog is not required. How

A note about Visual Basic Generator and repository LOV definitions

Note that Visual Basic Generator ignores repository LOV definitions.


About launch screens for Visual Basic applications

Related Topics

An additional module may be defined specifically to create a launch screen for your generated Visual Basic application. How

This module is referred to as the 'top-level' module. Normally, launch screens just contain a series of buttons which link to the rest of the modules within the generated application.

The content of the launch screen is derived from the top-level module definition and module network information. The title of the launch window (OBS) is derived from the Window Title. The launch screen caption (Oracle Brokerage Services) is derived from the module's Top Title property.

Buttons are generated for each navigation action item defined against the window. These will typically call other modules that are linked to the top-level module.

Note:	Top-level modules created to generate launch screens do not contain module components.

Default template form

The appearance and layout of the launch screen is determined by the CGTWLaunch template form.


About runtime behavior of generated Visual Basic applications

Related Topics

When a generated application is run, the user is initially prompted with a connect dialog in order to provide database logon details and then the first window of the application is displayed. If the first zone is query-only, a query operation on that zone is invoked automatically.

From there, zone buttons may be used to initiate database operations and data entry controls may be manipulated to provide data values. Where appropriate text box-style controls are generated with a list of values (LOV) button that allows the user to pick from a list. Validation of user data is generally deferred until the data is to be saved by the user.

Some aspects of runtime behavior can be controlled via options specified on the Options dialog, called from the Options menu on the main window. For example:


About runtime database access of generated Visual Basic applications

Related Topics

Generated Visual Basic applications can access the database using Oracle Objects for OLE or the Visual Basic Data Access Objects (DAO) programming interface. You can select the data access method used by your application prior to generation. How

For each zone, a dynaset is created at form startup through which single-record Insert, Update, Delete, and Query operations are performed. After Insert or Update operations, the dynaset is automatically refreshed so that data derived or defaulted by server-side triggers is displayed to the user. If required, a second dynaset is created for querying associated lookup data.

Also, for each zone, a dynaset is created to fetch the zone's set of records. Here, only the primary key plus some descriptive data is fetched for each record; the full details are then queried upon navigation to a specific record. The descriptive data allows the user to navigate directly to the required record without having to browse records one at a time.

If any Oracle7 database server errors are encountered, the number and text of the error are examined and if anticipated, are converted to a more user-orientated message (definable in the repository). If the error is not anticipated, a Server Error dialog is displayed:


About customization of Visual Basic applications

Related Topics

Following installation, the Visual Basic Generator can be used 'as is' to generate applications with a consistent look and feel, using the controls supplied with Microsoft's Visual Basic Professional Edition. However, various aspects of the generated application may be configured, as described below.

Templates

All the display characteristics of generated windows, zones, control groups, stacking areas, and controls are driven from a set of template forms, defined within a template project. To implement an alternative look and feel, this template may be copied and the properties of the different objects within the template modified accordingly. About

Control definition file

All other control characteristics are driven from entries in the control definition file; for example, whether the control has a Caption property or whether the control is query-only etc. To utilize third-party controls, the control definition file may be extended and templates for the controls added to the template project. About

Preferences

Other aspects of Generator behavior are driven from a set of options known as preferences; for example, whether mnemonic access characters are added to prompts or whether radio buttons are to be laid out horizontally or vertically. Preferences may be set at container (i.e. folder or application system) level to be inherited by all modules in the container, or set on a module-by-module basis. About

Library forms and code modules

Finally, the generated application makes use of various library forms and code modules. These provide generic functionality, such as database logon and the displaying of LOV dialogs. The shipped library files can, if required, be copied and modified and extra library files can also be added. About


About template Visual Basic projects

Related Topics

Templates determine the look-and-feel of the forms, zones, dialogs, frames and controls that make up a generated Visual Basic application.

A set of standard templates is shipped with the product as a Visual Basic makefile. This contains a set of template forms, each responsible for defining the templates for a specific purpose. There are four types of template forms:

Template controls

A single template controls form (CGTCControls) contains controls that define the appearance of generated controls; that is, fonts, sizes, colors etc. For each control type (e.g. TextBox), you may define up to four versions. These determine the look-and-feel when the control is used as:

•	a mandatory control

•	a read-only control

•	an optional control

•	a control within a query dialog

Template windows

Template windows (the forms prefixed by CGTW) define the appearance of the generated windows, property sheet dialogs, and query dialogs. The size of the template form defines the largest window size to be generated and the items within the template define the margin size. It may also include the 'standard' controls that are copied into each generated application e.g. a status bar.

Template zones

Template zones (the forms prefixed by CGTZ) define the appearance of generated zones. This includes:

•	the relative position of the zone's controls to its buttons

•	the orientation of the buttons

•	the appearance and location of other controls, such as browse buttons

•	the look-and-feel of the frame that the zone may be placed on

Template groups

Template groups (the forms prefixed by CGTG) define the appearance of the frames used to enclose control groups, plus the look-and-feel of the control(s) used to implement any stacking area within a zone.


About Visual Basic Generator preferences

Related Topics

Preferences are options that influence the appearance and behavior of generated Visual Basic modules. Every preference has a default setting that is used by the Generator if the preference has not been set explicitly. Visual Basic Generator allows preferences to be set at container (i.e. folder or application system) or module level. How

Preference settings can also be grouped into named preference sets. The set can then be applied to different modules.

Visual Basic preferences are grouped into these categories:

Controls	Options that give the specific controls to use for different types of generated control, plus the location of the control definition file.
DBA	Options for referencing database objects.
End User Interface	Options that govern various aspects of the user interface; for example, whether mnemonic access characters should be used for data entry controls.
Layout - Control	Options for laying out individual controls; for example, the gap between a text box and its prompt.
Layout - Group	Options that determine how controls within a control group are placed.
Layout - Zone	Options that determine how controls within a zone, property sheet dialog, or query dialog are placed.
Templates	Options that give the location of the template and library objects, and define the use of template menus.


About third-party controls in a Visual Basic application

Related Topics

A set of controls is supplied as standard with Visual Basic. In addition, you can make use of third-party controls for buttons, frames and data entry controls.

Use of third-party controls depends on the properties and events that a particular control supports. As long as any differences between the third-party control and the standard Visual Basic control can be documented in the control definition file, the third-party control can be used instead of the standard control. Additional properties of the third-party control will typically not be used by the Generator.

The more 'unusual' kinds of third-party control are generally not supported, except via inclusions within a template window or zone.

Registering third party controls

There are two steps involved in defining third party controls:

•	First, add the new control in the Controls template form (which defines the appearance of generated controls) How

•	Then, add the new control type to the Control Definition file (which defines the characteristics and capabilities of the control type) How

Using a third party control

Once a third party control has been registered it can be incorporated within the module design in one of two ways depending on your needs:

•	to define that all controls of a given type (e.g. Check box) use the new control, set the appropriate Control type mapping preference at the module or container (i.e. folder or application system) level. How

•	to generate a specific item using the new control (instead of its default type), set the Template/Library Object property for the item. How


Features added for Visual Basic in 6i
Features added for Visual Basic Generator in 6i

New and improved features in Visual Basic Generator 6i

When you are generating Lists of Values (LOVs), you now use preferences, rather than properties. See About List of Value (LOV) dialogs in Visual Basic applications

Oracle Designer Visual Basic Generator is no longer certified against VB4. However, if you want to generate VB4 applications, guidance is given where appropriate, for example, for preferences MGPROJ and TFPROJ. For information about the issues you need to consider, see Using Visual Basic 4.0.

Support for domain key constraints and user-defined domain tables.

New colors for those messages displayed in the Message Window that indicate whether Visual Basic Generator has successfully or unsuccessfully updated repository properties during generation and design capture.

Support for generation from versioned repositories.

New repository features enable you to use the repository as well as the filesystem to store files required during generation, and also to store generated files after generation. Storing files in the repository gives you access to features such as the Dependency Analyzer and version control.

Preferences

New preferences

Preferences removed in 6i

New Visual Basic Generator preferences

The Filter records before display in LOV (RECFLT) preference replaces the obsolete Filter Before Display? property.

The Display lookup item in List of Values (ITMDLV) preference replaces the obsolete Display in LOV? property.

Preferences removed in 6i

Radio group button orientation (RADOWG)

You now determine the the radio group button orientation by setting the Display Type property to Radio Group (Across) or Radio Group (Down) as appropriate.

Control group orientation within group (GRPOWG)

You now determine the the radio group button orientation by setting the Display Type property to Radio Group (Across) or Radio Group (Down) as appropriate.

Properties removed in 6i

The following properties used in specifying Lists of Values have been removed:

Filter before Display?	Filter records before display in LOV (RECFLT) preference is used instead.
Display in LOV?	Display lookup item in List of Values (ITMDLV) preference is used instead.
The property, LOV Title, has been removed.


Features added to Visual Basic Generator in previous releases

Features added to Visual Basic Generator in Oracle Designer Release 6.0

Features added to Visual Basic Generator in Oracle Designer Release 2.1.2

Features added to Visual Basic Generator in Designer/2000 Release 2.1.1

Features added to Visual Basic Generator in Designer/2000 Release 2.1


Features added to Visual Basic in Oracle Designer Release 6.0
Features added to Visual Basic Generator in Oracle Designer Release 6.0

No new features were added to Visual Basic Help Generator in Oracle Designer Release 6.0.


Features added to Visual Basic in Oracle Designer Release 2.1.2
Features added to Visual Basic Generator in Oracle Designer Release 2.1.2

Major new features in Oracle Designer Visual Basic Generator Release 2.1.2

Generation and design capture of multiple modules is now supported by the Design Editor's new batch processing tools.

Visual Basic 5.0 templates and library forms

The VB4 templates and library forms shipped in earlier releases of Visual Basic Generator continue to be shipped in release 2 onwards and remain the default. The VB4 templates and libraries make use of the following third party controls, which are installed as part of a standard VB4 installation:

•	The MicroHelp Gauge Control (Gauge32.ocx): Gauge

•	Sheridan 3D Controls (ThreeD32.ocx): SSCheck, SSFrame, SSCommand, SSPanel, SSOption, SSRibbon

However, in release 2 onwards, Visual Basic Generator is also supplied with copies of the VB4 templates and library forms that have been upgraded to Visual Basic 5.0. In VB5, functionality provided by the third party controls is provided by standard Microsoft controls. The third party controls are no longer necessary, and are therefore not included in a standard VB5 installation. For the same reason, the new VB5 templates shipped with Visual Basic Generator do not make use of third party controls but make use of the standard Microsoft controls.

If your generated application makes use of these third party controls, we strongly recommend you consider using the Microsoft standard controls instead.

In addition, the SSPanel control type has been removed from the VB5 CGTCControls template form. If you are using this VB5 template, you will no longer be able to:

•	specify SSPanel as an item's Display Template/Library Object

•	specify SSPanel as the default control type for any of the Visual Basic Generator preferences in the Controls category

 For more information, refer to Using Visual Basic 5.0.

Compatibility with Visual Basic 6.0

The VB5 templates supplied with Visual Basic Generator are fully compatible with Visual Basic 6.0. For more information, refer to Using Visual Basic Version 6.0.


Features added to Visual Basic in Designer/2000 Release 2.1.1
Features added to Visual Basic Generator in Designer/2000 Release 2.1.1

No new features were added to Visual Basic Help Generator in Designer/2000 Release 2.1.1.


Features added to Visual Basic Generator in Designer/2000 Release 2.1

Terminology

New/changed terminology

Major new features

Visual Basic Data Access Objects (DAO) support

Visual Basic version 4.0 and 5.0 support

New Visual Basic Design Capture utility

Application logic generation and capture

Other new and improved features

New Repository elements

New Repository properties

Preferences

New preferences

Preferences removed in Release 2.1

New/changed terminology

If you have used Visual Basic Generator in a previous release of Oracle Designer you will notice some terminology changes:

Release 1.x element	Release 2.1 element
Detailed column usage	Item
Detailed table usage	Module component table usage
Release 1.x property	Release 2.1 property
Zone Caption	Title
Zone Style	Layout Style
Template Zone	Template/Library Object
Column Usage Alias	Item Name
Select	Query
Caption	Prompt
Justification	Alignment
Control Style	Display Type
Template Control Name	Template/Library Object
Display Group	Item Group
Group Caption	Item Group Prompt
Major new features

Visual Basic Data Access Objects (DAO) support

You can now design and generate Visual Basic applications that use the DAO programming interface to interact with databases. This means you can build applications that access databases other than Oracle databases.

To support this new feature Visual Basic Generator provides an additional library project called INCLDAO.VBP. All you have to do is select the correct Data Access Method for your application prior to generation, no further configuration is required.

Visual Basic version 4.0 and 5.0 support

You can use the latest Visual Basic design environment (Version 5.0) to view and run generated Visual Basic applications.

New Visual Basic Design Capture utility

This new feature transforms existing Visual Basic applications into module design specifications held in the Designer/2000 Repository. The Visual Basic Design Capture utility can assist the documentation of Visual Basic applications and the migration to other environments such as Oracle Developer Forms and Reports.

Application logic generation and capture

If you add your own Visual Basic code to a generated application using the Visual Basic design environment you can save the additions back to the Designer/2000 Repository using the new Visual Basic Capture Application Logic utility. This feature prevents new code from being overwritten the next time the project is generated.

In addition to this, you can enter new event logic and new named routines directly against Visual Basic module design specifications in the Repository. Visual Basic modules support user-defined application logic against Windows, Module Components, Items and Action Items.

New Repository element used by Visual Basic Generator

Repository element	Use in Visual Basic application

Window	Defines characteristics of windows that enclose zones.
Module Components	Defines characteristics of zones.
Unbound Item	Defines controls that are not bound to columns.
Custom Action Item	Executes user defined code on a particular Visual Basic event.
Generator Action Item	Executes standard Visual Basic Generator functionality.
Navigation Action Item	Navigates to other zones and windows.
New Repository properties used by Visual Basic Generator

Repository element	Property	Use in Visual Basic application

Window	Title	Title for the window.
	Template/Library Object	Template for the window.
Module Component	Autoquery?	Controls how zones are queried.
Table Usage	Name in Database	Table name used in FROM clause of generated queries.
Lookup Table Usage	Filter before Display?	Controls the number of records displayed in a lookup LOV.
	LOV Title	Title for lookup LOV dialog.
	Lookup Validation WHERE Clause	Condition for foreign key validation.
Item Group	Template/ Library Object	Template for item group.
	User/Help Text	Help text for item group.
Item	Unbound Type	Defines a custom unbound item.
	Range Search	Controls range searching on the Query dialog.
	Show Meaning?	Controls display of allowed values and meanings.
New Visual Basic Generator preferences

Additional default control styles
Default Button control type	CTLBUT
Default Datetime control type	CTLDTT
Default OLE control type	CTLOLE

Use Tab control for stacking areas (USETAB)
Use this preference to define how stacking areas are implemented. This functionality was previously controlled in the CGTGStackSelector template form. See USETAB.

Template menu to locate menu items for custom action items (TFMNCA)
Use this preference to define the menu item used to display custom action items. See TFMNCA.

Preferences removed in Release 2.1

Scope of code controls table (CCTABL)
This preference is now one of several 'General application' options you can set from Design Editor.

Scope of reference codes table (DVTABL)
This preference is now one of several 'General application' options you can set from Design Editor.

Hold Time on Change History Columns (WHTIME)
This preference is now one of several 'General application' options you can set from Design Editor.

Maximum number of rows to auto-query (MAXQRY)
This functionality provided by this preference is now controlled by two new properties Filter before Display? and AutoQuery?


Using application logic and Visual Basic Generator

Related Topics	Where am I?

About application logic and Visual Basic Generator

About generated application logic created by Visual Basic Generator

About user-modified generated application logic and Visual Basic Generator

Modifying generated application logic created by Visual Basic Generator

Capturing application logic from Visual Basic applications

About user-defined application logic and Visual Basic Generator

Entering user-defined event code for Visual Basic Generator

Entering user-defined named routines for Visual Basic Generator

About template application logic and Visual Basic Generator

Event types in generated Visual Basic applications

Physical Visual Basic event types

Pseudo Visual Basic event types

Visual Basic Generator code groups


About application logic and Visual Basic Generator

Related Topics	Where am I?

Visual Basic Generator supports the following types of application logic:

Type of application logic	Description
generated	Event code and named routines in the generated application that have been created by a Generator from generatable application logic.
generatable	Code that a Generator may or may not generate. You can view generatable event code (but not named routines) in the Design Editor, but the code is not saved in the repository.
user-defined	Event code and named routines you define using the Design Editor or capture from an application. In either case, the code is saved in the repository.
template	Code in a template file that a Generator includes in the generated application.
user-modified generated	Modifications to generated code made using the target design-time environment. Captured and saved in the repository as user-modified generated application logic.
hand-coded	New code added into the generated application using the target design-time environment. Captured and saved in the repository as additional user-defined application logic.


About generated application logic created by Visual Basic Generator

Related Topics	Where am I?

Generated application logic is not held in the repository, it is the code generated by Visual Basic Generator each time a module is generated. If the module has been generated before, the existing code is overwritten.

If you enter your own user-defined application logic, generatable event code segments for the module element are displayed in Design Editor (even though the generated code is not stored in the repository). This is so that you can define the overall sequence of event code. How


About user-modified generated application logic and Visual Basic Generator

Related Topics	Where am I?

You can modify generated code and then test the changes you have made using the Visual Basic design environment. How

Then you can use the Visual Basic Capture Application Logic utility to save the changes back to the repository (where it is held against the appropriate Visual Basic module element). This prevents the modified logic from being overwritten when the project is next generated. How

Code cannot be captured for Visual Basic controls that do not map to elements in the repository i.e. LOV buttons, zone list boxes, template menus, OK, Cancel and New buttons. However, code for these items can be added to the template instead.


Modifying generated application logic created by Visual Basic Generator

Related Topics	Where am I?

You can modify generated code and then test the changes you have made using the Visual Basic design environment. If the modified code is suitably marked the changes can be saved back to the repository (where it is held against the appropriate Visual Basic module element).

To modify Visual Basic code in a generated form:

1.	Open the generated form in Visual Basic Designer.

2.	If you intend to generate the form again using Visual Basic Generator, mark the Visual Basic code you intend to modify by editing the comment line.

For example, Visual Basic Generator might create the comment (or tag):

'	CG$PD0009
To indicate that you intend to modify this part of the generated code, you might add the words 'User Modified', or 'Override':

'  User Modified	CG$PD0009
'  Override	CG$PD0009
Note that the text you enter is not significant.

3.	Modify the Visual Basic code and then test the modifications as required.

4.	Use the Visual Basic Capture Application Logic Utility to save the modified logic in the repository.  How


Capturing application logic from Visual Basic applications

Related Topics	Where am I?

Use the Visual Basic Capture Application Logic utility to save changes to modified code back to the repository (where it is held against the appropriate Visual Basic module element). About

Note: 	Code cannot be captured for Visual Basic controls that do not map to elements in the repository i.e. LOV buttons, zone list boxes template menus, OK, Cancel and New buttons. However, code for these items can be added to the template instead.

To capture modified code from a generated Visual Basic project:

1.	On the Navigator select the destination Visual Basic module for the modified code.

To capture modified code for more than one module in a module network, select the top level module.

2.	Choose Generate→Capture Application Logic.

3.	Specify the name of the Visual Basic Project File that contains the modified code.

4.	(optional) Select Capture Module Network, if required.

5.	Use the Post Capture options to specify whether to save changes to the repository during application logic capture:

•	Commit - update repository objects

•	Browse/Edit - show proposed repository changes, enabling you to choose how to process them

Note that there are some circumstances when Visual Basic Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture.

6.	Click Start.

The sequence of the modified/new code in relation to other generatable event code is maintained during the capture process.


About user-defined application logic and Visual Basic Generator

Related Topics	Where am I?

User-defined application logic can be either or both:

•	code you enter into the repository using the Design Editor and the Logic Editor

•	code you enter using the Visual Basic design environment and then capture into the repository

When you enter user-defined application logic in the Design Editor, you specify it as being one of the following:

•	event code, which is generated as code for Visual Basic physical events and pseudo-events

•	a named routine, which is generated as a Visual Basic routine and called from event code or other routines


Entering user-defined event code for Visual Basic Generator

Related Topics	Where am I?

You can enter user-defined event code against windows, module components, items and action items in a Visual Basic module. You can also define where the new code is sequenced in relation to other code (generatable event code and other user-defined event code) generated for the same event. About

Within event code you can make use of any native function and procedure provided by Visual Basic. You can also call named routines defined in the repository. How

To enter user-defined event code for Visual Basic Generator:

1.	In the Design Editor, create user-defined event code.  How

2.	Use the Target Location property to define which Visual Basic form the event code should be added to during generation.

The Target Location property is only applicable when defining application logic against module components and items. It enables you to define a different action on each type of form that can be generated for a single zone i.e. a single item may be displayed on a Query dialog, Property dialog, as well as the Main Form.


Entering user-defined named routines for Visual Basic Generator

Related Topics	Where am I?

You can define new named routines against windows, module components, items and action items in a Visual Basic module. These routines can be referenced within user-defined event code.

To enter user-defined named routines for Visual Basic Generator:

1.	In the Design Editor, create a user-defined named routine.  How

2.	Use the Target Location property to define which Visual Basic form the routines should be added to during generation.

The Target Location property is only applicable when defining application logic against module components and items. It enables you to define a different action on each type of form that can be generated for a single zone i.e. a single item may be displayed on a Query dialog, Property dialog, as well as the Main Form.

3.	Choose whether the named routine is Public or Private.


About template application logic and Visual Basic Generator

Related Topics	Where am I?

Template application logic is not held in the repository, it is standard library forms and code (standard inclusions) that is copied into the Visual Basic application from a template library project during generation. For more information on the standard inclusions provided by Visual Basic Generator refer to Visual Basic library forms and code.

You can add your own forms or code modules to the template library project using the Visual Basic design environment if required. How


Event types in generated Visual Basic applications

Related Topics

There are two categories of events that code can be added to during Visual Basic generation:

Physical events	The physical or actual events supported by Visual Basic e.g.  Click, GotFocus, Load etc.
Pseudo events	A set of events recognized by Visual Basic Generator, but not supported by the Visual Basic language e.g. PreInsert event, Reposition event, the declaration section of a Visual Basic Form etc.


Physical Visual Basic event types
Physical Visual Basic events

Related Topics

These are physical or actual events supported by Visual Basic. To access Visual Basic event topics in the Visual Basic 5.0 Help file (vb5.hlp), click the event type in the table below. Alternatively, use the Visual Basic 6.0 Help system.

Note:	You must have the vb5.hlp file either referenced in the path, or installed in the same directory as your Oracle Designer help files, otherwise the topics below will not be displayed and you will receive an error message.

Event type	Repository elements	Description
Activate	Window	Occurs when a form becomes the active window.
Change	Item	Indicates that the contents of a control have changed. How and when this event occurs varies with the type of control.
Click	Window, Item, Action Item	Occurs when the user presses and then releases a mouse button over an object. It can also occur when the value of a control is changed.
Dblclick	Window, Item	Occurs when the user presses and then releases a mouse button over an object. It can also occur when the value of a control is changed.
Deactivate	Window	Occurs when a form is no longer the active window.
DragDrop	Window, Item, Action Item	Occurs when a drag-and-drop operation is completed as a result of dragging a control over a form or control and releasing the mouse button, or using the Drag method with its action argument set to 2 (Drop).
DragOver	Window, Item, Action Item	Occurs when a drag-and-drop operation is in progress. You can use this event to monitor the mouse pointer as it enters, leaves, or rests directly over a valid target. The mouse pointer position determines the target object that receives this event.
GotFocus	Window, Item, Action Item	Occurs when an object receives the focus, either by user action, such as tabbing to or clicking the object, or by changing the focus in code using the SetFocus method. A form receives the focus only when all visible controls are disabled.
Initialize	Window	Occurs when an application creates an instance of a Form, MDIForm, or class.
KeyDown	Window, Item, Action Item	Occur when the user presses (KeyDown) or releases (KeyUp) a key while an object has the focus. (To interpret ANSI characters, use the KeyPress event.)
KeyPress	Window, Item, Action Item	Occurs when the user presses and releases an ANSI key.
KeyUp	Window, Item, Action Item	Occur when the user presses (KeyDown) or releases (KeyUp) a key while an object has the focus. (To interpret ANSI characters, use the KeyPress event.)
LinkClose	Window, Item	Occurs when a DDE conversation terminates. Either application in a DDE conversation may terminate a conversation at any time.
LinkError	Window, Item	Occurs when there is an error during a DDE conversation. This event is recognized only as the result of a DDE-related error that occurs when no Visual Basic code is being executed. The error number is passed as an argument.
LinkExecute	Window	Occurs when a command string is sent by a destination application in a DDE conversation. The destination application expects the source application to perform the operation described by the string.
LinkNotify	Item	Occurs when the source has changed the data defined by the DDE link if the LinkMode property of the destination control is set to 3 (Notify).
LinkOpen	Window, Item	Occurs when a DDE conversation is being initiated.
Load	Window	Occurs when a form is loaded. For a startup form, occurs when an application starts as the result of a Load statement or as the result of a reference to an unloaded form's properties or controls.
LostFocus	Window, Item, Action Item	Occurs when an object loses the focus, either by user action, such as tabbing to or clicking another object, or by changing the focus in code using the SetFocus method.
MouseDown	Window, Item, Action Item	Occur when the user presses (MouseDown) or releases (MouseUp) a mouse button.
MouseMove	Window, Item, Action Item	Occurs when the user moves the mouse.
MouseUp	Window, Item, Action Item	Occur when the user presses (MouseDown) or releases (MouseUp) a mouse button.
Paint	Window	Occurs when part or all of a form or PictureBox control is exposed after it has been moved or enlarged or after a window that was covering the object has been moved.
PathChange	Item	Occurs when the path is changed by setting the FileName or Path property in code.
PatternChange	Item	Occurs when the file listing pattern, such as "*.*", is changed by setting the FileName or Pattern property in code.
QueryUnload	Window	Occurs before a form or application closes. When an MDIForm object closes, the QueryUnload event occurs first for the MDI form and then in all MDI child forms.
Resize	Window	Occurs when a form is first displayed or the size of an object changes.
Scroll	Item	Occurs when a user repositions the scroll box on a scroll bar or scrolls a DBGrid control horizontally or vertically.
SelChange	Item	Occurs when the current range changes to a different cell or range of cells.
Terminate	Window	Occurs when all references to an instance of a Form, MDIForm, or class are removed from memory by setting all the variables that refer to the object to Nothing or when the last reference to the object falls out of scope.
Timer	Item	Occurs when a preset interval for a Timer control has elapsed. The interval's frequency is stored in the control's Interval property, which specifies the length of time in milliseconds.
Unload	Window	Occurs when a form is about to be removed from the screen. When that form is reloaded, the contents of all its controls are reinitialized. This event is triggered by a user closing the form using the Close command on the Control menu or an Unload statement.
Declarations	Window, Module Component	General declarations


Pseudo Visual Basic event types
Pseudo Visual Basic events

Related Topics

These are a set of events recognized by Visual Basic Generator, but not supported by the Visual Basic language. Code associated with these events is stored against module components in the repository i.e. a zone in the generated application.

Pseudo events	Repository element	Code group name	Description	Additional information
PostInsert	Module Component	CG$GN0007	This routine is triggered after inserting a record into the database. Processing that should occur after a record is inserted can be added here.	Property sheet dialogs
PreInsert	Module Component	CG$GN0003	This routine is triggered before inserting a record into the database. Processing that should occur before a record is inserted can be added here.
PreUpdate	Module Component		This routine is triggered before updating a record on the database. Processing that should occur before a record is updated can be added here.	Property sheet dialogs Column derivation
Reposition	Module Component	CG$GN0001	This routine is triggered after displaying a new record in the zone i.e. when a record has been queried from the database, after a new record has been inserted into the database, or after moving from one record to another record in the zone.	Context-style zones Form-style zones List-style zones Zone co-ordination
Validate	Module Component	CG$GN0004	This routine validates the data in the controls.	Form-style zones Populating lookups Property sheet dialogs Validation code


Visual Basic Generator code groups

Related Topics

This table lists Visual Basic Generator code groups, by functionality. It also shows the prefix used to identify code within a particular group and this information may be useful if you intend to modify generated code or add new application logic.

Visual Basic Generator code groups to implement:	Code group prefix
Column derivation	CG$CD...
Domain validation	CG$DV...
Foreign keys	CG$FK...
General code	CG$GN...
Hint text	CG$HT...
Keyboard navigation	CG$KN...
Sequence within parent functionality	CG$SP...
Validation	CG$VL...
Zone coordination	CG$ZC...
Form functionality
Property Sheet dialog	CG$PD...
Query dialog	CG$QD...
Form and List/Form zone	CG$Z1...
List zone	CG$Z2...
Context zone	CG$Z4...


Visual Basic Generator code groups to implement column derivation

Code group name	Description	Associated event	element type
CG$CD0002	Derive column values e.g. unique identifiers and user created.	PreInsert	Zone
CG$CD0003	Derive column values e.g. date or user modified.	PreUpdate	Zone
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend to:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Column derivation in generated Visual Basic applications


Visual Basic Generator code groups to implement domain validation

Code group name	Description	Associated event	element type
CG$DV0001	Load valid value list into VB arrays	Load	Window
CG$DV0002	Declare variables for domain validation (valid values array)	Declarations	Window
CG$DV0003	Valid controls with lists of valid values	Validate	Module Component
CG$DV0004	Valid control value against list of allowed values	LostFocus	Item
CG$DV0005	Invoke LOV for control with valid values list	KeyPress	Item
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Domain validation in generated Visual Basic applications


Visual Basic Generator code groups to implement foreign keys

Code group name	Description	Associated event	element type
CG$FK0005	Validate Foreign Key value	LostFocus	Item
CG$FK0006	Validate lookup control value and populate hidden FK value	LostFocus	Item
CG$FK0007	Invoke LOV for control within a foreign key	KeyPress	Item
CG$FK0008	Invoke LOV for a lookup control	KeyPress	Item
CG$FK0009	Validate Enterable Foreign Key Lookup correctly defined	Validate	Module Component
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Populating lookups in generated Visual Basic applications

List-style zone (generated Visual Basic code)


Visual Basic Generator code groups to implement general code

Code group name	Description	Associated event	element type
CG$GN0005	If form is project's main form, then End the VB session	Unload	Window
CG$GN0006	Declare constants for the generator's name and version	Declarations	Window
CG$GN0008	If MDIChild, avoid dynamic resizing of window at startup	Load	Window
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How


Visual Basic Generator code groups to implement hint text

Code group name	Description	Associated event	element type
CG$HT0001	Display hint text for the control (subject to timer delay)	MouseMove	Item
CG$HT0002	Clear the hint text popup label	Deactivate	Window
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

About hint text for controls


Visual Basic Generator code groups to implement keyboard navigation

Code group name	Description	Associated event	element type
CG$KN0001	Ensure first stacked frame is at front of stacking area	Load	Window
CG$KN0003	Highlight contents of TextBox; ensure stacked area visible	GotFocus	Item
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

About keyboard navigation in generated Visual Basic applications


Visual Basic Generator code groups to implement property sheet dialog functionality

Code group name	Description	Associated event	element type
CG$PD0011	Property Sheet Dialog: Prepare form for Insert or Query	Activate	Window
CG$PD0012	Check user may modify value; Enable OK/Cancel buttons	Change	Item
CG$PD0017	Declare variables for Property Sheet Dialog (Dynasets...)	Declarations	Window
CG$PD0020	Create dynaset(s) requires to query the database row	Load	Window
CG$PD0023	Unload Property Sheet Dialog upon unloading main form	Unload	Window
CG$PD0024	If Multiline Textbox, don't make PSD's OK button the default	GotFocus	Item
CG$PD0025	If Multiline textbox, make PSD's OK button the default	LostFocus	Item
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Property sheet dialogs (generated Visual Basic code)


Visual Basic Generator code groups to implement query dialog functionality

Code group name	Description	Associated event	element type
CG$QD0002	Query Dialog - Highlight last search criteria	Activate	Window
CG$QD0003	Unload Query Dialog Form upon unloading main form	Unload	Window
CG$QD0008	Query Dialog: Fire clear button to clear all controls	Load	Window
CG$QD0009	Query Dialog: Declare global flag to control QD reset	Declarations	Window
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Query dialogs (generated Visual Basic code)


Visual Basic Generator code groups to implement sequence within parent functionality

Code group name	Description	Associated event	element type
CG$SP0003	Allocate Sequence In Parent derived column value	PreInsert	Module Component
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Column derivation in generated Visual Basic applications


Visual Basic Generator code groups to implement validation

Code group name	Description	Associated event	element type
CG$VL0001	Convert control value to uppercase	KeyPress	Item
CG$VL0002	Validate all the zone's controls for length, datatype...	Validate	Module Component
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Validation code in generated Visual Basic applications


Visual Basic Generator code groups to implement Form and List/Form functionality

Code group name	Description	Associated event	element type
CG$Z10011	Fetch entire row; maintain record status variables	Reposition	Module Component
CG$Z10012	Check user may modify value; Enable Save/Undo buttons	Change	Item
CG$Z10015	Declare variables for a Form zone (dynasets...)	Declarations	Window
CG$Z10030	Create dynasets for DML in Form and List/Form zones	Load	Window
CG$Z10034	Supply value for Sequence In Parent column	PreInsert	Module Component
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Form-style zone (generated Visual Basic code)

List/Form-style zone (generated Visual Basic code)


Visual Basic Generator code groups to implement List zone functionality

Code group name	Description	Associated event	element type
CG$Z20011	Copy PK to hidden controls; Set Record management variables	Reposition	Module Component
CG$Z20015	Declare variables for a List zone (PK arrays...)	Declarations	Module Component
CG$Z20017	Resize List zone and move surrounding controls	Resize	Window
CG$Z20018	Save size/locations of objects for resizing List zone	Load	Window
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

List-style zone (generated Visual Basic code)


Visual Basic Generator code groups to implement Context zone functionality

Code group name	Description	Associated event	element type
CG$Z40001	Context zone: Enable appropriate buttons	Reposition	Module Component
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Context-style zone (generated Visual Basic code)


Visual Basic Generator code groups to implement zone coordination

Code group name	Description	Associated event	element type
CG$ZC0001	Declare variables for zone coordination	Declarations	Window
CG$ZC0004	Enable and coordinate detail zones	Reposition	Module Component
CG$ZC0007	Check for changes in, and close detail forms	QueryUnload	Window
CG$ZC0008	Initialize for state with respect to zone coordination	Load	Window
CG$ZC0009	Autoquery first zone if applicable	Activate	Window
CG$ZC0012	Unload detail form(s)	Unload	Window
This table shows the prefixes used to identify code groups within the generated application. This information may be useful if you intend:

•	Modify generated code How

•	Add new event code How

For more information about when Visual Basic Generator creates these code groups, refer to:

Zone coordination in generated Visual Basic applications


 Visual Basic Generator preferences

Related Topics

You can customize the generation of Visual Basic applications by changing the initial settings of the Visual Basic Generator preferences. How

Click the category to display a list of preferences. To display the complete list, click Expand All

 Controls

 DBA

 End User Interface

 Layout-Control

 Layout-Group

 Layout-Zone

 Templates


Visual Basic Generator preferences

Related Topics

These preferences customize the generation of Visual Basic applications. Collapse All

Controls
Control definition file	CTLDEF
Button control	CTLBUT
Default character text control	CTLCHR
Default checkbox control	CTLCHK
Default combo box control	CTLCMB
Default date text control	CTLDAT
Default datetime text control	CTLDTT
Default integer number text control	CTLINT
Default listbox control	CTLLST
Default pop list control	CTLPLT
Default OLE control	CTLOLE
Default radio group control	CTLRAD
Default real number text control	CTLREL
DBA
Table owner for use in SQL	TABOWN
End User Interface
Should hint text be created for data controls	HTDATA
Should hint text be created for buttons	HTUINT
Add mnemonic access characters to controls	MNMADD
Add mnemonic access characters to data entry controls	MNMDEC
Reuse characters when assigning mnemonics	MNMREU
Make property sheet dialogs modal	PSDMOD
Filter records before display in LOV	RECFLT
Use Tab control for stacking area	USETAB
Layout - Control
Text control default character length	TXTDCL
Text control default date length	TXTDDL
Text control default numeric length	TXTDNL
Radio group horizontal inter-button spacing	RADHIS
Radio group buttons per line	RADMLF
Radio group vertical inter-button spacing	RADVIS
List of values button alignment	LOVBAL
List of values control/button gap	LOVITG
Display lookup item in List of Values	ITMDLV
Allow prompts above controls	ITMPAS
Control post-prompt marker	ITMPPM
Control split-prompt marker	ITMSPM
Default prompt separator	ITMDPS
Control/prompt gap	ITMIPG
Prompt/control gap	ITMPIG
Alignment of single control lines when BLKLYS is set to FILL	ITMSFJ
Layout - Group
Control group multi-line format	GRPMLF
Control group horizontal inter-control spacing	GRPHIS
Use group tabulation table	GRPUTT
Control group vertical inter-control spacing	GRPVIS
Layout - Zone
Alignment of controls within zone	BLKLYS
Number of controls per line	BLKMLF
Vertical space separating controls	BLKMLL
Zone tabulation table	BLKTAB
Use zone tabulation table?	BLKUTT
Zone vertical fill?	BLKVFL
Templates
Library (standard inclusions) project	MGPROJ
Template project	TFPROJ
Template menu to locate module network entries	TFMNMN
Template menu to locate menu items to open detail forms	TFMNZC
Template menu to locate menu items for custom action items	TFMNCA


Visual Basic Generator preferences

Related Topics

You can customize the generation of Visual Basic applications by changing the initial settings of the Visual Basic Generator preferences.

Click the category to display a list of preferences. Alternatively, click Expand All [image] or Collapse All

Controls
Control definition file	CTLDEF
Button control	CTLBUT
Default character text control	CTLCHR
Default checkbox control	CTLCHK
Default combo box control	CTLCMB
Default date text control	CTLDAT
Default datetime text control	CTLDTT
Default integer number text control	CTLINT
Default listbox control	CTLLST
Default pop list control	CTLPLT
Default OLE control	CTLOLE
Default radio group control	CTLRAD
Default real number text control	CTLREL
DBA
End User Interface
Layout - Control
Layout - Group
Layout - Zone
Templates


Visual Basic Generator preferences

Related Topics

You can customize the generation of Visual Basic applications by changing the initial settings of the Visual Basic Generator preferences.

Click the category to display a list of preferences. Alternatively, click Expand All [image] or Collapse All

Controls
DBA
Table owner for use in SQL	TABOWN
End User Interface
Layout - Control
Layout - Group
Layout - Zone
Templates


Visual Basic Generator preferences

Related Topics

You can customize the generation of Visual Basic applications by changing the initial settings of the Visual Basic Generator preferences.

Click the category to display a list of preferences. Alternatively, click Expand All [image] or Collapse All

Controls
DBA
End User Interface
Should hint text be created for data controls	HTDATA
Should hint text be created for buttons	HTUINT
Add mnemonic access characters to controls	MNMADD
Add mnemonic access characters to data entry controls	MNMDEC
Reuse characters when assigning mnemonics	MNMREU
Make property sheet dialogs modal	PSDMOD
Filter records before display in LOV	RECFLT
Use tab control for stacking area	USETAB
Layout - Control
Layout - Group
Layout - Zone
Templates


Visual Basic Generator preferences

Related Topics

You can customize the generation of Visual Basic applications by changing the initial settings of the Visual Basic Generator preferences.

Click the category to display a list of preferences. Alternatively, click Expand All [image] or Collapse All

Controls
DBA
End User Interface
Layout - Control
Text control default character length	TXTDCL
Text control default date length	TXTDDL
Text control default numeric length	TXTDNL
Radio group horizontal inter-button spacing	RADHIS
Radio group buttons per line	RADMLF
Radio group vertical inter-button spacing	RADVIS
List of values button alignment	LOVBAL
List of values control/button gap	LOVITG
Display lookup item in List of Values	ITMDLV
Allow prompts above controls	ITMPAS
Control post-prompt marker	ITMPPM
Control split-prompt marker	ITMSPM
Default prompt separator	ITMDPS
Control/prompt gap	ITMIPG
Prompt/control gap	ITMPIG
Alignment of single control lines when BLKLYS is set to FILL	ITMSFJ
Layout - Group
Layout - Zone
Templates


Visual Basic Generator preferences

Related Topics

You can customize the generation of Visual Basic applications by changing the initial settings of the Visual Basic Generator preferences.

Click the category to display a list of preferences. Alternatively, click Expand All [image] or Collapse All

Controls
DBA
End User Interface
Layout - Control
Layout - Group
Control group multi-line format	GRPMLF
Control group horizontal inter-control spacing	GRPHIS
Use group tabulation table	GRPUTT
Control group vertical inter-control spacing	GRPVIS
Layout - Zone
Templates


Visual Basic Generator preferences

Related Topics

You can customize the generation of Visual Basic applications by changing the initial settings of the Visual Basic Generator preferences.

Click the category to display a list of preferences. Alternatively, click Expand All [image] or Collapse All

Controls
DBA
End User Interface
Layout - Control
Layout - Group
Layout - Zone
Alignment of controls within zone	BLKLYS
Number of controls per line	BLKMLF
Vertical space separating controls	BLKMLL
Zone tabulation table	BLKTAB
Use zone tabulation table?	BLKUTT
Zone vertical fill?	BLKVFL
Templates


Visual Basic Generator preferences

Related Topics

You can customize the generation of Visual Basic applications by changing the initial settings of the Visual Basic Generator preferences.

Click the category to display a list of preferences. Alternatively, click Expand All [image] or Collapse All

Controls
DBA
End User Interface
Layout - Control
Layout - Group
Layout - Zone
Templates
Library (standard inclusions) project	MGPROJ
Template menu to locate module network entries	TFMNMN
Template menu to locate menu items to open detail forms	TFMNZC
Template menu to locate custom action items	TFMNCA
Template project	TFPROJ


Visual Basic Generator preferences - alphabetical
Select the initial letter of the preference that you require.

A

B

BLKLYS

BLKMLF

BLKMLL

BLKTAB

BLKUTT

BLKVFL

C

CTLBUT

CTLCHK

CTLCHR

CTLCMB

CTLDAT

CTLDEF

CTLDTT

CTLINT

CTLLST

CTLOLE

CTLPLT

CTLRAD

CTLREL

D

E

F

G

GRPHIS

GRPMLF

GRPUTT

GRPVIS

H

HTDATA

HTUINT

I

ITMDLV

ITMDPS

ITMIPG

ITMPAS

ITMPIG

ITMPPM

ITMSFJ

ITMSPM

J

K

L

LOVBAL

LOVITG

M

MGPROJ

MNMADD

MNMDEC

MNMREU

N

O

P

PSDMOD

Q

R

RADHIS

RADMLF

RADVIS

RECFLT

S

T

TABOWN

TFMNCA

TFMNMN

TFMNZC

TFPROJ

TXTDCL

TXTDDL

TXTDNL

U

USETAB

V

W

X Y Z


Control type mapping preferences

Related Topics

These preferences provide the default mapping between the item's Display Type property and the specific type of control used to implement the item in the generated application.

The following table shows how each preference provides a default value for a particular Display Type. This default is a specific control type. Each control (or at least, its type) must appear in the control definition file.

Display Type	Column Datatype	Preference	Default	Description
Text	Character	CTLCHR	TextBox	Default Character text control type.
Text	Date	CTLDAT	TextBox	Default Date text control type.
Text	Datetime	CTLDTT	TextBox	Default Datetime text control type.
Text	Number	CTLINT	TextBox	Default Integer Number text control type.
Text	Real Number	CTLREL	TextBox	Default Real Number text control type i.e. a number with decimal places.
Checkbox		CTLCHK	CheckBox	Default Check Box control type.
ComboBox		CTLCMB	ComboBox	Default ComboBox control type.
OLE		CTLOLE	OLE	Default OLE control type.
Pop List		CTLPLT	ComboBox	Default PopList control type.
Radio Group		CTLRAD	Frame	Default Radio Group control type.
Text List		CTLLST	ListBox	Default ListBox control type.
Button		CTLBUT	Command Button	Default button control (custom unbound items only).
The Template/Library Object property against the item can be used to override the default mapping defined by a particular preference.


Control definition file (CTLDEF)

Related Topics

Default:	cvbetc\ctldef.txt
Values:	Up to 255 characters
Levels:	Container

Use this preference to specify the name of the control definition file to be used during generation. The control definition file holds information on the characteristics and capabilities of each of the controls being used.

If you specify Repository as the Source option on the Visual Basic Generator Options dialog box, Visual Basic Generator searches for the control definition file in the repository folders specified in the Repository Folders field on the Visual Basic Generator Options dialog box.

If you specify File System as the Source option on the Visual Basic Generator Options dialog box, include the full path of the control definition file. If only a partial pathname is specified, the location is relative to the Generator's installation directory and this is defined in the CGENV61 entry in the registry.


Table owner for use in SQL (TABOWN)

Related Topics

Default:	None
Values:	Up to 30 characters
Levels:	Container
Examples:

Use this preference to specify whether generated table references (within SQL statements) are prefixed with the name of the Oracle user who owns the tables.

This preference has no effect on those table usages where the Name in Database property is defined.

These values are:

Value	Tables are prefixed with the given owner name.
None	Tables are not prefixed with the name of the owner in generated SQL.


Hint text preferences

Related Topics

The Visual Basic Generator may optionally generate code and controls to provide 'tooltip' or 'popup' style hint text on generated buttons and/or data entry controls. The generation of this code is controlled by these preferences:

Should hint text be created for data controls (HTDATA)

Use this preference to determine whether or not 'tooltip' style hint text is provided for data controls.

Default:	Yes
Values:	Yes, No
Levels:	Container, module
These values are:

Yes	Provides hint text support for data controls (except in query dialogs) that have hint text defined against the associated item in the repository.
No	No data controls will have hint text support.

Use this preference to determine whether or not 'tooltip' style hint text is provided for data controls.

Should hint text be created for buttons (HTUINT)

Default:	Yes
Values:	Yes, No
Levels:	Container, module
These values are:

Yes	Provides hint text support for all generated buttons.
No	No generated buttons will have hint text support.

Use this preference to determine whether or not 'tooltip' style hint text is provided for generated buttons.


Mnemonic access preferences

Related Topics

These preferences act together to specify how mnemonic access is implemented for generated controls.

Add mnemonic access characters to controls (MNMADD)

Default:	Yes
Values:	Yes, No
Levels:	Container, module

Use this preference to determine whether or not mnemonic access characters are added to controls during generation.

If this preference is set to Yes, the other mnemonic preferences (MNMDEC and MNMREU) govern which controls are allocated access characters, and whether multiple controls within the same window may store the same access character. If you have assigned your own mnemonic characters to data entry controls (Prompt property), these are also added during generation.

These values are:

Yes	Mnemonic characters are added to controls.
No	Mnemonic characters are not added to controls. The MNMDEC and MNMREU preferences are ignored.
Add mnemonic access characters to data entry controls (MNMDEC)

Default:	All
Values:	All, None, Non-stacked
Levels:	Container, module

Use this preference to determine whether or not mnemonic access characters are added to data entry controls during generation. This preference is ignored if the MNMADD preference is set to No.

These values are:

All	Add to all of them Mnemonic access characters are added to all data entry controls.
None	Do not add to any of them Mnemonic access characters are not added to any data entry controls.
Non-stacked	Only add to those not on a stacking area Mnemonic characters are added only to permanently displayed controls i.e. not to those in stacking areas.
Reuse characters when assigning mnemonics (MNMREU)

Default:	Yes
Values:	Yes, No
Levels:	Container, module

Use this preference to determine whether or not characters are reused when assigning mnemonics. This preference is ignored if the MNMADD preference is set to No.

These values are:

Yes	Characters are reused when assigning mnemonics. The letter least used by other controls (not in the same stacked zone) is allocated. Letters are never reused if they are used by top-level menu items copied from the template or if they are allocated to a stacking area's option buttons.  At runtime, repeated pressing of ALT+letter will toggle focus between all controls that share the same access character.
No	Characters are not reused when assigning mnemonics.


Make property sheet dialogs modal (PSDMOD)

Related Topics

Default:	Yes
Values:	Yes, No
Levels:	Container, module

Use this preference to specify the modality of the property sheet dialogs that are created to view or modify records from a List style zone.

Notes:	Changes to non-modal dialogs are not synchronized back in the calling zone. Hence, if synchronization is important for a specific application, this preference must be set to Yes.

Property sheet dialogs are always displayed modally:

•	when creating new records

•	when viewing a record from a Context zone

•	if it is an MDI application

These values are:

Yes	Property sheet is displayed as a modal dialog.
No	Property sheet is non-modal. Multiple instances may be opened concurrently.


Filter records before display in LOV (RECFLT)

Related Topics

Default:	No
Values:	Yes, No
Levels:	Item

This preference determines how the records in a list of values (LOV) dialog are displayed.If set to Yes, the user is prompted to enter search criteria to restrict the number of records displayed. If set to No, the LOV dialog lists all available records.

These values are:

Yes	A search dialog is displayed for the user to restrict the search and reduce the number of values displayed in the LOV dialog.
No	The LOV dialog displays all the rows automatically.


Use tab control for stacking area (USETAB)

Related Topics

Default:	Yes
Values:	Yes, No
Levels:	Container, module

Use this preference to specify how stacking areas are implemented in the generated Visual Basic application.

If this preference is set to Yes, item groups that have the Stacked property set to Yes are generated as a set of tabbed dialogs using the SSTab control. If this preference is set to No, radio buttons are used to implement the stacked control groups.

Note: 	Detail module components that have the Placement property set to Stacked, are also incorporated in the master's stacking area.

These values are:

Yes	Use Tab control for stacking areas.
No	Do not use Tab control for stacking areas, use radio buttons instead.


Prompt placement preferences

Related Topics

These preferences act together to determine how prompts are to be placed.

Default prompt separator (ITMDPS)

Default:	:
Values:	Up to 10 characters
Levels:	Container, module

Use this preference to specify the character or string that the Generator appends to control prompts.

Control/prompt gap (ITMIPG)

Default:	2
Values:	0 to 99
Levels:	Container, module

Use this preference to specify the minimum gap (in grid units) between the end of a control (or its post-control prompt, if one exists) and the beginning of the prompt of the following control.

Prompt/control gap (ITMPIG)

Default:	1
Values:	0 to 99
Levels:	Container, module

Use this preference to specify the gap (in grid units) between the end of a prompt and the beginning of its control.


Allow prompts above controls (ITMPAS)

Related Topics

Default:	No
Values:	Yes, No
Levels:	Container, module

Use this preference to specify whether prompts are placed to the left, or above data entry controls.

By default prompts are placed to the left of controls. However, if horizontal space is limited the prompt may still be placed above the control to optimize the use of space. To place all prompts above controls regardless of the amount of space available, set this preference to Yes.

These values are:

No	Prompts are placed to the left of controls, providing there is sufficient horizontal space to do so.
Yes	Prompts are always placed above controls, reducing the amount of horizontal space required.


Prompt marker preferences

Related Topics

These preferences act together to define how prompts are split.

Control post-prompt marker (ITMPPM)

Default:	|
Values:	Up to 2 characters
Levels:	Container, module

Use this preference to specify the post-prompt marker character.

The Prompt property defined against an item may optionally be split into two portions: one that appears before the control, and another that appears after it. A marker may be placed within the prompt to indicate that the prompt is to be split in this way.

Note:	Do not use the & character if you intend to allocate your own mnemonics to data entry controls.

The part of the prompt string occurring before the post-prompt marker character is treated as the pre-prompt; the part after is the post-prompt. For example, if this preference is set to '|' the prompt 'Distance| (Miles)' looks like this:

Control split-prompt marker (ITMSPM)

Default:	<Null>
Values:	Up to 1 ASCII character
Levels:	Container, module

Use this preference to specify the split-prompt marker character. Control prompts can be split over more than one line if the prompt will not fit on a single line next to the generated control.

If horizontal space is limited, generated control prompts are split over more than one line. By default, prompts are split by replacing the white space nearest the center of the prompt with a new line (the white space is one or more space characters). However, if you want to split the prompt at a specific location you can define a split character using this preference.

This character can then be placed within the prompt text at the point where you want the prompt to be split.

When it splits a prompt, the Generator does so at the first occurrence of the split-prompt marker. Any additional instances of this character are displayed normally. For example, If this preference is set to '\' the prompt 'Distance\ (Miles) looks like this:

These values are:

<Null>	The Generator splits the prompt by replacing the white space nearest the center of the prompt by a new line (the white space is one or more space characters).
ASCII character	The Generator splits the prompt by replacing the first occurrence of this character by a new-line. If no such character is found in the prompt, the prompt is not split. If the prompt is not split, the first occurrence of this character is replaced by a space.  Do not use the & character if you intend to allocate your own mnemonics to data entry controls.


Display lookup item in List of Values (ITMDLV)

Related Topics

Default:	Display Property
Values:	Yes, No, Display Property
Levels:	Item

Use this preference to specify whether an item is displayed in a LOV. If this preference is not set, the Display? property of the item is used.

These values are:

Display Property	The value of the Display? property for this item is used.
Yes	Display this item in an LOV.
No	Do not display this item in an LOV.


List of values button placement preferences

Related Topics

These preferences act together to determine how list of values buttons are to be placed.

List of values button alignment (LOVBAL)

Default:	Center
Values:	Center, Top, Bottom
Levels:	Container, module

Use this preference to specify the vertical alignment of a control and the control's list of values button.

These values are:

Center	Align the center of the control and the button.
Top	Align the top of the control and the button.
Bottom	Align the bottom of the control and the button.
List of values control/button gap (LOVITG)

Default:	0
Values:	0 to 10
Levels:	Container, module

Use this preference to specify the gap (in grid units) between the control and the control's list of values button.


Radio group button placement preferences

Related Topics

These preferences act together to determine how the buttons within radio groups are to be placed. The property Display Type determines whether the radio buttons are displayed horizontally or vertically.

Radio group horizontal inter-button spacing (RADHIS)

Default:	2
Values:	0 to 99
Levels:	Container, module

Use this preference to specify the minimum gap (in grid units) between buttons in a horizontally-oriented radio group.

Note:	This preference has no effect when the radio buttons are laid out vertically, i.e. the Display Type property is set to Radio Group (Down)

Radio group buttons per line (RADMLF)

Default:	Wrap
Values:	1 to 10, Wrap
Levels:	Container, module

Use this preference to specify how many radio buttons will be positioned on each line in a horizontally-oriented radio group.

These values are:

1 to 10	1 to 10 fields per line  No more than the number of radio buttons specified by this preference are placed on any one line. If set to 1, this has the same effect as specifying a vertical layout for the radio button group. If set to 2, the buttons are laid out in a rectangular array.
Wrap	Keep adding fields as long as they fit No restriction is placed on the number of radio buttons placed on a line.
Note:	This preference has no effect when the radio buttons are laid out vertically, i.e. the Display Type property is set to Radio Group (Down)

Radio group vertical inter-button spacing (RADVIS)

Default:	0
Values:	0 to 9
Levels:	Container, module

Use this preference to specify the space (in grid units) between buttons in a vertically oriented radio group.

Note:	This preference has no effect when the radio buttons are laid out horizontally, i.e. the Display Type property is set to Radio Group (Across)


Default text control display length preferences

Related Topics

If a text style control (such as TextBox) is generated and no Width is defined against the item, one of these preferences determines the default display length, according to the datatype of the underlying column.

Text control default character length (TXTDCL)

Default:	30
Values:	1 to 255
Levels:	Container, module

Use this preference to specify the length of text controls based on character columns if no Width is set against the item.

Text control default date length (TXTDDL)

Default:	9
Values:	1 to 250
Levels:	Container, module

Use this preference to specify the length for text controls based on date columns if no Width is set against the item.

Text control default numeric length (TXTDNL)

Default:	8
Values:	1 to 100
Levels:	Container, module

Use this preference to specify the length for numeric controls based on number columns if no Width is set against the item.


Control group placement preferences

Related Topics

These preferences act together to determine how the controls within a control group are placed.

Note:	Control group preferences DO NOT effect the layout of stacked control groups. Stacked groups inherit the layout characteristics of the zone.

Control group multi-line format (GRPMLF)

Default:	Wrap
Values:	1 to 10, Wrap
Levels:	Container, module

Use this preference to specify the number of controls to be positioned on each line in a horizontally-oriented control group. This preference has no effect when the Control group orientation within group (GRPOWG) preference is set to Vertical Layout.

These values are:

1 to 10	1 to 10 fields per line  No more than the number of controls specified by this preference are placed on any one line.
Wrap	Keep adding fields as long as they fit  No restriction is placed on the number of controls that can be placed on a line.
Control group horizontal inter-control spacing (GRPHIS)

Default:	2
Values:	0 to 99
Levels:	Container, module

Use this preference to specify the space (in grid units) between controls in a horizontally-oriented control group. This preference has no effect when the Control group orientation within group (GRPOWG) preference is set to Vertical Layout.

Use group tabulation table (GRPUTT)

Default:	<Null>
Values:	ED, EP, SD, SP, <Null>
Levels:	Container, module

Use this preference to specify the alignment of controls in a vertically-oriented control group, where there is only ever one control per line. This preference has no effect when the Control group orientation within group (GRPOWG) preference is set to Horizontal Layout.

The ED and SD alignments can be used to increase the overall width of the control group. However, if this makes the control group too wide for the available width, the Generator uses the EP or SP alignments to position the controls appropriately.

These values are:

<Null>	No alignment option set.
ED	Use tabs to align the end of the controls.
EP	Use tabs to align the end of the post-prompts.  If EP is specified and there are no post-prompts, the effect is the same as for ED.
SD	Use tabs to align the start of the controls.
SP	Use tabs to align the start of the prompts.
Control group vertical inter-control spacing (GRPVIS)

Default:	0
Values:	0 to 9
Levels:	Container, module

Use this preference to specify the space (in grid units) between controls within a control group.


Alignment preferences

Related Topics

These preferences are used to influence the alignment of controls within a zone.

Alignment of controls within zone (BLKLYS)

Default:	Fill
Values:	Center, Fill, <Null>
Levels:	Container, module

Use this preference to determine how controls are centered within a zone.

If this preference is set to <Null>, controls are not centered within a zone. If tabulation stops are used to position controls, this preference has no effect; see Use zone tabulation table (BLKUTT) preference.

These values are:

Center	Centers each line within the width of the longest line in the zone.
Fill	Each line is left- and right-justified within the width of the longest line in the zone. The positioning of single controls is determined by the ITMSFJ preference setting.
<Null>	Controls are not centered.
Alignment of single control lines when BLKLYS is set to FILL (ITMSFJ)

Default:	Left
Values:	Left, Center, Right
Levels:	Container, module

Use this preference to specify where to place a single control on a line. This preference takes effect only when the BLKLYS preference is set to FILL.

This preference is also used to position a single control that is displayed between two tall controls or between the margin and a tall control.

These values are:

Left	Left-align single controls with the longest line.
Centered	Center-align single controls within the longest line.
Right	Right-align single controls with the longest line.


Wrapping preferences

Related Topics

These preferences are used to control the way that controls are wrapped.

Zone vertical fill (BLKVFL)

Default:	No
Values:	Yes, No
Levels:	Container, module
Examples:

Use this preference to specify whether or not the Generator uses the space available below vertically short controls that are adjacent to tall controls. If this preference is set to Yes, it overrides the Number of controls per line (BLKMLF) preference and is equivalent to setting BLKMLF to Wrap.

These values are:

Yes	Vertical space below short controls is used if they are adjacent to tall controls.
No	Prevents the Generator from using any space below short controls.
Number of controls per line (BLKMLF)

Default:	Wrap
Values:	1 to 10, Wrap
Levels:	Container, module
Examples:

Use this preference to specify the number of controls that are placed on each line in a zone.

This preference is overridden when:

•	Zone vertical fill (BLKVFL) preference is set to Yes.

•	Use zone tabulation table (BLKUTT) preference is set to Yes. In this case the number of tabs specified by the Zone tabulation table (BLKTAB) preference represents the maximum number of controls that can be placed on any one line.

These values are:

1 to 10	1 to 10 fields per line. No more than the number of controls specified by this preference are placed on any one line.
Wrap	Keep adding fields as long as they fit No restriction is placed on the number of controls that can be placed on a line.


Vertical space separating controls (BLKMLL)

Related Topics

Default:	1
Values:	0 to 9
Levels:	Container, module

Use this preference to specify the amount of vertical space (in grid units) used to separate lines of controls in a zone where the record wraps onto more than one line.

If set to 0, the Generator minimizes the amount of vertical space used in the generated zone.


Tabulation preferences

Related Topics

These preferences determine how tabulation stops are used to position controls and prompts when they wrap over more than one line.

Use zone tabulation table ? (BLKUTT)

Default:	<Null>
Values:	ED, EP, SD, SP, <Null>
Levels:	Container, module

Use this preference to specify whether or not the Generator uses tab stops to position controls and prompts when they wrap over more than one line. Tab stops are set by the Zone tabulation table (BLKTAB) preference.

If this preference is <Null>, tab stops are not used and the BLKTAB preference is ignored.

When tab stops are used, the gap between prompt and control is specified by the Prompt/control gap (ITMPIG) preference. The minimum gap between a control and the next prompt is as specified by the Control/prompt gap (ITMIPG) preference. If this minimum gap is greater than the distance to the next tab stop, then the tab stop after the next tab stop will be used.

If EP is specified and there is no post-prompt, then the effect is the same as for ED.

Note:	If a single control cannot fit in the available space, the control is truncated to fit. If you have asked for controls to be aligned to tab stops, this is done, even if it means truncating the controls.

These values are:

ED	Use tab stops to align the end of the controls.
EP	Use tab stops to align the end of the post-prompts.
SD	Use tab stops to align the start of the controls.
SP	Use tab stops to align the start of the prompts.
<Null>	No tab stop option set
Zone tabulation table (BLKTAB)

Default:	2.20.42.60
Values:	Up to 80 characters
Levels:	Container, module

Use this preference to specify the tab stops that are used to place controls and their prompts when they wrap over more than one line. The tab stops must be in ascending order and be separated by periods. The values are in grid units.

This preference has no effect if the Use zone tabulation table ? (BLKUTT) preference is set to <Null>.


Library (standard inclusions) project (MGPROJ)

Related Topics

Default:	"Library inclusions for VB5/6"
Values:	Up to 255 characters
Levels:	Container, module

Use this preference to specify the name of the Visual Basic project file (.vbp) that defines the library forms and basic module files (standard inclusions) needed in the generated project, but which are not generated. This project contains the database logon form, list of values form, and other general purpose forms and routines.

If you specify Repository as the Source option on the Visual Basic Generator Options dialog box, Visual Basic Generator searches for the project file in the repository folders specified in the Repository Folders field on the Visual Basic Generator Options dialog box.

If you specify File System as the Source option on the Visual Basic Generator Options dialog box, include the full path of the Visual Basic project file. If only a partial pathname is specified, the location is relative to the Generator's installation directory and this is defined in the CGENV61 entry in the registry.

The value can be one of:

"Library inclusions for VB5/6"	This is the default, and it means that one of the default library projects are used, that is: - Oracle Objects for OLE uses cvb5vblib/incl.vbp - Visual Basic Data Access Objects uses cvb5vblib/incldao.vbp
Any valid pathname	If you are using your own library inclusions, enter the pathname here. You can enter a partial pathname relative to the installation directory. This is defined in the CGENV61 registry key
<Null>	Oracle Designer Visual Basic Generator is no longer certified against VB4, and we recommend that you generate Visual Basic applications for VB5 or VB6. However, if you want to generate VB4 applications, you must set this preference to <Null>, or to the path of your VB4 project, if you have created one. About


Template menu preferences

Related Topics

These preferences determine which menu controls (in the CGTWFirst template window in <tmpt.vbp>) are used to place navigation and custom action items. If all generated menu items are to be placed on a single menu, these preferences must all be the same.

Template menu to locate module network entries (TFMNMN)

Default:	mnuNavigate
Values:	A valid menu control name
Levels:	Container, module

Use this preference to specify the menu control where menu items for calling other modules are placed.

No menus (only buttons) are generated for modules called from launch screen windows and therefore this preference will not apply.

Note:	This preference does not concern menu items involved in zone coordination. This is dealt with by the Template menu to locate menu items to open detail forms (TFMNZC) preference.

Template menu to locate menu items to open detail forms (TFMNZC)

Default:	mnuNavigate
Values:	A valid menu control name
Levels:	Container, module

Use this preference to specify the menu control where menu items for navigating to detail zones on a separate window are placed.

Template menu to locate custom action items (TFMNCA)

Default:	mnuNavigate
Values:	A valid menu control name
Levels:	Container, module

Use this preference to specify the menu control that indicates where to place menu items generated for custom action items.


Template project (TFPROJ)

Related Topics

Default:	cvbt5mpt1\tmpt.vbp
Values:	Up to 255 characters
Levels:	Container, module

Use this preference to specify the name of the Visual Basic project file (.vbp) that defines the template forms. These define the look and feel of the objects that are generated, such as controls, frames etc.

If you specify Repository as the Source option on the Visual Basic Generator Options dialog box, Visual Basic Generator searches for the project file in the repository folders specified in the Repository Folders field on the Visual Basic Generator Options dialog box.

If you specify File System as the Source option on the Visual Basic Generator Options dialog box, include the full path of the Visual Basic project file. If only a partial pathname is specified, the location is relative to the Generator's installation directory and this is defined in the CGENV61 entry in the registry.

Note:	Oracle Designer Visual Basic Generator is no longer certified against VB4, and we recommend that you generate Visual Basic applications for VB5 or VB6. However, if you want to generate VB4 applications, you must set this preference to cvbtmpt1\tmpt.vbp. About


Repository module properties used by Visual Basic Generator

Use Design Editor to set these properties. How

Module property	Use by Visual Basic Generator	Notes and related topics
Short Name	Mandatory, 20 characters Used to name generated files if the Implementation Name is not defined. In this context the name is limited by any filename length restriction. The Short Name may also be incorporated in the CGTWLaunch template window as a static caption.	CGTWLaunch Visual Basic template form
Purpose	Mandatory, 70 characters The purpose or short description for documentation purposes.
Language	Mandatory Defines that the language of the module is Visual Basic.
Module Type	Optional Visual Basic Generator only processes modules if the type is <null> or MENU  The generation of LIBRARY modules are not supported in release 2 onwards.
Implementation Name	Optional, 30 characters Used to name files generated from this module. If the Implementation Name is omitted the Short Name is used instead. If you have set a length restriction for generated files, ensure this value does not exceed the maximum length allowed, otherwise generation will be unsuccessful e.g. for 16 bit applications this property must not exceed 6 characters in length.
Display
Top Title	Optional, 70 characters In the absence of a Window Title, this defines the default title of the first (main) window generated from this module.  For a module with no module components, it is used for the default banner caption in the CGTWLaunch template form.	CGTWLaunch Visual Basic template form
Short Title	Optional, 70 characters The default title for buttons and menus (action items) that are used to navigate to this module. The Short Title may also be incorporated in the CGTWLaunch template form as a static caption.	CGTWLaunch Visual Basic template form
Command Line	Optional, 100 characters The command used to invoke this module. For example, you could call a form modally rather than non-modally by entering the following command: <formname>.show vbmodal Typically the Command Line does not need to be defined as the Generator determines the appropriate command to use when linking modules.
Help
User/Help Text	Optional  Help text for the module. A Windows Help file can be generated for the Visual Basic application. Text for the module normally serves to introduce the module. If this is the top-level module for your application, this text will be displayed on the Contents topic of the generated MS Help file.	About Help files for generated Visual Basic applications
Help File Name	Optional, 100 characters The name of the compiled Help file (.HLP) created for this module and its associated module network. Only specify this property against the top-level module for the Help file.
Help Graphic File Name	Optional, 60 characters The name and file extension of the graphic file used to illustrate the module topic.
Help Context ID Prefix	Optional, 3 digits Used to generate unique context IDs for the module. This value must be unique for each module to be included in a Help file.
Module Network
Menu Items	Optional Determines which modules are called by the current menu module.  The order of the modules in the list determine the order in which they appear in the generated application.


Repository window properties used by Visual Basic Generator

Use Design Editor to set these properties. How

Window property	Use by Visual Basic Generator	Notes and related topics
Name	Mandatory The window name. This property is not used during generation.	About windows and zones in Visual Basic applications
Title	Optional, 240 characters The title of the generated window.
Template/Library Object	Optional, 30 characters The name of a custom Visual Basic template window that the generated window is to be based on. This template must exist in the template project, otherwise there will be an error during generation. If omitted, the default template form is used.	About template Visual Basic projects


Repository module component properties used by Visual Basic Generator

Use Design Editor to set these properties. How

Module component property	Use by Visual Basic Generator	Notes and related topics
Name	Mandatory Used to name generated objects for the zone.  The name must be unique for all components within the module. The name must not exceed 10 characters in length.	About windows and zones in Visual Basic applications
Language	Mandatory  Defines that the language of the module component is Visual Basic.  Multi-language module components are not supported by Visual Basic Generator.
Display
Title	Optional, 70 characters The default title for the zone. If the generated zone is enclosed within a frame control, this specifies the frame caption.  This text may also be used in user messages and on navigation buttons that may be generated to link to this zone from a different window.  When a new module components is created, the title defaults to the display title held against the underlying table.	About windows and zones
Template/Library Object	Optional, 30 characters The name of a custom zone template that the generated zone will be based on. This template must exist in the template project, otherwise there will be an error during generation. If omitted, the default template form for the given Layout Style is used.	About template Visual Basic projects Overriding the default zone appearance
Layout Style	Optional The overall layout of the zone in the generated Visual Basic application. Valid options are Context, Form, List and List/Form.	About zone layout styles
Placement	Optional Indicates whether this detail zone is included in the stacking area of the master zone. Valid options are Stacked and <Null> (unstacked).	About stacking areas in Visual Basic applications
Operations
Insert?	Determines whether records can be added using this zone.
Update?	Determines whether records can be updated using this zone.
Delete?	Determines whether records can be deleted using this zone.
Query
Query?	Determines whether QUERY operations are allowed using this zone.	About Query dialogs in Visual Basic applications
Autoquery?	For masterless module components this determines whether the zone is queried automatically on startup (Yes) or when the user selects the query button (No). If this is a detail module component, this determines whether or not the detail zone is automatically queried when the master record changes. If this property is set to Default Behavior, Visual Basic Generator checks whether there is a Query dialog associated with the zone i.e. one or more items are marked Query. If it does not have a Query dialog, the zone is automatically queried.
Data
Datasource Type	Mandatory, 16 characters  Visual Basic applications display data sourced from a QUERY.
Datatarget Type	Mandatory, 16 characters  Visual Basic applications write data to TABLES.
Help
User/Help Text	Optional  Help text for the zone. A Windows Help file can be generated for the Visual Basic application.	About Help files for generated Visual Basic applications
Help Context ID Prefix	Optional, 3 digits Used to generate unique context IDs for reusable module components. This value must be unique for all reusable module components included in a Help file.


Repository table usage properties used by Visual Basic Generator

Use Design Editor to set these properties. How

Table usage property	Use by Visual Basic Generator	Notes and related topics
Usage Alias	Mandatory, 30 characters Used to alias the table name within the FROM clause of generated SQL statements.
Name in Database	Optional, 100 characters The name to be used by Generators instead of the table/view/materialized view name (OWNER.TABLE) within the FROM clause of generated queries. For example EMP@NEWYORK. This name is used without any user/schema prefix, regardless of the preference settings (TABOWN). A suggestion list displays the Global Synonym Names for all implementations of the relation but free-format text may also be entered.	Table owner for use in SQL (TABOWN) preference
Usage Type	Optional Identifies whether the table usage is a base or lookup table usage within the module component.	About windows and zones in Visual Basic applications
Where
WHERE Clause of Query	Optional A SQL WHERE condition to be applied to the SELECT statement used to query the zone's records.  Use this property to restrict the records displayed within the particular zone.	Defining a restrictive WHERE condition
Select Distinct	Optional Indicates whether to add DISTINCT to the query when generating LOVs and zones.	Defining a restrictive WHERE condition
Lookup
Validation WHERE Clause	Optional A SQL condition to perform foreign key validation and restricts records displayed within the lookup LOV.


Repository item group properties used by Visual Basic Generator

Use Design Editor to set these properties. How

Item group property	Use by Visual Basic Generator	Notes and related topics
Name	Mandatory, 30 characters A name for the item group.	About control groups in Visual Basic applications
Display
Prompt	Optional, 130 characters The caption for the frame control generated for the item group.
Template/Library Object	Optional, 30 characters The name of a custom frame template that the generated frame will be based on. This must exist in the template project, otherwise there will be an error during generation. If omitted, the default control group is used (CGTGMainGroup). Note: If the item group is stacked, the custom template property has no effect.	About template Visual Basic projects CGTGMainGroup Visual Basic template form
Orientation	The orientation of the item group can be either Horizontal or Vertical. Select Horizontal to lay out the item groups side by side. If the item does not fit the available width, it is wrapped to the next line. You can specify the distance between them using GRPHIS.  Select Vertical to lay out the item groups one below the other. You can specify the vertical space between lines using GRPVIS.	Customizing control group layout
Stacked?	Indicates that the item group is to form part of the zone's stacking area. The Use tab control for stacking areas (USETAB) preference determines whether the item group is implemented using an SSTab Control or a radio group.	About stacking areas in Visual Basic applications Use tab control for stacking areas (USETAB) preference
Help
User/Help Text	Optional Help text for the item group. A Windows Help file can be generated for the Visual Basic application.	About Help files for generated Visual Basic applications


Repository item properties used by Visual Basic Generator

Use Design Editor to set these properties. How

Item property	Use by Visual Basic Generator	Notes and related topics
Column	Mandatory The name of the underlying column on which the generated item is based.
Name	Mandatory, 30 characters  Used as the base name for generated controls.  It must be 30 characters or less and be unique across all items within the module component.
Unbound Type	(Unbound items only)  Visual Basic Generator supports 'Custom' unbound items only.	About unbound items in Visual Basic applications
Maximum Length	(Unbound items only)  If greater than 255, used to set the Query Length of generated items.
Operations
Insert?	Indicates whether the user can enter a value into this control when a new record is being created. It should be unchecked (No) if the control value is to be generated automatically.
Update?	Indicates whether the user is allowed to update this control's value when updating an existing record.
Query		About Query dialogs
Query?	Indicates whether this control is displayed on the zone's Query dialog. If unchecked (No), this control does not appear on the Query dialog. For Context zones an LOV dialog is displayed and a simple query reduction criteria dialog is displayed for the first item whose Query property is checked (Yes).
Range Search	Mandatory Determines whether range searching is allowed for the item. By default, Visual Basic Generator creates a pair of To/From for items based on DATE and non-key NUMERIC columns.
Display
Display?	Indicates whether the generated control is displayed in the zone.  If set to No, a control is created in the top-left corner of its container frame or form, but with its Visible property set to False.
Prompt	Optional, 130 characters The prompt (or caption) for the generated control.  Prompts may be split into two portions that appear before and after the control. Preferences determines how prompt splitting operates and also where prompts are to be placed relative to their control. To define a particular mnemonic character for a control, enter a single & character immediately before the letter you require.	About prompt/control layout About splitting control prompts About mnemonic access keys for controls
Display Type	Optional, 20 characters  The control style associated with the generated item.  The actual (standard) control used depends on the Control Type Mapping preferences.	About the control definition file Control type mapping preferences
Show Meaning?	Optional Indicates whether the Value or Meaning properties of allowable values are displayed for the item. If set to <Null> the allowable value is displayed in the generated application. If set to 'Meaning Only' the Meaning is displayed. Visual Basic Generator does not support the 'Meaning alongside code' option.	About allowable control values
Template /Library Object	Optional, 30 characters  The name of a custom (non-standard) control that the generated control will be based on. This must exist in the template project and the control definition file, otherwise there will be an error during generation. If omitted, the default control style is used, as defined by the Control Type Mapping preferences.	About template Visual Basic projects CGTCControls Visual Basic template form  About the control definition file
Width	Optional, 5 digits  The width of text fields, specified in characters. Visual Basic Generator computes the width required for the control by multiplying this value out by the average character cell width of the font, and adding in an overhead for the left and right margins, as defined by the LayoutWidthOverhead setting in the control definition file. Note: This property has no effect for 'Checkboxes' and 'Radio Groups'. If this property is undefined, the Default text control display length preference values are used instead.	About the control definition file Default text control display length preferences
Height	Optional, 6 digits  The number of lines to display in a generated text field or text list. Visual Basic Generator computes the height required for the control by taking the height of the template control, and then adding in the average font height for each extra line. Note: This property has no effect for Pop List, Check Box and Radio Group style controls.
Alignment	Optional The horizontal alignment of the value within a text field.
Format Mask	Optional, 60 characters Not used by Visual Basic Generator  The FormatProp setting in the control definition file defines the format used.	About the control definition file
Item Group	Optional Identifies the item group in which this item is to be placed. The value set here is used to determine the setting of the control's Alignment property in the generated application, as specified by the TextAlignmentProp setting in the control definition file.	About control groups in Visual Basic applications About the control definition file
Context?	Indicates whether this item is displayed in the record list box generated for List, List/Form and Form zones.  In a Context zone this property indicates whether the item is displayed in the main window. If no context items are selected for the module component the Primary Key columns are used instead, together with any columns which are marked as 'descriptors' within the column definition (Descriptor Sequence).	About record list boxes  About zone layout styles
Definition
Domain	Optional  (Unbound items only) The name of a domain to be associated with this unbound item. If specified, the allowed values are derived from the domain definition.	About allowable control values
Default Value	Optional, 60 characters  The default value used to populate the control when a new record is created. You can enter AutoGen types if you wish, for example DATETIME. These values are not case sensitive but you must add $$ before and after the AutoGen keyword. For example, $$DATETIME$$.	About default control values
Default Value Type	Indicates whether the default value is a literal string or a function call.  When this is set to Literal, the literal string is returned. For example, if the Default Value is set to $$DATETIME$$ and the Default Value Type is set to Literal, then the value returned is the string "$$DATETIME$$". To return a date value, set this property to either Database Function Call or Client Function Call.	About default control values
Optional?	Indicates whether validation code is generated to ensure that the user provides values for these controls when creating or updating records.	About validation code
Ordering
Order By Sequence	Optional, 6 digits The Sequence number defines the position within the ORDER BY.
Sort Order	Optional Indicates whether records are displayed in an ascending, or descending order.
Help
Hint	Optional, 132 characters  Hint text may be displayed via 'Tool Tip' style popup captions, depending on preference settings and runtime options.	About hint text for controls
User/Help Text	Optional  Help text for the item. A Windows Help file can be generated for the Visual Basic application.	About Help files for generated Visual Basic applications


Repository action item properties used by Visual Basic Generator

Use Design Editor to set these properties. How

Action Item property	Use by Visual Basic Generator	Notes and related topics
Module Component	The name of the module component that contains this action item.
Name	Mandatory, 30 characters A unique name for the action item. Visual Basic Generator supports Navigation, Custom and Generator action items.	About action items in Visual Basic applications
Usage Sequence	Optional, 6 digits  The order in which all action items in the same window are displayed.
Enable on database record?	(Custom action items only) Indicates whether the custom action item should only be active (or enabled) when a record is displayed (Yes).
Generator Item Type	(Generator action items only) Indicates the standard functionality the action item is to invoke, e.g. Delete record, New Record etc.
Navigate To
To Module Component	Mandatory Identifies the module component (zone) this navigation action item navigates to in the generated application.
To Module	Mandatory Identifies the module this navigation action item navigates to in the generated application.
Display
Template/Library Object	Optional, 30 characters The name of a custom action item control that the generated control will be based on. This must exist in the template project and the control definition file, otherwise there will be an error during generation. If omitted, the default control style is used. Note: If the Create Button? property for the action item group is set to No, the custom template property has no effect.	About template Visual Basic projects CGTCControls Visual Basic template form  About the control definition file
Prompt	Optional, 130 characters The caption or label to appear on the control (or menu item) generated from this action item.
Create Button?	Indicates whether the action item is implemented as a button. Note: Buttons are always created for Generator action items.
Create Menu Item?	(Navigation and custom action items only) Indicates whether the action item is implemented as a menu item. Preferences determine which menu item is used. Note: You cannot generate menu items from Generator action items or Module Navigation action items on a launch screen.	Template menu preferences


Visual Basic Generator templates

Related Topics

The tmpt.vbp template project contains a standard set of template forms that define the look and feel of generated forms and controls. You can also create (or customize) your own template forms by taking a copy of the shipped set and amending the new versions. How

Two template projects are provided; these are held in the file system under <oracle_home>\cgenv61, in the template directories cvb5tmpt1 and cvb5tmpt2. Templates that are common across both projects are held in the cvb5tmptc directory. The Template Project (TFPROJ) preference specifies the template project.

Note:	If you are generating applications for VB4, you need to use templates in different directories. See Using Visual Basic Version 4.0

The complete set of shipped template forms is:

Template Controls (\cvb5tmptc template directory):

CGTCControls	Defines the look and feel of data entry controls and buttons.
Template Windows (not in common \ cvb5tmptc template directory):

CGTWLaunch	Applies only to modules with no module components. Defines the look and feel of launch screens in a generated module network.
CGTWMDIParent	If present in the template project, this causes the generation of an MDI application. Defines the look and feel of the MDI parent window.
CGTWFirst	Applies only to modules with module components. Defines the look and feel of the first form (window) in each generated module.
CGTWOthers	Defines the look and feel of the second and subsequent forms in each generated module.
Template Windows (\cvb5tmptc template directory):

CGTWPsd	Defines the look and feel of a property sheet dialog.
CGTWQd	Defines the look and feel of a query dialog.
Template Zones (\cvb5tmptc template directory):

CGTZContextDefault	Defines the look and feel of a Context zone.
CGTZFormDefault	Defines the look and feel of a Form zone.
CGTZListFormDefault	Defines the look and feel of a List/Form zone.
CGTZListDefault	Defines the look and feel of a List zone.
CGTZListCombo	An alternative List zone template that uses a combo box instead of a list box so that only one row is visible.
CGTZUnboundDefault	Defines the look and feel of an unbound module component.
Template Groups (\cvb5tmptc template directory):

CGTGMainGroup	Defines the look and feel of the frame that encloses a control group.
CGTGStackSelector	Defines the radio group or tab control used to implement a stacking area.
CGTGStackedGroup	Where a radio group is used to implement a stacking area, this defines the look and feel of the frames that enclose stacked control groups and stacked detail zones.
Note:	The TMPTCLR.VBP template project contains a different version of the template controls form. This provides different colored controls, depending on the characteristics of the generated controls.


CGTCControls Visual Basic template form

Related Topics

The CGTCControls template form contains a sample of each of the control types to be used in a generated application.

Data Entry Controls and Captions:

During generation, each item is allocated the name of a control. The control must exist in this controls template form and this is known as the <basename> version of the control.

There may be other versions of the same control type which can provide a different look and feel according to how the control is used. These other versions are also defined in this template:

Name	Optional?	How Control is Used
<basename>	N	The base version of the control, named after the control type; for example: TextBox, ListBox, Frame, and so on.
<basename>Mand	Y	Used where the control is enterable and mandatory. If omitted, the <basename> version is used.
<basename>RO	Y	Used if the control is read-only. If omitted, the <basename> version is used.
<basename>QD	Y	Used where the control appears in a query dialog. If omitted, the <basename> version is used.
DfltCaption	N	Defines the appearance of captions for those controls that do not have an integrated caption property.
DfltCaptionMand	N	Defines the appearance of captions for mandatory controls.
DfltCaptionRO	N	Defines the appearance of captions for read-only controls.
DfltCaptionQD	Y	Defines the appearance of captions for controls in a query dialog.
Button Bar Buttons:

Name	Optional?	How Control is Used
CG_BB_DEL	N	Button to delete the current record in the zone.
CG_BB_INS	N	Button to enter a new record in the zone.
CG_BB_QRY	N	Button to query records within the zone.
CG_BB_UPD	N	Button to bring up the property sheet dialog to view/update the current record.
CG_BB_SAVE	N	Button to save changes to the current record.
CG_BB_UNDO	N	Button to undo changes to the current record.
CG_BB_RESEQ_UP	N	Button to resequence current record before the previous record.
CG_BB_RESEQ_DOWN	N	Button to resequence current record after the next record.
CG_BB_ZC	N	Button to navigate to a related zone located on a different window.
CG_BB_WINDOW	N	Button to navigate to a form on another window.
Other Controls:

Name	Optional?	How Control is Used
CG_HINT_TEXT	N	Defines the appearance of the tooltip captions. If one or both of the Hint text preferences are set to Yes. In this case, it is mandatory.
ContextZoneControl	N	Defines the appearance of controls created in a Context zone.
ContextZoneLabel	N	Defines the captions for controls created in a Context zone.
LOVBUT	Y	Defines the appearance of buttons placed next to data entry controls to invoke the control's LOV. If omitted, no LOV buttons will be generated.
You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions.  How


CGTWLaunch Visual Basic template form

Related Topics

The CGTWLaunch template form applies only to modules with no module components. It defines the look and feel of launch screens in a generated module network. A placeholder menu item (mnuNavigate) is provided in this template, to the right of the File menu option, where calls to menu items will be embedded by default, if the Template menu preferences have not been set.

The controls defined in this template are:

Name	Optional?	How Control is Used
CG_BUTTON_BAR	N	Defines the positioning of the buttons.
CG_BB_START CG_BB_NEXT	N N	The position of these controls relative to each other defines the inter-button gap, and whether buttons within the button bar are laid out horizontally or vertically. The size of these two shapes is not significant.
CG_LAYOUT_AREA	N	Not currently used.
The captions of the form itself, plus label style controls, may be set to specific keyword values to indicate that they should be substituted during generation to values derived from repository design properties. The keywords currently supported are:

Caption	Optional?	How Control is Used
CG$AN	Y	The repository application system's Name property.
CG$MS	Y	The module Short Name, derived from the mandatory Short Name property.
CG$M1	Y	The module Top Title, derived from the optional Top Title property. If this property is not defined, the caption of the generated control is also blank.
CG$MT	Y	The module Short Title, derived from the optional Short title property. If this property is not defined, the caption of the generated control is also blank.
You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTWMDIParent Visual Basic template form

Related Topics

The CGTWMDIParent template form defines the look and feel of the MDI parent window which will contain all the generated windows when the application is run. It must be defined as an MDI Parent form.

If this form is missing from the template project, no MDI Parent form is added to the generated project. Hence, at runtime, the application will be presented as a set of independent windows.

The controls defined in this template are:

Name	Optional?	How Control is Used
mnuFile	Y	Top-level menu item, containing the Exit option.
mnuExit	Y	Unloads the form and ends the Visual Basic session.
picStatusBar pnlDate pnlUser	Y Y Y	These controls provide a status bar at the bottom of the main MDI parent window to display the current date and user. The status bar may be hidden at runtime via a view menu option defined on the other template windows CGTWFirst and CGTWOthers.
You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTWFirst Visual Basic template form

Related Topics

The CGTWFirst template form applies only to modules with module components. Defines the look and feel of the first form (window) in each generated module.

The controls defined in this template are:

Name	Optional?	How Control is Used
CG_LAYOUT_AREA	N	Defines the size of the margins around the generated controls.
mnuFile	Y	Top-level menu item, containing the Exit option.
mnuExit	Y	Exits the form or application, depending on the Startup Form option given in the Generate Visual Basic dialog.
mnuEdit	Y	Top-level menu item, containing the Cut, Copy, and Paste options.
mnuCopy	Y	Copies selected text.
mnuCut	Y	Cuts selected text.
mnuPaste	Y	Pastes data from the clipboard to the selected control.
mnuView	Y	Top-level menu item, containing the Status Bar option.
mnuOptions	Y	Displays the runtime options dialog.
mnuNavigate	Y	Top-level menu item, to which the Generator may add navigation options during generation (Template menu preferences).
mnuWindow	Y	Top-level menu item, to provide standard Windows menu i.e. allows you to navigate between windows that are currently open.
mnuHelp	Y	Top-level menu item, containing the About, Search Index, and Contents options.
mnuStatusBar	Y	Displays or hides the status bar.
mnuAbout	Y	Displays the About box.
picStatusBar	Y	Contains the date and user panels.
pnlDate	Y	Displays the date in the status bar.
pnlUser	Y	Displays the user connection string in the status bar.
There are different versions of this form, depending on whether you are generating a project with an MDI Parent (tmpt.vbp) or without (tmpt2.vbp). The MDI version has no status bar, but has an additional mnuWindow menu item.

Note:	The size of this template form determines the maximum allowed size of the first form in the module. The size of the generated window can be smaller than the maximum size, and will be sized accordingly to fit the controls.

You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTWOthers Visual Basic template form

Related Topics

The CGTWOthers template form defines the look and feel of the second and subsequent forms in the generated module. The controls defined in this template are:

Name	Optional?	How Control is Used
CG_LAYOUT_AREA	N	Defines the size of the margins around the generated controls.
CG_BUTTON_BAR	N	Defines the positioning of the buttons.
CG_BB_START CG_BB_NEXT	N N	The position of these controls relative to each other defines the inter-button gap, and whether buttons within the button bar are laid out horizontally or vertically. The size of these two shapes is not significant.
The version of this form in the MDI template project tmpt.vbp contains a template menu similar to the one defined in CGTWFirst.

Note:	The size of this template form determines the maximum allowed size of the second and subsequent forms. The size of the generated window can be smaller than the maximum size, and will be sized accordingly to fit the controls.

You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTWPsd Visual Basic template form

Related Topics

The CGTWPsd template form defines the look and feel of a generated property sheet dialog. The controls to be defined in this template are:

Name	Tag	Optional?	How Control is Used
CG_LAYOUT_AREA	n/a	N	Defines the size of the margins around the generated controls.
any	CG_PSD_OK	N	Copied into the generated window if Insert/Update is allowed. Code generated onto the button carries out the required database action and dismisses the dialog.
any	CG_PSD_CANCEL	N	Copied into the generated window if Insert/Update is allowed. Code generated onto the button dismisses the dialog without any action.
any	CG_PSD_UNDO	Y	Copied into the generated window if Insert/Update is allowed. Code generated onto the button undoes any changes made and reverts the state to the way it was when the dialog opened.
any	CG_PSD_CLOSE	N	Copied into the generated window if Query is allowed but Update is not allowed. Code generated onto the button dismisses the dialog. Note: This button is placed beneath the OK button in the shipped template form.
any	CG_PSD_APPLY	Y	Code generated onto the button carries out the required database action without dismissing the dialog.
Note:	The size of the property sheet dialog template form determines the maximum allowed size of a property sheet window. The size of the generated window can be smaller than the maximum size, and will be sized accordingly to fit the controls.

You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTWQd Visual Basic template form

Related Topics

The CGTWQd template form defines the look and feel of a generated query dialog. The controls defined in this template are:

Name	Tag	Optional?	How Control is Used
CG_LAYOUT_AREA	n/a	N	Defines the size of the margins around the generated controls.
any	CG_QD_OK	N	Code generated onto the button actions the required Query processing. It builds up the WHERE clause required for the given criteria, and dismisses the query dialog, passing control back to the main form.
any	CG_QD_CANCEL	N	Code generated onto the button dismisses the dialog without any action.
any	CG_QD_CLEAR	N	Code generated onto the button clears all controls, setting them to null. User can then enter a new query.
any	CG_QD_NEW	Y	Copied into the generated window if Insert is allowed in the zone. Code generated onto the button dismisses the dialog and notifies the calling code that the user wishes to enter a new record.
Note:	The size of the query dialog template form determines the maximum allowed size of a query dialog window. The size of the generated window can be smaller than the maximum size, and will be sized accordingly to fit the controls.

You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTZContextDefault Visual Basic template form

Related Topics

The CGTZContextDefault template form is used to change the look and feel of any generated Context zone. The controls defined in this template are:

Name	Optional?	How Control is Used
CG_ZONE_FRAME	N	Defines the look and feel of a Context zone's enclosing frame (if generated). Determines the smallest size of any Context zone. Any generated zone will be enlarged horizontally and vertically, as required to fit the controls/buttons.
CG_LAYOUT_AREA CG_BUTTON_BAR	N N	Together, these define the positioning of the zone's controls relative to its buttons.
CG_BB_START CG_BB_NEXT	N N	The position of these controls relative to each other defines the inter-button gap, and whether buttons within the button bar are laid out horizontally or vertically. The size of these two shapes is not significant.
CG_BB_CLR	Y	Button to clear the zone. If omitted, no clear button will be added to the zone.
CG_BB_DEL	Y	Button to delete the current record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_INS	Y	Button to bring up the property sheet dialog to enter a new record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_QRY	Y	Button to bring up the LOV to find an existing record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_UPD	Y	Button to bring up the property sheet dialog to view/update an existing record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_ZC	Y	Button to navigate to a related zone located on a different window. If omitted, the template defined in CGTCControls will be used instead.
You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTZFormDefault Visual Basic template form

Related Topics

The CGTZFormDefault template form is used to change the look and feel of any generated Form zone. The controls defined in this template are:

Name	Tag	Optional?	How Control is Used
CG_ZONE_FRAME	n/a	N	Defines the look and feel of a Form zone's enclosing frame (if generated). Determines the smallest size of any Form zone. Any generated zone will be enlarged horizontally and vertically, as required to fit the controls/buttons.
CG_LAYOUT_AREA CG_BUTTON_BAR	n/a n/a	N N	Together, these define the positioning of the zone's controls relative to its buttons.
CG_BB_START CG_BB_NEXT	n/a n/a	N N	The position of these controls relative to each other defines the inter-button gap, and whether buttons within the button bar are laid out horizontally or vertically. The size of these two shapes is not significant.
any	CG_REC_FIRST	Y	Button to navigate to the first record in the set of queried records.
any	CG_REC_GOTO	Y	Button to navigate to a specific record in the set of queried records.
any	CG_REC_LAST	Y	Button to navigate to the last record in the set of queried records.
any	CG_REC_NEXT	Y	Button to navigate to the next record in the set of queried records.
any	CG_REC_PREV	Y	Button to navigate to the previous record in the set of queried records.
any	CG_REC_STATUS	N	Label to display the current record number and the total number of queried records.
fraGotoRec	n/a	Y	Enclosing frame for the list box displaying the set of queried records.
any	CG_ZN_LIST	N	List box to display, and allow direct navigation to, any record within the set of queried records.
CG_BB_CLR	n/a	Y	Button to clear the zone. If omitted, no clear button will be added to the zone.
CG_BB_DEL	n/a	Y	Button to delete the current record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_INS	n/a	Y	Button to put the zone into 'Add New Record' mode. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_QRY	n/a	Y	Button to perform a new query for the zone. The zone's query dialog is opened, if there is one. If omitted, the template defined in CGTCControls will be used instead.
You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTZListFormDefault Visual Basic template form

Related Topics

The CGTZListFormDefault template form is used to change the look and feel of any generated List/Form zone. The controls defined in this template are:

Name	Tag	Optional?	How Control is Used
CG_ZONE_FRAME	n/a	N	Defines the look and feel of a List/Form zone's enclosing frame (if generated). Defines the smallest size of any List/Form zone. Any generated zone will be enlarged as required to fit the controls/buttons.
CG_LAYOUT_AREA CG_BUTTON_BAR	n/a n/a	N N	Together, these define the positioning of the zone's controls relative to its buttons and list box.
CG_BB_START CG_BB_NEXT	n/a n/a	N N	The position of these controls relative to each other defines the inter-button gap, and whether buttons within the button bar are laid out horizontally or vertically. The size of these two shapes is not significant.
any	CG_ZN_LIST	N	Defines the look and feel of the list box used to display the records.
any	CG_ZN_LISTHDR	Y	Defines the position and appearance of the list box's caption.
any	CG_REC_STATUS	N	Label to display the zone's Record Status.
CG_BB_CLR	n/a	Y	Button to clear the zone. If omitted, no clear button will be added to the zone.
CG_BB_DEL	n/a	Y	Button to delete the current record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_INS	n/a	Y	Button to put the zone into 'Add New Record' mode. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_QRY	n/a	Y	Button to perform a new query for the zone. The zone's query dialog is opened, if there is one. If omitted, the template defined in CGTCControls will be used instead.
You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTZListDefault Visual Basic template form

Related Topics

The CGTZListDefault template form is used to change the look and feel of any generated List zone. The controls defined in this template are:

Name	Tag	Optional?	How Control is Used
CG_ZONE_FRAME	n/a	N	Defines the look and feel of a List zone's enclosing frame (if generated).Defines the smallest size of any List zone. Any generated zone will be enlarged horizontally according to the display length(s) of the column(s) displayed in the list box.
CG_LAYOUT_AREA CG_BUTTON_BAR	n/a n/a	N N	Together, these define the positioning of the zone's embedded details relative to its buttons.
CG_BB_START CG_BB_NEXT	n/a n/a	N N	The position of these controls relative to each other defines the inter-button gap, and whether buttons within the button bar are laid out horizontally or vertically. The size of these two shapes is not significant.
any	CG_ZN_LIST	N	Defines the look and feel of the list box used to display the records.
any	CG_ZN_LISTHDR	Y	Defines the position and appearance of the list box's caption.
any	CG_REC_STATUS	Y	Defines the position and appearance of the zone's Record Status.
CG_BB_CLR	n/a	Y	Button to clear the zone. If omitted, no clear button will be added to the zone.
CG_BB_DEL	n/a	Y	Button to delete the current record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_INS	n/a	Y	Button to bring up the property sheet dialog to enter a new record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_QRY	n/a	Y	Button to execute a query for the zone. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_UPD	n/a	Y	Button to bring up the property sheet dialog to view/update an existing record. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_RESEQ_UP	n/a	Y	Button to resequence the current row above the previous row. If omitted, the template defined in CGTCControls will be used instead.
CG_BB_RESEQ_DOWN	n/a	Y	Button to resequence the current row beneath the next row. If omitted, the template defined in CGTCControls will be used instead.
CGTZListCombo Visual Basic template form

This is an alternative List zone template that uses a combo box instead of a list box so that only one row is visible.

You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTZUnboundDefault Visual Basic template form

Related Topics

The CGTZUnboundDefault template form is used to change the look and feel of a zone that is not bound to any tables i.e. a module component that does not contain any table usages. The controls defined in this template are:

Name	Tag	Optional?	How Control is Used
CG_ZONE_FRAME	n/a	N	Defines the look and feel of an unbound zone.
CG_LAYOUT_AREA CG_BUTTON_BAR	n/a n/a	N N	Together, these define the positioning of the zone details relative to its buttons.
CG_BB_START CG_BB_NEXT	n/a n/a	N N	The position of these controls relative to each other defines the inter-button gap, and whether buttons within the button bar are laid out horizontally or vertically. The size of these two shapes is not significant.
You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions.  How


CGTGMainGroup Visual Basic template form

Related Topics

The CGTGMainGroup template form is used to define the look and feel of the frame that encloses a control group.

The controls defined in this template are:

Name	Optional?	How Control is Used
CG_GROUP_FRAME	N	Defines the look and feel of the frame that encloses a control group.
CG_LAYOUT_AREA	N	Defines the margins around the controls within the control group.
You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTGStackSelector Visual Basic template form

Related Topics

The CGTGStackSelector template form is used to define the look and feel of the control group used to implement the stacking area.

The controls defined in this template are:

Name	Optional?	How Control is Used
CG_FRAME_SELECTOR	N	Defines the control used to implement the stacking area i.e. a tab control or a radio group.
CG_LAYOUT_AREA	N	Defines the margins around the controls within the frame.
OptionButton	N	For a radio group, defines the button within the enclosing frame.
SSTab	N	Provides a group of tabs, each of which acts as a container for other controls. Only one tab can be active in the control at one time; it displays the controls it contains to the user while hiding the contents of the other tabs.
Set the Use tab control for stacking areas (USETAB)  preference to choose between radio groups and tabs.

You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


CGTGStackedGroup Visual Basic template form

Related Topics

The CGTGStackedGroup template form is used to define the look and feel of the stacked frames that make up a zone's stacking area. These frames will enclose the stacked control groups and stacked detail zones.

The controls defined in this template are:

Name	Optional?	How Control is Used
CG_GROUP_FRAME	N	Defines the look and feel of the frames.
CG_LAYOUT_AREA	N	Defines the margins around the controls within the frame. Does not apply to stacked detail zones.
If a group is stacked and that group is using a tab control, the CGTGStackedGroup template form is ignored. Instead, the CGTGStackSelector template form is used for the stacking area.

You can customize Visual Basic Generator templates by taking a copy of the shipped set and amending the new versions. How


Visual Basic Generator template directories

Related Topics

cvb5tmpt1 directory

This directory contains the default template project (tmpt.vbp). This project contains an MDI parent form which causes the generated application to appear as a single window on the desktop, with all main windows created as child windows within the MDI parent.

The status bar showing user and date information is placed on the MDI parent form. The template windows are sized for use on SVGA monitors.

Note that this directory contains an additional project named tmptclr.vbp. This template project contains a different template controls form. This version will generate different colored controls, depending on the characteristics of the controls.

Note:	Oracle Designer Visual Basic Generator is no longer certified against VB4, however if you do want to generate VB4 applications, use the cvbtmpt1 version of this directory. About

cvb5tmpt2 directory

This version of the template project (tmpt2.vbp) lacks the MDI parent form so the generated application is therefore presented as a set of independent windows.

The status bar showing user and date information is placed on the first main window of each module. The template windows are sized for use on SVGA monitors.

Note:	Oracle Designer Visual Basic Generator is no longer certified against VB4, however if you do want to generate VB4 applications, use the cvbtmpt2 version of this directory. About

cvb5tmptc directory

Template forms that are common across both projects are held in the \cvb5tmptc directory.

Note:	Oracle Designer Visual Basic Generator is no longer certified against VB4, however if you do want to generate VB4 applications, use the cvbtmptc version of this directory. About


About the control definition file

Related Topics

The control definition file contains information that defines the capabilities and characteristics of each type of control used in generated applications.

By default, the name of the control definition file is CTLDEF.TXT and it is located in the \cvbetc subdirectory of the Visual Basic Generator installation. However, you can use the Control definition file (CTLDEF) preference to specify a different version of the file.

The format of the control definition file is similar to an .ini file in that each control type has its own section, denoted by a section header within square brackets. Entries within that section define the properties of that control type.

Note:	To utilize third-party controls, you must add them to the control definition file. How

Control classes

The BasicControlType property defines the basic class of each control; there are five possible control classes:

TEXT	A text-based data entry or display, such as a Text Box or Label control.
CHECK	A control that may represent two distinct values, such as a CheckBox or SSCheck.
LIST	A control that allows the user to pick a value from a list of values, such as a ComboBox or ListBox.
RADIO	A container control, capable of holding a number of option buttons. It collectively represents a radio/option group, such as the Frame control.
OTHER	Other types of control, such as buttons, gauges, and so on.
Types of entry in the control definition file

Each property that may be defined in the control definition file falls into a particular category:

Control suitability entries	Entries that check the suitability of a control definition for its role in the generated application.
Control property name entries	Entries that give the name of a Visual Basic control property; for example, to carry out data entry validation, or to assist the user in the data entry process.
Control property value entries	Entries that specify a value for a particular property.
Other entries	Miscellaneous entries.


Control suitability entries

Related Topics

Once an item has been mapped to a template control during the generation process, the corresponding control definition is checked against the item to confirm its suitability for a particular role.

The default value of these properties is False, and therefore an entry is required in the control definition file only if the property is True. True is denoted by -1. So, for example, CantHoldNumberValue=-1 would be added if the control (such as a third-party date control) could not store a number.

The following control suitability entries may be used:

Name	Description
ButtonHasNoDefaultProperty	The button style control does not have a Default property; that is, it cannot be set to be the form's Default button.
CantHoldDatabaseValue	The control is not suitable for displaying a database value; for example, a Command Button.
CantHoldDateValue	The control is not suitable for holding or displaying a date value; for example, a scrollbar or checkbox.
CantHoldNullValue	The control always has a value, and is therefore unsuitable where null values are to be entered by the user, or retrieved from the database; for example, a scrollbar.
CantHoldNumberValue	The control is not suitable for holding or displaying a numeric value; for example, a custom date control.
DontAllowInQueryDialog	The control is not suitable for use in a query dialog. Note this property does not perform the basis of any validation; it is used to determine the control type to use for the item in the query dialog.
HasNoGotFocusEvent	The control does not support a GotFocus event; for example, a Label or a Frame.
HasNoHelpContextIdProp	The control does not have a HelpContextId property.
HasNoHWndProp	The control does not have an Hwnd (Window Handle) property; for example, a Label.
HasNoMouseMoveEvent	The control does not support a MouseMove event; for example, a Combo Box.
HasNoTabIndexProp	The control has no TabIndex property; for example, an image control.
ListFixedSetOfValues	Should be set to True if the List/Combo style control can accept only a fixed set of values, rather than allow the user to enter a value not in the list.
ListMultiline	Should be set to True if the List style control can display multiple lines; for example, a List Box. Should be set to False if the List style control can display only a single line; for example, a Combo Box.
ReadOnly	The control cannot be set interactively by the user. It is therefore unsuitable for data entry; for example, a label or a gauge.


Control property name entries

Related Topics

These properties define the existence and name of specific Visual Basic control properties. If a control supports a particular logical property, this string specifies the name of that Visual Basic control property.

It is assumed that, by default, these properties do not exist on the control. Hence, an entry must be added to the control definition file only if the control does support it. For example, by default, a control is assumed not to support a 'read-only' property but, if it does, the name of the property that enables the control to be 'read-only' should be set to something like: ReadOnlyProp='DisplayOnly'. Strings must be always be defined in single quotes.

The following control property name entries are used:

Name	Description
MinProp	Name of the property that defines the minimum numeric value. Used on those controls where a single valid range has been defined on the number column.
MaxProp	Name of the property that defines the maximum numeric value. Used on those controls where a single valid range has been defined on the number column.
MinSetValueProp	If the control has a MinProp/MaxProp pair, then MinSetValueProp should be set to the control's 'Value' property name so that it too can be set to the minimum value setting.
SmallChangeProp	Name of a (scrollbar type) control's small change property. It will be set to be one hundredth of the difference between low and high values.
LargeChangeProp	Name of a (scrollbar type) control's large change property. It will be set to be one tenth of the difference between the low and high values.
CaseProp	Name of the property that can be set to provide uppercase conversion. If specified, the valid values should also be specified.
ComboStyleProp	For Combo Box-type controls, the name of the property that determines the style of the combo box. If specified, the valid values should also be specified.
FormatProp	This property can be set to provide a specific format. Date formats are taken from the Windows Control Panel (Regional Settings).
HintLineProp	Name of the property that can be set to provide hint/status text. If specified, it will be set to the value of the Hint property against the item.
IntegratedCaptionProp	Name of the control's integrated caption property. If set, it indicates that the Prompt property defined against the item is used to set this property on the generated control. If unset, it causes the creation of a separate label control for the item prompt.
ListMultiSelectProp	For List Box style controls, the name of the control's multiselect property. If specified, the valid value should also be specified.
MaxLengthProp	Name of the property that defines the maximum number of characters that can be entered.
NumberPrecisionProp	Name of the property that defines the total precision of an entered number.
NumberScaleProp	Name of the property that defines the maximum number of allowed decimal places.
ReadOnlyProp	Name of the property that sets the control to be read-only.
ScrollBarProp	Name of the property that places a scrollbar on the control. If specified, the valid values should also be specified.
TabStopProp	Name of the control's tab stop property.
TextAlignmentProp	Name of the control's alignment property. If specified, it will be set to a value according to the setting of the Alignment property against the item.
ValueProp	Name of the property that holds the database value for the control. Typically, it is used only in cases where the control's default 'value' property includes formatting characters.
WordWrapProp	Name of the property that can be set to provide word wrapping.


Control property value entries

Related Topics

If a control supports a particular property, the control property name entries specify the name of that Visual Basic control property. The property value entries define those property values that have a specific significance.

The following control property value entries may be used:

CaseProp values

CaseValueMixed	If CaseProp is set, this specifies the value of the property used to denote that any case is permitted.
CaseValueUpper	If CaseProp is set, this specifies the value of the property used to denote that uppercase only is permitted.
ComboStyleProp values

ComboStyleDDCombo	If ComboStyleProp is set, this specifies the value of the property indicating 'Drop Down Combo'; that is, the entry can be taken from the list or else typed in.
ComboStyleDDList	If ComboStyleProp is set, this specifies the value of the property indicating 'Drop Down List'; that is, the entry can be taken only from the list.
ListMultiSelectProp value

ListMultiSelectNone	If ListMultiSelectProp is set, this specifies the value of the property indicating that multiselect is turned off.
ScrollBarProp values

ScrollBarValueNone	If ScrollBarProp is set, this specifies the value of the property indicating that no scrollbar is required.
ScrollBarValueVertical	If ScrollBarProp is set, this specifies the value of the property indicating that a vertical scrollbar is required.
TextAlignmentProp values

TextAlignmentValueLeft	If TextAlignmentProp is set, this specifies the value of the property indicating that left-alignment is required.
TextAlignmentValueRight	If TextAlignmentProp is set, this specifies the value of the property indicating that right-alignment is required.
TextAlignmentValueCenter	If TextAlignmentProp is set, this specifies the value of the property indicating that center-alignment is required.


Other entries in the control definition file

Related Topics

There are several properties that do not fall into any of the other categories. Note that strings must always be defined in single quotes.

Name	Type	Default	Description
ChangeEvent	String	'Change'	The name of the event that fires when the user changes the control's value.
ClickEvent	String	'Click'	The name of the event that fires when the user clicks the mouse over the control.
ClickEventParameters	String	"	If the control's Click event takes one or more parameters, this defines the nature of the parameter declaration; for example, "Value As Integer".
ControlNamePrefix	String	"	The prefix of the generated control name. This is used to standardize control names; for example, you may wish to prefix the names of all text box controls with the string 'txt'.
EnforceDatatype	String	None	Specifies that the control implicitly enforces that its value is of the given datatype. Valid values are: INT, REAL, DATE. By default, no implicit enforcement is assumed.
LayoutWidthOverhead	Number	0	The size (in twips) of a control's left and right margins.
RecoverControlType	String	None	The BasicControlType used when recovering the control i.e. one of TEXT, CHECK, LIST, BUTTON, RADIO, OTHER.
RecoverAsDataControl	Number	-1	If the item is to be recovered as a data control, set this property to -1. If this property is set to 0, or omitted, the item will be captured as an unbound item.
DontRecoverItem	Number	-1	If the item is not to be recovered, set this property to -1. If this property is set to 0, or omitted, the item will be captured.
RecoverAsZone	Number	0	If either DontRecoverItem or RecoverAsDataControl are set to -1, this property is not relevant. If both DontRecoverItem or RecoverAsDataControl are set to 0 or omitted, and this property is set to -1, the item will be captured as a zone.


About Visual Basic library forms and code

Related Topics

Standard library forms and code are included with Visual Basic Generator. These elements are known as 'standard inclusions' and they are shipped together in default library project files called incl.vbp and incldao.vbp:

Data access method	Default library project
Oracle Objects for OLE	cvbvb5lib\incl.vbp
Visual Basic Data Access Objects (DAO)	cvbvb5lib \incldao.vbp
Standard inclusions are not generated, but simply copied over at generation time. They consist of the following:

•	general library routines (contained in lg.bas)

•	Oracle Objects for OLE database-access library routines (contained in ld.bas)

•	DAO database-access library routines (contained in lddao.bas)

•	global constants (contained in lm.bas) , that define translatable strings and messages issued to the user (by both library and generated code) at runtime

•	standard library forms, including:

−	the logon form, used as a front-end to generated applications, where the user enters logon and database connection information.

−	the server-error form, used to display detailed information about server errors.

−	an 'about' box that provides information about the generated application.

•	a file containing Oracle Objects for OLE global constants (oraconst.txt)

Customization

If you need to add or modify library forms and code modules you can customize the default library project. How

If you want to generate a non-English Visual Basic application you will need to update the library project to include the appropriate translated version of lm.bas. About

Note: 	If you create a custom library project, specify the project using the Library (standard inclusions) project (MGPROJ) preference. How

Visual Basic 4.0 generation

Oracle Designer Visual Basic Generator is no longer certified against VB4, and we recommend that you generate Visual Basic applications for VB5 or VB6. However, if you want to generate VB4 applications, you must use the default library project files in the \cvbvblib directory. For more information, see Using Visual Basic Version 4.0


General library code

Related Topics

Routines	Description
lgCallDVLOV	Calls a List of Values for Domain Validation
lgCentralizeForm	Returns the value of the given Check Box
lgCheckFormLoaded	Check to see if form is already loaded.
LgCtrlCheckBoxGet	Returns the value of the given Check Box
lgCtrlCheckBoxGetQD	Returns the value of the given Check Box when used in a Query Dialog
lgCtrlCheckBoxSet	Sets the given check box control to the given value
lgCtrlDVListGet	Returns the code associated with the current selected item in a DV list
lgCtrlDVListGetQD	Returns the value to be incorporated into the SQL where clause associated with the current selected item in a DV list
lgCtrlDVListPopulate	Populates a list control with values from a domain array
lgCtrlDVListSet	Set a DV list according to the current value
lgCtrlDVMeaningSet	Set a DV list displaying the domain meaning, and the control representing the code according to the current value
lgCtrlRadioGet	Returns the value of the given Radio group
lgCtrlRadioGetQD	Returns the value of the given Radio group when used in a Query Dialog
lgCtrlRadioSet	Sets the given Radio group to the given value
lgEditCopyProc	Copies the selected text of the given control to the clipboard
lgEditCutProc	Cuts the selected text from the given control to the clipboard
lgEditPasteProc	Copies the text from the clipboard into the given control
lgFormLoaded	Checks that the given instance of a form is not already loaded
lgHighlightTextBox	Highlights the text in the given text box
lgHintText	Displays floating hint text for the control under the mouse pointer
lgSettingReadBoolean	This function gets the value of a parameter from the runtime ini file (16 bit) or system registry (32 bit)
lgSettingReadString	This function gets the value of a parameter from the runtime ini file (16 bit) or system registry (32 bit)
lgSettingWriteBoolean	This function sets the value of a parameter in the runtime ini file (16 bit) or system registry (32 bit)
lgSettingWriteString	This function sets the value of a parameter in the runtime ini file (16 bit) or system registry (32 bit)
lgMsg	Displays the given text in a MsgBox with an appropriate icon and title
lgMsgSubst	Replaces the parameter token of the given text, with the given parameter
lgMsgAsk	Displays a two-button dialog (YES/NO) and returns the user action
lgMsgAsk3Button	Displays a three-button dialog (YES/NO/CANCEL) and returns the user action
lgMsgServerError	Displays detailed information about an unknown server error to the user
lgMsgVBError	Displays a standard Visual Basic error with the location where the error occurred
lgNow	Returns the current system date or time
lgNvl	Returns a substitute value if the value to be tested is null
lgQDAddPredEqual	Adds a WHERE clause predicate to the given where clause, for a straightforward equality or like operator
lgQDAddPredRange	Adds a WHERE clause predicate to the given where clause, for a range search
lgQDHighlightTextBox	Highlights the first non-empty text box in the form
lgQDRHS	Validates and constructs the RIGHT HAND SIDE value of the where clause for both the lgQDAddPredEqual & lgQDAddPredRange procedures
lgQDStripQuotes	Checks for and removes surrounding quotes of a given string
lgRemoveSelectedFromList	Removes the selected rows from a multi-select list control
lgRPad	Right pads the given string with spaces to return the string to the required length
lgRszAddControl	Registers the given control for resizing/repositioning
lgRszResize	Resizes/moves the given set of controls according to the form size
lgSetFocus	Sets the focus to the control if possible
lgSetFocusTextBox	Sets the focus of the first non-empty text box in the form
lgSetLength	Sizes the given string to the given length (padding/shortening)
lgShowRecordStatus	Displays the record status
lgStatusDate	Sets the given controls caption to the current date and time
lgValCheckRange	Checks a given value is in the specified range
lgValChkNumPrecision	Checks whether the given value exceeds the specified maximum length and scale
lgValDVCode	Validates a value against a given domain
lgValDVMeaning	Validates a meaning against a given domain
lgValForceCaseKey	Converts the given ASCII value to the case specified
lgValForceCaseString	Converts the given string to the case specified
lgValIsDate	Checks to see if the given string contains a valid date or not
lgValIsNumber	Checks to see if the given string value contains a valid number or not
lgValNotNull	Checks to see if the given control is null
Note:	Further information on these routines can be found within the Visual Basic module itself.


Database-specific library code

Related Topics

Routines	Description
ldDeleteRow	Deletes a specific record from the database
ldDVPopulateDom	Populates a Domain Array with values from a reference codes table
ldErrorClass	Returns the class of server error that has occurred (lddao.bas only).
ldGetDataAccessInfo	Returns information about the data access method, for display in the about box
ldGetOIPErr	Returns the error code from the given Oracle Objects error message (ld.bas only).
ldGetUserLogonInfo	Returns information about the logged on user/database for display in the about box
ldIsServerError	Checks for Server Error (lddao.bas only).
ldLOVDefine	Defines requirements for a List of Values dialog
ldLOVUnload	Unloads the LOV from memory
ldNextIdCC	Provides a unique id from a code controls table
ldNextIdSeq	Provides a sequence number from a sequence
ldQDBuildLiteral	Validates and constructs a literal value to use in the where clause of a query.
ldSetBindParametersVals	Extracts the bind parameters names and its associated values and assigns them to query definition object (lddao.bas only)
ldSetParamVal	Sets a database parameter to the given value
ldSPResequence	Updates the database sequence of rows in a list control
ldSPSwap	Swaps the database sequence of two given rows
ldSrvErrConstraint	Provides the constraint name of the given error
ldSrvErrGetErrNum	Provides the error number of the given error (ld.bas only).
ldSrvErrGetErrText	Provides the error text of the given error (ld.bas only)
ldSrvErrPopStack	Removes the error message at the top of the given error stack (ld.bas only).
ldStatusUserLogon	Sets the Caption of the given control to the current user logged on
ldTransactionBegin	Begins a database transaction
ldTransactionCommit	Commits all pending database transactions
ldTransactionRollback	Rolls-back all pending database transactions
Note:	Further information on these routines can be found within the Visual Basic module itself.


Standard library forms

Related Topics

Forms	Description
frm (ldLogon.frm)	Provides the standard logon form that acts as the application front-end (Only applicable to Oracle Objects for OLE)
frmldLogon (ldDaoLogon.frm)	Provides the standard logon form that acts as the application front-end (Only applicable to DAO)
frmldLOV (ldLOV.frm)	Provides a list of values (LOV) dialog that is used to display values from a table (Only applicable to Oracle Objects for OLE)
frmldLOV (ldDaoLOV.frm)	Provides a list of values (LOV) dialog that is used to display values from a table (Only applicable to DAO)
frmlgAbout (lgAbout.frm)	Provides information about the generated application
frmlgAskQry (lgAskQry.frm)	Obtains reduction criteria for a query that would potentially return a large number of rows
frmlgDVLOV (lgDVLOV.frm)	Displays a list of values which are defined in a domain
frmlgOptions (lgOption.frm)	Provides the mechanism for setting runtime options of generated applications
frmlgSE (lgSE.frm)	Provides information about server errors
frm (ldLogon.frm form) (Oracle Objects for OLE)

The standard logon form that enables the user to log on to the database. It will be the front-end to the generated application. It allows the user to enter a username, password and the database where they want to connect.

The form is displayed in the center of the screen. On selecting the connect button it verifies both a username and password, and then calls the ldLogon function to create the database session and handle any errors. On successful logon the form is hidden to display the application.

frmldLogon (ldDaoLogon.frm form) (Data Access Objects)

The standard logon form that enables the user to log on to the database. It will be the front-end to the generated application. It allows the user to select local access database or ODBC datasource. If you choose a local access database, it can be opened in exclusive mode, read only mode or default mode. If you choose an ODBC datasource, you can either open the datasource directly, or go through an intermediate attachment mdb file.

The form is displayed in the center of the screen. If local access database option is set when the connect button is selected the existing access database file is opened based on selected options.

If ODBC datasource option is set when the connect button is selected the datasource name, username and the password are verified. The ODBC database is opened directly if the attachment file name is not specified, otherwise an existing file is opened. If the creates/resolve attachments option is set and attachment file name is supplied, the ResolveAttachments function is called to create or resolve attachments.

On successful logon the form is hidden to display the application.

frmldLogon (ldDAOLOV.frm DAO and ldLOV.frm Oracle Objects for OLE)

This is a list of values dialog (LOV), used to display values from a table to the user. It contains a set of public routines to build the requirements for the LOV and activate the LOV, plus a set of private functions.

These functions are listed below:

Public routines:

InitialiseForm	Initializes the form
DefineField	Defines a field in the LOV
Activate	Activates the LOV allowing the user to pick a value
RetVal	Returns the value of the given field in the chosen row
Private routines:

Position	Positions the LOV form
BuildRequirements	Works out the SQL select list required, plus the heading to display
ConvertPattern	To convert search criteria as entered by the user
DoHeading	To display/hide the heading on the LOV form
FilterList	Copies the values from the string array into the List Box control
GetListFromDB	Fetches the list from the database
GotoListEntry	Searches the LOV list for the given string, and selects the entry
SetModeFilter	Sets the mode to 'Filter', by enabling the filter button and changing the Text Box label
SetModeFind	Sets the mode to 'Find', by disabling the filter button and changing the Text Box label
frmlgAbout (lgAbout.frm form)

This form is an about box, used to provide information about the generated application. The form is displayed by selecting the 'About' menu option under the 'Help' menu of the main form.

Information displayed on the about box:

•	System resources

•	Amount of free memory

•	Name and version of the generator

•	Name and version of the database server

•	User connection string

The form picks up and displays the icon of the executable file. The system resource and memory information are obtained by Windows API calls.

frmlgAskQry (lgAskQry.frm form)

This is used to obtain reduction criteria for a query which would potentially return a large number of rows.

The function DlgQuery is called, taking as its parameters the name of the underlying column, a prompt, the maximum length of the column, and whether the input should be forced to uppercase. These parameters are copied into labels in the form lgAskQry.frm which is then invoked modally. The user can enter a string into the visible text control and press OK, or Cancel. If OK is pressed, the entry by the user is copied to a hidden label which is picked up by DlgQuery. A WHERE clause predicate of the form "<column name> LIKE '<entry>'" is built and used to restrict the query.

frmlgDVLOV (lgDVLOV.frm form)

This is used to display a List of Values which are defined in a Domain.

The lgCallDVLOV procedure uses this form to display values (or meanings) from a domain and allow the user to select a value for data entry. On selection of the OK button, or double clicking on the list, the index of the selected item is copied to a hidden label (zsSelection) and this is then used to find the associated value and/or meaning from the domain array.

frmlgOptions (lgOption.frm form)

This form provides the mechanism for setting runtime options of generated applications.

The settings of these options are stored as parameters in the file vbgr.ini (16 bit) or system registry (32 bit):

Parameter	Value	Description
AutoCommit	1 True 0 False	Auto Commit pending changes
CoordOnActivate	1 True 0 False	Only Coordinate detail forms when activated
CloseDetailsOnDisable	1 True 0 False	Close disabled detail forms
HintTimerDelay	Delay in milliseconds	Hint Text (Short Delay, Long Delay, or Off)
frmlgSE (lgSE.frm form)

This is a dialog box used to display detailed information about unknown server errors to the user. It will be used by the error handlers of those functions and procedures that involve database interaction. It is called by the lgMsgServerError function which provides its interface.

The form has been designed to display the first four outputs above, with a SQL button available only if the SQL statement has been provided. On pressing the SQL button the form unfolds to display the SQL statement in error. If the SQL error location is available (pintPosition), the section of text causing the error, in the SQL statement, is highlighted. Once given this location the algorithm works on the basis that if the first character is a letter or a number then it highlights the whole word/number until it reaches a space or a character that is neither a number or letter; otherwise the first non-numeric/non-alphabetic character is highlighted.


Aspects of generated Visual Basic code

General

Column derivation

Domain validation

Populating lookups

Server constraint error trapping

Validation code

Zone coordination

Help files for generated Visual Basic applications

Hint text for controls

Keyboard navigation

Menu generation

Generated zones (main form)

Context-style zones

Form-style zones

List-style zones

List/Form-style zones

Supporting dialogs

Property sheet dialogs

Query dialogs


Column derivation in Visual Basic applications

Related Topics

A column may be defined in the repository as having its value derived automatically, either from a

•	sequence (UID generation), or via an

•	auto-generate type

If a zone contains any such columns, a routine called <zone>_ClientDerivation is generated to perform this derivation. It is called from the <zone>_PreInsert and/or <zone>_PreUpdate routines.

UID Generation

UID generation is achieved by specifying the name of a Sequence definition against the column definition. This indicates that when new rows are created, a unique number is to be assigned to the column. The Code Control property on the Sequence definition indicates whether a 'Code Control Sequence', or an 'ORACLE Sequence', is to be used to source the unique numbers.

Note:	Choose 'Code Control Sequence' if your target database is not Oracle.

Code Control Sequences

Using Code Controls tables will guarantee sequential numbers with no gaps between them; this may be crucial for the allocation of, say, invoice numbers. The next value in the sequence is obtained by calling the ldNextIdCC routine in ld.bas.

ORACLE Sequences

By contrast, an ORACLE sequence provides better concurrency, but the numbers are not guaranteed to be in an unbroken sequence. The next value in the sequence is obtained by calling the ldNextIdSeq routine in ld.bas.

Auto-Generate

Auto-Generate features are defined by setting the AutoGen Type property against the column to one of the following:

AutoGen Type setting
Created By	Set to the name of the Oracle user that created the row
Modified By	Set to the name of the Oracle user that modified the row
Date Created	Set to the date when the row was created
Date Modified	Set to the date when the row was last modified
Seq In Parent	Set to a number unique within a parent column value
With the exception of Seq In Parent, controls which are based on columns with an AutoGen Type setting will be created as non-enterable in the generated application and will be set programmatically, immediately prior to the database operation (INSERT or UPDATE).

In general, UID, and Created By and Date Created controls, will be populated on insert; Modified By and Date Modified controls will be populated on update. However, if the Modified By and Date Modified columns are mandatory, they will also be populated on insert.

If the Server Derived property is set against the column, no code will be generated, on the assumption that all derivation will be implemented on the server using database triggers. The generated application will, however, requery the row following the insert or update operation so as to display the server-derived values.

If any columns are not 'Server Derived', but are one of: Created By, Modified By, Date Created, or Date Modified, and are required but missing from the module definition, they are added automatically, and a warning is issued.

If the AutoGen property of the column is set to Seq In Parent, it should also form part of a unique or primary key. The other columns in the key define the parent columns, within which the allocated number is to be unique. If the column forms part of a unique key that has been defined to be validated on the client-side, and the zone layout style is List or List/Form, then a pair of Resequence Up/Down buttons will be added to the zone's button bar. These will allow the user to change the sequence value, relative to the adjacent row.


Domain validation in Visual Basic applications

Related Topics

A column may be defined in the repository as being restricted to a given set of values, or as belonging to a domain with such a set. The Generator will ensure that this validation is enforced in generated applications. This may be via specific data entry controls, such as radio group, checkbox, poplist, text list etc. or via generated code against a Text Box control.

Value, meaning, and abbreviation

When you enter an allowable value against a column, you can also record a corresponding meaning. Therefore, data entry and display can either be 'by Value' or 'by Meaning' and this is controlled using the 'Show Meaning property.'

Text controls also support Abbreviations.

•	If entry is by Value, and an Abbreviation has been defined for that value of the domain, the Abbreviation may be typed into the text control, and this will be replaced by the Value when the focus is moved out of the control.

•	If entry is by Meaning, the Abbreviation (defaulting to Value if no Abbreviation is defined) may be typed into the text control, and this will be replaced by the Meaning when the focus is moved. If an entry (sufficient to uniquely identify a value in the domain) is made into a text control, the remainder will be filled in when the focus is moved.

Within any layout constraints, a command button may be created alongside a text control (if it allows Insert or Update). This will invoke a List of Values (LOV) for the domain. The Meaning or Value will be displayed as described above.

Query dialogs

For query dialogs, where the column in the domain is optional, an additional value "IS NULL" will be provided in the list for possible inclusion in the search criteria.

Text and list controls

An array of possible values is built for text and list controls during the Form_Load event of any form containing such controls. These arrays consist of the allowed values, and possibly the associated Meanings and Abbreviations.

The Dynamic List property of the domain defines how these arrays are built. If this property is False, the initialization of the arrays is hard-coded; if it is True, a call is made to a library routine to initialize the array from rows stored in a reference code table.

Suggestion lists

If the Suggestion List property is set to Yes, no validation is performed on data entry. For text controls, this means that only a List of Values is provided. For PopList style controls, this means setting its style property to DropDownCombo during generation (see the ComboStyleProp, ComboStyleDDCombo, and ComboStyleDDList properties in the control definition file ).


Populating lookups in Visual Basic applications

Related Topics

A List of Values (LOV) dialog is generated for enterable lookup controls. The LOV lets the user choose the value from a list and any related lookup values are populated as the user leaves the enterable lookup control.

Conversely, if a foreign key control is not enterable but has an associated lookup table usage with an enterable control, then code is added to the lookup control to populate the non-enterable foreign key value upon exit from the lookup control, and a List of Values is again provided.

Invalid data in foreign key controls

If data entered into an enterable foreign key control is invalid, a warning is issued, and any associated lookup controls are cleared. If an attempt is made to commit the record before it has been corrected, the server is responsible for trapping the error, preventing the operation, and then translating the error into a suitable user message.

Invalid data in lookup controls

If data entered into an enterable lookup is invalid, a warning is issued, and the associated foreign key control and non-enterable lookups are cleared. However, a further check is added to the <zone>Validate routine to ensure that, if the state (foreign key control is empty yet lookup control has a value) prevails at commit time, then the same message is issued; however, this time the operation is prevented from continuing.

Composite foreign keys

If a foreign key comprises multiple columns, each column in the key is handled individually; each one is given its own List of Values, plus code to populate its corresponding lookup controls upon exit from the foreign key control.

Hence, for each column in the foreign key, a search is done to find a single lookup table usage to associate with the foreign key control. This works by following the link through from the foreign key column to its immediate lookup, and then beyond through other chained lookups until the corresponding column on the lookup is not involved in any links to further lookups, or indeed in any of its table's foreign keys. The foreign key control's list of allowed values is then based on this lookup table usage, and is constrained by the values in the controls that correspond to the other columns that link this lookup table usage to its parent.

If the search for a lookup table usage does not find such a candidate, a search is then made through the table's foreign key links. Again, this follows the links through until it finds a table where the corresponding column is not involved in any further foreign key links. Here, the table found is used to provide the list of allowed values.

Constraining by links to master zone

If a foreign key control is part of a composite key, and another column in the key actually forms the link to a master zone, the List of Values (and the corresponding 'validation' SELECT against the lookup table) will be restricted by the master value. This situation may occur when a column is involved in more than one of its table's foreign keys.

Note: 	LOV dialogs are generated for data entry only; they are not generated against the Query dialog.


Server constraint error trapping in Visual Basic applications
Oracle server constraint error trapping in Visual Basic applications

Related Topics

Most of the complex data validation that takes place in a generated application is the responsibility of the server, either by declarative constraints or by database triggers. However, code will be generated in the client application to trap any expected Oracle server errors, so that the server error message can be translated into messages that are more meaningful to the user.

Failure detection

If the server detects a failure while data is being inserted, updated, or deleted, it returns an error code and message to the client. For each zone, a routine called <zone>_SrvErrCheck is generated, and called from the appropriate <zone>Insert, <zone>Update, and <zone>Delete routine. This examines the error code and where possible translates it, so as to provide the user with an appropriate error message. This is usually the message recorded for the Error Message property against the constraint. The code added to this routine depends on the zone's base table and the allowed operations on that zone.

Oracle error codes

Explicit Oracle error codes that are trapped are:

ORA-00001	unique constraint violated
ORA-02290	check constraint violated
ORA-02291	integrity constraint violated - parent key not found
ORA-02292	integrity constraint violated - child record found
ORA-20000 to ORA-20999	user defined errors resulting from raise_application_error within trigger code
Constraint violation

If a constraint violation occurs, the error message returned from the server is parsed to find the name of the constraint that was violated.

If the Validate in property for the constraint is defined in the repository as 'Server' or 'Both', the message associated with the constraint, or (if absent) some other appropriate message, is displayed. This is handled via the standard lgMsg procedure in the lg.bas library module.

If the constraint was not defined in the repository, or the error was not one of the error codes above, a message is issued via the lgMsgServerError library procedure. This uses the Server Error dialog to display the error message, plus the code location of the error and (optionally) the SQL statement that caused the error.

Additional notes

No Visual Basic code is generated to actively enforce constraints. Hence, if a constraint in the repository has its 'Validate in' property set to 'Client', a warning will be issued indicating that that constraint will not be validated.

In the current release, it is not possible to record in the repository the name of a column-level check constraint. Hence no code will be generated to trap column-level check constraint violations.


Validation code in Visual Basic applications

If the Insert or Update property of an item is set to 'Yes' but its associated control cannot perform validation itself, validation code can be added to the data entry control. Such validation code is added to the zone's <zone>Validate routine and this routine is called before inserting and updating records in the database.

The following checks may be added to the <zone>Validate routine:

Check user has entered a value

If an item's Optional property is set to 'No', code is added to ensure the user has entered a value. The lgValNotNull library routine performs the validation.

Note that code is not required (and hence not added) for GUI controls that have default values.

Correct datatype entered

This ensures that the value entered by the user is of the correct datatype. Code is added if the underlying column is NUMBER or DATE and the control is subject to text entry by the user. The lgValIsNumber and lgValIsDate library routines perform the validation.

Note that code is not added if the control can implicitly enforce datatype validation; that is, the EnforceDatatype property is set for the control in the control definition file.

Value entered does not exceed maximum permitted length

This ensures that the value entered by the user is no longer than the underlying column permits. Code is added if the underlying column is a character column.

Note that code is not added if the control can implicitly enforce maximum length validation; that is, the MaxLengthProp property is set for the control in the control definition file.

Precision/scale entered respects underlying column

This ensures that the value entered by the user respects the precision and scale of the underlying column. Code is added if the underlying column is a numeric column.

The lgValChkNumPrecision library routine performs the validation.

Note that code is not added if the control can implicitly enforce numeric precision and scale validation; that is, the NumberPrecisionProp and NumberScaleProp properties are set for the control in the control definition file.

Number entered is within range

This ensures that the value entered by the user is within the permitted range of values for the control. Code is added if the underlying column is a numeric column, and it has a single range defined against it in the repository.

The lgValCheckRange library routine performs the validation.

Note that code is not added if the control can implicitly enforce maximum/minimum value validation; that is, the MaxProp and MinProp properties are set for the control in the control definition file.

Value entered is forced to uppercase

This ensures that the value entered by the user is converted to uppercase, both on the <zone>Validate routine and on the control's KeyPress event. Code is added if the Uppercase property for the underlying column is set to Yes.

The lgValForceCaseString and lgValForceCaseKey library routines perform the conversion.

Note that code is not added if the control can implicitly force values to uppercase; that is, the CaseProp property and the CaseValueUpper property are both set for the control in the control definition file.


Zone coordination in Visual Basic applications

Each generated application may comprise one or more forms, each typically with one or more zones of different styles. The exception is launch screens, which have no zones.

Master-detail relationships

Zones related to each other in master-detail relationships (key based link); these relationships may be within a single form, or may span forms. A zone may also have a relationship with a zone in another form sourced from a different module definition and this relationship is also defined using key based links.

Master-detail relationships between zones are classified as either of the following:

•	Internal, where zones are within the same form

•	External, where zones are on separate forms

A master form is a form with one zone that has an external detail zone.

A detail form is a form with a zone with an external master.

Two zones with a master-detail relationship must have a foreign key or primary key link between the base tables. The foreign key may be on the master table or on the detail table.

Defining coordination

Coordination is defined by adding a key based link between the master and detail module components. If the key based link is between components in different modules, both the master and detail modules must be generated into the same project. Typically, this is achieved by checking the 'Include the module network in this application' checkbox when generating the master module (or one of its ancestors).

User interface

The coordination of zones ensures that:

•	detail zones are either clear, or show valid records for the current master record

•	detail zones are disabled, unless a valid master is present

•	when navigating between master records, all associated detail zones are checked for pending changes, and cleared once the changes have been resolved, before navigating to the target record

•	when repositioning on a new master, detail zones defined as AutoQuery zones are coordinated as follows:

−	if detail zones are internal and visible, they will be queried automatically; if they are not visible, they will be requeried when that stacking area is made visible

−	if detail zones are external and visible, and the runtime Options dialog checkbox 'Only Coordinate detail forms when activated' is unchecked, these zones are requeried automatically; if they are not visible, they will be requeried when the form that contains them becomes visible

−	if detail zones are external, and the runtime Options dialog checkbox 'Only Coordinate detail forms when activated' is checked, they are requeried when that form becomes active

•	when opening a form containing detail zones defined as AutoQuery, a query is performed automatically to link those zones back to the master

•	detail forms are automatically unloaded when a form is unloaded

•	if the first zone has been defined as AutoQuery, a query is performed automatically in that zone when the application starts up

Generated code

The principles of coordination are the same for internal and external relationships. Coordination is managed by a set of private routines created for each zone, plus public interface routines created on detail forms.

Generated zone-level private routines

<zone>_ZCClearDetails	Clears the detail zones by calling <zone>_Clear for internal details, and public function <form>.ZCPIClear for external details.
<zone>_ZCCheckChanges	Checks for outstanding changes in the current zone, plus any detail zones. Detail zones are checked by calling <zone>_ZCCheckChanges for internal details and public function <form>.ZCPICheckChange for external details.
<zone>_ZCEnable	Created for detail zones, this enables or disables the controls of the zone as dictated by the state of the master zone.
<zone>_ZCCoord<detail form>	Coordinates the detail zone by copying primary key columns to hidden labels, and then calling public function <form>.ZCPIZoneCoord. Coordination will update the caption of the detail, requery if required, and set focus to that detail form.
<zone>_Reposition	Code is added to the Reposition event of master zones in order to coordinate its detail zones, by calling <zone>_ZCEnable and <zone>_Query for internal details, and <form>.ZCPIEnable and <zone>_ZCCoord<detail form> for external details.
External detail Form public routines

<form>.ZCPIClear	Called by the master zone to clear one or more detail zones in the current form.
<form>.ZCPICheckChange	Called by the master zone to check if there are any uncommitted changes in the detail zone. Returns True if changes are resolved.
<form>.ZCPIZoneCoord	Called by the master zone to coordinate any detail zones in the current form.
<form>.ZCPIEnable	Called by the master zone to enable or disable one or more detail zones in the current form.


Auto Query zone

A zone based on a module component where the Auto Query property is set to 'Yes'.

Also, if the Autoquery property is set to 'Default Behavior' and the Query property for all of the items within the module component are set to No (i.e. query dialog is not required), the zone will automatically be queried.


Context style zones (generated Visual Basic code )
Context-style zones (generated Visual Basic code)

Related Topics

Generated Routines

<zone>Clear

Clears the current zone controls and any detail zones. Basic tasks are:

•	Clear any detail zones (call <zone>ClearDetails)

•	Clear the current zone controls

•	Disable the appropriate database buttons

<zone>DeleteRow

Deletes the current record from the database. Basic tasks are:

•	Get the user to confirm the deletion

•	Build up the 'Where' clause, using the primary key value

•	Delete the row, using the built up 'Where' clause (ldDeleteRow)

On successful deletion, clear the zone (call <zone>Clear)

<zone>EnableDBBtns

Enables and disables those buttons that should be active only when there is a database row displayed.

Generated Events

Add button click

Displays the property sheet dialog to insert a new record. Basic tasks are:

•	Check no pending changes in any detail (<zone>CheckChanges)

•	Display the property sheet dialog in Insert mode, (via <zone>DlgInsert, the public interface routine on the property sheet dialog) passing in the primary key value

On successful insert (done by the property sheet dialog):

•	Clear the zone and any details

•	Copy values passed back from the property sheet dialog into the context controls

•	Call the <zone>Reposition routine to enable the appropriate button

Clear button click

An optional Clear button calls the <zone>CheckChanges routine to check for outstanding changes to details before calling the <zone>Clear routine to clear the zone.

Delete button click

Calls <zone>DeleteRow to delete the row from the database.

Query button click

Basic tasks are:

•	Check for outstanding changes to details, if necessary

•	Prompt the user for search criteria prior to querying the list (if the Query property of an item is set to Yes)

•	Build up the necessary 'where' clause

•	Display the List of Values dialog

If a row is selected then:

•	the zone is cleared (call <zone>Clear)

•	the controls are populated with the values obtained

•	call the <zone>Reposition routine to query any detail zones and enable the appropriate buttons

View button click

Displays the property sheet dialog to view or modify the current record. Basic tasks are:

•	Display the property sheet dialog in Insert mode (via <zone>DlgView, the public interface routine on the property sheet dialog) passing in the primary key value

On successful update (done by property sheet dialog):

•	Copy modified values, as passed back from the property sheet dialog, into the context controls


Form-style zones (generated Visual Basic code )

Related Topics

Keeping track of the current record

A form-level variable (mint<zone>_CurRecord) is used to note the number of the current record in the zone. Generally, this corresponds to (lst.ListIndex+1) of the zone's hidden List Box, and it is set to this value on the Reposition event. However, when the user tries to navigate from one record to another by clicking on a different list entry, the two will be different. So, on the list click event, the current ListIndex is compared with (<current record variable>-1) to prevent the unnecessary cost of clearing/requerying details, if the user has simply clicked on the same row.

On the list click event, the record number that the user has just selected is saved, and then ListIndex is programmatically reset back to what was the current record number (<current record variable>-1). This is to check for outstanding changes within the context of the previously current row. If everything is OK, the ListIndex is reset to the row to which the user is navigating.

Tracking when a record has been modified or a new record entered

A form-level variable (mb<zone>_RowModified) is used to track whether the user has made any changes to a new record or existing record. This is tested in the <zone>CheckChanges routine to denote whether there are any outstanding changes in the zone.

Zone states

A form-level variable (mstr<zone>RecordState) is used to record the zone's current state.

The zone's state variable is set via the <zone>SetState routine. There are four possible zone states:

NewRecord	New record entry state
DBRecord	A database record is currently displayed in the zone
NoRecord	No record is currently displayed in the zone
Disabled	All zone controls are disabled
NewRecord

Set when the user requests the entry of a new record from the New button click event. This will enable the Undo button and (if there is more than one record in the list) the GotoList button. Hence, the zone is in this state when a new record is being entered, and the zone contains other buffered records.

In the NewRecord state, the Undo button is initially enabled to allow the user to cancel the insert and return to the row previously displayed.

DBRecord

Set when the zone controls are populated with a database record from the Reposition routine. (This state is set on a query following a successful insert, when the user navigates between records, and whenever a record is displayed programmatically; e.g. after a deletion).

This will enable the Add, Query, and Clear buttons, plus the Navigation buttons, if appropriate.

NoRecord

When in this state the zone is ready for the entry of a new record (if zone allows insert) but is different from the NewRecord state in that the zone does not contain any buffered records. Hence the Undo button is not enabled until the user starts to enter data.

Disabled

All buttons and data controls are disabled. Set when the zone is to be disabled in the case where the master zone does not show a valid record. Set via the <zone>Clear routine when the parameter pbDisableThis is set.

Generated routines

<zone>AddRowToArray

Adds a new entry to the array(s) used to store the primary keys for the zone. It is responsible for creating and extending the arrays as required.

<zone>ChangesSet

Called when the user makes a change to one of the zone's bound controls to enable the Save/Undo buttons, and also to set the Row Modified flag.

This routine is also called to disable the buttons, in the <zone>Clear routine, the Undo button click event, and the Save button click event.

<zone>CheckChanges

Looks for outstanding user changes in either this zone or any detail zones, and returns True if there are none (i.e. zones may be cleared without losing any changes); otherwise False is returned if any outstanding changes have not been resolved.

<zone>Clear

Clears the zone. Basic tasks are:

•	Clear the zone by clearing the list and clearing down the arrays and other form-level variables used to store the primary key, current record number etc.

•	Call <zone>RecordClear to clear the data controls

•	Call <zone>SetState to set the zone to the appropriate state

•	Call <zone>ChangesSet to disable the Save and Undo buttons

<zone>CreateBaseDynaset

Creates a dynaset for database operations for the given table and stores the dynaset fields in a form-level object array. This array is later used within the <zone>SetCtrls routine to set the form's bound controls to display the appropriate fields. This is called from the form load event.

<zone>CreateLookupDynaset

Creates a dynaset for fetching data from lookup table(s). The dynaset's fields are then stored in a form-level object array. This array is later used within the <zone>SetCtrls routine to set the lookup controls to display the appropriate fields. This is called from the form load event.

<zone>DeleteRow

Deletes the current row from the database (using ldDeleteRow ), and from the list box. If the last row is deleted, the zone is cleared (call <zone>Clear); otherwise <zone>Reposition is called to display the previous/next record.

<zone>Insert

Adds the new row to the database. If the Insert is successful, the record is added to the List Box/primary key arrays. Basic tasks are:

•	Validate the user entry (<zone>Validate)

•	Add the row to the database

•	Add the row to the list

•	Reposition without querying detail zones

•	Get server-derived values (<zone>RecordFetch)

<zone>Query

Performs a query for the zone, returning True if row(s) found; else False. Triggers the <zone>Reposition routine by selecting the first row in the list, which in turn will populate the zone's controls.

Basic tasks are:

•	Build up SQL statement to:

−	Select primary key, plus the descriptive expression to display in the 'Goto Record' List Box

−	Where - joins between tables, links to parent, plus the 'Where' condition against the base table usage

•	Create a dynaset with the SQL statement

•	If no rows found, returns false

•	Populate the List Box and primary key arrays

•	Select the first item in the list which triggers the <zone>Reposition event for the first record

<zone>RecordClear

Responsible for clearing the data controls in the zone, thereby clearing the current record. It is called by the <zone>Clear routine and, also, prior to creating a new record (New button click).

<zone>RecordFetch

Queries and populates a record. Returns True if row fetched OK; otherwise reports the error and returns False. Basic tasks are:

•	Clear the 'bound' data controls in the zone via <zone>RecordClear

•	Perform a query of all the zone's columns where primary key = primary key values from the primary key array

•	Copy the database values into the zone's controls via <zone>SetCtrls

<zone>Reposition

This is a 'pseudo' event, designed to fire upon navigation to a database record.

Basic tasks are:

•	Set RecordNumber to (ListIndex+1)

•	Set the Record Status label (Record n of m)

•	Call <zone>RecordFetch, to query and set all of the zone's controls

•	ZoneCoordination - synchronize details

The "QueriedRecord" parameter indicates that the row moved to is a queried record rather than a newly created record.

<zone>SetCtrls

This routine sets the bound controls to the values obtained from the database. Called not only by <zone>RecordFetch, but also by the Undo event code to redisplay the record as it was before any changes. The database values are held in the dynaset fields.

<zone>SetState

Sets the zone to the given state by enabling/disabling the appropriate buttons and data controls, setting the record state flag and record indicator, and resetting the Row Modified flag.

<zone>Update

Updates the current record on the database. Basic tasks are:

•	Validate the user entry (<zone>Validate)

•	Lock the row (<zone>LockRow)

•	Update the row using the dynaset

•	Get server-defined values (<zone>RecordFetch)

•	Update the list entry

Generated events

Add button click

Basic tasks are:

•	Check for pending changes in this or any detail (<zone>CheckChanges)

•	Clear all detail zones (<zone>ClearDetails)

•	Clear the record (<zone>RecordClear)

•	Update the zone state (<zone>SetState)

Clear button click

An optional Clear button simply calls the <zone>Clear routine.

Click event on the (...)Goto Record button (Form layout style only)

Displays the list. If the user clicks on the button when the list is already displayed, the list is dismissed.

Delete button click

Calls <zone>DeleteRow to delete the row from the database.

List click

Please click here for details on how to keep track of the current record.

Next/Previous/First/Last button click (Form layout style only)

Updates the List Box's ListIndex, which triggers the List's Click event which handles the reposition/record fetch/setting the zone state, and so on.

Query button click

Basic tasks are:

•	Ensure no outstanding changes, if necessary

•	Call up query dialog (if there is one)

•	Run the query for the zone (calls <zone>Query)

The generated code will be significantly different, depending on whether there is a query dialog for the zone.

Save button click

Depending on the current state of the zone, this event calls either the <zone>Insert routine or the <zone>Update routine to save the user changes.

Undo button click

If there is an existing row, the dynaset values from the Query dynaset are recopied into the data controls. If this is a new row, either call <zone>Clear to set zone status to cleared (if no rows in the zone), otherwise call <zone>Reposition to make the ListIndex row the current one.


List-style zone (generated Visual Basic code)

Related Topics

Adding a record

The property sheet dialog is called as a modal form when a new record is added. When the OK button is pressed, the new record is committed on the database, and added to the list.

Any controls within the property sheet dialog that are based on foreign key columns that link back to the master are populated automatically, and disabled.

Modifying a record

When a row is modified, the property sheet dialog may be called either as a modal form, or non-modal, depending on the Make property sheet dialogs modal (PSDMOD) preference setting.

Non-modal allows multiple concurrent windows for different rows; however, the dialog and main windows will be independent and, therefore, changes to descriptive data will not be applied to the list box after an update via the dialog.

Any controls based on foreign key columns that link back to the master are disabled if the foreign key is not transferable, or they are enabled to allow a change of master. In the latter case, the dialog must be called as a modal form if a change of master is to remove the detail from the list in the main form.

Resizing

If a List zone is the last zone in the window, code is added to resize the list and move objects on the form resize event.

Generated routines

<zone>AddRowToArray

Adds a new entry to the array(s) used to store the primary keys for the zone. It is responsible for creating and extending the arrays as required.

<zone>Clear

Clears the zone by clearing the following:

•	list box

•	form-level arrays used to store the primary key

•	current record flag

•	record status label

It also disables the appropriate buttons.

<zone>DeleteRow

Deletes the currently selected record(s) from the database and the list box. Basic tasks are:

•	Get the user to confirm the deletion

•	Build the where clause and creates the parameters for the primary key, using the value held in the primary key array

•	Delete the row using the constructed 'Where' clause (call ldDeleteRow)

•	If the zone is 'Sequence to Parent', the sequence values below the deleted row(s) are updated on the database and in the mirroring array

•	If the sequence is displayed in the list, the list entries are updated accordingly

•	If the last row is deleted, the zone is cleared (call <zone>Clear); otherwise the nearest row is selected (that is, the one above the last one to be deleted) This in turn triggers the <zone>Reposition so that any detail zones are requeried for the new record.

<zone>EnableDBBtns

Enables/disables those buttons that should be active only when there is a database row selected.

<zone>Query

Performs a query for the zone. Returns True if row(s) found; else False. Triggers the Reposition routine by selecting the first row in the list in order to query any related detail zones.

<zone>Reposition

Called whenever a database row is made current. Basic tasks are:

•	Copy primary key value from the array to hidden controls (for use by the property sheet dialog and any detail zones)

•	Enable the appropriate buttons (call <zone>EnableDBBtns)

•	Refresh the record status label

•	Coordinate any detail zones

Generated events

Code is generated to initiate the standard database functions against the base table of the zone from buttons copied in from the template. This code interfaces with property sheet and query dialogs for Insert, Update, and Query operations.

Add button click

Displays the property sheet dialog to insert a new record by calling the public interface routine <zone>DlgInsert on the property sheet dialog after checking that there are no pending changes in any detail zone (<zone>CheckChanges).

If a row was inserted in the dialog, it then clears any details and adds the new row to the list and to the form-level primary key array.

Clear button click

An optional Clear button calls the <zone>CheckChanges routine to check for outstanding changes to details before calling the <zone>Clear routine to clear the zone.

Delete button click

Calls <zone>DeleteRow to delete the row from the database.

List click

Please click here for details on how to keep track of the current record.

List DblClick

Selects the View button by setting its value to True.

Query button click

Ensures no outstanding changes, if necessary, calls up query dialog (if there is one), and then runs the query for the zone (calls <zone>Query).

Resequence Up/Down button click

Basic tasks are:

•	Save the sequence values of the current row, plus the previous/next row

•	Build up the 'Where' clause and create parameters for the primary key and the two sequence values

•	Swap the 'sequence to parent' values on the database for the current row, and the previous/next rows

•	Rebuild the list and array entries for the altered sequence values

•	Select the row being resequenced, in its new position

•	Refresh the record status label

View button click

Displays the property sheet dialog to view or modify the current record by calling the public interface routine <zone>DlgView on the property sheet dialog. If a row was updated, the list entry is updated to reflect any modification. If the foreign key value has been changed, the row is removed from the list.


List/Form-style zones (generated Visual Basic code)

Related Topics

The List/Form layout style is similar to the Form style, except that a list box displays a set of queried records alongside a single-record view of the currently selected record. In List/Form zones:

•	the list is permanently displayed

•	there are no navigation buttons in the template

•	if the zone has a 'Sequence In Parent' column, it will have resequence up/down buttons (see below)

Resequence Up/Down button click

Basic tasks are:

•	Check for pending changes in this or any detail (<zone>CheckChanges)

•	Save the sequence values of the current/previous/next row

•	Build up the 'Where' clause and create parameters for the primary key and the two sequence values

•	Swap the 'sequence to parent' values on the database for the current/previous/next rows

•	Rebuild the list and array entries for the altered sequence values

•	Select the row that has moved up/down

•	Refresh the record status label

•	Recreate the query dynaset for the modified record (<zone>RecordFetch)


Property sheet dialogs (generated Visual Basic code)

Related Topics

Modality

The property sheet dialog is called as either a modal or non-modal form, according to these rules:

Layout Style	Database Operation	PSDMOD Preference	Modality
Context	n/a	n/a	Modal
List	Insert	n/a	Modal
List	Update	Yes	Modal
List	Update	No	Non-modal
If the dialog box is non-modal, multiple instances of the form may be invoked to allow different records to be compared. However, there is no synchronization with the main window; changes in the dialog will not be reflected in the main window, and indeed the main window may be closed independently of the property sheet dialog. Therefore, if synchronization is important for a particular application, the Make property sheet dialogs modal (PSDMOD) preference must be set to Yes.

Note:	Modal dialogs will be used in MDI applications i.e. where an MDI Parent form is included in the template project.

Generated form

A single form is used for creation and for update purposes. This provides a consistent interface for both operations. However, two different public interface routines are created in the property sheet dialog to provide the interface to the dialog, because the parameters involved and the functionality are significantly different.

Note:	Detail zones are always placed on the main form, not on the master zone's property sheet dialog.

Handling foreign key to master zones

When the property sheet dialog is displayed for the creation of new records in a detail zone, any controls based on foreign key columns that link back to a master are populated automatically. If they are visible and updateable, they are disabled. This ensures that the new row to be created is within the context of the current master on the main form.

When the property sheet dialog is displayed to update an existing record, any controls based on foreign key columns that link back to a master, and that are defined as visible and enterable via the item, may be used to change the master. If the user changes the master (and the form was called modally), the main form is notified so that the source List zone can remove it from the list.

Public routines added to the Property Sheet Dialog Form

<zone>DlgInsert

A public interface function used by the calling form. It sets up and displays the property sheet dialog ready for the user to insert a new record. It is called by the Add button click event of that zone. Basic tasks are:

•	Pass in the input parameters to tell the property sheet dialog what mode it is to be set to (i.e. "INSERT"), and the caption to display, etc.

•	Display the dialog

After the dialog has been dismissed, if the user pressed either OK or Apply Now, followed by Cancel, then the routine returns the new primary key and any values to be displayed in the zone.

<zone>DlgView

A public interface function used by the calling form. It sets up and displays the property sheet dialog to enable the user to view and modify the current record.

The dialog is displayed as modal or non-modal, depending on the Make property sheet dialogs modal (PSDMOD) preference. It is called by the View button click event of that zone. Basic tasks are:

•	Pass in the input parameters to tell the property sheet dialog the row's primary key value, what mode it is to be set to (i.e. "VIEW"), and the caption to display, etc.

•	Display the dialog

After the dialog has been dismissed (for modal dialogs only), if the user pressed either OK or Apply Now, followed by Cancel, then the routine returns the modified record values to be displayed in the zone.

Private Routines added to the Property Sheet Dialog Form

<zone>ChangesClear

Disables the OK, Apply Now, and Undo buttons to prevent the insert/update operation when no changes have been made. This routine is called from the DlgView and DlgInsert routines to prepare the property sheet dialog when it is initially displayed, within the <zone>UndoRecord routine and on the Apply Now button click event.

<zone>ChangesSet

Enables the OK, Apply Now, and Undo buttons. This routine is called on the change event of each data control, to allow the user to save/undo the changes.

<zone>Clear

Clears all the controls on the property sheet dialog and applies any default values. This routine is called from the DlgView and DlgInsert routines to prepare the property sheet dialog when it is initially displayed, and by the Undo Button click event (<zone>UndoRecord) when the dialog is in Insert mode.

<zone>CreateBaseDynaset

Creates a dynaset for database operations for the dialog's underlying table and stores the fields in a form-level object array. This array is later used within the <zone>SetCtrls routine to set the forms bound controls to display the appropriate fields. This is called from the DlgView and DlgInsert routines to prepare the property sheet dialog when it is initially created.

<zone>CreateLookupDynaset

Creates a dynaset for fetching data from the zone's lookup table(s). The dynaset's fields are then stored in a form-level object array. This array is later used within the <zone>SetCtrls routine to set the lookup controls to display the appropriate fields. This is called from the DlgView and DlgInsert routines to prepare the property sheet dialog when it is initially created.

<zone>Insert

Adds the new row to the database. Basic tasks are:

•	Validate the user entry (Validate event)

•	Start database transaction

•	Call the PreInsert event

•	Add the row to the database

•	Call the PostInsert event

•	Commit the transaction

•	Get server-defined values (<zone>RecordFetch)

<zone>RecordFetch

Fetches the record from the database by refreshing the dynaset(s) using the given primary key value. Then calls <zone>SetCtrls to populate the property sheet dialog controls with the dynaset field values.

<zone>SetCtrls

Sets the bound controls to the dynaset field values obtained from the database. Called not only by <zone>RecordFetch, but also by the <zone>UndoRecord event code to redisplay the record as it was before any changes.

<zone>UndoRecord

Asks the user to confirm the undo. On confirmation, if the property sheet dialog is in Insert mode, the controls are cleared (call <zone>Clear); else, if in update mode, the controls are set back to their original values (call <zone>SetCtrls). Finally the action buttons (Save/Undo) are disabled.

<zone>Update

Updates the current record on the database. Basic tasks are:

•	Validate the user entry (Validate event)

•	Start the database transaction

•	Call the PreUpdate event

•	Lock the row (call <zone>LockRow)

•	Update the row using the dynaset

•	Commit the transaction

•	Get server-defined values (<zone>RecordFetch)

Events added to the property sheet dialog form

OK button click

Calls the <zone>Insert routine or the <zone>Update routine to save the user changes, as appropriate. Control is then passed back to the calling form.

Apply Now button click

Similar to the OK button, this calls the <zone>Insert or the <zone>Update routine to save the user changes as appropriate. However, unlike the OK button, the property sheet dialog is left open so the user can continue to view or modify the record, and the action buttons are disabled until further changes are made (call <zone>ChangesClear). If the dialog was originally displayed for insert, and the user selects the Apply Now button, the record is saved and the dialog is set to update mode.

Cancel button click

Dismisses the dialog without performing any action.

Close button click

Dismisses the dialog without performing any action.

Undo button click

Calls <zone>UndoRecord.


Query Dialogs (generated Visual Basic code)

Related Topics

A query dialog provides the mechanism for defining search criteria used to qualify the query for a particular zone. It is a modal dialog, through which you may enter query criteria across one or more columns of the zone's data source. As with the zone on which it is based, the query dialog may include controls derived from lookup items, and these controls can contribute to the query criteria.

When the user dismisses the query dialog, it is hidden but not unloaded so that the next time the dialog is invoked, the last entered criteria are displayed. To enter different criteria, the user can either modify the criteria as displayed, or use the Clear button to remove the existing criteria and then type in the new query criteria.

Generated controls

The controls displayed in the query dialog created for a specific zone are those whose item's Query property is set (Yes). If no items are so defined, (and the module component's Query property is set), no query dialog is created and the Query button for the zone performs an unrestricted query.

For each item in the zone that has the Query property set, an interface will be provided in the query dialog for the user to enter selection criteria for the underlying column. This interface will take one of two forms:

•	a single control through which users may define equality or wildcard searches

•	a pair of controls (or twin controls), through which the user may define upper-bound, lower-bound, or range searches. By default, a range pair of controls is created if:

−	the item is based on a numeric or date column and

−	the underlying column does not form part of any primary, foreign, or unique key and

−	the underlying column is not constrained by a fixed set of values

Note: 	You can override this default behavior by setting the Range Search property against the item.

Single control

Where a single control is created, its type will be based on the type of control in the main zone, or in the main zone's property sheet dialog. For example, if a column in a zone is represented by a checkbox, then a checkbox will be also created in the query dialog to allow query on that column. But, if the control type in the main form is read-only (such as, Label or Gauge), then a Text Box will be used. The suitability of a control is governed by the DontAllowInQueryDialog entry in the control definition file.

For text-based controls, the entry of "IS NULL" in the query control will imply a search for NULL values (col IS NULL) while the entry of a "" or "*" in the query control will imply a wildcard search (col LIKE a). In other cases, the equality operator will be used (col = a).

For non text-based controls, the Generator will attempt to provide a mechanism to allow a search for NULL values, depending on the type of control.

Twin controls

Twin controls are always of type TextBox. If the controls are both given a different value, a range search (col between a and b) is implied.

If the first control is given a value and the second control is left blank, a lower-bound search is implied (col >= a), unless the control's value is either "IS NULL", or contains a "" or "*" in which case the behavior is the same as for a Single control).

If the second control is given a value and the first control is left blank, an upper-bound search is implied (col <= a).

If both controls are given the same value, an equality search is implied.

Template form

As with other generated windows, a form in the template project is used as the basis for creating any new query dialog forms. The form that applies to query dialogs is named CGTWQd .

If present in the CGTCControls template form, controls named "<base control type>QD" will be used to define the look and feel of controls in the query dialog; for example, TextBoxQD, FrameQD, ComboBoxQD, and CheckBoxQD. If they are not present, the base versions will be used.

Generated Buttons

The query dialog buttons are:

OK	Passes control back to the main form from where the query is executed, based on the given criteria.
Cancel	Dismisses the dialog, and passes control back to the main form without performing any action.
Clear	Clears all the controls, ready for the user to enter a new query.
New	Applies only if it appears in the template, and if Insert is allowed. Acts in the same way as Cancel but, once back in the main form, puts the user into 'Add New Record' mode. This might, for example, trigger a property sheet dialog for the insertion of a new record.
Routines added to the Query Dialog Form

<zone>DlgQuery

This is a public interface routine used by the calling form. Two parameters are passed back by this routine, representing:

•	the action taken by the user

•	the string built by the BuildWhere() routine

BuildWhere

This routine is responsible for building the WHERE clause from the values specified in the controls. The routines lgQDAddPredEqual and lgQDAddPredRange in lg.bas are used to build the WHERE clause predicate for columns represented as Single and Pairs of controls respectively.


Known restrictions and limitations for Visual Basic Generator

The following restrictions and limitations apply in the current release of Visual Basic Generator.

Database design

Table constraints

Visual Basic Generator does not generate code into the application to enforce constraints; it is assumed that the server handles this. However, the Generator does add generated code to trap Oracle server errors, and it can then convert these into meaningful user messages.

Column-level check constraints

It is not possible to record the name of a column-level check constraint in the repository. Hence no code will be generated to trap column-level check constraint violations.

Validation against multiple ranges

Validation of a column value against multiple ranges is NOT supported in release 2 onwards.

Denormalization

Generation of code to handle data denormalization is NOT supported in release 2 onwards.

View definitions

You can use view definitions instead of table definitions to define table usages. But if a view is defined as being used by a module, the properties of the underlying tables - such as key definitions, lists of valid values, column autogeneration, and so on - are NOT inherited by the view. Views and their columns must therefore be given the same attributes as the tables they are defined on so that the Generator can add the required code.

In addition, if a view is defined as 'SELECT * ...', no columns are defined in the repository and hence none are visible to the Generator. In this case, modules cannot contain a usage of the view.

Module design

Module element name restrictions

The following module element name restrictions apply:

•	Module Implementation Name is limited to a maximum of 6 characters if you are generating an application for a 16bit environment as filenames are restricted to 8 characters. If you set the Maximum File Name Length Restriction option prior to generation Visual Basic Generator will check that all the names of generated files do not exceed 8 characters.

•	Module Component Name is limited to a maximum of 10 characters.

•	Item Name is limited to a maximum of 30 characters.

Unbound items

Visual Basic Generator only supports custom unbound items.

Use of ListBox/ComboBox controls for data entry

The use of List style controls for foreign key validation is NOT supported in release 2 onwards. List style controls may however, be used for columns with an associated list of valid values (either static or dynamic).

Third-Party Controls

Controls Not Supported

Support for third-party OCX controls is limited to those controls that can represent a single atomic value and whose characteristics may be adequately defined in the control definition file.

Specifically, the following types of controls are NOT supported in release 2 onwards:

•	grid style controls

•	list style controls that do not support the standard methods and properties available in Visual Basic's native listbox control

•	support for generation of tabbed stacking areas is limited to the use of the SSTAB OCX control

Control Name Prefixes

The ControlNamePrefix (from the control definition file) is limited to 3 characters.


Sample Context layout style


Sample Form layout style


Sample List layout style


Sample List/Form layout style


Sample property sheet dialog


Sample query dialog


current working directory

By default this is the working directory of the program item used to start Oracle Designer (\ORANT\BIN, or \ORAWIN95\BIN).


About Help files for Visual Basic applications

You may optionally record help text alongside the module design definitions within the repository. Such text can then be used to provide context-sensitive online help for generated Visual Basic applications. About

A Windows Help file can be generated for a single module, a group of modules (within a module subsystem), or for an entire module network. Help topics within the Help file can be made available to the generated application at form, zone, and control level.

Note:	All the modules that form a single Visual Basic application (project file) must be described in the same help file. This means that the top-level module for the Help file must be the same module as the top-level module in the Visual Basic application (or a module higher up in the module network).

Entering help text

Typically, you use Design Editor to design and generate the modules which make up your generated Visual Basic application. At the same time, you can record help text (and any required keywords) against the following repository elements:

•	module definitions

•	module components

•	item groups

•	items

Generating the Windows Help file

Once your help text has been entered, you can generate a Windows Help file. To do this, you use MS Help Generator to extract the Help text and transform it into a Windows Help project.

Note:	You must generate the Visual Basic application again after generating the Help file so that context-sensitive help-ids can be incorporated within the Visual Basic application

Accessing Help from the generated application

Help menu items

Help menu items are included on the default template and hence are generated automatically. Two menu options are provided:

•	Contents, which opens the associated help file on its contents topic

•	Search for Help on... which allows index-based access to relevant help topics

Context-sensitive entry via the F1 key

A context-id is built up and held against each data entry control that has a HelpContextId property. These ids define the entry point and location of help text recorded against corresponding items.

In addition, a context-id is built up against each window to define the entry point and location of help text recorded against corresponding module component.

Location of the Help files

Typically Help files are located in the same directory as their Windows application. However, you may set up your Visual Basic application to look in a different location for the Help file at runtime, by setting the 'HelpFilePath' parameter in vbgr.ini (16 bit) or system registry (32 bit).

Note:	In addition to the Help File Path, vbgr.ini allows you to set other properties which relate to the end-user, runtime environment e.g. Auto Commit Changes, Hint Text Delay etc.


About keyboard navigation in Visual Basic applications

Related Topics

Generated applications include certain features that facilitate efficient keyboard operation:

Mnemonic access characters	Individual letters are underscored within generated control prompts to provide the ALT+mnemonic method for navigation purposes.
Autohighlighting text box contents	Text box contents are auto-selected when the user navigates into the text box via the keyboard.
Use of the tab key	The tab order of the generated controls is set to provide a suitable navigation order when the user moves between the controls using the Tab key. Code is added to provide auto-switching between stacking areas when the user navigates into an area not currently visible.
Mnemonic access characters

Mnemonics that exist on controls read from the template are preserved when copied into the generated application. The Generator can also add mnemonics to generated controls and this is controlled by a set of Visual Basic mnemonic access preferences.

For more information see About mnemonic access keys for controls

Autohighlighting text box contents

Generated code is added to the GotFocus event of Text Box style controls that are used for data entry such that the control's value is automatically selected on entry into the control.

Use of the tab key

The tab order of all the generated controls is set so that:

•	there is a suitable navigation order when the user moves between the controls using the Tab key

•	each control is sequenced after its associated caption label control

•	for controls that are read in from the template, the tab order is allocated in the same sequence as the controls lie in the Z order

Stacking area containing radio buttons

Upon navigation to a control on a different (currently hidden) stacked frame via the Tab key, code is generated so that the frame is automatically brought to the front. Code is also added to the radio buttons that control switching between the stacking areas in order to:

•	ensure the stacking area associated with the control is brought to the front when the user clicks the radio button

•	set the focus to the first enterable control within the stacking area

Stacking area containing tab controls

Code is added to the click event of the tab control in order to:

•	ensure the tab associated with the control is brought to the front when the user clicks on that tab

•	set the focus to the first enterable control within the tab


About menu generation in Visual Basic applications

Menu items may be generated to enable the user to navigate between different components of a generated application. Menus are created for each action item (navigation or custom) if the Create Menu? property is set to Yes. Preferences are used to define which top-level menu the items are added to.

The navigation action items allow navigation:

•	between two different modules

−	module network exists (called modules)

−	key based link exists between two module components in a different modules

•	to a module component in the same module (but on a different window)

Module network links (called modules)

The Generator treats each module navigation action item as a requirement to allow the user to navigate from the current module or form to another component of the overall generated application.

The invocation code required to call the module at the other end of the link may be defined against the called module's command line property:

•	If no command line is specified, and the called module is a Visual Basic module, the code to load and display the form as a non-modal window will be generated.

•	If no command line is specified, and the called module is not a Visual Basic module, a warning is issued.

•	If a command line is specified, it is assumed to be a valid Visual Basic statement (such as, "Dim x As Integer: x = Shell("calc", 1) "), and is used to call the other module.

To allow navigation between Visual Basic modules, these modules must be generated into a single Visual Basic project. To achieve this, generate your top-level module using the 'Create New Visual Basic Project' option in the Generate Visual Basic dialog, and select the 'Include the module network?' checkbox. This will generate the entire module network, using the first window of the top-level module as the 'Startup Form'.

If, following generation, one of the modules in the network is modified in the repository, you do not need to generate the entire module network again. Instead, you specify the 'Add module to existing Visual Basic project' option at generation time which merges the modified module into the specified Visual Basic project.

Note:	If a module has no module components, but has module navigation action items to link to other modules, the module is implemented as a form consisting solely of buttons and/or menu items for navigation. Such forms are called launch screens.

Zone coordination

Navigation may be required if master and detail zones are held on separate windows, either in the same or different modules. Here, zone coordination generates code both for the menu item created and for any required buttons. The two windows and the key based link between them, are set up visually in the Design Editor.

Template menu preferences

The location of the generated menu items is governed by the menus defined on template windows, such as CGTWFirst.

The menu created for zone coordination items may be different from the menu for module network entries, as defined by the following preferences:

TFMNMN	Specifies the name of the template menu where menu items sourced from module network entries will be placed i.e. module navigation action items.
TFMNZC	Specifies the name of the template menu where menu items required for zone coordination will be placed i.e. module component navigation action items.
TFMNCA	Specifies the name of the template menu where menu items for custom action items will be placed.
If the template menu item has a caption, then generated menu items are added to it as child menu items. If it has no caption, then it is treated as a placeholder; generated menu items are merged in at its location.

Generated code

The Generator generates invocation code for the Click event of the menu items and buttons that perform the navigation.

Navigation Action Items	If a menu contains items that apply only where a row is present in the item's corresponding zone, code to dynamically enable or disable any such menu item is generated onto the Click event of the item's parent menu.
Custom Action Items	The Enable on Database Record property can be used to indicate whether code should be added to enable or disable menu items depending on whether a row is present.
Multi-level menus

You can also define Menu modules in the module network if you wish. Menu modules allow you to group several module links together under a single menu option and this results in the generation of multi-level cascading menus. How

In the example below a Menu module has been added to the module network to group together two administration screens (Adverts and Third Parties). The caption for each menu item is derived from the Short Title property of the called modules.


Generate Visual Basic dialog box

You can use Visual Basic Generator to generate a Visual Basic application from module design specifications held in the repository. For more information, refer to The Visual Basic application design process

Use this dialog box to generate a new Visual Basic project from the selected module (or module network), or update an existing Visual Basic project.

Module

Displays the Short Name of the module selected for generation.

Generate Option

To generate a new Visual Basic project or update an existing one, click the appropriate Generate Option.

Create new Visual Basic project

To generate a new Visual Basic project for the chosen module, click Create new Visual Basic project.

Note: The name of the new project is derived from the module Implementation Name. Any existing files with the same name will be overwritten.

Include the module network in this project

To generate a Visual Basic application for the whole module network starting from the chosen module, select the Include the module network checkbox.

Do not select this checkbox if you want to create a standalone (temporary) application for a single module, for testing purposes.

Add module to existing Visual Basic project

To include files generated from this module within an existing Visual Basic project, click Add module to existing Visual Basic project.

Project

To specify a target Visual Basic project for files generated from this module, enter the name and location of the project file (.VBP). Alternatively, click Browse to select the name of the project file you require.

Runtime database user password

To run the application after generation, enter the password for the runtime database user. This field is only active if the Name and Connect String of the Runtime Database User is defined on the Visual Basic Generator Options dialog box. Click Options to open this dialog box.

Post Generation

Use the Post Generation options to specify what happens when generation is complete.

Post Generation - Commit

Select this option to update repository objects when generation is complete.

Note that there are some circumstances when Visual Basic Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture?.

Post Generation - Revert

Select this option if you do not want to update repository objects with the property settings used during generation.

Post Generation - Browse/Edit mode

Select this option to activate Post Processing Mode, which enables you to choose how to process proposed repository changes.

For more information about Post Processing Mode, refer to About the Design Editor Post Processing Mode.


Visual Basic Generator Options dialog
Visual Basic Generator Options dialog box

Before running Visual Basic Generator you can set options that affect Visual Basic generation. How

Use this dialog box to specify:

•	the location of files required during generation

•	where Visual Basic Generator saves generated files

•	the data access method

•	the runtime database user for the application

For a step-by step guide on how to use Visual Basic Generator, refer to the Visual Basic application design process.

Source

These options enable you to specify the location of files required during generation.

File System

Select this option if you want those files that are required during generation to be retrieved from the filesystem and not from the repository.

Repository

Select this option if you want those files that are required during generation to be retrieved from the repository and synchronized with files in the filesystem before being used.

For more information about storing source files in the repository, refer to About storing files in the repository for use during generation.

Repository Folders

Specify the repository folder containing the files required during generation. To specify multiple folders, separate the folder names with commas. Multiple folders are searched in the order in which you specify them.

For more information about storing source files in the repository, refer to About storing files in the repository for use during generation.

Target

These options enable you to specify where generated files are stored.

Destination of generated files

To save generated files in a specific directory on the filesystem, enter the drive and directory you require. Alternatively, click Browse to select the location.

If no location is specified, generated files are saved to the working directory of the program item or shortcut used to start Oracle Designer. The default location is <ORACLE_HOME>\BIN\

Upload generated files to repository

To save generated files in the repository folder mapped to the directory specified in the Destination of generated files field, check this checkbox. If a repository folder is not mapped to the specified directory, the file is not saved in the repository.

For more information about saving generated files in the repository, refer to About storing generated files in the repository after generation.

Data Access Method

To define how the generated application interacts with the runtime database, click the Data Access Method you require.

Oracle Objects for OLE

To specify that the generated Visual Basic application must use Oracle Objects for OLE to run against an Oracle database, click Oracle Objects for OLE.

Data Access Objects

To specify that the generated Visual Basic application must use the Data Access Objects (DAO) to interact with the database, click Data Access Objects. If you select this option you will also need to:

•	Ensure an ODBC driver for the target database is installed. How

•	Ensure a data source is set up for the required database. How

Runtime Database User

Name

To pre-define the database logon used to run the Visual Basic application after generation, enter the Name of the runtime database user.

The password can either be entered here (e.g. scott/tiger) or, if security is an issue it can be omitted and entered prior to generation from the Generate Visual Basic dialog box instead.

Connect String

Enter the Connect String associated with the runtime database user.


Capture Visual Basic Design dialog
Capture Visual Basic Design dialog box

You can use design capture to transform Visual Basic projects into design specifications held in the repository. For more information, refer to The Visual Basic project capture process

Use this dialog box to set options that affect the capture of a Visual Basic project.

Target container

Specifies the container into which to capture the Visual Basic project.

Visual Basic Project File

To identify the Visual Basic application you want to capture, enter the name and location of the project file (.VBP). Alternatively, click Browse to select the name of the Visual Basic project file you require.

Create one module for each form

To create one module in the repository for each form in the Visual Basic project, click Create one module for each form.

Create single module for entire Project

To create a single module in the repository that represents the entire Visual Basic project, click Create single module for entire Project.

Define mapping from forms to modules

To map individual forms in the Visual Basic project to new modules in the repository, click Define mapping from forms to modules.

Mapping

Displays the forms in the Visual Basic project.

To map a form in the Visual Basic project to a module in the repository, enter an appropriate Module Short Name. A module will be created with the Short Name defined here.

Multiple forms may be mapped to the same module if required. If no module is required for a particular form, do not enter a Module Short Name.

To populate this table, click Define mapping from forms to modules.

Startup Form

To identify which Visual Basic form should be used as the 'startup form' in the generated project, select a form from the dropdown list.

Capture report file

To create a report detailing which objects have been captured, specify a file name and location. If you do not specify a name, no file is created.

Additional Containers

Use this field to specify additional containers in which to locate objects referenced by the project being captured. Use a comma to separate container names.

Visual Basic Generator captures the project into the specified target container. If the objects being captured refer to other objects (e.g. tables, languages, attached libraries, reusable module components) that are not in the target container, Visual Basic Generator attempts to locate the referenced objects by searching the specified additional containers.

Note the following:

•	Visual Basic Generator does not update or create referenced objects in additional containers during design capture.

•	Referenced objects must be visible in the current workarea.

•	Visual Basic Generator searches for referenced objects in the additional containers in the order in which you enter the containers in the field.

•	If referenced tables and languages do not exist in either the target container or the additional containers, Visual Basic Generator is unable to capture the project.

•	If referenced reusable module components do not exist in either the target container or the additional containers, Visual Basic Generator captures the project and creates new reusable module components in the target container.

•	If referenced attached libraries do not exist in either the target container or the additional containers, Visual Basic Generator captures the project but does not capture or create the attachment.

Additional Containers - Browse button

To search for the container containing referenced objects, click Browse.

Post Capture

Use the Post Capture options to specify what happens when design capture is complete.

Post Capture - Commit

Select this option to update repository objects when design capture is complete.

Note that there are some circumstances when Visual Basic Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture?.

Post Capture - Browse/Edit mode

Select this option to activate Post Processing Mode, which enables you to choose how to process proposed repository changes.

For more information about Post Processing Mode, refer to About the Design Editor Post Processing Mode.

Create on Diagram after Capture

To display the captured application on a Module Diagram, click Create on Diagram after Capture.

Previous Settings button

To revert to the last saved version of these settings, click Previous Settings.


Visual Basic Recover Application Logic dialog
Capture Visual Basic Application Logic dialog box

You can capture modifications to generated Visual Basic code and save the changes back to the repository (where it is held against the appropriate Visual Basic module element). How

Use this dialog box to set options that affect the capture of application logic from a generated Visual Basic project.

Target container

Displays the container into which to capture the application logic.

Module Short Name

Displays the Short Name of the selected module. Application logic will be captured for this module.

Capture Module Network

To capture application logic for the whole module network starting from the chosen module, select the Capture Module Network checkbox.

Visual Basic Project File

To identify the Visual Basic project that contains application logic you want to capture, enter the name and location of the project file (.VBP). Alternatively, click Browse to select the name of the Visual Basic project file you require.

Post Capture

Use the Post Capture options to specify what happens when application logic capture is complete.

Post Capture - Commit

Select this option to update repository objects when application logic capture is complete.

Note that there are some circumstances when Visual Basic Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture?.

Post Capture - Browse/Edit mode

Select this option to activate Post Processing Mode, which enables you to choose how to process proposed repository changes.

For more information about Post Processing Mode, refer to About the Design Editor Post Processing Mode.


Mandatory, 30 characters
The name of the table. The name must be unique and must not contain any embedded spaces. Words can be separated by underscores.


Optional, 10 characters
A short, unique alias name for the table. Typically, you use the initial letters of words in the table name to define the alias. For example, CUSTOMER_ADDRESSES would take the alias CA.

This property provides a default table usage alias when defining a module. In turn, the table usage alias is used within the FROM clause in generated SQL statements. It is also used to name generated objects.


Optional, 132 characters
Used to default the module component Title property when a base table usage is created on a module. In turn, the title is used as the title on frames that contain generated zones.


Optional

Default help text to be displayed by the generated application. The information that is displayed can be modified when defining modules.


Mandatory, 30 characters
A unique name for the column. The name must not contain any embedded spaces. Words can be separated by underscores.


Optional

The name of an existing domain to which this column belongs. If the column has been derived from an attribute in a domain, this field displays the name of that domain. Domains allow you to define a common set of allowable values which can be reused across multiple columns e.g. Y/N for flag columns.

When you associate a column with a domain, the column datatype and length fields are inherited from the domain definition. [ Note: If you change the column datatype, maximum length or valid values when it is associated with a domain, the column properties will override those defined at the domain-level.]


Optional, 5 digits
The maximum length of data that the column can contain. This field must be completed for datatypes other than DATE.

Validation code is generated onto controls based on this column to check (during data entry) that the length defined here is not exceeded.


Optional, 2 digits
The number of decimal places allowed for the column. This is only applicable to columns of the type NUMBER and DECIMAL.

If defined, validation code is generated onto controls based on this column to check (during data entry) that the number of decimal places defined here is not exceeded.


If set to Yes, code is generated onto controls based on this column to convert the value entered by the user to uppercase.

If set to No, mixed case values can be entered for the column.


Optional

The name of a sequence used to create unique values for this column when a row is inserted in the database table. If specified, code is generated to derive a unique value for the column when new rows are created. Sequence values may be sourced from a code controls table or an Oracle sequence.

Typically, sequences are used to provide unique values for Primary Key columns.


Indicates whether any items based on the column will normally be displayed in the generated application.


Specifies the default display type for items based on this column.


Optional, 5 digits
For text-based controls, this specifies the default number of characters to be displayed.

If you use a format mask, you should increase the display length by 1 character greater than the length of the format, to enable the whole field to be displayed.


Optional, 6 digits
Specifies the default number of lines in a multi-line text control.


Optional, 6 digits
Specifies the default order in which the columns should appear in the generated application.

Tip: 	You can revise this order after items have been specified for a module, by dragging and dropping the columns into a different order on a module diagram.


Optional, 132 characters
Specifies the default prompt that accompanies generated controls.


Optional, 132 characters
Specifies default hint text for generated controls.


Optional, 3 digits
Specifies the default sort order, when querying rows. If set, the column appears within the generated ORDER BY clause within SQL statements that query from this table.


Specifies that the column is to be used in the generated application as a descriptor column for the table (instead of the primary key). Descriptor columns appear in the generated list boxes when no items are marked 'Context' in the module design.


Optional, dropdown list
Determines how the column's value is to be automatically populated via generated code.


Optional, 70 characters

A user-defined error message to be issued instead of the default error message when data is entered that violates this constraint. In the absence of a user-defined error message, a default error message will be issued incorporating the column prompt.


Should be set to 'Server' or 'Both' so that Server Generator will create the required constraint on the server.

Note:	Do not set this property to 'Client' if you are generating Visual Basic applications; otherwise, a warning will be issued indicating that constraint will not be validated.

In the current release, it is not possible to record in the repository the name of a column-level check constraint. Hence no code will be generated to trap column-level check constraint violations.


Visual Basic Generator does not make use of this property.


Indicates whether, at runtime, the value of a column is validated against a soft-coded database table, rather than being checked against a list of values that has been hardcoded in the generated code. This property is applicable when the column has valid values defined directly against it (using the Value and High Value properties), as opposed to being in a domain.[ only the predefined list of values can be entered in the column]

Yes	Indicates that the value of a column is validated against a soft-coded database table. This means that the list of allowable values is to be loaded into a reference codes table (CG_REF_CODES).

No 	(Default) Indicates that the values are hardcoded in the generated application and are validated from there.


Indicates whether the list of allowable values (defined either against the column or against an associated domain) is used at runtime as a suggestion list, rather than a list that strictly enforces the column's value. [You can enter values other than those in the list.]

Yes	Indicates that the list of allowable values is used as a suggestion list.

No 	(Default) indicates that the list values are enforced.

This setting is primarily required if you want to implement an item with a combo-box. See Creating a combo box for a suggested list of values.


Mandatory, 40 characters
Defines the allowable values permitted in the column. When defining values, you can specify either of the following:

•	a single range, where you record the low value via Value, and the high value via High Value e.g: a percent column might have a range from 0 to 100

If a single range is defined against a column, then the low and high values may be used to set the generated control's MinProp and MaxProp properties. If those properties are absent, the low and high values are used when adding validation code.

•	 a set of valid values, where you define the Value and (optionally) the Meaning for each valid value.

Note:	Validation against multiple ranges is NOT supported in the current release.


Optional, 40 characters
Specifies a high value for the column, if a high/low range is being defined.


Optional, 60 characters
The full meaning of the value specified. The use of Meaning depends on the control style being used:

If the Display Type is Pop List, Radio Group (Across), Radio Group (Down) or Text List and the Show Meaning property is set to Yes, the meaning is displayed to the user instead of the value.

If the Display Type is Text, the Show Meaning property is set to Yes and all the allowable values have a corresponding meaning, the meaning is displayed and the value is hidden at runtime.


Indicates whether the column's value is derived on the server, via a database trigger, and therefore should not be set or provided client side. If set to Yes, it will prevent any control based on this column from being set by the user, cause code to be generated to requery database rows following an Insert or Update in order to display server-defined values and disable the generation of code for client derivation (such as UID generation)

Default: No


Indicates whether the action item is implemented as a button.

Note: Buttons are always created for Generator action items.


(Navigation and custom action items only)
Indicates whether the action item is implemented as a menu item.

Preferences determine which menu item is used.

Note: You cannot generate menu items from Generator action items.

Related topics

Template menu preferences


(Generator action items only)

Indicates the standard functionality the action item is to invoke e.g. i.e. Delete record, New Record etc.


Optional, 30 characters
The name of a custom action item control that the generated control will be based on.

This must exist in the template project and the control definition file, otherwise there will be an error during generation. If omitted, the default control style is used.

Note: If the Create Button? property for the action item group is set to No, the custom template property has no effect.

Related topics

About template Visual Basic projects

CGTCControls Visual Basic template form

About the control definition file


Mandatory, 30 characters
A unique name for the action item.

Visual Basic Generator supports Navigation, Custom and Generator action items.

Related topics

About action items in Visual Basic applications


Optional, 130 characters
The caption or label to appear on the control (or menu item) generated from this action item.


(Custom action items only)
Indicates whether the custom action item should only be active (or enabled) when a record is displayed (Yes).


Determines whether records can be deleted using this zone.


Determines whether records can be added using this zone.


Determines whether records can be updated using this zone.


Determines whether QUERY operations are allowed using this zone.

Related topics

About Query dialogs in Visual Basic applications


Optional, 70 characters
The default title for the zone. If the generated zone is enclosed within a frame control, this specifies the frame caption.

This text may also be used in user messages and on navigation buttons that may be generated to link to this zone from a different window.

When a new module components is created, the title defaults to the display title held against the underlying table.

Related topics

About windows and zones


Optional
The overall layout of the zone in the generated Visual Basic application. Valid options are Context, Form, List and List/Form.

Related topics

About zone layout styles


Optional
Help text for the module.

A Windows Help file can be generated for the Visual Basic application. Text for the module normally serves to introduce the module. If this is the top-level module for your application, this text will be displayed on the Contents topic of the generated MS Help file.

Related topics

About Help files for generated Visual Basic applications


Optional, 70 characters
In the absence of a Window Title, this defines the default title of the first (main) window generated from this module.

For a module with no module components, it is used for the default banner caption in the CGTWLaunch template form.

Related topics

CGTWLaunch Visual Basic template form


Optional, 100 characters
The name of the compiled Help file (.HLP) created for this module and its associated module network.

Only specify this property against the top-level module for the Help file.


Mandatory
Defines that the language of the module is Visual Basic.


Mandatory, 70 characters
The purpose or short description for documentation purposes.


Optional, 70 characters
The default title for buttons and menus (action items) that are used to navigate to this module.

The Short Title may also be incorporated in the CGTWLaunch template form as a static caption.

Related topics

CGTWLaunch Visual Basic template form


Optional, 60 characters
The name and file extension of the graphic file used to illustrate the module topic.


Mandatory, 20 characters
Used to name generated files if the Implementation Name is not defined. In this context the name is limited by any filename length restriction.

The Short Name may also be incorporated in the CGTWLaunch template window as a static caption.

Related topics

CGTWLaunch Visual Basic template form


Optional, 100 characters
The command used to invoke this module.

For example, you could call a form modally rather than modeless by entering the following command: <formname>.show vbmodal

Typically the Command Line does not need to be defined as the Generator determines the appropriate command to use when linking modules.


Optional, 30 characters
Used to name files generated from this module. If the Implementation Name is omitted the Short Name is used instead.

If you have set a length restriction for generated files, ensure this value does not exceed the maximum length allowed, otherwise generation will be unsuccessful e.g. for 16 bit applications this property must not exceed 6 characters in length.


Optional
Visual Basic Generator only processes modules if the type is DEFAULT or MENU

The generation of LIBRARY modules are not supported in release 2 onwards.


Indicates whether this item is displayed in the record list box generated for List, List/Form and Form zones.

In a Context zone this property indicates whether the item is displayed in the main window.

If no context items are selected for the module component the Primary Key columns are used instead, together with any columns which are marked as 'descriptors' within the column definition (Descriptor Sequence).

Related topics

About record list boxes

About zone layout styles


Indicates whether the user can enter a value into this control when a new record is being created.

It should be unchecked (No) if the control value is to be generated automatically.


Indicates whether this control is displayed on the zone's Query dialog.

If unchecked (No), this control does not appear on the Query dialog.

For Context zones an LOV dialog is displayed and a simple query reduction criteria dialog is displayed for the first item whose Query property is checked (Yes).

Related topics

About Query dialogs


Mandatory
Determines whether range searching is allowed for the item.

By default, Visual Basic Generator creates a pair of To/From for items based on DATE and non-key NUMERIC columns.


Indicates whether validation code is generated to ensure that the user provides values for these controls when creating or updating records.

Related topics

About validation code


Optional, 20 characters
The control style associated with the generated item.

The actual (standard) control used depends on the Control Type Mapping preferences.

Related topics

About the control definition file

Control type mapping preferences


Indicates whether the generated control is displayed in the zone.

If set to No, a control is created in the top-left corner of its container frame or form, but with its Visible property set to False.


Optional, 130 characters
The prompt (or caption) for the generated control.

Prompts may be split into two portions that appear before and after the control. Preferences determines how prompt splitting operates and also where prompts are to be placed relative to their control.

To define a particular mnemonic character for a control, enter a single & character immediately before the letter you require.

Related topics

About prompt/control layout

About splitting control prompts

About mnemonic access keys for controls


Indicates whether the user is allowed to update this control's value when updating an existing record.


Optional
(Unbound items only) The name of a domain to be associated with this unbound item. If specified, the allowed values are derived from the domain definition.

Related topics

About allowable control values


Optional, 60 characters
The default value used to populate the control when a new record is created.

Related topics

Specifying a default control value


Optional
Indicates whether the Value or Meaning properties of allowable values are displayed for the item.

If set to <Null> the allowable value is displayed in the generated application. If set to 'Instead of code' the Meaning is displayed.

Visual Basic Generator does not support the 'Alongside code' option.

Related topics

About allowable control values


Optional, 30 characters
The name of a custom (non-standard) control that the generated control will be based on.

This must exist in the template project and the control definition file, otherwise there will be an error during generation. If omitted, the default control style is used, as defined by the Control Type Mapping preferences.

Related topics

About template Visual Basic projects

CGTCControls Visual Basic template form

About the control definition file


Optional, 5 digits
The width of text fields, specified in characters.

Visual Basic Generator computes the width required for the control by multiplying this value out by the average character cell width of the font, and adding in an overhead for the left and right margins, as defined by the LayoutWidthOverhead setting in the control definition file.

Note: This property has no effect for 'Checkboxes' and 'Radio Groups'.

If this property is undefined, the Default text control display length preference values are used instead.

Related topics

About the control definition file

Default text control display length preferences


Optional, 6 digits
The number of lines to display in a generated text field or text list.

Visual Basic Generator computes the height required for the control by taking the height of the template control, and then adding in the average font height for each extra line.

Note: This property has no effect for Pop List, Check Box and Radio Group style controls.


Optional
The horizontal alignment of the value within a text field.


Optional, 60 characters
Defines how number or date information is displayed in the generated application.

This value determines the setting of the control's FormatMask property in the generated application, as specified by the FormatProp setting in the control definition file.

Related topics

About the control definition file


Mandatory, 30 characters
Used to alias the table name within the FROM clause of generated SQL statements.


Optional
A SQL condition to perform foreign key validation and restricts records displayed within the lookup LOV.


Controls the number of records displayed in a list of values (LOV) window generated for this lookup table usage.

If set to Yes, the user is prompted to enter search criteria to restrict the number of records displayed (referred to as a long list). If set to No, the LOV window lists all available records.

Related topics

Querying lookup LOVs automatically


Optional
A SQL WHERE condition to be applied to the SELECT statement used to query the zone's records.

Use this property to restricts the records displayed within the particular zone.

Related topics

Defining a restrictive WHERE condition


The Visual Basic project capture process

Related Topics

The overall process for capturing a Visual Basic project is outlined below.

	Prepare to capture Visual Basic Projects
	Review project and plan module mappings
	Refine control definition file
	Capture the Visual Basic project
	Review and save the captured module


Preparing to capture Visual Basic projects

Related Topics

Before you can capture a Visual Basic project, an Oracle Designer container (i.e. folder or application system) must exist for you to use. You must then capture the database design.

To prepare for the capture of a Visual Basic project:

1.	Use the Repository Object Navigator to create a target Oracle Designer container for the Visual Basic project you wish to capture. Alternatively, you could use an existing container.

2.	Use Design Editor to create a database design, for the tables used by the Visual Basic project. About

Note:	Use database capture to create a database design based on an existing database. About

3.	(Optional) Use a Server Model Diagram to build up a picture of a captured database design:

a.	In the Design Editor, choose File→New→Server Model Diagram.

b.	Display the repository definitions on the Server Model Diagram. How

4.	Use the Server Model Diagram to ensure that the design specification is complete, check that:

•	primary keys and foreign keys are defined for master-detail links

•	columns which use Sequences are mapped accordingly

•	allowable values are defined for columns

Next step

Once the database design is complete you must decide how you want to capture your Visual Basic project, i.e. plan the module mappings.How


Planning module mappings for Visual Basic design capture

Related Topics	Example

The starting point of the design capture process is to review your Visual Basic project, and decide how you wish to group the forms into the modules which will be created in the repository.

The design capture utility provides the following capture options:

•	Create single module for entire project

•	Create one module for each form

•	Define mapping from forms to modules

By the nature of their design, some Visual Basic projects are easy to map using either of the first two options. More often you will need to define mappings from forms to modules (custom mappings) to suit a specific project design. In most cases user-defined mappings will create the optimum module design, so you are encouraged to spend some time planning what they will be, before design capture takes place.

Note that regardless of the capture option you choose, the captured module short names must not already exist within the Oracle Designer container (i.e. folder or application system).

Defining custom mappings

If you choose to define custom mappings consider the following points:

•	A module should typically represent a single business function:

Where several forms implement a certain function within a Visual Basic project you should consider mapping them to the same module, e.g. a Personnel function may comprise a Departments form and an Employees form, in this case both forms should be mapped to the same module.

•	If a project is mapped to more than one module, one of the forms must be designated as the 'StartUp Form'.

•	Forms can be omitted from the captured project if desired.

Next step

Capture your Visual Basic project. How

Note:	If your project contains any third-party control you must first edit the control definition file.How


Example - Planning module mappings

The table below illustrates how you might plan to capture this sample Visual Basic project:

Main Menu	Orders Form	Products Form	Department Form	Employees Form
Visual Basic Form	maps to	Module Short Name	StartUp Form
Main Menu Form	⇒	Main
Products Form	⇒	Products
Orders Form	⇒	Orders
Departments Form	⇒	Departments
Employees Form	⇒	Departments


Refining the control definition file

Related Topics

In order to capture controls from a Visual Basic project they must be defined in the control definition file. About

To define which controls to capture, edit the control definition file:

1.	Use Notepad, or a similar text editor to open CTLDEF.TXT.

Note:	This file is located in the CGENV61\CVBETC directory.

2.	For each control-type, ensure that the following entries are correct:

Name	Type	Default	Description
DontRecoverItem	Number	-1	If the item is not to be captured, set this property to -1. If this property set to 0, or omitted, the item will be captured.
RecoverAsDataControl	Number	-1	If the item is to be captured as a data control, set this property to -1.
RecoverControlType	String	None	The BasicControlType used when capturing the control, i.e. one of TEXT, CHECK, LIST, BUTTON, RADIO, OTHER.  All control types defined in the control definition file must have an entry for RecoverControlType.
Note:	Any third-party controls in the Visual Basic project must be registered in the control definition file.

3.	Save any changes you have made.

Example

[Control VB.Data]
DontRecoverItem=0
RecoverAsDataControl=-1
RecoverControlType="OTHER"

Next step

When you have defined every control type, you are ready to capture the Visual Basic project. How


Recovering a Visual Basic Project
Capturing a Visual Basic project

Related Topics

Visual Basic projects can be transformed into design specifications held in the repository. About

To capture a Visual Basic project from the Design Editor:

1.	Ensure that you are connected to the correct, target Oracle Designer container (i.e. folder or application system).

2.	Choose Generate→Capture Design of→Visual Basic to display the Capture Visual Basic Design dialog box.

Note:	If the Visual Basic design capture utility has been used before the Previous Settings button is active. If appropriate, use this button to load the previously defined capture options and then edit the options as required.

3.	Enter the name of the Visual Basic project (.VBP) that you want to capture.

4.	Select the appropriate capture option for your project:

To ...	Select ...
Capture a project comprising many independent forms	Create one module for each form
Capture a very simple project	Create single module for entire Project
Define custom mapping for a project (recommended)	Define mapping from forms to modules
To capture the project using custom mappings:

For each entry in the list of Forms:

a.	To map to a new module, enter a Module Short Name. The name you specify must not already exist within the container (i.e. folder or application system).

To map to a module already defined for another form within this project, select the appropriate Module Short Name from the dropdown list.

b.	Repeat step a. until you have defined a destination module for every form that you wish to capture.

5.	From the Startup Form dropdown list, select the form which is displayed first when you run the Visual Basic project.

6.	(Optional) To create a new module diagram displaying the modules captured from the Visual Basic project, check the Create on Diagram after Capture checkbox.

7.	(Optional) To log capture information to a file, enter the name of the file in the Capture Report File field.

8.	Use the Additional Containers field to specify the location of objects (e.g. tables, languages, attached libraries, reusable module components) that are referenced by the project being captured but which are not in the target container.

9.	Use the Post Capture options to specify whether to save changes to the repository during design capture:

•	Commit - update repository objects

•	Browse/Edit - show proposed repository changes, enabling you to choose how to process them

Note that there are some circumstances when Visual Basic Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture.

10.	Click Start.

11.	Save the captured module(s).

Next step

After successful design capture, you need to review the design of each newly created module and any module network which may have been generated for the project. How


Create single module definition for entire Visual Basic project

Use this option when capturing simple Visual Basic projects. This mapping option is illustrated using the example below:

Sample Visual Basic project: Forms		Modules created in the repository


Create one module for each Visual Basic Form

Use this option when capturing more complex Visual Basic projects comprising many 'independent' forms. This mapping option is illustrated using the example below:

Sample Visual Basic project: Forms		Modules created in the repository


Create Visual Basic modules according to user-defined mappings

Use this option to create modules according to groupings you define. For most projects this option creates the optimum module design and you are encouraged to define custom mappings, prior to design capture. This mapping option is illustrated using the example below:

Sample Visual Basic projects: Forms		Modules created in the repository


Reviewing the design of captured Visual Basic modules

Related Topics

Use the Design Editor to review and save the repository modules created during design capture.

For each newly created module check the following:

•	windows

•	module components

•	table usages

•	action items

•	items (bound and unbound)

•	item groups


Design capture of Visual Basic applications

About

What is the Visual Basic design capture utility?

Visual Basic design capture options

Captured Visual Basic modules

Captured module network links

Capturing Visual Basic projects

Capturing Visual Basic projects step-by-step

Preparing to capture Visual Basic projects

Planning module mappings

Refining the control definition file

Capturing Visual Basic projects

Reviewing captured Visual Basic modules


What is the Visual Basic design capture utility?

Related Topics

The Visual Basic design capture utility transforms Visual Basic projects into design specifications held within a repository. During the design capture process, as much design and implementation information as possible is extracted from the project and recorded in the repository as:

•	module definitions

•	windows

•	module components

•	table usages

•	items (bound and unbound)

•	item groups

•	action items

The new, captured elements can be visualized using a module diagram in the Design Editor where they may be modified if necessary.

Note:	If the project being captured uses Visual Basic's data control then table usages may be captured. However, in this case definitions of the tables and columns used by the application must exist in the repository before you can capture the design. If you have not done so already, use the Oracle Designer database capture utility to read information from the database and create corresponding table and column definitions in the repository.

The Visual Basic design capture utility may be used to:

•	assist in the migration of Visual Basic projects to other environments such as Oracle Forms

•	document existing Visual Basic projects in the repository

•	modify or upgrade existing Visual Basic applications


About Visual Basic design capture options

Related Topics

Visual Basic projects typically comprise several forms. The starting point of the design capture process is for you to decide how to group these forms, into the 'modules' which will be created in the repository.

A repository module is normally used to represent a single business function e.g. "Enter Customer Order" or "Define Product List". Within a Visual Basic project the same function would typically be implemented as one or more linked screens.

The Visual Basic design capture utility provides the following capture options:

•	Create single module for entire project

•	Create one module for each form

•	Define mapping from forms to modules

The appropriate option depends on the nature of the project you wish to capture.

Top-level module

When multiple modules are created during design capture, they are linked together (in a module network) to define how the user will navigate around the modules within the project. Before starting the capture process you must indicate which Visual Basic form is the 'StartUp Form' for the project. The module created from the StartUp Form will become the 'top-level' module in the module network.


About captured Visual Basic modules

Related Topics

During the capture process, forms which make up the Visual Basic project are analyzed and their objects and object properties used to define the repository elements that comprise each newly created module:

•	windows

•	module components and table usages

•	item groups

•	items (bound, unbound and action)

Windows

A window definition is created for each source form. So if you group several Visual Basic forms into a single repository module, it will contain several windows, i.e. one for each form, as is shown in this example.

Note:	Empty windows are not created by the Visual Basic design capture utility.

Module components and table usages

A module component is created for every container (e.g., form or subform) which must be represented within a module. So if a Visual Basic form contains several subforms, the repository module will have several module components, i.e. one for each bound data control.

The design capture utility uses the 'RecordSource' property to identify bound data controls. The value of this property is then used to associate the module component with a database table. So, if the RecordSource property of a control is set and the control definition file defines the control as 'RecoverAsDataControl', a table usage is created

Unbound module components may also be created if the project contains sets of Visual Basic controls which are not bound to any database table or columns.

To capture the usage of a table by an application during design capture (i.e. to create a table usage), a corresponding repository table definition must already exist. The design capture utility uses the name of the table used by the application to identify the corresponding repository table definition, as follows:

Firstly:	The design capture utility searches for a repository table definition with the same name as the table used by the application.
If Repository table definition not found:	If the table used by the application has a name ending with the characters _JN (i.e. the table is a journal table), the design capture utility searches for a repository table definition without the _JN suffix
If Repository table definition still not found:	The design capture utility searches for a repository table definition that has a synonym with the same name as the table used by the application
Item groups

An item group is created for every grouped set of controls in the Visual Basic project, e.g. radio group frames and other data controls (that cannot be bound to an item) used to group controls.

Items (bound, unbound and action)

A bound item is created for every bound control in the Visual Basic project, e.g. text fields, popup lists, combo boxes and list boxes.

The design capture utility uses the 'DataField' property to identify bound controls (items) within each bound data control (module component). The value of this property is then used to associate the item with a database column.

An unbound item will also be created for every unbound control in the Visual Basic project, except where the unbound control is simply a container for grouping controls or a button. Unbound items will only be created if the DontRecoverItem flag is not set in the control definition file. Action items for buttons will also only be created if the DontRecoverItem flag is not set.

Preferences

Visual Basic preferences are not set during capture. After capture, set the preferences manually and generate.


Example - How window definitions are created during design recovery
Example - How window definitions are created during design capture

Two Visual Basic forms are mapped to the same module (named Personnel).     departments.frm + employees.frm During capture a window is created for each form.


About captured module network links
About captured Visual Basic module network links

Related Topics

If more than one module is created during design capture, module links are automatically created. These links represent how the user of the project will navigate around the forms that make up the project.

For example, a Visual Basic project may comprise several forms:

Main Menu	Department Form	Orders Form	Items Form
During design capture, a separate module can be created for each form. If 'Main Menu' is selected as the 'StartUp form', a set of module links are created from the StartUp form (top-level module) to the other modules in the project:

Inferred module network links

Links are automatically created from the module containing the designated StartUp form, to any other module 'without a parent'.


About database design capture for Visual Basic projects

Related Topics

The database design for the Visual Basic project must be recorded in the repository before you can run the Visual Basic design capture utility. Modules and module components cannot be created until the relevant table and column definitions are present in the repository.

Use the Oracle Designer database capture utility to record an existing database design, in the repository.

Oracle databases

If your Visual Basic project uses an Oracle database, use database capture to create database object definitions in the repository.

Other databases

Through ODBC support, other database designs can also be captured.

Attention:	As ODBC drivers may modify certain details of the tables in your database, e.g. truncate column names, you should check the table definitions after they have been captured into the repository.


bound control

Within a Visual Basic project, a bound control is mapped to a column in a database table using the DataSource property.


unbound module component

An unbound module component is a module component with no table usages, and hence contains only unbound items.


Generating Visual Basic Applications Step-by-Step

	Set up the database design Record the database design Set key database design properties Prepare database for generated application
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design Record the database design Set key database design properties Prepare database for generated application
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design Record the database design Set key database design properties Prepare database for generated application
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design Record the database design Set key database design properties for columns Prepare database for generated application
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create a Simple Visual Basic module Plan the structure of the module Create Visual Basic module definition Create Visual Basic module components Create data usages Define master-detail links Define basic layout Set table usage properties Set basic item properties
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Generating Visual Basic Applications Step-by-Step

	Set up the database design
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


Designing Visual Basic Applications

	Set up the database design Record the database design Set key database design properties Prepare database for generated application
	Set Visual Basic Generator options
	Create Visual Basic modules
	Add more functionality to the module design
	Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


The Visual Basic application design process

Related Topics

This diagram presents the range and sequence of tasks required to design and generate a Visual Basic application. If this is your first application you may want to step through the tasks one at a time. To jump to a particular task, click on the appropriate box.

	Set up the database design Record the database design Set key database design properties Prepare database for generated application
	Set Visual Basic Generator options
	Create a Visual Basic module Plan the structure of the module Create Visual Basic module definition Create module components Create data usages Define key based links Define basic layout Set table usage properties Set basic item properties
	Extend module design and customize layout Add more functionality to the module design Customize the appearance and layout
	Create multiple module applications
	Generate the Visual Basic application
	Run the Visual Basic application


About database design for Visual Basic Generator
About database design

Related Topics

Before you can begin to design and generate a Visual Basic application, the database design for the target application must be complete. The flow chart illustrates the process for ensuring that the database design specification is complete. If this is your first Visual Basic application you may want to step through the tasks one at a time. To jump to a task, click on the appropriate box.

	Record the database design
	Set key database design properties
	Prepare database for generated application
Once you are satisfied that the database design is complete, create the Visual Basic modules which make up your application. How

Repository-held database design

During module design and generation Visual Basic Generator makes use of table and column information defined in the repository. It does not reference the 'actual' user tables created in your application database. Therefore, before you can create a module and generate a Visual Basic application from it, the database design must be recorded accurately in the repository. How

Whether you intend to use an existing database design, or an entirely new design it is important to spend some time fine-tuning the database design in preparation for Visual Basic generation. If all the database objects are defined accurately, module design and generation is greatly simplified. How

Database preparation prior to generation

Before you generate a Visual Basic application, always ensure that the application's test database is set up with the required database objects and that they are up to date. How

Generating DDL from your repository-held server model creates:

•	database objects from definitions in the repository

•	the Code Control Table needed to provide unique identifier for columns deriving unique values from a sequence defined as 'Code Control'

If any of your tables contain columns that derive their values from 'dynamic lists' or 'domains' (e.g. pop lists and text lists) you must also generate a reference code table. A reference code table is needed to carry out runtime validation and LOV processing for such columns.


Recording the database design for Visual Basic Generator
Recording the database design

Related Topics	Where am I?

Before you can create a module and generate a Visual Basic application from it, the database design must be recorded accurately in the repository. About

To record the database design:

If one has not already been defined, you may record a new database design using Oracle Designer in one of three ways:

•	record a new database design, using a server model diagram in Design Editor. For more information, refer to  Generating a database from a new relational design

•	create a database design automatically from analysis data, using Database Design Transformer. For more information, refer to Generating a default design from analysis data

•	capture database objects from an existing database, using the Capture Database Design utility. For more information, refer to  Generating a database from a captured design

Next step

To ensure that the database design specification is complete, check certain key database properties are set. How


Setting key database design properties for Visual Basic Generator
Setting key database design properties

Related Topics	Where am I?

The steps below guide you to database design properties that are particularly important for Visual Basic generation. About

To set key database design properties:

1.	Ensure that a Navigator window is open in Design Editor. How

2.	Choose Options→Use Property Palette. About

3.	In the Navigator, double-click the table definition and then ensure these properties are set correctly:

Alias

Display Title

4.	In the Navigator, double-click a column definition and then ensure these properties are set correctly:

Column Name	Prompt
Domain	Display Type
Sequence	Display Length
AutoGen Type	Uppercase?
5.	Define allowable values against columns if appropriate. How

6.	Ensure that each table has an appropriate:

Primary Key	At least one primary key column must be defined. How
Foreign Key	All necessary foreign keys must be defined. How
Next step

Before generating a Visual Basic application always ensure that the application's test database is set up with the required database objects and that they are up to date. How


Preparing the database for generated Visual Basic applications
Preparing the database for Visual Basic applications

Related Topics	Where am I?

Before generating a Visual Basic application, always ensure that the application's test database is set up with the required database objects and that they are up to date. About

To prepare the test database:

Generate DDL from your server model:

•	generate objects on an Oracle database How

•	generate objects on a database other than an Oracle database How

Generate the reference code table for a specific set of modules. For more information, refer to About reference code tables

Next step

If the modules which make up your generated application exist, first set Visual Basic Generator options. How

Then, generate the Visual Basic application. How

If no modules exist, use Design Editor to create Visual Basic modules. For more information, refer to Creating a simple Visual Basic module.


Setting Visual Basic Generator options

Related Topics	Where am I?

Before running Visual Basic Generator you must specify the data access method and runtime database user for the application. You can also specify where Visual Generator finds required files during generation and the directory in which to save generated Visual Basic applications (including whether to upload generated files to the repository after generation). About

To set Visual Basic Generator options:

1.	In Design Editor, choose Options→Generator Options→Visual Basic.

2.	Use the Source options to specify where to locate required files (on the filesystem or in the repository) during generation.

3.	Specify where to save generated files using the Destination of generated files field.

By default, generated files are saved to the current working directory of Oracle Designer.

4.	If you want to store generated files in the repository after generation, check the Upload generated files to repository checkbox.

5.	Select the appropriate data access method for the generated application:

•	Oracle Objects for OLE

•	Data Access Objects

If you select Oracle Objects for OLE, you will also have to install Oracle Objects for OLE on the client machine.  If you do not, the application will generate correctly but you will not be able to run it.

If you select Data Access Objects you will also need to:

a.	Ensure an ODBC driver for the target database is installed. How

b.	Ensure a data source is set up for the required database. How

6.	Enter the name and connect string for the Runtime Database.

Next step

If the modules which make up your generated application exist, generate the Visual Basic application. How

If no modules exist, first use Design Editor to create Visual Basic modules. For more information, refer to Creating a simple Visual Basic module.


About Visual Basic module design

Related Topics

Once the database design is complete, you may create one or more Visual Basic modules. This diagram illustrates the process for defining data usages and key based links for one, simple Visual Basic module.

If this is your first Visual Basic module you may want to step through the tasks one at a time. To jump to a task, click on the appropriate box.

	Plan module structure
	Create Visual Basic module definition
	Create Visual Basic module components
	Create data usages
	Define key based links
	Define basic layout
	Set table usage properties
	Set basic item properties
Next step

Once you have completed the set of tasks outlined here you can generate a Visual Basic application from the new Visual Basic module. How

No further configuration is required to display a prototype application and test the fundamental module design.

Once the basic module design is complete, you can add more functionality to the module design or customize the appearance and layout as required. About


Planning the structure of Visual Basic modules

Related Topics	Where am I?

Before you start to create a Visual Basic module it is good practice to plan the module structure. Consider the following:

•	Which database tables will be used for the base tables of each zone?

•	How should the zones be sequenced ?

•	Which lookup tables are required ?

•	Do the necessary foreign key constraints exist ?

Next step

Once you have a firm idea of how to structure the module, use Design Editor to create the module definition. For more information, refer to About creating Visual Basic module definitions

Examples

These figures represent two sample Module Diagrams, where:

•	each colored box represents a table usage

•	table usages shown on the left of the diagrams represent base tables

•	table usages shown to the right represent lookup tables

•	a single base table and any associated lookups represents a module component

•	each vertical line represents a key based (master-detail) link between table usages

•	each horizontal line represents a link to a lookup table

•	the crow's-foot on the line shows the table that contains the foreign key used to implement the link


Creating Visual Basic module definitions using Design Editor

Related Topics	Where am I?

A module definition is used to record data usage and layout information, from which an application (also referred to as a module) can be generated. You may create a Visual Basic module definition, in various ways:

•	Create a new module definition from scratch	How
•	Copy an existing module definition from the current container (i.e. folder or application system) and adapt a new definition from it	How
•	Create default modules from this analysis information, using the Application Design Transformer	How
•	create modules from an existing application, using design capture	How
Next step

Once a module definition is complete, you can create module components for the module. How


Creating new Visual Basic module definitions

Related Topics	Where am I?

There are various different ways to create a Visual Basic module definition using Design Editor. This method describes how to create a new module from scratch, using a Module Diagram. About

To create a new Visual Basic module definition:

1.	In Design Editor, choose File→New→Module Diagram.

2.	Click Create and enter the following mandatory properties:

Module Type

Module Short Name

Purpose

Language

3.	(Optional) Click Next and enter the following information:

Button/menu text 	(Short Title)

Main window title 	(Top Title)

Command Line

4.	(Optional) Click Next again and enter an Implementation Name.

5.	If you intend to generate Windows Help for your Visual Basic application, click Next and enter Help text for the module. See Generating MS Help for Windows applications.

6.	Click Finish to save and then OK to display the new module definition on a Module Diagram. Tip

Next step

Once a module definition is complete, you can create module components for the module. How

If they are already defined create data usages for the module component. How


Creating Visual Basic modules by copying existing definitions
Creating a Visual Basic module by copying an existing definition

Related Topics	Where am I?

You can create a new Visual Basic module definition by basing it on an existing one. This technique allows you to copy modules originally designed for other languages (such as Forms, Reports and WebServer) and then modify or adapt them for use in a Visual Basic application.

To copy a module definition and create a new diagram:

1.	Ensure that a Navigator window is open in Design Editor. How

2.	In the Navigator, select the module you want to copy.

3.	Do one of the following:

To copy a Visual Basic module

a.	Choose Utilities→Copy Object.

b.	Enter a new name for the module.

c.	Choose Copy.

To copy a non-Visual Basic module

a.	Choose Utilities→Copy With New Language.

b.	Enter a new name for the module.

c.	Define the new language as Visual Basic.

d.	Choose OK.

4.	Display the new, copied module on a Module Diagram. How

Next step

Once a module definition is complete, you can create module components for the module. How

If they are already defined create data usages for the module component. How


Creating Visual Basic module components

Related Topics	Where am I?

A single Visual Basic module may contain one or more module components. Each module component forms the basis for a zone in the generated application. About

Note:	Some modules will not contain module components, e.g. top-level modules created to launch the Visual Basic application.

To create a module component for a Visual Basic module:

1.	Open the Module Diagram in Design Editor. How

2.	Choose Options→Use Property Palette. About

3.	Click [image] and then click on the module.

4.	Enter a Module Component Name that is unique within the module.

5.	Enter the following information (as appropriate):

Title	Query?	Insert?	Delete?
Layout Style		Update?
6.	Click [image] to save.

To define another zone for this Visual Basic module, create another module component. The order in which module components are positioned on the diagram determines their display sequence in the generated application. To change the sequence, drag and drop the module components on the Module Diagram.

Next step

Create the data usages for the module component. How


Creating data usages for Visual Basic zones

Related Topics	Where am I?

After you have recorded a module component definition for a Visual Basic zone you can define the tables and columns that it uses (data usages). Each module component is based on a specific table (the base table) but may also make use of other tables to provide lookup information (lookup tables). Bound items are used to specify which columns are used.

To create data usages for a Visual Basic zone:

1.	Open the Module Diagram in Design Editor. How

2.	Choose View→Data View. About

3.	Create a base table usage:

a.	In the Navigator, select the table definition for the base table usage.

b.	Drag the table definition onto the module component on the diagram where the base table usage is to appear.

The base table usage is created on the diagram. Example

If a base table already exists you will only be able to create lookup table usages, as each module component can only have one base table usage.

4.	(Optional) Create one or more lookup table usages.

a.	In the Navigator, select the table definition for the lookup table usage.

Ensure that a foreign key constraint exists between the base and lookup table you want to add. You can create foreign key constraints using Design Editor How

b.	Drag the table definition on, or to the right of the base table usage on the Module Diagram.

The lookup table usage is created on the diagram. Example

Note:	Lookup tables typically provide lookup information for base table usages. However, they can also be linked to another lookup table usage, forming a chained lookup.

5.	Define bound items for each table usage:

a.	Select the table usage.

b.	Click the right mouse button and choose Bound Items.

c.	Choose the required columns.

d.	Click [image] to save.

Next step

If the module contains more than one zone, you will typically:

•	create key based links (master-detail) between them How

•	and use the 'window' and ' popup' layout items to define the basic layout of the generated application. How

Alternatively, you may set properties for the table usages. How


Defining key based links between Visual Basic zones

Related Topics	Where am I?

A key based link defines a link between two table usages in different Visual Basic zones. To create a key based link the appropriate constraint must exist (primary key or foreign key).

To define a key based link between two zones:

1.	Open the Module Diagram in Design Editor. How

2.	Choose View→Data View. About

3.	Click [image].

4.	Click on one of the table usages that are to make up the link.

5.	Click on the other table usage that is to complete the link.

If the destination of the link is in a different module, click on the white space surrounding the module definition diagram element and choose the table usage you require.

6.	Choose the appropriate key constraint from the list.

If only one constraint exists, it is selected automatically. The key based link is created on the diagram. Example

Next step

Once you have defined the zones and data usages, and linked them together, use Design Editor in display view to define the basic layout. How


Defining basic Visual Basic module layout in Display View

Related Topics	Where am I?

The placement of master-detail zones on the same, or separate windows is defined visually, using window and popup layout items. Both these layout items are available when the Module Diagram in set to Display View. In Display View, you can also create item groups and change the sequence in which module components and items are displayed.

Window layout item

By default, a module component is created within a new window. You can use this layout item to:

•	display master-detail zones on separate windows How

•	display master-detail zones on the same window How

Note that the width and height of generated windows are driven from templates, not from window layout item properties.

Popup layout item

You can use the popup layout item to display detail zones within their master zone's stacking area. How

Item group layout item

You can use the item group layout item to display one or more items within a group frame control. How

Display sequence

You can drag and drop objects on the Module Diagram to change the display order of module components and bound/unbound items in the generated application. How

Next step

After defining the basic layout of the module you will typically set:

•	table usage properties How

•	and item properties How


Displaying master-detail zones in separate windows
Displaying master-detail zones on separate windows

Related Topics	Where am I?

Use the window layout item to define that a detail zone is displayed in a new window in the Visual Basic application.

Illustration: Master-detail zones on separate windows

To display master-detail zones in separate windows:

1.	Open the Module Diagram in Design Editor. How

2.	Choose View→Display View. About

3.	Click [image].

4.	Draw the window layout element around the detail zone.

Hold down the mouse button and drag the rubberband box to create a boundary around the module component to be included in the window layout element. At least one module component must be included in the selection.

Next step

You can further define the basic layout of a Visual Basic module in Display View. About

Once the basic layout is complete, you will typically set:

•	table usage properties How

•	and item properties How


Displaying master-detail zones in the same window

Related Topics	Where am I?

Use the window layout item to define that master-detail zones are placed on the same window in the Visual Basic application.

Illustration: Master-detail zones on same window

To display master-detail zones in the same window:

1.	Open the Module Diagram in Design Editor. How

2.	Choose View→Display View. About

3.	Resize the window surrounding the master zone, so that it encompasses the detail zone.

Next step

You can further define the basic layout of a Visual Basic module in Display View. About

Once the basic layout is complete, you will typically set:

•	table usage properties How

•	and item properties How


Placing detail zones on the master zone's stacking area

Related Topics	Where am I?

Use the popup placement item to define that a detail zone is placed within its master zone's stacking area. About

Illustration: Multiple detail zones on the same window

To place detail zones on the master zone's stacking area:

1.	Open the Module Diagram in Design Editor. How

2.	Choose View→Display View. About

3.	Resize the window surrounding the master zone, so that it encompasses the detail zone.

4.	Click [image].

5.	Draw the popup layout element around the detail zone.

Hold down the mouse button and drag the rubberband box to create a boundary around the module components to be included in the popup layout element. At least one module component must be included in the selection.

6.	Repeat step 5 to include other detail zones on the stacking area.

Note:	Multiple detail zones defined using the popup layout item will appear as a series of tabbed zones in the generated application.

Next step

You can further define the basic layout of a Visual Basic module in Display View. About

Once the basic layout is complete, you will typically set:

•	table usage properties How

•	and item properties How


Setting table usage properties for Visual Basic modules

Related Topics	Where am I?

After you have recorded the module definition and module components, and built up a picture of the tables to be used, you must set certain table usage properties. The steps below guide you to properties that are particularly important for Visual Basic generation.

To set table usage properties for a Visual Basic module:

1.	Open the Module Diagram in Design Editor. How

2.	Choose View→Data View. About

3.	Choose Options→Use Property Palette.

4.	Double-click the table usage and set the following properties as required:

Base tables	Lookup tables
Usage Alias	Validation WHERE Clause
WHERE Clause of Query	WHERE Clause of Query
5.	Click [image] to save.

Next step

Once table usage properties are defined, specify item properties which determine how the columns are used and displayed in the Visual Basic application. How

You may also want to create further bound or unbound items. How


Setting basic item properties for Visual Basic modules

Related Topics	Where am I?

The steps below describe how to set some basic properties which determine how items are used and displayed in a Visual Basic application. For information on the more advanced item properties, see Adding more functionality to the module design.

To set item properties for a Visual Basic module:

1.	Open the Module Diagram in Design Editor. How

2.	Choose View→Data View. About

3.	Choose Options→Use Property Palette.

4.	Double-click the item and set the following basic properties as required:

Display?	Insert?	Optional?
Prompt	Update?	Context?
Display Type	Query?
5.	To change the order in which controls appear in the Visual Basic zone, click an item using the right mouse button and then click Resequence Items.

Note:	By default, lookup items will appear immediately after the foreign key item.

6.	To add another control based on a column, create a bound item. How

Tip: 	To create a control that is not derived from a column, create an unbound item. How

Next step

After you have defined all the module components and items you may generate a standalone application from the Visual Basic module. How

Note:	If the module contains items that must derive their values from a dynamic list of allowable values held on the database, or a Sequence, ensure that the appropriate reference code or code control tables exist on the test application database prior to generation. About

Once the basic module design is complete, you can further enhance the module design or customize the appearance and layout as required. About


Generating Visual Basic applications

Related Topics	Where am I?

Once the module design is complete, you can generate the Visual Basic application. Whenever you modify a module definition, the module network, or any of the preferences, you will have to generate all or part of the Visual Basic application again. Before following these steps, ensure:

•	the test database is complete (and up to date) How

•	Visual Basic Generator options are set correctly How

To generate a Visual Basic application:

1.	On the Navigator, select the module to generate.

To generate a Visual Basic application for a module network, ensure that the module you select is the top-level module.

2.	Choose Generate→Generate Module to display the Generate Visual Basic dialog box.

Tip:	To generate from a non-Visual Basic module, choose Generate→Generate Module As.

3.	Do one of the following:

To create a new Visual Basic project:

a.	Click Create new Visual Basic Project.

b.	(Optional) Select Include the module network in this project.

To update or add to an existing Visual Basic project:

a.	Click Add module to existing Visual Basic project.

This option avoids having to regenerate all the modules that make up a project when modifications are restricted to a specific module.

b.	Specify the Visual Basic project.

4.	To run the application after generation, enter the password for the runtime database.

This field is only active if the Name and Connect String are defined on the Visual Basic Generator Options dialog. Click the Options button to view the current settings.

5.	Use the Post Generation options on the Generate Visual Basic dialog box to specify whether to save changes to the repository during generation:

•	Commit - update repository objects

•	Revert - do not update repository objects

•	Browse/Edit - show proposed repository changes, enabling you to choose how to process them

Note that there are some circumstances when Visual Basic Generator will not update the properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture.

6.	Click Start.

During generation the Message Window displays progress information and details of any errors that occur. Use the automated message action facility to correct any errors that occur and then generate all or part of the Visual Basic application again. How

Next step

After successful generation run the Visual Basic application. How


Running Visual Basic applications after generation

Related Topics	Where am I?

If Visual Basic Designer is installed, you can run generated Visual Basic projects from Design Editor immediately after generation.

To run a generated Visual Basic application:

1. 	After successful generation, choose Messages→Build Actions, or click [image] on the Message Window.

Actions are only displayed after generation.

2.	Double-click Run Visual Basic project from the list of possible actions.

If Visual Basic Designer is not initiated, check to see if the location of Visual Basic Designer (VB32.EXE, VB5.EXE, or VB6.exe) is in the system path.

3.	Check the application, looking for:

•	missing or incorrect functionality

•	incorrect navigation between modules and zones

•	aspects of the layout which could be improved

Next step

Typically you will customize or refine the module design and regenerate the application several times, until you are satisfied that it meets your business requirements.


You may save a diagram independently of its corresponding module definition. For instance, you may wish to annotate the diagram with embedded OLE objects. However, as you can always create a new diagram wholly from an existing module, you rarely need to save a Module Diagram in the repository; the diagram is merely a visual representation of the underlying module definition.


Base table usage


Lookup table usage


Key-based links


Visual Basic module containing two zones


Master-detail zones on same window

This module layout displays the master
zone and detail zone on the same window:


Master-detail zones on separate windows

This module layout displays the detail zone
on a new window:


Multiple master-detail zones on the same window

This module design stacks multiple detail zone
on the same window as the master:


Extend the functionality of the module design and customizing layout
Extending Visual Basic module design and customizing layout

Related Topics	Where am I?

Once you have a basic module design you can generate a first-cut application. From here, you will probably want to extend the functionality further and customize the layout of the application to suit your particular requirements.

For information on some of the more advanced aspects of design and generation, refer to the following topics:

Adding more functionality to the module design

Customizing the appearance and layout


 Adding more functionality to the Visual Basic module design

Where am I?

Once you are satisfied with your basic module design, you may want to introduce some of the more advanced features described here.

Unbound items and action items

Defining custom unbound controls

Defining custom action items

Defining generator action items

Defining module component navigation action items

Defining module navigation action items

Control groups and stacking areas

Grouping controls together

Creating stacked control groups using tabs or radio groups

Allowable values for pop lists, radio groups & text lists

Defining a list of allowable values

Defining a list of suggested values

Record queries

Querying zones automatically

Defining a restrictive WHERE condition for the zone

Displaying records in a specific order

Lookup LOVs

Querying lookup values automatically

Defining a WHERE condition for lookup validation

List boxes

Displaying columns in record list boxes

Data entry controls

Using sequences to provide unique control values

Defining error messages for constraint violations

Defining optional/mandatory fields

Specifying default control value

Customizing mnemonic access key generation

Assigning a mnemonic character to a data control

Context sensitive Help

Entering hint text for data controls

Generating MS Help Files, using the Oracle Designer MS Help Generator

Generated application logic

Modifying generated application logic created by Visual Basic Generator

Capturing application logic from Visual Basic applications

User-defined application logic

Entering user-defined event code for Visual Basic Generator

Entering user-defined named routines for Visual Basic Generator


About default control values for Visual Basic applications
About default control values in Visual Basic applications

Related Topics

To speed up data entry, it can be useful to provide the user with appropriate default control values. This is so that when a new record is created the controls initially appear with frequently used values. Defaults may be set explicitly, or in some cases can be generated automatically. How

Default values for check boxes, radio groups, pop lists and text lists

The default value you specify for these control types must be one of the allowable values defined for the column. About

For example:

Display Type	Popup example	Allowable values (Meaning)	Default
Radio group	Property Class	PD (Private Dwelling) CP (Commercial Property) AL (Agricultural/Land)	PD
Pop list	Status	FS (Currently trying to sell it) SD (Sold) NS (Not for Sale)	FS
Text list	Condition	E (Excellent) I (Immaculate) D (DIY)	I
		Domain values (Meaning)
Check box	Photograph Available	Y (Yes) N (No)	Y
Note:	Domains allow you to define a common set of allowable values which can be reused across multiple columns e.g. Y/N for flag columns.

Default values for text fields

Use the Default Value and Default Value Type property of a repository item to set the initial value of the generated item. Note that the default values defined for text fields must be compatible with the datatype of the HTML form element.

Set Default Value Property to	Set Default Value Type property to	Displayed in generated item	Notes
a literal string	Literal	the specified string	For example, to set a default value to 1, set the datatype to Number and set the Default Value property to 1, and the Default Value Type property to Literal.
USER	Client Function Call or Database Function Call	current username
SYSDATE	Client Function Call or Database Function Call	current system date	You may find that one of the system default values below suits your purposes better than SYSDATE
a date/time system default value	Client Function Call or Database Function Call	local system date/time or database date/time	The date/time system default values are $$DATE$$, $$DATETIME$$, $$TIME$$, $$DBDATE$$, $$DBDATETIME$$, $$TIME$$.


Specifying default control values for Visual Basic applications
Specifying default control values

Related Topics	Where am I?

To speed up data entry, it can be useful to provide the user with appropriate default control values. About

To specify a default control value:

1.	In Design Editor, double-click the item you require.

2.	Set the Default Value property.

Tip:	If you are using Property Dialogs this is displayed on the Definition tab.

Radio groups  Pop lists Text lists Check boxes	Enter a previously defined allowable value. About Note: Allowable values are case sensitive.
Text fields	Enter a value that matches the datatype of the item.  You can enter AutoGen types if you wish e.g. DATETIME. These values are not case sensitive but you must add $$ before and after the AutoGen keyword. For example, $$DATETIME$$
3.	Click [image] or Finish to save the changes.


Default Value - Radio Group


Default Value - Pop List


Default Value - Text List


Default Value - Checkbox


About mnemonic access characters for controls in Visual Basic applications
About mnemonic access keys for controls in Visual Basic applications

Related Topics

Controls may be generated with mnemonic access keys if required. Mnemonics allow the application user to select a particular control, simply by pressing the relevant shortcut key combination i.e. ALT+mnemonic character.

Mnemonics can be added to:

•	zone frame captions (for List and List/Form zone styles)

•	stacking area tabs

•	stacking area radio group buttons

•	bound and unbound controls

•	action items

Mnemonics are not added to:

•	button bar buttons for data manipulation (mnemonics should be added to the template form buttons, if required)

•	read-only control prompts

Controlling mnemonic access generation

You can control the way mnemonic access keys are generated:

•	using a set of Visual Basic mnemonic access preferences. How

•	assigning mnemonic characters within the item Prompt. How


Customizing mnemonic access key generation in Visual Basic applications
Customizing mnemonic access key generation

Related Topics	Where am I?

Controls can be generated with mnemonic access keys so the user can select controls using shortcut key combinations e.g. ALT+mnemonic letter. About

By default, mnemonic keys are generated for all data entry controls and where necessary mnemonic letters are reused. This behavior can be modified using preferences.

To customize mnemonic access key generation using preferences:

1.	In Design Editor, display the Generator Preference Palette for the entire container (i.e. folder or application system), or an individual Visual Basic module. How

Typically, users would expect keyboard navigation to be the same throughout a single application. Therefore, these preferences should be set at the container level to encourage consistency across all your modules.

2.	Select the End User Interface branch and set the mnemonic access preferences:

Add mnemonic access characters to controls ? (MNMADD)

Add mnemonic access characters to data entry controls? (MNMDEC)

Reuse characters when assigning mnemonics ? (MNMREU)

3.	Click [image] to save.

Tip:	Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


Assigning mnemonic characters to bound or unbound controls in Visual Basic applications
Assigning a mnemonic to bound or unbound controls

Related Topics	Where am I?

Controls may be generated with mnemonic access keys if required. Mnemonics allow the application user to select a particular control, simply by pressing the relevant shortcut key combination i.e. ALT+mnemonic letter. About

To assign a mnemonic to a data control:

1.	In Design Editor, double-click the item you require.

2.	In the item Prompt field, insert an '&' character immediately before the mnemonic character you want to use.

Tip:	If you are using Property Dialogs the prompt property is displayed on the Display tab.

For example, to display Product Code, enter Product &Code.

Do not leave a space after the & character if you are using the character to indicate that a mnemonic key is required. If you leave a space, the & is treated as a normal character e.g. Address & Telephone.

3.	Click [image] or Finish to save the changes.


About custom unbound items in Visual Basic applications

Custom unbound items can be used to record the use of a control, whose value is not derived from a database column. Unbound items are recorded in the context of a module component and therefore they can be placed and sequenced with other bound and unbound items on main zone forms, property sheet dialogs and query dialogs.

You can create unbound items on a Module Diagram using Design Editor. How

Note:	Visual Basic Generator only supports custom unbound items.

Display properties

The display characteristics of unbound items are defined using the same repository properties as bound items.

If the Display Type of a custom unbound item is set to Button, the Default Button Control Type (CTLBUT) preference takes effect.

Allowable values

A set of allowable values can be defined directly against custom unbound items. How These allowable values are hard-coded within the application during generation.

Alternatively, unbound items can derive allowable values from a domain. If you choose to use a domain, you can decide whether the allowable values are stored in a 'reference code table' on the database (referred to as a Dynamic List), or hard-coded within the generated application. Use the Dynamic List? property to control this behavior.

Application logic

User-defined code may be specified against custom unbound items. For example, you may want to generate an unbound control that executes user-defined code on a Visual Basic event. About


Creating custom unbound items for Visual Basic applications
Creating custom unbound items

Where am I?

To generate a control whose value is not derived from a database column, create a custom unbound item. About

To create an unbound item using a Module Diagram:

1.	Open the correct Module Diagram in the Design Editor. How

2.	Choose Options→Use Property Dialogs.

3.	Choose View→Display View. About

3.	Click [image] and then click the module component.

The snap line indicates where the unbound item will be created.

5.	Enter a Name for the unbound item and set the Unbound Type property to Custom.

6.	Click Next and define valid operations for the unbound items:

Insert?	Query?
Update?	Range Search
7.	Click Next and define information about the unbound item values:

Default value	Optional?
Domain
8.	(Optional) Click Next and define a set of allowable values for the unbound item.

9.	Click Next and set the following display properties as required:

Prompt	Format Mask	Context?
Display Type	Width
Show Meaning	Height
Template object	Alignment
For a complete list of properties, see repository item properties used by Visual Basic Generator.

10.	Click Finish to save.

11.	To change the order in which unbound controls appear in the Visual Basic zone, click an unbound item using the right mouse button and then click Resequence Items.

12.	(Optional) Define a set of allowable values for the unbound item. How

13.	(Optional) Enter user-defined event code for the unbound item. How


About action items in Visual Basic applications

Related Topics

Action items can be used to represent a requirement within the application where a user is given the option to take a certain action. In generated Visual Basic applications, action items are typically represented as buttons or menu options.

Visual Basic Generator supports three types of action item:

• Navigation	Generates a button or menu item that allows a user to navigate to a module component in the same module, or to another module. About
• Custom	Generates a button or menu item that executes code on a Visual Basic event. About
• Generator	Generates a button that executes a piece of standard Visual Basic Generator functionality. About
A set of repository action item properties define how these items are to be generated.

Action items on the Module Diagram

	On the Module Diagram (in Display View)., action items are represented as buttons. In Display View, you can drag and drop action items on the Module Diagram to define the order in which they are displayed in the application. This example shows action items held against a module component. Action items can also be defined against a window.


About navigation action items in Visual Basic applications

Related Topics

This type of action item allows navigation within a generated application, or to another generated application. The Visual Basic Generator supports two kinds of navigation action items:

Module component	These navigation action items can be created to navigate to a specific zone within the same module. How If two module components in the same module are linked together via a key based link and the module components do not appear in the same window, a navigation action item is created automatically.
Module	These navigation action items can be created to navigate to a different module (Visual Basic or Menu), but not a specific zone within that module. How If a module network link is created and the calling module is a Visual Basic module, a module navigation action item is automatically created within the calling module.
In Visual Basic modules, navigation action items can be defined against module components and windows.

Button generation

By default, navigation action items are generated as buttons. The buttons are either placed in the button bar created for the window, or the zone (not a zone's window button bar). Note that these buttons are not displayed on query dialogs or property sheet dialogs. Alternative template objects can be defined for the action item providing that the Create Button? property for the action item is set to Yes.

Menu generation

Navigation action items can also be generated as menu items. If the Create Menu Item? property for the action item is set to Yes, preferences are used to determine which menu control the navigation menu item is added to:

Module navigation	Template menu to locate module network entries (TFMNMN)
Module component navigation	Template menu to locate menu items to open detail forms (TFMNZC)
Note:	Module navigation action items defined for a launch screen window are generated as buttons only. About

Availability within the application

If a navigation action item is defined against a window, the generated button (or menu) is always active/enabled. If defined against a module component, the generated button (or menu) is only active when a record is displayed in the zone.

Display order

The display order of action items within a zone or window can be modified by dragging and dropping the action items on the Module Diagram (in Display View).

Application logic

User defined application logic may be specified against navigation action items. About


About custom action items in Visual Basic applications

Related Topics

This type of action item executes a specific piece of user-defined code on a particular Visual Basic event. For example, the Click, DragDrop, DragOver, GotFocus, KeyDown, KeyPress, KeyUp, LostFocus, MouseDown, MouseMove and Mouse Up events.

In Visual Basic modules, custom action items can be defined against module components or windows. How

Button generation

By default, custom action items are generated as buttons and appear in the button bar created for the window, or the zone (not a zone's window button bar). Note that these buttons are not displayed on query dialogs or property sheet dialogs. Alternative template objects can be defined for the action item, providing the Create Button? property for the action item is set to Yes.

Menu generation

Custom action items can also be implemented as menu items. If the Create Menu? property for the action item is set to Yes, the Template menu to locate custom action items (TFMNCA) preference determines which menu control the menu item is added to.

Availability within the application

If a custom action item is defined against a window, the generated button (or menu) is always active/ enabled. If defined against a module component, the generated button (or menu) can be active all the time, or just when a record is displayed. The Enable on Database Record property on the Edit Custom Action Item dialog controls this behavior.

Display order

The display order of action items within a zone or window can be modified by dragging and dropping the action items on the Module Diagram (in Display View).

Note:	Custom unbound items can also be used to generate controls that execute user-defined code on a Visual Basic event. The main difference between custom action items and custom unbound items is where they are placed in the generated application. Custom action items are placed and sequenced with the other action items, whereas custom unbound items can be placed and sequenced with other bound and unbound items and can appear on property sheet dialogs and query dialogs.

Application logic

User defined application logic may be specified against custom action items. About


About generator action items in Visual Basic applications

Related Topics

This type of action item executes a piece of standard Visual Basic Generator functionality i.e. Delete record, New Record, Query, Resequence Down, Resequence Up, Save, Undo, View/Update Record. Use a generator action item to customize the default action of a button that is generated for a zone's main form. For example, you may want to add some user-defined code to the Query button, or Delete button.

When a generator action item is defined for a particular module component it is used instead of the default (or template) button. As generator action items relate specifically to zone-level actions, they can only be defined against module components. How

Button generation

Generator action items are generated as buttons and appear in the button bar created for the zone (not the zone's window button bar). They are not displayed on query dialogs or property sheet dialogs. A custom template object can be used instead of a button, if required.

Availability within application

The functionality of a particular button determines whether the generated button is active all the time, or just when a record is displayed. For example, a Delete button is only active when a record is present, whereas a Query button is always active.

Display order

The display order of action items within a zone or window can be modified by dragging and dropping the action items on the Module Diagram (in Display View).

Application logic

User defined application logic may be specified against generator action items. About


Defining module component navigation action items for Visual Basic applications
Defining module component navigation action items

Related Topics	Where am I?

To generate a button or menu item that allows a user to navigate to a module component on a different window, define a module component navigation action item. About

To define a module component navigation action item:

1.	In Design Editor, open the Module Diagram in Display View. How

2.	Choose Options→Use Property Dialogs.

3.	Click [image] and then click the module component or window where the action item is to appear.

4.	Select Navigation within the Module and then click Next.

5. 	Enter a Name for the action item and a suitable display Prompt.

6.	Click Next and choose the module component (or zone) this action item will navigate to in the generated application.

7.	Click Next and specify display options for the action item:

Create Button?	Create Menu Item?

Template Object

If a menu item is to be generated from the navigation action item, use the template menu preference (TFMNZC) to define the menu control on which it is placed.

8.	Click Finish to save.


Defining module navigation action items for Visual Basic applications
Defining module navigation action items

Related Topics	Where am I?

To generate a button or menu item that allows a user to navigate to another Visual Basic module or a Menu module, define a module navigation action item. About

To define a module navigation action item:

1.	In Design Editor, open the Module Diagram in Display View. How

2.	Choose Options→Use Property Dialogs.

3.	Click [image] and then click the module component or window where the action item is to appear.

4.	Select Navigation to a different Module and then click Next.

5. 	Enter a Name for the action item and a suitable display Prompt.

6.	Click Next and choose the module this action item will navigate to in the generated application.

7.	Click Next and specify display options for the action item:

Create Button?	Create Menu Item?

Template Object

If a menu item is to be generated from the navigation action item, use the template menu preference (TFMNMN) to define the menu control on which it is placed.

8.	Click Finish to save.

.


Defining custom action items for Visual Basic applications
Defining custom action items

Related Topics	Where am I?

To generate a button or menu item that executes code on a Visual Basic event, define a custom action item. About

To define a custom action item:

1.	In Design Editor, open the Module Diagram in Display View. How

2.	Choose Options→Use Property Dialogs.

3.	Click [image] and then click the module component or window where the action item is to appear.

4.	Select Custom and then click Next.

5. 	Enter a Name for the action item and a suitable display Prompt.

6.	Click Next and choose a Visual Basic event for the action item.

7. 	Click Next and specify display options for the action item:

Create Button? 	Create Menu Item?

Template Object

Enable On Database Record?

If a menu item is to be generated from the navigation action item, set the template menu preference (TFMNCA) to define the menu control on which it is placed. How

8.	Click Next, choose the option to invoke the Logic Editor and then click Finish.

9.	Use the Logic Editor to enter application logic for the Visual Basic event.

If you wish to change the application logic, expand the custom action item node on the Navigator and then use the Application Logic node to edit the event code.


Defining generator action items for Visual Basic applications
Defining generator action items

Related Topics	Where am I?

To generate a button that that executes a piece of standard Visual Basic Generator functionality, define a generator action item. About

To define a generator action item:

1.	In Design Editor, open the Module Diagram in Display View. How

2.	Choose Options→Use Property Dialogs.

3.	Click [image] and then click the module component where the action item is to appear.

4.	Select Generator and then click Next.

5. 	Enter a Name for the action item and a suitable display Prompt.

6. 	Click Next and choose the appropriate functionality.

Note: Generator action items only effect buttons generated for the main form.

7.	Click Finish to save.

You can use the Logic Editor to enter application logic against generator action items. About


Grouping controls together in Visual Basic applications
Grouping controls together

Related Topics	Where am I?

Within a zone or property sheet dialog, one or more controls may be grouped together visually. About

To group controls together:

1.	In Design Editor, open the Module Diagram in Display View. How

2.	Choose Options→Use Property Dialogs.

3.	On the diagram, select one or more of the items to be included in the group and click

4.	Enter a unique name for the item group.

5.	In the Prompt field, type the caption for the frame control which encloses the group.

Note:	Leave the Stacked option set to No, to ensure the group is permanently displayed.

6.	To assign other items to this group, click Next and select the items you require.

7.	Click Finish to save.

8.	To rearrange items in the item group, drag and drop them on the Module Diagram (in Display View). About


Creating stacked control groups using tabs or radio groups in Visual Basic applications
Creating stacked control groups using tabs or radio groups

Related Topics	Where am I?

Within a zone or property sheet dialog, multiple control groups may be stacked. The stacked frames can be implemented as a series of tabs, or radio groups. About

To create stacked control groups:

1.	In Design Editor, open the Module Diagram in Display View. How

2.	Choose Options→Use Property Dialogs.

3.	On the diagram, select one or more of the items to be included in the group and click

4.	Enter a unique name for the item group.

5.	In the Prompt field, type the caption for the tab or radio group selector.

6.	Set the Stacked property to Yes.

7.	To assign other items to this group, click Next and select the items you require.

Note that nested item groups are not supported in release 2 onwards.

8.	Click Finish to save.

9.	Repeat steps 3 to 8 to create one or more item groups, as required.

10.	To define a specific tab order, rearrange the item groups by dragging and dropping them on the Module Diagram (in Display View).

11.	Use the Use tab control for stacking areas (USETAB) preference to define whether tabs or radio groups are used. How

Series of tabbed dialogs (default)	USETAB =Yes
Stacked radio groups	USETAB =No


About allowable control values for Visual Basic application
About allowable control values for Visual Basic applications

Related Topics

For controls such as radio groups, checkboxes, pop lists and text lists, you will need to define a set of allowable values. How

If appropriate, you can also provide a list of allowable values for text-based controls.

Allowable values can be defined against a column definition (in which case they are inherited by all bound items based on that column) or unbound item. Alternatively, they can be defined within a domain, in which case they can be used by several columns or unbound items.

Allowable values against column definitions and unbound items

This is a sample set of allowable values for the optional item CUST_BUY_STATUS:

Sequence 1 2 3	Value F H C	Meaning First Time Buyer Home Owner Cash Buyer
If an item is defined as 'optional' (in terms of data entry) an additional 'Unknown' value is generated automatically. For checkboxes that are 'optional', only one allowable value is required because the second value automatically becomes 'Unknown'.

Sequence	For radio groups, this defines the order in which the radio buttons are displayed. For checkboxes, the first value defines the 'true', or 'checked' state.
Value	The valid value. For bound items this defines the value to be stored in the column on the database. If you intend to enter a corresponding Meaning, this can be a short identifier for the value.
Meaning	Optional. Provides a meaningful description of the value. The Show Meaning? property defines whether values or meanings are displayed in the generated application.
Note:	A set of allowable values can also be defined against an unbound item.

Reusable sets of allowable values within using domains

Domains allow you to define a common set of allowable values which can be reused across multiple columns e.g. Y/N for flag columns. To define that a column makes use of a Domain, first use Design Editor to create the Domain and specify its associated values. Then, set the column's 'Domain' property. How

Note:	Unbound items can also derive a set of allowable values from a domain.

Defining where allowable values are stored (Dynamic List? property)

If you define a set of allowable values, you must decide whether you want them stored in a 'reference code table' on the database (referred to as a Dynamic List), or hard-coded within the generated application. The Dynamic List? property (of the column definition or domain) controls this behavior. Note that in previous versions of Designer, the Dynamic List? Property was referred to as ‘Soft LOV’.

Reference Code Table	Dynamic List? property=Yes If you select this option you must run the Reference Code Table Utility prior to generation. For more information, refer to About reference code tables. This utility will populate the database with the 'allowable values' that are defined for the container (i.e. folder or application system).  Choose this option if the allowable values are likely to change after an application has been delivered. It is much easier to extend the list by adding new rows on a database, than to change and redistribute your Visual Basic application (see below).
Hardcoded	Dynamic List? property=No Choose this option if you intend to use control types that implicitly enforce hardcoded values i.e. checkboxes or radio groups. For other control types, only choose this option if the allowable values are not going to change. If you did need to modify the values at some later stage it would mean generating the Visual Basic module again, and this may not be practical, especially if the application is being used at several locations.


Defining a list of allowable values for a Visual Basic application
Defining a list of allowable values

Related Topics	Where am I?

Allowable values can be defined against a column definition, unbound item, or within a domain. The values can be stored on the database, or hardcoded within the generated application. About

To define a set of allowable values against a column definition (or unbound item)

1.	On Design Editor Navigator, expand the column definition (or unbound item) that requires allowable values.

2.	Choose Options→Use Property Palettes.

3.	Select Allowable Values and click

4. 	Set Value, Meaning and Sequence properties as required.

5.	Click [image] to save.

For each allowable value, repeat steps 3 to 5.

6.	Set the Dynamic List? property to define where the allowable values should be stored.

a.	Select the column definition or unbound item and click [image].

b. 	Set the Dynamic List? property to Yes, to store the values on the database.

Note:	If you specify allowable values for unbound items, a reference code table will not be created or populated automatically. If the reference code table does not already exist, you must explicitly create it and update the table.

To define a set of allowable values within a domain:

1.	In Design Editor, choose Options→Use Property Dialogs

2.	Create the domain.

a.	On the Navigator, select Domains and click

b.	Enter a name for the domain, then click Next to define further domain details.

c.	Click Next again to define one or more allowable values for the domain.

Set the Dynamic List? property to define where the allowable values should be stored.

d.	Click Finish to save.

3.	Associate the columns (or unbound items) with the domain.

a.	On the Navigator, select the column definition, or unbound item.

b.	Use the Domain property to enter the name of the Domain.

c.	Click Finish to save.

Next step

If the allowable values are to be stored on the database (Dynamic List?=Yes), you must run the Reference Code Table Utility prior to generation. For more information, refer to About reference code tables

This utility will populate the database with the 'allowable values' you have just defined.


About suggested control values for a Visual Basic application
About suggested control values in Visual Basic applications

Related Topics

Combo boxes can be used within a Visual Basic application to display lists of suggested values. How

This type of control allows the user to either select a value from the list, or enter a different value of their choice. Here is a sample set of suggested values for the column CUST_BUY_STATUS:

Sequence 1 2 3	Meaning First Time Buyer Home Owner Cash Buyer
The suggested values can be stored on the database, or hardcoded within the generated application. The Dynamic List? property of the column definition controls this behavior.

Note:	No validation takes place during data entry when suggested values are used.


Defining a list of suggested values

Related Topics	Where am I?

You can generate a combo box that allows a user to either select a value from a list, or enter a different value of their choice. About

To define a list of suggested values:

1.	On the Navigator, expand the column definition that requires suggested values.

2.	Choose Options→Use Property Palettes.

3.	Select Allowable Values and click

4. 	Set the Value property.

Define the full, suggested value for the column. The Meaning value is not used when generating suggestion lists.

5.	Click [image] to save.

6.	Repeat steps 3 to 5 for each suggested value required.

7.	Select the column definition and click [image].

8. 	Set the Suggestion List? property to Yes.

Note:	If you change the value of this property you must re-generate the DDL for the associated table.

9.	Set the Dynamic List? property to define where the suggested column values should be stored. About

10.	Click [image] to save.

11.	Set the Display Type property of the item to Pop List. How

Note:	The Text option may also be used; in this case a separate list of values is provided.

Next step

If the suggested values are to be stored on the database (Dynamic List?=Yes), you must run the Reference Code Table Utility prior to generation. For more information, refer to About reference code tables.

This utility will populate the database with the 'suggested values' you have just defined.


About record list boxes in Visual Basic applications

Related Topics

In a generated Visual Basic application, list boxes are used to display records relating to a particular zone. Typically the list box displays enough information to identify each record, and the full details of the record are displayed separately.

A list box is generated if the layout style of the zone is set to either List, or List/Form and it displays the set of items marked 'Context' in the module design. How

In the example below two items are marked Context. The column titles (Edition and Paper) are derived from the Prompt property of each item.

Note: 	List boxes are also used to display lookup information. Lookup list boxes display the set of lookup items that have the preference Display lookup item in List of Values (ITMDLV) in the module design set to Yes. How

Customization

To change the entire look and feel of generated list boxes, modify the default templates CGTZListDefault and CGTZListFormDefault. How


Displaying columns in record list boxes in Visual Basic applications
Displaying columns in record list boxes

Related Topics	Where am I?

You can choose which columns appear in record list boxes. About

To display columns in a record list box:

1.	In Design Editor, choose Options→Use Property Palettes

2.	Choose one or more items to appear in the record list box of a List or List/Form zone.

3.	Choose Edit→Properties

4.	Set the Context? property to Yes.

5.	Click [image] to save.

To display a column in a lookup list box:

1.	In Design Editor, choose the item and display the Generator Preference Palette. How

2.	Set the Display lookup item in List of Values (ITMDLV) preference to Y.

3.	Click [image] to save.


About custom record queries for Visual Basic zones

You can customize how records are displayed in a zone. For example, a zone can be designed to:

•	Query records automatically on startup

•	Display a restricted set of records

•	Display records in a specific order

Auto-query zones

You can define whether a master zone is queried automatically or when the user selects the Query button. How

For detail zones, you can define whether the detail zone is automatically queried when the master record changes.

Restrictive WHERE conditions

You can restrict the records displayed for a particular zone, by defining a SQL WHERE condition on the base or lookup table. How

The SQL WHERE condition is applied to the SELECT statement used to query the zone's records. For example, TYPE = 'MOVIE'.

Record order

You can define the order in which records are returned from the database using the Sequence and Direction properties. How

These properties indicate which items (if any) participate within the ORDER BY clause of the SQL statement that is used to query rows for the zone. The Sequence number defines the position within the ORDER BY. For example, you may want to sort SALES_ORDERS by REGION first (1), SALES_PERSON second (2), and ORDER_VALUE third (3).

For Direction, you may specify whether records are displayed in an ascending, or descending order. For example, you may want to view ORDER_VALUE in either ascending, or descending order.

Note: 	These properties may be set against both base and lookup items.


Querying Visual Basic zones automatically

Related Topics	Where am I?

You can define whether a master zone is queried automatically or when the user selects the Query button. For detail zones, you can define whether the detail zone is automatically queried when the master record changes. About

To query a zone automatically:

1.	In Design Editor, double-click the module component.

2.	Set the AutoQuery? property to Yes.

Tip: If you are using Property Dialogs this is displayed on the Operations tab.

3.	Click [image] or Finish to save the changes.


Defining restrictive WHERE condition for a Visual Basic zone
Defining restrictive WHERE conditions for Visual Basic zones

Related Topics	Where am I?

You may restrict the records displayed for a particular zone, by defining a SQL WHERE condition on the base or lookup table. The SQL WHERE condition is applied to the SELECT statement used to query the zone's records. About

To define a restrictive WHERE condition:

1.	In Design Editor, double-click the base or lookup table usage.

2.	Use the WHERE Clause of Query property to define the SQL WHERE condition for the table.

Tip: 	If you are using Property Dialogs this is displayed on the WHERE tab. For lookup table usages, choose the Query option. The Validate option is used to restrict the records displayed in the LOV for a foreign key lookup control. How

•	the 'WHERE' keyword must not be entered here.

•	it is recommended that you prefix column names with the Table Usage Alias property e.g. TITLE.type = 'MOVIE'

See the "SQL Language Reference Guide" for more information on how to construct valid WHERE statements.

3.	Click [image] or Finish to save the changes.


Displaying records in a specific order in Visual Basic applications
Displaying records in a specific order

Related Topics	Where am I?

You can define the order that records are returned from the database. About

To determine record order:

1.	In Design Editor, choose Options→Use Property Palette.

2.	Double-click the item to include in the order.

3.	For Order by Sequence, enter the number which specifies the position of this item within the ordering sequence.

4.	For Sort Order, choose whether rows are sorted in ascending order or descending order.

5.	Click [image] to save.

6.	Repeat steps 2 to 5 for the other items that are to participate in the ORDER BY.

Important:	Ensure the 'Order by Sequence' property is not set for those items not participating in the ORDER BY.


Querying lookup values automatically in Visual Basic applications
Querying lookup values automatically

Related Topics	Where am I?

You can define whether lookup values are queried automatically or whether an additional query dialog is displayed in order to reduce the number of values returned. About

To query lookup values automatically:

1.	In Design Editor, display the Generator Preference Palette. How

2.	Set the Filter records before display in LOV (RECFLT) preference to Y.

3.	Click [image] or Finish to save the changes.


Defining WHERE conditions for lookup validation in Visual Basic applications
Defining WHERE conditions for lookup validation

Related Topics	Where am I?

You can restrict the records displayed in the list of values (LOV) for a foreign key lookup control. For example, DATE_LEFT_COMPANY IS NULL would only display, or validate against existing employees. About

To define a WHERE condition for lookup validation:

1.	In Design Editor, double-click the lookup table usage.

2.	Use the Validation WHERE Clause property to define the SQL WHERE condition for the lookup.

Tip: 	If you are using Property Dialogs, select the WHERE tab and then choose the Validate option. The Query option is used to restrict the records displayed in the zone. How

•	the 'WHERE' keyword must not be entered here.

•	it is recommended that you prefix column names with the Table Usage Alias property.

See the "SQL Language Reference Guide" for more information on how to construct valid WHERE statements.

3.	Click [image] or Finish to save the changes.


Using sequences to provide unique control values in Visual Basic applications
Using sequences to provide unique control values

Where am I?

A sequence may be used to provide unique numbers for a single column in a single table (invoice numbers) or a number of columns in different tables (if contiguous numbers are not paramount). About

To set up a column to provide unique values from a sequence:

1.	In Design Editor, choose Options→Use Property Palette.

2.	Double-click the column definition.

3.	From the Sequence drop-down list, select the sequence which must be used to derive the column values.

Create the sequence definition first if it does not exist. How

Note:	If the target database is not Oracle, only use Code Controls sequences.

4.	Click [image] to save.

Next step

Ensure that the target database contains the sequence definition (or code controls table) before generating the Visual Basic application. How


About optional/mandatory fields in Visual Basic applications

Related Topics

To assist data entry, individual controls may be defined as optional or mandatory. How

When saving a new record, or updating an existing record, 'optional' controls may be left blank. However, values must be provided for mandatory controls and additional code is generated to check this. If a mandatory control is not defined the record is not saved; instead, a message is displayed to advise the user which control value has been omitted.

For example, if a form is used to record details about videos, the 'Title', 'Movie Category' and 'Age Classification' items may be considered essential (mandatory), whereas the 'Duration' of the video could be considered optional.

Customization

If you want to use color to differentiate between optional and mandatory fields, make use of the 'colored' template project TMPCLR.VBP. Alternatively, different colored control captions can be used to highlight mandatory fields and this may be achieved by modifying the appearance properties of the DfltCaptionMand control within the CGTCControls template.


Defining optional/mandatory fields in Visual Basic applications
Defining optional/mandatory fields

Related Topics	Where am I?

To assist data entry, individual controls may be defined as optional or mandatory. About

To define optional/mandatory fields:

1.	In Design Editor, double-click the item you require.

2.	Set the Optional property.

Tip: If you are using Property Dialogs this is displayed on the Definition tab.

Yes	For an item that is optional during data entry.

No	For a mandatory field.

3.	Click [image] or Finish to save the changes.


Defining error messages for constraint violations in Visual Basic applications
Defining error messages for constraint violations

Related Topics	Where am I?

You can define custom error messages against table constraints in your generated application. About

There is no need to define error messages for columns that derive their values from sequences (typically Primary or Foreign key columns) as such values will always be valid. If specific error message text is not defined for a particular constraint, the Generator provides a default message incorporating the prompts of related controls.

To define an error message for constraint violation:

1.	In Design Editor, double-click the constraint definition you require.

One of Primary Key, Foreign Key, Unique Key and Check Constraint.

2.	Enter suitable Error Message text, up to 70 characters. For example,

3.	Select 'Server' from the Validate In dropdown list.

Server-side validation prevents invalid data from being stored on the server. In contrast, Client application validation will prevent the user from entering incorrect values. Validation on both sides provides the best 'protection' but at the expense of performance. However, because generated Visual Basic applications do not provide Client-side validation, the 'Both' option need not be specified (unless you intend to migrate the module to/from a Form Builder or Web PL/SQL application).

4.	Click [image] or Finish to save the changes.


About hint text for controls in Visual Basic applications

Related Topics

Generated applications may provide context-sensitive help for data controls and buttons using 'tooltip' style popups. This hint text is displayed after a short delay, when the mouse pointer is placed over a control. For example,

Hint text is displayed directly below and aligned to the left edge of the control to which the hint applies. If this would cause any of the text to be hidden, it is repositioned accordingly.

Buttons	This hint text is generated automatically. Typically, the hint text utilizes the prompt of the zone where the control belongs. For example, the Delete button in an Employees zone might have the hint "Delete the current Employees record".  To disable hint text on buttons, set the Should hint text be created for buttons (HTUINT) preference to No.
Controls	Hint text can be added to data controls using the item Hint property. How Typically users would expect either all, or none of the controls to provide this information. To disable hint text on data controls, set the Should hint text be created for data controls (HTDATA) preference to No. Note: No hint is given for controls in query dialogs.
Tip:	Hint text is very useful for a novice user, however it may not be necessary as they become more experienced. Generated applications provide a 'runtime option' which allows the user to switch the popup hint text on/off as required.

Generated code and controls

The appearance of hint text is determined by a control named CG_HINT_TEXT in the CGTCControls template form. This control defines the colors and font of the hint text. The width is scaled automatically to size when the text is displayed.

If either of the Hint text preferences are set to Yes, another control is generated for each form based on CG_HINT_TEXT.

In addition, a call to the lgHintText procedure is added to the MouseMove event of each control. This procedure uses the hWnd property of the control in Windows API calls in order to position the hint text near the appropriate control. For these reasons, hint text can be provided only for controls that have a hWnd property and that support a MouseMove event; otherwise, the HasNoHWndProp and HasNoMouseMoveEvent properties must be set explicitly to -1 (True) in the control definition file to prevent the generation of inappropriate code.


Entering hint text for data controls

Related Topics	Where am I?

Generated applications may display 'tooltip' style popups to provide context-sensitive help for data controls and buttons. About

To enter hint text for data controls:

1.	In Design Editor, double-click the item you require.

2.	Select the Hint property and enter appropriate Hint text for the item.

Tip: If you are using Property Dialogs this is displayed on the Help tab.

3.	Click [image] or Finish to save the changes.


Using Visual Basic Version 5.0

Where Am I?

Visual Basic Generator is shipped with Visual Basic 5.0 templates. To generate applications for Visual Basic 5.0, use the VB5 templates shipped with Visual Basic Generator. Ensure that:

•	MGPROJ is set to cgenv61/cvb5vblib\<project_name>

•	TFPROJ is set to cgenv61\cvb5tmpt1\<project_name>

If your generated applications do make use of these third party controls, we strongly recommend you consider using the Microsoft standard controls instead.

However, you may have generated applications for VB5 that use third party ocx controls, e.g. ANIBTN32.OCX, GAUGE32.OCX, GRAPH32.OCX, GRID32.OCX, KEYSTA32.OCX, MSOUTL32.OCX, SPIN32.OCX, TABCTL32.OCX, THREED32.OCX. These controls are on the VB5 CD, although they are not installed by default because Microsoft supplies standard controls to provide the same functionality. If you want to continue to generate applications that use these third party controls, you should copy the third party controls and register them manually as described below:

•	copy the third party controls from the tools\controls directory on the VB5 CD to a directory included in the PATH environment variable

•	register the third party controls and their licenses by running the VBCTRLS.REG file in the tools\controls directory on the VB5 CD


Using Visual Basic Version 6.0

Where am I?

Visual Basic Generator is shipped with Visual Basic 5.0 templates. You can generate Visual Basic 6.0 applications using these  by setting:

•	MGPROJ to cgenv61/cvb5vblib\<project_name>

•	TFPROJ to cgenv61\cvb5tmpt1\<project_name>

Note:	If you have used Visual Basic Generator to generate Visual Basic 5.0 applications, you can generate these as Visual Basic 6.0 applications using the Visual Basic 5.0 templates. Visual Basic 6.0 will display a message to tell you that you are using templates saved under a previous version. To avoid getting this message every time, load the templates into Visual Basic 6.0 and save them.


Using Visual Basic Version 4.0

Where am I?

Oracle Designer Visual Basic Generator is no longer certified for Visual Basic 4.0, however Visual Basic Generator is shipped with Visual Basic 4.0 templates and libraries. If you want to generate applications for VB4 you need to take the following into account:

ocx controls

If you have generated applications for VB4 that use third party controls (e.g. ANIBTN32.OCX, GAUGE32.OCX, GRAPH32.OCX, GRID32.OCX, KEYSTA32.OCX, MSOUTL32.OCX, SPIN32.OCX, TABCTL32.OCX, THREED32.OCX), and you want to continue to generate applications that use them, you should copy the third party controls and register them manually as described below:

•	copy the third party controls from the tools\controls directory on the VB5 CD to a directory included in the PATH environment variable

•	register the third party controls and their licenses by running the VBCTRLS.REG file in the tools\controls directory on the VB5 CD

We strongly recommend you consider using the Microsoft standard controls instead of these third party controls.

Library and template directories

If you want to generate VB4 applications, you must set:

MGPROJ preference to <Null>, or to the path of your own VB4 project if you have created one, e.g. cvbvblib\<project_name>.

TFPROJ preference cvbtmpt1\tmpt.vbp.


Customizing the appearance and layout of Visual Basic applications

Related Topics	Where am I?

During the initial design stages you will probably generate your Visual Basic application using default design and layout settings. Once you are satisfied with the basic content of your windows and zones you may want to customize or refine the layout to suit your particular requirements. These topics describe how to customize different aspects of a generated Visual Basic application:

Main forms for a Visual Basic zone

Context zones	List/Form zones	Property sheet dialogs
List zones	Form zones	Query dialogs
Zones - General

Making use of vertical space within a zone

Aligning controls within a zone

Displaying detail zones on a master zone

Overriding the default zone appearance

Creating custom zones styles in the Visual Basic template project

Changing button captions in Visual Basic templates

Control groups

Customizing control group layout

Pop lists, radio groups, text lists & check boxes

Creating radio groups and radio buttons

Customizing radio group layout

Creating text lists and pop lists

Defining check boxes

Controls & prompts - General

Changing the line spacing between controls

Changing the text alignment within controls

Setting the size of text based controls

Defining how prompts/controls are displayed

Defining split prompt markers

Defining prompts with markers

Adding color to controls

Default control types

Defining default control types

Overriding default control types

Third-party control types

Registering third-party controls in the template controls form

Adding a new control type to the control definition file

Template project

Customizing the template Visual Basic project

Library project

Customizing the template library project

Specifying the Visual Basic library project

Preferences

Setting generator preferences

Non-English applications

Generating Visual Basic applications for use in other countries


About Context zones in Visual Basic applications
About Context zones

Related Topics

Context zones display limited information from a single record that defines the context for operations performed in detail zones. It is therefore used as a master in a master-detail relationship where only a subset of columns of the master record need to be permanently displayed, and where selection of the desired master is to be made via a list of values. A separate property sheet dialog is used to create and edit records.

To create a Context zone, set the Layout Style property of the module component to 'Context'. How

In the example below, Third Party details are maintained using a context zone. Little information about the Third Party is required, but the name of the Third Party provides the context for details to be entered.

Controls in a Context zone

Context zones contain one or more read-only controls derived from items where the Context? property is set to Yes. Usually these zones contain a single Text Box control.

Buttons in a Context zone

Context zones contain a set of buttons. The default captions for these buttons are:

Query	Invokes an LOV dialog to allow searching for an existing record.  This button is generated if the Query property for one or more items is set to Yes.
Add	Invokes a property sheet dialog for creating records. Associated property sheet dialogs are always called modally from a Context zone. Thus any changes made to column values will be reflected back in the Context zone. This button is generated if the Insert property for one or more items is set to Yes.
View	Invokes a property sheet dialog for editing records.  This button is generated if the Update property for one or more items is set to Yes.
Delete	Deletes the current record.  This button is generated if the Delete property for the module component is set to Yes.
Clear	Clears the zone. This button is generated if a Clear button is defined in the zone template.
Default template form

The overall appearance and layout of this zone is determined by the CGTZContextDefault template form.


Designing Context zones for Visual Basic applications
Designing Context zones

Related Topics	Where am I?

Context zones display limited information from a single record that defines the context for operations performed in detail zones. About

To set up a Context zone:

1.	In Design Editor, double-click the module component you require.

2.	Set the Layout Style property to 'Context'.

Tip: If you are using Property Dialogs this is on the Display tab.

3.	Click [image] or Finish to save the changes.

4.	Choose the item (or items) you want to display on the master context zone:

a.	Double-click the item you require.

b.	Set the Context? property to Yes.

Tip: If you are using Property Dialogs this is on the Display tab.

c.	Click [image] or Finish to save the changes.

Typically, this type of zone displays a single control. Lookup columns may be used if required.

5.	(Optional) Modify the layout of the property sheet dialog generated for the zone. How

Further customization

To change the entire look and feel of a context zone, modify the default template CGTZContextDefault. How

If you just want to customize the appearance of controls on a context zone, edit the ContextZoneControl and ContextZoneLabel controls within the CGTCControls template.


About List zones in Visual Basic applications
About List zones

Related Topics

List zones display multiple records in a standard list box and make use of separate property sheet dialogs to create and edit records. This layout style provides an interface that is native to many MS-Windows applications and is useful in situations where the detail is to be placed on the same window as the master, and where space is limited.

To create a List zone, set the Layout Style property of the module component to 'List' How

Controls in a List zone

List zones contain a single list box. This list displays those items with the Context? property set to Yes. If all items have the Context? property set to Yes and the zone is query-only, no property sheet dialog is generated.

Buttons in a List zone

List zones contain a set of buttons. The default captions for these buttons are:

Query	Invokes a dialog that allows the user to define search criteria to be incorporated when executing a query against the module component. This button is generated if the Query property for one or more items is set to Yes.
Add	Invokes a property sheet dialog for creating records.  This button is generated if the Insert property for one or more items is set to Yes.
View	Invokes a property sheet dialog for editing records.  This button is generated if the Update property for one or more items is set to Yes.
Delete	Deletes the current record.  This button is generated if the Delete property for the module component is set to Yes.
Clear	Clears the zone. This button is generated if a Clear button is defined in the zone template.
Default template form

The overall appearance and layout of this zone is determined by the CGTZListDefault template form.


Designing List zones for Visual Basic applications
Designing List zones

Related Topics	Where am I?

List zones display multiple records in a standard list box and make use of a separate property sheet dialogs to create and edit records. About

To set up a List zone:

1.	In Design Editor, double-click the module component you require.

2.	Set the Layout Style property to 'List'.

Tip: If you are using Property Dialogs this is on the Display tab.

3.	Click [image] or Finish to save the changes.

4.	Choose the item (or items) you want to display in the list box:

a.	Double-click the item you require.

b.	Set the Context? property to Yes.

Tip: If you are using Property Dialogs this is on the Display tab.

c.	Click [image] or Finish to save the changes.

If you do not want to generate a property sheet dialog, simply mark all displayed items as 'Context'.

5.	(Optional) Modify the layout of the property sheet dialog generated for the zone. About

Further customization

If you want to be able to open property sheets for more than one record at a time, set the Make Property Sheet Dialogs Modal (PSDMOD) preference to No. How

To display the record list through a pop list rather than a list box, set the item's Template/Library Object property to 'CGTZListCombo'. How

To change the entire look and feel of a List zone, modify the default template CGTZListDefault. How

To customize the list box control itself either:

•	modify the ListBox control within the CGTCControls template How

•	or, define a new default control type for list boxes in general by setting the Default ListBox control type (CTLLST) preference. How


About List/Form zones in Visual Basic applications
About List/Form zones

Related Topics

List/Form zones are similar to Form zones, except that a list box permanently displays the set of queried records, alongside a single-record view of the currently selected record. No additional property sheets are required for adding or viewing the records, all these operations are carried out on the same form.

To create a List/Form zone, set the Layout Style property of the module component to 'List/Form'. How

Controls in a List/Form zone

List/Form zones contain a list box and the set of controls that map to a single record, i.e. those items where the Display? property is set to Yes. List/Form zones may contain item groups and these groups may also be stacked.

Buttons in a List/Form zone

The zone may also contain buttons to query or delete records. The default captions for these buttons are:

Query	Invokes a dialog that allows the user to define search criteria to be incorporated when executing a query against the module component. This button is generated if the Query property for one or more items is set to Yes.
Add	Displays an empty record. This button is generated if the Insert property for one or more items is set to Yes.
Delete	Deletes the current record.  This button is generated if the Delete property for the module component is set to Yes.
Save	Saves changes to the current record. This button is generated if the Insert or Update property for one or more items is set to Yes.
Undo	Discards changes to current record. This button is generated if the Insert or Update property for one or more items is set to Yes.
Clear	Clears the zone. This button is generated if a Clear button is defined in the zone template.
If the zone has a control based on a 'Sequence In Parent' column, it will have resequence up/down buttons.

Default template form

The overall appearance and layout of this zone is determined by the CGTZListFormDefault template form.


Designing List/Form zones for Visual Basic applications
Designing List/Form zones

Related Topics	Where am I?

List/Form zones are similar to Form zones, except that a list box permanently displays the set of queried records, alongside a single-record view of the currently selected record. About

To set up a List/Form zone:

1.	In Design Editor, double-click the module component you require.

2.	Set the Layout Style property to 'List/Form'.

Tip: If you are using Property Dialogs this is on the Display tab.

3.	Click [image] or Finish to save the changes.

4.	Choose the item (or items) you want to display in the list box:

a.	Double-click the item you require.

b.	Set the Context? property to Yes.

Tip: If you are using Property Dialogs this is on the Display tab.

c.	Click [image] or Finish to save the changes.

It is counter intuitive for all the items in a List/Form zone to be marked 'Context'.

Further customization

Various preferences can be used to determine the appearance and layout of controls within a List/Form zone. About

To change the entire look and feel of a List/Form zone, modify the default template CGTZListFormDefault. How


About Form zones in Visual Basic applications
About Form zones

Related Topics

Form zones allow the user to browse through multiple records which are displayed, one row at a time, via standard next, previous, first, and last buttons. A 'Goto Record' button (...) is also provided. This displays a list of all the queried records, and allows the user to navigate directly to a specific record.

To create a Form zone, set the Layout Style property of the module component to 'Form' How

Controls in a Form zone

Form zones display a set of controls that map to a single record, i.e. those items where the Display? property is set to Yes. Form zones may also contain item groups and these groups may also be stacked.

The list of queried records displays those items where the Context? property is set to Yes.

Buttons in a Form zone

The zone may also contain buttons to add, undo, save or delete records. The default captions for these buttons are:

Query	Invokes a dialog that allows the user to define search criteria to be incorporated when executing a query against a particular module component. This button is generated if the Query property for one or more items is set to Yes.
Add	Invokes a property sheet dialog for creating records. This button is generated if the Insert property for one or more items is set to Yes.
Delete	Deletes the current record.  This button is generated if the Delete property for the module component is set to Yes.
Save	Saves changes to the current record. This button is generated if the Insert or Update property for one or more items is set to Yes.
Undo	Discards changes to current record. This button is generated if the Insert or Update property for one or more items is set to Yes.
Clear	Clears the zone. This button is generated if a Clear button is defined in the zone template.
Default template form

The overall appearance and layout of this zone is determined by the CGTZFormDefault template form.


Designing Form zones in Visual Basic applications
Designing Form zones

Related Topics	Where am I?

Form zones allow the user to browse through multiple records which are displayed, one row at a time, via standard next, previous, first, and last buttons. About

To set up a Form zone:

1.	In Design Editor, double-click the module component you require.

2.	Set the Layout Style property to 'Form'.

Tip: If you are using Property Dialogs this is on the Display tab.

3.	Click [image] or Finish to save the changes.

4.	Choose the item (or items) you want to display in the 'Goto...' list box:

a.	Double-click the item you require.

b.	Set the Context? property to Yes.

Tip: If you are using Property Dialogs this is on the Display tab.

c.	Click [image] or Finish to save the changes.

Further customization

Various preferences can be used to determine the appearance and layout of controls within a Form zone. About

To change the entire look and feel of a List/Form zone, modify the default template CGTZFormDefault. How


About property sheet dialog layout in Visual Basic applications
About property sheet dialog layout

Related Topics	Where am I?

Property sheet dialogs display the set of controls which map to a single record. They are used by Context and List zones to create, view and modify records. About

Property sheet dialogs inherit the preference settings defined for the zone. These topics describe aspects of the property sheet layout which may be changed:

•	vertical space usage

•	line space between controls

•	control alignment

•	control alignment within groups

•	text alignment within controls

•	radio group layout

•	placement of control prompts

Further customization

To change the entire look and feel of a property sheet dialog, modify the default template CGTWPsd. How


Designing query dialogs for Visual Basic applications
Designing query dialogs

Related Topics	Where am I?

Query dialogs can be generated for List, Form and List/Form zones. About

To create a Query dialog:

1.	In Design Editor, double-click the item you want to appear on the query dialog.

2.	Set the Query? property to Yes.

Tip: If you are using Property Dialogs this is on the Operations tab.

You may want the user to be able to perform a query on all the items, or just a subset. Lookup items and unbound items can also be included if required.

3.	Repeat steps 1 and 2 for each item you require.

4.	Click [image] or Finish to save the changes.

Further customization

To change the entire look and feel of a query dialog, modify the default template CGTWQd. How


About vertical space within a Visual Basic zone

Related Topics

By default, controls are laid out horizontally in the order they appear within the module component and depending on the number of controls and size of the form, the controls may be wrapped onto more than one line. This sometimes means that vertically short controls are adjacent to tall controls, creating areas of empty space.

One way to optimize use of this space is to set the Zone vertical fill (BLKVFL) preference to Yes. How

For example:

Zone vertical fill (BLKVFL) = No	Zone vertical fill (BLKVFL) = Yes
Note:	An alternative way would be change the display order of the items such that tall controls (or short controls) are displayed adjacent to each other. Drag and drop the items on the Module Diagram (in Display View) to resequence the items.

To further reduce the amount of vertical space you can change the line space between controls. How


Making use of vertical space within a Visual Basic zone
Making use of vertical space within a zone

Related Topics	Where am I?

You can optimize the use of vertical space on a generated form using the Zone vertical fill (BLKVFL) preference. About

To make use of vertical space:

1.	In Design Editor, display the Visual Basic Generator Preference Palette for the required module, or for the container (i.e. folder or application system). How

2.	Select the Layout - Zone branch and set the Zone vertical fill (BLKVFL) preference to Yes.

Note:	Setting this preference to Yes overrides the Number of controls per line (BLKMLF) preference.

3.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


About control alignment within a Visual Basic zone

Related Topics

You can define how controls are aligned within a zone using a set of default layout preferences or, if a more ordered layout is required you can use tabulation preferences. How

Default layout preferences

Together, these preferences can provide several different layout styles:

Preference		Default
Alignment of controls within zone	(BLKLYS)	Fill
Alignment of single control lines when BLKLYS is 'FILL'	( ITMSFJ)	Left
Number of controls per line	(BLKMLF)	Wrap
By default, controls are both left and right aligned to the longest line (BLKLYS=Fill) and single control lines are aligned to the left (ITMSJF=Left). Also, there is no restriction on the number of controls on each line (BLKMLF=Wrap). For example:

Tabulation preferences

Alternatively, you may align controls using a set of pre-defined tab stops which is achieved by setting two tabulation preferences. When set, these preferences override all the default layout preferences.

Preference		Default
Zone tabulation table	(BLKTAB)	2.20.42.60
Use zone tabulation table	(BLKUTT)	Use tab stops to align the start of the controls (SD)
Specific tab positions may be set up (BLKTAB) - the tab stops are defined in grid units. The number of tab stops also defines the maximum number of controls per line. Next, you choose what part of the control or prompt must align to these tabs stops (BLKUTT). For example:


Aligning controls within a Visual Basic zone
Aligning controls within a zone

Related Topics	Where am I?

You can define how controls are aligned within a zone using a set of default layout preferences or, if a more ordered layout is required you can use tabulation preferences. About

To align controls within a zone:

1.	In Design Editor, display the Visual Basic Generator Preference Palette for the required module, or for the container (i.e. folder or application system). How

2.	Set zone control alignment preferences as required.

Either, customize the default layout preferences using:

•	Alignment of controls within zone (BLKLYS)

•	Alignment of single control lines when BLKLYS is 'FILL' (ITMSFJ)

•	Number of controls per line (BLKMLF)

Or, set up tab stops to align controls using:

•	Zone tabulation table (BLKTAB)

•	Use zone tabulation table? (BLKUTT)

Note:	Tabulation preferences override the default layout preferences.

3.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


Creating custom zones styles in the Visual Basic template project
Creating custom zone styles in the template project

Related Topics	Where am I?

You can customize one of the template zone styles in order to handle a specific requirement. About

To create a custom zone template:

1.	If you have not already done so, make a copy of the default template project. How

2.	In Visual Basic Designer, open the copied Visual Basic project.

3.	Select the form on which you want to base your custom zone, one of:

•	CGTZContextDefault

•	CGTZFormDefault

•	CGTZListDefault

•	CGTZListFormDefault

•	CGTZUnboundDefault

4.	Change the name of the form.

For example, change the List zone template form name to CGTZMyListZone. This will be the name you will specify against the module component (see step 9).

5.	Choose File→Save As to save the new template as a new file with a different name.

6.	Choose Project→Add File to re-include the default template form in the template project.

7.	Change your custom template zone as required.

8.	Choose File→Save to save the changes.

9.	In Design Editor, use the Template/Library Object property to enter the name of the custom zone template against the module component. How

10.	Ensure that the Template project (TFPROJ) preference is set to the correct Visual Basic project (containing the custom zone).


Overriding the default zone appearance in Visual Basic applications
Overriding the default zone appearance

Related Topics	Where am I?

You use a custom zone template to override a zone's default appearance, or to handle a specific requirement. About

To override the default zone appearance:

1.	In Visual Basic Designer, create a custom zone template based on one of the default styles. How

2.	In Design Editor, double-click the module component that will use the custom template.

a.	Choose the Layout Style on which the custom template is based.

Tip: If you are using Property Dialogs this is on the Display tab.

b.	Use the Template/Library Object property to enter the name of the custom template form.

This name must correspond to the name you gave to your custom template within the template project.

If you leave the Template Object property blank, the default template for the selected Layout Style is used instead.

3.	Click [image] or Finish to save the changes.

4.	Ensure that the Template project (TFPROJ) preference is set to the correct Visual Basic project (containing the custom zone).

If an error message occurs during generation, then you have either spelt the name of the custom form wrong, or the Template project (TFPROJ) preference has not been set correctly.

Further customization

If the custom layout style contains any third-party controls, make sure they have been added to the control definition file. How


About buttons in Visual Basic applications

Related Topics

Template buttons

Push-buttons for performing general database operations are generated with a set of default captions. Alternative captions may be specified by modifying the appropriate template form. How

Generated buttons	Default captions	Template form
Main zone form*	Save, Undo, Add, View, Query, Delete	CGTCControls
Property sheet dialog	OK, Cancel, Clear, New	CGTWPsd
Query dialog	OK, Cancel, Apply Now, Undo	CGTWQd
Note:	* A generator action item can be defined to replace a template button on the main form. The caption of Generator action items is defined using the Prompt property. About

Navigation buttons

Additional navigational push-buttons are generated for zones which are linked to other zones, either via a master-detail relationship or module network link. The default captions for these buttons are derived as follows:

Buttons navigating to...	Default caption
Detail zones	Title property of detail module component
Linked modules	Short Title property of called module
These push-buttons are represented on the Module Diagram as navigation action items. To change the default caption, modify the Prompt property of the navigation action item. About

Custom buttons

To generate a button that executes user-defined application logic on a Visual Basic event, define a custom action item on the Module Diagram. About


Changing button captions in Visual Basic templates
Changing template button captions

Related Topics	Where am I?

You can define alternative captions for template buttons by modifying the appropriate template form. About

To customize the caption of a template button:

1.	If you have not already done so, make a copy of the default template project. How

2.	In Visual Basic Designer, open the copied Visual Basic project.

3.	Select the template form which defines the button, one of:

•	CGTCControls

•	CGTWPsd

•	CGTWQd

4.	Click the button and edit the Caption property as required.

5.	Choose File→Save to save the changes.

6.	Ensure that the Template project (TFPROJ) preference is set to the correct Visual Basic project (containing the custom button captions).


Customizing control group layout in Visual Basic applications
Customizing control group layout

Related Topics	Where am I?

You can modify Control Group preferences to customize the default layout of controls within a control group. About

To customize control group layout:

1.	To choose whether controls are laid out horizontally instead of vertically, change the Orientation property. In Design Editor, double-click the item group you require.

2.	From the Orientation property dropdown list, choose one of:

Horizontal	To display the control group items side by side.
Vertical	To display the control group items one about the other.
3.	To change the Control Group preferences, display the Visual Basic Generator Preference Palette for the required module, or for the container (i.e. folder or application system). How

3. 	Select the Layout - Group branch to set Control Group preferences:

Task	Preference
To align the start of controls	Use group tabulation tables (GRPUTT)=SD
To align the start of control prompts to the right	Use group tabulation tables  (GRPUTT)=SP
To align the end of split prompts	Use group tabulation tables  (GRPUTT)=EP
To specify the number of horizontally laid out controls per line	Control group multi-line format  (GRPMLF)
To modify the vertical gap between controls	Control group vertical inter-control spacing (GRPVIS)
To modify the horizontal gap between controls	Control group horizontal inter-control spacing (GRPHIS)
Note:	The horizontal layout preferences (GRPMLF and GRPHIS) have no effect when controls are laid out vertically (Orientation property=Vertical).

3.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.

Note:	Control group preferences do not effect the layout of stacked control groups. Stacked groups inherit the layout characteristics of the zone. How


About radio groups and radio buttons in Visual Basic applications

Related Topics

Radio button controls (also called option buttons) can be used to display allowable values. How

They are typically used when you want a user to select a single option, from a group of options. When any one radio button is selected, the other buttons within the group are automatically unset. For example,

Allowable values

To generate an item as a radio group, a set of allowable values must be defined for the item. How

If a radio group is based on an optional item (Optional? property) an extra 'null' or 'unknown' value is generated as shown in the example above.

Display property

You determine whether the radio buttons are laid out vertically or horizontally by setting the Display Type property on the item.

Radio Group (Across)	displays the radio buttons as a horizontal row
Radio Group (Down)	displays the radio buttons as a vertical row
Layout preferences

These are set at module level, and by default:

•	vertical radio buttons and their prompts are laid out within a radio group frame and the vertical space between each control is set at 0 grid units.

Preference		Default
Radio group vertical inter-button spacing	(RADVIS)	0
•	horizontal radio buttons and their prompts are laid out within a radio group frame. The buttons and their prompts are continued to be added as long as they fit, and the default horizontal space between the prompt of one button and and the next radio button is 2 grid units.

Preference		Default
Radio group buttons per line	(RADMLF)	Wrap
Radio group horizontal inter-button spacing	(RADHIS)	2
You can further customize the layout of radio buttons using radio group preferences. How

Customization

You can change the complete look and feel of radio buttons by modifying the Frame and/or OptionButton controls within the CGTCControls template. How

Alternatively, a custom radio group control type may be specified using the Default Radio Group control type (CTLRAD) preference. How


Creating radio groups and radio buttons in Visual Basic applications
Creating radio groups and radio buttons

Related Topics	Where am I?

You can generate a radio button control when you want a user to select a single option from a group of options. About

To generate an item as a radio group:

Before you start, ensure that a set of allowable values are defined for the item. How

1.	In Design Editor, double-click the item you require.

2.	From the Display Type dropdown list, select:

Radio Group (Across)	to display the radio buttons laid out horizontally.
Radio Group (Down)	to display the radio buttons laid out vertically.
Tip: If you are using Property Dialogs this is on the Display tab.

3.	(Optional) If more descriptive meanings are defined against all the allowable values, select Meaning Only from the Show Meaning dropdown list.

If the Optional? property is set to Yes, an extra radio button for 'Unknown' is generated. If you are using Property Dialogs this is on the Definition tab.

4.	Click [image] or Finish to save the changes.

Next step

You can further customize the layout of radio buttons using radio group preferences. How


Customizing radio group layout in Visual Basic applications
Customizing radio group layout

Related Topics	Where am I?

You can customize the layout of radio buttons using preferences. About

To customize radio group layout:

1.	In Design Editor, double-click the item you require.

2.	From the Display Type dropdown list, choose one of:

Radio Group (Across)	To display values as a horizontal row of radio buttons
Radio Group (Down)	To display values as a vertical row of radio buttons
Tip:	If you are using Property Dialogs this is on the Display tab.

3.	Display the Visual Basic Generator Preference Palette for the required module, or for the container (i.e. folder or application system). How

4.	Select the Layout - Control branch to set Radio Group preferences.

Task	Preference
To change the vertical gap between buttons	Radio group vertical inter-button spacing (RADVIS)
To define the number of horizontally laid out radio buttons per line	Radio group buttons per line  (RADMLF)
To modify the horizontal gap between controls	Radio group horizontal inter-button spacing (RADHIS)
Note:	The vertical layout preference (RADVIS) has no effect when the radio buttons are laid out vertically, i.e. the Display Type property is set to Radio Group (Across).
The horizontal layout preferences (RADMLF and RADHIS) have no effect when radio buttons are laid out vertically, i.e. the Display Type property is set to Radio Group (Down).

5.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


About text lists and pop lists in Visual Basic applications

Related Topics

Text List and Pop List controls can be used to display lists of allowable control values and single column foreign key lookups. How

Text Lists provide vertical scroll bars which allow a user to scroll up and down the list of available options. Pop Lists provide a single 'down arrow' that displays a dropdown list of options.

For example:

Text List
Pop List
Allowable values

If allowable values are defined for the item, they can be displayed in the Text List or Pop List. How

If the control is based on an optional item (Optional? property), an extra 'null' or 'unknown' value is generated.

Suggested values

You can create a list of suggested values for bound controls. How

For suggested values, the Pop List control effectively becomes a Drop Down Combo Box. This control allows a user to either select a value from the list, or enter a different value of their choice.

Customization

The look and feel of text lists may be customized by modifying the ListBox control within the CGTCControls template. Similarly, Pop Lists may be customized using the ComboBox control. How

Alternatively, you can override the default control types using the Default ListBox control type (CTLLST) and Default ComboBox control type (CTLCMB) preferences. How


Creating text lists and pop lists in Visual Basic applications
Creating text lists and pop lists

Related Topics	Where am I?

You can generate text list and pop list controls to display lists of allowable control values and single column foreign key lookup values. About

To generate an item as a text or pop list:

If you want to generate a text list or poplist that displays a list of allowable values, ensure they have been defined. How

1.	In Design Editor, double-click the item you require.

2.	From the Display Type dropdown list, choose one of:

Text List	To display values in a text list
Pop List	To display values in a dropdown list
Tip:	If you are using Property Dialogs this is on the Display tab.

3.	(Optional) If more descriptive meanings are defined against all the allowable values, select Meaning Only from the Show Meaning dropdown list.

Note:	Meanings are not displayed in a suggested list of values.

If the Optional? property is set to Yes, an extra value for 'Unknown' is generated. If you are using Property Dialogs this is on the Definition tab.

4.	Click [image] or Finish to save the changes.


About check boxes in Visual Basic applications

Related Topics

A check box displays a check mark (e.g. X) when selected, which disappears when the check box is cleared. Use this type of control to give the user a True/False or Yes/No option. You can also use check boxes in groups to display multiple choices from which the user can select one or more. How

Allowable values

To generate an item as a check box control, suitable allowable values must be defined against the item. How

•	for mandatory items, two values must be defined

•	for optional items, only one value need be defined as the second value automatically becomes 'null' or 'unknown'

•	the allowable value with the lowest sequence number defines the 'true', or 'checked' state.

•	if no default is defined (Default Value property), the check box initially appears unchecked.

Note that allowable values for checkboxes are always hardcoded in the generated application i.e. the Dynamic List? property is ignored.

Note:	Use domains to define a common set of allowable values which can be reused across multiple columns and unbound items e.g. Yes / No values for check boxes. About

Customization

A custom check box control type may be specified using the Default Check box control type (CTLCHK) preference. How


Defining check boxes in Visual Basic applications
Defining check boxes

Related Topics	Where am I?

You can generate an item as a check box to give the user a True/False or Yes/No option. You can also use check boxes in groups to display multiple choices from which the user can select one or more. About

To generate an item as a check box:

Before you start, ensure that appropriate allowable values are defined for the item. How

1.	In Design Editor, double-click the item you require.

2.	From the Display Type dropdown list, select Check Box.

Tip: If you are using Property Dialogs this is on the Display tab.

4.	Click [image] or Finish to save the changes.


About line spacing between controls in a Visual Basic application
About line spacing between controls in Visual Basic applications

Related Topics

You can modify the vertical space between controls using preferences. How

•	Vertical space separating controls (BLKMLL)

•	Control group vertical inter-control spacing (GRPVIS)

The vertical space is defined in grid units, where the height of a grid unit is pre defined by the Visual Basic design environment (default 120 twips).

Default line spacing

The default settings are designed to optimize the use of space and reduce the overall size of the generated form. Where form size is not critical you may choose to increase the line spacing and improve the visual appearance. For example:

Vertical space separating controls (BLKMLL) = 1
Control group vertical inter-control spacing (GRPVIS) = 0

Custom line spacing

Where form size is not critical you may choose to increase the line spacing and improve the visual appearance. For example:

Vertical space separating controls (BLKMLL) = 2
Control group vertical inter-control spacing (GRPVIS) = 1

Note:	The GRPVIS preference does not apply to stacked groups. Stacked groups inherit the line spacing defined for the zone, using BLKMLL.

Further customization

You may fine tune the line spacing by modifying the grid size of the Visual Basic design environment, prior to generation. The settings for grid height and width can be set by selecting Tools→Options in the Visual Basic design environment.


About text controls in Visual Basic applications

The size of radio groups and check box controls is determined by the prompts defined against the item and (for radio groups) the allowed values/meanings. For other text based controls, the size and shape of the text box may be modified using the item display properties Width and Height. How

Note:	The overall display size is not limited by the number of characters the column can store.

Width

This property defines the display length of the text box, in characters. The width required for the control is computed by multiplying this value by the average character cell width of the font and adding in an overhead for the left and right margins, as defined by the LayoutWidthOverhead setting in the control definition file.

If this property is undefined, the Default text control display length preferences are used instead.

Note:	This property has no effect for 'Checkboxes' and 'Radio Groups'.

Height

This property defines the number of lines to display in a text box or text list. The height required for the control is computed by taking the height of the template control and then adding the average font height for each extra line.

Note: 	This property has no effect for Pop List, Check Box and Radio Group style controls.

Text alignment

Values within text box may be aligned to the left (default), center or right using the Alignment property of the item. This property only applies if the Display Type of the item is set to Text. How


Setting the size of text based controls in Visual Basic applications
Setting the size of text based controls

Related Topics	Where am I?

You can determine the width and height of text based controls using the item display properties, Width and Height. About

To define the size of a text based control:

1.	In Design Editor, double-click the item you require.

2.	Use the Width property to define the width, in characters.

Tip: If you are using Property Dialogs this is on the Display tab.

3.	Use the Height property to define the height, in lines.

4.	Click [image] or Finish to save the changes.


Changing the text alignment within controls in Visual Basic applications
Changing the text alignment within controls

Related Topics	Where am I?

Values within text style controls may be aligned to the left (default), center or right using the Alignment property of the item. About

To align text within a text control

1.	In Design Editor, double-click the item you require.

2.	From the Alignment dropdown list, select the alignment option you require.

Tip: If you are using Property Dialogs this is on the Display tab.

3.	Click [image] or Finish to save the changes.


Changing the line spacing between controls in Visual Basic applications
Changing the line spacing between controls

Related Topics	Where am I?

You can modify the vertical space between controls using preferences. About

To modify the vertical spacing:

1.	In Design Editor, display the Visual Basic Generator Preference Palette for the required module, or for the container (i.e. folder or application system). How

2. 	To set the spacing, use these preferences to enter the number of grid units you require.

Task	Preference
To set the spacing within control groups.	Control group vertical inter-control spacing (GRPVIS)
To set the spacing for zones and stacked control groups.	Vertical space separating controls (BLKMLL)
3.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


About prompt/control layout in Visual Basic applications

Related Topics

Prompts are used to identify controls in a generated application. You can modify the appearance and layout of controls and their prompts using preferences. How

Default layout

Custom layout options

Change or remove the character separating the prompt from its control
Modify the space between prompts and controls modified
Change the position of the prompt, relative to its control
Template customization

You may change the font used for prompt text by modifying the Font property of the control prompts defined within the CGTCControls template. How

For example,


Defining how prompts/controls are displayed in Visual Basic applications
Defining how prompts/controls are displayed

Related Topics	Where am I?

Prompts are used to identify controls in a generated application. You can modify the appearance and layout of controls and their prompts using preferences. About

To modify prompt/control layout

1.	In Design Editor, display the Visual Basic Generator Preference Palette for the required module, or for the container (i.e. folder or application system). How

2. 	To modify prompt layout, set the required preferences from the Layout-Control branch.

Task	Preference
To change, or remove the character that separates the prompt from its control.	Default prompt separator (ITMDPS)
To increase or decrease the space between controls.	Control/prompt gap (ITMIPG)
To increase or decrease the space between a control and its prompt.	Prompt/control gap (ITMPIG)
To place prompts above controls.	Allow prompts above controls (ITMPAS)
3.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


About splitting control prompts in Visual Basic applications

Related Topics

Prompts are used to identify controls in a generated application and normally they appear to the left or above their control. Using preferences and special character markers, you can split prompts and change their position (relative to their control).

•	 Control post prompt marker (ITMPPM)

•	 Control split prompt marker (ITMSPM)

First use the appropriate preference to define the character marker you want to use. How

Then insert the character marker at the point where the prompt is to be split. How

Preference value	Prompt	Example
ITMPPM = |	Distance | (Miles)
ITMSPM = *	First * Name


Defining Split prompt markers in Visual Basic applications
Defining a split prompt marker

Related Topics	Where am I?

You can use preferences to define special character markers that indicate where prompts are split and hence change the prompt position (relative to their control). About

To define split prompt markers:

1.	In Design Editor, display the Visual Basic Generator Preference Palette for the required module, or for the container (i.e. folder or application system). How

2. 	Select the Layout - Control branch and use the prompt marker preferences to specify the special characters you want to use.

Task	Preference
To change the post prompt marker.	Control post prompt marker (ITMPPM)
To define or change the split prompt marker.	Control split prompt marker (ITMSPM)
Tip:	We recommend you set the ITMSPM and ITMPPM to different special characters.

3.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.

4.	Insert the new marker within item prompts as required. How


Defining prompts with markers in Visual Basic applications
Defining prompts with markers

Related Topics	Where am I?

You can insert special character markers within item prompts to indicate where prompts are split and hence change the prompt position (relative to their control). About

To define a prompt with a marker:

1.	In Design Editor, double-click the item you require.

2.	In the Prompt field, insert the special marker character to indicate where the prompt must be split.

Tip: If you are using Property Dialogs this is on the Display tab.

The Prompt marker preferences define the characters that must be used.

3.	Click [image] or Finish to save the changes.


About adding color to controls in Visual Basic applications
About colored controls in Visual Basic applications

You can help users identify whether controls are optional, mandatory or read-only through the use of color. For example:

To generate this type of application you first need to customize the colored template project (TMPTCLR.VBP) using the Visual Basic design environment. How

Then, you use the Template project (TFPROJ) preference to specify the name of the custom (colored) template project you intend to use.


Creating a custom color Visual Basic template project

Related Topics 	Where am I?

You can help users identify whether controls are optional, mandatory or read-only through the use of color. About

To create a custom color template project:

1.	If you have not already done so, make a copy of the default color template project (cvb5tmpt1\tmptclr.vbp). How

2.	In Visual Basic Designer, open the copied Visual Basic project.

3.	Select the form which defines the colored controls, CGTCControls.

4.	Change the BackColor property for the different types of controls as required.

5.	Choose File→Save to save the changes.

6.	In Design Editor, specify the name of the custom color template project using the Template project (TFPROJ) preference for the required Visual Basic module, or for the container (i.e. folder or application system). How

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


Changing default control types for Visual Basic applications
Changing default control types

Related Topics	Where am I?

During generation, the Display Type defined against items are mapped to a set of Visual Basic control types. You can define that all controls of a given type (e.g. Check box) use a different control type, by changing the appropriate default mapping preference. About

To change a default control type:

1.	In Design Editor, display the Visual Basic Generator Preference Palette for the required module, or for the container (i.e. folder or application system). How

2. 	Select the Controls branch to set the required Control Type Mapping preference.

Note:	The control (or at least, its type) must appear in the control definition file. About

3.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


Overriding default control types in Visual Basic applications
Overriding default control types

Related Topics	Where am I?

Sometimes, you may need a non-standard type of control to be generated for a particular item instead of the default control. About

To override default control types:

1.	Ensure that the custom control is registered correctly:

a. 	The new control must exist in the controls template form. About

b.	The new control type must exist in the Control Definition file. How

2.	In Design Editor, double-click the item that will use the custom control.

3.	Use the Template/Library Object property to enter the name of the custom control.

Tip: If you are using Property Dialogs this is on the Display tab.

This name must correspond to the name you gave the custom control in the template project and control definition file.

If you leave the Template/Library Object property blank, the default control is used instead. About

4.	Click [image] or Finish to save the changes.


Registering third-party controls to the Visual Basic template form
Registering third-party controls in the template controls form

Related Topics	Where am I?

A set of standard controls are registered in the default Visual Basic template controls form. You can add third-party controls, if required. About

To register a third-party control to the template controls form:

1.	If you have not already done so, make a copy of the default template project. How

2.	In Visual Basic Designer, open the copied Visual Basic project.

3.	Choose Project→Components to add a reference to the custom control in the template project.

4.	Add an instance of the custom control to the CGTCControls template form.

5.	Set the properties of the custom control as required.

For example, change the font, colors and so on.

6.	Use File→Save to save the modified templates.

Next step

To make use of the third-party control during generation you must add the new control type to the control definition file. How

To define that all controls of a given type (e.g. Check box) use the new control, set the appropriate Control type mapping preference at the module or container (i.e. folder or application system) level. How

To generate a specific item using the new control (instead of its default type), set the Template/Library Object property for the item. How


Adding new control types to the control definition file

Related Topics Where am I?

A set of standard control types are defined in the default Visual Basic control definition file. You can add third-party controls types, if required. About

To add a new control type to the control definition file:

1.	Using Notepad, or a similar text editor, open CTLDEF.TXT.

This is located in the Visual Basic Generator's \cvbetc installation directory.

2.	Create a section header, by typing the name of the control type within square brackets.

All further entries within that section will refer to that control type.

3.	Use the BasicControlType property to define the basic control class.

There are five basic classes: TEXT, LIST, CHECK, RADIO, OTHER.

4.	Add the following entries, as required:

•	control suitability entries About

•	property name entries About

•	property value entries About

•	other "uncategorized" entries About

For example, a section for the Control TextBox type might be entered in the control definition file as follows:

[Control TextBox]
BasicControlType="TEXT"
ControlNamePrefix="txt"
MaxLengthProp="MaxLength"
LayoutWidthOverhead = 120
MultilineProp="MultiLine"
ScollBarProp="ScrollBars"
ScrollBarValueNone=0
ScrollBarValueHorizontal=1
ScrollBarValueVertical=2
ScrollBarValueBoth=3

5.	Choose File→Save As to save the edited file with a different name in a separate directory e.g. MYCTLDEF.TXT.

6.	When you are ready to use the new third-party control, set the Control definition file (CTLDEF) preference at container (i.e. folder or application system) level using Design Editor. How

This preference specifies the control definition file to be used during generation.

Next step

To make use of the third-party control during generation you must register the new control type in the Controls template form. How

To define that all controls of a given type (e.g. Check box) use the new control, set the appropriate Control type mapping preference at the module or container (i.e. folder or application system) level. How

To generate a specific item using the new control (instead of its default type), set the Template Object property for the item. How


Customizing the Visual Basic template project

Related Topics	Where am I?

You can modify the set of shipped template forms if you wish. For example, you may want to customize the appearance of generated forms, add third-party controls to your application or generate a non-English application. About

Important:	Do not modify the shipped templates directly; always take a copy first.

To customize the Visual Basic template project:

1.	Use File Manager/Windows Explorer to create a new directory for the new templates.

In a team environment, do this on a network drive so that the entire team can access them using a consistent drive letter.

2.	Copy all the files from the \cvb5tmpt1 directory to this new directory.

3.	In Visual Basic Designer, open the copied project and amend the files as required:

•	Do not remove any controls that are mandatory (see Templates for guidance).

•	When replacing an existing template control with a new control of a different control type, ensure that the Name and Tag properties are consistent with the control being replaced.

4.	When you are ready to use the amended template project, set the Template project (TFPROJ) preference at container (i.e. folder or application system) level to specify the amended template project.  How


Customizing the Visual Basic library project

Related Topics	Where am I?

If you need to add or modify library forms and code modules you can customize the default library project. About

To customize the default library project:

1.	Use File Manager/Windows Explorer to copy the default library project you want to use to a new file.

Choose the applicable project file for the data access method:

Data access method	Default library project
Oracle Objects for OLE	cvb5vblib\incl.vbp
Visual Basic Data Access Objects (DAO)	cvb5vblib\incldao.vbp
In a team environment, do this on a network drive so that the entire team can access them using a consistent drive letter.

2.	In Visual Basic Designer, open the new project.

3.	Choose Project→Add File to add extra files, as required.

4.	Save the new project.

5.	When you are ready to use the amended template project, set the Library (standard inclusions) project (MGPROJ) preference at container (i.e. folder or application system) level to specify the name of this new library project file. How


Specifying the Visual Basic library project

Related Topics	Where am I?

You can specify a custom library project file (.VBP) to be used during generation. About

To specify the Visual Basic library project:

1.	If you have not done so already, customize the library project as required. How

2.	In Design Editor, display the Visual Basic Generator Preference Palette for the container (i.e. folder or application system). How

3. 	Select the Template branch and use the Library (standard inclusions) project (MGPROJ) preference to specify the library project you want to use.

4.	Click [image].

Whenever you change any of the preference values, you need to generate the affected module(s) again, according to the level at which the preference has been set.


Generating Visual Basic applications for use in other countries

Where am I?

To generate Visual Basic applications where the visible text is not English, the following steps are required.

1.	Ensure Visual Basic Generator uses the appropriate language option.

During generation the appropriate generation message file for your language (cvx<lang>.msb) must be used. This file is chosen by the Generator, according to the NLS_LANG parameter defined under the HKEY_LOCAL_MACHINE\Software\Oracle registry entry.

The languages supported (and corresponding values for <lang>) are:

<lang>	Language	<lang>	Language
cs	Czech	pl	Polish
d	German	pt	Portuguese
dk	Danish	ptb	Brazilian Portuguese
e	Spanish	ru	Russian
el	Greek	s	Swedish
f	French	sf	Finnish
hu	Hungarian	sk	Slovak
i	Italian	tr	Turkish
n	Norwegian	us	American
nl	Dutch
2.	Edit text in the Visual Basic Generator template forms.

Several textual strings are located and copied from the template forms shipped with the Visual Basic Generator. These templates are stored under the \cgenv61\cvb5tmpt* directories of your Oracle Designer installation. The majority of these strings define default captions for menu items and buttons and any translation required must be done manually. First, copy or backup the template project you want to use. Then, open the project in Visual Basic Designer and carry out the translation by directly editing the controls and menus.

3.	Add the appropriate translated library file to the Visual Basic Generator 'Standard Library' project you intend to use (incl.vbp or incldao.vbp)

All the end user text located in library forms (e.g. Logon and List of Values forms) and library code is extracted as a set of global constants and defined in a separate Visual Basic module file named cgenv61\cvb5vblib\lm.bas. Translated versions of this file are named lm<lang>.bas and they appear in the cgenv61\cvb5vblib directory of your Oracle Designer installation.

To incorporate the translated file for your target language, first open the standard library project you intend to use (incl.vbp or incldao.vbp) in the Visual Basic design environment.

Data Access Method	Library Project
Oracle Objects for OLE	cvb5vblib\incl.vbp
Visual Basic Data Access Objects (DAO)	cvb5vblib\incldao.vbp
Then, using the File→Remove File and File→Add File menu items, replace the default version of this file (lm.bas) which uses the language selected at install time with the required alternative. This step is not performed automatically by the installation and must be done manually

4.	Use the appropriate language, when defining any textual display properties within Visual Basic modules.

For example, the text property 'Title' (for module components) and 'Prompt' (for items) will be displayed in a generated application and thus should be defined in the required language.

These tasks outline the additional steps required to create Visual Basic applications in languages other than English. Once complete, generate the application in the usual way. How


About multiple module Visual Basic applications

Related Topics

To combine a set of modules into one integrated application you may need to further define the structure of the application by setting up module network links. How

You may also want to introduce extra modules to provide additional navigation, for example:

•	create a module for a Visual Basic launch screen How

•	add menu modules to the Visual Basic application How


Creating a module for a Visual Basic launch screen

Related Topics	Where am I?

You can generate a launch screen for your Visual Basic application by defining an additional, top-level module that contains navigation action items. About

To create a module for the launch screen:

1.	In Design Editor, choose Options→Use Property Dialogs.

2.	On the Navigator, select the module branch and choose Edit→Create

3.	Enter the following mandatory properties:

Module Type

Module Short Name

Purpose

Language

4.	Click Next and enter the following information (as appropriate):

Button/Menu Text (Short Title)

Main Window Title (Top Title)

Command Line

5.	(Optional) Click Next again and enter an Implementation Name.

6.	If you intend to generate on-line Help for your Visual Basic application, click Next and then enter Help Text against this top-level module.

This text will appear on the Contents topic of the generated Help file. See Generating MS Help for Windows applications for more information.

7.	Click Finish to save.

8.	Create a window definition for the launch screen module.

a.	On the Navigator, select the Window branch and choose Edit→Create.

b.	Enter the following information (as appropriate):

Name	The name of the window.
Window Title	The window title for the launch screen.
Template/Library Object	The name of a custom Visual Basic template window.
c.	Click Finish to save.

8.	Create a module navigation action item for each module you want to link from the launch screen. How

Module navigation action items on a launch screen are generated as a series of buttons. About


Adding menus modules to Visual Basic applications
Adding menu modules to Visual Basic applications

Related Topics	Where am I?

You can create menu modules to group several module links together under a single menu option and form menu hierarchies. About

To add a Menu module:

1.	In Design Editor, choose Options→Use Property Dialogs

2.	On the Navigator, select the module branch and choose Edit→Create

3.	Set the Module Type property to Menu.

4.	Enter the following mandatory properties:

Module Short Name

Purpose

Language

5.	Click Next and enter the Menu Caption.

All modules that link directly from this menu module are added beneath the menu option defined here.

6.	Click Next to create module network links:

a.	Click Select Modules and choose the set of modules to link to, from this menu.

b.	If there is more than one called module, use the Up and Down arrows to define the order in which the menu items are displayed in the application.

7.	Click Finish to save.