[-----------------------------------------------------------------------] [ A C O S Tutorial ] [ ver 1.2 ] [ Written by . A RIPCO System... Upgraded By UPS Network ] [ ] [ ] [-----------------------------------------------------------------------] ACOS COMPILER RELEASE 1.2 SPECS ----------------------------- Hardware Required : Apple ][ series Memory Required : 64k Operating System : DOS 3.3 or PRODOS Hardware Supported : printer, modem, display cards, clock, etc. Total Program Space: 24k Total Variable Space: 24k - program space Internal Editor Space: 4k Disk Channels: 2 (plus 1 for message base use) Ram Drive: 128 bytes Scratch Ram: 192 bytes Compiler Info: standard 2 pass compiler built on assembler principles for label oriented languages. Pass 1 Info: compiler pass 1 takes text source code and tokenizes all statements and functions into single byte tokens. All text and symbols are marked as such for fast recognition. All label addresses are stored into a table. All label references are also put into a separate table. Tokenized code is generated into memory without addresses. Pass 2 Info: Compiler pass 2 goes through the label reference table and searches for the address of the desired routine. If a match is not found, a LABEL NOT FOUND message is displayed. Otherwise, the address is saved into the second table. Afterwards, all references that were found are inserted into the actual code. The compiled code is then saved to disk. Code Execution: Actual code execution is based on a "fetch-and-go" method. Each token is fetched from the compiled code. The routine is then found via a lookup table and is executed. When label references are made, the address is already known so no time is taken searching for it. ------------------------- ACOS REFERENCE FOR ACOS RELEASE 1/2 --------------------------------- GENERAL INFORMATION Welcome to the world of ACOS. The following document was written to help give you an introduction to ACOS and to help you to learn to write your own programs or modify others written in ACOS. ACOS is a full featured language just like BASIC, PASCAL, FORTRAN, or any other language. it resembles BASIC more than any other language due to the fact that almost everyone involved with computers is familiar with BASIC because it comes standard with most personal computers. Since the aim was to make ACOS as easy to use as possible, it was modeled after BASIC. At the same time, there are also many differences also. This package contains a proprietary ACOS compiler which you will be using. Unlike many interpreted BASICs which have their editor built in, ACOS requires the use of some form of text editor for you to manipulate your source files. All ACOS source files are stored as text, so any editor that can modify standard text files can be used. ------------------------- WRITING A PROGRAM Since actually doing something tends to be a better teacher than just reading about something, we will be writing a small sample program in ACOS. The first thing you need to do is start your text editor/word processor you plan on using to write your code. Once you are ready, enter the following program: LOOP print "this is an acos program" print "i hope it works!" goto loop The important points to note are these: ACOS is not based around line numbers as is the BASIC language. It is free form like PASCAL or ASSEMBLY LANGUAGE. It uses labels as markers for groups of code instead of line numbers that marks the beginning of a line of code when the requirement arises to identify a specific point within the program. Since your labels can have descriptive names to begin a section of code, it makes it easier to see what this code does. Also, you can add extra blank lines at the top and bottom of a group of code to identify it more clearly. If you add comments within your code it helps you remember what you are trying to do in that section. When you begin to write your program there are a few rules that must be followed in order for ACOS to process your code. LABELS must ALWAYS begin at the column 0 at the left side of the screen. The rest of the code always begins in column 1. The only exception to this deals with the use of quotes (") to identify text. When you open a quote at the start of the print statement, all following text will be printed to the screen until another quote is encountered. This includes normal text, any control character and blank lines as well. Once you have typed in this test program, save it to your ACOS compiler disk under the name "TEST.S". You must ALWAYS add a ".S" to the end of any source file for ACOS so that ACOS knows it is a "source" file. Then exit from your editor back to your operating system. Insert the disk with the ACOS compiler and log to that disk. Execute the ACOS compiler with the appropriate operating system command (-ACOS, BRUN ACOS, ACOS). At this time, the ACOS loader will execute and check through you directory for any ACOS source files and do some file maintenence at the same time. You will then be asked for the name of the ACOS program to be executed. Hitting return will execute the default starting program which is indicated in brackets. This default filename will differ from application to application. Type in "TEST" and return. You will see "TEST" displayed as the default filename. Enter a return and the compl'iler will start to execute. The screen will clear and you will get a "COMPILING 1..." message. This means that the compiler is in the first phase of its two phase compile. This first phase takes the longest. After a quick wait, the message will change to "COMPILING 2...". This indicates that the compiler is in the second phase. This generally is very fast. Once the second phase is complete and has created a new file, which in this case is called "TEST.G", the message will be cleared and the program executed. In this case, the following will be displayed: THIS IS AN ACOS PROGRAM I HOPE IT WORKS! THIS IS AN ACOS PROGRAM I HOPE IT WORKS! THIS IS AN ACOS PROGRAM I HOPE IT WORKS! The two lines will be repeated over and over again, unless you stop the program via the RESET key. Lets see how this program worked. The first thing that happend is that the ACOS interpreter looked at the first line of code for a label that begins at the very left most column of the screen. This told ACOS that the first line is actually a LABEL. A LABEL is a reference point in a program to a section of code. A LABEL has no effect when the program flow passes through it, but it directs the operation from the line executing from one section of code to the beginning of the section where the LABEL is. Execution then is passed to the next line, the first having no actual effect. ACOS looked and saw that the second line did NOT start at the leftmost column but started at column 1 instead. This tells ACOS that the data on the line is the actual program code. ACOS then looked at the first word which in this case was PRINT. ACOS then went into its internal PRINT routine as you asked it. Once within the PRINT routine, special rules take over that govern the PRINT statement. Summing it up quickly, PRINT will display to the console whatever text or data is in between the " " marks. In this case, it printed "THIS IS AN ACOS PROGRAM". This data was placed within quotes to show that it was text. Once the end of the line was encountered, execution passed to the next line. The next line was another PRINT statement which was displayed: "I HOPE THIS WORKS!". This is the same text that you typed in when you wrote the short program. It works in the same way as the first PRINT statement. This is the simplest form of the PRINT statement. Its function is by no means limited to this basic form since there are many other variations that can be used. The last line of the program contained another statement to be executed by virtue that it was indented 1 space. This time, the STATEMENT or COMMAND was GOTO. This statement does what is called FLOW CONTROL. This is the process by which the point of execution of the program is changed from the last line executed to a new line. When the GOTO routine is executed, it searches for the name of the LABEL and when it finds the LABEL it executes the next line of code. In this case, the label was LOOP. ACOS then looks through the program to find a label called LOOP. As it happens, that label is on the first line of the program, though it could have been in any line. The program execution point is then moved to the label LOOP which happens to be at the beginning of the program in this case. Thus, the text is printed again and again. This situation is called an INFINITE LOOP. That is, the loop will never stop (unless you as operator stops it via RESET or some other means). After you hit [RESET], you will be faced with a group of choices labeled "RESTART: S,M,Q ?". By pressing "S" you will restart the original program you told ACOS to execute. By pressing "M" you will restart the program in memory. In this case, they are the same, but programs can link to other programs so that the original one is different from the one in memory now. This is helpful for debugging so you can re-start that program in memory without starting with the original program first. By pressing "Q", you will quit ACOS and return to your operating system. At this point, you have successfully written, entered, and executed an ACOS program. Though this was a simple example, the steps are the same for advanced programs. The following is a summary of the steps involved with writing an ACOS program: 1) Enter some form of word or text processor that can accommodate standard text files. 2) Type in your ACOS program. All labels start at column 0 while all actual code starts at column 1. 3) Save the program to disk adding a ".S" suffix onto your filename (ex: TEST.S) so that ACOS can identify it as an ACOS source file. 4) Execute ACOS from your operating system via whatever commands are needed. (ex: -ACOS, BRUN ACOS, ACOS). 5) Enter the name of the module you wish to execute if it is different from the default name. Don't add the ".S" suffix or the file will not be found. 6) The compiler will then compile and execute your program. If you execute the program again without changing the source code, the compiler will NOT re-compile, it will just run the old code. The following section contains information on all the data formats, variable types, and disk access methods that can be used with ACOS. A working knowledge of BASIC is recommended to help you along. If you don't know ant other language, try and use the examples as much as possible. They will be the best teacher. Also, try modifying existing code. This is another easy way to learn. ------------------------- PROGRAM STRUCTURE Under ACOS the structure of a program is very much "free-form". That is, the compiler is very tolerant of different styles of programming. You are allowed to add blank lines and comments anywhere in your code for ease of reading. Any line within an ACOS source program must be in one of the following formats: Blank Line: If the line is blank, this line will be skipped by the compiler. Blank lines are a good way to separate blocks of your code apart from other bloacks for ease of reading. Comment Line: By placing a semi-colon (;) as the first character of the line in column 0, all data until the end of the line will be ignored. In this way, you can enter comments so that when you come back to work on a program, you will have some idea of what you were trying to accomplish. Label Line: By entering just a keyword of your choice starting at column 0 of the line, you can enter a label. The first character of a label must be alphabetic. The rest of the label can consist of alphanumeric characters. The first 8 characters of the label are significant. That is, the labels TEST and TEST2 are considered different labels by ACOS while SHOWFILE2 and SHOWFILE8 would appear the same to ACOS since the first 8 characters are the same. Statement line: A statement line is always indented 1 space from the the left side. That is, at column 1, not column 0 like the previous line types. Statements are just entered on the line in the order you want them executed. If you wish to put multiple statements on a line, separate the statements with a colon (:). Statements may be typed in either upper,lower or mixed case. ------------------------- SPECIAL CHARACTERS There are several special characters that ACOS recognizes within your program code and uses them for different purposes. The following list show characters that have special meanings to ACOS. There are other characters which when encountered will be ignored. Any character including those below can be displayed by the program without problem, they just have special meanings when encountered outside the PRINT statement. Character Meaning space or blank = equals sign and also used for assignment statements + plus sign also used for adding strings - minus sign used for subtraction * multiply sign used for multiplication / divide sign used for division ( open parenthesis used to begin a function ) close parenthesis used to end a function $ dollar sign used to indicate a string function , comma used as a data separator ; semi-colon used for text formatting : colon used as a statement separator " double quote or string delimiter ? question mark or PRINT abbreviation \ backslash or new-line character < less than for IF statement > greater than for IF statement ------------------------- RESERVED WORDS Under ACOS, certain reserved words have predefined meanings. These words all correspond to ACOS statements, functions, and operands. When encountered, they will be executed as an ACOS command. These may NOT be used for variable names. It is always best if you separated reserved words from data or each other by use of a space or a colon or whatever special characters the particular command syntax allows. One of the keys behind writing a good program is making sure you can understand what you wrote. For example, PRINT A$;B$,C PEEK(27):HOME uses a (;), a (,), a ( ), space and a (:) between data. The following is a list of reserved words: ADDINT APPEND BYTE CHR$ CLEAR CLOCK CLOSE COPY CREATE DATE$ ECHO EDIT END FILL FLAG FOR FREE GET GOSUB GOTO HOME IF INFO INPUT INSTR KEY KILL LEFT$ LEN LINK LOG MARK MID$ MODEM MOVE MSG NEXT NIBBLE NOT ON NOCAR OPEN PDL PEEK POKE POP POSITION PRINT PUBLIC PUSH RAM RAM2 RANDOM READ READY RETURN REWIND RIGHT$ RIPCO RND$ SET SETINT STR$ TEXT THEN TIME$ TONE UPDATE USE VAL WHEN$ WIDTH WRITE ------------------------- VARIABLES One of the most powerful parts of any language are the use of VARIABLES. ACOS contains two basic variable types. The common ways of using them are listed below: Numeric Variables: Under ACOS, numberic variables are just integers. Floating point numbers are not supported. ACOS is not a good language if your application demands heavy math support. The integers are in the range -32767 to +32768. Numbers outside this range will either "wrap-around" or give an OVERFLOW ERROR. Numeric variables are represented as names of your choice. They must start with an alphabetical character, but can contain any alphanumeric characters that you desire. For instance, ABC, Z7, AS76D are all legal numeric variables. String Variables: Under ACOS, string variables are the same as they are under most BASICs. They can be between 0-255 characters in length, they can accept any type of characters (control, upper/lowercase, numeric, etc.), and can be manipulated in a number of ways. String variables must start with an alphabetical character and can contain any alphanumeric character as can a numeric variable. However, the variable name nust be terminated by a dollar sign. For example, ZQ$, A7$, NAME$ are all legal string variables. Unlike many basics, ACOS does NOT support arrays. Due to speed and memory considerations, array support is impractical. Fortunetly, ACOS has been engineered to handle large groups of data that will out preform most normal array systems. Under ACOS, variable names can be of any length, though only the first two characters are used within ACOS for identification. For example, you can use the variable VOTE throughout you program without a problem. Internally though, ACOS only looks at it as VO. As a result, if you have a second variable named VOLUME, internally, it will be the same as VOTE. Thus the two variables will be the same as far as ACOS is concerned. The ability to use variable names greater than 2 characters is only for your reading convenience. You can assign a variable a value the same way you do in any BASIC. You can use: LET VOTE=1 to set the variable VO to a value of 1. As a shortcut, you can just say VO=1, and ACOS will figure out what you mean. The LET is an optional operator. When assigning a string variable to an absolute value, the string to be assigned must be enclosed in quotes and must be no more than 255 characters in length. ------------------------- ARITHMETIC OPERATORS There are several standard srithmetic operators that can be applied to numeric and string variables. Though they are somewhat limited in nature under ACOS, most common functions can be accomodated. Addition: A=B+C or A=B+5 or A=3+7 are all legal operators. Whenever a number is needed for whatever purpose, an equation may be substituted with its place. A$=B$+C$ or A$=B$+"HMMM" or A$="THIS IS "+"A TEST" are all legal string addition commands. Under string addition, the contents of the second string are appended onto the contents of the first. Subtraction: A=B-C or A=B-5 or A=3-7 are all legal operators. It is very similar to using the addition operator. There is no string subraction operator. Multiplication: A=B*C or A=B*5 or A=3*7 are all legal operators. If you combine multipication/division operands with addition/subtraction operands, the multiplication/division will be executed first. ex: 4+5*3=19 not 27. Division: A=B/C or A=B/5 or A=3/7 are all legal operators. Since ACOS is an integer based language, with division operands, the results are rounded to the nearest integer and the remainders are thrown away. Thus 10/2=5, 10/3=3, 10/7=1, 10/11=0. Modulo: A=B MOD C or A=B MOD 5 or A=3 MOD 7 are all legal operators. The MOD operand is a sub function of division. Instead of returning the quotient as with division, the remainder is returned. Thus, 10 MOD 2=0, 10 MOD 3=1, 10 MOD 7=3. Grouping: By using the parenthesis, you can create complex equations and control the method of expression evaluation. Arguments within a set of parenthesis are always executed first. You may also nest several levels of paranthesis if needed. Thus ((3+4)*5)/(3+4) is evaluated in the following steps: step 1 (7*5)/(3+4) step 2 35/(3+4) step 3 35/7 step 4 result is 5. ------------------------- RELATIONAL OPERATORS Relational operators are used to compare two values and return a true/false result. Strings may be compared with other strings but not to numbers. The same is true for numbers. A "TRUE" result is returned as the value of 1 while a "FALSE" result is returned as the value 0. The following are the legal relational operators: Operator Relation Example = equality X=Y <> or >< inequality X<>Y or X> greater than X>Y <= or =< less than or X<=Y or X== or => greater than X>=Y or X=>Y or equal to examples: (1=0) with the result of false or (0), (1=1) with the result of true or (1), (5<4) with the result of false or (0), (5>4) with the result of true or (1), (7<7) with the result of false or (0), (7>=7) with the result of true or (1). You may always substitute more complex variables in place of simple variables. You can replace ((X)>(Y)) with a more complex expression like ((4+5*6)>(3/4+12)) or expressions that are even more complex. If you do have a complex expression on a side, you should put parenthesis around it to separate it from the relational operator so it is processed as one side. When used in conjuction with the IF statement, you have one of the most powerful statements with in ACOS. When used with the IF statement, you have a conditional branch, the single most important program execution statement. ------------------------- LOGICAL OPERATORS Logical operators perform simple logic operations on numeric values. They can be used to increase the power of the IF statement by allowing more conditions to be evaluated. Under their simplest form, logical operators work with true (1) and false (0) values. The following truth tables show the results of all the possible logical operators in action. z= not x z=x and y z=x or y x z x y z x y z -------- --------- --------- 1 0 1 1 1 1 1 1 0 1 1 0 0 1 0 1 0 1 0 0 1 1 0 0 0 0 0 0 The following examples show the IF statement being used with the relational and logical operators: IF (X=5) AND (Y=9) GOTO label IF (NAME$="SHIT") AND (UN=1) GOTO label IF NOT ((A=3) OR (B=4)) GOTO label Again it is important to use parenthesis when complex equations are being evaluated so that ACOS can understand the order the operand is processed. Since execution order is normally sequential, without grouping, ACOS will be on its own to decide what order you wanted to do things. Many times it will guess correctly, but on occasion, it will guess wrong. Using grouping is an easy way to avoid this problem. ------------------------- PRINT STATEMENTS The two most frequently used versatile statements have to be PRINT and INPUT. These are the basic means by which you input data into variables and print data out to the screen. Dur to the frequency of use, a basic understanding of these two statements is very important. The PRINT statement has the function of taking data and displaying it on the console/modem. There are many options in PRINT that can be used. The basic form of print is PRINT [expression]. In the simplest form you can use PRINT [any absolute data]. This would include numbers (PRINT 563) or text within quotes (PRINT "HELLO"). To include multiple arguments, you need not even separate them, though a space or semi-colon between them makes it easier to read. PRINT "THE VALUE 4+5=";9. Of course, in place of absolute data, you can have statements, equations, and variables. For example the above print statement could be written as: PRINT"THE VALUE 4+5";4+5. If we wish to print a function, just enclose the function within the print statement. For example, PRINT PEEK(456), would display the contents of memory location 456. To print a variable, just include the name of the variable in the PRINT statement. A PRINT NAME$ would print the contents of NAME$ on the screen. To combine multiple statements, just use the semi-colon or a space. PRINT NAME$;UN;PEEK(465);4+5 would display all the above data. There are several special characters that can be used with the PRINT statement to format the data. If you use a comma instead of a semi-colon, the comma will also be printed. There is also a print-at character (@) that can be used. PRINT@5,0;"HELLO" will display the word HELLO at verical location line 5 horizontal location column 0. ------------------------- INPUT STATEMENTS The INPUT statement is used to enter data in variables from the console/modem by the user. It also has a quick directive so the text can be displayed (like a PRINT statement) before the data is entered. This works well as a prompt. In its simplest form, INPUT is used to enter either a string or numeric variable from the console/modem. INPUT NAME$ would wait for the user to enter a string from the keyboard. That string would then be put into NAME$. To enter multiple variables, separate the variable names with either the comma or the backslash character. When you separate variables with a comma, the input must correspond to the number of commas used in the input. For example, INPUT A,B,C would wait for 3 numbers to be entered. Typing 1,2,3 would enter 1 for A, 2 for B, and 3 for C. If you enter a backslash between variables, then each value must be on a separate line. This avoids having to do multiple INPUT statements all in a row. Thus INPUT A$\B$, would enter two lines worth of data into the two string would enter two lines worth of data into the two strin