# Managing Juggler Objects

A group of Music library functions allows a task to manage Juggler objects. The library functions allow a task to initialize the Juggler, define new classes, create objects from those classes, destroy existing objects, and check an object's validity.

## Initializing the Juggler

Before a task can perform any object-oriented work in the Juggler environment, including object management and playing objects with the Juggler, the task must first initialize the Juggler with the following call:

  `int32 InitJuggler( void )`

This call accepts no arguments and, when it executes, initializes the Juggler and its object-oriented programming environment. It also defines the Juggler default classes so the task can create objects or define new classes based on the default classes.

If successful, `InitJugger()` returns 0. If unsuccessful, it returns an error code (a negative value).

Note that a task must call `InitJuggler()` before it can use any Juggler calls or play Juggler objects (including MIDI scores created as described in Playing MIDI Scores).

## Creating an Object

To create an object based on an existing class, a task uses this call:

  `COBObject *CreateObject( COBClass *Class )`

The call accepts a single argument: `*Class`, a pointer to the `COBClass` data structure containing the class definition. There are currently two classes defined in the header file juggler.h. The classes are `SequenceClass` and `CollectionClass`, which you can supply to this call as the pointers `&SequenceClass` and`&CollectionClass`.

When it executes, `CreateObject()` allocates memory for the object, sets up object variables and method pointers in that memory, and initializes the object variables to default values.

`CreateObject()` returns a pointer to the `COBObject` data structure defining the object if successful or a negative value (an error code) if unsuccessful. The task uses the pointer to the `COBObject` structure when sending messages to the object or when using other object management calls on the object.

## Destroying an Object

When a task is finished with an object, it deletes the object from memory using this call:

  `int32 DestroyObject( COBObject *Object )`

The call accepts one argument: `*Object`, a pointer to the object to be destroyed. When executed, the call terminates any methods the object may be executing and frees the memory used to contain the object's `COBObject` data structure.

`DestroyObject()` returns 0 if successful, or a negative value (an error code) if unsuccessful.

## Checking an Object's Validity

A task must pass a pointer to an object to an object-management call or a method. If the argument does not point to an object, the results of the call are unpredictable. A task can check a pointer's validity using this call:

  `int32 ValidateObject( COBObject *cob )`

The call accepts one argument: `*cob`, a pointer to an object's `COBObject` data structure. When the call executes, it looks in the object's data structure for an element that confirms the object's validity.

If the object is valid, `ValidateObject()` returns 0. Otherwise, the call returns a negative value (an error code).