4D Plugin API

version 2003

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.

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.

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.

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.