Host Screen and Session Control Actions

Page Links	TEACTION, TEACTION DROPHOST, TEACTION KEY, TEACTION SETCURSOR, TEACTION PUTDATA, TEACTION PUTFIELD, TEACTION ENTER, TEACTION CONNECT, TEACTION RECONNECT, TEACTION RELEASE, TEACTION RESTART, TEACTION WAITFOR, TEACTION GOTO, TEACTION GETSESSION, TEACTION RETURN, TEACTION ENDREQUEST, TEACTION WEBTOSCREEN, TEACTION WEBTOSCREENMAP, TEREADYWHEN, TEFIND, TEENTER, Keystroke Mnemonics for Host Keys
Examples	TEACTION KEY, TEACTION ENTER: Combining Two Screens, TEACTION ENTER: Navigation, TEACTION WAITFOR, TEACTION GOTO, TEREADYWHEN, TEENTER FromScreen ToScreen TEENTER ToScreen

This document covers three tags which together provide Session Management, Screen Navigation and Screen Interaction.

• TEACTION is a "tag of many uses" since it is in fact 13 tags in one, all of which perform actions against the user session, the HTTP session or the host screen.
• TEREADYWHEN is a new tag to address the challenges of screen transitions. TEREADYWHEN allows the developer to "prime" the screen transition logic with a "strategy" to avoid conditions where intermittent and unpredictable host responses present a challenge.
• TEFIND provides a means of searching the current screen for a given text string. An optional timeout turns TEFIND into another approach to managing screen transitions.
• TEENTER inputs the specified keys, including an AID key (such as Enter) to enter the screen along with identifing the FROM and TO screen in a screen transition.

TEACTION Perform an action affecting the current Host Screen Session or the User Session

Available Actions

Actions	Description
DROPHOST	Stop the current host session and disconnect (drop) the connection while keeping the active "session" and its state variables active
KEY	Input the specified keys to the current session
SETCURSOR	Set the cursor position in the current session
PUTDATA	Put specified data to the specified location in the current session
PUTFIELD	Put specified data to the specified field in the current session
ENTER	Input the specified keys, including an AID key (such as Enter) to enter the screen
CONNECT	Connect the current user to a requested session-- only valid in transactions
RECONNECT	Re-connect the user based on IP address-- like CONNECT
RELEASE	Release the user from a session (make it available to other users), with optional "keepopen" of the session.
RESTART	Restart a host connection for an already active session-- can be used following the DROPHOST
WAITFOR	Wait for a particular screen/section to be displayed
GOTO	Go to a specific screen section using built-in PATHTO navigation
GETSESSION	Using the current transaction URL, connect to and validate URL-to-Session Key
RETURN	Stop executing template code and return immediately to client
ENDREQUEST	Return control to client (end HTTP request) but continue processing script
WEBTOSCREEN	Copy automatic field variables from web to active screen
WEBTOSCREENMAP	Copy all automatic web entry fields to the current screenmap

---

TEACTION DROPHOST Drop the current host connection

<TEACTION DROPHOST>

Will stop the current host connection and drop any communications resources associated with that session while maintaining the scripting session. This is useful in environments where the host connection may need to be restarted in order to back-out of an error condition, or where on occasion an alternate host connection is needed for a specific application requirement.

---

TEACTION KEY Input the specified keys to the current session

<TEACTION KEY {KeyTextExpression}]>

KeyTextExpression = a valid text expression which can include variables as well as text literals concatenated using the "+" sign.

Will enter the specified keystring to the active session screen during execution of the current section.  Standard EHLLAPI escape sequences, such as "[tab]" or "@T" for TAB may be used (see table, below for defined keys), but AID keys such as "@E" for ENTER are not allowed-- to enter keystrings accompanied by an AID key, use <TEACTION ENTER>.

NOTE: with version 1.3E, the registry setting "Compatible Mnemonics" was added, which defaults to YES. If you change this to NO, then EHLLAPI escape sequences are no longer supported which also means that the @ character will not cause any problems if keyed-in by a user!. When operating in this mode (Compatible Mnemonics=NO), only the "square bracket" mnemonics are supported in all key strings.

TEACTION KEY SAMPLE
<TEACTION KEY "[home][tab][tab]"+Customer.Number+"[tab]"+"OPEN">
This example will position the cursor at the first (home) field on the screen, then tab to the third field (using two tab actions), then enter the contents of the SurferScript variable "Customer.Number", then tab to the next field and key the text "OPEN".


Valid Keystroke Mnemonics for Host Keys
 
In a keystroke string, you may use either the "square bracket" mnemonic or the EHLLAPI sequence (see note above) described in the first two columns in the following table.  Keystroke strings are used in the <TEMACRO SendKeys>, <TEACTION ENTER> and <TEACTION KEY> macros.
 

Mnemonic	EHLLAPI Sequence	Emulator Key
[left tab]	@B	Back Tab to start of Field or Prior Field
[back tab]	@B	Back Tab to start of Field or Prior Field
[clear]	@C	Clear Screen
[delete]	@D	Delete current character
[enter]	@E	Enter Key (AID)
[erase eof]	@F	Erase EOF (5250)
[help]	@H	Help (5250) (AID)
[insert]	@I	Insert
[left]	@L	Cursor Left
[new line]	@N	Cursor to New Line
[space]	@O	Space character
[print]	@P	Print
[reset]	@R	Reset Keyboard
[tab]	@T	Tab to start of next field
[up]	@U	Cursor Up
[down]	@V	Cursor Down
[right]	@Z	Cursor Right
[home]	@0	Cursor Home (first field on screen)
[pf1]	@1	PF Key 1 (AID)
[pf2]	@2	PF2 (AID)
[pf3]	@3	PF3 (AID)
[pf4]	@4	PF4 (AID)
[pf5]	@5	PF5 (AID)
[pf6]	@6	PF6 (AID)
[pf7]	@7	PF7 (AID)
[pf8]	@8	PF8 (AID)
[pf9]	@9	PF9 (AID)
[pf10]	@a	PF10 (AID)
[pf11]	@b	PF11 (AID)
[pf12]	@c	PF12 (AID)
[pf13]	@d	PF13 (AID)
[pf14]	@e	PF14 (AID)
[pf15]	@f	PF15 (AID)
[pf16]	@g	PF16 (AID)
[pf17]	@h	PF17 (AID)
[pf18]	@i	PF18 (AID)
[pf19]	@j	PF19 (AID)
[pf20]	@k	PF20 (AID)
[pf21]	@l	PF21 (AID)
[pf22]	@m	PF22 (AID)
[pf23]	@n	PF23 (AID)
[pf24]	@o	PF24 (AID)
[plus]	@p	Plus Sign
[end]	@q	End
[page up]	@u	Page Up (5250) (AID)
[page down]	@v	Page Down (5250) (AID)
[pa1]	@x	PA1 Key (AID)
[pa2]	@y	PA2 Key (AID)
[pa3]	@z	PA3 Key (AID)
[word delete]	@A@D	Delete Word
[field exit]	@A@E	Field Exit
[erase input]	@A@F	Erase Input
[sys req]	@A@H	System Request (AID)
[insert]	@A@I	Insert
[cur select]	@A@J	Cursor Select
[attn]	@A@Q	Attention
[printps]	@A@T	Print PS
[erase eol]	@S@A"	Erase to End of Line

Special ScreenSurfer Key Sequences

The following sequences are ScreenSurfer-unique and have been introduced to assist in screen transitions in a PATHTO, and to provide field-oriented data entry. Note that the concept of "parameters" are introduced following the mnemonic, in parenthesis characters.

Mnemonic	Effect
[Put](F_row_column,"Text")	Will copy the "Text" to the Field described using the ScreenSurfer auto field name. During the copy, any blank processing/truncation will occur, just as with other putfield operations. Example: [Put](F_2_10,"Hello")
[c_pos](offset)	Sets current cursor position to the specified offset. Example: [c_pos](100)
[buffers](HostWritesExpected)	Next screen transition will have N buffers before screen is ready. Example: [buffers](3)
[sleep](milliseconds)	Sleep for the specified milliseconds (1000 = second). Example: [sleep](5000)
[settle](milliseconds)	Change the current settletime to the specified milliseconds (1000 = second). Settletime is the time ScreenSurfer will wait between buffers to assure the host is all done (default=200). Example: [settle](500)

 

---

TEACTION SETCURSOR Set the cursor position in the current session

<TEACTION SETCURSOR {RowExpression | OffsetExpression} [ColumnExpression] >

This action will set the cursor location in the current host screen session.  It expects either one or two integer expressions.

If a single integer expression is given, it is interpreted as being the zero-based offset into the host screen area.  If two integer expressions are given, they aer interpreted as 1-based row, column values.  This allows the SETCURSOR to be used in a greater variety of situations, particularly when an HTML value may be providing cursor location in an offset (such as the Web.C_POS variable).

RowExpression/OffsetExpression and ColumnExpression may be any valid integer expression, including integer variables.
 

---

TEACTION PUTDATA Put specified data to the specified location in the current session

<TEACTION PUTDATA RowExpression ColumnExpression DataExpression>

RowExpression and ColumnExpression are both INTEGER expressions.

DataExpression is a TEXT expression.  Note:  the TEACTION PUTDATA does not translate embedded mnemonics.  You should not include strings such as "[tab]", as they will not be translated and acted upon.  This avoids the performance penalty of interpreting the string, as the DataExpression may be directly written to the host buffer.

An alternative to TEACTION KEY.  The TEACTION PUTDATA tag will directly put the data specified into the row/column area, up to the size of the data provided.

It is recommended that you use TEACTION PUTFIELD (described below) in favor of TEACTION PUTDATA any time you are updating a complete field where the data being put in the field is an indeterminate length. When you are updating a portion of a field, the TEACTION PUTDATA should be utilized.

Example:

<TEACTION PUTDATA found.row 20 web.invoice_number>

The above example will put data on the row contained in the local variable "found.row" (this looks to be the result of a <TEFIND> tag) and column 20 in that row.  The data put will come from the current web page, in either a URL name/value (where the name is "invoice_number"), or from an HTML FORM input field with an attribute of 'name="invoice_number"'.

---

TEACTION PUTFIELD Put specified data to the specified field in the current session

<TEACTION PUTFIELD RowExpression ColumnExpression DataExpression>

RowExpression and ColumnExpression are both INTEGER expressions.

DataExpression is a TEXT expression.  Note:  the TEACTION PUTFIELD does not translate embedded mnemonics.  You should not include strings such as "[tab]", as they will not be translated and acted upon.  This avoids the performance penalty of interpreting the string, as the DataExpression may be directly written to the host buffer.

TEACTION PUTFIELD is very similar to the TEACTION PUTDATA tag with the exception that the TEACTION PUTFIELD will null-terminate any remainder of the field at the specified location, so that if the data being updated to the field is shorter than the data that is already present, ScreenSurfer will ensure that there will be no remaining characters from any prior data in the field.

It is recommended that you use TEACTION PUTFIELD in favor of TEACTION PUTDATA any time you are updating a complete field where the data being put in the field is an indeterminate length. When you are updating a portion of a field, the TEACTION PUTDATA should be utilized.

---

TEACTION ENTER Input the specified keys, including an AID key (such as Enter) to enter the screen

<TEACTION ENTER KeystrokeExpression
  [EXPECTING SectionName]
  [SKIPCODE | SKIPSCAN]>

TEACTION ENTER is the primary means of performing a controlled screen transition inside your SurferScript. It is what you use to transition from one screen to the next. Note that unless you code a SKIPCODE or SKIPSCAN another TESECTION will run inside this tag!. That is because the TEACTION ENTER performs a screen event by default, which will cause either one of your screen event sections to execute, or global.default. So, if you don't want another screen to appear in your HTML page, code the SKIPSCAN or SKIPCODE!

Will send the text expression KeystrokeExpression to the current session's host screen; you may include mnemonics such as [home] and [tab], but note that the keystroke defined must be an "AID" sequence such as "[enter]" or "@E" (which is the ENTER key).  For valid keystroke strings, see Valid Keystroke Mnemonics for Host Keys.

EXPECTING sectionname will "prime" the screen transition logic to wait for the specified screen to be recognized; this can improve performance as well as assure that the right screen is displayed.

If SKIPCODE is specified, than the template for the screen that is displayed will be NOT be executed (if any). Specify SkipCode to avoid playing any sections connected to the resulting screen.

If SKIPSCAN is specified, than no screen recognition or active screen timer is updated.  This is useful when executing transactions such as HELP transactions, where a help screen is called, scraped and then the active screen is returned (in the host session) to its prior state.  SKIPSCAN will also not execute any section code (will imply SKIPCODE).

TEACTION ENTER Example: Combining Two Screens
<TESECTION CustomerStatus WHEN Screen_1_10 is "Customer Status"> <TEPUTSECTION Global.Header> <TEFORM> <TENOTEXT> <TESHOW "<PRE>"> <TEAREA 1 1 22 80 AS READONLY> <TEIF Screen(23,60,4)=="More"> <TEACTION ENTER "[pf8]" SKIPCODE> <TEAREA 3 1 22 80 AS READONLY> </TEIF> </TENOTEXT></PRE> <br> <TESHOW AidButtons("Enter=Enter pf3=Customer List pf10=Main Menu","")> </FORM> <TEPUTSECTION Global.Footer> </TESECTION>
This example demonstrates how you can combine two screens easily with a minimal amount of coding. The Customer Status Screen event section is a query screen that may have a second screen if the customer is a "premium" customer. The host application displays "More" on row 23, column 80 if there is a second screen. PF8 is used to display the second screen if it exists. TENOTEXT is used to prevent gaps and formatting issues inside the <PRE> tags. Note the use of the SKIPCODE to prevent the next screen "just displaying itself" during the TEACTION ENTER.

TEACTION ENTER Example: Navigation
<TESECTION GetCustBalance WHEN TRANPATH_1 is "customer" AND TRANPATH_2 is "balance"> <TEACTION GETSESSION> <TEIF Screen(1,2,4) != "MENU"> <TEACTION ENTER "[pf3]" skipcode> </TEIF> <TEACTION ENTER "3[erase eof][enter]" SKIPCODE> <TEACTION ENTER "[home]"+web.CustomerNumber+"[enter]"> </TESECTION>
The above URL-event transaction section uses a TEIF if see if the screen is on the main menu. If not, the host application system provides a PF key (PF3) which will always "exit" the current screen and return to the main menu, so the example performs this, using SKIPCODE to avoid displaying an image of the menu screen in the user's browser. Next, the "Customer Balance Inquiry" menu item is selected (it's selection 3), to display the customer number entry screen. At this point, the next TEACTION ENTER keys the customer number as passed by the HTTP client, and because neither of the SKIP attributes is used, the customer balance screen will be displayed at the browser (using global.default or a screen event section if one is set-up to recognize it).

---

TEACTION CONNECT Connect the current user to a session

<TEACTION CONNECT ["GroupName[:LUNAME/DEVNAME]"]> --OR--
For host type *ANY:
  <TEACTION CONNECT ["GroupName:null"]> --OR--
  <TEACTION CONNECT ["GroupName:SNA:luname[(term characteristics)]"]> --OR--
  <TEACTION CONNECT ["GroupName:tn3270:host:[port:][luname][(term characteristics)]"]> --OR--
  <TEACTION CONNECT ["GroupName:tn5250:host:[port:][DevID][(term characteristics)]"]>

This action is intended for use in transactions which are designed for accepting web transactions from any user along with some information, prior to performing a connection.

A GroupName text expression may be optionally entered, which should be one of the valid group names, such as LU_GROUP_1. If no group name is entered, LU_GROUP_1 is assumed.

3270 LU Names

You may also optionally specify a specific LU name to connect to, which is valid for SNA connections as well as TN3270E (extended) connections which support specific LU requests. By implementing a "side database" of userID's, you can match a user (or use the IP address of the user) to a specific LU name, and specify that LU name as part of this text expression. This supports host security environments where a specific "terminal address" or "TERMID" is associated with specific authority, in addition to the user's access privileges.

AS400 Device Names

To connect using a specific Device Name to an AS400 using TN5250, you specify the device name the same way as specifying an LU name for SNA or TN3270E connections. A Device Name can be used to provide the AS400 with identification of the ScreenSurfer connections in order to attach priority or security attributes.

Host Type *ANY

The host type of *ANY may be defined in your host connection definition, in which case everything about the host must be included in your connect string, along with the group name. What you include depends on the host type you are connecting to. See the TEACTION CONNECT heading, above, for the formats. The meaning of each attribute in the connect string is described in the following table:

Attribute	Description
NULL	Start no host connection, but allocate and initialize a session. This enables full ODBC interaction and access to all defined session variables. Useful for opening a session, reading a user profile from database tables, then using the user profile information to perform a subsequent TEACTION RESTART to connect to the host defined for the user, with the user's profile attributes (such as the user's assigned logical unit name).
SNA	Target host connection uses a native SNA connection through SNA Server
TN3270	Host Connnection uses a TN3270 connection to a 3270 mainframe
TN5250	Host connection uses a TN5250 connection to an AS400
Host	For TN3270 and TN5250 the TCP/IP DNS name or IP Address of the TN3270/TN5250 host
Port	Optional-- for TN3270 or TN5250 hosts, the TelNet port (default 23) -- Required if a DevName or TermID is also to be included (use :23 if you don't usually need a port but want to specify a devname or termid)
LUName	For TN3270, requires a TN3270E connection and enables specific override of the LU name assigned for the connection. For SNA, this is required, and can be the name of an LU Pool, or a specific LU.
DevID	For TN5250, enables the specification of a "Device ID" which is used for security profiles on the AS400
Terminal Characteristics	Optional terminal characteristics, identified with a left and right parenthesis (see following section for format of the terminal characteristics string)

Optional Terminal Characteristics

You can specify per-session characteristics at CONNECT time using the terminal characteristics string. This is specified at the end of the CONNECT target using parenthesis and one or more settings. Settings are separated by the semicolon and optional spaces. For example, the following CONNECT specifies that the terminal type should be IBM-3278-4 (model 4) with 43 rows and 80 columns for the alternate screen size:

<TEACTION CONNECT "LU_GROUP_1(Termtype=IBM-3278-4;ScreenRows=24;ScreenColumns=80;
                                    AltScreenRows=43;AltScreenColumns=80)">

The terminal attributes that are settable in this fashion are as follows:

Setting	Description
TermType	The terminal type, based on the valid list for the TN3270 service you are connecting to (not valid and ignored for direct SNA host connections)-- Valid device-types are: IBM-3278-2 IBM-3278-2-E (24 row x 80 col alternate size) IBM-3278-3 IBM-3278-3-E (32 row x 80 col alternate size) IBM-3278-4 IBM-3278-4-E (43 row x 80 col alternate size) IBM-3278-5 IBM-3278-5-E (27 row x 132 col alternate size) IBM-DYNAMIC (no pre-defined display size)
ScreenRows	Standard number of terminal screen rows for device (default is 24)
ScreenColumns	Standard number of terminal screen columns for device (default is 80)
AltScreenRows	Alternate number of terminal screen rows for device (default is 24)
AltScreenColumns	Alternate number of terminal screen columns for device (default is 80)
BasicTN3270E	If set to YES, if host is TN3270E type, only support the "BASIC" TN3270E functions- which avoids response mode and device information requests.
IgnoreTN3270E	If set to YES, will not attempt TN3270E, which may be incompatible in some environments that employ proprietary or non-standard implementations of TN3270E.

---

TEACTION RECONNECT Re-connect the user to a session

<TEACTION RECONNECT [GroupName[:LUNAME]]>

The TEACTION RECONNECT tag is identical to the TEACTION CONNECT tag described above, with the additional logic added to search the requested group for the current user's IP address; if the address is found, the user is "reconnected" to session which already exists. This is useful for customized logon transactions where you don't want to leave "zombie" sessions on your server by assuring that a new connection request by a user picks-up any lingering sessions that user may already be logged onto.

---

TEACTION RELEASERelease (exit) the user from the currently connection session

<TEACTION RELEASE [KeepOpen]>

This action will disconnect the submitting client from the active session, making that session available for other users.

KeepOpen Attribute

When you include the optional attribute KeepOpen, the host connection will not be dropped as part of disconnecting the browser. This option should only be used in ScreenSurfer environments where either transactions or users are accustomed to connecting to a session already in use.

Generally, the <TEACTION GOTO ScreenID> tag should be used prior to releasing a session, with the target screen a known "starting point" for other connection transactions or users (such as a main menu). Note that in order to utilize the GOTO action, you need to have a PathTo attribute for all involved screens.
 

---

TEACTION RESTART Re-start a new host session

<TEACTION RESTART [GroupName[:LUNAME]]>

The TEACTION RESTART tag is identical to the TEACTION CONNECT tag described above, but will use the existing session ID to perform the connection. This is useful to obtain a new host connection following the use of TEACTION DROPHOST, or when the registry setting "KeepSessionValid" is set to YES. When KeepSessionValid is YES, if the mainframe or AS400 connection/session is dropped by the host (possibly a timeout, which is very common in many environments) the user session is still valid, but the host session doesn't exist anymore. In your SurferScript you can test for this condition using the Screen.HostStatus variable, which will return the current host connection status, which will have the value "stopped" if no host connection is present.

---

TEACTION WAITFOR Wait for a particular screen to be displayed

 <TEACTION WAITFOR SectionName [timeout seconds] [SKIPCODE]>

Where:
 

SectionName (required)	The name of a section defined in this or another template file which has a valid WHEN clause.
Timeout Seconds	An integer literal providing the timeout (in seconds).  This tag will wait up to this number of seconds before continuing.
SKIPCODE	When you include this optional keyword, any code in the section specified for SectionName will not be executed once the section has been displayed.

 
This TEACTION is useful for situations where a brief message is displayed on the screen, and that message causes the emulation to return too quickly to the user...this is usually caused by multiple host writes with the OIA clock turned-off on the first write, and a noticable delay prior to the subsequent writes.

You can also use this at any time, for example following a TEENTER with SKIPSCAN.

TEACTION WAITFOR EXAMPLE
<TESECTION Unwanted WHEN Screen_1_5 IS "Please Wait-- CICS Initializing..."> <TEACTION WAITFOR CICS_WELCOME 10> </TESECTION> <TESECTION CICS_WELCOME WHEN Screen_1_10 is "Welcome to CICS"> <TEPUTSECTION Global.Default> </TESECTION>
The above example will wait up to 10 seconds for the CICS_WELCOME screen whenever the string "Please Wait-- CICS Initializing..." is displayed on Row 1, Column 5.

---

TEACTION GOTO Go to a particular screen in the host session

<TEACTION GOTO {SectionName}>

This action will use the built-in navigational engine to change the active host screen from the current section to the requested one (if a PATH exists).  It can also be used to validate the current screen in transactions which are general in purpose, but which need to be applied against the correct screen.

Note: the SectionName is not an expression; it must be a literal, as the resolution of the screen to "goto" is performed at compile time.

TEACTION GOTO Example
<TESECTION MainMenu WHEN Screen_1_2 is "Menu" PathTo CustBalance is "3[erase eof][enter]"> ... <TESECTION CustBalance WHEN Screen_1_2 is "CustBal" PathTo MainMenu is "[pf3]"> ... <TESECTION SupplierList WHEN Screen_1_2 is "SupLst" PathTo MainMenu is "[pf3]"> ... <TESECTION GetSuppliers When TranpPath_1 is "Supplier" and TranPath_2 is "List"> <TEACTION GETSESSION> <TEACTION GOTO SupplierList> <TEACTION RETURN WITHSCAN>
This example shows three screen-event sections and one transaction (url) event section. Each of the three screen sections have at least one pathto defined. Since CustBalance and SupplierList both can get to menu with PF3, we only code that. The Menu screen can get to either of the other two with simple menu entries. In the GetSuppliers transaction, we can code a GOTO the screen we want; if it is on the right screen already, nothing will happen. If it is on the CustBalance screen, the GOTO will "find" the path through the MENU screen to the SupplierList screen.

---

TEACTION GETSESSION Link to the correct session and validate the current URL SessionKey

<TEACTION GETSESSION [SessionKeyExpression]>

When this action is encountered, the current transaction URL will be checked for the SessionKey value (if it doesn't exist, an error will occur).  The SessionKey value is then used to identify the correct session for the user, as well as authenticating the user against the session.

If the current URL also has the C_POS name-value pair, the C_POS value will be used to update the current screen cursor position.

The optional SessionKey expression may be used to switch from one ScreenSurfer session to another when a user is connected to more than one session. For example, a "master" session for a given user can maintain the SessionKey for another session in a variable so that both host sessions can be accessed from a single SurferScript execution.
 

---

TEACTION RETURN [WITHSCAN] Stop executing template code and return immediately to browser

<TEACTION RETURN>

This simple macro will close and flush the current HTML output stream (or active Cold Fusion or ASP result set if a co-server call is active) and stop execution of template code for the current section.

The optional parameter WITHSCAN will cause ScreenSurfer to activate the screen recognition and execute any <TESECTION SurferScript which is associated with the currently displayed screen. The WITHSCAN attribute is particularly convenient for circumstances where you have been navigating through multiple screens using the <TEENTER ... SKIPSCAN> or <TEENTER ... SKIPCODE> and have reached a point where you do want an associated section to be executed following a scan through the recognition rulebase.
 

---

TEACTION ENDREQUESTReturn immediately to browser or Co-Server but continue processing script.

<TEACTION ENDREQUEST>

This simple action will end the active request (from a browser or co-server), returning control to the caller, but will continue to process the active script.

This is particularly useful when additional screen transitions are desired to "reposition" the active screen to a base screen while not wanting to propogate the additional response time to the caller.
 

---

TEACTION WEBTOSCREEN [ENTER] [WEBEVENT]Copy TEFORM variables created with TEAREA and TEDATA tags ("F_" fields) from web variables to screen

<TEACTION WEBTOSCREEN>

This macro will copy all variables from the current web hit from the web. pool to the active screen. Note that this is all variables of the format F_offset_length, such as "F_10_20" for a field at row 1, column 11 for 20 characters. This is the same action that is performed by the built-in ScreenSurfer URL, "/surfer/emulator" and is intended for use in custom transactions or <TEEVENT WEBINPUT> sections.

The optional parameter ENTER will cause ScreenSurfer to interpret the AID code and send it to the host, without performing screen recognition or template execution.

The optional parameter WEBEVENT will cause ScreenSurfer to execute any section defined as a web event for the currently active screen template.


---

TEACTION WEBTOSCREENMAP Copy all automatic web entry fields to the current screenmap

<TEACTION WEBTOSCREENMAP ScreenMapName>

This macro will copy all variables from the current web hit from the web. pool to the specified screenmap. Note that the web. variables have to be the same name as the screenmap field names to use this tag. This tag eliminates the need to code one to many <TESET> tags to set the screenmap fields to the web. values.


---

TEREADYWHEN Prime the next screen transition to assure host timing errors or inconsistent buffer writes don't cause a problem

Syntax: 

<TEREADYWHEN
 {[type=]
  {IgnoreEmptyWrites |
   UseEmptyWrites |
   StrictRecognition |
   StrictBufferCount |
   Timing |
   Recognition |
   RecognitionNoEmpty}}
  [name when screen_row_col is "text" [[and/or] screen_row_col is...]
   name2 when screen_row_col is "text" [[and/or] screen_row_col is...]
   ...]
  [hostwritesexpected=number]
  [settletime=milliseconds]
  [timeout=milliseconds]>

Where:
 

Type (required)	Is a text expression representing the option desired (described below)
Name WHEN (StrictRecognition)	A Screen recognition ID and criteria as with the Screen event Section. You may specify more than one screen id, so that the next screen transition can result in more than one potential screen (potential errors).
HostWritesExpected (StrictBufferCount)	Use this attribute for the StrictBufferCount type-- using this is equivilent to setting the Screen.HostWritesExpected variable to the same value.
Timeout	Overrides the default timeout set for this session for the next transition. This attribute may be set for any type, but if it is the only thing you want to change for the next transition, use the type=timing. Default is 20000.
SettleTime	Overrides the default SettleTime set for this session for the next transition. This attribute may be set for any type, but if it is the only thing you want to change for the next transition, use the type=timing. SettleTime is the number of milliseconds that the host needs to be "silent" before a transition is assumed...default is 100.


The TEREADYWHEN provides rich control over the next screen transition. This allows support for managing odd buffer writes from the host, typically needed when switching from one application system to another, logging on, accessing help systems and so on.

The setting created by the TEREADYWHEN will only exist for one screen transition, then revert to the default value set by the Screen.DefaultReadyState variable.

A key advantage of using TEREADYWHEN is that you only need to know the screen before the transition, then not worry about "cleaning-up" after the screen transition occurs.

TEREADYWHEN Example
<TESECTION LOGON WHEN Screen_1_20 is "Logon"> <TEREADYWHEN StrictRecognition Mainmenu when Screen_1_2 is "Menu" PassError when Screen_20_5 is "Incorrect Password" NewPass when Screen_20_5 is "Password expired"> <TEPUTSECTION Global.default> </TESECTION>
This example shows how a logon screen can be recognized and the next screen transition "hard wired" to only complete when one of the three possible text combinations occur. The reason for the need to use TEREADYWHEN is that if the logon is successful, three status screens "flash" in the real system while the connection is made from the user to the right application system. If we don't create a "StrictRecognition" transition, the next HTML page will be one of the status screens that "flash" in the real environment rather than the one we want (Menu). Meanwhile, in case the logon screen has some error message, we code for it so that the transition will complete on that circumstance also.

---

TEFIND Search the current Host Session Screen for a Text Expression

Syntax: 

<TEFIND {[text=]"FindExpression"}
        {[VarRoot=]varRoot}
        [[StartRow=]StartRowExp]
        [[EndRow=]EndRowExp]
        [[timeout=]timeoutExpression]>

Where:
 

Text (required)	Is a text expression representing the text to be searched for
VarRoot (required)	The variable "root", which will provide source generation for three variables populated by this tag-- the VarRoot.Offset, VarRoot.Row and VarRoot.Column (see comments).
StartRow (optional)  default=1	Integer expression representing the starting row for the search (the search includes this row).
EndRow (optional)  default=24	Integer expression representing the ending row for the search (the search includes this row).  Endrow must be greater-than or equal to StartRow.  When EndRow is equal to StartRow, the search will be performed on the single row.
Timeout (optional)	An integer expression representing the number of milliseconds that the template execution will wait for the text to be found.  This is intended to be used in conjunction with a <TEACTION ENTER "Keystring" SKIPSCAN>, enabling the template logic to check the next screen in circumstances where the next screen may take some time to appear or involve multiple write events from the host applications.

 
The TEFIND tag will search the current host screen session for the FindExpression, and will update three variables with the find results.  The name of the updated variables are based on the VarRoot parameter, as the text entered for VarRoot forms the basis of the updated variables.  For example, a VarRoot of "Found" will update the variables "Found.Offset", "Found.Row" and "Found.Column".  Each of these automatically generated variables are integer types.

Note-- VarRoot may be re-used in additional TEFIND tags.  For example, the "Found" VarRoot can be specified in all <TEFIND> tags, and will be updated each time a TEFIND is executed.  Using the same name where logic permits will conserve session-allocated memory by avoiding the definition of redundant variables.  Meanwhile, you may use unique VarRoot names where more than one TEFIND may be active or relevant in your logic.

When the text expression entered as the first parameter (FindExpression) is not found, the values of all the result variables will be -1 (negative one).

The optional parameter timeoutExpression may be used to have the TEFIND tag wait for the FindExpression for a given amount of time.  The value for TimeoutExpression is in MILLISECONDS, meaning that a second is equal to 1000.  So, for a timeout (wait) of ten seconds, the value for timeoutExpression would be "10000".  A timeout of one half second would be 500.

---

TEENTER Input the specified keys, including an AID key (such as Enter) to enter the screen along with identifing the FROM and TO screen in a screen transition

Syntax: 

<TEENTER [[Keys=]"Keys"]
         [FromScreen="ScreenID"]
         [ToScreen="ScreenID"]
         [Scan="YES|no"]
         [Code="NO|yes"]
         [Strict="low|medium|HIGH"]
         [TimeOut=milliseconds]>

Where:
 

Keys (optional)	The aid key to submit to the host.
FromScreen (optional)	The name of the screen recognition section for the "From" screen. If the screen recognition section is called VSRecog, then you can just use the template name.
ToScreen (optional)	The name of the screen recognition section for the "To" screen. If the screen recognition section is called VSRecog, then you can just use the template name.
Scan (optional)  default=YES	Whether to scan the ScreenSurfer Screen Recognition RuleBase to see if a screen recognition section was coded for the "To" screen. If a screen recognition section was coded, the Screen.ScreenID variable will have the template.section name of the screen recognition; otherwise, the Screen.ScreenID will contain the value "global.default".
Code (optional)  default=NO	Whether to execute the screen recognition section of code (or the default section of the global template for host screens with no screen recognition sections) for a detected host screen. Value of NO indicates to SKIP THE CODE in the screen recognition section for that host screen. The value will be "NO" when using ScreenSurfer's co-server support and if you want to "hide" a host screen using ScreenSurfer's "screen-to-HTML" support.
Strict (optional)  default=HIGH	This parameter dictates how "strict" you want to be on the subsequent screen transition. LOW states that you don't care what the next host screen is; all you are concerned about is that any valid screen transition occurred (not recommended). MEDIUM states that the next host screen must be one of the valid "To" screens defined for the "From" screen via the Identify and Navigate Wizard executed from the Visual Surfer tool in the DevCenter. HIGH states that the "To" screen after the screen transition must only be the "To" screen.
TimeOut (optional)  default=20000 (from ScreenTimeout Registry Entry)	An integer expression representing the number of milliseconds that the template execution will wait for the next screen transition. This value overrides the default timeout set for this session for the next transition.

 
The TEENTER tag basically combines the functionality of the <TEACTION ENTER> tag and the <TEREADYWHEN StrictRecognition> tag into one tag...AND MORE! The TEENTER tag in its simplest form can only submit an aid key to the host as the following:

<TEENTER "[enter]"> which is the same as coding <TEACTION ENTER "[enter]">

Or, the TEENTER tag can use the screen transition declaration defined in a <TEDECLARE SCREENCHANGE> tag to navigate "From" a host screen "To" another host screen similar to the following:

<TEENTER FromScreen="menu" ToScreen="addemp">

In this case, the TEENTER uses a TEDECLARE SCREENCHANGE definition that defines any inputs to make this transition occur and the valid aid key to make the transition. Also, since the Strict parameter is defaulted to HIGH the screen transition will only occur if the next screen is actuall the "addemp" screen.

TEENTER FromScreen ToScreen
<TEDeclare ScreenChange FromScreen="menu.VSRecog" ToScreen="addemp.VSRecog" TestKeys="[put](f_1694_2,'1')[Enter]" EnterKeys="[put](F_1694_2,'1')[Enter]" NavPath="YES"> <TEEnter FromScreen="menu.VSRecog" ToScreen="addemp.VSRecog"> <!-- TEENTER #1 --> <TEEnter FromScreen="menu" ToScreen="addemp"> <!-- TEENTER #2 -->
This example shows how to use the TEENTER tag to navigate "From" one host screen "To" another. The first TEENTER is the long form in specifying the "From" and "To" screens by qualifying on the screen recognition section VSRecog. If the screen recognition section is called VSRecog then you can simply code the second TEENTER and not include the .VSRecog. If you use the Identify and Navigate Wizard via the Visual Surfer link in the DevCenter, then all screen recognition sections are named VSRecog.

<TEENTER ToScreen="addemp">

In this case, the TEENTER works like the TEACTION GOTO since ScreenSurfer knows the "path" to get to the requested "ToScreen" based on going through the "ID and Navigate Wizard" in V3. Again, one of the outputs of the "ID and Navigate wizard" is a <ScreenChange> declaration identifying the AID keys to get from screen to screen.

TEENTER ToScreen
<TEDeclare ScreenChange FromScreen="menu.VSRecog" ToScreen="addemp.VSRecog" TestKeys="[put](f_1694_2,'1')[Enter]" EnterKeys="[put](F_1694_2,'1')[Enter]" NavPath="YES"> <TEEnter ToScreen="addemp">
This example shows how to use the TEENTER tag similar to a <TEACTION GOTO> to "goto" the "ToScreen". The user is sitting on the "menu" screen and since the "EnterKeys" are defined via the <ScreenChange> declaration, ScreenSurfer knows how to get to the "addemp" screen.