Obyx

The Function Instruction

This tutorial introduces the iteration flow-function to create a loop

The Instruction operation "function" performs a specific task separately from the main program, functions may take any number of named parameters as arguments. Also known as a subroutine or subprogram in other languages. The first input of a function operation must declare the function source, subsequent inputs provide the named parameters.

In this tutorial we will create a simple function and then pass it to the screen with an OBYX file, so we need two files, an OBYX file that we call "fn-caller.obyx" and a function file that we call "fnQuotient.ixml" (similarly to other tutorials on this site, the function file could have any other extension), we call it function quotient as it is the operation it performs and the result we want to output to screen.

The Function Caller

Below is the full code for our OBYX file, this is the file that calls the function, we then break down the function caller into more digestible pieces and look at them individually and at what each instruction does.

At this point you may wish to create both files with the code provided (see on the right) and run it to see what it returns, or to play with the code in your editor.

fn-caller.obyx:
<instruction xmlns="http://www.obyx.org">
        <input>
            <!-- Defines the stores "a" and "b" -->
            <instruction note="put 23 into a">
                <output space="store" value="a"/>
                <input value="23"/> 
            </instruction>
            <instruction note="put 3 into b">
                <output space="store" value="b"/>
                <input value="3"/> 
            </instruction>
            <!-- Creates a stores Q via the function -->
            <instruction operation="function" note="passes the value in the store 'a' as a parameter named 'x'">
                <input space="file" value="fnQuotient.ixml"/>
                <input name="x" space="store" value="a"/>        
                <input name="y" space="store" value="b"/> 
            </instruction>
            <!-- Display the values created by the function -->
            <instruction operation="append">
                <input value="Q is equals to: "/>
                <input space="store" value="Q"/>
            </instruction>
        </input>
</instruction>

Defining the stores

These two instructions define our two stores, we have an input value of 23 that is stored in a store called "a" and an input of 3 that is stored in a store called "b". That is all these instructions do, so let's look at our third instruction below.

<instruction note="put 23 into a">
             <output space="store" value="a"/>
             <input value="23"/> 
</instruction>
<instruction note="put 3 into b">
             <output space="store" value="b"/>
             <input value="3"/> 
</instruction>

Pass stores as parameters

This instruction passes the value in store "a" as a parameter "x" and the value in store "b" as a parameter "y" to the file "fnQuotient.ixml", so we have now left the OBYX file and go to the function file, where the actual function is processed.

<!-- Creates a stores Q via the function -->
<instruction operation="function" note="passes the value in the store 'a' as a parameter named 'x'">
          <input space="file" value="fnQuotient.ixml"/>
          <input name="x" space="store" value="a"/>        
          <input name="y" space="store" value="b"/> 
</instruction>

The Function

Below is the full code to build our function.

So we had two parameters from our OBYX file "x" and "y", if you still remember above we established that our desired output to screen is the quotient of a division of two values, once the function processes the quotient operation, it then returns the result in store called "Q" back to the OBYX file to then be output to the screen.

fnQuotient.ixml:
<instruction xmlns="http://www.obyx.org">
        <input>
        <!--Stores quotient in a store called "Q"-->
               <instruction operation="quotient">
                    <output space="store" value="Q" />
                    <input space="parm" value="x"/>
                    <input space="parm" value="y"/>
               </instruction>
        </input>
</instruction>

Displaying the results

Our last instruction receives the value in store "Q" from the function file and displays it together with the first input, "Q is equals to: " so the final output is "Q is equals to: 7". This is achieved using the operation append which concatenates multiple inputs. calls the function and displays the result onto the screen.

<!-- Display the values created by the function -->
<instruction operation="append">
            <input value="Q is equals to: "/>
            <input space="store" value="Q"/>
</instruction>

Q is equals to: 7

Summary of Function Tutorial

By the end of this tutorial you should have knowledge about the following concepts:

• The function instruction
• Pass stored values as parameters
• Call a function file into OBYX

Understanding these basic concepts are essential to OBYX programming. Spend time experimenting with each of the examples and ensure you understand why each of the elements are used.