SMS Interfaces
AWES Language Reference

Overview

It is helpful to know something about HTML Forms in order to understand the AWES scripting language. The scripting language allows you to automate actions on HTML Forms as well as click on HTML links and read text from a Web page. A line of AWES script will begin with a command followed by the target (or argument) of that command. Some command do not require a target. The script itself is saved with the extension .awe . Syntax: Command [1st target] [2nd target (if needed)] Conventions Numbers are usually enclosed in parentheses and text is usually enclosed in quotes. Elements in a form are referred to by using the word "Element" followed by the element number in parentheses e.g Element(7). The same is true of form Options e.g. Option(10). Concatenation of stings (for the Respond command) is done using the ampersand (&). Command targets are separated by a single space. Case is ignored. Although this document capitalizes all commands this is arbitrary and you may also write commands in lower case. Brackets [] are used in this document to separate command arguments but these are not to be used with the actual command. The word "command" and "statement" are used interchangeably. Errors Error messages will occur if there is a problem with executing your script. If the term "Fatal Error" is used this means that the script could not continue executing. You must then correct the error before proceeding.

- Variables -

The AWES language comes equipped with its own system variables that you can use to temporarily store information for both input (information coming into the system from a user such as a cell phone text message) and output (information gathered by the system that will be sent to the user). These variables are as follows. InWord[1-5] InWords are special input variables and are actual text boxes that appear on the AWES screen. You can populate these boxes yourself with words that would correspond to the words of an incoming text message. This will enable you to test the behavior of your script once it has been deployed on the AWES gateway. There are 5 InWord variables. They are referred to as: InWord1, InWord2, InWord3, InWord4 and InWord5 (no spaces between INWord and the following number). InWord cannot be used by itself and must always be followed by a number. Incoming Text commands are usually composed of 2-3 three words (e.g. get weather) but the AWES system supports up to 5 words. A phrase can also be used by enclosing a group of words in quotes. This counts as one word and will be stored as a phrase in one InWord variable. The Word() Array The Word() array is populated whenever a GetWords command is encountered in your script. It is a zero based array that holds a list of the words on the currently loaded Web page. Depending on the Web page a Word may contain a punctuation character at the beginning or the end of the Word. These characters are ignored unless you are using the FindMarker command. You can use the Word() array to gather information from the Web page based on the position of the words and their proximity to other characters used as "markers". For example Word(10) may hold the word "international". WordNum The WordNum variable holds a number that corresponds with your current position in the Word() list. For example suppose you have an incoming text message for retrieving the phone number of a local McDonalds. The message may be "lookup McDonalds 90621". In this case InWord1=lookup, Inword2=McDonalds and InWord3=90621. After accessing the proper page you may use the Find command as follows: Find InWord2. If it was found on the page at Word(48) the value of WordNum would then be 48. If you used FindNext and it was found again, the value of WordNum would change to the next position at which the word was found in the list. If the word is not found then WordNum is set to one more than the position of the highest word in the list. The WordNum variable basically keeps track of your current position as you search through the list of words. You could then use the SET command (see below) to store that word position in an OutWord variable. When referencing WordNum in your script it must always be used in connection with a word in the Word() array and enclosed in parentheses. The only exception is if you are viewing its current value using the View WordNum command. Example: Respond Word(WordNum) OutWord[1-10] OutWords are variables that will allow you to hold words from the Words() list as you are interacting with your target Web page(s). These words can be sent to the user's cell phone using the Respond command. There are 10 OutWord variables that you can use: OutWord1, OutWord2, OutWord3, OutWord4, OutWord5, OutWord6, OutWord7, OutWord8, OutWord9 and OutWord10. OutWord cannot be used by itself and must always be followed by a number. No spaces are allowed between "OutWord" and the number. OutWords are populated by using the SET command (see below). Example: Set OutWord3 WordPhrase WordPhrase is a special variable that will output a group of words from the word list starting with the WordNum position at the time the SET command was used. The phrase is terminated when a blank, period, question mark or exclamation point is encountered. WordPhrase is limited to 150 characters. Example: Set WordPhrase The SET Command The SET command allows you to set the OutWord[1-10] and WordPhrase variables to the current word in the list based on current value of the WordNum variable. Example: Set OutWord1

- Commands -

The following commands (or statements) may be used in your script for directing the AWES system in performing automated actions on Web Pages. ID [identification number] The ID statement must always be the first line in your script and will contain your product registration number. Example: ID 12345678 ' (apostrophe) The apostrophe denotes a comment line. A comment must be on a line by itself but may appear anywhere in the script. Example: 'Your comment here USE [command word]-ONFAULT-ENDUSE These three commands are typically used together. The AWES system will Process a section of the script only if the word following the USE statement matches InWord1 (the first word of the incoming message). The first word of an incoming message is usally considered the "command" word. The section that executes (if there is a match) is terminated when an ENDUSE statement is encountered. If there is no match then the entire section is skipped. If an ONFAULT statement is encountered then the section from the ONFAULT to the ENDUSE statement is executed if an error occurs, such as a word is not found. You can think of this as being similar to an If-Else-EndIf construct. In the example below the message could be like: getphone dennys 90621 (where getphone is the "command" word). You could populate the InWord boxes as follows: Inword1=getphone, Inword2=dennys, Inword3=90621 . The use of "getphone" is arbitrary. You could just as easily use "lookup" or any other word as a trigger. A script may contain multiple USE statements for performing different functions based on the incoming command word. Example: USE getphone GETURL http://www.smartpages.com (more script lines here ...) ONFAULT (more script lines here ...) ENDUSE GETURL [URL] Loads the target URL to be processed. Example: GETURL http://www.smartpages.com GETWORDS Gets all the words from the currently loaded Web page and assigns a number to each one. These words are itemized in the Word() array (see Variable section). This command must be run before attempting to reference words on a Web page or an error will occur. Using this command will reset all form elements so any information entered into a form will be lost. No arguments are needed for this command. Example: GETWORDS GETFORM() Indicates the number of the form that following actions will effect. If omitted then Form(0) is used. Getform takes just one argument - the number of the form enclosed in parentheses. Example: GETFORM(1) TYPE [text or InWord variable] [element()] This command is used to type directly into a text box on a form. The words to be typed should be enclosed in quotes and followed by the element number of the text box you will be typing into. InWord variables can also be used. You should use Analyze Form to determine the element number of the text box. You should have indicated the form number on a previous line of your script or Form(0) will automatically be used. Example: TYPE "dennys" element(2) TYPE InWord2 element(4) CLICK [element()] This command can be used on clickable form elements. The most common would be to click on a submit button but it can also be used to click a radio button or checkbox based on its element number. You should use Analyze Form to determine the element number you need. You should have indicated the form number on a previous line of your script or Form(0) will automatically be used. IMPORTANT: The CLICK command cannot be used to navigate to a page link. For that use the LINKTO command. Example: CLICK Element(3) IMAGECLICK [name] This is a special command for when an image has been used for a submit button. When this technique is used on a form the conventional element number is not assigned, therefore the only way to automate the button click is by using its name. You can determine if a form uses this technique by noting that the submit button is absent from the element list when you analyze the form. If you go to the bottom of the form analysis output you can find the actual name of the button (usually "submit") and use that name with the IMAGECLICK command. You should have indicated the form number on a previous line of your script or Form(0) will automatically be used. Example: IMAGECLICK submit SELECT [element()] [option()] This command allows you to make a selection from a drop down menu on a form. It has two targets: the element number and the option number. The Element number is the number of the drop down box on the form and the option number is the number of the selection from 0 to last. You should use Analyze Form to determine the element number and option you need. You should have indicated the form number on a previous line of your script or Form(0) will automatically be used. Example: SELECT Element(4) Option(5) LINKTO [link()] This command allows you to go to a link within a Web page. Keep in mind that menu items are usually comprised of individual links. This is how you would navigate to those pages. Use the keyword "Link" instead of "Element" to denote the target. The link number should be enclosed in parentheses. Example: LINKTO Link(120) FIND [word to find] [starting position] Finds the number of a Word on a page and puts its reference number into the WORDNUM script variable. The first argument can be a text string such as "McDonalds" (enclosed in quotes ) or an InWord variable (see Variable section). The starting number for the search can be specified by denoting the Word number enclosed in parentheses. If none is specified then Word(0) is used as the starting position. Example: Find "Dennys" Word(11) Find InWord3 Word(50) FINDNEXT [blank, nonblank or marker] Finds the next position of the word used in the previous find command. This command also takes the optional arguments "blank", "nonblank" or marker. In the word list generated by the GETWORDS command there will be blank spaces between groups of words. When this argument is used it will find the next blank or nonblank word starting from your current position. This can be used for orienting yourself in the word list. You may also use "marker" as an argument in order to find the next marker (single character) when the FINDMARKER has been used on a previous line. Example: FINDNEXT nonblank FINDNEXT marker FINDMARKER [character] Looks for a single punctuation character (except for a quote which is a reserved character) either at the beginning or ending of a word in the Word() array. It will also find a single character on a line by itself. This command is usually used for marking a spot for orientation within the word list. If no marker character is specified then a period is used as a default. When the marker is found the WORDNUM variable is set to that position. Example: FINDMARKER ! SET [variable name] The set command is used to set the variable WORDPHRASE or the OutWord1-OutWord10 variables (see Variable section) to the current position of a word found in the Word() array. Example: SET OutWord1 VIEW WORDNUM Shows the current numerical value of the WordNum variable. System waits for 5 seconds to give you a chance to view it before proceeding to the next line. Useful for viewing the position of a word within a page after using the FIND command. Best used for debugging purposes and should not be part of your final script. Example: VIEW WORDNUM DELETE COOKIES Deletes all internet cookies residing on your computer. This command should be used if cookies that have been set are intefering with the processing of your script. Example: DELETE COOKIES OUTPUT[s] When this command is encountered all messages from the Status and Response box will be output to the the Information window. This is useful for debugging purposes. If an "s" is added to the end then the output of the RESPOND command will be saved to the file AWES_Responses.txt on your computer. Example: OUTPUTs RESPOND [text or variable] [&] This command is used for sending a response back to a user's cell phone based on the results of the processing done by your script. Each word or variable after the RESPOND command MUST be separated by an ampersand (&). You can used text enclosed in qoutes, OoutWord variables or InWord variables that have been previously populated. You may also use word values themselves such as Word(28). In order to output words in relative positions you may also use addition or subtraction within the Word() variable such as Word(23+5). Example: Respond "The phone number for " & InWord2 & " is " & OutWord1 RUNCYCLE [interval] This command can be used to run your script automatically to regular intervals in increments of one minute. You can specify an interval of 10 minutes or more after the RUNCYCLE command. The command may appear anywhere in your script. You will need to run the script manually the first time to initiate the command. IMPORTANT: If you have used the OUTPUTs command in your script the output file could eventually fill up with responses to the point that the file size exceeds your disk space. As long as you monitor the output file (AWES_Responses.txt) and delete it periodically this should not be a problem. To turn off RUNCYCLE you can use RUNCYCLE off. Example: RUNCYCLE 15 BROADCAST [filename] This command will broadcast the message indicated by the RESPOND command to a list of cell phone numbers. The BROADCAST command must ALWAYS appear after the RESPOND command in your script since the latter is used to populate the outgoing message. The broadcast file should be a standard ASCII text file and the numbers must be listed one per line. Example: BROADCAST numbers.txt END When this command is encountered the script will stop processing. Usually used for debugging purposes. It is not necessary to include this at the end of your script. Example: END Sample Script ID 12345678 'This script will return the temperature based on a zip code 'From a cell phone type: temp 90621 (for example) output use temp geturl http://www.cnn.com/WEATHER/ getform(2) type inword2 element(0) click element(1) getwords find "current conditions" findnext nonblank findnext nonblank set outword1 findnext nonblank findnext nonblank set wordphrase Respond "Current Conditions:" & OutWord1 & "and" & InWord5 & WordPhrase & InWord4 OnFault Respond "Nothing found" EndUse

Click Here for AWES Introduction