About 4th Dimension Plugins

4D - Documentation   Français   English   German   4D Plugin API, Command Theme List   4D Plugin API, Command Alphabetical List   Back   Previous   Next

version 2003


The 4D Language

Both 4th Dimension and 4D Server are platform independent, graphical, relational database managers that provide flexible and powerful development tools integrated into the database environment. A common and easy to learn high-level language called 4D Language is used to manipulate both database objects (Tables, Selections, Records, Fields) and User Interface objects (Windows, Forms, Menu Bars, Buttons).

The 4D Language is a modern, structured programming language whose features are fully detailed in the 4th Dimension Language Reference manual.

4th Dimension can manage a database (create, search, sort records) and create user interface components (windows, menus, splitters) using very few numbers of lines, regardless of the platform (Windows or MacOS). Implementing the same tasks a native language such as C/C++ can be done using thousand of lines of code, taking months instead of minutes.

Why the need for a plug-in ?

Although 4th Dimension provides hundred of commands used to manipulate records and implement user interface, some special use or feature (sometimes platform dependant) may be needed: one may need OLE or DDE under Windows, another may need AppleEvents under MacOS, while yet another may want to implement specific Statistics tools, file access over the network, a special user interface, or a private picture structure.

It is obvious that covering all areas of both the Macintosh and Windows operating systems by way of 4th Dimension commands would certainly lead to a product with thousands of commands, and at the same time, most users would have no need for such a large set of capabilities. Also, creating such an all-encompassing tool would make the 4th Dimension environment incredibly complex and would take most users months of study before useful results could be expected.

4D SA Productivity and Connectivity Modules such as 4D Write, 4D Draw, 4D Open (which are based on the 4D Plug-in architecture) provide an open, elegant solution that is irrespective of the particular user's needs. The modular nature of the 4th Dimension environment allows the creation of basic applications but does not preclude the development of highly complex systems. The 4th Dimension Plug-in architecture opens the 4D environment to any type of application or user. 4D Plug-ins multiply that application or user's power and productivity.

What is a plug-in and what can it do ?

A plug-in is a piece of code (DLL under Windows and Shared Library under MacOS) that 4th Dimension launches at start up. It adds functionality to 4th Dimension and thus increases its capacity.

Usually, a plug-in does things that:

- 4th Dimension cannot do (ie, specific platform technology),

- will be very hard to write just using 4th Dimension,

- are only available as Plug-in Entrypoint

In the past, a plug-in (referred to as an "External Procedure" or a "Package") could be written for speed improvement (long loops, statistics). This has no longer been the case for several years, in fact ever since the release of 4D Compiler.

A plug-in usually contains a set of routines given to the 4D Developer. It can handle an External Area and run an external process.

A plug-in routine is a routine written in native language (usually C or C++) that causes an action.

An external area is a part of a form that can display almost everything and interact with the user when necessary

An external process is a process that runs alone, usually in a loop, doing almost everything it wants. All process code belongs to the plug-in, 4th Dimension is simply present to receive/send events to the process.

Important note

A plug-in can be very simple, with just one routine performing a very small task, or it can be very complex, involving hundred of routines and areas. There is virtually no limit to what a plug-in can do, however every plug-in developer should remember that a plug-in is a "sample" piece of code, DLL or Shared Library. It is the plug-in that runs within 4th Dimension, not the opposite. As a piece of code, it is the host of 4th Dimension; it is not a stand-alone application. It shares CPU time and memory with 4th Dimension and other plug-ins, thus, it should be a polite code, using just what is necessary to run. For example, in long loops, a plug-in should call PA_Yield() to give time to the 4th Dimension scheduler unless its task is critical for both it and the database.

Structure of a plug-in

To be recognized as a plug-in by 4th Dimension, the plug-in must:

1- be a CFM Shared Library (MacOS 9 or MacOS X), a MachO Bundle Package (MacOSX) or a DLL (Windows)

2- under MacOS, it should contain some special resources (see below). Under Windows, this means that a file (containing the resources) with the same name and the extension ".RSR" must be located at the same level than the DLL.

3- be located in a Win4DX and/or a Mac4DX folder.

The resources of a plug-in must contain at least:

- A resource of type '4BNX'. The ID of this resource should always be greater than 15000

- A resource of type 'STR#' of the same ID. This resource contains the list of routine names

- Optionally, but useful for the user: a FON# and a THM# resource. These resources are used to group routines by theme in one or more pop-ups in the Method Editor.

ResEdit® and Resorcerer® Templates exist for all these resources, but the plug-in developer should use 4D PluginWizard, as one of its main features is to build all these resources. This is particulary useful for Windows programers as there is no resource editor such as ResEdit for that platform. Under Windows, 4th Dimension can itself be used to generate the resource file with the appropriate resources, but using 4D PluginWizard will be much easier.

Note for experienced users and previous 4D ExtensionKit users

4D Plug-in API is made to simplify plug-in writing. Using this API, a developer (Windows, MacOS or both) that only writes in C can write a sample plug-in in no time.

As you might have guessed, the 4D Plug-in API consists of C routines that wrap 4D Entry Points. This is done in the 4DPluginAPI.c source file. You may notice that the Call4D is still available, but some names have changed (The ParameterBlock becomes an EngineBlock).

Experienced developers probably have already wrapped the entry points they use, but moving code to this new API may take some time. Previous plug-ins that run using 4th Dimension version 5.5 or later should still run under this version, with the exception of some entry points that are no longer supported (see the "EntryPoints.h" header file). Please note that Hooks are no longer supported.

Since version 6.5, 4th Dimension does not support 68k machine. Plug-ins can only use double values and the REAL union is no long needed. The STR# definition of routines using real or real array should use the "&8" dans "&Y" flags.

About "hidden" entry points

All available entry points are present in this API.

There is no "hidden" entry point; all plug-in developers have the same tools. 4D SA does not make an entry point public when it is not supported (when an entry point is provided and appears in documentation, it should be supported), or when it is for internal use, or it may change or be removed without warning, even in a minor version, depending on internal development.

Modifying 4DPluginAPI.c

Previous 4D ExtensionKit users will notice that occasionally all the possible parameters for an entry point are not covered by the 4D Plug-in API function. It is possible for the developer to add his or her own routines in 4D Plug-in API, or to modify existing functions, but in this case it is better to do it in a separate source file. In this case, it will be easier to keep changes when 4D SA provides updated versions of 4D Plug-in API.


4D - Documentation   Français   English   German   4D Plugin API, Command Theme List   4D Plugin API, Command Alphabetical List   Back   Previous   Next