General Container Methods Component Methods Introduction Generic Container Generic Component Utility Methods Frame Button State-Aware Methods Panel Checkbox Remote File Procedures Combobox Hyperlink Label Message Box Passwordfield Table Textarea Textfield Textpane Introduction 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 In addition, a powerful utility method 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 methods are available to start and end a "state-aware" session, which dedicates a Progress Webspeed agent or AppServer process to one client and maintains its "state" (value of working variables, temp-tables, etc.) between interactions with that client. Related methods are used to start, commit, undo and retry transactions within a state-aware session. 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 } Another example disables a button whose object name is "bDelete" so that it cannot be clicked or receive focus: {jsi/component/setenabled.i &name='bDelete' &b='false' } If the value used for a parameter is a variable name, database field name, temp-table field name or a Progress function (string, substring, etc.) then it is not quoted, like the customer.name value in the first example. 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.'" } Note that the message box example could also use a variable, which can allow more streamlined coding. For example: 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 } Most include files have at least one required argument, the "object name" which names a container or component object to which the method 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 Progress language itself, and can be the cause of numerous errors if not carefully followed. 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. Remote File Procedures jsi/file/write.i This function is used to open a new text file on the client device, write text data to it, and close it. The text data can be a character string of any (reasonable) size. It may contain newlines. If a file with the same name already exists, it will be overwritten. Any specified directories (folders) must already exist, this method will NOT create them. &pathName - a character string that is the pathname of the file to write to. &val - a character string that is the data to write to the file. jsi/file/append.i This function is used to append text data to a new or existing text file on the client device. The text data can be a character string of any (reasonable) size. It may contain newlines. If no file with the specified name exists, it will be created. Any specified directories (folders) must already exist, this method will NOT create them. &pathName - a character string that is the pathname of the file to append to. &val - a character string that is the data to append to the file. jsi/file/delete.i This function is used to delete an existing file on the client device. &pathName - a character string that is the pathname of the file to delete. 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 this version. 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. Panel No Panel methods are available in this version.   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 unless otherwise specified. jsi/component/disable.i This method is used to disable any of the following components: Button, Checkbox, Combobox, Datefield, Hyperlink, Passwordfield, Table, Textarea, Textfield, and Tree. Note that the Table and Hyperlink components will not change color when disabled, but they will not respond to any user interaction until re-enabled. &name - The internal name used in the client app for this object. jsi/component/enable.i This method is used to enable any of the following components: Button, Checkbox, Combobox, Datefield, Hyperlink, Passwordfield, Table, Textarea, Textfield, and Tree. &name - The internal name used in the client app for this object. Button No Button methods are available in this version. 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). Hyperlink 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. Label No Label methods are available in this version.   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. Passwordfield 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. Table 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. Textarea jsi/textarea/append.i This method is used to append to the existing displayed text within a text area. &name - The internal name used in the client app for this object. &val - The character string to be appended to 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/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). Textfield jsi/textfield/append.i This method is used to append to the existing displayed text within a textfield. &name - The internal name used in the client app for this object. &val - The character string to be appended to 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/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. Textpane jsi/textpane/append.i This method is used to append to the existing displayed text within a textpane. &name - The internal name used in the client app for this object. &val - The character string to be appended to 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). 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).