windows-server-2003/tools/perl/site/lib/pod/perlez.pod

=head1 NAME

PerlEz - PerlEz host DLL

=head1 DESCRIPTION

This document attempts to describe the functions of the PerlEz host Dynamically
Linked Library (DLL). Please refer any questions or comments to the author below.

=head2 Datatypes

PerlEz has one specific data type, PERLEZHANDLE; this is a non-zero handle to
a Perl interpreter that is created and can be accessed by the routines described below.

=head2 PerlEzCreate

=over 

 PERLEZHANDLE PerlEzCreate(LPCSTR lpFileName, LPCSTR lpOptions);

=item DESCRIPTION:

=item *

Creates a Perl interpreter. The return value is required parameter for all subsequent �PerlEz� calls.
Multiple interpreters can be created, but only one will be executing at a time.

=item PARAMS:

=item *

lpFileName a pointer to a ASCIIZ string that is the name of a file; can be NULL 

=item *

lpOptions a pointer to a ASCIIZ string that are the command line options that
will be provided before the script; can be NULL. This parameter is used for setting @INC or debugging. 

=item RETURNS:

=item *

A non zero handle to a Perl interpreter if successful; zero otherwise. Call PerlEzDelete to release this handle.

See also L</PerlEzDelete> L</PerlEzCreateOpt>

=back

=head2 PerlEzCreateOpt

=over 

 PERLEZHANDLE PerlEzCreateOpt(LPCSTR lpFileName, LPCSTR lpOptions, LPCSTR lpScriptOpts);

=item DESCRIPTION:

=item *

Creates a Perl interpreter. The return value is required parameter for all subsequent �PerlEz� calls.
Multiple interpreters can be created, but only one will be executing at a time.

=item PARAMS:

=item *

lpFileName a pointer to a ASCIIZ string that is the name of a file; can be NULL 

=item *

lpOptions a pointer to a ASCIIZ string that are the command line options that
will be provided before the script; can be NULL. This parameter is used for setting @INC or debugging. 

=item *

lpScriptOpts a pointer to a ASCIIZ string that are the command line options that
will be provided as parameters to the script; can be NULL.

=item RETURNS:

=item *

A non zero handle to a Perl interpreter if successful; zero otherwise. Call PerlEzDelete to release this handle.

See also L</PerlEzDelete> L</PerlEzCreate>

=back

=head2 PerlEzDelete

=over 

 BOOL PerlEzDelete(PERLEZHANDLE hHandle);

=item DESCRIPTION:

=item *

Deletes a previously created Perl interpreter. Releases all resources allocated by PerlEzCreate or PerlEzCreateOpt.

=item PARAMS:

=item *

hHandle	a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item RETURNS:

=item *

True if no error false otherwise.

=back

=head2 PerlEzEvalString

=over 

 int PerlEzEvalString(PERLEZHANDLE hHandle, LPCSTR lpString, LPSTR lpBuffer, DWORD dwBufSize);

=item DESCRIPTION:

=item *

Evaluates the string a returns the result in lpBuffer. If there is an error $! is returned in lpBuffer.

=item PARAMS:

=item *

hHandle	a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

lpString a pointer to the ASCIIZ string to evaluate

=item *

lpBuffer a pointer to the buffer where the result will be placed

=item *

dwBufSize the size in bytes of the space where lpBuffer points

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">

=back

=head2 PerlEzCall1

=over

 int PerlEzCall1(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, LPVOID lpVoid);

=item DESCRIPTION:

=item *

Calls the function lpFunction and returns the result in the buffer lpBuffer.

=item PARAMS:

=item *

hHandle	a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

lpFunction a pointer name of the function to call

=item *

lpBuffer a pointer to the buffer where the result will be placed

=item *

dwBufSize the size in bytes of the space where lpBuffer points

=item *

lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">

=item *

lpVoid a pointer to a parameter will be interpreted based on lpFormat

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">

=back

=head2 PerlEzCall2

=over 

 int PerlEzCall2(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
  LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2);

=item DESCRIPTION:

=item *

Calls the function lpFunction and returns the result in the buffer lpBuffer.

=item PARAMS:

=item *

hHandle	a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

lpFunction a pointer name of the function to call

=item *

lpBuffer a pointer to the buffer where the result will be placed

=item *

dwBufSize the size in bytes of the space where lpBuffer points

=item *

lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">

=item *

lpVoid1...2 pointers to parameters that will be interpreted based on lpFormat

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">

=back

=head2 PerlEzCall4

=over

 int PerlEzCall4(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4);

=item DESCRIPTION:

=item *

Calls the function lpFunction and returns the result in the buffer lpBuffer.

=item PARAMS:

=item *

hHandle	a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

lpFunction a pointer name of the function to call

=item *

lpBuffer a pointer to the buffer where the result will be placed

=item *

dwBufSize the size in bytes of the space where lpBuffer points

=item *

lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">

=item *

lpVoid1...4 pointers to parameters that will be interpreted based on lpFormat

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">

=back 

=head2 PerlEzCall8

=over

 int PerlEzCall8(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4, LPVOID lpVoid5,
   LPVOID lpVoid6, LPVOID lpVoid7, LPVOID lpVoid8);

=item DESCRIPTION:

=item *

Calls the function lpFunction and returns the result in the buffer lpBuffer.

=item PARAMS:

=item *

hHandle	a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

lpFunction a pointer name of the function to call

=item *

lpBuffer a pointer to the buffer where the result will be placed

=item *

dwBufSize the size in bytes of the space where lpBuffer points

=item *

lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">

=item *

lpVoid1...8 pointers to parameters that will be interpreted based on lpFormat

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">

=back

=head2 PerlEzCall

=over

 int PerlEzCall(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, ...);

=item DESCRIPTION:

=item *

Calls the function lpFunction and returns the result in the buffer lpBuffer.

=item PARAMS:

=item *

hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

lpFunction a pointer name of the function to call

=item *

lpBuffer a pointer to the buffer where the result will be placed

=item *

dwBufSize the size in bytes of the space where lpBuffer points

=item *

lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">

=item *

... parameters to be interpreted based on lpFormat

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">

=back

=head2 PerlEzCallContext

=over

 int PerlEzCallContext(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPVOID lpContextInfo,
   LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, ...);

=item DESCRIPTION:

=item *

Calls the function lpFunction and returns the result in the buffer lpBuffer.

=item PARAMS:

=item *

hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

lpFunction a pointer name of the function to call

=item *

lpContextInfo context info for magic fetch and store functions

=item *

lpBuffer a pointer to the buffer where the result will be placed

=item *

dwBufSize the size in bytes of the space where lpBuffer points

=item *

lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">

=item *

... parameters to be interpreted based on lpFormat

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">

=back

=head2 PerlEzSetMagicScalarFunctions

=over 

 int PerlEzSetMagicScalarFunctions(PERLEZHANDLE hHandle, LPFETCHVALUEFUNCTION lpfFetch,
		LPSTOREVALUEFUNCTION lpfStore);

=item DESCRIPTION:

=item *

Sets the call back function pointers for magic scalar variables.

=item PARAMS:

=item *

hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

lpfFetch a pointer to the call back function for fetching a string. 
if lpfFetch is NULL, then the scalar is write only.

=item *

lpfStore a pointer to the call back function for storinging a string.
if lpfStore is NULL, then the scalar is read only.

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">
NOTE: if lpfFetch and lpfStore are both NULL, then it is an error.

See also L</PerlEzSetMagicScalarName>

=back

=head2 PerlEzSetMagicScalarName

=over 

 int PerlEzSetMagicScalarName(PERLEZHANDLE hHandle, LPCSTR pVariableName);

=item DESCRIPTION:

=item *

Creates the variable if it does not exists and sets it to be tied to
the call back function pointer for magic variables.

=item PARAMS:

=item *

hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

=item *

pVariableName a pointer to the name of the variable.

=item RETURNS:

=item *

A zero if no error; otherwise error code. See L</"Error Codes">

See also L</PerlEzSetMagicScalarFunctions>

=back

=head2 Format String

=over

The format string is a series of characters that represents the type of parameters being supplied.

=item s

=item *

this parameter is a pointer to a null terminated string.

=item i

=item *

this parameter is to be considered an integer.

=item d

=item *

this parameter is to be considered a double.

=item l[s | i | d]x

=item *

the next 'x' parameters will be put into an anonymous list of the type specifed. Either 's', 'i', or 'd' 

=back

=head2 Error Codes

=over

=item 1

More space is needed to return a result

=item 2

Error string returned in the buffer

=item 3

More space needed to return the error message

=item 4

Format string is invalid

=item 5

Function call caused an exception

=item 6

Handle is invalid

=item 7

The second call to PerlEzSetMagicFunction failed

=item 8

Invalid parameter was passed to the routine

=item 9

Cannot allocate more memory

=back

=head1 AUTHORS

This document is maintained by Douglas Lankshear <[email protected]>