The Developer Connection…ice Driver Kit for OS/2 3/DEV3-D1.ISO/devtools/persond/readme.scr

Text File | 1994-01-11 | 183.0 KB | 730 lines

  INTRODUCING PERSONAL AS BUILDER/2
  _________________________________

  Many organizations and industry sectors have very
  specific decision-support needs.  Personal AS Builder/2
  provides a comprehensive set of programming tools
  specifically designed to address these needs.
  Application designers with specific requirements not
  served by a product can use the application development
  component of Builder/2 to design, prototype, and build
  applications which meet their own particular needs,
  easily and quickly.

  Four components of Builder/2 provide the ability to
  develop applications in controlled stages.


  THE MENU EDITOR
  _______________

  You can use the Menu editor to create the menus used for
  menu bars, and to specify mnemonic and shortcut key
  sequences for each menu entry.  Also, if you have the
  OS/2* Programmer's Toolkit, you can create help text with
  the editor for any or all of your menu entries.


  THE WINDOW EDITOR
  _________________

  You can use the Window editor to create a graphic
  interface to "paste" buttons, menu bars, text entry or
  display fields, and other window controls onto your
  application windows.  Any menus that are defined can be
  connected to the menu bar (a list of available menus).
  The window control features such as maximize window,
  minimize window, scroll vertically, and scroll
  horizontally are defined for each of your application
  windows.


  THE PROGRAM EDITOR
  __________________


  You can use the Program editor to write and edit AS
  Language code (ASL) for your application.  If you use the
  Window and Menu editors to design your windows and menus,
  you can use the Program editor to automatically generate
  skeleton source code for the controls, menu bar entries,
  and their characteristics.  The Program editor also
  provides syntax checking, code formatting, and syntax
  help windows to help you create programs.


  THE MAKE FACILITY
  _________________


  You can use the Make facility to administer the programs,
  windows, and menus that you have designed for an
  application.  You can also use Make to compile selected
  files from your library, for example, if you are creating
  an application in stages.


  THE FACILITIES OF PERSONAL AS BUILDER/2
  _______________________________________

  With Personal AS Builder/2, you can build applications
  with varying degrees of complexity.  You can build simple
  applications with a single window and a program using the
  Window and Program editors.  These can then be compiled
  directly, without the need to use the Make facility.

  You can also design more complicated applications that
  use many programs and windows, and use the Make facility
  to compile them all together.  For example, you could use
  Builder/2 to create complex applications, such as a stock
  control facility for an international, multi-product,
  organization.  Indeed, Personal AS Chart and Report were
  themselves developed using the full functions of
  Builder/2.

  With Personal AS Builder/2 you can build 32-bit
  applications with the following features:

  o   Dynamic Data Exchange (DDE) enabled, either as DDE
      Clients, or DDE Servers, or both Clients and Servers

  o   Drag and drop enabled

  o   Personalized end-user interfaces

  o   Support for a range of data file types, including:

      -   OS/2 Metafile (.MET)
      -   OS/2 2.0 Bitmap (.BMP)
      -   OS/2 1.1 Bitmap (.BMP)
      -   Zsoft Image Format (.PCX)
      -   Tagged Image Format File (.TIF)
      -   Graphics Interchange Format (.GIF)
      -   Personal AS object

  o   Supporting the Common User Access* (CUA*) and Systems
      Application Architecture* (SAA*) guidelines

  o   Supporting the application programming interfaces
      (APIs) for the other Personal AS objects

  o   Sharing data and common end-user interfaces with
      mainframe and other workstations

  o   Supporting the exchange of data using host AS,
      including facilities for handling different file
      types

  o   Linking existing applications written in "C" to the
      application's front-end user interface by using the
      Window and Menu facilities

  o   Linking, via SQL, to DB2/2* and other databases

  o   Including your own extensive help or on-line
      documentation, using the OS/2 Programmer's Toolkit.


  USING PERSONAL AS BUILDER/2 WITH OTHER PARTS OF
  _______________________________________________
  THE PERSONAL AS FAMILY
  _______________________

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

  Builder/2 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
  Personal AS product -- including the development of
  Personal AS Builder/2 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
  Builder/2:

  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.

  Builder/2 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.


  PROGRAMMING FUNDAMENTALS
  ________________________


  This section explains the concepts relevant to
  application programming with Builder/2.


  SINGLE TASKING SYSTEMS
  ______________________

  The most basic system is a single user, single task,
  system with text based input and output.  A block diagram
  of such a system is shown below:

                 *-------------*     *--------------*
                 |             |     |              |
                 |   Operating |---->| Text Display |
                 |             |     *--------------*
                 |             |
                 |    System   |     *--------------*
                 |             |<----|  Keyboard    |
                 *-------------*     *--------------*
                        |
                 *-------------*
                 |             |
                 |  Program    |
                 *-------------*
                        |
                 *-------------*
                 |             |
                 | Subroutines |
                 *-------------*

  In this system, the programmer has written a program
  which performs the processing and uses basic features of
  the operating system to input and display text.  There
  are probably subroutines included that can be reused by
  other programs for commonly occurring processing.  The
  program is started by the operating system and it runs
  until it reaches a stop statement.


  MULTITASKING SYSTEMS
  ____________________

  A multitasking system allows more than one program to
  reside in the memory space at one time.  There are two
  systems used with multiple programs in memory: one system
  stops the first program when the second program starts,
  the other method has the operating system dividing
  processing time between the two programs.  This gives the
  impression that the programs are executing
  simultaneously, although only one program executes at a
  given moment.  The operating system switches each program
  on in sequence, and the rapid swapping between programs
  gives the impression that there are multiple active
  programs.

  Even though the programs are not actually active at the
  same moment, it is possible for one program to send a
  message to another program.  The operating system stores
  the communication requests between programs and sends
  them when the destination program becomes active.

  *----------------------------*     *--------------*
  |                            |     |              |
  |   Operating System         |---->| Text Display |
  |                            |     *--------------*
  |                            |
  |   Multi-tasking Interface  |     *--------------*
  |                            |<----|  Keyboard    |
  *----------------------------*     *--------------*
         |              |
   *-----------*  *------------*
   |           |  |            |
   | Program 1 |  | Program 2  |
   *-----------*  *------------*

  Note that the two programs share a single display for
  output and a single keyboard for input.  The user must
  have a way of indicating which one of the programs they
  are using at a particular moment.  There are several ways
  of doing this, but the most useful and user friendly is
  the graphical user interface (GUI).


  MULTITASKING WITH GRAPHICAL INTERFACE
  _____________________________________

  Using a graphical interface allows the creation of more
  than one virtual display on the screen and allows easy
  switching between programs.

  *----------------------------*     *-------------*
  |                            |     |  1  |*------|
  |  Operating System          |---->|-----*|      | Display
  |                            |     |      |  2   |
  |  Multi-tasking Interface   |     *-------------*
  |                            |     *--------------*
  |  Graphic Interface         |<----|  Keyboard    |
  *----------------------------*     *--------------*
         |              |
   *-----------*  *------------*
   |           |  |            |
   | Program 1 |  | Program 2  |
   *-----------*  *------------*

  The display now has two windows displayed on it.  One
  window is for program one and the other is for program
  two.  The windows also include controls for changing
  their size and location.  Since the display area of the
  window is less than the size of the full display, scroll
  controls may be available on the window to move the
  program output to view text or graphics that will not fit
  inside the window.

  The multiple areas on the display simplify multitasking.
  More information on windows and window controls is
  available in later sections.


  EVENT-DRIVEN PROGRAMS
  _____________________

  In the earlier examples, the program started at the
  beginning and went through to the end and then stopped,
  although some code may have been executed more than once
  before stopping.  In an event-driven program, the order
  of execution is determined by the order of external
  events.  One such event is the starting of the program,
  which activates code for handling a start event.  Some
  code will execute to initialize the program variables and
  perhaps communicate with the user.

  Other events might come from other programs sending a
  message, from the user performing some action on the
  program's window (for example, selecting an item from a
  menu or selecting a graphic object).  The communication
  of events to the program is handled by system software
  (the operating system and some extensions).

  *----------------------------*     *-------------*
  | Operating System           |     |  1  |*------|
  |                            |---->|-----*|      |Display
  | Multi-tasking Interface    |     |      |  2   |
  |                            |     *-------------*
  | Graphic Interface          |     *--------------*
  |                            |<----|  Keyboard    |
  | Event Control Software     |     *--------------*
  *----------------------------*
  *----------------* *------------------*
  |*--------------*| |*--------------*  |
  ||event block 1 || ||event block 1 |  |
  |*--------------*| |*--------------*  |
  |*--------------*| |*--------------*  |
  ||event block 2 || ||event block 2 |  |
  |*--------------*| |*--------------*  |
  |*--------------*| |*--------------*  |
  ||event block 3 || ||event block 3 |  |
  |*--------------*| |*--------------*  |
  |                | |                  |
  |  Program 1     | |   Program 2      |
  *----------------* *------------------*

  One event handles the starting of the program, one
  handles processing selected data, one handles stopping
  the program.  Many additional types of event are
  possible.  The program generation feature of Builder/2
  simplifies handling events by generating most of the
  event handling code.


  BLOCK STRUCTURING

  Each of the blocks of code for handling events has a
  start point and an end point or way of exiting.  It is
  not possible to jump into the middle of a block of event
  code.  The practice of coding in distinct functional
  blocks is called block structuring.

  The preceding diagram shows only event blocks, but other
  types of blocks exist.  The blocks which contain code,
  but are not activated by external events, are called
  procedure blocks.  Events control the execution of the
  program, so the procedure blocks are started from a block
  of code that has been activated by an event.

  Some languages, such as BASIC or C, can be written in
  block structured form or free form, depending on the
  programmer's preference.  Other languages, such as PASCAL
  and ASL, require all code to be in blocks.

  Using block structuring for the code may seem to involve
  more work.  It does impose an additional requirement, but
  there are many benefits that arise from the ease of

  maintenance of the code, and from reliability.  Indeed,
  some types of programming could not be done practically
  without block structure to the coding.


  APPLICATIONS WITH MULTIPLE PROGRAMS

  The preceding examples consider each program as a
  self-contained unit.  It is also possible to group
  programs together in an application.  Each of the
  programs would handle part of the processing and would
  communicate the results to the controlling program.

  *----------------------------*     *-------------*
  | Operating System           |     |  1  |*------|
  |                            |---->|-----*|      |Display
  | Multi-tasking Interface    |     |      |  2   |
  |                            |     *-------------*
  | Graphic Interface          |     *--------------*
  |                            |<----|  Keyboard    |
  | Event Control Software     |     *--------------*
  |                            |
  | Shared Data and Events     |
  *----------------------------*
  *----------------*      *------------------*
  |*--------------*|      |*---------------* |
  ||event block 1 ||      ||event block 1  | |
  |*--------------*|<---->|*---------------* |
  |*--------------*|      |*---------------* |
  ||event block 2 ||      ||event block 2  | |
  |*--------------*|      |*---------------* |
  |*--------------*|      |*---------------* |
  ||event block 3 ||      ||event block 3  | |
  |*--------------*|      |*---------------* |
  |                |      |                  |
  |  Program 1     |      |   Program 2      |
  *----------------*      *------------------*

  In Builder/2 there is a hierarchy of program, master, and
  application.  These different types of program work
  together and can share messages and data in defined ways.
  This hierarchy is covered in greater detail in later
  sections.


  OBJECT-ORIENTED PROGRAMMING WITH ASL
  ____________________________________

  The definitions already covered are general ones.
  Different programming environments implement them in
  different ways.  Usually, the amount of code needed to
  support event driven, multitasking, applications with
  graphic interfaces is substantial.

  To simplify coding, much of the functionality is placed
  into libraries, which are collections of subroutines or
  functions.  Using libraries helps to code these
  applications, but there is still a lot of code to
  understand and maintain.

  One way to simplify the task of programming while still
  providing advanced features, is to use an object-oriented
  language.  As with the other definitions, there are
  different ways to implement this feature.  All
  implementations of object-oriented languages use
  constructions called OBJECTS.  These associate data,
  events, and code together in a specific way.

  *----------------------------*     *-------------*
  | Operating System           |     |  1  |*------|
  |                            |---->|-----*|      |Display
  | Multi-tasking Interface    |     |      |  2   |
  |                            |     *-------------*
  | Graphic Interface          |      (window 1 has an
  |                            |      object displayed)
  | Event Control Software     |
  |                            |
  | Shared Data and Events     |
  |                            |     *--------------*
  | Code and Data for Objects  |<----|  Keyboard    |
  *----------------------------*     *--------------*
  *----------------*      *------------------*
  |*--------------*|      |*--------------*  |
  ||event block 1 ||      ||event block 1 |  |
  || open object  ||<---->|*--------------*  |
  || set attribute||      |*--------------*  |
  |*--------------*|      ||event block 2 |  |
  |*--------------*|      |*--------------*  |
  ||event block 2 ||      |*--------------*  |
  || call action  ||      ||event block 3 |  |
  |*--------------*|      |*--------------*  |
  |                |      |                  |
  |  Program 1     |      |   Program 2      |
  *----------------*      *------------------*

  For example consider the SLE object class in ASL.  An SLE
  is a SINGLE-LINE ENTRY field which can display text or
  accept input from the user.  The word CLASS indicates the
  master copy or template for the objects.  Multiple
  copies, or instances, of the object can be created from
  this template.  This allows several SLEs on a window.
  Each SLE provides a box for entering or displaying data.
  To create an SLE, you must open an instance of the SLE
  object.  When the SLE object is opened, it must be opened
  in a certain context.  For an SLE, this means that the
  entry must be defined for a window.

  Each object has attributes that define how a particular
  instance of the object will appear to the user.  The SLE
  object has attributes for location and size, for the
  variable that matches this SLE, whether the SLE is
  selectable or not, the number and location of copies of
  the SLE, how text in the entry box is displayed, and
  links to help for how to use this control.  Rather than
  write code to handle all these attributes each time an
  entry is needed, the programmer can simply define the
  attributes.  Code already associated with the SLE object
  will control the presentation of the SLE to the user,
  ensuring that it appears in the way that the programmer
  requires.

  The following code opens an instance of the SLE object
  class called mysle1 on the SampWind window.  The
               ______        ________
  location, size and text for the control are defined.
  Attributes which are not defined are given default
  values.

    OPEN SLE  mysle1,SampWind,
         x=70, y=150,           ! Location of entry field
         sizey=100,             ! Horizontal size of field
                                ! vertical height is one character
         expression="days1"     ! Variable to associate with field

  If attributes have default values, these are used for the
  initialization of the attributes.  ENABLED is normally
  set to 1 to enable the selection of the SLE.  This value
  can be overwritten as the example below shows:

    LET mysle1'enabled=0     ! The entry field cannot hold a cursor

  Note that the ENABLED attribute for the SLE1 entry field
                                          ____
  is indicated by joining the object name and attribute
  together with the quote symbol.

  There are also events associated with the SLE object
  class.  If the data in the SLE has changed, and the user
  selects a window control, the event handling code causes
  a DATA event to be sent to the program that opened the
  control.  The ON DATA event block in that program is
  given control and whatever instructions are in it are
  executed.  After execution of the ON DATA block, the
  program will go into a waiting state until another event
  occurs.

    ON DATA
        IF days1 = "friday" THEN
        LET day =5
    END

  There can also be actions connected with objects.  The
  SLE object has the REFRESH action associated with it.
  This just repaints the SLE field on the screen.

      LET days1 = "Today"
      CALL mysle1'refresh

  The coding for actions is similar to the way that
  attributes are specified for an object, although actions
  use CALL rather than LET.  This is covered in more detail
  in later sections.


  Objects and subroutines

  Objects may seem to be nothing more than an unusual way
  of writing subroutines, but there is more to an object
  than that.  Certainly, many of the functions of objects
  could be duplicated with a collection of subroutines with
  passed parameters instead of attributes.  There would
  need to be a subroutine for each action, as well as a
  subroutine to open and close the object.

  Remembering all the possible parameters for each
  subroutine, and which subroutines perform which actions,
  indicates a reason for simplifying the coding process by
  using objects.  There are many attributes to the SLE
  object that receive default values if they are not
  explicitly defined.  If an SLE was a subroutine, all the
  values would have to be passed each time the subroutine
  was called.

  The object-oriented nature of the SLE object also aids
  program design and testing.  A program can be written
  with the minimum number of attributes defined, as in the
  previous examples, and more attributes defined later
  after the design has been tested.  Other attributes that
  might be used later include HORZJUST, TEXTLIMIT, and
  HELP.  These are the horizontal justification setting,
  the maximum length of text that can be displayed, and a
  link to any help text that can to displayed to aid the
  user's understanding of the SLE's function.

  There is another reason for using objects.  Objects are
  much more powerful when used in an environment with many
  different applications, such as in &core..  With use,
  objects will become more intuitive and their advantages
  over subroutines will become apparent.

  WINDOW DESIGN TOOLS
  ___________________

  A large percentage of the code for programs, and a large
  part of a programmer's work, can be for communicating
  with the end user.  Since coding for placing a menu on a
  window or accepting text from an entry field is so
  common, it is sensible to create some tools for handling
  these functions.  Some code is already in the operating
  system and, particularly with modern systems, this code
  can greatly simplify dialogs with the user.

  You have another level of tools for screen design with
  Builder/2 editors.  The Menu editor helps the programmer
  to create and maintain menus for window menu bars.  The
  Window editor provides a palette of available window
  parts, such as push buttons, radio boxes, check boxes,
  list boxes, scroll bars, and graphic areas.  The
  programmer selects a tool from the palette and places it
  on a template window.

  After the programmer has produced a window with all the
  entry and display tools in the correct places, the
  Program editor creates code based on the window.  The
  Program editor also produces code for the various events
  that can happen in the application.

  A window can be easily created with the editing tools.
  After the window is made, the code for opening the
  object, reacting to events, and modifying data must be
  added.  The Program editor works closely with Window
  editor to simplify writing code.  Most of the code
  written for handling window objects is automatically
  generated.

  The following code was generated automatically by the
  Program editor for the a simple window.
  Note that since the execution is controlled by events,
  the code blocks do not need to be in a specific order.

    ! This block is executed when the user selects Close on
    ! the system menu
    ON QUIT
    DO
      IF A.System.Object = "T..W_SPBDEMO"
        RUN PROGRAM A.System.ThisTask,STOP
    END
    ! This block is executed whenever a selectable control or menu
    ! entry is activated.
    ON SELECT
    DO
      CASE A.System.Object        ! Which screen object?
        WHEN "T.W_SPBDEMO.PUSH1"  ! PUSH Control marked
        DO
          ! Insert your code here
        END
        ! no other controls in this list
      END                         ! End case, A.System.Object
    END

    ! This block is executed when the program is initially invoked.
    ! It is normally used to initialize variables needed during
    ! program execution and to open the main window of the
    ! application.
    ON START
    DO
      ! Open window based on source window "SPBDEMO.WIN"
      OPEN WINDOW W_SPBDEMO, , "I.windows.SPBDEMO"
      ! Window name W_SPBDEMO generated from window file name
    END

    ! This block is executed when terminating the program.
    ! Use this block to carry out any housekeeping required before
    ! termination.
    ON STOP
    DO
      ! Insert your code to tidy up here
      STOP ! Final action, stop the program
    END

  The START block code is generated to open the window.
  The program then goes into a wait state until another
  event occurs.  When the push button is selected, the
  SELECT block is activated to process whatever window
  control was selected.  (For this window, there is only
  one control.)  The two other blocks control the ending of
  the program.  If QUIT is selected from the system menu,
  the QUIT block will be activated.

  The QUIT block runs the STOP block in the same program.
  It sends an event trigger to its own program.  The
  program will receive the event and run the STOP block.
  The STOP block includes the STOP statement which will
  shut down the program.

  Note that there are comments in the generated code to
  indicate what the different blocks are.  There is also an
  indication of where you will need to add code of your own
  to customize your application.

  If you are not a programmer, and do not wish to develop
  code for an application, you can still use the window
  editor and the Menu editor to develop the interface for
  an application.  The interface consists of all the
  windows, controls, and displayed text that the end user
  sees when they run the program.  The design of the
  application can include the actual windows that the end
  user sees.  The additional code needed to make the
  application functional can be added later by a
  programmer.


  HELP TEXT FOR THE END USER
  __________________________

  Builder/2 provides the ability to link help text with the
  different parts of your application.  There is a Help
  Index with a list of all the subjects for which help is
  available, or context sensitive help can be invoked for a
  particular control.

  The IBM Help Manager Information Presentation Facility
  (IPF) is part of OS/2.  It displays the help text
  associated with different window controls in your
  application.  As part of the development of an
  application, you can set links between your windows and
  help text files.


  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                          SAA
  DB2/2                        Systems Application Architecture
  Presentation Manager