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: Variables, Functions, Operators, Built-in Classes.

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.

Warnings:

1. Do not confuse built-in functions with SQL aggregate functions like:
   • AVG( )
   • MAX( )
   • MIN( )
   • SUM( )
2. Do not confuse built-in functions with 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)

List of built-in functions

List of de-supported functions:

ARG_VAL( )

Purpose:

This function returns a command line argument by position.

Context:

1. At any place in the program.

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.

See also: NUM_ARGS().

NUM_ARGS( )

Purpose:

This function returns the number of program arguments.

Context:

1. At any place in the program.

Syntax:

Notes:

1. returns 0 if no arguments are passed to the program.

See also: ARG_VAL().

ORD( )

Purpose:

This function accepts as its argument a character expression and returns the integer value of the first byte of that argument.

Context:

1. At any place in the program.

Syntax:

Notes:

1. source is a string expression.
2. This function is case-sensitive.
3. Only the first byte of the argument is evaluated.
4. Returns NULL if the argument passed is not valid.
5. For a default (U.S. English) locale, this function is the logical inverse of the ASCII() operator.

See also: FGL_KEYVAL(), ASCII().

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:

Notes:

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

Warnings:

1. When using new graphical objects such as TABLEs, this functions 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 records that contain data in a static array.

Context:

1. Before a DISPLAY ARRAY or INPUT ARRAY statement.

Syntax:

Notes:

1. nbrows defines the number of rows in the static array.
2. Using this function is equivalent to the COUNT attribute of INPUT ARRAY and DISPLAY ARRAY statements.

Usage:

When using a static array in an INPUT ARRAY (with WITHOUT DEFAULTS clause) or a DISPLAY ARRAY statement, you must specify the total number of records in the array. In typical applications, these records contain the values in the retrieved rows that a SELECT statement returned from a database cursor. You specify the number of rows with the SET_COUNT() function or with the COUNT attribute of INPUT ARRAY and DISPLAY ARRAY statements.

Warning: 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 use inside or after INPUT ARRAY blocks.

Syntax:

Notes:

1. Returns the current number of records that exist in the current array.
2. Typically used inside INPUT ARRAY blocks.

Usage:

You can use ARR_COUNT() to determine the number of program records that are currently stored in a program array. In typical BDL applications, these records correspond to values from 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, 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(). 

ERR_GET( )

Purpose:

This function returns the text corresponding to an error number.

Context:

1. At any place in the program.

Syntax:

Notes:

1. error-number is a runtime error or an Informix SQL error.
2. For development only.

Warnings:

1. Informix SQL error numbers can only be supported if the program is connected to an Informix database. 

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.

Context:

1. At any place in the program.

Syntax:

Notes:

1. error-number is a runtime error or an Informix SQL error.
2. For development only.

Warnings:

1. Informix SQL error numbers can only be supported if the program is connected to an Informix database.

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.

Context:

1. At any place in the program.

Syntax:

Notes:

1. error-number is a runtime error or an Informix SQL error.
2. For development only.

Warnings:

1. Informix SQL error numbers can only be supported if the program is connected to an Informix database. 

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

ERRORLOG( )

Purpose:

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

Context:

1. At any place in the program.

Syntax:

Notes:

1. text is the character string to be inserted in the error log file.
2. The error log must be started with STARTLOG().

See also: STARTLOG(), Exceptions.

SHOWHELP( )

Purpose:

This function function displays a runtime help message, corresponding to its specified argument, from the current help file.

Context:

1. At any place in the program.

Syntax:

Notes:

1. help-number is the help message number in the current help file.
2. You set the current help file with the HELP FILE clause of the OPTIONS instruction.

See also: OPTIONS, Message Files.

STARTLOG( )

Purpose:

This function initializes error logging and opens the error log file passed as 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. 

See also: ERRORLOG(), Exceptions.

FGL_BUFFERTOUCHED( )

Purpose:

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

Context:

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

Syntax:

Notes:

1. returns TRUE if the input buffer has been touched since the current field was selected.

Warnings:

1. 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() always returns TRUE for a field which was modified during the interactive instruction.

See also: FGL_DIALOG_SETBUFFER(), FGL_DIALOG_GETBUFFER().

FGL_DIALOG_GETBUFFER( )

Purpose:

This function returns the value of the current field as a string.

Context:

1. In AFTER FIELD blocks of CONSTRUCT instructions.

Syntax:

Notes:

1. Returns the content of the input buffer of the current field.
2. Only useful in a CONSTRUCT instruction, because there is no variable associated with fields in this case.

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

FGL_DIALOG_SETBUFFER( )

Purpose:

This function sets the value of the current field as a string.

Context:

1. In BEFORE FIELD blocks of CONSTRUCT instructions.

Syntax:

Notes:

1. value is the text to set in the current input buffer.
2. Only useful in a CONSTRUCT instruction, because there is no variable associated with fields in this case.

Warnings:

1. When used in an INPUT statement, 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 in INPUT statements.
2. 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_CHARBOOL_TO_INTBOOL( )

Purpose:

This function converts a character representation of a Boolean value to an INTEGER Boolean.

Context:

1. At any place in the program.

Syntax:

Notes:

1. value represents the Boolean as 't' or 'f'.
2. This function is not case-sensitive.
3. 't' is converted to 1.
4. 'f' is converted to 0.

See also: FGL_INTBOOL_TO_CHARBOOL().

FGL_INTBOOL_TO_CHARBOOL( )

Purpose:

This function converts an INTEGER Boolean to a character representation of the Boolean value.

Context:

1. At any place in the program.

Syntax:

Notes:

1. value represents the INTEGER Boolean.
2. 1 is converted to 't'.
3. 0 is converted to 'f'.

See also: FGL_CHARBOOL_TO_INTBOOL().

FGL_DIALOG_GETFIELDNAME( )

Purpose:

This function returns the name of the current input field.

Context:

1. In INPUT , INPUT ARRAY, CONSTRUCT or DISPLAY ARRAY instructions.

Syntax:

Notes:

1. Returns the name of the current input field.

Warnings:

1. Only the column part of the field name is returned.

See also: FGL_DIALOG_INFIELD(). 

FGL_DIALOG_INFIELD( )

Purpose:

This function returns TRUE if the field passed as the parameter is the current input field.

Context:

1. In INPUT , INPUT ARRAY, CONSTRUCT or DISPLAY ARRAY instructions.

Syntax:

Notes:

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

Warnings:

1. Only the column part of the field name is used.

See also: INFIELD(). 

FGL_DIALOG_SETCURSOR( )

Purpose:

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

Context:

1. In interactive instructions.

Syntax:

Notes:

1. index is the character position in the text.

See also: FGL_GETCURSOR().

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. With graphical front ends, however, 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 necessary, 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.

Syntax:

Notes:

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

Warnings:

1. The line parameter is ignored in graphical mode.
2. Use the FGL_SET_ARR_CURR() function instead.
3. 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.

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.

Syntax:

Notes:

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

Warnings:

1. 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.

FGL_DRAWBOX( )

Purpose:

This function draws a rectangle based on character terminal coordinates in the current open window.

Context:

1. At any place in the program.

Syntax:

Warnings:

1. This function is deprecated, because it breaks the rules of abstract user interface programming.

See also: FGL_DRAWLINE(). 

FGL_DRAWLINE( )

Purpose:

This function draws a line based on character terminal coordinates in the current open window.

Context:

1. At any place in the program.

Syntax:

Warnings:

1. This function is deprecated, because it breaks the rules of abstract user interface programming.

See also: FGL_DRAWBOX(). 

FGL_LASTKEY( )

Purpose:

This function returns the key code of the last key pressed by the user.

Context:

1. Any interactive instructions.

Syntax:

Notes:

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

See also: FGL_KEYVAL().

FGL_KEYVAL( )

Purpose:

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

Context:

1. At any place in the program.

Syntax:

Notes:

1. character can be a single character, a digit, a printable symbol like @, #, $ or a special keyword.
2. Keywords recognized by FGL_KEYVAL() are: ACCEPT, HELP, NEXT, RETURN, DELETE, INSERT, NEXTPAGE, RIGHT, DOWN, INTERRUPT, PREVIOUS, TAB, ESC, ESCAPE, LEFT, PREVPAGE, UP, F1 through F64, CONTROL-character ( except A, D, H, I, J, L, M, R, or X )
3. 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.
4. The function returns NULL if the parameter does not correspond to a valid key.

Usage:

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

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 default Accept key is ESCAPE. To test if the key most recently pressed by the user was the Accept key, 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"). The value returned by FGL_LASTKEY() is undefined in a MENU statement.

See also: FGL_LASTKEY().

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.

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

FGL_GETCURSOR( ) / FGL_DIALOG_GETCURSOR()

Purpose:

This function returns the position if the edit cursor is in the current field.

Context:

1. In interactive instructions.

Syntax:

Notes:

1. index is the character position in the text.

See also: FGL_DIALOG_SETCURSOR().

FGL_GETWIN_HEIGHT( )

Purpose:

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

Context:

1. At any place in the program.

Syntax:

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

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:

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

See also: FGL_GETWIN_WIDTH().

FGL_GETWIN_X( )

Purpose:

This function returns the horizontal position of the current window.

Context:

1. At any place in the program.

Syntax:

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

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:

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

See also: FGL_GETWIN_X().

LENGTH( )

Purpose:

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

Context:

1. At any place in the program.

Syntax:

Notes:

1. expression is any valid expression.
2. Trailing blanks are not counted in the length of the string.
3. If the parameter is NULL, the function returns zero.

Warnings:

1. The function counts bytes, not characters. This is important in a multi-byte environment.
2. Most database servers support an equivalent scalar function in the SQL language, but the result may be different from the FGL 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.

Context:

1. At any place in the program.

Syntax:

Warnings:

1. Provided for debugging info only; please do not write business code dependent on the build number.

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 definition of the current help file (OPTIONS HELP FILE).

Syntax:

Notes:

1. id is the help text identifier.

See also: The OPTIONS instruction.

FGL_GETPID( )

Purpose:

This function returns the system process identifier.

Context:

1. At any place in the program.

Syntax:

Notes:

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

Warnings:

1. The function returns positive integers on Windows platforms. (On Windows platforms, process identifiers are negative integers).

See also: FGL_SYSTEM().

FGL_DIALOG_GETBUFFERSTART( )

Purpose:

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

Syntax:

Usage:

See DISPLAY ARRAY. 

FGL_DIALOG_GETBUFFERLENGTH( )

Purpose:

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

Syntax:

Usage:

See DISPLAY ARRAY. 

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 file to retrieve from the front end.
2. dst contains the name of the source file to write on the server side.

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.

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.
2. If the specified environment variable is not defined, the function returns a NULL value.
3. If the environment variable is defined but does not have a value assigned to it, the function returns blank spaces.

Warnings:

1. 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.

Usage:

The argument of FGL_GETENV() must be a string expression that returns 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. 

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.

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

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. 

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

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.

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

See also: FGL_SETKEYLABEL(), FGL_DIALOG_SETKEYLABEL().

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. 

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

See also: FGL_SETKEYLABEL(), FGL_DIALOG_GETKEYLABEL().

FGL_SETSIZE( )

Purpose:

This function sets the size of the main application window.

Syntax:

Notes:

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

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

See also: FGL_SETTITLE().

FGL_SETTITLE( )

Purpose:

This function sets the title of the main application window.

Syntax:

Notes:

1. label is the text of the title. 

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

See also: FGL_SETSIZE().

FGL_SYSTEM( )

Purpose:

This function starts a program in a UNIX terminal emulator when a graphical front end is used.

Syntax:

Notes:

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

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

Usage:

The function starts a program that needs a UNIX terminal emulator when using the Windows Front End, even if the current program has been started without a visible terminal. The command parameter is a string or variable that contains the commands to be executed. The UNIX terminal will be raised and activated. The terminal is automatically lowered when the child process finishes.

See also: WINEXEC().

FGL_WIDTH()

Purpose:

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

Context:

1. At any place in the program.

Syntax:

Notes:

1. expression is any valid expression.
2. Trailing blanks are counted in the length of the string.
3. 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.

Warnings:

1. This function is supported for backward compatibility; we do not recommend that you use it.

FGL_WINBUTTON( )

Purpose:

This function displays an interactive message box in a separate window with multiple choices

Syntax:

Notes:

1. title defines the title of the message window.
2. text specifies the string displayed in message window.
3. Use in text '\n' to separate lines (does not work on ASCII client).
4. default indicates the default button to be pre-selected.
5. buttons defines a set of button labels separated by "|".
6. You can define up to 7 buttons that each have 10 characters.
7. icon is the name of the icon to be displayed.
8. Supported icon names are: "information", "exclamation", "question", "stop".
9. danger (for X11 only), number of the warnings item. Otherwise, this parameter is ignored.
10. The function returns the label of the button which has been selected by the user.

Warnings:

1. You can also use a form or a menu with "popup" style instead.
2. If two buttons start with the same letter, the user will not be able to select one of them on the ASCII client.
3. The "&" before a letter for a button is either displayed (ASCII client) or it underlines the letter.

Example:

01 MAIN
02   DEFINE answer STRING
03   LET answer = FGL_WINBUTTON( "Media selection", "What is your favorite media?",
04       "Lynx", "Floppy Disk|CD-ROM|DVD-ROM|Other", "question", 0)
05   DISPLAY "Selected media is: " || answer
06 END MAIN

FGL_WINMESSAGE( )

Purpose:

This function displays an interactive message box in a separate window with a text.

Syntax:

Notes:

1. title defines message box title.
2. text is the text displayed in the message box. Use '\n' to separate lines.
3. icon is the name of the icon to be displayed.
4. Supported icon names are: "information", "exclamation", "question", "stop".

Warnings:

1. You can also use a form or a menu with "popup" style instead.
2. icon is ignored by the ASCII client.

Example:

01 MAIN
02   CALL FGL_WINMESSAGE( "Title", "This is a critical message.", "stop")
03 END MAIN

FGL_WINPROMPT( )

Purpose:

This function displays a dialog box with a field that accepts a value.

Syntax:

Notes:

1. x is the column position in characters.
2. y is the line position in characters.
3. text is the message shown in the box.
4. default is the default value.
5. length is the maximum length of the input value.
6. type is the datatype of the return value : 0=CHAR, 1=SMALLINT,  2=INTEGER, 7=DATE, 255=invisible
7. value is the value entered by the user.

Warnings:

1. You can also use a form or a menu with "popup" style instead.

2. Avoid passing NULL values.

Example:

01 MAIN
02   DEFINE answer DATE
04   LET answer = FGL_WINPROMPT( 10, 10, "Today", DATE, 10, 7 )
05   DISPLAY "Today is " || answer
06 END MAIN

FGL_WINQUESTION( )

Purpose:

This function displays an interactive message box in a separate window with Yes, No, Cancel buttons

Syntax:

FUNCTION FGL_WINQUESTION(
  title STRING, text STRING, default STRING,
  buttons STRING, icon STRING, danger SMALLINT ) 

Notes:

1. title is the message box title.
2. text is the message displayed in the message box. Use '\n' to separate lines (not working on ASCII client).
3. default defines the default button that is pre-selected.
4. buttons defines the buttons: Either "yes|no" or "yes|no|cancel", not case-senstitive.
5. icon is the name of the icon to be displayed.
6. Supported icon names are: "information", "exclamation", "question", "stop".
7. danger is for X11, it defines the code of the warning item. Otherwise, this parameter is ignored.
8. The function returns the label of the button which has been selected by the user.

Warnings:

1. You can also use a form or a menu with "popup" style instead.
2. Setting buttons to another value may result in unpredictable behavior at runtime.
3. Avoid passing NULL values

Example:

01 MAIN
02   DEFINE answer STRING
04   LET answer = "yes"
05   WHILE answer = "yes"
06     LET answer = FGL_WINQUESTION(
07         "Procedure", "Would you like to continue ? ",
08         "cancel", "yes|no|cancel", "question", 0)
09   END WHILE
10   IF answer = "cancel" THEN
11      DISPLAY "Canceled."
12   END IF
13 END MAIN

FGL_GETRESOURCE( )

Purpose:

This function returns the value of an FGLPROFILE entry.

Context:

1. At any place in the program.

Syntax:

Notes:

1. name is the FGLPROFILE entry name to be read.
2. If the entry does not exist in the configuration file, the function returns NULL.
3. See also FGLPROFILE definition.

Warnings:

1. FGLPROFILE entry names are not case-sensitive.

FGL_KEYVAL( )

Purpose:

This function waits for a keystroke and returns the key code.

Syntax:

Notes:

1. See the key-code table

See also: FGL_LASTKEY().

DOWNSHIFT( )

Purpose:

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

Context:

1. At any place in the program.

Syntax:

Notes:

1. source is the character string to convert to lowercase letters.
2. Non-alphabetic or lowercase characters are not altered.

Warnings:

1. Conversion depends on locale settings (the LC_CTYPE environment variable).

See also: UPSHIFT().

UPSHIFT( )

Purpose:

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

Context:

1. At any place in the program.

Syntax:

Notes:

1. source is the character string to convert to uppercase letters.
2. Non-alphabetic or uppercase characters are not altered.

Warnings:

1. Conversion depends on locale settings (the LC_CTYPE environment variable).

See also: DOWNSHIFT().

WINEXEC( )

Purpose:

This function executes a program on the machine where the Windows Front End runs and returns immediately.

Context:

1. At any place in the program, but only after the first instruction has displayed something on the front end.

Syntax:

Notes:

1. command is the command to be executed on the front end.
2. The function executes the program without waiting.
3. The function returns FALSE if a problem has occurred.

See also: WINEXECWAIT(), DDE Support.

WINEXECWAIT( )

Purpose:

This function executes a program on the machine where the Windows Front End runs and waits for termination.

Context:

1. At any place in the program, but only after the first instruction has displayed something on the front end.

Syntax:

Notes:

1. command is the command to be executed on the front end.
2. The function executes the program and waits for its termination.
3. The function returns FALSE if a problem has occurred.

See also: WINEXEC(), DDE Support.

WINSHELLEXEC( )

Purpose:

This function opens a document with the corresponding program according to the file extension.

Context:

1. At any place in the program, but only after the first instruction has displayed something on the front end.

Syntax:

Notes:

1. filename is the file to be opened on the front end.
2. The function executes the program and returns immediately.
3. The function returns FALSE if a problem has occurred.

See also: WINEXEC(), DDE Support.

WINOPENDIR( )

Purpose:

This function shows a dialog window to let the user select a directory path on the front end workstation file system.

Context:

1. At any place in the program, but only after the first instruction has displayed something on the front end.

Syntax:

Notes:

1. dirname is the default path to be displayed in the dialog window.
2. caption is the label to be displayed..
3. The function returns the directory path on success.
4. The function returns NULL if a problem has occurred or if the the user canceled the dialog.

WINOPENFILE( )

Purpose:

This function shows a dialog window to let the user select a file path on the front end workstation file system, for a load.

Context:

1. At any place in the program, but only after the first instruction has displayed something on the front end.

Syntax:

Notes:

1. dirname is the default path to be displayed in the dialog window.
2. typename is the name of the file type to be displayed.
3. extlist is a blank separated list of file extensions defining the file type.
4. caption is the label to be displayed..
5. The function returns the file path on success.
6. The function returns NULL if a problem has occurred or if the the user canceled the dialog.

WINSAVEFILE( )

Purpose:

This function shows a dialog window to let the user select a file path on the front end workstation file system, for a save.

Context:

1. At any place in the program, but only after the first instruction has displayed something on the front end.

Syntax:

Notes:

1. dirname is the default path to be displayed in the dialog window.
2. typename is the name of the file type to be displayed.
3. extlist is a blank separated list of file extensions defining the file type.
4. caption is the label to be displayed..
5. The function returns the file path on success.
6. The function returns NULL if a problem has occurred or if the the user canceled the dialog.

The key code table