>>  <<  Usr  Pri  JfC  LJ  Phr  Dic  Rel  Voc  !:  Help  User

Calling Procedures in Dynamic-link Libraries (DLLs)

Calling procedures incorrectly can crash your system or corrupt memory.

J can call procedures that are compiled in a shared library file. In Windows these files are called DLLs (dynamic link libraries) and have a .dll extension. In Linux they are called shared libraries or shared objects and have a .so extension. In Mac they are called dynamic libraries and have a .dylib extension. The term DLL is used here for all platforms. A procedure in a DLL is called by its name and filename.

J can also call a procedure in memory directly with its address.

J can also call a procedure in an object with the object address and the procedure index.

Calling procedures from J is the same across platforms.

To learn how to call DLLs, run Labs 'DLL: Writing and Using a DLL' and 'DLL: Using System DLLs (file examples)'. These labs are for Windows.

Script main\dll.ijs ( load 'dll' ) defines utilities for working with DLLs.

Verb cd calls a procedure. The form is:
   'filename procedure [>][+][%] declaration' cd parameters

filename is usually the name of a DLL. The search path for finding a filename that is not fully qualified involves many directories and is different on each platform. Except for system DLLs, a fully qualified filename is recommended.

A filename of 0 indicates procedure is a memory address (J display of a J signed integer with _ as the negative sign).

A filename of 1 indicates procedure is a non-negative integer that is the index of a procedure in a vtable (list of procedure addresses). The first paramter is the 'object address' and is the address of the address of the vtable. The declaration of the first parameter must be * or x .

procedure is usually the case-sensitive name of the procedure in the DLL to call. A Windows procedure can be identified by a number specified as # followed by digits. Win32 API procedures that take string parameters are documented under a name, but are implemented under the name with an A suffix for 8 bit characters and a W suffix for 16 bit characters. For example, CreateFile is documented, but the procedures you call are CreateFileA or CreateFileW. If filename is 0 or 1, procedure is treated as discussed in the filename section.

A procedure returns a scalar result and takes 0 or more parameters. Parameters are passed by value or by a pointer to values. Pointer parameters can be read and set.

> option returns a scalar result. Without > the result is the boxed scalar result appended to the boxed arguments.

+ option selects the alternate calling convention. The calling convention is the rules for how the result and parameters are passed between the caller and the procedure. Using the wrong one can crash or corrupt memory. On Windows standard is __stdcall and + selects __cdecl. On Unix + currently has no effect, but should be avoided as this may change in future releases.

% option does an fpreset (floating-point state reset) after the call. Some procedures leave floating-point in an invalid state that causes a crash at some later time.

declaration is a set of blank delimited codes describing result and parameter types:

c  J character (1 byte)
w  J literal2 (2 byte) (see u:)
u  J literal4 (4 byte) (see u:)
s  short integer (2 byte)
i  integer (4 byte)
l  long integer (8 byte)
x  J integer (4 byte or 8 byte depending on 32/64)
f  short float (4 byte)
d  J float (8 byte)
j  J complex (16 byte - 2 d values) (pointer only, not as result or scalar)
*  pointer
n  no result (result, if any, is ignored and 0 is returned)

The first declaration type describes the result and the remaining ones describe the parameters in the cd right argument. Arguments are converted as required to conform with their declaration type.

The c w u x d j types are native J types. In J32 (32 bit) the i type is the same as x and the l type is an error. In J64 (64bit) the l type is the same as x and the i type is handled similarly to s.

A scalar type (c w u s i l x f d j) must have a scalar parameter of the right type. Scalar s i l values take a J integer and f values take a J float.

The * type is a pointer to values. A * can be followed by c w u s i l x f d or j to indicate the type of values. The DLL can read or write this memory.

A pointer type parameter must be an array with rank > 1 of the right type, or a scalar boxed scalar integer that is a memory address.

A J integer list used for *s is converted in place to shorts before calling the dll and is converted back after the call. A J integer list used for *i on J64 is converted in place to 4 bytes and then back. A J float list used for a *f is converted in place to short floats and then back.

A *s and *f also allow a character list with a count that is evenly divisible respectively by 2 and 4.

J doesn't have unsigned types so DLL unsigned type values with the top bit on are returned to J as negative values.

The mema result (Memory Management) can be used as a * type parameter. A memory address parameter is a boxed scalar. The NULL pointer is <0 .

The cd right argument is a list of enclosed parameters. If the argument is not boxed, it is  treated as if <"0 were applied.

cd is rank 1. Its result, without the > option, is the procedure result catenated with its possibly modified right argument. With the > option the result is the procedure scalar result.

For example, the Win32 API procedure GetProfileString in kernel32 gets the value of the windows/device keyword.
   a=: 'kernel32 GetProfileStringA s *c *c *c *c s'
   b=: 'windows';'device'; 'default'; (32$'z');32
   a cd b
+--+-------+------+-------+--------------------------------+--+
|31|windows|device|default|HP LaserJet 4P/4MP,HPPCL5MS,LPT |32|
+--+-------+------+-------+--------------------------------+--+

The first type s indicates that the procedure returns a short integer. The first pointer names a section. The second pointer names a keyword. The third pointer is the default if the keyword is not found. The fourth parameter is where the keyword text is put. The fifth parameter is the length of the fourth parameter.

If the GetProfileStringA declaration was wrong, say a d result instead of s, it would crash your system. If the fifth parameter was 64 and the keyword was longer than the 32 characters allocated by the fourth parameter, the extra data would overwrite memory.

Procedures are usually documented with a C prototype or a Visual Basic declaration. The C prototype and VB declaration for GetProfileString are:
DWORD GetProfileString(
LPCTSTR lpAppName, // address of section name
LPCTSTR lpKeyName, // address of key name
LPCTSTR lpDefault, // address of default string
LPTSTR lpReturnedString,// address of destination buffer
DWORD nSize // size of destination buffer
);

Declare Function GetProfileString Lib "kernel32"
Alias GetProfileStringA"
ByVal lpAppName As String,
ByVal lpKeyName As String,
ByVal lpDefault As String,
ByVal lpReturnedString As String,
ByVal nSize As Long)
As Long

J declaration types and some corresponding C and VB types are:
c  char, byte, bool
s  short, short int, word, %
i  int, dword
f  float, !
d  double, #
*c char*, int*, LP..., void*, $
n  void

cdf'' unloads all DLLs that cd has loaded. A loaded DLL is in use and attempts to modify it will fail. If you are developing and testing a DLL you must run cdf'' before you can build and save a new version.
>>  <<  Usr  Pri  JfC  LJ  Phr  Dic  Rel  Voc  !:  Help  User