Object Bind Editor

The Object Bind Editor is the place that Object Bindings are created. In order for the Object Bind Editor to be invoked, a valid Activator must be first selected (Using the Activator Selector). When a Data Object is opened, all of its Arguments and Results are displayed. The developer can then bind the Arguments to HTML Form Input Elements and the Results to Data Sites contained in a Template.

States of the Object Bind Editor.

Figure 2-24 Object Bind Editor

About the Object Bind Editor

Area Description

`Menu Bar` Pulldown menu options.

`Data Object` Invokes the Object Selector. The Object Selector allows Data Objects to be selected and loaded into the Object Bind Editor.

`Object ID` This textField is the identifier for a Data Object. For PROC and DSQL Data Objects, the format is: `server|databa[owner.]se|object_name` For FILE, EXEC and FUNC Data Objects, the format is: `object_name` For NULL Data Objects, the Object ID is blank.

`Bind Name` Displays the Bind Name for the current Object Binding and lets developers load an existing Object Binding from the drop-down list. All of the Object Bindings associated with the current Activator are contained in the drop-down-list of the `Bind Name` combo. Every Object Binding must have a name that is unique to the project. A unique Bind Name is generated every time you create a new Object Binding. This Bind Name can be changed by the developer by changing the value of the `Bind Name` combo. If the specified name is not unique, an error will occur. Bind names can contain alpha-numeric characters and the underscore `(_)`.

`Preview Activator` When this button is pressed, the developer's preferred HTML Browser will be invoked with this Object Binding's Activator loaded into it.

`Activator ID` Identifies the Activator that is associated with the current Object Binding. For a definition, see the Activator ID Strings subsection in the Activator Selector section.

`Arguments List` This scrolled area contains a list of all the Arguments associated with the current Data Object. If a Data Object has no Arguments, this area is blank. Each Argument is represented by a name and textField.

`Preview Template` When this button is pressed, the developer's preferred HTML Browser will be invoked with this Object Binding's Template loaded into it.

`Template` This combo contains a list of all the HTML Documents in the current Project. When a Template is selected from the list of HTML Documents, it will be used as the output HTML when the Activator is activated by the end user. Templates can contain Data Sites to which bind Result Columns are bound.

`Results List` This is list of all the Result Columns that will be generated when the current Data Object is executed with the specified Arguments. Each Result Column is represented by a name, `Group`, value and `Results Detail` button.

`Options` Invokes the Options Editor with Options for Data Objects. These Options override those specified in the Object Editor for the Data Object. PROC, DSQL and NULL Data Objects do not have Options.

`Type` Contains the Data Object Type of the current Data Object.

`Vendor` This contains the Database Vendor ID for PROC and DSQL Data Objects. `SYB` = Sybase `ORA` = Oracle `INF` = Informix

`Activator Code` This button will invoke the Activator Code interface for the current Activator. The current Object Binding must have been saved once before this button will work.

`Argument Value` This element is normally a textField that contains the C expression to bind the Argument to. When the textField is clicked on to modify it, the textField becomes a combo containing a list of Form Elements in the Activator or Argument Extraction Functions for Anchors. See the subsection on Arguments.

`Max Rows` Value used to limit the number of rows returned by a PROC or DSQL Data Object. A value less than 1 means return all rows.

`Result Column Value` This element is normally a textField that contains the Data Site to bind the Result Column to. When the textField is clicked on to modify it, the textField becomes a combo containing a list of Data Sites contained in the Template. See the subsection on Results.

`Results Detail` This invokes the Results Detail Editor. The Results Detail Editor allows detailed information about the binding of a Result Column to a Data Site. See the Results Detail dialog subsection.

`Group` A group is the product of a SELECT statement in SQL (rows and columns). Only PROC and DSQL Data Objects for Sybase and FUNC Data Objects can have multiple groups. This label represents the group the Result Column is associated with. Groups start at 1.

Area	Description
`Menu Bar`	Pulldown menu options.
`Data Object`	Invokes the Object Selector. The Object Selector allows Data Objects to be selected and loaded into the Object Bind Editor.
`Object ID`	This textField is the identifier for a Data Object. For PROC and DSQL Data Objects, the format is: `server\|databa[owner.]se\|object_name` For FILE, EXEC and FUNC Data Objects, the format is: `object_name` For NULL Data Objects, the Object ID is blank.
`Bind Name`	Displays the Bind Name for the current Object Binding and lets developers load an existing Object Binding from the drop-down list. All of the Object Bindings associated with the current Activator are contained in the drop-down-list of the `Bind Name` combo. Every Object Binding must have a name that is unique to the project. A unique Bind Name is generated every time you create a new Object Binding. This Bind Name can be changed by the developer by changing the value of the `Bind Name` combo. If the specified name is not unique, an error will occur. Bind names can contain alpha-numeric characters and the underscore `(_)`.
`Preview Activator`	When this button is pressed, the developer's preferred HTML Browser will be invoked with this Object Binding's Activator loaded into it.
`Activator ID`	Identifies the Activator that is associated with the current Object Binding. For a definition, see the Activator ID Strings subsection in the Activator Selector section.
`Arguments List`	This scrolled area contains a list of all the Arguments associated with the current Data Object. If a Data Object has no Arguments, this area is blank. Each Argument is represented by a name and textField.
`Preview Template`	When this button is pressed, the developer's preferred HTML Browser will be invoked with this Object Binding's Template loaded into it.
`Template`	This combo contains a list of all the HTML Documents in the current Project. When a Template is selected from the list of HTML Documents, it will be used as the output HTML when the Activator is activated by the end user. Templates can contain Data Sites to which bind Result Columns are bound.
`Results List`	This is list of all the Result Columns that will be generated when the current Data Object is executed with the specified Arguments. Each Result Column is represented by a name, `Group`, value and `Results Detail` button.
`Options`	Invokes the Options Editor with Options for Data Objects. These Options override those specified in the Object Editor for the Data Object. PROC, DSQL and NULL Data Objects do not have Options.
`Type`	Contains the Data Object Type of the current Data Object.
`Vendor`	This contains the Database Vendor ID for PROC and DSQL Data Objects. `SYB` = Sybase `ORA` = Oracle `INF` = Informix
`Activator Code`	This button will invoke the Activator Code interface for the current Activator. The current Object Binding must have been saved once before this button will work.
`Argument Value`	This element is normally a textField that contains the C expression to bind the Argument to. When the textField is clicked on to modify it, the textField becomes a combo containing a list of Form Elements in the Activator or Argument Extraction Functions for Anchors. See the subsection on Arguments.
`Max Rows`	Value used to limit the number of rows returned by a PROC or DSQL Data Object. A value less than 1 means return all rows.
`Result Column Value`	This element is normally a textField that contains the Data Site to bind the Result Column to. When the textField is clicked on to modify it, the textField becomes a combo containing a list of Data Sites contained in the Template. See the subsection on Results.
`Results Detail`	This invokes the Results Detail Editor. The Results Detail Editor allows detailed information about the binding of a Result Column to a Data Site. See the Results Detail dialog subsection.
`Group`	A group is the product of a SELECT statement in SQL (rows and columns). Only PROC and DSQL Data Objects for Sybase and FUNC Data Objects can have multiple groups. This label represents the group the Result Column is associated with. Groups start at 1.

Pulldown Menus

File

Option Description

`New Editor` Invokes the Activator Selector which enables the developer to choose an Activator. When `Ok` is pressed on the Activator Selector, a new instance of the Object Bind Editor is invoked with the newly chosen Activator loaded.

`Load Activator` Invokes the Activator Selector which enables the developer to choose an Activator. When `Ok` is pressed on the Activator Selector, the chosen Activator is loaded into the current Object Bind Editor instance.

`Open Data Object` Performs the same operation as pressing `Data Object`. See About the Object Bind Editor.

`Load Bind Name` This option attempts to load the Object Binding that is entered in the Bind Name textField. This can also be accomplished by pressing <Return> while the focus is in the Bind Name textField, or selecting the Object Binding from the Bind Name combo's drop-down-list.

`Save` This Saves the current Object Binding and leaves the Object Bind Editor popped up.

`Close` Closes the Object Bind Editor.

Option	Description
`New Editor`	Invokes the Activator Selector which enables the developer to choose an Activator. When `Ok` is pressed on the Activator Selector, a new instance of the Object Bind Editor is invoked with the newly chosen Activator loaded.
`Load Activator`	Invokes the Activator Selector which enables the developer to choose an Activator. When `Ok` is pressed on the Activator Selector, the chosen Activator is loaded into the current Object Bind Editor instance.
`Open Data Object`	Performs the same operation as pressing `Data Object`. See About the Object Bind Editor.
`Load Bind Name`	This option attempts to load the Object Binding that is entered in the Bind Name textField. This can also be accomplished by pressing <Return> while the focus is in the Bind Name textField, or selecting the Object Binding from the Bind Name combo's drop-down-list.
`Save`	This Saves the current Object Binding and leaves the Object Bind Editor popped up.
`Close`	Closes the Object Bind Editor.

Edit

Option Description

`Activator Code` Invokes the Activator Code interface for the current Activator. The current Object Binding must have been saved once before this button will work.

`Add Alias` Invokes the Alias Manager, which enables the developer to specify Aliases.

`Data Object Options` Invokes the Options Editor with Options for Data Objects. These Options override those specified in the Object Editor for the Data Object. PROC, DSQL and NULL Data Objects do not have Options.

`Copy Object Binding` Copies the Object Binding and automatically invoke the Activator Selector. Once an Activator is selected to copy the Object Binding to, a new instance of the Object Bind Editor is invoked with the new Object Binding loaded. A new and unique Bind Name gets generated.

`Refresh Object Binding` Refreshes the current Data Object throughout the entire project. If a Data Object changes while Sapphire/Web is up, it is recommended to update the Object Bindings to reflect the new changes. This is performed automatically when Objects are changed in the Object Editor (if the developer chooses `Ok` when prompted), but if the change occurs outside Sapphire/Web, the application has no way of knowing about the change. There is also a Refresh All Objects option on the Project Window's Edit menu that will refresh all Data Objects in the Project.

`Delete Object Binding` Deletes the current Object Binding from the Object Editor and unload it from the Object Bind Editor.

Option	Description
`Activator Code`	Invokes the Activator Code interface for the current Activator. The current Object Binding must have been saved once before this button will work.
`Add Alias`	Invokes the Alias Manager, which enables the developer to specify Aliases.
`Data Object Options`	Invokes the Options Editor with Options for Data Objects. These Options override those specified in the Object Editor for the Data Object. PROC, DSQL and NULL Data Objects do not have Options.
`Copy Object Binding`	Copies the Object Binding and automatically invoke the Activator Selector. Once an Activator is selected to copy the Object Binding to, a new instance of the Object Bind Editor is invoked with the new Object Binding loaded. A new and unique Bind Name gets generated.
`Refresh Object Binding`	Refreshes the current Data Object throughout the entire project. If a Data Object changes while Sapphire/Web is up, it is recommended to update the Object Bindings to reflect the new changes. This is performed automatically when Objects are changed in the Object Editor (if the developer chooses `Ok` when prompted), but if the change occurs outside Sapphire/Web, the application has no way of knowing about the change. There is also a Refresh All Objects option on the Project Window's Edit menu that will refresh all Data Objects in the Project.
`Delete Object Binding`	Deletes the current Object Binding from the Object Editor and unload it from the Object Bind Editor.

Tools

Option Description

`Document Manager` Invokes the Document Manager.

`Object Editor` Invokes an instance of the Object Editor with the current Data Object from the Object Bind Editor loaded in it.

`Database Browser` Invokes an instance of the Database Browser.

Option	Description
`Document Manager`	Invokes the Document Manager.
`Object Editor`	Invokes an instance of the Object Editor with the current Data Object from the Object Bind Editor loaded in it.
`Database Browser`	Invokes an instance of the Database Browser.

Help

Option Description

`About` Displays the About Sapphire/Web Dialog.

`Interfaces` Provides on-line help for the Object Bind Editor interface.

Option	Description
`About`	Displays the About Sapphire/Web Dialog.
`Interfaces`	Provides on-line help for the Object Bind Editor interface.

How to Invoke the Interface

: 1. The Tools Menu of the Project Window
: 2. The Project Window's Selected Activators Pop-up
: 3. The Project Window's Main Button Bar
: 4. Double-clicking the Project Window's Activators Area list.
: 5. The project Window's Selected Activator's Button Bar
: 6. The Activator Code interface's Bind button

Arguments

Arguments are input to a Data Object. Some Data Objects have Arguments and some don't.

Valid Values for Arguments

Any valid C expression that returns a character pointer (char *) is a valid Argument value.

Example:

: 1. Hard-coded string:

	"Scott"

: 2. Constant:

	#define ARGVAL "Scott"

: 3. An initialized variable:

	char *argval = strdup("Scott");

: 4. A function that returns a character pointer:

	char *SaGetInputValue(char *name);

Functions should never return malloc'd data because it can never be free'd.

Form Arguments

When a Form Activator with form input elements is bound to a Data Object that has Arguments, the names of the input elements are displayed in the Argument Value combo. When an element name is selected from the combo, it is wrapped as follows:

SaGetInputValue("element_name")

The function call SaGetInputValue will return the values to which the end user sets the element_name element. This data does not have to be free'd. If the Sapphire/Web developer wishes to use a function, it should not malloc data because it can never be free'd.

Anchor Arguments

When an Anchor Activator is bound to a Data Object that has Arguments, there are no names to bind to. Therefore, it is necessary to retrieve Anchor Arguments by number. In the Argument Value combo, there is a function for this purpose:

SaGetNArg(0)

SaGetNArg will by default, get the first Anchor Argument's value. To retrieve the remaining values, change 0 to the number of the Argument for which you wish to retrieve a value.

Results

Results are returned from the execution of a Data Object. Not all Data Objects have results. Valid values for Result Column Values are Data Sites contained within the selected Template. When selected, the Data Site's name is copied to the Result Column Value textField.

Multiple Result Columns can be bound to the same Data Site. This will cause the returned data to be populated into that single Data Site. The behavior of the population of Data Sites depends upon the Population Callback specified. The default Population Callback is SaPopulateForText.

Usage Example

To display results from an EXEC object to an HTML results template, complete the object you are creating in the Object Results Editor by defining the results in the bottom portion of the dialog box. You can call your results anything you want. Next, bind to the results template. You should use the standard Sapphire naming convention (##Sa_VarName##) for the datasite in your results template. For example, if you're binding to a UNIX shell script, the standard output of the script will display to the datasite in your results template.

Results Detail Dialog

The Results Detail Dialog enables the developer to specify detail information about the binding of a Results Column to a Data Site. The detailed information includes the Population Callback, Client Data, result column order and Population Callback Options.

Figure 2-25 Results Detail Dialog

Option Description

Callback This is the Population Callback combo. The names of Population Callbacks are typed here. Population Callbacks can also be selected from the combo's drop-down-list.

Client Data Client Data that is to be passed to the Population Callback is specified here.

Order If more than one Result Column is bound to the same Data Site, this is used to specify the order in which the Result Columns will be populated. If they are all set to zero (0), then they will be populated in the order they appear in the Object Bind Editor.

Options Invokes the Options Editor for Population Callback options. If a Population Callback has been written to accept Options, they can be specified in the Options Editor. See the Population Callback Options subsection.

Help When this button is pressed, Help will be displayed that describes the selected Population Callback. The help is displayed in the developer's favorite HTML browser.

Option	Description
`Callback`	This is the Population Callback combo. The names of Population Callbacks are typed here. Population Callbacks can also be selected from the combo's drop-down-list.
`Client Data`	Client Data that is to be passed to the Population Callback is specified here.
`Order`	If more than one Result Column is bound to the same Data Site, this is used to specify the order in which the Result Columns will be populated. If they are all set to zero (0), then they will be populated in the order they appear in the Object Bind Editor.
`Options`	Invokes the Options Editor for Population Callback options. If a Population Callback has been written to accept Options, they can be specified in the Options Editor. See the Population Callback Options subsection.
`Help`	When this button is pressed, Help will be displayed that describes the selected Population Callback. The help is displayed in the developer's favorite HTML browser.

Population Callback Options

When a Population Callback is written to handle Options, they are specified within an Options Editor. The following describes the version of the Options Editor used for this purpose. See the Options Editor section for more information.

Figure 2-26 Population Options Dialog

Option Description

`Add` Prompts the developer for the name of the Option to Add to the Options Editor. Once entered, the Option name is added to the list of Options and the developer can enter a value for the new Option.

`Delete` Removes the selected Option from the Options Editor.

Option	Description
`Add`	Prompts the developer for the name of the Option to Add to the Options Editor. Once entered, the Option name is added to the list of Options and the developer can enter a value for the new Option.
`Delete`	Removes the selected Option from the Options Editor.

[Top] [Prev] [Next] [Bottom] [Contents]

info@bluestone.com

Object Bind Editor

Figure 2-24 Object Bind Editor

Pulldown Menus

Tools Option Description Document Manager Invokes the Document Manager. Object Editor Invokes an instance of the Object Editor with the current Data Object from the Object Bind Editor loaded in it. Database Browser Invokes an instance of the Database Browser.

Help Option Description About Displays the About Sapphire/Web Dialog. Interfaces Provides on-line help for the Object Bind Editor interface.

How to Invoke the Interface

Arguments

Figure 2-25 Results Detail Dialog

Tools

Option Description

`Document Manager` Invokes the Document Manager.

`Object Editor` Invokes an instance of the Object Editor with the current Data Object from the Object Bind Editor loaded in it.

`Database Browser` Invokes an instance of the Database Browser.

Help

Option Description

`About` Displays the About Sapphire/Web Dialog.

`Interfaces` Provides on-line help for the Object Bind Editor interface.