Programming Guidelines

3 Programming with Eloquence

Programming Guidelines

Entering Programs

Be sure to check the following points before entering your first program:

Unique line labels can be used. This optional label must be from 1 to 15 characters long (alphanumeric and underscore allowed), begin with a capital letter, and be followed by a colon. For example:

50 Display_name:DISP "Name is, ";A$

Branching instructions can refer to the optional label. So GOTO Display_name would branch to the above example line.
All numeric variables are assumed to be of real (full) precision unless specifically declared as integer or short precision. The default maximum length of string variables is 18 characters. Strings with a length other than the default of 18 characters will have to be declared in a DIM (dimension) statement. Details on declaring variable names and sizes are in page 73 .
The maximum program line length is 512 characters. This length includes the line number. After each line is typed in, check it carefully and then enter it into memory by pressing RETURN. The line is automatically checked for syntax errors before it is stored. If an error is detected, an error message appears.
Use the exclamation point (!) comment delimiter and the REM (remark) statement to annotate your programs. Some examples are shown later.
An END statement should be the last line in the main program. END stops program operation and resets program pointers.

NOTE: String constants and comments are limited to 255 characters. Comments cannot be positioned beyond column 255.

The following guidelines belong to the character oriented development environment, only:

Each program line must be preceded by a unique line number. Although line numbers are stored in ascending order, you can enter them in any order since they are automatically sorted when stored. All integer numbers from 1 through 32767 are allowed.
Branching instructions can refer to either the line number (not recommended) or the optional label. So either GOTO 50 or GOTO Display_name would branch to the above example line.
To edit a previously-stored line, just move the cursor up to the image of the line remaining in the display, edit it, and store it again with RETURN. If the old line is no longer in the display, you can either recall it with the FETCH command or simply retype the line number and line correctly. Then press RETURN. This will overwrite any existing line with the same line number.
You also can enter your program using any HP-UX editor or utility (for example, vi or awk). The ASCII text file you create using an editor or utility must then be syntax checked and converted to an Eloquence program file. This is done using the store command from the HP-UX prompt. Refer to page 32 for more information on this procedure.

Entering a Sample Program

Now you are ready to enter your first program. The next example shows some useful programming tips. The program is a simple guessing game which first computes an integer number between 0 and 9 and then gives the operator three chances to guess it. This example uses the character I/O (INPUT, DISP), so it cannot run on the NT platform.

10 REM
20 REM  THIS IS A GUESSING GAME
30 REM AN EXAMPLE PROGRAM DESIGNED AS AN INTRODUCTION TO Eloquence
40 REM
50 REM  DATE WRITTEN: dd/mm/yy
60 REM  AUTHOR      : John SMITH
70 REM  INSTALLATION: XYZ Computers
75 INTEGER Try,Guess,Number,You,Me
80 REPEAT
90    DISP  "~~"     ! Cursor home, clear display
100    PRINT "I'm thinking of a number between 0 and 9"
110    PRINT "You have three guesses"
120    Number = INT(RND*10)
130    FOR Try=1 TO 3
140        PRINT "Enter guess number, ";Try
150        INPUT "Now, ";Guess
160        IF Guess=Number THEN Win
170        IF Guess<Number THEN PRINT "Too Low"
180        IF Guess>Number THEN PRINT "Too High"
190    NEXT Try
200    !
210 Lose:  PRINT "Sorry, the number was: ";Number;"."
220           Me = Me+1
230           GOTO Tally
240 Win:   PRINT "That's right!"
250        You=You+1
260 Tally: PRINT SPA(30);"Game Score"
270        PRINT SPA(30);YOU      ME"
280        PRINT SPA(30);You;SPA(5);Me
290        WAIT 4000
300        INPUT "Do you want to play again? (YES/NO), ";Reply$
310 UNTIL Reply$="NO"
320 END

Here are some useful programming tips:

Annotate your listings using REM and ! comments (see lines 10 through 70). Comments can be used to explain sections of code and to insert blank lines. Both uses enhance program readability. Comment delimiters can be placed anywhere within a line. Any items occurring after the comment will be ignored by the Eloquence interpreter. The comment ends at the end of the line.
Use prompts in your input statements (see lines 150 and 300), which appear in place of the question mark (?) when the program requests data.
Define variables at the start of a program. This makes program maintenance easier. In Eloquence, a variable can be defined anywhere within a program and only needs to be quoted to be defined. For example, there would be no error if line 75 was omitted. If it did not appear, then the variable Try would be defined as a REAL variable (the default numeric type) when it first appeared in the program on line 140.
Use line labels, such as "Win:" in line 240, to allow for relative branching to a named part of the program (see line 160). A branch to a label is executed just as fast as if the line number was referenced.
Use the alternate character sets within string variables, such as the DISP statement in line 90, which clears the display buffer. The "~" represents cursor-home and clear-display. The keys corresponding to these characters can vary from terminal to terminal.
To minimize confusion, avoid using variable names, subprogram names, or line labels that are identical to Eloquence keywords.
Always include an END or STOP statement as the last line of every main program.

This programming tips are concerning line numbers and so they are useful for the character oriented development environment, only.

So that you can add new lines of code later, number the lines in increments greater than one. For example, it was possible to insert line 75 between lines 70 and 80, as a gap in the numbering had been left. If lines 70 and 80 had been consecutive (71, 72) then the program would have to be renumbered before another line could be inserted between them.

There is another way to insert lines, without concern for line numbers. This process involves using the list and store commands from the HP-UX prompt. List the program without line numbers (option -n) to an ASCII text file, insert your lines using an HP-UX editor or utility, and then store the program. When the store command converts the ASCII text file back to an Eloquence program file, it automatically renumbers the program in increments of one, starting with one. For more information see chapter , The LIST and list Commands.

Spacing between line numbers and statements is not important, so you can indent FOR-NEXT loops or any other structures for clarity. (For more information see chapter , The INDENT Command, for exceptions.)

Programming Aids

Program Annotations

The Eloquence language provides two ways to include non-executable text fields in program listings--the REM (remark) statement and the exclamation point (!) comment delimiter. All characters following either REM or ! are stored with the program but not executed. Any combination of text can follow each keyword, as shown in the next example. Notice that ! comment fields can be placed either on lines by themselves or after program statements. REM statements cannot.

10 ! You can say any **** thing you wish
20 ! in a REM statement
30 ! *********************************************
40 ! *                                           *
50 ! *      DOCUMENT YOUR PROGRAMS WELL!         *
60 ! *                                           *
70 ! *********************************************
80 PRINT "Enter Sales Code, ";Sales_Code
90 IF Sales_code < 1000 THEN Invalid_entry! Error_routine
100          ELSE
110             Enter_asale     !Code OK so user permitted entry
120                             !to Sales database
130          END IF

The Bit Bucket

When you wish to run programs that involve time-consuming output operations but do not want the output, you may assign program output to the Bit Bucket. This is an imaginary device where data is dumped and cannot be retrieved.

To assign output from the printer to the bit bucket, specify device address 9 in the appropriate printer assignment statement--PRINTER IS, SYSTEM PRINTER IS, or PRINT ALL IS. For example, to send all PRINT and PRINT USING output to the bit bucket, execute the following:

PRINTER IS 9

NOTE: Be sure to read page 252 before using these statements.

Creating programlines dynamically

With the COMMAND statement it is possible create programlines dynamically in the program.The COMMAND statement executes a statement contained within a string expression. The syntax is as follows:

Any executable, non-declarative statement (not DIM, COM, etc.) can be executed via COMMAND. For example, the following program uses a COMMAND statement to display a user selected variable:

10   INPUT Variable$
30   COMMAND "DISP "&Variable$
60   END

Note that the string expression can contain any combination of string characters within quotes, string variable names, substrings and string functions. String operations are described in page 73 .

One COMMAND statement can be executed by another COMMAND statement. However one COMMAND statement cannot call itself, nor can it call itself via intermediate COMMANDs. (The COMMAND statement is not recursive.) For example, the following sequence is permitted:

10   A$="COMMAND B$"
20   B$="DISP C$"
30   C$="OK"
40   COMMAND A$
50   END

However, the following sequence causes ERROR 156:

10   A$="COMMAND A$"
20   COMMAND A$
30   END

Execution of COMMAND Statements

There are three general forms of COMMAND statement execution available:

1 Scan/parse Eloquence statement contained in a string expression and execute.

2 If the first character of a string expression is an exclamation mark (comment), a system command is executed. Stdout and stderr are redirected to SYPR. You can redirect them with output redirection.

3 If the first character of a string expression is an colon (:), a system command is executed. In this form it is possible to start a interactiv process, as an editor or a shell, except the 'ksh'.

It is possible to execute HP-UX and Windows commands through the Eloquence COMMAND statement. The HP-UX command must be enclosed in quotation marks (" ") and begin with an exclamation mark (!).

It also supports the specification of a result string. If present, the output of a HP-UX command will be returned in the result string instead being output to the SYSTEM PRINTER.

Here is an example:

COMMAND "!uname -i",Serial$
DISP "Your serial number is ";Serial$

This example reads the serial number of the system and copies the output in the variable Serial$.

If the HP-UX or Windows command fails, you will receive error number 170, or a more detailed error code if you specified the return variable.

It is possible to execute interactive HP-UX processes, as an editor or a shell, except the 'ksh'.

Here is an example:

COMMAND ":elm"

This example starts the 'elm' and after quiting this process the eloqcore refreshes the screen and continues.

Space Dependency

Each line entered is automatically checked by the Eloquence interpreter. This check not only shows syntax errors in the line, but also assists with line spacing. Two methods of assistance are provided.

The SPACE INDEPENDENT Statement

This mode is the default. Power up or SCRATCH A will set the SPACE INDEPENDENT mode. The SPACE INDEPENDENT mode may be entered without a full reset by typing:

SPACE INDEPENDENT

Store the following line using the default (SPACE INDEPENDENT) mode.

10 IF Hours_worked>40 THEN GOTO Overtime

You must key in each word correctly. All Eloquence keywords (for example, IF, THEN, and GOTO) must be in uppercase, while variables (Hours_worked), line labels (Overtime) and subroutine names must be in initial caps (meaning the first letter of each word is in uppercase, while the rest of the word is in lowercase). However, the spacing between words is not important.

10IFHours_worked>40THENGOTOOvertime

10 IF Hours_worked> 40T HE NG OTOOv ertime

Both the above examples will enter the desired line correctly.

The SPACE DEPENDENT Statement

When the SPACE DEPENDENT mode is set, spaces between keywords and variables (or the lack of them) become significant. Keywords and variables must be separated from each other by at least one space. However, Eloquence variables, subprogram names, and labels can now be typed in any combination of uppercase and lowercase characters.

To set the SPACE DEPENDENT mode, execute:

Now, as each line is stored, the computer automatically sets all Eloquence keywords to uppercase and sets other words to initial caps. Text in quotes, in REM lines, and after ! comment fields is not affected.

To store the example line using the SPACE DEPENDENT mode, the case of each character is not important, but intraline spacing (between keywords, variables, labels, and subprogram names) is essential. Using the SPACE DEPENDENT mode type in and store either of these lines:

10 IF Hours_worked > 40 THEN GOTO OVERTIME

10 if hours_worked > 40 then goto overtime

Notice that each word is separated by at least one space. Leaving any spaces out in this example will result either in a syntax error or in an unexpected line. Note also that the underscore character, "_", cannot be altered. (A minus sign, "-", is not a lowercase underscore!)

In SPACE DEPENDENT mode, trying to store the following program line gives an appropriate error message.

10FORI=1TO10

The computer interprets this as an assignment statement and encounters an error when trying to assign the value 1 to the variable FORI.

Another problem is encountered in SD mode when entering the following:

50WHILEA=50

This example would pass the Eloquence interpreter without error. Unfortunately, the interpreter would assign the value 50 to the short variable WHILEA, instead of performing the correct interpretation (that is, to begin a WHILE loop, governed by the test A=50).

Here are some rules to follow when entering programs in SPACE DEPENDENT mode:

Any variable name that is the same as a secondary keyword (function, logical operator, THEN, etc.) cannot be entered. To minimize confusion, it is a good idea to use variable names that are not the same as any keyword (primary or secondary).
A line label that is identical to an Eloquence keyword cannot be entered at the start of a line.
The first variable in an implied LET statement cannot be entered if it is the same as a keyword. This is also the case if the implied LET follows THEN.
If a program line is not accepted while using the SPACE DEPENDENT mode, try to enter the line by setting the space independent mode, changing all characters in the line to their correct upper and lower case forms, and re-entering the line.

Error Messages

There are three main types of errors.

Syntax Errors

Each line entered is automatically checked for syntax errors. The system will not accept an invalid Eloquence statement, and will help you by showing where the statement fails. However, a mistake in typing that accidentally forms another valid Eloquence statement cannot be detected.

How you will be informed about the error, depends on the development environment

Run-Time Errors

These errors only appear when a program is run. A run-time error will halt the program and display the line number where the error was found. Consider this fragment of a payroll program:

190 INPUT "Please Enter Number of Employees;",Emp_quantity
200 Emp_bonus = Total_bonus/Emp_quantity
210 PRINT Emp_bonus

If the operator enters an Emp_quantity of 0, an error 31 will occure. Error 31 indicates attempted division by 0. Note that this error can only be detected at run time, as a division by zero will only occur if an Emp_quantity of 0 is entered.

The line number displayed by a run-time error need not be the incorrect line. It merely shows the point at which the error was detected. These run-time errors can be handled (or "trapped") by the program by using the ON ERROR statement, as described in page 151 .

Internal Errors

If an irretrievable system condition occurs while Eloquence is running, it stops and issues an error message. The error message contains the reason Eloquence stopped, will be different displayed, on HP-UX and Windows NT. Please make a note of this information, and report it to Marxmeier Software AG. To continue working, restart Eloquence.

Eloquence Language Manual - 19 DEC 2002