[adrotate group=”3,5,7,8,9″]
As a C programmer I have become used to using the return values set by a function as an indicator of the success of the function to carry out its intended role, so when I created Service programs I used the same process. This raised a question about how I could capture that return value and use it within my PHP scripts as an indicator. I have read through the manuals and could not find a way to capture that value so I had resulted to creating a parameter that I would pass in and have that set on return instead of relying on the return value from the function. It seems that there is a way to capture the return value from the function, although it is not documented Easycom provides a simple way to capture the return value via a “virtual parameter”. Why is this important, well we use C a lot, so it is important that when we write a module that we can use it across multiple programs. Before we found this gem we had to write a function which we could call from our C programs and use the return value and another function with exactly the same process that used the input parameters as a way of determining the functions sucess.
Before we go whole hog into this we wanted to check to make sure that our understanding was correct, its not documented so we had to work out some of the details ourselves although Aura did give us the basic structure. The C function we will test with is a service program with a single function, it will return the index of the passed in character within an array of characters (very simple check but provided us with all we need). Here is the C program we compiled as a service Program.
#include<stdio.h>
#include<string.h>
int retvaltst(char *tstchar) {
int i = 0;
char sample[10] = "ABCDEFGHIJ";
for(i = 0; i < 10; i++) {
if(sample[i] == *tstchar)
break;
}
return ++i;
}
As you can see all it does is look at the character passed as looks for it in the sample array, if it finds the character it breaks and returns the index of the character (we increment the counter before we return it). This is the code that we used in a PHP function to test the theory, the connection and everything else is a hack of the connection routines etc we created in previous tests using the PHPTST website..
function get_ret_val(&$conn,$tstchar) {
$description = Array (array ("Name" => "tstchar", "IO" => I5_IN, "Type" => I5_TYPE_CHAR, "Length" => "1"),
array ("Name" => "retval", "IO" => I5_RETVAL | I5_OUT, "Type" => I5_TYPE_INT ));
$prog = i5_program_prepare("CHLIB/RETVALTST(retvaltst)", $description );
if ($prog == FALSE) {
$errorTab = i5_error ();
echo "Program prepare failed RETVALTST(retvaltst)";
var_dump($errorTab);
var_dump($conn);
die ();
}
$parameter = array('tstchar' => $tstchar);
$parmOut = array('retval' => 'retval');
$ret = i5_program_call($prog, $parameter,$parmOut);
if (!$ret) {
throw_error("i5_program_call failed");
exit();
}
// close the program call
i5_program_close($prog);
echo($retval);
return;
}
The function takes a character which is passed to the page as part of the call and sends it to the service program function. The set up of the program prepare shows how we set the retval parameter as a “I5_RETVAL | I5_OUT” type, Easycom knows that this is where the return value from the function is to be set. The function call only accepts a character so the i5_program_prepare() understands that the “I5_RETVAL | I5_OUT” is only used to carry the result and will not be passed into the function. We have to set the $parmOut variable to reflect the retval content as this is where it will be stored by the program. Then we call the program function and echo out the result.
Here are a couple of test results.
http://www.phptst.shield.local/retvaltst.php?tstchar=D = 4
http://www.phptst.shield.local/retvaltst.php?tstchar=F = 6
http://www.phptst.shield.local/retvaltst.php?tstchar=Z = 11 (remember we only have 10 characters so anything above 10 says we did not find it! Its case sensitive as well)
So we can now reduce the coding effort and utilize the same functions in many cases whether they are called from ILEC or PHP.. Now we need to look at the possibility of picking up other return values such as strings and structures…. There are a number of other undocumented features which we will try out in later test, particularly the ability to pass by Value or by Reference.
Happy PHP’ing.
Chris…