DLL: run-time dynamic linking (H+)

• • DLL(Name=your_DLL_name, Fncname=function_name_in_DLL [, Argument=arg1 [, A=arg2... , A=argN ]] )
  • or
  • DLL(Name=your_DLL_name, Subname=subroutine_name_in_DLL [, Argument=arg1 [, A=arg2... , A=argN ]] )
• any number of numeric or string arguments arg1, ..., argN is allowed
• for an interactive example run Tutorial.hic / DLL

  Keyword	type	mini sample	this function is executed in the given keyword sequence
  Name ( required )	txt	N="c:\DLLs\myDLL"	path and name of the DLL
  Handle	NUM	hdl=hDLL	if Handle=... is not present: the DLL is automatically closed and unloaded after the call. Else the DLL remains loaded and is closed only by the Close=... option
  Fncname	txt	Fnc="Fnc1"	for one DLL(...) call 1 Fnc=... or 1 Sub=... is required ⇒ how to write the DLL procedure headers the program will crash if a function call refers to a subroutine name and vice versa
  Subname	txt	Sub="Sub1"	for one DLL(...) call 1 Fnc=... or 1 Sub=... is required. ⇒ how to write the DLL procedure headers
  Argument	NUM	Arg=my_number	HicEst numeric standard is binary 8-Byte real
  Argument	TXT	A=my_string	variables as arguments can be changed in the DLL
  Argument	txt	A="hello world"	be careful not to overwrite numeric or string constants
  Argument	struct	a=struct	a binary structure can be written in HicEst by a WRITE(Text=struct, Format= binary_format_string, ...) ... binary structures can be read by a READ(Text=struct, Format= binary_format_string, ...) ... text formats can be mixed with binary numeric formats be careful about padding different data types. If you use something like C typedef struct or Fortran TYPE in your DLL consult your manual about padding. define largest size (explicit length!) numeric data items first place numeric data before character data add small data items (padding) if needed to ensure natural alignment. This may be on up to 64-bit boundaries, compare your compiler manual. type defined arrays may need trailing padding
  Close	NUM	c=hDLL	unload DLL if no longer needed
  ERror	LBL	err=999	⇒ on error jump to label 999

• the example in Tutorial.hic " sum = exp(1) + (-1) " is coded:
  • sum = DLL(Name="user", Fnc="SumArguments", Arg=exp(1), Arg=-1)
• HicEst performs the

  run-time dynamic linking

  only when needed: the existence of the DLL is only checked at call time, not at program start

• procedure-headers

  for your DLL
  • Fortran:

     !======== clone this to your own function/subroutine, replace only the name
    ! check your compiler manual how to declare entry points to a DLL, e.g. for Visual Fortran:
    ! procedure headers should always have all 6 arguments listed, even if not needed:
    ! for a function:
       FUNCTION   yourFNC(Real8Vector, Arguments, StartPositions, Lengths, Types, Char1Vector)
       !DEC ATTRIBUTES DLLEXPORT:: yourFNC
    ! or for a subroutine:
       SUBROUTINE yourSUB(Real8Vector, Arguments, StartPositions, Lengths, Types, Char1Vector)
       !DEC ATTRIBUTES DLLEXPORT:: yourSUB
    ! required declarations for functions and subroutines:
    ! 1.  Real8Vector has ALL numeric  data (constants, scalars, arrays):
       REAL    (KIND=8), DIMENSION(*),         INTENT(INOUT) :: Real8Vector
    !2.   Arguments is the number of Argument=... options in the scripts DLL(...) statement:
       INTEGER (KIND=4),                       INTENT(IN   ) :: Arguments
    !3.   StartPositions: for strings the position of the 1st byte, for numerics the position of the 1st number
       INTEGER (KIND=4), DIMENSION(Arguments), INTENT(IN   ) :: StartPositions
    !4.   Lengths: for strings the number of bytes, for numerics the number of elements ( 1 for scalar)
       INTEGER (KIND=4), DIMENSION(Arguments), INTENT(IN   ) :: Lengths
    !5.   Types: CONSTANT=1, ARRAY=16, CHARACTER=64, NUMERIC=128
       INTEGER (KIND=4), DIMENSION(Arguments), INTENT(IN   ) :: Types
    !6.   Char1Vector has ALL character data in 1 single string:
       CHARACTER(LEN=1), DIMENSION(*),         INTENT(INOUT) :: Char1Vector
    !
       INTEGER, PARAMETER:: CONSTANT=1, ARRAY=16, CHARACTER=64, NUMERIC=128
    !
    ! add your own declarations next (this is an EXAMPLE):
    !
    ! this is a part of the HicEst script:
          DIMENSION vec(20)
          CHARACTER txt*100
          DLL(N="yourDLL", F="yourFNC", A=1, A=x, A=vec, A=txt, A="abc")
    !
    ! this is the procedure header in your DLL (Fortran is just the example):
      FUNCTION   yourFNC(Real8Vector, Arguments, StartPositions, Lengths, Types, Char1Vector)
    !=== after the call from HicEst the DLL will have:
     !         Arguments == 5
     !             Types == 129  128  16     64   65
     !           Lengths ==   1    1  20    100    3
     !    StartPositions ==  44   22   1      3  123 (just examples, set by HicEst)
     ! argument 1 ( == 1   ) is in Real8Vector(44)
     ! argument 2 ( == x   ) is in Real8Vector(22)
     ! argument 3 ( == vec ) is in Real8Vector( 1) to Real8Vector(20)
     ! argument 4 ( == txt ) is in Char1Vector( 3) to Char1Vector(102)
     ! argument 5 ( =="abc") is in Char1Vector(123) to Char1Vector(125)
    

  • C:

     _declspec(dllexport) double _stdcall  // function call, returns double (8 byte)
             yourFNC(            // yourFNC is a function in a yourDLL.c
     double    *Real8Vector,     // has ALL num data      
     const int *Arguments,       // payload in script     
     const int *StartPositions,  // in Char1Vector if CHAR, in Real8Vector if NUM 
     const int *Lengths,         // bytes for a string, elements for array, 1 for numeric scalar
     const int *Types,           // CONSTANT=1, ARRAY=16, CHARACTER=64, NUMERIC=128   
     char      *Char1Vector)     // has ALL character data   
    

How your donation will be used, and how to get a HicEst key code in return ©2000-2010 Georg Petrich, HicEst Instant Prototype Computing. All rights reserved. Impressum