Welcome in this series of short videos, we will look at topics common to both the Power Basic console and Windows compilers today we will look at the parameters passed between functions and subroutines. It has been some time since we did a video on the parameters passed between functions and subroutines. So today we're going to revisit the subject for those of you who are just using Power Basic. Both the console compiler and the Windows compiler can be used with the source code for this project. We have two include files at the top of our code, one for the Windows API and one for our common display library, which allows the source code to be used either in the Windows compiler or the console compiler. The first function in your application that gets executed is the pb_main function and in this function you can include code and call other functions and subroutines. We're going to start this demonstration by calling a function called process count by reference. We're passing a parameter to this function called count. We have declared the count as a long and we're using a for next loop to count between one and five. This function will be called five times. So here is our new function process count by ref. In the brackets we have the parameter list, in this case just a single parameter called count, which has been defined as a long. This is preceded by the word byref to indicate that this parameter has been passed by reference. This is a reference to where the information is stored. Power basic by default passes parameters by reference. So if we had no mention of the word by ref it would still be passed by reference. Within this function we're declaring a local variable called value also as a long and we're populating that local variable with the value of the parameter passed in count and we're adding one to it and we're printing the value out to our log. If we try running the application now we will see the values put out to a log are two, three, four, five and six. This is because every time we call this function we're taking the values one to five and adding a one to it, giving us the values two through six. So we have successfully passed a parameter from one function to another. One thing to note when you're calling functions is that the value you're passing in here which is called count which is the variable we could have this called something entirely different. If we call this new count and changed the other references to that, the application would work just as well. The reason for this is that you're passing a parameter by reference therefore the name of the parameter from this point of view is irrelevant it's the same value. We can prove this quite easily by adding an extra line of code to our function. If we place an increment command in as the bottom line of this function which would increment the long new count. As this value being passed in is being passed in by reference then if you increase this by one then this would be passed back to the calling function. So if we run the application once more we will see the values we get out are quite different. This is because each time we pass through this function we are incrementing the current variable and this is being passed back to the calling function. So this is something to be wary of when you're passing variables from one function to another or from one function to a subroutine. If they're passed by reference then any change made to that variable within the subroutine or function will be reflected in the calling routine. If you wish not to pass them by reference you can pass it byval that's by value. This way the actual value of the variable is passed and not the pointer to where it sits in memory. If we change our code to call this function and run the code now you will see the values return to as they were before. As any change made to this variable is not reflected back to the calling function. Normally you will pass parameters by reference as it is more efficient. Power basic will allow you to pass up to 32 parameters between functions and subroutines. So let's say we wanted to pass a parameter to a subroutine as opposed to a function. How would we do that? We can call a subroutine by using the word call followed by the name of the subroutine and its parameters. The command word call is optional. If we emitted call and just put the name of the subroutine in it would still function perfectly well. Our subroutine would look like this. It would start with the word sub followed by the subroutine name and then the list of parameters. The main difference between a function and a subroutine is that a function will return a value. As we see here the function has declared that it's going to return a long number. The difference between a function and a subroutine is that a function can return a value. Functions are very useful as you can embed them in your code. Subroutines on the other hand do not return values. If we try running that now we will see our subroutine is returning this value here 6 which was the last value of the current variable. As with functions if the parameter passed is not defined as by val or by ref it will always be passed as by reference. To demonstrate using your function within your code we're going to call a new function to determine whether a value is odd or even. First of all we will set up a variable which we're going to test and we're setting the value of this variable to the value 9. And we're going to test the value coming back from this function. Is it true or is it false? Power basic has an is true command word which tests the value returned from this function. And we're passing our parameter value to the function. And then we can determine what to do based on the return from this function. It's always an advantage to name your functions for the purpose they perform. In this case "is value even". If that returns true then the value is even. If it returns false then the value is false. This makes your code much easier to read and understand. So let's now create this new function. So here is a new function is value even passing the single parameter of value defined as a long. And our return from this function is also defined as a long. And we're using the modulus command to take the value, divide it by 2 and if the remainder from that division is 0 then the value is divisible by 2. Therefore the value is even. So we will return true to the function calling this function. Otherwise there is some remainder and we return the value false. So if we run that code now it would tell us that the number 9 is odd. If we change that to an even number. So for example 12 and run the code again it would tell us the value is even. So we've passed a variable to a function and returned a value which is either true or false. Another thing you can do with parameters is make one or more of the parameters optional. Say for example we declared another value variable called special value and we've populated that variable with the value function passing it two parameters. As soon as you do this if we make no change to the function is value even then the program will no longer compile. As you're attempting to call a function with two parameters and the function only has declarations for one parameter. Therefore it will not compile. So what you can do to the function to allow it to accept either one or two parameters is to put the word optional before the second parameter. If you're passing say for example five parameters to a function then every parameter after the first declaration of optional will be optional. So the optional parameters need to be at the end of the parameters list. So now that we have an optional parameter in how does our function know that a parameter has been passed or not. Well you can test for it. There is an inbuilt command called is missing. If is missing returns true then there is no optional parameter. If if missing returns false then the optional parameter has indeed been passed. You can place this at the beginning of your function to work out whether the optional or optional parameters have been passed. It's important not to reference the special value variable if the parameter has not been passed. Using this construct allows you to set your code to handle missing parameters. If the parameter is missing then you should have no reference to the named parameter. For example special value. If the parameter is not missing then you can reference the value. And if you're going to use this for the on in the code you can populate a locally declared variable with that value. So if we try running the application now it will print out that the optional parameter equals 13. If we change it so there is no optional parameter the code will still compile and run and it will tell us there is no optional parameter. So using optional parameters gives you a great deal of flexibility within your function. So what happens if we want to pass more information than just numbers? Let's declare a user defined type. We've now declared a user defined type called udt car and it has four elements make model type and color. Each of these is set up as a 20 character string. Within a user defined type all the strings are not dynamic they have to be fixed length so it's important to set them up to be large enough for the data you're going to be populating it with. We can now declare a local variable as that user defined type. So our local variable is called ucar and it's been declared as a udt car which is the type we declared a moment ago. You can then populate that by the construct of ucar dot and then the element name. I'm using the prefix command here to save a little bit of typing and to make the code look a little easier to read. The prefix command takes the string which appears immediately after it and adds it to the beginning of each line of code that follows until we get to end prefix. This saves you in some cases a great deal of typing and makes the code look nice and tidy. So now that we've populated this user defined type how do we pass that to a function? Actually quite simply as we would pass any other variable just by mentioning it in the list within the brackets. So let's create this new show car details function. So as you will see in the parameters list we've declared a local variable in this case ucar as the udt car type in the same way as you declare any other variable passed on the parameters list. So all we're doing within this function is we're displaying the details of the car out to our log. By printing out the local name ucar dot then the element name in this case the string make followed by a carriage return line feed. So that each element of this user defined type is printed out on a separate line. So if we try running that code now we will see we get the Ford Capri electric silver printed out to our log. So we've successfully passed a user defined type from one function to another. However we can go further with this. What if we had multiple car details to pass to our function. We can set up an array of user defined types. So we're dimensioning an array as udt car and the number of elements we have specified as two. So we can step through a little for next loop to populate this information. So we're doing between one and two and we're using the prefix which is the name of the user defined type and in brackets the element number and then the details of the car. The make the model the type and the color. And we're adding on the number to the end of the word just so we can distinguish which is number one and which is number two. As it is an array we need to put the two brackets at the end of the variable name. As in a ucars open then close brackets. This tells Power Basic that we're passing an array by reference. So on our function to actually display these to the user we're calling the function showAllCarDetails. The array is defined as a u cars open and close bracket. This tells Power Basic that it's an incoming array which has been passed by reference and we're specifying that the type of this array is a user defined type car. And we're putting a for next loop in here again to display each element within the array. We can determine the number of elements within the array by using the ubound command. From one to the value in this case two. And we're printing the details out to the log using ucars and then within brackets the element number. Followed by the type from the user defined type as in make, model, type and color. So if we try running that code now we will see we get the details for number one and the details for number two. So you can pass a great deal of data using the array as one of the parameters. But it's important to note that you're always passing this by reference. So you can pass a great deal of data between one function and another function or subroutine by using an array. The arrays are always passed by reference. As in you're not passing the data within the array but you're passing details which Power Basic can use to determine where the data actually sits. Any change made to data within the array will of course be reflected in the calling routine as they're both pointing at the same place. Even if the name you're using in the parameters list is different. So what other kind of parameters can we possibly use? Well say for example we want to run a process. A simple arithmetic process that's going to be called many times. So I'm going to set up some local variables. A counter variable, a total variable, a loop variable and a quad timer. We'll set the values for the counter to 10 and the total to be 0. And I'm going to be using a for next loop from 1 to 1000. So we're going to be calling this new function process 1000 times. In order to determine how long this actually takes for the processor to process I'm going to be using the tix command. The tix command takes a single parameter. In this case a quad value. This picks up the cycle count of the CPU. And after the processing I'm calling tix end. Which picks up the value again and subtracts the first value from the second value. This gives us the number of CPU cycles used between the tix and the tix end command. This is useful to determine just how efficient one routine is to another. So we're going to print out the total to the log with the number of CPU cycles. So let's create this fun process function. This is a very straightforward process which takes the two parameters coming in the total and the counter. And it adds to the total what's already in total plus the counter. And then returns to the calling function the value of the total variable. So if we try running that now we will see it gives us a value 10,000 and it has taken 20,787 CPU cycles to perform these 1000 iterations. So that is our baseline. So now that we have a function that performs something purely arithmetic can we do this faster? Is there a faster way of executing this process? Power basic has a different type of function called fast proc. We've now created a fast proc function. It's taking in exactly the same parameters. However it's taking them in by value. In fast proc you have to use by value. The arithmetic calculation within the routine is exactly the same as the previous one. We're taking the value in total and adding on the counter. And at the end of the fast proc we're returning that total to the calling routine. So we now go back to our pb_main function and call this new function. So here is the call to the new function. We're resetting the counter and the total to 10 and zero. We're starting the tix command. We're doing a look from 1 to 1000 as we did before. But we're calling the new fast proc process. And we're ending the tix command and printing out the details to the log. If we try running the code once more we will see we get a different value coming back. We get the same value for the total 10 000. But the number of cpu cycles is considerably less. It's only 7371. So running this as a fast proc means our process runs in almost a third of the time. So just in case the position in the code is actually giving the fast proc an advantage. We'll move that code to before the normal process. We'll cut that code out of here and we'll put it in before the other one. So we're calling the fast process first and we're calling the normal process second. So if we run that code again we're still getting the same 10 000 values. But the fast proc is still running considerably faster than the normal function. There are some disadvantages in using fast proc. You can't use local variables within the function. But if you have something that is computationally intensive and you're calling it a great many times it can speed up your processing as you can see. So this completes our short look at parameters being passed between functions and subroutines. Hopefully you'll find this code useful in your applications. But that's it for today. Thank you for watching.
