OS/2 Shareware BBS: Product/Product.zip/visdevin.zip/FTD1OAD4.INF

OS/2 Help File | 1994-07-12 | 326KB | 2,663 lines

ΓòÉΓòÉΓòÉ 1. Notices ΓòÉΓòÉΓòÉ

References in this publication to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program, or service is not intended
to state or imply that only IBM's product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe any
of IBM's intellectual property rights may be used instead of the IBM product,
program, or service. Evaluation and verification of operation in conjunction
with other products, except those expressly designated by IBM, is the user's
responsibility.

IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:

IBM Corporation
IBM Director of Licensing
208 Harbor Drive
Stamford, Connecticut 06904-2501
U.S.A.

This publication contains examples of data and screens used in daily business
operations. They are intended only to be illustrative of the type of functions
available in IBM Visualizer Development and may contain the names of
individuals, companies, brands, and products. All of these names are
fictitious, and any similarity to the names and addresses used by an actual
business enterprise is entirely coincidental. Screens shown in this publication
are intended to be examples and may not be exact representations of actual
screens.

This publication contains sample programs. Permission is hereby granted to copy
and store the sample programs into a data processing machine and to use the
stored copies for internal study and instruction only. No permission is granted
to use the sample programs for any other purpose.


ΓòÉΓòÉΓòÉ 1.1. Trademarks ΓòÉΓòÉΓòÉ

The following terms, denoted by an asterisk (*), used in this publication, are
trademarks or service marks of IBM Corporation in the United States of America
or other countries:

Common User Access                                OS/2
CUA                                               Presentation Manager
DB2/2                                             SAA
Systems Application Architecture                  Ultimedia

The following terms, denoted by a double asterisk (**), used in this
publication, are trademarks of the following companies:

dBASE lll                                         Borland International, Inc.
80386                                             Intel
80486                                             Intel
Lotus                                             Lotus Development Corporation
Windows                                           Microsoft Corporation


ΓòÉΓòÉΓòÉ 1.2. About this book ΓòÉΓòÉΓòÉ

This book introduces IBM Visualizer Development for OS/2 with information on
its components, and the types of menu, window and their components that it
supports. It also contains a step-by-step guide to building the interface to,
and automatically generating the code for a simple application.

Visualizer Development for OS/2 is referred to in this book as Visualizer
Development.


ΓòÉΓòÉΓòÉ 1.3. Who should use this book? ΓòÉΓòÉΓòÉ

This book is for programmers who want to develop applications with Visualizer
Development. The book is also for user interface designers who want to use
Visualizer Development to produce prototypes of user interfaces.

This book assumes a basic familiarity with OS/2. If your applications or
prototypes will manipulate Visualizer Query for OS/2 objects, a familiarity
with Visualizer Query for OS/2 will be helpful. Consult the Visualizer Query
for OS/2 documentation, starting with IBM Visualizer Query for OS/2: Using,
SH45-5089.

If your applications or prototypes will manipulate Visualizer Charts, then a
familiarity with Visualizer Charts for OS/2 will be helpful. Visualizer Charts
is referred to in this book as Charts. Consult the Charts documentation,
starting with IBM Visualizer Charts for OS/2: Using, SH45-5097.

If you are using Visualizer Development to develop complete applications, any
previous programming experience will be helpful, though this need not include
experience with object-oriented programming. If you are only using Visualizer
Development to produce prototypes of user interfaces, no programming experience
is necessary.


ΓòÉΓòÉΓòÉ 1.3.1. What you need to know ΓòÉΓòÉΓòÉ

Before you read this book, you should be familiar with the following:

o The OS/2* 2.1 environment within which you will use Visualizer.

o These OS/2 concepts:

   - Mouse and keyboard use
   - Objects and folders
   - Window parts
   - Online help

To learn about OS/2, do one or more of these:

o Open the Master Help Index for explanations of how to use OS/2.

o Open the Information folder, which is in your OS/2 System folder, to access
  the Glossary, Command Reference, and Tutorial.

o Refer to OS/2 documentation, such as IBM OS/2 2.1: Using the Operating
  System.


ΓòÉΓòÉΓòÉ 1.3.2. How this book is structured ΓòÉΓòÉΓòÉ

This book has the following chapters:

o Installing Visualizer Development, outlines the installation prerequisites,
  and tells you how to install the product.

o Introducing Visualizer Development, provides a short overview of the product.

o Windows and the graphical interface, describes the types of window, window
  controls and menus that you can construct with Visualizer Development.

o More about the components, describes the Visualizer Development components in
  greater detail.

o Building your first application, contains a set of 10 exercises leading to
  completion of a simple application.


ΓòÉΓòÉΓòÉ 1.3.3. How to use this book ΓòÉΓòÉΓòÉ

There are two distinct elements in this book:

o Information for you to read-contained in Introducing Visualizer Development,
  Windows and the graphical interface, and More about the components.

  It is not necessary to read this before you start the exercises. However, it
  is recommended that you read it sometime, particularly if you are not
  familiar with Common User Access guidelines on interface design.

o A set of 10 exercises leading to the completion of a simple
  application-contained in Building your first application.

  This is the most important chapter in the book. It provides an opportunity to
  learn about Visualizer Development by using it.

  If you prefer, start with this chapter, but make sure first that Visualizer
  Development is installed correctly.


ΓòÉΓòÉΓòÉ 1.3.4. Other sources of information ΓòÉΓòÉΓòÉ

Other sources of information on Visualizer Development are:

o IBM Visualizer Development for OS/2: Using, SH45-5095, which tells you how to
  use the product and contains several worked examples on developing
  applications

o IBM Visualizer Development for OS/2: Reference, SH45-5096, which documents
  Application System Language (ASL) in detail

o The online help for the editors

o The online help for ASL

o The samples applications in the Development Samples folder


ΓòÉΓòÉΓòÉ 1.3.5. Getting online help ΓòÉΓòÉΓòÉ

To get online help when you are using one of the editors, select the Help menu
or the Help push button. If you have not used OS/2 help before, select Using
help from any Help menu.

Reference information on ASL objects, functions, and statements is available
from the edit window of the Program editor. The easiest way to get information
on a specific language element is to highlight the word in your code, or
position the text cursor over it, then press F1. Alternatively, you can obtain
this help by selecting Syntax help from the Help menu.

If you are using another editor to edit a program, use the following OS/2
command:

C:\OS2\VIEW FTD1OAD2.INF

or

C:\OS2\VIEW FTD1OAD2.INF keyword

where keyword is an ASL statement or object.


ΓòÉΓòÉΓòÉ 1.3.6. Late news ΓòÉΓòÉΓòÉ

Information that was not available when this book was published may be found in
the online book, Extra Information, in the Development Manuals folder.


ΓòÉΓòÉΓòÉ 2. Introducing Visualizer Development ΓòÉΓòÉΓòÉ

This chapter provides a short overview of Visualizer Development and outlines
how to use it with other Visualizer products.


ΓòÉΓòÉΓòÉ 2.1. About Visualizer Development ΓòÉΓòÉΓòÉ

Visualizer Development is a set of application development tools, including an
object-oriented language, Application System Language (ASL). You can use it to
design and build applications, extending the database query capabilities of
Query for OS/2 to your own requirements. Your applications can be run on any
system containing Query for OS/2.

Visualizer Development applications run under Presentation Manager* and can use
windows, push buttons, menus, and other graphical window controls. Visualizer
Development generates code for handling the graphical user interface. You add
the code for processing the user's data. This means that you can quickly
produce a prototype of an application and do the programming later.

The components of Visualizer Development are as follows:

Menu editor

Use this to create menus. You can specify mnemonics and shortcut key sequences
for each menu choice.

Window editor

Use this to create windows. You can put a menu bar on a window and include
menus previously created with the Menu editor. Standard window controls, such
as push buttons, the Maximize button, Minimize button, and scroll bars, are
available.

Program editor

Use this to edit ASL programs. In addition to performing the usual editing
functions, the Program editor structures the code into blocks, generates code
for handling the user interface, indents code and capitalizes keywords, and
checks the syntax.

Make

Use this to maintain a list of the windows, menus, and programs in an
application and to compile some or all of the items in the list. Using the Make
facility is optional, but it is useful for large applications.

The ASL interpreter runs the application you created with Visualizer
Development whenever the application is selected from the desktop. (The ASL
interpreter is supplied as part of Query for OS/2.)

Applications that you develop, do not need Visualizer Development in order to
run. You need only have Visualizer Query for OS/2.

Note:   Refer to Windows and the graphical interface, for more information
about these components.

Visualizer Development has the following features:

o Facilities for building end-user interfaces

o Easy prototyping

o Support for compliance to Common User Access (CUA) guidelines

o Application programming interfaces (APIs) for connection to other Visualizer
  Query for OS/2 objects such as Chart and Report

o Shared data and common end-user interfaces with hosts and other PS/2* systems

o Support for hosts and other PC connections, including facilities for handling
  different file types (Lotus**, dBASE III**, Integrated Exchange Format (IXF),
  and ASCII)

o Ability to link to existing applications written in C to an application end
  user interface through the Window and Menu facilities

o Ability to link, through SQL, to OS/2. Database Manager, DB2/2* databases or
  other remote databases

o Ability to link to the OS/2 Help Manager (Information Presentation Facility)
  to associate online help with your applications

o Ability to link to mail systems that support the simple messaging interface
  (SMI) functions of the vendor-independent messaging (VIM) specification

o Support for multimedia

The following window is an illustration of an application, created using
Visualizer Development:


ΓòÉΓòÉΓòÉ 2.2. Using Visualizer Development with other parts of the Visualizer family ΓòÉΓòÉΓòÉ

You can use Development to create OS/2 Presentation Manager* applications that
may then be run on any system containing Visualizer Query for OS/2.
Applications created using Visualizer Development can take advantage of links
to any of the Visualizer objects, such as Visualizer Report and Visualizer
Chart. You can also use your applications in a Visualizer Procedure, automating
your regular tasks.

Visualizer Development provides the powerful programming language Application
System Language (ASL). ASL is an event-driven high-level language, possessing a
wide range of built-in functions. It embodies many of the principles of
object-oriented programming, and was extensively used to develop the facilities
of the Visualizer product - including the development of Visualizer Development
itself. It is designed to enable users to build applications that can conform
to the IBM Common User Access (CUA) and Systems Application Architecture (SAA)
guidelines with the minimum of effort.

There are two distinct sets of tasks you can perform with Development:

o Creating the end user interface, or prototyping
o Creating program code which actually does the processing

When you choose to prototype, you can build an application in separate, though
related, stages. You can generate code from a WYSIWIG interface, with which you
design the interface by selecting controls from a palette, and then the code is
generated automatically for you.

Development contains a debugger sample application which you can use to debug
any application you are writing. You can use the debugger application to:

o Walk through your compiled ASL application
o Set break points in the executing ASL application
o Query and modify any variables and objects in the application
o Display the data and objects that are active in the current application.


ΓòÉΓòÉΓòÉ 2.3. Using Visualizer Development with other Visualizer products ΓòÉΓòÉΓòÉ

This short section lists the prerequisites for using Visualizer Development
with other products in the Visualizer range. They are:

o To use Visualizer Development, you need to have Query for OS/2 installed.

o To use Visualizer Charts with Visualizer Development, you need to have
  Visualizer Charts installed.

o To run an application that you develop with Visualizer Development, your
  end-users need to have Query for OS/2 installed. If your application uses
  Visualizer Charts, your end-users also need to have Visualizer Charts
  installed.

With Query for OS/2 Version 1.1, you can create applications that end-users can
run without having Query for OS/2 installed.

o If your application uses Visualizer Tables, Visualizer Reports, SQL
  Statements or Data Browser, your end-users need to have Query for OS/2
  installed.

o If your application uses Visualizer Charts, your end-users need both
  Visualizer Charts and Query for OS/2 installed.


ΓòÉΓòÉΓòÉ 2.4. What next? ΓòÉΓòÉΓòÉ

After you have completed the exercises, you will want to know more about the
full facilities of Visualizer Development. Read IBM Visualizer Development for
OS/2: Using, SH45-5095 and IBM Visualizer Development for OS/2: Reference,
SH45-5096 to see what you can do with Development, and for a complete reference
to the Application System Language (ASL).


ΓòÉΓòÉΓòÉ 3. Windows and the graphical interface ΓòÉΓòÉΓòÉ

This chapter is a general introduction to windows and their components within
the context of Visualizer Development.

The chapter describes the types of menu supported by the Menu editor. It also
describes the types of window and window controls supported by the Window
editor. You use these two editors to create a graphical user interface for your
application. For more information on window controls and designing graphical
user interfaces, refer to the SAA Common User Access Advanced Interface Design
Guide, SC34-4290.


ΓòÉΓòÉΓòÉ 3.1. Window types ΓòÉΓòÉΓòÉ

A window is an area with a border, used for conducting a dialog with the user
or presenting a view of an object. There are two types of window: primary
windows and secondary windows.

A primary window appears when a user opens an object, and it is where the main
interaction between a user and an application takes place.

A secondary window is used to supplement the interaction in the primary window.
It is used when the application needs to prompt the user for more information
about a request or to display more information. A secondary window can, for
example, be used to display online help without obscuring the information in
the primary window.

A secondary window can be modal or modeless. If a modal window is displayed,
the user cannot use any of the other application windows until the required
user action on the modal window is completed. For example, a modal window can
be used if a user attempts to save a file without a name. In this case, the
dialog prompts the user for the file name. Modal windows are also used for
displaying error messages.

If a modeless window is displayed, the user can continue to use other
application windows. An example of a modeless dialog box is the Find dialog,
which is used to locate the names of files to be included in a list. A modeless
window is displayed until the user explicitly closes it.


ΓòÉΓòÉΓòÉ 3.2. Standard window components ΓòÉΓòÉΓòÉ

Most windows have a title bar, and primary windows often have a menu bar and
sometimes a tool bar.


ΓòÉΓòÉΓòÉ 3.2.1. The title bar ΓòÉΓòÉΓòÉ

A title bar is the area at the top of a window that contains the system menu
symbol, the window title, and, optionally, the Maximize, Minimize, and Restore
buttons. A window can be moved by dragging its title bar.

The system menu appears when the symbol in the left corner of the title bar is
selected. It contains choices that affect the window or the view it contains.
From the system menu, the end user can usually select:

Restore     To return the window to the size it was and the position it was in
            before the user minimized or maximized the window

Move        To move the window to a different location on the desktop

Size        To change the size of the window

Minimize    To reduce the window to its smallest possible size

Maximize    To enlarge the window to its largest possible size (often full
            screen)

Close       To remove a window and all of the windows associated with it from
            the workplace, ending the application

Window list To display a list of open windows and switch to another window


ΓòÉΓòÉΓòÉ 3.2.2. Menu bars and menus ΓòÉΓòÉΓòÉ

A menu bar is the area below the title bar that contains a list of choices.
These are the names of menus. When the end user selects a menu-bar choice, the
associated menu is displayed. The user can then select one of the menu choices.
Because menus are displayed immediately below the associated menu names, they
are also known as pull-down menus.

An ellipsis (...) immediately after the name of a menu choice indicates that
another window will be displayed when that choice is selected before the action
is completed. For example, a choice labeled Sort... would display a window from
which the user can specify the order in which items should be sorted. A menu
choice can be grayed to indicate that it cannot currently be selected.

A mnemonic allows the user to select a menu-bar choice or menu choice by typing
a character instead of using the mouse. Generally, the first letter of the
choice is used as the mnemonic. If that letter has already been used, the first
letter unused as a mnemonic is assigned to the role. The chosen character must
be unique within the menu bar or menu. The mnemonic is underlined in the menu
bar or menu.

A shortcut key, also known as an accelerator, is a key or combination of keys
assigned to a menu choice. Experienced users can select a menu choice by
pressing the associated shortcut key, even if the menu is not currently
displayed. A shortcut key consists of an extended function key (such as Ctrl,
Alt, and Shift), with or without a character key. The shortcut key for a menu
choice is displayed next to the name of the choice. Shortcut keys must be
unique within a window.

Most Visualizer Development menu bars contain a menu labeled with the name of
the class of object that can be manipulated in the window. For example, the
Program editor contains a Program menu. In your applications, you can use the
supplied File menu to provide the functions of an object menu. Standard Edit,
Data, and Help menus are also supplied. These menus are supported specifically
by the code generator in the Program editor.


ΓòÉΓòÉΓòÉ 3.3. Window controls ΓòÉΓòÉΓòÉ

This section describes each of the window controls available in Visualizer
Development.

Text

A text control allows the display of static text on the window, and is normally
used for labeling and prompts. The words Location, Name, Names, and Locations
in the picture above are text fields.

Push buttons

A push button is a labeled button that represents an action that will be
initiated when a user selects it.

Standard push buttons

Standard push buttons provide the following predefined functions: OK, Apply,
Reset, Cancel, and Help. An additional standard push button is available for a
user-defined function.

Bitmap buttons

A bitmap button is a button displaying a picture (graphic) that represents an
action that is initiated when a user selects it: for example, a tool bar
button. Three bitmap images are supplied. They show the button in the following
states:

o Up
o Down
o Disabled (unavailable).

Radio button

A radio button consists of a circle with text beside it. Radio buttons are
grouped to show a user a fixed set of choices from which the user can select
only one. When a radio button is selected, the circle becomes partially filled.
The Left, Center, and Right alignment buttons in the following illustration are
radio buttons.

Check box

A check box consists of a square box with associated text that represents a
choice. When a user selects the choice, a check mark, is shown in the box. The
user can clear the check box by selecting the choice again. Check boxes are
typically used in groups. Unlike groups of radio button, however, more than one
check box can be selected at a time. Check boxes are appropriate for choices
that have two clearly distinct states.

Value set

Like radio buttons, a value set is used to present mutually exclusive choices.
However, a value set is used primarily for graphical choices, and the choices
are arranged in a matrix.

List box

A list box is a rectangular box, usually with a scroll bar. It can be used to
display a fixed or variable list of settings choices or objects, such as a list
of the files in a directory. The list box provides for the display of lists of
tabular data in one or more columns (optionally with column titles). Single,
multiple, and extended selection techniques are all supported for list boxes.
Both horizontal and vertical scroll bars are allowed on list boxes.

Single line entry field

A single-line entry (SLE) field provides an area into which the user can enter
a line of text. An SLE can be made to scroll horizontally automatically to
allow input of long text strings. The display of the input text can be
suppressed (for entering passwords). An SLE supports use of the clipboard for
cutting, copying, and pasting text. Clipboard operations can be used with SLEs.

Multi-line entry field

A multi-line entry (MLE) field is a multiple-line version of the SLE, and
allows the end user to type large amounts of data from the keyboard. The field
can be configured to scroll, and can support automatic word wrapping.  An MLE
supports use of the clipboard for cutting, copying, and pasting text.

Drop-down list

A drop-down list is a variation of a list box. It only displays one item from
the list until the user clicks on the list button to display the other items.

Drop-down entry A drop-down entry control combines an entry field with a
drop-down list. The user can scroll through the list to make a selection or
complete the entry field.

Group box

A group box is a rectangular box drawn around a group of fields to indicate
that the fields are related and to provide a label for the group.

Graphic area

A graphic area is a rectangular area which can display graphic primitives (such
as lines, rectangles, and curves).

Scroll bars

A scroll bar indicates to a user that more information is available in a
particular direction and can be scrolled into view. Scroll bars can be either
horizontal or vertical, and can be activated on windows, MLEs, and list boxes,
or added onto windows as additional controls.


ΓòÉΓòÉΓòÉ 3.4. Tool bars ΓòÉΓòÉΓòÉ

The primary window-the first window you see-in all four Visualizer Development
editors, displays a row of buttons just under the menu bar. This is called the
Tool bar. Programs created with Visualizer Development can also add tool bars
to the windows they open.

Each button bears an icon which represents a regularly used function offered on
one of the pull down menus.

You obtain the function offered by a Tool bar button by clicking on it with
mouse button 1.

For more information about the Tool bar buttons, read the Tool bar online help,
or refer to IBM Visualizer Development for OS/2: Using, SH45-5095.


ΓòÉΓòÉΓòÉ 3.4.1. Tool bar online help ΓòÉΓòÉΓòÉ

You can get help on the function of any Tool bar button by clicking on it with
mouse button 2.

This action displays a short pull down menu with two entries on it. The first
entry offers you the function of the button: the second entry offers you online
help.

If you choose help, the help panel that is displayed presents a list of all the
buttons on the Tool bar. Use mouse button 1 to click on the title of the button
about which you want help.


ΓòÉΓòÉΓòÉ 4. More about the components ΓòÉΓòÉΓòÉ

This chapter explains the Visualizer Development components in more detail.
These components are:

o The Visualizer Menu editor
o The Visualizer Window editor
o The Visualizer Program editor
o The Visualizer Make object
o The Application System Language (ASL).


ΓòÉΓòÉΓòÉ 4.1. The Visualizer Menu editor ΓòÉΓòÉΓòÉ

This section explains more about the Menu editor.

Your window-based application can have a primary window which the end user uses
to access the main functions of the application.  A common way to access these
functions is through menus on a menu bar at the top of the primary window.

You define the menus individually with the Menu editor. By using the Window
editor, you then add the menus you want to include on the menu bar to your
primary window.


ΓòÉΓòÉΓòÉ 4.1.1. Menu features ΓòÉΓòÉΓòÉ

Each menu that you define consists of a menu bar entry and a list of menu
entries.  The title of the menu appears on the menu bar.  When the end user
selects the menu title, the menu entries are revealed beneath it.

You can design your application so that there is a menu entry for each of the
main application functions. For example, the end user might request a display
of the values in the currently selected table by using a customized menu entry.

In other cases, you may provide a secondary window or set of windows for the
entry of further details before the function can be performed. For example,
when an end user wants to import data from a database, the names of the key
fields must be specified.  A secondary window might be presented for entering
the search fields.


ΓòÉΓòÉΓòÉ 4.1.2. Menu editor functions ΓòÉΓòÉΓòÉ

The Menu editor allows you to create menus for menu bars. The menu entries of a
window are created within the Menu editor while the menus to appear on a menu
bar are defined in the Window editor.

Menus are stored as separate objects and can be used more than once in an
application. They can also be used in several applications.

For the title of the menu and the individual menu entries, you can specify the
following details:

Text      The literal string that is to appear as the menu item on the menu bar
          or as the menu entry text.

Mnemonic  A short form of entry, normally a single letter from the displayed
          text is underlined (assigned according to CUA guidelines).

Reference An object name to link menu actions to the program (the internal
          variable name for the menu or menu entry).

Res id    A resource identifier reference number relating to available help
          text.  (Help is available for the standard Help menu entry, but you
          will need to write new help text for your own menus.)

Accelerator (Shortcut key) A key combination that the end user can press to
          speed the menu selection (Ctrl + K for example). You can have both a
          mnemonic and a shortcut key if you wish, or just a mnemonic.

Operation Some action will take place when the menu entry is selected by the
          end user.  The action taken can be specified during the menu creation
          and code generated automatically to perform the requested operation.
          The radio buttons indicate what type of action will take place and
          the location and name of the related object (if any). The operation
          selection can be left as undefined and the action determined later by
          re-editing the menu or by placing the code into the program manually
          during the programming stage (from the Program editor).

Whenever practical, the Menu editor supplies sensible defaults for all input.

Note:   References, shortcut keys, and mnemonics must not be repeated within a
        menu or within a created menu bar. The Menu editor will protect you
        from repeating these in an individual menu, but it is up to you to
        ensure that repetition does not occur in any of your menu bars.


ΓòÉΓòÉΓòÉ 4.1.3. Menu editor windows ΓòÉΓòÉΓòÉ

The Menu editor consists of a primary window (with menu bar) which displays the
details of the menu being created, and two secondary windows, for defining the
menu bar entry and the individual menu entries.

The above illustration shows the Menu editor primary window on which you create
the menu bar entry and menu entries.

Near the top of the primary window is the literal string that will appear in
the created menu bar. Listed below the menu bar entry are up to 12 individually
defined menu entries that make up the menu. The mnemonics and shortcut keys
associated with each menu entry are also displayed.

A mnemonic defined for a menu bar or menu entry is shown on the Menu editor in
parentheses. This letter will be underlined when displayed on the final menu.

Note:   Instead of a letter, you can specify a number as a mnemonic to follow
        the entry text, for example, Open (1).

The above illustration shows the Menu editor secondary window for defining a
menu bar entry. The above illustration shows the Menu editor secondary window
for defining an individual menu entry.


ΓòÉΓòÉΓòÉ 4.1.4. Standard menu entries in Visualizer Development ΓòÉΓòÉΓòÉ

Because menus like File, Edit, Data, and Help occur in many applications,
pre-constructed standard menus are available for these menu bar entries.  You
can include them on the menu bar when you are designing the window or you can
choose to include on the menu bar your own version of these entries that you
have written with the Menu editor.

The following sections describe these menus in more detail.


ΓòÉΓòÉΓòÉ 4.1.4.1. The Data menu ΓòÉΓòÉΓòÉ

Data provides a way for the user to select tables for processing by the
application.

Data gives access to a menu with Select table which causes Program edit to
generate code for manipulating tables.


ΓòÉΓòÉΓòÉ 4.1.4.2. The File menu ΓòÉΓòÉΓòÉ

File gives access to a menu with New, Open, Save, Save as and Print.

Selecting Save will save the current version of the object with the same name
it had when it was opened. If an object has been modified to create a new
object, the Save as entry allows the object to be saved with a new name and
location. Not all applications support the saving of a changed object with a
new name. Visualizer Query for OS/2 objects do not have a Save as choice,
though they do have Copy to, which performs a similar function. A template file
will automatically generate a Save as dialog if a template is changed and then
exited. For objects which support printing or plotting, the Print/plot entry
will send the object to the default printer. Many applications use the name of
the application for the menu bar label.  The Menu editor uses Menu to indicate
the menu which holds the main filing operations.


ΓòÉΓòÉΓòÉ 4.1.4.3. The Edit menu ΓòÉΓòÉΓòÉ

The Edit menu bar entry gives access to the standard menu selections of Cut,
Copy and Paste. The one illustrated also has Delete and Insert. Copy is clearly
not possible if there is nothing selected on the current window for copying. In
this situation, the Copy option is grayed and the menu item appears in reduced
contrast.

The Edit functions available may vary depending on the object type or the
application.  For example, the Visualizer Program editor allows Cut and Paste
only within the edit windows. The Visualizer Window editor will allow Cut and
Paste of window controls within the template, but will not allow pasting from
other applications.


ΓòÉΓòÉΓòÉ 4.1.4.4. The Help menu ΓòÉΓòÉΓòÉ

A standard Help facility is available for most products. Help is
context-sensitive and the items covered for each product depend on the nature
of the product. The entries for the Help menu are:

Help for help  To provide information on how to use the help facility.

Extended help  To provide more detailed help information on the entire window
               or application.

Keys help      To provide help for the use of special keys and key combinations
               in the context of the current application.

Help index     To provide a list of topics for which help is available. The
               help index is context-sensitive and provides information for the
               current focus on the screen.

Product information To provide the name of the program and its owner. (Not all
               Help menus have a product information entry).

The Help menu is linked to Information Presentation Facility (a standard
component of OS/2). Refer to the OS/2 Programmer's Reference for more
information on how to create and manage help text files.


ΓòÉΓòÉΓòÉ 4.2. The Visualizer Window editor ΓòÉΓòÉΓòÉ

This section explains more about the Window editor.


ΓòÉΓòÉΓòÉ 4.2.1. Window features ΓòÉΓòÉΓòÉ

Each window that you design may have a title bar and a border, a system menu
icon and minimise and maximise buttons with instances from the two basic sets
of features:

Window attributes These define the overall appearance and behavior of the
          window.

          You can define the following window attributes:

   o The border of the window can be normal (permitting resizing), dialog, thin
     line, or omitted.

     Primary windows are normally resizable while secondary windows are not.

   o The title bar can contain a system menu and the maximize and minimize
     icons (these are normally present on a primary window).

   o When opened, the window can be either hidden or modal.  Modal means that
     action must be taken on this window, and before any other window in the
     application can be used, the window is closed.

   o Scroll bars can be placed on the window to permit horizontal and vertical
     scrolling.

Controls  End users interact with the application through a window by using
          window controls.  The available controls are: multi line entry,
          single line entry, drop-down entry, dropdown list, bitmap button,
          radio button, push button, standard push button, value set, check
          box, list box, graphic area, group box, text, horizontal scroll, and
          vertical scroll.

          The end user can also interact with the application via a menu bar
          with pull-down menus. You can use the Menu editor and the Window
          editor to define the contents of the menu bar.


ΓòÉΓòÉΓòÉ 4.2.2. Window editor functions ΓòÉΓòÉΓòÉ

With the Window editor you create and modify windows and dialog windows for use
in an application, and specify how they can be manipulated.

To create the contents of a window, you select each control from a palette on
the main window of the editor, and then place it on the Window Template window.

The controls that you can place on your Window Template window are shown in the
following table.

ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Control Area      Can be   Name    Text      Specific
           cloned        attribute    attributes
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Multi line edit    YES    YES    NO       YES
Single line entry   YES    YES    NO       YES
Drop-down entry    NO     YES    NO       YES
Drop-down list     NO     YES    NO       YES
Radio button      YES    YES    YES       NO
Bitmap button     YES    YES    YES       NO
Standard push     YES    YES    NO       YES
Value set       YES    YES    YES       NO
Check box       NO     YES    YES       YES
List box        YES    YES    YES       NO
Graphic area      NO     YES    NO       YES
Group area       NO     YES    NO       YES
Group box       NO     YES    YES       NO
Text          YES    YES    YES       YES
Horizontal scroll   NO     YES    NO       YES
Vertical scroll    NO     YES    NO       YES
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This table shows information as follows:

Control type   The name of the control (multi line edit, for example).

Can be cloned  The ability to replicate a control into sets that work together.
               Radio buttons and push buttons are commonly cloned controls.
               The cloned push buttons become a clone set and each member of
               the clone set is identified by the set name and the clone
               number.

Name           The variable name used by the program for this control or clone
               set. This is the name used by the program for references to the
               control. All controls must have a name within the program, even
               if there is no text associated with them for the end user to
               read.

Text attribute Whether the control supports the TEXT attribute. This specifies
               text that the user will see. For example, a push button might
               have the text Cancel on it.

Specific attributes Whether there are attributes specific to this type of
               control. All controls have attributes for position, size, and
               selectable for example, but some controls have additional
               attributes specific to them. The single line entry (SLE) control
               has an additional attribute for the horizontal alignment of text
               within the control's display. A push button does not have this
               alignment attribute.


ΓòÉΓòÉΓòÉ 4.2.3. Window editor windows ΓòÉΓòÉΓòÉ

You use the main window of the Window editor to define controls and place them
on the template window (the window under construction). The following
illustration shows the main window of the Window editor and the Template
window.

The main window is divided into two main sections: the Controls Palette and the
Selected Control.  Use the Controls Palette section to select a control type
and specify its reference details. (This information will be used later by the
ASL code.) The Selected Control list contains all controls currently on the
template window. The Selected Control group provides the details of the
selected template control.

When you first open the Window editor, the template window is blank. The title
bar shows Window Template and no window controls are present.


ΓòÉΓòÉΓòÉ 4.2.3.1. Window dimensions (DBUs) ΓòÉΓòÉΓòÉ

The area of the template window initially measures approximately 270 units
across by 110 high, in dialog box units (DBU). The window can be resized
whenever the normal border is still present (the template in the following
illustration has been resized to 173 by 66).

 A DBU is approximately related to character size as follows:

o 4 DBU = 1 horizontal character (width)
o 8 DBU = 1 vertical character (height)
The grid, which can be displayed on the template window, is marked off in
multiples of 4 DBU horizontally and 3 DBU vertically.


ΓòÉΓòÉΓòÉ 4.3. The Visualizer Program editor ΓòÉΓòÉΓòÉ

This section explains more about the Program editor.

Use the Program editor to generate, add and modify Application System Language
(ASL) code in the following ways:

o Link end-user activity to the windows and menus you have created

o Link your windows and menus to the logical functions that your application
  performs


ΓòÉΓòÉΓòÉ 4.3.1. Program features ΓòÉΓòÉΓòÉ

You can write and edit the code for your application with any editor that can
work with ASCII files. If, however, you use the Window and Menu editors to
design your windows and menus, you can then use the Program editor to generate
skeleton source code for the controls, menu bar entries, and all their
characteristics automatically.

Then, you have only to edit the created blocks of code to include the logic
that reacts to each potential end-user interaction. The Program editor also
provides syntax checking, code formatting, and contextual syntax help to aid
you with program creation.

If you use an ordinary text editor, the file attributes may not be set
correctly. If this happens, you can use the sample application, Classer to
restore the correct file attributes.


ΓòÉΓòÉΓòÉ 4.3.2. Program editor functions ΓòÉΓòÉΓòÉ

ASL is an event-driven language. An ASL coded program is structured in blocks
so that a block handles an event.

You can select various event blocks for the program you are writing. (When you
use Create, template code for each of the events is generated for you.)

From within these event blocks, you can also call procedures, which are
themselves blocks of code.  A procedure block contains discrete code for any
processing that you want performed for a defined action.

The Program editor recognizes and manipulates code at block level, and
therefore simplifies navigation through the program structure.

You can write code blocks yourself using the Program editor. When you create
code this way, the editor recognizes the events and procedures you have written
and separates them out as required.

Syntax help is available for the ASL language from any point on an edit window.


ΓòÉΓòÉΓòÉ 4.3.3. Program editor window ΓòÉΓòÉΓòÉ

The Program editor has a primary window (with a menu bar and a tool bar) which
displays lists of Events and Procedures. It is shown in the following
illustration.


ΓòÉΓòÉΓòÉ 4.4. The Visualizer Make object ΓòÉΓòÉΓòÉ

This section explains more about Make object.

You can use the Make to manage the programs, windows, and menus that you have
designed for an application. You can also use Make to compile selected files
from your library (when creating an application in stages).

With Visualizer Development, you build the components of an application-the
programs, windows, and menus-separately, using the editors.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéMenu  Γö£ΓöÇΓöÇΓöéMenu  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé EditorΓöé  Γöé  File Γöécompile     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÿ         Γöé

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ     ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéWindow Γö£ΓöÇΓöÇΓöéWindow Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöé Final    Γöé
Γöé EditorΓöé  Γöé  File Γöécompile  Γöé       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ     Γöé Compiled   Γöé
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ     Γöé       Γöé
ΓöéProgramΓö£ΓöÇΓöÇΓöéProgramΓö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöé Application Γöé
ΓöéEditor Γöé  Γöé File  Γöécompile  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Simple applications with a single window and program are easily built using the
Window and Program editors, each of which allows direct compilation into the
final application as shown in the diagram above.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéMenu  Γö£ΓöÇΓöÇΓöéMenu  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé EditorΓöé  Γöé  File Γöé     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ     Γöé
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ     Γöé
ΓöéWindow Γö£ΓöÇΓöÇΓöéWindow Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
Γöé EditorΓö£ΓöÉ  Γöé  File Γöé    Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿΓöé  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ    Γöé Γöé
     Γöé  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    Γöé Γöé
     ΓööΓöÇΓöéWindow Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Γöé
      Γöé  File Γöé   Γöé Γöé Γöé
      ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ   Γöé Γöé Γöé
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ   Γöé Γöé Γöé
ΓöéProgramΓö£ΓöÇΓöÇΓöéProgramΓö£ΓöÇΓöÇΓöÇΓöÉ Γöé Γöé Γöé
Γöé EditorΓö£ΓöÉ  Γöé  File Γöé  Γöé Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿΓöé  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  Γöé Γöé Γöé Γöé
     Γöé  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé Γöé Γöé Γöé   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
     ΓööΓöÇΓöéProgramΓö£ΓöÇΓöÉ Γöé Γöé Γöé Γöé   Γöé Final    Γöé
      Γöé  File Γöé Γöé Γöé Γöé Γöé Γöé   Γöé Application Γöé
      ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ        Γöé (compiled  Γöé
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ       ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé from Make  Γöé
ΓöéMenu  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöé Make  Γö£ΓöÇΓöÇΓöé or object  Γöé
Γöé EditorΓöé       Γöé  File Γöé  Γöé Editors)   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ       ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

More complex applications may require many programs and windows. Make file
simplifies these applications by providing a list of all components included in
your application, and giving the ability to compile source files selectively.

You can use Make to manage and compile applications itself, or you can create
Make files for use by the Create options of the Program editor.

When you compile the contents of a Make file, the ASL code in your programs is
linked to the references associated with each control, the menu selections, and
other interactions with your created windows.


ΓòÉΓòÉΓòÉ 4.4.1. Make features and windows ΓòÉΓòÉΓòÉ

Make consists of a primary window with menu bar, which displays a list of the
source program, window, and menu objects selected for inclusion in an
application.

The following illustration shows the Make primary window listing the objects in
an application.

Two secondary windows are displayed when you select one of the "add object
class" entries from the Edit pull-down. On one window are displayed the
available objects from selected locations, and you can select the ones you
want. On the other window is a list of the objects that you have already
selected.

The following illustration shows the Make secondary windows for listing and
selecting programs for inclusion in a Make file.

The selected objects are added to the Make file when you select OK.

Alternatively, program, window and menu objects can be added to a Makeby
dragging their respective icons and dropping them onto the main Make window.


ΓòÉΓòÉΓòÉ 4.5. Useful drag and drop combinations ΓòÉΓòÉΓòÉ

This section lists the Visualizer objects and types of file that can be dragged
and dropped on to other Visualizer objects.

This            Accepts

Make            All (Programs, Menus and Windows)

Menu item       Program and Window

Window          Menus and Bitmaps

Program         Window and Make

Program block   Windows, applications and other objects

                Examples from Visualizer Query for OS/2 include Visualizer
                Tables, Reports and SQL tables. You can also drag and drop
                charts from Visualizer Charts.

                Other examples include digital video files, digital audio files
                and MIDI files.


ΓòÉΓòÉΓòÉ 4.6. The Application System Language ΓòÉΓòÉΓòÉ

This section describes more about the Application System Language (ASL). For
more information on particular statements, functions, and objects, refer to IBM
Visualizer Development for OS/2: Reference, SH45-5096 and IBM Visualizer
Development for OS/2: Using, SH45-5095.


ΓòÉΓòÉΓòÉ 4.6.1. Programs and applications ΓòÉΓòÉΓòÉ

ASL programs are made up of blocks containing code. The functional blocks in a
program are either blocks which handle events, or they are procedures. There is
no defined order in which blocks need be placed in a program.

The event blocks contain code to process events from the user or a program.
Procedure blocks contain additional code, for example for performing
calculations. Procedures blocks are activated either by a call from an event
block or from another procedure.

Event-driven programming may require some adjustment if you are used to
conventional programming, but the differences are easily learned. The main use
of events is to react to the user selecting a control (such as a menu choice)
from one of the program's windows. Each program also has an ON START event
block, which executes when the program is first started.

The term application denotes the compiled output from Visualizer Development.
It is the result of a compiling one or more component files which can be
programs, menus and windows. Applications are fully integrated programs. You
can run them on any system with Visualizer Query for OS/2: Visualizer
Development does not need to be installed.

An application is stored in an application objectstore, which is an OS/2 file.
A compiled program in an application objectstore is known as a module, and an
active module is known as a task. There can be several programs in an
application, and at any time, there can be several tasks running the same
module, or different modules. Programs can also open further objectstores to
access data stored in them.


ΓòÉΓòÉΓòÉ 4.6.2. Writing ASL ΓòÉΓòÉΓòÉ

Each functional line of ASL code contains an ASL statement. Other lines can be
blank lines, comment lines or continuation lines where a statement is split
over several lines. There is no limit to the number of lines in a block. You
can include a comment in any line, and you are free to add spaces between
elements of the language to make your programs easy to read and maintain.


ΓòÉΓòÉΓòÉ 4.6.2.1. A simple program ΓòÉΓòÉΓòÉ

The simplest program possible consists of just an ON START block which carries
out an action and then stops the program. For example, the following code
produces a message on the screen and then stops the program. Each line is
commented:

ON START                                 ! Definition of the block.
DO                                       ! To enclose the statements.
  MESSAGE "FTB10002", 0 ,"Hello world"   ! An information message.
  STOP                                   ! Stop this program.
END                                      ! End the block.

You can enter this code using the Program editor, compile it, as the key
program, into an application of your own choice, and run the application. A
window containing your message appears on the screen. When you select OK, the
message window disappears, and the application stops. The FTB10002 identifies a
message box style, the 0 is a reserved parameter, and the text string contains
the message to be displayed to the end user.


ΓòÉΓòÉΓòÉ 4.6.2.2. Uppercase and lowercase ΓòÉΓòÉΓòÉ

For clarity, we recommend that you use uppercase for the names of ASL elements,
and also, perhaps, for the names of procedures. We also recommend that you use
lowercase for the names of variables. ASL is not case sensitive, but using
different cases improves the readability of the programs.


ΓòÉΓòÉΓòÉ 4.6.2.3. Splitting lines ΓòÉΓòÉΓòÉ

A functional line of ASL may take up more than one line in the program. You can
split a statement over more than one line if you break it after any symbol that
implies continuation, such as a comma, an arithmetic operator such as a plus
sign (+) or an opening bracket. For more information about this, refer toIBM
Visualizer Development for OS/2: Reference, SH45-5096

Each new statement begins on a separate line. A statement following ELSE, THEN
or FORGIVE, can be on the same line, or on a separate line.


ΓòÉΓòÉΓòÉ 4.6.2.4. Comments ΓòÉΓòÉΓòÉ

Comments either:

o Start with an exclamation mark and continue to the end of the line
o Start with /* and end with */ on the same line
o Start and end with exclamation marks on the same line

Lines with an exclamation mark (!) as the first character are comment lines
throughout.


ΓòÉΓòÉΓòÉ 4.6.2.5. The Program editor ΓòÉΓòÉΓòÉ

You can use the Program editor to reformat blocks with standard indentation. It
can also split and join lines 'intelligently' (taking account of continuation
symbols) and provide syntax checking and syntax help while you are writing the
program. The Program editor can also generate code for you for windows and
menus created with the Window editor and the Menu editor.


ΓòÉΓòÉΓòÉ 5. Building your first application ΓòÉΓòÉΓòÉ

This chapter contains a set of step by step exercises that take you through
building a Visualizer application by using Visualizer Development. It assumes
no knowledge of Visualizer Query for OS/2 or of Visualizer Development,
although familiarity with the basic concepts of OS/2, such as opening folders
and copying objects, is highly desirable.


ΓòÉΓòÉΓòÉ 5.1. About the application ΓòÉΓòÉΓòÉ

The application you are going to build consists of one menu, two windows, (a
main window and a data window) and two programs. The Data Window will contain a
list box, some text, two single line entry fields, and three push buttons. A
data table is created, which contains people's names and bank balance. The
application will allow the end user to update the information contained in the
data table.

Note:   The data table you create for the application is a Visualizer table.
        However, you could use a DB2/2 (SQL) instead. This would work in much
        the same way.

The Main Window for your application looks like this:

The Data Window, for you application looks like this:


ΓòÉΓòÉΓòÉ 5.2. About the exercises ΓòÉΓòÉΓòÉ

There are 10 exercises in the set:

o Exercise 1 - Creating a directory and folder
o Exercise 2 - Opening Visualizer Development and setting up
o Exercise 3 - Adding the objects to the Make
o Exercise 4 - Creating the Menu
o Exercise 5 - Creating the Main window
o Exercise 6 - Creating the Main program
o Exercise 7 - Creating the Data window
o Exercise 8 - Creating the Data program
o Exercise 9 - Compiling the application
o Exercise 10 - Running the application

If you are not familiar with OS/2, pay particular attention to the first two
exercises. It is also recommended that you read through the appropriate
sections of the OS/2 online help system to strengthen your grasp of these
skills.

Do the exercises in the order in which they are presented.

Note:   You do not have to complete the exercises in one session.


ΓòÉΓòÉΓòÉ 5.3. Before you start ΓòÉΓòÉΓòÉ

Ensure that you have Visualizer Development installed according to the
information contained in IBM Visualizer Query for OS/2: INstalling and
Supporting, SH45-5087.

Ensure that you have access to the AVGSAL.REP report. (Look in your Visualizer
Samples folder.)


ΓòÉΓòÉΓòÉ 5.4. Exercise 1 - Creating a directory and folder ΓòÉΓòÉΓòÉ

Before creating the application, you should create a directory and a folder to
hold the files for the application.

If you are an experienced OS/2 user, you may prefer to create the directory and
folder without reference to the following sets of instructions.

The name of both the directory and folder should be Exercise and you should use
the the drive on which you normally keep your work files.


ΓòÉΓòÉΓòÉ 5.4.1. Creating the directory ΓòÉΓòÉΓòÉ

To create the directory:

 1. Open the Drives folder by double clicking on the Drives icon. This folder
    will have one icon representing each hard disk drive. Move the folder to
    the bottom left of the screen.

 2. Choose the drive (for example, C, D, or E) you want to hold these files on
    by double clicking on it.

 3. Open the OS/2 Templates folder by double clicking on the Templates icon.
    Move the folder to the top right of the screen.

    This folder will contain all your template icons, and one of the icons will
    be for a Folder.

 4. Place the mouse pointer over the Folder icon in the Templates folder, and
    hold down the right button of the mouse. Drag the icon to the Drives folder
    so that it is over the icon representing the drive in which you are going
    to create the application. Let go of the right button of the mouse.

 5. After a few seconds of disk activity, double click on the icon representing
    the drive on which you dropped the Folder icon. This will open another
    folder, Tree View, of the drive. Scroll up and down until you locate an
    icon called Folder.

 6. Place the mouse pointer over the Folder icon in the Tree View folder, and
    click with the right button of the mouse. On the resultant menu select the
    arrow to the right of Open option. From the resultant menu choose Settings.

 7. On the resultant Settings notebook control choose the tab marked General.

 8. On the resultant page, in the area marked Title, overwrite the existing
    text Folder with the text Exercise Close the settings notebook by double
    clicking on the System Icon.
This has created a directory on the drive called Exercise, and the icon in the
Tree View folder will now be called Exercise.


ΓòÉΓòÉΓòÉ 5.4.2. Creating the folder ΓòÉΓòÉΓòÉ

To create the folder:

 1. Hold down the Ctrl and Shift key (Arrow) together. Place the mouse pointer
    over the Exercise icon in the Tree View folder, hold down the right button
    on the mouse, and drag the Exercise icon to anywhere on the desktop. The
    icon being dragged should be linked to the original icon by a line. Let go
    of the right button of the mouse, and let go of Ctrl and Shift.

 2. A new icon will be created on the desktop called Exercise but the text
    should be a light grey (assuming you still have the OS/2 defaults). You
    have now created a Shadow of the original folder icon.

 3. Shut down the Drives Tree View folder, shut down the main Drives folder,
    and shut down the Templates folder,

 4. Double click on the Exercise folder on the desktop. This folder maps to the
    directory Exercise on your chosen drive. The folder will open, but it is
    empty. You have no objects in your folder, or in the directory.

 5. Make the Exercise folder just big enough to contain eight icons, and move
    it to the bottom left of the screen.

You have now created a directory and a folder to hold the files for the
application.


ΓòÉΓòÉΓòÉ 5.5. Exercise 2 - Opening Visualizer Development and setting up ΓòÉΓòÉΓòÉ

In this exercise, you will open Visualizer Development and use the Visualizer
Development templates to create copies of the six objects you need in order to
create the application. As you create a copy of each object, you will also
rename it. The objects are:

o A menu called MainMenu
o A window called MainWin
o A window called DataWin
o A program called MainProg
o A program called DataProg
o A make called MainMake

At the end of this exercise, your Exercise folder should contain icons that
represent these objects, and it should look like this:

If you look in your Exercise directory, you should find six files that have
corresponding names.


ΓòÉΓòÉΓòÉ 5.5.1. Creating MainMenu ΓòÉΓòÉΓòÉ

To create the main menu:

 1. Open the main Visualizer folder by double clicking on the Visualizer icon.

 2. Open the Shadows of Templates folder by double clicking on the Shadows of
    Templates icon. Move the folder to top right of the screen.

 3. Close the main Visualizer folder by double clicking on the System Icon.

 4. Place the mouse pointer over the Visualizer Menu icon in the Shadows of
    Templates folder, hold down the right button of the mouse, and drag the
    icon to the Exercise folder. Let go of the right button of the mouse. You
    have now created your menu, and the result should look like this:
To rename your menu:

 1. Click on the icon with the right button of the mouse. On the resultant
    menu, select the arrow to the right of Open option. From the resultant
    menu, choose Settings.

 2. On the resultant Settings notebook control, choose the tab marked General.

 3. On the resultant page, in the area marked Title, overwrite the existing
    text Visualizer Menu with the text MainMenu. Close the settings notebook by
    double clicking on the System Icon. Your renamed menu icon should look like
    this:


ΓòÉΓòÉΓòÉ 5.5.2. Creating MainWin ΓòÉΓòÉΓòÉ

To create the main window:

 1. Place the mouse pointer over the Visualizer Window icon in the Shadows of
    Templates folder, hold down the right button of the mouse, and drag the
    icon to the Exercise folder.

 2. Let go of the right button of the mouse.

You have now created your own window.

To rename your window:

 1. Place the mouse pointer over your new window icon, hold down the Alt key on
    the keyboard, and select with the left button of the mouse.

 2. In the resultant box under the icon, overtype the existing text Visualizer
    Window with the text MainWin.

 3. When finished, select the icon with the left button of the mouse.

You have renamed your object MainWin, and have tried an alternative for
renaming objects to that used previously for the menu.


ΓòÉΓòÉΓòÉ 5.5.3. Creating DataWin ΓòÉΓòÉΓòÉ

To create the data window:

 1. Use the right button of the mouse to select the MainWin icon.

 2. On the resultant menu, select Copy.

 3. On the resultant window, overtype the existing text in the New name field
    with DataWin.

 4. At the bottom of the window, press the Copy button.

You now have another window, called DataWin.


ΓòÉΓòÉΓòÉ 5.5.4. Creating MainProg ΓòÉΓòÉΓòÉ

To create the main program:

 1. Place the mouse pointer over the Visualizer Program icon in the Shadows of
    Templates folder.

 2. Hold down the right button of the mouse, drag the program icon to the
    Exercise folder, and then let go of the mouse button.

You have now created your own program.

To rename your program:

 1. Click on the icon with the right button of the mouse, and on the resultant
    menu, select the arrow to the right of Open option.

 2. From the resultant menu choose Settings.

 3. On the resultant Settings notebook control, choose the tab marked General.

 4. On the resultant page, in the area marked Title, overwrite the existing
    text with the text MainProg

 5. Close the settings notebook by double clicking on the System Icon.

This has renamed your object MainProg.


ΓòÉΓòÉΓòÉ 5.5.5. Creating DataProg ΓòÉΓòÉΓòÉ

In this part of the exercise, you create the data program by copying the main
program and renaming it.

To create the data program:

 1. Select the MainProg icon with the right button of the mouse.

 2. On the resultant menu, select Copy.

 3. On the resultant window next to New name, overtype the existing text with
    DataProg

 4. At the bottom of the window click on the Copy button.

You now have another program, called DataProg.


ΓòÉΓòÉΓòÉ 5.5.6. Creating MainMake ΓòÉΓòÉΓòÉ

Finally, you need to create the Make:

 1. Place the mouse pointer over the Visualizer Make icon in the Shadows of
    Templates folder, and hold down the right button of the mouse.

 2. Drag the icon to the Exercise folder, and let go of the the mouse button.

You have now created the Make.

To rename the Make:

 1. Hold down the Alt key on the keyboard, and select the icon with the left
    button of the mouse.

 2. In the resultant box under the icon, overtype the existing text with the
    text MainMake. When you are finished, select on the icon with the left
    button of the mouse.

This has renamed your object MainMake.

Your Exercise folder should now contain the six icons that you need. They are:

o A menu called MainMenu
o A window called MainWin
o A window called DataWin
o A program called MainProg
o A program called DataProg
o A make called MainMake

The folder should look like this: Close the Visualizer Shadows of Templates
folder.

Check your Exercise directory to see that you have the six corresponding files.


ΓòÉΓòÉΓòÉ 5.6. Exercise 3 - Adding the objects to the Make ΓòÉΓòÉΓòÉ

In this exercise, you add all your newly created Visualizer objects to the
Make. At the end of the exercise, your Make window should look like this:

 1. In the Exercise folder, double click on the MainMake icon. The Make window
    is displayed:

 2. In the Exercise folder, place the mouse arrow over the MainMenu icon, hold
    down the right button of the mouse, and drag the icon to the MainMake
    window.

    As you drag, a line links the two icons.

    Let go of the mouse button. The MainMenu menu is then added to the
    MainMake.

 3. In the same way, drag the following icons to the MainMake window:

   o MainWin
   o DataWin
   o MainProg
   o DataProg

    The Make should now look as follows:

 4. Click on the Save tool bar button to save the Make.

    Alternatively:, on the MainMake main window, select the Make menu, and from
    that menu select Save.

You have now added all the Visualizer Development objects you require to the
Make.

You need to use the Make in the next exercise. If you want to continue at this
point, do not close it.


ΓòÉΓòÉΓòÉ 5.7. Exercise 4 - Creating the Menu ΓòÉΓòÉΓòÉ

In this exercise, you create the menu. At the end of the exercise, your menu
should look like this:

 1. On the MainMake main window, double click on the entry for the MainMenu
    menu. This displays a window with the title MainMenu - Menu.

 2. Click on the Change menu bar entry tool bar button. Alternatively:, on the
    MainMenu - Menu window, select the menu called Menu, and the option Change
    menu bar entry.

 3. On the resultant window, change the Text to Start the Mnemonic to S and the
    Reference to Start as shown in the following illustration.

 4. Select OK.

    This is the title of the menu, and Start will appear on the menu bar.

 5. On the MainMenu - Menu, window select the menu called Selected, and select
    the Open Settings option.

 6. On the resultant window, type the following text under Entry attributes:

   Field               You type
   Text                Run report
   Accelerator         Shift
   Key                 R
   Mnemonic            R
   Reference           RunRep

 7. Make no changes to the bottom half of the window (Entry action). Press the
    Apply button, then the Next button. You have just created the first entry
    on the menu, Run Report.

 8. You are now going to create the second entry on the menu. Type the
    following text under Entry attributes:

   Field               You type
   Text                Start Data Program
   Accelerator         Shift
   Key                 S
   Mnemonic            S
   Reference           StartDataProg

 9. In the Entry action field, select the Start Program radio button.

10. Select the small button in the bottom right hand corner of the window
    marked Select File.

11. From the resultant Select Program window, select the DataProg program and
    select OK. The details of the program will be entered in the Location and
    Name fields.

12. Press the OK button on the Menu entry settings window.

13. The finished menu should look as follows:

14. Click on the Save tool bar button. Alternatively:, on the MainMenu - Menu
    window select the menu called Menu, and the Save option.

15. Double click on the system icon on the top left of the MainMenu - Menu
    window to close the window.

You have now created the menu.

You need to use the Make in the next exercise. If you want to continue at this
point, do not close it.


ΓòÉΓòÉΓòÉ 5.8. Exercise 5 - Creating the Main window ΓòÉΓòÉΓòÉ

In this exercise, you create the main window of the application by adding the
main menu to a blank window template. At the end of the exercise, your window
should look like this:

 1. On the MainMake main window, double click on the entry for the MainWin
    window. This displays two windows:

   o A window with the title MainWin - Window
   o A blank window with the title Window Template.

 2. By dragging the yellow border, make the Window Template window slightly
    smaller.

 3. Click on the Open Settings tool bar button. Alternatively:, on the MainWin
    - Window window, select the menu called Window and then select the Open
    Settings option.

 4. On the resultant window, change the Window title to Main Window.

 5. Change the border type to Dialog.

 6. In the Title bar section, select the Minimize and Maximize check boxes, and
    then select OK.

    Notice the Window Template has now changed.

 7. In the Exercise folder, place the mouse arrow over the MainMenu icon, hold
    down the right button of the mouse, and drag the icon to the window called
    Main Window.

    As you do so, a line links the two icons.

 8. Let go of the mouse button. The MainMenu menu is added to the Main Window
    window.

 9. On the Main Window window, select the Start menu and note the two options,
    Run Report and Start Data Program, as shown in the following illustration:

10. Click on the Save tool bar button. Alternatively:, on the MainWin - Window
    window select the menu called Window, and the Save option.

11. Double click on the system icon on the top left of the MainWin - Window
    window to close down the window.

You have now created the MainWin window.

You need to use the Make in the next exercise. If you want to continue at this
point, do not close it.


ΓòÉΓòÉΓòÉ 5.9. Exercise 6 - Creating the Main program ΓòÉΓòÉΓòÉ

In this exercise, you create the main program - the code which is the entry
point to the application.

Much of the code is generated for you automatically by Visualizer Development,
based on the design of your window. You are going to automatically generate
some code based on the window you have just created called MainWin.

You also need to use the shadow of an existing Visualizer Report, such as
AVGSAL.REP. (Look in your Visualizer Samples folder.)

Before you start the exercise, create a shadow of the report and position the
shadowed report icon in such a way that it is near the top of the window. Later
in the exercise, you need to drag it to another window.

 1. On the MainMake main window, double click on the entry for the MainProg
    program. This displays a window with the title MainProg - Program:

 2. In the Exercise folder, place the mouse arrow over the MainWin icon, hold
    down the right button of the mouse, drag it to anywhere on the MainProg
    window, and let go of the mouse button.

    After a few seconds a MainProg - Create window is displayed. This indicates
    which blocks of code are going to be built, based on the window MainWin. It
    looks like this:

 3. Press the OK button to accept the defaults.

    The MainProg - Program window will now look like this:

 4. In the MainProg - Program window, under the Events list box, double click
    on the word SELECT. The following window will be displayed, showing the ON
    SELECT block of code.

 5. Using the title bar and the yellow border, position and size the MainProg -
    Event(SELECT) window so that it fills most of the screen.  Do not cover up
    the Report icon you positioned earlier at the top of the window.

 6. Within the MainProg - Event(SELECT) window locate the following text:

          !
          WHEN "T.W_MainWin.RunRep"
          DO
          ! Respond to Menu entry marked '"Run Report"'
          END
          !

 7. Place the cursor at the end of the line which contains the text:


        ! Respond to Menu entry marked '"Run Report"'

    Select with the left button of mouse to position the cursor there, and
    press the enter a couple of times to make some space.

    The text should now look as follows:

          !
          WHEN "T.W_MainWin.RunRep"
          DO
          ! Respond to Menu entry marked '"Run Report"'

          <cursor position>
          END
          !

 8. Place the mouse arrow over the report icon that you want to use, hold down
    the right button of the mouse and drag the icon to the MainProg -
    Event(SELECT) window.

 9. Place the icon anywhere on the window and let go of the mouse button.

    Text, similar to the text that follows, will be added to the existing text
    (you may need to scroll up or down to find it).

          IF NULL(AVGSAL_Rep'CLASS)
            OPEN IBMREPORT AVGSAL_Rep,
              NAME = "AVGSAL.REP",
              IDENTIFIER = "D:\FTW\SAMPLES\ENU\AVGSAL.REP"

          CALL AVGSAL_Rep'OPEN()

    Note:   The generated code is placed at the cursor, not the position where
    you drop the icon.

10. Remove any blank lines from before and after the new text (use the delete
    key).

11. Click on the Format tool bar button to line up the text.

    The text should now look similar to the following (there is more text above
    and below this text).

          !
          WHEN "T.W_MainWin.RunRep"
          DO
          ! Respond to Menu entry marked '"Run Report"'
          IF NULL(AVGSAL_Rep'CLASS)
            OPEN IBMREPORT AVGSAL_Rep,
              NAME = "AVGSAL.REP",
              IDENTIFIER = "D:\FTW\SAMPLES\ENU\AVGSAL.REP"

          CALL AVGSAL_Rep'OPEN()

          END
          !

12. Close the MainProg - Event(SELECT) window by double-clicking on the System
    Icon, and select Yes when prompted to save changes to the code.

13. Click on the Save tool bar button. Alternatively:, on the MainProg -
    Program main window, select the menu called Program, and from that menu
    select Save.

14. Double click on the system icon on the top left of the MainProg - Program
    window to close the window.

You have now created your main program.

You need to use the Make in the next exercise. If you want to continue at this
point, do not close it.


ΓòÉΓòÉΓòÉ 5.10. Exercise 7 - Creating the Data window ΓòÉΓòÉΓòÉ

In this exercise, you create the Data window. You use the Data window for
entering the data that your application will process.

During the exercise, you select the controls you need to include in the Data
window, position them where you want them to be, and resize them by using the
mouse.

The exercise also introduces the technique of cloning. Visualizer Development
allows you to replicate window controls that you have created into sets that
work together. You can clone a control by using the the Clones window.

At the end of the exercise, your Data window should look like this:

As you can see, the window contains the following parts:

o Three Push buttons
o A List box with horizontal and vertical scroll bars
o Two Single line entry fields with accompanying text fields

This exercise is divided into three corresponding parts.

When you start the exercise, and the Window Template is on display, turn on the
tool bar Display grid and the Snap to grid functions.

The Display grid function causes the Window Template to display a matrix of
dots. These are designed to help you align manually the controls that you place
on the window. The Window Template with the grid on display looks like this:
The Snap to grid function aligns controls automatically to the nearest row and
column of dots.


ΓòÉΓòÉΓòÉ 5.10.1. Adding the push buttons ΓòÉΓòÉΓòÉ

To create and position the push buttons:

 1. On the MainMake main window, double click on the entry for the DataWin
    window.

    This displays two windows: a window with the title DataWin - Window, and a
    window with the title Window Template.

 2. To make it easier to build the window, position the DataWin - Window at the
    top left of the screen, and position the Window Template at the bottom
    right of the screen.

    Do not change the size of the Window Template.

 3. On the DataWin - Window window, under the text Controls Palette, select
    dropdown list, and from the resultant list select Push button. You may need
    to scroll down the list to locate Push button.

 4. In the data entry field to the right of the text Data1, type Insert and
    select the check box called Text.

 5. On the Edit menu choose the Place control option.

 6. On the resultant Place control window type the numbers 5 for X position,
    and 5 for Y position. Press OK.

    This places a push button containing the text Insert in the bottom left
    hand corner of the Window Template.

    Alternatively, use the mouse to select the position on the Window Template
    where you want the push button to appear. Move the mouse arrow to the
    position, and click the left mouse button.

    Note:   The position of the mouse arrow becomes the position of the bottom
    left corner of the push button.

 7. On the Selected menu, choose the Clones option.

 8. On the resultant Clones window, type 3 for Number of clones, and 5 for
    Clone gap. Select Right for Clone direction. Press OK.

You now have three push buttons in the bottom left corner of the window, but
they are all labelled Insert. You need to change the labels on two push
buttons, and you need to increase the length of the buttons to accommodate
their new longer labels.

 1. On the Selected menu choose the Change Name option.

    On the resultant Change name window, you see first the information for
    button one, Clone 1.

 2. Press the down arrow beside the Clone number and you see the information
    for button two, Clone 2.

 3. In the data entry field to the right of Data 1, overwrite Insert with the
    text Change and press Apply.

 4. Press the down arrow beside the Clone number and you see the information
    for button three, Clone 3.

 5. In the data entry field to the right of Data 1, overwrite the text Insert
    with the text Delete and press OK.

 6. Shut the Change name window by double clicking on the System Icon.

    In the Window Template window, you now have three push buttons called
    Insert, Change, and Delete, but the buttons may be too small to hold all
    the text. In the step, you resize them by using the mouse.

    The group of three is surrounded by a border which has eight sizing handles
    around it.

 7. Place the mouse cursor on the handle in the middle of the right side of the
    border. The mouse cursor turns into a left-right arrow. Hold down either
    mouse button and drag the the border to the right. Make the push buttons
    about 50% wider, but do not make them any higher.

    The window should now look as follows:


ΓòÉΓòÉΓòÉ 5.10.2. Adding the list box with scroll bars ΓòÉΓòÉΓòÉ

In the following section of this exercise, you add the list box and its scroll
bars to the window:

 1. On the DataWin - Window window, under the text Controls Palette, select the
    down arrow, and from the resultant list select List box.  (You need to
    scroll down the list to locate List box.)

 2. In the data entry field, to the right of the text Data1, type Layout and in
    the data entry field, to the right of the text Data2, type Column as shown
    in the following screen:

 3. Move the mouse arrow to the position on the window template where you want
    the List box to appear, and double click the left mouse button.

    Note:   Remember that the position of the mouse arrow becomes the position
    of the bottom left corner of the List box.

    Alternatively, you could use the Edit menu, and the Place control option.
    If so, type 5 for X position, 25 for Y position, and press OK. This will
    place a list box above the push buttons in the Window Template.

 4. On the Selected menu, choose the Open Settings option.

 5. On the resultant List box - Settings window, select Vertical and Horizontal
    scroll bars, and press OK.

    Your List box should now have its horizontal and vertical scroll bars.

 6. Resize the List box by using the mouse so that it is almost the full width
    of the window, as shown in the following screen.

    Remember - use the left mouse button to select the List box; use either
    mouse button to drag the appropriate sizing handle.

    The window should now look as follows:


ΓòÉΓòÉΓòÉ 5.10.3. Adding the single line entry fields ΓòÉΓòÉΓòÉ

In this third and final part of this exercise, you add the two labelled Single
line entry fields, and then save the whole window.

You use the mouse and Ctrl key to copy and position the second of the two entry
fields.

At the end of this part of the exercise, your window is complete, and it should
look like this:

 1. On the DataWin - Window window, under the text Controls Palette, select the
    down arrow, and from the resultant list select Text.

 2. In the data entry field, to the right of the text Data1, type Name and
    select on the check box called Text.

 3. Move the mouse arrow to the position on the Window Template where you want
    the text to appear, and double click the left mouse button.

    Name appears on the Window Template.

 4. Move the mouse arrow back to the Controls Palette and open it.

 5. Scroll down the list and select Single line edit

 6. In the data entry field, to the right of the text Data1, type SLEName.

 7. Move the mouse arrow back to the Window Template, position it where you
    want the Single line entry field to appear, beside Name, and double click
    the left mouse button.

    The entry field appears on the Window Template.

 8. Resize the entry field by using the mouse. Make it about three times as
    long.

    Remember - use the left mouse button to select the entry field; use either
    mouse button to grab the appropriate sizing handle and drag it till the
    extry field is long enough.

Now you need to copy both the name and the entry field. You then need to change
the label on the copy, and resize the space for the new label. You also need to
shorten the copied entry field.

 1. Select Name by placing the mouse pointer on top of it and clicking the left
    mouse button.

    The sizing handles appear around it.

 2. Release the left mouse button, and hold down the right mouse button.

 3. Drag to the position where you want the copy of Name to appear below the
    original.

    Note:   As you begin to do this, a shadowed copy of the border around Name
            appears and moves as you drag.

 4. Press and hold the Ctrl key, and release the right mouse button.

    The copy of Name appears below the original.

 5. Select the copy by clicking on it with the left mouse button, and open the
    Selected menu on the DataWin - Window.

 6. Select the Change Name option.

    The Change Name screen is displayed.

 7. In the data entry field, to the right of the text Data1, type Balance and
    select OK.

    The word Balance now replaces the word Name on the template window, but not
    all of it is visible. You need to lengthen the space for it.

 8. Select Balance

 9. Use the mouse to copy the Single line entry field and position it beside
    the word Balance.

    Remember - use the left mouse button to select, release it and then hold
    down the right mouse button and drag. Hold down the Ctrl key and release
    the right mouse button.

10. Shorten the copied entry field to about half of its original length by
    using the mouse.

11. With the sizing handles still around the entry field, go back to the
    Selected menu on the DataWin - Window

12. Select the Change Name option.

    The Change Name screen is displayed.

13. In the entry field, to the right of the text Data1, type SLEBalance and
    select Apply.

14. Click on the Open settings tool bar button. Alternatively:, on the DataWin
    - Window window, select the Window menu and select the Open Settings
    option.

15. On the resultant window, change the Window title to Data Window and the
    border to Dialog. Select the OK button. Note how the Window Template has
    changed.

16. Click on the Save tool bar button. Alternatively:, on the DataWin - Window
    window select the Window menu and select the Save option.

17. Close the DataWin - Window window by double clicking on the system icon in
    its top left corner.

You have now created the DataWin window.

You need to use the Make in the next exercise. If you want to continue at this
point, do not close it.


ΓòÉΓòÉΓòÉ 5.11. Exercise 8 - Creating the Data program ΓòÉΓòÉΓòÉ

In this exercise, you create the Data program.

The Data program is generated from the Data window in a way similar to the way
that Main program was generated from the Main window. For the most part, the
process is automatic, and then you make some manual additions.

The code you generate is based on the window you have just created called
DataWin,.

 1. On the MainMake main window, double click on the entry for the DataProg
    program. This displays a window with the title DataProg - Program.

 2. In the Exercise folder, place the mouse arrow over the DataWin icon, hold
    down the right button of the mouse, and drag the icon to anywhere on the
    DataProg window. Let go of the mouse button when you have finished.

    The DataProg - Create window is displayed. This indicates which blocks of
    code are going to be built, based on the window DataWin.

Because you have a list box on your window, you need to indicate which data
this list box is going to show:

 1. In the top right hand corner of the DataProg - Create window, select on the
    text Data for Lists.

    This changes the window to look as follows:

 2. Select the small Add details button in the center of the window.

    A window with the title DataProg - Define 'LIST1' on window 'DataWin' is
    displayed:

 3. In the data entry fields Title, Data, and Width, type the following text:

   Field               You type
   Title               Name
   Data                Tab1.Name
   Width               150

 4. Press the Apply button.

    This updates the list box at the top of the window with the details of
    column 1.

 5. In the data entry fields Title, Data, and Width type the following text:

   Field               You type
   Title               Balance
   Data                Tab1.Balance
   Width               100

 6. Press the Apply button.

    This updates the list box at the top of the window with the details of
    column 2.

 7. Press OK on the DataProg - Define 'LIST1' on window 'DataWin' window.


ΓòÉΓòÉΓòÉ 5.11.1. Generating the code ΓòÉΓòÉΓòÉ

To generate the code:

 1. In the top left hand corner of the DataProg - Create window, select the
    text Blocks to be built.

    The window reverts to its original layout.

 2. Press OK.

    The code is now generated automatically, and the DataProg - Program window
    should look as follows:


ΓòÉΓòÉΓòÉ 5.11.2. Editing the code ΓòÉΓòÉΓòÉ

The following sets of instructions tell you how to insert additional blocks of
code you need for running the application.


ΓòÉΓòÉΓòÉ 5.11.2.1. Adding code to the On Start block ΓòÉΓòÉΓòÉ

The following additional code creates a data table called Mytable.Tab, adds two
columns called Name and Balance, and enters two rows of data into the table.
You add the code to the ON START block of code so that the table is created
each time the program runs.

Note:   When you type vertical bars, ensure that they are the unbroken vertical
        bars, or the code will not work.

 1. In the DataProg - Program window, under the text Events, double click on
    the word START.

    The DataProg - Event(START) window is displayed, and it should contain the
    ON START block of code.

 2. Maximize the window by selecting the button in the top right hand corner of
    the DataProg - Event(START) window. Within the DataProg - Event(START)
    window locate the following text:

             CALL List_Define
             CALL Source_Define
             CALL Target_Define
             !
             OPEN WINDOW W_DataWin, , "I.Windows.DataWin",
              SOURCECTRL = POINTER(SourceCtrl[0]),
              TARGETCTRL = POINTER(TargetCtrl[0])

 3. Place the cursor at the end of the line which contains the text CALL
    Target_Define. Use the left button of the mouse to position the cursor
    there, and press the enter key to create some blank lines.

 4. In the space after the CALL Target_Define statement, type the following
    text.

             ! Set two variables to hold the name of the table,
             ! and it's location
             LET tabname = "mytable.tab"
             LET tabloc = A.System.StartDS'LOCATION

             ! Delete the table if it already exists,
             ! but ignore error (FORGIVE) if table does not exist
             OPEN SYSTEM Sys
             FORGIVE
               CALL Sys'DELETE(FULLPATH(tabloc,tabname))

             ! Open a new table, known to the program as Tab1
             OPEN TABLE Tab1,
              NAME = tabname,
              LOCATION = tabloc,
              MODE = "Write",
              OBJECTCLASS = "IBMTABLE"

             ! Put two columns in the table
             DEFINE Tab1.Name[0]
             DEFINE Tab1.Balance[0]

             ! Set some column attributes
             LET Tab1.Name[0]'TYPE = "Character"
             LET Tab1.Name[0]'WIDTH = 50
             LET Tab1.Balance[0]'TYPE = "Numeric"
             LET Tab1.Balance[0]'WIDTH = 50
             LET Tab1.Balance[0]'FORMAT = "$,<2"

             ! Create the table key column as 'Name'
             DEFINE keys[1]
             LET keys[1]= "Name"
             CALL Tab1'SETKEYS(keys)

             !Add two rows of data
             INSERT Tab1.Balance{"Martin Smith"} = 12345
             INSERT Tab1.Balance{"Mary Jones"} = 23456

 5. Click on the Format tool bar button to line up the text. Alternatively:, go
    back to the DataProg - Program window, and select the Format option from
    the Program menu.

 6. Click on the Syntax tool bar button to check the syntax of the code.

    Correct any errors you may have in your code by verifying it against the
    code above.

 7. Shut the DataProg - Event(START) window, by double clicking on the System
    Icon, and select Yes when prompted to save changes to the code.


ΓòÉΓòÉΓòÉ 5.11.2.2. Adding code to the ON SELECT block ΓòÉΓòÉΓòÉ

You need to add sections of code to four areas of the ON SELECT block of code.
The sections of code you add, relate to the following user actions:

o Pressing the Insert button
o Pressing the Change button
o Pressing the Delete button
o Selecting a row in the list box

Adding code for the Insert action

The code you type in this set of instructions runs when a user presses the
Insert button to add a new row to the table.

 1. In the DataProg - Program window, under the text Events, double click on
    the word SELECT.

    The DataProg - Event(SELECT) window is displayed, and it should contain the
    ON SELECT block of code.

 2. If it is not already maximized, maximize the window by selecting on the
    button in the top right hand corner of the DataProg - Event(SELECT) window.

 3. Within the DataProg - Event(SELECT) window, locate the following text:

        WHEN 1                                     ! button marked 'Insert
        DO
        ! 'push' button marked 'Insert'
        END

 4. Place the cursor at the end of the line which contains the text ! 'push'
    button marked 'Insert', and press the enter key to insert some blank lines.

 5. In the space after the ! 'push' button marked 'Insert' statement, type the
    following text:

        IF ROW(Tab1.Name{SLEName}) = 0
        DO
          LET row = INSERT(Tab1.Name{SLEName})
          LET Tab1.Balance[row] = SLEBalance
        END
        ELSE
          MESSAGE "FTB10003",0,
            "The row you want to insert already "||
            "exists.  Please retry."


Adding code for the Change action

The code you type in this set of instructions runs when the user presses the
Change button to change existing data in the table.

 1. Scroll down the window and locate the following text:

        WHEN 2                                     ! button marked 'Change
        DO
        ! 'push' button marked 'Change'
        END

 2. Place the cursor at the end of the line which contains the text ! 'push'
    button marked 'Change'. Press the enter key to create some blank lines.

 3. In the blank lines after the ! 'push' button marked 'Change' statement,
    type the following text:

        IF ROW(Tab1.Name{SLEName}) > 0
        DO
          LET Tab1.Balance{SLEName} = SLEBalance
          END
        ELSE
          MESSAGE "FTB10003",0,
           "The row you want to change does not "||
           "exist.  Please retry."


Adding code for the Delete action

The code you type in this set of instructions runs when the user presses the
Delete button to delete an existing row in the table.

 1. Scroll down the window and locate the following text:

        WHEN 3                                    ! button marked 'Delete
        DO
        ! 'push' button marked 'Delete'
        END

 2. Place the cursor at the end of the line which contains the text ! 'push'
    button marked 'Delete' Press the enter key to create some blank lines.

 3. In the blank lines after the ! 'push' button marked 'Delete' statement,
    type the following text:

        IF ROW(Tab1.Name{SLEName}) > 0
          DELETE Tab1.Name{SLEName}
        ELSE
          MESSAGE "FTB10003",0,
           "The row you want to delete does not "||
           "exist.  Please retry."


Adding code for the Select action

The code you type in this set of instructions runs when the user selects a row
in the list box.

 1. Scroll down the window and locate the following text:

        WHEN "T.W_DataWin.LIST1"
        DO
        ! list box set for single select mode
        END

 2. Place the cursor at the end of the line which contains the text ! list box
    set for single select mode (select with the left button of mouse to
    position the cursor there) and press the enter key to create some blank
    lines.

 3. In the blank lines after the ! list box set for single select mode
    statement, type the following text.

        IF A.System.BoxNumber > 0        ! Enduser select
        DO
          LET SLEname = Tab1.Name[A.System.BoxNumber]
          LET SLEbalance = Tab1.Balance[A.System.BoxNumber]
        END

 4. Click on the Format tool bar button to line up the text. Alternatively:, go
    back to the DataProg - Program window, and select the Format option from
    the Program menu.

 5. Press the Syntax button to check the syntax of the code.

    Correct any errors you may have in your code by verifying it against the
    code above.

 6. Shut the DataProg - Event(SELECT) window by double clicking on the System
    Icon, and select Yes when prompted to save changes to the code.

 7. Click on the Save tool bar button. Alternatively:, on the DataProg -
    Program main window, select the Program menu, and from that menu select
    Save.

 8. Double click on the system icon on the top left of the DataProg - Program
    window to close down the window.

You have now created your data program.

You need to use the Make in the next exercise. If you want to continue at this
point, do not close it.


ΓòÉΓòÉΓòÉ 5.12. Exercise 9 - Compiling the application ΓòÉΓòÉΓòÉ

In this exercise, you compile the objects into an application.

 1. On the MainMake main window, choose the Make menu, and the Set compile
    destination option.

 2. On the resultant window, MainMake - Compile destination, next to
    Application name, type MainApp and press OK.

    On the MainMake main window, the text at the bottom of the screen should
    now be Destination: MainApp.

 3. Within the MainMake main window, select the entry for MainProg.

 4. Select the Selected menu, and then select the Make Key option.

    The class of the MainProg should then be Key Program.

 5. Click on the Compile all tool bar button. Alternatively:, on the MainMake
    main window, choose the Make menu, and select the Compile all option.

After a few seconds, you should hear a sound.

If the compile has been successful, the MainApp application icon is added
automatically to your Exercise folder. Your folder should now look like this:

You have now finished developing your application.


ΓòÉΓòÉΓòÉ 5.12.1. What to do if you get errors ΓòÉΓòÉΓòÉ

If you get errors when you compile your application, Visualizer Development
displays a window which tells you the program where they occur, and lists the
line numbers which may be at fault.

In many cases, one error-often the first one listed in a specified program-can
cause the compiler to register errors in lines which are correct. Therefore,
you may find that in correcting just one error, other apparent errors disappear
when you re-compile.

To investigate and correct errors:

Move the mouse arrow to the appropriate program entry in the MainMake-Make
window, and double click on it.

This action opens the Program editor window which displays the source code for
the specified program.

There are now three courses of action you can try:

   o Use the Compile tool bar button to compile the program by itself.

     When you compile an individual program, Visualizer Development produces a
     more comprehensive list of errors.

   o Check all the code you have added to the program against the code you were
     instructed to type in the appropriate exercise.

     You may have, for example, accidentally omitted a line of code, or made a
     typing or syntax error.

   o Use the Syntax tool bar button to check the code for syntax errors.

For more information on debugging code, refer to IBM Visualizer Development for
OS/2: Using, SH45-5095.


ΓòÉΓòÉΓòÉ 5.13. Exercise 10 - Running the application ΓòÉΓòÉΓòÉ

In this exercise, you run the application, and enter data which you can
process.

 1. In the Exercise folder, double click on the MainApp application icon.

    The main window for your application, Main Window, is displayed:

 2. Select the Start menu and choose the first option, Run Report.

    This opens the Visualizer Report.

 3. Close down the report by double clicking on the report system icon.

 4. On the main window for your application, Main Window, select the Start menu
    and choose the second option, Start Data Program.

    This displays your other window, the Data Window, containing the list box
    and the data from your table.

    Note:   Starting this program has also created the table mytable.tab which
            has been added to the Exercise folder:

 5. In the Name field of the Data Window, type the name Steve Dickson. In the
    Balance field, type a balance of 56789 and press Insert. The new data is
    added to the table and the list box is updated.

 6. In the list box, select the row for Mary Jones. (You may need to scroll.)

    This data is added to the Name and Balance fields above.

 7. In the Balance field, change the data to 98765 and press Change. The data
    in the table and the list box is updated.

 8. In the list box, select the row for Martin Smith. This data is added to the
    Name and Balance fields above.

 9. Press Delete. The data is deleted from the table and the list box.

10. Try other operations such as pressing the insert button when the name field
    is a name that already exists in the table, pressing the delete button or
    change button when the name field is a name that does not exist, or
    inserting a new name without any balance.

11. When you have finished, close down the Data Window by double clicking on
    the system icon.

12. Maximize the Main Window by selecting the large box in the top right hand
    corner of the window.

13. Normalize the Main Window by selecting the same button again.

14. Minimize the Main Window by selecting the small box in the top right hand
    corner of the window.

15. Surface the Main Window by selecting on the OS/2 desktop with both buttons
    of the mouse simultaneously, and from the resultant Window List window,
    double click on Main Window.

16. Shut down the application.

17. Finally double click on the system icon on the top left of the MainMake -
    Make window to close down the window and answer Yes to the question about
    saving your changes.


ΓòÉΓòÉΓòÉ 5.14. Summary ΓòÉΓòÉΓòÉ

You have now built a simple Visualizer application.

For more examples of applications, see IBM Visualizer Development for OS/2:
Using, SH45-5095. For more information about the ASL language, see IBM
Visualizer Development for OS/2: Reference, SH45-5096.


ΓòÉΓòÉΓòÉ 6. Visualizer Education Request Form ΓòÉΓòÉΓòÉ

To receive details on Visualizer Education, please complete this form and mail
or fax it to:

IBM United Kingdom Limited
ContactPoint
Warwick Software Development Laboratory
PO Box 31, Birmingham Road
WARWICK
United Kingdom  CV34 5JL

Telephone:                    [phone]
Fax number:                   [phone]
IBM Mail Exchange:            GBIBMNRT at IBMMAIL
IBM Internal Network:         MARKET at ASICVM1
Bitnet:                       MARKET at VNET
Internet:                     [e-mail]

IBM Corporation
FAO Mary Crocket
1 East Kirkwood Blvd
Roanoke
Texas  762 99 0001
USA

Telephone:                    [phone]
Fax number:                   [phone]
IBM Mail Exchange:            USIB5Z9J at IBMMAIL
IBM Internal Network:         JONESSH at MSNVM1
Internet:                     [e-mail]

Query for OS/2                          Procedures for OS/2

[]  Introductory education              []  Introductory education
[]  Advanced education                  []  Advanced education

Charts for OS/2                         Development for OS/2

[]  Introductory education              []  Introductory education
[]  Advanced education                  []  Advanced education

Statistics OS/2                         Plans for OS/2

[]  End-user education                  []  End-user education

Other (Please detail your requirements)

ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Name:                Address:

Company:

Phone No.:


ΓòÉΓòÉΓòÉ 7. Visualizer Information Request Form ΓòÉΓòÉΓòÉ

To receive information about Visualizer products, just call:

In U.S.A., 1-800-IBM-CALL, extension 137

In Canada, 1-800-465-1234, extension 2002

Elsewhere, [phone]

Alternatively, complete this form and fax it to:

[phone]

[]  Query for OS/2                 []  Procedures for OS/2
[]  Charts for OS/2                []  Development for OS/2
[]  Statistics for OS/2            []  Plans for OS/2
[]  Ultimedia Query for OS/2

Other (Please detail your requirements)

ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Name:                Address:

Company:

Phone No.: