Data Warehouse Center Application Integration Guide

INSTANCE

Defines or identifies objects or relationships to be acted on.

Context

This tag is required following:

:ACTION.OBJINST

The INSTANCE tag follows an OBJECT tag.

:ACTION.RELATION

The INSTANCE tag follows a RELTYPE tag.

Syntax

There are four formats for the INSTANCE tag, depending on the format of the ACTION tag:

ACTION.OBJINST(ADD) or ACTION.OBJINST(MERGE)

Adding or merging objects

:INSTANCE.short_name (property_value) . . .

Context

Figure 50. Using the INSTANCE tag when adding objects

:ACTION.OBJINST(ADD) :OBJECT.TYPE() :INSTANCE.short_name()

Figure 51. Using the INSTANCE tag when merging objects

:ACTION.OBJINST(MERGE) :OBJECT.TYPE() :INSTANCE.short_name() :short_name() :short_name()

Keywords

short_name

Identifies each property by its 8-character short name. This value is not case sensitive; you can specify this value by using uppercase or lowercase characters. If an INSTANCE tag has multiple short names associated with it, use only one INSTANCE tag followed the short names as shown in Figure 51.

property_value

Specifies the value of the property for the given object. This value is case sensitive.

Rules

• When adding an object:
  • You must specify all UUI values, a value for the NAME property, and values for any other properties that are defined as required.
  • You can omit a property that does not have a value to add from the INSTANCE tag. However, if an omitted property is a required property with a CHAR, VARCHAR, or LONG VARCHAR data type, a not-applicable symbol is generated and stored in the information catalog. If an omitted required property has a TIMESTAMP data type, then the Information Catalog Manager generates and stores the value 9999-12-31-24.00.00.000000.
• When merging an object:
  • You must specify all UUI values, to ensure that matching objects can be identified.
  • You can omit a property that does not have a value to be added or updated. However, if the defined object does not exist, and the omitted property is required, then a not-applicable symbol is generated and stored in the information catalog.

ACTION.OBJINST(DELETE) or ACTION.OBJINST(DELETE_TREE_ALL) or ACTION.OBJINST(DELETE_TREE_REL)

Deleting an object

:INSTANCE.SOURCEKEY(UUI_short_name (UUI_property_value) . . . )

Context

Figure 52. Using the INSTANCE tag when deleting objects

:ACTION.OBJINST(DELETE) :OBJECT.TYPE() :INSTANCE.SOURCEKEY(UUI_short_name()...)

Figure 53. Using the INSTANCE tag when deleting Grouping category objects and contained objects

:ACTION.OBJINST(DELETE_TREE_ALL) :OBJECT.TYPE() :INSTANCE.SOURCEKEY(UUI_short_name()...)

Figure 54. Using the INSTANCE tag when deleting Grouping category objects and relationships

:ACTION.OBJINST(DELETE_TREE_REL) :OBJECT.TYPE() :INSTANCE.SOURCEKEY(UUI_short_name()...)

Keywords

SOURCEKEY

Specifies the UUI property values that identify a particular object.

SOURCEKEY must be the first keyword of the INSTANCE tag.

UUI_short_name

Identifies a UUI property name by its 8-character short name. Specify all of the UUI_short_name(UUI_property_value) combinations. The UUI_short_name is not case sensitive; you can specify this value by using uppercase or lowercase characters.

UUI_property_value

Specifies the value of a UUI property for a particular object. This value is case sensitive.

Rules

You must specify one UUI_short_name(value) combination for each property that is defined as a UUI property for the object type. Each object type has one or more properties defined as UUI properties. These properties uniquely identify an object in the information catalog.

ACTION.OBJINST(UPDATE)

Updating property values for an object

:INSTANCE.SOURCEKEY(UUI_short_name (UUI_property_value) . . . ) short_name (property_value) . . .

Context

Figure 55. Using the INSTANCE tag when updating objects

:ACTION.OBJINST(UPDATE) :OBJECT.TYPE() :INSTANCE.SOURCEKEY(UUI_short_name()...) short_name()

Keywords

SOURCEKEY

Specifies the UUI property values that identify a particular object.

SOURCEKEY must be the first keyword of the INSTANCE tag.

UUI_short_name

Identifies a UUI property by its 8-character short name. The UUI_short_name is not case sensitive; you can specify this value by using uppercase or lowercase characters.

UUI_property_value

This value is case sensitive. With UUI_short_name, specifies the value of a UUI property for a particular object.

short_name

Identifies the property to be updated by its 8-character short name. The short_name is not case sensitive; you can specify this value by using uppercase or lowercase characters.

You cannot specify the following property short names because you cannot update these properties: OBJTYPID, INSTIDNT, UPDATIME, UPDATEBY.

property_value

With short_name, specifies the new value of the property for the given object. This value is case sensitive.

Rules

You must specify one UUI_short_name(value) combination for each property that is defined as a UUI property for the object type. Each object type has one or more properties defined as UUI properties. These properties uniquely identify an object in the information catalog.

If you specify a property value, that value is updated in the information catalog. If you do not specify a property value, the value is not updated.

ACTION.RELATION(ADD) or ACTION.RELATION(DELETE)

Adding or deleting relationships

:INSTANCE.SOURCEKEY(UUI_short_name (UUI_property_value)...) TARGETKEY(UUI_short_name (UUI_property_value)...)

Context

Figure 56. Using the INSTANCE tag when adding relationships

:ACTION.RELATION(ADD) :RELTYPE.TYPE() SOURCETYPE() TARGETYPE() :INSTANCE.SOURCEKEY(UUI_short_name()...) TARGETKEY(UUI_short_name()...)

Figure 57. Using the INSTANCE tag when deleting relationships

:ACTION.RELATION(DELETE) :RELTYPE.TYPE() SOURCETYPE() TARGETYPE() :INSTANCE.SOURCEKEY(UUI_short_name()...) TARGETKEY(UUI_short_name()...)

Keywords

SOURCEKEY

Specifies the UUI property values that identify the first object in a relationship.

When the relationship is:

The SOURCEKEY identifies:

Contains

The Grouping category object

Contact

The object the contact is for

Attachment

The object the comment is for

Link

Either object to link

SOURCEKEY must be the first keyword of the INSTANCE tag.

TARGETKEY

Specifies the UUI property values that identify the second object in a relationship.

When the relationship is:

The TARGETKEY identifies:

Contains

The Elemental category object

Contact

The Contact category object

Attachment

The Attachment category object

Link

Either object to link

TARGETKEY must be the second keyword of the INSTANCE tag.

UUI_short_name

Identifies a UUI property name by its 8-character short name. This value is not case sensitive; you can specify this value by using uppercase or lowercase characters.

UUI_property_value

Specifies the value of a UUI property for a particular object. This value is case sensitive.

Rules

For each object, you must specify one UUI_short_name(value) combination for each property that is defined as a UUI property for the object type. Each object type has one or more properties defined as UUI properties. These properties uniquely identify an object in the information catalog.

You must separate each UUI_short_name(value) and short_name(value) pair with a blank, as shown in Figure 58.

Figure 58. Example of an INSTANCE tag with several short names

:INSTANCE.SOURCEKEY(UUIname1(value1) UUIname2(value2)) sname3(value3) sname4(value4)

Leading blanks that are included between the parentheses for a value become part of the value; trailing blanks are removed. The Information Catalog Manager counts these blanks as part of the data length when determining whether the length of the value is valid. An error occurs if you include extra leading blanks or trailing blanks on a value that make the entire value longer than the maximum allowed length.