Getting Started with TRANSACT (32247-90007)

Chapter 8 147
Special Topics
Intrinsics
The example is a program that builds a file using the COMMAND intrinsic and then
writes a record to the file using the FOPEN and FWRITE intrinsics.
Line 21 sets up the buffer for the COMMAND intrinsic to be the BUILD command. The
buffer for a command has to end with a [[RETURN]] which is what lines 22 and 23
accomplish.
Line 41 executes the FOPEN intrinsic. This line illustrates several important points to
remember when calling intrinsics. The intrinsics manual describes the information we
need to know about both the intrinsic and the data being passed to it.
The first parameter passed to the FOPEN intrinsic is the formal designator or filename of
the file to be opened. It is a byte array. The % in front of the first parameter tells Transact
that this parameter is to be passed as a byte array.
The next parameter is the foptions. This is a word that FOPEN interprets groups of bits as
a description of the attributes of the file. The bit numbering convention is from left to right
starting with bit 0 and ending with bit 15. In line 36, we established a value for fopt with
only bit 15 on. This specifies the file domain to be an old permanent file. The # tells
Transact to pass this parameter by value to the intrinsic.
The parameter to satisfy the aoptions is also passed by value.
The remainder of the FOPEN parameters do not need to be specified for our use of the
intrinsic. However, there is one special case parameter which we need to consider, which is
the filesize parameter. This parameter is a double word parameter that is passed by value.
Transact does not know anything about the data types that intrinsics expect. It expects
you to provide that information. This works great and is easy to do for all data types except
optional double by value. When an option variable intrinsic contains this kind of
parameter, pass the parameter with either the default value in those cases where you don't
care what the parameter value is or with the needed value in those cases where you do
care. This assures that the correct number of words are passed to the intrinsic when
called.
Another special thing about this intrinsic is that it is an option variable intrinsic. This
means a bit map must be passed to the intrinsic telling it which parameters are being
passed to it. The intrinsic expects 13 parameters. Thus one word is passed to the intrinsic
with the first 13 bits of the word designating those parameters passed. In our example,
parameters 1, 2, 3, and 10 were passed, so the first three and the 10th bits of the bit map
word are set on in line 38 (1110000001000 to the base 2 is equal to 7176 to the base 10).
The last special thing about this intrinsic is that it is a function intrinsic which means it
returns a value to you. The very last parameter we pass it is the parameter to hold this
data. The & in front of the parameter tells Transact that this is where the value returned
is to be placed.
Line 43 executes the FWRITE intrinsic to write the data we specified to the file opened in
line 41.