=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 L =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 L =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 =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 =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 =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 =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 =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 =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 =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 =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 =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 =item * ... parameters to be interpreted based on lpFormat =item RETURNS: =item * A zero if no error; otherwise error code. See L =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 =item * ... parameters to be interpreted based on lpFormat =item RETURNS: =item * A zero if no error; otherwise error code. See L =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 NOTE: if lpfFetch and lpfStore are both NULL, then it is an error. See also L =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 See also L =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