Using Python functions as UDF() functions

Using the built-in UDF() (user-defined-) function you can call any Python modules/functions in formulas in GS-Base.
This can help you to significantly increase GS-Base functionality thanks to the large number of various Python modules and libraries including, for example, science, finance, graphics.

From GS-Base you can pass to Python functions any type of parameters: (double precision) numbers, text strings, ranges of field values as numeric arrays/matrices, automatically saved blocks of CSV data from field ranges.

GS-Base can accept from Python functions any type of data it supports in formulas: (double precision) numbers, text strings, numeric arrays/matrices, CSV data blocks and images/graphics/charts to be inserted in the LongText, Images/Files, Code binary fields.

The UDF() function:

UDF(module, function, type, parameter1, parameter2, ...)

module - Python module name with full path, for example "c:\my_modules\some_functions.py"
function - function name as it appear in the above module, for example "my_function"
type - an index (0-5) specifying what type of data GS-Base should expect from the Python procedure. Possible values are:
- 0 - a number
- 1 - a matrix/array of numbers
- 2 - a text string (up to 8192 characters)
- 3 - a string/block of CSV data (of any size) to be inserted in the LongText/Code field
- 5 - an image (binary data returned as standard Python "memoryview" binary data) to be inserted in the Images/Files field
Additionally, you can add to the "type" parameter the following flags:
32 - all ranges/arrays (of field) values passed from GS-Base to Python will be saved and pass to Python as blocks/strings of CSV data
64 - same as 32 except that CSV data is created and pass instead of an array only if there any non-numeric/text field values within that GS-Base field range.

If neither 32 nor 64 is used, if you specify a range as a parameter in the UDF() function, GS-Base will pass it as an array of numbers ignoring any text data. Rules used to save and parse such CSV data blocks are the same as for handling regular CSV files in GS-Base.

Python modules are plain text files with the "*.py" extension. Below is an example of such a file containing seven simple functions.

e:\example.py :


def function1():
   return 10

def function2(a, b):
  return a + b

def function3(text):
   return 'A new text with ' + text + ' inserted in the middle'

def function4(csvdata):
   return csvdata

def function5(csvFilePath):
   f = open(csvFilePath, 'rb')
   file_content = f.read()
   f.close()
   return file_content

def function6(imageFilePath):
   f = open(imageFilePath, 'rb')
   file_content = f.read()
   f.close()
   return bytearray(file_content)

In GS-Base the above functions can be use as follows:

1.UDF("e:\example.py", "function1", 0)

takes no arguments and returns 10
2. UDF("e:\example.py", "function2", 0, 10, 20)

returns the sum of two numbers
3. UDF("e:\example.py", "function3", 2, "a word")

takes a text string, inserts it in another string and returns the obtained new string to GS-Base.
4. UDF("e:\example.py", "function5", 3 + 32, fields(10, 100))

accepts from GS-Base a CSV data block (of fields 10 to 100) and returns it back to GS-Base.
If this formula is used with the "Insert > Generating Function" command, it can be used to populate binary LongText/Code fields sequentially in all records.
5. UDF("e:\example.py", "function6", 3, "e:\some_csv_file.csv")

loads a CSV file and returns its contents. It can be used in calculated formulas to insert the returned result in plain record text fields or such formulas can be used with the "Insert > Generating Function" command to populate binary LongText/Code fields sequentially in all records.
6. UDF("e:\example.py", "function7", 5, "e:\some_image.jpg")

returns a jpeg/png/gif/bmp/tiff image loaded from the specified file and inserts it in a binary field. Returning graphics is applicable to such formulas when they are used with the "Insert > Generating Function" command to populate binary LongText/Code fields sequentially in all records.