>> << Ndx Usr Pri Phr Dic Rel Voc !: wd Help User

# Calling J.DLL

The J DLL can be called by any program that can call DLLs.

Since J.DLL is itself used by the J session, you need to make a copy of J.DLL first before calling it from J; for example, copy it to file JJ.DLL.

File system\examples\data\jdll.h. gives C prototypes for J procedures.

Script system\examples\dll\jdll.ijs. gives examples of calling the J DLL from J.

Use procedure JDo to execute a sentence. For example, the following writes text `abc` to file t1.txt:

       load 'dll files'
       cmd=: '''abc'' 1!:2 <''t1.txt'''     NB. example sentence
       'jj.dll JDo i *c' cd <cmd            NB. send to J DLL
    +-+--------------------+
    |0|'abc' 1!:2 <'t1.txt'|
    +-+--------------------+
    fread 't1.txt'                          NB. check file was written
    abc

Use procedure JGetM to retrieve a J variable. The `cd` right argument is a name, followed by 4 pointers, which will correspond to the result datatype, rank, pointer to shape, and pointer to values. For example:

       'jj.dll JDo i *c' cd <'ABC=: i.5'   NB. define ABC
    +-+---------+
    |0|ABC=: i.5|
    +-+---------+

       'jj.dll JGetM i *c *i *i *i *i' cd 'ABC';4#<,0
    +-+---+-+-+--------+--------+
    |0|ABC|4|1|13496196|13496500|
    +-+---+-+-+--------+--------+

The 6 items in the result are: error code (`0`=success), name, datatype (`4`=integer), rank(`1`), pointer to shape, and pointer to values.

The pointers refer to memory addresses within the J DLL. You should reference their values before calling the J DLL again, as further calls may invalidate the memory addresses. Use function `memr` to read memory and and `ic` to convert to J integers. For example, the shape is:

       _2 ic memr 13496196 0 4
    5

Once the result datatype and shape are known, you can read the values, again using `memr`, and convert to a J variable.

File system\examples\dll\jdll.ijs defines functions that perform the necessary conversions. For example:

       load 'system\examples\dll\jdll.ijs'
       jdo 'ABC=: i.3 4'
    +-+-----------+
    |0|ABC=: i.3 4|
    +-+-----------+

       jget 'ABC'
    0 1  2  3
    4 5  6  7
    8 9 10 11

       jcmd 'q: 123456'
    2 2 2 2 2 2 3 643

>> << Ndx Usr Pri Phr Dic Rel Voc !: wd Help User