Black Box 4

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

/ Black Box 4 / BlackBox.cdr / os2 / te2_120.arj / SCRIPT.DOC < prev next >

Wrap

Text File | 1992-06-15 | 102.2 KB | 2,371 lines

TE/2 Script Language Reference Oberon Software 518 Blue Earth Street Mankato, MN 56001-2142 Last Revision: June 15, 1992 ------------------------------------------------------------- Copyright 1990-92, Oberon Software, Mankato, MN - All Rights Reserved ------------------------------------------------------------- ---------------------------------------------------- Notice: Information in this document is subject to change without notice and does not constitute a commitment on the part of Oberon Software. ---------------------------------------------------- General: ======== A TE/2 script file is a flat ASCII file containing TE/2 script commands. Each line in the file must be terminated with either a carriage return-line feed pair or with a single line feed. No line may be longer than 256 characters in length, a line longer than 256 characters will generate an error message and terminate execution of the script. The TE/2 script language is not case sensitive, identifiers, keywords, functions, et al may be entered in either upper or lower case in any mixture. Identifier names (variables, subroutine names) have no formal length restriction except as relates to the line length restriction given above. Blank lines within the script file are ignored as are any leading or trailing space or tab characters on a line. You may indent and space the file any way you please for readability purposes. The semicolon is the comment mark character. Any and all text on a line including and following a semicolon (;) is ignored. The obvious exception to this is when the semicolon appears within a quoted string. REXX/2 Language Scripts ======================= In addition to the script language syntax described in this document, you may also create your scripts using the REXX Procedure Language. You must be operating under a version of OS/2 which supports REXX to use this feature. Because TE/2 sets itself up as the default addresssing environment when it executes a REXX procedure, all of the functions described later in this document are available also to the REXX script as are most of the TE/2 built-in and system variables. You are referred to the section of this document titled "Notes on REXX Scripts" for further information. Executing a script: =================== A script file may be executed in one of four ways: 1) Type Alt-/ (Alt-Slash) in terminal mode, at the "Command:" prompt type "call filename" where filename is the full file name (including path and extension) of the script to execute. 2) Associate a script file name (once again, full path and extension) with a dialing directory entry and make connection with that number. 3) Assign the "call" command to a TE/2 function key. Set the macro associated with the function to to "!call filename". Note that ANY script command may be associated with a function key using the exclamation point as the leading character. 4) Run a script automatically when TE/2 starts using the "-mfilename" command line parameter. Note that there is one "magic" script file name "TE2START.SCR" which TE/2 will always execute automatically at startup if it finds it on the script path. Program structure: ================== The general structure of a TE/2 script file is thus: variable declarations/definitions subroutine definitions program body Constants: ========== Numeric Constants ----------------- Numeric constants are 32 bit, signed quantities. A numeric constant may be expressed in standard decimal, hexadecimal, or octal notation and may range from -2147483647 to 2147483647. Some examples of numeric constants are: 32, -768, 0x1b, 0333, 0x12345678 There are several built in numeric constants. The most important of these are TRUE (1) and FALSE (0). There are others that are designed for special purposes, these will be covered in the appropriate sections. Table 1 contains a list of these constants. Table 1. -- Built in numeric constants --------------------------------------- ansi_bbs ansi_te2 ascii false ifcarrier query toggle true tty vt100 xmodem xmodem1k ymodem ymodemg zmodem Character Constants ------------------- Character constants are really just a special method of specifying an numeric constant. A character constant is any single character between a pair of single quote marks (') or any two character Control Character sequence (See Table 2. below) between a pair of single quotes. The result is the ASCII value of the specified character and it may be used anywhere a numeric constant or variable is allowed. To specify the ASCII value of the single quote character (39), simply use a sequence of three single quotes. Note that the character constant 'A' is exactly equal to ASCIIVAL("A") (See function ASCIIVAL below). String Constants ---------------- String constants are any string of ASCII characters delimited before and after with double quote marks ("). To embed a quote mark in a string use a sequence of two double quotes. For example: "This string has ""quotes"" embedded into it." String constants should not exceed 256 characters in length. This is not a hard and fast rule though exception handling for long strings may be less than robust at this point. The carat (^) character is treated specially, use it to embed control characters into a string. Table 2 lists all of the valid conversions. If a carat character appears in any other situation in a quoted string it is ignored. Note that ^! yields character 94 which is itself the carat character, thus "^!" is the method of embedding the carat character itself into a string. "^`" is a space character, this is interesting but not very useful. Table 2. -- Control character conversions -------------------------------------------------------------- ^@ 0 ^L or ^l 12 ^X or ^x 24 ^A or ^a 1 ^M or ^m 13 ^Y or ^y 25 ^B or ^b 2 ^N or ^n 14 ^Z or ^z 26 ^C or ^c 3 ^O or ^o 15 ^[ 27 ^D or ^d 4 ^P or ^p 16 ^\ 28 ^E or ^e 5 ^Q or ^q 17 ^] 29 ^F or ^f 6 ^R or ^r 18 ^^ 30 ^G or ^g 7 ^S or ^s 19 ^_ 31 ^H or ^h 8 ^T or ^t 20 ^` 32 ^I or ^i 9 ^U or ^u 21 ^! 94 ^J or ^j 10 ^V or ^v 22 ^K or ^k 11 ^W or ^w 23 There is one built in string constant, "null" which specifies the absence of a string. Note that "null" is not the same as the string constant "". The later is a representation of the empty string whereas "null" is no string at all; several functions in the TE/2 script language will make a distinction. Variables: ========== Variable types and scope: ------------------------- User defined variables may be either string or integer variables. An integer variable is capable of holding a signed, 32 bit quantity - the same as the numeric constants mentioned above while a string variable may refer to anything expressible with a string constant. Variables may be local or global in scope. If a variable is local, it is in effect for the current script file only; it is released when the script file ends execution and it is not available in any nested script file execution. If a variable is global, it is in effect from the instant it is declared until TE/2 ends execution and exits back to the OS/2 prompt and it is available to any script file that executes thereafter and may even be used at the "Command:" prompt. Declaring variables: -------------------- Variables are declared in the first section of the script file, anywhere before the "PROGRAM" statement except in a "SUBROUTINE" .. "ENDSUB" block. A variable declaration has the following form: [GLOBAL] type name [ = expression ] If the "GLOBAL" scoping modifier is omitted, the variable is local in scope. "type" is either "INTEGER" or "STRING". A variable name must begin with an alphabetic character ("A" through "Z"), be comprised entirely of alphanumeric characters ("A" through "Z" plus "0" through "9"), and must not conflict with a TE/2 keyword or predefined variable. If a GLOBAL variable name coincides with another GLOBAL variable already defined in another script file, it will refer to the same entity. If a LOCAL variable has the same name as an already defined GLOBAL variable, it takes precedence over the GLOBAL variable for the duration of the current script file after which the GLOBAL variable will be reinstated. The optional initializing expression follows all of the rules given below for expressions. Remember that it can't refer to any variables which are not yet declared. Subroutines: ============ All subroutines must be defined before the "PROGRAM" statement in the script file. The general form of a subroutine is: SUBROUTINE name statements ENDSUB A subroutine name must begin with an alphabetic character and be composed entirely of alphanumeric characters. Unlike variables, the name may conflict with a TE/2 script language keyword or a variable name but not with any other subroutine name in that script file. Rules for the statements in a subroutine are the same as the general rules given below except that the "RETURN" statement is only valid within a subroutine. The "RETURN" statement is not strictly needed, the subroutine will exit back to the main line of code when it reaches the "ENDSUB" statement but the "RETURN" statement may be used to exit the subroutine early. A subroutine has access to all of the local variables defined in the script file even though they may have been declared later in the file. Program body: ============= After all variable declarations and subroutine definitions, the keyword "PROGRAM" is used to indicate the beginning of the main program body of the script file. Execution of the script begins at the very next statement after the "PROGRAM" directive. The program is composed of one or more statements. Statements: =========== A statement may be one of the following: an assignment statement a TE/2 function call a control statement Assignment statements: ---------------------- An assignment statement has the following form: variablename = expression "variablename" must be the name of any LOCAL variable declared within that script file, any GLOBAL variable declared within some script file that has executed during this TE/2 session, or any TE/2 system-global variable that is not specifically read-only (see list of keywords and system variables below). Depending on the type (INTEGER or STRING) of the variable on the left hand side, the expression may take either of the following forms: String expressions ------------------ Either a string variable, string literal, or string valued function or the addition (concatenation) of two or more such variables, literals or functions. Examples: stringvar = "fred flinstone" HelloMsg = "Hello " + strleft("Worldwide", 5) + "^M^J" Integer expressions ------------------- Either an integer variable, numeric constant, or integer valued function or the algebraic combination of two or more such variables, constants, or functions. Examples: intvar = 12345 area = width * length loword = longval & 0x0000ffff The following operators are available for use in integer expressions, given in the order of precedence. Parenthesis may be freely used to ensure the correct order of evaluation and/or for clarity and readability. Table 3. -- Integer arithmetic operators ---------------------------------------- - Unary minus ~ Unary bitwise negation ! Unary logical negation & Bitwise AND operator | Bitwise OR operator ^ Bitwise EXCLUSIVE-OR operator >> Bitwise shift-right << Bitwise shift-left * Multiplication / Division % Modulus + Addition - Subtraction AND Logical AND OR Logical OR > Relational Greater-Than < Relational Less-Than >= Relational Greater-Than-Or-Equal <= Relational Less-Than-Or-Equal != Relational Not-Equal == Relational Equality TE/2 Function calls: -------------------- The TE/2 script file language has a rich set of built in functions which are listed alphabetically below in the Function Directory. In general, each function has a return value, either INTEGER or STRING and may appear in the right hand side of an expression as discussed above but a function (indeed an entire expression, see below) may also appear on a line of its own in the script file. In this case the function is evaluated (usually for its actions or side effects) and the return value is discarded. Clearly, this is not advantageous for some functions such as GETENV or STRLEN whose entire purpose in life is to return some information however it may be just the ticket for action functions like CHAT, SCROLLBACK, or even WAITFOR if you aren't interested in the return value. It was mentioned that an entire expression could appear on a line in the script file. The following is a perfectly valid statement: waitfor("Select:", 60) + 5 + atoi("1234") however the result (1239 or 1240 if WAITFOR was successful) will be discarded. You might be tempted to write: waitfor("Select:", 60) + transmit("m^M") instead of: waitfor("Select:", 60) transmit("m^M") however you should NOT depend on left-to-right evaluation of this or any expression as it may not be the case in future versions of TE/2 or in the compiled language when it become available. Likewise, Boolean statements (those which use AND, OR, the logical negation (!), and/or the relational operators are NOT short circuited once their results are clear (as they are in "C", for instance); expect all terms of a Boolean expression to be evaluated. Control statements: ------------------- The following is a brief summary of the program control structures available in the TE/2 script language. Subroutines: ------------ GOSUB subname { subname must be defined in file } RETURN { valid within a subroutine only } Notes: The subroutine has access to all variables that are available at the main line level. The program location after the GOSUB statement is saved and restored when the RETURN statement is encountered or when an ENDSUB statement is reached. Subroutines may call other subroutines in the same file. The END statement may be used within the subroutine with the same results as using it in the main program body. IF-ELSEIF-ELSE structure: ------------------------- IF num-expression statements [ELSEIF num-expression { any number of ELSEIF clauses are } statements { allowed } ELSEIF num-expression . .] [ELSE { ELSE statement is optional } statements] ENDIF Loop structures: ---------------- DO { loop forever } statements LOOP DO WHILE num-expression statements LOOP DO UNTIL num-expression statements LOOP DO statements LOOP WHILE num-expression DO statements LOOP UNTIL num-expression BREAK { exit current loop structure } CONTINUE { branch to top of current loop structure } Notes: In the DO WHILE..LOOP and DO UNTIL..LOOP structures, the control expression is evaluated at the beginning of the loop, execution may never enter the loop if the expression does not evaluate correctly for that style of loop. In the DO..LOOP WHILE and DO..LOOP UNTIL forms, the expression is evaluated at the end of the loop, the loop will always be executed at least once. The BREAK statement will exit the current loop structure. If execution is within nested loops, only the innermost loop will be exited. The BREAK statement is the only way to exit the first form of the DO..LOOP structure. The CONTINUE statement transfers control back to the top of the loop structure. If it is of the form DO WHILE..LOOP or DO UNTIL..LOOP, the expression is immediately reevaluated. Other controls: --------------- END { terminate current script file even if currently in subroutine } STOP { terminate current script file and all calling script files } RUN(str-expression) { execute script file - control returns to current file when called file ends } PROCESS { recursively execute a TE/2 terminal session, script file is suspended until an EXIT() is performed. Note that Alt-X generates an EXIT() by default } EXIT(num-expression) { terminate current PROCESS level or terminate TE/2 if not in a PROCESS shell } Note that the END statement is not strictly necessary, the script file will terminate when it reaches the end of the file. Please note that loop structures, IF blocks and subroutines must be properly nested. The TE/2 script language interpreter may detect a faulty nesting and terminate with an error but the problem may not be detected in some pathological cases until execution has already progressed in an erroneous manner for a while. The following are examples of incorrect block nesting. Incorrect nesting: ------------------ counter = 0 do while counter < 50 if counter == 25 loop endif counter = counter + waitfor("Next", 10) loop Correct nesting: ---------------- counter = 0 do while counter < 50 if counter == 25 continue endif counter = counter + waitfor("Next", 10) loop Incorrect nesting: ------------------ if stricmp(strg1, strg2) == 0 message("^M^Jwaiting") do message(".") else message("!") until waitfor(strg2, 1) endif Keywords: ========= This is a list of reserved words within the TE/2 script language. In addition to these words, no user variable may have the same name as a system-global variable (see below). Table 4. -- TE/2 script language reserved words ----------------------------------------------- abs getenv setphone and gets setscript ansi_bbs getyesno settag ansi_te2 hangup setxonxoff ascii ifcarrier setvt100bksp asciival itoa setxlattable atoi jdate sendbreak beep julian sendbyte cancelwatch julian2 sendinit chat jwday shell chdir kbdabort sleep chdisk keypressed snapshot closedialog lastdownload sprintf cls lastupload status connected lfaftercr strcmp curdir localecho strdate cursorcol logclose streval cursorrow logfile strget date logopen stricmp dial logpause strleft directory mainmenu strlen direntry message strput dirname muxwait strright dirphone null strstr dirscript opendialog strtime dirtag or strtrim download parmsmnu substr dumpinit password termecho emulate pgmmenu time erase porthandle timedout errormsg query toggle execpgm queuedial tolower exit redial toupper false rename trace fnkey restorescr transmit fclose rgetc true feof rgets tty ferror rshell upload fgetc savedirfile vt100 fgets savescr waitfor fopen scrollback watchfor fputc setctsrts weekday fputs setcursor xmodem fseek setname xmodem1k ftell setparms ymodem getc setpassword ymodemg zmodem TE/2 System-Global Variables: ============================= The following are the system-global variables (those which are usually set in TE2.INI) which may be referred to in script language statements. The type (INTEGER or STRING) of each is given by its name. In general, these variables may also appear on the left-hand side of an assignment statement, i.e.: modemInitStrg = "ATE0 V1 X6^M^J" Those which cannot be assigned directly are marked with an asterisk. The marked variables must be set/reset through other means (usually a function is provided, in some cases only through a TE/2 dialog box or only from TE2.INI). Table 5. -- TE/2 system-global variables ---------------------------------------------- * indicates read-only variable w.r.t assignment statements TermAttr - INTEGER MenuNormAttr - INTEGER MenuHiAttr - INTEGER LogoAttr - INTEGER DLogNormAttr - INTEGER DLogHiAttr - INTEGER DLogDaAttr - INTEGER DLogEdAttr - INTEGER DLogEdHiAttr - INTEGER ShadowAttr - INTEGER DialNormAttr - INTEGER DialHiAttr - INTEGER ErrorAttr - INTEGER ScrlBackAttr - INTEGER ScrlBackFdAttr - INTEGER ScrlBackMkAttr - INTEGER ScrlBackTiAttr - INTEGER ChatAttr - INTEGER ChatRemoteAttr - INTEGER ChatTitleAttr - INTEGER CmdPromptAttr - INTEGER CmdInputAttr - INTEGER CmdInputHiAttr - INTEGER SnapShotAttr - INTEGER LocalEcho - INTEGER DtrHangUp - INTEGER LFafterCR - INTEGER AutoZM - INTEGER MatchBaud - INTEGER AutoDirSave - INTEGER ChatBuffered - INTEGER Te2DEBUG - INTEGER AlarmPopUp - INTEGER MenuActive - INTEGER * ColorLock - INTEGER ClsReset - INTEGER QueryZMRecover - INTEGER DialerDC - INTEGER AutoNL3101 - INTEGER AutoLF3101 - INTEGER Scroll3101 - INTEGER EndChar3101 - INTEGER NoOvIO - INTEGER ExtendedFIFO - INTEGER SwapBS4Del - INTEGER VT100Backspace - INTEGER * BreakLen - INTEGER DialerTimeOut - INTEGER AlarmType - INTEGER AlarmTime - INTEGER ForceLines - INTEGER ScrlBackLns - INTEGER * RedialDelay - INTEGER LogoDelay - INTEGER QueryHangUp - INTEGER ClobberDL - INTEGER DialerSendInit - INTEGER ModemInitStrg - STRING ModemDialStrg - STRING ModemDialSufx - STRING ModemHangStrg - STRING ModemAnsStrg - STRING ModemOKStrg - STRING ModemDelayChar - INTEGER EnqReply - STRING VT100Prn - STRING CallLog - STRING * LogPath - STRING UploadPath - STRING DownloadPath - STRING ScriptPath - STRING ShellCmd - STRING DIRFile - STRING * FNKFile - STRING * XEXFile - STRING * Device - STRING * Port - INTEGER * Baud - INTEGER * Parity - INTEGER * WordLen - INTEGER * StopBits - INTEGER * XonXoff - INTEGER * CtsRts - INTEGER * ULPrtyClass - INTEGER DLPrtyClass - INTEGER Other System variables: ======================= The following are other read-only variables, maintained by the system which may not be set in any way. Their values may only be examined. Connected - INTEGER, TRUE if TE/2 is online CurDir - STRING, the current subdirectory CursorCol - INTEGER, current horizontal postion of the cursor, leftmost column is 0 CursorRow - INTEGER, current vertical position of the cursor, topmost row is 0 Date - INTEGER, the current date in packed format Time - INTEGER, the current time in packed format TimedOut - INTEGER, TRUE if last WAITFOR, MUXWAIT, RGETS ended because of a timeout KbdAbort - INTEGER, TRUE if last WAITFOR, MUXWAIT, RGETS ended because of ESCape was typed KeyPressed - INTEGER, TRUE if a local keystroke is pending LastUpload - STRING, the name of the most recently uploaded file or "" if no uploads have occurred LastDownload - STRING, the name of the most recently downloaded file or "" if no downloads have occurred Porthandle - INTEGER, the OS/2 file handle for the open com port StrDate - STRING, the current date in string format StrTime - STRING, the current time in string format Weekday - STRING, the current day of the week, one of: "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", or "Sat". Note: the formats of the date and time strings are determined by querying OS/2 for the current codepage. Note: the formats of the date and time numeric variables are: year = (date & 0xffff0000) >> 16 month = (date & 0x0000ff00) >> 8 day = date & 0x000000ff hour = (time & 0xff000000) >> 24 minute = (time & 0x00ff0000) >> 16 second = (time & 0x0000ff00) >> 8 hunds = time & 0x000000ff Function directory: =================== All functions are invoked by giving their names plus a pair of parentheses containing the list of arguments. In some cases, a function may not require an argument list, in these cases the empty parentheses are still required. In the function directory below, the format is: the function name is listed and, in the parentheses, the type of each required argument is given. If no arguments are required, the word "void" appears in the parentheses. Some functions receive "special" parameters; usually these will be taken from a select set of predefined constants (as mentioned in the section on constants above). In these cases, the word "special" will appear in that argument position and an explanation will be given in the text. If a function takes a variable number of arguments, this is indicated by ending the argument list with three dots ("..."). ABS(integer) Returns: INTEGER, the absolute value of its argument ASCIIVAL(string) Returns: INTEGER, the ASCII value of the first character of its argument ATOI(string) Returns: INTEGER, the numeric value of the argument Notes: this function understands hex and octal notation, thus ATOI("27") and ATOI("0x1b") and ATOI("033") all return the same value, 27. BEEP(integer, integer) Returns: INTEGER, always TRUE Notes: this function will sound the console beeper, the first parameter specifies the frequency (pitch) of the sound, the second the duration. CANCELWATCH(integer) Returns: INTEGER, TRUE or FALSE Notes: The argument must be a 'watch handle' created via a previous call to WATCHFOR. This function releases the watch. It returns FALSE if the watch did not exist, TRUE otherwise. See also WATCHFOR. CHAT(void) Returns: INTEGER, always TRUE Notes: Activates chat mode, same as Alt-G from terminal mode CHDIR(string) Returns: INTEGER, TRUE or FALSE Notes: the argument specifies a subdirectory, this function will attempt to change the current working directory on the current or specified disk, it will NOT change the currently logged disk however. CHDIR returns TRUE if it was successful. (See CHDISK) Examples: CHDIR("D:\") CHDIR("\comm\log") CHDISK(string) Returns: INTEGER, TRUE or FALSE Notes: the first character of the argument should specify a disk letter. This function will attempt to make that the current drive. It returns TRUE if it was successful. (See CHDIR) CLOSEDIALOG(integer) Returns: INTEGER, always TRUE Notes: The argument MUST be a handle to a dialog that has been created by an earlier call to OPENDIALOG. Restores the area of the screen which was saved during the OPENDIALOG call and frees up all memory associated with this dialog. CLS(void) Returns: INTEGER, always TRUE Notes: Clears the terminal screen to the current attribute. DIAL(string OR integer) Returns: INTEGER, TRUE or FALSE Notes: If the argument is an integer or if it is a string with the format "#nnn" where the n's are digits, DIAL will attempt to dial the indicated entry in the current dialing directory. If it is a string and not "#nnn" format, then if the first character is a digit it will manually dial the string, else if the string is not empty it will search for a TAG in the current dialing directory that matches and dial that entry. If the string is empty, the user is prompted for a number (this is equivalent to typing Alt-M from terminal mode). DIAL returns TRUE if a connection was made. DIRECTORY(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-D from terminal mode. DIRECTORY returns TRUE if a connection was made. DIRNAME(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Name" field in the specified entry or "" if it could not be located. DIRPHONE(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Number" field in the specified entry or "" if it could not be located. DIRSCRIPT(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Script" field in the specified entry or "" if it could not be located. DIRTAG(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Tag" field in the specified entry or "" if it could not be located. DOWNLOAD(special, string) Returns: INTEGER, TRUE or FALSE Notes: The "special" parameter must be one of the following pre-defined constants: XMODEM, XMODEM1K, YMODEM, YMODEMG, ZMODEM, or QUERY. If this parameter is QUERY, the user is prompted for the protocol. The second parameter is the file name, if it is the empty string, XMODEM and XMODEM1K will prompt the user for the filename, this parameter is ignored by YMODEM, YMODEMG, and ZMODEM. The function returns TRUE if the file transfer ended with no fatal errors. (See UPLOAD) DUMPINIT(void) Returns: INTEGER, always TRUE Notes: Prints the current value of all the system-global values settable via TE2.INI to the terminal screen. EMULATE(special) Returns: INTEGER, the new emulation. Notes: The "special" parameter must be one of the following pre-defined constants: TTY, ANSI_BBS, ANSI_TE2, VT100, or QUERY. If it is QUERY, the user is prompted for the emulation. ERASE(string) Returns: INTEGER, 0 on success, -1 on error Notes: This function will delete the indicated file from the disk. Clearly, you should use this function with care. ERRORMSG(string, string) Returns: INTEGER, always TRUE Notes: Displays the error message dialog (TE/2 uses this dialog for most all, non-script related errors). String1 is left justified on the first line of the dialog, string2 centered on the second and "Strike any key to continue" is placed at the bottom of the dialog. ErrorAttr from the initialization file is used for the dialog color. The portion of the screen overlaid by the dialog is saved and restored when the dialog is exited. EXECPGM(string, string, string, integer, integer) Returns: INTEGER Notes: The arguments are, in order, session_title, program_name, program_args, exec_type, and exec_flags. These parameters map directly to the information contained in the external program file that TE/2 uses to build the "User Programs" menu (Alt-J), you should refer to the TE/2 Manual for more information on these settings. All of the functionality for user input and global value passing that is referred to there is present here. The exec_flags parameter is NOT optional for this call like it is in the external programs file however. The return value of EXECPGM() depends on the mode in which the child process was executed. A return value of -1 will usually indicate an invalid parameter list. If the child was executed in the background or in a new session, the return value is zero for success or the error code which was returned by OS/2. If the child was executed as a foreground process, the return value is the exit code of the child program (i.e., the value which it passed to DosExit()). EXIT(special) Returns: INTEGER, TRUE or FALSE Notes: The "special" parameter must be one of the following pre-defined constants: TRUE, FALSE, IFCARRIER. If it is FALSE, the user will be asked for confirmation before exiting, if TRUE TE/2 will unconditionally exit, if QUERY the user will be queried only if the carrier is high (TE/2 is online). The function returns TRUE if TE/2 is exiting (although you won't be able to test this, if the function returns to the script at all it should do so with FALSE). FNKEY(integer) Returns: INTEGER, TRUE or FALSE Notes: If the argument is zero or greater than 48, the function key menu is activated, this is equivalent to typing Alt-K from terminal mode. If it is a number from 1 to 48, the corresponding function key macro is transmitted. 1 - 12 -> unshifed function keys 1-12 13 - 24 -> shifted function keys 1-12 25 - 36 -> control-function keys 1-12 37 - 48 -> alt-function keys 1-12 The function returns TRUE if a macro was transmitted. FCLOSE(integer) Returns: INTEGER, TRUE or FALSE Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function returns TRUE if the file was successfully closed. FEOF(integer) Returns: INTEGER, TRUE or FALSE Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function returns TRUE if the current file pointer position is at the end of file. FERROR(integer) Returns: INTEGER, error code Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function returns FALSE if no error has occurred accessing the indicated file, else it is an error code. FGETC(integer) Returns: INTEGER, character code or -1 Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function returns the next character in a file which has been opened for input. A -1 result is used to indicate end-of-file or error (See FEOF and FERROR). FGETS(integer) Returns: STRING, input from file Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function reads a line of text from a file opened for input. It reads all characters up to and including a newline character ("^J", see notes on file handling for information about newline translation) or 1024 characters, whichever occurs first. It returns and empty string to indicate end-of-file or error (See FEOF and FERROR). FOPEN(string, string) Returns: INTEGER, file handle Notes: This function MAY NOT be called outside the context of and assignment statement. It opens a file and its return value is a "handle" for all the other file oriented functions (FGETC, FEOF, FCLOSE, etc). Care should be taken with this value so that it not altered in any way until FCLOSE has safely been called. The first argument is a file name, the second is the open "mode" and should be one of "r", "w", "a", "rt", "rb", "wt", "wb", "at", "ab", "r+t", "w+t", "a+t", "r+b", "w+b", or "a+b" (see notes on file handling for an explanation). If the function returns 0, the file was not opened. FPUTC(integer, integer) Returns: INTEGER, the output character or -1 Notes: The second argument should be the value returned from an earlier call to FOPEN (see notes on file handling). The first argument is the ascii value of the character to be output to the file, the file must have been opened in a mode which allows writing of data ("w", "a", etc). A return value of -1 indicates an error situation (see FEOF and FERROR). FPUTS(string, integer) Returns: INTEGER, the last output character or -1 Notes: The second argument should be the value returned from an earlier call to FOPEN (see notes on file handling). The first argument is the string to write to the file. The file must have been opened in a mode which allows writing of data ("w", "a", etc). A return value of -1 indicates an error (see FEOF and FERROR). FSEEK(integer, integer, special) Returns: INTEGER, TRUE or FALSE Notes: The first argument should be the value returned from an earlier call to FOPEN (see notes on file handling). The second integer specifies an offset into the file which may be positive, negative, or zero depending upon the mode specified in the third argument. This function will attempt to move the current file location pointer in the indicated file to a number of bytes (specified in the second argument) from the origin (specified in the third argument). The third argument MUST be one of: 0 -- beginning of file 1 -- current position in file 2 -- end of file If this function returns false, an error has occurred. (see FEOF and FERROR) FTELL(integer) Returns: INTEGER, Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function retrieves the current location pointer in the indicated file. A return value of -1 indicates an error (see FOEF and FERROR). GETC(void) Returns: INTEGER, keystroke value or zero Notes: Waits for the user to type a key and returns the value of the keystroke. If an error occurred, the return is zero, if it was a 'standard' key, the return is the ASCII value of the keystroke, if it was an 'extended' key (i.e., Alt key or function key) it returns the scan code of the key times 256. The keystroke is NOT echoed to the terminal screen. (See GETS) GETENV(string) Returns: STRING Notes: This function will scan the OS/2 environment table for the current process (TE/2) and retrieve the value associated with the string specified in its argument or the empty string if the argument was not found in the environment. Examples: CmdExe = GETENV("COMSPEC") MESSAGE("%s", GETENV("PROMPT")) GETYESNO(string, string, integer) Returns: INTEGER, User selection result Notes: Displays the Yes/No dialog (TE/2 uses this dialog for querying the user for hangup and exit). Both strings are centered in the dialog, string2 may be NULL. The integer determines the default answer (TRUE for Yes, FALSE for No). DLogNormAttr and DLogHiAttr from the initialization file are used for the dialog colors. The portion of the screen overlaid by the dialog are saved and restored when the dialog is exited. Returns TRUE if "Yes" was selected, FALSE if "No" was selected. GETS(integer) Returns: STRING Notes: Gets a string from the console at the current cursor location. The argument specifies the maximum length of the string, it may be a number from 1 to 255. If it is less than one, an empty string is immediately returned, if it is greater than 255, it is treated as if it were 255. GETS retrieves a string from the user up to, but not including the first carriage return character or the maximum length whichever occurs first. Backspace will erase the previous character typed (if any) and the ESCape key will immediately terminate the input and GETS will return an empty string. If terminal display is turned on (see TERMECHO) the input is echoed to the terminal screen in the current attribute and at the current cursor location. (See GETC) HANGUP(special) Returns: INTEGER, TRUE or FALSE Notes: The "special" argument must be one of TRUE, FALSE, or IFCARRIER. If FALSE, the hangup sequence will be unconditionally performed, if TRUE the user will be queried for permission, if IFCARRIER, the user will be queried only if the carrier is high (TE/2 is online). The function returns TRUE if the hangup sequence was successfully transmitted and TE/2 is no longer on line. NOTE: The parameter for the HANGUP() statement will override the current setting of the TE/2 QueryHangUp initialization variable. ITOA(integer, special) Returns: STRING, ASCII representation of the argument Notes: The "special" argument must be in the range 2-36, it specifies the radix for the conversion (number system base. If the radix is 10 and the value of the first argument is negative, a leading '-' sign is the first character of the result. Examples: ITOA(1234, 10) returns "1234" ITOA(8, 2) returns "1000" JDATE(integer, integer) Returns: INTEGER, A packed date (in the same format as the 'date' read-only variable) based on the given Julian day number in the first parameter. Returns 0 on error. Notes: The first parameter is the Julian Day Number to translate, the second is a Boolean switch. If the second parameter is TRUE, the returned date will be relative to the Gregorian Calendar otherwise it will be relative to the Julian Calendar. If the Julian Day Number is invalid or the results would be out of bounds for the requested calendar, the return value will be 0. (See discussion on Julian date conversions elsewhere in this document.) JULIAN(integer, integer) Returns: INTEGER, Julian Day Number or -1 on error. Notes: The first parameter must be a packed date in the same format as the 'date' read-only variable. The second parameter indicates which calendar to use when translating the date: TRUE means that this is a Gregorian date, FALSE implies a Julian date. The return value is the Julian Day Number for the given date. If the date is invalid for the indicated calendar, this function returns -1. (See discussion on Julian date conversions elsewhere in this document.) JULIAN2(integer, integer, integer, integer) Returns: INTEGER, Julian Day Number or -1 on error. Notes: The parameters are, in order: month number (1 to 12), day number (1 to 31), year number, and a Boolean to indicate which calendar to use when translating this date: TRUE means that this is a Gregorian date, FALSE inplies a Julian Date. The return value is the Julian Day Number for the given date. If the date is invalid for the indicated calendar, this function returns -1. (See discussion on Julian date conversions elsewhere in this document.) JWDAY(integer) Returns: INTEGER, weekday index (0 to 6) or -1 on error. Notes: The single parameter is a Julian Day Number, the function will return the weekday index for that Julian Day (0 is Sunday). If the Julian Day number is invalid, the function returns -1. LFAFTERCR(special) Returns: INTEGER, TRUE or FALSE, the new value of LFafterCR Notes: The "special" parameter must be one of TRUE, FALSE, or TOGGLE. If TRUE or FALSE, the value of the LF-After-CR flag is set to that value, if it is TOGGLE the flag becomes TRUE if it was FALSE and vice-versa. LOCALECHO(special) Returns: INTEGER, TRUE or FALSE, the new value of LocalEcho Notes: The "special" parameter must be one of TRUE, FALSE, or TOGGLE. If TRUE or FALSE, the value of the Local-Echo flag is set to that value, if it is TOGGLE the flag becomes TRUE if it was FALSE and vice-versa. LOGCLOSE(void) Returns: INTEGER, TRUE or FALSE Notes: Closes the currently open log file and returns TRUE, if there is no currently open log file no action is performed and the function returns FALSE. LOGFILE(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-L in terminal mode. If a log file is currently open this function will close it and return TRUE, else the user will be prompted for a log file name to open. In this case it returns TRUE if a log file was opened or FALSE if the user typed ESCape at the prompt of if there was an error opening the file. LOGOPEN(string, integer) Returns: INTEGER, TRUE or FALSE Notes: The first argument specifies the log file to open. This must contain the entire path/name of the file, default logpath handling is NOT performed on this string. The second argument should be TRUE if the the log file should overwrite any existing file of the same name, if FALSE, new data will be appended to the file. If the first argument is NULL, the user will be prompted for the file name and overwrite/append mode, the second parameter is ignored. The function returns TRUE is a log file was successfully opened, FALSE if the file was not opened due to error or user intervention. LOGPAUSE(special) Returns: INTEGER, TRUE or FALSE Notes: The "special" argument must be one of TRUE, FALSE, or TOGGLE. If TRUE, the log file will be placed in the paused state, if FALSE it will be made active, if TOGGLE it will alternate states. The function returns TRUE if an action was performed, if there is no currently open log file, it will return FALSE. MAINMENU(special) Returns: INTEGER, TRUE or FALSE Notes: The "special" argument must be one of TRUE, FALSE, or TOGGLE. If TRUE, the TE/2 main menu will be displayed, if FALSE it will be hidden, if TOGGLE it will alternate states. The function returns TRUE if the menu state was changed. Note that the system-global variable "MenuActive" may be examined to determine the current state of the menu. MESSAGE(string, ... ) Returns: INTEGER, the length of the message string Notes: MESSAGE takes a parameter list identical to the SPRINTF function, refer to SPRINTF for a more complete discussion of the format string and its arguments. This function will build a string according to the rules for SPRINTF and display it on the terminal screen at the current cursor location. MUXWAIT(string, integer) Returns: INTEGER Notes: Very much like the related WAITFOR function, MUXWAIT allows you to specify, in the its first argument, as many as 10 strings to wait for. The first character of the string argument defines the delimiter that will be in effect for parsing the seperate wait strings. This may be any character you choose bit it should be a character that does not otherwise appear in any of the substrings (see the examples). MUXWAIT does not return until one of the specified strings has been encountered at the comm port, the duration in seconds specified in the second argument has elapsed, or the user types ESCape, whichever occurs first. Returns the index of the string which was found or FALSE if a timeout occured or the wait was aborted by typing ESCape. Incoming characters are echoed to the terminal screen unless terminal display is turned off, the log file is maintained. (See WAITFOR, WATCHFOR) If the second parameter is less than zero, normal timeout processing is disabled and MUXWAIT will not return until a string has been matched or an ESCape is typed at the keyboard. Examples: MUXWAIT("/ENTER to continue/Select:/", 60) The above example will wait up to 60 seconds for either the string "ENTER to continue" or "Select:" to appear at the comm port. If, for instance, "Select:" was encountered, the function returns 2. MUXWAIT("!Enter name/userid:!What system?!", 30) Note the use of "!" as the delimiter in this example rather than the "/" used in the first. This example needs to use the slash as a valid character in one of its searches thus the different delimiter is mandated. OPENDIALOG(integer, integer, integer, integer, integer) Returns: INTEGER, handle to created dialog Notes: Creates a dialog box on screen complete with frame and shadow. The arguments are, in order, top row, left column, bottom row, right column, and color attribute. The contents of the portion of the screen overlaid by the dialog box are saved and will be restored with a subsequent call to CLOSEDIALOG. The return value is a 'handle' to the dialog. PARMSMNU(void) Returns: INTEGER, always FALSE Notes: This is equivalent to typing Alt-P from terminal mode. The system-global variables "Device", "Port", "Baud", "WordLen", and "StopBits" may be examined to determine the current line settings at any time. PASSWORD(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Password" field in the specified entry or "" if it could not be located. PGMMENU(void) Returns: INTEGER, always TRUE Notes: This is equivalent to typing Alt-J in terminal mode. QUEUEDIAL(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-Q in terminal mode or "Q" in the dialing directory in that it activates the Queue Dialer. The function returns TRUE if a connection resulted. REDIAL(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-R in terminal mode in that the Redialer is activated. The function returns TRUE is a connection resulted. RENAME(string, string) Returns: INTEGER, TRUE or FALSE Notes: This function will attempt to rename the file specified in the first argument to the new name given in the second argument. The function returns TRUE if it was successful, otherwise an error has occurred. Further note, this function may be used to move a file from one subdirectory to another on the same disk but not across disks. Examples: RENAME("logfile.log", "logfile.bak") RENAME("somefile.dat", "\safe\place\somefile.dat") RESTORESCR(integer) Returns: INTEGER, always TRUE Notes: The argument MUST be a handle to a saved screen that has been created via an earlier call to SAVESCR or disaster is sure to follow. This function will restore a previously saved screen setup, restoring the video mode (if neccessary), cursor position, size, and attribute, and the entire contents of the screen and frees up all memory used by SAVESCR. RGETC(integer, special) Returns: INTEGER, received character or 0 Notes: This function retrieves one byte of incoming data. The integer parameter specifies the timeout value in seconds. If the timeout period elapses or the user types an ESCape at the console before a byte of information is received, RGETC returns 0. The second, special parameter determines how TE/2 will echo the character back to the sender. It may be an integer or a string. If it is an integer and is non-zero then the character will be echoed back to the sender, if it is zero, or if it is an empty or NULL string, no character is echoed. Otherwise, the first character of the string is echoed back to the sender (use this for remote entry of passwords, for instance). Note that by specifying a number less than zero as the timeout parameter, timeout processing is disabled. Incoming characters are echoed to the terminal screen unless terminal display is turned off, the log file is maintained. Backspaces are processed and filtered by RGETS before returning, if echoing is enabled, backspaces, carriage returns, and line feeds are echoed as themselves regardless of any translation specified in parameter 2. (See RGETS) RGETS(integer, integer, special) Returns: STRING, the received data Notes: This function retrieves incoming data into a string variable up to the first carriage return or the string length specified in the first argument or until the number of seconds specified in the second argument has elapsed, or until the user types an ESCape character at the console, whichever occurs first. The third, special parameter determines how TE/2 will echo the characters back to the sender. It may be an integer or a string. If it is an integer and is non-zero then the characters will be echoed back to the sender, if it is zero, or if it is an empty or NULL string, no characters are echoed. Otherwise, the first character of the string is echoed back to the sender for each received character. (use this for remote entry of passwords, for instance). Note that by specifying a number less than zero as the timeout parameter, timeout processing is disabled. Incoming characters are echoed to the terminal screen unless terminal display is turned off, the log file is maintained. Backspaces are processed and filtered by RGETS before returning, if echoing is enabled, backspaces, carriage returns, and line feeds are echoed as themselves regardless of any translation specified in parameter 3. If the length parameter evaluates to 1, backspaces are NOT filtered or translated. (See RGETC) RSHELL(string, string, integer) Returns: INTEGER Notes: Similar in many ways to the SHELL function but subtly different in several important aspects. The first string specifies a program to be executed, the second its arguments. The program argument MUST be specified, there is no default value. When the program is executed, the standard input, standard output, and standard error system handles are all redirected to the comm port. Thus, any program which takes its input from stdin and writes to stdout and/or stderr, will receive its input now from the comm port and send its output back out the comm port. If the third, integer parameter is non-zero TE/2 will continue to monitor the status of the connection while the child process is running. If a loss of carrier is detected, the child program will be aborted and control will return to your script file. TE/2's screen wil be saved and cleared before executing the RSHELL program and restored upon return. The return value is -1 if there was an error otherwise it is the return code of the program. RSHELL processes incoming backspace characters in the expected fashion. The meaning of the third parameter has been expanded. The parameter may take any of the following values either singly or ORed together: 1 --> watch carrier 2 --> echo incoming characters 4 --> translate cr == cr-lf 8 --> buffer remote input & translate backspaces Any other bits set in the parameter are ignored. While in the RSHELL, the remote user has several special key sequences available that will modify the behavior. Each begins with a Control-Backslash (^\, ascii code 28): ^\e --> toggles echoing of characters ^\x --> toggles cr-crlf translation ^\b --> toggles buffering Anything else following a ^\ is simply passed through unchanged (thus ^\^\ == ^\). Note that the character codes ARE case sensitive, that is, ^\B is not the same thing as ^\b. More special codes may be added in the future. SAVEDIRFILE(string) Returns: INTEGER, 0 on success or an eror code Notes: Saves the current dialing directory to disk using the filename specified in the parameter. If the parameter is "" then the file will be saved using its current name. SAVESCR(void) Returns: INTEGER, handle to saved screen information Notes: Saves the current contents of the entire screen and returns a 'handle' to the saved information. This information includes the current video mode, the cursor position, the cursor size and attribute as well as the actual contents of the screen. If SAVESCR returns zero then there was not sufficient memory to perform the operation. SCROLLBACK(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-W from terminal mode. The function returns TRUE unless the Scroll Back feature is disabled in which case it returns FALSE. SETCTSRTS(integer) Returns: INTEGER, TRUE or FALSE Notes: Sets the Cts/Rts handling according to the argument: 0 - CTS/RTS both off 1 - CTS on, RTS off 2 - RTS on, CTS off 3 - CTS/RTS both on The function returns TRUE if it was successful. SETCURSOR(integer, integer) Returns: INTEGER, TRUE on success, FALSE on error Notes: Places the cursor at (row, column) on the terminal screen. This is direct placement independent of the current terminal emulation. The origin is (usually) the upper lefthand corner and is (0,0). If the current terminal emulation is VT100 AND the virtual terminal is in relative cursor addressing mode AND a scroll region is set, this function will obey the VT100 emulation's rules for cursor placement relative to scrolling region. If the requested location is invalid, this function will return FALSE. SETNAME(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry. The "Name" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETPARMS(integer, integer, integer, integer, integer) Returns: INTEGER, TRUE or FALSE Notes: The arguments are Portnumber, baudrate, parity, wordlength, and stopbits respectively. SETPARMS returns TRUE if it was able to set the specified parameter configuration. If it was unsuccessful NONE of the parameters were changed. If the port number changes, the original comm port will be closed and any active connection severed. If any of the parameters are to stay the same either the appropriate system-global variable should be used or, alternately a -1 in that position. Examples: SETPARMS(Port, 2400, 0, 8, 0) sets the current comm port to 2400 baud, no parity, 8 bit word length and 1 stop bit. SETPARMS(-1, 2400, 0, 8, 0) is equivalent to the previous example. SETPARMS(-1, 9600, -1, -1, -1) sets the current comm port to 9600 baud and leaves all other settings alone. SETPARMS(Port, 9600, Parity, WordLen, StopBits) is equivalent to the previous example. Further Notes: The following is a list of the numbers to use for setting parity, word length, and stop bits: Parity: 0 - no parity 1 - odd parity 2 - even parity 3 - mark parity 4 - space parity Word Length: 7 - 7 bit words 8 - 8 bit words Stop Bits: 0 - 1 stop bit 1 - 1.5 stop bits 2 - 2 stop bits SETPASSWORD(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry. The "Password" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETPHONE(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry. The "Number" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETSCRIPT(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry. The "Script" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETTAG(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry. The "Tag" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETXONXOFF(integer) Returns: INTEGER, TRUE or FALSE Notes: If the argument is zero, XonXoff processing will be turned off, if the argument is "1" transmit XonXoff processing will be enabled, if it is "2" receive XonXoff processing will be enabled, if it is "3" both transmit and receive XonXoff processing are enabled. The system-global variable "XonXoff" may be examined at any time to determine the current state of XonXoff processing. The function returns TRUE if it was successful. SETVT100BKSP(integer) Returns: INTEGER Notes: Sets the VT100 emulation backspace translation mode. If the parameter is TRUE then the VT100 eumlation will treat incoming Backspace characters (ASCII 8) as destructive backspaces, if FALSE the VT100 backspace will be non-destructive. Returns the previous setting for the VT100 Backspace handling. SETXLATTABLE(string, integer) Returns: INTEGER Notes: Reads a new character translation table from the file specified in the first parameter. If the second parameter is zero, the new table will replace the input character translation table, if it is non-zero, it will replace the output character translation table. Returns 0 on success or an error code on failure. SENDBREAK(integer) Returns: INTEGER, the value of its argument Notes: Will transmit a break signal to the port for the specified duration in milliseconds. If a zero value is specified, the current value of the system-global variable "BreakLen" is used for the duration. SENDBYTE(integer OR string) Returns: INTEGER, TRUE or FALSE Notes: Sends the byte specified by either the integer expression or the first character of the string expression to the port. If the character is either Ctrl-S or Ctrl-Q, the byte is transmitted immediately. The function returns TRUE if it was successful. SENDINIT(void) Returns: INTEGER, TRUE or FALSE Notes: Transmits the string in the system-global variable "modemInitStrg" to the comm port. Returns TRUE if it was successful. SHELL(string, string) Returns: INTEGER Notes: Executes the program specified in the first argument sending it the parameters specified in the second. If the first argument is NULL, the current value of the system-global variable "ShellCmd" is used unless it is also NULL in which case CMD.EXE is executed with no parameters. If the first argument is NULL, the second argument is ignored. The program is executed synchronously in the foreground, TE/2 is suspended while in the shell. TE/2's screen is saved before and restored after execution. The return value of the function is the return code of the executed program or -1 if an error occurred. SHELL(NULL, NULL) is equivalent to typing Alt-O from terminal mode. SLEEP(integer) Returns: INTEGER, the value of its argument Notes: Suspends execution of TE/2 for the duration in milliseconds specified in its argument. SNAPSHOT(string) Returns: INTEGER Notes: Performs the TE/2 SnapShot function saving its results to the filename indicated in the parameter. If the parameter is "" the the screen capture is saved to the default file name. Snapshot always appends data to the output file. Returns zero on success or an error code on failure. SPRINTF(string, ... ) Returns: STRING Notes: SPRINTF receives a format string in its first argument followed by up to 10 additional arguments that may be either integers or strings. The arguments are formatted into a string according to rules specified by embedded commands in the format string. With the exception of floating point handling and pointer notation, all of the functionality of the "C" functions "printf" and "sprintf" are supported by TE/2's implementation of SPRINTF, the reader is referred to the C Language library reference manual of his or her choice for complete definition of all of the rules regarding format strings. Here we will note the following: All characters from the format string are copied to the output string with the following exceptions: If "%s" is encountered in the format string, the next unexamined parameter is interpreted as a string an embedded at that point in the output string. The notation "%10s" will right justify the string in a field of 10 spaces at that point in the output string. "10" is used by way of example, it may be any decimal number. The notation "%-10s" will likewise left justify the string in a field of 10 spaces. If "%d" is encountered in the format string, the next unexamined parameter is interpreted as a 16 bit signed integer and the ascii representation of it is embedded into the output string at that point. "%ld" interprets the numeric parameter as a 32-bit signed integer (the native form of all integers in the TE/2 script language). "%10d" or "%10ld" right justifies the number in a field of 10 spaces in the output string, "%010d" or "%010ld" right justify the number in a field of ten zeros in the output string. If "%*s", "%-*s", "%*d", et cetera are encountered in the format string, these will behave exactly the same as the examples above with numeric values except that TWO parameters are expected in the argument list, the first an integer which will specify the field width, the second the string or integer to place in the output string. If "%%" is encountered in the format string, a single "%" is placed in the output string. The arguments to SPRINTF may be literal strings, string variables, string expressions, numeric literals, constants, variables, or expressions in any form or order. The only restriction is that the first argument, the format string, must evaluate to a string. WARNING It is not possible to type check all of the parameters in an SPRINTF (or MESSAGE or TRANSMIT) argument list. The script file writer is expected to take precautions to avoid type mismatches so that integers are not interpreted as strings and vice versa. In general, if a string is interpreted as an integer there should be no ill effects other than erroneous output. If an integer is interpreted as a string however, a protection violation may well occur. Examples: SPRINTF("Hello %s", "World") returns "Hello World" SPRINTF("Hello %8s", "world") returns "Hello world" SPRINTF("Hello %-8s", "World") returns "Hello World " SPRINTF("This is the %dth example", 4) returns "This is the 4th example" SPRINTF("Action is %03d%% %s", 35, "complete") returns "Action is 035% complete" STATUS(void) Returns: INTEGER, always FALSE Notes: This is equivalent to typing Alt-I from terminal mode. STREVAL(string) Returns: STRING, the value of its argument Notes: This function is included as a convenience for the REXX language script writer, it simply returns the value of its argument allowing a REXX script to query any TE/2 internal or global variable. STRCMP(string, string) Returns: INTEGER Notes: Lexigraphically compares two strings, returns zero if the strings are identical, less than zero if the first string is "less than" the second, greater than zero otherwise. STRGET(string, integer, integer, integer, integer, integer, integer) Returns: STRING, user response Notes: String input routine. The string parameter is the default value, and the integer parameters are, in order, row for the input, column for the input, width of the input area, maximum input length (may be larger, smaller or equal to the previous parameter), attribute for 'first display' of the default, and attribute for display while the user is editing/inputting. Returns the edited string, returns the empty string if the user pressed ESCape. Note that input area is NOT saved and restored, it will remain on screen after the input. STRICMP(string, string) Returns: INTEGER Notes: Case-insensitive version of STRCMP. See STRCMP. STRLEFT(string, integer) Returns: STRING Notes: Returns the leftmost N characters in the string where N is the number specified in the second argument. If N is greater than the length of the string, the entire string is returned. (see STRRIGHT, SUBSTR) STRLEN(string) Returns: INTEGER, the length of the string STRPUT(integer, integer, integer, string, ... ) Returns: INTEGER, length of displayed string Notes: The integer parameters are, in order, screen row, screen column, and attribute for display. The string is a format string (see SPRINTF) which may be followed by up to ten additional arguments. The resulting string is placed at the indicated position on screen using the indicated attribute. Return value is the length of the displayed string. STRRIGHT(string, integer) Returns: STRING Notes: Returns the rightmost N characters in the string where N is the number specified in the second argument. If N is greater than the length of the string, the entire string is returned. (see STRLEFT, SUBSTR) STRSTR(string, string) Returns: INTEGER Notes: Scans the string in the first argument for an occurrence of the string in the second. Returns zero if the string was not found else it returns the position of the second string in the first. STRTRIM(string) Returns: STRING Notes: Returns a string which is a copy of the string in its argument with all leading space, tab, carriage return, and newline characters removed from the beginning and end. Embedded spaces, etc., are not removed. SUBSTR(string, integer, integer) Returns: STRING Notes: Returns a substring of the string in its argument. If N is the value of the second argument and M the value of the third, SUBSTR returns the string which begins N characters into the first argument and continues for M characters. If N is greater than the length of the string, the empty string is returned, if N+M is greater than the length of the string, only the characters in the string from position N to the end of the string are returned. (see STRLEFT and STRRIGHT) TERMECHO(special) Returns: INTEGER, TRUE or FALSE Notes: The special argument must be one of TRUE, FALSE, or TOGGLE. TERMECHO will enable or disable the echoing of characters to the terminal screen. This effects both incoming characters from the comm port received during a WAITFOR, MUXWAIT, RGETS, or RGETC and characters typed at the keyboard during a GETS call. It does NOT have any effect on characters received during a main or higher level PROCESS. Example: message("Enter string to wait for:") termecho(FALSE) waitSrch = gets(255) ; no screen echo here waitfor(waitSrch, 60) ; or here process ; screen will update during this ; but will still be off when we ; get back TOLOWER(string) Returns: STRING Notes: Returns a string which is a copy of its argument with all upper case letters translated to lower case. (see TOUPPER) TOUPPER(string) Returns: STRING Notes: Returns a string which is a copy of its argument with all lower case letters translated to upper case. (see TOLOWER) TRACE(integer) Returns: INTEGER, the value of its argument Notes: Enables and disables trace mode during script file execution. When in trace mode each line of the script file is printed on the terminal display (and will appear in the scroll back buffer and log file if one is open) as it is encountered. This is a global toggle, once turned on it is on for all subsequent script file processing until it is turned off again or until TE/2 ends. TRANSMIT(string, ... ) Returns: INTEGER, the length of the message string Notes: TRANSMIT takes a parameter list identical to the SPRINTF function, refer to SPRINTF for a more complete discussion of the format string and its arguments. This function will build a string according to the rules for SPRINTF and transmit it to the comm port. UPLOAD(special, string) Returns: INTEGER, TRUE or FALSE Notes: The "special" parameter must be one of the following pre-defined constants: ASCII, XMODEM, XMODEM1K, YMODEM, YMODEMG, ZMODEM, or QUERY. If this parameter is QUERY, the user is prompted for the protocol. The second parameter is the file name, if it is the empty string, the user is prompted for the file name. The function returns TRUE if the file transfer ended with no fatal errors. (See DOWNLOAD) WAITFOR(string, integer) Returns: INTEGER, TRUE or FALSE Notes: Does not return until either the string specified in the first parameter is encountered at the comm port, the duration in seconds specified in the second parameter has elapsed, or the user types ESCape, whichever occurs first. Returns TRUE if the string was encountered, FALSE if a timeout occurred or the wait was aborted by typing ESCape. Note that specifying a number less than zero as the timeout parameter, timeout processing is disabled. Incoming characters are echoed to the terminal screen unless terminal display is turned off, the log file is maintained. (See MUXWAIT, WATCHFOR) WATCHFOR(string, string) Returns: INTEGER, 'handle' for installed watch Notes: Unlike WAITFOR, which does not return until the indicated string has been encountered or a set period of time has elapsed, WATCHFOR installs an asynchronous 'watch' and returns immediately. The return value is zero if TE/2 could not install this watch, only 10 watches may be active at any time. If successful, the return value is a 'handle' which you will need to pass to CANCELWATCH when you want to end the watch. This handle is therefore every bit as precious as the handle returned from FOPEN and the warnings given below in the notes about file handles apply equally well to watch handles. The first parameter is the string to 'watch' for. The second parameter may be nearly any valid TE/2 Script Language assignment statement or function call. The statement is not checked for proper syntax or variable usage until the watch string has been matched and TE/2 attempts to execute the statement so you must take care that the syntax is correct and that any variables referred to in the statement will be accessible when the statement is to be executed. Global and system-global variables are always safe but local variables will cause problems if the watch is left to continue after the current script has finished execution or during the execution of any nested script files or recursive PROCESSes. Every incoming character from the com port is checked against the currently active watches, if a watch string is matched it is tagged for execution. If TE/2 is in a process loop at the time, it will be immediately executed. However, if a script file is running at the time, it will not execute until the current line has finished execution - this means that a WAITFOR, MUXWAIT, RGETS, RGETC, etc., will not be interrupted to execute a watch command. Use the function CANCELWATCH to release a watch that is no longer needed. (See CANCELWATCH) Example: integer whand1 integer whand2 integer gotMail = FALSE program whand1 = watchfor("ENTER to continue", "sendbyte(13)") whand2 = watchfor("mail waiting", "gotMail = TRUE") waitfor("Enter your choice:", 120) cancelwatch(whand1) cancelwatch(whand2) if gotMail ; et cetera Special Notes on the File Handling Functions: ============================================= The integer value returned from FOPEN is a very important one. It is a file "handle" that is used for all actions performed on that file via the other file oriented functions. This value should NOT be modified by your program until the file is safely closed (via a call to FCLOSE) and is no longer needed. Though all the other file oriented functions other than FOPEN will accept any integer valued expression in the field used for the file handle, it is VERY dangerous to use anything but the variable containing the value returned from FOPEN. Any number of problems, up to and including general protection violations, may occur is this procedure is not followed. The valid open modes for a file that may be used as the second argument to FOPEN are given in Table 6 below. Certain of the file oriented functions will operate only on a file which has been opened in a mode which permits reading from the file. FGETS, FGETC, are examples of these functions. Others, like FPUTS and FPUTC, will operate only on a file which has been opened on a file which has been opened in a mod which allows writing to the file. Others, like FCLOSE and FTELL will work on any open file. Table 6. -- Valid "mode" parameters for FOPEN --------------------------------------------- "r" open for reading. If the file does not exist, the FOPEN call will fail. "w" open an empty file for writing. If the given file exists it will be truncated. "a" open for writing at the end of file (appending) create the file if it does not exist. "r+" open for both reading and writing. If the file does not exist, the FOPEN call will fail. "w+" open for both reading and writing. If the given file exists it will be truncated. "a+" open for both reading and appending. If the file does not exist it will be created. Translation mode specifiers: --------------------------- One of the following characters may be optionally appended to the mode string, they control the translation mode of the file. The default mode is "t" (translated) mode so that the use of "t" is unnecessary. "b" open in binary (untranslated) mode. Absolutely no translation is performed on data read from or written to the file. "t" open in text (translated) mode. Carriage return- line feed combinations are translated to a single line feed on input, line feed characters are translated to carriage return-line feed pairs on output. Control-Z characters are considered to be the end of file regardless of their position in the physical file. A file opened for writing or read/writing will have a Control-Z found at the end of the file removed if possible because the presence of this character at the end of the file may cause FSEEK to behave improperly. Note that the return value of FTELL and the actions of FSEEK may not be consistent with the actual physical locations in a file opened in translated mode. However, they will behave compatibly, that is, FSEEKing to a location previously determined by a call to FTELL will return the location pointer to the same spot in the file. Note: because "t" is the default action for FOPEN, its use is discouraged. Special Notes on Julian Date Conversion Functions: ================================================== General notes on the calendars: ------------------------------- Julian proleptic dates earlier than January 1, 4713 B.C. are invalid, as are Julian dates in the year 0. Gregorian dates prior to October 15, 1582 are also invalid, as are dates with month numbers not in the range 1 to 12, or with day numbers less than 1 or greater than the number of days in that month. Invalid dates will cause an error return. Julian Date Conversion Functions: --------------------------------- JULIAN(integer packed_date, integer Gregorian) JULIAN2(integer mon, integer day, integer year, integer Gregorian) These two functions return the Julian Day Number corresponding to the input calendar date or -1 if given an invalid input date. If parameter 'Gregorian' is non-zero, this denotes input as a Gregorian calendar date, otherwise it is a Julian calendar date. Note that, in JULIAN, the date is given in the same packed format as the TE/2 Script Language read-only variable 'date', in JULIAN2 the date is broken out into its componants. Month ranges from 1 to 12, day from 1 to 31 (or less depending on the month). For Julian B.C. dates, express the year as a negative number (remembering, there is no Julian Year 0). These function are, except as noted above, identical. JDATE(integer JulianDay, integer Gregorian) Returns date, in packed format, if it can calculate it from the Julian Day Number argument (JulianDay), or 0 if it cannot. If valid, the calculated month, day, and year are stored in the return value in the same packed format as the TE/2 Script Language read-only variable 'date'. If parameter 'Gregorian' is non-zero, a Gregorian calendar date will be calculated, otherwise a Julian calendar date is calculated. JWDAY(integer JulianDay) Returns a day-of-week code (0 => Sunday, 1 => Monday, etc.) if given a valid Julian Day Number, or -1 if the Julian Day Number is invalid. Notes on REXX Scripts ===================== You can call a REXX script from TE/2 anyplace you can call a TE/2 Script Language script! TE/2 determines whether or not it's a REXX script by examining the first two bytes of the file for "/*" (as all good REXX files should begin) so you can name the file with a .SCR if you want. If it's not .SCR, you'll have to specify the full file name. REXX scripts also go into a directory referred to in the ScriptPath .INI variable (see note below). A REXX script is executed directly (not via a shell to the command processor) and the default addressing environment is set to 'TE2'. As a subcommand handler, TE2 will accept any command that can be typed at the Alt-/ Command Prompt (i.e, any TE/2 Script Language assignment or function but not "if", "do .. loop" or any such control construct). TE2 also registers itself to handle screen and keyboard i/o. All PULLs come from TE/2's keyboard handler and all, non debug, SAYs go to TE/2 terminal screen. Debug mode SAYs go to stderr as always. Calling a TE/2 Script language function from REXX: -------------------------------------------------- Just put the call into quotes like you would if you were addressing CMD.EXE, the return value will be in RC. E.g., 'upload(ZMODEM, "myfile.zip")' if rc = 1 ... Note the use of single and double quotes. REXX will accept either but the TE/2 Script Language requires double quotes to delimit it's strings so you will have to watch for this. If you wanted to make the above UPLOAD call but had the file name in a REXX variable, call it as such: 'upload(ZMODEM, "' rexxvar '")' If the TE/2 Script function returns a string instead of a numeric value, this also will be in rc. E.g., 'rgets(250, 60, TRUE)' if rc = 'exit' ... Errors when calling TE/2: ------------------------- After returning from calling a TE/2 Script Language function, the REXX special variable RC is always set to the return value of the function unless a syntax error of some sort occured. TE/2 will print an error message on the terminal screen in this event and raise a REXX error condition (the value of RC is indetermanent in this case). You may want to use the REXX "SIGNAL ON ERROR ..." feature while debugging scripts. Querying TE/2 Internal 'System' Variables: ------------------------------------------ Clearly, because you aren't executing a TE/2 script language script, you won't have any TE/2 local, user variables to deal with at all but you may want to query a TE/2 system variable or perhaps a global variable from a previously executed TE/2 Script Language script. If the variable is a string: use the StrEval() function. 'streval(downloadpath)' rxdlpath = rc If the variable is an integer: use the itoa() function. 'itoa(kbdabort, 10)' if rc = 1 ... Setting a TE/2 Variable from REXX: ---------------------------------- Some TE/2 System variables may be set by a script, all global user variables may also be set. Set a string from a literal: 'downloadpath = "D:\Junk"' -- or -- 'downloadpath = "' "D:\Junk" '"' Set a string from a variable: 'downloadpath = "' rxvar '"' Set an integer from a literal: 'localecho = 1' -- or -- 'localecho = ' 1 Set an integer from a variable: 'localecho = ' rxnumvar