CHAPTER 26. USING THE 4TH API 492
72
6C
64
21
00
D6 l r d
!
<null>
Checksum
Why this elaborate scheme? Well, for two reasons. First, it allows HX-code to be portable across a wide range of platforms
2
. Second, it is very compact. If we would write out all numbers in full, most space would be occupied by zeros. That would be a waste, especially when embedding HX-files. The speed penalty is negligible.
26.6
A first look at comp_4th()
The function comp_4th() is one of the most complex and most important functions of the API. It takes a source and compiles that to H-code. If you want to save the source, copy it or reload it, since comp_4th() consumes it entirely. That is why source has to be allocated in dynamic memory. On the other hand, it explains why compilation needs very little memory.
If comp_4th() can’t compile anything, it returns just the header, containing all the information on what went wrong and where. If there is not enough memory to allocate even the header it returns a NULL-pointer. If it could compile part of the code it returns what it could compile. But that might not be everything and you need it all to get a program you can execute.
Lucky for you, but the API can determine whether comp_4th() returned an executable
H-code or not. If exec_4th() doesn’t execute the program, it just couldn’t.
The comp_4th() function is just as smart. It can survive the NULL pointer you feed it.
When you read on, you’ll find out that the comp_4th() function is a toolkit by itself with lots of tools to create your own 4tH words.
If we extend the example we started with open_4th(), we could continue like this. In order to make an executable H-code we feed source to comp_4th() and get H-code in return. We just need a pointer to store its address:
Hcode *Program;
So the entire 4tH-compiler now looks like: char *source;
Hcode *Program; source = open_4th ("venture.4th");
Program = comp_4th (source);
We assume you want to execute the program you’ve just compiled, so we’ll continue with the interpreter-function called exec_4th().
2
As long as the 7-bit ASCII characterset is supported. EBCDIC HX-files will not be portable for obvious reasons.
