PA_LockHandle

version 2003

PA_LockHandle (handle) char*

Parameter	Type		Description
handle	PA_Handle		The handle to lock
Function result	char*		Pointer to the data led to by handle

The routine PA_LockHandle locks the memory block led to by handle and returns a pointer to it.

This is useful if you call system traps that can move memory while using the handle. Remember to unlock the handle once you have completed your task so 4th Dimension can better avoid memory fragmentation.

This lock is not an incremental lock. If you call PA_LockHandle 10 times on the same handle, one simple call to PA_UnlockHandle unlocks the handle.

The code is usually built like this :

   pt = PA_LockHandle(aHandle);
      /* . . . code . . . */
   PA_UnlockHandle(aHandle);

Lock a handle before allocating new block of memory

   typedef struct
   {
      short      fValue;
      PA_Handle   fArray[10];
   } Sample;
   
   /* . . . code . . . */
   
   // mySample has been allocated using PA_NewHandle( sizeof( Sample ) )
   // We allocate memory via PA_NewHandle in a loop that de-references
   // the "parent" handle. We must lock it prior to this.
   Sample* p;

   p = (Sample*) PA_LockHandle( mySample );
   for ( i = 0; i < 10; i++ )
   {
      p->myArray[i] = PA_NewHandle(. . .);
      
      /* . . . code . . . */
   }
   // Time to unlock the handle to prevent memory fragmentation
   PA_Unlock( mySample );

PA_UnlockHandle.

Use PA_GetLastError to see if an error occurred.