Constructing and Destroying LogicalFile Instances

As always, before we can run we must lean how to walk. Our first step is thus learning how to create a GATLogicalFile instance. This is done through a call to the function

GATLogicalFile
  GATLogicalFile_Create(GATContext context, GATLocation location,
    GATLogicalFileMode mode, GATPreferences_const preferences)

The first argument to this function is a GATContext, covered previously in this manual. The next argument is a GATLocation instance. This GATLocation instance is simply used as a name for the resultant GATLogicalFile instance, it has nothing do do with actual physical location. The next argument is the enumeration GATLogicalFileMode. The various values of this enumeration dictate what should occur if the specified GATLocation corresponds to a preexisting GATLogicalFile instance. The various values that this enumeration may take on are given, along with their semantics, in the following table

The final argument to this function is a GATPreferences instance, covered in Appendix . This function returns a GATLogicalFile corresponding to the passed information and NULL upon failure.

As an example, let us consider opening a GATLogicalFile named by the GATLocation instance location. A code snippet which fits the bill is

GATContext context;
GATLocation location;
GATLogicalFile logicalFile;

context = ...
location = ...

logicalFile = GATLogicalFile_Create( context, location, GATLogicalFileMode_Open, NULL );

if( NULL != logicalFile )
{
  /* Play GATLogicalFile games */
}

After creating a GATLogicalFile and playing any amusing games with it that may cross our minds we need to send it out to pasture. This is accomplished through a call to the ``executioner''

void GATLogicalFile_Destroy(GATLogicalFile *logicalFile)

This function takes as tis first and only argument the GATLogicalFile which is to be destroyed. Upon return from this function all resources which the passed GATLogicalFile maintained are freed.