Carbon


GetMemFragment

Header: CodeFragments.h Carbon status: Supported

Prepares a memory-based fragment for subsequent execution.

OSErr GetMemFragment (
    void *memAddr, 
    UInt32 length, 
    ConstStr63Param fragName, 
    CFragLoadOptions loadFlags, 
    CFragConnectionID *connID, 
    Ptr *mainAddr, 
    Str255 errMessage
);
Parameter descriptions
memAddr

The address of the fragment.

length

The size, in bytes, of the fragment.

fragName

The name of the fragment. (This information is used primarily to allow you to identify the fragment during debugging.)

loadFlags

A flag that specifies the operation to perform on the fragment. The Code Fragment Manager recognizes the constants described in “Load Flag, Symbol Class, and Fragment Locator Constants”.

connID

On return, a pointer to the connection ID that identifies the connection to the fragment. You can pass this ID to other Code Fragment Manager functions (for example, CloseConnection).

mainAddr

On return, a pointer to the main address of the fragment. The value returned is specific to the fragment itself.

errMessage

On return, the name of the fragment that could not successfully be loaded. This parameter is meaningful only if the call to GetMemFragment fails.

function result

A result code.

DISCUSSION

The GetMemFragment is most useful for handling code that is contained in a resource. You can read the resource data into memory using normal Resource Manager functions (for example, Get1Resource) and then call GetMemFragment to complete the processing required to prepare it for use (for example, to resolve any imports and execute the fragment’s initialization function).

You must lock the resource-based fragment into memory (for example, by calling HLock) before calling GetMemFragment. You must not unlock the memory until you have closed the connection to the fragment (by calling CloseConnection).

Loading involves finding the specified fragment, reading it into memory (if it is not already in memory), and preparing it for execution. The Code Fragment Manager attempts to resolve all symbols imported by the fragment; to do so may involve loading import libraries.

If the fragment loading fails, the Code Fragment Manager returns an error code. Note, however, that the error encountered is not always in the fragment you asked to load. Rather, the error might have occurred while attempting to load an import library that the fragment you want to load depends on. For this reason, the Code Fragment Manager also returns, in the errMessage parameter, the name of the fragment that caused the load to fail. Although fragment names are restricted to 63 characters, the errMessage parameter is declared as type Str255; doing this allows future versions of the Code Fragment Manager to return a more informative message in the errMessage parameter.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)