Action! and BBS Express! PRO Tutorial#
by Thomas M. Johnson
Available from
Villa Video's Bargain Cellar (414) 265-5149 ExpressNet Node X11
Action! is copyright of ACS, OSS, ICD. BBS Express! PRO is copyright Orion Micro Systems.
This tutorial is copyright Thomas M. Johnson.
This tutorial can be distributed under the following conditions: 1. It is free. 1. All of the above information is intact.
Lesson 1#
Welcome to the Action!/PRO tutorial. In it, I plan to teach you how to write command modules for BBS Express! PRO. But to write these, you must know the Action! programming language. So this is a 2 for the price of 1 tutorial.
I strongly suggest you print the files of this tutorial out. There are a number of programs that accompany the text part (the part you are reading now) and smaller program included in the text part that may take a long explanation. So instead of trying to view this on the screen and paging around looking for what I am talking about, having it on paper would make things easier.
First thing you should do is turn on your computer with the Action! cartridge plugged in.
You should see a flashing cursor in the upper left hand corner of the screen and the words "ACTION! (c) 1983 ASC" in inverse letters at the bottom. This is the EDITOR mode. This is where you enter and edit your program. The Action! editor is very versatile. I am using it right now to write this tutorial.
I guess we should start with the "standard" first program that you see in ANY book that teaches a programming language. The infamous "Hello, World" example.
To set aside parts of this text that should be entered into the editor, I will indent from here on in.
PROC main()
PrintE("Hello, World")
RETURN
OK, so now what does it mean? The word PROC is a Action! reserved word (that means you can't name a variable, procedure or function that name).
PROC is short for PROCedure and that simply means it is a section of code.
The word "main" comes down to us from the language C. A short digression is needed. In the language Pascal, the last procedure is the controlling procedure. It can calls all the other procedures and it is not named.
In C, the controlling procedure is the one called "main". But it can be anywhere in the program.
In Action!, we compromise. It is named like C, but it must be last like Pascal. But in Action!, we don't have to call it "main", we can call it anything we want. But most programmers call it main.
Then comes the "()". This mean there are no parameters. The main PROC can NEVER have any parameters. If you are wondering what parameters are, we will cover them in a later lesson.
Next is the "PrintE()" line. This is part of the Action! library. It prints what ever is between the quotes and puts the cursor on the left side of the screen on the next line down.
Why is the PrintE() line indented? In Action!, indention and capitalization do nothing. "PRINTE()", "printe()" and "PrintE()" are exactly the same thing. But to keep programs from 1 programmer to another looking the same, the "PrintE" is used. And it is indented to show that it belongs to the PROCecude "main".
Lastly, is the word "RETURN". This signifies the end of a procedure. When it occurs at the end of the "main" procedure, your program returns control back to the Action! cartridge.
How do you run this program? When it is typed into the editor exactly as shown, you press the CONTROL key, the SHIFT key and the M key at the same time (I will abbreviate this as <C><S>M).
You will hear a buzz and the screen will go blank. There will be a inverse line at the top of the screen. You are now in the MONITOR mode. From here you must Compile your program.
You press C then the RETURN key. If there are errors, you will get a message telling you so. If you have errors, press E and the RETURN key to go back to the Editor. If not, you press R and the RETURN key to Run you program.
This is a good place to end lesson one. If you want to experiment until the next lesson, try adding some more PrintE lines in the program. Like:
PROC main()
PrintE("Hello World!")
PrintE("I am programming in")
PrintE("Action!")
RETURN
Lesson 2#
In the last lesson, we went over how to compile and run a Action! program. We also learned that the last PROC in a program is the first one that is run. Finally, we learned our first Action! library PROC - PrintE.
Now we are going to cover varibles. In Action!, you must know what type of values a variable will take on before you can use it. This is so the compiler can set aside the right amount of space for that variable.
In Action!, we have 3 basic variable types: BYTE, INT and CARD.
Note: the keywords BYTE and CHAR are identical and can ALWAYS be used in place of each other.
First the BYTE. A BYTE can have a value from 0 to 255 and that is all. When you add 1 to a BYTE with a value of 255 you get 0. The same when you subtract 1 from 0 you get 255.
BYTE values are used for loops and most other general values.
The next basic type is a INT. INTs can have values from -32768 to 32767. If you need to use negative numbers, a INT is the only way to do it.
Lastly we have a CARD. CARDs can have values from 0 to 65535. Use CARDs when you need larger numbers. But 65535 is the largest number you can have. When you add 1 to 65535 you get 0 for an answer.
The are no real numbers like 5.7 in Action!. Nor are there scientific notation like 5.8E4.
Why does Action! have these restrictions? I know BASIC programmers are say "In BASIC we don't have to declare variables and they can be real and larger than 65535."
But in BASIC, EVERY variable takes up 6 bytes of memory. In Action!, a BYTE takes up 1 byte and INTs and CARDs take up only 2. And this is the way the computer really looks at numbers. The floating point package is the thing that really slows BASIC down.
So we have this chart:
| name | size in bytes | low val. | high val |
|---|---|---|---|
| BYTE | 1 | 0 | 255 |
| INT | 2 | -32768 | 32767 |
| CARD | 2 | 0 | 65535 |
Ok, so how do you use them? Here is a sample program.
PROC main()
BYTE i
Print("Give me a number. ")
i=InputB()
PrintBE(i)
RETURN
The first line we know. It is required by all Action! program to define a PROC.
The next line declares i and j as variable of type BYTE. They will only have a value from 0 to 255.
The Print statement prints what is between the quotes without returning the carriage after.
The i=InputB() line inputs a BYTE from the keyboard and places its value in i.
j=i set the value of j to be the same as the value in i.
PrintBE(j) prints the value of j as a BYTE and returns the carriage.
If a number larger than 255 is entered the Action! system will take what is called the "least significant byte" of that number and place that in i. I won't go into LSB right now. But if you want to experiment...
What if you wanted INTs instead of BYTEs?
PROC main()
INT i
Print("Give me a number. ")
i=InputI()
PrintIE(i)
RETURN
OK, the last thing I will do in this lesson is the related Input and Print functions.
BYTE b CARD c INT i
Just declaring some dummy variables.
| Example | Description |
|---|---|
| i=InputI() | input a INT |
| c=InputC() | input a CARD |
| b=InputB() | input a BYTE |
| Print("hi") | print string without the carriage return |
| PrintE("hi") | print the string with the carriage return |
| PrintB(b) | print a BYTE without the CR |
| PrintBE(b) | print a BYTE with a CR |
| PrintC(c) | print a CARD without a CR |
| PrintCE(c) | print a CARD with a CR |
| PrintI(i) | print a INT without a carriage return |
| PrintIE(i) | print a INT with a CR |
Next we will go into expressions and the IF statement.
Lesson 3 #
In the last lesson we went over variables. The name of a variable doesn't have to a name like the "i" I used in the examples. In fact, they shouldn't be like that. Variable names should be descriptive to you know what their purpose is. In Action!, the only restriction is that variable names start with a letter. They may contain letters and the underline "_" character later in the name. Which is easier to understand?
t=(p*x)+p
or
total_price = (price * tax) + price
This brings us to our next subject, expressions.
Action! supports the following operators.
| Operator | Description |
|---|---|
| - | as in negative numbers. Remember only INT can be negative. |
| * | multiply |
| / | divide. This is integer division because Action! doesn't have real numbers. So when you take 5/2 it is equal to 2 NOT 2.5 |
| MOD | This is the remainder when you divide. 5 MOD 2 equals 1 because 5/2=2 with a remainder of 1 |
| + | addition |
| - | subtraction |
Action! also has a number of bit-wise operators but we will cover those later.
I guess a sample program would be good about now. This sample program is a little too long for you to have to type in to your editor. So I guess this is a good time to say that when this occures, the sample program will be called APROG.301
This means it is a program with the ATUTOR series. It goes with lesson 3 and it is the 01 (first) program.
To load the program into your Action! editor, you press <control><shift><R> at the same time. The bottom line of the editor will print "Read?"
Here you type in the filename and it will load. Then you can compile and run the program like normal.
You will notice that the variables are of type INT. I did this so you can see how Action! handles negative numbers. Try -32767 and 4 for sample numbers once.
You will see that Action! does some weird things when you try to go past the boundaries of the variable type. In this case, INT can only be -32768 to 32767.
Try some nicer numbers to show the program works fine. Like 10 and 6. Or any other number you may want to try. You will have to recompile and rerun the program for each different set of values.
You may have noticed a PutE() command in the program. This places a carriage return on the screen. In other words, it just puts a blank line on the screen. I just put it in there to make it easier to read.
The next things we will cover are relationals. Relationals yield a value of TRUE or FALSE. An example might be: 4=7. This is false. Here is a list of the Action! relationals:
a=b tells if a and b are equal
a<>b tests to see if a and b are not equal
a\#b the same as a<>b
a>b is a greater than b
a>=b is a greater than or equal to b
a<b test to see if a is less than b
a<=b is a less than or equal to b
The are 2 more, AND and OR and I will cover them in the next tutorial.
Now we will go into the simplest case of the IF-FI statements. They are used like this:
IF <relational is TRUE> THEN statement statement statement FI
If the relational expression between the brackets is true, Action! will execute all the statements between the IF line and the FI line.
If the relational is false, Action! will skip all the statements between the IF and FI and start with the statement after the FI.
The statements between the IF and the FI should be indented a few spaces to show that they are dependent on the IF statement. And it also makes it alot easier to read!
try this program:
PROC main()
IF 4>9 THEN
PrintE("4 is greater than 9")
PrintE("Do you believe it?!?")
FI
PrintE("done")
RETURN
The above program should just print the word "done". If 4 should happen to be equal to 9 today (maybe its Friday the 13th?) then it would print the other 2 lines followed by the word "done".
This is the end of lesson 3, I will leave you with another program that is too big to print here. It is called: APROG.302
Lesson 4 #
Well, I guess its time we started talking about loops. Loops give us the ability to repeat a section of code over and over again until we want it to stop.
The section of code we want to repeat is marked off with a DO at the start and a OD at the end.
PROC main()
DO
Print("Hello!! ")
OD
RETURN
This is print Hello!! over and over and there is no way to stop it other than pressing the BREAK key or the RESET key. So we need a way to control the number of times a loop get executed. Action! provides us with 3 ways.
The first and probably the least powerful is the FOR loop. It is the most used loop. Then why do I say it is the least powerful? Because it executes a loop a fixed number of times.
PROC main()
BYTE i
FOR i=1 TO 8
DO
PrintBE(i)
OD
RETURN
This program just prints the numbers 1 to 8 vertically on the screen. ANY commands can be places between the DO and the OD and they will get executed 8 times.
The next loop controller Action! gives us it the WHILE loop. It looks like this:
WHILE (a condition is true) DO OD
The WHILE loop evaluates its condition at the top of the loop, so if the condition is FALSE to begin with, the loop will never execute. Try program APROG.401 to see.
The last type of loop control Action! gives us is the UNTIL loop.
DO
statements
UNTIL (condition is true)
OD
The major difference between the WHILE and the UNTIL is that the UNTIL get evaluated at the bottom of the loop. This means it will be executed at once. After it is executed once, if the condition is FALSE it will get executed again.
DO
PutE()
PrintE("Press any key or 0")
PrintE("to exit")
i=InputB()
UNTIL i=0
OD
If the condition i=0 is TRUE the loop exits.
The last loop command I saved for last to mention because in theory, it is never needed. I say in theory because in the REAL world it can be useful.
The command name is EXIT. Lets say your program has to input a large number. And the next numbers are divided into the bug number until the answer gets down below 10. But if the user inputs a 0 to divide into, the is very bad since a division by 0 doesn't exist.
Look at program APROG.402 for this program. You will notice that the divison is not what you would expect. That is because Action! only has whole numbers.
In Action! if you:
PrintBE( 1 / 3)
That is take 1 divided by 3, you will get 0, NOT .33333 Action! has no decimal notation.
I am getting of the subject but I feel that since it is used in the program it is a good idea to explain it.
Anyway, the EXIT command is good when you use it in emergency situations, when you have to get out of a loop in a hurry.
A EXIT is also useful when you have alot of conditions on when to end a loop.
Like: UNTIL (the user answers yes AND the record number =0 AND you haven't reached the end of the file AND you aren't running out of memory space)
I haven't gone into the actual Action! statements of those situation yet so I put them in words. But you get the picture, there are 4 conditions to end this loop.
The better thing to do is just have 1 or 2 conditions in the UNTIL statement and put the others in IF FI with can EXIT.
MOST other times, if you must have an EXIT in your loop to make it work right, you have chosen the wrong type of loop.
APROG.403 compares doing the same loop with the 3 looping statements. Remember, each time a program must do a loop, it is up to you, the programmer, do decide which type of loop to use. For APROG.403, try and guess which one is BEST. They all work, but one is best for what I am trying to accomplish.
That's it for Action!'s looping commands. In the next file, we won't be going into any new Action! commands. It will cover some editor and monitor commands that will make your writing and debugging of Action! programs faster and easier.
Lesson 5#
As promised, now we are going to talk about advanced editor and monitor commands. Knowing these will make your writing, editing and debugging of Action! programs many times faster and easier.
In this file, when I use something like this: <C><S>M That means to press the Control, the Shift and the M keys at the same time. And we all know that doing that will take us into the monitor.
There are more commands to help you than I can possibly list. If I did it would take me over 100K. I am just going to cover the ones I use most. I use almost all the commands at sometime or another. Please look at your Action! manual and carefully read over the sections on these commands. They are very important.
I guess we should dive right in with some editor commands. You already know <C><S>R and <C><S>W for reading and writing to and from the editor.
Pressing <C><S>- and <C><S>= (these are the arrow keys) will jump you around the editor 1 screen at a time. You can really get around the editor fast using these.
If you are looking for a certain word or words in you Action! program, the editor has the <C><S>F command. Action! will ask you for the string to search for. And zip you are there or a not found message appear. This only searches from the point you are in, downward. So if you are at the end of your file, no matter what you search for you won't find it because there is nothing below it.
<C><S>S will also find a string of characters but it will also replace it with another string. This will come in very handy when we start programming for BBS Express! PRO.
A word of caution, when you substitute, use a word that does not have the old string contained in it.
Let's say you want to change all the occurrences of the word 'score' in your program into 'u_score'. Changing the first occurrence is great. The cursor will be on the 'u' in 'u_score'.
The next occurrence it will find is the 'score' in 'u_score' so you will get 'u_u_score'.
If you change a existing line but have not yet pressed the RETURN key, <C><S>U will restore it back as good as new.
To delete a line just press <SHIFT><DELETE>. To delete a bunch of line just hold this key down. Oh no! You just deleted the wrong line, well <C><S>P will put the entire block of deleted lines back.
This is also how you move and copy blocks of text. Just delete them, and go to where you want to appear. Press <C><S>P and it is moved.
If you just want a copy somewhere else, make sure you <C><S>P it in the same spot where you deleted it, the move and <C><S>P again.
To erase you file, <Shift><Clear> does the trick.
Remember, look in the Action! manual and read over the commands I did not cover. They are very useful!
Now the monitor. You already know the C command compiles a Action! program and R runs it.
B reboots the Action! system without having to turn your computer off and on. This erases anything you have in the editor and starts you from scratch.
O takes you to the options menu. In here you can change some features of the Action! system and also turn on some debugging flags.
The first option is the Display option. When you turn this on, it speeds up reading and writing to the disk and printer. It also speeds up compiling your program. It does this by turning the screen off while doing these operations. The first thing I always do then I load my Action! cartridge it turn this on.
If that stupid bell is driving you nuts every time you go to the monitor or come across an error while compiling, the Bell flag can turn this off.
The Case Insensitive flag can turn on the.... well I better show you.
In Action!, the variables:
score
Score
SCORE
sCoRe
are all the same. Turning this on will make them all different varialbles. It will also make you spell the Action! routines correctly too. PrintE is spelled with a cap P and a cap E. If this is off, the default, you can spell it anyway.
The Trace flag prints the PROC or FUNC you are currently entering when you run your program. We haven't covered PROCs and FUNCs yet but I will say this is VERY, VERY useful when debugging.
Most of the time when Action! finds an error while it is compiling, it will take you right to the spot in the editor where the error occurred. Sometimes Action! doesn't know where the error is and setting List to y will print each line to the screen while that line if being compiled. This in only useful when the Display flag is on. Compile a sample program with this on to see what it does.
Window size, Line size and Left margin we won't go into.
EOF character will change the last character of each line from a blank space to something you can see. The Action! manual say it will "aid visualization of the program."
That's it for the Options menu. Back to the monitor commands. D will take you to DOS. If you are using DOS 2.0 or 2.5 the editor will be erased so be sure to save it before you use this. If you have DOS XL or SpartaDOS, the editor remains. To get back to Action! from DOS use the B (to cartridge) command in DOS 2.0-2.5 and CAR in DOS XL and SpartaDOS.
You can compile a Action! source program without having to load it into the editor. Just put a filename after the C for compile. Make sure you use the whole filename and device and make sure there are "quotes" on both ends of the filename.
C "D:APROG.402"
will compile APROG.402 off disk drive #1. This is useful when your program won't compile because it is out of memory.
W "D:MYPROG.CMD" will write the compiled code to disk. That way you don't have to recompile it each time. Using R "D:MYPROG.CMD" will load and run your Action! program if it was saved using W.
If you have the Action! runtime package, this is how you write programs that don't need the cart. to run.
This is also how you save BBS Express! PRO command modules.
Well that's about it for now. I have barely scratched the surface with the number of commands you have available to you. But, These bare minimums will help you get around easier.
Lesson 6 #
Well, now it is time to cover the most powerful of all the Action! Print routines. It is called PrintF for print formatted.
This baby does it all!
The first thing PrintF must have it a string in "quotes." If PrintF is used like this, it is just like Print.
| command | output |
|---|---|
| PrintF("Hello") | Hello |
| Print("Hello") | Hello |
But if some special characters appear inside the "quotes", PrintF can do anything you want.
The first of the special characters is the %E. That is a percent sign followed by an E. This can appear anywhere in the "quotes" and Action! will do a RETURN where the %E appears.
Here is a comparison of the old way versus PrintF
old way
PutE()
PrintE("What is your name?")
PrintE("Only 10 characters please.")
PutE()
new way
PrintF("%EWhat is your name?%EOnly 10 characters please.%E")
It may look a little harder to read but it actually takes up less memory and time. Why? Because with each call to an output procedure, Action! must open a channel to the screen, print what you want and then close the screen. So the old way there are 4 opens and closes. With PrintF there is only 1.
The next special character is the %U. What does the U stand for? It means Unsigned. INTs are signed with a +/- so it must be used by BYTEs and CARDs. But how does it know what value to print where the %U is?
Assume a and b are BYTES.
a=5 b=10
old way
PutE()
Print("The sum of ")
PrintB(a)
Print(" and ")
PrintB(10)
Print(" is ")
PrintBE(a+b)
new way
PrintF("%EThe sum of %U and %U is %U%E",a,b,a+b)
Both print the line:
The sum of 5 and 10 is 15
After the second quote, there is a comma and then the BYTEs that get substituted. The first BYTE in that list goes with the first %U. And so on with the rest.
Then what does a %C stand for? %C prints the value associated with it as a character. The ATASCII value for the letter 'A' is 65. So,
PrintF("The letter %C.%E",65)
will print:
The letter A.
This may not seem very useful but when you want to print special graphics characters it is real nice.
Here is a list of special characters and how they output the data in the list.
| format char | description |
|---|---|
| %I | INT |
| %U | CARD (the U stands for Unsigned) and BYTE |
| %C | print as a character |
| %H | a Hexdecimal number |
| %E | the RETURN character |
| %% | output the percent sign |
| %S | output as a string (we'll cover this in a later lesson) |
So what is wrong with PrintF? Well, it can only print to the screen. Not to a external device like a disk or your printer. Don't worry about that now, we'll cover that in a later lesson also.
Try APROG.601 for an example of using PrintF for handling some complex output formats.
Well that's is for this instalment. Short, sweet and to the point. Next, we will go into the heart of Action!, the ability to call PROCs.
Lesson 7#
Now its time to learn about PROCs. What is a PROC? We already know about PROC main() but what else is there?
A PROC is an independent block of code that can be called. Ideally, a PROC should use only local variables and not global. We'll get into that in a minute.
You define a PROC the same way you define main().
PROC my_proc() local variables statements RETURN
The "my_proc" can be any name that isn't already used by the Action! system.
For you BASIC programmers, a PROC is like a GOSUB. But much more powerful.
PrintE and the most of the other routines we've looked at so far are PROCs that are built in to the Action! cartridge.
Let's take a look at a sample.
PROC my_proc() BYTE a a=10 PutE() PrintBE(a) RETURN PROC main() BYTE a a=5 PutE() PrintBE(a) my_proc() PutE() PrintBE(a) RETURN
Can you guess what will be printed? The output will look like this:
5 10 5
First 'a' is set to 5 in main(). Remember that the last PROC is always the first one run. The value of 'a' is then printed. Then when the computer gets to the line "my_proc()" it goes up to the spot where "PROC my_proc()" is and starts running there.
Ok, now we have another 'BYTE a' and we already declared a BYTE a. These 2 "a's" are as different as apples and oranges. They are local to the PROC they were declared in.
So 'a' is set to 10 and is printed. When the RETURN statement is executed, the computer goes to the next line after the call to the PROC. In this case it will print 'a' again.
And it prints 5. But in my_proc we set a=10. Once again, these are 2 different variables because each can only be used by the PROC it is defined in.
A even more powerful feature of PROCs it the ability to pass it parameters. Parameters and local variables allow PROCs to not know or care anything about the outside program. A PROC will have a specific task and it won't care what called it or why. Take a look at APROG.701 for an example.
The call to the PROC in main() looks like "square(num)". Action! takes whatever num is equal to and places in the variable "number" in PROC square(BYTE number).
You can have a number of parameters and they can be any type. You can even mix types. To pass 2 BYTEs and 1 CARD to a PROC use this:
PROC m(BYTE a,b CARD c)
and the call would look like:
m(10,30,5000)
There are commas between like variable types and a space between different types.
You can have PROCs call other PROCs. It's important to understand the use of local variables and PROCs. Even more so of the PROCs. Next time we will cover FUNCs, which are similar to PROCs, and the opposite of local variables, globals.
Lesson 8#
Do you remember what a function is from high school algebra? It take an number, performs some operation on it and return only 1 number back. Like:
y = f(x)
where f(x) = x^2
So if x=3 then y=9.
In Action!, a function is like a PROC only it has a type associated with it. We can write the x^2 function in Action! like this.
CARD FUNC squared(BYTE x) CARD y y = x * x RETURN(y) PROC main() CARD answer answer = squared(3) PrintCE(answer) RETURN
And it will output a 9.
Notice that there is a variable type before the word FUNC. This tells what is going to be returned. A BYTE, CARD or INT can be used. As you can see, the rest is alot like a PROC. The next different thing is the RETURN statement.
Whatever is on the left side of the equals sign in the call, in this case the variable 'answer' will get the same value as what is inside the () after the word RETURN in the FUNC.
You can see that the input routines we've been using so far are really FUNCs. When you do a:
value = InputB()
the first line of InputB in reality looks like this.
BYTE FUNC InputB()
meaning it returns a BYTE to value.
When we first talked about IF FI, I said that the conditional after the IF returned a TRUE or a FALSE. In reality, the FALSE is the number 0. And TRUE is actually any other number. The most common values for TRUE are 1 or 255 but ANY positive value will due.
So if you wrote a FUNC that returns a 0 or a 1, you could use it in place of a conditional. This is a powerful use of FUNCs.
BYTE FUNC values_match(BYTE x,y)
BYTE rval
rval=0
IF x=10 AND y=20 THEN
rval=1
FI
RETURN(rval)
PROC main()
BYTE v1,
v2
PrintE("Please give me 2 numbers.")
Print("v1 = ")
v1=InputB()
Print("v2 = ")
v2=InputB()
IF values_match(v1,v2) THEN
PrintE("Your values match!!")
FI
RETURN
This is almost a trivial sample of the power this type of construct. If you have seen a program I wrote running on BBS Express! PRO called "The Wheel", 50% of that program is BYTE FUNCs that return a 1 or a 0 to IF FI statements.
Now, what if you need a variable that will be used by alot of PROCs and FUNCs? Do you keep sending it as a parameter? Well, you could, but using globals would be better.
We know that using a local variable doesn't affect any of the other variable used outside that PROC or FUNC. What if we want to change something in the outside program? Again, global variables are the answer.
A global variable is a variable that is not declared between a PROC and its RETURN or a FUNC and its RETURN. They are declared at the start of the program and between PROCs and FUNCs.
The compiler knows a variable is a global by use of the work MODULE. The word MODULE is assumed as the first line your program. But it never hurts to put it in. If you declare globals anywhere else in your program (like between PROCs etc.) then you MUST have the MODULE there.
MODULE
BYTE score
PROC you_win()
PrintE("You won this game!!!")
score = score +100
RETURN
PROC main()
you_win()
PutE()
Print("Your score is: ")
PrintCE(score)
RETURN
You can see that the value of score in the main() was increased by the "score = score +100" in you_win(). You can't do this with locals because when you change a local (this includes parameters too) it is only changed within that PROC or FUNC.
Try to resist the urge to use all globals in your programs. Globals make bugs nearly impossible to find. And there are times when you don't NEED a variable to change in the outside program.
When I first introduced PROCs I said that they were independent blocks of code. Using globals makes a PROC dependent on the rest of the program.
Lesson 9#
An ARRAY is a group of numbers that are the same type. Whether that means they are a BYTE, INT or CARD.
A string is something like this: "Hello, how are you today?"
So why are these 2 concepts begin presented in the same lesson? Because to a computer, they are the same thing. A string is just an ARRAY of BYTE values. But since a BYTE and a CHAR are EXACTLY the same thing, we will use CHAR just so we know that we are using that ARRAY as a string instead of just holding numbers. There is one small difference between strings and BYTE ARRAYs and we cover that in a little bit.
An ARRAY is a indexed group of numbers. Lets say you have 4 people playing a game and you want to keep track of all their scores. You could use 4 different variables like this:
PROC print_score()
BYTE score1,
score2,
score3,
score4
PrintF("Score 1: %U",score1)
PrintF("Score 2: %U",score2)
PrintF("Score 3: %U",score3)
PrintF("Score 4: %U",score4)
RETURN
Everytime you needed to do something with a persons score, you have to figure out who is playing and then use their particular score variable.
A better way is to use an ARRAY.
PROC print_score()
BYTE ARRAY score(5)
BYTE player
FOR player=1 TO 4
DO
PrintF("Score %U: %U",player,score(player))
OD
RETURN
Now any time you need a persons score, you just place that player's number in score( ) and it is given to you.
The declaration of an ARRAY is
type ARRAY name(dimension)
type can be any of the fundamental types; BYTE (CHAR), INT or CARD. The dimension is how big the ARRAY is going to be. In Action!, ARRAYs go from 0 to dimension-1. That is why we declared score(5), now the player numbers go from 0 to 4. We could have used score(4) but then the numbers would go from 0 to 3 and humans usually don't think that way.
The type has nothing to do with how big an ARRAY can be. The type is what the ARRAY will hold. For example, you can have this:
BYTE ARRAY total_pay(5000)
Now you can have 5000 employees but each can only have a pay of 0 to 255. (Sounds familiar huh?)
total_pay(1) = 210
total_pay(2) = 170
total_pay(3) = 250
total_pay(4) = 100
.
.
.
total_pay(4999) = 30
If you want to input a number into an array you could use:
PROC main()
CARD ARRAY lottery(10)
BYTE i
FOR i=1 TO 9
DO
lottery(i)=InputB()
OD
RETURN
You use ARRAY just like any normal variable, but you must subscript "(i) or something" each time you use it.
So, what is the difference between a ARRAY of BYTEs and a string? The zeroth (0th) BYTE of a string holds its length. For this reason, you can't do a direct assignment, the compiler won't let you. Here's what I mean:
CHAR ARRAY prompt(30) prompt="What is your guess? "
That is illegal. Instead, Action! provides you with a ton of PROCs and FUNCs to make working with strings easy.
To assign a string variable some text, you use:
SCopy(prompt,"What is your guess? ")
This just copies what ever is second into what ever is first. So you can also use:
SCopy(again,prompt)
This will make the variable "again" equal to the same text as the variable "prompt". This is assuming that "again" was dimensioned to the same size or bigger than "prompt".
Printing strings is easy, we just use the normal Print() and PrintE() we have always been using. Just now, you use the string name inplace of the text.
PrintE(prompt)
Inputing strings is a little different that inputing normal variables. Here we use:
InputS(prompt)
Notice that it is a PROC and not a FUNC.
Action! also has PROCs that take part of one string and copy them into another (sub strings) and taking a string and copying into part of another (appending or inserting). Look in you Action! manual on how to use these PROCs.
Another thing you can't do in Action! is compare string like this:
IF prompt=again THEN ...
You must use a built in FUNC that does this for you.
SCompare(prompt, again)
This FUNC returns an INT value. It return a number <0 if prompt is less than again. It return 0 if they are equal. And it returns a number >0 if prompt is greater than again.
This is great for alphabetization. In fact, APROG.902 does a little alphabetizing.
Before I let you go I have to tell you a little something I left off of ATUTOR.003.
In an IF statement, if the conditional is not true you can have an ELSE statement.
IF a>b THEN
PrintE("A is less than B")
ELSE
PrintE("A is greater than or")
PrintE("equal to B")
FI
Action! will execute the second part only if the first is not true. You can also have multiple IFs.
IF a>b THEN
PrintE("A is less than B")
ELSE
IF a=b THEN
PrintE("A is equal to B")
ELSE
PrintE("A is greater than or")
FI
FI
In fact, this happens so often that we have a special statement for it: the ELSEIF. The next example is the exact same thing as the above one.
IF a>b THEN
PrintE("A is less than B")
ELSEIF a=b THEN
PrintE("A is equal to B")
ELSE
PrintE("A is greater than or")
FI
The reason I am mentioning this now is APROG.901 uses both the ELSE and the ELSEIF.
Lesson 10#
Well, I guess its time to talk about files. Now, when I say files, I mean both files and devices. The only Atari device that uses files is the disk drive. But when it comes down to using files and devices, things are done the same.
Your Atari has a few devices built in to it when you turn it on.
E: - input and output - This is the standard Atari editor that is used. When you do a PrintE() or other simple output, this is the device it goes to. Also, when you do a InputB() this is the device it comes from. It is the screen and the keyboard combined.
C: - input and output - This is the cassette player.
P: - output only - This was originally meant to stand for parallel but Atarians now know it as printer. It makes sense that it is for output only, right?
S: - output only - This is the screen. This is the device that is opened by the Atari when you do a Graphics command. (We'll cover Graphics later in the tutorial.)
K: - input only - The keyboard. When you input information from the keyboard, nothing is echoed on the screen.
There are 2 more devices that we call standard, even though they aren't built in to you computer. They have to be loaded in before you can use them.
D: - input and output - Your disk drive. DOS must be loaded before you can use it. Also, a filename must be supplied when you first open this device.
R: - input and output - The RS232 port on the 850 or P:R: Connection. This is used by modems that need the interface.
There is also 1 custom device that is "famous" enough to merit me mentioning it here.
T: - input and output - This is your 1030 or XM301 modem.
OK, those are the devices. How do you use them? Good thing you asked. The first thing you must do before you can use a device, is open it.
Open(1,"K:",4,0)
The number "1" is the device number. After you open a device, from the then on you refer to it by its device number.
The "K:" is what device you want to open. It is a string and must either be in "quotes" or a CHAR ARRAY variable.
The next number is the command. Use this chart to find out which command to use.
| Access | Value |
|---|---|
| Input Only | 4 |
| Output Only | 8 |
| Input and output | 12 |
| Append to end of file | 9 |
| Disk drive directory | 6 |
Since a K: device can only do input, the number "4" is an easy choice.
Just because a device can do input and output DOES NOT mean you should choose the number 12. If you want to output to a disk file use 8. The reason the command number 12 is there is in a situation like this:
If you want to change the 5th BYTE in a file, you read the first 4 and then over write the 5th.
The last number "0" is required and there must always be a "0" there.
If you know BASIC, you will see there is a little difference between the order Action! uses and the order BASIC uses.
In BASIC it is like this:
OPEN #1,4,0,"K:"
The arguments mean the same things, just a different order.
To output to a file, you use the standard Atari Print PROCs except you put a D (for device) at the end in the proper place. For example, if you want to print a string with a carriage return on the end to a device, you'd use:
PrintDE(2,"Hi there")
The number "2" is the device number you assigned it in the Open(). This can be done to any device that can do output and the statement will be exactly the same.
Here are the output PROCs.
| Proc | output |
|---|---|
| PrintD | string |
| PrintDE | string with CR |
| PrintBD | BYTE |
| PrintBDE | BYTE with CR |
| PrintCD | CARD |
| PrintCDE | CARD with CR |
| PrintID | INT |
| PrintIDE | INT with CR |
The input statements are close to the normal input FUNCs as well.
b=InputBD(1)
Input a byte from device number 1.
Here are the input FUNCs.
InputBD - BYTE InputCD - CARD InputID - INT
And for strings:
InputSD(3,name)
This get a string from device number 3 and places it in name.
There are 3 more statements you can use with devices.
c=GetD(1) - get a single character from device number 1
PutD(1,c) - put a single character on device 1. PutDE(1,c) - same but CR after
InputMD(3,name,20) - Get a string from device number 1 and only 20 characters long.
When you are done with a device, you must always close it.
Close(4) - close device number 4.
There are a few things that are different when you use D:
The first is you must supply a filename. It can be 8 characters long with a 3 character extension.
Open(3,"D:MYFILE.DAT",8,0)
If you use a DOS that has subdirectories, they can be included in the device string as well.
If you use Open a disk file with a command number of 8, it will create a new file if it does not already exist or erase the old file if it does.
When you Open a disk file with command number 4, it always starts reading at the beginning.
It is a good idea to get in the habit of close a device number before you open it just to make sure it is ok to use. If you try to open a device number when it is already open, you program will bomb.
The device numbers that you are allowed to use are 1 though 7.
Lastly, every time you compile an Action! program, a BYTE ARRAY is automatically declared for you. The ARRAY is called "EOF". EOF holds either a 0 or a 1 so it can be used in a IF, WHILE or UNTIL statement.
When using disk or cassette files, you cannot try to read past the end of the file. If you do try, the program will crash.
So you have 2 choices, either you have to save the number of entries in that file and use a FOR loop to read in exactly that number of entries. Or use EOF.
EOF holds a 1 if you are at the end of file and 0 otherwise. For example:
EOF(2)
If device number 2 is at the end of the file, then this will be a 1. The best way to use EOF is in a WHILE loop because a WHILE loop checks before the loop is run the first time.
PROC read()
BYTE character
Close(1)
Open(1,"D1:ATUTOR.001",4,0)
WHILE EOF(1)=0
DO
character=GetD(1)
Put(character)
OD
Close(1)
RETURN
This PROC prints ATUTOR.001 on the screen character by character. The file ATUTOR.001 must be on the disk in disk drive #1 for this program to work. Also, you may have noticed that I didn't call it main() this time. Remember, you don't have to call it main().
This type of PROC might be good if you wrote a game and this will print the instruction file to the screen for the user.
You may also have noticed that reading character by character is not the most efficient way to do this. A better way would have been to read the whole line in with a InputSD() and echo it with a PrintE(). But to so this the last line must end with a CR before the end of file. If you KNOW that it does, you can use the next PROC instead. But, if you are unsure, you don't want to make assumptions. (By the way, ATUTOR.001 does have a CR before the end of file so it is OK to use this PROC)
PROC better_read()
BYTE ARRAY line(50)
Close(1)
Open(1,"D1:ATUTOR.001",4,0)
WHILE EOF(1)=0
DO
InputSD(1,line)
PrintE(line)
OD
Close(1)
RETURN
Lesson 11#
We have just finished pretty much of the basics of Action! Now it's time to get into the more advanced topic that Action! offers.
The first of these is the POINTER. A POINTER does not hold a value like a "normal" variable. Instead it tells us where that value physically is inside your Atari. To declare a POINTER we first have to declare what type it will point to.
BYTE POINTER a CARD POINTER b
There are 2 new operators that can be used with POINTERS. If we have a variable i of type INT we can use this:
INT POINTER g g=@i
This means g points to i. Well, it really mean that we have assigned g to point to the same memory location as i. g holds the memory location of i.
Another new operator we now have is:
g^=5
This says to put the value 5 into the memory location that g points to.
Try APROG11.001 and try and follow what is going on. You can see that POINTERs are a nice way of simulating the BASIC POKE command. But Action! has even better ways to accomplish that.
They say "A picture is worth a thousand words" to I'll try it now. I'll try and show you this PROC graphicly.
PROC m()
CARD c
CARD POINTER cp
c=10
cp=@c
cp^=6
RETURN
Ok, we have 2 objects to begin with: I'll use ? to mean we don't know for sure that these value hold since we didn't assign them to anything yet.
? ? cp cWhen the assignment c=10 come up the variable look like this:
? 10 cp c
When cp=@c is executed, cp is assigned to point to the memory location that c occupies. NOT to the value in c.
-------| 10 cp -------> c
Then, we change the value in the location cp points to to 6.
-------| 6 cp -------> c
I hope that helped a little.
Have you ever wanted to change the value of parameter you passed to a PROC or FUNC? Well, before now you have to create a global and not use a parameter at all. POINTERs allow you to keep PROCs and FUNCs independent by not using globals and allowing you to change the value of a parameter outside of the PROC.
PROC add(BYTE POINTER a) a^==+10 RETURN PROC main() BYTE a a=5 PrintBE(a) add(@a) PrintBE(a) RETURN
Well, I bet you are saying, "That's nice, I MIGHT use that once in a while, but big deal otherwise." I am going to introduce 2 more types of new Action! ideas then you will see the importance of POINTERs. We are going to leave POINTER for a moment to talk about 2 things. The first is VERY short. It is the Action! directive DEFINE. You use DEFINE to clarify your programs and make them easier to read. And they take up no extra memory so you can use tons of them without any overhead.
DEFINEs simply substitute one thing for another. We know from a previous APROG that Put(125) clears the screen. But you really can't tell that just by looking at it can you? But CLS looks like it might mean clear screen. So we can use:
DEFINE CLS = "Put(125)"
PROC m()
CLS
Print("hi")
Or you can use it like this:
DEFINE MAX = "25"
PROC any()
FOR i=1 TO MAX
DO
;read in values
OD
FOR i=1 TO MAX
DO
;print out values
OD
This way, if you want to increase the maximum number of entries, you only have to change the value in MAX, and all the times it is used are changed.
The next thing is records. You may have noticed that when you declare an ARRAY, all the items have to be the same type. All INTs, all CARDs etc. Records allow us to mix types into one object.
TYPE new = [ BYTE player_number,
points_per_game
CARD season_total,
lifetime_total ]
new bball_player
We have just made a new type of variable. When we use the
new bball_player
it is just like
INT g
"new" is the type and bball_player is the variable name. To use a record we have "dot notation". That is just a fancy way of saying we do this:
bball_player.player_number=12 bball_player.points_per_game=28 bball_player.season_total=300 bball_player.lifetime_total=InputC()
And to retrieve this information we can just:
PrintBE(bball_player.player_number)
I think this is a good time to stop. We have gone over alot in a short time and this stuff is pretty hard to get the hang of right away. And it is probably hard to think of what you can use this for. And your also saying, "Hey, you said there would be more with POINTERs!" We'll go over how to get more out of records using POINTERs next time.
Lesson 12#
Well, as you probably noticed in the last file that POINTERs and records aren't all that useful by themselves. In fact, I decided not to include a sample program about records because I couldn't think of a good example.
But, when you mix POINTERs and records you get alot of power. You may have tried to make a ARRAY of records. This is illegal in Action! But, if you use POINTERs to accomplish this it will work.
Also, you cannot have a ARRAY as a field in a record. Since strings are just CHAR ARRAYs, you can't, for example, associate a name with other information about a person. Again, POINTERs make this possible too.
Even more, you can't have ARRAYs of strings. You guessed it, POINTERs to the rescue again. I will be covering all of these in this lesson. You don't have to fully understand records and POINTERs to use the concepts I am introducing. You can just copy the routines, etc. and modify them for whatever use you have in mind. But, a good understanding of POINTERs will allow you to even more powerful things in Action!
First, how do you make an ARRAY of records in Action!? First you have to decide what your record will look like.
TYPE employee=[CARD ssnumber1
BYTE ssnumber2
CARD ssnumber3
BYTE department,
salary ]
Now we have to count up the total number of bytes in the record. CARDs and INTs take up 2 bytes and BYTEs take up 1. So, here we have 2 CARDs and 3 BYTEs for a total of 7.
DEFINE size = "7"
We have to decide how many records we want to hold. Our company is kind of small, we only have 6 employees. So, 6 employees each taking up 7 bytes. We have to reserve 42 bytes of memory to hold our information because 6*7=42.
BYTE ARRAY company(42)
Now its time to make that POINTER I have been talking about.
employee POINTER info
'employee' is the type of record that the POINTER will point to. 'info' is the name of the POINTER.
Lastly, you need an equation to figure out where in memory this really is. This equation is the same one we will use for all advanced record and POINTER manipulations.
info = company + (counter * size)
That's it!
label | use info | The name we gave our POINTER company | The ARRAY we used to reserve memory. counter | This is the record number we wish to look at. Since we have 6 employees this will be a number from 0 to 5. This can be a constant like 3 or a variable like in a FOR loop. size | The number of bytes in a record in our DEFINE line.
Ok, so how do you use it? Easy... If we want to enter employee number 3's information.
info = company + ( 3 * size) info.ssnumber1 = 392 info.ssnumber2 = 80 info.ssnumber3 = 4593 info.department = 3 info.salary = 7
And if employee #2 got a raise to paycode #10
info = company + ( 4 * size) info.salary = 10If you want to print employee #0's social security number:
info = company + ( 0 * size)
PrintC( info.ssnumber1)
Print("-")
PrintB( info.ssnumber2)
Print("-")
PrintCE( info.ssnumber3)
The numbers in the record can be used just like any other variable.
info.department = 4 * 5
Or whatever. Here is a little picture that I hope will help you to see what is going on. In case you didn't know, when you declare a ARRAY in Action!, the ARRAY name is actually a POINTER to where the ARRAY is in memory. So, let's say our ARRAY starts at memory location 16000. Also, I'll use - to represent bytes. So a CARD would have 2 bytes, --.
TYPE employee=[CARD ssnumber1
BYTE ssnumber2
CARD ssnumber3
BYTE department,
salary ]
record 0 record 1 record 2 -- - -- - -|-- - -- - -|-- - -- - -| ^ | 16000
To get record 1 we use this formula:
info = company + ( 1 * size)
Sticking in the numbers:
info = 16000 + ( 1 * 7) info = 16007
So, we move our pointer over 7 bytes to location 16007.
record 0 record 1 record 2
-- - -- - -|-- - -- - -|-- - -- - -|
^
|
16007
To get record 2:
info = 16000 + ( 2 * 7) info = 16014
So, we move our pointer over 14 bytes from location 16000 to 16014
record 0 record 1 record 2
-- - -- - -|-- - -- - -|-- - -- - -|
^
|
16014
But records can't contain strings. So POINTERs must be used again to trick Action!
What if you wrote a game where there are multiple levels. When the first player dies, the second player takes over, right where he left off. Well, you have to keep track of the players score, level and name. The score and level are easy with records, but the name? We'd use this:
TYPE record = [BYTE level
CARD score
BYTE name]
Why only 1 BYTE for the name? This is just the first BYTE of the players name. We'll save more space for it in a second. Count up the bytes without the name BYTE. 1 BYTE and 1 CARD = 3 bytes
DEFINE offset = "3"
We'll save 20 bytes for the name. So add the length of the name and the offset value for the size.
DEFINE size = "23"
How many players maximum can play our game? We'll just say 8. So, 8 * 23 = 184
BYTE ARRAY players(184)
Now we need 2 POINTERs. One like normal, and 1 to point to the name.
record POINTER active_player CHAR POINTER his_name
The first POINTER we use just like we have been before.
active_player = players + (count * size)
But to get the name we use:
his_name = active_player + offset
That's it! We'll so some assignments to record number 4.
active_player = players + (4 * size) his_name = active_player + offset active_player.level=1 active_player.score=0 InputS(his_name)
Now lets output player 6.
active_player = players + (6 * size)
his_name = active_player + offset
Print("Level: ")
PrintBE(active_player.level)
Print("Score: ")
PrintCE(active_player.score)
Print("Name: ")
PrintE(his_name)
Ok, the last situation like these is if you need an ARRAY of different size strings. Let's say a you need a program to keep track of your customers first name, lastname and the last date the ordered from you. We'll say the date is of the form mm/dd/yy.
How big to we want each field?
field | size in bytes firstname | 11 lastname | 14 date | 9
Try to declare your sizes 1 bigger because strings go from 0 to 1 less than their size. This is needed because, remember, the 0th byte is the length of the string.
There are no records involved this construct. Here we just use POINTERs to get around. The first DEFINE always starts at 0.
DEFINE firstname = "0"
If you want to the firstname to be 11 bytes, the lastname must start at the 12th byte. 0 + 12 = 12
DEFINE lastname = "12"
If the lastname is 14 bytes long the date must start 15 bytes later than the lastname. This means the 27 byte overall. 12 + 15 = 27
DEFINE date = "27"
The total size is 27 + 9 = 36
DEFINE size = "36"
How many customers do you have? Let's just say 100. 100 * 27 = 2700
BYTE ARRAY data(2700)
Since we don't have a record only characters, our POINTER is just:
CHAR POINTER ptr
The POINTER is just like normal
ptr = data + (counter * size)
Once again, that's it! For customer #53:
ptr = data + (53 * size)
Print("First name: ")
InputS(ptr + firstname)
Print("Last name: ")
InputS(ptr + lastname)
Print("Last order date: ")
InputS(ptr + date)
APROG12.002 is a full featured phone book based on this last subject.
Lesson 13#
Well, here we are at the last lesson of Part 1. And I have to apologize for this one. There are a lot of little things I want to mention. Most of them have nothing to do with any of the others.
The first has to do with assigning variables and routines to specific memory locations. You saw how you can use POINTERs to change memory locations (like the background color of the screen). But there is a better way. When you declare a variable, you can assign it to a location.
BYTE bkgnd=710
Now any change you make to bkgnd will go into location 710.
bkgnd=0
This will change the background color to black. You can also assign PROCs to specific memory locations too. That way, if there is a routine loaded into memory, you can call it easily.
PROC machine_routine=$3500 (BYTE ARRAY s)
In Part 2 of this tutorial we will use this quite a bit.
There is another thing you can do with variables where you declare them. You can assign them to a value using [square brackets\].
INT i=[-32] BYTE b=[0]
So, if you do a:
PrintIE(i) PrintBE(b)
you will get
-32 0
Square brackets are also used for inserting machine language subroutines in Action! programs. You can use hex values or decimal. You can even access Action! variable. Here's an example:
[$A9 my_val $2A $8D $CD $04]
Action! is very fast but sometimes you can use that little extra burst from machine language.
If you want your Action! code to compile to a specific memory location you just insert this at the start of your program.
SET 14 = $4000 SET $491 = $4000
Now you program will compile to location $4000.
- SET IS NOT LIKE A POKE! SET CHANGES
If you create a bunch of global routines that you in all your programs, you don't have to type them in each time. They can be loaded in while the program is compiling. That way they are compiled in with your code. You can INCLUDE a file anywhere as long as if is above whatever PROCs are going to call them. You usually INCLUDE files after the global variable and before your first PROC.
I have included a Public Domain runtime package. If you INCLUDE this when you compile your programs, they will work without the Action! cartridge. It would look like:
INT global1,
global2
INCLUDE "D:RUNTIME.ACT"
PROC My_first_proc()
.
.
.
RETURN
I mentioned that Action! predeclares some variables for you. There is an important one that HAS to be mentioned.
Normally, if you Action! program finds an error, it aborts. Your can trap errors by making PROCs that will execute when an error occures.
PROC my_error(BYTE errno)
Print("I found an Error number ")
PrintBE(errno)
RETURN
A BYTE parameter is always needed. To make Action! go to this PROC instead of aborting, you just put in:
Error = my_error
Lastly, Action! has the same graphics command built in as BASIC. I am not going to go into great detail on graphics. There have been thousands of magazine articles written on the subject. I will just list the BASIC graphics command and their Action! equivalents.
BASIC | Action! GRAPHICS 0 | Graphics(0) SETCOLOR 1,0,0 | SetColor(1,0,0) COLOR 2 | color=2 POSITION 3,4 | Position(3,4) PLOT 10,10 | Plot(10,10) DRAWTO 20,20 | DrawTo(20,20)
I have not listed all the routines in the Action! library. There are sound and game controller routines as well as a ton more.
Take a look at your Action! manual again. Hopefully you will understand it better than the first time you opened it and said "What does that mean?!?"
Well, I hope you all have enjoyed this tutorial. Action! is a great programming language and Action! programmers are very friendly.
Stay tuned for Part 2, writing programs for BBS Express! Pro.
Tom
