Lesson 8. Cold Fusion and ASP Co-Servers Lesson 7. Logic and control
 Click on any item to view...
Contents

+Introduction
+Concepts
+Product Positioning
+Operations
+Customization
+SurferScript Guide
ScreenSurfer Tutorial

The ScreenSurfer Tutorial Introduction

Visual Surfer Introduction

Lesson 1. The ScreenSurfer Environment

Lesson 2. 3270/5250 Display Characteristics

Lesson 3. SurferScript Screens and Events

Lesson 4. Basic Customization

Lesson 5. Key ScreenSurfer HTML Tags

Lesson 6. Variables and Expressions

Lesson 7. Logic and control

Lesson 8. Cold Fusion and ASP Co-Servers


This lesson introduces you to servicing requests from ColdFusion and ASP Co-Servers with ScreenSurfer. The skills presented include:

Review Skills

Since you may have skipped directly to this tutorial section without covering any of the prior sections, please be sure to read the following prior to following this material:

Co-Server Design Options

As the first seven lessons in this tutorial demonstrate, ScreenSurfer has many features oriented to delivering HTML-based protocol conversion for 3270 and 5250 datastreams. This section describes the additional features designed to provide middleware functionality to ColdFusion and ASP application servers, or co-servers.

How ScreenSurfer works with these two co-servers is as a server in a "remote procedure call" environment. The client, or co-server makes a specific request to ScreenSurfer, passing input parameters; ScreenSurfer then acts on the input parameters and provides an answer. The "answer" supports complex responses; it can include multiple recordsets, each with one or more rows containing one or more named columns/fields (even the most simple business object, such as an invoice requires supporting complexity in the returned data).

In ColdFusion, the act of making a call to ScreenSurfer is achieved using the CFX_Surfer tag, with the Transaction="tranID" identifying the SurferScript that is executed (see Defining transactions to be called by a co-server). In an ASP page, the call is made to ScreenSurfer when the SSurfer.AspRequest object's Execute("TranID") method is called. How each of these environments defines input and processes output is defined in the corresponding environment's documentation (installed with the component, and also available in the ScreenSurfer documentation under "Advanced Scripting").

Modes of Operation

There is a lot of flexibility built into the Web; there is also a lot of flexibility built into delivering applications with ScreenSurfer and a Co-Server!

The important design point to understand about ScreenSurfer's capability when teamed with either ColdFusion or ASP is that at any time you can exploit ScreenSurfers screen-to-html protocol conversion to make your development job faster and easier. This is either at the whole-page level described in the previous paragraph, or on the same page using the <TERESULT HTML> tag to identify a ScreenSurfer-generated HTML block, returned as a named text field to the co-server.

All pages and HTML from Co-Server

This is the simplest mode in a Co-Server environment; all of the HTML that is sent to the user is sent based on HTTP hits to the Co-Server's Web Server, and all HTML is generated by the Co-Server application. ScreenSurfer is given structured data (named fields) as input in calls, and returns structured data (as one or more recordsets) that are then incorporated into user HTML pages by the co-server logic. 		Co-Server generates all HTML

All pages from Co-Server; Some ScreenSurfer HTML

This is a simple variant of the simple mode, where all pages are still delivered by the co-server, but now ScreenSurfer's ability to generate screen areas as HTML is exploited. In the diagram, this is represented as the dark-green dataflow. The advantage of this mode of operation is that when a screen that is involved in the application is already formatted in a readable manner, you don't need to "re-invent the wheel" by converting all pertinent data to structured fields, passing them to the co-server only to have those fields reconstructed in a web page that looks remarkably similar to the original screen! 		ScreenSurfer Generates some HTML

Full mix of pages

This mode utilizes both pass-through ScreenSurfer screen-to-HTML emulation alongside co-server page delivery, in a mixed-mode environment. In a mixed-mode environment, your primary server (CF or ASP-based) delivers some Web pages, while ScreenSurfer delivers others. You can accomplish this using frames at the client's browser (to integrate between a Co-server delivered page and a ScreenSurfer delivered page) or links/cookies. See Maintaining a relationship between a co-server session and a ScreenSurfer session. 		Fully mixed mode

ScreenSurfer/Co-Server Design Options Summary: ScreenSurfer and Co-Server HTML Page Delivery Options:
  1. Pure co-server mode: all pages delivered by co-server; ScreenSurfer providing purely middleware capability (handling procedure calls and returning field-formatted data).
  2. Mixed page mode: all pages delivered by co-server; ScreenSurfer providing certain screen sections pre-formatted as HTML as part of one or more procedure call results.
  3. Mixed server mode: Some pages delivered by the co-server, some pages delivered by ScreenSurfer, with SessionKey providing common link beween the two. Note that option 3 can also be seen as an extension of option 2, involving mixed pages as well as mixed servers.

Defining Co-Server Transactions

As described in the previous section, co-server applications make procedure call requests to ScreenSurfer, passing input and accepting output in return. As with Transaction URL's defined for HTML clients, Co-Server transactions are executed in your SurferScript where there is a matching <TESECTION Tag>. As with the transaction URL, the co-server transaction is defined in the TESECTION using the WHEN TRANPATH_1 is "tranid". You can include additional clauses to describe multi-part transaction ID's, using TRANPATH_2 and so on.

Defining Transactions Exercise: Define and execute a transaction This simple exercise will lead you through defining a simple transaction that can be called by a co-server.
  1. Create a new SurferScript file named rpc.stml
  2. Line 1: <TESECTION Hello WHEN Tranpath_1 is "Hello">
  3. Line 2:  <TERESULT HTML Name="MyData">
  4. Line 3:  Hello World
  5. Line 4:  </TERESULT>
  6. Line 5: </TESECTION>
The above transaction is now ready to be called. This transaction processes no input, and returns a single field in the base recordset named "MyData". This uses an HTML result type, rather than a ROW or TABLE result type in the TERESULT tag. This avoids needing to start (TEACTION CONNECT) to a session, which is required for ROW and TABLE result types.

In ColdFusion, in a .CFML page, you could exercise the above transaction using the following CFML: 


<CFX_SURFER NAME="MyCall" Transaction="Hello"> 
<CFOUTPUT QUERY="MyCall">
  <b>#MyData#</b>
</CFOUTPUT>
In a .ASP page, you could exercise the above with the following: 

<% SS = Server.CreateObject("SSurfer.AspRequest") %>
<% SS.Execute("Hello") %>
<b><%=SS.Field("MyData") %></b>

The ScreenSurfer/Co-Server DataFlow

An interesting aspect of Co-Server transaction calls is that the HTTP protocol is used as the connection mechanism between the two processes. Since HTTP is built on top of standard sockets, this makes it easy to locate the servers on different machines anywhere on an Intranet or the Internet. The input from the co-server to ScreenSurfer is formatted as a standard HTTP request, with all input parameters from the co-server passed in the body of the request. The returned data is passed-back in HTTP contents using a special structured data implementation that works in a similar fashion to XML.
Understanding Co-Server Dataflow
ASP to ScreenSurfer Dataflow

ASP Server ScreenSurfer Host
SSurfer.ASPRequest Object created
Input data is loaded into the object using the AddInput() method
Execute() Method is called using transaction name
Request is received, and TESECTION with WHEN Tranpath criteria matching Execute transaction name is executed.
All input values from ASP are accessible using the Web. variables and WebText() function
SurferScript starts (TEACTION CONNECT) or re-acquires (TEACTION GETSESSION) a host session
Host screens are displayed and navigated from SurferScript
Screen data is read using the Screen() function and TERESULT tags are used to return structured data and HTML to ASP
The Field(), GetNextRecord() and EOF methods and property are used to read the returned data and incorporate it in pages returned to the browser.

\ColdFusion to ScreenSurfer Dataflow
Understanding Co-Server Dataflow
ColdFusion to ScreenSurfer Dataflow

CF Server ScreenSurfer Host
CFX_Surfer CFX Tag executed with Transaction property set and any other input values set as tag attributes
Request is received, and TESECTION with WHEN Tranpath criteria matching Execute transaction name is executed.
All input values from the CFX_Surfer tag are accessible using the Web. variables and WebText() function
SurferScript starts (TEACTION CONNECT) or re-acquires (TEACTION GETSESSION) a host session
Host screens are displayed and navigated from SurferScript
Screen data is read using the Screen() function and TERESULT tags are used to return structured data and HTML to ColdFusion
The CF_OUTPUT tag and variable names are used to read the returned data and incorporate it in pages returned to the browser.

Processing Co-Server Input

While the mechanism for passing input to ScreenSurfer is different for each Co-Server, how you process the input in ScreenSurfer is the same.

There are primarily two mechanisms for processing the input. They are the Web. variables and the WebText() function.

For simple requests, which involve single data values, such as "Customer Number" or "Item Number," you will find that referencing the passed value using the Web. variable prefix as the most straight-forward and simplest mechanism. As with requests originating in an HTML browser, co-server requests that pass input name that input and by prefixing a values name with the string "web." that value is accessible in any ScreenSurfer expression.

For more complex requests, such as those involving multiple rows of data (such as a complete order with multiple line items), the WebText() function is critical.

The WebText() function allows you as the developer to construct the name of the variable you are referencing as a string. For example, while processing multiple rows of input data, you can iterate in a loop and concatenate the loop integer variable with field names to reference a specific row's field value.
Processing Multiple rows of data Processing Multiple Rows of Input Data

Here is sample code which will accept up to eight lines of order items. Each line has been passed by the co-server with the name of each field appended with the line number. Assume for the purpose of the sample that the screen which accepts line items is displayed and can accept up to eight lines of item details.
Plugging Order Lines into the Screen 
<!-- First plug-in the single values for the customer placing
        the order -->
<TEACTION PUTFIELD 3 10 Web.CustNumber>
<TEACTION PUTFIELD 4 10 Web.CustShipToID>
<TEACTION PUTFIELD 6 10 Web.CustShipToPhoneNumber>
<TEACTION PUTFIELD 7 2 Web.SpecialInstructions>
<!-- We are passed the number of items in the value named "NumItems":
        for each item, there is a ItemNum, ItemQty and ItemPrice field.
        Each row appends the number of the line item to the field name
        in order to give a unique value...
        First line item starts at row 10.-->
<TELOOP Name="LineItem" First=1 Last=Web.NumItems>
  <TEACTION PUTFIELD LineItem+9 2 WebText("ItemNum"+LineItem)>  
  <TEACTION PUTFIELD LineItem+9 25 WebText("ItemQty"+LineItem)>  
  <TEACTION PUTFIELD LineItem+9 40 WebText("ItemPrice"+LineItem)>  
</TELOOP>
The above demonstrates how both single field values and multiple field values are passed and processed with ScreenSurfer. For each co-server, the techniques for naming the input fields is different.

Sending back a simple set of fields in the base recordset

When ScreenSurfer returns data to a co-server, it is sent in two levels of simplicity. The simplest level is the base recordset which is a single row of one or more named fields. The base recordset is always selected by default at the beginning of a request. Any TERESULT ROW or TERESULT HTML performed from the beginning of a request go into the base recordset.

Accessing the base recordset from each co-server environment is documented in the respective documentation for that co-server. In general, the base recordset is the default environment for accessing returned data from ScreenSurfer.

The following example shows a simple transaction which accesses a specific transaction and returns details to the calling co-server. The transaction is an inventory quantity on hand with pricing information. The input includes the ItemNumber field, which is the item identification. Output includes ItemDescription, ItemQtyOnHand and ItemPrice.
Returning fields in Base Recordset Returning Fields in the Base Recordset

The following sample assumes that the calling co-server session contains the active ScreenSurfer SessionKey, which is the connection between any client (whether a browser or co-server) and an active ScreenSurfer host screen session.
Returning Simple Fields in the Base Recordset 
<!-- All structured field data is returned as part of 
        a declared ROW, defined using TEDECLARE ROW -->
<TEDECLARE ROW Name="Item"
    ItemDescription Text 70,
    ItemQtyOnHand Integer,
    ItemPrice float>
<TESECTION ItemInfo
    WHEN TRANPATH_1 is "ItemOnHand">
<!-- First we connect to the active session using
        TEACTION GETSESSION-->
<TEACTION GETSESSION>
<!-- The host session we use provides a "fastpath" to access
        any transaction.  This involves the CLEAR key followed by
        the entry of the transaction code.  The SKIPSCAN or the
        SKIPCODE attribute is used in TEACTION ENTER to avoid
        any Screen Sections from executing during the ENTER.-->
<TEACTION ENTER "[clear]" SKIPSCAN>
<!-- Now enter the transaction for item inquiry -->
<TEACTION ENTER "ITOH[enter]" SKIPSCAN>
<!-- Item number to query is entered at row 4 column 20 -->
<TEACTION PUTFIELD 4 20 web.ItemNumber>
<TEACTION ENTER "[enter]" SKIPSCAN>
<!-- The result screen includes the answers on rows 5,7 and 9 -->
<TESET Item.ItemDescription=TextTrim(Screen(5,10,70))>
<TESET Item.QtyOnHand=TextTrim(Screen(7,30,15))>
<TESET Item.ItemPrice=TextTrim(Screen(9,30,15))>
<!-- Now return the row "Item" as a part of the base recordset -->
<TERESULT ROW Item>
<!-- All done for this request -->
</TESECTION>
Any TERESULT will "push" data to the calling co-server request. The TERESULT ROW will push the active contents of the named row to the caller. In this case, since the TERESULT ROW is not inside a TERESULT TABLE block, the TERESULT ROW belongs to the base (simple) recordset.

Sending back multiple records as a multi-row recordset

To support more complex requests, ScreenSurfer provides the ability to "bracket" rows of data with the TERESULT TABLE tag, which defines any matching TERESULT ROW tags as being part of a multi-row recordset (or "table"). Since a request may not include a single row or a single recordset, you can return any number of recordsets you wish, with each containing one or more rows of data.

Remember that as described in the previous section, any returned data that is not part of a table belongs to the base recordset. If you want to return data that "belongs" to a specific, named recordset, you always use the <TERESULT TABLE> to identify the recordset (even if the recordset consists of a single row, the TERESULT TABLE is necessary to identify the row as belonging to a unique, named recordset instead of the base recordset, which is unnamed).

The following example returns ship-to codes, addresses and contact information for a given customer. There are up to eight ship-to addresses on each screen; if there are more addresses, the text PF8=MORE text appears at row 24, column 60. The same transaction system as the item on hand inquiry is used, with the assumption that sessionkey is active.
Returning multiple rows in a recordset Returning fields in multiple recordsets with multiple rows

The following sample assumes that the calling co-server session contains the active ScreenSurfer SessionKey, which is the connection between any client (whether a browser or co-server) and an active ScreenSurfer host screen session.
Returning multiple recordsets, with multiple rows 
<!-- All structured field data is returned as part of 
        a declared ROW, defined using TEDECLARE ROW -->
<TEDECLARE ROW Name="Cust"
    CustName Text 30,
    NumShipToCodes Integer>

<TEDECLARE ROW Name="ShipTo"
    Code Text 10,
    Location Text 60,
    ContactName Text 40,
    ContactTelNo Text 20>
<TESECTION ShipToInfo
    WHEN TRANPATH_1 is "ShipToInfo">
<!-- First we connect to the active session using
        TEACTION GETSESSION-->
<TEACTION GETSESSION>
<!-- The host session we use provides a "fastpath" to access
        any transaction.  This involves the CLEAR key followed by
        the entry of the transaction code.  The SKIPSCAN or the
        SKIPCODE attribute is used in TEACTION ENTER to avoid
        any Screen Sections from executing during the ENTER.-->
<TEACTION ENTER "[clear]" SKIPSCAN>
<!-- Now enter the transaction for item inquiry -->
<TEACTION ENTER "CSST[enter]" SKIPSCAN>
<!-- Item number to query is entered at row 4 column 20 -->
<TEACTION PUTFIELD 4 20 web.CustNumber>
<TEACTION ENTER "[enter]" SKIPSCAN>
<!-- The result screen includes the customer details at
        the top, and then two rows per ship-to on rows 6 to 22 -->
<TESET Cust.CustName=TextTrim(Screen(3,10,30))>
<TESET Cust.NumShipToCodes=TextTrim(Screen(4,30,4))>
<!-- Send the simple stuff as part of the base recordset -->
<TERESULT ROW Name="Cust">
<!-- We will now go into a loop, up to 10 screens worth of 
        ship-to details...but first we start the ship to 
        recordset with a TERESULT TABLE -->
<TERESULT TABLE Name="ShipTo">
<TELOOP Name="ScreenCount" First=1 Last=20>
 <TELOOP Name="Row" First=6 Last=20 Step=2>
   <!-- On a blank line, we're all done... -->
   <TEIF Screen(Row,2,3)=="   ">
    <TEBREAK>
   </TEIF>
   <TESET ShipTo.Code=TextTrim(Screen(Row,2,10))>
   <TESET ShipTo.Location=TextTrim(Screen(Row,13,60))>
   <TESET ShipTo.ContactName=TextTrim(Screen(Row+1,3,40))>
   <TESET ShipTo.ContactTelNo=TextTrim(Screen(Row+1,50,20))>
   <!-- Now send this shipto record out -->
   <TERESULT ROW Name=ShipTo">
 </TELOOP>
 <TEIF Screen(24,60,8) != "PF8=MORE">
  <TEBREAK>
 </TEIF>
 <TEACTION ENTER "[pf8]" SKIPSCAN>
</TELOOP>
<!-- All done for this request -->
</TESECTION>
ScreenSurfer will complete all open TERESULT actions at the end of the transaction, as well as sending status information that is part of the base recordset.

Maintaining a relationship between a co-server session and a ScreenSurfer session

When a connection is made in a co-server transaction using the TEACTION CONNECT tag, a screen session is allocated and reserved at the time of the TEACTION CONNECT. There is a special text string associated with that screen session, called the SessionKey. The SessionKey may be included in outgoing HTML using the <TEMACRO SESSIONKEY> tag, or using the internal reserved variable Screen.SessionKey in a <TESHOW Screen.SessionKey> tag.

For a Co-Server transaction, embedding the sessionkey in HTML is not necessary, however, as each call to ScreenSurfer will return the SessionKey if the session is still reserved for the caller at the end of the transaction. The SessionKey is included as a named variable ("SessionKey") in the Status Query for ColdFusion and the Status RecordSet for Active Server Pages.

Storing the SessionKey in a Co-server Session Variable

Each of the supported co-servers include techniques whereby a developer can maintain state variables for a user in a "Session" object. By copying the SessionKey returned by a call to ScreenSurfer into a corresponding Session variable, a co-server application can maintain a connection between an active ScreenSurfer screen session and a co-server user session.

Using URL Cookies

The most dependable method of maintaining a connection with a ScreenSurfer session is in URL cookies; this is the oldest of state management techniques for the web, where the state identification variable is included in each anchor HREF or form ACTION in a name value pair. By always assuring that each interaction between the browser and the co-server application includes a sessionkey for a corresponding ScreenSurfer session, that session will always be identified regardless of the level of the user's browser and that user's enablement of JavaScript.

Using JavaScript and Frames

JavaScript and frames provide a very simple approach to maintaining state with a ScreenSurfer session, with the simple assumption that a user will be employing a browser which has both frames and JavaScript support.

In this approach, at session establishment (logon), a frameset is returned to the browser which includes some top-level JavaScript. Included in the JavaScript is a simple variable setting which includes the active ScreenSurfer sessionkey.
Maintaining a ScreenSurfer Session Relationship Maintaining a ScreenSurfer Session Relationship

The following sample demonstrates how an ASP page opens a connection with ScreenSurfer and saves the ScreenSurfer sessionkey in a client-side Javascript variable.
Sticking the SessionKey in a Client-Side JavaScript variable 
<!-- This page is called from a logon form with a userid and password.
        This is passed to ScreenSurfer to connect to a session, enter
        the userID and password and return to ASP with a sessionkey if
        the userid and password is valid. -->
<!-- Create an instance of the ActiveX ASP component -->
<% SS = Server.CreateObject("SSurfer.AspRequest") %>

<!-- Set the "UserID" and "Password" input attributes using
     data passed in the current URL -->
<% SS.AddInput("userid", Request.UserID) %>
<% SS.AddInput("password", Request.Password) %>

<!-- Call the LOGON transaction -->
<% SS.Execute("logon") %>

<!-- The SS object now contains the SessionKey in the
        Status recordset -->
<html>
<head>
<title>Toy Incorporated ExtraNet
<script language="Javascript">
var SessionKey=<%=SS.Field("status.sessionkey")>;
// the DoPassThrough function can be called at any time to display the
// current ScreenSurfer session in the main frame
function DoPassThrough()
{
   top.Main.location="http://myss:82/surfer/refresh/"+
                        top.SessionKey+"/"+Math.random()
}
</script>
</head>
<FRAMESET ROWS="100%" COLS="200,*">
  <FRAME NAME="Nav" SRC="Mainmenu.asp">
  <FRAME NAME="Main" SRC="Started.asp" SCROLLING="AUTO">
</FRAMESET>
</HTML>
In any displayed page, the link <a href="javascript:top.DoPassThrough()">Passthrough</a> will display the active ScreenSurfer session in the frame named "main". Note that this assumes that ScreenSurfer is running on a machine named "myss" and listening on port 82.

Lesson 7. Logic and control