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, 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 lines of code, regardless of the platform (Windows or MacOS). Implementing the same tasks in a native language such as C/C++ would use thousands of lines of code, and would take months instead of minutes.

What is a 4D 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 capabilities.

Usually, a plug-in does things that:

- 4th Dimension cannot do (i.e., specific platform technology)

- would be very hard to write just using 4th Dimension

- are only available as Plug-in Entrypoints

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, 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. (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 routine is a routine written in a native language (usually C or C++) that causes an action.

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, therefore 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:

1- must be a Shared Library (MacOS) or a DLL (Windows)

2- under MacOS, should have a resource fork with 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 as the DLL.

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

The resource fork of a plug-in must contain at least:

- a resource of type '4BNX' of the ID the plug-in wants that is also > 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 Plug-In Wizard, as one of its main features is to build all these resources. This is particularly useful for Windows programmers since 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 Plug-In Wizard 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 4DPlug-inAPI.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 (3.5 in North America) 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 machines. 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 or when it is for internal use, since it may change or be removed without warning, even in a minor version, depending on internal development. (When an entry point is provided and appears in documentation, it should be supported.)

Why the need for a 4D plug-in ?

Although 4th Dimension provides hundred of commands used to manipulate records and implement the user interface, some features (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, and 4D Open (which are based on the 4D Plug-in architecture) provide an open, elegant solution regardless of a 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 the power and productivity of both the application and the user.