Page Links	Using Functions, Function Parameters, Function Quick Reference, Detailed Function Descriptions

As a general naming pattern, functions beginning with Text can be used in expressions in the same way as a text literal, and generally provide some form of text manipulation or transformation. Functions can be integrated directly with SurferScript expressions, which are used in <TEIF>, <TESET>, <TESHOW> <TEDATA>, <TEAREA> and a number of other tags.

Function Parameters

Function Quick Reference

Function Quick Reference This chart contains the current function set for ScreenSurfer, organized by type. Click on a function for a more detailed description. String/Text FindText (SearchText, TextToFind) Len (Text) Length (Text) TextClean (HTMLText) TextEncode (URLText) TextLeft (SourceText, Length) TextLower (SourceText) TextMid (SourceText, BaseZeroOffset, Length) TextUpper (SourceText) TextRight (SourceText, Length) TextScreen (Offset, Length) TextScreen (Row, Column, Length) TextTrim (SourceText) TextTrim (SourceText, CharListToTrim) WebText (NameOfValue) HTML Generation AidButtons (ButtonSource, Options) AidLinks (LinkSource, Target, Options) AidScriptButtons (LinkSource, Target, Options) Time/Date Now ("GMT"|"Local") Now ("GMT"|"Local", "MDY"|"DMY"|"YMD"|"YMDT") Now ("GMT"|"Local", "MDY"|"DMY"|"YMD"|"YMDT", SepChar) Math Max (FirstNumber, SecondNumber) Min (FirstNumber, SecondNumber) Modulus (BaseNumber, Divisor) Remainder (BaseNumber, Divisor) Screen Interaction FieldIsBold (Offset) FieldIsBold (Row, Column) FieldIsEntry (Offset) FieldIsEntry (Row, Column) FieldIsHidden (Offset) FieldIsHidden (Row, Column) FindNextBold (Offset) FindNextBold (Row, Column) FindNextEntry (Offset) FindNextEntry (Row, Column) FindNextField (Offset) FindNextField (Row, Column) Web/Session Management FileExists (FullFilePathName) GetColor (colorIndex) SetClientCookie (CookieName, Value, PathRoot, HoursToExpiry) SetColor (colorIndex, colorText) Server Control GetMaxSessions (LUGroupName) GetNumSessions (LUGroupName) GlobalLock () GlobalRelease () SetMaxSessions (LUGroupName) ManageSessions (Command, TargetSessions)

AidButtons(AIDKeys, Options)

Generates HTML Buttons from a formatting string based on AID key mnemonics. Use to create PFKey buttons. Note that text from the screen can be used as the source of this parameter to generate buttons automatically.
 

Syntax	AidButtons(AIDKeys,Options)
Parameters	AIDKeys String of the format "mnemonic=description, mnemonic2=description2". For example, "pf1=Help pf2=LastMajor pf3=Exit Clear=StartOver". Options Interpretation and formatting options. Up to three are supported. To specify more than one, separate with commas: Keep Will retain the text leading-up to the equals sign. For example, with Keep as an option, the string "pf1=help" will generate a button with "pf1=help" as its text. Default is nokeep, which will generate buttons with only the text to the right of the equals sign. Spaces For formats where there is a blank between the text descriptions and the "equals" character, such as "pf1 = Help" instead of "pf1=Help". EqChar=X Specifies a different "equals" character from the default of "=". For example, you would use "EqChar=-,Spaces" for a format of "PF1 - Help".
Returns	Returns a Text string of HTML defining one or more buttons

 

AidLinks(AIDKeys, Target, Options)

Generates HTML Links from a formatting string based on AID key mnemonics. Use to create PFKey links. Works in a similar fashion to AidButtons (see above), but adds the ability to direct the sending of a PFKey or other AID (such as the ENTER key) to another browser window or frame.
 

Syntax	AidLinks(AIDKeys,Target,Options)
Parameters	AIDKeys String of the format "mnemonic=description, mnemonic2=description2". For example, "pf1=Help pf2=LastMajor pf3=Exit Clear=StartOver". Target Target window or frame for the ScreenSurfer emulation form. This parameter will default to "document" if left blank, which means that the link is being generated in the same frame or window as the target ScreenSurfer emulation form. Options Interpretation and formatting options. Currently, only one is supported: Keep will retain the text leading-up to the equals sign. For example, with Keep as an option, the string "pf1=help" will generate a link with "pf1=help" as its text. Default is nokeep, which will generate links with only the text to the right of the equals sign.
Returns	Returns a Text string of HTML defining one or more links.

 

AidScriptButtons(AIDKeys, Target, Options)

Generates HTML Buttons from a formatting string based on AID key mnemonics. Use to create PFKey buttons. Works in a similar fashion to AidButtons (see above), but adds the ability to direct the sending of a PFKey or other AID (such as the ENTER key) to another browser window or frame.
 

Syntax	AidScriptButtons(AIDKeys,Target,Options)
Parameters	AIDKeys String of the format "mnemonic=description, mnemonic2=description2". For example, "pf1=Help pf2=LastMajor pf3=Exit Clear=StartOver". Target Target window or frame for the ScreenSurfer emulation form. This parameter will default to "document" if left blank, which means that the link is being generated in the same frame or window as the target ScreenSurfer emulation form. Options Interpretation and formatting options. Currently, only one is supported: Keep will retain the text leading-up to the equals sign. For example, with Keep as an option, the string "pf1=help" will generate a button with "pf1=help" as its text. Default is nokeep, which will generate buttons with only the text to the right of the equals sign.
Returns	Returns a Text string of HTML defining one or more buttons.

 

FieldIsBold(offset)

Returns 1 if field is bold at the given location (can give any location following attribute)
 

Syntax	FieldIsBold(offset)
Parameters	offset Zero-based offset into the current screen session-- can be any location in the field, starting with the attribute byte. The offset of the attribute byte provides the most efficient value.
Returns	Returns a 1 if the field is bold, otherwise 0.

 

FieldIsBold(row,column)

Returns 1 if field is bold at the given location (can give any location following attribute)
 

Syntax	FieldIsBold(Row, Column)
Parameters	Row One-based row of the current screen session-- this combined with column can describe any location in the subject field, starting with the attribute byte. The location of the attribute byte provides the most efficient value. Column One-based column of the current screen session-- this is combined with row (see above description of the row parameter.
Returns	Returns a 1 if the field is bold, otherwise 0.

 

FieldIsEntry(Offset)

Returns 1 if the field is unprotected at the given location (can give any location following attribute)
 

Syntax	FieldIsEntry(Offset)
Parameters	offset Zero-based offset into the current screen session-- can be any location in the field, starting with the attribute byte. The offset of the attribute byte provides the most efficient value.
Returns	Returns a 1 if the field is unprotected (an entry field), otherwise 0.

 

FieldIsEntry(row,column)

Returns 1 if the field is unprotected at the given location (can give any location following attribute)
 

Syntax	FieldIsEntry(Row, Column)
Parameters	Row One-based row of the current screen session-- this combined with column can describe any location in the subject field, starting with the attribute byte. The location of the attribute byte provides the most efficient value. Column One-based column of the current screen session-- this is combined with row (see above description of the row parameter.
Returns	Returns a 1 if the field is unprotected (an entry field), otherwise 0.

 

FieldIsHidden(offset)

Returns 1 if field is hidden at the given location (can give any location following attribute)
 

Syntax	FieldIsHidden(offset)
Parameters	offset Zero-based offset into the current screen session-- can be any location in the field, starting with the attribute byte. The offset of the attribute byte provides the most efficient value.
Returns	Returns a 1 if the field is hidden, otherwise 0 if displayed.

 

FieldIsHidden(row,column)

Returns 1 if field is hidden at the given location (can give any location following attribute)
 

Syntax	FieldIsHidden(Row, Column)
Parameters	Row One-based row of the current screen session-- this combined with column can describe any location in the subject field, starting with the attribute byte. The location of the attribute byte provides the most efficient value. Column One-based column of the current screen session-- this is combined with row (see above description of the row parameter.
Returns	Returns a 1 if the field is hidden, otherwise 0 if displayed.

 

FindNextField(offset)

Starting at the given location, return the offset of the next field
 

Syntax	FindNextField(Offset)
Parameters	offset Zero-based offset into the current screen session-- can be any location in the screen.
Returns	Returns the offset of the next field on the screen with an attribute byte anywhere starting with the Offset parameter, or a -1 if no field is found.

 

FindNextField(row,column)

Starting at the given location, return the offset of the next field
 

Syntax	FindNextField(Row, Column)
Parameters	Row One-based row of the current screen session-- this combined with column can describe any location in the screen from row 1, column 1 to the maximum row/column combination (typically 24, 80). Column One-based column of the current screen session-- this is combined with row (see above description of the row parameter.
Returns	Returns the offset of the next field on the screen with an attribute byte anywhere starting with the location described by the row/column parameters, or a -1 if no field is found.

 

FileExists(FullPathandFileName)

Using the full file name, return a 1 if the file currently exists, otherwise return 0
 

Syntax	FileExists(FullPathandFileName)
Parameters	FullPathandFileName Standard system file name, including the full path. The disk letter or network path name should be included, even if the file location is on the same disk as the ScreenSurfer service, in case the location of the service should move.
Returns	Returns a 1 if the file exists, otherwise a 0. This enables the direct use of this function in a TEIF statement, as a 1 is the BOOLEAN TRUE in this statement.

 

FindNextBold(offset)

Starting at the given location, return the offset of the next BOLD field-- can be quite handy when processing errors and the fields in error have been given the BOLD attribute by the host application.
 

Syntax	FindNextBold(Offset)
Parameters	offset Zero-based offset into the current screen session-- can be any location in the screen.
Returns	Returns the offset of the next Bold field on the screen with an attribute byte anywhere starting with the Offset parameter, or a -1 if no bold field is found.

 

FindNextBold(Row,Column)

Starting at the given location, return the offset of the next BOLD field-- can be quite handy when processing errors and the fields in error have been given the BOLD attribute by the host application.
 

Syntax	FindNextBold(Row, Column)
Parameters	Row One-based row of the current screen session-- this combined with column can describe any location in the screen from row 1, column 1 to the maximum row/column combination (typically 24, 80). Column One-based column of the current screen session-- this is combined with row (see above description of the row parameter.
Returns	Returns the offset of the next Bold field on the screen with an attribute byte anywhere starting with the location described by the row/column parameters, or a -1 if no Bold field is found.

 

FindNextEntry(Offset)

Starting at the given location, return the offset of the next ENTRY field
 

Syntax	FindNextEntry(Offset)
Parameters	offset Zero-based offset into the current screen session-- can be any location in the screen.
Returns	Returns the offset of the next Entry field on the screen with an attribute byte anywhere starting with the Offset parameter, or a -1 if no Entry field is found.

 

FindNextEntry(row,column)

Starting at the given location, return the offset of the next ENTRY field
 

Syntax	FindNextEntry(Row, Column)
Parameters	Row One-based row of the current screen session-- this combined with column can describe any location in the screen from row 1, column 1 to the maximum row/column combination (typically 24, 80). Column One-based column of the current screen session-- this is combined with row (see above description of the row parameter.
Returns	Returns the offset of the next Entry field on the screen with an attribute byte anywhere starting with the location described by the row/column parameters, or a -1 if no Entry field is found.

 

FindText Function

Find one text expression inside another  

Syntax	FindText(BaseText, LookForText)
Parameters	BaseText Text expression to be searched LookForText Text expression to be found inside of BaseText
Returns	Offset of LookForText inside of BaseText, with zero (0) representing the first character.  If LookForText is not found, returns -1.

 

GetColor Function

Read the current color setting for an extended 3270 color code  

Syntax	GetColor(colorIndex)
Parameters	colorIndex Index of the color being queried, in the range 1..15. The colors as defined for the 3270 device have the following indexes and original 3270 color names: Index 3270 Name HTML Default 0 NEUTRAL (foreground) blue 1 BLUE blue 2 RED red 3 PINK fuchsia 4 GREEN green 5 TURQUOISE teal 6 YELLOW yellow 7 NEUTRAL (background) black 8 BLACK black 9 DEEPBLUE navy 10 ORANGE olive 11 PURPLE purple 12 PALEGREEN lime 13 PALETURQUOISE aqua 14 GREY gray 15 WHITE white
Returns	The current HTML color name or color code for the requested index. If index is invalid (less than 0 or greater than 15), an empty string is returned.

 

Use the SetColor Function to change the setting for a given color code for the active session.

GetMaxSessions Function

Get the number of maximum sessions defined for the specified LU connection group  

Syntax	GetMaxSessions(LUGroupName)
Parameters	LUGroupName LU Group name to be queried, such as "LU_GROUP_1" or "LU_GROUP_6"
Returns	Maximum sessions currently defined for the group. This number is initially set at startup based on the range setting for the group in the console settings page. It can be changed using the SetMaxSessions function.

 

GetNumSessions Function

Get the number of active sessions for the specified LU connection group  

Syntax	GetNumSessions(LUGroupName)
Parameters	LUGroupName LU Group name to be queried, such as "LU_GROUP_1" or "LU_GROUP_6"
Returns	Current number of active sessions for the group. ScreenSurfer will not allow the number of active sessions to exceed the maximum sessions set using SetMaxSessions and queried using the GetMaxSessions function.

 

GlobalLock Function

Acquire a single global lock for the entire ScreenSurfer server's SurferScript execution. Note that this function does not prevent other sessions from executing-- but that it will stop any other session at the point that session executes the GlobalLock. The Lock acquired will persist until the GlobalRelease Function is executed or until the current HTTP request is completed.  

Syntax	GlobalLock()
Parameters	No Parameters
Returns	Always returns a 1.

 

GlobalRelease Function

Releases a single global lock for the entire ScreenSurfer server's SurferScript execution acquired using the GlobalLock Function. The next session waiting on the lock will continue execution following execution of GlobalRelease by the session owning the lock.  

Syntax	GlobalRelease()
Parameters	No Parameters
Returns	Always returns a 1.

 

Length Function (also Len Function)

 

Syntax	Length(Text) (also supported are "Len" and "strlen")
Parameters	Text Any text expression.
Returns	An integer with the length of the provided text. Note that blanks are included in the length of any text string; you can remove blanks with the TextTrim Function

 

Max Function

 

Syntax	Max(FirstNumber, SecondNumber)
Parameters	FirstNumber Any numeric expression (will be evaluated to an integer) SecondNumber Any numeric expression (will be evaluated to an integer)
Returns	The higher value of FirstNumber and SecondNumber

 

Min Function

 

Syntax	Min(FirstNumber, SecondNumber)
Parameters	FirstNumber Any numeric expression (will be evaluated to an integer) SecondNumber Any numeric expression (will be evaluated to an integer)
Returns	The lower value of FirstNumber and SecondNumber

 

Modulus Function

 

Syntax	Modulus(BaseNumber, Divisor)
Parameters	BaseNumber Any numeric expression (will be evaluated to an integer) Divisor Any numeric expression (will be evaluated to an integer)
Returns	The remainder when BaseNumber is divided by Divisor. For example, Modulus(17,3) will return the value 2, while Modulus(10,2) will return 0.

 

Now Function

Returns a string representing the current ScreenSurfer system time and date. Optional parameter enables control over "local" time or Greenwich Mean Time (GMT). Note that there is no date/time data type in SurferScript in the current version; the value returned by the now() function is a text string like any other, and is not useful in date/time calculations or comparisons!  

Syntax	Now(Option) Now(Option,FormatNumber) Now(Option,FormatNumber,Separator) Now(Option,FormatText,Separator)
Parameters	Option Optional control of the time produced. Default is "local" which will return a string representing the local time. If "gmt" is the Option value, the string returned will represent Greenwich Mean Time, which is the standard time used by Web Servers to represent resource dates and expirations. FormatNumber Optional format of the datetime string returned. Note that numeric or text representations may be used. The supported format numbers include (assumes a separator of "-"; if no separator is specified, the separator will be omitted): Number Description 1 HTTP (Monday Mon, 13 Jul 1998 22:12:24) 2 DDMMYYYY (13-07-1998) 3 MMDDYYYY (07-13-1998) 4 YYYYMMDD (1998-07-13) 5 YYYYMMDDTIME (1998-07-18-22-12-24) FormatText Optional format text of the datetime string returned. Note that numeric or text representations may be used (see above). The supported format text maps include (assumes a separator of "-"; if no separator is specified, the separator will be omitted): Format Description HTTP (Monday Mon, 13 Jul 1998 22:12:24) DDMMYYYY (13-07-1998) MMDDYYYY (07-13-1998) YYYYMMDD (1998-07-13) YYYYMMDDTIME (1998-07-18-22-12-24)
Returns	A string representation of date and time, an example of which is: "Monday Mon, 13 Jul 1998 22:12:24"

 

Screen Function

 

Syntax	Screen(Row, Column, Length)
Parameters	Row Integer expression representing the screen session data row (1..24) Column Integer expression representing the screen session data column (1..80) Length Integer expression representing the length of the screen data
Returns	A text value from the current host screen session at Row, Column, for Length characters.

 

Example:

<TEIF Screen(TargetRow+1,20,5)="Jones">

The list on the screen has <TESHOW Screen(1,10,2)> customers,

and includes the customer Jones.

</TEIF>

If Jones is found, the data at row 1, column 10 for 2 characters is merged with some simple HTML text to display how many customers are in the list.  This assumes a screen with the number of customers displayed at this position.

Other Examples:

<TESET global.URL="www.mycompany.com">
<TESET row=10+offset*2>
<TESET CustomerName=Screen(row,10,20)>
<TESET Message= '<A HREF="'+global.URL+'">'+Click Here to go There+"</A">

Note in the final example that the apostrophe (single quote) or double-quote character can be used to open and close a literal text value.  Thus, if the literal (such as an HREF tag) requires the use of double quotes, use single-quotes to bracket the literal, as the parser will then ignore the double quotes. 

SetClientCookie Function

 

Syntax	SetClientCookie(CookieName, CookieValue, DomainPrefix, HoursToKeep)
Parameters	CookieName Text expression representing the name of the cookie to be stored at the client browser. CookieValue Text expression for the new value of the cookie being set. DomainPrefix Text expression defining the full URL root on which the client browser should return the value of the cookie. For example, if you want the cookie returned to all requests to your ScreenSurfer machine, you would use something like "http://mymachine/surfer/". HoursToKeep Number of hours until the cookie "expires". Since this can be any integer value, you can put a very high number to get a long value. The special value of -1 will result in a 10 year expiration. The special value of 0 will have the effect of deleting the cookie if it is on the client machine, as this will set the cookie to expire immediately, whether or not it already exists.
Returns	An integer value of 0 on success.

 

When the DomainRoot you define for the cookie matches the beginning or full URL on either an HREF (in a anchor/link tag) or on the ACTION in a form tag, the cookie value will be sent-in along with the other data in the request.

Cookies may be read in your surferscript using web.Cookie_name, where the name following the web.cookie_ is the name you give here.

SetColor Function

Set the current color setting for an extended 3270 color code  

Syntax	SetColor(colorIndex, htmlColor)
Parameters	colorIndex Index of the color being set, in the range 1..15. The colors as defined for the 3270 device have the following indexes and original 3270 color names: Index 3270 Name HTML Default 1 BLUE blue 2 RED red 3 PINK fuchsia 4 GREEN green 5 TURQUOISE teal 6 YELLOW yellow 7 NEUTRAL black 8 BLACK black 9 DEEPBLUE navy 10 ORANGE olive 11 PURPLE purple 12 PALEGREEN lime 13 PALETURQUOISE aqua 14 GREY gray 15 WHITE white htmlColor HTML name of the color. Note that the setting for the color can either be of the simple HTML "color name" text form, or the #336699 form, where the 2 digit hex representation of the Red, Green and Blue components are used.
Returns	The colorIndex as provided to the function as a parameter. If the colorIndex is invalid (less than 0 or greater than 15), -1 is returned.

 

Use the GetColor Function to query the setting for a given color code for the active session.

SetMaxSessions Function

Set the number of maximum sessions defined for the specified LU connection group-- usefull for controlling the maximum number of logical units acquired from the host in a flexible manner. For example, in a University environment, student access can be constrained during periods of time when administration access requires priority.  

Syntax	SetMaxSessions(LUGroupName)
Parameters	LUGroupName Target LU Group name for the maximum sessions update, such as "LU_GROUP_1" or "LU_GROUP_6" MaxSessions Maximum allowable sessions for the group. Note that this value cannot exceed the size of the group's range. The group's range is set in the Administrator's Console Settings page.
Returns	Actual maximum set by the function. If the MaxSessions value exceeds the maximum allowable for the group, the maximum allowable for the group will become the new MaxSessions value (and will be returned by the function)

 

TextClean Function

TextClean assures that the passed text will not affect any HTML code in a target HTML page. All symbols that control HTML are converted to a "safe" symbol representation, such as the ampersand character (&) being converted to (&amp;). Any HTML tag in the text will not be "operational" after this function, as all "less than" (<) symbols are converted to ("&lt;"). 

Syntax	TextClean(Text)
Parameters	Text Any text expression. Maximum size is 2000 characters.
Returns	A text value which consists of the characters from Text that have been "HTML-Cleaned". See general description, above.

 

TextEncode Function

 

Syntax	TextEncode(Text)
Parameters	Text Any text expression.
Returns	A text value which consists of the characters from Text that have been "URL-Encoded". For example, any spaces (blanks) are converted to the "+" symbol. Any special characters not found in the basic alphabet and a few other characters are encoded using the percent-sign followed by the hexidecimal value of that character. All URL text must be encoded if it has any blanks in it, or it will break the HTTP protocol!

 

TextLeft Function

 

Syntax	TextLeft(Text, Length)
Parameters	Text Any text expression. Length An integer expression representing the amount of text to take starting from the leftmost position of text
Returns	A text value which starts with the leftmost character of Text and has a length which is no greater than Length characters.  Note that if the length of Text is less than Length, than the full text of Text will be returned. If Length evaluates to less than or equal to 0, than a zero-length text value will be returned.

 

TextLower Function

 

Syntax	TextLower(Text)
Parameters	Text Any text expression.
Returns	A text value which is the result of converting each character of Text to its lower-case representation.

 

TextMid Function

 

Syntax	TextMid(Text, Start, Length)
Parameters	Text Any text expression. Start An integer expression representing the zero-based offset inside of Text to create a new text value from. The first character would have a Start of 0, while the second character would have a Start of 1 and so on. Length An integer expression representing the amount of text to take starting from the Start position of Text
Returns	A text value which starts at the Start offset within Text and has a length which is no greater than Length characters.  Note that if the length of Text minus Start is less than Length, than only the text between Start and the end of Text will be returned. If Length evaluates to less than or equal to 0, or Start evaluates to a value past the end of Text than a zero-length text value will be returned.

 

TextRight Function

 

Syntax	TextRight(Text, Length)
Parameters	Text Any text expression. Length An integer expression representing the amount of text to take starting from the rightmost position of text
Returns	A text value which starts with the rightmost character of Text and has a length which is no greater than Length characters.  Note that if the length of Text is less than Length, than the full text of Text will be returned. If Length evaluates to less than or equal to 0, than a zero-length text value will be returned.

 

TextScreen Function

 

Syntax	TextScreen(Offset, Length)
Parameters	Offset Any numeric expression. The offset that text should be read from the active screen session. For situations where row/column is desired, you can use the Screen() function. Should be between 0 and 1919, inclusive. Length An integer expression representing the amount of text to read from the screen starting at offset.
Returns	A text value which starts at offset in the current screen session and is length characters long.

 

TextTrim Function

 

Syntax	TextTrim(Text, [TrimChars])
Parameters	Text Any text expression. TrimChars (optional) To specify characters to trim, include this parameter and include a text string with up to three characters to remove, such as " _-" (blank, underscore, dash)
Returns	A text value which is the result of removing any leading or trailing spaces/characters from Text.

 

TextUpper Function

 

Syntax	TextUpper(Text)
Parameters	Text Any text expression.
Returns	A text value which is the result of converting each character of Text to its upper-case representation.

 

WebText Function

 

Syntax	WebText(Name)
Parameters	Name A text epression that resolves to the name of an active web value in the current hit.
Returns	The value of the name-value pair, if found. If not found, returns a string with no data in it (zero length). If the current web hit has more than one value with the same name, calling this function with that name will return each value in sequence, until the values have been all returned and then it will return the first value again.