Special Considerations When Using External DLLs

Because the SAS language does not provide pointers as data types, you must use the PIB4. format and informat to represent pointers. You can then use the SAS PEEKLONG functions to access the data stored at these address values.

For example, suppose you have a routine named GetPath in a library named SERVICES.DLL. It has two arguments, an integer function code and a pointer to a pointer. The function code determines what action GetPath takes, and the second argument points to a pointer that is updated by GetPath to refer to a system character string. The calling code in C might be

GetPath(1,&stgptr);
printf("GetPath indicates string is
   '%s'.\n",stgptr);

Using MODULE, the corresponding attribute table entry would be

ROUTINE GetPath MINARG=2 MAXARG=2
  MODULE=SERVICES;
ARG 1 NUM INPUT BYVALUE FORMAT=PIB4.;
ARG 2 NUM OUTPUT BYADDR FORMAT=PIB4.;

and could be invoked as follows:

call module('GetPath',1,stgptr);
put stgptr= stgptr=hex8.;

If the pointer value in STGPTR is 0035F780, STGPTR would actually be set to the decimal value 3536768, which is the decimal equivalent of 0035F780. So the PUT statement above would produce:

STGPTR=3536768 STGPTR=0035F780

However, you want the data at address 0035F780, not the value of the pointer itself. To access that data, you need to use the PEEKCLONG function.

The PEEKCLONG function is given two arguments, a pointer via a numeric variable (such as STGPTR above) and a length in bytes (characters). PEEKCLONG returns a character string of the specified length containing the characters at the pointer location.

In the example, suppose that GetPath sets the second argument's pointer value to the address of the null-terminated character string C:\XYZ. You can access the character data with:

call module('SERVICES,GetPath',1,stgptr);
length path $64;
path = peekclong(stgptr,64);
i = index(path,'00'x);
if i then substr(path,i)=' ';
/* path now contains the string */

The PEEKCLONG function copies 64 bytes starting at the location referred to by the pointer in STGPTR. Because you need only the data up to the null terminator (but not including it), you search for the null terminator with the INDEX function. Then you need to blank out all characters including and after that point.

You can also use the $CSTR format in this scenario to simplify your code slightly:

call module('SERVICES,GetPath',1,stgptr);
length path $64;
path = put(peekclong(stgptr,64),$cstr64.);

The $CSTR format accepts as input a character string of a specified width. It looks for a null terminator and pads the output string with blanks from that point.

For more information, see the PEEKLONG Function in SAS Functions and CALL Routines: Reference .

The MODULE routine reads the attribute table referenced by the SASCBTBL fileref once per step (DATA step, PROC IML step, or SCL step). MODULE parses the table and stores the attribute information for future use during the step. When you use a MODULE function, SAS searches the stored attribute information for the matching routine and module names. The first time you access a DLL during a step, SAS loads the DLL, and determines the address of the requested routine. Each DLL that you invoke stays loaded for the duration of the step, and is not reloaded in subsequent calls. All modules and routines are unloaded at the end of the step. For example, suppose the attribute table had the basic form:

* routines XYZ and BBB in FIRST.DLL;
ROUTINE XYZ MINARG=1 MAXARG=1 MODULE=FIRST;
ARG 1 NUM INPUT;
ROUTINE BBB MINARG=1 MAXARG=1 MODULE=FIRST;
ARG 1 NUM INPUT;
* routines ABC and DDD in SECOND.DLL;
ROUTINE ABC MINARG=1 MAXARG=1 MODULE=SECOND;
ARG 1 NUM INPUT;
ROUTINE DDD MINARG=1 MAXARG=1 MODULE=SECOND;
ARG 1 NUM INPUT;

and the DATA step looked like:

filename sascbtbl 'myattr.tbl';
data _null_;
   do i=1 to 50;
      /* FIRST.DLL is loaded only once */
      value = modulen('XYZ',i);
      /* SECOND.DLL is loaded only once */
      value2 = modulen('ABC',value);
      put i= value= value2=;
   end;
run;

In this example, MODULEN parses the attribute table during DATA step compilation. In the first loop iteration (i=1), FIRST.DLL is loaded and the XYZ routine is accessed when MODULEN calls for it. Next, SECOND.DLL is loaded and the ABC routine is accessed. For subsequent loop iterations (starting when i=2), FIRST.DLL and SECOND.DLL remain loaded, so the MODULEN function simply accesses the XYZ and ABC routines. SAS unloads both DLLs at the end of the DATA step.

Note that the attribute table can contain any number of descriptions for routines that are not accessed for a given step. This process does not cause any additional overhead (apart from a few bytes of internal memory to hold the attribute descriptions). In the above example, BBB and DDD are in the attribute table but are not accessed by the DATA step.

A common need when calling external routines are to pass a pointer to a structure. Some parts of the structure might be used as input to the routine. Other parts might be replaced or filled in by the routine. Even though SAS does not have structures in its language, you can indicate to MODULE that you want a particular set of arguments grouped into a single structure. You indicate this structure by using the FDSTART option of the ARG statement to flag the argument that begins the structure in the attribute table. SAS gathers that argument and data (until encountering another FDSTART option) into a single contiguous block, and passes a pointer to the block as an argument to the DLL routine.

For example, consider the GetClientRect routine, which is part of the Win32 API in USER32.DLL. This routine retrieves the coordinates of a window's client area. This process also requires the use of another routine, GetForegroundWindow, to get the window handle for the window that you want the coordinates from.

The C prototypes for these routines are

HWND GetForegroundWindow(VOID);
BOOL GetClientRect(HWND hWnd, LPRECT lprc);

In C, the code to invoke them is:

typedef struct tagRECT {
    int left;
    int top;
    int right;
    int bottom;
    } RECT;
  /* RECT is a structure variable */
....                  /* other code */
/* Need the window handle first */
hWnd=GetForegroundWindow();
/* Function call, passing the address */
/* of RECT                            */
GetClientRect(hWnd, &RECT);

To call these routines using MODULE, you would use the following attribute table entries:

routine GetForegroundWindow
  minarg=0
  maxarg=0
  stackpop=called
  module=USER32
  returns=long;
routine GetClientRect
  minarg=5
  maxarg=5
  stackpop=called
  module=USER32;
arg 1 num input byvalue format=pib4.;
arg 2 num update fdstart format=ib4.;
arg 3 num update         format=ib4.;
arg 4 num update         format=ib4.;
arg 5 num update         format=ib4.;

with the following DATA step:

filename sascbtbl 'sascbtbl.dat';
data _null_;
  hwnd=modulen('GetForegroundWindow');
  call module('GetClientRect',hwnd,left,
       top,right,bottom);
  put left= top= right= bottom=;
run;

The use of the FDSTART option in the ARG statement for argument 2 indicates that argument 2 and all subsequent arguments are gathered into a single parameter block.

The output in the log from the PUT statement would look like:

LEFT=2 TOP=2 RIGHT=400 BOTTOM=587

You can pass any type of expression as an argument to the MODULE functions. The attribute table indicates whether the argument is for input, output, or update.

You can specify input arguments as constants and arithmetic expressions. However, because output and update arguments must be able to be modified and returned, you can pass only a variable for these parameters. If you specify a constant or expression where a value that can be updated is expected, SAS issues a warning message pointing out the error. Processing continues, but the MODULE routine cannot update a constant or expression argument (meaning that the value of the argument that you wanted to update is lost).

Consider these examples. Here is the attribute table:

* attribute table entry for ABC;
routine abc minarg=2 maxarg=2;
arg 1 input format=ib4.;
arg 2 output format=ib4.;

Here is the DATA step with the MODULE calls:

data _null_;
  x=5;
  /* passing a variable as the    */
  /*   second argument - OK       */
  call module('abc',1,x);
  /* passing a constant as the    */
  /*   second argument - INVALID  */
  call module('abc',1,2);
  /* passing an expression as the */
  /*   second argument - INVALID  */
  call module('abc',1,x+1);
run;

In the above example, the first call to MODULE is correct because the variable x is updated with what the abc routine returns for the second argument. The second call to MODULE is not correct because a constant is passed. MODULE issues a warning indicating you have passed a constant, and MODULE passes a temporary area instead. The third call to MODULE is not correct as an arithmetic expression is passed, causing a temporary location from the DATA step to be used. The returned value is lost.

If you specify i in the control string parameter to MODULE, SAS prints several informational messages to the log. You can use these messages to determine whether you have passed incorrect arguments or coded the attribute table incorrectly.

Consider this example that uses MODULEIN from within the IML procedure. It uses the MODULEIN function to invoke the changi routine (stored in theoretical TRYMOD.DLL). In the example, MODULEIN passes the constant 6 and the matrix x2, which is a 4x5 matrix to be converted to an integer matrix. The attribute table for changi is as follows:

routine changi module=trymod returns=long;
arg 1 input num format=ib4. byvalue;
arg 2 update num format=ib4.;

The following IML step invokes MODULEIN:

proc iml;
     x1 = J(4,5,0);
     do i=1 to 4;
        do j=1 to 5;
           x1[i,j] = i*10+j+3;
           end;
        end;
     y1= x1;
             x2 = x1;
                      y2 = y1;
     rc = modulein('*i','changi',6,x2);
     ....

The '*i' control string causes the lines shown in MODULEIN Output to be printed in the log.

---PARM LIST FOR MODULEIN ROUTINE---  CHR PARM 1 885E0AA8 2A69 (*i)
CHR PARM 2 885E0AD0 6368616E6769 (changi)
NUM PARM 3 885E0AE0 0000000000001840
NUM PARM 4 885E07F0
0000000000002C400000000000002E40000000000000304000000000000031400000000000003240
000000000000384000000000000039400000000000003A400000000000003B400000000000003C40
0000000000004140000000000080414000000000
---ROUTINE changi LOADED AT ADDRESS 886119B8 (PARMLIST AT 886033A0)--- PARM 1
06000000     <CALL-BY-VALUE>
PARM 2 88604720
0E0000000F00000010000000110000001200000018000000190000001A0000001B0000001C000000
22000000230000002400000025000000260000002C0000002D0000002E0000002F00000030000000
---VALUES UPON RETURN FROM changi ROUTINE---   PARM 1 06000000    
<CALL-BY-VALUE>
PARM 2 88604720
140000001F0000002A0000003500000040000000820000008D00000098000000A3000000AE000000
F0000000FB00000006010000110100001C0100005E01000069010000740100007F0100008A010000
---VALUES UPON RETURN FROM MODULEIN ROUTINE---  NUM PARM 3 885E0AE0
0000000000001840
NUM PARM 4 885E07F0
00000000000034400000000000003F4000000000000045400000000000804A400000000000005040
00000000004060400000000000A06140000000000000634000000000006064400000000000C06540
0000000000006E400000000000606F4000000000

The output is divided into four sections.