Guide Store Object Relationships (Visual Basic)

Many objects in the Guide Store repository have an implicit relationship with one another. For example, programs are related to schedule entries. Every schedule entry is associated with a program, and a program may be associated with one or more schedule entries.

Relationships are defined by metaproperties. In the case of schedule entries and programs, the relationship is defined by the standard MetaPropertyType object named "Program" in the standard MetaPropertySet object named "ScheduleEntry". In the shorthand used throughout the Guide Store, this MetaPropertyType object is called "ScheduleEntry.Program", and it can be obtained from the MetaPropertySets.Lookup property.

There are two kinds of relationships: direct and inverse. The kind of relationship is determined by the way the data is added to the repository. If object B is added to the collection of objects that are directly related to object A, then object A is inversely related to object B. Nothing in the metaproperty itself defines the direction of the relationship.

In the case of programs and schedule entries, the Program object is directly related to the ScheduleEntry object, and the ScheduleEntry object is inversely related to the Program object.

The following function retrieves a collection of Program objects related to the ScheduleEntry object represented by MyEntry. The retrieved collection normally contains a single item, because only one program can be scheduled at a time.

' Assume that g_gs is a GuideStore object 
' and that the database has been opened.
 
Public Function ProgramsFromEntry(myEntry As ScheduleEntry) As Programs

  ' Get the MetaPropertyType for the relationship.
  
  Dim mpType As MetaPropertyType
  Set mpType = g_gs.MetaPropertySets.Lookup("ScheduleEntry.Program")
  
  ' Get the collection of all programs.
  
  Dim allPrograms As Programs
  Set allPrograms = g_gs.Programs
  
  ' Get the Objects interface.
  
  Dim allProgramsObj As Objects
  Set allProgramsObj = allPrograms '
  
  ' Find programs related to a schedule entry.
  
  Set ProgramsFromEntry = allProgramsObj.ItemsRelatedToBy(myEntry, mpType)
  
End Function

Similarly, the following function retrieves a collection of ScheduleEntry objects inversely related to the given Program object.

Public Function EntriesFromProgram(myProgram As Program) _
    As ScheduleEntries

  ' Get the MetaPropertyType for the relationship.
  
  Dim mpType As MetaPropertyType
  Set mpType = g_gs.MetaPropertySets.Lookup("ScheduleEntry.Program")
  
  ' Get the collection of all schedule entries.
  
  Dim allEntries As ScheduleEntries
  Set allEntries = g_gs.ScheduleEntries
  
  ' Get the Objects interface.
  
  Dim allEntriesObj As Objects
  Set allEntriesObj = allEntries
  
  ' Find schedule entries inversely related to a program.
  
  Set EntriesFromProgram = _
      allEntriesObj.ItemsInverseRelatedToBy(myProgram, mpType)
  
End Function

These examples are solely for the purpose of illustration and are not very useful. For standard relationships, you can retrieve related objects more easily by using properties such as ScheduleEntry.Program. Relationships are of more interest for custom objects. For example, you might create a generic object representing an artist, and define relationships between artists and programs by metaproperties such as "Role.Actor" and "Role.Director". Given an artist object that has been added to the database, you could establish a direct relationship between the artist and a Program object as follows:

1. Create a MetaPropertyType object that defines the relationship, and add this to the database. For example, this could be "Role.Actor". You can create this object, or obtain it if it already exists, by using MetaPropertySets.Lookup, as in the previous example.
2. Obtain a collection of all Program objects in the database by using GuideStore.Programs.
3. Assign the Programs collection to an Objects variable.
4. From the Objects collection obtained in the previous step, obtain a collection of all programs that have the specified relationship to the artist object, by passing the MetaPropertyType object and the artist object to Objects.ItemsRelatedToBy. This collection might be empty, but that doesn't matter.
5. Use Objects.AddAt to add the Program object to the collection of related objects. This establishes the relationship between the program and the actor, and also establishes an inverse relationship between the actor and the program.

   Note   You cannot establish an inverse relationship in any other way. Attempting to add an item to a collection returned by Objects.ItemsInverseRelatedToBy results in an error.