If you are new to EBL, you are likely starting to see that there are many ways EBL can be used. There is a significant difference between simple DOS batch files that you may have used and the power of Extended Batch Language. Although EBL has many powerful commands, there is no need to be intimidated, help is always at your finger tips. Before we look at any more EBL commands, let's look at the several forms of quick reference that are available!

Help with Commands - BAT

Type from DOS:

    C> BAT

The help screen displayed will be similar to the following:

EXTENDED BATCH LANGUAGE - PLUS
(C) Copyright Seaware Corp 1982-1995
(C) Copyright Frank Canova 1982-1985


Batch file statement:

  BAT -[label] [cmd] | [cmd]
Batch file commands [operands]
  BEEP      [stmt]
  BEGSTACK...[text] [\hex] [\%var] [;]... END
  BEGTYPE ...[text] [\hex] [\%var] [;]... END
  CALL     -[label]  ... [token] ...
  CLS       [stmt]
  COLOR     [\hex] [\%var]
  ELSE      [stmt]
  EXIT
  GOTO     -[label]
  IF        [exp] < = > <> == [exp] THEN [stmt]
  INKEY     [text] [var]
  LEAVE
  PARSE     [token] [var] [delim] [var]
  READ      [text] [vars]
  READSCRN  [vars]
  READ.PARSED [text] [var] [delim] [var]
  READSCRN.PARSED    [var] [delim] [var]
  RETURN
  SHELL     [stmt]
  SKIP      [numoflines]
  STACK  ...[tokens] [;]...
  STACK.LIFO  ...[tokens] [;]...
  TYPE   ...[tokens] [;]...
  [var]  =  ( [token] + - * / % # $ ? & [token]  )
  * [comment]


Control Functions:

  CALL.PURGE [levels]
  STACK.ON
  STACK.OFF
  STACK.PURGE
  TRACE()
  >file   - Write file
  >>file  - Append file
  >       - Close write
  <file   - Read file
  <<file  - Re-open file
  <       - Close read

Options:

  /K         - Kill
  /L         - LEAVE default
  /P         - No BAT Prefix
  /Q         - Quoted string
  /R [filename] - Run new file
  /S         - SHELL default
  /U         - Upper case
  BIOS or RAM  display speeds


Variables:

  %0 to %9 - DOS Vars
  %A to %O - Global EBL Vars
  %Q - Stack status

  %R - Return Code [0:4FE]

  %% - "%" Literal
  %NAME% - Environment vars

Error Recovery
  -ON.ERROR-  Label
  %R          Type #
  %L          Line #

Help with Error Messages - EHELP

No programmer has ever worked with a new language for long before getting their first error message. If you have already gotten several, don't worry, a full explanation of how to fix the problem is at your finger tips.

EHELP is a special EBL Plus program that will give a full explanation about the last EBL error you have received. It contains most of the text from the Messages appendix of this manual. It not only explains what the error message means, but often offers solutions to rectify the Problem. An added advantage is that this Ehelp facility is immediately available on-line, without having to search through the pages of this manual. We think you will find it invaluable.

Be aware that certain DOS and application errors can also show up for which EHELP cannot provide assistance. Although some common DOS errors are in this manual, EHELP can only help with EBL errors. All EBL error messages have >>> preceding the message.

For example, if you receive an EBL error message that looks like:

    >>> Label could not be found

then just ask EHELP for assistance with the following command:

    C> EHELP

and you will see an explanation that looks something like this. <$&ehelp[v]>

Trying examples in this manual - VIEW

One of the great ease-of-learning factors for getting started with EBL is that we have already entered all of the main examples in this book onto your EBL System Diskette. Therefore, these EBL programs are ready for you to begin running. The first entered example is the text printed on page 9.

All the examples within this manual are ready to try out on the EXAMPLES sub-directory of your EBL diskette. This sub-directory contains a packed library of files. If you would like to take a closer look at these examples use the VIEW program from the \EXAMPLES sub-directory. To get to look at any example, enter the command "VIEW". You will then be asked to enter the page where the EXAMPLE appears in your EBL manual. In addition to VIEWing these examples, you can also immediately execute them as well!

    A> CD \EXAMPLES
    A> VIEW

You should then see this VIEW menu to look at and try out the examples. <$&viewmenu[v]>

For example, to try out the example on page 9, type 9 and press Enter. Next the example will appear, and it will ask for your choice:

    S = Save as a file
    T = Try it out
    R = Return to the menu

When the EXAMPLE is "Saved," it exists as a separate file. For example, if you had chosen to Run and Save the EXAMPLE on page 9, the file PAGE9.BAT will be created. The next time you can just run PAGE9, without using the VIEW program.

Our First EBL Plus Program

With the EBL Plus language, this menu can be easily created. Note that there are several different programs that we will be controlling with this menu. To create or edit a document, we might use Personal Editor (PE). To print a document, we might use the PRINT program in DOS. To display a directory, we might use the DIR command in DOS. Let's take a look at the batch file using EBL Plus.

BAT * Eva's EBL program...
-Menu CLS BEGTYPE               |* Show the menu

    Eva's Document Menu

1 - Create/Edit a document
2 - Print a document
3 - Display directory of documents
4 - Exit

END
    READ Select an option> %0   |* Ask for selection

    IF %0 <> 1 GOTO -N1         |* If edit option..
    READ Enter document name> %1|* which file?
    PE %1
    GOTO -Menu                  |* EDIT then return

-N1
    IF %0 <> 2 GOTO -N2         |* If Print option...
    READ Which document to print> %1 |* Which file?
    PRINT %1
    GOTO -Menu                  |* PRINT then return

-N2
    IF %0 <> 3 GOTO -N3         |* If Directory...
    READ Which documents to show? %1 |* Which files?
    DIR  %1 /P
    PAUSE
    GOTO -Menu                  |* DIR then return

-N3
    IF %0 = 4 EXIT              |* Exit this menu?
    BEEP                        |* No, beep & return
    GOTO -Menu

In this example, all EBL Plus commands were shown in upper case while comments to the user are mostly lower case. We create this menu system by using the general purpose BEGTYPE command. Four possible selections are allowed. In order to get the selection from the user, we use the READ command. In this example, we used the %0 variable to hold the user's selection. As you look at the EBL program you will notice that the BEGTYPE and READ commands are similar to the PRINT and INPUT commands respectively in BASIC.

Once the READ command gets the user's selection, we use successive IF and GOTO commands to get to the selected section within the program. Again, these commands have very similar counterparts in BASIC. In EBL however, GOTO commands reference labels rather than line numbers. Note that labels always have a minus sign proceeding them.

Once the proper option is identified with the IF command, EBL executes a series of commands that are unique to each option. In the first option, we use another READ command to get the file name to be edited. Next, the PE command loads the Personal Editor program. If you would like to try this batch file and do not have Personal Editor, you may want to substitute any other editor here you may use. After the editor has ended, the command BAT GOTO -MENU will return control to the top of the batch file and show the menu again.

You may wish to run this example. Refer to the file already in the \EXAMPLES subdirectory on the EBL diskette. Alternately, you may wish to use your favorite editor to enter this example into a file called MENU.BAT. After you do this, all you need to do is type "MENU" at the DOS prompt in order to get Eva's document menu to appear. It's that simple!

In the following pages you will find out how to use Extended Batch Language. With each EBL command, you will see examples and tips on ways to use them. We encourage you to write your own simple EBL programs and try the supplied examples. Running the commands is the quickest method of learning the capabilities of Extended Batch Language.

EBL PLUS LANGUAGE STRUCTURE

Standard batch files normally just contain a series of commands which are passed to DOS, just as if the user had typed them in. Its primary function is to save the user time and trouble from having to enter a repetitive series of commands to the system to do some task. It is a valuable tool to minimize end user interaction.

With Extended Batch Language (EBL), the batch file can now contain not only these same repetitive DOS commands, but control commands, prompts, and other programming constructs. Generally, it gives the user more control over programs in their system.

These powerful programming capabilities are provided by the control program BAT.COM. BAT.COM executes the EBL commands within the batch file, and should stay on the same disk, or path, as the batch file.

It is important that the first line of the EBL batch file start with the keyword BAT. When a batch file starts running, commands execute from DOS just as any batch file would. When it comes across a statement which starts with BAT it loads in the batch extensions from the file BAT.COM. The EBL program takes the remainder of this batch file and starts execution.

EBL Plus Language Statements

    [-label] [command] { | [command] {| [command]} }

        or

    [external application]

An optional label can begin the statement. EBL uses the label to identify this statement as the target of a GOTO or CALL command. Labels are ignored at other times. Labels must begin with the '-' (minus) character and can have up to 254 characters after the minus for a total of 255 characters.

A command may follow the label. Following the command keyword are optional operands to the command. Commands, and their available operands, are described later. These commands are things like IF, READ, BEEP, TYPE and other useful functions.

If EBL does not recognize the command name as a part of EBL, then it will execute the statement as an external application. EBL will automatically use the SHELL command, described later, to start the program. If the program has the same name as an EBL keyword, you can force execution by manually using the SHELL command. When the application ends, the variable %R will contain the return code from the application, if supported by that application.

EBL also has the ability to have multiple commands in each statement. EBL separates each command with the "|" (vertical bar) character. This can be used between any commands, except within the BEGTYPE/END and BEGSTACK/END commands. If you do use the "|" character in those commands, it will be sent to the display, or stack, respectively.

Multiple commands within an EBL statement are very useful when combined with the IF command. For example:

 BAT IF %A = abc TYPE this | CALL -that | GOTO -other

If the condition is true, all three commands following the IF will be interpreted. If the condition is false, none of the commands will be interpreted and execution will continue with the line following this statement. By combining the commands into one line, the flow of execution after the IF command can be described very concisely.

You cannot use the "|" character if you manually enter EBL commands from the DOS prompt, or in the first line of an EBL program. DOS will interpret the "|" character as a piping command rather than pass the entire line to EBL. Use the "|" character only within an EBL program.

Variable Types

Although EBL values can be created in many ways, type declaration and conversion is not necessary in EBL. In other words, EBL is a typeless language (everything, including numbers, is a string). Text strings and numbers can be used interchangeably. Conversion is automatic and transparent, depending on how they are used.

Literals

Strings of characters can also be a numeric value. If the beginning of the value is a quotation mark, all characters that follow, up to the ending quotation mark, will become the resulting value. A single or double quote can be used, but must be used in matching pairs. The following are valid strings:

    ABC
    Fred
    Don't.Panic!
    'Bernard'
    "That's a string"
    'That's also a string'
    "'"
    "5+3"

Note that certain special characters are reserved for arithmetic operations. If you use characters that are not letters, numbers, or periods, it is best to enclose the text with quotes.

Variables

        ALTERABLE:


10   DOS variables              %0 to %9
15   Global EBL variables       %A to %O
 n   Extended Variables         &ANTELOPE to &ZEBRA


        REFERENCE ONLY:


     Environment variables      %VarName%
6    Predefined variables       %Q %R %% %(

Each variable can contain up to 255 characters. When used, the contents of the variable (not the variable name) will be used as the resulting value. For example, if %0 contains the characters ABC, then using the variable %0 in a batch file will be the same as if you had entered ABC in its place. Let's try an experiment at the DOS prompt:

    C> BAT %A = XYZ

                              (Sets the %A variable)

    C> BAT TYPE This is %A

                              (Requests %A value)

    This is XYZ

                              (EBL returns its value)

    C>

Unquoted literal characters and DOS or Global variables can be combined as well. This is done by putting the variables and literals beside each other in the batch file without spaces. This will concatenate the strings, perform the substitutions for each variable, and create a final result. This result can have no more than 255 characters, trailing characters will be truncated without errors if you exceed this limit. This automatic concatenation can be shown as:

    C> BAT %A = XYZ

                              (Sets the %A variable)

    C> BAT TYPE This is %Aabc%A

                              (Requests %A value)

    This is XYZabcXYZ

                              (EBL returns its value)

    C>

DOS and Global variables can be automatically concatenated. Described later are Extended variables which must be used individually and can not be concatenated as shown above.

DOS Variables

There is a maximum of 255 characters that can be stored in each DOS variable. Note that DOS has an additional restriction of 118 total characters available for all DOS variables (%0 through %9). If you exceed this limit, an error message will result when control passes from EBL back into DOS.

You cannot use DOS variables in immediate execution mode since no DOS memory is available for them, as no batch file is executing. An error message will result if you try to use them in immediate execution mode.

When batch processing begins, DOS initializes the variables %0 (zero) to %9 (nine) based on the original command line which invoked the batch file. For example, for a batch file called TEST1, EBL will make the following assignments:

    For the command line .  .  .

        TEST1 DATAA DATAB

    The variable        would be initialized to

        %0                      TEST1
        %1                      DATAA
        %2                      DATAB
        %3 to %9                would be empty

The batch file can then alter the contents of any of these variables through EBL. When you change the contents with EBL, DOS commands within the batch file can make use of the new value. Let's say the batch file TEST1 contains the following statements:

    BAT * Backup example
    TYPE Now creating a backup of %1
    %3 = %1.TMP
    COPY %1 %3

When invoked, EBL would create a new variable (%3), then pass it to DOS for the COPY command. When executing this EBL program, the following will be seen on the screen:

    TEST1 DATAA

    Now creating a backup of DATAA
    COPY DATAA DATAA.TMP

Note, if EBL ends with an EXIT or LEAVE command, only DOS variables can be used with DOS commands and applications. DOS will not recognize other EBL variables.

Global EBL variables

Between EBL programs, the global EBL variables will remain in memory undisturbed. They keep their contents even when no EBL program is running. This means two things. First, global EBL variables can be used to pass information between several EBL programs. This is useful for determining if a previous program was executed and what its results were. Second, when necessary, you may want to initialize these variables yourself within the EBL program if an indeterminate state is unacceptable.

It should be emphasized that we can only use these global EBL variables with DOS commands while EBL is running. If you EXIT the batch file or use the LEAVE command, DOS cannot use these variables. So, while a statement which contains 'COPY %1 %2' is fine, 'COPY %A %B' cannot be used after EBL stops running. To understand how DOS uses these variables, refer to Chapter 3 of the DOS manual under Batch Processing.

If there is an error, the global EBL variable %L will be set to the line number on which the error occurred. This will destroy the previous contents of %l. You should therefore use caution if you plan to use its contents between programs where errors are possible. Refer to the special -ON.ERROR- label description for a complete explanation of error recovery and the significance of the %L variable.

Global EBL variables depend on resident memory space being available for EBL to use. EBL creates this space only the first time you use EBL. When EBL makes this space resident, you will see a message "EXTENDED BATCH LANGUAGE - PLUS version 4.00 installed." and all 15 global EBL variables will be initialized to null. A null string contains 0 (zero) characters. Unlike the DOS variables, this is the only time when global EBL variables become initialized.

Stack status (%Q)

This variable can be used to determine if an EBL program has been able to put data into the stack. You can also use it to tell if more stack data exists that might be passed between subroutines within the EBL program. Examples of this can be found in the appendix.

Return codes (%R)

The %R variable is also useful for retrieving the error level returned from external DOS commands or application programs. By executing these commands or applications with the SHELL command within EBL, the %R variable will be set upon completion of the command. The %R variable will be set to the error level that the command or application received when exiting. This is the same error level that is often used by compilers and other programs. DOS refers to this value as ERRORLVL.

This special variable is read-only. EBL can only read from it, not write into it. So while a statement like %9 = %R is valid, %R = %9 is not valid. Also, %R contains hex, not decimal values, and leading zeros are stripped from %R. A user routine can setup a return code for EBL by saving its value at the word location 0000:04FE. For further examples of how to use return codes, see the examples in the appendix.

Character literals

If you wish to use a percent sign within a batch file without being interpreted as a variable name, you need to use two percent signs.

    TYPE A percent sign is like %%

Parenthesis - %(

If you want to use an open parenthesis symbol without being considered part of an expression, then you must precede it with a percent sign.

    TYPE A parenthesis is like %(

Environment Variables

DOS Environment variables can also be used within EBL. DOS keeps these variables for setting system parameters for other programs. These variables can be referenced by starting and ending the variable name with percent signs. For example, the DOS environment variable COMSPEC should be referenced within EBL as %COMSPEC%. The value of this variable will then used as the result. To see some examples, from DOS type

    C> BAT TYPE %PATH%


    C:\                             (Perhaps)


    C> BAT TYPE %COMSPEC%


    C:\COMMAND.COM                  (Perhaps)

To set environment variables to a value, you must use LEAVE or EXIT in EBL, then insert the SET command in DOS. This is because DOS officially does not allow programs like EBL to permanently alter environment variables. Using LEAVE or EXIT however is permissible. For example

    BAT  * Environment variable example...
    TYPE "Ready to set ABC..."
    LEAVE
    SET  ABC=xyz
    BAT  * Return to EBL...
    TYPE "ABC contents is" %ABC%

Environment variables with a "%" in the middle of the name will be treated as compound EBL variables instead of DOS environment variables. That is, %name% is a DOS environment variable while %n%ame% is a compound EBL variable. The latter version will concatenate simple EBL variables %n, and %a with other constants like m, and e.

Extended Variables

Extended variables can be used in cases where you do not have enough global variables (%A to %O), or you would like to have variable names more readable. These additional EBL variables are available by loading the program BATXV before the batch file begins.

Extended variables are identified with the form:

    &Root&index&index ... &index

The ampersand character begins the root variable name. It also identifies any indexes to that root name. The index is optional, and any number can be added to the root variable name. All characters within the variable name are converted to upper case before being used.

When used, the &index will lookup the contents of another &root variable and substitute its contents as part of the final name. For example:

IF:

           &Name     = Pig
           &Type     = Sound


THEN:

           &Animal&Name&Type = oink


SAME AS:

           &AnimalPigSound   = oink

Extended variables can contain any upper/lower case character string up to 255 characters long. The resulting variable name, when appending all index values to the root name, also has a limit of 255 characters. When a variable is not yet initialized, it will contain a null (empty) value.

Examples

BATCH FILE CONTAINS       RESULTING VALUE IS

        Abc                   Abc
        %1                    XYZ
        123%1                 123XYZ
        %0123%1               ABC123XYZ
        %0%2%1                ABCXYZ
        ('123' && %1)         123 XYZ
        "That's easy"         That's easy

        %PATH%                C:\

        %PATH%1               PATHXYZ
        &XTENDED              Contents
        (5+2)                 7
        123 %1                123   XYZ

The last example creates two separate values since a space exists before the percent sign in the batch file. Spaces are delimiters for each value. The example shown as "('123' && %1)" creates only one value. It uses the concatenation operator '&&' to combine the strings '123' and %1 with an interveaning space.

We will use values like these within EBL commands, described later, to control the actions or results they produce. If %1 contains XYZ again, then a batch file which contains:

TYPE ABC 123%1

ABC 123XYZ

Expressions

An expression may appear in any of the following forms:

     [string]                    
     [number] +  [number]         - addition
     [number] -  [number]         - subtraction
     [number] *  [number]         - multiplication
     [number] /  [number]         - division
     [number] %  [number]         - remainder
     [string] #                   - string length
     [string] $  [index] [length] - substring
     [string] &  [string]         - concatenation
     [string] && [string]         - concat' with space
     [string] ?  [string]         - locate string

For the above types of expressions, the following definitions are:

[var] - A DOS variable, global EBL variable, or extended variables. It may not be a character literal.

[string] - Any type of value. Letters, numbers, any variable, or any function result. It may also be a nested expression (up to 5 levels deep). 123, "ABC", %J, CENTER('text',25), and (5+3) are all valid strings.

[number] - Any string with a numeric result. This can be up to a 20 digit integer. For example, if %A contained 34, the numbers 98, %A, and 12%A5 (equivalent to 12345) would all be valid numbers. Numbers are always integers in EBL. Any fractional part after a decimal point is ignored. For full floating point support, use the FLOAT() function. If the value is empty (null), it will be interpreted as zero. If commas separate parts of the number, they will be ignored by EBL. EBL also accepts a unary minus sign immediately before the number provided these is no intervening space.

[index] - Same restrictions as [number] above, except that an [index] in the range 257 and higher is meaningless and is equivalent to the number 256.

[length] - Same restrictions as [number] above, except that a [length] in the range 256 and higher is meaningless and is equivalent to the number 255. Note that [length] is optional and has a default value of 255.

Variables in expressions

    BAT * Assignment Example
    %C = ABC                   |*
    TYPE %C                    |* Shows 'ABC'

Arithmetic Operators

     [number] + [number]
     [number] - [number]
     [number] * [number]
     [number] / [number]
     [number] % [number]

The % (percent) arithmetic operator computes the remainder of the division. The sign of the result may be either positive or negative. This remainder operator is useful since EBL's integer arithmetic provides no fractional part. If you always work with fractions, use the more powerful FLOAT() external functions described later. Examples of EBL arithmetic expressions are:

    BAT * Arithmetic examples...

    TYPE "These have GOOD results:"

    %A = 7
    %A = %A + 1               |* Result is 8
    TYPE (23 * %A)
    TYPE (13 / 3)             |* division result is 4
    TYPE (13 % 3)             |* remainder is 1
    TYPE (123 + -222)
    TYPE (123 + (1 - 223))


    TYPE "These have BAD results:"

    %A = 47 / 0               |* division by zero
    %A = 23 * 3.5             |* 3.5 not an integer
    %A = 9999999 * 999999890  |* result too large
    %A = 123 + - 222          |* minus not part of
                              |*           the number

String Operators

String Length

     [string] #

The Command:     Results in:


%A = ABDC #        4
%A = 345  #        3
%A = "12 45" #     5  (blanks are counted)
%A = %E   #        ?  (length of contents of %E)

Substring

     [string] $ [index] [length]

The $ operator creates a substring of the [string] value to the left of the operator. The [index] and [length] operands are used to define what portion of the [string] will be assigned to the final variable.

This operator returns a string of [length] characters from [string] beginning with the [index] character. If you omit the [length] or if there are less than [length] characters to the right of the [index] character, then all right most characters beginning with the [index] character will be returned. If [length] is equal to zero, or if [index] is greater than the length of [string], then the result will be an empty string. For example:

%A = ABCD $ 2 2          results in     BC
%A = ABCD $ 1 9                         ABCD
%A = ABCD $ 7 3                         (empty)
%A = ABCD $ 3                           CD

Note: In the last example, the [length] operand is optional and will default to 255. This will give the maximum length string possible.

Concatenation

     [string] &  [string]
     [string] && [string]

%A = ***12               results in     ***12
%A = *** & 12                           ***12
%A = *** && 12                          *** 12
%A = *** & ( 6 * 2 )                    ***12

Locate String

     [string] ? [string]

The locate string operator ? will find the position of the second [string] within the first [string]. If EBL did not find a match, then it returns 0. If it does match, EBL returns the first matching position.

%A = ABCDEFG ? DEF       results in     4
%A = ABCDEFG ? DOG                      0
%A = ABCDBCD ? BC                       2

Compound Operations

Operators and their associated values may be applied to the results of the previous operators. Compound operations of this type can be mixed between various types of [strings]. You can assume all values can be a [string]. Although EBL can easily convert all [number] values to [string] values, not all [string] values can be converted to [number] values to use in arithmetic calculations. Because of this, caution should be observed when mixing types,

When you use several operators and values within one statement, no precedence between operators exists. That is, the order of operations will be in a strict left-to-right order, no matter which operators are present. For example:

%A = 2 * 5 + 7           results in     17
%A = 5 + 7 * 2                          24
%A = ABC # * 4                          12
%A = ABCD $ 2 11 #                      3
%A = 100 * 99 $  2 2                    90
%A = A234C $ 3 2 / 3                    11

%A = A234C $ 1 2 / 3   (Error! The substring A2
                        is not a number which can
                        be divided by 3)

It is possible to group operations together with parenthesis for ease of calculation. EBL will calculate the expression in the inner most parenthesis first. Parenthesis can be nested up to five levels of depth and must always match. For each opening parenthesis "(" there must be a matching closing parenthesis ")".

%A = 2 * ( 5 + 7 )       results in     24
%A = 5 + ( 7 * 2 )                      19
%A = ABCD $ 2 11 #                      3
%A = ABCD $ 2 ( 11 # )                  BC
%A = 2 + ( 7 * ( 6 / 2 ) )              23

Expressions within other commands

Where ever you can use EBL variables and literals, an expression can also be used in its place. These expressions can be any calculations mentioned above including string operations, arithmetic operations, or any combination. The open parenthesis character '(' will mark the beginning of an expression. The expression follows and ends with a closing parenthesis ")". Expressions within the previous assignment statements also have the same form. When variables are referenced in expressions, only a look is made at their value so that a result can be calculated. This result will be the final single value that the expression represents. For example,

TYPE Result is ( 2 * ( 5 + 7 ) )


 displays:  "Result is 24"


IF (&Income - &Expenses) > 1000 THEN GOTO -BUYMORE

Note that parenthesis pairs "( ... )" may be used anywhere that an EBL variable or literal can be used. The expressions' value can not only be used in assignments, but also commands like TYPE,BEGTYPE, STACK, etc. Note also that the parenthesis must be used in pairs. Failure to do this will give the error message "Mismatched parenthesis". You can perform any expression, including string and arithmetic operations, within the parenthesis. Parenthesis can be nested up to 5 levels. Going beyond this will give the error message "Parenthesis is nested too deep. Limit is 5"

Note: If you need to have a value with only a single parenthesis, use the new reserved variable "%(" instead. Using this variable will place a single parenthesis in its place and will not perform the nested expression function mentioned previously.

Assignments

There are a number of ways to do an assignment. You have already seen simple assignments like variable = expression. When an expression contains a variable that is repeated from the left side, it can also be rewritten in a compressed form with an op= assignment operator.

For example

    %A = %A + 1

    %A += 1

The various types of assignments are:

 [variable]  = [expression]    
 [variable] += [expression]        - addition
 [variable] -= [expression]        - subtraction
 [variable] *= [expression]        - multiplication
 [variable] /= [expression]        - division
 [variable] %= [expression]        - remainder
 [variable] #=                     - string length
 [variable] $= [exp.index] [exp.length]    - substring
 [variable] &= [expression]        - concatenation
 [variable] ?= [expression]        - locate string

The first variable can be any DOS variable, global EBL variable, or extended variable. It cannot be an environment variable or predefined variable as they have a fixed content that can not be changed.

If no expression is supplied, like [variable] =, then the variable is assigned an empty result. Refer to the previous section for a discussion on various types of expressions.

EBL PLUS COMMANDS

BEEP

COMMAND:

BEEP [statement]

PURPOSE:

Sounds the speaker for the operator.

DESCRIPTION:

The speaker will sound for about 1 second by using this command. This can be used to alert the operator of an error condition or to request a response. The remainder of the line after the word BEEP may be any valid EBL statement. For more powerful control over the sound output, refer to the PLAY() function.

RELATED COMMANDS:

TYPE, BEGTYPE, PLAY()

EXAMPLES:

    BAT * BEEP example...
        BEEP TYPE "Your response was invalid."
        BEEP

BEGSTACK

COMMAND:

BEGSTACK
  [...text...] [;]
  [\hex]
  [\%Variable]
  [\( expression )]
END

PURPOSE:

Puts text into a keyboard stack in order to give automatic responses to programs.

DESCRIPTION:

This command is useful when sending a long series of data to the keyboard stack. The stack holds simulated keystrokes that will used by an application when it is ready. The characters will appear on the stack exactly as in the batch file. Spaces, case, and control characters are preserved. Text is copied from the EBL program to the keyboard stack until finding a line starting with "END" in column 1. The word END indicates that there are no more lines of text to send to the keyboard stack.

If the last character on the line is a ";" (semicolon) then the Enter key will not be stacked. This is useful when pressing the Enter key causes some side effect or undesired action in the application receiving the keystrokes. This can also be used to concatenate lines of text.

The general form for using the BEGSTACK command is as follows. Always put the keystrokes into the stack before executing the application. If you have another application, put the keystrokes for the next application after executing the first application.

    BAT * Form of Begstack EBL Programs...

    BEGSTACK
    Put all keystrokes and function keys here
    for the Application1 program.
    END

    Application1

    BEGSTACK
    Put all keystrokes and function keys here
    for the Application2 program.
    END

    Application2

Stacking Function Keys

The most easy way to add function keys to the stack is to use the KEY() function. This function can take the key name and convert it to the unique hardware scan code that represents this key.

    BAT * BEGSTACK & KEY() sample (2)...
    BEGSTACK
     This text and control key
     goes direct to the application...
     in this case the DOS COPY command.
    END
    KEY(Ctrl-Z)

    copy con: nul:

Another way to add a function key is to use the flag "\xx". If the line contains '\xx' where xx is a two digit hex value immediately following the backslash, then this hex value will be stacked. This is useful for entering control characters into the stack which some programs may need. For example '\1B' would enter the ESC (escape) character into the stack. Note that some keys (such as the function keys) have "Extended Codes" which require a 00 to be stacked before a second key code. Refer to Appendix D for a complete description of these keys.

If xx above is a variable or expression whos result is a two digit hex value, it will also be used as a keystroke value to put in the stack. The "\xx" flag method can only be used within a BEGSTACK block, not the STACK command or KEY() function.

    BAT * BEGSTACK sample (3)...
    BEGSTACK

     This set of control keys: \04\1c

     goes to the DOS COPY command.

     Again, Ctrl-Z ends it: \1A

    END

    copy con: nul:

If a second backslash follows the first, then a single backslash will be stacked. That is, a "\\" will create a single "\" keystroke.

By using the KEY() function, EBL programs are much clearer. The use of the \xx form is only intended for backward migration purposes. It should be avoided in new applications.

Stacking Variable results

A "%" (percent) after the backslash indicates that the contents of a variable should be used. If the content of the variable is exactly two digits and a valid hex number, it will be used as a control character value. Otherwise, the contents will be put directly into the stack. For example, if %A contained "03", using "\%A" after a BEGSTACK command would treat 03 as a CTRL-C control character (see Appendix D). If %A had only contained "3", using "\%A" would not have created a control character, but would just have put the ASCII number "3" into the keyboard stack.

If you have an open parenthesis '(' after the backslash, it indicates that an expression will follow. Any expression can be started with an open parenthesis and can contain arithmetic or string operations. The closing parenthesis ends the expression. The result of the calculation is used as the value to stack.

The previously mentioned rule about two digit control character values is still in effect with expressions. Therefore, if %A contains 3 and you use "\( 5 * %A )", then the control character 15 (Ctrl-U) will result.

    BAT * BEGSTACK & KEY() sample (4)...
    %A = 3
    %B = "DOS"
    BEGSTACK

     \%A times 5 is: \(%A * 5 & " ")

     This text and control key
     goes direct to the application...
     in this case the \%B COPY command.
    END
    KEY(Ctrl-Z)

    copy con: nul:

Hint: If you are ever unsure of an arithmetic result with an expression in BEGSTACK, just add a space on the end. For example, if you want to stack the expression result as keystrokes, use the expression '\( 5 * %A & " ")'. By adding a space on the end, it will never match the two digit rule. That is, it will be treated as the text value "15", not as a single control character.

Keystroke delays

Keystrokes are normally played back from the stack at full speed, which can be over 1000 characters per second. Some programs have problems receiving input at that speed. They may lose characters or start beeping furiously at you. If that happens, you can slow down sections of the keystrokes by adding delays. This feature is useful for communications programs which must pause for an acknowledgement before continuing to enter further commands from the stack.

One simple way to add delay is to use the KEY(PAUSE) function. The BEGSTACK command is not needed in this case. Each time this function is used, a one second delay will be placed on the stack. This can be used several times to increase the delay time if needed.

Another way to add a delay within a BEGSTACK block is to use the flag "\FF\xx". Again, xx is a two digit time delay value in hex. When a program reads the keyboard and \FF is the next character on the stack, the keyboard will look as if there are no more "keystrokes" available for a certain amount of time. To control the keystroke delay time, set the hexadecimal byte xx following the \FF to the number of CPU "ticks" to pause. There are roughly 18.2 CPU "ticks" to each second independent of your CPU speed. For example, stacking the data: "DELAYED \FF\20 TEXT" would cause a delay of about 2 seconds between the word "DELAYED" and the word "TEXT" when a program reads in this line. (20 hex is 32 decimal. At 18.2 CPU "ticks" per second, a 32 "tick" delay it will last 1.76 seconds.)

    BAT * BEGSTACK & KEY() sample (5)...
    KEY("This is a delay between>")
    KEY(Pause)
    KEY(" <Words")
    KEY(Enter)

    BEGSTACK
    This is also a delay between>;
    \FF\20 <Words
    END
    KEY(Ctrl-Z)

    copy con: nul:

Stacking Inline Code

In addition to simulated keystrokes, inline program code can also be placed in the stack. If you are familiar with assembly language programming, this technique can provide extra power within the stack in special instances.

The executable code must be preassembled and the hexadecimal machine code must be placed in the stack using BEGSTACK. The prefix within BEGSTACK is \F0\02\ss\cc\cc\cc ... \cc\C3; where ss is the size of the code bytes in hexadecimal (0 to FF bytes) and cc is the hexadecimal value of each byte to execute. The suffix \C3; must also be added. C3 is a near RET instruction and the ';' prevents an implied Enter key from being stacked.

Please refer to Chapter 9 for further information and examples of inline program code within the keyboard stack.

Hints

Some programs remove keystrokes before accepting a critical key. For example, a program may ask "Do you wish to erase this file? (y/n)". Programs will flush the keystroke buffer before looking for the answer to make sure that the correct answer is properly entered. In some instances, this will also flush the stack.

If you wish to avoid the stack being flushed past the desired keystroke in the stack, place a keyboard delay on the stack. Use \FF\01 within a BEGSTACK block, or use KEY(PAUSE) outside of BEGSTACK. This will cause the program to think for a short period that the keystroke buffer is empty. Your desired answer will then be accepted just after this.

Note that only a carriage return is stacked at the end of each line. A line feed, which is normally not entered from the keyboard, is also not stacked by EBL. If need to stack a line feed, you may do so by entering "\0A" in the text.

Refer to the description on how the keyboard stack can be used titled "Keyboard Stack" in this guide for additional hints. In addition, refer to Appendix B for examples using the stack.

BEGTYPE

COMMAND:

BEGTYPE
  [..text..] [;]
  [\hex]
  [\%Variable]
  [\( expression )]
END

PURPOSE:

Types a series of lines directly from the batch file.

DESCRIPTION:

This command is very useful for printing a long series of text to the user, usually a prompt or menu. The characters will appear exactly as in the batch file. Spaces, case, and control characters are preserved. Text is copied from the EBL program to the screen until finding a line starting with "END" in column 1. The word END indicates that there are no more lines of text to display.

If the last character on the line is a ";" (semicolon) then a carriage return/line feed will not be used. The cursor will remain at the end of the line. This can be used to concatenate lines of text, or to give a prompt for the user to enter data.

    BAT * BEGTYPE sample (1)...
    BEGTYPE
     Show any text you want.
     These two lines->;
     <-appear as one.
    END

Adding Color

The easiest way to add color to menus is to first use the COLORCHAR command to make a character represent a color change. Then, every time that character is used within the BEGTYPE block, future text will be highlighted with the new color. A space will be added where each color change occurs. This technique is useful for both BEGTYPE and TYPE commands.

    BAT * BEGTYPE color sample (2)...
    ColorChar '@' as Color(Yellow)
    BEGTYPE
     @This@is highlighted
    End
    Type "So is@this!@"

Another way to add color is to change the flag "\xx". If a line contains "\xx", where xx is a two digit hex value immediately following the backslash, then this hex value will be used as a color for the screen. Refer to Appendix D for all available combinations of colors. This allows text to be highlighted for the operator. The text color defaults to white on black (color Hex 07) at the beginning of the BEGTYPE command.

If xx is a variable or expression that results in a two digit hex value, it will also be used as a new color for the screen. The COLOR() function is useful to do conversions to hex values for use in expressions.

The flag "\xx" will not take any space on the screen when the color change occurs. While this gives tighter control over color changes than the COLORCHAR method, the spacing of menus within the batch file may appear awkward compared with the final result. The "\xx" flag method can only be used within a BEGTYPE block, not the TYPE command.

    BAT * BEGTYPE color sample (3)...
    %A = COLOR( Normal )
    %B = COLOR( Yellow )
    BEGTYPE
    \%BThis\%A text is yellow.
    This text is \0fHigh intensity\07
    END

If a second backslash follows the first, then a single backslash will be printed. That is, a "\\" will produce a "\" on the screen.

Showing Variable results

A "%" (percent) after the backslash indicates that the contents of a variable should be used. If the content of the variable is exactly two digits and a valid hex number, it will be used as an escape or color value. Otherwise, the contents will be directly displayed. For example if %A contained "0F", using "\%A" after a BEGTYPE command would treat 0F as a high intensity color value. If %A had only contained "F", using "\%A" would not have changed the color, but would just have printed out the "F" onto the display.

If you have an open parenthesis '(' after the backslash, it indicates that an expression will follow. Any expression can be started with an open parenthesis and can contain arithmetic or string operations. The closing parenthesis ends the expression. The result of the calculation is then used as the value to display.

The previously mentioned rule about having two digit color values is still in effect with expressions. Therefore if %A contains 3 and you use "\( 5 * %A )", then the value 15 will result and would be treated as a color 15.

Hint: If you are ever unsure of an arithmetic result with an expression in BEGTYPE, just add a space on the end. For example if you want to display (5 * 3) as a number, use the expression \( 5 * 3 & " "). By adding a space on the end, it will never match the two digit rule and will be treated as the text value "15". Use this technique to guarantee that the value will be displayed, instead of being used as a color.

    BAT * BEGTYPE sample (4)...
    %A = 70
    %B = B.Contents
    BEGTYPE

     Average values: \( %A / 5 & " " )

     The content of Var B is \%B
    END

File I/O

If file redirection is in effect for writing, then all data would normally be displayed will be sent to the file. You can open a file for writing with the ">filename" command, and closed with the ">" command. If redirection is active and a \xx style color value is within the text, then it will be sent to the file as a binary value, not as a color. This is useful for sending special control values to files or devices like printers (LPT1). Refer to the File I/O section later in this chapter for examples.

CALL

COMMAND:

CALL [-label] [parm] [parm] ...

PURPOSE:

Changes the flow of execution within the batch file by using subroutines. Parameters can also be passed to the subroutine.

DESCRIPTION:

The string following the CALL command may have a '-' (minus) as its first character. This identifies it as a local label within the current EBL program. EBL will then start scanning, at the top of the EBL program for this label. If it is found, the location of the CALL command is saved and execution will begin from the new label. You should end the local subroutine with a RETURN command. An error will result if the label is not found.

As an alternative, if the label does not have a '-' minus as its first character, then the CALL command will call another external EBL program in another file, rather than a local subroutine within the current EBL program. You should end the external EBL program with an EXIT command (the RETURN command is local only within the currently executing batch file).

Note: The called batch program can not use the LEAVE command, and can not start TSR type applications. Refer to the LEAVE command for more information.

Remember the different indicators between calling EBL labels and calling external EBL programs. EBL uniformly uses the "-" (minus) symbol to indicate a local label and no minus symbol to indicate an external EBL program. That is:

   CALL -LABEL    (looks for EBL label  "-LABEL")
   CALL LABEL.BAT (looks for the file   "LABEL.BAT")

When the subroutine ends, EBL will return to the line following the CALL command. Execution will resume from this point.

• To end local EBL subroutines, use the RETURN command.
• To end external EBL programs, use the EXIT command.

In both case, EBL will branch back to the statement following the most recent CALL command. Subroutines may appear anywhere in the EBL program.

To prevent your program from accidentally entering a subroutine, you may want to put a GOTO command in front of a local subroutine. This will direct program control around it.

When you call a subroutine, the subroutine may call other subroutines. However, if you nest them too may times, it will overflow the available memory and result in an error.

• Local EBL subroutines can be nested 31 times before a corresponding RETURN command must be executed.
• External EBL program nesting depends on the amount of memory your system contains.

The label can also contain a variable, which will allow the CALL command to act like a case statement. Multiple way branches can therefore be created with a statement like "CALL -%A".

With the CALL command, you can also pass parameters to subroutines.

• For local subroutines, text after the label will be placed onto the keyboard stack in a "LIFO" (last in first out) format. The READ command is used in the subroutine to assign these parameters to variables.
• For external EBL programs, text after the label will be passed to the %0 to %9 variables. These variables are local to the called EBL program file only. Changes to them will not be shared with the calling program.

The following program segment will illustrate how local subroutines handle parameters:

     %A = PARM3
     CALL -LABEL PARM1 PARM2 %A
     .
     .
     .
    -LABEL READ %1 %2 %3
     ...
     RETURN

In this example, the subroutine is called "-LABEL". Following it, three values will be put onto the stack "PARM1 PARM2 PARM3". Notice that these values can have variables or expressions. In this example, the contents of %A will be used as the third parameter. The READ command, which starts the subroutine, will put the parameters into the variables %1 to %3. If no parameters exist after the label, nothing is put onto the stack. Therefore, it is necessary to make sure that the parameters match between the CALL and the subroutine which uses the parameters.

If something is already on the keyboard stack during parameter transmission, it will not be altered or destroyed since the "LIFO" form of stacking is done. Use caution, however, if you have a file open ready for reading as the READ command will prefer to read the file instead of the stack. You can suspend and resume file I/O with the "<" and "<<" commands respectively. In general, passing parameters to local subroutines with this method is preferable to other, more clumsy, methods.

RELATED COMMANDS:

RETURN, GOTO, IF, SKIP, /R, SHELL, EXIT

EXAMPLES:

    BAT * Subroutine example
        CALL -SUB.NAME "a"
        CALL -SUB.NAME "another"
        TYPE "Back from subroutine"
        EXIT
    -SUB.NAME READ %0
        TYPE "This is" %0 "line"
        TYPE "  inside the subroutine"
        RETURN

    This is a line
      inside the subroutine
    This is another line
      inside the subroutine
    Back from subroutine

CALL.PURGE

COMMAND:

CALL.PURGE [levels]

PURPOSE:

Removes pending RETURN address from the CALL/RETURN stack.

DESCRIPTION:

This command clears out the CALL/RETURN stack for error recovery handling routines. All previous local subroutine calls that were pending (without RETURNs being executed) are removed. Once removing pending addresses, the CALL command can be nested up to 31 levels deep, no matter how many previous levels were previously pending. Normally, the RETURN command is the only way to remove the nested return address locations.

With no operands, CALL.PURGE will remove all pending CALL/RETURN levels. However, [levels] can be any numeric value from 0 to 31 so that it can selectively delete that number of RETURNs and others will be saved. All levels will be purged if you do not use a number or use an amount beyond what was saved. When only a portion of levels are purged, the last executed CALLs will be the ones to be purged. See the example below for a sample. The command only affects local subroutine nesting. No change is made to the way external EBL programs are nested.

In general, if you are just starting with EBL, do not use this command. It is only intended if a more complex error recovery scheme is required.

It is poor coding practice to use this command within the normal control flow of programs. It is best to use it only in rare and exceptional conditions, where necessary. Generally, subroutines should be "pure" so that they will operate in "layers". Doing a GOTO between layers instead of a CALL or RETURN will need CALL.PURGE to correct the stack and should be avoided. However, in instances of error recovery or exception conditions, CALL.PURGE may be necessary to "clean up" the stack.

Generally, you may need a "CALL.PURGE" command just after an -ON.ERROR- error trap location. This will clean up the stack so that future CALL commands will have room for proper growth without overflow. Then use the GOTO command, not the CALL or RETURN commands, to resume execution at a known location. That is:

    -ON.ERROR-
     CALL.PURGE [levels]
      ... test for error types ...
      ... and do any clean up  ...
     GOTO -Resume.Location

This example is to show typical structure only. In real usage, the amount of levels may depend on the type of error that has occurred and the location of the error within the program. Use CALL.PURGE carefully so that the stack remains balanced (previous call levels pending will equal future returns) even after the GOTO to the -Resume.Location.

RELATED COMMANDS:

CALL, GOTO, RESUME, RETURN, -ON.ERROR-

EXAMPLES:

    BAT * Example of CALL.PURGE command.

    -A Type Calling level B
       Call -B
       Type Returned from level B
       Exit

    -B Type Calling level C
       Call -C
       Type Returned from level C
       Return

    -C Type Calling level D
       Call -D
       Type Returned from level D
       Return

    -D CALL.PURGE 1
       Return

    Calling level B
    Calling level C
    Calling level D
    Returned from level C
    Returned from level B

CLS

COMMAND:

CLS [statement]

PURPOSE:

Clears the screen.

DESCRIPTION:

The screen type (color 40, color 80, mono, etc) is sensed via BIOS and this screen is cleared. This is very useful when creating prompts on the screen for the user and is often used just before the commands TYPE or BEGTYPE. The remainder of the line after the word CLS may have any valid EBL statement.

RELATED COMMANDS:

TYPE, BEGTYPE

EXAMPLES:

    BAT * CLS Example...
    CLS BEGTYPE
       This is a prompt for the user.
       They will see it on a new clear screen.
    END

COLORCHAR

COMMAND:

COLORCHAR [char] {as} [color value]

PURPOSE:

Changes a text character to a screen color whenever it is typed out.

DESCRIPTION:

The COLORCHAR command causes a character to represent a selected screen color. When you display the selected character with a TYPE or BEGTYPE command, only a blank is shown, but the screen color changes to the requested color. When you display this same character a second time, the original screen color is restored. The color can be toggled on and off in this manner to surround the highlighted area.

COLORCHAR can be used to hold up to eight character/color pairs. If one color is being used when a second is turned on, the first will be saved. When the second is turned off, the first color is restored. Colors can be "nested" in this way up to eight levels deep.

If you have used COLORCHAR with one character and you request the same character to represent a new color, the first association is removed.

If you indicate a character without any color, then no further association will be made. That character will be seen as it is without changing the screen color. If you also use the COLORCHAR command without indicating any characters or colors, then all color associations will be removed.

RELATED COMMANDS:

TYPE, BEGTYPE

EXAMPLES:

    BAT * COLORCHAR Example...
    COLORCHAR '@' as COLOR( red on black )
    COLORCHAR '$' as COLOR( yellow on black )
    BEGTYPE
       This is a demonstration of$COLORCHAR$

       Whenever selected characters are printed
       they make the screen color change.

      @Note that colors can be$nested$ on the screen@

       Also@colored@characters@toggle@on@and@off!

    END
    TYPE "This is useful in the@TYPE@command..."

    COLORCHAR '@'
    TYPE "and can be @Individually@ removed...."

    COLORCHAR
    Type "or all can be removed as a group."

EXIT

COMMAND:

EXIT

PURPOSE:

Ends the batch file.

DESCRIPTION:

EXIT requires no operands, and will immediately stop the batch file from being processed. DOS will then show a prompt for accepting new commands from the user. If data has been put on the keyboard stack (see STACK or BEGSTACK) then the stack will start feeding DOS with commands without waiting for the user.

This command is used to return to DOS in the middle of a batch file. It is not necessary to use this command at the end of batch files. The normal end-of-file mark within the file will also exit in the same manner.

RELATED COMMANDS:

IF, STACK, BEGSTACK

EXAMPLES:

    BAT * EXIT example
     TYPE "Would you like to exit? (Y/N)"
     READ  %9
     IF %9 = Y EXIT
    .
    .
    .

In the above example, the user is prompted to see if they would like to exit the batch file before continuing. If they type 'Y' and press enter, the compare will match and the batch file will end. Otherwise, processing will continue.

GOTO

COMMAND:

GOTO [-label]

PURPOSE:

Changes the flow of execution within the batch file.

DESCRIPTION:

The string following the command GOTO may have a '-' (minus) as its first character. This identifies it as a local label within the current EBL program. EBL will then start scanning, from the top of the EBL program, for this label. If it is found, command execution will begin processing at this line. If it is not found, an error will result. An example of an infinite loop using the GOTO command would be:

    BAT * Infinite loop example

    -SELF GOTO -SELF

The label can also contain a variable. This allows the GOTO command to act like a case statement. Multi-way branches can be easily created with a statement like "GOTO -%A".

As an alternative, if the label does not have a '-' minus as its first character, then the GOTO command will start another external EBL program in another file, rather than a label within the current EBL program. Text after the label will be passed to the %0 to %9 variables for the external EBL program to use.

Note: The external program can not use the LEAVE command, and can not start TSR type applications. Refer to the LEAVE command for more information.

Remember the different indicators between EBL labels and starting external EBL programs. EBL uniformly uses the "-" (minus) symbol to indicate a local label and no minus symbol to indicate an external EBL program. That is:

   GOTO -LABEL    (looks for EBL label  "-LABEL")
   GOTO LABEL.BAT (looks for the file   "LABEL.BAT")

RELATED COMMANDS:

CALL, IF, SKIP, Comments

EXAMPLES:

    BAT * Example of GOTO command.
    -TOP
        READ Enter an animal's name> %0
        GOTO -%0
    -Pig
        TYPE A pig goes oink.
        GOTO -TOP
    -Cow
        TYPE A cow goes moo.
        GOTO -TOP
    -%0
        TYPE I don't know how a %0 goes!
        GOTO -TOP

This example prints the result on the display:

    Enter an animal's name> COW
    A cow goes moo.
    Enter an animal's name> DOG
    I don't know how a DOG goes!
    Enter an animal's name>

IF

COMMAND:

IF [expression] [comparison] [expression] [...stmts...]

PURPOSE:

Tests for various conditions in order to alter the way the batch file executes.

DESCRIPTION:

Three parts are expected after the command word IF. The first and third parts are expressions that are held temporally while the comparison is being made. The second part is the comparison operator and must be one of the following:

     IS        - equal
     IS NOT    - not equal
     <         - less than
     <=        - less than or equal
     =         - equal
     ==        - exactly equal (case sensitive)
     >         - greater than
     >=        - greater than or equal
     <>        - not equal

For an equality to exist between two strings, they must match in both value and length. This comparison is done with the "=" and "<>" operators that test for equal and not equal respectively. Note that these comparisons are case insensitive. That is, the upper case letters "ABC" would be considered equal to the lower case letters "abc".

A case sensitive version of the equal operator is "==". Using this operator, "ABC" will not equal "abc". Only when the case matches exactly will they be considered equal. For example "AbC" equals "AbC" with the "==" operator, but "ABc" does not equal "AbC".

For less-than or greater-than comparisons, two possible tests are done.

First, if string lengths are not equal, the string with the larger number of characters is greater than the string with the smaller number of characters. That is, the string "0000" will be greater than "0", even though numerically they have the same value.

If string lengths are equal, the ASCII value of the characters are compared. The string with the higher ASCII value is the greater. Refer to an ASCII table or the Appendix in the BASIC Reference manual for these values.

If the comparison is true, then the statement that follows the IF command will be executed. This may be ANY batch command. If the comparison is false, then the remainder of the line is skipped and command execution will resume with the next line. Note that multi-IF comparisons are possible, although limited. The statement which follows the comparison of the IF can just as well be another IF statement. This has the effect of ANDing together the conditions. That is, all comparisons must be true in order for the final statement to be executed. See the last statement in the examples below for a sample.

THEN and ELSE

The IF command should be combined with the THEN or ELSE commands for improved control flow and readability. The last IF command executed will affect the THEN or ELSE commands, even if they are separated by several lines. Extended Batch Language will remember the results from the last IF command processed. If the condition IS true, any statements after upcoming THEN statements will be executed. If the condition is NOT true, then statements after upcoming ELSE statements will be executed.

IF commands do not need a comparison operator. If an expression is followed by THEN or ELSE, the expression is tested to determine if the IF clause passes. If the expression is null (empty), or an 'F' or '0' value, the result is considered false. Any other value is true. This can be a convenient way to test results in variables, expressions, or functions. For example:

 BAT * IF example 1...
       IF %A THEN TYPE "Result in %A was True."
       IF %A ELSE TYPE "Result in %A was False."
 -Wait IF NOT(KEYPRESSED()) THEN TYPE "Waiting..."
          THEN Goto -Wait

The result of the last IF comparison is remembered by EBL so that the THEN and ELSE commands can also be used on separate lines. Note that the last statement in the example above uses this feature.

Additionally, DOS commands can be executed after a THEN or ELSE command. For example "IF %A = doit THEN COPY file1 file2" is a mixture of the IF command in EBL and the COPY command in DOS.

BEGIN ... END

The IF command can also be combined with a BEGIN command. The entire group of commands between BEGIN and END will be executed, or skipped, depending on the previous IF condition.

The BEGIN and END statements allow you to write with structured programming. They surround a group of commands that are executed only as a group. There is always an IF statement somewhere before the BEGIN statement. This will determine if the statements between the BEGIN and END keywords will be executed. An ELSE statement can also be used to determine if an alternative block structure will be executed. For proper nesting, the BEGIN and END keywords must be the first keywords on the line.

You can use the statements freely as long as both BEGIN and END statements are used in pairs. You can nest these pairs within other BEGIN/END pairs up to 8 levels deep. Also, be careful to never have a GOTO that is used to enter or leave a BEGIN/END block. Doing so can cause an error showing that the block was nested too deep. Finally, you cannot use the LEAVE command from within a BEGIN/END block since LEAVE forces EBL to give up control of the program. To improve readability, used indentations like those shown in the examples below.

RELATED COMMANDS:

EXIT, GOTO, SKIP, THEN, TYPE, Assignments

EXAMPLES:

All the following IF statements will compare correctly:

BAT * IF example 2. All will compare correctly.
 %1 = ABC
 %2 =

 IF ABC = %1     TYPE The variable contains ABC.
 IF %1 = abc     TYPE This also matches.
 IF 0 <> 00      TYPE These are different lengths.
 IF 0 < 00       TYPE 0 has a smaller length.
 IF 456 > 123    TYPE Numerically, 456 is bigger.
 IF 456 < %1     TYPE ASCII value of 456 is smaller.
 IF AABCD = A%1D TYPE Substitutions are made.
 IF %2 <> %1     TYPE Variables are different lengths
 IF .%2 = .      TYPE This matches if var is empty.
 IF 1 + 2 = 3    TYPE Arithmetic results match.

 IF ABC = %1   THEN TYPE The 'Then' helps flow.
  THEN TYPE 'Then' will execute even if on next line.
  ELSE TYPE 'Else' will NOT execute since IF passed.

 IF ( 5*(4/2) ) = 10 Type Expressions match.

 IF BOX = BOX IF DOG <> CAT TYPE "Multi-IF compare."

This example demonstrates the use of structured BEGIN/END blocks.

    BAT * BEGIN/END - IF Example...
    IF %a = %b THEN
    BEGIN
       TYPE "This message is displayed"
       TYPE "if the values ARE equal."
    END if
    ELSE
    BEGIN
       TYPE "This message is displayed"
       TYPE "if the values are NOT equal."
    END if

INKEY

COMMAND:

INKEY [text] [variable]

PURPOSE:

Accepts a single keystroke from the user as a response. Optional text may be included as a prompt to the user.

DESCRIPTION:

This command will wait for the user to enter a single key on the keyboard. If the optional variable is specified, the key name will be placed into that variable. This key can be not only letters, but all function keys, control keys, and so on.

If the pressed key is between "!" to "z" (decimal 33 to 122) then the key will be echoed to the screen. Lower case letters will be converted to upper case before being stored into the variable. If the key is not in this range, then the key will be converted to the form "KEYxxx" where xxx is the hex value of the key. Refer to Appendix D of this manual for a complete description of the various assignments of key codes. The KEY() function can be used to convert between this hex value, and the common name on the key itself.

When working with function keys, the CHARIN() function is a flexible alternative. The CHARIN() function is almost the same as INKEY except function key names are always provided rather than a hex value.

The key pressed does not have to be assigned to a variable. INKEY will wait for a key and discard it. For example

    INKEY Press any key when ready...

In the event that you wish to clear the keyboard of any pre-typed characters before executing the INKEY command, precede it with a STACK.PURGE command. This forces the system to wait until a character is typed.

Optional text before the variable will be displayed as a prompt for the user if present. The cursor will remain on the same line just after the prompt text. Quotes are not needed. It is copied to the screen exactly as it appears in your EBL program. Only leading blanks to the text will be ignored. As a result of this text prompt, the two statements:

    TYPE "This is your prompt ;"
    INKEY %7

can be replaced with the simpler and equivalent form:

    INKEY This is your prompt %7

In addition, the TYPE command and CHARIN() function can make a similar prompt. Because function key names are also returned, the CHARIN() function can be a flexible substitute for the INKEY command.

    TYPE "This is your prompt ;"
    %7 = CHARIN()

The STACK command has no effect on the INKEY command. The keystroke always comes from the physical keyboard, never the stack, even if the stack contains its own keystrokes. Use the READ command if you wish to get keystrokes from the stack.

RELATED COMMANDS:

READ, STACK.PURGE, CHARIN(), KEY(), KEYPRESSED()

EXAMPLES:

    BAT * INKEY example...
    * Empty the working variable.
       %0 =

    * Read in a key, then append it to working var.
    * Exit when found the carriage return.
    Repeat until %1 = "KEY00D"
       INKEY %1
       %0 = %0 && %1
    End Repeat

    * Show results of reading all those keys.
       Type "Resulting string =" %0
       Exit

When this EBL program is run and the keys A, b, F6, Tab, and carriage return are pressed, the result will be shown as:

    Resulting string = A B KEY140 KEY009 KEY00D

INTERPRET

COMMAND:

INTERPRET [expression]

PURPOSE:

Executes the EBL command contained in the expression.

DESCRIPTION:

The INTERPRET command will execute any other EBL command based on the value of the expression. The expression may be any combination of literals or variables. The result of the expression is used as a new EBL command that is executed. Because variables can be used, any EBL command can be created "on the fly". INTERPRET is especially useful when the EBL command is created from user replies.

EXAMPLES:

    BAT * INTERPRET example... (a simple calculator)

        READ.PARSED Enter a math equation: %A

        Type 'Equation is:' ( %A )

        INTERPRET "Type 'Result is:  ' (" %A ")"

    Type 'Result is:  ' ( 3+5 )

    Equation is: 3+5

    Result is:   15

LEAVE

COMMAND:

LEAVE

PURPOSE:

Stops executing EBL commands and passes control to DOS for future batch file commands. It must be used before DOS applications that become resident (TSRs)!

DESCRIPTION:

The LEAVE command tells Extended Batch Language to stop executing the batch file and return control to DOS. DOS will continue executing the batch file on the next line. EBL will terminate and relinquish the memory it used to DOS. In order to return control back to EBL, you must explicitly use the program name "BAT" in the batch file that is executing.

The term "TSR" means Terminate and Stay Resident. Examples of TSR programs that become resident are pop-up applications like Sidekick and SuperKey or certain DOS commands like PRINT and SHARE. If you want to run an application that leaves part of itself in memory, to preform some function in the background, then you must use this command. Doing otherwise will leave holes in memory that can lead to system crashes.

If a command is encountered that is not understood by EBL, it is always passed to DOS. Extended Batch Language will create an implied (hidden) SHELL command of its own in order to transfer control. By default, an implied SHELL command is used, but can be changed with the "/L" (leave) option. This will transfer commands to DOS with the LEAVE command if you use the "/L" option. To return to the default mode, transferring commands to DOS with the SHELL command, use the "/S" (shell) option.

In the following example, the LEAVE command is used to return control of the batch file to DOS.

    BAT   * LEAVE example - Explicit LEAVE
            TYPE "Going to do XYZ application.."
            LEAVE
    XYZ
    BAT   * Return to EBL..
            TYPE "Did XYZ"

Notice that LEAVE gives DOS full control starting from the line with the XYZ command. In order to resume execution with EBL, a "BAT" command is needed at the start of the line. This line tells DOS to reload Extended Batch Language from the disk and resume processing. Note that any options that are required must be restated again in the batch file, or added to a BAT environment variable. Refer to the Appendix G Special Installation if you want to change EBL defaults with the environment variable.

A word of caution. Do not try to use the LEAVE command in instances where a window environment is using EBL to execute batch files. In these cases, COMMAND.COM is either altered or not used to execute other programs. If the LEAVE command is used, execution of the batch file may simply stop cold and not continue. Also, do not use the LEAVE command in the middle of a BEGIN/END or REPEAT/END pair of commands. Doing so will lead to block nesting errors.

RELATED COMMANDS:

SHELL, /L option, /S option

EXAMPLES:

    BAT * Example 2 using LEAVE command

    -Doread
        READ File to display? %1

        LEAVE
    Type %1
    BAT * Return to EBL..

        READ Display another? (y/n) %1
        IF %1 = Y GOTO -Doread

LOCATE

COMMAND:

LOCATE x y

PURPOSE:

Moves the cursor position so text can be positioned anywhere on the screen.

DESCRIPTION:

This command moves the cursor to the position specified by the X and Y values. X can be in the range from 1 to 80, and Y can be from 1 to 25. To position the cursor at the upper left use "LOCATE 1 1", and to position the cursor at the lower right (on an 80 column screen) use "LOCATE 80 25".

This command is useful when followed by a TYPE command to position text on the display. It can also be used before a READSCRN command to read specific lines from the display.

RELATED COMMANDS:

TYPE, BEGTYPE, READSCRN

EXAMPLES:

    BAT * LOCATE example

      Cls
      LOCATE 10 5 | Type "LOCATE example!"

      Repeat with %I = 1 to 4
        LOCATE %I %I
        Type "Zig!;"
      End Repeat

      Repeat with %I = 5 to 9
        LOCATE (10 - %I) %I
        Type "Zag!;"
      End Repeat

    Zig!
     Zig!
      Zig!
       Zig!
        Zag! LOCATE example!
       Zag!
      Zag!
     Zag!
    Zag!

-ON.ERROR-

COMMAND:

-ON.ERROR-

PURPOSE:

This label marks the beginning of an EBL error recovery procedure.

DESCRIPTION:

Even with a perfectly debugged program, many types of errors can still be created due to user errors or system environment. When an error occurs, EBL will look for the "-ON.ERROR-" label within the batch file. If it exists, EBL will do a GOTO to the procedure following the label. No error message will be displayed by EBL. It is the responsibility of this procedure to recover, or display, an error message of its own. If this label does not exist, the error message is displayed as usual and batch file execution is halted.

Appendix C lists all error messages and and associated numbers. This message number is saved in the %R variable when the error occurs. It can be used to determine the cause of the error once the error recovery procedure has started.

As a second aid, the line number of the statement that generated the error is saved in the %L variable. The first line of the file is number 1 and proceeds sequentially down the file. It includes blank lines as well as lines with statements. If the error occurred in immediate mode outside of a batch file, then %L will be 0.

Note that some errors are considered severe. These will always be displayed and terminate batch file execution. These errors are listed in Appendix C without error message numbers. You cannot expect to recover from these errors under any circumstance.

RELATED COMMANDS:

RESUME

EXAMPLES:

    BAT * Error Recovery example.
    -TOP
       READ Enter a number> %0
       %1 = %0 * %0
       TYPE %0 "squared is" %1
       GOTO -TOP
    -ON.ERROR-
       IF %L <> 4 SKIP 2
         TYPE "Not a valid number!"
         GOTO -TOP
       TYPE "Unknown error" %R "in line" %L.
       EXIT

    Enter a number> 2
    2 squared is 4
    Enter a number> ABC
    Not a valid number!
    Enter a number>

PARSE

COMMAND:

PARSE [expression] [variable] [delimiter] [variable]...

PURPOSE:

Separates [expression] into parts and assigns each to one or more [variables]. [Delimiter] can be defined to identify the point at which [expression] is separated into parts for each [variable].

DESCRIPTION:

The [expression] will be separated at the points indicated by the [delimiter] operand in this command. For example, if the delimiter is a blank, an [expression] that contains "EBL HAS MANY EXTRA-COMMANDS" will be assigned four separate values: "EBL", "HAS", "MANY", and "EXTRA-COMMANDS". If, however, the [delimiter] is a "-" (minus) sign, then the same response will be separated into only two values: "EBL HAS MANY EXTRA" and "COMMANDS".

The delimiter indicated between each variable name indicates the separation point before the assignment is made to each variable. Once the string is separated, each value will be assigned, in order, to the variables indicated after the PARSE command. If there are no more variables after the PARSE command to assign, the remainder of the response is discarded. If there are more variables to be assigned after the PARSE command than there are values from the original string, these variables will be cleared out to an empty state.

Again, [expression] is parsed at the single [delimiter] character between words. All of [expression] that does not match [delimiter] is put into the last [variable] in the list. If [delimiter] is the last item in the list, then [expression] contents after [delimiter] are ignored. If no [delimiter] is provided, [expression] is put into [variable]. If there are more [variables] than text to be stored, these [variables] are cleared out (set to null). The [delimiter] must immediately follow the [variable] name (no spaces) and must be a single character only. All characters after [delimiter] are expected to be a valid [variable] name. Note that a space can also be a [delimiter].

For example, if the the variable %0 contains "To be, or not to be?", the following PARSE commands will result. The READ.PARSED and READSCRN.PARSED commands would be have similar results.

 %0 = "To be, or not to be"

 PARSE %0 %A        %A contains "To be, or not to be"

 PARSE %0 %A %B     %A contains "To"
                    %B contains "be, or not to be"

 PARSE %0 %A,%B     %A contains "To be"
                    %B contains " or not to be"

 PARSE %0 %A,%B,%C  %A contains "To be"
                    %B contains " or not to be"
                    %C contains nothing. (null)

RELATED COMMANDS:

READ.PARSED, READSCRN.PARSED

EXAMPLES:

    BAT * PARSE Example

        PARSE Date() %A %B %C      |* get system date

        TYPE Today is day number %A of the year %C

    Today is day number 12 of the year 1995.

READ

COMMAND:

READ [prompt] [variable] ... [variable]

PURPOSE:

Accepts a response (with optional prompt) from a user and assigns it to one or more variables.

DESCRIPTION:

When the command READ is executed, an optional prompt is displayed and a line of text is accepted from the user. All function keys are assigned to the normal DOS edit functions. When ENTER is pressed, the input line is split apart into individual words with spaces as delimiters. For example, the response typed by the user "EBL IS VERY POWERFUL" will be assigned four separate values: "EBL", "IS", "VERY", and "POWERFUL".

Once the response is split apart, each value will be assigned, in order, to the variables indicated after the READ command. If there are no more variables after the READ command to assign, the remainder of the response is discarded. The special variables %R, %V, and environment variables, are not writable and are not allowed as arguments of the READ command. If there are more variables to be assigned after the READ command than there are words from the input, these variables will be cleared out to an empty state.

Note: There do not have to be any variables indicated after the command READ. In this case, EBL would wait for the enter key, discard any response, then continue to process the next batch file command.

Note: The READ command can get text from places other than the keyboard, such as files and the keyboard stack. In the event that more than one source has text available at the same time, the following priority is used:

    1. A file
    2. The keyboard stack
    3. The keyboard

In the case of a file, it must first be opened with a "<filename" statement before the READ command will read the file's data. Note that if you wish to suspend, and later resume file reading, use the "<" and "<<" commands respectively. In the case of the keyboard stack, use the STACK or BEGSTACK commands to make text available for the READ command. Stack reading can be suspended and resumed with the STACK.OFF and STACK.ON commands respectively.

Reading from a file or the keyboard stack will not echo its text to the display. Reading from the keyboard directly, will echo the test being typed to the display.

There is a 250 character buffer allocated for data on the READ command. When reading data from the physical keyboard, DOS will cause a beep if the user tries to type pass this limit. If the data comes from the stack or a file, exceeding this limit will cause an error message, the stack will be purged of any remaining data, and the EBL program will be stopped.

Text may be included in the READ command before the list of variables. If present, it will be displayed as a prompt for the user. The cursor will remain on the same line just after your prompt text. The text can not contain variables or expressions and is copied to the screen exactly as it appears in your batch program. Only leading blanks to the text will be ignored. As a result of this text prompt, the two statements:

    TYPE This is your prompt ;
    READ %7

Can be replace with the simpler and equivalent form:

    READ This is your prompt %7

RELATED COMMANDS:

BEGTYPE, IF, TYPE

EXAMPLES:

    BAT * READ example.
    Repeat until %1 is not ""
        READ Type your FIRST and LAST name> %1 %2
    End Repeat
    Type "HELLO" %1 %2

Type your FIRST and LAST name>

Type your FIRST and LAST name> Frank Canova Jr.
HELLO Frank Canova

READ.PARSED

COMMAND:

READ.PARSED [prompt] [variable] [delimiter] [variable]...

PURPOSE:

Accepts a response (with optional prompt) from a user and assigns it to one or more variables. A delimiter can be defined to identify the point at which the response is separated into components for each variable.

DESCRIPTION:

When the command READ.PARSED is executed, an optional prompt is displayed and a line of text is accepted from the user. All function keys are assigned to the normal DOS edit functions. When ENTER is pressed, the response line is parsed. That is, words will be separated at the points indicated by the delimiter operand in this command. If the delimiter is a blank, the response from a user "EBL HAS MANY EXTRA-COMMANDS" will be assigned four separate values: "EBL", "HAS", "MANY", and "EXTRA-COMMANDS". If, however, the delimiter is a "-" (minus) sign, then the same response will be separated into only two values "EBL HAS MANY EXTRA" and "COMMANDS".

The delimiter indicated between each variable name will indicate the separation point for parsing before the assignment is made to each variable. Once the response is parsed, each value will be assigned, in order, to the variables indicated after the READ command. If there are no more variables after the READ command to assign, the remainder of the response is discarded. The special variables %R, %V, and environment variables are not writable and not allowed as arguments of the READ command. If there are more variables to be assigned after the READ command than there are values from the input, these variables will be cleared out to a empty state.

All of the response that does not match the delimiter is put into the last variable in the list. If the delimiter is the last item in the list, text after the delimiter is ignored. If no delimiter is provided, the entire response is put into the variable. If there are more variables than text to be stored, these variables are cleared out (set to null). The delimiter must immediately follow the variable name (no spaces) and must be a single character only. Any characters after the delimiter are expected to be the next variable name and must be valid. Note that a space can also be a delimiter.

If the input from the user is "To be, or not to be?", the following READ.PARSED commands will result. The PARSE and READSCRN.PARSED commands would be have similar results.

 Where user entered: "To be, or not to be"


 READ.PARSED %A
                    %A contains "To be, or not to be"


 READ.PARSED %A %B     %A contains "To"
                       %B contains "be, or not to be"


 READ.PARSED %A,%B     %A contains "To be"
                       %B contains " or not to be"


 READ.PARSED %A,%B,%C  %A contains "To be"
                       %B contains " or not to be"
                       %C contains nothing. (null)

Note: There do not have to be any variables indicated after the command READ.PARSED. In this case, EBL would wait for the enter key, discard any response, then continue to process the next batch file command.

Note: The READ.PARSED command can get text from places other than the keyboard, such as files and the keyboard stack. In the event that more than one source has text available at the same time, the following priority will be used:

    1. A file
    2. The keyboard stack
    3. The keyboard

In the case of a file, it must first be opened with a "<filename" statement before the READ.PARSED command will read the file's data. Note that if you wish to suspend, and later resume, file reading, use the "<" and "<<" commands respectively. In the case of the keyboard stack, use the STACK or BEGSTACK commands to make text available for the READ.PARSED command. Stack reading can be suspended and resumed with the STACK.OFF and STACK.ON commands respectively.

Reading from a file or the keyboard stack will not echo its text to the display. Reading from the keyboard directly, will echo the text being typed to the display.

There is a 250 character buffer allocated for data on the READ.PARSED command. When reading data from the physical keyboard, DOS will cause a beep if the user tries to type pass this limit. If the data comes from the stack, however, exceeding this limit will cause an error message, the stack will be purged of any remaining data, and the EBL program will be stopped.

Text may be included in the READ.PARSED command before the list of variables. If present, it will be displayed as a prompt to the user. The cursor will remain on the same line just after the prompt text. The text is not parsed and is copied to the screen exactly as it appears in your batch program. Only leading blanks to the text will be ignored. As a result of this text prompt, the two statements:

    TYPE This is your prompt ;
    READ.PARSED %7

Can be replace with the simpler and equivalent form:

    READ.PARSED This is your prompt %7

RELATED COMMANDS:

BEGTYPE, IF, PARSE, READ, TYPE

EXAMPLES:

BAT * Read.Parsed Example


-again READ.PARSED Type your FIRST and LAST name: %1

    IF /%1 = / GOTO -again

-again2
    Type "Hello" %1, "please enter the date"

    READ.PARSED in the form mm/dd/yy: %A/%B/%C

    If /%C = / then goto -again2    |* check presence
    if %C # <> 2 then goto -again2  |* check length

    %A = %A + 0                     |* strip 0's
    %B = %B + 0

    If %A = 1        then %E = st   |* creating end
      Else if %A = 2 then %E = nd
      Else if %A = 3 then %E = rd
      Else                %E = th


    TYPE %1:

    TYPE Today is day number %B of the %A%E month
    TYPE of the year 19%C.

    Type your FIRST and LAST name: Frank Canova

    Hello Frank Canova, please enter the date
    in the form mm/dd/yy: 07/25/95


    Frank Canova:

    Today is day number 25 of the 7th month
    of the year 1995.

READSCRN

COMMAND:

READSCRN [variable] ... [variable]

PURPOSE:

Reads messages from the display and assigns each word to one or more variables.

DESCRIPTION:

When the command word READSCRN is seen in the batch file, a line of text is read from the display screen into the variables. The ability to read text from the display can be useful for determining the result of another program, or for making a query of some system status which would not normally be available from within a batch file. For example, by reading a directory from the screen, a series of files can be submitted to a Macro Assembler. Once the assembly is completed, the status can be read from the screen to determine if there were errors which would stop the link step. Virtually any message which a program can generate can also be used as feedback to a batch file by using READSCRN.

Its operation is very much like the READ command except that the information being read is coming from the display screen and not from the keyboard. Like the READ command, the text from the screen is split apart into individual words with spaces as delimiters. For example, the screen contents "EBL IS VERY POWERFUL" will be assigned four separate values: "EBL", "IS", "VERY", and "POWERFUL".

Once the display text is split apart, each value will be assigned, in order, to the variables indicated after the READSCRN command. When there are no more variables after the READSCRN command to assign, the remainder of the text on the display line is discarded. Only DOS variables and global EBL variables are allowed as operands to the READSCRN command. If there are more variables to be assigned after the READSCRN command than there are words from the display screen text, the remaining variables will be cleared out to an empty state.

The return code %R will reflect the line number on the display that was read. This number will be in the range of 1 to 25 for the top to bottom lines respectively.

For example, If text was just printed to the screen line 14, the first READSCRN command will read the text from this line; the next READSCRN command will read from line 13; and the next from line 12, and so on. As long as no more text is printed to the screen, text will be read on each preceding line. If enough READSCRN commands are executed, the line read will wrap around to the bottom line and back up to the top of the screen again. The return code can be monitored to determine if this wrap around has occurred. Note that in some cases, where a program ends and returns to EBL, a DOS prompt may be printed onto the screen before entering EBL. You may need to account for this by having one or two extra READSCRNs to account for this prompt. The READSCRN command will then be reading above the prompt and into the text area of the previous program.

RELATED COMMANDS:

READ, Return codes

EXAMPLES:

    BAT * READSCRN Example
     CLS
     TYPE Hello there user.
     READSCRN %A %B %C %D

%A   contains   Hello
%B   contains   there
%C   contains   user.
%D   is empty

%R   (return code) contains 1
     (the line number that was read).

READSCRN.PARSED

COMMAND:

READSCRN.PARSED [variable] [delimiter] [variable]...

PURPOSE:

Reads messages from the display and assigns each word to one or more variables. A delimiter can be defined to identify the point that the response is separated into parts for each variable.

DESCRIPTION:

When the command word READSCRN.PARSED is executed, a line of text is read from the display screen into the variables. Having the ability to read text from the display can be useful for determining the result of another program, or for making a query of some system status which would not normally be available from within a batch file. For example, by reading a directory from the screen, a series of files can be submitted to a Macro Assembler. Once the assembly is completed, the status can be read from the screen to determine if there were errors which would stop the link step. Virtually any message which a program can generate can be used as input to a batch file by using READSCRN.PARSED.

Its operation is very much like the READ.PARSED command except that the information being read is coming from the display screen and not from the keyboard. Like the READ.PARSED command, the text from the screen is parsed. That is, words will be separated at the points indicated by the delimiter operand in this command. If the delimiter is a blank, for example, the display text "EBL HAS MANY EXTRA-COMMANDS" will be assigned four separate values: "EBL", "HAS", "MANY", and "EXTRA-COMMANDS". If however, the delimiter is a "-" (minus) sign, then the same text will separated into only two values: "EBL HAS MANY EXTRA" and "COMMANDS".

Once the display text is parsed, each value will be assigned, in order, to the variables indicated after the READSCRN.PARSED command. If there are no more variables after the READSCRN.PARSED command to assign, the remainder of the text on the display line is discarded. Only DOS variables and global EBL variables are allowed as operands to the READSCRN.PARSED command. If there are more variables to be assigned after the READSCRN.PARSED command than there are values from the display screen text, the remaining variables will be cleared out to an empty state.

All of the text that does not match the delimiter is put into the last variable in the list. If the delimiter is the last item in the list, input after the delimiter is ignored. If no delimiter is provided, the entire text is put into the variable. If there are more variables than text to be stored, these variables are cleared out (set to null). The delimiter must immediately follow the variable name (no spaces) and must be a single character only. Any characters after the delimiter are expected to be the next variable name and must be valid. Note that a space can also be a delimiter. For example, If the text on the display was "5 Errors/Warnings", the following: READSCRN.PARSED commands will result. The PARSE and READ.PARSED commands would be have similar results.

 Where display text was: "5 Errors/Warnings"


 READSCRN.PARSED %A
                      %A contains "5 Errors/Warnings"

 READSCRN.PARSED %A %B

                      %A contains "5"
                      %B contains "Errors/Warnings"

 READSCRN.PARSED %A/%B

                      %A contains "5 Errors"
                      %B contains "Warnings"

 READSCRN.PARSED %A/%B %C

                      %A contains "5 Errors"
                      %B contains "Warnings"
                      %C contains nothing. (null)

The return code %R will reflect the line number on the display that was read. This number will be in the range of 1 to 25 for the top to bottom lines respectively.

If text was just printed to screen line 14, the first READSCRN.PARSED command will read the text from this line; the next READSCRN.PARSED command will read from line 13; the next from line 12, and so on. As long as no more text is printed to the screen, text will be read on each preceding line. If enough READSCRN.PARSED commands are executed, the line read will wrap around to the bottom line and back up to the top of the screen again. The return code can be monitored to determine if this wrap around has occurred.

Note that in some cases, where a program ends and returns to EBL, a DOS prompt may be printed onto the screen before entering EBL. You may need to account for this by having one or two extra READSCRN.PARSEDs to account for this prompt. The READSCRN.PARSED command will then be reading above the prompt and into the text area of the previous program.

RELATED COMMANDS:

READ, Return codes

EXAMPLES:

    BAT * READSCRN.PARSED Example
     %A = Eva
     %B = Canova
     CLS

     TYPE Hello there user: %A %B

     READSCRN.PARSED %A:%B %C %D



     type readback: %A, %B, %C, %D,

 "Hello there user: Eva Canova"


%A   contains   Hello there user
%B   contains   Eva
%C   contains   Canova
%D   is empty

%R   (return code) contains 1
     (the line number that was read).

REPEAT

COMMAND:

REPEAT WHILE [expression] [comparison] [expression]

REPEAT UNTIL [expression] [comparison] [expression]

REPEAT WITH [variable] = [expression] <DOWN> TO [expression]

REPEAT FOREVER

PURPOSE:

Repeatedly executes a group of statements as long as a condition is true.

DESCRIPTION:

The REPEAT command is always paired with an END REPEAT command. The group of statements between these commands will be executed several times until some condition becomes true. There are several ways to determine the number of times it loops as we will discuss below.

You can also nest the REPEAT/END pair within other REPEAT/END or BEGIN/END pairs up to 8 levels deep. Caution should be practiced so that a GOTO is not used to enter or leave a REPEAT/END group. Doing so can cause an error indicating the block is nested too deep. The NEXT REPEAT and EXIT REPEAT commands are available as a structured way to avoid GOTO. Also, you cannot use the LEAVE command from within a REPEAT/END group since LEAVE forces EBL to give up control of the program. The indentations shown in the examples below are suggested to improve readability.

REPEAT WHILE

The REPEAT WHILE command accepts a comparison followed by a group of statements between REPEAT WHILE and END REPEAT commands. As long as the comparison is true, the group of statements will be executed repeatedly. The test is performed at the top of the group of statements. If the condition is initially false, the entire group will be skipped. Execution will resume after the END REPEAT command.

BAT * REPEAT WHILE Example..
    Type "Directory of all files is..."
    %A = Dir("*.*")           |* get First name
    REPEAT WHILE %A IS NOT "" |* while a name exists...
       Type %A                |* show the directory
       %A = Dir("*.*",i)      |* get Next file and loop
    END REPEAT

The expression and comparison after the WHILE command is of the same format as the IF command. It can be the comparison between two expressions, or the simple true/false test of a single expression. For more information, refer to the description of the IF command earlier in this chapter.

REPEAT UNTIL

The REPEAT UNTIL command is almost the same as REPEAT WHILE except the group of statements is executed repeatedly if the condition is false. When the condition becomes true, the group is skipped and execution resumes after the END REPEAT command. The test is performed at the bottom of the loop so that the group will always execute once even if the condition is initially true.

BAT * REPEAT UNTIL Example..
    Window( 5,5, 25,9)
    REPEAT UNTIL keypressed() |* Show the time until
       Locate 10 7            |* we have a key...

       Type "Current time:" Time()

    END REPEAT
    Inkey %A                  |* then get the key

REPEAT WITH

The REPEAT WITH command allows a control variable to be stepped each time the group of statements is executed. Its general form is:

    REPEAT WITH [v1] = [e1] <DOWN> TO [e2]
       ...statements...
    END REPEAT

The EBL variable [v1] is assigned an initial value from the expression [e1]. The group of statements repeatedly executes up to the END REPEAT command. The variable is stepped by one at the bottom of the loop each time the group executes. If the optional word "DOWN" was used, the variable is decreased by one. Otherwise it is increased by one. When the variable reaches the second expression [e2] value, the loop is terminated.

BAT * REPEAT WITH Example..
    Type "Show a 4 x 5 matrix..."
    %0 = 1
    REPEAT WITH %A = 1 to 5

    Type %A:;

       REPEAT WITH %B = 1 to 4
          Type Right(%0,4) ;
          %0 += 1
       END REPEAT
    END REPEAT

REPEAT FOREVER

In special cases, a group of statements needs to execute continuously. The REPEAT FOREVER command can be used for this purpose. The only way to exit from the loop is to use the EXIT REPEAT command within the loop, or press Ctrl-Break from the keyboard.

BAT * REPEAT FOREVER Example..
    Type "Ready to start program at 2am,"
    Type "or press Ctrl-Break to exit now!"

    REPEAT FOREVER

      If Time(c) is "2:00am" then EXIT REPEAT

    END REPEAT

    Type "Now ready to do XYZ program..."
    XYZ

EXIT REPEAT

As shown in the above example, the EXIT REPEAT command can be used to prematurely stop the executing loop. It is intended to be used after an IF command. All remaining statements before the nearest END REPEAT command are bypassed. Execution will resume with the statement following the nearest END REPEAT command.

NEXT REPEAT

The NEXT REPEAT command alters the flow of a REPEAT loop by bypassing the remaining statements and testing the end conditions for the loop. For example, to print a set of files except the fifth one

BAT * NEXT REPEAT Example..
    Type "Simulate using PRINT for a set"
    Type "of files... (except 5th one)"

    Repeat with %A = 1 to 8
      If %A is 5 then NEXT REPEAT
      Type PRINT FILE.%A
    End repeat

RESUME

COMMAND:

RESUME {n}

PURPOSE:

This command returns control to the main program after an error recovery procedure is performed.

DESCRIPTION:

Even with a perfectly debugged program, many types of errors can still be created due to user errors or system environment. When an error occurs, EBL will look for the "-ON.ERROR-" label within the batch file. If it exists, EBL will do a GOTO to the procedure which follows the label.

If the "-ON.ERROR-" procedure exists, EBL will store the type of error in the %R variable, and the line number that caused the error in the %L variable. The error recovery procedure you write can detect the type of error, and perform corrective action if necessary.

Once the error has been recovered, use the RESUME command to begin execution in the main program. You can choose to return to one of three places in the main program.

RESUME Execution will resume at the statement immediately following the one which caused the error. Internally, EBL executes a RESUME (%L) statement.

RESUME {-label} Execution will resume at the statement identified with the -label. Internally, EBL executes a GOTO {-label} statement.

RESUME {line} This form will begin execution at the specific line number plus 1. For example, if "RESUME 49" is used, execution will begin at line 50 in the batch file.

RESUME (%L-1) Execution resumes at the line which had the original error. %L is the variable that contains the line number with the error. Subtracting one makes it return to the same point.

Note that because the last two forms use the %L variable, this variable must not be altered by your error recovery procedure. Also, you should not RESUME to the middle of a REPEAT/END or BEGIN/END group of statements. Doing this will create a block nesting error.

RELATED COMMANDS:

-ON.ERROR-

EXAMPLES:

    BAT * Error Recovery example.
    -TOP
       READ What file to look at> %0
       If %0/ = / then EXIT
       <%0
       READ.PARSED %1
       <
       TYPE "File header contained" %1
       GOTO -TOP

    -ON.ERROR-
       IF %L <> 4 SKIP 2
         TYPE "DOS Error. Can not open file" %0
         RESUME 2
       TYPE "Unknown error" %R "in line" %L.
       EXIT

RETURN

COMMAND:

RETURN

PURPOSE:

Returns from a subroutine and transfers control back to the line just past the previous CALL command.

DESCRIPTION:

When a CALL command is executed, it will save its current location in the EBL program and transfer control to a subroutine. When the RETURN command is executed, it causes EBL to branch back to the statement following the most recent CALL command. A subroutine may contain more than one RETURN statement if you want to return from different points in the subroutine.

RELATED COMMANDS:

CALL, CALL.PURGE

EXAMPLES:

(refer to the CALL command for examples)

SHELL

COMMAND:

SHELL [DOS command]

PURPOSE:

Passes DOS a command or program for execution.

DESCRIPTION:

The SHELL command tells Extended Batch Language to give a DOS Command to DOS for execution. Normally you can add DOS commands to an EBL program without the SHELL command. However, SHELL allows you to add DOS commands that might otherwise be confused with EBL commands. For example, both DOS and EBL have a TYPE command, but they have different meanings. Extended Batch Language will normally assume that the command is for itself. However, using SHELL will make sure that DOS gets control.

The DOS Command can contain any type of value. Global EBL variables, DOS variables, and even extended EBL variables can be used within the DOS Command.

Applications and DOS commands can be started with SHELL. However, they will not be aware that a batch file is running.

The EBL return code %R will be set upon completion of the command to the error level with which the DOS command exited. If the command, or program does, not support this concept the return code will be zero.

EBL will keep the EBL program in memory and continue execution after the command has finished. As a result, the overall execution speed will be faster than with the LEAVE command or the /L option.

In the following example, the SHELL command is used to pass control of the DOS Command to DOS.

 BAT * SHELL example 1...

 TYPE "Do a SHELL by default..."
 XYZ

 TYPE "Do a SHELL explicitly..."
 SHELL XYZ

 TYPE "This TYPE is for EBL...."
 TYPE XYZ

 TYPE "This TYPE is for DOS...."
 SHELL TYPE XYZ

You can use the SHELL command, or the /S option, when executing with "window environments" like TopView. In these environments, do not try to use the LEAVE command or the /L option. Usually with such environments, COMMAND.COM is either altered or not used to execute other programs. If the LEAVE command is used, execution of the batch file may simply stop cold and not continue.

Usage notes:

• ECHO: The SHELL command will "quietly" execute DOS commands and applications. To make commands echo to the display, use a TRACE(C) command before using SHELL. The TRACE() command is the default and will not echo DOS commands to the display.

• COMMENTS: All text after the SHELL command will be passed to DOS. Therefore, do not try to put additional EBL commands or EBL comments on the same line with the SHELL command. All text after the SHELL command should only contain DOS commands.

• TSR APPLICATIONS: Never use SHELL with a TSR (Terminate and Stay Resident) application, you should always use LEAVE instead. If you are unsure if your application is a TSR type, then always use LEAVE. Examples of such programs are Borland's SideKick, the PRINT command in DOS (just the first time), or other pop-up programs. With TSR programs loaded by SHELL, system memory will contain holes that DOS can not handle when EBL ends. It may eventually lead to a system crash. Therefore, to start TSR applications properly, use the LEAVE command rather than SHELL.

• AUTOEXEC: If EBL is within an AUTOEXEC, then the /L option is the default unless specifically overridden by /S option. This avoids accidentally executing a TSR program from within a SHELL which could create DOS holes which cause system problems.

• DOS COMMANDS: With SHELL, do not try to use commands that DOS only understands in batch files. These are the DOS commands CTTY, ECHO, FOR, GOTO, IF, PATH, SET, or SHIFT. To use them, precede these DOS commands with EBL's LEAVE command, and follow them with BAT to continue the EBL program.

  When using the SHELL command, DOS is not aware that a batch file is executing. DOS will not return the proper results with these commands. Depending on your version of DOS, it may return an error if they are used. Note that the CTTY, ECHO, SET, and PATH commands are included because they make temporary environment changes that are immediately lost under the SHELL command. The other commands are only intended for DOS batch files and may not always achieve the desired results.

• EBL VERSION: Note that previous versions of EBL always did an implied LEAVE command rather than an implied SHELL. This will not affect most EBL programs except those that start TSR applications or use special DOS commands as mentioned above. If you are upgrading from EBL version 3, refer to Appendix F for additional information.

RELATED COMMANDS:

/L option, /P option, /S option

EXAMPLES:

    BAT * Example 5 using SHELL command

    -Doread
        READ File to display? %1
        SHELL Type %1
        READ Display another? (y/n) %1
        IF %1 = Y GOTO -Doread

SKIP

COMMAND:

SKIP [number of lines]

PURPOSE:

Performs a forward jump by the specified number of lines.

DESCRIPTION:

This command does a forward jump only. The operand for this command is a decimal amount of lines to be skipped. It may be a number between 0 and 9999. If a skip amount is sufficiently large so as to cause it to go past the end of the batch file, batch execution will terminate (a poor coder's way of doing an EXIT command!).

The skip amount can be a number, variable, or expression. This allows for a variable number of lines to be skipped. For instance if %A = 23, then the command "SKIP %A" would skip 23 lines of the batch file. Execution would resume on the 24th line. If the command had been "SKIP 23", the same action would result, but it would only skip the fixed 23 lines and would not change.

RELATED COMMANDS:

GOTO, IF

EXAMPLES:

    BAT * SKIP example

    -top READ What's your first name? %1

    IF .%1 <> . SKIP 3
       TYPE "Don't forget to give your name!"
       TYPE "Try again..."
       GOTO -top
    TYPE Thank you %1

In the above example, if the user presses Enter and types nothing else to the READ command, the comparison at the IF will fail and a message is printed. The GOTO command is needed here because it is a backward reference jump. However, if the user does type something, the SKIP command will jump over these two lines which would print the "thank you" message.

STACK

COMMAND:

STACK [value] ... [value]

PURPOSE:

Creates messages on a stack which simulates keyboard entries.

DESCRIPTION:

The stack is useful for answering questions automatically that a program might ask. Every character that is stacked can be an input to any program which requests data from the keyboard. This includes BASIC, DOS, and even EBL programs. Refer to the end of this chapter on how the stack operates for further details.

The operation of this command is very similar to the TYPE command. Instead of typing to the screen, the STACK command essentially enters into the keyboard what the user would have typed.

The STACK command accepts any number of values as operands. Read the description on literal values, variables, and expressions to find out the many formats available. Any combination of these may be stacked. Only one space will separate each of these values in the stack. If a variable is empty, and an attempt is made to put it on the stack, nothing will happen.

To stack function keys or control keys, use the KEY() function in EBL. This function provides additional flexibility for controlling the keyboard stack.

    BAT * This program will issue remarks to DOS.
        %1 = hello
        STACK REM This     is    some    TEXT
        STACK "REM The current variable %1 =" %1

        STACK "REM A control Z character looks like:;"

        KEY('ctrl-z')
        EXIT

When executed, the following will appear on the screen:

    A>REM This is some TEXT

    A>REM The current variable %1 = hello


    A>REM A Control Z character looks like: ^Z

Notice that in this example we are stacking keyboard entries and then exiting back into DOS. DOS then reads the keyboard to determine what the next command is. In this case, it reads (and ignores) the DOS remark (REM) statement that was stacked. The application that uses the keystrokes (in this case DOS) is always started after the keyboard stack contents is setup.

Note: When special non-ASCII keys need to be put into the keyboard stack (like function keys), use the KEY() function shown above. Further description on the KEY() function can be found with other console functions in the next chapter.

STACK.LIFO

The STACK.LIFO command enters text into the stack in a Last In First Out (LIFO) basis. That is, the last text entered by using the STACK.LIFO command will be the first text available from the stack. By comparison, the STACK command puts the line of text into the stack in a First In First Out (FIFO) basis. That is, the first text entered into the STACK command will be the first text available from the stack.

 BAT * STACK.LIFO example


 STACK 10 Cls: for i=1 to 4

 STACK 20 PRINT ""EBL's STACK is very POWERFUL!""
 STACK 30 Next i
 STACK 40 PRINT ""Use it to automate the keyboard..."
 STACK 50 system"
 STACK Run

 STACK.LIFO BASICA
 EXIT

This example will build and execute a simple BASIC program, all automatically. In this example, the STACK commands will put the text into the stack in the order shown. However, the STACK.LIFO command will place the word "BASICA" at the top of the stack so it is executed first (even though it was the last in). The result on the display will be:

    EBL's STACK is very POWERFUL!
    EBL's STACK is very POWERFUL!
    EBL's STACK is very POWERFUL!
    EBL's STACK is very POWERFUL!
    Use it to automate the keyboard...

STACK.ON / STACK.OFF

CONTROL FUNCTIONS:

STACK.ON

STACK.OFF

PURPOSE:

Turns on and off the flow of stacked keyboard data coming into the system.

DESCRIPTION:

These two control functions control the source of keyboard data. The STACK.ON function is the default for normal system operation. Use of the STACK.ON function will force keyboard data to come first from the keyboard stack if there is any data in the stack. If there is no data in the keyboard stack, then the keyboard data will come from the physical keyboard. The use of STACK.ON is to have programs (BASIC, DOS, EBL, etc..) respond to data from the keyboard stack.

If, however, the data in the stack is to be used only within the EBL program, or to only certain selected programs, then the STACK.OFF control function can be used. Its purpose is to direct data to come directly from the physical keyboard and bypass the keyboard stack. Note that data is not removed from the stack. If data is to be removed from the stack, use the STACK.PURGE control function. By using STACK.OFF, the EBL program can use data from the stack while other programs may be called which need data directly from the physical keyboard.

Note that STACK.ON and STACK.OFF only control the reading of data from the stack into an application. Even when the STACK.OFF is in effect, the stack is still available for data to be put into the stack with the STACK and BEGSTACK commands. Also, while STACK.OFF is in effect, keystrokes will only come from the physical keyboard and not the stack.

RELATED COMMANDS:

STACK, BEGSTACK, STACK.PURGE, STACK.LIFO

EXAMPLES:

BAT * Create list of files to be edited.
 BEGSTACK
 mon.doc
 tue.doc
 wed.doc
 thr.doc
 fri.doc
END

* As long as there are more files to edit,
* ask if user wants to do this one and loop.
-NEXT.FIL IF %Q <> S EXIT
  READ %1
  TYPE "DO YOU WANT TO EDIT %1 TODAY? (YES/NO/ABORT)"
  INKEY %A
  IF %A = A GOTO -ABORT
  IF %A <> Y GOTO -NEXT.FIL

* Now turn off stack so editor will
* come from kbd, yet stack data remains.
  STACK.OFF
EDLIN %1
  STACK.ON
  GOTO -NEXT.FIL

* Abort going through edit list.
* Remove remaining stack data before exit.
-ABORT STACK.PURGE
    EXIT

STACK.PURGE

CONTROL FUNCTION:

STACK.PURGE

PURPOSE:

Removes any pending data from the keyboard stack.

DESCRIPTION:

This control function removes any data in the keyboard stack. It should be used when exiting an EBL program with an error. STACK.PURGE will remove the keyboard stack data before exiting and not allow the stack data to be inadvertently received by DOS as a command.

Another function of the STACK.PURGE control function is to remove any pending key presses that may be held in the keyboard buffer maintained by BIOS. For example, if you wish to clear the keyboard of any pre-typed characters before executing the INKEY command, precede it with a STACK.PURGE command. This forces the system to wait until a character is typed.

RELATED COMMANDS:

INKEY, READ, STACK, BEGSTACK, STACK.ON, STACK.OFF

EXAMPLES:

(See abort example in STACK.ON command above)

TYPE

COMMAND:

TYPE [value] ... [value]

PURPOSE:

Prints messages and the contents of variables to the screen.

DESCRIPTION:

The TYPE command accepts any number of values as operands. Read the description on literal (text) values, variables, and expressions to find out the many formats available. Any combination of these may be printed. Only one space will separate each of these values in the stack. If a variable is empty and printed out, nothing will appear.

Notice that the values can also be valid expressions. Any expression begins with an open parenthesis and can contain arithmetic or string operators. The closing parenthesis ends the expression. The result of the calculation is then used as the value to be displayed.

If a file redirection is in effect for writing, then all data normally displayed will be sent to the file. A file is opened for writing with the ">filename" command, and closed with the ">" command. This is useful for not only sending text to a file, but also for sending text to a printer by opening a file as ">LPT1".

If the last character on the line is a ";" (semicolon) then a carriage return/line feed will not be inserted. This can be used to concatenate lines of text, or to give a prompt where the user enters data immediately after the prompt. If you wish to print a semicolon at the end, then use two semicolons within your program.

RELATED COMMANDS:

BEGTYPE, ASSIGNMENTS

EXAMPLES:

    BAT * TYPE example
    %1 = hello
    TYPE  This     is    some    Text!
    TYPE "This     is    MORE    Text!"
    TYPE "The current variable %1 =" %1
    TYPE "The current return code is" %r
    TYPE "Result is" ( 2 * ( 5 + 7 ) )
    COLOR( Reverse )
    TYPE "This entire text is REVERSE VIDEO."
    COLOR( Normal )

    This is some Text!
    This     is    MORE    Text!
    The current variable %1 = hello
    The current return code is 0
    Result is 24
    This entire text is REVERSE VIDEO.

WAIT

COMMAND:

WAIT UNTIL [expression]

WAIT WHILE [expression]

PURPOSE:

Continuously evaluates the expression until it is true or false.

DESCRIPTION:

The WAIT command will test the expression and pause UNTIL or WHILE the expression is true. It will continuously execute the expression while waiting. When the exit condition is met, EBL ends the loop and continues with the next command. Pressing Ctrl-Break at the keyboard will also end the loop.

WAIT UNTIL

The WAIT UNTIL command will pause EBL execution until the expression becomes true (non-zero). WAIT UNTIL can be used to create time delays when combined with the TIME() function.

WAIT WHILE

The WAIT WHILE command will pause EBL execution until the expression becomes false (zero).

EXAMPLES:

    BAT * WAIT example...
        TYPE "Press a key to start the timer"
        WAIT UNTIL KEYPRESSED()
        INKEY   |* Get the key but throw it away

        TYPE "Waiting 5 seconds....;"
        WAIT UNTIL TIME(5)
        TYPE "Done"


        TYPE "Now wait until seconds end in :00"

        WAIT WHILE RIGHT(TIME(),2)
        TYPE "Done... time is" TIME()

LABELS

COMMAND:

[-label] [statement]

PURPOSE:

This is the destination of a jump via the GOTO, CALL command.

DESCRIPTION:

This label is not actually a command, but the format for any standard statement. The label is any name that starts with a '-' (minus) sign. EBL normally ignores these labels. However, when a GOTO command is processed, the entire batch file will be scanned, starting from the top, for this label. When found, execution will resume with this line. For example:

    BAT * Looping example..
    -SELF GOTO -SELF

The first -SELF is seen as a label and skipped, the GOTO will be taken as the command. The GOTO is seen as a branch command whose destination is the label -SELF. This batch line, of course, will execute in an infinite loop.

RELATED COMMANDS:

GOTO, CALL

EXAMPLES:

    BAT * Example of labels

    -TOP
        TYPE Select A, B, or X
        READ %9
        GOTO -%9
    -A  TYPE You selected option A.
        GOTO -TOP
    -B  TYPE You selected option B.
        GOTO -TOP
    -X  EXIT
    -%9 TYPE You didn't select the proper option!
        GOTO -TOP

Note: You do not need to have a statement after the label.

Note: Any label can also be a variable value, calculated on the fly. In the above example, the label '-%9' will always match if the others do not.

FILE I/O (REDIRECTION)

COMMAND:

[I/O Direction] [filename]

PURPOSE:

Opens or closes files for reading or writing.

DESCRIPTION:

File I/O is accomplished by redirecting the data that EBL normally reads and writes to the display into or out from a file. The file I/O statement indicates to EBL which file is to be used, and for what purpose. The various forms of redirection are as follows:

        FILE WRITE

   >file          - Open 'file' for writing
   >>file         - Open 'file' for appending
   >              - Close 'file' for writing

        FILE READ

   <file          - Open 'file' for reading
   <<file         - Re-open for reading
   <              - Close 'file' for reading

In all cases, the data will be accessed in a sequential manner unless modified by the SEEK() function. The file is expected to be ASCII, although it is not required. When a file is opened for writing, the existing TYPE and BEGTYPE commands within EBL will now send their text to the file, instead of the display. Similarly, when a file is opened for reading, the existing READ, and READ.PARSED commands within EBL will now read the text from the file into EBL. Two files can be open at the same time, one for reading and one for writing. Looking at each command possibility in detail:

Open File for Writing

When a file is opened for writing, it will first request that DOS create the file. If the file already exists, the old file will be removed before the new one is set up. Initially the file will contain zero bytes of data. When a TYPE or BEGTYPE command is used after the file is opened, all the text created by these commands will go into the file. No text will be displayed since it is entirely redirected into the file. This will continue until the file is closed, or until a LEAVE or EXIT command is executed.

    BAT * Open file for writing example
    >test.t                        |* (open write)
    TYPE "This goes to the test file."
    >                              |* (close)
    TYPE "This text goes to the display."

Note: Character output during a TYPE or BEGTYPE command will expand tabs only when going to the display. However, it will not expand tabs when writing characters to a file. In this way, special escape codes using the value 09 will not be altered when sent to a file or device.

Open File for Appending

When a file is opened for appending, EBL will first request that DOS check if the file exists. If the file does not exist, it is created. If the file does exist, a pointer is moved to the end of the file. If the end of the file contains the character 'EOF' (hex 1A), then the pointer is positioned to write over it. This allows the append function to work with editors that add this control character at the end of files.

This pointer is used by future TYPE and BEGTYPE commands to tell DOS where to store its new data. When a TYPE or BEGTYPE command is used after the file is opened, all the text created by these commands will go into the file. No text will be displayed as it is entirely redirected into the file. This will continue until the file is closed, or until a LEAVE or EXIT command is executed.

    BAT * Open file for appending example
     >>test.t                       |* (open append)
     TYPE This will be appended to the test.
     >                              |* (close)
     TYPE This text goes to the display.

Close File for Writing

When either the file write or file append functions are used, the file must be closed in order to ensure that the directory entries within DOS are updated properly. This will also make future TYPE and BEGTYPE commands display their text on the screen instead of to a file.

Note that if either the LEAVE or EXIT commands are executed within EBL, this command will be executed automatically. Use caution since the default method to execute other DOS commands is by automatically executing an implied LEAVE command. If file I/O was in progress, it will be terminated. If you wish to execute DOS commands and still keep the files open, then use the SHELL command.

Refer to the previous examples to see how the "Close File for Writing" function is performed.

Open File for Reading

When a file is opened for reading, DOS will be asked to locate the file. If the file does not exist, an error will result. Otherwise all future READ, and READ.PARSED commands will read text from these files instead of from the keyboard stack or the keyboard. This will continue until the file is closed for reading.

It is possible to determine where the end-of-file exists from within the EBL program. If no more data is available, the READ or READ.PARSED command will read the characters "^Z" (caret zee). You can test for "^Z" to determine when to stop reading data. The example below shows this.

Note that the file could not only be a data set on a diskette or hard file, but could also be another device like a printer (LPT1), or a communication port (COM1).

    BAT * Open file for reading example
     %0 = TEST.T
    -top
     Type Listing of file %0...
     <%0                            |* (open file)

     Repeat Forever                 |* (read file)
        Read.parsed %A
        If %A is ^Z then Exit Repeat
        Type %A                     |* (display file)
     End Repeat

     <                              |* (close file)
     Read Next file to list? (ENTER to exit) %0
     if /%0 <> / goto -top
     else exit

Re-Open File for Reading

When a file is re-opened for reading, DOS will be asked to locate the file. The pointer is positioned to the point in the file that was last read. This allows EBL to close a file that is being read, then re-open the file to continue processing it later. All future READ, and READ.PARSED commands will read the text from these files instead of from the keyboard stack or the keyboard. This will continue until the file is closed for reading.

It is possible to tell when the end-of-file exists from within the EBL program. If no more data is available to read, the READ or READ.PARSED command will read the characters ^Z (caret zee).

Note that the file could not only be a data set on a diskette or hard file, but could also be another device like a printer (LPT1), or a communication port (COM1).

    BAT * Open file for re-reading example
     %0 = TEST.T
    -top
     <%0                            |* (open read)
     Type Listing of file %0...

     Repeat forever                 |* (read file)
        Read.parsed %A
        if %A is ^Z then exit repeat
        Type LINE= %A               |* (display file)

        <                           |* (close file)
        Read Show next line? %1     |* (read kbd)
        <<%0                        |* (re-open file)
        if %1 is not "Y" then exit repeat
     End Repeat

     <                              |* (close file)
     exit

Note: You cannot re-open a file for reading after you run an application or use the SHELL or LEAVE commands. You must save the position of the file with the SEEK() function, close the file, run the application, and then re-open the file and use SEEK() to restore the position. This is necessary as EBL cannot keep files open due to network SHARE support. It avoids "sharing violations" in DOS while the application runs.

Close File for Reading

When a file is open for reading, it may be closed to return control of the READ, and READ.PARSED commands back to the keyboard. Use of this function is not required and may be used only when needed.

Note that if either the LEAVE or EXIT commands are executed within EBL, this command will be executed automatically.

Refer to the previous examples to see how the Close File for Reading function is performed.

COMMENT LINES

COMMAND:

    *   [comment line]

    :   [comment line]

    REM [comment line]

PURPOSE:

Allows comments to be seen in the batch file.

DESCRIPTION:

When the "*" (asterisk) character is seen as a command in the batch file, the remaining characters on the line are skipped over and processing begins with the next line. The comment is not printed on the screen to the user and is intended only to provide helpful information within the batch file.

When the ":" (colon) character is seen at the beginning of a statement, it is also treated as a comment. This is the way comments are made in DOS batch files. Although DOS also uses the colon as a label prefix, for EBL labels use the "-" (minus) character instead.

When REM is seen at the beginning of a statement, it is also treated as a comment. This is actually the remark command used by DOS. Since EBL recognizes this command also, it can treat the remainder of the line as a comment without having to pass it on to DOS. Overall, this will speed up execution of the batch file.

EXAMPLES:

    BAT * This is a comment.

      Type "This is a text line on the screen."

    * This comment is just to the EBL programmer.

      Goto -LABEL

    *   This is a comment in the style of EBL.

    :   This is a comment in the style of DOS.

    REM This is also a comment in the style of DOS.

    -LABEL * This is where the above GOTO comes.

EXTENDED FUNCTIONS

Built into EBL Plus is a large set of useful functions. These functions are helpful when writing advanced EBL programs. In general, you could write almost all of your EBL programs without using these functions. Occasionally, there may be some special need for a unique operation that is not a part of the standard commands built into Extended Batch Language. For these advanced needs, we have written a rich library of Extended Functions.

In addition, it is possible to add your own personal functions to EBL. Refer to the Developer's Edition manual from Seaware for more information about how to create your own functions.

EBL functions are organized into five categories.

CONSOLE

  BLINK( on/off )
  CHARIN()
  COLOR( names )
  CURSOR( on/off/block/line )
  CURSOR.ROW()
  CURSOR.COL()
  DOSCHARIN()
  EDIT( field color )
  FIELD( field number {,field color} )
  KEY( name )
  KEYPRESSED()
  PLAY( notes )
  SELECT( Field Color {,Bar Color {,Arrow}} )
  WINDOW( X1, Y1, X2, Y2 {, Kind } )

MATH/CONVERSION

  ABS( number )
  C2H( string )
  D2H( value )
  FLOAT( expression )
  FRAC( number )
  H2C( value )
  H2D( value )
  INT( number )
  RANDOM( {{min,} max {,seed}} )

STRING

  ABBREV( information, info {, length})
  BITAND( string1 {,{string2} {,pad}} )
  BITOR( string1 {,{string2} {,pad}} )
  BITXOR( string1 {,{string2} {,pad}} )
  CENTER( string, i {, pad} )
  COPIES( string, n )
  DELWORD( string, n {, length} )
  FIND( sentence, phrase )
  LEFT( string, i {, pad} )
  LENGTH( string )
  LOWER( string )
  MID( string ,start {,length, {pad}} )
  OVERLAY( new, target, n {,length {,pad}} )
  REVERSE( string )
  RIGHT( string, i {,pad} )
  SPACE( string, n {, pad} )
  STRIP( string {, type {, char}} )
  SUBSTR( string ,start {,length, {pad}} )
  SUBWORD( string, n {, length} )
  TRANSLATE( string {,{to list}{,{from list}{,pad}}} )
  UPPER( string )
  VERIFY( string, reference )
  WORD( string, n )
  WORDS( string )
  XRANGE( start {, end )

SYSTEM

  CHDIR( directory )
  DATE( {type} )
  DIR( file {,type {,attribute}} )
  EXIST( file )
  GETDIR()
  INT86( intr, regs )
  MKDIR( directory )
  PEEK( locn )
  POKE( locn, value )
  REBOOT
  RMDIR( directory )
  SEEK( r/w, posn )
  TIME( {type} )

EBL/CONTROL

  NOT( expression )
  TRACE( type )
  VERSION()
  WHATFUNC()

CONSOLE Functions

The console group of functions interact with the screen and keyboard that the user sees. Functions can be used anywhere other values or expressions are used. For example, in an assignment statement, an IF or TYPE statement, and so on.

BLINK( on/off )

This function turns on background color blinking with BLINK(ON) (the system default) or turns it off to provide 16 background colors with BLINK(OFF). This function will work with EGA and VGA compatible displays. The on/off parameter can also be an expression that evaluates to a true/false value.

CHARIN()

This function waits for a single keystroke then returns its value. If a function key is pressed, the entire key name is returned. The key is not echoed to the screen, you can do that explicitly with the TYPE command. The keystroke always comes from the physical keyboard, never the stack, even if the stack contains its own keystrokes. Because function key names are also returned, this function can be a flexible substitute for the INKEY command.

    CHARIN()            ==  'a'         (perhaps)
    CHARIN()            ==  'ALT-F3'    (perhaps)

COLOR( color name {{on} color name} )

This function converts one or more color names into its corresponding hexadecimal attribute. The result can be used in menus within the BEGTYPE command. If used by itself as a keyword, this function will set the default color of any future text to be printed with either the TYPE or BEGTYPE commands.

The color name is a phrase which describes the color. Typical phrases are listed in Appendix E. The descriptive words can be used for either a monochrome or a color display. EBL will allow either to be used.

Some examples are as follows:

COLOR( BLUE )           - Blue on black
COLOR( WHITE ON BLUE )  - White on blue
COLOR( BLINK LRED )     - Blinking light red on black
COLOR( HIGH-INTENSITY ) - High intensity white on blk
COLOR( UL )             - Underlined white on black

There are, of course, many more combinations. Refer to Appendix E for a complete list of valid combinations. Any of the following words can be combined to describe colors. You should only use keywords from the same group below. Mixing the two groups, or using combinations not shown in Appendix E, will give unpredictable results on the display.

The first group is for color displays:

BLACK   BLUE    GREEN     CYAN     RED      MAGENTA
BROWN   GRAY    LGRAY     DGRAY    LBLUE    LGREEN
LCYAN   LRED    LMAGENTA  YELLOW   WHITE    BLINK

ON

The second group is for monochrome displays:

NORMAL     UNDERLINE    BLINK      NON-DISPLAY
REVERSE    LIGHT        UL         HIGH-INTENSITY

These color names can be used by themselves, or in pairs (eg. BLUE ON RED). The word BLINK is an adjective that can be a prefix to the color name. The computer hardware may not allow all combinations. Refer to Appendix E for a complete list of variations.

Note, if the ANSI command is in effect, then the COLOR() function will change the color of both EBL and DOS screens. If however the RAM or BIOS commands are used instead of ANSI, then only the color of EBL screens are changed. DOS screens are not affected.

Once a color is used, it will affect the color of future CLS, TYPE, and BEGTYPE commands. The color will remain in effect until the next COLOR() function, or until the color is changed within a BEGTYPE command, or until EBL reloads from DOS (such as after a LEAVE command). When EBL first starts, the default color is white on black.

bat * COLOR() Function example
    %A = COLOR(White on Blue)
    %B = COLOR(Yellow on Red)
    BEGTYPE
\%A The COLOR() function helps simplify
entering color attributes for typing out
text. Making your text colorful is rather
\%B easy \%A with this tool!
END
    TYPE
    COLOR( high-intensity )
    TYPE "It is also easy to change colors"
    TYPE "on the fly with COLOR() function."
    COLOR( Normal )
    TYPE
    COLORCHAR '$' as COLOR( yellow on red )
    TYPE "The$COLOR()$ function can also be"
    TYPE "used with the$COLORCHAR$command."

CURSOR( on/off/block/line )

It is used to turn the text cursor on or off, or to adjust the cursor's size. Use CURSOR(OFF) to turn off the cursor, CURSOR(ON) to restore the size of the last visible cursor, CURSOR(BLOCK) to create a large block cursor, CURSOR(LINE) to create a thin line cursor, or CURSOR(hhhh) for any other cursor size.

hhhh is a four digit hexadecimal number representing the new cursor size. The first two digits are the starting line number, and the second two digits are the ending line number. For example CURSOR(LINE) is equivalant to CURSOR(0607) which creates a cursor from line 6 to 7. The result on the screen depends on the type of hardware installed.

This function is useful for turning off the cursor when there is continuous activity on the screen, such as updating a clock. Note that DOS may restore the cursor type when it returns to the DOS prompt (e.g. C:> ).

CURSOR.ROW()

CURSOR.COL()

This function returns the cursor's current row or column position. It is useful when you want to hold the current cursor position so that you can use LOCATE to return the cursor to the same point.

DOSCHARIN()

This function waits for a single keystroke then returns its value. If a function key is pressed, the entire key name is returned. The key is not echoed to the screen, you can do that explicitly with the TYPE command. Unlike the CHARIN() function, the keystroke always comes from DOS. DOS may get the keystroke from a redirected file, the keyboard stack, or the physical keyboard in that priority depending on what's available. In contrast, the CHARIN() function will avoid redirected files and the keyboard stack. Because function key names are also returned, this function can be a flexible substitute for the INKEY command.

    DOSCHARIN()         ==  'a'         (perhaps)
    DOSCHARIN()         ==  'ALT-F3'    (perhaps)

EDIT( field color )

This function allows any text on the console to be edited interactively. Several fields, or an entire edit window, can be set up. The screen is first set with the area to edit, marked with a color code. This can be done with the TYPE or BEGTYPE commands. Then the EDIT() function is used to allow the user to interactively modify and create text right on the screen. Only colored areas on the screen that match the field color can be modified. The initial cursor position can be preset with the LOCATE command.

When inside the function, the user can add or modify any text within the fields. Standard editing keys can be used to modify the text such as Insert, Delete, and Backspace. The Enter, Tab, and Arrow Keys will move the cursor between fields if there are multiple fields on the screen. The ESC, Function, Alt-letter, and Ctrl-letter keys will edit within this function. The name of the exit key pressed will be returned as the value of this function. The CURSOR.COL() and CURSOR.ROW() functions will indicate cursor position upon exiting. This text can then be read back with the FIELD() function or READSCRN command.

  BAT * EDIT example...

  COLORCHAR '@' as COLOR( Yellow on Cyan )
  COLOR( white on black )
  CLS BEGTYPE


           Name: @                   @

           Rank: @           @

  Serial number: @           @

  end
  EDIT( COLOR( Yellow on Cyan ))
  %A = FIELD(1)

  LOCATE 10 10
  COLOR( yellow on blue )
  TYPE "Welcome" %A, " we're glad you could join us"
  COLOR( normal )

This function will always use the BIOS interface to the computer so it will operate on the widest variety of systems. The DOS, BIOS, and ANSI commands in EBL have no affect on this.

FIELD( field number {,field color} )

This function returns the text contents of a screen field. Field numbers are counted from the top left of the screen sequentially to the bottom right. Fields are identified by a specific field color on the display. If no field color is specified, then the last field color from the previous FIELD(), EDIT(), or SELECT() functions will be used. This function will return at most one line from the screen.

When this function returns the text contents of the field, the cursor will be moved to the beginning of the field. The CURSOR.COL() and CURSOR.ROW() functions can then be used to determine field location. This is also an easier way to move the cursor than the LOCATE command.

If the entire screen contains the same field color (that is, the entire screen is one huge multi-line field), the field number will be the same as the line number of the screen.

  BAT * FIELD() and WINDOW() example...

  * Set field colors....
  %A = COLOR( yellow on cyan )
  COLORCHAR '!' as %A

  * Set background colors...
  COLOR( white on blue )
  RAM CLS

  * Setup window & fields...
  COLOR( white on cyan )
  WINDOW( 5, 1, 29, 8 )

  TYPE " -Room Reservation-  "
  TYPE

  TYPE "Room: !     !        "

  TYPE "Date: !             !"

  TYPE "From: !!:!!  To:!!:!!"

  FIELD( 2, %A ) |COLOR %A |TYPE DATE()

  * Move to start then edit fields
  -DoEdit  FIELD(1) |EDIT( %A )

  * Check that fields are valid..
  IF FIELD(4) > FIELD(3) THEN GOTO -Ok
    COLOR( Yellow on Red )
    LOCATE 6 7 |TYPE "Time values are bad."
    GOTO -DoEdit

  -Ok LOCATE 6 7 |TYPE "I'll get the room now..."

KEY( name )

When used outside an expression, this function will put the named key on the keyboard stack.

        KEY(PgUp)

If the name is plain text and not a key name, then the plain text will be stacked instead.

        KEY("Plain text")

The stack will simulate keystrokes to automate applications. Applications can use this stack to automatically perform functions on behalf of the user. For example, "KEY(Ctrl-Z)" will simulate the control 'Z' key. Refer to the last chapter in this manual on the keyboard stack for more information.

If "KEY(PAUSE)" is used outside an expression, then this function will put a one second delay on the keyboard stack. The application will pause briefly before 'pressing' more keys after this.

In addition to simulated keystrokes, inline code can also be placed in the stack. If you are familiar with assembly language programming, this technique can provide extra power within the stack in special instances. Please refer to Chapter 9 for information about this feature.

When used in an expression, the KEY() function converts from the common key name on the keyboard (such as "ENTER") to the name used by the system hardware and the INKEY command (such as "KEY00D"), and visa versa. Refer to appendix D for a list of the names that the KEY() function will also convert between.

  BAT * KEY() example...


  KEY("KEY() can press control keys:")

  KEY(CTRL-Z)

  KEY("  or pause between")
  KEY(Pause)
  KEY(" words")
  KEY(Ctrl-C)

  TYPE  "KEY() can also convert the"
  INKEY key you press now... %0
  TYPE  "That was the" KEY(%0) "key"
  TYPE  "also known to INKEY as" %0

Hints

Some programs remove keystrokes before accepting a critical key. For example, a program may ask "Are you sure? (y/n)". Programs will flush the keystroke buffer before looking for the answer to make sure that the correct answer is properly entered. In some instances, this will also flush the stack.

If you wish to avoid the stack being flushed past the desired keystroke in the stack, place a keyboard delay on the stack by using KEY(PAUSE). This will cause the program to think for a short period that the keystroke buffer is empty. Your desired answer will then be accepted just after this. For example to answer Y (yes) to the above question, you should use the commands:

  KEY(Pause)
  KEY("Y")

KEYPRESSED()

This function returns the letter "F" if the keyboard has not been pressed, and the letter "T" if any key has been pressed. The result is obtained by calling the operating system console status routine.

This function is useful for instances where the batch file may be doing one task while checking with the operator to see if a second task is to be performed, or if the first is to be interrupted.

This function does not affect the results of future CHARIN(), READ, or INKEY commands. It does not remove any keys pending to be read, it only returns the status of key availability.

  BAT * KEYPRESSED() function example

    Type "You have 10 seconds to answer!..."
    Repeat until time(10)
        If KEYPRESSED() then Exit Repeat
    End repeat
    If KEYPRESSED() then Goto -Responded

  -Timeout
    Type "Time is up! You did not answer!!!"
    Exit

  -Responded
    %0 = Charin()
    Type "You answered in time!"
    Type "You pressed the" %0 "key."
    Exit

PLAY( notes )

This function converts a list of notes into the corresponding sound. The music is played in the background so that other operations can continue at the same time in the foreground. Up to 50 notes and rests can be played in the background. If there are more than 50 notes and rests to play, this function will wait for the internal queue to become empty.

The notes available are the same as in BASIC. They can be any combination of the following. To avoid confusion, strings of notes should always be enclosed by quotes.

Pitch

• A to G - The pitch corresponding to the notes on a piano. The suffix + or # raises the pitch a half note. The suffix - lowers the pitch a half note. A length suffix may also follow which changes the length of this one note without changing the measure.
• On - Octave. n is from 1 (low) to 8 (high) octave. Middle C is on octave 3, the default.
• > - Increase the octave by one.
• < - Decrease the octave by one.

Speed

• Ln - Length. n is from 1 (meaning whole note) to 64 (meaning 1/64th note). A quarter note (4) is the default.
• Tn - Tempo. n is from 32 to 250 quarter notes per minute. 120 is the default.
• Pn - Pause. No sound is played. n is from 1 (meaning whole note) to 64 (meaning 1/64th note). A quarter note (4) is the default.
• . - Dotted note. Increases the note length by 3/2.
• ML - Music Ligato. Notes are connected without a rest.
• MN - Music Normal. Notes are separated by 1/8 of a quarter note. This is the default.
• MS - Music Sitcato. Notes are separated by 2/8 of a quarter note.

    BAT * PLAY() a tune to Mary's Lamb...
    %A = "GFE-FGGG"
    PLAY( "T200" %A "P4 FFFP G B-B-4" %A "GFFGFE-..." )

SELECT( Field Color {,Bar Color {,Arrow}} )

This function allows the user to select one item from a list of several items using the cursor. A moving bar indicates which item can be selected. The position, and length of the bar, is limited to the areas on the screen using the field color. The color of the movable bar is bar color. If the bar color is not provided, it will be inverted video.

To use this function, first display the menu with the TYPE or BEGTYPE commands. Highlight each selectable field with the help of the COLOR() or COLORCHAR functions. Then use SELECT() to allow the user to make his selection.

A movable bar is displayed, and is limited to the field colors specified. The arrow keys can move the bar in any direction. Any Function Key, ESC, or Enter key will exit the function. If a letter or number is pressed, it will be compared with upper case characters in each field. If there is a match, the bar will be moved to this field and the function will exit. The Key used to exit is returned as the value of the function.

Upon completion of this function, the position of the bar can be determined from the CURSOR.ROW() and CURSOR.COL() functions. The return code %R will indicate the field number selected.

If the optional word Arrow is used in the SELECT() function, any arrow key will move the bar and exit the function. Normally arrow keys will not cause an exit. This is useful with Lotus(tm) style menus where a changing description is displayed with each different bar position.

  BAT * SELECT example...
  COLORCHAR '/' as COLOR(yellow on black)

  -menu
  COLOR white on black
  CLS BEGTYPE

      Select your favorite fruit

      and press Enter:


             /Apples        /
             /Oranges       /
             /Grapes        /
  end

  -Again
  %0 = SELECT( COLOR(yellow on black) )
  IF LENGTH(%0) = 1 THEN SKIP 1
  IF %0 <> "ENTER" THEN GOTO -Again

  %1 = FIELD(%R)
  LOCATE 1 10
  TYPE %1 "an excellent choice!"

WINDOW( X1, Y1, X2, Y2 {, Kind } )

This function draws a rectangular area on the display. The area is defined by the X1, Y1 location of the top left corner, and the X2, Y2 location of the bottom right corner. The color used is based on the last COLOR command executed. There are several types of borders available as shown. Only the first letter in the border name is required.

Kinds

• B - Blank. No border character is used.
• C - Combo border. A combination of single and double line border that creates a 3D effect.
• D - Double line border.
• H - Highlighted. Light appears to highlight the border from the upper left.
• S - Single line border.
• 3 - 3D border. The window appears to rise from the surface of the display. This is the default.

For convenience, EBL will perform an implied LOCATE command before any TYPE command to align text within the window just created. Using the actual LOCATE command within the program will reset this feature.

Refer to the FIELD() function for an example of using WINDOW().

MATH/CONVERSION Functions

The floating point math and conversion group of functions perform operations on numbers in a variety ways. These functions are useful for special cases where the high precision integer math built into EBL is not sufficient for your application. These are the only group of functions not built into EBL and can be loaded whenever you need them. Like other functions, they can be used anywhere other values or expressions are used. For example, in an assignment statement, an IF or TYPE statement, and so on.

The BATMATH3.COM and BMATH87.COM programs contain these functions for performing floating point math. The BATMATH3 provides 18 digit floating point BCD math. The BMATH87 provides identical functions using the 8087 math co-processor. Use BMATH87 only if you have an 8087 or 80287 co-processor installed in your system. Select either BATMATH3 OR BMATH87 math functions, but do not use both packages at the same time.

To add the math functions to EBL, just enter the name of the external function package from DOS. This is what you should see:

    A> BATMATH3

    Extended Batch Language Plus External Functions
        (BATMATH3-VER2.0)
    (C) Copyright 1986-1995 by Seaware Corp.
    Optional MATH/CONVERSION functions are loaded.

If you use the SET BATINT=xx statement in your AUTOEXEC.BAT file, put BATALLF after this statement. Otherwise, this statement can be put anywhere in your AUTOEXEC.BAT file. See the section on special setup procedures to understand the SET BATINT=xx statement further.

Note: The BATMATH3 or BMATH87 functions are in a TSR that stays loaded in memory. If memory space is in short supply for other programs, you may want to remove BATMATH3 or BMATH87 from memory when it is no longer needed. To do this, use the /K (kill) option.

    A> BATMATH3 /K

Note: The mathematics examples that follow will not work without installing the appropriate external function. Install BATMATH3 or BMATH87 first if you wish to try them out. All other functions are built into EBL for convenience. No extra 'load' step is necessary.

ABS( number )

This function returns the absolute value of the number. The result will always have a positive sign. Results from integer arithmetic built into EBL, as well as results from the FLOAT() function, can be used as an input number. The resulting number will be suitable for continued use in either integer or floating point arithmetic.

    BAT * INT function example

    IF ( WHATFUNC() ? "BATMATH" ) = 0
      THEN TYPE "Must load BATMATH3 first!" | Exit

    TYPE "-PI is almost" FLOAT(-355/113)
    TYPE "Its absolute value is" ABS(FLOAT(-355/113))

Prints the result:

    -PI is almost -3.1415929203539823
    Its absolute value is 3.1415929203539823

C2H( string )

This function does a conversion from characters into hexadecimal values. All characters have an ASCII code representation within the computer. Any character string can be used with this function. The corresponding ASCII code, when represented in hexadecimal, is the output from this function. Valid ASCII codes range on the IBM PC from 00 to FF hexadecimal.

The character string passed to this function will be converted to a series of bytes. The result of this function will be the hexadecimal value of each byte. For example "C2D('Hello')" will result in "48656C6C6F". The ASCII value 48 corresponds to the letter "H", etc.

Note: Although 00 is a valid ASCII character code, it will never be returned from this function as EBL uses it to identify the end of character strings.

This function can be used to interpret special characters coming from files. By using file redirection, these characters can be read from files and devices like serial communication ports. Refer to the previous section for a description of file I/O operations.

This conversion function should be used by advanced programmers only. You should not attempt to use any of them without first understanding the usage of special and non-printable characters. Using them incorrectly can result in hung printers, invisible displays, or other undesired results.

 BAT * C2H function example
 IF ( whatfunc() ? BATMATH ) = 0
   THEN Type Must load BATMATH first! | Exit

 %A = "NOW IS THE TIME"

 TYPE "The ASCII string  is:" %A

 TYPE "The string -> HEX is:" C2H( %A )


 %B = C2H( %A )

 Type "The HEX -> ASCII  is:" H2C( %B )

Prints the result:

 The ASCII string  is: NOW IS THE TIME

 The string -> HEX is: 4E4F57204953205448452054494D45

 The HEX -> ASCII  is: NOW IS THE TIME

D2H( value )

This function performs a conversion from decimal values into hexadecimal values. All decimal values have a corresponding hexadecimal value that is used internally to the PC. There are special programming circumstances that require direct usage of these hexadecimal values (for example with the PEEK() function described later). This function makes it easy to move between these two formats.

This function will accept decimal values that can range from -32768 to 32767. If the input value is not a valid decimal number or is out of this range, an error will result. The hexadecimal results of this function range from 0 to FFFF.

Sixteen bit signed arithmetic is used when working with hexadecimal. Since the highest bit of input value is considered to be a sign bit, the resulting hexadecimal value will change with this sign. For example "D2H( 32767 )" will be "7FFF", but the result of "D2H( -32768 ) will be "8000".

This conversion function should be used by advanced programmers only. You should not attempt to use this without first understanding the usage of hexadecimal manipulation.

Refer to the PEEK() and POKE() functions for further examples.

FLOAT( expression )

This function returns a floating point result after evaluating the expression. This expression can contain both integer and floating point values. For instance 12, 12.0, 1.2E1, and 1.2e+1 all represent the same value, twelve, and all are valid in this expression. The operators can be +, -, *, and /, and are of equal precedence. The order that the operators are evaluated can be changed by using parenthesis. For example:

    FLOAT( 12+5*2 )           returns the value 34
    FLOAT( 12+(5*2) )         returns the value 22
    FLOAT( 12 + ( 5 * 2 ) )   returns the value 22

Notice that the spacing of blanks within the expression is not critical. Variables can also be used freely within the expression.

If %A contains 12.5

    FLOAT( %A+5*2 )           returns the value 35
    FLOAT( %A+(5*2) )         returns the value 22.5
    FLOAT( %A + ( 5 * 2 ) )   returns the value 22.5

Notice that if the result of the expression does not contain a fractional part, then the resulting value will not have any trailing zeros nor a decimal point. An integer result can therefore be used in other non-floating point calculations without modification or adjustment. However, if a fractional part exists, and is not desired, use the INT() function described later. The INT() function will always make results suitable for use in other non-floating point calculations if the fractional result cannot be predicted.

Since the FLOAT() function was created with the BCD version of Turbo Pascal, you can expect 18 digits of precision in the range of 1E+63 to 1E-63. Also, you will not have any rounding errors since numbers are internally represented in BCD. as the results will always be in floating point format, you should use caution when using very large or very small numbers as they may result in a value with many zeros. If you have started the BATMATH3 program, issue the command "BAT TYPE FLOAT( 123e60 )" from DOS for an example of this.

  BAT * FLOAT() function example

    IF ( whatfunc() ? BATMATH ) = 0
      THEN Type Must load BATMATH3 first! | Exit


    Type "PI is:               " FLOAT( 355/113 )

    Type "Its whole part is:   " INT(FLOAT(355/113))

    Type "Its fraction part is:" FRAC(FLOAT(355/113))

    Type


    Type "ENTERING DESK-TOP CALCULATOR:"

  -calc

    Read.Parsed Enter an expression: %A

    If /%a = / exit

    Type Result is ->> FLOAT( %A )
    Type
    goto -calc

Prints the result:

    Pi is:                3.1415929203539823

    Its whole part is:    3

    Its fraction part is: 0.1415929203539823



    ENTERING DESK-TOP CALCULATOR:

    Enter an expression: 15 + 3.14
    Result is ->> 18.14


    Enter an expression:

FRAC( number )

This function returns the fraction portion of the number. The resulting value will never have an integer part.

Results from both integer and floating point arithmetic can be used as an input value. However, as the resulting number contains only fractions, it will only be suitable for continued use in floating point arithmetic with the FLOAT() function.

    BAT * INT function example
    IF ( whatfunc() ? BATMATH ) = 0
      THEN Type Must load BATMATH first! | Exit

    %B = FLOAT( 355/113 )
    Type "A close approximation of PI is" %B

    %A = FRAC( %B )

    Type "The fractional portion is:" %A

Prints the result:

    A Close approximation of PI is 3.1415929203539823

    The fractional portion is: 0.1415929203539823

H2C( value )

This function does a conversion from hexadecimal values into characters. All characters are represented by an ASCII code within the computer. The ASCII code, when represented in hexadecimal, is the input to this function. The corresponding character is the output of this function. Valid ASCII codes range on the IBM PC from 00 to FF hexadecimal.

When using this function, the hexadecimal value will be padded with a leading 0's, if necessary, to make an even number of hexadecimal digits. The value will represent a series of ASCII byte values. The result will be a string of characters corresponding to the series of bytes. For example "H2C( 414243 )" will result in the character string "ABC". The ASCII value 41 corresponds to the letter "A", etc.

Caution: Although 00 is a valid ASCII character code, it cannot be used within this function because EBL uses it to identify the end of character strings. Therefore, when it is used, it will prematurely end any string you are trying to create. For instance H2C( 410043 ) will yield "A" and not "A C" as requested.

This function can be used to create special characters for the display. By using file redirection, these characters can also be sent to files and devices like printers. Refer to the previous section for a description of file I/O operations.

Note that this conversion function should be used by advanced programmers only. You should not attempt to use any of them without first understanding the usage of special and non-printable characters. Using them incorrectly can result in hung printers, invisible displays, or other undesired results.

 BAT * H2C function example
 IF ( whatfunc() ? BATMATH ) = 0
   THEN Type Must load BATMATH first! | Exit

 %A = "NOW IS THE TIME"

 Type "The string in ASCII is:" %A

 Type "The string in HEX is:  " C2H( %A )


 %B = C2H( %A )

 Type "HEX back to ASCII is:  " H2C( %B )

 Type
 Type "You can use H2C to create special characters"
 Type "like the bullet!" h2c( FE )
 Type

 Read May I eject your printer paper? (y/n) %A
 If %A <> 'y' then exit
 >lpt1
 type h2c( 0c ) ;
 >

Prints the result:

 The string in ASCII is: NOW IS THE TIME

 The string in HEX is: 4E4F57204953205448452054494D45

 HEX back to ASCII is:   NOW IS THE TIME


 You can use H2C to create special characters
 like the bullet! þ

 May I eject your printer paper? (y/n) Y

As you see, the printer paper can be ejected by the example above. H2C() is convenient for sending control characters to printers and other devices.

H2D( value )

This function performs a conversion from hexadecimal values into decimal values. All decimal values have a corresponding hexadecimal value that is used internal to the PC. There are special programming circumstances that require direct usage of these hexadecimal values (for example with the PEEK() function described later). This function makes it easy to move between these two formats.

This function will accept hexadecimal values 0 to FFFF as input. The resulting decimal values from this function can range from -32768 to 32767. If the value is not a valid hexadecimal number, 0 is returned. If the hexadecimal value is greater than FFFF, it is an an error. The hexadecimal value does not have to have leading zeros as input. For example "H2D( F )" will result in "15".

Sixteen bit signed arithmetic is used when working with hexadecimal. Since the highest bit of input value is considered to be a sign bit, the resulting decimal value can be negative. For example "H2D( 7FFF )" will be "32767" but the result of "H2D( 8000 ) will be "-32768".

This conversion function should be used by advanced programmers only. You should not attempt to use this without first understanding the usage of hexadecimal. Because H2D() is a function, it can be used anywhere other values can be used. For example, in an expression, an IF or TYPE statement, and so on.

Refer to the PEEK() and POKE() functions for further examples.

INT( number )

This function returns the integer portion of the number. The resulting value will never have any fractional part. The INT() function is therefore useful for converting a floating point result into a form that can be used with the integer arithmetic built into EBL.

Results from both integer and floating point arithmetic can be used as an input value. The resulting number will be suitable for continued use in either integer or floating point arithmetic.

    BAT * INT function example
    IF ( whatfunc() ? BATMATH ) = 0
      THEN Type Must load BATMATH3 first! | Exit

    %B = FLOAT( 355/113 )
    Type "A close approximation of PI is" %B

    %A = INT( %B )

    Type "The integer portion is:" %A

Prints the result:

    A Close approximation of PI is 3.1415929203539823

    The integer portion is: 3

RANDOM( {{min,} max {,seed}} )

This function generates a pseudo-random number. The default min is 0, default max is 999, default seed is random based on time. If only one parameter is supplied, that parameter is a max and the min will be 0. If seed is not given, the seed is random based on system time. Otherwise the seed will restart a repeatable pseudo random pattern.

   RANDOM()             == 345  (perhaps)
   RANDOM(10)           == 7    (perhaps)
   RANDOM(50,75)        == 62   (perhaps)

STRING Functions

The string group of functions perform various operations on characters. As with other functions, they can be used anywhere other values or expressions are used. For example, in an assignment statement, an IF or TYPE statement, and so on.

ABBREV( information, info {, length})

This function identifies when an abbreviation is correct. It returns 1 when info matches the first characters within information. Otherwise it returns 0. By default, all characters within info must match, but the minimum amount of characters required to match can be changed with length. If info is empty or length is zero, then the abbreviation matches.

    ABBREV('Print','Pri')    == 1
    ABBREV('PRINT','Pri')    == 0
    ABBREV('PRINT','PRI',4)  == 0
    ABBREV('PRINT','PRY')    == 0
    ABBREV('PRINT','')       == 1
    ABBREV('PRINT','',1)     == 0

For example, ABBREV() can be used to identify when an option or its proper abbreviation is used.

    READ Enter option: %1

    %1 = UPPER(%1)
    IF ABBREV('KEYWORD1', %1) THEN GOTO ....
    IF ABBREV('KEYWORD2', %1) THEN GOTO ....
    ELSE GOTO ....

BITAND( string1 {,{string2} {,pad}} )

This function returns the logical bit AND of two strings. If the strings are not the same size, the pad character is ANDed with the larger remaining string. The resulting size is the same as the largest string.

BITOR( string1 {,{string2} {,pad}} )

This function returns the logical bit OR of two strings. If the strings are not the same size, the pad character is ORed with the larger remaining string. The resulting size is the same as the largest string.

    BITOR("FRED", "", " ")         == "fred"
    BITOR("ThAT", "    This", "")  == "thatThis"

BITXOR( string1 {,{string2} {,pad}} )

This function returns the logical bit XOR of two strings. If the strings are not the same size, the pad character is XORed with the larger remaining string. The resulting size is the same as the largest string.

CENTER( string, length {,pad} )

CENTRE( string, length {,pad} )

This function returns a character string of length length. The center-most characters of the string are returned. If the length is smaller than the string, the result is truncated at both ends to fit. If the length is larger than the string, the result is padded on the left and right. The default pad character is a blank, but may be optionally supplied. The length can be from 0 to 255 characters long. If an odd number of characters are truncated or added, the right hand end loses or gains one more character than the left hand end. This function may be called either CENTER or CENTRE to avoid errors due to differences between American and British spellings.

    CENTER( 'ABC', 7 )              ==  '  ABC  '
    CENTER( 'ABC', 8, '-' )         ==  '--ABC---'
    CENTER( 'The Blue Sky', 8 )     ==  'e Blue S'
    CENTER( 'The Blue Sky', 7 )     ==  'e Blue'

COPIES( string, n )

This function returns n copies of the string.

    COPIES('Two-',2)                ==  'Two-Two-'
    COPIES('Two-',0)                ==  ''

DELWORD( string, n {, length} )

This function removes a portion of the string starting at the nth word. A length amount of words separated by blanks will be removed. If length is not used, it will remove all remaining words in the string. If n is larger than the amount of words in the string, then nothing is deleted.

    DELWORD('now is the time',2,2)  == 'now time'
    DELWORD('now is the time',3)    == 'now is '
    DELWORD('now is the time',5)    == 'now is the time'

FIND( sentence, phrase )

This function finds the phrase string within the sentence string. If found, it will return the position of the first matching word in the sentence. If not found, it will return 0. Various amounts of blanks between words in the sentence and phrase do not affect the comparison.

    FIND('now is the time','is the')    ==  2
    FIND('now is the  time','the time') ==  3
    FIND('now is the  time','the day')  ==  0

LEFT( string, length {,pad} )

This function returns a character string of length length. The left-most characters of the input string are returned. If the length is smaller than the input string, the result is truncated. If the length is larger than the string, the result is padded on the right. The default pad character is a blank, but may be optionally supplied. The length can be from 0 to 255 characters long.

    LEFT( "ABC D", 8 )                  == 'ABC D   '
    LEFT( "ABC", 8, '-' )               == 'ABC-----'
    LEFT( "---Hello-There--", 8 )       == '---Hello'
    LEFT( "ABCDEFGH", 5 )               == 'ABCDE'

LENGTH( string )

This function returns the number of characters in the 'string'.

    LENGTH('abcdefgh')                  == 8
    LENGTH('')                          == 0

LOWER( string )

This function returns a character string with all characters converted to lower case. The string length remains identical. Only characters from upper case "A" to "Z" are affected. Other characters, including control characters, remain unaffected.

MID( string ,start {,length, {pad}} )

Please see the SUBSTR() function for further information. A synonym for the MID() function is SUBSTR(). Either function name can be used.

OVERLAY( new, target, n {,length {,pad}} )

The OVERLAY() function returns a new string placed on top of an existing target string. at position n. The length determines how many characters from new are used. Pad characters will be added if new is too short. The default length is the size of the new string. The default pad is a blank.

   OVERLAY(' ','abcdef',3)      == 'ab def'
   OVERLAY('.','abcdef',3,2)    == 'ab. ef'
   OVERLAY('qq','abcd',1)       == 'qqcd'
   OVERLAY('qq','abcd',4)       == 'abcqq'
   OVERLAY('123','abc',5,6,'+') == 'abc+123+++'

REVERSE( string )

This function will reverse the letters within the string end for end. The reversed string is returned to the caller.

    REVERSE('Abc defg')  ==  'gfed cbA'

RIGHT(string,length{,pad})

This function returns a character string of length length. The right-most characters of the input string are returned. If the length is smaller than the input string, the result is truncated. If the length is larger than the string, the result is padded on the left. The default padding character is a blank, but may be optionally supplied. The length can be from 0 to 255 characters long.

    RIGHT("ABC D",8)                    ==  '   ABC D'
    RIGHT("ABC",8,'-')                  ==  '-----ABC'
    RIGHT("---Hello-There--",8)         ==  '-There--'
    RIGHT("ABCDEFGH",5)                 ==  'DEFGH'
    RIGHT("123",8,0)                    ==  '00000123'
    RIGHT("123.45",8,'*')               ==  '**123.45'

SPACE( string, {n {, pad}} )

This function changes the spacing of the string to be n blanks between each word. If n is 0, then all blanks are removed. The filler character can be something other than blank by using the optional pad character. Leading and trailing blanks are always removed.

    SPACE('abc    def')         == 'abc def'
    SPACE('abc  def  ',1)       == 'abc def'
    SPACE(' abc def  ',2)       == 'abc  def'
    SPACE(' abc def  ',0)       == 'abcdef'
    SPACE(' abc def  ',1,'-')   == 'abc-def'

STRIP( string {,type {,char}} )

This function removes a character from the sides of the string. The default type of striping is to Both sides of the string but may also be Leading or Trailing. The optional parameter type indicates the sides to be striped. This parameter may be "B", "L", or "T" respectively for the three types of striping.

The default character to be striped from the sides of the string is a blank. The optional parameter char can be used to indicate another character to be striped. Since this parameter is position dependant, the type parameter must be specified when the char parameter is used.

The effect of this function is the reverse of the LEFT(), RIGHT(), or CENTER() functions. Those functions add a character to a side of a string where the STRIP() function removes it.

    STRIP( "ABC   ")                    ==  'ABC'
    STRIP( "   AB C   ")                ==  'AB C'
    STRIP( "   AB C   ",L )             ==  'AB C   '
    STRIP( "   AB C   ",T )             ==  '   AB C'
    STRIP( 12.700   , B, '0' )          ==  '12.7'
    STRIP( 00012.700, T, '0' )          ==  '00012.7'
    STRIP( "---Hello-There--",B, '-' )  ==  'Hello-There'

SUBSTR( string ,start {,length, {pad}} )

MID( string ,start {,length, {pad}} )

This is a superset of the existing substring operator '$'. This function returns a portion of a string starting at the start character within the string, up to length characters long. If length is longer than the original string, then a pad character is appended. The default length is the size of the original string. The default pad character is a blank. A synonym for the SUBSTR() function is MID(). Either function name can be used.

   SUBSTR("12/23/56",4)      == "23/56"
   SUBSTR("12/23/56",1,5)    == "12/23"
   MID("12/23/56",1,5)       == "12/23"
   SUBSTR("Abcde",4,5,'-')   == "de---"

SUBWORD( string, n {, length} )

This function returns a portion of the string starting from the nth word for length words long. If length is omitted, the remainder of the string is returned.

    SUBWORD("now is the time",2,2)   == 'is the'
    SUBWORD("now is the time",3)     == 'the time'
    SUBWORD("now is the time",5)     == ''

TRANSLATE( string {,{to list}{,{from list}{,pad}}} )

This function translates a string to different characters. If a character in the string is found in the input list of characters from list, then it will be translated to the corresponding character in the output to list. If the character is not found in the input list, then no change is made. If there are more characters in from list than to list, it will be translated to a pad character. The default pad character is a blank. The default output list is empty (null). If only a string is supplied without any lists, then the string will be translated to upper case. For example:

   TRANSLATE("12/23/56","-","/")    == "12-23-56"
   TRANSLATE("abcde","HEX","bcd")   == "aHEXe"
   TRANSLATE("abcde","1","bcd",".") == "a1..e"

UPPER( string )

This function returns a character string with all characters converted to upper case. The string length remains the same. Only characters from lower case "a" to "z" are affected. Other characters, including control characters, remain unaffected.

    UPPER("ABC/def/Ghi")   ==   'ABC/DEF/GHI'
    UPPER("abc/def/ghi")   ==   'ABC/DEF/GHI'
    LOWER("ABC/def/Ghi")   ==   'abc/def/ghi'
    LOWER("abc/def/ghi")   ==   'abc/def/ghi'

VERIFY( string, reference )

This function verifies that the string is composed only of characters in the reference string. The first non-matching character position in string is returned. If all characters in the string are in the reference, then 0 is returned.

    VERIFY( "$12.95","0123456789.$")    ==  0
    VERIFY( "$12xxx","0123456789.$")    ==  4

WORD( string, n )

This function returns the nth blank delimited word from the string.

    WORD('Powerful new EBL features',2) ==  'new'
    WORD('Powerful new EBL features',7) ==  ''

WORDS( string )

This function returns the number of blank delimited words within the string.

    WORDS(' ')                          ==  0
    WORDS('Power house capability')     ==  3
    WORDS("fe fi fo fum")               ==  4

XRANGE( start {, end )

The XRANGE() function returns a sequence of characters between and including the characters start and end. The start character is required, but the default end character is hexadecimal FF. If start or end are strings, only the first character is used from each string to determine the range. If start is greater than end, the sequence will wrap from FFh to 01h. The value 00h is never returned as this character is a delimiter within EBL.

    XRANGE(a,h)      == 'abcdefgh'

    XRANGE(0,A)      == '0123456789:;<=>?@A'

SYSTEM Functions

The System Functions are use to get the status of the computer, and performs various operations on the files of a hard disk or floppy disk. As with other functions, they can be used anywhere other values or expressions are used. For example, in an assignment statement, an IF or TYPE statement, and so on.

CHDIR( directory_name )

The current sub-directory and/or default drive is changed to the new directory_name. For example CHDIR("\path") will change the current sub-directory to \path, CHDIR("D:") will change the default drive to D:, and CHDIR("D:\path") will change both drive and sub-directory. If the path to the new sub-directory is not found on the disk, the error "Path was not found" will result (error #82).

CHDIR() returns no value. It can be used by itself to change to a sub-directory. To get the name of the current directory, use the GETDIR() function.

  BAT * CHDIR directory example

    * Change to drive C root

    CHDIR("C:\")


  -show.dir
    CLS TYPE Current directory is GETDIR()
    IF ( GETDIR() # ) = 3
       THEN TYPE "This is the root directory."

    TYPE                  |* show directory, wide
    SHELL DIR *.* /W
    TYPE

  -next.dir
    READ Enter a new subdirectory name> %A

    IF /%A = / THEN EXIT
    CHDIR(%A)             |* change to new dir.
    GOTO -show.dir

  -on.error-              |* recover from CHDIR errors
    if %R = 33 TYPE "Path not found!" | GOTO -next.dir
    TYPE "Unexpected error #" %R "in line" %L
    EXIT

DATE( {type} )

This function returns a character string representing the system date. The default DATE() function without a type will return the system date in the format 'dd Mmm yyyy'. For example, it would return a date in the form '2 Sep 1995'. There will be no leading zero or blank on the day.

It is also possible to obtain other formats by using the type operand. Type is a single character used to indicate the type of alternate format desired. The possible formats are:

C - (Century) This returns the number of days, including the current day, so far in this century. It has the format 'ddddd' and does not contain any leading blanks or zeros in this value.

D - (Days) This returns the number of days, including the current day, so far in this year. It has the format 'ddd' and does not contain any leading blanks or zeros in this value.

E - (European) This returns the date in the format 'dd/mm/yy'.

J - (Julian) This returns the date in the format 'yyddd'.

M - (Month) This returns the full name of the current month. For example it might be 'January'.

N - (Normal) This returns the date in the default format 'dd Mmm yyyy'. For example it might be '27 Aug 1985'. There will be no leading zero or blank on the day.

O - (Ordered) This returns the date in the format 'yy/mm/dd'.

S - (Standard) This returns the date in the format 'yyyymmdd'. For example it might be '19850827'. This is one of the three forms recommended by the International Standards Organization. The other two forms can be derived from this to become the forms '1985 08 27' or '1985-08-27'. Refer to the ISO document ISO/R 2014-1971 for further details if needed.

U - (USA) This returns the date in the format 'mm/dd/yy'.

W - (Weekday) This returns the full name of the current week day. For example it might be 'Monday'.

Note that because DATE() and DATE( type ) are functions, they can be used anywhere other values can be used. For example, within an expression, an IF or TYPE statement, and so on.

    BAT * DATE examples

    TYPE This example started at TIME() on DATE()
    BEGTYPE

     --Format-------Usage---------Example--

     Normal    :  DATE()     :  \( DATE()    )

     Normal    :  DATE( N )  :  \( DATE( N ) )

     USA       :  DATE( U )  :  \( DATE( U ) )

     European  :  DATE( E )  :  \( DATE( E ) )

     Ordered   :  DATE( O )  :  \( DATE( O ) )

     Standard  :  DATE( S )  :  \( DATE( S ) )

     Julian    :  DATE( J )  :  \( DATE( J ) )

     Century   :  DATE( C )  :  \( DATE( C ) )

     Month     :  DATE( M )  :  \( DATE( M ) )

     Days      :  DATE( D )  : \(" " & DATE( D ) )

     Week Day  :  DATE( W )  :  \( DATE( W ) )

    END

Prints the result:

    This example started at 13:32:09 on 25 Aug 1995


    --Format-------Usage---------Example--

    Normal    :  DATE()     :  25 Aug 1995

    Normal    :  DATE( N )  :  25 Aug 1995

    USA       :  DATE( U )  :  08/25/95

    European  :  DATE( E )  :  25/08/95

    Ordered   :  DATE( O )  :  95/08/25

    Standard  :  DATE( S )  :  19950825

    Julian    :  DATE( J )  :  95237

    Century   :  DATE( C )  :  32744

    Month     :  DATE( M )  :  August

    Days      :  DATE( D )  :  237

    Week Day  :  DATE( W )  :  Friday

Any additional way to use the DATE() or TIME() functions is to have it determine when other applications can execute. For example, this batch file will start a PS2TAPE tape backup program only on Monday.

    BAT * Tape Backup example

    * Test for day of week match to start program
    IF Date(W) = Monday THEN PS2TAPE BACKUP ALL

DIR( filename {,type {,attribute}} )

This function is a superset of the EXIST() function. It can return any information about the files on the disk. The type and attribute portions are optional. If neither are used, the result is identical to the EXIST() function. A summary of options follows. Results shown are typical but may be different than your results. The following types of information can be returned:

N - Name returns the first matching file name on the disk. Path and wild card characters are allowed. If there is not a matching file, then an empty (null) result is returned. In this category, the following attributes are allowed. They can be used to limit the search to certain kinds of information.

 V - Volume label
 D - Sub-Directory
 H - Hidden
 S - System
 I - Include Normal files

The attribute I can be combined with the attributes D, H, or S. Typical results are:

 DIR('*.COM')      == 'COMMAND.COM'    Name of normal
                                       file
 DIR('*.XXX')      == ''               Non-existent Name
 DIR('*.COM',n)    == 'COMMAND.COM'    Name of normal
                                       file
 DIR('*.COM',n,d)  == 'SUBDIR1'        Subdirectory
                                       search only
 DIR('*.COM',n,di) == 'COMMAND.COM'    Subdirectories +
                                       normal files

S - Size returns the decimal size of the file in bytes.

 DIR('*.COM',s)    == 27654            Size

D - Date returns the date that the file was last written. In this category, the following attributes are allowed. They are the same as the DATE() function. If no attribute is used, the default is the USA style date.

 N - Normal        29 Mar 1995
 U - USA           03/25/95
 E - European      25/03/95
 O - Ordered       95/03/25
 S - Standard      19950325
 J - Julian        95084
 C - Century       31126
 M - Month         March
 D - Days          84
 W - Week Day      Tuesday

Typical results are

 DIR('*.COM',d)    == '03/29/95'        Default=USA
                                        style
 DIR('*.COM',d,n)  == '29 Mar 1995'     Normal style 'N'

T - Time returns the time when the file was last written. In this category, the following attributes are allowed. They are the same as the TIME() function. If no attribute is used, the default is Civil time.

 N - Normal        01:29:14

 C - Civil         1:29am

 L - Long          01:29:14.41

 H - Hours         1
 M - Minutes       95
 S - Seconds       5354

Typical results are

 DIR('*.COM',t)    == 2:24pm           Default=Civil

 DIR('*.COM',t,n)  == 14:24:14         Normal type 'N'

A - Attribute returns the type of file that is named. Possible values returned can be as follows. Depending on the file type, more than one may be present.

"V" - Volume label
"D" - Sub-Directory
"H" - Hidden
"S" - System
"R" - Read only
"A" - Archive
" " - Normal file

I - Index returns the next matching file name in the directory. When you use a file name with wild card characters, use the Name type to find the first name, and this Index type find all other possible names after that. If there are no more matching file names, then an empty (null) result is returned.

 DIR('*.COM',i)    == 'SHARE.COM'      Index to next
                                       name
 DIR('*.COM',i)    == 'PRINT.COM'      Index to next
                                       name
 DIR('*.COM',i)    == ''               No more names

P - Position returns a 'bookmark' to the current directory position. You can use this when doing several Index lookups in different subdirectories if you want to return to the same place. The bookmark is actually a hex string that should not be used, or altered, for other purposes.

R - Return is the complement of Position. Use the previous bookmark value as the file name. After this, future Index lookups will come from the previously marked Position. No value is returned from this function.

 DIR('*.COM',p)    == 123...90         Position of dir
 DIR('123..90',r)  == ''               Return to
                                       position

Note: The Size, Date, Time, and Attribute types will return their proper value for the last file looked up via the Name or Index options. The file name must be the same. If, instead, it is a different file name, the value will be returned for the first file that matches the new name.

BAT * DIR() function example...

    %B = "*.COM"
    TYPE "Directory of all" %B "files..."

    %A = DIR(%B)                |* Get first name
    Repeat While %A THEN        |* Loop on all names
      Type LEFT(%A,20) ;        |* show name
      Type LEFT(DIR(%B,A),4)  ; |* show attributes
      Type LEFT(DIR(%B,S),10) ; |* show size
      Type DIR(%B,D) "   ;"     |* show date
      Type DIR(%B,T)            |* show time
      %A = DIR(%B,I)            |* Index to next name
    End Repeat

EXIST( file )

EXIST(filename) determines if a file is in the directory. It returns the file name if it does exist, and a NULL value if it does not exist. The file name can contain a complete path and the wild characters * or ?. It is easily combined with the IF command like:

    IF EXIST("FILE.TXT") THEN ..statement..

If the file FILE.TXT exists, then the statement that follows it will be executed. Note that the ELSE command has the reverse meaning of THEN. That is, if ELSE is substituted above, the statement will be executed if FILE.TXT does NOT exist.

Note that this uses the 'Find First' DOS call. Therefore if you use the wild card characters * or ?, the EXIST() function will always return the same file name. If you want to look for successive files with wild card characters, use the DIR() function.

BAT * EXIST() function example..
    %D = left(date(Month),3) & ".DAT"
    TYPE "Ready to use" %0 "data file"
    IF EXIST(%D) THEN
    BEGIN
       TYPE "Data file exists already"
       READ Want to erase it? (y/n) %0
       IF %0 <> y then skip 1
       erase %D
    END
    TYPE "Continuing with fresh" %D

GETDIR()

The current sub-directory name of the default drive is returned. The name will be a valid, fully qualified, path name including the current default drive. For example, if the current directory is the root directory on drive C, a "C:\" will be returned.

Because this is a function, it can be used anywhere other values can be used. For example, in an expression, an IF statement, and so on.

  BAT * GETDIR() Get directory example

  -show.dir
    CLS TYPE "Current directory is" GETDIR()
    IF ( GETDIR() # ) = 3
       THEN TYPE This is the root directory.

    TYPE                  |* show directory, wide
    SHELL DIR *.* /W
    TYPE

  -next.dir
    READ Enter a new subdirectory name> %A

    IF /%A = / THEN Exit
    CHDIR(%A)             |* change to new dir.
    GOTO -show.dir

  -on.error-              |* recover from CHDIR errors
    if %R = 82 TYPE "Path not found!" | GOTO -next.dir
    TYPE "Unexpected error #" %R "in line" %L
    Exit

INT86( intr, regs )

This function executes an 8086 software interrupt. CAUTION! The INT86() function is for advanced programming functions only. You should not attempt to use it without first understanding the system memory layout and interrupt requirements. Using it incorrectly can easily result in system crashes. Do not try this command if you do not know how to use it properly. In the worst case, you could loose all your data on your diskettes or hard files.

The intr value is a hex number from 00 to FF of the software interrupt to be executed.

The regs value is a series of hex values for AX BX CX DX SI DI DS and ES in that order. They are word values given in hex and separated by blanks. If only the first values are needed, the remaining ones do not need to be present.

Implementation note: Currently this function is defined such that each register's contents must be in a separate constant or variable. One EBL variable containing all register contents will not work.

For example, if you need to do interrupt 21 with AX set to 0900 and DX set to 2A0 then the command would be "INT86( 21 0900 0 0 02A0 )". Note that dummy values need to be given to BX and CX, but are not required for the remaining registers.

In cases where either a string of text, or a small amount of temporary storage needs to be passed to an interrupt, a variable can be used. In order to pass the location of a variable, the special notation "%%A" is used to indicate the address of the variable "%A". If this notation is used with registers AX through DI, the offset of the variable will be used. If used with either DS or ES, the segment of the variable will be used. Global EBL variables can be used as temporary storage with this technique, but only with caution. These variables can hold no more than 256 bytes, and you must specify global variables %A to %O only. This could be useful for holding FCB's, etc. DOS variables or other special variables do not have a fixed allocated space and may not work.

If these variables are used for storage, other techniques are available if larger storage areas are needed. For example, you could write another extended EBL function that has its own storage allocated especially for that function. Alternately, you could call DOS to allocate memory and use the pointer it returns for other functions. As an example of pointing to storage, the variable %A will be initialized to a string and printed with a DOS interrupt.

    %A = Hello$
    INT86( 21 0900 0 0 %%A 0 0 %%A )

In this case, DS:DX will point to the memory location of the variable %A. The function in AH was 09 and the DOS call to print the "Hello" string was interrupt 21. All other registers were unused.

In the use of INT86() above, it is a keyword all by itself and nothing is returned to EBL. However, if used as a value, then a string will be returned with nine hexadecimal values separated by blanks. These values will be AX BX CX DX SI DI DS ES and FLAGS in that order. Note that this is a single string. Use the PARSE command within EBL to separate this string to look at an individual register. For example, after the command "%A = INT86( 21 0900 0 0 %%A 0 0 %%A )" is executed, the variable %A might be set to "098A 00 00 02A0 00 00 3F04 3F04 0202". Note that nine values are always returned, with each separated by a space.

As the INT86() function is so powerful, it may be tempting to overuse. Because EBL is interpreted it may be slower than using an external EBL function written yourself or calling an outside program that does the same task. You should carefully consider this in cases where INT86() may over burden your application. In simpler cases, the INT86() function will be a joy to quickly get direct access to the system without special hooks.

 BAT * INT86 function example. Clear Screen From line X.

 If /%1 = /
   THEN Read Clear screen from which line number? %1

 %A = D2H( %1 ) & 00           |* Make line # hex
 INT86( 10 0700 0700 %A 1850 ) |* Use BIOS to clear
                               |*   screen portion
 INT86( 10 0200 0 0 %A )       |* Use BIOS to put
                               |*   cursor at top
 INT86( 10 0AC4 0 50 )         |* Draw line at top

 %A = D2H( ( %1 + 1 ) ) & 00   |* Convert dec line #
                               |*   +1 to hex
 INT86( 10 0200 0 0 %A )       |* Use BIOS to put
                               |*   cursor at next line

 %B = "Demonstration of INT86() using BIOS and DOS!$"

 INT86( 21 0900 0 0 %%B 0 0 %%B )
                               |* Use DOS to print text
                               |* Note use of "%%" as
                               |*    pointers to text.
 exit

Clears the screen and prints the result:

    --------------------------------------------------
    Demonstration of INT86() using BIOS and DOS calls!

In the second example, the INT86() function is used to determine how much free space is available on a specific disk drive. After asking the user which drive to test, the D2H() H2D() and C2H() conversion functions are used to convert the drive letter A, B, C... into a hexadecimal drive number 00, 01, 02, ... etc. The INT86() function is then used to call a DOS function 36H to report the available space. The DOS results are immediately moved to variables %1 to %4 with the PARSE command. Once converted to decimal, those results can be displayed.

bat /N * TEST FREE SPACE

* BATMATH3 needed under interpreter.
*     Not needed for Compiler...
If ( Whatfunc() ? BATMATH ) = 0
   Then type "Must load BATMATH3 first!" | Exit

* Get drive letter
READ Which drive letter? %0

* Convert drive letter %0 into hex drive number %D
%D = D2H((H2D(C2H(UPPER(%0))) - 64))

* Get free space from DOS into %1 to %3 via
*     DOS Func 36H (%4 is dummy)
PARSE INT86( 21 3600 0 0 %D ) %1 %2 %3 %4

* Convert hex results into final decimal value
%1 = H2D( %1 )
%2 = H2D( %2 )
%3 = H2D( %3 )
TYPE "Drive" %0 "free space is" ( %1 * %2 * %3 )

MKDIR(directory_name)

A new sub-directory is created with this function. This new name can include a default drive name. The directory name can not exceed 63 characters.

  BAT * MKDIR() directory example

  -show.dir
    CLS TYPE "Current directory is" GETDIR()
    IF ( GETDIR() # ) = 3
        THEN TYPE "This is the root directory."
    MKDIR("SALE$")        |* Create a sales directory
    MKDIR("SALE$\FRANK")  |*   for Frank & Eva
    MKDIR("SALE$\EVA")
                          |* Show (empty) contents
    TYPE "Contents of temporary sales directory..."
    DIR SALE$\*.* /W

    RMDIR("SALE$\FRANK")   |* Remove directories
    RMDIR("SALE$\EVA")
    RMDIR("SALE$")
    TYPE "Temporary sales directory has been removed."

PEEK(location)

This function returns a byte of memory, in hex, at location. The hex value returned is always two characters. The location is a two part hex value and contains both a segment and an offset, separated by a colon ":". For example, the location "0040:01A4" would represent segment 0040 and offset 01A4. If the segment is not present, it is assumed to be zero. If both segment and offset are supplied, then the colon ':' between them is required.

For example, PEEK( 40:9F ) looks at the memory location segment 40 offset 9F and returns the byte value 2E (for example). Note that values supplied to, and returned from, this function are in hexadecimal. If you require decimal values instead of hexadecimal, use the H2D() or D2H() functions described earlier in this section.

The PEEK() and POKE() functions are for advanced programmers only. You should not attempt to use them without first understanding the system memory layout. Using them incorrectly can result in system crashes.

Because PEEK() is a function, it can be used anywhere other values can be used, for example, in an expression, an IF or TYPE statement, and so on.

  BAT * PEEK() function example
  IF ( whatfunc() ? BATMATH ) = 0
    THEN Type Must load BATMATH first! | Exit

  -get.locn
    Type
    Type "Ready to display a block of memory..."

    Read What Segment (in hex) > %A
    Read What Offset  (in hex) > %B
    If /%A = / then exit        |* stop if no entry
    If /%B = / then exit        |* stop if no entry

    Repeat with %I = 0 to 63
      If (%I % 16) is 0 then    |* Every 16th byte...
      Begin
        Type                    |* display the address

        Type (RIGHT(%A,4,0) & ':' & RIGHT(%B,4,0)) ;

      End if

      Type PEEK( %A:%B ) ;      |* display memory loc

      %B = D2H((H2D(%B)+1))     |* Hex address+1
    End Repeat
    Goto -get.locn

  -on.error-
    If %R = 81 Beep Type "Invalid Hex value"
       Then  goto -get.locn
    Else Type "Unexpected error" %R "at line" %L
    Exit

Prints the result (values you get may be different):

Ready to display a block of memory...
What Segment (in hex) > 40
What Offset  (in hex) > 0


0040:0000 F8 03 F8 02 00 00 00 00 78 03 00 00 00 00 D0

0040:0010 61 44 B0 00 02 00 00 00 00 00 24 00 24 00 0D

0040:0020 30 0B 0D 1C 00 48 0D 1C 3E 34 74 14 2E 34 74

0040:0030 00 3C 04 20 74 14 74 14 0D 1C 34 05 30 0B 00


Ready to display a block of memory...
What Segment (in hex) >

POKE(location,value)

This function writes a byte of memory at location with the contents of value. No value is returned from this function after the write. Location is a two part hex value and contains both a segment and an offset separated by a colon ":". For example, the location "0040:01A4" would represent segment 0040 and offset 01A4. If the segment is not present, it is assumed to be zero. If both segment and offset are supplied, then the colon ':' between them is required.

For example, POKE( 40:9F,2E ) writes the memory location segment 40 offset 9F with the byte value 2E (for example). Note that values supplied to this function are in hexadecimal. If you require decimal values instead of hexadecimal, use the H2D() function described earlier in this section.

The PEEK() and POKE() functions are for advanced programmers only. You should not attempt to use them without first understanding the system memory layout. Using them incorrectly can result in system crashes.

Because POKE() is a function, it can be used anywhere other values can be used. For example, in an expression, an IF or TYPE statement, and so on.

                                                 x
 BAT * POKE function example
 IF ( whatfunc() ? BATMATH ) = 0
   THEN Type Must load BATMATH first! | Exit


   If PEEK( 40:49 ) = 07 then %A = B000  |* mono screen

   Else %A = B800                        |* color screen

   Cls Type "Direct video character dump using POKE ..."
   %B = 32      |* Init offset of 1st line (decimal)
   Locate 1 20

 Repeat with %C = 0 to 255               |* 256 chars
   If ( %C % 16 ) = 0        |* new line each 16 chars

      then %B += (H2D(PEEK(40:4A)) * 2) - 32

   %J = POKE((%A: & D2H(%B)) D2H(%C))    |* write char

   %B += 2                               |* next posn
 End Repeat

Prints the result (this is a subset of your results):

    Direct video character dump using POKE ...
     !"#$%&'()*+,-./

    0123456789:;<=>?

    @ABCDEFGHIJKLMNO
    PQRSTUVWXYZ[\]^_
    'abcdefghijklmno
    pqrstuvwxyz{|}~

REBOOT

This command initializes the PC by starting the bootstrap (IPL) procedure. This is equivalent to pressing CTRL-ALT-DEL on the keyboard. Once this command is executed, all programs are removed from memory (including EBL) and the system will reload from either diskette or hard disk. If the system is a PC compatible, the memory test will be avoided which will speed up the re-booting process.

This command is useful in batch files which configure a system automatically. For example, EBL could set the CONFIG.SYS and AUTOEXEC.BAT files on a hard disk, then start the system with that configuration automatically by using REBOOT. Another use is to create a way of automatically removing resident programs such as SIDEKICK or SUPERKEY. Creating a new Autoexec file without these TSRs then using REBOOT is a slow, but reliable, way to re-configure your system. An example of this is shown below.

The first example re-configures the system so that the system configuration, and all resident programs, are removed. A CTRL-ALT-DEL after that re-configuration will restore the original configuration.

 BAT * REBOOT example

 Type "The REBOOT command is useful after a batch file"
 Type "that reconfigures the system. This example will"
 Type "remove all resident programs & configuration.  "
 Type "                                               "
 Type "Pressing CTRL-ALT-DEL after that will restore  "
 Type "the original configuration.                    "
 Type
 Type "Would you like to REBOOT to a"
 Read simple autoexec? (y/n) %A
 If %A is not 'y' then exit
 Type "Setting up new configuration...."

 cd \
 rename autoexec.bat autoexec.$$$

 * setup new simple autoexec.bat

 >autoexec.bat
 type tmp.bat
 >
 >tmp.bat
 type erase autoexec.bat
 type rename autoexec.$$$ *.bat
 type rem  REBOOT AGAIN TO RESTORE AUTOEXEC!
 >
 REBOOT

RMDIR(directory_name)

An empty sub-directory is removed with this function. The name can include a default drive name. The directory name cannot exceed 63 characters. DOS requires that the sub-directory be completely empty of both files and other sub-directories before it can be removed.

Because this is a command, it must be used at the beginning of a statement and the name RMDIR is considered a keyword.

  BAT * RMDIR() directory example

  -show.dir
    CLS TYPE Current directory is GETDIR()
    IF ( GETDIR() # ) = 3
        THEN TYPE "This is the root directory."
    MKDIR("SALE$")        |* Create a sales dir
    MKDIR("SALE$\FRANK")  |*   for Frank & Eva
    MKDIR("SALE$\EVA")
                          |* Show (empty) contents
    TYPE Contents of temporary sales directory...
    DIR SALE$\*.* /W

    RMDIR("SALE$\FRANK")   |* Remove directories
    RMDIR("SALE$\EVA")
    RMDIR("SALE$")
    TYPE Temporary sales directory has been removed.

SEEK( r/w {,position} )

This function can be used to find the location within a file that is are being read or written. It can also be used to change that position. This can be used to create files with special formats, or to allow files to be randomly accessed.

The first parameter r/w is required. It may be one of:

    "<" or "R" for file currently being read,
    ">" or "W" for file currently being written.

If this is the only parameter supplied, the SEEK() function will return the current I/O position in the file. This value will be a decimal offset from the beginning of the file. For example:

    BAT TYPE SEEK(R)

This will display on the screen the current position of the file being read, without changing this position.

If position is supplied, the file position will be moved to this new location. The position must be a positive decimal number. For example:

    BAT * Change a file's read position
        <TEST.FIL
        SEEK(R,12)
        READ.PARSED %0

        TYPE "File character 12 is:" %0

moves the position of the file currently being read to byte 12.

If position is 'EOF', the file position will be moved to the end of the file. For example:

    BAT * Show file size
        <TEST.FIL
        TYPE "File contains" SEEK(R,EOF) "bytes"

moves the file position to the end of the file and displays the number of bytes currently in the file.

If SEEK() is used as a value, it will return the new read/write pointer position, in bytes, relative from the beginning of the file.

BAT * SEEK() function example - simple DATA BASE

  %N = EBLSEEK.TST        |* name of database file
  CLS BEGTYPE
--- This example allows a file to be a simple    ---
--- data base to demonstrate the powerful SEEK() ---
--- function in EBL.                             ---

END

-Show
  <%N                |* open the test file
  %I = SEEK( R,EOF)+79/80 |* How many 80 byte records?
  Type "Data base" %N "now contains" %I "records."
  <                  |* close the file

-Reqst
  Type

  Type "Select one:"

  Read (A)dd, (D)isplay a record? %0
  if %0/ = / then exit
  type
  goto -Cmd.%0       |* goto routine to handle request

-Cmd.A

  Read.parsed Enter data to be saved: %A

  if %A/ = / then goto -reqst

  >>%N               |* append to write (not create)
  seek(W,(%I * 80))  |* seek to next available record
  type (%A $ 1 78)   |* write 78 chars + CR/LF into rec
  >                  |* close file
  goto -show

-Cmd.D
 If %I < 1 then type "No records have been stored yet!"
    Then Goto -reqst
 Type "Record numbers 1 to" %I "are available."
 Read Which record to display? %A
 if %A/ = / goto -reqst

 <%N                      |* open to read file
 seek( R, (%A - 1 * 80) ) |* go to requested record
 read.parsed %0
 color('High-Intensity')
 type %0                  |* show entire line of data
 color('Normal')
 <                        |* and close file
 goto -Reqst

-Cmd.%0 goto -reqst       |* invalid request comes here

-on.error-                |* errors come here
 If %R = 33 then skip 1

 If %R <> 32 then goto -err2  |* on file not found:

    Type "Creating new database..."
    >%N                   |* create empty file
    >                     |*    (1st time only)
    Resume (%L-1)         |* return to open error
-err2
 Type "Unexpected error" %R "in line" %L
 Exit

TIME( {type} )

This function returns a character string representing the system time. In the case of the TIME() function without a type, the time returned will be in the default 24-hour clock format 'hh:mm:ss'. For example, it might be '04:41:37'.

It is also possible to obtain other formats by using the type operand. Type is a single character used to indicate the type of alternate format desired. The possible formats are:

C - (Civil) This returns the time in the format 'hh:mmxx'. The hours range from 1 to 12, and the minute the values 00 to 59. Following the minutes are the letters "am" or "pm". The "am" indicates times in the morning starting from 12:00am midnight, and "pm" indicates times in the afternoon starting from 12:00pm noon. The hours will not have leading zeros or blanks.

H - (Hours) This returns the number of hours, since midnight, in the format 'hh'. The hours will not have leading zeros or blanks.

L - (Long) This returns the time in the format 'hh:mm:ss.uu'. In this case uu is the fraction of seconds in a 10 millisecond resolution.

M - (Minutes) This returns the number of minutes, since midnight, in the format 'mmmm'. The minutes will not have leading zeros or blanks.

N - (Normal) This returns the default 24-hour clock format 'hh:mm:ss'. For example, it might be '04:41:37'.

S - (Seconds) This returns the number of seconds, since midnight, in the format 'sssss'. The seconds will not have leading zeros.

n - ('n' second Timer) This returns a false (zero) result until 'n' seconds have passed. Once started, the timeout length cannot be changed. When the time has passed, it will return a true (non-zero) result and a new timer can then be started. The value 'n' is the integer amount of seconds, independent of CPU speed. Only one timer can be in operation at any moment.

Because TIME() and TIME( type ) are functions, they can be used anywhere other values can be used. For example, in an expression, an IF or TYPE statement, and so on.

    BAT * TIME() examples

    TYPE This example started at TIME() on DATE()
    BEGTYPE

     --Format-------Usage---------Example--

     Normal    :  TIME()     :  \( TIME()        )

     Normal    :  TIME( N )  :  \( TIME( N )     )

     Civil     :  TIME( C )  :  \( TIME( C )     )

     Long      :  TIME( L )  :  \( TIME( L )     )

     Hours     :  TIME( H )  : \(" " & TIME( H ) )

     Minutes   :  TIME( M )  : \(" " & TIME( M ) )

     Seconds   :  TIME( S )  : \(" " & TIME( S ) )

     Timer     :  TIME( 4 )  :  ;

    END
    WAIT UNTIL TIME(4)
    TYPE "Done!"

Prints the result:

     This example started at 01:32:09 on 25 Mar 1995


     --Format-------Usage---------Example--

     Normal    :  TIME()     :  01:29:14

     Normal    :  TIME( N )  :  01:29:14

     Civil     :  TIME( C )  :  1:29am

     Long      :  TIME( L )  :  01:29:14.41

     Hours     :  TIME( H )  :  1

     Minutes   :  TIME( M )  :  89

     Seconds   :  TIME( S )  :   5354

     Timer     :  TIME( 4 )  :  Done!

EBL/CONTROL Functions

The EBL Control Functions determine the status of EBL and the functions being used. Like other functions, they can be used anywhere other values or expressions are used. For example, in an assignment statement, an IF or TYPE statement, etc.

NOT( expression )

The NOT() function reverses the results of true/false expressions. This is useful in IF statements that use an expression or function to determine the next direction.

    BAT * NOT() example
    %F = 'TEST.FIL'
    IF NOT( EXIST( %F )) THEN
    BEGIN
        TYPE "File" %F "does not exist..."
        EXIT
    END
    <%F
    READ.PARSED %0
    <

    TYPE "File exists and contains:" %0

TRACE( type )

As an aid in debugging, the TRACE() function enables a trace flag which causes various types of information to be displayed as the EBL program executes.

The various types of traces are listed below. Only one can be active at a time. Just the first letter of the trace type is recognized. As a result, TRACE(R) and TRACE(Results) will perform the same trace.

These traces are listed from the most quiet to the most verbose. When a more verbose level is active, all less verbose results are also shown. For example, TRACE(R) shows results, all EBL statements, and DOS commands.

-Trace Type-  -Meaning-           -Trace Symbols-
   blank       Tracing off         none
   O           Tracing Off         none
   C           DOS Commands        none
   A           All statements      *-*
   R           Results             *-*, >>>
   I           Intermediates       *-*, >>>, >F>,
                                   >E>, >V>, >L>

The default trace type is TRACE(). This will not show any DOS commands or applications that execute. To make DOS commands show on the screen as they start, use TRACE(C). This is the equivalent of ECHO ON in DOS batch files.

A symbol will precede the diagnostic information to identify its source. On a color display, the trace will also appear with green characters on black, while actual results from the program will appear white on black. The meaning of the various trace symbols are:

  -Symbol-      -Indicates-
    *-*          EBL Source line in program
    >>>          Result assigned to a variable
    >F>          Result within a Function call
    >E>          Result within an Expression
    >V>          Value outside of expression
    >L>          Literal outside of expression

For debug purposes, the TRACE(R) setting is recommended. This will display the program source and results of assignments as the EBL program executes.

To set up a trace without changing the EBL program under test, you may want to use the BAT environment variable in DOS. The contents of this variable is executed before any EBL program starts. For example, to do a result trace for any batch file, in DOS type:

    SET BAT=TRACE(R)

The TRACE(I) setting is interesting, although usually too complex for most purposes. If an error occurs while tracing, expect some residual results with TRACE(I) while EBL is looking for the -ON.ERROR- label.

    BAT * TRACE() example.
        TRACE(Result)
        %I = 2
    -Loop %I -= 1
        IF %I <> 0 GOTO -Loop
        TRACE(Off)
        TYPE "This is the end of the program"
        EXIT

When executed, this EBL program produces:

     *-* %I = 2
     >>>   "2"
     *-* -Loop %I -= 1
     >>>   "1"
     *-* IF %I <> 0 GOTO -Loop
     *-* -Loop %I -= 1
     >>>   "0"
     *-* IF %I <> 0 GOTO -Loop
     *-* TRACE(Off)
     This is the end of the program

VERSION()

This function returns information describing the language level and the release date of this level. It consists of five words separated by blanks. For example

    VERSION()  ==  "EBL 4.08 30 Jul 1995"   (Perhaps)

The components of the result are

1. A word describing the language. The first three letters will always be "EBL" and any remainder may be used in the future to identify particular variations of the language.
2. The version of EBL currently running. The base version number reported with EBL Plus is 4.00. The revision you have will likely be higher than this. For example "4.08".
3. The final three words are part of the release date for this version. It is the same format as the DATE() function described previously. For example "30 Jul 1995".

   Note that this function can be combined with the PARSE command to separate the various components for easy usage.

   EBL Versions prior to 3.08a did not have this function. If the first three letters of the result do not equal "EBL", then you can be assured that it is an early version of EBL.

       BAT * VERSION() example...
   
   
       TYPE "Current EBL version ID is:" VERSION()
   
   
       *
   
       * Now break it into parts:
   
       *  %A  - EBL Type
       *  %B  - Version number
       *  %C  - Release date
       *
       PARSE VERSION() %A %B %C
   
       IF %B < 3.08 THEN
       BEGIN
          TYPE  "Sorry, you must use the latest"
          TYPE  "EBL version for all these new "
          TYPE  "advanced features!            "
       END
   
       * Now test to see if this EBL is old!
       If WORD(VERSION(),1) is not "EBL"
          THEN TYPE "This is an old EBL version!"
       EXIT
   

   WHATFUNC()
   This command should be built into all function packages to identify what is loaded and available. This function is special in that all external function package ID's will be appended together. Each ID name will be separated by a single space. From this result you can determine the order the functions were loaded, the number of external functions available, the names of each package, and the functions associated with them.

   The ID names for the set of external functions provided by Seaware are:

   
       Program Name            ID Name
       BATMATH3.COM            BATMATH3
       BMATH87.COM             BATMATH87
       Built into EBL          BATFUNC1.BATFUNC2
   

   As these functions are modified or added to, additional ID names can be expected. If you, or others, write external functions, the WHATFUNC() function should be supported and an ID name given to help distinguish it from others.

   For example, with two sets of external functions loaded, the command "BAT TYPE WHATFUNC()" might display "BATFUNC1 EVA.UTILS". This shows that two function packages are loaded. Furthermore, "BATFUNC1" was located first and "EVA.UTILS" was located second. If the same function name was used in both packages, (for instance if both had a LOCATE function) only the function within "BATFUNC1" would be used because of the order. External functions located first have a higher priority.

   If you use the WHATFUNC() function and get back just the string "WHATFUNC()", then no external functions are loaded at all.

   Note to implementers of external functions: Refer to the examples provided on the distribution diskette to understand how to properly write the WHATFUNC() function. Following this guide will help make your external function compatible with packages of functions that others may write.

    BAT * WHATFUNC() example
   
    * This gets all function ID's present
       %A = WHATFUNC()
   
    * This tests to see if a specific package is loaded.
       If ( %a ? BATFUNC ) Then
          Then Type "Seaware's Functions are present!"
          Else Type "Seaware's Functions are NOT present!"
   
   
    * Note: If in following test we completely spell out
   
    *       whatfunc() name, we will always match and get
    *       the wrong answer!
       If ( %A ? whatfunc ) Then
          Then Type "NO Functions are present at all!"
   
    * This splits up and displays all function ID names
   
       Type "ALL External Functions present are:"
   
   
    Repeat with %I = 1 to 999  |* show each word available
       If Word(%A,%I) is '' then Exit Repeat
       Type Word(%A,%I)        |* Show the package name
    End Repeat
   

EBL OPTIONS

All EBL options have default values. These have been chosen for compatibility with previous EBL and for ease of use. Using these options may change how your EBL program is written.

Summary:


  /A                 - Any DOS
  /K                 - Kill (remove) from memory
  /N                 - No Logo
  /R [filename]      - Run new file
  /W                 - DesqView/MS Windows support
  /C                 - Clear BATXV Extended variables

  BIOS, RAM, or ANSI - display speeds

The EBL display speed defaults to the BIOS option. In addition, other options are available that control compatibility with older versions of EBL. The defaults for them are /NEW, /P, /Q, /S, and /U-. These are discussed in further detail in Appendix F Updating programs for EBL Plus.

/A - Any DOS

This option ignores DOS version checking, but must be used with caution. This option must be used together with the /R option as in:

 BAT /A /R PROGRAM.BAT

to startup the batch file named PROGRAM. This will allow EBL to work under many DOS enhancers like 4DOS and DR-DOS. Refer to the /R (run) option for some restrictions to observe.

DEFAULT: MS-DOS versions 2.0 to 6.x are supported.

/K - KILL

This option removes Extended Batch Language-Plus from memory. Vectors are restored and memory is returned to DOS. Note, if another program is installed after EBL, which uses the same interrupts, it will not be possible to remove EBL. If another program was made resident after EBL, and EBL is later killed, a hole in memory will result. In some cases, this hole may not be tolerated by DOS and may cause DOS to hang. Therefore, the use of /K is recommended only if EBL is loaded last in memory.

Note, in DOS 3.x to DOS 5.x the storage area for the variables %0 to %9 always requires expansion. This memory is added when EBL is initialized but cannot be removed when /K is used. Because of this, repeated start/kill attempts will gradually cause memory to be completely used up. This will eventually lead to the DOS error "Program too big to fit in memory". You should, therefore, not use the /K option excessively during the day.

If /K is used while a batch file is running, EBL will be removed from memory, and control will be passed to DOS to look at the next line of the batch file. If a later EBL command is in the same batch file, EBL will need to reload the resident stack area into memory again before execution can continue. Although reloading EBL is automatic, the process slows down batch file execution and is not recommended for conventional programs. If you simply want to stop EBL from processing the remainder of a batch file, use the LEAVE statement.

The /K option can also be used with any other EBL extensions that become resident. For example BATXV, BATMATH, and other programs from Seaware.

DEFAULT: Resident portions of EBL are kept in memory.

/N - No Logo

Normally during booting, EBL takes a portion of memory to use for the keyboard stack and global variables. After this memory is set, a Logo for Seaware is displayed showing the terms and conditions for using the program. This same Logo is displayed when the quick help is requested by typing "BAT" at the DOS prompt.

In both cases, by putting the /N (No Logo) option immediately following the "BAT" keyword, the Logo is suppressed.

DEFAULT: Logo is displayed.

 BAT /N * 1024
 BEGTYPE

 If in an Autoexec.BAT file, this initial line would:

  1) Bypass the Seaware logo.
        (/N)
  2) Setup a keyboard stack size of 1024 characters.
        (* 1024)
 END

/R filename - RUN

Loads and runs filename as an EBL batch file. The batch file will be brought into memory, replacing any other batch files already in storage. EBL will then begin execution at the first line of the file. EBL will execute the entire batch file on its own, while DOS is unaware that a batch file is running. Note that by using this command, EBL does not need DOS's assistance for locating and reading the batch file. As a result, this allows EBL to operate under a wider number of system "environments" like DesqView.

Use the /R option when starting batch files from these environments. The specific command to start the batch file XYZ from DesqView would be "BAT /R XYZ.BAT". In this mode, the entire batch file is interpreted by EBL instead of DOS. DOS is not aware that any batch file is running. Because of this, "environments" that are not normally able to start batch files will still run with this mode.

Also in this mode, the /S option is forced on so that all DOS commands are "shelled", and EBL remains in memory to continue executing other commands. CAUTION: You should not attempt to use the /L option or LEAVE command since it will cause the batch file to prematurely terminate at that point. This is because DOS is not able to locate any commands past LEAVE since it doesn't know that a batch file is running. Use the SHELL command (not LEAVE) to execute other DOS commands. If you want to stop batch file execution use the EXIT command.

/R is a required option when invoking EBL programs from within TopView. Note that EBL must have been initialized before TopView is started in order for EBL to work properly. For more information, refer to the appendix "Special Installation Steps" to understand how to use EBL with TopView. If this option is used with others, it must be the last one on the command line. All other options after 'filename' are ignored.

Note that this option is useful if you want to start one batch file from within another batch file. If you are in the first batch file, you can "call" the second batch file with the command "BAT SHELL BAT /R Second.BAT". When the second batch file terminates, it will "return" to the statement after the SHELL command in the first batch file.

For example

    BAT /R BATDEMO.BAT

Typing this command from DOS will start the batch file BATDEMO.BAT. Putting this command within "Start A Program" within TopView will have the same effect.

/W - WINDOW Usage

The option /W is available if running in a DesqView compatible window environment (MS Windows, TopView, etc). This option looks up the 'virtual screen' address for these environments and uses it instead of the physical screen. When combined with the RAM option, it allows the TYPE and BEGTYPE commands to be used within windows at high speeds.

The /W option should not be used outside of these environments as it may cause a system hang.

DEFAULT: Direct screen access (Non-window addressing)

BAT * DesqView & MS Windows option example

  RAM
  LOCATE 1 1

  TYPE "Screen line 1: This is outside all windows"


  /W  RAM
  LOCATE 1 2

  TYPE "Window line 2: This is inside of the window"

Note that the LOCATE command positions the text either to the top of the screen (with RAM) or the top of the window (with /W RAM).

/C - Clear BATXV Extended Variables

This option will clear all extended variables (for example &NAME) from BATXV storage. This option can only be used with BATXV. For example

    BATXV /C

This option is useful whenever a new program is starting. This way, extended variables from the previous program will not take space needed by the new application.

RAM or BIOS or ANSI - SCREEN SPEEDS

When the RAM option is used, all text sent to the displayed is sent directly to the video RAM of the active display. This mode of operation will speed up any text that is sent to the display. The RAM option also supports the VGA and EGA modes that have up to 43 lines. Because some computers are not 100% compatible with the IBM video RAM, this option might not always work. If this happens, just stay with the BIOS or ANSI modes instead. This is the fastest possible method of writing to the display.

Because of the requirement to share the display with other programs, BIOS will always be used for scrolling even when using the RAM option. It will also be used at the end of TYPE, BEGTYPE, and CLS commands to update the cursor position. Therefore, the highest speed improvements will be noticed only when displaying large blocks of text (such as with BEGTYPE) when the cursor is near the top of the display (such as after a CLS command). Note also that only text modes of the display are supported with the RAM option. Graphic modes on the display will always use BIOS.

The BIOS option is the default method of writing to the display with EBL. This provides for a medium speed interface to the display while being compatible with a wide variety of computers. As the name implies, only ROM BIOS is used to write to the display. There is no direct access to the display hardware in this mode.

The ANSI option should be used when you want to write to the display only through DOS instead of either BIOS or RAM. The ANSI.SYS device driver color commands will automatically be created when needed. If there is a need for screen I/O via DOS, use this ANSI command before any TYPE or BEGTYPE commands. You may need to use ANSI on MS-DOS compatible computers that are not BIOS or RAM compatible. This is the slowest possible method of writing to the display, but provides the widest compatibility offering.

The ANSI option will not only use DOS for all display I/O, but will also create ANSI.SYS escape sequences. The escape sequences are created for the CLS, COLOR, BEGTYPE, and LOCATE commands. Colors are "rounded" to the closest ANSI compatible color. Other plain text for the screen will be sent to DOS. Although this mode is slower than the BIOS or RAM options, it allows EBL to operate with ANSI.SYS enhancers like FANSI.

DEFAULT: BIOS

    BAT * RAM and BIOS option example
    RAM CLS
    COLOR White
    BEGTYPE
     This text appears on the display
     by writing directly to the video
     RAM..... very fast!

    END
    BIOS
    COLOR Yellow
    BEGTYPE

     This text appears on the display
     by writing to BIOS. Many IBM
     compatibles can do this...
     ...... medium speed!

    END
    ANSI
    COLOR LMagenta
    BEGTYPE

     This text appears on the display
     by writing to DOS. All MS-DOS
     compatible computers should be
     able to do this.... but slow!

    end
    COLOR Normal

THE KEYBOARD STACK

There is a method within the EBL Plus® language for answering questions from programs without operator intervention. This is done by the use of a "keyboard stack". By putting keystrokes into the stack, the system will act as if you had automatically typed on the keyboard when a program requests input. In this way, a batch file can now answer questions that programs may have asked by 'typing' them on the user's behalf.

Stack Operation

This step will reserve a small area of memory for three things:

1. 1024 (default) characters for the keyboard stack.
2. Space for all global EBL variables (%A to %O).
3. Space for CALL/RETURN linkage.

The keyboard stack normally operates in a "First In, First Out" (FIFO) basis. That is, the first line of text put into the stack will be the first seen by the program. The second line entered will be the second seen by the program, and so on. As long as there are keystrokes remaining on the stack, all requests for data from the keyboard will come from the EBL stack. Once the program empties the stack, keystrokes will then come from the keyboard as usual.

Note that by using the STACK.LIFO statement, the stack will operate in a "Last In, First Out" (LIFO) basis. That is, the first line of text put into the stack will be the last seen by the program. The second line entered will be the next from the last seen by the program, and so on. If the second line is the last one entered, it will be the first one out.

Since the stack simulates the keyboard operation, normal keyboard entries will not be seen by the application until the stack is empty. If the user has typed ahead of the program, these keys will not affect the stack data in any way. These keystrokes will remain in the existing 15 character buffer maintained by BIOS. When the stack is empty, characters will be drawn from BIOS's keyboard buffer.

Let's try an example. If you type the following line from DOS:

    C>BAT STACK  REM HELLO 

    C>REM HELLO
    C>

The above EBL command is an immediate mode command. EBL exits immediately after this command is completed. In this statement, EBL puts the first text "REM HELLO" into the keyboard stack. Before the user has a chance to type a response from the keyboard, the second "REM HELLO" appears. This DOS remark statement comes from the output of the keyboard stack. Here, DOS will ignore the remark command. The final DOS prompt "C>" appears and will wait for a keyboard entry from the user. It will wait since the keyboard stack is now empty of any previous characters.

Notice the order of the STACK command in relation to the program that receives input. The STACK command is given first in preparation for keyboard input from a program. The program is executed second after the STACK or BEGSTACK command. The program will then look for keyboard input and actually get it from the keyboard stack.

By following this sequence you will gain automatic control of applications. Do not attempt to put the name of the program within the STACK or BEGSTACK commands. Doing that will allow DOS the chance to read the keyboard stack before your program. As a result, your program would not run automatically from the keyboard stack. The following examples illustrate this:

GOOD:


   Bat * Stack commands in correct order...
       STACK 1     |* select option 1 in lotus menu
       LOTUS
       * First, LOTUS gets the "1" command
       * Second, when LOTUS exits, it returns to
       *  the batch file. DOS gets nothing from stack


BAD:


   Bat * Commands in stack in wrong order...
       STACK 1     |* select option 1 in Lotus menu
       STACK LOTUS
       * First, DOS gets the "1" command (error)
       * Second, DOS gets the "LOTUS" command
       * LOTUS gets nothing from stack

Notice that any program can be reading data from the stack. This includes not only DOS, but BASIC, other applications, and even other EBL batch files. Because of this, the stack is potentially very powerful. An EBL program is able to determine all of the parameters required to control a program, put them on the stack, and then transfer control to that application.

Refer to the detailed descriptions on the STACK, STACK.LIFO, and BEGSTACK commands for further details and examples about the stack.

Stack Control

STACK.OFF     - Redirects data to come directly
                from the physical keyboard. Does
                not remove any data in the stack.

STACK.ON      - Directs data to come from the
                stack. This is the default.

STACK.PURGE   - Removes any data from the stack
                and keyboard buffers which are
                pending.

Each of these control functions will be described in detail later in this document. In addition, there are some examples on the use of the stack in the appendix.

Stack Size

When you use EBL for the first time, it reserves a small amount of memory permanently for its own use. At that time, the amount of memory that EBL reserves for its keyboard stack can be selected. The default amount of space, 1024 characters, can be changed by having the first command to EBL be of the form:

    BAT * [size]

This statement, which is normally a comment, will tell EBL how much memory to set aside for the stack. The size is the number of characters to reserve. This number is decimal and is in the range of 0 to 65535. Note that EBL will limit this size to the available memory. Because of this, the amount of memory requested and the amount reported may not always match. This statement will only be used when the resident portion of EBL is installed, which would be the first time you use EBL after doing a system reset. At all other times, EBL treats this statement as a comment. For example:

AUTOEXEC.BAT contains:

    BAT * 2048
    BAT TYPE The above statement has
    BAT TYPE changed the amount of memory
    BAT TYPE reserved to the keyboard stack
    BAT TYPE for the EBL program now running.

Seen on the display after a system reset:

     A> BAT * 2048

     EXTENDED BATCH LANGUAGE - PLUS (tm) version 1.00
                                           installed.
     Stack size = 2048
     Batch file is being restarted.

     A> BAT * 2048
     The above statement has
     changed the amount of memory
     reserved to the keyboard stack
     for the EBL program now running.

Inline stack code

The executable code must be preassembled and the hexadecimal machine code must be placed in the stack using BEGSTACK. The prefix within BEGSTACK is \F0\02\ss\cc\cc\cc ... \cc\C3; where ss is the size of the code bytes in hexadecimal (0 to FF bytes) and cc is the hexadecimal value of each byte to execute. The suffix \C3; must also be added. C3 is a near RET instruction and the ';' prevents an implied Enter key from being stacked.

The registers AX, BX, CX, DX, and SI will be saved prior to execution and can be used freely as temporary storage. The DS register will be the same as CS. On entry to the inline code, AH=0 if the application is requesting a keystroke, and AH=1 if requesting keyboard status (refer to BIOS Int 16h for more information). DS:SI will be set to the address (offset within the segment) of the inline code entry point. If SI is zero before returning, EBL will allow a single keystroke to be gotten from the hardware and the inline code will be reexecuted. In this case, other items on the keyboard stack will not be used until the inline code returns SI non-zero. The code must be fully relocatable without any absolute addresses. If any other registers are used, they must be saved and restored within the inline code.

Some examples:

The following will create a beep when executed within the stack.

BEGSTACK
\f0\02\06\b8\07\0e\cd\10\c3;
END

It is equivalent to the following assembly language code

        Mov     Ax,0E07h        ; B8 07 0E
        Int     10h             ; CD 10
        Ret                     ; C3

The following will page eject the LPT1 printer

BEGSTACK
\f0\02\08\ba\00\00\b0\0c\cd\17\c3;
END

and is equivalent to

        Mov     Dx,0            ; BA 00 00
        Mov     Al,0Ch          ; B0 0C
        Int     17h             ; CD 17
        Ret                     ; C3

The following automatically types the word 'ACCOUNT', then will allow 3 keystrokes to be manually entered, then the Enter key will be pressed after this.

BEGSTACK
ACCOUNT;
\f0\02\12\EB\02\04\00\80\FC\00;
\75\05\FF\4C\02\74\03\BE\00\00\C3;

END

and the inline code is equivalent to the following. This example demonstrates how local storage can be maintained for the inline code. It also shows how the stack can be stopped until specific events occur, in this case waiting for the application to request 3 keys.

    Jmp  short Me        ; Jump over local storage
    Dw   4               ; Define local counter

Me: Cmp  Ah,0            ; Did App request a key?

    Jne  Re              ; No, am counting just keys
    Dec  Word ptr [si+2] ; Decrement the count of keys
    Je   Dx              ; Count is over?

Re: Mov  Si,0            ; No, SI = 0 means restart

Dx: Ret                  ; Else continue & release stack

PROGRAMMING TIPS AND TECHNIQUES

Always Make First Line a Comment

Make the first line of your EBL program a comment. Also, after using the LEAVE command, use a comment on the statement that returns to EBL. This will cause DOS to print this line to the screen as the batch program loads. If this line is a comment, it can serve as a title to your program as the files are loading. You may also wish to include a version number in this title as well. If the EBL program is very large, this first line can serve as message to the operator that there will be a slight delay before execution.

    BAT * A comment starts on the 1st line
    Repeat Forever
      Read Which file to edit> %0
      EDLIN %0
    End Repeat

You should never use any variables or special characters on the first line, nor on an EBL statement immediately following the LEAVE command. Be cautious with the following conditions:

1. Lines that use any predefined variable (e.g. %V %R %% %Q)
2. Lines with assignment commands (e.g. %1 = XYZ)
3. Lines that use any global user variable (e.g. %A to %O)

These types of lines CANNOT be used on the first executable EBL line, nor the first EBL statement after a LEAVE command. This is because DOS will do substitutions for variables before EBL receives control of execution. Due to this, substitutions will not be properly done for any of the above conditions. If it is necessary to have one of those conditions, you may simply insert above a line containing only the word 'BAT'. This will cause BAT to be reloaded before executing the following line.

For example this is not legal

    BAT Type "BAD use of variables in" %0
     Leave
    DIR B:*.*
     BAT Type The current return code is %R

but this is legal because comments are used at the beginning of the EBL program, and at the first EBL statement after a LEAVE command:

    BAT * Comment Here Makes Next Statement Work..
     Type "OK use of variables in" %0
     Leave
    DIR B:*.*
     BAT * Always use a comment line to restart
     Type The current return code is %R

EBL Program Size

EBL programs of all sizes are supported. If, however, your EBL program is smaller than 65535 bytes, it will fit entirely into memory and execute quickly. If the EBL program is larger than 65535 bytes, then EBL is forced to read the program from the disk as it is being executed. This will slow down the speed of execution considerably. If it is necessary to have a large EBL program, try to split it into several pieces and have them communicate through the global user variables.

SKIPping

LOOPS

GOTO / CALLs within the EBL program

The execution speed of the GOTO and CALL commands has been dramatically improved compared with prior versions of EBL. The GOTO and CALL commands will save the destination of the jump when found. The memory offset of the destination label will be saved for the next use of this command. The GOTO or CALL command will then be altered (in memory only) to do a direct jump using this offset. Therefore, the destination label only requires one lookup within the batch file, the second time it goes directly to the label. This is a transparent way to dramatically speed up execution of these commands.

This applies to all GOTO or CALL commands as long as the batch file remains in memory. If excessive LEAVE commands are performed, even if invoked with the /L option, then performance will be degraded since the batch file must be removed from memory. Also, if the batch file is so large that it must be loaded on and off the disk during execution due to memory constraints, then performance will also suffer.

Therefore, if your batch file requires the highest possible performance, use the SHELL command or the /S option, and keep your batch files small enough so they can remain in memory (64K or less).

GOTOS to Other EBL Programs

    GOTO WORKDAY.BAT

will transfer control to the second batch file "WORKDAY.BAT". When the second batch file ends, it will return to DOS. Operands after the file name are transfered to the variables %0 to %9 for the second batch file. Also the global variables %A to %O are shared between all batch files and can also be used to pass information between them.

Unlike previous versions of EBL, you can not transfer control to another batch file just by using the filename without any GOTO command. With EBL Plus, this practice will create an implied SHELL which will be similar to a CALL command rather than a GOTO. Refer to Appendix F for other tips on migrating older programs to EBL Plus.

CALLs to Other EBL Programs

    CALL WORKDAY.BAT

This will call the second batch file "WORKDAY.BAT". When the second batch file exits, control will be returned to the statement after the CALL command.

Note that this type of CALL/RETURN between batch files is obviously slower than if it had been done entirely within the same file. Operands after the file name are transfered to the variables %0 to %9 for the second batch file. Also the global variables %A to %O are shared between all batch files and can also be used to pass information between them.

Read the sections about the /R and /S options as there are a few DOS commands (IF, FOR, and ECHO) that cannot be used in the second batch file. Almost all batch files will work, however.

Speeding up the SHELL Command

The SHELL command will use its first operand as a program name to execute, and all remaining operands will be passed to this program. For example "SHELL DW4 MYFILE" will start up the DW4 (Displaywrite 4) program, and give it the file MYFILE to edit. EBL will look for the DW4 program on the default subdirectory, for a DW4.COM program, then a DW4.EXE program. If not found, then EBL will load COMMAND.COM, and it, in turn, will try to run the DW4 program.

As you may see, if the DW4 program was in the current sub-directory, or if a path name had been given before DW4, then this program would have been quickly found and executed. For instance, if it was in the "edit" sub-directory, then it would have been better to use "SHELL \EDIT\DW4 MYFILE" to reduce the search time. In addition, since COMMAND.COM would not have been required, overall memory usage would have been smaller.

In general, it is better to use SHELL instead of LEAVE as EBL and its associated batch file will not have to reload from disk after each DOS command. Since SHELL uses the same mechanism to load programs as DOS, overall execution speed is improved. This is especially true when compared with conventional batch files that load programs through DOS. Note, however, that there are a few DOS commands that will only work within batch files and not work with SHELL. Examples are IF, ECHO, and FOR. In general, if the command will work at the DOS prompt "A>", then it will also work with SHELL (memory permitting).

NO Multiple Commands in Immediate Mode

DOS Dependency

Minimizing the EBL Logo

    BAT /N

Other options can be combined after the /N option. For example:

 BAT /N * 1024
 Begtype

 If in an Autoexec.BAT file, this initial line would:

  1) Bypass the Seaware logo.
  2) Remove the requirement for the "BAT" prefix.
  3) Setup a keyboard stack size of 1024 characters.
 End

DOS Variables in AUTOEXEC.BAT

The following AUTOEXEC.BAT file will give bad results or hang:

    BAT * Starting EBL...
     %1 = ABC
     REM ABC Characters come out like %1

By restarting the file by hand, there won't be a problem. As a fix, you can have EBL restart it automatically by doing the following:

    BAT * Starting EBL...
     If %Q = K Stack Autoexec | Stack | Exit
     Stack.purge
     * Continue with original batch file
     %1 = ABC
     REM ABC Characters come out like %1

It turns out that DOS supplies invalid pointers to EBL for the %0-%9 variables only during an AUTOEXEC. The locations DOS supplies get overwritten by DOS during it's execution. In some systems, it will hang. Hopefully, next versions of DOS won't have this problem.

Improving Execution Performance

1. Use the RAM option if possible. This will make EBL write directly to the video RAM, bypassing BIOS.
2. Use the GOTO command instead of SKIP, especially when used for loops. Only use SKIP if you have a forward reference that is only executed once. Any labels used for loops should be put near the beginning of the batch file.
3. Use the SHELL command to execute other DOS commands or programs.
4. Specify the sub-directory path (if any) for the command executed by SHELL.
5. Limit the size of the batch file to less than 64KB. Going beyond that will force EBL to reference the batch file from diskette (disk) instead of memory.

Setting Return Codes

The following portion of a BASIC program can be used to set up a return code before it exits. EBL keeps the return code at address 0000:04FE which is reserved by DOS for inter-program communication.

        .
        .
2000 DEF SEG=0         'Point to user segment
2010 POKE &H04FE,&H2B  'Setup return code of 2B
2020 DEF SEG           'Restore basic's segment
2030 SYSTEM   'Return to DOS to do more batch file
        .
        .

When BASIC exits and batch processing resumes, EBL allows for a test on the return code to control processing. A sample batch file to check this result would be:

BASICA SETRC
BAT * Return code tester
   IF %R = 2B TYPE "The program ended with an error!"
   IF %R = 0  TYPE "You had a normal exit! **"

EXAMPLES OF ADVANCED FEATURES

TELE - AN EXAMPLE USING "STACK"

EXAMPLE OF USE:


     A> TELE ED  555-9876


     ED ANDERSON :TELEPHONE NUMBER IS: 555-5678



     FRANK SMITH :TELEPHONE NUMBER IS: 555-9876




LISTING OF FILE "TELE.BAT" :



bat * TELE - A Telephone quick reference *
    IF .%1 <> . goto -fill.list
    BEGTYPE
 You did not enter a name or number to lookup
 Enter "TELE <name1> <name2> ... <name5>"
end

* If no more names, then exit
-fill.list IF .%1 = . EXIT

* This begins the telephone reference list
    BEGSTACK
555-9876 Frank Smith
555-6789 Eva Jones
555-5678 Ed Anderson
555-1234 Robert Henry
end

* Read the entire tel. list and
* hunt for person.
    /U
-read.list
    READ.PARSED %A
    IF %A ? %1 > 0 GOTO -print.entry
    IF %Q = S GOTO -read.list
    /U-
    Type %1 :Could not be found ;
    Type     in the telephone list!

-prep.4.next * Shift names to lookup
             *     next person.
    %1 = %2
    %2 = %3
    %3 = %4
    %4 = %5
    %5 =
    GOTO -fill.list

-print.entry * Print out the fact that
             *     I found one.
    /U-
    PARSE %A %A %B

    TYPE %B :Telephone number is: %A

    TYPE
    * Remove remainder of tele list

    *              for next search:

    STACK.PURGE
    GOTO -prep.4.next

TELE2 - AN EXAMPLE USING FILE I/O

EXAMPLE OF USE:


     A> TELE2 ED FRANK


     ED ANDERSON :TELEPHONE NUMBER IS: 555-5678



     FRANK SMITH :TELEPHONE NUMBER IS: 555-9876




LISTING OF FILE "TELE2.BAT" :


bat * TELE2 - Telephone quick reference for files
     IF .%1 <> . goto -fill.list
     BEGTYPE
 You did not enter a name or number to lookup
 Enter "TELE <name1> <name2> ... <name5>"

 This program references the file TELE.DIR
end

* If no more names, then exit
-fill.list IF .%1 = . EXIT

* This opens the telephone reference file
    <tele.dir

* Read the entire tel. list and
* hunt for person. Use /U option
* to ignore case while matching names.
    /U
-read.list
    READ.PARSED %A
    IF %A ? %1 > 0 GOTO -print.entry
    IF %A <> ^Z GOTO -read.list
    /U-
    Type %1 :Could not be found ;
    Type     in the telephone list!

-prep.4.next * Shift names to lookup
                |* next person.
    <           |* close file.
    %1 = %2
    %2 = %3
    %3 = %4
    %4 = %5
    %5 =
    GOTO -fill.list

-print.entry * Print out the fact that
             *     I found one.
    /U-
    PARSE %A %A %B

    TYPE %B :Telephone number is: %A

    TYPE
    GOTO -prep.4.next

-not32.error
    type Unexpected error %R in line %L
    exit

-on.error-
    if %R <> 32 then goto -not32.error
    begtype
The directory file TELE.DIR was not found.
Would you like to create a sample to try? (y/n) ;
end
    read %A
    if %A <> y then exit
    >TELE.DIR  |* open file
    BEGTYPE    |* This begins the sample list
555-9876 Frank Smith
555-6789 Eva Jones
555-5678 Ed Anderson
555-1234 Robert Henry
end
    >          |* close file
    cls type Sample phone list contains...
    leave
    type tele.dir

ASM - AN EXAMPLE USING "READSCRN"

(Due to page format limitations, this listing
has been compressed. Refer to the ASM.BAT
file on the diskette for clarity)


MASM %1,%1;
bat * Automatic test for any errors from
                                   above assembly
bat      READSCRN               |* skip return msg
                                   from DOS to BAT
bat -tst READSCRN %A %B         |* skip empty lines
                                   after MASM step
bat      IF .%A = . GOTO -tst   |* stop loop at 1st
                                   non-empty line.
bat      IF %A <> 0 BEEP TYPE|TYPE Assembly halting
                                   due to error|EXIT
bat      IF %B <> 0 BEEP TYPE|TYPE Assembly halting
                                   due to error|EXIT
LINK %1,%1,CON;
EXE2BIN %1 %1.COM

The above batch file assumes that the user begins the batch file by typing something like: "ASM PROGNAME", with no file extension. Of course, a more elaborate check could be done to verify the parameter entry.

This EBL program uses READSCRN to read the number of warnings and errors generated from the assembly. Both must be 0 (zero) in order for the link step to begin. If either is not zero, the operator is beeped, an error message is displayed, and the batch file is execution is ended.

QT - AN EXAMPLE USING "PARSE"

Example of use:

    A> QT

    It's about twenty past four.

BAT * Query Time in natural English.

* Extract the hours, minutes, and seconds
*       from the time.


     PARSE time() %H:%M:%1


* Convert to an English sentence...
*
-Convert.time
     type "It's" ;                |* start building..
     if %M > 30 then %H += 1      |* towards an hour?
     if ( %M % 5 ) <> 0           |* about on minute?
        then type about ;
     %M -= ( %M % 5 )             |* find apx 5 mins
     %H += 0                      |* strip 0's fm hr
     if %H = 0
        then %H = 12              |* handle midnight.
     if %H > 12
        then %H -= 12             |* make it 12hr tim

     goto -min.%M                 |* multi-way goto

-min.0
-min.60 %M = 0                    | skip 11
-min.5  type "five past ;"        | skip 10
-min.10 type "ten past ;"         | skip 9
-min.15 type "quarter past ;"     | skip 8
-min.20 type "twenty past ;"      | skip 7
-min.25 type "twenty-five past ;" | skip 6
-min.30 type "half past ;"        | skip 5
-min.35 type "twenty-five till ;" | skip 4
-min.40 type "twenty till ;"      | skip 3
-min.45 type "quarter till ;"     | skip 2
-min.50 type "ten till ;"         | skip 1
-min.55 type "five till ;"

        %N = "one two three four five six seven "
        %N &= "eight nine ten eleven twelve"

-Select.Hour
        PARSE %N %0 %N            |* get hr name
        %H -= 1
        if %H <> 0 goto -Select.Hour

        type %0;                  |* show hr name
        if %M = 0
           then Type " o'clock;"  |* add if exact.
        type .
        exit

MESSAGES

In the event that an error recovery procedure is available by using the "-ON.ERROR-" label, no message will be displayed. Instead, execution will resume at this special label and it is the responsibility of the executing EBL program to print any warning messages to the operator.

Where a message number is indicated, the number will be reported in the return code variable %R. This may be tested in an error recovery routine to determine the nature of the error. If a message number is not listed below, the error will be considered unrecoverable, will always be displayed, and cause EBL to terminate the running program.

Foreign Messages

Extended Batch Language now supports full National Language Support (NLS). If you would like to see the EBL error messages in an alternate foreign language, you can use the BATERR environment variable in DOS. First, copy the desired language file from the EBL distribution diskette. The file name is the same as the language name. If the language is not found, the file ENGLISH.BAT contains all possible messages in English. It is public domain and may be translated. Contributions are appreciated and will be added to future EBL diskettes for others to use.

Before any batch file starts, from DOS set the BATERR variable to point to the language file. For example, if you have a Spanish message file, from the DOS prompt enter the following:

  SET BATERR=/R C:\SPANISH.BAT

This statement uses the /R option to transfer control to the alternate EBL program. Although this form is the most useful, any other valid EBL command is allowed here.

When an error occurs, EBL will first check to see if an -ON.ERROR- handler is available. If it does not exist, the command in the BATERR environment variable will be executed if it exists. Certain DOS and applications may show errors, that you may think are from EBL, however these can not be translated. Only the translation for EBL errors can be in the EBL batch program. EBL errors will be identified with a >>> preceding the error message.

Help with Error Messages - EHELP

No programmer has ever worked for long with a new language before getting an first error message. If you've already gotten several, don't worry, a full explanation of how to fix the problem is at your finger tips.

EHELP is a special EBL program that gives a full explanation about the last EBL error encountered. It contains most of the text below. It not only explains what the error message means, but often says what to do to fix the problem. The added advantage is that it is immediately available without having to fumble through the pages of this manual. We think you will find it valuable.

Be aware that certain DOS, and application errors, can show up that EHELP cannot give assistance on. Although some common DOS errors are in this manual, EHELP can only help with EBL errors. All EBL error messages have >>> before it. If you do not see this, refer to the DOS or application manuals for further assistance. Otherwise EHELP will be available to help with those occasional EBL messages.

For example, if you see an EBL error message that looks something like:

        >>> Label could not be found

then just ask EHELP for assistance:

        C> EHELP

If you would like to have help automatically appear, use the BATERR environment variable similar to the example above for foreign language help. In this case, provide the drive and path to the EHELP batch program.

  SET BATERR=/R C:\EHELP.BAT

If you have this set when an EBL error occurs, a full page description of the error plus possible remedies will appear.

Message description

EXTENDED BATCH LANGUAGE - PLUS installed. Stack size = xxx Immediate mode command must be re-entered.

This message indicates this is the first time EBL was used and the portions of EBL that need to remain resident in memory have been successfully installed. In this case, an immediate command was executed from DOS into EBL at the same time. Since the resident portions of EBL must be installed before commands may execute, the immediate command that was entered must be re-typed. The F3 (retrieve) key from DOS is useful for this purpose.

EXTENDED BATCH LANGUAGE - PLUS installed. Stack size = xxx Batch file is being restarted.

This message indicates this is the first time EBL was used and the portions of EBL that need to remain resident in memory have been successfully installed. In this case, however, a batch file was being executed. DOS will restart the batch file from the line that originally invoked EBL (usually the first line). This line from the batch file will only be executed once after the resident portion of EBL has been installed. Note that the stack size will be indicated as well. This size can be changed by having the first statement to EBL be of the form: BAT * [size]

Improper version of COMMAND.COM

This error is caused by an improper level of COMMAND.COM being used. There are certain parameters within DOS that must be accessed by EBL. Therefore, a check is made to determine which level of COMMAND.COM is loaded so the parameters pertaining to batch files can be correctly used. EBL will not operate with DOS 1.0 or 1.1 or versions of DOS above 5.x. DOS 2.x to DOS 5.x including OS/2 1.x will work properly and will not produce this message. Be sure that your COMMAND.COM is unaltered before using EBL.

Every attempt will be made to update Extended Batch Language as new DOS releases become available. Check with Seaware if you have a new DOS release that produces this message. An update might be available. The BAT-BBS is the quickest way to find out about updates.

You may also get this error when using the 4DOS replacement to COMMAND.COM. To use EBL with 4DOS, rename any EBL batch file .BAT to a new .EBL extension. Then before you use EBL, set up an "executable extension" with the command

 SET .EBL=d:\path\BAT.COM /A /R

Bad command or filename.

This is a DOS error message. It may occur because a DOS command was attempted within the batch file that did not exist within your system. If you believe it is available and the spelling is correct within the batch file, check that the PATH command for DOS in your AUTOEXEC.BAT file is correct. Refer to your DOS manual for more information about the PATH command.

This error may also occur if the Extended Batch Language keyword was unknown. In this case, EBL may have turned control over to DOS without knowing how to understand the statement in error. This may cause a long series of these error messages to follow. Look carefully at the first statement that was reported. This statement must not have contained one of the valid commands or control functions for EBL. Check the spelling of the command and be sure that there are blanks separating each operand in the command.

Another program is preventing access to resident EBL functions or you are mixing EBL versions! Erase old copy and reboot.

There is a portion of EBL which remains resident in memory that controls the keyboard stack and contains the global variables. This is accessed via the system interrupt mechanism so that EBL will co-exist with the widest number of other programs in a friendly way. This interrupt can no longer be accessed properly for one of two reasons.

The first reason is that there are two different active versions of EBL. One version was made resident in memory when your system initially booted, and a second version was attempted to be used while running the current batch file. To remedy this, erase the oldest version in your system and reboot.

The second reason for this error is that another resident program is interfering with, or altering the interrupt EBL is using. Although that other resident program may be faulty and poorly written, it is possible to move EBL's critical interrupt out of that program's way with the "SET BATINT=xx" statement during the initial boot process. See the appendix "Special Installation Steps" to understand this further.

(Message #3) Unrecognized EBL command.

The first keyword in the EBL statement was not one of the valid EBL commands or control functions. Check the spelling of the command and be sure there are blanks on either side of this command to ensure that it will be properly identified.

If you believe the unrecognized command is an external EBL function, the external functions may not have been installed. Just enter the name of the external functions from DOS to install them. The external functions supplied with EBL are BATXV, and BATMATH.

(Message #4) Invalid SKIP amount.

The command 'SKIP' must be followed by a decimal number. This number shows the number of lines to skip during execution. Either the number contained non-numeric characters, or the number was not present.

(Message #6) Label could not be found.

A valid label name was referenced from a GOTO or CALL. A search was made through the entire batch file for this label and was not found. Check the spelling of the label, and ensure that the label which is the destination of the transfer also has a '-' (minus) sign if an EBL label is used. If an external EBL program is used, it must be referenced without a '-' sign. For example:

GOTO -LABEL      will look for the EBL label  "-LABEL"
GOTO LABEL.BAT   will look for the file  "LABEL.BAT"

(Message #7) Bad number or improper condition.

In an expression, this error can occur when an arithmetic operator (such as +, -, *, or /) caused a value to be read as a numeric. However, if the value could not be properly converted to a number, this error will result.

In an IF command, this error can occur when a comparison could not be made. After the 'IF' command, three values are required. The first is an expression to check during the compare. The second must be one of the EBL relationships, for example '=' (equal). The third must be another expression for the comparison. If any of these three values are not found as expected, this error will result.

(Message #8) Variable name is missing or improper.

In a READ or INKEY command, a variable name was expected, but was not seen. A valid variable name is one which starts with a '%' (percent sign). Since these commands will cause the contents of the variable to be altered, only DOS variables (%0 to %9) or global user variables (%A to %O) are allowed. Any other variable is not allowed. READ and INKEY commands do not need a variable name as an operand, but if it does have an operand, then it must be a valid variable name. If no operand exists, this error will result.

This error can also be caused by trying to use a DOS variable (%0 to %9) in an immediate execution statement. These variables cannot be used in this way as DOS only allocates storage for variables when .BAT files are executing.

(Message #9) Assignment syntax error.

An assignment statement was detected since the statement started with a variable (eg. %1, %B, &Name, etc). However an equal sign '=' was expected after the variable but was not provided. Check the format of your statement, and make sure that there is a space between your variables and the equal sign. The statement "%B=5" is not valid, yet "%B = 5" is valid.

(Message #10) Internal error - report MSG 10.

This message should never appear. If it does, please report this error, the conditions under which it occurred, and if possible, a copy of the failing EBL program.

(Message #11) Out of memory in keyboard stack

The STACK or BEGSTACK commands were used to put data into the keyboard stack and there was no more space for your data. The default stack size is 1024 characters. Exceeding this value will result in this error. Your EBL program must be re-written to either simplify the data being sent to the stack, or run an application program which will remove some of this data. When this error occurs, the stack will be purged of it's data before returning to DOS.

The stack size can be changed during booting to be as high as 52k characters. See the section on special setup procedures to understand this further.

(Message #13) "Syntax error in Escape or Color value.".

The color name used may not be valid. Refer to Appendix F for valid combinations of colors and/or hex attributes.

Also, there may have been a '\' (backslash) character found in the text following a BEGSTACK or BEGTYPE command. The character(s) following must be either another '\' character, which will represent a single backslash being seen, or it must be a valid two digit hex number. Examples of valid hex numbers would be: \00 \F9 \0E.

In addition, a '%' (percent) after the backslash indicates that the contents of a variable should used. When this is done, if the contents is a two digit valid hex number, it will be used as an escape or color value. Otherwise, the contents will be directly displayed or put into the stack. For example if %A contained "0F", using "\%A" after a BEGTYPE command would treat 0F as a high intensity color value. If %A had just contained "F", using "\%A" would not have changed the color, but just would have printed out the "F" onto the display.

(Message #14) CALL is nested too deep. Limit is 31.

The CALL command was issued too many times without doing a RETURN command. Subroutines within EBL files can only be nested up to three times. If this is not the case, check for a missing RETURN command within your EBL program. Another possibility is that a stray CALL was executed. The TRACE.ON command may be useful for finding this problem within your EBL program.

(Message #15) RETURN did not have a matching CALL.

There were no CALL commands pending for the RETURN command to respond to. If a RETURN command was executed without a matching CALL command previously having been executed, then this error will result. Check how deep the subroutines within your EBL program are nested. Also check that your program did not accidentally enter a subroutine by making sure that there is an EXIT or GOTO command in front of the subroutine which directs program control around it. The TRACE.ON command may be useful for finding the problem within your EBL program.

(Message #16) String too long during READ or concat.

During the execution of a concatenation operator, the sum of the two strings exceeded 255 total characters. The string length can never exceed 255 characters in EBL.

If EBL was executing a READ command, data was being taken from the keyboard stack or a file (not the physical keyboard) and there was an overflow of the buffer allocated for the READ command. There can be a maximum of 250 characters, including the carriage return, for input during the READ command. This situation will not occur with input data from the physical keyboard since DOS will warn the user with a beep if the 250 character limit is exceeded.

This error may have been caused by STACKing an excessive number of lines without doing a carriage return. See the STACK command with the ";" (semicolon) option. Alternately, it could have also been caused by reading a file that had unusually long lines or files that were binary instead of ASCII text.

(Message #17) Numeric value out of range.

During the execution of an assignment statement, the result of an arithmetic operation was outside the range of +2⁶⁴ to -2⁶⁴-1. This error will also occur if a division by zero was attempted.

(Message #19) Out of memory for DOS variables.

When EBL was exiting and returning control back to DOS, the variables %0 to %9 could not be compressed into the 118 total character space available to them within DOS. If some of these variables are unused, you may wish to empty the variable before exiting to DOS. This error is unrecoverable. If it occurs, the batch file will stop.

(Message #20) Mismatched BEGIN/END or REPEAT/END group.

The BEGIN and END statements or REPEAT and END statements were not executed in pairs. Check your program to ensure both exist. If you have both statements, you may have attempted to use a GOTO or CALL command to enter or leave the group of statements between them. For example, do not use GOTO to break out of a REPEAT loop. Use EXIT REPEAT instead.

(Message #21) BEGIN/END or REPEAT/END is nested too deep. Limit is 8.

Too many BEGIN or REPEAT statements were executed without having reached its associated END statement. This results in overflowing the nesting level. This can occur if the program is too complex. It may also occur if a GOTO is used to prematurely exit from within these pairs. Instead of GOTO, use the EXIT REPEAT or NEXT REPEAT commands.

(Message #27) - Parenthesis is nested too deep. Limit is 5.

During an arithmetic or character string expression, too many parenthesis pairs were used to nest the operations. No more than 5 pairs of parenthesis are allowed. Simplify the expression by breaking it into parts between separate statements.

(Message #28) - Mismatched parenthesis.

During an arithmetic or character string expression, parenthesis were used to nest the operations. The parenthesis did not have balanced opening and closing pairs. You may need to add or delete a parenthesis. Also, ensure that the parenthesis were separated by blanks on both sides so that they are not confused with character strings in the expression.

(Message #29) - Mismatched quotes.

A string was found to begin with a starting quote, but did not have a matching ending quote. A blank is required before the first quote, and after the last quote. Ensure that blanks surround the string. Also, be sure that the same type of quotation mark is used at the beginning and end of the string. Either a single quote or double quote is valid, but they must be used in pairs and match. A string also cannot span more than one line.

(Message #30) - DOS error in accessing data.

DOS had an error in attempting to either read or write data to a file or device. In the case of devices, it could have been the display or keyboard. The specific cause of the error was unspecified by DOS. With DOS versions greater than 3.1, new DOS errors that are unknown to EBL, as of this writing, will appear as this error.

(Message #31) - DOS invalid function.

DOS was not able to read or write the file because the "function code" that EBL used to access the file did not match the available "function codes" that DOS knows to be usable. This error should never occur. It could only occur if there is an internal error within either EBL or DOS. In addition, other background programs (SideKick and print spoolers for example) could be accidentally altering memory in either EBL or DOS. Try removing all other background and multi-tasking programs and see if the error still occurs. If it does, please report the error to Seaware. Please send the version number of DOS you are using, your system configuration, and a copy of the failing EBL program. If the error goes away after removing a background program, please report this error to the company that provided the program.

(Message #32) - DOS file not found.

DOS was not able to open the requested file for reading because its name was not found in the directory. Check the name of the requested file. If it is correct and a path was not specified, the current subdirectory may not be the correct. You can use the "CHDIR" command in DOS or the "CHDIR( )" command in the extended EBL functions to alter the current subdirectory. If a path was specified in the file name, check the name given for correctness and make sure it matches with the subdirectories currently in use on your disk or diskette.

(Message #33) - DOS Path not found.

DOS was not able to find the requested path to the subdirectory specified. Check the name given for correctness and make sure it matches with the subdirectories currently in use on your disk or diskette.

(Message #34) - DOS Too many open files.

DOS was not able to open the requested file because too many other files were already open. This may occur in multi-tasking systems, or when a large number of resident applications are already loaded. Check the "FILES=xx" statement in the file \CONFIG.SYS. You may want to increase the number of files that DOS can open at once. Refer to the CONFIG.SYS configuration section in your DOS manual for more information.

(Message #35) - DOS access denied.

DOS was not able to open the requested file. This could be caused by trying to write to a file marked read only, or by trying to read from a subdirectory instead of a file. Check the file name that is being opened to ensure that it is correct.

In some networks, it could also be that the file is currently being used by another source. In this case, you may have to wait until the file is made available by that other source before accessing this file again.

(Message #36) - DOS invalid file handle.

DOS was not able to read or write the file because the "handle" that EBL used to access the file did not match the available "handles" that DOS knows to be usable. This error should never occur. It could only occur if there is an internal error within either EBL or DOS. In addition, other background programs (SideKick and print spoolers, for example) could be accidentally altering memory in either EBL or DOS. Try removing all other background and multi-tasking programs and see if the error still occurs. If it does, please report the error to Seaware. Please send the version number of DOS you are using, your system configuration, and a copy of the failing EBL program. If the error goes away after removing a background program, please report this error to the company that provides the program.

(Message #37) - DOS memory control blocks destroyed.

DOS was not able to use the control blocks that it maintains to keep multiple programs separated within memory. This may occur during the SHELL command in EBL. Under normal conditions, this error should never occur. It could only occur if there is an internal error within DOS. In addition, other background programs (SideKick and print spoolers, for example) could be accidentally altering memory in DOS. Try removing all other background and multi-tasking programs and see if the error still occurs. If it does, please report the error to Seaware. Please send the version number of DOS you are using, your system configuration, and a copy of the failing EBL program. If the error goes away after removing a background program, please report this error to the company that provides the program.

(Message #38) - DOS Insufficient memory.

There was not enough memory to perform the SHELL command properly. There must be enough free memory for EBL (about 20k), the executing batch file, and space for the new application being loaded. Typically this could total from 50k to 100k or more depending on the application being loaded. You can use the CHKDSK command in DOS to determine your amount of free memory.

(Message #39) - DOS invalid memory block address.

DOS was not able to use the control blocks that it maintains to keep multiple programs separated within memory. This may occur during the SHELL command in EBL. Under normal conditions, this error should never occur. It could only occur if there is an internal error within either EBL or DOS. In addition, other background programs (SideKick and print spoolers, for example) could be accidentally altering memory in either EBL or DOS. Try removing all other background and multi-tasking programs and see if the error still occurs. If it does, please report the error to Seaware. Please send the version number of DOS you are using, your system configuration, and a copy of the failing EBL program. If the error goes away after removing a background program, please report this error to the company that provides the program.

(Message #40) - DOS invalid environment.

DOS was not able to use the environment space while using the SHELL command. This error should never occur. It could only occur if there is an internal error within either EBL or DOS. In addition, other background programs (SideKick and print spoolers, for example) could be accidentally altering memory in either EBL or DOS. Try removing all other background and multi-tasking programs and see if the error still occurs. If it does, please report the error to Seaware. Please send the version number of DOS you are using, your system configuration, and a copy of the failing EBL program. If the error goes away after removing a background program, please report this error to the company that provides the program.

(Message #41) - DOS invalid format.

This error should never occur. It could only occur if there is an internal error within DOS. In addition, other background programs (SideKick and print spoolers, for example) could be accidentally altering memory in DOS. Try removing all other background and multi-tasking programs and see if the error still occurs. If it does, please report the error to Seaware. Please send the version number of DOS you are using, your system configuration, and a copy of the failing EBL program. If the error goes away after removing a background program, please report this error to the company that provides the program.

(Message #42) - DOS invalid access code.

This error should never occur. It could only occur if there is an internal error within DOS. In addition, other background programs (SideKick and print spoolers, for example) could be accidentally altering memory in DOS. Try removing all other background and multi-tasking programs and see if the error still occurs. If it does, please report the error to Seaware. Please send the version number of DOS you are using, your system configuration, and a copy of the failing EBL program. If the error goes away after removing a background program, please report this error to the company that provides the program.

(Message #43) - DOS devices are not same.

This error should never occur. It could only occur if there is an internal error within DOS. In addition, other background programs (SideKick and print spoolers, for example) could be accidentally altering memory in DOS. Try removing all other background and multi-tasking programs and see if the error still occurs. If it does, please report the error to Seaware. Please send the version number of DOS you are using, your system configuration, and a copy of the failing EBL program. If the error goes away after removing a background program, please report this error to the company that provides the program.

(Message #44) - DOS disk full.

While writing, DOS was not able to send the data to the device without getting errors. The usual reason is that the disk is full. The data has been truncated and is probably not usable. Change the media or erase unneeded files to make space, and try the operation once again.

(Message #45) - ColorChar is nested too deep. Limit is 8.

The characters that represent colors toggle the color on and off. If one color is being used when a second is turned on, the first will be saved. Normally, when the second is turned off, the first color is restored. If more than 8 colors are turned on without being turned off, this error will occur. Check that you have the colored character at both the beginning and end of the desired colored area.

(Message #46) - BATXV is needed since an extended variable was used.

An extended variable was used in the EBL program, however the storage for it was not yet loaded. First use the BATXV.COM program from DOS to setup a storage area for extended variables.

(Message #79) - Extended variable storage full.

The variable space within the BATXV.COM program has been filled. Space may be freed by setting an extended variable to null, or by using the "/C" option in the BATXV program to clear all variables from memory. Note that the default area in BATXV is 2000 bytes and may be extended when initially loaded. Remember to account for space for the variable contents plus, space for the variable names.

Summary of Error Messages:

Message Number      Message

-       EXTENDED BATCH LANGUAGE - PLUS installed.
           Stack size = xxx
           Immediate mode command must be re-entered.
-       EXTENDED BATCH LANGUAGE - PLUS installed.
           Stack size = xxx
           Batch file is being restarted.
-       Improper version of COMMAND.COM
-       Bad command or filename.
-       Another program is preventing access to resident
           EBL functions or you are mixing EBL versions!
           Erase old copy and reboot.
3       Unrecognized EBL command.
4       Invalid SKIP amount.
6       Label could not be found.
7       Bad number or improper condition.
8       Variable name is missing or improper.
9       Assignment syntax error.
10      Internal error - report MSG 10.
11      Out of memory in keyboard stack
12      Internal error - report MSG 12.
13      Syntax error in escape or color value.
           Use "\hex", or "\%Variable".
14      CALL is nested too deep. Limit is 31.
15      RETURN did not have a matching CALL.
16      Line too long during READ.
17      Numeric value out of range.
19      Out of memory for DOS variables.
20      Mismatched BEGIN/END group.
21      BEGIN/END is nested too deep. Limit is 8.
27      Parenthesis is nested too deep. Limit is 5.
28      Mismatched parenthesis.
29      Mismatched quotes.
30      DOS error in accessing data.
31      DOS invalid function.
32      DOS file not found.
33      DOS Path not found.
34      DOS Too many open files.
35      DOS access denied.
36      DOS invalid file handle.
37      DOS memory control blocks destroyed.
38      DOS Insufficient memory.
39      DOS invalid memory block address.
40      DOS invalid environment.
41      DOS invalid format.
42      DOS invalid access code.
43      DOS devices are not same.
44      DOS disk full.
45      ColorChar is nested too deep, limit is 8
46      BATXV is needed since an extended variable
           was used
79      Extended Variable storage full.

80     Closing parenthesis is missing.
81     Value out of range for function.
82     Path was not found.

83     Float Error: String cannot be converted to number

84     Float Error: More operators than available values

85     Float Error: Division by zero

86     Float Error: Invalid letters within expression

87     Float Error: Unbalanced expression

88     Float Error: Overflow within expression

89     Unexpected floating point error

EXTENDED KEYSTROKE CODES

The first column of this list is a cross reference between the keystroke that may be needed in an application, and its associated value to put on the stack in order to create this keystroke. The second column of this list is a cross reference between the key pressed and the actual value received from an INKEY command.

Note that the conventional ASCII values (hex 01 through FE) can be put on the stack by simply typing the character itself. As an alternative, the actual hex code of the character can also be put on the stack. For example, the following two cases both create the same result:

BAT BEGSTACK               BAT BEGSTACK
The first letter is A      The first letter is \41
END                        END

For special keys such as F1, a special hex value sequence is needed. This is because they are not part of the standard ASCII character set. For example, the F1 key is created by putting on the stack \00\3B. This is shown as:

BAT * STACK example (1)...
BEGSTACK

The F1 key is pressed when I reach: \00\3B

END

This can be simplified with the KEY() function as follows. The KEY() function does the necessary conversion and directly puts the key on the stack.

BAT * STACK example simplified (2)...

 STACK "The F1 key is pressed when I reach: ;"

 KEY('F1')

When special keys such as F1 are read via the INKEY command, a similar hex value will be returned. Again, this is because special keys like F1 have no ASCII representation. For example, the following case will display the hex value "KEY13B" when the F1 key is pressed. The KEY() function converts it back to the original name 'F1'.

BAT * Press a key to test...
    Inkey %0

    Type "Hex value from INKEY is:" %0

    Type "Real name from KEY() is:" KEY(%0)

The following table is a list of all special non-alphanumeric characters. By putting the special hex value on the stack, the required key can be simulated for your application. When testing for special keys from the INKEY command, use the "KEYxxx" value indicated below. You may also wish to consult the KEYTEST.BAT program on your EBL distribution diskette to display these values interactively.

KEY               Hex Value         Hex Value  
                 for BEGSTACK       from INKEY 
         ---Function Keys---
F1                 \00\3B             KEY13B
F2                 \00\3C             KEY13C
F3                 \00\3D             KEY13D
F4                 \00\3E             KEY13E
F5                 \00\3F             KEY13F
F6                 \00\40             KEY140
F7                 \00\41             KEY141
F8                 \00\42             KEY142
F9                 \00\43             KEY143
F10                \00\44             KEY144
F11                \00\85             KEY185
F12                \00\86             KEY186
SHIFT-F1           \00\54             KEY154
SHIFT-F2           \00\55             KEY155
SHIFT-F3           \00\56             KEY156
SHIFT-F4           \00\57             KEY157
SHIFT-F5           \00\58             KEY158
SHIFT-F6           \00\59             KEY159
SHIFT-F7           \00\5A             KEY15A
SHIFT-F8           \00\5B             KEY15B
SHIFT-F9           \00\5C             KEY15C
SHIFT-F10          \00\5D             KEY15D
SHIFT-F11          \00\87             KEY187
SHIFT-F12          \00\88             KEY188
CTRL-F1            \00\5E             KEY15E
CTRL-F2            \00\5F             KEY15F
CTRL-F3            \00\60             KEY160
CTRL-F4            \00\61             KEY161
CTRL-F5            \00\62             KEY162
CTRL-F6            \00\63             KEY163
CTRL-F7            \00\64             KEY164
CTRL-F8            \00\65             KEY165
CTRL-F9            \00\66             KEY166
CTRL-F10           \00\67             KEY167
CTRL-F11           \00\89             KEY189
CTRL-F12           \00\8A             KEY18A
ALT-F1             \00\68             KEY168
ALT-F2             \00\69             KEY169
ALT-F3             \00\6A             KEY16A
ALT-F4             \00\6B             KEY16B
ALT-F5             \00\6C             KEY16C
ALT-F6             \00\6D             KEY16D
ALT-F7             \00\6E             KEY16E
ALT-F8             \00\6F             KEY16F
ALT-F9             \00\70             KEY170
ALT-F10            \00\71             KEY171
ALT-F11            \00\8B             KEY18B
ALT-F12            \00\8C             KEY18C

KEY               Hex Value         Hex Value  
                 for BEGSTACK       from INKEY 

         --- Misc Types ---
ALT-0              \00\81             KEY181
ALT-1              \00\78             KEY178
ALT-2              \00\79             KEY179
ALT-3              \00\7A             KEY17A
ALT-4              \00\7B             KEY17B
ALT-5              \00\7C             KEY17C
ALT-6              \00\7D             KEY17D
ALT-7              \00\7E             KEY17E
ALT-8              \00\7F             KEY17F
ALT-9              \00\80             KEY180
ALT--              \00\82             KEY182
ALT-=              \00\83             KEY183
ALT-A              \00\1E             KEY11E
ALT-B              \00\30             KEY130
ALT-C              \00\2E             KEY12E
ALT-D              \00\20             KEY120
ALT-E              \00\12             KEY112
ALT-F              \00\21             KEY121
ALT-G              \00\22             KEY122
ALT-H              \00\23             KEY123
ALT-I              \00\17             KEY117
ALT-J              \00\24             KEY124
ALT-K              \00\25             KEY125
ALT-L              \00\26             KEY126
ALT-M              \00\32             KEY132
ALT-N              \00\31             KEY131
ALT-O              \00\18             KEY118
ALT-P              \00\19             KEY119
ALT-Q              \00\10             KEY110
ALT-R              \00\13             KEY113
ALT-S              \00\1F             KEY11F
ALT-T              \00\14             KEY114
ALT-U              \00\16             KEY116
ALT-V              \00\2F             KEY12F
ALT-W              \00\11             KEY111
ALT-X              \00\2D             KEY12D
ALT-Y              \00\15             KEY115
ALT-Z              \00\2C             KEY12C

CTRL--             \1F                KEY01F
CTRL-6             \1E                KEY01E
CTRL-A             \01                KEY001
CTRL-B             \02                KEY002
CTRL-C             \03                KEY003
CTRL-D             \04                KEY004
CTRL-E             \05                KEY005
CTRL-ENTER         \0A                KEY00A
CTRL-ESC           \1B                KEY01B
CTRL-F             \06                KEY006
CTRL-G             \07                KEY007
CTRL-H             \08                KEY008
CTRL-I             \09                KEY009
CTRL-J             \0A                KEY00A
CTRL-K             \0B                KEY00B
CTRL-L             \0C                KEY00C
CTRL-M             \0D                KEY00D
CTRL-N             \0E                KEY00E
CTRL-O             \0F                KEY00F
CTRL-P             \10                KEY010
CTRL-Q             \11                KEY011
CTRL-R             \12                KEY012
CTRL-S             \13                KEY013
CTRL-T             \14                KEY014
CTRL-U             \15                KEY015
CTRL-V             \16                KEY016
CTRL-W             \17                KEY017
CTRL-X             \18                KEY018
CTRL-Y             \19                KEY019
CTRL-Z             \1A                KEY01A
CTRL-[             \1B                KEY01B
CTRL-\             \1C                KEY01C
CTRL-]             \1D                KEY01D
CTRL-PRTSC         \00\72             KEY172
ESC                \1B                KEY01B


KEY               Hex Value         Hex Value  
                 for BEGSTACK       from INKEY 
         --- Editing Keys ---
BACKSPACE           \08               KEY008
CTRL-LEFT           \00\73            KEY173
CTRL-RIGHT          \00\74            KEY174
CTRL-END            \00\75            KEY175
CTRL-HOME           \00\77            KEY177
CTRL-PGDN           \00\76            KEY176
CTRL-PGUP           \00\84            KEY184
DOWN                \00\50            KEY150
LEFT                \00\4B            KEY14B
RIGHT               \00\4D            KEY14D
UP                  \00\48            KEY148
DEL (delete)        \00\53            KEY153
END                 \00\4F            KEY14F
ENTER               \0D               KEY00D
HOME                \00\47            KEY147
INS (insert)        \00\52            KEY152
NUL (break)         \00\03            KEY103
PGDN                \00\51            KEY151
PGUP                \00\49            KEY149
PRTSC               \F0\01              -
SHIFT-BACKSPACE     \08               KEY008
SHIFT-ENTER         \0D               KEY00D
SHIFT-ESC           \1B               KEY01B
SHIFT-TAB (backtab) \00\0F            KEY10F
TAB                 \09               KEY009

KEY               Hex Value         Hex Value  
                 for BEGSTACK       from INKEY 

COLOR REFERENCE

To display text in color, a special hex value is needed which represents the value of this color within the display's hardware. This also applies to special features of the monochrome display as well, such as reverse video. When the special hex value is used in the BEGTYPE command, the corresponding color will be displayed on the screen. For example to display part of a message highlighted, we might use:

BAT BEGTYPE
\71 WARNING \07 do I need to alert you any more?!
END

In the above example, two different colors are used, \71 and \07. From the table below with a color display, these mean to display the word "WARNING" as blue characters on white background. The remainder of the line is displayed as light grey on black. On a monochrome monitor, the word "WARNING" is displayed as underlined and the remaining words are normal.

The following table is a list of all special color values. By putting the special hex value in the BEGTYPE text, the required color can be seen on the display. Where noted, the symbol UL indicates Underline.

 Hex     Color                  Monochrome 

\00     Black   on Black        Non-Display
\01     Blue    on Black        Underline
\02     Green   on Black        Normal
\03     Cyan    on Black        Normal
\04     Red     on Black        Normal
\05     Magenta on Black        Normal
\06     Brown   on Black        Normal
\07    LGray    on Black        Normal
\08    DGray    on Black        Non-Display
\09    LBlue    on Black        High Intensity UL
\0A    LGreen   on Black        High Intensity
\0B    LCyan    on Black        High Intensity
\0C    LRed     on Black        High Intensity
\0D    LMagenta on Black        High Intensity
\0E     Yellow  on Black        High Intensity
\0F     White   on Black        High Intensity
\10     Black   on Blue         Normal
\11     Blue    on Blue         Underline
\12     Green   on Blue         Normal
\13     Cyan    on Blue         Normal
\14     Red     on Blue         Normal
\15     Magenta on Blue         Normal
\16     Brown   on Blue         Normal
\17    LGray    on Blue         Normal
\18    DGray    on Blue         High Intensity
\19    LBlue    on Blue         High Intensity UL
\1A    LGreen   on Blue         High Intensity
\1B    LCyan    on Blue         High Intensity
\1C    LRed     on Blue         High Intensity
\1D    LMagenta on Blue         High Intensity
\1E     Yellow  on Blue         High Intensity
\1F     White   on Blue         High Intensity
\20     Black   on Green        Normal
\21     Blue    on Green        Underline
\22     Green   on Green        Normal
\23     Cyan    on Green        Normal
\24     Red     on Green        Normal
\25     Magenta on Green        Normal
\26     Brown   on Green        Normal
\27    LGray    on Green        Normal
\28    DGray    on Green        High Intensity
\29    LBlue    on Green        High Intensity UL
\2A    LGreen   on Green        High Intensity
\2B    LCyan    on Green        High Intensity
\2C    LRed     on Green        High Intensity
\2D    LMagenta on Green        High Intensity
\2E     Yellow  on Green        High Intensity
\2F     White   on Green        High Intensity
\30     Black   on Cyan         Normal
\31     Blue    on Cyan         Underline
\32     Green   on Cyan         Normal
\33     Cyan    on Cyan         Normal
\34     Red     on Cyan         Normal
\35     Magenta on Cyan         Normal
\36     Brown   on Cyan         Normal
\37    LGray    on Cyan         Normal
\38    DGray    on Cyan         High Intensity
\39    LBlue    on Cyan         High Intensity UL
\3A    LGreen   on Cyan         High Intensity
\3B    LCyan    on Cyan         High Intensity
\3C    LRed     on Cyan         High Intensity
\3D    LMagenta on Cyan         High Intensity
\3E     Yellow  on Cyan         High Intensity
\3F     White   on Cyan         High Intensity
\40     Black   on Red          Normal
\41     Blue    on Red          Underline
\42     Green   on Red          Normal
\43     Cyan    on Red          Normal
\44     Red     on Red          Normal
\45     Magenta on Red          Normal
\46     Brown   on Red          Normal
\47    LGray    on Red          Normal
\48    DGray    on Red          High Intensity
\49    LBlue    on Red          High Intensity UL
\4A    LGreen   on Red          High Intensity
\4B    LCyan    on Red          High Intensity
\4C    LRed     on Red          High Intensity
\4D    LMagenta on Red          High Intensity
\4E     Yellow  on Red          High Intensity
\4F     White   on Red          High Intensity
\50     Black   on Magenta      Normal
\51     Blue    on Magenta      Underline
\52     Green   on Magenta      Normal
\53     Cyan    on Magenta      Normal
\54     Red     on Magenta      Normal
\55     Magenta on Magenta      Normal
\56     Brown   on Magenta      Normal
\57    LGray    on Magenta      Normal
\58    DGray    on Magenta      High Intensity
\59    LBlue    on Magenta      High Intensity UL
\5A    LGreen   on Magenta      High Intensity
\5B    LCyan    on Magenta      High Intensity
\5C    LRed     on Magenta      High Intensity
\5D    LMagenta on Magenta      High Intensity
\5E     Yellow  on Magenta      High Intensity
\5F     White   on Magenta      High Intensity
\60     Black   on Yellow       Normal
\61     Blue    on Yellow       Underline
\62     Green   on Yellow       Normal
\63     Cyan    on Yellow       Normal
\64     Red     on Yellow       Normal
\65     Magenta on Yellow       Normal
\66     Brown   on Yellow       Normal
\67    LGray    on Yellow       Normal
\68    DGray    on Yellow       High Intensity
\69    LBlue    on Yellow       High Intensity UL
\6A    LGreen   on Yellow       High Intensity
\6B    LCyan    on Yellow       High Intensity
\6C    LRed     on Yellow       High Intensity
\6D    LMagenta on Yellow       High Intensity
\6E     Yellow  on Yellow       High Intensity
\6F     White   on Yellow       High Intensity
\70     Black   on White        Reverse Video
\71     Blue    on White        Underline
\72     Green   on White        Normal
\73     Cyan    on White        Normal
\74     Red     on White        Normal
\75     Magenta on White        Normal
\76     Brown   on White        Normal
\77    LGray    on White        Normal
\78    DGray    on White        Reverse Video
\79    LBlue    on White        High Intensity UL
\7A    LGreen   on White        High Intensity
\7B    LCyan    on White        High Intensity
\7C    LRed     on White        High Intensity
\7D    LMagenta on White        High Intensity
\7E     Yellow  on White        High Intensity
\7F     White   on White        High Intensity

\80     Black   on Black        Non-Display
\81     Blue    on Black        Underline
\82     Green   on Black        Normal
\83     Cyan    on Black        Normal
\84     Red     on Black        Normal
\85     Magenta on Black        Normal
\86     Brown   on Black        Normal
\87    LGray    on Black        Normal
\88    DGray    on Black        Non-Display
\89    LBlue    on Black        High Intensity UL
\8A    LGreen   on Black        High Intensity
\8B    LCyan    on Black        High Intensity
\8C    LRed     on Black        High Intensity
\8D    LMagenta on Black        High Intensity
\8E     Yellow  on Black        High Intensity
\8F     White   on Black        High Intensity
\90     Black   on Blue         Normal
\91     Blue    on Blue         Underline
\92     Green   on Blue         Normal
\93     Cyan    on Blue         Normal
\94     Red     on Blue         Normal
\95     Magenta on Blue         Normal
\96     Brown   on Blue         Normal
\97    LGray    on Blue         Normal
\98    DGray    on Blue         High Intensity
\99    LBlue    on Blue         High Intensity UL
\9A    LGreen   on Blue         High Intensity
\9B    LCyan    on Blue         High Intensity
\9C    LRed     on Blue         High Intensity
\9D    LMagenta on Blue         High Intensity
\9E     Yellow  on Blue         High Intensity
\9F     White   on Blue         High Intensity
\A0     Black   on Green        Normal
\A1     Blue    on Green        Underline
\A2     Green   on Green        Normal
\A3     Cyan    on Green        Normal
\A4     Red     on Green        Normal
\A5     Magenta on Green        Normal
\A6     Brown   on Green        Normal
\A7    LGray    on Green        Normal
\A8    DGray    on Green        High Intensity
\A9    LBlue    on Green        High Intensity UL
\AA    LGreen   on Green        High Intensity
\AB    LCyan    on Green        High Intensity
\AC    LRed     on Green        High Intensity
\AD    LMagenta on Green        High Intensity
\AE     Yellow  on Green        High Intensity
\AF     White   on Green        High Intensity
\B0     Black   on Cyan         Normal
\B1     Blue    on Cyan         Underline
\B2     Green   on Cyan         Normal
\B3     Cyan    on Cyan         Normal
\B4     Red     on Cyan         Normal
\B5     Magenta on Cyan         Normal
\B6     Brown   on Cyan         Normal
\B7    LGray    on Cyan         Normal
\B8    DGray    on Cyan         High Intensity
\B9    LBlue    on Cyan         High Intensity UL
\BA    LGreen   on Cyan         High Intensity
\BB    LCyan    on Cyan         High Intensity
\BC    LRed     on Cyan         High Intensity
\BD    LMagenta on Cyan         High Intensity
\BE     Yellow  on Cyan         High Intensity
\BF     White   on Cyan         High Intensity
\C0     Black   on Red          Normal
\C1     Blue    on Red          Underline
\C2     Green   on Red          Normal
\C3     Cyan    on Red          Normal
\C4     Red     on Red          Normal
\C5     Magenta on Red          Normal
\C6     Brown   on Red          Normal
\C7    LGray    on Red          Normal
\C8    DGray    on Red          High Intensity
\C9    LBlue    on Red          High Intensity UL
\CA    LGreen   on Red          High Intensity
\CB    LCyan    on Red          High Intensity
\CC    LRed     on Red          High Intensity
\CD    LMagenta on Red          High Intensity
\CE     Yellow  on Red          High Intensity
\CF     White   on Red          High Intensity
\D0     Black   on Magenta      Normal
\D1     Blue    on Magenta      Underline
\D2     Green   on Magenta      Normal
\D3     Cyan    on Magenta      Normal
\D4     Red     on Magenta      Normal
\D5     Magenta on Magenta      Normal
\D6     Brown   on Magenta      Normal
\D7    LGray    on Magenta      Normal
\D8    DGray    on Magenta      High Intensity
\D9    LBlue    on Magenta      High Intensity UL
\DA    LGreen   on Magenta      High Intensity
\DB    LCyan    on Magenta      High Intensity
\DC    LRed     on Magenta      High Intensity
\DD    LMagenta on Magenta      High Intensity
\DE     Yellow  on Magenta      High Intensity
\DF     White   on Magenta      High Intensity
\E0     Black   on Yellow       Normal
\E1     Blue    on Yellow       Underline
\E2     Green   on Yellow       Normal
\E3     Cyan    on Yellow       Normal
\E4     Red     on Yellow       Normal
\E5     Magenta on Yellow       Normal
\E6     Brown   on Yellow       Normal
\E7    LGray    on Yellow       Normal
\E8    DGray    on Yellow       High Intensity
\E9    LBlue    on Yellow       High Intensity UL
\EA    LGreen   on Yellow       High Intensity
\EB    LCyan    on Yellow       High Intensity
\EC    LRed     on Yellow       High Intensity
\ED    LMagenta on Yellow       High Intensity
\EE     Yellow  on Yellow       High Intensity
\EF     White   on Yellow       High Intensity
\F0     Black   on White        Reverse Video
\F1     Blue    on White        Underline
\F2     Green   on White        Normal
\F3     Cyan    on White        Normal
\F4     Red     on White        Normal
\F5     Magenta on White        Normal
\F6     Brown   on White        Normal
\F7    LGray    on White        Normal
\F8    DGray    on White        Reverse Video
\F9    LBlue    on White        High Intensity UL
\FA    LGreen   on White        High Intensity
\FB    LCyan    on White        High Intensity
\FC    LRed     on White        High Intensity
\FD    LMagenta on White        High Intensity
\FE     Yellow  on White        High Intensity
\FF     White   on White        High Intensity

 Hex     Color                  Monochrome 

Where noted, the symbol UL indicates Underline.

UPGRADING FROM PRIOR EBL VERSIONS

1. If you have lots of older EBL version 3 batch programs, it may be easiest to put the statement "SET BAT=/OLD" within your AUTOEXEC.BAT file. EBL-Plus will then assume all batch files have an old syntax. If you write new EBL-Plus programs, you will need /NEW near the top to use the new EBL-Plus features.
2. If you only have a couple of EBL version 3 batch programs, add /OLD near the top of each of those batch programs. EBL-Plus will assume all batch files have the new syntax unless it sees the /OLD keyword. You may also need to add /OLD anywhere EBL reloads within those batch programs such as just after DOS commands.
3. In some unusual cases, your older batch program may use an EBL-Plus command that has been enhanced. If using the /OLD keyword does not work, check your program for any of the enhanced commands below. Some complex batch programs may need to use the newer EBL-Plus commands.

Updating EBL Version 3 to EBL Plus

Enhanced Commands

cols='20 20' width=40 rules=none frame=none.

Previous Command Migrate to...

CHDIR filename	CHDIR(filename)
COLOR colorname	COLOR(colorname)
MKDIR filename	MKDIR(filename)
RMDIR filename	RMDIR(filename)
STATEOF filename	EXIST(filename) or DIR(filename)
TRACE.OFF	TRACE()
TRACE.ON	TRACE(A)
WHILE condition	REPEAT WHILE condition
SHELL DOS program	DOS program (SHELL is the default)
DOS program - TSR Type	LEAVE DOS program - TSR Type BAT (or add /L option)
/TV	/W
BAT prefix required	Not needed, or add /P- option to make them required.
Strings with - math (Quotes not always needed)	"Strings with - math" (Use quotes to distinguish characters from operators)
%S variable	" " (Use quotes)
'#' operator	LENGTH()
':' DOS label prefix	'-' EBL label prefix
\1B attribute in BEGTYPE	Prefix BEGTYPE with >CON, or change \1B to ANSI and COLOR command pair.

.

New Defaults

EBL now defaults to the most commonly used modes, based on comments from our users. Through these new defaults, the EBL syntax has become easier to use and more free form. However, there are some things you should be aware of from these changes.

The new defaults are:

• /P - The 'BAT' prefix is not required
• /S - DOS commands are assumed to SHELL to access DOS
• DOS commands are kept "quiet" as they start. Use TRACE(C) to display them if wanted.
• If a label after a GOTO command does not have a minus sign, the label will be an external EBL program file name. This is consistent with the CALL command.
• Spaces are not required between strings and operators. Example: %A=%B+(%C*5) is the same as %A = %B + ( %C * 5 )
• Quotes are required to help distinguish strings from operators. For example %A= "10-5" is the assignment of a single string constant rather than an arithmetic expression.
• Commas can be used within functions that have several operands. Example: %A=Center("My Text",30) is the same as %A = Center( "My Text" 30 )

Note that since the '*' character is considered an operator, it cannot also be part of a string without being enclosed in quotes. Therefore, existing batch files should ensure that strings are contained in quotes when necessary. This will tell EBL the difference between "*" the string, and * the arithmetic operator. The same is true for other special characters.

Some problems encountered with running version 3 batch files that might be seen are:

• DOS reports "Bad command or file name" error.
  Solution: You may need to surround an application with LEAVE and BAT commands.
• Error number 7 from EBL is reported "Bad number or invalid condition".
  Solution: Characters that look like operators may be inside a string. Enclose the suspect strings in quotes.
• Error number 9 from EBL is reported "Expression syntax error"
  Solution: Characters that look like operators may be inside a string. Enclose the suspect strings in quotes.

Caution: If you use EBL to start a 'Terminate and Stay Resident' (TSR) program, you should always precede the program with the LEAVE command, then follow the program with a BAT command to return to EBL. This will guarantee EBL is not active during execution of the TSR and ensures DOS will not leave 'holes' in system memory allocation. The 'holes' can lead to other difficulties with programs. Prior to EBL Plus, the LEAVE command was optional. Now it is mandatory when using TSR programs. If you use EBL in your AUTOEXEC.BAT file, you very likely encounter this situation. You should therefore use care to add the LEAVE command before any programs that are TSRs.

It it usually trivial to update batch files to work well with these new flexible defaults. If you still want to run old files without making any changes (and without using any of the new features of EBL Plus), use the /OLD option at the start of your old batch file.

Options for Migration

  SET BAT=/OLD

You can also add this to the top of your AUTOEXEC.BAT file with an editor. Any other options or start-up EBL commands can also be used in this manner.