Using Metadata

The following examples provide a guide into how you can implement metadata within your project. In the first example you will set parameters using metadata, and in the second example see how genie substitutions can be used in metadata. The third example shows you how to use Metadata to define a subset of current objects on your graphics page and to use Cicode to call, retrieve and set metadata values from an outside source such as a database.

In the examples a paint factory needs to control the amount of Cyan, Magenta, Yellow, and Key (Black) (CMYK), which is mixed to create different colors in their color chart.

Example 1: Setting Parameters Using Metadata

1. From the toolbox select the ‘number’ tool and in the Text Properties dialog configure as below. This is the pump that represents the color Cyan.

2. 

2. Repeat to create the remaining pumps M_ PUMP, Y_ PUMP, K_ PUMP

3. Note:Add these pumps to the example project as Local Variable tags

3. Create a button object. This button when selected at runtime will set the CMYK values for a specific color e.g Pine Green

4. 

   Note: For Display functions DspAnGetMetadataAt, DspAnSetMetadata, DspAnGetMetadata, and DspAnSetMetadataAt -2 is the default value used to retrieve the unique animation number for the button object.

4. At runtime when the ‘Pine green’ button is selected the values of the metadata defined for Cyan, Magenta, Yellow and Black are retrieved and the relevant pumps set.

Example 2: Using Genie Substitutions in Metadata

Instead of creating a new button for every color as you did in the previous example, you can create a genie and save it in the genie library. You can use the genie every time you need to create a new color button.Only needing to configure the name of the button and the CMYK values that belong to it.

1. From File New-> Genie
2. Add a button object onto the page
3. Configure the button – the title of the button and the Value of the Metadata have been defined using genie substitutions e.g %Color% and %Cyan%.

4. 

4. Save the genie in the appropriate genie library
5. At design time paste the genie onto the graphics page. A dialog will open prompting you for the name of the button, and the numeric values for Cyan, Magenta, Yellow and Black. In this example the name of the color is “Purple Heart”

6. 

6. At runtime when the ‘Purple Heart’ color button is selected the values of the metadata (that were entered in the genie prompt) are retrieved and the relevant pumps set.

Example 3: Defining a subset of Animation points using Metadata

A graphics page could have over four hundred Animation points. Each Animation point belongs to an object, which raises the question how can you define a subset of these objects and perform an operation only on that subset. In this example, metadata is used to define a subset of animation points, and then Cicode is used to operate on this subset collectively using values stored in an outside source.

Note:For the following example it is assumed you are already using an ODBC data source.

This example:

• Defines a subset
• Two cicode functions (created for this example only) – LoadColors(), and LoadColorsForButton()
• Cicode to loop through a database table and match, and retrieve values belonging to the subset defined as “ColorName”.

1. Create four new buttons for the colors – Charcoal, Lime, Olive and Puce.

2. 

2. In the graphics editor create a new button. This button will be used to call the values from the data source using the function LoadColors()
3. At runtime when the LoadColors() button is selected Cicode is triggered that will search for metadata entries named “ColorName” on the current page. In this example the “ColorName” is Olive. From the data source it then loads relevant the CMYK values.
4. When the Olive color button is then selected the values are displayed and the pumps set.

Cicode used in this example:

// This function finds animation objects on the current page with
// a metadata entry named "sColorName". This demonstrates how metadata
// values can be used to dynamically identify objects.
FUNCTION LoadColors()
INT nAn;
STRING sColorName;

// Disable hardware errors for this Cicode task. If you don't do
// this then DspAnGetMetadata will generate a hardware error for
// any object that does not have a metadata entry "sColorName".
ErrSet(1);

nAn = DspGetAnFirst();
WHILE nAn <> -1 DO
// Determine whether the current animation object has a
// metadata entry named "ColorName". If DspAnGetMetadata
// cannot find the named entry, it returns an empty string.
sColorName = DspAnGetMetadata(nAn, "ColorName");
IF sColorName <> "" THEN
LoadColorsForButton(nAn, sColorName);
END
nAn = DspGetAnNext(nAn);
END
END
// This function loads the CMYK metadata values for the specified
// button (nAn) from a database. This demonstrates how metadata values
// can be modified at runtime.
FUNCTION LoadColorsForButton(INT nAn, STRING sColorName)
INT hSQL;
INT nStatus;
STRING sCyan;
STRING sMagenta;
STRING sYellow;
STRING sBlack;

// Load the CMYK values from the database.
hSql = SQLConnect("DSN=Colors");
IF hSQL <> -1 THEN
nStatus = SQLExec(hSQL, "SELECT * FROM Colors WHERE ColorName = '" + sColorName + "';");
IF nStatus = 0 THEN
IF SQLNext(hSQL) = 0 THEN
sCyan = SQLGetField(hSQL, "Cyan");
sMagenta = SQLGetField(hSQL, "Magenta");
sYellow = SQLGetField(hSQL, "Yellow");
sBlack = SQLGetField(hSQL, "Black");
END
SQLEnd(hSQL);
ELSE
Message("Exec Error", SQLErrMsg(), 48);
RETURN;
END
SQLDisconnect(hSQL);
ELSE
Message("Connect Error", SQLErrMsg(), 48);
RETURN;
END

// Update the metadata values of the specified object.
DspAnSetMetadata(nAn, "Cyan", sCyan);
DspAnSetMetadata(nAn, "Magenta", sMagenta);
DspAnSetMetadata(nAn, "Yellow", sYellow);
DspAnSetMetadata(nAn, "Black", sBlack);
END

See Also