Skip to content

Library Workspaces

Libraries

We encourage the use of Libraries for sharing code among multiple workspaces. This is very flexible and easy to use:

  • Multiple libraries can be added/removed on a workspace level.
  • Libraries are easier to transport between multiple computers (due to the ability to use relative paths).
  • Libraries are easier to migrate between revisions (requires no special migration and/or configuration as all the configuration is on the workspace level).
  • Enables use of multiple library revisions in different workspaces (i.e., workspace A may use VDFQuery 2.3, workspace B may use VDFQuery 2.4, etc.).

In short, to share source/classes/class palette entries, we encourage you to use libraries rather than changing the system make path or modifying a workspace's AppSrcPath.

Using libraries is essentially the same as adding additional workspace-level paths. You get the same end result—sharing source between multiple workspaces—but they are easier to use, easier to migrate, and more flexible.

Recommendations for Library Usage

A set of recommendations has been implemented for library usage. The goal is to have a set of suggested standards that determines how libraries should be written, assembled, and installed. We've tried to come up with suggestions that would work well with all types of libraries, ranging from those written by a single developer for private use to those that will be widely distributed to others. This applies to both private libraries (used within a company) and public libraries (distributed to others).

These are guidelines and not requirements.

Installation

The term “installation” is informal. This can apply to creating your own library, unzipping and copying files, or executing a formal install program. The mechanics for the installation will differ, but the end results should be the same.

Library Installation

We strongly recommend that a library be installed in one of two relative modes:

  1. Installing Relative to Your Workspace
    This technique should be used with private libraries. Typically, these libraries will not have a formal installation program and often change as part of the development process.

If you install your libraries relative to your workspace, you have the advantage that the workspace and your libraries can be easily copied to other computers and drives. If you maintain the same relative file locations, no extra configuration work is required. For example, you can copy your workspace and libraries to a zip file, unzip them on another computer, click on the Workspace’s .sws file, and everything will just work.

We recommend that you create a sibling directory named "Libraries" and that you install the libraries as children of this directory.

Workspace Parent 15.0
MyWorkspace1
MyWorkspace2
Libraries
MyLibrary1
MyLibrary2

The specific structure of "Libraries\LibName" places libraries in a known location and groups them in a way that makes it clear what workspaces are libraries. This is useful because you normally do not load a library workspace directly in the Studio.

We encourage keeping the relative location between the workspace and its library simple. If a simple structure cannot be maintained because your workspaces are spread all over your disk, you can consider installing multiple copies of a library. For example, you may install separate copies of a library for a sample and for actual use. This allows you to try out a library and a sample without “polluting” your actual work area.

  1. Installing Relative to VDFRoot
    This technique should be used by public libraries. Typically, these libraries will have a formal installation program and will not change as part of the development process. If they change, you will probably receive a new installation build for reinstallation.

Since a public library will often have a more formal installation program, this installation program may not be able to determine where the workspaces that will use it are. In fact, those workspaces may not even exist yet. In such a case, you will want to install the library relative to VDFRoot. We suggest that you locate the library as a sibling of VDFRoot. Since DataFlex is usually installed in “Program Files,” this means that your library will also be installed in “Program Files.”

Program Files
DataFlex
SomeLibrary

Installing a library in this manner will still allow you to attach your workspace in a relative manner. When searching for a library with relative pathing, the Studio first looks for the library relative to the current workspace, and if not found, looks for the library relative to VDFRoot. This means that your workspaces can still be easily ported to other computers as long as those computers have the same library installed in the same relative fashion.

If you are creating an installation program for your library, note that the location of VDFRoot can be found in the registry location HKLM\Software\Data Access Worldwide\DataFlex\%REV%\Defaults\VDFRootDir (where %REV% is a specific revision of DataFlex). The registry key will return a value with the trailing slash already on it (e.g., C:\Program Files\DataFlex\18.0\).

When you place a library in “Program Files,” you should assume that the library is read-only. If you are planning on changing a library, do not install it under “Program Files.” Normally, a public library should be read-only, so a relative to VDFRoot installation is a perfect fit. Note that you should not install your samples under “Program Files.”

A library must be paired with a specific revision of DataFlex. Therefore, the library name should indicate the DataFlex revision number (e.g., "PublicLibrary1" instead of "PublicLibrary1").

When creating an install, note that the library’s .sws file (e.g., PublicLibrary1.sws) must contain the proper Version tag for the revision using it.

[Properties]
Version=18.0
[WorkspacePaths]
ConfigFile=.\Programs\Config.ws

If your installation program installs for multiple revisions of DataFlex, it is up to you to make sure that the appropriate .sws contains the appropriate revision marker.

When installing a library relative to VDFRoot, there is a good chance that this library should not be automatically migrated to a new revision. In fact, the user of the library may not have sufficient rights to create a migrated copy. It is up to the library provider to determine what the rules for library migration are. For example, you may state that migrating a library to a newer revision of DataFlex is not supported and that a user of the library should contact you for a newer library.

Samples Installation

Samples are usually only provided with Public Libraries. If the public library is installed relative to VDFRoot, the sample can be installed anywhere you wish (other than under a write-protected directory like Program Files).

C:\PublicLibrary1
Sample

The sample workspace’s .sws file can refer to the library using relative pathing. For example, PublicLibrary1Sample.sws might look like:

[Properties]
Version=18.0
[WorkspacePaths]
ConfigFile=.\Programs\Config.ws
[Projects]
Project0=Demo.src
[Libraries]
Lib1=..\PublicLibrary1 18.0.sws

If a sample is installed for a library that is located relative to your workspaces, the sample should be installed as a sibling of the workspace that will use the library.

Workspace Parent
MyWorkspace1
MySampleForLibrary1
Libraries
MyLibrary1

In this case, MySampleForLibrary1.sws might look like:

[Properties]
Version=18.0
[WorkspacePaths]
ConfigFile=.\Programs\Config.ws
[Projects]
Project0=Demo.src
[Libraries]
Lib1=..\Libraries\MyLibrary1.sws

Installing samples for private libraries is probably an unusual occurrence.

Documentation

We expect that a library may contain documentation ranging from a text file to a compiled help file (a .chm file). Whatever the type, documentation should be located in the library's Help sub-folder. The help file can be accessed by navigating to the directory and accessing the help file.

Integrating a Compiled Help File into the Studio's Help

Important: We wish to encourage the use and sharing of libraries. While we encourage the creation of complete documentation and provide a mechanism for integrating this into the help system, we recognize that this will not always happen. This should not stop you from creating and using libraries. Any type of documentation, even a text file, is valid. Do not consider integrating a compiled help book to be a requirement.

If your help is in the form of a compiled .chm help document, a mechanism is provided for adding the help directly to the DataFlex help system. This will make the help available from the Studio. It will be included in the Studio's help "Contents," "Index," and "Search" pages.

The Studio reserves a number of special help book names that are optionally part of the help system. If you rename your help file to one of these reserved names and copy the help file into the DataFlex help directory (e.g., C:\Program Files\DataFlex 15.0\Help), that help will become part of the help system.

Integrating Help for a Private Library

If your library is private, you can use one of the predefined private help book names. There are 5 predefined “slots” named Developer1.chm to Developer5.chm. It is up to the developer to determine how to use these names.

Integrating Help for a Public Library

If your library is public, we will provide a way that your help can be made available for all users of your library. To do this, contact Data Access Corporation and let us know that you have a public library. We will provide you with a unique help file name for your library. You will rename your help file to this name and copy it into the DataFlex Help directory. Note that you should only do this if:

  • You have a public library that you want others to use, and
  • You've actually created a properly formatted .chm help file.

Requirements for a Studio Compliant .chm Help File

If you wish to integrate your help file into the DataFlex Help system, your compiled help file should adhere to certain rules. The items in bold are the rules that are the most critical for correct operation. The other items are so that your help will “play nicely” with the other books in the set.

  • Index Settings should be set to:
  • Add New Keywords to Index File (HHK)
  • Binary Index
  • The Default Window should be named $global_main

  • The Default Frame should be set to Default (none)

  • The following TOC (Table Of Contents) Styles should be selected:

  • Border
  • Lines from Root
  • Plus/Minus Squares
  • Always Show Selection
  • Lines Between Items
  • Raised Edge
  • The Default Window should be named $global_main

  • The Default Frame should be set to Default (none)

  • Set the following options for Tri-pane Tabs and Windows:

  • TOC & Index
  • Favorites
  • Search Tab

  • Adv. Search

  • Set the following Tri-pane Options:

  • Auto-synchronize TOC

  • Remember Windows Size and Position

  • Set the following Buttons:

  • Hide/Show
  • Back
  • Forward
  • Refresh
  • Home
  • Options
  • Print

  • Locate

  • Set the following Placement options:

  • Top = 84
  • Left = 102
  • Height = 600

  • Width = 820

  • Set your outermost TOC so that it is a single book that contains all the other TOC levels.

  • Create an index entry for each keyword you want the Studio Code Editor to be able to access with Context Help.

For instance, if you have a library class named cMySpecialClass and the documentation for that class is on the page MyClassHelp.htm in your compiled help, create an index entry cMySpecialClass and have it point to the MyClassHelp.htm page in the compiled help project.

The key is to have a single index entry that exactly matches the keyword as it would be typed in your source code.

Note that after adding or updating a help book to the DataFlex Help system, the combined index (VisualDataFlex.chw) must be regenerated. This is automatically done when the index in the help system is first accessed (you’ll see the message “Preparing Index for first use…”) after the new help file has been added or changed.

On Windows Vista systems with UAC on, the combined VisualDataFlex.chw file may not be properly updated in the main Help folder if the help system was not first accessed with elevated rights. The easiest way to ensure that the combined index is updated correctly is to run the Studio with elevated rights (Run as Administrator) and access the help from the Studio after updating or adding a help book.

Library Creation Suggestions

These suggestions apply to the creation of libraries:

  • Assign a prefix that identifies each library. This prefix should be used for your class names, struct names, and globals. This will reduce the chance that there will be name collisions with other libraries and with future changes in DataFlex.
  • Do not test libraries within the library workspace. When you create a library, you will need to create a dummy project so you can create classes and files. Do not compile this project. Do your testing in another workspace that uses the library. This way you are properly testing the library as a library.
  • Add any classes to the class palette directly in the library. This way they will be available to the workspaces that use this library.
  • Any templates or wizards that will be added to the “Create New” dialog should be added directly to the library. This way they will be available to the workspaces that use this library.
  • Remember that you can load multiple instances of the Studio. When building libraries, you may wish to have a copy opened to the library (for registering classes and templates) and another to a test workspace.
  • Do not create library pre-compile packages and never pre-compile within a library. Pre-compiling packages in libraries makes them more difficult to use with other libraries. You should only pre-compile within non-library workspaces.
  • Do not create any new non-DataFlex file extensions. In most cases, all class files will have a “.pkg” extension.
  • If your library requires that you define windows structs such as RECT or NMHDR, use the following strategy. First, determine if the struct is defined in the package file tWinStructs.pkg. These contain the windows structs defined as part of the normal packages. They all use the prefix tWin, so RECT would be tWinRect. If this exists, use it. If the struct does not exist, create your own using your own unique prefix. Do not use the tWin prefix. Do not use #IFNDEF to conditionally create structs as you cannot be sure that the previous definition will match yours. It is acceptable that the same struct is defined in multiple libraries with different names.

If your library requires that you define a windows external function, you should define it conditionally using #IFNDEF. For example:

#IFNDEF Get_GetScrollInfo
External_Function GetScrollInfo "GetScrollInfo" User32.dll ;
    Handle hwnd ;
    UInteger fnBar ;
    Pointer lpsi ;
Returns UInteger
#ENDIF

System Settings

We have replaced the use of the term "global" (as in "global classes") with the term "system" (as in "system make path" and "system classes").

When we refer to "system," we simply refer to the DataFlex system entries/configuration, and we strongly discourage any modifications of system classes, packages, paths, and other system configurations. Instead, we encourage modifications of workspace entries/configuration and/or paths. This allows for easier migration between revisions, e.g., no migration of the Global Subclass layer, and no need to worry about any changes made in our system packages and/or directories or registry settings. It also makes it much easier to just take a directory structure consisting of one or more workspaces, zip it up, and unzip it on another machine and just start using it, without having to worry about any special system/machine-level configurations, etc. i.e., greater flexibility and easier to use.

See Also

Workspaces and Libraries