TECHNICAL BULLETIN #78 - Rev 1.10 (9/03/96) ============================================================================== TITLE : DLLs and ASPECT: C Language Specifications PRODUCT : Procomm Plus 4.x, 3.x ============================================================================== Procomm Plus for Windows implements a powerful scripting language called the Windows ASPECT Script Language (ASPECT). One of ASPECT's strengths is the ability to call functions embedded in Dynamic Link Libraries (DLLs) written and compiled outside of ASPECT. This document focuses on writing DLLs for ASPECT in the C language. ASPECT TO DLL PARAMETER SEQUENCE ASPECT generates a standard parameter block for every DLL call that it makes. This standard parameter block has five parameters, listed in order below. When writing a DLL to be called from ASPECT, every exported function that is to be accessible from within ASPECT should declare these parameters: 1. [HWND] - a handle to the Procomm Plus main window. 2. [HANDLE] - a handle to the instance of Procomm Plus that made the DLL call. 3. [void far * far *] - a far array of far pointers to the data elements listed as parameters on the ASPECT script line that called the DLL function. 4. [LPBYTE] - a far array of bytes. Byte N of this array describes the type of element N stored in the array of data elements (e.g., parameter 3). The range of values in this array follows this scheme: Byte Value Meaning ========== ======= 0 nth element is an ASPECT string 1 nth element is an ASPECT integer 2 nth element is an ASPECT long 3 nth element is an ASPECT float 5. [int] - an integer containing the count of parameters provided on the ASPECT script line calling the DLL function. AN EXAMPLE DLL Here is the code for a DLL that generates a random number. Under a PASCAL style, stack-based parameter passing scheme, a variable number of parameters is not normally possible. However, ASPECT provides an array-based parameter passing scheme as described by the parameter block above. To demonstrate the ability to pass a variable number of parameters, the DLL function listed below makes certain assumptions about the provided parameters based on the number of parameters that are available: 1. If two parameters are passed to the DLL function, the first parameter holds a number for seeding the random-number generator and the second parameter will hold the return value (i.e. the random number). 2. If one parameter is passed to the DLL function, the DLL function should seed the random number generator using the GetCurrentTime() function from the Windows API and the parameter will hold the return value (i.e. the random number). SAMPLE DLL: RANDINT.C #include #include #define IntegerType 1 int FAR PASCAL LibMain( HANDLE, WORD, WORD, LPSTR ); int FAR PASCAL RandomInt( HWND, HANDLE, void far * far *, LPBYTE, int ); int FAR PASCAL WEP( int ); HANDLE hInst; int FAR PASCAL LibMain( HANDLE hInstance, WORD wDataSeg, WORD cbHeapSize, LPSTR lpszCmdLine ) { if (cbHeapSize) UnlockData(0); /* make the data segment moveable */ hInst = hInstance; return(TRUE); } int FAR PASCAL RandomInt( HWND PWWnd, HANDLE PWInst, void far * far *vdatptr, LPBYTE vtypeptr, int argcnt ) { if ( argcnt < 1 ) /* at least one argument? */ return( FALSE ); /* if not, return FAILURE */ if ( vtypeptr[0] != IntegerType ) /* is first arg an integer? */ return( FALSE ); /* if not, return FAILURE */ if ( argcnt > 1 ) { /* more arguments? */ if ( vtypeptr[1] != IntegerType ) /* is second arg an integer? */ return( FALSE ); /* if not, return FAILURE */ srand( *(int far *)vdatptr[0] ); /* seed the generator with arg */ *(int far *)vdatptr[1] = rand(); /* get a random number */ } else { srand( (unsigned)GetCurrentTime() );/* seed the generator with time */ *(int far *)vdatptr[0] = rand(); /* get a random number */ } return( TRUE ); /* return SUCCESS to ASPECT */ } int FAR PASCAL WEP( int bSystemExit ) { return(TRUE); } SAMPLE PROJECT DEFINITION FILE: RANDINT.DEF LIBRARY RandInt CODE MOVEABLE DISCARDABLE DATA SINGLE MOVEABLE HEAPSIZE 2048 EXPORTS WEP @1 RandomInt @2 SAMPLE ASPECT SCRIPT: RANDINT.WAS ;ASPECT script demonstrating RANDINT.DLL integer hdll, rNum proc cleanup dllfree hdll exit endproc proc main string DLLPATH = "C:\PROWIN\ASPECT\RANDINT.DLL" ;path to the DLL when userexit call cleanup ;point to cleanup routine dllload DLLPATH hdll ;load the DLL if (failure) usermsg "dllload failed" exit endif ;generate a random number letting the DLL use system time as seed dllcall hdll "RandomInt" rNum if (failure) usermsg "RandomInt call with system time seed failed" cleanup() else usermsg "RandomInt with system time seed returned %d" rNum endif ;generate a random number with the seed 65 dllcall hdll "RandomInt" 65 rNum if (failure) usermsg "RandomInt call with seed 65 failed" cleanup() else usermsg "RandomInt with seed 65 returned %d" rNum endif cleanup() endproc ============================================================================== To ensure that you have the latest version of this document, compare its revision number to that of the same document on any of our support sites. This technical bulletin may be copied and distributed freely as long as it is distributed in its entirety and it is not distributed for profit. Copyright (c) 1996 Quarterdeck All rights reserved. ==============================================================================