Beginners Guide To Programming - Part VI - User Defined Functions Primer

[kevin]

TDK's PlayBASIC Programming For Beginners

Back To Index

Part 6 - User Defined Functions Primer

  Whereas a subroutine, (some times called a 'procedure'), starts with a label and ends with a RETURN and is called using GOSUB, functions are a somewhat different beast. Although similar to look at code-wise as subroutines, functions in PlayBASIC have three main differences:


1. Local Variables

All variables in a function are local as opposed to global. In programming terms global means that they are visible to all of your program, whereas local means that they are only visible inside a function they are used in. The visibility of variables is called the variable's 'scope'.

A normal variable in your main program can be seen inside a sub routine (procedure), but not inside a function.

Another thing to remember about local variables is that they can co-exist at the same time as other variables with the same name.

This is very important to remember as not knowing this can lead to some very hard to find bugs in your programs.

For example, if you set the variable A to equal 10 in your main program with A=10, then call a function in which you say A=20, when you exit the function what will A equal?

  If you said 20 then you got it wrong! The answer is 10 because inside the function, the variable A would be a newly created local variable called A - entirely separate from the previously created variable A outside the function.  When you exit from the function, you revert back to the the original variable A, which is of course is still equal to 10.

This feature can be very useful, but if you are used to programming in other languages you can be lured into a trap, so beware.

Variables in many forms of BASIC do not need to be declared at the start of your program like in Delphi or C - they exist from the moment you refer to them.   For example, if you write a PB program with just one line which says PRINT MYVAR then PB will quite happily initialize the variable containing the value 0 and print 0 on the screen.   You don't have to tell PB beforehand that you are going to use the variable MYVAR in your program and that it is going to be an integer variable.

Moreover, local variables are 'destructive', which means that when you exit a function, any local variables are destroyed.

The next time you visit the function, the variables are created again as entirely new entities.

  However, in PlayBASIC local variables in functions are 'non-destructive' which means that when you return to a function, the variables still exist and contain whatever values they did when you were last there. This 'feature' can be very useful if you know it's there, but an annoying source of difficult to trace bugs if you don't!



2. Entry & Exit Parameters

Functions can be used to do a specific task without any external information and then exit without returning any information. If no entry parameters are required, empty parenthesis can be used when calling the function and in the function header - or they can be omitted entirely. PB will accept either format.

Alternatively, functions can do a task calculated on the information supplied and then return information. One example of a return value would be a success value.   A 1 returned could denote that the function's task was completed successfully whereas a 0 could denote that something went wrong.

As described above, all variables in a function are local, so you need a method to pass information from your main program to the function and this is done by calling the function with the required variables in a 'parameter list' which is enclosed in parethesis '()'. The function itself must have the exact same parameter list to accept the same variables. So, you would have functions something like these:

No Entry Or Exit Parameters:

PlayBASIC Code: [Select]

Function StartScreen()
   CLS RGB(100,0,100)
   Ink RGB(255,255,255)
   Print "Screen Now Cleared And Ready For Use!"
EndFunction

Using Entry And Exit Parameters:

PlayBASIC Code: [Select]

Function MyFunction(Var1,Var2,Var3,StringVar$)
   SLen=Len(StringVar$)
   RetVal=Var1*Var2*Var3+SLen
EndFunction RetVal

It's fairly obvious here that the function called MyFunction() is passed a parameter list of four variables - the first three being integer numbers and the fourth a string. These variable names are used inside the function as local variables to calculate the value of RetVal.  RetVal is then returned back to the calling function. The actual calculation is of course nonsense, but demonstrates how things work.

So, how are functions called? Well, it depends on whether you need to pass parameters or not and whether your function returns anything. The first example above neither requires or returns anything so it is called with:

StartScreen()

  The second function needs three integer variables and a string so they are passed in the parameter list. The actual variable names used in the call need NOT be the same as used in the parameter list of the function header as the variable's contents are placed into local variables when they get there. Think of it as passing the contents of each variable to the function - not the variables themselves.

The function also returns the contents of the variable RetVal, so we must take that into account when calling the function. This is done by using a variable of the same type in the call. As our example function MyFunction() returns an integer, we use the following call:

ValueBack=MyFunction(MinLen,MaxLen,Score,"Elephant")

After calling the function, the variable ValueBack will contain the returned contents of RetVal from the function. The value returned can be an integer number, a real number or a string.   You can return a list of variables in PlayBasic, but goes beyond the scope of this primer.   See the Help\About\Functions & Psub for something more indepth.




3. #Include Files

Functions can be used in Include files - something widely misunderstood by the newcomer to programming with PlayBASIC.

In a nutshell, the idea is that they prevent you from having to write certain sections of often used code over and over again, each time you write a new programs.   A good example is the keyboard/mouse control code which you use for controlling the game character or ship in your games.   If all the actions for moving and firing etc. are done with functions, then they can all be saved in a single file called, let's say Control.pba for example.

  The next time you write a program which uses the same control method, all you have to do is put the Control.pba file into the same folder as your new program and use the following line as the first line of your program:   

#Include "Control.pba"

When the program is run, all the code in the #Include file becomes available - without you having to re-code them again. A big time saver - especially if you have functions to cover all possible control input methods. You'd never have to write a piece of input code again!

  Another approach, would to use the PlayBasic IDE's project manager.

 

  The project manage allows you to 'attach' other existing PB source files to your current project.


   

Why Use Functions?

Well speed-wise, there is little or no difference between using a sub routine and a function, so the main reason for using them would be for the ability to use local variables or the future grouping together of them in a #include file.

In fact in some cases, a procedure is better due to the lack of the local variable problem.

Some users will swear by using functions for everything, but my advice is to go with whichever you are happiest with.

TDK_Man

Back To Index