Parameterization and specific/custom development rules

Introduction

When custom/specific developments must be carried out, it is necessary to be organised in order that they survive as long as possible with respect to version changes. The fist section of this document details the ways of doing this.

Independently of this first point, there is a question about the technical organization of the folders where the developments are carried out. This question is considered in the second part of the documentation.

Protection of the modifications carried out

The software makes it possible to encapsulate the specific/custom developments from within the standard, notably when modifying at a final level certain elements in order to respond to requirements that are not covered in the standard software.

In order to facilitate the maintenance of these customizations and to give them as long a life as possible, a certain number of rules must be respected. These rules are 5 in number and are displayed below. By respecting them it is possible to limit to the maximum problems in the case of a patch or update.

But, before starting it is necessary to know the limits that exist. Irrespective of the sophistication of the activity code system, there are developments that are better carried out by re-writing rather than by modification of a standard OBJect. Thus, if a screen has been greatly modified (in particular if the sections have been modified) such that its is no longer easy to maintain the difference with the standard screen, it will probably be better to create it from scratch. Similarly, if a standard function is radically modified, it will probably be better to re-write it as a custom/specific function by working on the standard sub-programmes documented in ADONIX.

It is a element to be considered before any specific/custom development : is it better to re-write or modify the elements supplied by the standard software?

Once this question is considered case by case, the rules for giving the longest useful life as possible are as follows :

Rule number 1 : Never modify a standard source

Not keeping to this rule is the best means of obtaining a folder that is impossible to maintain.

In fact, the fact that a standard source is delivered means that this source must not be modified. The standard sources that are shipped provide documentation.

This limit is not however much of a problem. In fact, in the majority of cases, a dedicated specific/custom process is called if it exists. This is notably the case :

 in OBJect management, as well as the SUBXXX process, XXXbeing the OBJect code, a process SPEXXX exists to manage the custom/specific.

in enquiry, as well as the standard process (normally named CNSXXXSTD, XXX being the code for the enquiry), there is the possibility to enter the name of a specific/custom process (in general CNSXXXSPE).

 in the dictionary of actions, if the action is of the type Standard process, and the process name start with SUB, the equivalent process starting with SPE can also be used ; if the name of the process (TRAITE for example) does not start with SUB, the associated specific/custom process is named XYTRAITE and is therefore used to carryout the customization without touching the original code.

 in the dictionary of actions, in the action type is Window entry, the principal window calling for example FENETRE, a specific/custom process, named XWFENETRE, is used to carryout the customizations with out touching the original code.

Beyond this, if a customization requires the modification of a standard process, the only admissible way to resolve the problems of longevity consist of requesting an entry point in the ADONIX editor.

Rule number 2 : strict use of the naming rules for all the added elements.

It is imperative, to avoid any collision with future versions of the software, to name the added elements with names starting with X, Y, or Z. The contents of the grid shown below displays what is meant by an element.

Function definition	Title
GESATY	Data types
GESATB	Tables
GESACV	Activity codes
GESAMK	Screens
GESAWI (*)	Windows
GESAOB	Objects
GESACN	Inquiries
GESACT	Actions
ADOTRT	Processes
GESARP	Reports

(*) An exception is made for the windows starting with O, which are associated with an OBJect when the name start with X, Y, or Z.

Particular naming rules exist for certain elements. In fact :

 specific/custom parameters must imperatively be added in the dedicated chapters, whose code must start with X, Y, or Z.

 specific/custom messages must imperatively be added in the chapters, where the number falls between 160 and 169.

 specific/custom local menus and the specific/custom miscellaneous tables must use numbering ranges between 1000 and 1999.

Finally, the name of the fields added to the standard tables or screen must start with X_, Y_, or Z_.

Rule number 3 : protect with an activity code, but at the most refined level.

Respect of the naming rules is not sufficient to safeguard the longevity of the elements. It is also necessary to protected them with an activity code starting with X, Y, or Z. But is is advisable to only protect the modification made at the lowest level of detail, in order to benefit to the maximum from the evolution carried out on other elements in a software element. Thus, it is possible to protect :

 A complete screen, or a compete table. In this case, any modification carried out on the screen or the table by a patch will be ignored. Thus type of protection is only advisable for new screens or tables or in the case of a total modification of a screen or table. It is then of no use to place a specific/custom activity code at the level below, except if an activity code will be of use in order to have available variants in the screen or the table.

 The section of a screen. No fields in the section are then modified when a patch is applied. However, this is a quite high level of protection, because all the fields in the section are no longer modified when a patch is applied. It would therefore be better to protect at a more refined level when this is possible. It does remain the only acceptable level however if the position of a standard section is modified or if looking to make configurable to the folder management, the number of lines in a grid that would otherwise remain fixed.

 The screen field or the field in a table or the index of a table. It is this level of use in the case where the characteristics of a field are modified (format, type, title, length…). This level of protection is very refined, the only potential conflict being in the case of a patch affecting the protected fields.

 A linked table, a table a left list in an OBJect, a left list in an object (it is preferable to the global protection of the OBJect).

 An option, a variable associated with a function (it is preferable to the global protection of the function).

Certain elements cannot be protected in a detailed fashion (this is the case for the reports). In this case, the only solution is to globally protect the report, by installing the file with the .rpt extension at the level of the production folder, remembering that it is also possible to rename it.

There is a whole series of cases where the activity codes are of no use, notably for fields in the screens :

 If an additional control on a field is to be added and this control can be defined by a control table, it would be better to implement it in this way : it is in effect then a parameterization that has no requirement to be protected.

It is the same if wanting to restrict access to a field as a function of the user : the assigning of the access codes is in the parameterization.

 Similarly, if the user wants to globally change the attributes of the data type associated with the field, it would be better to modify the data type and protect it with an activity code : the protection of the field is then of no use.

 If specific/custom actions (named SPE or SPX) are to be added, it must be remember that these actions remain unchanged when a patch is applied, even if the field is not protected. It is therefore of little use to add an activity code to the field if other modifications have not been carried out. If the specific/custom actions impose the opening of a window, these actions must be catalogued in the dictionary of the actions. In addition, once the action code starts with X, Y, or Z, it is protected in the same fashion without it being necessary to protect the field. It is however necessary to protect the action with an activity code (it will only be applied if the code is Active).

 If the a standard action on a field is to be removed, it is simpler to carry out this with an action called SPX rather than deleting it (thus, the protection by activity code will not be necessary for the field).

Rule number 4 : Warning on the insertion on the existing sub-elements

The insertion of sub-elements in an element inhibits in certain cases the longevity. This is the case in the following :

 adding an index to a standard table must be made at the end of the index list, and certainly not at the start of the index list (the first index is the default). There is however no restriction on the fields. It is in addition recommended to not rename them in a consecutive fashion in the form ABVn, ABV being the abbreviation of the table and n the line number (it is in fact possible that an evolution of the standard requires the addition of a standard index).

 the sections of a screen are only known by their number. Thus, if a section is to be added to a screen, it is always necessary to add it at the end (exit to play on the entry rank). These is no longer a restriction on the fields.

 it will be the same for the tabs in a table, the left lists for an OBJect (version 140 differentiates the order of their appearance order, because field rank exists).

Rule number 5 : Before the installation of any patch or new version, the user must test the patch.

This utility has been created to make it possible to test for any potential conflicts arising from the application of a patch. In fact, it reads the parch file headers present in a given directory and displays in a log file the list of the elements present in this list and being the OBJect of customizations. If the list in question is empty, there is normally no risk of conflict. Conversely, the list of elements with conflict is generally poor and it is then necessary to examine the detail of elements that are found in it.

When a version is installed by means of a CD, a series of directories will be found (in a directory depending on the software, in version 130 of ADONIX X3 for example, the directory is X3Patch\X3V130_technical) named as a function of the intermediate versions of the software (P131, P132, P133…), which contain the files named List_nnn.dat. These files contain only the header of the elements contained in the consecutive patches that are used to pass from one version to another. It is therefore possible to use these files in the same way by the patch tester, in order to identify potential conflicts (start from the list following the current list installed in the folder to be updated).

---

Organization of the folders on two or three levels

During the execution of the software, the ADONIX engine loads and executes the files containing an intermediate code (the p-code) independently of the environment. These files can be programmes, the screen descriptions, table descriptions (in order to create a request on the table in question). This files are looked for in the folder currently in execution. But if a file does not exist in the folder, the Adonix engine will look for it in the parent folder, then in the grand-parent folder … The Adonix engine could thus possibly move up a hierarchy of 8 successive folders, but for for practical reasons, there is a limit of 3 levels (the folder management only manages 3).

The consequence of this structure is as follows : a user folder created under the software will depend either on the supervisor folder or on a folder that is itself dependent on supervisor folder. In fact, if this is not the case, the elements indispensable to the functioning of the folder and its parameterization, which are only present in the supervisor folder, will no longer be accessible. The two possible structures for a production folder are therefore as follows :

The intermediate reference is in general called the development folder, because one of the possible implementations of the folder hierarchies includes specific/custom developments.

The hierarchy with 3 levels is heavy to maintain. In fact, the existence of this 3 level hierarchy has practical consequences : transfer a production folder for a server to another assumes, so that the transferred folder transfer can function, that the hierarchy has also been transferred. In the case of a 2 level hierarchy, there are no problems, because the supervisor folder is present by default in an environment where the software is installed. Conversely, in the case of 3 level hierarchy, it will also be necessary to transfer the development folder.

In addition, the inheritance principle, if used to simply transfer the developments made by revalidation of the production folder, presents some perverse effects, in that the inheritance is immediate if a process is modified in the development folder… but differed for all the elements in the dictionary, which are not transferred except in the case or re-validation. There is thus a risk of having temporary incoherencies in the production folder, once work starts in the development folder.

This hierarchy is therefore only recommended in the following cases :

 the final client wants to develop their own customizations and that those need to be isolated from the production folder ; remembering in addition that developments carried out by an ADONIX partner will be made in the intermediate folder.

 in a vertical development environment and where wanting to use the production folders for the purposes of testing.

In all other cases, it is recommended to use a level hierarchy. It is necessary in this case, to use a test folder next to the production folder, if developments are to be carried out during use and to test them before they are implemented (by copy or patch in the production folder. The use of the patch function is often preferable : It is used in fact to create application "packages" from the development folder and to integrate them as a block in the production folder. Additionally, the version 130 integrates a new incremental patch creation function. In fact there is the possibility to create a patch that contains all that has been modified in a folder from a given date. This makes it possible to very easily isolate the developments and parameterization carried out between two deployment stages.

More information on this subject will be found in the documentation associated with the folder management.