Host Procedures for Oracle
PL/SQL
Version 3
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 textpane
-
selecting ("checking") or unselecting
a checkbox
-
assigning or changing an object's
title, caption or image
-
adding or selecting a specific
value in a combobox
In addition, a powerful utility
procedure
allows a host procedure to make use of all functions available in a client
app:
-
invoke any existing function
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.InvokeTasklist(appName VARCHAR2,
tasklistName VARCHAR2)
This procedure is used to
instruct the client to execute an existing function in a specific app.
The function can contain any valid list of statements, 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 function to be invoked in the app.
Container
Procedures
These procedures are used with
various container objects (frames, panels). 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).
No Generic Container methods are available in Version
3.0
Frame
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.
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.
No Generic Component methods are available in Version
3.0
Button
No Button methods are available in Version 3.0
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.
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.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
No Label methods are available in Version 3.0
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.
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.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).
Up to Top
Return to Help Index