ch26.htm

《Perl 5 Unreleased》

3     print "Process $$ : UID is
$&lt; and GID is $(\n&quot;;<BR>
4 }</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
Calling Perl functions with arguments and using the return values
requires manipulation of the Perl stack. When you make the call,
you push values onto the stack, and upon return from the function
you get the returned value off the stack. Let's see how to work
with the calling stack.<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD ><B>Note</B></TD></TR>
<TR VALIGN=TOP><TD >
<BLOCKQUOTE>
A note to the Perl-savvy reader: You can get the values from Perl special variables directly. See the section titled &quot;Getting Special Variable Values,&quot; later in this chapter.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
Here is another Perl subroutine, which prints whatever parameters
are passed to it:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">sub PrintParameters<BR>
&nbsp;&nbsp;&nbsp;&nbsp;{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;my(@args) = @_
;<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;for $i (@args)
{ print &quot;$i\n&quot; }<BR>
&nbsp;&nbsp;&nbsp;&nbsp;}</FONT></TT>
</BLOCKQUOTE>
<P>
Here is the function to use when calling this Perl subroutine:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">static char *words[] = {&quot;My&quot;,
&quot;karma&quot;, &quot;over&quot;, &quot;my&quot;, &quot;dogma&quot;,
NULL} ;<BR>
&nbsp;&nbsp;&nbsp;&nbsp;static void justDoit()<BR>
&nbsp;&nbsp;&nbsp;&nbsp;{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dSP;<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;perl_call_argv(&quot;PrintParameters&quot;,
G_DISCARD, words) ;<BR>
&nbsp;&nbsp;&nbsp;&nbsp;}</FONT></TT>
</BLOCKQUOTE>
<P>
As you can see, it's easy to construct parameters and then use
them directly in C statements to call Perl functions or programs.
<H2><A NAME="WorkingwiththePerlStack"><B><FONT SIZE=5 COLOR=#FF0000>Working
with the Perl Stack</FONT></B></A></H2>
<P>
Perl has several C functions to use when calling Perl subroutines.
Here are the most important ones to know:
<UL>
<LI><TT><FONT FACE="Courier">perl_call_sv</FONT></TT>
<LI><TT><FONT FACE="Courier">perl_call_pv</FONT></TT>
<LI><TT><FONT FACE="Courier">perl_call_method</FONT></TT>
<LI><TT><FONT FACE="Courier">perl_call_argv</FONT></TT>
</UL>
<P>
The <TT><FONT FACE="Courier">perl_call_sv</FONT></TT> function
is called by the other three functions in the list. These three
functions simply fiddle with their arguments before calling the
<TT><FONT FACE="Courier">perl_call_sv</FONT></TT> function. All
these functions take a flags parameter to pass options. We'll
discuss the meaning of these flags shortly.
<P>
All these functions return an integer of type <TT><FONT FACE="Courier">I32</FONT></TT>.
The value returned is the number of items on the Perl stack after
the call returns. It's a good idea to check this value when using
unknown code. Calling functions use the return value to determine
how many returned values to pick up from the stack after the calling
function returns.<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD ><B>Note</B></TD></TR>
<TR VALIGN=TOP><TD >
<BLOCKQUOTE>
One important point to note here is that you'll see a lot of types of returned values and arguments passed into functions. These declarations come from the Perl sources and header files starting from <TT><FONT FACE="Courier">perl.h</FONT></TT>. You really 
do not need to know how <TT><FONT FACE="Courier">I32</FONT></TT> is defined, but its name suggests it's a 32-bit integer. If you are really curious to see how it works or what the definitions are, check out the <TT><FONT FACE="Courier">perl.h</FONT></TT> 
header file. Please refer to <A HREF="ch25.htm" tppabs="http://www.mcp.com/815097600/0-672/0-672-30891-6/ch25.htm" >Chapter 25</A> for more information on internal Perl variables.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H3><A NAME="Theperl_call_svFunction"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">perl_call_sv</FONT></B></TT><B><FONT SIZE=4>
Function</FONT></B></A></H3>
<P>
The syntax for this function is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">I32 perl_call_sv(SV* sv, I32 flags) ;</FONT></TT>
</BLOCKQUOTE>
<P>
The <TT><FONT FACE="Courier">perl_call_sv</FONT></TT> takes two
arguments. The first argument, <TT><FONT FACE="Courier">sv</FONT></TT>,
is a pointer to an <TT><FONT FACE="Courier">SV</FONT></TT> structure.
(The <TT><FONT FACE="Courier">SV</FONT></TT> structure is also
defined in the header file <TT><FONT FACE="Courier">perl.h</FONT></TT>.)
The <TT><FONT FACE="Courier">SV</FONT></TT> stands for <I>scalar
vector</I>. This way you can specify the subroutine to call either
as a C string by name or by a reference to a subroutine.
<H3><A NAME="Theperl_call_pvFunction"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">perl_call_pv</FONT></B></TT><B><FONT SIZE=4>
Function</FONT></B></A></H3>
<P>
The function <TT><FONT FACE="Courier">perl_call_pv</FONT></TT>
is like the <TT><FONT FACE="Courier">perl_call_sv</FONT></TT>
call except that it expects its first parameter to be a string
containing the name of the subroutine to call. The syntax to this
function is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">I32 perl_call_pv(char *subname, I32 flags)
;</FONT></TT>
</BLOCKQUOTE>
<P>
For example, to specify the name of function, you would make a
call like this:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">perl_call_pv(&quot;showUser&quot;,0);</FONT></TT>
</BLOCKQUOTE>
<P>
The function name can be qualified to use a package name. To explicitly
call a routine in a package, simply prepend the name with a <TT><FONT FACE="Courier">PackageName::</FONT></TT>
string. For example, to call the function <TT><FONT FACE="Courier">Time</FONT></TT>
in the <TT><FONT FACE="Courier">Datum</FONT></TT> package, you
would make this call:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">perl_call_pv(&quot;Datum::Time&quot;,0);</FONT></TT>
</BLOCKQUOTE>
<H3><A NAME="Theperl_call_methodFunction"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">perl_call_method</FONT></B></TT><B><FONT SIZE=4>
Function</FONT></B></A></H3>
<P>
This function is used to call a method from a Perl class. The
syntax for this call is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">I32 perl_call_method(char *methodName,
I32 flags) ;</FONT></TT>
</BLOCKQUOTE>
<P>
<TT><FONT FACE="Courier">methodName</FONT></TT> is set to the
name of the method to be called. The class in which the called
method is defined is passed on the stack and not in the argument
list. The class can be specified either by name or by reference
to an object.
<H3><A NAME="Theperl_call_argvFunction"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">perl_call_argv</FONT></B></TT><B><FONT SIZE=4>
Function</FONT></B></A></H3>
<P>
This subroutine calls the subroutine specified in the <TT><FONT FACE="Courier">subname</FONT></TT>
parameter. The values of the flags that are passed in when making
this function call will be discussed shortly. The <TT><FONT FACE="Courier">argv</FONT></TT>
pointer is set in the same manner as the <TT><FONT FACE="Courier">ARGV</FONT></TT>
array to a Perl program: each item in the <TT><FONT FACE="Courier">argv</FONT></TT>
array is a pointer to <TT><FONT FACE="Courier">NULL</FONT></TT>-terminated
strings. The syntax for this call is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">I32 perl_call_argv(char *subname, I32
flags, register char **argv) ;</FONT></TT>
</BLOCKQUOTE>
<H2><A NAME="TheFlagstoUse"><B><FONT SIZE=5 COLOR=#FF0000>The
Flags to Use</FONT></B></A></H2>
<P>
The <TT><FONT FACE="Courier">flags</FONT></TT> parameter in all
the functions discussed in the previous section is a bitmask that
can consist of the following values:
<UL>
<LI><TT><FONT FACE="Courier">G_DISCARD</FONT></TT>
<LI><TT><FONT FACE="Courier">G_NOARGS</FONT></TT>
<LI><TT><FONT FACE="Courier">G_SCALAR</FONT></TT>
<LI><TT><FONT FACE="Courier">G_ARRAY</FONT></TT>
<LI><TT><FONT FACE="Courier">G_EVAL</FONT></TT>
</UL>
<P>
The following sections detail how each flag affects the behavior
of the called function.
<H3><A NAME="TheG_DISCARDFlag"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">G_DISCARD</FONT></B></TT><B><FONT SIZE=4>
Flag</FONT></B></A></H3>
<P>
The <TT><FONT FACE="Courier">G_DISCARD</FONT></TT> flag is used
to specify whether a function returns a value or not. If the <TT><FONT FACE="Courier">G_DISCARD</FONT></TT>
flag is set to <TT><FONT FACE="Courier">True</FONT></TT>, no values
are returned. By default, a returned value or a set of values
from the <TT><FONT FACE="Courier">perl_call</FONT></TT> functions
are placed on the stack, and placing these values on the stack
does take time and processing. If you are not interested in these
values, set the <TT><FONT FACE="Courier">G_DISCARD</FONT></TT>
flag to get rid of these items. If this flag is not specified,
there might be returned values pushed onto the stack that you
might not be aware of unless you explicitly check the returned
value of the function call. Therefore, specify the flag explicitly
if you don't care to even look for returned values.
<H3><A NAME="TheG_NOARGSFlag"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">G_NOARGS</FONT></B></TT><B><FONT SIZE=4>
Flag</FONT></B></A></H3>
<P>
Normally you'll be passing arguments into a Perl subroutine. The
default procedure is to create the <TT><FONT FACE="Courier">@_</FONT></TT>
array for the subroutine to work with. If you are not passing
any parameters to the Perl subroutine, you can save processing
cycles by not creating the <TT><FONT FACE="Courier">@_</FONT></TT>
array. Setting the flag stops the flag from being created.
<P>
Be sure that the function you are calling does not use arguments.
If the called Perl subroutine does use parameters and you do not
pass any parameters, your program might return totally bogus results.
In such cases, the last value of <TT><FONT FACE="Courier">@_</FONT></TT>
is used.
<H3><A NAME="TheG_SCALARFlag"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">G_SCALAR</FONT></B></TT><B><FONT SIZE=4>
Flag</FONT></B></A></H3>
<P>
The flag specifies that only one scalar value will be expected
back from this function. The called subroutine might attempt to
return a list, in which case only the last item in the list will
be returned. Setting this flag sets the context under which the
called subroutine will run. <TT><FONT FACE="Courier">G_SCALAR</FONT></TT>
is the default context if no context is specified.
<P>
When this flag is specified, the returned value from the called
function will either be <TT><FONT FACE="Courier">0</FONT></TT>
or <TT><FONT FACE="Courier">1</FONT></TT>: <TT><FONT FACE="Courier">0</FONT></TT>
is returned if the <TT><FONT FACE="Courier">G_DISCARD</FONT></TT>
flag is set; otherwise, <TT><FONT FACE="Courier">1</FONT></TT>
is returned. If a <TT><FONT FACE="Courier">1</FONT></TT> is returned,
you must remove the returned value to restore the stack back to
what it was before the call was made.<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD ><B>Tip</B></TD></TR>
<TR VALIGN=TOP><TD >
<BLOCKQUOTE>
The called subroutine can call the <TT><FONT FACE="Courier">wantarray</FONT></TT> function to determine if it was called in scalar or array context. If the call returns <TT><FONT FACE="Courier">false</FONT></TT>, the called function is called in scalar 
context. If the call returns <TT><FONT FACE="Courier">true</FONT></TT>, the called function is called in array context.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H3><A NAME="TheG_ARRAYFlag"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">G_ARRAY</FONT></B></TT><B><FONT SIZE=4>
Flag</FONT></B></A></H3>
<P>
Set this flag when you want to return a list from the called Perl
subroutine. This flag causes the Perl subroutine to be called
in a list context. <TT><FONT FACE="Courier">0</FONT></TT> is returned
when the <TT><FONT FACE="Courier">G_DISCARD</FONT></TT> flag is
specified along with this flag. If the <TT><FONT FACE="Courier">G_DISCARD</FONT></TT>
flag is not specified, the number of items on the stack is returned.
This number is usually the number of items the calling routine
pushed on the stack when making the function call; however, the
number of items could be different if the called subroutine has
somehow manipulated the stack internally. If <TT><FONT FACE="Courier">G_ARRAY</FONT></TT>
was specified and the returned value is <TT><FONT FACE="Courier">0</FONT></TT>,
an error has occurred in the called routine.
<H3><A NAME="TheG_EVALFlag"><B>The </B><TT><B><FONT SIZE=4 FACE="Courier">G_EVAL</FONT></B></TT><B><FONT SIZE=4>
Flag</FONT></B></A></H3>
<P>
The called subroutine might crash while processing bogus input
parameters. It's possible to trap an abnormal termination by specifying
the <TT><FONT FACE="Courier">G_EVAL</FONT></TT> statement. The
net effect of this flag is to put the called subroutine in an
evaluated block from which it's possible to trap all but the more
shameful errors. Whenever control returns from the function, you
have to check the contents of the <TT><FONT FACE="Courier">$@</FONT></TT>
variable for any possible error messages. Remember that any anomaly
can set the contents of <TT><FONT FACE="Courier">$@</FONT></TT>,
so check the value as soon as you return from a subroutine call.
<P>
The value returned from the <TT><FONT FACE="Courier">perl_call_*</FONT></TT>
function is dependent on what other flags have been specified
and whether an error has occurred. Here are all the different
cases that can occur: If an error occurs when a <TT><FONT FACE="Courier">G_SCALAR</FONT></TT>
is specified, the value on top of the stack will be <TT><FONT FACE="Courier">undef</FONT></TT>.
The value of <TT><FONT FACE="Courier">$@</FONT></TT> will also
be set. Just remember to pop the <TT><FONT FACE="Courier">undef</FONT></TT>
from the stack.