Power GUI Programming with VisualAge C++/powergui.iso/trialva/ibmcppw/help/iwfwsm35.hlp

OS/2 Help File | 1996-02-23 | 26.2 KB | 592 lines

ΓòÉΓòÉΓòÉ 1. Project Smarts ΓòÉΓòÉΓòÉ

Use Project Smarts to create a default project or projects that are
preconfigured for certain programming tasks.

To create a project, select the type of project you want to create, and then
click on the Next>> push button to customize the project.  A fully-configured
project with template source files is created for you. A README file tells you
how to build and run the project.

To create an empty project with default settings, select Default project from
the Project types list box.  Specify the project title, working directory, and
where you want the project created on the Location page. No source files are
created for you.  You can create source files by selecting the Edit button on
the project toolbar to bring up the VisualAge for C++ editor.

If you create any of the other project types, Project Smarts creates a
pre-configured project that comes with template source files that you can
modify to meet your application-specific requirements.

Note:  You can also create pre-configured projects by copying one of the sample
projects.


ΓòÉΓòÉΓòÉ 2. Location Page ΓòÉΓòÉΓòÉ

In the Location page, you can specify the following information:

 Project title
      The title for the project.  This title appears on the title bar of the
      project window.  If you are using Windows 95, it also appears below the
      project icon if the project is on your "Desktop".

 Source directory
      This is the directory where the files are to be generated, and will also
      be the working directory of your project. It will be created for you if
      it does not exist.

      If you create the Default Project, no files will be generated in this
      directory, but the directory will be created for you if it does not
      exist.

 Where to create project
      The container shows you all the directories in the drive selected in the
      Drives list.  You can select another drive from the Drives field to
      update the container with all the directories from your selected drive.
      Select the directory where you want the project file to be stored. The
      project file will be created in the directory you select from the
      container.

 Project file name
      This is the name that you want to give the created project file. Specify
      an unqualified file name.  For example, if you specify the project file
      name MYPROJECT, Project Smarts creates the project file MYPROJECT.IWP,
      with a corresponding project options file, MYPROJECT.IWO.


ΓòÉΓòÉΓòÉ 3. Source Files Page ΓòÉΓòÉΓòÉ

Use the Source Files page to specify the filename stem of the main source files
in your project.

For example, if you specify the file stem HELLO, your C++ main source files
will be named HELLO.CPP, HELLO.HPP, HELLO.H, HELLO.MAK, HELLO.RC, and the
executable will be called HELLO.EXE.

Any .C, .VBB, .RTF, .IPF, and .HLP files will be similarly named.


ΓòÉΓòÉΓòÉ 4. Prolog Page ΓòÉΓòÉΓòÉ

In the Prolog page, specify the prolog text that is to be placed at the
beginning of all your generated source files.  The text is saved in a file so
that the next time you create a project, the same prolog is used.

Prolog text is saved for projects whose source files use the same comment
syntax.  For example, the same prolog text is saved for the C++ Hello World, UI
Class Library, and C++ Dynamic Link Library projects because they use the same
comment style.  Similarly, the same prolog text is saved for IPF script files
that produce context-sensitive help or online documents.

You can use variables from the Name, Date, Version, and Copyright fields when
writing your prolog text.  These fields are represented by the following
variables:

 $NAME$       Substituted by the value in the Your name field.

 $DATE$       Substituted by the value in the Today's date field.

 $VERSION$    Substituted by the value in the Version field.

 $COPYRIGHT$  Substituted by the value in the Copyright field.


ΓòÉΓòÉΓòÉ 5. Title Page ΓòÉΓòÉΓòÉ

In the Title page, you specify the title of the generated visual application.
This text is displayed on the title bar of the application's frame window.

You also use this page to specify the title of a document or online help
source.  This title is displayed on the the help window's title bar.


ΓòÉΓòÉΓòÉ 6. Runtime Page ΓòÉΓòÉΓòÉ

In the Runtime page, you select the version of the VisualAge for C++ runtime
library you want to use.

Select Single-threaded if your program will only run in a single thread.
Select Multi-threaded if you plan to perform processing in secondary threads
and if you plan to use multithreaded libraries, such as the Open User Interface
Class Library.

The multithread version of the runtime library has slightly more overhead than
the single thread version, but the difference is almost insignificant. If you
need optimum performance from a single-threaded program, use the single thread
library. Using the multi-thread version of the library is recommended for most
applications.

Related Programming Guide Topics:

  Creating Multithread Programs
  Choosing Libraries


ΓòÉΓòÉΓòÉ 7. Linking Page ΓòÉΓòÉΓòÉ

In the Linking page, you specify whether you want to link statically or
dynamically to the VisualAge for C++ runtime library.

Linking Statically means that the code for all the runtime library functions
called by your program is copied into your executable file.  This results in a
larger executable file.  And if many copies of your program are run at the same
time, there will be one copy of the library functions in memory for each
program.  Statically linked programs, however, are easier to distribute because
the library functions are part of your executable file.

Linking Dynamically means that the code for the VisualAge for C++ runtime
library functions are not copied into your executable file.  Instead, the
function code stays in a separate VisualAge for C++ DLL file and your calls to
the functions are resolved at load time.  You will have a smaller executable
file, and there will only be one copy of the runtime library functions in
memory for all the programs that use them.  However, dynamically linked
programs can be harder to distribute because a separate DLL file that contains
the library functions must also be distributed.

You cannot distribute the VisualAge for C++ runtime library as is because that
would be in violation of the licensing agreement. You must create your own
runtime library DLL for distribution.

Related User's Guide Topic:

  Static and Dynamic Linking


ΓòÉΓòÉΓòÉ 8. Initialization/Termination Page ΓòÉΓòÉΓòÉ

In the Initialization/Termination page, you specify whether you want to write
your own custom _DLL_InitTerm function.

Select Custom if your DLL requires initialization and termination processing in
addition to that performed for the runtime environment. Otherwise, select
Default.


ΓòÉΓòÉΓòÉ 9. Export Method Page ΓòÉΓòÉΓòÉ

In the Export Method page, you can specify how you want the symbols in your C++
DLL exported. There are three different methods, each having their own
advantages and disadvantages:

 Ordinal
      Exporting by ordinal is the simplest method to use, but it is the most
      difficult to maintain.  To export all the symbols of a class by ordinal,
      you mark their definition with the _Export keyword, like this:

              class _Export foo
              {
                :
              };

      (You can also apply the _Export keyword to specific symbols like member
      functions and data members.)

      When a class is exported using the _Export keyword, all the public
      symbols in the class are exported only by ordinals that are assigned by
      the compiler.  When your DLL is updated, the compiler may assign
      different ordinals to the symbols, and may therefore cause the clients of
      your DLL to change the way they refer to your exported symbols.

      It is also important to know that accessing exported symbols by ordinal
      is the most efficient way.

 Assigned name and ordinal
      This method requires that you explicitly export each member of a class.
      You can optionally assign a name to each symbol so that it is known by
      that name to clients of your class. You can also assign an ordinal to the
      symbol so that the same ordinal is generated for the symbol each time you
      update the DLL.

      This method is the most convenient for the clients of your class if they
      do not have an import library to link to, and if they do not want to
      refer to your symbols via their ordinals.

      To export your classes in this manner, you must add a #pragma export
      directive for each member you want to export, like this:

              #pragma(foo::memberFcn, "Fcn", 5)

      In this example, the member function memberFcn was exported with the
      assigned name "Fcn" and the ordinal 5.

      There are some members that you must export:

       You must always export constructors and destructors.

       If an inlined or exported function uses private or protected members,
        you must also export those members.

       You should also export all static members, otherwise clients of your
        class will not be able to debug their code because the reference to the
        static data members cannot be resolved.

 Mangled name
      This method of exporting C++ symbols is the easiest to maintain because
      changing the DLL will not affect its clients. Also, this method enables
      you to easily export virtual function tables (VFTs).

      This method uses the CPPFILT utility to generate a list of all the symbol
      names in your object files (including the VFT), and places this list into
      a module definition (.DEF) file that tells the compiler and linker what
      symbols need to be exported.

      Even though the symbols in your classes are exported by their mangled
      names, clients of your class could still access them as if your symbols
      were statically linked as long as they had an import library they could
      link to. An import library for your DLL is automatically built for your
      C++ DLL using the IMPLIB function.

      Using this method, your source files do not need any special keywords or
      pragmas to mark a symbol for export.  All the export information is
      contained in the .DEF file.

 Related How Do I Topic:

  Exporting C++ members from a DLL


ΓòÉΓòÉΓòÉ 10. Document Type Page ΓòÉΓòÉΓòÉ

An IPF file can be compiled to either an online help file or an online book.
Select Online document if you intend to produce an online book. Select Help if
you intend to produce context-sensitive help information.


ΓòÉΓòÉΓòÉ 11. Resource Files Page ΓòÉΓòÉΓòÉ

In the Resource Files page, you specify whether you already have one or more
resource (.RC) files that you want to use for this project, or whether you want
Project Smarts to generate a template resource file for you.

If you want to use your existing resource files, enter the directory where
these files can be found.  All the .RC files in the specified directory are
copied over to the project's working directory (as specified in the Location
page). Any icon or bitmap files found in the specified directory are also
copied to the project's working directory. When the project is created, you can
run the Build action to build a resource DLL from your resource files.

Related User's Guide Topic:

  Using Resource Tools


ΓòÉΓòÉΓòÉ 12. Language Page ΓòÉΓòÉΓòÉ

In the Language page, you specify what language you want for the generated
source files, C or C++.


ΓòÉΓòÉΓòÉ 13. Target Names Page ΓòÉΓòÉΓòÉ

In the Target Names page, you specify the name of the Direct-to-SOM dynamic
link library that you want the DTS project to build.  Enter an unqualified name
without an extension in the DLL target name entry field.  This name will also
be used to name the main source files of the DLL.

The Also create a client EXE project with a main program check box lets you
specify whether you want Project Smarts to also create a client EXE program
that uses the DTS classes in your DLL. If you do want a client program created
for you, indicate the name of the target EXE as an unqualified name without an
extension in the Target name entry field.  The name will also be used to name
the main source files of the client EXE program.

If you choose to create a client EXE program, Project Smarts creates two
projects for you:  a client EXE project (titled as you specified in the
Location page.), and a DTS DLL subproject. The project hierarchy reflects the
dependency relationship between the EXE and DLL projects.

If you choose to create only the DTS DLL, Project Smarts creates only one
project for you, titled as you specified in the Location page.


ΓòÉΓòÉΓòÉ 14. DTS Classes Page ΓòÉΓòÉΓòÉ

In the DTS Classes page, list the names of C++ classes you want packaged as SOM
(System Object Model) classes. Enter one class name per line.

Select the Use long names for header files check box if you want Project Smarts
to generate source files with long names.  If you do not select the check box,
the generated files will be abbreviated to FAT file system format, based on the
class names.


ΓòÉΓòÉΓòÉ 15. Object Framework Page ΓòÉΓòÉΓòÉ

In the Object Framework page, specify whether you want your application to work
in the SOM (System Object Model) or DSOM (Distributed SOM) framework.

The power of SOM technology comes from the fact that SOM insulates the client
of an object from the object's implementation.  The power of DSOM lies in the
fact that DSOM insulates the client of an object from the object's location.

Distributed SOM (or DSOM) provides a framework that allows application programs
to access objects across address spaces. That is, application programs can
access objects in other processes, even on different machines. Both the
location and implementation of an object are hidden from a client, and the
client accesses the object (by way of method calls) in the same manner
regardless of its location.

For more information about SOM and DSOM, see the SOM Programming Guide.


ΓòÉΓòÉΓòÉ 16. Access Method Page ΓòÉΓòÉΓòÉ

The Data Access Builder supports DB2 version 2.1 directly through your choice
of embedded SQL (ESQL) or the DB2 Call Level Interface (DB2 CLI). In many
cases, embedded SQL, because of its static binding, provides a performance
advantage over DB2 CLI's dynamic binding. For more information on the
advantages and disadvantages of static versus dynamic binding, please refer to
your DB2 documentation.

The Data Access Builder  allows access to a multitude of database products
through its Open Database Connectivity (ODBC) driver manager and related
drivers.

If you are using a product supported by a compatible ODBC 2.0 driver (such as
Sybase 10 and Oracle 7), select ODBC as your access method.

For more information, see the section on Supported Database Products in the
User's Guide.


ΓòÉΓòÉΓòÉ 17. Component Page ΓòÉΓòÉΓòÉ

The first decision you need to make when creating components with the Compound
Document Framework is whether you want to create a container component or a
server component.

A server component can be embedded inside container components; however, it
cannot have objects linked to it or embedded inside it.

A container component has all of the features of a server component so it can
also be embedded inside other containers.  However, it can also have OLE
objects embedded in it. Container components use Structured Storage to save
their native data, along with data in the embedded components.

Most Win32 applications are containers, but some, such as a paintbrush
application that can be inserted inside a word processor document, are server
components.

Related IBM Open Class Library User's Guide Topics:

  Introducing the Compound Document Framework
  Creating a Server
  Creating a Container


ΓòÉΓòÉΓòÉ 18. Application Name Page ΓòÉΓòÉΓòÉ

The Compound Document Framework helps you create OLE-enabled applications.
Much of OLE's handling of objects is accomplished through the Win32 registry.

The application short name registers the component you create and it also
appears on the context menu for any objects the component can edit.

The long name is displayed on the application's title bar.

If you check the Use long names for header files checkbox, you can specify long
file names (that is, more than 8 characters) and Project Smarts will generate
the .hpp, .cpp, .rc, and .reg files using these names without shortening it.
Check this box only if your file system can take long names.

Related IBM Open Class Library User's Guide Topic:

  Introducing the Compound Document Framework


ΓòÉΓòÉΓòÉ 19. Model Class Page ΓòÉΓòÉΓòÉ

A component is comprised of a model and a view. The model defines and stores
the application data.  When embedding a component it is the component's model
data that is stored inside a container's Structured Storage file.

The Compound Document Framework provides an IModel base class which defines the
minimum behavior that a model class needs, including support for streaming.
The derived model class that Project Smarts creates for you can be customized
to meet the unique needs of your application by adding member functions and
data.

Enter the class name of the model in the Model Class Name field.

Related IBM Open Class Library User's Guide Topics:

  Introducing the Compound Document Framework
  Creating a Server Model
  Creating a Container Model
  The imodel.hpp header file


ΓòÉΓòÉΓòÉ 20. View Class Page ΓòÉΓòÉΓòÉ

A component is comprised of a model and a view.  The view defines the manner in
which data is presented to the end-user.

The Compound Document Framework provides an IView base class which defines the
minimum behavior that a view needs. The derived model class that you create can
be customized to meet the unique needs of your application by adding member
functions and data.

Enter the class name of the view in the View Class Name field.

Related IBM Open Class Library User's Guide Topics:

  Introducing the Compound Document Framework
  Creating a Server View
  The iview.hpp header file


ΓòÉΓòÉΓòÉ 21. File Extension Page ΓòÉΓòÉΓòÉ

When your application saves a file, a 3-character extension needs to be
assigned to the file to differentiate it from other files in the file system.
Specify the filename extension that should always be assigned during File save
operations.

Related IBM Open Class Library User's Guide Topic:

  The imodel.hpp header file


ΓòÉΓòÉΓòÉ 22. Datastore Page ΓòÉΓòÉΓòÉ

In the Datastore name field, enter the name of the database that contains the
tables or views that you want to access in your application.

In the Class name field, enter a name that is representative or descriptive of
the data that you will be accessing.

When Data Access Builder generates your access classes, it uses a class name
that you specified in this field to name the generated classes. For example, if
your application will be accessing a car dealer's database that contains all
pertinent information about the inventory of automobiles (such as make, color,
serial number), you may choose car as your class name. The generated Manager
and Datastore classes will be named by the Data Access Builder as "carManager"
and "carDatastore", respectively.

In the Source file stem field, enter the name that you want the Data Access
Builder to use when generating files. The generated file names consist of the
specified file stem and a file extension that is generated by the Data Access
Builder. This name should not be changed. The Data Access Builder uses specific
file extensions so that the files that it generates can be used by the compiler
or the appropriate tool.

If your file system limits the length of the file names, the Data Access
Builder  truncates the file stem accordingly.

For more information, see the section Class Settings Notebook - Names Page in
the User's Guide.


ΓòÉΓòÉΓòÉ 23. Access Classes Page ΓòÉΓòÉΓòÉ

Based on your requirements, select the type of source code that you want the
Data Access Builder to generate. If you will be programming C++ applications,
select the C++ button. If you want to generate system objects that provide
release-to-release binary compatibility and language-independent access, select
the IDL(SOM) button.

For more information, see the section Selecting the Code Generation Options of
the User's Guide.


ΓòÉΓòÉΓòÉ 24. Help Page ΓòÉΓòÉΓòÉ

In this page, you can specify the type of help file that Visual Builder is
going to create for you. Select IPF if you want to generate help information
using IBM's IPF format. Select RTF if you want to generate help information
using Microsoft's RTF format.


ΓòÉΓòÉΓòÉ 25. Executable Page ΓòÉΓòÉΓòÉ

In this page, you can specify whether you want to create an EXE or a DLL file.
If you select DLL, you have the option of specifying a project that has a
client main program. In this case, the main project is created with a Data
Access DLL subproject.


ΓòÉΓòÉΓòÉ 26. Include Path Page ΓòÉΓòÉΓòÉ

In this page, specify the directories that contain the header files used by
this application.


ΓòÉΓòÉΓòÉ 27. Layout Page ΓòÉΓòÉΓòÉ

In this page, you can specify if the online information will take up the entire
screen or will be displayed in two panels. Select Whole if you want the
information to take up the entire screen. Select Split if you want the
information to be displayed in two screens. In this case, you can use the
slider to indicate the display ratio of the two screens.


ΓòÉΓòÉΓòÉ 28. DSOM Page ΓòÉΓòÉΓòÉ

In this page, you must specify the name of the Interface Repository (IR) and
the server that will be associated with the SOM class.

An object can be accessed remotely by DSOM only if its class interface and
implementation is registered in the Interface Repository. Enter the name of the
local IR to be used in the Interface repository file name field.

In DSOM, each SOM class must be associated with a server. In turn, the server
is registered with DSOM in an Implementation Repository. Enter the name of the
server that will be associated with the SOM class in the Server name  field.


ΓòÉΓòÉΓòÉ 29. Push Buttons ΓòÉΓòÉΓòÉ

This section describes the push buttons on the bottom of the Project Smarts
notebook:

  <<Back
  Next>>
  Help
  Cancel
  Done


ΓòÉΓòÉΓòÉ 29.1. <<Back and Next>> ΓòÉΓòÉΓòÉ

Use the Back>> and Next>> push buttons to navigate through the Project Smarts
notebook.

Back>> takes you to the previous page in the notebook, and Next>> takes you
forward a page.


ΓòÉΓòÉΓòÉ 29.2. Help ΓòÉΓòÉΓòÉ

Click on the Help push button to get help about the top page of the Project
Smarts notebook. The page help will give you more information about the choices
on the page, and, if applicable, link you to related topics in the VisualAge
for C++ User's Guide and other publications.


ΓòÉΓòÉΓòÉ 29.3. Cancel ΓòÉΓòÉΓòÉ

Click on the Cancel push button to exit from Project Smarts without creating
any projects or saving any settings.


ΓòÉΓòÉΓòÉ 29.4. Done ΓòÉΓòÉΓòÉ

Click on the Done push button when you are ready to create your project.  When
you click on Done, files are copied to the source directory you specified on
the Location page, and one or more projects and subprojects are created for
you. The main project is opened after it is created.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

A project file is the physical representation of a project. It has the
extension .IWP, and can be stored anywhere on the file system.  If it is stored
in a directory on the file system that represents a Windows 95 folder, the
project file is visible as an object in the folder.  The title that appears
below the project icon is the project's title.

Every project also has an options file where the option settings for the
project's actions are stored. An options file has the extension .IWO and has
the same name as a project file.