PerlEz - Perl Host DLL

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.

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.

PerlEzCreate

 PERLEZHANDLE PerlEzCreate(LPCSTR lpFileName, LPCSTR lpOptions);
DESCRIPTION:
  • 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.

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

  • 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.

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

    See also PerlEzDelete PerlEzCreateOpt

    • PerlEzCreateOpt

     PERLEZHANDLE PerlEzCreateOpt(LPCSTR lpFileName, LPCSTR lpOptions, LPCSTR lpScriptOpts);
    DESCRIPTION:
  • 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.

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

  • 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.

  • 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.

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

    See also PerlEzDelete PerlEzCreate

    • PerlEzDelete

     BOOL PerlEzDelete(PERLEZHANDLE hHandle);
    DESCRIPTION:
  • Deletes a previously created Perl interpreter. Releases all resources allocated by PerlEzCreate or PerlEzCreateOpt.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

    RETURNS:
  • True if no error false otherwise.

    • PerlEzEvalString

     int PerlEzEvalString(PERLEZHANDLE hHandle, LPCSTR lpString, LPSTR lpBuffer, DWORD dwBufSize);
    DESCRIPTION:
  • Evaluates the string a returns the result in lpBuffer. If there is an error $! is returned in lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpString a pointer to the ASCIIZ string to evaluate

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

  • dwBufSize the size in bytes of the space where lpBuffer points

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall1

     int PerlEzCall1(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, LPVOID lpVoid);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

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

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

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

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall2

     int PerlEzCall2(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
  LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

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

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

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

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall4

     int PerlEzCall4(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

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

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

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

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall8

     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);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

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

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

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

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall

     int PerlEzCall(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, ...);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

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

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • ... parameters to be interpreted based on lpFormat

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCallContext

     int PerlEzCallContext(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPVOID lpContextInfo,
   LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, ...);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpContextInfo context info for magic fetch and store functions

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

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • ... parameters to be interpreted based on lpFormat

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzSetMagicScalarFunctions

     int PerlEzSetMagicScalarFunctions(PERLEZHANDLE hHandle, LPFETCHVALUEFUNCTION lpfFetch,
                LPSTOREVALUEFUNCTION lpfStore);
    DESCRIPTION:
  • Sets the call back function pointers for magic scalar variables.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

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

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

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes NOTE: if lpfFetch and lpfStore are both NULL, then it is an error.

    See also PerlEzSetMagicScalarName

    • PerlEzSetMagicScalarName

     int PerlEzSetMagicScalarName(PERLEZHANDLE hHandle, LPCSTR pVariableName);
    DESCRIPTION:
  • Creates the variable if it does not exists and sets it to be tied to the call back function pointer for magic variables.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • pVariableName a pointer to the name of the variable.

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    See also PerlEzSetMagicScalarFunctions

    • Format String

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

    s
  • this parameter is a pointer to a null terminated string.

    i
  • this parameter is to be considered an integer.

    d
  • this parameter is to be considered a double.

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

    • Error Codes

    1. More space is needed to return a result

    2. Error string returned in the buffer

    3. More space needed to return the error message

    4. Format string is invalid

    5. Function call caused an exception

    6. Handle is invalid

    7. The second call to PerlEzSetMagicFunction failed

    8. Invalid parameter was passed to the routine

    9. Cannot allocate more memory

    Authors

    This document is maintained by Douglas Lankshear <dougl@ActiveState.com>