What is a Programming Function?

        A programming function is a programming tool in most modern programming languages which contains a specific set of commands. The main function is the "entry-point" in a program where commands begin being executed. Usually, there are several functions used within the main function. These "nested functions are usually those called from another function. Of course, technically, the main program is a function. Nested functions, unlike the main function, serve the purpose of accomplishing very specific, limited tasks whenever they are called** (likewise, a function called from the main function, can call other functions). After a function is called from the main program function it returns to the line in the program after it was called. This is accomplished in XBasic and XCSB Basic with the use of the RETURN command.

        To use a function in XBasic it must be declared at the beginning of a program. It is also strongly recommended that the author of the program use documentation just after the function to explain the purpose of the function so that the user understands it better, but also for another person who may need to use the program, and for troubleshooting. Good documentation of programs is very important.

        To declare a function in XBasic

DECLARE FUNCTION [type] function-name ([parameters])  

The words "DECLARE" and "FUNCTION" are reserved words in XBasic and as such they must always be capitalized. The "type" refers to the data type being returned to the function.  Data types for XBasic can be found at http://www.maxreason.com/software/xbasic/documentation. Then on the left-most window, click on Programming Language/Guide/Data/Data Types. The function-name is simply the name you give to the function. The name should describe the purpose of the function somewhat. The parameters are values, expressed as variables, constants, etc that are passed to the CALLed function.

CALLING A FUNCTION

            We do not actually call the main function, but when we write it into the program, we understand that it is the entry point for all programming instructions, including the calling of other functions. We do not have to name the main function "main". We can call it what we like. The main function in XBasic could be written as

FUNCTION primary ( )

            In XCSB basic the word function is replaced by the reserved word "proc". Thus to begin the main function in XCSB Basic, we could start with

proc main ( )

            To actually call a function, we can assign a variable equal to that function as in the example below:

            in0  = SelectBits (ibyt, 0)

            Simply by looking at the function we are calling, which is named SelectBits, we can see that we are sending it two values, contained within the parentheses. The first value is the number stored in the variable "ibyt; the second is the CONSTANT "0" which will be sent to UBYTE bitno in the function definition below. 
           
            The function named SelectBits is defined later on in the program and looks like this in XBasic:

            FUNCTION UBYTE SelectBits (UBYTE ibyt,  UBYTE bitno)
          UBYTE bit, mask
         
          mask = 1, 1 << bitno
          bit = ibyte & mask
          bit = bit >> bitno

          RETURN bit
          END FUNCTION

           Students, please notice that the first line of the function definition and the FUNCTION DECLARATION use the same format.

          Notice the RETURN bitcommand. It will return the value of the variable "bit" and assign it to the variable "in0" in the main function. At this point, the program the program returns to the main function to execute program commands. END FUNCTION simply marks the end of the function definition. You can actually have several RETURN statements in a function.
           
           
*To branch in a program simply means that a command inside the program forces the program to jump to another part of the program. If a program contained 100 numbered lines of program code, these lines of code, that we see in a text editor like notepad are rarely ever executed sequentially from line 1 too 100. Any modern program could, for example, be at line 10, and then BRANCH to line 80, probably returning to the line after line 10, after the branching is finished.

** A function is called every time that the name of the function is referred to in a program. This causes the program, again, to branch to that function to accomplish a very specific task.