Basic SurferScript  Click on any item to view... Contents + Introduction + Concepts + Product Positioning + Operations + Customization SurferScript Guide SurferScript Introduction SurferScript Example Basic SurferScript Visual Surfer Introduction This section describes the basic tags and functionality you need to implement enhancements of host screens using Screensurfer. The Big Organizer: TESECTION The <TESECTION> tag is the primary means of identifying both sections of Surferscript as well as optionally associating those sections with certain events. The simplest TESECTION only names a block of Surferscript, enabling other sections in any template file to "call" the section using the <TEPUTSECTION> tag. To call a section in another template, you include the name of the template (without any extension) followed by the name of the target section. Screen-driven sections include a name (yes, they can be called too by other sections) as well as the WHEN clause, with one or more screen identification phrases (SCREEN_row_column IS "text") to uniquely identify the screen that will cause the subject section to execute. You should note that the Screensurfer template compiler takes care of identifying any ambiguity and/or duplication across all templates and all sections. Web-driven sections include a name followed by a WHEN clause that identifies submitted URLs (uniform resource locators) with the TRANPATH_ID phrase. These sections are commonly referred to as "transactions" in that they are requested by a client by name. Note that web-driven sections can be called from HTML links that use the TEMACRO TRANURL tag to create the HREF attribute. Hooking-in to the user To connect Surferscript to a user's entry from a TESECTION, you use the TEEVENT WEBINPUT tag, which will be executed when the user clicks on the "ENTER" button or another button, such as the "PF1" or other host key on a Screensurfer-generated form. This allows you to capture the user's entries (the data from the web page is written to the screen prior to execution of your Surferscript). You may then save them in variables, log to a database, perform validation and reformatting or whatever. Catching Host Error Messages You can easily associate Surferscript with host error messages so that your exception Surferscript is executed instead of the primary TESECTION. You do this by implementing a TEEVENT HostEventName tag. Note that any name for you host event can be used except "WEBINPUT" and "CATCH". By defining a TEEVENT of this type, you can direct Surferscript for specific host errors, and the recognition engine in the Screensurfer runtime will look first for your exceptions before trying to identify the "next" screen. Catching Errors Screensurfer can encounter errors during execution either by a Surferscript programming error, a host connection being lost, an ODBC SQL error or an internal error. These errors will by default display a "Error occurred" message to the user. You can catch these errors yourself using the TEEVENT CATCH tag. The TEVENT CATCH can be implemented at any level in your Surferscript; when an error occurs, the runtime engine will "bubble-up" to find a calling section that has a CATCH implemented. Controlling Logic You manage the flow of control using the TEIF, TEELIF, /TEIF, TELOOP and /TELOOP tags. You may have TEIF's inside TEIF's, and also TELOOP's inside TELOOP's. In a TEIF expression, you can compare using ">" (greater than), "<" (less than), ">=" (greater than or equals), "<=" (less than or equals), "<>" (not equal), "!=" (not equal) and "==" (equal). Setting Variable Values You set variable values using the TESET tag. The expressions used will be executed based on the "left-side" variable's type. Expressions used to set variables may include the "+", "-", "*" and "/" operators. You may also use parenthesis characters to force precedence of the expression. Without parenthesis characters, Screensurfer follows the natual precedance of "*/+-". Creating a Screensurfer HTML Form To properly return user entries that may be associated with screen entry fields, you should use the TEMACRO TERMFORM tag, which will create a special version of the HTML FORM tag. This special version generates the form's ACTION attribute with all the right information to maintain state and authenticate subsequent submissions. Note that JavaScript is also generated that may be used to request a form submission from Javascript in other windows or frames. Including Screen Data in your HTML There are a variety of tags that may be used to display information from a screen inside your HTML. The three principal tags are: TEAREA The TEAREA tag will display a "block" of the current screen to the active HTML stream. By default, and entry (unprotected) fields will be displayed as HTML input fields. If displaying screen areas with input fields, be sure to include the Screensurfer TEMACRO TERMFORM, described above. Since the TEAREA tag provides a "block" oriented area of the screen, it is typically bounded (or a group is bounded) by the HTML <PRE> and </PRE> tags. TEDATA The TEDATA tag is similar to the TEAREA tag, but is designed for displaying a single field at a time. If the field being displayed is an entry-capable field, the default behavior is to create an HTML entry field with the matching attributes. TESHOW The TESHOW tag may be used to display any data, from not only the screen, but also any Surferscript variables or an ODBC result row. To display screen data, you use the Screen or TextScreen functions. No automatic entry field generation is created by these functions; they are read only. TESHOW is useful for re-formatting screen fields or perhaps splitting-them and seperating with literals, since TESHOW supports standard string concatenation with the "+" operator. Displaying Special HTML The TEMACRO tag provides a number of options for generating special links, displaying special values and so on. For example, the <TEMACRO SESSIONKEY> tag will include the active session key in the outbound HTML (needed when creating links back to the current session). Interacting with the Host The TEACTION tag provides a number of options for interacting with the host screen session as well as controlling the current user request. For example, the <TEACTION ENTER "logon[enter]"> tag will enter the keystrokes "logon" and then simulate the 3270 ENTER key.