3GL Program Rules and Guidelines

The following rules and guidelines should be observed when coding User Defined Built-In Functions:

• Do not prefix any variable or #define value with X_, V_ or U_.

• Avoid using variable or #define names that conflict with any of the names and types defined in X_GLODEF.H , X_GLOUSR.H or X_BIF000.H.

• All U_BIFnnn.DLL's must reside in the ....\x_lansa\execute directory at the time they are to be executed.

• Use the Visual LANSA type definition variables X_SHORT, X_LONG, X_DOUBLE, X_CHAR and X_VCHAR to define working storage in your function whenever possible. You may also use X_PSHORT, X_PLONG, X_PDOUBLE, X_PCHAR and X_PVCHAR as pointer declarations to the same types.

• Use the VISUAL LANSA variable prefixes whenever possible. For example:

s is the prefix for X_SHORT

l is the prefix for X_LONG

d is the prefix for X_DOUBLE

c is the prefix for X_CHAR

vch is the prefix for X_VCHAR

p is the prefix for a pointer

a is the prefix for an array

Prefixes can accumulate, so "apsOperation" indicates that nominal variable "Operation" is an array of pointers to X_SHORTs. Similarly pvchName indicates that this is a pointer to an X_VCHAR variable that contains a "Name".

 

• Use the U_BIF macros whenever possible to retrieve and return Built-In Function argument variables. This will go a long way towards insulating your application from future changes to the VISUAL LANSA code generation techniques.

• Use one Built-In Function per C source file and one per DLL.
  
  This rule will making porting of your code to other platforms much easier. Multi-entry point DLLs (or shared objects) are much harder to address under some Linux systems, so avoid hitting upon this problem later when you come to port your Built-In Functions.

• Most user defined Built-In Functions reference various .H header files shipped with Visual LANSA. Do not change these files as they are replaced every time a new version of VISUAL LANSA is installed and all your changes will be lost.

• A user defined Built-In Function has the following arguments:

struct X_IDS *pX_Ids,
struct X_PRO *pX_Pro,
struct X_FUN *pX_Fun,
struct X_BIF *pX_Bif,
struct X_FLD X_Fld[],
struct X_LIST X_List[],
X_SHORT sInCount,
X_SHORT sInVec[],
X_SHORT sRetCount,
X_SHORT sRetVec[]
Modification of storage pointed to by any of these arguments, other than by U_BIF macros, may result in unpredictable results and application failure. Do not modify storage outside the direct scope of your function other than by using the U_BIF macros. Failure to observe this rule may lead to loss of integrity in your application and future compatibility problems.