Back to Contents

Built-in Functions

Summary:

• What is a built-in function?
• List of built-in functions
• List of de-supported functions
• The key code table

See also: Utility Functions, Variables, Functions, Operators, Classes and Objects.

What is a built-in function?

A built-in function is a predefined function that is included in the runtime system or provided as a library function automatically linked to your programs. You do not have to link with any additional BDL library to create your programs. The built-in functions are part of the language.

Built-in functions are not operators. Some operators have the same syntax as functions, but these are real language operators that have a specific order of precedence. Operators can be used in different contexts according to the BDL grammar. See for example: YEAR(date), MONTH(date), DAY(date),WEEKDAY(date), MDY(integer,integer,integer) GET_FLDBUF(field), INFIELD(field), FIELD_TOUCHED(field)

See also Utility Functions.

List of built-in functions

List of de-supported built-in functions:

ARG_VAL( )

Purpose:

This function returns a command line argument by position.

Syntax:

Notes:

1. position is the argument position. 0 returns the name of the program, 1 returns the first argument.

Usage:

This function provides a mechanism for passing values to the program through the command line that invokes the program. You can design a program to expect or allow arguments after the name of the program in the command line.

Like all built-in functions, ARG_VAL() can be invoked from any program block. You can use it to pass values to MAIN, which cannot have formal arguments, but you are not restricted to calling ARG_VAL() from the MAIN statement. You can use the ARG_VAL() function to retrieve individual arguments during program execution. You can also use the NUM_ARGS() function to determine how many arguments follow the program name on the command line.

If position is greater than 0, ARG_VAL(position) returns the command-line argument used at a given position. The value of position must be between 0 and the value returned by NUM_ARGS(), the number of command-line arguments. The expression ARG_VAL(0) returns the name of the application program.

If the argument position is negative or greater than NUM_ARGS(), the method returns NULL.

See also: NUM_ARGS().

NUM_ARGS( )

Purpose:

This function returns the number of program arguments.

Syntax:

Usage:

See also: ARG_VAL().

SCR_LINE( )

Purpose:

This function returns the number of the current screen record in its screen array. 

Context:

1. During a DISPLAY ARRAY or INPUT ARRAY statement.

Syntax:

Usage:

The current record is the line of a screen array that is highlighted at the beginning of a BEFORE ROW or AFTER ROW clause.

Note that when using new graphical objects such as TABLEs, this function can return an invalid screen array line number, because the current row may not be visible if the user scrolls in the list with scrollbars. 

See also: ARR_CURR().

SET_COUNT( )

Purpose:

This function specifies the number of rows containing explicit data in a static array used by the next dialog.

Context:

1. Before a DISPLAY ARRAY or INPUT ARRAY statement.

Syntax:

Notes:

1. nbrows defines the number of explicit rows in the static array.

Usage:

When using a static array in an INPUT ARRAY (with WITHOUT DEFAULTS clause) or a DISPLAY ARRAY statement, you must specify the number of rows in the array which contain explicit data. In typical applications, these array elements contain the values retrieved from a SELECT statement controlled by a database cursor.

When using a static array, you can specify the number of rows with the SET_COUNT() function or with the COUNT attribute of INPUT ARRAY and DISPLAY ARRAY statements.

Note that you do not have to specify the number of rows when using a dynamic array. When using a dynamic array, the number of rows is defined by the getLength() method of the array object.

See also: ARR_CURR(), FGL_SET_ARR_CURR(). 

ARR_COUNT( )

Purpose:

This function returns the number of records entered in a program array during or after execution of the INPUT ARRAY statement.

Context:

1. Can be called at any place in the program, but should be limited to usage inside or after INPUT ARRAY or DISPLAY ARRAY blocks.

Syntax:

Notes:

1. Returns the current number of records that exist in the current array.
2. Typically used inside INPUT ARRAY blocks, can also be called in DISPLAY ARRAY.

Usage:

You can use ARR_COUNT() to determine the number of program records that are currently stored in a program array. In typical Genero BDL applications, these records correspond to values from the result set of retrieved database rows from the most recent query. By first calling the SET_COUNT() function or by using the COUNT attribute of INPUT ARRAY, you can set an upper limit on the value that ARR_COUNT() returns.

ARR_COUNT() returns a positive integer, corresponding to the index of the furthest record within the program array that the user accessed. Not all the rows counted by ARR_COUNT() necessarily contain data (for example, if the user presses the DOWN ARROW key more times than there are rows of data).

See also: INPUT ARRAY, DISPLAY ARRAY, ARR_CURR(). 

ARR_CURR( )

Purpose:

This function returns the current row in a DISPLAY ARRAY or INPUT ARRAY.

Context:

1. During a DISPLAY ARRAY or INPUT ARRAY statement.

Syntax:

Usage:

The ARR_CURR() function returns an integer value that identifies the current row of a list of rows in a INPUT ARRAY or DISPLAY ARRAY instruction. The first row is numbered 1.

You can pass ARR_CURR() as an argument when you call a function. In this way the function receives as its argument the current record of whatever array is referenced in the INPUT ARRAY or DISPLAY ARRAY statement.

The ARR_CURR() function can be used to force a FOR loop to begin beyond the first line of an array by setting a variable to ARR_CURR() and using that variable as the starting value for the FOR loop.

The built-in functions ARR_CURR() and SCR_LINE() can return different values if the program array is larger than the screen array.

See also: INPUT ARRAY, DISPLAY ARRAY, ARR_COUNT(), FGL_SET_ARR_CURR(), SCR_LINE(), DIALOG.getCurrentRow(). 

ERR_GET( )

Purpose:

This function returns the text corresponding to an error number.

Syntax:

Notes:

1. error-number is a runtime error or an Informix SQL error.

Usage:

The ERR_GET() function returns the error message corresponding to the number passed as parameter.

Note that IBM Informix SQL error numbers can only be supported if the program is connected to an Informix database. You may not want to use this function when programming an application the must run with different type of database servers.

See also: ERRORLOG(), STARTLOG(), ERR_QUIT(), ERR_PRINT(), Exceptions.

ERR_PRINT( )

Purpose:

This function prints in the error line the text corresponding to an error number.

Syntax:

Notes:

1. error-number is a runtime error or an Informix SQL error.

Usage:

The ERR_PRINT() function displays to the screen the error message corresponding to the number passed as parameter. The message will be displayed in the error line defined by the program.

Note that IBM Informix SQL error numbers can only be supported if the program is connected to an Informix database. You may not want to use this function when programming an application the must run with different type of database servers.

See also: ERRORLOG(), STARTLOG(), ERR_QUIT(), ERR_GET(), Exceptions.

ERR_QUIT( )

Purpose:

This function prints in the error line the text corresponding to an error number and terminates the program.

Syntax:

Notes:

1. error-number is a runtime error or an Informix SQL error.

Usage:

The ERR_QUIT() function prints the error message corresponding to the number passed as parameter. The message will be displayed in standard error stream and the the program will terminate.

Note that IBM Informix SQL error numbers can only be supported if the program is connected to an Informix database. You may not want to use this function when programming an application the must run with different type of database servers.

See also: ERRORLOG(), STARTLOG(), ERR_QUIT(), ERR_GET(), Exceptions.

ERRORLOG( )

Purpose:

This function copies the string passed as parameter into the error log file.

Syntax:

Notes:

1. text is the character string to be inserted in the error log file.

Usage:

The ERRORLOG() function writes the passed string in the current error log file defined by a call to the STARTLOG() function.

You can use this function to identify errors in programs and to customize error handling. The error log functions can also be used to trace the way a program is used to improve it, record work habits or help to detect attempts to breach security.

See also: STARTLOG(), Exceptions.

SHOWHELP( )

Purpose:

This function displays a runtime help text.

Syntax:

Notes:

1. help-number is the help message number in the current help file.

Usage:

The SHOWHELP() function displays a runtime help message, corresponding to its specified argument, from the current help file.

In GUI mode, the help text will be displayed in a new popup window.

See also: OPTIONS, Message Files.

STARTLOG( )

Purpose:

This function initializes error logging and opens the error log file passed as the parameter.

Context:

1. At the beginning of the program.

Syntax:

Notes:

1. filename is the name of the error log file.
2. Runtime errors are automatically reported.
3. You can insert error records manually with the ERRORLOG() function.

Usage:

Call STARTLOG() in the MAIN program block to open or create an error log file. After STARTLOG() has been invoked, a record of every subsequent error that occurs during the execution of your program is written in the error log file. If you need to report specific application errors, use the ERRORLOG() function to make an entry in the error log file.

The default format of an error record consists of the date, time, source-module name and line number, error number, and error message. If you invoke the STARTLOG() function, the format of the error records appended to the error log file after each subsequent error are as follows:

Date: 03/06/99 Time: 12:20:20
Program error at "stock_one.4gl", line number 89.
SQL statement error number -239.
Could not insert new row - duplicate value in a UNIQUE INDEX column.
SYSTEM error number -100
ISAM error: duplicate value for a record with unique key.

The STARTLOG() and ERRORLOG() functions can be used for instrumenting a program, to track how the program is used. This use is not only valuable for improving the program but also for recording work habits and detecting attempts to breach security.

If the argument of STARTLOG() is not the name of an existing file, STARTLOG() creates one. If the file already exists, STARTLOG() opens it and positions the file pointer so that subsequent error messages can be appended to this file. The following program fragment invokes STARTLOG(), specifying the name of the error log file in a quoted string that includes a pathname and a file extension. The function definition includes a call to the built-in ERRORLOG() function, which adds a message to the error log file:

01   CALL STARTLOG("/var/myapp/logs/error-" || fgl_getpid() || ".log")
02   ...
03   CALL ERRORLOG("The current user is not allowed to perform order validation")

See also: ERRORLOG(), Exceptions.

FGL_BUFFERTOUCHED( )

Purpose:

This function returns TRUE if the input buffer was modified in the current field.

Context:

1. In AFTER FIELD, AFTER INPUT, AFTER CONSTRUCT, ON KEY, ON ACTION blocks.

Syntax:

Usage:

Note that this function is not equivalent to FIELD_TOUCHED(): The flag returned by FGL_BUFFERTOUCHED() is reset when you enter a new field, while FIELD_TOUCHED() returns always TRUE for a field that was modified during the interactive instruction.

See also: FGL_DIALOG_SETBUFFER(), FGL_DIALOG_GETBUFFER().

FGL_DB_DRIVER_TYPE( )

Purpose:

Returns the 3-letter identifier/code of the current database driver.

Syntax:

Usage:

This function can be called after connecting to a database server with the CONNECT or DATABASE instructions, in order to identify the type of the target database with the driver type. Returned value is the 3-letter driver code. See Connections page for more details about the list of database driver codes.

The function returns NULL if there is no current database driver (i.e. if database connection is not yet established).

FGL_DECIMAL_TRUNCATE( )

Purpose:

Returns a decimal truncated to the precision passed as parameter.

Syntax:

Notes:

1. value is the decimal to be converted.
2. decimals defines the number of digits after the decimal point.

Usage:

This function truncates the decimal to the number of decimal digits specified. The value is not rounded, it is just truncated. For example, when truncating 12.345 to 2 decimal digits, the result will be 12.34, not 12.35.

FGL_DECIMAL_SQRT( )

Purpose:

Computes the square root of the decimal passed as parameter.

Syntax:

Notes:

1. value is the decimal to be computed.

FGL_DECIMAL_EXP( )

Purpose:

Returns the value of Euler's constant (e) raised to the power of the decimal passed as parameter.

Syntax:

Notes:

1. value is the decimal to be computed.

FGL_DECIMAL_LOGN( )

Purpose:

Returns the natural logarithm of the decimal passed as parameter.

Syntax:

Notes:

1. value is the decimal to be computed.

FGL_DECIMAL_POWER( )

Purpose:

Raises decimal to the power of the real exponent.

Syntax:

Notes:

1. base is the decimal to be raise to the power of exp.
2. exp is the exponent.

Usage:

Note that unlike the ** operator, the FGL_DECIMAL_POWER() supports real numbers for the exponent.

FGL_DIALOG_GETBUFFER( )

Purpose:

This function returns the text of the input buffer of the current field.

Context:

1. In INPUT , INPUT ARRAY, CONSTRUCT instructions.

Syntax:

Usage:

See also: FGL_DIALOG_SETBUFFER(), FGL_BUFFERTOUCHED(), GET_FLDBUF().

FGL_DIALOG_SETBUFFER( )

Purpose:

This function sets the input buffer of the current field, and assigns corresponding program variable when using UNBUFFERED mode.

Context:

1. In INPUT , INPUT ARRAY, CONSTRUCT instructions.

Syntax:

Notes:

1. value is the text to set in the current input buffer.

Usage:

With the default buffered input mode, this function modifies the input buffer of the current field; the corresponding input variable is not assigned. It makes no sense to call this function in BEFORE FIELD blocks of INPUT and INPUT ARRAY. However, if the statement is using the UNBUFFERED mode, the function will set both the field buffer and the program variable. If the string set by the function does not represent a valid value that can be stored by the program variable, the buffer and the variable will be set to NULL.

Note that this function sets the 'touched' flag of the current form field, and the 'touched' flag of the dialog. Therefore, both FIELD_TOUCHED() and FGL_BUFFERTOUCHED() would return TRUE if you call this function.

See also: FGL_DIALOG_GETBUFFER(), FGL_BUFFERTOUCHED(), GET_FLDBUF().

FGL_DIALOG_GETFIELDNAME( )

Purpose:

This function returns the name of the current input field.

Context:

1. In INPUT , INPUT ARRAY or CONSTRUCT instructions.

Syntax:

Usage:

Note that only the column part of the field name is returned (screen record name is omitted).

See also: FGL_DIALOG_INFIELD().

FGL_DIALOG_INFIELD( )

Purpose:

This function checks for the current input field.

Context:

1. In INPUT , INPUT ARRAY or CONSTRUCT instructions.

Syntax:

Notes:

1. field-name is the name if the form field.

Usage:

The FGL_DIALOG_INFIELD() function returns TRUE if the field name passed as the parameter is the current input field. This function is the equivalent of the INFIELD() operator, except that the function takes a string expression as parameter, while the INFIELD() operator expects a hard-coded form field name.

FGL_DIALOG_SETCURSOR( )

Purpose:

This function sets the position of the input cursor in the current field.

Context:

1. In interactive instructions control blocks, when staying in the current field.

Syntax:

Notes:

1. index is the character position in the text.

Usage:

This function has only an effect when staying in the current field, it should not be called in an AFTER FIELD or AFTER ROW for example. Note that you can also use FGL_DIALOG_SETSELECTION() to select a piece of text in a field.

See also: FGL_GETCURSOR(), FGL_DIALOG_SETSELECTION().

FGL_DIALOG_SETFIELDORDER( )

Purpose:

This function enables or disables field order constraint.

Context:

1. At the beginning of the program or around INPUT instructions.

Syntax:

Notes:

1. When active is TRUE, the field order is constrained.
2. When active is FALSE, the field order is not constrained.

Usage:

Typical BDL applications control user input with BEFORE FIELD and AFTER FIELD blocks. In many cases the field order and  the sequential execution of AFTER FIELD blocks is important in order to validate the data entered by the user. But with graphical front ends you can use the mouse to move to a field. By default the runtime system executes all BEFORE FIELD and AFTER FIELD blocks of the fields used by the interactive instruction, from the origin field to the target field selected by mouse click. If needed, you can force the runtime system to ignore all intermediate field triggers, by calling this function with a FALSE attribute.

FGL_DIALOG_SETCURRLINE( )

Purpose:

This function moves to a specific row in a record list.

Context:

1. During a DISPLAY ARRAY or INPUT ARRAY instruction, inside BEFORE DISPLAY / BEFORE INPUT or ON ACTION / ON KEY blocks only.

Syntax:

Notes:

1. line is the line number in the screen array.
2. row is the row number is the array variable.

Usage:

Moves to the row / screen line specified. See FGL_SET_ARR_CURR() for more details.

Note that the line parameter is ignored in GUI mode.

FGL_SCR_SIZE( )

Purpose:

This function returns the size of the specified screen array in the current form.

Syntax:

Notes:

1. screen-array is the name of a screen-array in the current displayed form.

Usage:

This function is typically used with traditional text mode forms having screen arrays with a constant size, to display data in screen array rows with the DISPLAY TO instruction.

For modern GUI applications, think of using the UNBUFFERED mode in dialogs, to get automatic form field synchronization with program variables.

Error -1108 will be raised if the passed screen-array does not exits in the current form, and error -1114 is returned if no form is currently displayed.

FGL_SET_ARR_CURR( )

Purpose:

This function moves to a specific row in a record list.

Context:

1. During a DISPLAY ARRAY or INPUT ARRAY instruction, inside BEFORE DISPLAY / BEFORE INPUT or ON ACTION / ON KEY blocks only.

Syntax:

Notes:

1. row is the row number is the array variable.

Usage:

Note that control blocks like BEFORE ROW and field/row validation in INPUT ARRAY are performed, as if the user moved to another row, except when the function is called in BEFORE DISPLAY or BEFORE INPUT.

When a new row is reached by using with this function, the first editable field gets the focus.

Note that an alternative to the FGL_SET_ARR_CURR() function is the ui.Dialog.setCurrentRow() method; However, the dialog class method will be used in a different programming pattern, as it does not trigger the control blocks like the built-in function.

FGL_SETENV( )

Purpose:

This function sets the value of an environment variable.

Syntax:

Notes:

1. variable is the name of the environment variable.
2. value is the value to be set.

Usage:

The FGL_SETENV() function sets or modifies the value of an environment variable.

Note that there is a little difference between Windows and UNIX platforms when passing a NULL as the value parameter: On Windows, the environment variable is removed, while on UNIX, the environment variable gets an empty value (i.e. it is not removed from the environment).

Warning: Use this function at your own risk: You may experience unexpected results if you change environment variables that are already used by the current program - for example, when you are connected to INFORMIX and you change the INFORMIXDIR environment variable.

See also: FGL_GETENV()

FGL_DRAWBOX( )

Purpose:

This function draws a rectangle in the current window.

Syntax:

Notes:

1. height is the height of the rectangle.
2. width is the width of the rectangle.
3. line is the horizontal coordinate of the upper side of the rectangle.
4. column is the vertical coordinate of the left side of the rectangle.
5. color is the color number (ignored).

Usage:

The FGL_DRAWBOX() function draws a rectangle based on the character terminal coordinates in the current open window.

Dimensions and coordinates are specified in grid cells unit (i.e. characters).

This function is provided for backward compatibility. A call to this function will be ignored if the current window is not SCREEN based. The function is supported to draw rectangles in text mode applications.

See also: FGL_DRAWLINE(). 

FGL_DRAWLINE( )

Purpose:

This function draws a line in the current window.

Syntax:

Notes:

1. line is the horizontal coordinate of the upper side of the rectangle.
2. column is the vertical coordinate of the left side of the rectangle.
3. width is the width of the line.
4. type (ignored).
5. color is the color number (ignored).

Usage:

The FGL_DRAWLINE() function draws a line based on the character terminal coordinates in the current open window.

Dimensions and coordinates are specified in grid cells unit (i.e. characters).

This function is provided for backward compatibility. A call to this function will be ignored if the current window is not SCREEN based. The function is supported to draw lines in text mode applications.

See also: FGL_DRAWBOX(). 

FGL_LASTKEY( )

Purpose:

This function returns the key code corresponding to the logical key that the user most recently typed in the form.

Syntax:

Notes:

1. The function returns NULL if no key has been pressed.

Usage:

The FGL_LASTKEY() function returns a numeric code corresponding to the user's last keystroke before the function was called. For example, if the last key that the user pressed was a lowercase s, the function returns the code 115 (i.e. the ASCII character set code).

Note that the value of FGL_LASTKEY() is undefined in a MENU statement.

It is not required to know the specific key codes returned by FGL_LASTKEY(): The FGL_KEYVAL() function can be used to compare the key code of the last key pressed. The FGL_KEYVAL() function lets you compare the last key pressed with a logical of physical key. For example, you do not need to know the physical key defined to validate a dialog, you can use the logical name "accept" instead. For a complete list of key codes and logical key names, see the Key code table.

Pay attention to the fact that this function is provided for backward compatibility. The Genero BDL Abstract User Interface protocol is based on logical events, not only key events. For example, in GUI mode, when selecting a new row with the mouse in a table, there is no key press as when moving in a static screen array in TUI mode. However, Genero BDL tries to emulate as much as possible keystrokes from non-keystroke events. 

See also: FGL_KEYVAL(), key code.

FGL_KEYVAL( )

Purpose:

This function returns the key code of a logical or physical key.

Syntax:

Notes:

1. string can be a single character, a digit, a printable symbol like @, #, $ or a special keyword such as ACCEPT.

Usage:

FGL_KEYVAL() can be used in form-related statements to examine a value returned by the FGL_LASTKEY() and FGL_GETKEY() functions.

The function returns NULL if the parameter does not correspond to a valid key.

If you specify a single character, FGL_KEYVAL() considers the case. In all other instances, the function ignores the case of its argument, which can be uppercase or lowercase letters.

To determine whether the user has performed an action, such as inserting a row, specify the logical name of the action (such as INSERT) rather than the name of the physical key (such as F1). For example, the logical name of the Accept action is ACCEPT, while the default physical key is ESCAPE. To test if the key most recently pressed by the user corresponds to the Accept action, specify FGL_KEYVAL("ACCEPT") rather than FGL_KEYVAL("ESCAPE") or FGL_KEYVAL("ESC"). Otherwise, if a key other than ESCAPE is set as the Accept key and the user presses that key, FGL_LASTKEY() does not return a code equal to FGL_KEYVAL("ESCAPE").

Note that this function is provided for backward compatibility especially for TUI mode applications. FGL_KEYVAL() is well supported in text mode, but this function can only be emulated in GUI mode, because the front-ends communicate with the runtime system with other events as keystrokes.

See also: FGL_LASTKEY(), FGL_GETKEY().

FGL_REPORT_PRINT_BINARY_FILE( )

Purpose:

This function prints a file containing binary data during a report.

Context:

1. In a REPORT routine.

Syntax:

Notes:

1. filename is the name of the binary file.

Usage:

This function prints a file containing binary data during a report.

This function is provided for backward compatibility.

FGL_REPORT_SET_DOCUMENT_HANDLER( )

Purpose:

This function redirects the next report to an XML document handler.

Context:

1. Before / After the execution of a REPORT.

Syntax:

Notes:

1. handler is the document handler variable.

Usage:

This function attaches the specified XML document handler to the next executed report.

This function is provided for backward compatibility, you should use the TO XML HANDLER of START REPORT instead.

FGL_DIALOG_GETCURSOR( ) / FGL_GETCURSOR()

Purpose:

This function returns the position of the edit cursor in the current field.

Context:

1. In interactive instructions.

Syntax:

Notes:

1. index is the character position in the text.

Usage:

The FGL_DIALOG_GETCURSOR() function can be used in conjunction with FGL_DIALOG_GETSELECTIONEND() to get the position of the edit cursor and the piece of text that is selected in the current field.

See also: FGL_DIALOG_GETSELECTIONEND(), FGL_DIALOG_SETCURSOR(), FGL_DIALOG_SETSELECTION()

FGL_GETWIN_HEIGHT( )

Purpose:

This function returns the number of rows of the current window.

Syntax:

Usage:

The FGL_GETWIN_HEIGHT() function returns the height of the current window, in character units.

This function is provided for text mode applications, in GUI mode, windows are resizable and thus their height is variable.

See also: FGL_GETWIN_WIDTH().

FGL_GETWIN_WIDTH( )

Purpose:

This function returns the width of the current window as a number of columns.

Context:

1. At any place in the program.

Syntax:

Usage:

The FGL_GETWIN_WIDTH() function returns the width of the current window, in character units.

This function is provided for text mode applications, in GUI mode, windows are resizable and thus their width is variable.

See also: FGL_GETWIN_WIDTH().

FGL_GETWIN_X( )

Purpose:

This function returns the horizontal position of the current window.

Syntax:

Usage:

The FGL_GETWIN_X() function returns the horizontal coordinate of the top/left corner of the current window.

This function is provided for text mode applications, in GUI mode, windows are movable and thus their position is variable.

See also: FGL_GETWIN_Y().

FGL_GETWIN_Y( )

Purpose:

This function returns the vertical position of the current window.

Context:

1. At any place in the program.

Syntax:

Usage:

The FGL_GETWIN_Y() function returns the vertical coordinate of the top/left corner of the current window.

This function is provided for text mode applications, in GUI mode, windows are movable and thus their position is variable.

See also: FGL_GETWIN_X().

LENGTH( )

Purpose:

This function returns the number of bytes of the expression passed as parameter.

Syntax:

Notes:

1. expression is any valid expression.

Usage:

The LENGTH() function counts the number of bytes of a string. Note that the function counts bytes, not characters. This is important in a multi-byte environment. Trailing blanks are not counted in the length of the string. If the parameter is NULL, the function returns zero.

Most database servers support an equivalent scalar function in the SQL language, but the result may be different from the Genero BDL built-in function. For example, Oracle's LENGTH() function returns NULL when the string is empty. 

See also: FGL_WIDTH().

FGL_GETVERSION( )

Purpose:

This function returns the build number of the runtime system.

Syntax:

Usage:

The FGL_GETVERSION() function returns the internal build number of the Genero version.

Pay attention to the fact that this function is provided for debugging only; do not write business code dependent on the build number. The format of the build number returned by this function is subject of change in future versions.

FGL_GETHELP( )

Purpose:

Returns the help text according to its identifier by reading the current help file.

Context:

1. At any place in the program, after the definition of the current help file (OPTIONS HELP FILE).

Syntax:

Notes:

1. id is the help text identifier.

Usage:

The FGL_GETHELP() function returns the text corresponding the the help message number passed as parameter. The text is read from the current help file. The current help file is defined by the OPTIONS HELP FILE instruction.

FGL_GETPID( )

Purpose:

This function returns the system process identifier.

Syntax:

Notes:

1. The process identifier is provided by the operating system; it is normally unique.

Usage:

The FGL_GETPID() function returns the current process identifier.

See also: FGL_SYSTEM().

FGL_DIALOG_GETBUFFERSTART( )

Purpose:

This function returns the row offset of the page to feed a paged display array.

Context:

1. In the ON FILL BUFFER block of a DISPLAY ARRAY.

Syntax:

Usage:

The FGL_DIALOG_GETBUFFERSTART() function returns the record list offset to be used to fill a page of a DISPLAY ARRAY running in paged mode.

Note that this function must be called in the context of the ON FILL BUFFER trigger. The returned value is undefined if the function is used outside this trigger.

FGL_DIALOG_GETBUFFERLENGTH( )

Purpose:

This function returns the number of rows of the page to feed a paged display array.

Context:

1. In the ON FILL BUFFER block of a DISPLAY ARRAY.

Syntax:

Usage:

The FGL_DIALOG_GETBUFFERLENGTH() function returns the number of rows to be provided by the program to fill a page of a DISPLAY ARRAY running in paged mode.

Note that this function must be called in the context of the ON FILL BUFFER trigger. The returned value is undefined if the function is used outside this trigger.

FGL_PUTFILE

Purpose:

Transfers a file from the application server machine to the front end workstation.

Syntax:

Notes:

1. src contains the name of the source file to send.
2. dst contains the name of the file to write on the front end.

Usage:

The FGL_PUTFILE() function downloads a file from the application server disk where fglrun is executed to the front-end workstation disk.

Warning: Using this function can result in a security hole if you allow the end user to specify the file paths without control. There is not limitation on the file content or file paths: If the user executing the application on the server side is allowed to read critical server files, the program could transfer these files on the client workstation. On the other hand, critical files can be written on the client workstation. It is in the hands of the programmer to implement file path and/or file content restrictions in the programs using FGL_PUTFILE().

See also: FGL_GETFILE().

FGL_GETFILE

Purpose:

Transfers a file from the front end workstation to the application server machine.

Syntax:

Notes:

1. src contains the name of the source file to retrieve from the front end workstation.
2. dst contains the name of the file to write on the server side.

Usage:

The FGL_GETFILE() function uploads a file from the front-end workstation disk to the application server disk where fglrun is executed.

Warning: Using this function can result in a security hole if you allow the end user to specify the file paths without control. There is not limitation on the file content or file paths: If the user executing the application on the server side is allowed to write critical server files, the program could transfer files from the client workstation and overwrite critical server files. On the other hand, critical files can be read from the client workstation and copied on the application server. It is in the hands of the programmer to implement file path and/or file content restrictions in the programs using FGL_GETFILE().

See also: FGL_PUTFILE().

FGL_GETENV( )

Purpose:

This function returns the value of the environment variable having the name you specify as the argument.

Syntax:

Notes:

1. variable is the name of the environment variable.

Usage:

The argument of FGL_GETENV() must be the name of an environment variable. If the requested value exists in the current user environment, the function returns it as a character string and then returns control of execution to the calling context.

If the specified environment variable is not defined, the function returns a NULL value. If the environment variable is defined but does not have a value assigned to it, the function returns blank spaces.

If the returned value can be a long character string, be sure to declare the receiving variable with sufficient size to store the character value returned by the function. Otherwise, the value will be truncated.

See also: FGL_SETENV()

FGL_GETKEY( )

Purpose:

Waits for a keystroke and returns the key code corresponding to the pressed physical key.

Syntax:

Notes:

1. keynum is the integer key code of the pressed key, equivalent of FGL_KEYVAL().

Usage:

Unlike FGL_LASTKEY(), which can return a value indicating the logical effect of whatever key the user pressed, FGL_GETKEY() returns an integer representing the key code of the physical key that the user pressed. The FGL_GETKEY() function recognizes the same codes for keys that the FGL_KEYVAL() function returns. Unlike FGL_KEYVAL() , which can only return keystrokes that are entered during dialogs, FGL_GETKEY() can be called outside a dialog context.

This function is provided for backward compatibility and works only in TUI mode.

See also: FGL_KEYVAL().

FGL_GETKEYLABEL( )

Purpose:

This function returns the default label associated to a key.

Syntax:

Notes:

1. keyname is the logical name of a key such as F11 or DELETE, INSERT, CANCEL.

Usage:

The FGL_GETKEYLABEL() function returns the default label defined for the function or control key passed as parameter.

Note that this function returns the default key labels defined for the all dialogs. There are different levels of key label definitions, as described in the Setting Key Labels section.

This function is provided for backward compatibility, you should use Action Defaults to define action view texts.

See also: FGL_SETKEYLABEL(), FGL_DIALOG_GETKEYLABEL().

FGL_SETKEYLABEL( )

Purpose:

This function sets the default label associated to a key.

Syntax:

Notes:

1. keyname is the logical name of a key such as F11 or DELETE, INSERT, CANCEL.
2. label is the text associated to the key.

Usage:

Note that this function defines the default key labels for all dialogs. There are different levels of key label definitions, as described in the Setting Key Labels section.

This function is provided for backward compatibility, you should use Action Defaults to define action view texts.

See also: FGL_SETKEYLABEL(), FGL_DIALOG_SETKEYLABEL().

FGL_DIALOG_GETKEYLABEL( )

Purpose:

This function returns the label associated to a key for the current interactive instruction.

Syntax:

Notes:

1. keyname is the logical name of a key such as F11 or DELETE, INSERT, CANCEL.

Usage:

The FGL_DIALOG_GETKEYLABEL() function returns the label defined for the function or control key passed as parameter, for the current interactive instruction.

Note that this function returns the key labels defined for the current dialog. There are different levels of key label definitions, as described in the Setting Key Labels section.

This function is provided for backward compatibility, you should use Action Defaults to define action view texts.

See also: FGL_SETKEYLABEL(), FGL_DIALOG_SETKEYLABEL().

FGL_DIALOG_GETSELECTIONEND( )

Purpose:

This function returns position of the last selected character in the current field.

Syntax:

Notes:

1. position is the position of the last selected character in the current field text.

Usage:

The FGL_DIALOG_GETSELECTIONEND() function returns the edit cursor position of the last selected character in the text of the current field.

The function returns zero if the complete text is selected.

Note that the edit cursor position returned by FGL_DIALOG_GETCURSOR() will be lower as the position returned by FGL_DIALOG_GETSELECTIONEND() if the text has been selected backwards.

See also: FGL_DIALOG_GETCURSOR(), FGL_DIALOG_SETSELECTION().

FGL_DIALOG_SETKEYLABEL( )

Purpose:

This function sets the label associated to a key for the current interactive instruction.

Syntax:

Notes:

1. keyname is the logical name of a key such as F11 or DELETE, INSERT, CANCEL.
2. label is the text associated to the key.

Usage:

Note that this function defines the key labels for the current dialog. There are different levels of key label definitions, as described in the Setting Key Labels section.

This function is provided for backward compatibility, you should use Action Defaults to define action view texts.

See also: FGL_SETKEYLABEL(), FGL_DIALOG_GETKEYLABEL().

FGL_DIALOG_SETSELECTION( )

Purpose:

This function selects the text in the current field.

Context:

1. In interactive instructions control blocks, when staying in the current field.

Syntax:

Notes:

1. cursor defines the edit cursor position. 
2. end defines the selection end position.

Usage:

Note that cursor can be lower, greater or equal to end.

This function has only an effect when staying in the current field, it should not be called in an AFTER FIELD or AFTER ROW for example.

See also: FGL_DIALOG_SETCURSOR(), FGL_DIALOG_GETCURSOR(), FGL_DIALOG_GETSELECTIONEND().

FGL_SETSIZE( )

Purpose:

This function sets the size of the main application window.

Syntax:

Notes:

1. height is the number of lines of the window.
2. width is the number of columns of the window.

Usage:

This function defines the size of the main window when using the traditional GUI mode.

See also: FGL_SETTITLE(), ui.Interface.setSize().

FGL_SETTITLE( )

Purpose:

This function sets the title of the current application window.

Syntax:

Notes:

1. label is the text of the title. 

Usage:

The FGL_SETTITLE() function defines the title of the current window, as well as the default title for new created windows.

This function is provided for backward compatibility, with Genero BDL you can define the title of the window with the TEXT attribute of a LAYOUT section.

See also: FGL_SETSIZE().

FGL_SYSTEM( )

Purpose:

This function runs a command on the application server.

Syntax:

Notes:

1. command is the command line to be executed on the server. 

Usage:

The FGL_SYSTEM() function suspends the execution of the BDL program and executes the command passed as parameter on the application server. The command is executed in a new shell and the program is suspended until the command terminates.

When running the BDL program in text mode, the terminal is switched to line mode before executing the command passed to the FGL_SYSTEM() function.

Note that this function is provided for backward compatibility. In older versions, the function could raise a terminal emulator on the front-end to show the command output on the workstation. This feature is no longer supported by Genero BDL.

FGL_WIDTH()

Purpose:

This function returns the number of columns needed to represent the printed version of the expression.

Syntax:

Notes:

1. expression is any valid expression.

Usage:

The FGL_WIDTH() function returns the number of columns that will be used if you display expression on a text terminal. The number of columns used by a character depends on the glyph (i.e. the graphical symbol used to draw the character on the screen). For example, an ASCII character like A uses one column, while one Chinese character uses 2 columns (i.e. on a text terminal, the size of one Chinese character takes the same size as AB).

Trailing blanks are counted in the length of the string.

If the parameter is NULL, the function returns zero.

See also: LENGTH().

FGL_WINDOW_GETOPTION( )

Purpose:

This function returns attributes of the current window.

Syntax:

Notes:

1. attribute is the name of a window attribute. This can be one of name, x, y, width, height, formline, messageline.

Usage:

The FGL_WINDOW_GETOPTION() function returns the value of the window attribute passed as parameter.

This function is provided for backward compatibility, you should not use have to use this function in modern GUI applications.

FGL_GETRESOURCE( )

Purpose:

This function returns the value of an FGLPROFILE entry.

Syntax:

Notes:

1. name is the FGLPROFILE entry name to be read.

Usage:

The FGL_GETRESOURCE() function reads the FGLPROFILE file(s) and returns the value defined for the entry passed as parameter. If the entry does not exist in the configuration file, the function returns NULL.

Note that FGLPROFILE entry names are not case sensitive.

See also FGLPROFILE definition.

DOWNSHIFT( )

Purpose:

This function returns returns a string value in which all uppercase characters in its argument are converted to lowercase.

Syntax:

Notes:

1. source is the character string to convert to lowercase letters.

Usage:

The DOWNSHIFT() function returns returns a string value in which all uppercase characters in its argument are converted to lowercase. The character conversion depends on locale settings (the LC_CTYPE environment variable). Non-alphabetic or lowercase characters are not altered.

See also: UPSHIFT().

UPSHIFT( )

Purpose:

Converts a string to uppercase.

Syntax:

Notes:

1. source is the character string to convert to uppercase letters.

Usage:

The UPSHIFT() function returns a string value in which all lowercase characters in its argument are converted to uppercase. The character conversion depends on locale settings (the LC_CTYPE environment variable). Non-alphabetic or uppercase characters are not altered.

See also: DOWNSHIFT().

The key code table

The next table lists internal key codes. Avoid hard-coding these numbers in your sources; otherwise your 4gl source will not be compatible with future versions of Genero BDL. Always use the FGL_KEYVAL(keyname) function instead.