ScreenSurfer URL Commands
This section describes how ScreenSurfer processes URL commands in order to deliver web-based 3270 gateway functionality.  It is organized by the initial command in the command path, which may consist of more than one item (a command path consists of multiple items separated by forward slashes).

Note that all ScreenSurfer URL commands start with the string "/SURFER/". This provides a consistent path off of the HTTP URI root for a Web Server plug-in or extension to indirect HTTP requests to the ScreenSurfer service.

Current product plans are for ScreenSurfer to integrate with the Netscape family of servers (using the NSAPI or WAI interfaces) as well as the Microsoft Internet Information Server (IIS) using the ISAPI filter extension type.

/SURFER/CONNECT[/LU GROUP]

The /SURFER/CONNECT URL requests that ScreenSurfer find an available host screen session and allocate it to the caller.  It includes an optional parameter, which if included identifies the defined LU group that the session should be allocated from.

If the user already has an active session, he or she will be reconnected to that session.  If a user needs to have more than one session active, the /SURFER/CONNECTNEW command should be used.

The LU GROUP parameter should be of the form LU_GROUP_n where "n" is a number from 1 to 10, and is the same as the subject groups position in the current ScreenSurfer settings page.

If the CONNECT URL is successful, the next page displayed will be from the first host screen displayed after a terminal activation, depending on the LU group and the host programming.  This first page may be created using the Global.Default template section or from a customization section described in a template file.  Note that the first page displayed following a CONNECT command is not cached so that the user can bookmark / re-key the connect command and not get a cached (dead) page.

In addition, on a successful connection, the client will be sent the special cookie SurferKey which is used to reconnect the user to any existing session if the /SURFER/CONNECT command is given while that session exists.

Typically, a page resulting from the CONNECT command will include an HTML form which contains a number of elements related to the screen displayed, and having an action URL which calls the EMULATOR command.


/SURFER/CONNECTNEW[/LU GROUP]

This command is essentially equivilent to the /SURFER/CONNECT command, except that the user will not be reconnected to any existing session.  This command should be used only in those circumstances where a user needs to have more than one session active concurrently.


/SURFER/FORM/EMULATOR/SESSIONKEY

The EMULATOR command (which is prefixed by "form" for ScreenSurfer to detect form processing) is the primary command for both general-purpose terminal emulation and most enhanced screen interaction.

The EMULATOR command has a required parameter, SessionKey, which is always included in any generated URL's using the <TEMACRO SessionKey> tag.

The EMULATOR command calls the ScreenSurfer emulation processor, which scans for any HTML name-value pairs of the following form:
 
F_offset_length  Defines field data to be updated directly to the host screen at the specified offset and length
E_Enter The Enter key-- usually set as the name of a button
C_Pos Cursor position, will contain a zero-based offset to set current cursor position
IAID.X, IAID.Y Horizontal PFKey image map was clicked-on -- see <TEMACRO TERMHKEYS>
VAID.X, VAID.Y Vertical PFKey image map was clicked on -- see <TEMACRO TERMVKEYS>
A_AidKeyString The AidKeyString can be of the EHLLAPI form (as in @E for ENTER) or the mnemonic form ([ENTER] for ENTER).
Any found data names matching any of the above patterns are used to update and process the current host screen.  That is, if the SessionKey is valid for the current screen.  If the SessionKey is valid, but the host screen is mismatched due to the user using the "back" button, any PATHTO entries in the current screen's <TESECTION> will be used to navigate to the correct screen prior to processing the entries.

Following data entry from the inbound web data, the EMULATOR command will send the ENTER or PFkey (depending on operator input) to the host, and then call the Screen Recognition Engine in order to identify the next host screen.  Note that by using the <TEEVENT> tag, any exceptions on the current host screen can be caught and processed, without "diving" into the general screen recognition rulebase.

/SURFER/REFRESH/SESSIONKEY

This URL may be used when the session is "out-of-synch" or the user believes that there has been a host refresh that is not reflected on the current HTML page.

The SessionKey is used to validate the user and if the user owns the session indicated by the sessionkey, the current host screen is redisplayed through the appropriate template (if the screen is known by ScreenSurfer).

See the /SURFER/CONNECT URL for situations where the SessionKey is not available but the user has a current session active.

//SURFER/EXIT/SessionKey

The EXIT command requires that the second part of the URL path be the valid SessionKey for the current user.

If the SessionKey is valid, the host screen session will be disconnected from the user and the user will be presented with the Global.Home HTML page.

//SURFER/HOME

Displays the Global.Home HTML page-- typically used as the entry point to ScreenSurfer applications.

//SURFER/SENDKEYS/SessionKey/KeyString/ScreenID

The SENDKEYS command will send KeyString to the current session after validating that the SessionKey is valid, and after performing any needed screen navigation using ScreenID in case the user has used the browser back button and is out-of-synch with the current host screen.

KeyString can be any sequence of host keys (see Valid Keystroke Mnemonics for Host Keys, but should end with an AID key, such as "[enter]").

An example of generating a link in a template follows: it homes the cursor, enters three fields then sends a PF1:

<A HREF="/SURFER/SENDKEYS/<TEMACRO SESSIONKEY>/[home]data1[tab]data2[tab]data3[pf1]/<TEMACRO SCREENID>">

/SURFER/UserDefinedTransaction?SessionKey=SessionKey&ScreenID=ScreenID

The user defined transaction will call the corresponding section that has defined a WHEN TRANPATH_1 IS "UserDefinedTransaction".

Note that the name-value pairs for SessionKey and ScreenID are required for any transaction which will be accessing an active session.  The <TEMACRO TRANURL> is specifically designed to generate user-defined transactions with the correct inclusion of SessionKey and ScreenID.
Top of Page