Host Procedures for Oracle
PL/SQL
Version 2.1
Introduction
This document lists each of
the procedures that can be used by an Oracle stored procedure to send various
commands to a client application (app). There are commands available for
a wide variety of purposes, including:
-
assigning or changing the displayed
value in a component such as a textfield, textarea or grid cell
-
selecting ("checking") or unselecting
a radio button or checkbox
-
making a container or component
visible or hidden
-
making a component enabled or
disabled for receiving user input and focus
-
assigning or changing a component's
tooltip (floating help message)
-
assigning or changing an object's
title, caption or image
-
adding or selecting a specific
value in a combobox or listbox
-
adding or changing the value
of a grid row or individual cell
-
bringing a specific panel to
the "top" in a cardpanel or tabpanel
In addition, two powerful utility
procedures
allow a host procedure to make use of all methods and tasklists available
in a client app:
-
invoke any method on any object
in the client app
-
invoke any existing tasklist
in a client app
Finally, several procedures
are available to start, commit, or rollback a transaction (coming soon).
These procedures are used
like any other stored procedure. For example, to display the value of the
database field "customer.name" in a client textfield whose object name
is "tName":
TEXTFIELD.SetText('tName', customer.name);
Another example disables a button
whose object name is "bDelete" so that it cannot be clicked or receive
focus:
COMPONENT.SetEnabled('bDelete',
FALSE);
Most include files have at least
one required argument, the "object name" which names
a container or component object to which the procedure will be applied.
These names are
case-sensitive, meaning that upper and lower case
must exactly match the name used in Jargon Writer for this object. This
means that 'TName' and 'tName' cannot be used interchangeably to
reference the same client object. This rule is different than the syntax
used in the PL/SQL language itself, and can be the cause of numerous errors
if not carefully followed.
Utility
Procedures
JSI.Invoke(objectName VARCHAR2, method
VARCHAR2, typelist VARCHAR2, vallist VARCHAR2, delimiter VARCHAR2)
This procedure is used to
invoke any valid client method on any object within the currently executing
app. The methods that can be invoked are the same ones used when adding
tasks in the Jargon Writer Task
Editor Window. This powerful procedure allows a host procedure full
access to any client method for which a specific procedure has not already
been defined in the Jargon schema. However, the syntax of these commands
requires more knowledge of the required parameters of a method, which can
be seen in the API help documents.
-
objectName - The internal
name used in the client app for the object on which a method will be invoked.
-
method - The name of
the method to be invoked on the object.
-
typelist - A delimiter-separated
list of data types for required parameters of the method. Data types are
specified as: boolean, int or String. (These are client data types, not
PL/SQL data types. Use upper/lower case as shown).
-
vallist - A delimiter-separated
list of values for each parameter. Note that values cannot contain the
delimiter character.
-
delimiter - The delimiter
used to separate entries in the typelist and vallist parameters. The default
is a comma.
JSI.InvokeTasklist(appName VARCHAR2,
tasklistName VARCHAR2)
This procedure is used to
instruct the client to execute an existing tasklist in a specific app.
The tasklist can contain any valid list of tasks, and is executed just
as if it were linked to a client event which had just taken place.
-
appName - The name of
the client app (without the ".xml" suffix) in which a tasklist is to be
invoked.
-
tasklistName - The
internal name of the tasklist to be invoked in the app.
Container
Procedures
These procedures are used with
various container objects (frames, panels, cardpanels, tabpanels). There
are both generic container procedures which can be used with any container
type, and other procedures that are specific to a particular container
type.
Generic
Container
These procedures can be
used on any container object (frame, panel, cardpanel, tabpanel).
CONTAINER.DisplayDefaultValues(name
IN VARCHAR2)
This procedure is used to
reset the contents of all components of the specified container by displaying
the default (initial) value of each component.
-
name - The internal name
used in the client app for this object.
CONTAINER.SetEnabled(name IN VARCHAR2,
bValue IN BOOLEAN DEFAULT TRUE)
This procedure is used to
enable or disable all components of the specified container. This procedure
must be used on the smallest containing object (like a panel or a tab of
a tabpanel). You cannot use it on an entire tabpanel or cardpanel container
object. (Well, strictly speaking, you could, but it wouldn't do
what you wanted).
-
name - The internal name
used in the client app for this object.
-
bValue - A boolean value:
TRUE to enable, FALSE to disable.
Frame
FRAME.Pack(name IN VARCHAR2)
This procedure is used to
dynamically size a frame as large as necessary to "pack" around its components.
This is the normal procedure used to size a frame and is done after adding
it.
-
name - The
internal name used in the client app for this object.
FRAME.SetMessage(name IN VARCHAR2,
msg IN VARCHAR2)
This procedure is used to
display a message in the system message area at the bottom of the frame.
-
name - The
internal name used in the client app for this object.
-
msg - A character string
to be displayed as a message. Example: 'Process completed' .
FRAME.SetTitle(name IN VARCHAR2,
title IN VARCHAR2)
This procedure is used to
assign a frame's title (displayed in the top border of the frame).
-
name - The
internal name used in the client app for this object.
-
title - A character string
to be displayed as the frame title. Example: " 'My Title' ".
FRAME.SetVisible(name IN VARCHAR2,
bValue IN BOOLEAN DEFAULT TRUE)
This procedure is used to
make a frame visible or invisible (hidden).
-
name - The
internal name used in the client app for this object.
-
bValue - A BOOLEAN value:
TRUE to make visible, FALSE to hide.
Card
panel
CARDPANEL.Show(name IN VARCHAR2, card
IN VARCHAR2)
This procedure is used to
change the panel within the card panel that is currently displayed.
-
name - The internal name
used in the client app for the cardpanel.
-
card - The
internal name of the panel within this cardpanel that should be displayed
("on top").
Tab
panel
TABPANEL.SetTab(name IN VARCHAR2,
tab IN VARCHAR2)
This procedure is used to
change the panel that is currently displayed within the tabpanel.
-
name - The internal name
used in the client app for the tabpanel.
-
tab - The
internal name of a panel within the tabpanel that is to be displayed ("on
top").
Component
Procedures
These procedures are used with
various component objects (objects which are not containers). There are
both generic component procedures which can be used with any component
type, and other procedures that are specific to a particular component
type.
Generic
Component
These procedures can be
used on any component object.
COMPONENT.SetEnabled(name IN VARCHAR2,
bValue IN BOOLEAN DEFAULT TRUE)
This procedure is used to
enable or disable a component.
-
name - The internal name
used in the client app for this object.
-
bValue - A
boolean (logical) value: TRUE to enable, FALSE to disable.
COMPONENT.SetTooltipText(name IN
VARCHAR2, value IN VARCHAR2)
This procedure is used to
assign a
tooltip help
message to a component.
-
name - The internal name
used in the client app for this object.
-
value - A
character string containing a one-line help message used as the tooltip
for this component.
COMPONENT.SetVisible(name IN VARCHAR2,
bValue IN BOOLEAN DEFAULT TRUE)
This procedure is used to
make a component visible or invisible (hidden).
-
name - The internal name
used in the client app for this object.
-
bValue - A
boolean (logical) value: TRUE to make visible, FALSE to hide.
Button
BUTTON.SetText (name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
change the caption on a button.
-
name - The internal name
used in the client app for this object.
-
value - A
character string to be displayed as the caption (label) of this object.
Checkbox
CHECKBOX.SetSelectedValue(name IN
VARCHAR2, bValue IN BOOLEAN DEFAULT TRUE)
This procedure is used to
select (check) or unselect (clear) a checkbox.
-
name - The internal name
used in the client app for this object.
-
bValue - A
boolean value for the selected state of the checkbox: TRUE for selected,
FALSE for not selected.
CHECKBOX. SetText (name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
change the caption on a checkbox.
-
name - The internal name
used in the client app for this object.
-
value - A
character string to be displayed as the caption (label) of this object.
Combo
box
COMBOBOX.AddItem(name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
add one or more values to the combobox choices. Values are always added
at the bottom of the list of choices.
-
name - The internal name
used in the client app for this object.
-
value - A
comma-separated list of one or more character strings to be displayed as
choices in the list. A choice cannot contain commas.
COMBOBOX.RemoveAllItems(name IN
VARCHAR2)
This procedure is used to
remove all choices from (clear) a combobox.
-
name - The internal name
used in the client app for this object.
COMBOBOX.SetDefaultSelection(name
IN VARCHAR2, value IN VARCHAR2)
This procedure is used to
set the default selection choice for a combobox. This choice will be displayed
when the combobox is first created and whenever a "set defaults" procedure
is invoked on it or its container.
-
name - The internal name
used in the client app for this object.
-
value - A
character string that must exactly match one of the current choices in
the combo box (case-sensitive).
COMBOBOX.SetSelectedIndex name IN
VARCHAR2, nValue IN NUMBER)
This procedure is used to
set the currently selected item to the n'th item in the list, starting
with 0 as the top item.
-
name - The internal name
used in the client app for this object.
-
nValue - An
integer value from 0 to (n - 1), where n is the number of current choices
in the combobox.
COMBOBOX.SetSelectedItem(name IN
VARCHAR2, value IN VARCHAR2)
This procedure is used to
set the currently selected item by specifying the value of one of the choices.
-
name - The internal name
used in the client app for this object.
-
value - A
character string that must exactly match one of the current choices in
the combo box (case-sensitive).
Label
LABEL.SetIcon(name IN VARCHAR2, value
IN VARCHAR2)
This procedure is used to
display an image with the text of a label.
-
name - The internal name
used in the client app for this object.
-
value - The
filename of an optional image to be displayed to the left of the label
text.
LABEL.SetText(name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
change the displayed text of a label.
-
name - The internal name
used in the client app for this object.
-
value - A
character string that is the label text to be displayed.
List
box
LISTBOX.AddItem(name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
add one or more values to the listbox choices. Values are always added
at the bottom of the list of choices.
-
name - The internal name
used in the client app for this object.
-
value - A
comma-separated list of one or more character strings to be displayed as
choices in the list. A choice cannot contain commas.
LISTBOX. RemoveAllItems(name IN
VARCHAR2)
This procedure is used to
remove all choices from (clear) a listbox.
-
name - The internal name
used in the client app for this object.
LISTBOX. SetDefaultSelection(name
IN VARCHAR2, value IN VARCHAR2)
This procedure is used to
set the default selected item by specifying the value of one of the choices.
-
name - The internal name
used in the client app for this object.
-
value - A
character string that must exactly match one of the current choices in
the listbox (case-sensitive).
LISTBOX. SetSelectedIndex name IN
VARCHAR2, nValue IN NUMBER)
This procedure is used to
set the currently selected item to the n'th item in the list, starting
with 0 as the top item.
-
name - The internal name
used in the client app for this object.
-
nValue - An
integer value from 0 to (n - 1), where n is the number of current choices
in the listbox.
LISTBOX. SetSelectedItem(name IN
VARCHAR2, value IN VARCHAR2)
This procedure is used to
set the currently selected item by specifying the value of one of the choices.
-
name - The internal name
used in the client app for this object.
-
value - A
character string that must exactly match one of the current choices in
the listbox (case-sensitive).
Message
Box
MSGBOX.Message(msg IN VARCHAR2)
This procedure is used to
display an informational message to the user, in a modal dialog box with
an OK button.
-
msg - A
character string for a one-line message to be displayed in the message
box. Cannot contain the comma (",") character.
MSGBOX.Warning(msg IN VARCHAR2)
This procedure is used to
display an error or warning message to the user, in a modal dialog box
with an OK button.
-
msg - A character string
for a one-line message to be displayed in the message box. Cannot contain
the comma (",") character.
Radio
Button
RADIOBUTTON. SetSelectedValue(name
IN VARCHAR2, bValue IN BOOLEAN DEFAULT TRUE)
This procedure is used to
select (check) or unselect (clear) a radio button.
-
name - The internal name
used in the client app for this object.
-
bValue - A
boolean value for the selected state of the radio button: TRUE for selected,
FALSE for not selected.
RADIOBUTTON. SetText(name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
change the caption on a radio button.
-
name - The internal name
used in the client app for this object.
-
value - A
character string to be displayed as the caption (label) of this object.
Table
(Grid)
GRID.RemoveAllItems(name IN VARCHAR2)
This procedure is used to
remove all rows from a table component in a client app.
-
name - The internal name
used in the client app for this object.
GRID.SetRowText(name IN VARCHAR2,
nRow IN NUMBER DEFAULT 0, value IN VARCHAR2, delimiter IN VARCHAR2)
This procedure is used to
add or change the contents of all cells in one row of a table. If the specified
row number does not exist, it will be added. If no row number is specified,
a new row is added at the end of the table. The value must be a comma-separated
list of column values for every column of the row. Each column value must
be a string of the appropriate data type as defined in the client table
column properties.
-
name - The internal name
used in the client app for this object.
-
nRow - An optional integer
row number of the cell to be added or changed, starting with 0 (zero) for
the top row.
-
value - A list of column
values, separated by commas or other optional delimiter character.
-
delimiter - An optional
single character to be used instead of the comma character to delimit values.
GRID.SetSelectedRow(name IN VARCHAR2,
nRow IN NUMBER DEFAULT 0)
This procedure is used to
set the "selected" row in a table.
-
name - The
internal name used in the client app for this object.
-
nRow - An
optional integer row number of the cell to be added or changed, starting
with 0 (zero) for the top row.
GRID.SetText(name IN VARCHAR2, nRow
IN NUMBER DEFAULT 0, nColumn IN NUMBER DEFAULT 0, value IN VARCHAR)
This procedure is used to
assign or change the contents of one cell in a table.
-
name - The internal name
used in the client app for this object.
-
nRow - An integer row
number of the cell to be added or changed, starting with 0 (zero) for the
top row.
-
nColumn - An integer
column number of the cell to be changed, starting with 0 (zero) for the
leftmost column.
-
value - The value to
be displayed in this cell.
Textarea
TEXTAREA.SetText(name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
display text within a text area.
-
name - The internal name
used in the client app for this object.
-
value - The
character string to be displayed within the text area. This value may contain
line feed characters, which will override the automatic word wrap feature
of the text area, to allow user-controlled text placement (as with a name/address
display).
Textfield
TEXTFIELD.SetText(name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
display a value within a textfield.
-
name - The internal name
used in the client app for this object.
-
value - The
value to be displayed in the textfield. All values will be automatically
converted to strings before being sent to the client, so you may use database
fields that are dates, integers, decimals, etc.
Textpane
TEXTPANE.SetText(name IN VARCHAR2,
value IN VARCHAR2)
This procedure is used to
display a value within a textpane.
-
name - The
internal name used in the client app for this object.
-
value - The
character string to be displayed within the textpane. This value may contain
line feed characters, which will override the automatic word wrap feature
of the textpane, to allow user-controlled text placement (as with a name/address
display).
Tree
(JSITree)
JSITree.AddNode(treeName IN VARCHAR2,
parentName IN VARCHAR2, nodeName IN VARCHAR2, text IN VARCHAR2, userData
IN VARCHAR2, tooltip IN VARCHAR2, imageIndex IN PLS_INTEGER DEFAULT 0,
nodeIndex IN PLS_INTEGER DEFAULT -1)
This procedure is used to
add a node to the tree.
-
treeName - The internal
name used in the client app for this tree object.
-
parentName - The name
of the parent node that this node should be added to (to add a node to
the root node, use the name of the tree, which is the same value use for
'treeName')
-
nodeName - The internal
name for the tree node being added.
-
text - The visible label
for the tree node being added.
-
userData - The hidden,
user-defined data for the tree node being added.
-
tooltip - The tooltip
for the tree node being added.
-
imageIndex - The index
of the tree's image list for the tree node being added.
-
nodeIndex - The index
within its parent's child node array for the tree node being added.
JSITree.CollapseNode(treeName IN
VARCHAR2, nodeName IN VARCHAR2)
This procedure is used to
collapse a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node to collapse.
JSITree.ExpandNode(treeName IN VARCHAR2,
nodeName IN VARCHAR2)
This procedure is used to
expand a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node to expand.
JSITree.RemoveChildNodes(treeName
IN VARCHAR2, nodeName IN VARCHAR2)
This procedure is used to
remove all child nodes from a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node.
JSITree.RemoveNode(treeName IN VARCHAR2,
nodeName IN VARCHAR2)
This procedure is used to
remove a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node to remove.
JSITree.SetNodeImageIndex(treeName
IN VARCHAR2, nodeName IN VARCHAR2, imageIndex IN PLS_INTEGER)
This procedure is used to
change the visible image that reperesents a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node.
-
imageIndex - The index
of the tree's image list for the tree node.
JSITree.SetNodeText(treeName IN
VARCHAR2, nodeName IN VARCHAR2, text IN VARCHAR2)
This procedure is used to
change the visible label of a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node.
-
text - The visible label
for the tree node.
JSITree.SetNodeTooltip(treeName
IN VARCHAR2, nodeName IN VARCHAR2, tooltip IN VARCHAR2)
This procedure is used to
change the tooltip of a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node.
-
tooltip - The tooltip
data for the tree node.
JSITree.SetNodeUserData(treeName
IN VARCHAR2, nodeName IN VARCHAR2, userData IN VARCHAR2)
This procedure is used to
change the hidden, user-defined data of a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node.
-
userData - The user-defined
data for the tree node.
JSITree.SetSelectedNode(treeName
IN VARCHAR2, nodeName IN VARCHAR2)
This procedure is used to
select a tree node.
-
treeName - The internal
name used in the client app for this tree object.
-
nodeName - The internal
name for the tree node to select.
Up to Top
Return to Help Index