Installation

The ATL is a module of the BSPK component, which, like all components, lust be installed in the Components folder of the 4D database, 4D application or 4D Server.

1.1 Prerequisites

the component version must absolutely match that of 4D, otherwise errors will be generated (component cannot be loaded). For example, to open an application with 4D v20 LTS, you need to use the v20 LTS version of the component, and if you then wish to open the same application with 4D v20 R, you'll need to replace the component with a v20 R version. Secondary version numbers (v20.1, v20.2 etc.) are not affected by this limitation.

the component must be installed and launched in interpreted mode, as certain utility methods will be generated in the host database (see Goodies section for details). The application is then compiled using these built-in methods.

The component can be used in both Project and Binary modes.

Tables/data classes must contain primary keys to be usable in ATL. However, tables without primary keys will still appear in the table list without being able to be opened.

In project mode, ATL is designed to work with standard 4D classes. Data classes, entities and selections must extend the default “DataClass”, “Entity” and “EntitySelection” classes.

1.2 Safety note

ATL does not require you to check the box “Execute the ‘On host event’ method for components”. So there's no risk of your code or data being altered by the component, which is totally neutral.

Data is an application's most precious asset, and no external communication or analysis of your data is carried out by ATL.

ATL is not allowed to run on 4D Server, in order to prevent any hidden or abusive use. As it is an interface tool, it can only be run on 4D, 4D Volume Desktop or 4D Client.

Like Use mode or Data Explorer, ATL is potentially very dangerous, as it can be used to modify and destroy data in production. It is therefore the developer's responsibility to authorize its use by other users.

1.3 Calling the ATL

To launch the ATL, simply execute the BSPK_ATL method from the Execute / Method menu, or by calling it from a menu, method or form object. The ATL will be launched in a new process, without a menu bar.

Without parameters, the ATL will open with full rights.

It is possible to modify certain characteristics by adding an object-type parameter, containing one or more of the properties below. In this case, you'll need to execute an intermediate method containing the call to the ATL.

1.3.1 Hiding certain tables

$vo_Param:=New object
$vo_Param.vc_DisableTableList:=New collection
$vo_Param.vc_DisableTableList.push(« Country »)
$vo_Param.vc_DisableTableList.push(« Line »)
BSPK_ATL($vo_Param)

To hide tables with very similar names (e.g. same root), it is not possible to use @ in table name strings. All table names must be added individually to the collection.

ATL, being ORDA-based, is case-sensitive. You must therefore respect the upper and lower case of the structure's table names.

1.3.2 Read-only ATL

$vo_Param:=New object
$vo_Param.vb_AllReadOnly:=True
BSPK_ATL($vo_Param)

None of the tables will be editable. Deleting and creating records will be impossible.

1.3.3 Some read-only tables

$vo_Param:=New object
$vo_Param.vc_ReadOnlyTableList:=New collection
$vo_Param.vc_ReadOnlyTableList.push("Country")
$vo_Param.vc_ReadOnlyTableList.push("Line")
BSPK_ATL($vo_Param)

Only tables in the collection are read-only. If the two properties vc_ReadOnlyTableList and vb_AllReadOnly are used together, the latter will take precedence and no table will be editable.

1.3.4 Associating a menu

$vo_Param:=New object
$vo_Param.vl_MenuBar:=1
BSPK_ATL($vo_Param)

By default, ATL runs without an associated menu bar, but you can keep the current menu bar by passing its number as a parameter.

This parameter will trigger the execution of the BSPH_SET_MENU_BAR method on the host, which in turn will install the designated menu bar.

If you're not using 4D's traditional menu bars, but rather the reference menus, you can nevertheless apply the same procedure, using BSPH_SET_MENU_BAR as a “marshalling yard” to launch your menu bars.

Important! You must share the methods launched by your menus between the host base and the component, so that they can be executed by the component (option available in method properties).

#DECLARE($vl_MenuBar : Integer)
Case of 
	: ($vl_MenuBar=1)
		SET MENU BAR(<>MyBar)
	: ($vl_MenuBar=2)
		SET MENU BAR(<>MySecondBar)
End case

1.3.5 Refresh frequency

$vo_Param:=New object
$vo_Param.vl_SecondWaitForAutoRefresh:=30
BSPK_ATL($vo_Param)

By default, ATL data is refreshed only when the table window is activated. This is generally sufficient to ensure that the data remains true to the database, at least for a certain period of time. However, if you wish to keep a table visible for a certain length of time, it may be useful to select the Refresh on timer option (see 3.6.2). In this case, the timer is set to 10 seconds by default. This value can be modified by changing the vl_SecondWaitForAutoRefresh parameter when ATL is launched.

1.4 First launch

When ATL is first launched, several BSPH-prefixed methods will be created in the host database. Most of these will not be of direct use to you. They are called by the component methods described in section 4.

One of these is designed to send an e-mail to the developer when an error occurs in the ATL (for example, when an incorrect ORDA instruction is entered in the search or formula editor). The parameters for sending these e-mails can be entered immediately.