The following example shows how to call a function in the library:

Private Declare Sub MathLibSin(ByVal iRef as Integer, ByVal x as Double, ByRef r as Double) Trap &HA805+5

Public Function MLSin(ByVal x as Double) as Double
  Dim r as Double

  MathLibSin iRefNum, x, r
  MLSin=r
End Function

Finally, the following example shows how to unload the library:

Private Declare Function MathLibClose(ByVal iRef as Integer, ByRef iUseCount as Integer) as Integer Trap &HA802

Public Sub MLClose()
  Dim e as Integer, u as Integer

  If iRefNum<>0 Then
    e=MathLibClose(iRefNum,u)
    If e<>0 And u=0 Then RemoveLibrary(iRefNum)
  End If
End Sub

Declaring external functions and passing parameters

As shown above, declaring shared library functions is carried out using the Declare statement. In most cases, converting parameters accepted by an external function written in C into data types specific to HB++ does not present any particular problems. The documentation of the Declare statement shows a comparison between the most common C data types and HB++ types. Sometimes, certain constructions in the C language can cause a problem: these concern return values of type Double or pointers, and some parameters taking up more that 4 bytes, like structures.

As already mentioned, the different development tools for the Palm OS^® platform do not use the same conventions for returning values of type Double. The HB++ compiler, as well as the GCC compliler expect these values in the register pair D0/D1, whilst the CodeWarrior™ compiler (with which Palm OS^® is compiled) transforms the return value into a hidden parameter of type pointer. Take the following C function for example:

double MyFunction(int n)
{
  return 1.0;
}

void MyFunction(double * ret, int n)
{
  *ret = 1.0;
}

Public Declare Sub MyFunction(ByRef ret As Double, ByVal n As Integer) Trap &HA8xx

Another problem is posed by the return pointers. Whilst return values are normally stored in the D0 register (or in the D0/D1 register pair for Double values), pointers are always returned in the A0 register. This convention is respected by all Palm OS^® platform development tools. To be able to call a C function returning a pointer, you should indicate to the HB++ compiler that the return value should be read into the correct register, by declaring the return value with the Pointer keyword. Refer to the documentation on the Declare statement for more information.

Note that the HB++ language ignores the notion of pointer (at least from the programmer's point of view). When an external function returns a pointer, it must be stored in a variable of type Long, and cannot be used directly. It can however be passed to another external function which will know how to use it. One such example will be illustrated later on in the chapter.

Finally, the last problem is posed by structures. The solution in HB++ is to pass a StreamMemory object to an external function. In fact, only a pointer on the first byte of the memory block contained in the object will be passed to the external function. It is only necessary therefore to fill this memory block, in order that the data it contains will correspond to the C structure expected by the function. Consider the following C structure for example:

typedef struct _Params
  {
    int  x, y;
    char sz[32];
    long z;
  }
    Params;

Dim struct As New StreamMemory
Dim x As Integer, y as Integer, z As Long, sz As String

Write struct, x
Write struct, y
Write struct, sz[32]
Write struct, z

Another frequently encountered case is the case of structures containing pointers to a character string. Such a pointer always contains 4 bytes, whatever the size of the string it is pointing to. A solution consists to allocate a memory block using the Palm OS^® API allocation functions, to initialize it if necessary, then write the pointer returned by the system in the required place in the structure. In the example below, we pass a string initialized to an external function. For simplicity, the structure only contains a single field, of type char * :

Public Declare Sub      MyFunction(ByVal iRefNum As Integer, ByRef objStruct As StreamMemory) Trap &HA8xx

Public Declare Function MemPtrNew(ByVal lSize As Long) As Pointer Trap &HA013
Public Declare Sub      MemPtrFree(ByVal lPtr As Long) Trap &HA012
Public Declare Sub      MemMove(ByVal lPtr As Long, ByRef sString As String, ByVal lSize As Long) Trap &HA026

Public Sub CallMyFunction(ByRef s As String)
  Dim struct As New StreamMemory
  Dim addr As Long, n As Long
  
  n=Len(s)+1
  addr=MemPtrNew(n)
  If addr=0 Then Err.Raise 1
  MemMove addr, s, n
  
  Write struct, addr
  MyFunction iRefNum, struct
  
  MemPtrFree addr
End Sub

The same type of construction can be used to construct a pointer on any type of data, for example a pointer to another structure. This can have some drawbacks in terms of execution time. When writing a shared library, you must avoid therefore as much as possible C functions accepting a pointer to a structure that itself contains other pointers.

Memory management

The HB++ execution library contains its own memory allocation routines, and includes notably a Garbage Collector that detects and frees up unused memory blocks. These routines ignore all allocations that could have taken place within external functions, hence certain rules must be respected to avoid conflicts.

• An external function cannot attempt to free a memory block provided by HB++, nor attempt to modify its size.
• A block allocated by an external function cannot be freed up by the garbage collector. If a library allocates a block, it must explicitly free it when it is no longer used.
• If an external routine makes intensive use of the memory, it can be useful to explicitly call the garbage collector using the MemCompact function before calling the external function, in order to avoid unused blocks and non-freed up blocks reducing the amount of available memory space.

• If an external function declares parameters of basic type ByRef (like Byte or Integer), the pointer received will always be found in the dynamic heap. The external function can use this pointer to modify the value of the variable to which it points, as long as it respects the type of this variable.
• If an external function declares parameters of type String, the pointer received will always be found in the dynamic heap. If the string passed by HB++ is not a constant string, the external function can use this pointer to modify the contents of the string as long as it does not attempt to write beyond the end of the string. If necessary, the HB++ programmer can reserve sufficient memory space using the Space function before calling the external function.
• If an external function declares parameters of type StreamMemory, the pointer received will be found in the dynamic heap if the StreamMemory has been explicitly allocated, and in the storage heap if the StreamMemory has been returned by the Record property of a GenericDB object or by the Resource property of a ResourceDB object. In both cases, the pointer will always point to an even address. The external function can modify such memory blocks, as long as it does not try to write beyond the end of the block, and also on condition that it uses the special functons DmWrite or DmStrCopy if the block is located in the storage heap.