Host Methods for Progress 4GL
Version 3

 

General	Container Methods	Component Methods
Introduction	Generic Container	Generic Component
Utility Methods	Frame	Button
State-Aware Methods	Panel	Checkbox
		Combobox
		Hyperlink
		Label
		Message Box
		Passwordfield
		Table
		Textarea
		Textfield
		Textpane

This document lists each of the "jsi" include files that can be used by Progress procedures 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
• making a container or component visible or hidden
• populating or clearing row and cell contents in a table
• adding or selecting a specific value in a combobox

• invoke any existing function in a client app

These include files are referenced using the normal Progress "include file reference" syntax, with enclosing brace characters containing the name of the include file and zero or more name/value pairs for any required arguments.

For example, to display the value of the database field "customer.name" in a client textfield whose object name is "tName", an include file reference with two arguments is used:

{jsi/textfield/settext.i &name='tName' &val=customer.name }

{jsi/component/setenabled.i &name='bDelete' &b='false' }

When a literal value is used for a parameter, it must be enclosed in single quotes, like the 'false' value in the second example. If the literal value contains embedded spaces, such as a multi-word message, then there should also be a set of double quotes outside the single quotes. This example will send an error message in a warning box when no customer record is available:

{jsi/msgbox/warning.i &component='fMain'
                      &msg="'No customer record was found.'" }

define variable vMsg as character.
find customer where customer.cust-num = tCustNum exclusive-lock no-wait no-error.
if not available customer then do:
   if locked customer
      then vMsg = "That customer record is locked.".
      else vMsg = "No such customer record was found.".
      {jsi/msgbox/warning.i &component='fMain' &msg=vMsg }
   end.
else
   {jsi/textfield/settext.i &name='tName' &val=customer.name }

Utility Methods

jsi/invoketasklist.i
This method 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. Note that functions which have one or more input parameters cannot be invoked in Version 3.0, only those functions which do not have any input parameters.

• &appname - The name of the client app (without the ".xml" suffix) in which a function is to be invoked.
• &tasklistname - The internal name of the function to be invoked in the app.

State-Aware Methods

jsi/state/start.i
This method is used to start a state-aware WebSpeed session and lock an agent to this client.

• &timeout - The number of minutes to wait before ending a state-aware session which has had no activity from its client during that time. Default is 5 minutes.

jsi/state/end.i
This method is used to explicitly end a state-aware WebSpeed session and free the agent to handle other clients.

jsi/tran/start.i
This method is used to explicitly start a Web transaction within a state-aware session.

jsi/tran/commit.i
This method is used to explicitly commit a Web transaction within a state-aware session.

jsi/tran/undo.i
This method is used to explicitly undo a Web transaction within a state-aware session.

jsi/tran/retry.i
This method is used to explicitly retry a Web transaction within a state-aware session.

Container Methods
These methods are used with various container objects (frames, panels, cardpanels, tabpanels). There are both generic container methods which can be used with any container type, and other methods that are specific to a particular container type.

Generic Container
These methods can be used on any container object (frame, panel, cardpanel, tabpanel).

No Generic Container methods are available in Version 3.0

Frame

jsi/frame/setmessage.i
This method 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.

&val - A character string to be displayed as a message. Example: " 'Process completed' ".

jsi/frame/settitle.i
This method 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.
• &val - A character string to be displayed as the frame title. Example: " 'My Title' ".

jsi/frame/setvisible.i
This method is used to make a frame visible or invisible (hidden).

&name - The internal name used in the client app for this object.

&val - A boolean (logical) value: 'true' to make visible, 'false' to hide.

No Panel methods are available in Version 3.0
 

Component Methods
These methods are used with various component objects (objects which are not containers). There are both generic component methods which can be used with any component type, and other methods that are specific to a particular component type.

Generic Component
These methods 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

jsi/checkbox/select.i
This method is used to select (check) or unselect (clear) a checkbox.

• &name - The internal name used in the client app for this object.
• &val - A boolean value for the selected state of the checkbox: 'true' for selected, 'false' for not selected.

Combo box

jsi/combobox/additem.i
This method is used to add a value to the combobox choices. Values are always added at the bottom of the list of choices (appended).

• &name - The internal name used in the client app for this object.
• &val - A character string to be displayed as a choice in the list. A choice cannot contain commas.


jsi/combobox/removeallitems.i
This method is used to remove all choices from (clear) a combobox.

• &name - The internal name used in the client app for this object.

jsi/combobox/setselectedindex.i
This method 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.
• &val - An integer value from 0 to (n - 1), where n is the number of current choices in the combobox.


jsi/combobox/setselecteditem.i
This method 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.
• &val - A character string that must exactly match one of the current choices in the combo box (case-sensitive).

jsi/hyperlink/settext.i
This method is used to assign the underlined text value to be displayed in a hyperlink.

• &name - The internal name used in the client app for this object.
• &val - The value to be displayed in the hyperlink. 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.

jsi/hyperlink/setuserdata.i
This method is used to assign a value to the hidden userdata attribute in a hyperlink.

• &name - The internal name used in the client app for this object.
• &val - The value to be stored as the hyperlink userdata value. 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.

No Label methods are available in Version 3.0
 

Message Box

jsi/msgbox/message.i
This method is used to display an informational message to the user, in a modal dialog box with an OK button.

• &component - The name of the frame that should receive focus after the user clicks the OK button.
• &msg - A character string for a one-line message to be displayed in the message box. Cannot contain the comma (",") character.


jsi/msgbox/warning.i
This method is used to display an error or warning message to the user, in a modal dialog box with an OK button.

• &component - The name of the frame that should receive focus after the user clicks the OK button.
• &msg - A character string for a one-line message to be displayed in the message box. Cannot contain the comma (",") character.

jsi/textfield/settext.i
This method is used to display a value within a passwordfield. Note that it uses the textfield method, the only difference is that the value will be displayed as asterisks instead of the real value.

• &name - The internal name used in the client app for this object.
• &val - The value to be displayed in the passwordfield. 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.

jsi/table/removeallitems.i
This method is used to remove all rows from a table.
 
• &name - The internal name used in the client app for this object.



jsi/table/setrowtext.i
This method 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 delimiter-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.
• &val - A list of column values, separated by commas or other optional delimiter character.
• &delim - An optional single character to be used instead of the comma character to delimit values. 
  
  
  
jsi/table/settext.i
This method is used to assign or change the contents of one cell in a table. Both the row and column numbers must be specified (both start at zero, not one.
 
• &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.
• &ncol - An integer column number of the cell to be changed, starting with 0 (zero) for the leftmost column.
• &val - The value to be displayed in this cell.

jsi/textarea/settext.i
This method is used to display text within a text area.

• &name - The internal name used in the client app for this object.
• &val - 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).

jsi/textfield/settext.i
This method is used to display a value within a textfield.

• &name - The internal name used in the client app for this object.
• &val - 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.

jsi/textpane/settext.i
This method is used to display a value within a textpane.

• &name - The internal name used in the client app for this object.
• &val - 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).