Contents of this Section:

What is a Scripting Language?
ECMAScript Overview
Functions
Variables
Arrays
Special Values
Comments
Control Statements
Operators
Arithmetic Operators
String Operators
Logical Operators
Bitwise Operators
Assignment Operators
Comparison Operators
Special Operators
Standard Methods
Strings
Boolean
Number
Date
Global
Other
Using ODBC with Local SQL Databases
Jargon Software Methods

A scripting language is an easy-to-use programming language that is used to manipulate, customize, and automate the facilities of an existing system, such as a Web browser or the Jargon Reader deployment engine.

In such systems, useful functionality is already available through a graphical user interface (GUI), and the scripting language is a way to control that functionality. In this way, the existing system is said to provide an environment of objects and facilities which completes the capabilities of the scripting language.

A scripting language is designed for both professional and non-professional programmers, and so it normally has a number of informalities built into the language.

ECMASCript Overview

ECMAScript is a standard Internet scripting language formally known as ECMA-262 (ECMAScript), sanctioned by the European Computer Manufacturers Association (ECMA). The language spec was based on an early version of JavaScript. This specification was then used by Microsoft, Netscape, Opera, and other browser venders who have provided support for it in later JavaScript and JScript versions.

ECMAScript is an interpreted, object-based scripting language. Although it has fewer capabilities than full-fledged object-oriented languages like C++, JScript is more than sufficiently powerful for its intended purposes. ECMAScript is not a cut-down version of another language (it is only distantly and indirectly related to Java, for example), nor is it a simplification of anything.

JavaScript and JScript include the core ECMAScript language plus many extensions that deal specifically with browser objects such as document, window, frame, form, etc. The methods for these browser-related objects can be ignored if you look at JavaScript documentation, since the scripting engine is being run within the context of the Jargon Reader engine, not within the context of a web browser. Only the core ECMAScript language features are used in Jargon Reader, not JavaScript or JScript extensions.

The scripting engine used by Jargon Software supports primarily the core ECMAScript language features, plus a few other useful methods from JavaScript and/or JScript that are generic methods (not related to browser objects). This scripting has been extended by Jargon Software to provide support for methods used by graphical components, host tasks, and other features of the Jargon Reader run-time environment.

ECMAScript is object-based: basic language and host facilities are provided by objects, and an ECMAScript program is a cluster of communicating objects. An ECMAScript object is an unordered collection of properties each with 0 or more attributes which determine how each property can be used.

Properties are containers that hold other objects, primitive values, or methods. A primitive value is a member of one of the following built-in types: Undefined, Null, Boolean, Number, and String; an object is a member of the remaining built-in type Object; and a method is a set of programming statements associated with an object via a property.

ECMAScript defines a collection of built-in objects which round out the definition of ECMAScript entities. These built-in objects include the Global object, the Object object, the Function object, the Array object, the String object, the Boolean object, the Number object, the Math object, and the Date object.

ECMAScript also defines a set of built-in operators which may not be, strictly speaking, functions or methods. ECMAScript operators include various unary operations, multiplicative operators, additive operators, bitwise shift operators, relational operators, equality operators, binary bitwise operators, binary logical operators, assignment operators, and the comma operator.

ECMAScript syntax intentionally resembles Java syntax. ECMAScript syntax is relaxed to enable it to serve as an easy-to-use scripting language. For example, a variable is not required to have its type declared nor are types associated with properties, and defined functions are not required to have their declarations appear textually before calls to them.

ECMAScript is a loosely typed language. Loosely typed means you do not have to declare the
data types of variables explicitly. In fact, you cannot explicitly declare data types. Moreover, in many cases ECMAScript performs conversions automatically when needed. For instance, if you add a number to an item consisting of text (a string), the number is converted to text.
 

Functions

A function contains some code that will be executed by an event or a call to that function. A function is a set of statements. To create a function you define its function name, any calling parameters ("arguments"), and one or more statements to be executed. A function may not be declared within another function. All functions may be called from anywhere in a script.

Functions have the following structure:

function FUNCTION_NAME(PARAM_LIST) {
  STATEMENT_BLOCK
}

• FUNCTION_NAME is user-assigned (see User Tips below)

 
• PARAM_LIST is a comma-separated list of user-assigned names for any input parameters (arguments) that will be supplied to this function. These names are scoped for use only within the function where they are declared. Their values will be the values passed on by the statement that calls the function.

 
• STATEMENT_BLOCK is a set of one or more methods or other statements to be executed. Each statement should be on a separate line and should be ended with a semi-colon (;). Statements are often indented for readability.

function ElvisHasLeftTheBuilding() {  // function linked to "Exit" button
    sys.Exit();
}

User Tip: You may wish to establish a naming convention that will make function, variable and parameter names consistent and easily recognizable and understandable.

A statement block is a group of statements enclosed in curly braces, "{}", which indicate that the enclosed individual statements are a group and are to be treated as one statement. A block can be used anywhere that a single statement can.

Here are some general guidelines for writing the statements within a function:

• ECMAScript is case-sensitive, so be careful to use upper/lower case letters carefully in the names of functions, variables, components and methods.
• Open symbols, like  ( { [ " ', must have a matching closing symbol, like  ' " ] } ).
• Extra spaces are ignored by the script engine. You can add spaces to your script to make it more readable. Avoid tabs since different programs may interpret their size differently.
• You can break up a long line onto several lines, however do not split a function or method name from its arguments (don't start the split line with a left parenthesis).
• You can insert special characters with a backslash (\), as shown in the next section.

Reserved Words
The following words have special meaning for the interpreter and cannot be used as identifiers for variable, component or function names:

abstract arguments Array as
Boolean boolean break byte
case catch cfunction char class const continue
Date debugger decodeURI decodeURIComponent default delete do double
else encodeURI enum Error escape eval EvalError export extends
false final finally float for Function function
goto
if implements import in Infinity instanceof int interface is isFinite isNaN
long
Math
namespace NaN native new null Number
Object
package parseFloat parseInt private protected public
RangeError ReferenceError RegExp return
short static String super switch synchronized SyntaxError
this throw throws transient true try TypeError typeof
undefined unescape URIError use
var void volatile
while with

Variables

A variable is a "container" for information you want to store. A variable's value can change during the script. You can refer to a variable by name to see its value or to change its value.

Rules for Variable names:

• Variable names are case sensitive
• Contain only letters (upper and lower case), digits 0-9 and underscores (_).
• Must begin with a letter or underscore character. It is best to start names with a letter.
• Do NOT use dashes (-) or any other special characters in user-defined names for functions, variables and parameters.

For example, both of the following statements are valid ways to create a variable and assign it a value.

two_squared = 2 * 2;
var three_squared = 3 * 3;

Arrays
A special type of variable is an array, which is an instance of the standard ECMAScript Array object. An Array is a special class of object that refers to its properties with numbers rather than with variable names. Properties of an Array object are called elements of the array. The number used to identify an element is called an index in brackets which follows an array name. Array indices must be either numbers or strings. Array elements can be of any data type. The elements in an array do not all need to be of the same type, and there is no limit to the number of elements an array may have.

Arrays use square brackets to specify the element number within the set of array values, normally starting with [0] for the first. Arrays are dynamic, and any index, positive or negative, into an array is always valid. If an element of an array is referenced, then the script engine ensures that such an element exists. For example, if a statement in a script is:

var foo[4] = 7;

Arrays can be defined in two ways, by specifying the number of elements, or by specifying a set of element values. Examples:

var bakersDozen = new Array(13); // creates the array 'bakersDozen' with 13 elements
var carName = new Array("Corvette", "Mustang", "SVX"); // carName[1] == "Mustang"

Sorting an Array
To sort the elements of an array, use the array.sort method. This is a very flexible sort routine which will (by default) sort strings in alphabetical order. However, you can optionally provide a compare function that the sort method will use to compare each pair of elements as it is sorting, to handle date and numeric values.

SYNTAX: array.sort([compareFunction])
WHERE:  compareFunction - identifier for a function which expects two parameters x and y,
and returns a negative value if x < y, zero if x = y, or a positive value if x > y.
RETURN: object - this Array object after being sorted.
DESCRIPTION: This method sorts the elements of the array. The sort is not necessarily stable (that is, elements which compare equal do not necessarily remain in their original order).

If a compare function is supplied, the array elements are sorted according to the return value of the compare function. If a and b are two elements being compared, then:

• If compareFunction(a, b) is less than zero, sort b to a lower index than a.
• If compareFunction(a, b) returns zero, leave a and b unchanged to each other.
• If compareFunction(a, b) is greater than zero, sort b to a higher index than a.

function compareNumbers(a, b)
{
return a > b
}

function compare( x, y )
{
   x = ToNumber(x);
   y = ToNumber(y);
   if( x < y )
      return -1;
   else if ( x == y )
      return 0;
   else
      return 1;
}
var array = new Array( 3, undefined, "4", -1 );
array.sort(compare);
// The sorted array is "-1,3,4,,"
// Notice the undefined value at the end of the array.

Special values

undefined
If a variable is created or accessed with nothing assigned to it, it is of type undefined. An undefined variable merely occupies space until a value is assigned to it. When a variable is assigned a value, it is assigned a type according to the value assigned. Though variables may be of type undefined, there is no literal representation for undefined. Since an undefined variable will cast to a boolean value as false, it can be tested as follows (although other values such as zero or an empty string will also cast to false so it is an ambiguous test):

var test;
if (!test)
   myMessage = "test is undefined or has some other value that casts to false";

var test;
if (test == null)
   myMessage = "test is null";

var test = null;

NaN
The NaN type means "Not a Number". NaN is an acronym for the phrase. However, NaN does not have a literal representation. To test for NaN, the global function isNaN() must be used, for example:

var Test = "a string";
if (isNaN(parseInt(Test)))
   myMessage = "Test is Not a Number";

Comments

Comments may be of two types: single-line or multi-line. In a single-line comment, all text following a pair of slashes ("//") to the end of that line is treated as a comment and ignored. In a multi-line comment, all text between a starting "/*" and ending "*/" is treated as a comment and ignored. Multi-line comments may not be nested within multi-line comments, but single-line comments can exist within multi-line comments.
 

thirty_six = two_squared * three_squared; // this is a single-line comment
/* This is a multi-line comment that
   also contains a single-line comment // like this one
*/

The standard ECMAScript statements include variable definitions and control commands for looping and conditional execution. The CONDITION in "if" and "while" tests can be anything that evaluates to a boolean value. For an explanation of how various data values convert ("cast") to a Boolean value, see the discussion in the Boolean Properties and Methods section.
 

break	Statement that terminates the current while or for loop and transfers program control to the statement following the terminated loop.
continue	Statement that terminates execution of the block of statements in a while or for loop, and continues execution of the loop with the next iteration.
do...while	Executes its statements until the test condition evaluates to false. Statements are executed at least once.  Syntax:  do {    STATEMENT_BLOCK} while (CONDITION);
for	Creates a loop that consists of three optional expressions, enclosed in parentheses and separated by semicolons, followed by a block of statements executed in the loop.  Syntax:  for ( INITIAL_EXPRESSION; CONDITION; INCREMENT_EXPRESSION ) {    STATEMENT_BLOCK } Example:  for (var i = 0; i < 9; i++) {    n += i    myfunc(n) }
if...else	Statement that executes a set of statements if a specified condition is true. If the condition is false, another set of statements can be executed. Note that the "else" clause is optional. Also, the statement blocks can in turn contain nested "if" statements, to any level.  Syntax:  if (CONDITION) {    STATEMENT_BLOCK } [else {    STATEMENT_BLOCK }] Example:  if (n1 == n2) {    n3++;    n4--;} else {    n5++;    n6--;}
return	Statement that exits a function and optionally specifies the value to be returned from running it.
switch	Allows a program to evaluate an expression and attempt to match the expression's value to a case label.  Syntax:  switch (EXPRESSION){    case LABEL:        STATEMENT_BLOCK;       break;    case LABEL:        STATEMENT_BLOCK;       break;    ...    default : STATEMENT_BLOCK; } Example:  switch (my_code) {   case "B" :      my_color = "Blue";      break;   case "R" :      my_color = "Red";      break:   default :      my_color = "Unknown"; }
var	Statement that declares a variable, optionally initializing it to a value.
while	Statement that creates a loop that evaluates an expression, and if it is true, executes a block of statements. If the condition is initially false, no statements will be executed (unlike "do...while").  Syntax:  while (CONDITION) {    STATEMENT_BLOCK }

Operators

ECMASCript provides a rich set of operators for arithmetic, string, logical and bit-level operations, value assignments, value comparisons, and other special operations.
 

Operator  Category	Operator	Description
Arithmetic	+	(Addition) Adds 2 numbers.
	++	(Increment) Adds one to a variable representing a number (returning either the new or old value of the variable)
	-	(Unary negation, subtraction) As a unary operator, negates the value of its argument. As a binary operator, subtracts 2 numbers.
	--	(Decrement) Subtracts one from a variable representing a number (returning either the new or old value of the variable)
	*	(Multiplication) Multiplies 2 numbers.
	/	(Division) Divides 2 numbers.
	%	(Modulus) Computes the integer remainder of dividing 2 numbers.
String	+	(String addition) Concatenates 2 strings.
	+=	Concatenates 2 strings and assigns the result to the first operand.
Logical	&&	(Logical AND) Returns true if both logical operands are true. Otherwise, returns false.
	||	(Logical OR) Returns true if either logical expression is true. If both are false, returns false.
	!	(Logical negation) If its single operand is true, returns false; otherwise, returns true.
Bitwise	&	(Bitwise AND) Returns a one in each bit position if bits of both operands are ones.
	^	(Bitwise XOR) Returns a one in a bit position if bits of one but not both operands are one.
	|	(Bitwise OR) Returns a one in a bit if bits of either operand is one.
	~	(Bitwise NOT) Flips the bits of its operand.
	<<	(Left shift) Shifts its first operand in binary representation the number of bits to the left specified in the second operand, shifting in zeros from the right.
	>>	(Sign-propagating right shift) Shifts the first operand in binary representation the number of bits to the right specified in the second operand, discarding bits shifted off.
	>>>	(Zero-fill right shift) Shifts the first operand in binary representation the number of bits to the right specified in the second operand, discarding bits shifted off, and shifting in zeros from the left.
Assignment	=	Assigns the value of the second operand to the first operand.
	+=	Adds 2 numbers and assigns the result to the first.
	-=	Subtracts 2 numbers and assigns the result to the first.
	*=	Multiplies 2 numbers and assigns the result to the first.
	/=	Divides 2 numbers and assigns the result to the first.
	%=	Computes the modulus of 2 numbers and assigns the result to the first.
	&=	Performs a bitwise AND and assigns the result to the first operand.
	^=	Performs a bitwise XOR and assigns the result to the first operand.
	|=	Performs a bitwise OR and assigns the result to the first operand.
	<<=	Performs a left shift and assigns the result to the first operand.
	>>=	Performs a sign-propagating right shift and assigns the result to the first operand.
	>>>=	Performs a zero-fill right shift and assigns the result to the first operand.
Comparison	==	Returns true if the operands are equal.
	!=	Returns true if the operands are not equal.
	>	Returns true if left operand is greater than right operand.
	>=	Returns true if left operand is greater than or equal to right operand.
	<	Returns true if left operand is less than right operand.
	<=	Returns true if left operand is less than or equal to right operand.
Special	?:	Lets you perform a simple "if...then...else"
	,	Evaluates two expressions and returns the result of the second expression.
	delete	Lets you delete an object property or an element at a specified index in an array.
	new	Lets you create an instance of a user-defined object type or of one of the built-in object types.
	this	Keyword that you can use to refer to the current object.
	typeof	Returns a string indicating the type of the unevaluated operand.
	void	The void operator specifies an expression to be evaluated without returning a value.

Standard Methods

The built-in String, Boolean, Number, Date and Global objects include a variety of standard properties and methods that may be used on literal or variables of the appropriate data type. There is also a full set of math functions for use in scientific or financial applications. The following tables show the most commonly used methods. For a complete list, refer to the complete ECMAScript or JavaScript documentation.

String Properties and Methods

A string is an ordered series of characters. The most common use for strings is to represent text. To indicate that text is a string, it is enclosed in quotation marks. You can declare a string with single quotes instead of double quotes. There is no difference between the two ways. Note that a String is both a primitive data type and an object. For most practical purposes, this distinction makes no difference.
 

Property Name	Description
length	Returns the number of characters in the target string Example: var myString = "abcde"; myLength = myString.length; // returns 5 (Note: no parentheses)
Method Name	Description
charAt (position)	Returns the character at the given position in a string, where position starts at zero for the first character. Example: var myString = "abcde"; myChar = myString.charAt(2); // returns "c" // get the last character in the string lastChar = string.charAt(string.length - 1); // "e"
indexOf (string[, offset])	Searches and (if found) returns the index number of the search string within the target string. The search begins at offset if specified, otherwise the search begins at the beginning of the string. If no match is found, "-1" is returned instead. Example: var myString = "abcde"; myPos = myString.indexOf("cd"); // returns 2 myPos = myString.indexOf("CD"); // returns -1 (case!!)
lastIndexOf (string[, offset])	Like above, but searches the string backwards, starting from the right end, so it finds the last occurrence of the search string.
replace (pattern,repl_exp)	The target string is searched using the regular expression pattern defined by pattern. If a match is found, it is replaced by the substring defined by repl_exp, and returns the original string with replacements in it made according to pattern and repl_exp. The parameter repl_exp may be: • a simple string • a string with special regular expression replacement elements in it • a function that returns a value that may be converted into a string A full explanation of the powerful features of regular expressions is beyond the scope of this document. See any unix scripting manual. Simple examples: var rtn; var str = "aa bb cc bb dd"; var pat = /b(b)/g;  // the "(b)" is $1 below rtn = str.replace(pat, "zz"); // rtn = "aa zz cc zz dd" rtn = str.replace(pat, "B$1"); // rtn = "aa Bb cc Bb dd"
split (delimiter)	Spits a string into multiple substring values according to the specified delimiter, and returns the split values as an array which is typically assigned to an array variable, starting with element [0] and on for as many elements as are found. Example: var message="Now you too can learn to parse text" var word=message.split(" ") //word[0] contains "Now", word[1] contains "you",  etc
substr (start, length)	Returns a substring starting at position start and including the next number of characters specified by length. If start is positive, the position is relative to the beginning of the string. If start is negative, the position is relative to the end of the string. Examples: var str = ("0123456789"); str.substr(0, 5)  // == "01234" str.substr(2, 5)  // == "23456" str.substr(-4, 2) // == "56"
substring (from, up_to)	Returns a substring of a string starting at position start and going to, but not including, position up_to. Examples: var str = "0123456789"; str.substring(0, 5) // == "01234" str.substring(2, 5) // == "234" str.substring(0, 10) // == "0123456789"
toLowerCase()	Returns a copy of a string with all of the letters changed to lower case. Example: var myName = "John Smith"; eecummingsname = myName.toLowerCase(); // john smith
toUpperCase()	Returns a copy of a string with all of the letters changed to upper case. Example: var myName = "John Smith"; ShoutingName = myName.toUpperCase(); // JOHN SMITH

Boolean Properties and Methods

A Boolean data type may have only one of two possible values: false or true. Since values are automatically converted when appropriate, Booleans can be used as they are in languages such as C. Namely, false is zero, and true is non-zero. A script is more precise when it uses the actual values (false and true), but it will work using the concepts of zero and not zero. When a Boolean is used in a numeric context, it is converted to 0, if it is false, and 1, if it is true.

Conversely, when a non-Boolean data type is converted to a Boolean value (as in an "if" test), the value is converted as follows:

• Buffer    - same as for String
• null      - false
• Number    - false if value is 0, +0, -0 or NaN, else true
• Object    - true
• String    - false if empty string (""), else true
• undefined - false

Number Properties and Methods

A Number data type may be an integer or a floating point (exponential) value.

Integers
Integers are whole numbers. Decimal integers, such as 1 or 10, are the most common numbers encountered in daily life. There are three notations for integers: decimal, hexadecimal, and octal.

Decimal notation is the way people write numbers in everyday life and uses base 10 digits from the set of 0-9. Examples are:

1, 10, 0, and 999
var a = 101;

0x1, 0x01, 0x100, 0x1F, 0x1f, 0xABCD
var a = 0x1b2E;

00, 05, and 077
var a = 0143;

Decimal floats use the same digits as decimal integers but allow a period to indicate a fractional part. Examples are:

0.32, 1.44, and 99.44
var a = 100.55 + .45;

4.087e2, 4.087E2, 4.087e+2, and 4.087E-2
var a = 5.321e33 + 9.333e-2;

Date Properties and Methods
ECMAScript shines in its ability to work with dates. All standard ECMAScript date methods are supported, with the important exception that all month references start at 1 (for January) instead of 0, so you do not have to constantly remember to add 1 to the month value when using these methods.

To create a Date object which is set to the current date and time, use the new operator, as you would with any object.

var currentDate = new Date();

var aDate = new Date(milliseconds);
var bDate = new Date(datestring);
var cDate = new Date(year, month, day);
var dDate = new Date(year, month, day, hours, minutes, seconds);

Global Properties and Methods
The properties and methods of the global object may be thought of as global values and functions. The object identifier global is not required when invoking a global method or function. Indeed, the object name generally is not used.
 
 

Method Name	Description
eval(expression)	Evaluates whatever is represented by the parameter expression. If expression is not a string, it will be returned. For example, calling eval(5) returns the value 5. If expression is a string, the interpreter tries to interpret the string as if it were an ECMAScript statement and execute it. If successful, the method returns the last variable with which it was working, for example, the return variable. If the method is not successful, it returns the special value, undefined.
getArrayLength(array)	Returns the length (number of elements) of an array. This function should be used with dynamically created arrays, that is, with arrays that were not created using the new Array() operator and constructor. When working with arrays created using the new Array() operator and constructor, use the length property of the Array object. Example: var arr = {4,5,6,7}; arr_Len = getArrayLength(arr);  // 4
isNaN(value)	Returns a boolean value: true if value is not a number, else false. Example: function testNumber(numValue) {    if (isNan(numValue))        return "Not a number"    else       return "OK"; }
parseInt(str[, radix])	Returns the integer to which the target string converts, else NaN. This method converts an alphanumeric string to an integer number. The first parameter, str, is the string to be converted, and the second parameter, radix, is an optional number indicating which base to use for the number. If the radix parameter is not supplied, the method defaults to base 10 which is decimal. If the first digit of string is a zero, radix defaults to base 8 which is octal. If the first digit is zero followed by an "x", that is, "0x", radix defaults to base 16 which is hexadecimal. White space characters at the beginning of the string are ignored. The first non-white space character must be either a digit or a minus sign (-). All numeric characters following the string will be read, up to the first non-numeric character, and the result will be converted into a number, expressed in the base specified by the radix variable. All characters including and following the first non-numeric character are ignored. If the string is unable to be converted to a number, the special value NaN is returned. Example: var i = parseInt("9"); var i = parseInt("9.3"); // In both cases, i == 9
parseFloat(str)	Returns the floating point number to which the string converts, else NaN. This method is similar to global.parseInt() except that it reads decimal numbers with fractional parts. In other words, the first period, ".", in the parameter string is considered to be a decimal point, and any following digits are the fractional part of the number.

Other Standard Methods

For details on other standard ECMASCript methods not covered here, such as methods for the Math object, consult any comprehensive JavaScript or JScript manual, or see any of the following Web sites:

Netscape JavaScript Reference:
http://developer.netscape.com/docs/manuals/communicator/jsref/index.htm

Microsoft JScript Reference:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/js56jsoriJScript.asp

Web Developers Virtual Library (WDVL) - Authoring JavaScript
http://wdvl.internet.com/Authoring/JavaScript/

DevGuru JavaScript Quick Reference
http://www.devguru.com/Technologies/ecmascript/quickref/javascript_index.html

Using ODBC with Local SQL Databases

Scripts can now use ODBC connections and SQL statements to read and update local databases, such as a Microsoft Access database on a Windows PC, or an Oracle 9i Lite database on a Palm or Pocket PC handheld device. For a complete list of the currently supported properties and methods, see these documents:

ODBC Table of Contents

ODBC Index

ODBC Example

Jargon Reader supports a variety of properties and methods that have been developed by Jargon Software for host calls, graphical components and other specialized features. For a complete list of the currently supported properties and methods, see these documents:

Component Properties

Client Methods