About the internal resource manager

version 2003

4th Dimension uses its own resource management scheme in the datafork of structure files. This Internal Resource Manager brings some abilities that the MacOS Resource Manager (used by Altura Mac2Win on the Window version of 4D) has not, especially the ability to have more than 2700 resources per kind of resource.

The theme "Resources" of the 4D Language reference refers to the standard MacOS-based resources, that are in resource forks of files (Open resource file, Create resource file, READ RESOURCE)

The Internal Resource Manager routines of the API that are referenced in this documentation refer to the "4D based" resources, stored in the datafork of files. Those routines have no equivalent in the 4th Dimension language in this version of 4D (currently 6.7)

These Internal Resources will continually be referred to in all the following documentation of this theme. All terms used (ID, Kinds, Names) refer only to those resources, not to any MacOS-based resources that could be in resource forks.

As MacOS-based resources, 4D-based resources have a type (a 4-bytes type, such as 'TEXT", 'PICT'), an unique ID, and optionally a name. You can use whatever type you want as an ID, into the range of a short.

Since it is an "internal" manager, there is no way to edit resources. A particular way to edit resource is by using the Structure Mode of 4th Dimension : it can be seen as an Internal Resource Editor of structure resources (such as forms, menus, or methods).

The developer can creates his own resources in his own format.

The developer can create a resource file (PA_CreateResFile), open a resource file (PA_OpenResFile), close a resource file (PA_CloseResFile), or get the reference number of the current database to access its resources.

When the plug-in wants to access a resource, it first pass a short to the routine used (PA_GetResource, PA_GetResourceSize). This short is the file reference number returned by the Internal Resources file management routines (PA_Create/OpenResFile). It tells 4D which file to use.

You can have more than one resource file opened at the same time.

As previously stated, the routines of this theme deal with internal resources. By using them, you can manipulate the structure resources of the database, such as forms, methods or menus. We strongly recommend that the plug-in act very carefully if it wants to change those resources in the structure file, since their format is not documented and many of these resources interact one with another.

It is recommended that the plug-in creates and uses new resources types and new resources in a file other than the structure file.

Before modifying a resource, the developer must lock it over the network, so no one can modify it at the same time. To lock a resource over the network, use PA_LockResource. If PA_LockResource returns 1, then the resource is locked for you and you can safely change its content and rewrite it on disk (PA_SetResource, PA_WriteResourceHandle). Once this is done, remember to unlock the resource by calling PA_UnlockResource. If PA_LockResource returns 0, then the resource is already in use on an other client.

If you want to read the resource content, it is not necessary to lock it before.

PA_LockResource always returns 1 on 4D single-user machines. It is the plug-in's responsibility to build a way to avoid multi access to the same resource (which could happen in a multiprocess environment).

On the other hand, PA_LockResourceHandle does two things:

	- It locks the handle of the resource, so it can't be moved, purged from memory (like PA_LockHandle)
	- It sets the "locked" property of the resource to "lock": the next time it is load, it will be loaded locked.

Please note that PA_LockResourceHandle does not deal with the network (the resource handle is not a shared).

Here are some basic examples of its use:

// --------------------------------------------
// Sample set resource

if(PA_LockResource(resFile, 'toto', 128))
{
   PA_SetResource(resFile, 'toto', 128, newData, dataSize);
   PA_UnlockResource(resFile, 'toto', 128);
}

// --------------------------------------------
// Use a resource handle, and modify this handle without changing
// its size
typedef struct {
   short   field1;
   short   field2;
   . . .
   short   fieldN;
}TOTO, *TOTOptr, **TOTOhdle;

if(PA_LockResource(resFile, 'toto', 128))
{
  h = (TOTOhdle) PA_GetResourceHandle(resFile, 'toto', 128);
  if(h)
  {
    pt = PA_LockHandle(h);
    pt->field1 = ...;
    pt->field2 = ...;
    PA_UnlockHandle(h);
    PA_WriteResourceHandle(h);
  }
  PA_UnlockResource(resFile, 'toto', 128);
}


// --------------------------------------------
// Use the resource handle, and resize it

if(PA_LockResource(resFile, 'toto', 128))
{
  h = PA_GetResourceHandle(resFile, 'toto', 128);
  if(h)
  {
    PA_SetHandleSize(h, 300);
    pt = PA_LockHandle(h);
    /* change the content */
    PA_UnlockHandle(h);
    PA_WriteResourceHandle(h);
  }
  PA_UnlockResource(resFile, 'toto', 128);
}


// --------------------------------------------
// Lock the resource handle, so it will be loaded locked
// the next time
if(PA_LockResource(resFile, 'toto', 128))
{
  h = PA_GetResourceHandle(resFile, 'toto', 128);
  if(h)
    PA_LockResourceHandle(h);
  // The resource will be locked the next time it is used
  PA_UnlockResource(resFile, 'toto', 128);
}