# FlashBASIC C functions overview C functions can be called from a FlashBASIC program or subroutine using a syntax similar to that of normal C. For Windows: The FlashBASIC program or subroutine must be compiled with the optimized (o option. Note: See the Reference Manual for your specific operating system for information on any C Functions that are not represented in this guide. Commonly used functions are included in the run time package and require no special linking. These functions are referred to as *built-in* functions. A *user-defined* function can also be included in a FlashBASIC application by linking it with the monitor, thus making a user-defined built-in function. C function calls can be embedded in FlashBASIC expressions, FlashBASIC statements or can be used as arguments to other C function calls. Combined size of all parameters passed cannot exceed 32 KB. This size can be changed, however, by the TCL set-cmem command. FlashBASIC expressions and FlashBASIC statements should *not* be used as arguments to FlashBASIC C functions. If a *type* specifier is omitted before an argument name, the argument is assumed to be of type integer when *arg* is a number, or to be of type pointer when *arg* is a dynamic array (string). If *type* is omitted before the function name, the function is assumed to be of type integer. `arg0...arg*n*` are the optional arguments to the function; up to 15 arguments are supported. The return type of a function is void if the function is not part of an assignment statement or used as an argument to another C function or FlashBASIC statement. Whenever the return value of a function can be neglected, the type can be overridden by (void). When a call to a function is made: - All arithmetic arguments are passed by value. - All dimensioned arrays are passed by reference. - All dynamic arrays (strings) are passed by reference. - String constants (strings between quotation marks) and sub-strings (string[m,n}) cannot be modified. If a C function tries to modify a string beyond the end of the string, the string is truncated to its original size, but no error is reported. As is usual in C, no data translation occurs implicitly. - Pointers are all treated as pointers to characters. When assigned to a FlashBASIC variable, a pointer can only be passed to another C function or be tested for the value 0 (null pointer), anything other than this makes no sense. The following statement has unpredictable results: ``` ptr=(char*)%malloc(1024) if ptr > 0 then print ’ok’ ``` The only valid form is to test for ptr = 0 or ptr # 0. ## Argument Types These argument types are supported: | Argument Type | Description | | --- | --- | | | Default. If arg is a number, an (int) is passed to the function. If arg is a dynamic array (string), a pointer to the first character of the string is passed to the function. If arg is a dimensioned array, a pointer to an image of the dimensioned array is passed to the function. See Passing Dimensioned Arrays below. | | (int) | Integer. The arg is divided by the precision factor and passed to the C function. Integers are 32-bit signed elements. | | (char) | Character. If arg is a dynamic array (string), the first character is passed to the C function. If arg is a number it is divided by the precision factor and the result is truncated to 8 bits and passed to the C function. | | (char*) | Pointer. The arg is a number that is passed to the C function without being divided by the precision factor. The only legal use of this type is to pass a null pointer or a pointer returned by a previous call to a C function to another C function. | All types, except pointers can be prefixed by the keyword unsigned, (unsigned char, for example). Note: The precision factor is a number between 0 and 9, with 4 being the default value. When a number is divided by the precision factor, the number is actually being divided by 10 raised to the power of precision. ## Passing Dimensioned Arrays Dimensioned arrays of integers can be passed to an external C function. When the array is passed, the C function receives a pointer to the array and all the integers in the array are divided by the precision factor. If the array is multidimensional, the integers are organized column by column. For example, if we have an array that is dimensioned to (2, 5) in FlashBASIC, the values in the C array would be in this order: (1, 1), (2, 1), (1, 2), (2, 2), (1, 3), (2, 3), and so on. ## Function Types These function types are supported: | Function | Description | | --- | --- | | | Default. The return value is assumed to be an integer. It is multiplied by the precision factor. | | (void) | Return value is discarded. When prefixed with this type, the function cannot be part of an assignment or be used as an argument to another C function or FlashBASIC statement or function. | | (int) | Integer. The return value is a signed integer. It is multiplied by the precision factor. | | (char) | Character. The return value is stored as a dynamic array containing only one character. | | (char*) | Pointer. The return value is stored without being multiplied by the precision factor. The only legal use of this type is to store a pointer that for use as an argument to another C function. | ## ’Address of’ Unary operator The C unary operator, &, is used to pass the address of an integer to an external C function. This is the only valid form. Note that FlashBASIC converts numbers that are too large into strings. In this case, the C function would receive a pointer to a character instead of a pointer to an integer. ## Space Reserve command When a FlashBASIC variable (a dynamic array or an element of a one or two-dimensional array) is used to store data returned by a call to a C function (by means of a pointer passed as an argument), the FlashBASIC variable must have been assigned a size before the call to the function. This needs to be done because C has no notion of dynamic arrays. If a size is not assigned before the result of a C function call is stored in the variable, the data is truncated. For example: ``` char var[size] {,var[size],...} ``` This reserves at least *size* bytes for *var*. *size* can be a constant or an expression. *var* can be a dynamic array or an element of a one or two-dimensional array. After reserving space for *var*, the content of the variable is undefined. If a string longer than *size* is assigned to a variable, it is truncated and the characters beyond the given size are ignored. If a string shorter than *size* is assigned to a variable, the remainder of the char buffer remains undefined. The content of the buffer, including how it is terminated, is determined by the function. A terminator is not automatically added. The buffer should not be used for any purpose other than as a C function call parameter. Doing so may change the internal format of the variable such that it is no longer a char buffer. If the data in the buffer needs further processing by BASIC, it should be copied to another variable and the copy used. For an example, see the [%read() function](https://d3codex.com/pickbasic-flashbasic/percent-read-function/) example code. ## Static Data When using user-defined built-in functions, static data defined as part of a user-defined function remains valid as long as the D3 process is not disconnected from the virtual machine. This is true even if the FlashBASIC program is finished executing and has returned to TCL. The scope of static data lasts longer than in conventional UNIX or Windows programs. Because static data takes up space in the data section of each D3 process (therefore main memory), it is not advisable to have large amounts of static space. **Includes**The following header files are provided in the file bp,unix.h, in the dm account. | errno.h | errno values | | --- | --- | | fcntl.h | Codes for %open(), %creat | | ipc.h | Semaphores, shared memory, messages | | mode.h | File access codes | | sem.h | Semaphore operations | | signal.h | UNIX signal numbers | These rules apply when making a call to a C function: - Parameters for each function must be enclosed in parentheses. - There must be no spaces between the %, the function name, and the (. - function is assumed to return an integer unless explicit casting is performed. ## Syntax ``` {variable =}{(type)}%function({{(type)} arg0{,...{(type)} argn}}) ``` ## See also - [@() function](https://d3codex.com/pickbasic-flashbasic/at-parenthesis-function/) - [abs() function](https://d3codex.com/pickbasic-flashbasic/abs-function/) - [access() function](https://d3codex.com/pickbasic-flashbasic/access-function/) - [addbi command](https://d3codex.com/tcl/addbi-command/) - [alpha() function](https://d3codex.com/pickbasic-flashbasic/alpha-function/) - [ascii() function](https://d3codex.com/pickbasic-flashbasic/ascii-function/) - [FlashBASIC C functions overview](https://d3codex.com/pickbasic-flashbasic/flashbasic-c-functions-overview/) - [cfunction statement](https://d3codex.com/pickbasic-flashbasic/cfunction-statement/) - [char() function](https://d3codex.com/pickbasic-flashbasic/char-function/) - [col1() function](https://d3codex.com/pickbasic-flashbasic/col1-function/) - [col2() function](https://d3codex.com/pickbasic-flashbasic/col2-function/) - [cos() function](https://d3codex.com/pickbasic-flashbasic/cos-function/) - [count() function](https://d3codex.com/pickbasic-flashbasic/count-function/) - [" Reserved Character](https://d3codex.com/pickbasic-flashbasic/quotes-reserved-character/) - [date() function](https://d3codex.com/pickbasic-flashbasic/date-function/) - [dcount() function](https://d3codex.com/pickbasic-flashbasic/dcount-function/) - [delete() function](https://d3codex.com/pickbasic-flashbasic/delete-function/) - [dtx() function](https://d3codex.com/pickbasic-flashbasic/dtx-function/) - [ebcdic() function](https://d3codex.com/pickbasic-flashbasic/ebcdic-function/) - [error() function](https://d3codex.com/pickbasic-flashbasic/error-function/) - [execute statement (UNIX)](https://d3codex.com/pickbasic-flashbasic/execute-statement-unix/) - [exp() function](https://d3codex.com/pickbasic-flashbasic/exp-function/) - [extract() function](https://d3codex.com/pickbasic-flashbasic/extract-function/) - [field() function](https://d3codex.com/pickbasic-flashbasic/field-function/) - [Compiling programs](https://d3codex.com/pickbasic-flashbasic/compiling-programs/) - [fmt() function](https://d3codex.com/pickbasic-flashbasic/fmt-function/) - [fold() function](https://d3codex.com/pickbasic-flashbasic/fold-function/) - [iconv() function](https://d3codex.com/pickbasic-flashbasic/iconv-function/) - [index() function](https://d3codex.com/pickbasic-flashbasic/index-function/) - [insert() function](https://d3codex.com/pickbasic-flashbasic/insert-function/) - [int() function](https://d3codex.com/pickbasic-flashbasic/int-function/) - [len() function](https://d3codex.com/pickbasic-flashbasic/len-function/) - [listbi command](https://d3codex.com/tcl/listbi-command/) - [ln() function](https://d3codex.com/pickbasic-flashbasic/ln-function/) - [mod() function](https://d3codex.com/pickbasic-flashbasic/mod-function/) - [not() function](https://d3codex.com/pickbasic-flashbasic/not-function/) - [num() function](https://d3codex.com/pickbasic-flashbasic/num-function/) - [occurs() function](https://d3codex.com/pickbasic-flashbasic/occurs-function/) - [oconv() function](https://d3codex.com/pickbasic-flashbasic/oconv-function/) - [pwr() function](https://d3codex.com/pickbasic-flashbasic/pwr-function/) - [rem() function](https://d3codex.com/pickbasic-flashbasic/rem-function/) - [ereplace() function](https://d3codex.com/pickbasic-flashbasic/ereplace-function/) - [rmbi command](https://d3codex.com/tcl/rmbi-command/) - [rnd() function](https://d3codex.com/pickbasic-flashbasic/rnd-function/) - [scan() function](https://d3codex.com/pickbasic-flashbasic/scan-function/) - [sentence() function](https://d3codex.com/pickbasic-flashbasic/sentence-function/) - [seq() function](https://d3codex.com/pickbasic-flashbasic/seq-function/) - [set-cmem command](https://d3codex.com/tcl/set-cmem-command/) - [sin() function](https://d3codex.com/pickbasic-flashbasic/sin-function/) - [sort() function](https://d3codex.com/pickbasic-flashbasic/sort-function/) - [soundex() function](https://d3codex.com/pickbasic-flashbasic/soundex-function/) - [space() function](https://d3codex.com/pickbasic-flashbasic/space-function/) - [sqrt() function](https://d3codex.com/pickbasic-flashbasic/sqrt-function/) - [Statements and functions](https://d3codex.com/pickbasic-flashbasic/statements-and-functions/) - [str() function](https://d3codex.com/pickbasic-flashbasic/str-function/) - [sum() function](https://d3codex.com/pickbasic-flashbasic/sum-function/) - [system() function](https://d3codex.com/pickbasic-flashbasic/system-function/) - [tan() function](https://d3codex.com/pickbasic-flashbasic/tan-function/) - [time() function](https://d3codex.com/pickbasic-flashbasic/time-function/) - [timedate() function](https://d3codex.com/pickbasic-flashbasic/timedate-function/) - [trim() function](https://d3codex.com/pickbasic-flashbasic/trim-function/) - [xtd() function](https://d3codex.com/pickbasic-flashbasic/xtd-function/) --- Source: https://d3codex.com/pickbasic-flashbasic/flashbasic-c-functions-overview/ - part of the D3Codex reference.