At some point during execution of your assembly language routine, you may want to retrieve the value of an argument so that you can use it in your processing. By doing so, you accomplish one of the methods of communicating with assembly language - namely, passing a value to the assembly language routine from BASIC.
There are a number of utilities for this purpose. The one to use is dependent upon the type of argument passed. The utilities available are
-Name Get value Get element Get_bytes
Get_ elem _bytes
Used For
Simple variables, expressions, individual elements of arrays passed as arguments, and file numbers Elements (from arrays passed as arguments) Substrings of strings passed as arguments either as simple string variables, expressions, or individual elements of arrays passed as arguments
Substrings of individual elements (from string arrays passed as arguments)
Example Parameters Alpha,2*SIN(2),A$, "ABC", B$(10),Array(2,3),#5 Array( * ),2$( *)
"DEF" ,String$,B$&C$, 2$(2,3 ),2$[5,6]
How each of these utilities is used is described in the immediately following pages.
UTILITY: Get value
General Procedure: The utility is given the address of the parameter declaration and the address where the value of the argument is to be stored. It returns with that value stored in the indicated area. It works on simple variables, expressions, strings, and individual elements of arrays (passed as arguments) of any type.
Special Requirements:
• The storage area set aside for the value must be large enough to hold the value. The size of the storage area must
be-for a file number for an integer value for a short-precision value for a full-precision value for a string
1 word 1 word 2 words 4 words
maximum length in bytes -:- 2
+
1 word (+ 1 additional word if the maximum string length is odd)• An argument must have been passed by the ICALL (in the case of parameters) or a corresponding BASIC COM declaration must exist (in the case of common declarations) .
• The storage area must lie within the ICOM region.
Caiiing Procedure:
1. Load register A with the address of the storage area for the value.
2. Load register B with the address of the parameter declaration.
3. Call the utility.
Exit Conditions: There are no error exits from the utility. It always returns to the instruction following the call.
In the case that it is used to pass a string value, the Get_value utility returns the entire dimensioned string (which includes all characters between the current length and the dimen-sioned length of the string).
Here is an example call to the utility, retrieving information from a full-precision
argument-'-'"-'"-' .:].
: : _ . _ _ _ . _.:.. _ . _ c r-·::i.f "·:::i.np::":." t:"f' I:
UTILITY: Get element
General Procedure: This is similar to the "Get_value" utility. This utility retrieves a value from an element of an array passed as an argument. It works on arrays of any type.
Special Requirements:
• The storage area set aside for the value must be large enough to hold the value. The size of the storage area must be
-for an integer
for a short-precision value for a full-precision value for a string
1 word 2 words 4 words
maximum length in bytes-:-2 + 1 word (+ 1 additional word if the maximum string length is odd)
• The array information must be retrieved with the "Get_info" utility before calling this utility.
• The offset of the element in the array must be correct in the array information (word 16 returned by "Get_info"). It should be remembered that the offset of the element is dependent upon the number of dimensions in the array and the length of each. A calcula-tion may be necessary to arrive at the offset when accessing multiple-dimension arrays.
The offset is in terms of number of elements. 1
• The storage area must lie within the ICOM region.
Calling Procedure:
1. Store the element offset within the array information (word 16 returned by "Get-info").
2. Load register A with the address of the storage area for the value.
3. Load register B with the address of word 0 of the information returned by the "Get_
info" utility (see description of that utility).
4. Call the utility.
Exit Conditions: There are no error exits from the utility. It always returns to the instruction following the call.
1 See the description of calculating array offsets under the "Get_info" utility.
Here is an example call, retrieving the third element (relative element 2) of an integer array and placing it into Value
-UTILITY: Get_bytes
i0Fn+1~ Element Offset
LIlA ::::Hr-·r-·,3.:) i ~-~f':::::
~ T!L: =F~.3.(··.::tf{~E·t. E"r-'
~et element offset
General Procedure: This is similar to the "Get_value" utility. This utility retrieves a substring of a string passed as an argument, having been given the starting byte and the number of bytes to be retrieved.
Special Requirements:
• The storage area set aside for the substring must be large enough to hold all of the substring. This includes not only the string itself, but also two extra words. Remember, a word holds two characters.
• A string must have been passed by the ICALL for the utility to work properly.
• The storage area must lie within the ICOM region.
Calling Procedure:
1. Store the number of the starting byte of the substring desired into the first word of the storage area set aside for the substring. (Note that bytes
a
and 1 are the length word of the string.)2. Store the number of bytes in the substring into the second word of the storage area.
3. Load register A with the address of the storage area.
4. Load register B with the address of the parameter declaration.
5. Call the utility.
Exit Conditions: There are no error exits from the utility. It always returns to the instruction following the call. The substring is returned starting with the third word of the storage area.
(Note: Since the second word contains the length of the substring, you have a string data structure starting with the second word!)
For
example-In this example, Value is the storage area. Since 2 has already been generated and stored in the first word, and 10 in the second, the first 10 bytes of the string would be transferred. Of course, the original string must contain at least 10 characters - or the bytes which are returned may be nonsense. Why was the value 2 stored as the byte number? Because bytes in a string are numbered starting with 0, and bytes 0 and 1 contain the length of the string (see "Data Structures" in Chapter 3).
UTILITY: Get_elem_bytes
General Procedure: This is a combination of the "Get_element" and "Get_bytes" utilities.
This utility retrieves a substring of an element of a string array passed as an argument. The utility is given the starting byte and the number of bytes to be retrieved.
Special Requirements:
• The storage area set aside for the substring must be large enough to hold all of it. This includes not only the string itself, but also two extra words. Remember, a word holds two characters.
• The array information must be retrieved with the "Get_info" utility before calling this utility.
• The offset of the element in the array must be correct in the array information (word 16 returned by "Get_info"). It should be remembered that the offset of the element is dependent upon the number of dimensions in the array and the length of each. A calcula-tion may be necessary to arrive at the offset when accessing multiple-dimension arrays.
The offset is in terms of number of elements. 1
• The storage area must lie within the ICOM region.
1 See the description of calculating array offsets under the "Get_info" utility.
Calling Procedure:
1. Store the number of the starting byte of the substring desired into the first word of the storage area set aside for the substring. (Note that bytes 0 and 1 are the length word of the string. )
2. Store the number of bytes in the substring into the second word of the storage area.
3. Store the offset within the array information.
4. Load register A with the address of the storage area for the value.
5. Load register B with the address of word 0 of the information returned by the "Get_
info" utility (see description of that utility).
6. Call the utility.
Exit Conditions: There are no error exits from the utility. It always returns to the instruction following the call. The substring is returned starting with the third word of the storage area.
(Note: since the second word contains the length of the substring, you have a string data structure starting with the second word!)
For
example-ISOURCE IS3 5
c~u Array info+16 ! Element WT-_~
I Set element offset to 2
23M ~7 e em bytes
In this example, Value is the storage area. Since 2 has already been generated and stored in the first word, and 10 in the second, the first 10 bytes of the string element are transferred. Of course, the string element must contain at least 10 characters - or the bytes which are re-turned may be nonsense.