2
OKAPI Functions

2.5.1 Environment Functions Compatibility Reference

This table lists the OKAPI functions that manage environment objects.

2.5.2 okInit

Creates an object cache for an application and initializes the system.

okError okInit(const okEnvParams_s *EnvParams,

   okEnv *RetEnv);

EnvParams

The environment handle.

RetEnv

A database handle.

The okEnvParams_s structure specifies options for the environment. If EnvParams is NULL, the system uses default parameters for the environment. If EnvParams is not NULL, you can set individual parameters to 0 or NULL for the default for that parameter.

The okEnvParams_s structure has the following format:

typedef struct okEnvParams_s {

    okU4B       StructSize;     /* caller fills in size of this structure */

    okU4B       CacheSize;      /* Number of unfixed objects to keep */

    okU4B       NumObjRefs;     /* optional estimated number of descriptors */

    okU4B       UserIDLen;      /* optional length of user ID */

    okName      UserIDPtr;      /* optional pointer to user ID */

    okU4B       PasswdLen;      /* optional length of password */

    okName      PasswdPtr;      /* optional pointer to password */

    okPtr       LocalHeap;      /* optional local heap handle */

    okPtr       CacheHeap;      /* optional cache heap handle */

    okU4B       Options;        /* optional environment options */

    okU1B       CharacterSet;   /* optional environment character set */

    okU1B       _Padding[3];    /* not used */

} okEnvParams_s;

2.5.3 okFinal

Terminates an environment.

okError okFinal(okEnv Env);

Env

An environment handle.

This function terminates an environment Env. It disconnects all outstanding database connections with the application and releases all runtime resources allocated by Env. This function commits the last transaction, if still active.

2.5.4 okCleanup

Abnormally terminates an environment.

void okCleanup(okEnv Env);

Env

An environment handle.

This function abnormally terminates an environment. It disconnects all outstanding database connections with the application and releases all run-time resources allocated by Env. This function aborts the last transaction, if still active.

The okEnvInfo structure has the following format:

struct okEnvInfo {

   okU4B StructSize;     /* caller fills in size of this structure */

   okU4B XactCount;      /* currently not implemented */

   okU4B MemoryUsed;     /* currently not implemented */

   okU4B MemoryFree;     /* currently not implemented */

   okU4B DescriptorsUsed; /* currently not implemented */

};

2.5.5 okGetEnvInfo

Gets information about the environment.

okError okGetEnvInfo(okEnv Env, okEnvInfo_s *RetEnvInfo);

Env

An environment handle.

RetEnvInfo

A buffer for returning environment information.

2.5.6 Environment Sample Program

The following code demonstrates the use of the environment procedures:

#define OK_CS_ASCII 1

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okEnvParameters_s EnvParams;  /* Env parameters */

okEnvInfo_s EnvInfo;  /* Env information */

okEnv  Env;  /* Env handle */

okError  e; /* for returned error code */

...


   memset((char *)&EnvParams, 0, sizeof(okEnvParameters_s));

   EnvParams.StructSize = sizeof(okEnvParameters_s);

   EnvParams.CharacterSet = OK_CS_ASCII;

   e = okInit(&EnvParams, &Env);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   (void)okFinal(Env); 

...

2.6.1 okCreateDsn

Creates a DSN.

okError okCreateDsn(okName user, okName pub, okName path, okName dbName, ok1B drv);

user

The database user name.

pub

The public part of the DSN name (see the example below).

path

The full path to the database file.

dbName

The name of the database file.

drv

A flag that indicates whether an embedded (native) driver or a client driver is used. This parameter can take two values: DRV_NATIVE and DRV_CLIENT.

okCreateDsn creates a new DSN section in the odbc.ini file and also includes the new entry in the registry.

It gets default volume ID and default data directory (if the path parameter is NULL) from the polite.ini file. If polite.ini does not have a default datadirectory, okCreateDsn gets it from the system environment or from the registry.

the default value for the volume ID is 64. If dbName is NULL, okCreateDsn will use the DSN name as the database file name.

The DSN name will be user_pub or pub if no user name is given (that is, if the user is NULL).

If the datadirectory does not exist, it will be created.

okError e = okCreateDsn("yev","polite","d:\orant\oldb40", NULL,DRV_NATIVE);

The above statement will create the DSN named yev_polite with an ODBC native driver, the datadirectory D:\orant\oldb40\yev and the database file named yev_polite.odb.

2.6.2 okDeleteDsn

Deletes a DSN.

okError okDeleteDsn(okName dsn);

dsn

DSN name.

okDeleteDsn deletes the DSN section from the odbc.ini file and from the registry.

2.6.3 okSetDsnAttribute

Writes single attribute into a DSN section.

okError okSetDsnAttribute(okName dsn, okName attributeName, okChar * value);

dsn

DSN name.

attributeName

The name of the DSN attribute (such as, database, datadirectory, and so on).

value

The attribute value.

If dsn is not given (NULL), the default dsn name will be taken from polite.ini.

If dsn does not exist, the dsn section will be created, but the attributes will not be filled in automatically.

2.6.4 okGetDsnAttribute

Reads a single attribute from a DSN section.

okError okGetDsnAttribute(okName dsn, okName attributeName, okSize valueBufferSize, char * valueBuffer);

dsn

DSN name.

attributeName

The name of the DSN attribute.

valueBufferSize

The size of the buffer receiving the value.

valueBuffer

The buffer that receives the attribute value.

If no dsn name is given, the default dsn name will be taken from polite.ini.

2.7.1 Database Functions Compatibility Reference

This table lists the OKAPI database management functions.

2.7.2 okCreateDatabase

Creates a database.

okError okCreateDatabase(okEnv Env, 

   okSize DatabaseNameLen, okName DatabaseNamePtr,

   const okDatabaseParameters_s *DatabaseParams);

Env

An environment handle.

DatabaseNameLen

The length of the database name.

DatabaseNamePtr

A name for the new database.

DatabaseParams

Parameters for the creation of the database.

This function creates a database with the name DatabaseNamePtr. The underlying operating system or file system limits the length of the database name, since each database is mapped to a raw partition or file.

The okDatabaseParameters structure contains parameters for the new database. It has the following format:

typedef struct okDatabaseParameters okDatabaseParameters_s;

struct okDatabaseParameters {

   okU4B  StructSize;    /* caller fills in size of this structure */

   ok2B   VolumeID;      /* database volume ID */

   okU2B  ExtentSize;    /* optional number of pages to cluster */

   okU4B  DatabaseSize;  /* size of database in kilobytes */

   okSize LabelLen;      /* length of label for the database */

   okName LabelPtr;      /* pointer to label for the database */

   okU4B  Options;       /* currently unused */

   okU1B  CharacterSet;  /* character set */

   okU1B  _Padding[3];   /* not used */

};

2.7.3 okDeleteDatabase

Deletes a database.

okError okDeleteDatabase(okEnv Env, 

   okSize DatabaseNameLen, okName DatabaseNamePtr);

Env

An environment handle.

DatabaseNameLen

The length of the database name.

DatabaseNamePtr

The name of the database to delete.

This function removes the database with the name DatabaseNamePtr and releases all resources allocated to the database. Since the objects in a deleted database cannot be recovered, you should be sure that the objects in the database are no longer needed before deleting the database.

On the Palm platform you must disconnect from the database before deleting it. See "okDisconnect" for more information.

2.7.4 okConnect

Establishes a database connection.

okError okConnect(okEnv Env, 

   okSize DatabaseNameLen, okName DatabaseNamePtr, 

   const okConnOpt_s *Options, okRef *RetDatabase);

Env

An environment handle.

DatabaseNameLen

The length of the database name.

DatabaseNamePtr

The name of the database.

Options

Options for the database connection. Possible value:

• OK_CONNECT_READ_ONLY: connects to the database in read-only mode.

RetDatabase

A buffer for returning a reference to a transient database object representing the connected database.

This function establishes a connection to the database with the name DatabaseNamePtr. It returns in RetDatabase a reference to a database object representing the connected database. An application must connect to the database before performing any operations on the objects in the database. Multiple okConnect calls to the same database by an application return the same database object.

2.7.5 okDisconnect

Breaks a database connection.

okError okDisconnect(okEnv Env, okHandle Database);

Env

An environment handle.

Database

A database handle.

This function breaks a connection to the database pointed to by Database. It flushes all objects in the database and releases all control data structures for maintaining the connection. You must invoke okDisconnect outside of a transaction.

2.7.6 Database Sample Program

The following code demonstrates the use of the database procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okDatabaseParameters DatabaseParams;  /* database parameters */

okRef  Database;  /* reference to database object */

okError  e;  /* for returned error code */


...


   memset((char *)&DatabaseParams, 0, sizeof(okDatabaseParameters_s));

   DatabaseParams.StructSize = sizeof(okDatabaseParameters_s);

   e = okCreateDatabase(Env, sizeof("staff.odb"), "staff.odb",  &DatabaseParam);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okConnect(Env, sizeof("staff.odb"), "staff.odb", 0,  &Database);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okDisconnect(Env, Database);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okDeleteDatabase(Env, sizeof("staff.odb"), "staff.odb");

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.8.1 Schema Functions Compatibility Reference

This table lists the OKAPI functions that manage the schema.

2.8.2 okCreateClass

Creates a new class in a database.

okError okCreateClass(okEnv Env, okHandle Database, 

   okSize ClassNameLen, okName ClassNamePtr, 

   okSize SuperclassCount, const okHandle Superclasses[],

   okSize AttrCount, const okAttrDesc_s AttrDescs[],

   okSize MethCount, const okMethDesc_s MethDescs[], 

   okU4B Options, okRef *RetClass);

Env

An environment handle.

Database

A database object.

ClassNameLen

The length of a class name.

ClassNamePtr

Name of a class.

SuperclassCount

The number of superclasses from which to inherit.

Superclasses

An array of superclasses from which to inherit.

AttrCount

The number of attribute descriptions.

AttrDescs

An array of attribute de­scriptions of type okAttrDesc_s.

MethCount

The number of method descriptions. This parameter is always set to 0. It is currently not used.

MethDescs

An array of method de­scriptions of type okMethDesc_s. This parameter is always set to NULL. It is currently not used.

Options

Additional information for creating the class.

RetClass

The buffer for returning a class object.

This procedure creates a new class ClassNamePtr in a database represented by Database. The order of the attribute descriptions in the array AttrDescs determines the order of the corresponding attributes in the class. Currently, MethCount must be set to 0 and MethDescs must be set to NULL. The caller uses Options to pass in additional information about the class. The option OK_APP_DEF_INHERIT suppresses default class inheritance. If using this option, you should individually specify the properties that should be inherited in the attribute descriptions and method descriptions.

Each property of a class, inherited or not, is represented as a schema object, which you can look up by name in the context of the class.

2.8.3 okAttachJavaClass

Attaches a Java class to an Oracle Lite class.

okError okAttachJavaClass(okEnv Env, okHandle Database,

   okHandle ClassRef, okU4B ClassDef, okSize JavaClsOrSrcNameLen,

   okName JavaClsOrSrcName, okSize JavaClsOrSrcPthLen, 

   okName JavaClsOrSrcPth, okSize ConsArgCount, 

   okHandle *ConsArgs);

Env

An environment handle.

Database

A database object.

ClassRef

A class object.

ClassDef

Class definition. Possible values include:

• CLS_IN_POLITE: specifies that the class is already in the Oracle Lite database (it is attached to another class prior to this call).

• CLS_CLS_FILE: specifies that the file in the path JavaClsOrSrcPth is a class file. The kernel attaches the class file to the Oracle Lite class and stores the class file in the database.

• CLS_SRC_FILE: specifies that the file in the path JavaClsOrSrcPth is a source file. The kernel compiles the Java class using the Java compiler specified in the class path set for the system.

JavaClsOrSrcNameLen

The length of the Java class or source file name.

JavaClsOrSrcName

Name of the Java class. For fully qualified names that include package names, you must use dots to separate the name components.

JavaClsOrSrcPthLen

The length of the path of the Java source or class file.

JavaClsOrSrcPth

The directory path location of the Java class or source file.

ConsArgCount

The number of arguments in the constructor used to create a Java instance.

ConsArgs

An array of attribute handles to pass as arguments to the class constructor.

This function attaches a Java class to an Oracle Lite class. After the function attaches the Java class, the methods of the Java class become the methods of the Oracle Lite class. Static methods of the Java class become class methods of the Oracle Lite class, while non-static methods become instance methods. Use the ClassDef argument to specify the class location.

When attaching a Java class, you can specify the constructor that the kernel should use to create instances of the class. The arguments ConsArgCount and ConsArgs specify the number of arguments the constructor takes and which attributes of the object should be passed to the constructor. Before an instance method executes (when invoked by the okExecMeth method described in section "Method Invocation"), the kernel constructs a Java object corresponding to the Oracle Lite object using the constructor that takes the attribute values passed in the ConsArgs argument.

2.8.4 okDeleteClass

Deletes a class from a database.

okError okDeleteClass(okEnv Env, okHandle Class);

Env

An environment handle.

Class

A class object.

This procedure deletes the class represented by the object Class. It deletes all the schema objects associated with the class. On the Palm platform, inheriting class objects are not automatically removed when you delete the super class. To prevent problems associated with dangling instances, every instance of a class should be deleted before you delete the class.

2.8.5 okDetachJavaClass

Detaches a Java class from an Oracle Lite class.

okError okDetachJavaClass(okEnv Env, okHandle Database, 

    okHandle ClassRef, okBool DeleteClassBody);

Env

An environment handle.

Database

A database object.

ClassRef

A class object.

DeleteClassBody

A boolean flag to indicate whether to delete the Java class body from the database.

This procedure detaches the Java class from the Oracle Lite class specified by Class. If DeleteClassBody is TRUE, okDetachJavaClass deletes the class from the database.

2.8.6 okSetCallBacks

Specifies runtime activator and deactivator functions for instances of a class.

okError okSetCallBacks(okEnv Env, okHandle Class,

   okPtr ActivatorData, okPtr DeactivatorData, 

   okCallBack Activator, okCallBack Deactivator);

Env

An environment handle.

Class

A class object.

ActivatorData

A pointer to data to pass to the activator function.

DeactivatorData

A pointer to data to pass to the deactivator function.

Activator

An activator function for instances of the class.

Deactivator

A deactivator function for instances of the class.

This procedure allows you to specify runtime activator and deactivator functions for instances of the class Class. Oracle Lite invokes the function Activator, if not NULL, when creating an instance of the class or bringing the instance into cache from disk. Oracle Lite invokes the function Deactivator, if not NULL, when deleting or swapping out an instance.

The kernel does not permanently store these functions in the class object. They must be set at runtime whenever a class object is brought in from disk.

The functions Activator and Deactivator each take two pointers as arguments. The first argument is a pointer given (as either ActivatorData or DeactivatorData) when okSetCallBacks is called. The second points to the body of a Class object.

2.8.7 okFindClass

Finds a class object in a database.

okError okFindClass(okEnv Env, okHandle Database, 

   okSize ClassNameLen, okName ClassNamePtr, okRef *RetClass);

Env

An environment handle.

Database

A database object.

ClassNameLen

The length of a class name.

ClassNamePtr

The name of a class.

RetClass

A buffer for returning a class object.

This procedure finds the class object with the name ClassNamePtr in database Database and returns a reference to the class object in RetClass. If it does not find the class in the database, okFindClass returns a NULL reference. Returning NULL is not considered an error (that is, it does not return an error code).

2.8.8 okFindAttr

Finds an attribute object in a class.

okError okFindAttr(okEnv Env, okHandle Class, 

    okSize AttrNameLen, okName AttrNamePtr, okHandle DefinedIn, 

    okRef *RetObj, okU4B *RetPos);

Env

An environment handle.

Class

A class object.

AttrNameLen

The length of an attribute name.

AttrNamePtr

The name of an attribute.

DefinedIn

The class from which an attribute or a method is inherited.

RetObj

An optional buffer for returning the attribute or method object.

RetPos

An optional buffer for returning the position of the attribute or method.

This function finds the attribute object for the attribute AttrName in the class represented by Class. If DefinedIn is NULL, it defaults to Class. The first attribute in a class is at position zero.

2.8.9 okGetAttrCount

Returns the number of attributes in a class, excluding hidden attributes.

okError okGetAttrCount(okEnv Env, okHandle Class, okU4B *RetCount)

Env

An environment handle.

Class

A class object.

RetCount

An optional buffer for returning the attribute count.

This function should be used in place of DAR_COUNT(class->Attributes) which does not exclude hidden attributes. This function will be available for Win32 in a future release.

2.8.10 okFindMethod

Finds a method object in a class.

okError okFindMethod(okEnv Env, okHandle dbH, 

   okHandle clsR, okU4B MethType, okSize MethNameLen, 

   okName MethName, okSize MethSigLen, okName MethSig,

   okHandle *retMeth);

Env

An environment handle.

dbH

A database object.

clsR

A class object.

MethType

The type of Java method to find. Possible values:

• OK_CLASS_METHOD: to find a class method.

• OK_INSTANCE_METHOD: to find an instance method.

MethNameLen

The length of the method name.

MethName

The method name.

MethSigLen

The length of the method signature as a string. If the method lookup should be based only on the name, set this value to 0.

MethSig

A Java Native Interface (JNI) style method signature string.

retMeth

An optional buffer for returning the attribute or method object.

This procedure finds the method object for the method MethName in the class represented by Class. The MethType argument specifies the type of method to find. Possible values are OK_CLASS_METHOD for class method and OK_INSTANCE_METHOD for instance method. Since more than one method may exist with the same name, the arguments MethSigLen and MethSig permit the caller to specify the method signature. You must specify the method signature as a string using the JNI format. For example, for the method String M (int, Date), the JNI signature is:

 "(ILjava/sql/Date;)Ljava/lang/String;"

2.8.11 okGetSuClasses

Returns the superclasses or subclasses of a class.

okError okGetSuClasses(okEnv Env, okHandle Class, 

   okBool isSuper, okBool isImmediate, okArray *RetList);

Env

An environment handle.

Class

A class object.

isSuper

A Boolean flag which is TRUE if the function should return superclasses, and FALSE if it should return subclasses.

isImmediate

A Boolean flag which is TRUE if the function should return all superclasses or subclasses, and FALSE if it should return only the immediate superclasses or subclasses.

RetList

An array for returning the results of the lookup.

This procedure returns the superclasses (when isSuper is TRUE) or subclasses (when isSuper is FALSE) of the class Class in RetList.

2.8.12 Schema Sample Program

The following code demonstrates the schema procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okError e;

okEnv Env;

okHandle Database;

okRef PersonRef, StudentRef, DeptRef, MethRef, NameAttr;

okArray AttrDescs;

okU4B NamePos;


...

   okAttrDesc_s DeptAttrs[] = {

      {sizeof("Name"), "Name", 0, NULL, sizeof("okChar"), "okChar",

       0, 0, 0, 0, 0, OK_DYNAMIC, 0, NULL, 0, NULL, 0},

      {sizeof("Students"), "Students", 0, NULL, 

      sizeof("Student_s"),

      "Student_s", 0, 0, 0, 0, 0, OK_DYNAMIC, 0, NULL, 0, NULL, 0},

      {sizeof("Staff"), "Staff", 0, NULL, sizeof("Professor_s"), 

      "Professor_s", 0, 0, 0, 0, 0, OK_SCALAR, 0, NULL, 0, NULL, 0}

   };


   okAttrDesc_s PersonAttrs[] = {

      {sizeof("ID"), "ID", 0, NULL, sizeof("okU4B"), "okU4B",

      0,0, 0, 0, 0, OK_SCALAR, 0, NULL, 0, NULL, 0},

      {sizeof("Name"), "Name", 0, NULL, sizeof("okChar"), "okChar",

      0, 0, 0, 0, 0, OK_DYNAMIC, 0, NULL, 0, NULL, 0},

      {sizeof("Age"), "Age", 0, NULL, sizeof("okU2B"), "okU2B",

      0, 0, 0, 0, 0, OK_SCALAR, 0, NULL, 0, NULL, 0},

      {sizeof("Gender"), "Gender", 0, NULL, sizeof("okU2B"), "okU2B",

      0, 0, 0, 0, 0, OK_SCALAR, 0, NULL, 0, NULL, 0},

      {sizeof("Phone"), "Phone", 0, NULL, sizeof("okU1B"), "okU1B",

      0, 0, 0, 0, 0, 8, 0, NULL, 0, NULL, 0},

      {sizeof("Picture"), "Picture", 0, NULL, sizeof("okLong"), 

      "okLong", 0, 0, 0, 0, 0, OK_SCALAR, 0, NULL, 0, NULL, 0}

   };

   okAttrDesc_s StudentAttrs[] = {

      {sizeof("Dept"), "Dept", 0, NULL, sizeof("Dept_s"), "Dept_s",

      0, 0, 0, 0, 0, OK_SCALAR, 0, NULL, 0, NULL, 0},

      {sizeof("Clock"), "Clock", 0, NULL, sizeof("okU4B"), "okU4B",

      0, 0, 0, 0, 0, OK_SCALAR, 0, NULL, 0, NULL,OK_RUNTIME_ATTR}

   };

   okAttrDesc_s ProfessorAttrs[] = {

      {sizeof("Dept"), "Dept", 0, NULL, sizeof("Dept_s"), "Dept_s",

      0, 0, 0, 0, 0, OK_SCALAR, 0, NULL, 0, NULL, 0}

   };


   #include <time.h>

   /* constructor function for run-time attr of "Student" */

   void GetTime(okPtr NotUsed, okObjData *StudentP)

      {((Student_s *)StudentP)->Clock = (okU4B)clock(); }


   e = okConnect(Env, 9, "staff.odb", FALSE, &Database);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* create class "Dept_s" */

   e = okCreateClass(Env, Database, sizeof("Dept_s"), "Dept_s",

       0, NULL, sizeof(DeptAttrs)/sizeof(okAttrDesc_s), 

       DeptAttrs, 0, NULL, 0, NULL); 

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* creates class "Person_s" */

   e = okCreateClass(Env, Database, sizeof("Person_s"),"Person_s", 

      0, NULL, sizeof(PersonAttrs)/sizeof(okAttrDesc_s),

      PersonAttrs, 0, NULL, 0, &PersonRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* creates class "Student_s" */

   e = okCreateClass(Env, Database, sizeof("Student_s"),

      "Student_s", 1, &PersonRef,

      sizeof(StudentAttrs)/sizeof(okAttrDesc_s), StudentAttrs,

      0, NULL, 0, &StudentRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* creates class "Professor_s" */

   e = okCreateClass(Env, Database, sizeof("Professor_s"),

      "Professor_s", 1, &PersonRef,

      sizeof(ProfessorAttrs)/sizeof(okAttrDesc_s),

      ProfessorAttrs, 0, NULL, 0, NULL);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* set constructor for run-time attr */

   e = okSetCallBacks(Env, StudentRef, NULL, NULL, GetTime, NULL);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okFindClass(Env, Database, sizeof("Dept_s"), 

      "Dept_s", &DeptRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okFindAttr(Env, DeptRef, sizeof("Name"), 

      "Name", NULL, &NameAttr, &NamePos);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* attach a Java class to class Dept_s. Assume that the Java 

   source file is c:\JavaSrc\DeptMeths. Use the Name

   attribute of Dept_s as a constructor argument */


   e = okAttachJavaClass(Env, Database, DeptRef, CLS_SRC_FILE,

      9,"DeptMeths",10,

      "c:\\JavaSrc",1,&NameAttr);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* find the void HireStaff(int ID, String Name) method */

   e = okFindMethod(Env, Database, DeptRef, OK_INSTANCE_METHOD,

      9, "HireStaff", 22, 

      "(ILjava/lang/String;)V", &MethRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   {okArrayBaseClasses;

    e = okGetSuClasses(Env, StudentRef, 

      TRUE, TRUE, &BaseClasses);

    if (OK_IS_ERROR(e)) { /* error handling */ }

   }   


   e = okDeleteClass(Env, PersonRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.9.1 Group Functions Compatibility Reference

This table lists the OKAPI functions that manage groups.

2.9.2 okCreateGroup

Creates a group object within a database.

okError okCreateGroup(okEnv Env, okHandle Database, 

   okSize GroupNameLen, okName GroupNamePtr, 

   okU4B Options, okRef *RetGroup);

Env

An environment handle.

Database

A database object.

GroupNameLen

The length of a group name.

GroupNamePtr

The name of a new group.

Options

Options for group op­eration.

RetGroup

A buffer for returning a group object.

This function creates an object group with the name GroupNamePtr in the database Database. It returns a reference to the new group object in RetGroup. Options is currently not used.

2.9.3 okDeleteGroup

Deletes a group object from a database.

okError okDeleteGroup(okEnv Env, okHandle Group);

Env

An environment handle.

Group

The group object to delete.

This function deletes the group specified by Group. This function deletes the group object as well as all objects in the group.

2.9.4 okFindGroup

Finds a group object in a database.

okError okFindGroup(okEnv Env, okHandle Database, 

   okSize GroupNameLen, okName GroupNamePtr, 

   okRef *RetGroup);

Env

An environment handle.

Database

A database object.

GroupNameLen

The length of the group name.

GroupNamePtr

The name of the new group.

RetGroup

A buffer for returning a group object.

This function finds the group with the name GroupNamePtr in the database Database. If it does not find a group with the given name, the function returns a NULL reference. Returning NULL is not considered an error (that is, no error code is returned).

2.9.5 okSetDefaultGroup

Changes the current default object group maintained by the kernel.

okError okSetDefaultGroup(okEnv Env, okHandle NewDefGroup, 

      okRef *RetOldDefGroup);

Env

An environment handle.

NewDefGroup

The new default group.

RetOldDefGroup

A buffer for returning the group.

This function changes the current default object group to the group specified by NewDefGroup. If NewDefGroup is NULL, the default group reverts to the system-defined default group. If RetOldRefGroup is not NULL, this function makes NewDefGroup the default object group and returns a reference to the prior default group object in RetOldDefGroup.

2.9.6 Group Sample Program

The following code demonstrates the use of the group procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okRef FacultyRef;

okRef PrevDefGroup;

okError e;


...


   e = okCreateGroup(Env, Database, sizeof("Faculty"), 

      "Faculty", 0, &FacultyRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okFindGroup(Env, Database, sizeof("Faculty"), 

      "Faculty", &FacultyRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   

   e = okSetDefaultGroup(Env, FacultyRef, &PrevDefGroup);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   

   e = okDeleteGroup(Env, FacultyRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.10.1 Object Functions Compatibility Reference

This table lists the OKAPI object functions.

2.10.2 okCreateObj

Creates a new instance of a class.

okError okCreateObj(okEnv Env, okHandle Group, 

   okHandle Class, const void *InitialVal, okU4B Options, 

   void *RetHandle);

Env

An environment handle.

Group

The group in which to create the object.

Class

The class object to instantiate.

InitialVal

The value of an object.

Options

Options for object creation.

RetHandle

A buffer for returning the pointer to the body of the object.

This function creates a new instance of the class Class in the group Group. If Group is NULL, the kernel assigns the object to a system-maintained default group. Optionally, you can pass an initial value for the object in Val. The option OK_FIX_OBJ (passed in Options) specifies that the newly created object should be fixed in cache upon return from the function.

2.10.3 okDeleteObj

Deletes an object from a database.

okError okDeleteObj(okEnv Env, okHandle Obj);

Env

An environment handle.

Obj

The object to delete.

This function removes the object obj from cache and reclaims its storage space on disk. After the function deletes the object, the kernel rejects attempts to access the object.

2.10.4 okFixObj

Fixes (or pins) an object in cache and returns a pointer to the object's body.

okError okFixObj(okEnv Env, okHandle Obj, 

   okLock LockMode, void *RetObjData);

Env

An environment handle.

Obj

The object to fix.

LockMode

The type of lock to apply to the object. OKAPI defines the following lock modes:

RetObjData

A buffer for returning the pointer to the body of the object.

This function fixes (or pins) the object Obj in cache and returns a pointer to the object's body in RetObjData. The kernel guarantees that a fixed object is not swapped out. In other words, the memory pointer returned in RetObjData is valid as long as the object remains fixed. Mode specifies the lock mode to apply to the object. In single-user mode, all lock requests are ignored.

This function allows you to directly manipulate the contents of an object. By casting the returned memory pointer to the appropriate pointer type, you can access the object body in the same manner as a C structure. Accessing data through a memory pointer instead of through an OKAPI function may be efficient, but it can cause problems with the integrity of the data. If changing attribute values through a memory pointer, you must notify the kernel of your changes by calling okPrepForUpdate, or by passing the appropriate flag to okUnfixObj.

To avoid memory leaks, you should call okUnfixObj after calling okFixObj to unfix the object once it is no longer needed. However, if you are certain that the cache is large enough to hold the objects that the application directly or indirectly handles in a transaction, you can reduce function call overhead by leaving the objects fixed. At the end of each transaction, the kernel automatically unfixes all objects in the cache.

2.10.5 okUnfixObj

Unfixes an object.

okError okUnfixObj(okEnv Env, 

   okHandle Obj, okBool isUpdated);

Env

An environment handle.

Obj

The object handle.

isUpdated

A Boolean flag indicating whether the object has been updated while fixed in cache.

This function unfixes (or un-pins) the object Obj and, if isUpdated is TRUE, marks the object as dirty. An object can be fixed when created or through a call to okFixObj. After an object is unfixed, the kernel may swap the object out at any time. Usually, it swaps out the object when the cache is nearly full.

Since an object may be fixed several times (such as when different modules of an application fix the object), the kernel keeps a fix count for each object in the cache. The kernel increments the counter whenever the application fixes the object, and decrements the counter whenever the application unfixes the object with okUnfixObj. The kernel does not swap out an object unless its fix count is zero.

2.10.6 okPrepForUpdate

Prepares an object for updating.

okError okPrepForUpdate(okEnv Env, okHandle Obj);

Env

An environment handle.

Obj

The object handle.

This function prepares an object Obj for updating. okPrepForUpdate acquires a write (or exclusive) lock on the object and marks the object as dirty. This function applies to objects that are fixed in cache. It makes no attempt to swap in an object if the object is not in the cache, and it does not increase the fix count of the object.

2.10.7 okSetShortLock

Acquires a lock on an object.

okError okSetShortLock(okEnv Env, okHandle Obj, 

   okLock LockMode);

Env

An environment handle.

Obj

The object handle.

LockMode

The mode of the lock to apply to the object. OKAPI defines the following lock modes:

Lock	Description
OK_NOLOCK	No lock
OK_ISLOCK	Intent shared lock
OK_IXLOCK	Intent exclusive lock
OK_SIXLOCK	Shared-intent exclusive lock
OK_SLOCK	Shared (read) lock
OK_XLOCK	Exclusive (write) lock
OK_ULOCK	Update lock

This function acquires a lock of the mode LockMode on the object Obj. If the lock request conflicts with an outstanding lock on the same object, the caller is blocked until the lock request is granted or rejected due to deadlock or time-out. In single-user mode, all lock requests are ignored.

2.10.8 okCreateObjs

Creates an array of objects from a single class.

okError okCreateObjs(okEnv Env, okHandle Group, okHandle Class, const okByte    

   *InitialVal, okU4B Options, okU4B ObjCount, okHandle RetHandles[]);

Env

An environment handle.

Group

Group in which to create objects.

Class

Class object to instantiate.

InitialVal

The value of objects.

Options

Options for object creation.

ObjCount

Number of objects to create.

RetHandles

A buffer for returning the pointers to the bodies of the objects.

This function creates a specified number (ObjCount) of new instances of the class Class in the group Group. If Group is NULL, the kernel assigns the objects to a system-maintained default group. Optionally, you can pass an initial value for the objects in InitialVal. The option OK_FIX_OBJ (passed in Options) specifies that the newly created objects should be fixed in cache upon return from the function.

2.10.9 okDeleteObjs

Deletes an array of objects from a database.

okError okDeleteObjs(okEnv Env, okU4B ObjCount, okHandle Objs[]);

Env

An environment handle.

ObjCount

Number of objects to delete.

Objs

Handles of objects to delete.

This function removes the objects Objs[] from cache and reclaims the storage space on disk. After the function deletes the objects, the kernel rejects attempts to access the objects.

2.10.10 okSetShortLocks

Acquires a lock on an array of objects.

okError okSetShortLocks(okEnv Env, okU4B ObjCount, okHandle Objs[], 

   okLock LockMode);

Env

An environment handle.

ObjCount

The number of objects to lock.

Objs

The handles of objects to lock.

LockMode

The mode of the lock to apply to the objects. OKAPI defines the following lock modes:

Lock	Description
OK_NOLOCK	No lock
OK_ISLOCK	Intent shared lock
OK_IXLOCK	Intent exclusive lock
OK_SIXLOCK	Shared-intent exclusive lock
OK_SLOCK	Shared (read) lock
OK_XLOCK	Exclusive (write) lock
OK_ULOCK	Update lock

This function acquires a lock of the mode LockMode on the objects Objs[]. If the lock request conflicts with an outstanding lock on the same object, the caller is blocked until the lock request is granted or rejected due to deadlock or time-out. In single-user mode, all lock requests are ignored.

2.10.11 okPrepForUpdates

Prepares an array of objects for updating.

okError okPrepForUpdates(okEnv Env, okU4B ObjCount, okHandle Objs[]);

Env

An environment handle.

ObjCount

The number of objects to prepare.

Objs

The handles of the objects to prepare.

This function prepares an array of objects Objs for updating. okPrepForUpdates acquires a write (or exclusive) lock on the objects and marks the objects as dirty. This function applies to objects that are fixed in cache. It makes no attempt to swap in objects if the objects are not in the cache, and it does not increase the fix count of the objects.

2.10.12 okFixObjs

Fixes (or pins) an array of objects in cache and returns a pointer to the body of each object.

okError okFixObjs(okEnv Env, okU4B ObjCount, okHandle Objs[], 

   okLock LockMode, void *RetObjData[]);

Env

An environment handle.

ObjCount

The number of objects to fix.

Objs

The objects to fix.

LockMode

The type of lock to apply to the object. OKAPI defines the following lock modes:

RetObjData

A buffer for returning the pointer to the body of each object.

This function fixes (or pins) the objects Objs[] in cache and returns a pointer to the body of each object in RetObjData. The kernel guarantees that fixed objects are not swapped out. In other words, the memory pointer returned in RetObjData is valid as long as the objects remain fixed. Mode specifies the lock mode to apply to the objects. In single-user mode, all lock requests are ignored.

This function allows you to directly manipulate the contents of objects. By casting the returned memory pointer to the appropriate pointer type, you can access the object body in the same manner as a C structure. Accessing data through a memory pointer instead of through an OKAPI function may be efficient, but it can cause problems with the integrity of the data. If changing attribute values through a memory pointer, you must notify the kernel of your changes by calling okPrepForUpdates, or by passing the appropriate flag to okUnfixObjs.

To avoid memory leaks, you should call okUnfixObjs after calling okFixObjs to unfix the objects once they are no longer needed. However, if you are certain that the cache is large enough to hold the objects that the application directly or indirectly handles in a transaction, you can reduce function call overhead by leaving the objects fixed. At the end of each transaction, the kernel automatically unfixes all objects in the cache.

2.10.13 okUnfixObjs

Unfixes an array of objects.

okError okUnfixObjs(okEnv Env, okU4B ObjCount,

   okHandle Objs[], okBool isUpdated);

Env

An environment handle.

ObjCount

The number of objects to be unfixed.

Objs

The objects to unfix.

isUpdated

A Boolean flag indicating whether the objects have been updated while fixed in cache.

This function unfixes (or un-pins) the objects Objs[] and, if isUpdated is TRUE, marks the objects as dirty. A group of objects can be fixed when created or through a call to okFixObjs. After the objects are unfixed, the kernel may swap the objects out at any time. Usually, it swaps out the objects when the cache is nearly full.

Since an object may be fixed several times (such as when different modules of an application fix the object), the kernel keeps a fix count for each object in the cache. The kernel increments the counter whenever the application fixes the object, and decrements the counter whenever the application unfixes the object with okUnfixObj or OkUnfixObjs. The kernel does not swap out an object unless its fix count is zero.

2.10.14 Object Sample Program

The following code demonstrates the use of object functions:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okEnv       Env;

okHandle    Database, Object;

okRef  Group, Class, ObjRef;

okObjData  ClassObj;

okError  e;


...


   /* assume Env and Database are set up properly */

   e = okFindGroup(Env, Database, sizeof("Faculty"), 

      "Faculty", &Group);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okFindClass(Env, Database, sizeof("Professor_s"),  "Professor_s", 

      &Class);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* fix the class object then release it */

   e = okFixObj(Env, Class, OK_NOLOCK, (okObjData *)&ClassObj);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okUnfixObj(Env, (okHandle)ClassObj, FALSE);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* create a new "Professor_s" object in "Faculty" group */

   e = okCreateObj(Env, Group, Class, NULL, OK_FIX_OBJ, &Object);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* set an exclusive lock on the "Dept_s" object */

   e = okSetShortLock(Env, Object, OK_XLOCK);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* release the new object then delete it */

   e = okUnfixObj(Env, (okHandle)Object, FALSE);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okDeleteObj(Env, Object);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.11.1 Object Information and Control Functions Compatibility Reference

This table lists the OKAPI object information and control functions.

2.11.2 okGetObjRef

Acquires a reference to an object.

okError okGetObjRef(okEnv Env, okHandle Obj, 

   okRef *RetRef);

Env

An environment handle.

Obj

The object handle.

RetRef

A buffer for returning the reference to the object.

This function returns a reference in RetRef to the object Obj. An object handle can be an object reference or a memory pointer to the body of the object. If Obj is already an object reference, the function returns the object reference in RetRef. If Obj is a memory pointer to the object body, okGetObjRef locates or creates an object reference to the object and returns it in RetRef.

2.11.3 okIsInstanceOf

Determines whether an object is an instance of a particular class.

okError okIsInstanceOf(okEnv Env, okHandle Obj, 

   okHandle Class, okBool isImmediate, okBool *RetResult);

Env

An environment handle.

Obj

The object handle.

Class

The class object.

isImmediate

A Boolean flag indicating whether to consider superclasses.

RetResult

A Boolean value to indicate whether the object is an instance of a class.

This function determines whether the object Obj is an instance of the class Class. It returns a Boolean result (either TRUE or FALSE) in RetResult. The argument isImmediate specifies whether the function should consider inheritance. If isImmediate is TRUE, the function returns TRUE only if Class is the class object of Obj. If isImmediate is FALSE, the function returns TRUE if Class is the class object or a superclass object of Obj.

On the Palm platform, if Class is the superclass object of obj, the function will return FALSE regardless of whether isImmediate is TRUE or FALSE.

2.11.4 okGetObjInfo

Returns information about an object.

okError okGetObjInfo(okEnv Env, okHandle Obj,

   okOID_s *RetObjID, okRef *RetDatabase, 

   okRef *RetGroup, okRef *RetClass, okObjInfo_s *RetInfo);

Env

An environment handle.

Obj

The object handle.

RetObjID

An optional buffer for returning the object ID.

RetDatabase

An optional buffer for returning the database of an object.

RetGroup

An optional buffer for returning the group of an object.

RetClass

An optional buffer for returning the class of an object.

RetInfo

A buffer for returning object information.

This function returns information regarding an object Obj, including its unique ID (in RetObjID) and associated meta-objects. The meta-objects include the database object (in RefDatabase), group object (in RetGroup), and class object (in RetClass). RetInfo provides the version and lock mode of the object in the following format:

typedef struct {

    okU4B Version;

    wsLockMode LockMode;

} okObjInfo_s;

2.11.5 okIsObjEqual

Determines whether two object handles are equal.

okError okIsObjEqual(okEnv Env, 

   okHandle Obj1, okHandle Obj2, okBool *RetResult);

Env

An environment handle.

Obj1

The first object handle to compare.

Obj2

The second object handle to compare.

RetResult

A Boolean value to indicate the result.

This function determines whether two object handles, Obj1 and Obj2, are equal. It considers two object handles equal only if they point to the same object.

2.11.6 okCtrlObjs

Applies control operations to an array of objects.

okError okCtrlObjs(okEnv Env, okU4B ObjCount,

   const okHandle ObjHandles[], okU4B Actions);

Env

An environment handle.

ObjCount

The number of objects in the control operation.

ObjHandles

The objects in the control operation.

Actions

The operations to apply to the objects. Actions can be any combination of the following:

• OK_FLUSH_OBJECT: Writes a copy of the object to disk if marked dirty.

• OK_FREE_OBJECT: Releases the memory space used by the body of an object. This option invalidates all direct memory pointers to the object body, but does not invalidate object references to the object. This is intended for use when the application no longer needs the object.

• OK_FREE_DESC: Releases the descriptor of an object and the body of the object if it exists in the cache.

  
  

  Important: Use of the OK_FREE_DESC option invalidates all existing object references, including those embedded in other cached objects. This is intended for use when memory is extremely scarce and the space used by object descriptors needs to be reclaimed.

  
  

This function allows you to apply the control operations specified in Actions to an array of objects ObjHandles.

2.11.7 okGetObjRefs

Gets references to an array of objects.

okError okGetObjRef(okEnv Env, okU4B ObjCount, okHandle Objs[], 

   okRef *RetRefs[]);

Env

An environment handle.

ObjCount

The number of objects.

Objs

The object handle.

RetRefs

A buffer for returning the references to the objects.

This function returns references in RetRefs[] to the objects in Objs[]. An object handle can be an object reference or a memory pointer to the body of the object. If Objs[] is already an object reference, the function returns the object reference in RetRefs[]. If Objs[] is a memory pointer to the object bodies, okGetObjRefs locates or creates object references to the objects and returns them in RetRefs[].

2.11.8 okFindRefs

Finds references to an array of objects, given an array of object IDs.

ok Error okFindRefs,( okEnv Env, okU4B ObjCount, okOID_s ObjIDs[], 

   okRef RetObjRefs[]);

Env

An environment handle.

ObjCount

The number of objects.

ObjIDs

The Object IDs.

RetObjRefs

A buffer for returning the references to the objects.

This function returns references in RetObjRefs[] to the objects identified in ObjIDs[].

2.11.9 Object Information and Control Sample Program

The following code demonstrates the use of the object information and control procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okRef Group, Class, ObjRef;

okHandle Object, NewObj;

Professor_s *Advisor;

okBool isa, isEqual;

okError e;


...


   e = okFindGroup(Env, Database, 

      sizeof("Faculty"), "Faculty", &Group);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okFindClass(Env, Database, 

      sizeof("Professor_s"), "Professor_s", &Class);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* create a new "Professor_s" object in "Faculty" group */

   e = okCreateObj(Env, Group, Class, NULL, OK_FIX_OBJ, &Object);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okGetObjRef(Env, Object, &ObjRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okIsInstanceOf(Env, Object, Class, TRUE, &isa);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   { 

      okOID_sObjID;

      okRefDatabase, Group, Class;


      e = okGetObjInfo(Env, Object, &ObjID, &Database, &Group, 

         &Class, NULL);

      if (OK_IS_ERROR(e)) { /* error handling */ }

   }


   e = okCtrlObjs(Env, 1, &Object, OK_FLUSH_OBJECT|OK_FREE_DESC);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* create a new "Dept_s" object */

   e = okCreateObj(Env, Group, Class, NULL, OK_FIX_OBJ, &NewObj);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okIsObjEqual(Env, Object, NewObj, &isEqual);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.12.1 Dynamic Array Attributes

When manipulating an attribute that is a dynamic array, you should set BufSize to sizeof(okArray), and BufPtr should point to a variable of type okArray. When getting an attribute, the kernel sets the Indicator field to the actual size of the returned data. If the Indicator is negative, the attribute has a null value.

Optionally, you can set a flag within the attrVal.BufSize which indicates to OKAPI that a dynamic array should be created. You can then pass the string inside of attrVal.BuffPtr as follows:

attrVal.BufSize = attrVal.Indicator = OK_NEW_ARRAY | strlen((char *) attrVal.BufPtr);

2.12.2 Attribute Value Functions Compatibility Reference

This table lists the OKAPI functions that manage attribute values.

2.12.3 okGetAttrVal

Extracts the value of an attribute and returns either a copy of the value or a direct memory pointer to the attribute value in the object body.

okError okGetAttrVal(okEnv Env, okHandle Obj, 

   okHandle AttrObj, okBool toCopy, okAttrVal_s *RetVal);

Env

An environment handle.

Obj

An object handle.

AttrObj

An object representing the attribute to access.

toCopy

A Boolean flag:

TRUE - On Win32 and EPOC platforms it returns a pointer to a pointer to the attribute. On the Palm platform it returns a pointer directly to the attribute.

FALSE - On Win32 and EPOC it returns a pointer directly to the attribute. The Palm platform does not support a FALSE value for this parameter.

RetVal

A buffer for returning a value.

This function extracts the value of the attribute AttrObj and returns in RetVal either a copy of the value (if toCopy is TRUE) or a direct memory pointer to the attribute value in the object body (if toCopy is FALSE). If toCopy is FALSE, the function fixes the object in cache to ensure the validity of the returned memory pointer. As a result, you must explicitly unfix the object by calling okUnfixObj. You do not need to fix the object before calling this function.

If the size of the attribute is small, you should make a copy of the attribute value, and avoid the function call overhead of explicitly unfixing the object. However, if the attribute is large, such as a dynamic or an embedded array, it may be more efficient to obtain a memory pointer to the object and access the attribute value directly.

If the attribute contains a dynamic array, okGetAttrVal returns a pointer to the dynamic array. The type of the attribute value returned is okArray, which is a generic pointer type. The elements in the array are not returned in the buffer provided by RetVal. If toCopy is TRUE, okGetAttrVal creates a new copy of the dynamic array. You must explicitly release the copy of the array using okDeleteArray when it is no longer needed. However, you do not need to unfix the object itself. If toCopy is FALSE, you do not need to release the dynamic array the function returns, but you must unfix its containing object explicitly using okUnfixObj.

2.12.4 okSetAttrVal

Updates the value of an attribute.

okError okSetAttrVal(okEnv Env, okHandle Obj, 

      okHandle AttrObj, const okAttrVal_s *NewVal);

Env

An environment handle.

Obj

An object handle.

AttrObj

An object representing the attribute to access.

NewVal

A buffer containing a new value.

This function updates the value of the attribute identified by AttrObj in object Obj with the new value specified in NewVal. You do not need to fix the object before calling this function. If the attribute contains a dynamic array, the NewVal buffer should point to a dynamic array. This function releases the original dynamic array in the attribute, creates the new dynamic array in NewVal, and places the new array in the object.

2.12.5 okGetAttrValAt

Extracts the value of the attribute at a specified position and returns either a copy of the value or a direct memory pointer to the attribute value in the object body.

okError okGetAttrValAt(okEnv Env, okHandle Obj, 

      okU4B Position, okBool toCopy, okAttrVal_s *RetVal);

Env

An environment handle.

Obj

An object handle.

Position

The position of the attribute to access.

toCopy

A Boolean flag:

TRUE - On Win32 and EPOC platforms it returns a pointer to a pointer to the attribute. On the Palm platform it returns a pointer directly to the attribute.

FALSE - On Win32 and EPOC it returns a pointer directly to the attribute. The Palm platform does not support a FALSE value for this parameter.

RetVal

A buffer for returning a value.

This function extracts the value of the attribute at position Position. It returns (in RetVal) either a copy of the value if toCopy is TRUE, or a direct memory pointer to the attribute value in the object body if toCopy is FALSE. If toCopy is FALSE, the object is implicitly fixed, which guarantees the validity of the returned memory pointer. Consequently, the caller must unfix the object with okUnfixObj. The object does not need to be fixed before a call to this function. See the preceding discussion of okGetAttrVal for more information.

2.12.6 okSetAttrValAt

Updates the value of an attribute at a specified position.

okError okSetAttrValAt(okEnv Env, okHandle Obj, 

   okU4B Position, const okAttrVal_s *NewVal);

Env

An environment handle.

Obj

An object handle.

Position

The position of the attribute to access.

NewVal

A buffer containing a new value.

This function updates the value of the attribute at position Position in object Obj with the new value specified in NewVal. The object does not need to be fixed before a call to this function. See the preceding discussion of okSetAttrVals for more information.

2.12.7 okSetAttrVals

Updates the values of multiple attributes listed by their names.

okError okSetAttrVals(okEnv Env, okHandle ObjH, okSize AttrCnt,

      okHandle AttrH, const okAttrVal_s *NewVal);

Env

An environment handle.

ObjH

An object handle.

AttrCnt

The number of attributes to update.

AttrH

The handles of the attributes to update.

NewVal

A buffer containing the new values.

This function updates the value of the attributes identified by AttrObj in object ObjH with the new value specified in NewVal. You do not need to fix the object before calling this function. If the attribute contains a dynamic array, the NewVal buffer should point to a dynamic array. This function releases the original dynamic array in the attribute, creates the new dynamic array in NewVal, and places the new array in the object.

2.12.8 okSetAttrValsAt

Updates the value of attributes at a specified position.

okError okSetAttrValsAt(okEnv Env, okHandle ObjH, okSize AttrPosCnt, 

   okU4B *Position, const okAttrVal_s *NewVal);

Env

An environment handle.

ObjH

An object handle.

AttrPosCnt

The number of attributes to update.

Position

A buffer containing the positions of the attributes to access.

NewVal

A buffer containing the new values.

This function updates the value of the attribute at position Position in object ObjH with the new value specified in NewVal. The object does not need to be fixed before a call to this function. See the preceding discussion of okSetAttrVal for more information.

2.12.9 Attribute Value Sample Program

The following code demonstrates the use of the attribute value procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"

#define DEPT_NAME "Computer Science"


okEnv Env;

okHandle  Object, Group;

okRef AttrRef, AttrRefs[2];

okArray DeptName;

okAttrVal_s Value, AttrVals[2];

okError  e;

okU4B AttrPoss[2];


...


   /* assume class "Dept_s" is in Class, find its attribute "Name" */

   e = okFindAttr(Env, Class, 

      sizeof("Name"), "Name", NULL, &AttrRef, NULL);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   

   /* create a new "Dept_s" object */

   e = okCreateObj(Env, Group, Class, NULL, OK_FIX_OBJ, &Object);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   

   /* prepare the string "Computer Science" in Value */

   e = okCreateArray(Env, &DeptName,

      sizeof(DEPT_NAME), DEPT_NAME);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   Value.BufSize = Value.Indicator = sizeof(okArray);

   Value.BufPtr = (okByte *)&DeptName;

   

   /* a silly sequence just to illustrate usage ... */

   e = okSetAttrVal(Env, Object, AttrRef, &Value);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okGetAttrVal(Env, Object, AttrRef, FALSE, &Value);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okSetAttrValAt(Env, Object, 0, &Value);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okGetAttrValAt(Env, Object, 0, FALSE, &Value);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okGetAttrVals (Env, Object, Obj, 2, AttrRefs, AttrVals);

   e = okGetAttrVals At (Env, Object, 2, AttrPoss, AttrVals);

...

2.13.1 Method Invocation Function Compatibility Reference

This table shows the platform compatibility of okExecMeth.

2.13.2 okExecMeth

Executes a method.

okError okExecMeth (okEnv env, okHandle dbH, okHandle meth, 

   okHandle obj,  okSize argValCount, okAttrVal_s  *argVals, 

   okU1B  *outFlag, okAttrVal_s  *result );

Env

An environment handle.

dbH

Handle to the database.

meth

The method object to execute.

obj

The handle to the object containing the method to execute.

argValCount

The number of arguments passed to the method.

argVals

An array of arguments passed to the method.

outFlag

A flag indicating IN/OUT parameters.

result

The result of the method.

This function executes the method meth. If the method is a class method, obj can be NULL. Otherwise, obj is a valid object handle. ArgValCount is the number of argument values provided in the argVals array. argVals is an array of okAttrVal_s structures, each containing an argument value. OutFlag is an array of ArgValCount bytes. A non-zero value in the n-th byte means that the n-th argument is an IN/OUT argument. Set outFlag to NULL if the method does not use IN/OUT arguments. The corresponding Java type of an IN/OUT argument must be a mutable type. The kernel returns the result in the okAttrVal_s structure pointed to by result.

2.13.3 Method Invocation Sample Program

The following code demonstrates the use of the method invocation procedure:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


#define  DEPT_NAME "Computer Science"


...


   okAttrVal_s argVals[2], res;

   /* declare other variables here */

   /* find the void HireStaff(int ID, String Name) method */

   e = okFindMethod(Env, Database, DeptRef, OK_INSTANCE_METHOD,

      9, "HireStaff", 22, 

      "(ILjava/lang/String;)V", &MethRef);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   /* use iterator to get a department object into variable dept */

   /* initialize argVal2[0] and argVals[1] here */

   e = okExecMeth(Env, Database, MethRef, dept, 2, argVals,NULL,&res);


...

2.14.1 Iterator Functions Compatibility Reference

This table lists the OKAPI iterator functions.

2.14.2 okCreateIterator

Prepares a query against instances of a class and returns a transient iterator object.

okError okCreateIterator(okEnv Env, okHandle Group,

   okHandle Class, okBool isImmediate, okU4B CondCount,

   const okSearchCond_s SearchConds[], Reserved, 

   okU4B UpdAttrCount, const okU4B UpdAttrPos[], 

   okIterator *RetIter);

Env

An environment handle.

Group

A group object.

Class

A class object.

isImmediate

A Boolean flag which is TRUE if subclasses should be included in the query, and FALSE if subclasses should not be included.

CondCount

The number of search conditions.

SearchConds

An array of search conditions of type okSearchCond_s.

Reserved

Reserved parameter. No value required.

UpdAttrCount

The number of attributes to update.

UpdAttrPos

The array of positions of the attributes the caller intends to update in the qualified instances.

RetIter

A buffer for returning an iterator.

This function prepares a query against instances of the class Class in the object group Group. It returns a transient iterator object in RetIter. UpdAttrPos enables the kernel to avoid picking an access path whose scanning order may be affected by the updates.

2.14.3 okDeleteIterator

Terminates a query associated with an iterator.

okError okDeleteIterator(okEnv Env, okIterator Iter);

Env

An environment handle.

Iter

An iterator.

This function releases all system resources allocated to the iterator, including the iterator object.

2.14.4 okIterate

Advances the cursor associated with an iterator and returns a pointer to the body of the current object.

okError okIterate(okEnv Env, okIterator Iter, 

   okU4B Action, okObjData *RetObj);

Env

An environment handle.

Iter

An iterator.

Action

Specifies the direction in which the cursor should move:

• OK_FIRST: move the cursor to the first qualified object.

• OK_LAST: move the cursor to the last qualified object.

• OK_NEXT: move the cursor to the next qualified object.

• OK_PRIOR: move the cursor to the prior qualified object.

RetObj

A buffer for returning a pointer to the object body.

This function advances the cursor associated with an iterator and returns (in RetObj) a pointer to the body of the current object. The kernel fixes the object returned by the function and automatically unfixes it when the cursor is moved. okIterate returns NULL in RetObj if:

• The direction is OK_NEXT and the iterator reaches the end of the scan.

• The direction is OK_PRIOR and the iterator reaches the beginning of the scan.

Neither event returns an error code.

2.14.5 okGetCursor

Returns the current cursor position of an iterator.

okError okGetCursor(okEnv Env, okIterator Iter, 

   okCursor *RetCursor);

Env

An environment handle.

Iter

An iterator.

RetCursor

A buffer for returning the cursor.

This function returns in RetCursor the current cursor position of an iterator. A cursor returned by okGetCursor is a transient object. You can use the returned cursor to alter the cursor position of Iter.

After calling okSetCursor, the user must call okIterate to get the reference to the object. For example:

okSetCursor (env, iterHandle, &RetCursor);

okIterate (env, iterHandle, OK_PRIOR, &foundRef);

okIterate (env, iterHandle, OK_NEXT, &foundRef);

2.14.6 okSetCursor

Changes the current cursor position of an iterator.

okError okSetCursor(okEnv Env, okIterator Iter,

   okCursor Cursor);

Env

An environment handle.

Iter

An iterator.

Cursor

The new cursor position.

This function changes the current cursor position of an iterator to that specified by Cursor, which you can obtain with okGetCursor. All cursors associated with an iterator are automatically deleted when okDeleteIterator deletes the iterator object. After calling okSetCursor, the user must call okIterate to get the reference of the object.

2.14.7 Iterator Sample Program

The following code demonstrates the use of the iterator procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okEnv Env;

okHandle Database;

okRef  Group, Class;

okIterator  Itor;

okCursor  Cursor;

Professor_S *Advisor;

okError  e;

okU4B  MinID = 101;

okU2B  MaxAge = 50;


...


   okSearchCond_s Cond[2] = { /* ID >= 101 && Age < 50 */

      {0, OK_GE, OK_AND, 0, 0,{sizeof(okU4B), 

        (unsigned char *)&MinID,sizeof(okU4B)}},

      {2, OK_LT, OK_AND, 0, 0,{sizeof(okU2B), 

        (unsigned char *)&MaxAge,sizeof(okU2B)}}

   };


   e = okFindGroup(Env, Database, sizeof("Faculty"), 

      "Faculty", &Group);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okFindClass(Env, Database, sizeof("Professor_s"),  

      "Professor_s", &Class);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okCreateIterator(Env, Group, Class, TRUE, 2, Cond, 

      0, 0, NULL, &Itor);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okIterate(Env, Itor, OK_NEXT, (okObjData *)&Advisor);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okGetCursor(Env, Itor, &Cursor);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okSetCursor(Env, Itor, Cursor);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okDeleteIterator(Env, Itor);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.15.1 Index Functions Compatibility Reference

This table lists the OKAPI index management functions.

2.15.2 okCreateIndex

Creates an index on a set of attributes.

okError okCreateIndex(okEnv Env, okHandle Group,

   okHandle Class, okU4B NumAttrs, okU4B AttrPos[],

   okU2B IndexType, okU2B Options, okU2B *RetIndexNo);

Env

An environment handle.

Group

A group object.

Class

A class object.

NumAttrs

The number of attributes on which the index is created.

AttrPos

The position of the attributes on which the index is created. Starts at 0.

IndexType

The type of index to create. Currently OK_BTREE, for a B-tree index, is the only supported value for this parameter.

Options

Additional options for index creation.

RetIndexNo

A buffer for returning the number of the new index.

This function creates an index on a set of attributes indicated by AttrPos. It creates the index on instances of Class in the object group Group. Options specifies key constraints on each constructed index. Valid key constraints include:

• OK_UNIQUE_KEY: key values must be unique and NULL values are allowed.

• OK_PRIMARY_KEY: key values must be unique and NULL values are not allowed.

After creating the index, the kernel automatically maintains the index whenever objects are created, updated, or deleted. If the specified index already exists, okCreateIndex does nothing. An error code is not returned.

2.15.3 okDeleteIndex

Deletes an index.

okError okDeleteIndex(okEnv Env, okHandle Group, 

   okHandle Class, okU4B IndexNo, okU2B IndexType);

Env

An environment handle.

Group

A group object.

Class

A class object.

IndexNo

The index number or attribute position.

IndexType

The type of index to delete. Currently OK_BTREE (for a b-tree index) is the only supported value for this parameter.

This function deletes the specified index. The arguments Group, Class, and IndexNo identify the index to delete. If the index is a multi-attribute index, IndexNo must be the index number returned by okCreateIndex. If the index is a single-attribute index, IndexNo can be the attribute position. If the index does not exist, okDeleteIndex does nothing. An error code is not returned.

2.15.4 okGetIndexInfo

Returns information pertaining to an index.

okError okGetIndexInfo(okEnv Env, okHandle Group, 

   okHandle Class, okU4B AttrPos, okU2B IndexType, 

   okU2B *RetInfo);

Env

An environment handle.

Group

A group object.

Class

A class object.

AttrPos

The index number or attribute position.

IndexType

The type of index on which to return information. Currently OK_BTREE (for a b-tree index) is the only supported value for this parameter.

RetInfo

The buffer for returning index information.

This function returns information in RetInfo pertaining to the index at attribute position AttrPos of Class instances in the group Group.

The returned bit map, which is placed in RefInfo, uses the following bit fields:

• OK_INDEX_EXISTS: the index exists; if the index does not exist, the return value is zero.

• OK_UNIQUE_KEY: key values must be unique and NULL values are allowed.

• OK_PRIMARY_KEY: key values must be unique and NULL values are not allowed.

If you are getting an index on four attributes, for example:

attrpos[]={0,1,2,3}

You can call okGetIndexInfo on attribute 0 to return the index information. Calling okGetIndexInfo on any other attribute will return a value of 0.

2.15.5 okNextIndex

Returns the next index for a given group and class.

okError okNextIndex(okEnv Env, okHandle Group, 

   okHandle Class, okIdxInfo_s *Info);

Env

An environment handle.

Group

A group object.

Class

A class object.

Info

The index number or attribute position.

This function returns in Info the next index in the specified group and class. The first call should set the Group argument to the appropriate group and the Info.AttrPos array to NULL. Subsequent calls should set the group to NULL. After retrieving the information for all the indexes, you should delete the Info.AttrPos array. okError returns TRUE if the an index exists, and FALSE if no index exists.

2.15.6 Index Sample Program

The following code demonstrates the use of the index procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okRef  Group, Class;

okU2B  IndexType;

okError  e;


...


   e = okFindGroup(Env, Database, sizeof("Faculty"), 

      "Faculty", &Group);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okFindClass(Env, Database, sizeof("Professor_s"),  "Professor_s",

      &Class);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* create a B-Tree type of index on attribute ID */

   e = okCreateIndex(Env, Group, Class, 0, OK_BTREE,  OK_UNIQUE_KEY);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okGetIndexInfo(Env, Group, Class, 0, &IndexType);

   if (!(RetInfo & OK_INDEX_EXISTS) { /* error handling */ }


   e = okDeleteIndex(Env, Group, Class, 0, OK_BTREE);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.16.1 Object Naming Functions Compatibility Reference

This table lists the OKAPI functions that manage object names.

2.16.2 okCreateName

Creates a name for an object.

okError okCreateName(okEnv Env, okHandle Directory, 

   okSize ObjNameLen, okName ObjNamePtr, okHandle Obj);

Env

An environment handle.

Directory

A directory object.

ObjNameLen

The length of an object name.

ObjNamePtr

A name for an object.

Obj

An object.

This function creates a name for the object Obj, relative to the directory object Directory. ObjNamePtr must be a NULL-terminated string. It cannot be empty. Instead of specifying the root directory object in a database, the caller can specify the database object. You can use the database object interchangeably with the root directory object in the Directory parameter for all object naming functions.

If you are using a one-level naming system, you need only to use the database reference for the Directory parameter value.

If you are using a multi-level naming system, you must create directory objects for each level. To create a directory object, use NULL as the obj parameter value and use the directory object for the Directory parameter value.

2.16.3 okDeleteName

Deletes an object name.

okError okDeleteName(okEnv Env, okHandle Directory, 

   okSize ObjNameLen, okName ObjNamePtr);

Env

An environment handle.

Directory

A directory object.

ObjNameLen

The length of an object name.

ObjNamePtr

A name for an object.

This function deletes the object name ObjNamePtr relative to the directory object Directory from the name hierarchy in the database. Instead of specifying the root directory object in a database, the caller can specify the database object. You can use the database object interchangeably with the root directory object in the Directory parameter for all object naming functions.

2.16.4 okFindObj

Finds an object name.

okError okFindObj(okEnv Env, okHandle Directory, 

   okSize ObjNameLen, okName ObjNamePtr, 

   okRef *RetObj, okBool *isDirectory);

Env

An environment handle.

Directory

A directory object.

ObjNameLen

The length of an object name.

ObjNamePtr

A name for an object.

RetObj

A buffer for returning the object reference.

isDirectory

A buffer for returning a Boolean flag which is TRUE if the object found is a directory object.

This function locates the object with the name specified by ObjNamePtr relative to Directory. The function returns a reference to the object, if found, in RetObj. If the object cannot be found, the function returns a NULL reference in RetObj. This is not considered an error. A Boolean flag returned in isDirectory indicates whether the object found is a directory object. Instead of specifying the root directory object in a database, the caller can specify the database object. You can use the database object interchangeably with the root directory object in the Directory parameter for all object naming functions.

2.16.5 Object Naming Sample Program

The following code demonstrates the use of the object naming procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okRef  Group, Class;

Professor_s *Chairman;

okError  e;


...


   /* create a directory called "EECS" */

   e = okCreateName(Env, Database /* to use root directory */,  sizeof("EECS"),

       "EECS", NULL);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* create a new professor object in Chairman */

   e = okFindGroup(Env, Database, 

      sizeof("Faculty"), "Faculty", &Group);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okFindClass(Env, Database, 

      sizeof("Professor_s"), "Professor_s", &Class);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okCreateObj(Env, Group, Class, 

      NULL, OK_FIX_OBJ, (okObjData *)&Chairman);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   /* assign "\EECS\CHAIRMAN" as name of a new "Professor_s" object */

   e = okCreateName(Env, Database, 

      sizeof("\\EECS\\CHAIRMAN"), "\\EECS\\CHAIRMAN", Chairman);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okFindObj(Env, Database, 

      sizeof("\\EECS\\CHAIRMAN"), "\\EECS\\CHAIRMAN", &Chairman, NULL);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okDeleteName(Env, Database, 

      sizeof("\\EECS\\CHAIRMAN"), "\\EECS\\CHAIRMAN");

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.17.1 Relationship Functions Compatibility Reference

This table lists the OKAPI functions that manage relationships.

2.17.2 okCreateRel

Establishes a relationship between two classes.

okError okCreateRel(okEnv Env, okHandle FromClass,

   okHandle FromAttr, okHandle ToClass, 

   okHandle ToAttr, okU4B Options);

Env

An environment handle.

FromClass

The first class involved in the relationship.

FromAttr

The attribute in the first class of the relationship.

ToClass

The second class involved in the relationship.

ToAttr

The attribute in the second class of the relation­ship.

Options

The type of relationship. Allowable values:

• OK_REF_INTEGRITY: for referential integrity.

• OK_CASCADE_DEL: for cascading deletion.

• OK_RESTRICT_DEL: for restricted deletion.

• OK_ONE_PARENT: for one parent only.

This function establishes a relationship between classes FromClass and ToClass. The relationship is maintained through the attribute FromAttr in FromClass and the attribute ToAttr in ToClass. Note that the kernel can maintain a relationship properly only if all object updates are made through the okCreateObj, okDeleteObj, okSetAttrVal, and okSetAttrValAt functions. Specifically, a direct modification to an attribute which participates in a relationship may cause a violation of the constraints required of the relationship. This function only works on the class attributes.

After creating the relationship between two classes and instantiating objects from those classes, you must update each objects class attribute with the reference to the related object using okSetAttrVal or okSetAttrValAt. The related object's class attribute will be updated automatically.

2.17.3 okDeleteRel

Deletes a relationship.

okError okDeleteRel(okEnv Env, okHandle FromClass, 

   okHandle FromAttr, okHandle ToClass, okHandle ToAttr);

Env

An environment handle.

FromClass

The first class involved in the relationship.

FromAttr

The attribute in the first class of the relationship.

ToClass

The second class involved in the relationship.

ToAttr

The attribute in the second class of the relation­ship.

This function deletes a previously established relationship maintained in the attribute FromAttr in FromClass and the attribute ToAttr in ToClass.

2.17.4 Relationship Sample Program

The following code demonstrates the use of the relationship procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okRef  DeptClass, StaffAttr, ProfClass, DeptAttr;

okError  e;


...


   e = okFindClass(Env, Database, sizeof("Dept_s"), "Dept_s",  &DeptClass);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okFindAttr(Env, DeptClass, sizeof("Staff"), "Staff", 

      NULL, &StaffAttr, NULL);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okFindClass(Env, Database, sizeof("Professor_s"),

      "Professor_s", &ProfClass);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okFindAttr(Env, ProfClass, sizeof("Dept"), "Dept", 

      NULL, &DeptAttr, NULL);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okCreateRel(Env, DeptClass, StaffAttr, ProfClass, DeptAttr,

      OK_REF_INTEGRITY);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okDeleteRel(Env, DeptClass, StaffAttr, ProfClass,  DeptAttr);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.18.1 BLOB Functions Compatibility Reference

This table lists the OKAPI functions that manage binary large objects (BLOBs).

2.18.2 okCreateBlob

Creates a BLOB.

okError okCreateBlob(okEnv Env, okHandle Group, 

   okU4B Size, okU4B EstimatedSize, okRef *RetBlobObj);

Env

An environment handle.

Group

A group object.

Size

The size of BLOB data in bytes.

EstimatedSize

The estimated size of the large object in bytes.

RetBlobObj

A buffer for returning a reference to a BLOB object.

This function creates a new BLOB in the object group Group and returns a reference to it in RetBlobObj. After creating the BLOB, the kernel guarantees that the object can grow to at least EstimatedSize bytes, subject to the actual amount of space available on disk. On the Palm Computing Platform, the maximum allowable size for a BLOB is 64K. The argument Size specifies the initial size of the BLOB object. A large object can grow to at least two megabytes, regardless of the value specified in EstimatedSize. The maximum size allowable for a large object is two gigabytes.

2.18.3 okDeleteBlob

Deletes a BLOB.

okError okDeleteBlob(okEnv Env, okHandle BlobObj);

Env

An environment handle.

BlobObj

A handle to the BLOB object to delete.

This function deletes a BLOB and releases the space used by the BLOB.

2.18.4 okGetBlobVal

Retrieves a portion of a BLOB starting from a given byte offset.

okError okGetBlobVal(okEnv Env, okHandle BlobObj, 

   okU4B Offset, okU4B Size, okAttrVal_s *RetVal);

Env

An environment handle.

BlobObj

A handle to the BLOB object to read from.

Offset

The byte offset into a BLOB object.

Size

The size of BLOB data in bytes.

RetVal

A buffer for returning the BLOB data in bytes.

This function retrieves a portion of a BLOB BlobObj, starting from a given byte offset. The value retrieved and its length are returned in the buffer and indicator specified in RetVal.

2.18.5 okSetBlobVal

Modifies a portion of a BLOB.

okError okSetBlobVal(okEnv Env, okHandle BlobObj, 

   okU4B Offset, okU4B Size, okAttrVal_s *NewVal);

Env

An environment handle.

BlobObj

A handle to the BLOB to modify.

Offset

The byte offset into a BLOB.

Size

The size of BLOB data in bytes.

NewVal

A buffer containing the new data value.

This function modifies a portion of a BLOB. The new value and its length are specified in NewVal. You must adjust the size of the BLOB to accommodate the modification prior to calling okSetBlobVal. For example, to append new data to the end of a large object, the size of the large object must first be adjusted with a call to okSetBlobSize to ensure that the new data fits into the large object.

2.18.6 okSetBlobSize

Adjusts the size of a BLOB.

okError okSetBlobSize(okEnv Env, okHandle BlobObj,

   okU4B Size);

Env

An environment handle.

BlobObj

A handle to the BLOB object to modify.

Size

The new size of the BLOB data in bytes.

This function adjusts the size of a BLOB. You can expand a large object by specifying a Size that is larger than the current size of BlobObj. Similarly, you can truncate a large object by specifying a Size that is smaller than the current size of BlobObj.

2.18.7 okGetBlobSize

Returns the size of a BLOB.

okError okGetBlobSize(okEnv Env, okHandle BlobObj, 

   okU4B *RetSize);

Env

An environment handle.

BlobObj

A handle to a BLOB object.

RetSize

The size of the BLOB in bytes.

This function returns in RetSize the current size in bytes of a BLOB BlobObj.

2.18.8 BLOB Sample Program

The following code demonstrates the use of the procedures that manage BLOBs:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


#define  BUF_SIZE 1024

#define  PICTURE_SIZE ((okU4B)10*BUF_SIZE)


okAttrVal_s BlobVal;

okByte Buffer[BUF_SIZE];

okRef Group, Blob;

okU4B BlobSize;

okError e;


...


   /* create a blob in a group */

   e = okCreateBlob(Env, Group, PICTURE_SIZE /* a hint */, &Blob);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okSetBlobSize(Env, Blob, sizeof(Buffer));

   if (OK_IS_ERROR(e)) { /* error handling */ }


   memset((void *)Buffer, 1, sizeof(Buffer));

   memset((void *)&BlobVal, 0, sizeof(BlobVal));

   BlobVal.BufSize = BlobVal.Indicator = BUF_SIZE;

   BlobVal.BufPtr = Buffer;

   e = okSetBlobVal(Env, Blob, 0, &BlobVal);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okGetBlobVal(Env, Blob, 0, BUF_SIZE, &BlobVal);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okGetBlobSize(Env, Blob, BUF_SIZE, &BlobSize);

   if (OK_IS_ERROR(e)) { /* error handling */ }


   e = okDeleteBlob(Env, Blob);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.19.1 Transaction Function Compatibility Reference

This table lists the OKAPI functions that manage transactions.

2.19.2 okTransact

Controls the outcome of the current transaction and optionally starts a new transaction.

okError okTransact(okEnv Env, okU4B Action);

Env

An environment handle.

Action

Action to perform.

This function controls the outcome of the current transaction and, optionally, starts a new transaction, as specified by the flags in the bit map Action. Action can take the following flags:

For most OKAPI functions that affect objects in a database, a transaction is automatically started if one is not already active.

2.19.3 okSetIsolationLevel

Sets the current isolation level.

okError okSetIsolationLevel (okEnv Env, okU2B Level);

Env

An environment handle.

Level

Isolation level. Allowable values:

• OK_TXN_SINGLE_USER: for single user.

• OK_TXN_READ_COMMITTED: for read committed.

• OK_TXN_REPEATABLE_READ: for repeatable read.

• OK_TXN_SERIALIZABLE: for serializable.

2.19.4 okGetIsolationLevel

Gets the current isolation level.

okError okGetIsolationLevel (okEnv Env, okU2B *Level);

Env

An environment handle.

Level

A buffer for returning the isolation level.

2.19.5 Transaction Sample Program

The following code demonstrates the okTransact procedure:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okError  e;


...


   e = okTransact(Env, OK_BEGIN);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   /* do something ... */

   e = okTransact(Env, OK_COMMIT_END);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...

2.20.1 Dynamic Array Functions Compatibility Reference

This table lists the OKAPI functions that manage dynamic arrays.

2.20.2 okCreateArray

Creates a new dynamic array.

okError okCreateArray (okEnv Env, okArray *RetArray, 

    okU4B Size, const okByte *Data);

Env

An environment handle.

RetArray

A buffer for returning a pointer to the new dynamic array.

Size

The size of data in a dynamic array.

Data

Data value for a dynamic array.

This procedure creates an array and returns a pointer to the new array in RetArray. If Data is NULL, the initial value of the dynamic array is not initialized. This function assumes that RetArray does not point to a valid dynamic array before the call. To avoid a memory leak, the caller should release any valid dynamic array pointed to by RetArray before passing RetArray to okCreateArray. It is an error if RetArray is NULL.

Generally, you should call okCreateArray to initialize an array before performing any other operation on it. Alternatively, you can initialize it by setting it directly to NULL, as follows:

okArray anArray = NULL;

2.20.3 okDeleteArray

Deallocates the memory occupied by a dynamic array.

okError okDeleteArray(okEnv Env, okArray *Array);

Env

An environment handle.

Array

A pointer to a dynamic array.

This procedure deallocates the memory occupied by a dynamic array pointed to by Array. The function sets the value pointed to by Array to NULL. If Array is NULL prior to the call, okDeleteArray performs no action.

2.20.4 okGetArraySize

Retrieves the size, in bytes, of a dynamic array.

okError okGetArraySize(okEnv Env, const okArray *Array, 

   okU4B *RetSize);

Env

An environment handle.

Array

A pointer to a dynamic array.

RetSize

A buffer for returning the size of a dynamic array.

This procedure retrieves the size in bytes of a dynamic array pointed to by Array. It returns 0 if Array is NULL or if Array points to a NULL pointer.

2.20.5 okSetArraySize

Sets the size in bytes of a dynamic array.

okError okSetArraySize(okEnv Env, okArray *Array, 

   okU4B NewSize);

Env

An environment handle.

Array

A pointer to a dynamic array.

NewSize

The new size of the dynamic array.

This procedure adjusts the size of the dynamic array pointed to by Array. If Array points to a NULL pointer and NewSize is greater than zero, okSetArraySize creates a new array. If NewSize is larger than or equal to the original size of the dynamic array, the original value of the dynamic array remains intact. The newly added memory is not initialized. If NewSize is smaller than the original size of the dynamic array, the value in the array is truncated according to NewSize. You can use this function when you know how many bytes are to be added to a dynamic array. Instead of calling okAppendArray incrementally to append each data item to the dynamic array, you can adjust the size once and assign the data items directly into the array, treating it as a regular C array.

2.20.6 okAppendArray

Appends data to the end of a dynamic array.

okError okAppendArray(okEnv Env, okArray *Array, 

   okU4B Size, const okByte *Data);

Env

An environment handle.

Array

A pointer to a dynamic array.

Size

The size of data in a dynamic array.

Data

Data value for a dynamic array.

This procedure appends Size bytes of new data (pointed to by Data) to the end of a dynamic array pointed to by Array. If Array originally points to a NULL pointer and Size is greater than zero, okAppendArray creates a new array. If Data is NULL, it does not initialize the newly appended area. It is an error if Array is NULL.

2.20.7 okCopyArray

Creates a copy of a dynamic array.

okError okCopyArray(okEnv NewEnv, okArray *RetNewArray,

   okEnv OldEnv, const okArray *OldArray);

NewEnv

The environment handle for the target array.

RetNewArray

The target array.

OldEnv

The environment handle for the source array.

OldArray

The source array.

This function creates a copy of a dynamic array pointed to by OldArray and returns a pointer to it in RetNewArray. It does not release a dynamic array pointed to by OldArray. To avoid memory leaks, you should release any valid dynamic array pointed to by RetNewArray before passing it to this function. If OldArray is NULL or points to a NULL pointer, the function returns a NULL pointer in RetNewArray. It is an error if RetNewArray is NULL.

2.20.8 okCreateMDArray

Creates a new multi-dimensional array.

okError okCreateMDArray (okEnv Env, okSize Dim, const okSize *Size, okArray *d);

Env

An environment handle.

Dim

Dimension. The number of elements.

Size

The size of data in each element (bytes).

d

The array handle.

2.20.9 okCopyMDArray

Copies a multi-dimensional array.

okError okCopyMDArray (okEnv Env, okSize Dim, okArray s, okArray *d);

Env

An environment handle.

Dim

Dimension. The number of elements.

s

The source array.

d

The target array.

2.20.10 okFreeMDArray

Frees a multi-dimensional array.

okError okFreeMDArray (okEnv Env, okSize Dim, okArray a);

Env

An environment handle.

Dim

Dimension. The number of elements.

a

A handle to the array to free.

2.20.11 Dynamic Array Sample Program

The following code demonstrates the use of the dynamic array procedures:

#include "okbasic.h"

#include "okerr.h"

#include "okapi.h"


okChar *CityName = "San Jose";

okU4B CityPopulation = 300000;

okU4B ArraySize;      /* size of a dynamic array */

okArray City;         /* dynamic array of okChar */

okArray Population;   /* dynamic array of okU4B */

okArray NewArray;     /* a new array */

okError e;

okEnv   Env;


...


   /* see okInit to initialize the environment here */

   e = okCreateArray(Env, &City, 

      strlen(CityName)+1, (okByte *)CityName);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   e = okCreateArray(Env, &Population, 

      sizeof(okU4B), (okByte *)&CityPopulation); 

   if (OK_IS_ERROR(e)) { /* error handling */ }

      

   e = okGetArraySize(Env, &City, &ArraySize);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   if (ArraySize != sizeof("San Jose")) { /* error handling */ }


   e = okSetArraySize(Env, &Population, 2*sizeof(okU4B));

   if (OK_IS_ERROR(e)) { /* error handling */ }


   CityPopulation = 350000;

   e = okAppendArray(Env, &Population,  

      sizeof(okU4B), (okByte *)CityPopulation);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   

   e = okCopyArray(Env, &NewArray, Env, &City);

   if (OK_IS_ERROR(e)) { /* error handling */ }

   

   e = okDeleteArray(Env, &City);

   if (OK_IS_ERROR(e)) { /* error handling */ }


...