SAND CDBMS Tools Reference Guide
NDL++ Functions: Syntax and Examples

Custom Library Functions

NDL++ allows users to define their own functions and store them in an external library file. By including a LIBRARY section in the load specification file, users may reference a custom library file and declare functions from the library, which can then be used in the NDL++ script. The library file must be compiled in C or C++.

For information about creating C/C++ run-time libraries and some sample code, refer to Appendix A: The User-Defined Function Library.

Declaring a Library and Functions

A custom library and its functions are declared in a LIBRARY section of the load specification file. The LIBRARY section(s) must appear before all other sections (TYPE, VAR, RECORD, and so on). Multiple LIBRARY sections may appear in the specification file, as each separate library file must have its own LIBRARY section. That is, there will be one LIBRARY section for each library declared in the script.

The LIBRARY section begins with the LIBRARY keyword, followed by whitespace, the @ symbol, and the name of the library file to be included, or the file path and name if the library file is not in the current execution directory. The rest of the LIBRARY section consists of a list of function declarations between braces { }.

A function declaration (or prototype) establishes the name of the function, the number and data type of arguments that the function receives, and the data type of the value that the function returns. A function declaration has the following form:

return-type function-name ( [arg-type1 [ {, arg-typeN }... ] ] )

where:

• return-type is the data type of the value returned by the function
• function-name is the name used to invoke the function

Important:
In the LIBRARY section declaration, the function name is case-sensitive: it must exactly match the function name defined in the library file. When used elsewhere in the specification script, the function name is not case-sensitive.

• The arg-type list consists of zero or more data type arguments.

Example

IMPORT @myflat.dat
{
LIBRARY @c:\work\bin\userlib.dll
{
    char StrCat ( char, char )
}
RECORD
{
    Field1 *,
    Field2 *,\r\n
}
users
{
    column1 StrCat ( Field1, Field2 )
}
}

In this sample script, a custom library called userlib.dll is referenced in the LIBRARY section. One function contained in the library, StrCat(), is declared in this section. Note that the library file may contain other functions that are not declared in the specification file; only those functions actually used in the script need to be declared. Here, the StrCat() function is used in the map specification section to concatenate Field1 and Field2 before assigning the result string to a column in the destination table.

Initializing a Library

The initialization of a library (if required) is performed in the INIT section of the load specification file. The INIT section must appear after the LIBRARY section(s) and before all other sections (TYPE, VAR, RECORD, and so on).

The INIT section begins with the INIT keyword and contains a list of one or more library (or LOOKUP function) initialization statements, all between braces { }.

The library initialization parameter has the following format:

LIBRARY @[file-path]filename ( initialization-value )

where:

• file-path is the directory path to the user-defined library file. If the library file is not in the current execution directory, the file path is required
• filename is the name of the library file
• initialization-value is the value passed to the library in order to initialize it.

Example

INIT
{
    LIBRARY @mylib1.dll ( 'in-string' )
    LIBRARY @mylib2.dll ( 'in-string' )
    LIBRARY @mylib3.dll ( 'in-string' )
}

Using the #INCLUDE Directive with Library Definitions

By placing the entire LIBRARY section in a text file, the same library can easily be referenced in multiple NDL scripts using the #INCLUDE directive. In this manner, if the content of the library changes, only the text file containing the LIBRARY section needs to be updated (unless a script uses a function that has been redefined or removed).

Example

The library definition from the previous example can be stored in a file called userlib.inc:

LIBRARY @c:\work\bin\userlib.dll
{
char StrCat ( char, char )
}

Multiple specification files can incorporate this information in the following way:

IMPORT @myflat.dat
{
#INCLUDE @c:\work\bin\userlib.inc
RECORD
{
    Field1 *,
    Field2 *,\r\n
}
users
{
    column1 StrCat ( Field1, Field2 )
}
}