Co-Server Support
Page Links Transactions, Screen Navigation, Session Management, Co-Server Tags, TEDECLARE ROW, TEDECLARE RPC, TERESULT, TERESULT TABLE, TERESULT ROW, TERESULT HTML, TERESULT XMLDOC, TERESULT XMLPUSH, TERESULT XMLPOP, TERESULT JAVASCRIPT,
Examples Screen Navigation, TEDECLARE ROW, TERESULT ROW/TABLE, TERESULT HTML, TEDECLARE RPC
Many ScreenSurfer installations benefit from integrating their ScreenSurfer server with other Web application servers within the enterprise. Currently, ScreenSurfer supports Cold Fusion from Allaire, ASP (Active Server Pages) from Microsoft, EJB (Enterprise Java Beans) - SUN J2EE specification and XML-over-HTTP. The current installation program for ScreenSurfer components for these products may be downloaded from the "Releases" section of the The ScreenSurfer SupportCenter.

SurferScript integrates with Cold Fusion, ASP, XML and EJB Co-Servers with three key SurferScript tags: the <TESECTION> tag, the <TEDECLARE ROW> tag and the <TERESULT> tag. An additional tag is useful for documentation and development with the DevCenter, which is the <TEDECLARE RPC> tag.

Understanding the Co-Server Environment

The best description of the Co-Server environment is in Tutorial Lesson 8; if you haven't read this lesson yet please do so now!

Visual Surfer and Co-Servers

This documentation page provides detailed descriptions of direct scripting for Co-Server support. If you are looking for rapid implementation of Co-server transactions, you should first utilize the high-level facilities in Visual Surfer.

To implement Co-Server transactions in Visual Surfer:

  1. Use the Identify and Navigate Wizard for each screen involved in your transaction set.
  2. For any screen which you will be reading or writing formatted data, use the Screen Object Wizard to define the field locations and names.
  3. Define the actual transactions using the Visual Logic Editor-- the standard Transaction Module Component will provide a means of defining the logic of your co-server transaction.

Should the high-level facilities of the Visual Surfer environment not provide enough flexibility, it is recommended that you rename the PML module that acts as your Transaction definition, and then edit the STML file generated by the PML module-- in this manner, you can exploit the code-generation capabilities of Visual Surfer while not being limited by it.

If you find that you need to extend the scripts generated by Visual Surfer...read on!

Key Co-Server Tags

Transactions: Parameters IN, Data OUT

Designing your Co-Server application consists of identifying what requests you will support, and for each request, the input parameters required and the results to be returned.

Input Parameters are passed by the co-server components as either CFX tag attributes (Cold Fusion) or using SSurfer.ASPRequest AddInput() method calls (ASP), or EJB's addInput() method calls. In SurferScript, all input parameters may be queried and utilized as web.name variables. A web. variable is a readonly variable that accesses all input for the current request (like a combination of the QUERY / FORM / CONTENTS containers in other web development environments).

Results are returned to the co-server component using one or more TERESULT tags. To return structured, named data fields, a row of data is defined using TEDECLARE ROW. Individual fields in the row are set using TESET, and a completed row (all fields set) is returned using TERESULT ROW. Using a TERESULT ROW by itself will return a single-row query (CF) or RECORDSET (ASP/EJB) to the co-server component.

To return a table of more than one row (QUERY for Cold Fusion, RECORDSET for ASP/EJB), you open the table first using TERESULT TABLE, specifying the ROW that you will be filling the table with (the row being one that was declared using TEDECLARE ROW). Then, as with the return of single-row results, you set each row field using TESET, and when the row is ready, send it as part of the active resultset using TERESULT ROW. A typical situation where a table would be returned is a screen with multiple rows; each containing fields for a unique entity. For this situation, you can use a TERESULT TABLE, then a TELOOP containing a number of TESET tags to copy from the current row to the defined result row and a TERESULT ROW to return the individual row to the co-server component.

To pass-through ScreenSurfer generated HTML (an entire screen for example), you use the TERESULT HTML which will "open" a named attribute for the co-server component where all subsequent HTML SurferScript will be written. To pass-through this HTML in the individual component, the attribute is displayed in the current page like any other variable (it will be a BIG text attribute!).

Note that due to limitations in the access to HTTP variables in a CFX tag, full passthrough is presently only supported for ASP co-server environments. In a Cold Fusion environment, this means that when you pass-through ScreenSurfer HTML that includes data entry forms, you will need to "hand-code" the transfer of all ScreenSurfer form entries on through to the CFX tag. In the ASP environment, the ScreenSurfer component has access to all HTTP variables, and "grabs" the ScreenSurfer values with a single method call.

Screen Navigation

Screen navigation for managing requests is best implemented using the TEREADYWHEN tag combined with the TEACTION ENTER tag.

The TEREADYWHEN Strictrecognition tag enables you to "prime" the next screen transition, so that in the procedural environment of navigating through multiple logon and application screens there is full synchronization between ScreenSurfer and the host. The TEREADYWHEN tag is optional, and is usually only required during logon sequences or top-level application system selection menus. Once in an application environment, such as CICS, you will only need the TEACTION ENTER to navigate from one screen to another, as the screen transitions are very reliable.

The TEACTION ENTER tag is used to directly control navigation from one screen to the next. Remember to use the SkipCode attribute when using TEACTION ENTER, to prevent ScreenSurfer from executing the script connected to Global.Default or a screen you have identified in a TESECTION.

Complete Transaction and Navigation Example 
<TEDECLARE ROW ItemInfo
    ReturnCode Integer,
    ReturnMessage Text 30,
    QtyOnHand Integer,
    QtyOnOrder Ingeger>
<TESECTION OnHand
    WHEN Tranpath_1 is "inventory"
     AND Tranpagh_2 is "onhand">
<!--We don't pass-through any HTML or screens, so suppress
    all outbound text not delivered in a TERESULT -->
<TENOTEXT> 
<TEACTION CONNECT "LU_GROUP_1"> <!-- Connect to host-->
<TEREADYWHEN StrictRecognition
   GoodLogon when screen_1_5 is "Main Menu"
    Badlogon when screen_20_60 is "Invalid Password">
<TEACTION ENTER web.Userid+"[tab]"+web.password+"[enter]" skipcode>
<!-- See if we logged on okay -->
<TEIF Task.ReadyID=="Badlogon">
  <!-- need better password...return-->
  <TESET ItemInfo.ReturnCode=-1>
  <TESET ItemInfo.ReturnMessage="Bad Password>
  <!-- ItemInfo goes back in base recordset -->
  <TERESULT ROW ItemInfo>
  <TEACTION RELEASE>
  <TEACTION RETURN>
</TEIF>

<!-- Next we select menu option 5 for item on hand inquiry-->
<TEREADYWHEN StrictRecognition
    OnHandEntry when screen_1_5 is "Quantity on hand Entry">
<TEACTION ENTER "5[enter]" skipcode>

<!-- Now enter the item number at row 5, column 10 -->
<TEACTION PUTFIELD 5 10 web.ItemNumber>
<!-- We are in a solid transaction system now, don't
        need TEREADYWHEN for good transition...-->
<TEACTION ENTER "[enter]" skipcode>
<TEIF Screen(20,60,9)=="NOT FOUND">
 <TESET ItemInfo.ReturnCode=100>
 <TESET ItemInfo.ReturnMessage="Item Not Found">
<TEELSE>
 <TESET ItemInfo.ReturnCode=0>
 <!-- Item Description-->
 <TESET ItemInfo.ReturnMessage=Screen(15,8,40)> 
 <TESET ItemInfo.QtyOnHand=Screen(15,50,10)>
 <TESET ItemInfo.QtyOnOrder=Screen(15,62,10)>
</TEIF>
<!-- ItemInfo goes back in base recordset -->
<TERESULT ROW ItemInfo>
<!-- This isn't a shared session, so we will
     logoff and release (stop) the session.  For
     shared sessions that keep open after logon,
     Don't logoff, and use <TEACTION RELEASE Keepopen>-->
<TEACTION ENTER "[pf12]" skipcode> <!-- logs off -->
<TEACTION RELEASE> 
</TENOTEXT>
</TESECTION>
Demonstrates a complete transaction for querying quantity on hand for an inventory item. The TEREADYWHEN StrictRecognition tag is used to make sure that each TEACTION ENTER only returns when the criteria "primed" in the TEREADYWHEN is met.

Since SurferScript supports the ability to call any number of sections as part of an individual request, sections should be developed specifically for managing screen navigation. For example, a section can be written which "knows" how to navigate to a "home" screen (either a command screen or a main menu) from any supported screen. This then can be used at any time to request a new function, regardless of where the last transaction left the application.

Typically, a transaction will start at this "home" screen-- when a session is newly started, a SurferScript section can be called to perform a logon to navigate correctly to the "home" screen. From the home screen, any number of host screens can be visited, with the data on the screens either entered from parameters passed by the co-server component (all input parameters passed are available as web.valuename variables). Note that navigation may be achieved using not only parameters passed in the current transaction request, but also any state variables declared using TEDECLARE and set using TESET.

Session Management

While you can mix and match session approaches with ScreenSurfer and co-server components, we will describe the two major session approaches here. The first approach is what we will call "anonymous requests". The second approach is "owned sessions".

The anonymous request environment involves sessions that are logged-on to the host using either a "dummy" userid/password. Note that if there are restrictions on the number of sessions an individual user can use: userids can be constructed using a base text and the Screen.SessionID variable, which is a number corresponding to the session number defined in the Console Settings Page.

The owned sessions environment is one where each co-server "application session" or "user" needs to logon with his or her own userid/password and own a specific session for the duration of the application. With owned sessions, the SessionKey is an important attribute that must be maintained in the co-server application, either as an application-level variable, a client-side cookie or in individual URL cookies. This is because the SessionKey is the connection between the co-server session, the host screen session and all the SurferScript session variables.

Co-Server Tag Reference

The following sections detail how to use each tag involved in supporting co-servers.

TEDECLARE ROW Defines a row of text and numeric variables

<TEDECLARE ROW
   [name=]{name} {variable 1 declaration}
   [variable n declaration]
   [...]>

Defines a row of SurferScript variables which will be returned either as simple variables using <TERESULT ROW> (not in a multirow return) or as a table using <TERESULT TABLE> and multiple <TERESULT ROW> tags (multiple rows).

TEDECLARE ROW Example 1 
<TEDECLARE ROW Header
       Name    Text 30,
       Company Text 30,
       Discount Float>
Defines a row named "Header" with three variables, accessed in any SurferScript expression (in any section) as: Header.Name, Header.Company and Header.Discount.

TEDECLARE ROW Example 2 
<TEDECLARE ROW Name=Detail
       ItemCode   Text 20,
       Quantity   Integer,
       Price      Float>
Defines a row named "Detail" with three variables, accessed in any SurferScript expression (in any section) as: Detail.ItemCode, Detail.Quantity and Detail.Price.

TERESULT  Controls return of QUERY data to ColdFusion, a RECORDSET to the SSurfer.ASPRequest Component, a RecordSet to the Surfer EJB or XML document data to XML-over-HTTP clients. Also provides an easy way to embed a row of data as named javascript variables in an HTML page.

<TERESULT {TABLE | ROW | HTML | XMLDOC | XMLPUSH | XMLPOP | JAVASCRIPT} ...>
The TERESULT tag has five major types, the TABLE, ROW, HTML, XMLxxx or JavaScript. Each of these is described in the following sections.

TERESULT TABLE

<TERESULT [type=]TABLE [[row=]RowOrScreenMapName [[name=]"XMLEntityName"]>
The TABLE result initiates a multirow result-set. The ROW attribute is used to specify the name of the TEDECLARE ROW or TEDECLARE SCREENMAP definition used to output each row of the table.

For a ColdFusion CFX tag, the result set will be returned as a QUERY (can access in a <CFOUTPUT> block) which has the name of the <CFX_SURFER Name="name"> attribute combined with an underscore and the RowName defined in the <TERESULT> tag. The names of the columns in the query will match the names in the named row.

For a SSurfer.ASPRequest or Surfer EJB object, a RecordSet with the same name as the RowName will be returned, containing fields matching the names in the named row.

For an XML-over-HTTP caller, an entity open tag is opened, with the name of the row or screenmap followed by the string "Table" as the entity name (for example, a row named "Person" would open a "<PersonTable>" tag. For XML output, the name= attribute can be used to name the open tag something different than the row name. For example, using <TEResult Table row=Person name="People"> will open an entity as <People> rather than <PersonTable>.

Following the <TERESULT TABLE RowName> tag, you typically will execute at least one <TERESULT ROW>, and usually more than one (you can use the <TELOOP> tag to control looping down a screen when multiple rows need to be returned).

TERESULT ROW

<TERESULT [type=]ROW [[row=]RowOrScreenMapName [[name=]"XMLEntityName"] [XMLPush="Yes|No"] [XMLAttrs="Yes|No"]>
The ROW result outputs a row that has been initialized using one or more TESET tags (one per row variable) or a SCREENMAP that has been initialized using the <TEGetScreen...> tag. The ROW attribute is used to specify the name of the TEDECLARE ROW/SCREENMAP definition to be output.

If the TERESULT ROW name matches the name given in a preceeding TERESULT TABLE, the row returned will belong to that table (or XML Entity). If not, the row is simply returned, and will be added to the BASE query or recordset for the current request (or added as single-level entities to the root XML document).

If no TERESULT TABLE is issued during the current transaction, all row fields returned will be added to the base query/recordset/root document. The base recordset has the same name as the active query in ColdFusion and has a name of "Base" for SSurfer.ASPRequest and the Surfer EJB.

For XML-over-HTTP results, the optional Name attribute can be used to name the opening entity tag something different than the name of the row.

XMLAttrs=Yes will cause all the variables in the row/screenmap to be included in the output entity as name/value pair attributes. By default (unless XMLPush=Yes is used), the Entity tag will be closed automatically at the end with a "/>".

XMLPush=Yes will prevent the "close of the entity" represented by the row from occuring (no /tag at end for a standard result or no / at the end of an attributes-style tag.

The default behavior for XML output is to have an opening entity tag with the name of the row or the optional XMLEntityName, followed by an entity open-body-entity close sequence for each variable defined in the row or screen. For an XML example, see XML Row Output Sample.

TERESULT TABLE and ROW Example 
<TENOTEXT>
<TESET Header.Name=TextScreen(1,2,30)>
<TESET Header.Company=TextScreen(1,40,30)>
<TESET Header.Discount=TextScreen(2,2,5)>
<TERESULT ROW HEADER>
<TERESULT TABLE DETAIL>
<TELOOP ScreenRow First=1 Last=19 Step=2>
  <TESET Detail.ItemCode=TextScreen(ScreenRow,2,20)>  
  <TESET Detail.Quantity=TextScreen(ScreenRow,60,5)>  
  <TESET Detail.Price=TextScreen(ScreenRow+1,70,10)>  
  <TERESULT ROW DETAIL>
</TELOOP>
</TENOTEXT>
This example demonstrates the sending of information from a fictional order status screen. It returns customer header information (name, company and discount percentage) along with one row for each "logical" row on the screen. Note that each logical row on the screen is two actual screen lines, and that the price is derived from data on the second row of each detail line.

TENOTEXT suppresses all text from the outbound datastream, making co-server communications more efficient, as it suppresses the line feeds and blanks between the TERESULT output fields.

TERESULT HTML

This is a new addition which enables full granular pass-through of any ScreenSurfer-generated HTML to the co-server component. All of the HTML passed-through will go into a single attribute with the NAME set in the tag. This attribute will be added to the Base RecordSet in ASP and the base Query in Cold Fusion.

TERESULT HTML Example 
<TERESULT HTML Name="ScreenTop">
<PRE><TEAREA 1 1 5 80 AS READONLY></PRE>
<TENOTEXT>
</TERESULT>
<TESET Header.Name=TextScreen(1,2,30)>
<TESET Header.Company=TextScreen(1,40,30)>
<TESET Header.Discount=TextScreen(2,2,5)>
<TERESULT ROW HEADER>
<TERESULT TABLE DETAIL>
<TELOOP ScreenRow First=1 Last=19 Step=2>
  <TESET Detail.ItemCode=TextScreen(ScreenRow,2,20)>  
  <TESET Detail.Quantity=TextScreen(ScreenRow,60,5)>  
  <TESET Detail.Price=TextScreen(ScreenRow+1,70,10)>  
  <TERESULT ROW DETAIL>
</TELOOP>
</TENOTEXT>
This example is a simple extension to the TABLE/ROW example, where we are passing through the top 5 lines of the current screen. This will be in a base query attribute named "ScreenTop" and will include all bold/normal attributes as are displayed in the current screen.

TERESULT XMLDOC xmldoc=VarName

For future release... (a future version of ScreenSurfer will include internal XML documents accessed for read/write the way that the Web:: XML input document is currently accessed. These internal documents will be managed with a new variable type that acts as an object handle to the document. The support for this capability will be combined with a XML schema parser so that the internal XML documents can be managed in a high performance manner (schema definitions will be required). The TEResult XMLDoc will be used to send an active internal XML document in a single operation).

TERESULT XMLPUSH name="EntityName">

Will open a new entity in the outbound XML stream--the name of the entity will be "EntityName" as defined in the name attribute. Note that to open an entity while including attributes, you use a <TEResult Row RowName xmlattrs="yes" xmlpush="yes">, otherwise for a simple entity open, use this tag, the TERESULT XMLPush.

Note that is your output in an XML-over-HTTP call starts with a TEResult XMLPush, it will override the name of the root document which as a default is named <Results>. So, to override the root document name use the TEResult XMLPUSH prior to any other TERESULT tags in your script.

TERESULT XMLPOP>

Will close the current entity. Note that an XML entity is opened using any of the following tags: 
<TEResult XMLPush name="EntityName">
(output = <EntityName>)

<TEResult Row RowName XMLPush="yes">
(output = <RowName>...variable entities...)

<TEResult Table RowName>
(output = <RowNameTable>...then TEResult Row's...)

TERESULT Javascript>

When embedded in a SCRIPT block, this can be used to easily transfer named javascript variables to a javascript array as "name/value" pairs so that the variables can easily be accessed in a dynamic manner in other script on the HTML page.

For a row named "Person" a Javascript array named nvPerson will be defined, and for each variable in the row or screenmap, a named element will be added to the array. For example, if the Person row contains three variables, "Name", "Height" and "Weight" and the values in these variables are "Windsurfer", "6-2" and "210" then the following javascript will be emitted: 

var nvPerson=new Array();
nvPerson['Name']='Windsurfer';
nvPerson['Height']='6-2';
nvPerson['Weight']='210';
Note that the value "Height" from person can be accessed in any javascript expression using nvPerson['Height'].
TEDECLARE RPC Define the interface for a co-server transaction  <TEDECLARE RPC [Parameters=]"Parm1,Parm2,..." [Results=]"row1,row2,..."
   [Description=]"Description">

Where:
 
Parameters The expected input, with each parameter name separated with a comma--since some transactions do not require any input parameters, this attribute is optional. Use the Description to identify if any declared parameters are optional/required, as a comment.
Results Returned results--this is a comma separated list of the rows that can be returned by this transaction in a TEDECLARE ROW. If a row is returned as part of a table, preceed its name with an underscore to indicate a full table return. (TERESULT TABLE preceeds one or more TERESULT ROW tags).
Description Freeform text used to describe this call to a developer viewing a list of calls in a DevCenter Co-server code generation wizard. Essentially a comment.

The TEDECLARE RPC tag should be included inside a TESECTION that is used to deliver functionality to a co-server application. By including a TEDECLARE RPC tag inside the transaction, the details of the objects identified in TEDECLARE RPC can be incorporated into a page generation wizard in the DevCenter.

TEDECLARE RPC Example 
<tesection DisplayEmployee
  when tranpath_1 is "display"
   and tranpath_2 is "employees">
<tedeclare rpc parameters="EmployeeNumber"
          results="_empStatData"
          description="Returns Employee Details">
<tenotext>
<teputsection connect>
<teaction goto toyscreens.mainmenu>
<teaction enter "2[enter]" skipcode>
<teaction enter web.EmployeeNumber+"[enter]" skipcode>
<teputsection empstat.screenread>
<teresult table empStatData>
<teresult row empStatData>
<teaction release keepopen>
</tenotext>
</tesection>
This example shows a transaction that accepts and employee number, navigates to the employee detail inquiry screen, then returns details for that employee. This example does not show the "worker script" that goes into the navigation and the copying of data from the screen to the row named "empStatData".
Top of Page