OS/2 Shareware BBS: 3 Comm

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / tt2man.zip / ttautoi.doc < prev next >

Wrap

Text File | 1993-12-10 | 29KB | 705 lines

TABLE OF CONTENTS 10. AUTOPILOT Language Overview 10.1 Introduction 10.2 Support For The Presentation Manager 10.3 Running an AUTOPILOT Program 10.4 The AUTOPILOT Script Search Order 10.5 Compiling An AUTOPILOT Program 10.6 Language Conventions And Definitions 10.6.1 Tokens 10.6.1.1 Identifiers 10.6.1.2 Labels 10.6.1.3 Keywords 10.6.1.4 Numeric Constants 10.6.1.5 String Constants 10.6.1.6 Operators 10.6.2 Comments 10.6.3 Conversions 10.6.4 Numeric And String Expressions And Operators 10.6.5 Conditional Expressions And Relational And Logical Operators 10.6.6 Order Of Precedence 10.6.7 Scope Of Identifiers 10.6.8 Syntax Notation 10.6.9 Customization Variable Access 10.6.10 Passing Variable Information 10.7 Definition Of Terms 10. AUTOPILOT Language Overview 10.1 Introduction AUTOPILOT is a fully functional language which, because of its interpretive nature, makes it very useful in general OS/2 tool building applications. The next three chapters are devoted to presenting the entire wealth of programming, communications, and OS/2 features and functions available within AUTOPILOT. The AUTOPILOT language is interpretive. Sequences of automated commands and responses (often called scripts) between the PC and Host are stored as text files on the PC. The remainder of this chapter provides a description of the AUTOPILOT language conventions. The next chapter provides a brief description of the AUTOPILOT Statements ordered by Category Of Function (i.e. String Manipulation, Arithmetic, etc.), and the last two Chapter provides a detailed listing, in alphabetical order, of every statement available. 10.2 Support For The Presentation Manager Since AUTOPILOT was originally architected for the PC/DOS environment, it contains a large number of statements which deal with the Presentation Space as if it were a Fixed Font, 80 Column, 25 Row environment (the size of the PC/DOS Screen). To allow the immediate support for AUTOPILOT applications developed under PC/DOS to run under OS/2, AUTOPILOT, when it encounters the first Statement addressing the PC/DOS Screen, provides a Fixed Font, 80 Column by 25 Row Presentation Manager Window. This allows ALL AUTOPILOT Statements which address the PC Screen (i.e. DISPLAY, CLS, COLOR) and which interact with the user (i.e. PROMPT, MOUSE Movement) to deal with the OS/2 environment exactly as they had in PC/DOS. Also, since this window is owned by the Presentation Manager window, you do not sacrifice the aesthetics, multi-tasking, and consistency provided by it. In order to expand upon the capabilities of TalkThru in the Presentation Manager environment, new Statements have been added to allow for the Creation, Sizing and Movement of PM Windows over and above what would have been meaningful in PC/DOS. For more information on the Statements implemented to support the Presentation Manager directly, refer to the Section, Managing Presentation Manager Windows, in the Chapter, AUTOPILOT Statements By Category. 10.3 Running an AUTOPILOT Program In TalkThru, AUTOPILOT programs can be requested in three ways: 1. From a Phone Book by indicating its name in the Initialization Script or Process dialog during Phone Book Entry Add or Change. Refer to the Chapter, The Phone Book for more information on how this is done. 2. From any Presentation Manager Menu or OS/2 Full Screen session by using the following syntax: ┌──────────────────────────────────────────────────────────────────────┐ │ TT2PILOT <program-name> [Arguments ... ] │ └──────────────────────────────────────────────────────────────────────┘ 3. From a Terminal Emulator Assigned Key or Terminal Window Button. Choose Keyboard or Buttons from the Settings pull down menu on any Phone Book or Terminal Emulator window. 10.4 The AUTOPILOT Script Search Order When AUTOPILOT runs a script, it uses the following search algorithm to find the script file: 1. If the script file specification includes a directory, the script file must reside in that directory. No other directories will be searched. 2. If the script file specification does not include a directory, directories are searched in the following order: o The directory of the parent script (this only applies to scripts that were called from another script). o The directory specified by the SCRIPT_DIRECTORY Customization Variable. o The directories specified by the SCRIPT_ALTPATH Customization Variable. If no extension is specified on the script name, files with an extension of .CMP (compiled scripts) are searched first and files with an extension of .SCR (source scripts) are searched next. 10.5 Compiling An AUTOPILOT Program AUTOPILOT Programs may be compiled into a small execution-only format. The advantages of compiling AUTOPILOT Programs are: 1. Compiled programs are "execution-only". They cannot be read or modified. 2. Compiled programs load faster. Large programs will usually load 3 to 4 times faster. 3. Compiled programs take up less disk space. Large programs will usually take at least 33% less disk space. 4. There are improvements in run-time speed and memory requirements. Compiled programs may be used interchangeably with normal AUTOPILOT Programs. They may call, be called from, INCLUDE or be INCLUDEd in, other AUTOPILOT Programs. GLOBAL identifiers may be used with no constraints. NOTE: It is highly recommended that you do your AUTOPILOT development in source form. If a run-time error occurs during the execution of a compiled AUTOPILOT program, the usual error display is presented. However, since the original source file is not available, the line in error is always reported as line 1. AUTOPILOT Programs may be compiled by invoking the following program: ┌──────────────────────────────────────────────────────────────────────┐ │ TT2SCOMP <input-file> <output-file> │ └──────────────────────────────────────────────────────────────────────┘ <input-file> is a standard AUTOPILOT program file. The default directory is the directory specified in the TalkThru Customization File variable as SCRIPT_DIRECTORY. <output-file> is the name of the compiled program you wish to create. The default directory is the same as <input-file>. There are no name restrictions though it is highly recommended that you use the extension .CMP. This is because the AUTOPILOT search algorithm (if no extension is supplied on a file name) is to search for a file with the extension of .CMP first and .SCR second. Examples: Example1: TT2SCOMP test.scr test.cmp In this example, test.scr MUST EXIST in the directory indicated by the SCRIPT_DIRECTORY Customization Variable. test.cmp would be placed in the same directory. Example2: TT2SCOMP c:\source\test.scr c:\compiled\test.cmp In this example, the source and compiled programs of an application are being isolated so that development and production environments can be separated. 10.6 Language Conventions And Definitions ┌───────────────┐ │ 10.6.1 Tokens │ └───────────────┘ There are six classes of tokens: Identifiers, Labels, Keywords, Numeric Constants, String Constants, and Operators. Blanks, tabs, newlines, and comments may be used to separate tokens. ┌──────────────────────┐ │ 10.6.1.1 Identifiers │ └──────────────────────┘ An identifier is a name used to uniquely identify a variable field. Letters, digits, and underscores (_) may be used. The first character must be a letter. Only the first eight characters are significant, although up to 250 may be used. Upper and lower case are the same. ┌─────────────────┐ │ 10.6.1.2 Labels │ └─────────────────┘ A label is a logical name used to identify a particular point in the program text. Its format is the same as that of an identifier with a colon (:) appended. Labels, when used as an object of a GOTO, PERFORM, etc., should not have a trailing colon. Labels may be assigned to variables. They may not be used in arithmetic expressions. The following program fragment is valid: IF Y = 1 GOTO L1 SET A = L1 GOTO A L1: DISPLAY "HERE WE ARE" ┌───────────────────┐ │ 10.6.1.3 Keywords │ └───────────────────┘ The keywords reserved in the AUTOPILOT language are listed in the Appendix, AUTOPILOT Reserved Words in this manual. Keywords may be specified in upper or lower case. ┌────────────────────────────┐ │ 10.6.1.4 Numeric Constants │ └────────────────────────────┘ Numeric constants may be specified as a sequence of characters representing a number in the form 999.99. A leading sign, '+' or '-', is allowed. The decimal point is optional. If it is specified, at least one digit must follow. A sequence of characters that starts with a ^H or ^h (carat H) indicates a hexadecimal number. For example a decimal 511 can be written as ^h1FF and a decimal 10 as ^ha. ┌───────────────────────────┐ │ 10.6.1.5 String Constants │ └───────────────────────────┘ A string constant is a sequence of characters surrounded by double quotes, as in "This is a string". If a double quote is to be used as a character in a string constant, it must be written as two adjacent double quotes. The maximum size of a string constant in AUTOPILOT is 250 bytes. Any character in a string may be represented in hexadecimal format by specifying a leading ^H or ^h followed by two hexadecimal characters. For example, an ASCII line feed could be imbedded in a string as "This is Line 1^H0A and this Line 2". A ^ (carat) may be specified as a ^^. A control character may also be imbedded in a string by following a ^ with a letter. For example a Control B may be imbedded as "Here is a Control-B -->>^B<--". A string constant may be up to 250 characters in length (not including the surrounding double quotes). ┌────────────────────┐ │ 10.6.1.6 Operators │ └────────────────────┘ There are five types of operators: arithmetic, string, relational and logical. Arithmetic Operators: + addition - subtraction / division * multiplication \ integer division MOD modulo arithmetic String Operators: & concatenation Relational Operators: >> greater than >>= greater than or equal to = equal to <= less than or equal to < less than <> not equal to IS used in attribute testing ISNOT Logical operators: AND Logical AND OR Logical OR NOT Logical NOT BITAND Bitwise AND operator. Compares each bit of its first operand to the corresponding bit of its second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise the corresponding result bit is set to 0. BITOR Bitwise inclusive-OR operator. Compares each bit of its first operand to the corresponding bit of its second operand. If either bit is 1, the corresponding result bit is 1. Otherwise the corresponding result bit is set to 0. BITXOR Bitwise exclusive-OR operator. Compares each bit of its first operand to the corresponding bit of its second operand. If one bit is 1 and the other bit is 0, the corresponding result bit is set to 1. Otherwise the corresponding result bit is 0. BITNOT Bitwise complement operator. Changes each bit of a single operand. If the bit is 0, the corresponding result bit is set to 1. Otherwise the corresponding result bit is set to 0. ┌─────────────────┐ │ 10.6.2 Comments │ └─────────────────┘ Comments do not affect the execution of a program, they are used only for documentation purposes. There are two methods of commenting: o A block comment may be created by using the characters /* to start a comment and the characters */ to end a comment. Block comments may be nested. o A single line comment may be created by using the ; character to start the comment. All characters to the end of the line are considered part of the comment. ┌────────────────────┐ │ 10.6.3 Conversions │ └────────────────────┘ A number of operators and commands may, depending on their operands, use a converted value of an operand. Arithmetic operators or commands where the operand must assume a numeric value will cause a string value to be converted to a numeric value. If the string value is not in a correct numerical format the value of zero will be used. For example, "+123.07" will be converted to 123.07, "dog" will be converted to zero. String operators or commands where the operand must assume a string value will cause a numeric value to be converted to a string value. For example, 123.07 will be converted to "123.07". In relational operations, the constants on each side of the operator must be of the same format. If they are not, the one to the right of the operator will be converted to the same format as the one on the left. No justification or padding will occur. For example, in the following instructions: set A = "007" /* Set a character constant */ set B = 7 /* Set a numeric constant */ if A = B goto label the comparison would fail because "007" is not equal to 7. But if the comparison read: if B = A goto label it would succeed because "007" would be successfully converted to a numeric constant of 7. ┌─────────────────────────────────────────────────────┐ │ 10.6.4 Numeric And String Expressions And Operators │ └─────────────────────────────────────────────────────┘ An expression may simply be a numeric constant, a string constant, a variable, or a function. It may also be used to combine constants, variables and functions to produce a single value. Arithmetic operators perform operations such as addition, subtraction, and multiplication. They all produce a value that is a number. Operator Operation Sample Expression * Multiplication X * Y / Floating Point Division X / Y \ Integer Division X \ Y MOD Modulo Arithmetic X MOD Y ++ Addition X + Y - Subtraction X - Y & Concatenation "The Value Is " & X Integer division is denoted by the backslash (\). The operands are rounded to integers before the division is performed and the quotient is truncated to an integer. For Example: 13 \ 3 = 4 13.7 \ 3.9 = 3 Modulo arithmetic is denoted by the operator MOD. It gives the integer value that is the remainder of an integer division. For example: 13 MOD 3 = 1 13.7 MOD 3.9 = 1 There is one string operator called concatenation. Concatenation is the joining together of two strings and is signified by the ampersand (&) symbol. ┌─────────────────────────────────────────────────────────────────────┐ │ 10.6.5 Conditional Expressions And Relational And Logical Operators │ └─────────────────────────────────────────────────────────────────────┘ A conditional expression has a value of true or false. It may be simply an expression or it may be expressions combined with relational and/or logical operators. The result is usually used to make a decision regarding program flow. (See the IF Statement). Relational operators compare two values. The value may be either numeric or string. If one value is numeric and the other value is string, the operand to the right of the relational operator is converted to the same type as the operand to the left of the operator. The result of the comparison is either true or false. Operator Relation Tested Sample Expression = Equality X = Y <> Inequality X <> Y < Less than X < Y > Greater than X > Y <= Less than or equal to X <= Y >= Greater than or equal to X >= Y IS Test for specific X IS Y ISNOT bit values X ISNOT Y String comparisons are essentially alphabetical. The ASCII codes of each character are compared. If all the ASCII codes are the same, the strings are equal. Otherwise, as soon as the ASCII codes differ, the string with the lower code is considered less than the other string. The IS and ISNOT operators are special operators generally used to test screen attributes (see the ATTRIBUTE function). Essentially, the operators test bit masks though it is not necessary to know how the operators work to test attributes. The first operand is considered the value to be tested. It is converted to an 8 bit integer. The second operand is the mask that the first operand is tested against. It is converted to a 16 bit integer where the high order 8 bits signify which bits are to be tested and the low order bits are the value those tested bits must have. More specifically, the operators do a logical AND between operand 1 and the high order 8 bits of operand 2 and compares the result of this value with the low order 8 bits of operand 2. If the comparison is equal then the condition is TRUE for IS and FALSE for ISNOT. If the comparison is not equal, the condition is TRUE for ISNOT and FALSE for IS. For example, to see if bit 1 and bit 3 are set to 1 and bit 2 and bit 5 are set to 0, the following test could be used. X IS ^H1705 If a conditional expression is a simple expression, that is, one without a relational operator, then it is considered true if the expression is not equal to zero and false if the expression is equal to zero. If the expression returns a string value then it is considered true if the length of the string is greater than zero and false if the length of the string is equal to zero. Logical operators are used to connect two or more relations and return a true or false value to be used in a decision. The logical operators are NOT, AND, and OR. Some examples of logical operators in an IF statement: IF x > 10 AND x < 20 . . . IF y = 1 OR Y = 2 OR Y = 3 . . . IF NOT FOUND . . . IF ATTRIBUTE IS _PROTECTED AND ( HOST_CURSOR_ROW < 5 OR HOST_CURSOR_ROW >> 20 ) . . . ┌────────────────────────────┐ │ 10.6.6 Order Of Precedence │ └────────────────────────────┘ Expressions are evaluated from left to right with the following order of precedence assigned to the operators: Level Operator Name 1 () Function,Array 2 - Arithmetic Negation 3 NOT Logical NOT BITNOT Bit testing 4 * Multiplication / Division \ Integer MOD Remainder BITAND Bit testing 5 + Addition - Subtraction 6 & String Concatenation 7* < Less than > Greater Than <= Less than or equal to >= Greater than orequal to = Equality <> Inequality IS Attribute testing ISNOT Attribute testing 8 AND Logical AND OR Logical OR 9 = Simple Assignment * <_>"NOT" may appear in front of any of the level 7 operators. ┌─────────────────────────────┐ │ 10.6.7 Scope Of Identifiers │ └─────────────────────────────┘ Identifiers used within one program are not associated in any way with identifiers used in another program unless specified as GLOBAL. See the GLOBAL statement for more information. Labels from one program are never associated with labels from another program. ┌────────────────────────┐ │ 10.6.8 Syntax Notation │ └────────────────────────┘ CAPITALIZED WORDS indicate language keywords which should be regarded as being reserved for their specified use except when used in a quoted character string. Words between < and > signs indicate a value which should be either a "numeric expression", "string expression" or "key". The meaning of these three is explained in the Definition of Terms section of this chapter. The characters , = + - / * < > & \ are reserved words whose meaning is defined in the Language Conventions and Definitions section of this chapter. Operands or expressions within chain brackets, { and }, are optional values, one of which must be encoded into the statement being constructed. If one of the optional values is underlined then that value is the default and may be omitted. An operand or expression within square brackets, [ and ], may be regarded as optional to the statement being constructed. A string of periods, ..., following an item indicates that it may be repeated a number of times. ┌──────────────────────────────────────┐ │ 10.6.9 Customization Variable Access │ └──────────────────────────────────────┘ The value of a Customization Variable defined in the TalkThru Customization File (issued as TALKTHRU.DEF and modified by selecting System Configuration from the Utilities pull down menu on any Phone Book), may be accessed in a program with the following construct: %<variable_name> where <variable_name> is defined in the TalkThru Customization File. For example, assuming that the statement DATA_DIRECTORY=C:\TALKTHRU\DATA is in the TalkThru Customization File, the program statement IF %DATA_DIRECTORY="C:\XXXXX" is equivalent to if "C:\TALKTHRU\DATA" = "C:\XXXXX" ┌──────────────────────────────────────┐ │ 10.6.10 Passing Variable Information │ └──────────────────────────────────────┘ Variable information can be passed to AUTOPILOT Programs from OS/2 and can be passed from one AUTOPILOT Program to another. AUTOPILOT Programs reference parameters passed by using a special identifier format of %n, where n is a number from 1 to the number of parameters passed. Also, %0 will contain a number from 0 - n indicating the number of parameters passed How variables are passed and the AUTOPILOT syntax to reference them is best presented as an example. If the following OS/2 Command TT2PILOT sample.scr ABC was issued, and sample.scr was written as SET inparm = %1 ; %1 is the parameter passed the value of inparm would be "ABC". If sample1.scr were written as set parm = "XYZ" run script "sample2.scr" using "ABC" , parm and sample2.scr were written as set inp1 = %1 set inp2 = %2 inp1 would be "ABC" and inp2 would be "XYZ" WARNING: If a %n value is not passed to a script, the default value for any %n variable is zero. 10.7 Definition Of Terms The terms number, string, and key appear throughout this guide. For the purposes of the AUTOPILOT language, they have the following definition: number A numeric expression. Any expression, constant, function, or identifier. String values will be converted to numeric values. String values which are not in proper numeric format will be converted to zero. The following examples are all valid representations of the number 10. 10 "10" LEN("abcdefghij") STR_LEFT("10xxxxx",2) string A string expression. Any expression, constant, function, or identifier. Numeric values will be converted to string values. The following examples are all valid representations of the string "3270". "3270" 3270 STR_LEFT("3270xx xx" ,4) key A 3270/Asynchronous key or function key ATTN BACK_TAB BACKSPACE BACKTAB BREAK CLEAR CURSOR_SEL DEL_LINE DELETE DELETE_LINE DOWN DUP ENTER ERASE_EOF ERASE_EOL ERASE_EOS ERASE_INPUT FM HOME INS_LINE INSERT INSERT_LINE KEYPAD_01 KEYPAD_02 KEYPAD_03 KEYPAD_04 KEYPAD_05 KEYPAD_06 KEYPAD_07 KEYPAD_08 KEYPAD_COMMA KEYPAD_ENTER KEYPAD_MINUS KEYPAD_PERIOD LEFT NEWLINE PA1 PA2 PA3 PF1 PF10 PF11 PF12 PF13 PF14 PF15 PF16 PF17 PF18 PF19 PF2 PF20 PF21 PF22 PF23 PF24 PF3 PF4 PF5 PF6 PF7 PF8 PF9 POWER_UP RESET RIGHT SEND_LINE SET_MODE SYSREQ TAB UF10 UF11 UF12 UF13 UF14 UF15 UF16 UF17 UF18 UF19 UF20 UF6 UF7 UF8 UF9 UP Or, An ASCII Control Code (Asynchronous only). ACK BEL BSC CAN CR DCn DEL DLE EM ENQ EOT ESC ETB ETX FF FS GS HT LF NAK NUL RS SI SO SOH STX SUB SYN US VT XON XOFF