At some point during the execution of your assembly language routine, you might want to accomplish the other half of this method of communication with BASIC - namely, changing the value of a BASIC variable which is used as an argument, in effect changing the value of a BASIC variable from the assembly language routine.
As with retrieving a value, there are a number of utilities available for changing a value. The one to use is dependent upon the type of argument passed. The utilities available are
-Name Used For
Put value Simple variables, strings and individual elements of arrays passed as arguments
Put element Elements (from arrays passed as arguments) Put_bytes Substrings of strings passed as arguments
either as simple variables or as individual elements of arrays passed as arguments.
Put_ elem _bytes Substrings of elements (from string arrays passed as arguments)
Example Parameters Alpha,A$,B$(lO),Array(2,3) Array( *),Z$(*)
String $,Z$(2,3)
Note that these utilities modify variables existing in the BASIC environment. They do not modify the length of the variables as dimensioned in BASIC.
How each of these utilities is used is described in the immediately following pages.
UTILITY: Put value
General Procedure: The utility is given the address of the parameter declaration and the address of the value. It changes the value of the BASIC variable associated with the parameter.
It works only on simple variables, expression strings, and individual elements of arrays (passed as arguments) of any type.
Special Requirements:
• The value must have the appropriate data structure for the data type of the argument (see
"Data Structures" in Chapter 3) .
• An actual argument must have been passed by the ICALL for the utility to work properly.
Calling Procedure:
1. Load register A with the address of the storage area of 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 al\vays returns to the instruction following the call.
Here is an example call to the utility, passing information to an integer
argument-~ .-. --: ::--.. . ; -I ::~ l_~_i r=:: L t.
ISaJRCE Parameter: INT
Here is an additional example demonstrating string passing
-UTILITY: Put element
General Procedure: This is similar to the "Put_value" utility. This utility changes the value of a single element in an array passed as an argument. It works on arrays of any type.
Special Requirements:
• The value must have the appropriate data structure for the data type of the argument (see
"Data Structures" in Chapter 3).
• 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 for the array (word 16 returned by "Get_info"). It should be remembered that the relative element number of the element is dependent upon the number of dimensions in the array and the length of each. A calculation may be necessary to arrive at the offset when accessing multiple-dimension arrays.
• The storage area must lie within the ICOM region.
Calling Procedure:
1. Store the element offset into the array information (word 16).
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.
Here is an example call, storing information from Value into element 0 of an integer array -ISOURCE Value: BSS
ISOURCE Array info:BSS ~;
ISOURCE SUB
I~:;Ci~JF:C:E F·.:it---:t.r(~E·tE·t"·: Ir~T (*)
I~;:;ctIPCE
I ~:;OUF~CE
I:;:;OURCE I:;:;OURCE
UTILITY : Put_bytes
L.uH =An-·.a:=--,_ i nfc L:D:B =F.3.t-·.::t.rf~~"t E'f-'
LIlA =0:1
LI;:B =Ar-·r-.3..=) i rl'fc=
-.r=;t·1 F't~t. E" 1 E'rfi~:-t"tt
I Set offset tc 0
General Procedure: This is similar to the "Put_value" utility. This utility changes the value of a substring which is part of a string variable or an individual element of a string array, having been given the starting byte and the number of bY.tes to be changed as well as the new characters.
Special Requirments:
• The bytes to be transferred are preceded by two words in the storage area. The two words contain the starting byte for the substring and the number of bytes to be transferred .
• A string variable or an element of a string array must have been passed as an argument for the utility to work properly.
Calling Procedure:
1. Store the number of the starting byte of the substring to be changed into the first word of the storage area. (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. 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, so it always returns to the instruction following the call.
For example
-_r-,_ . ___ . _..:.. __ _ -r-·::if '.:::i.~!;i=:~: .. =::"r'
In this example, Value is the storage area containing the string to be transferred. Since 2 has already been generated and stored in the first word, and 10 in the second, the first 10 bytes of the string are changed. 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: Put_ elem _bytes
General Procedure: This is a combination of the "Put_element" and "Put_bytes" utilities.
This utility changes a substring of an element in a string array which has been passed as an argument. The utility is given the starting byte and the number of bytes to be transferred.
Special Requirements:
• The bytes to be transferred are preceded by two words in the storage area. The two words contain the starting byte for the substring and the number of bytes to be transferred.
• The array information for the array 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 for the array (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 calculation may be necessary to arrive at the offset when accessing multiple-dimension arrays. The offset is in terms of number of elements. 1
Calling Procedure:
1. Store the number of the starting byte of the substring to be changed into the first word of the storage area. (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 element offset into the array information (word 16).
4. Load register A with the address of the storage area for the string to be transferred.
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.
1 See the description of calculating array offsets under the "Get_info" utility.
For example
-I::<tiPCE I::;OUPCE
LIlA =2
LIlA =\,'-3. 1 UE'
LIIB =Ary·a.::..' info .E;l'j P,-rl:. eleri"! b:: .... t.e:::.
I Set offset to 2
In this example, Value is the storage area for the string to be transferred. 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 changed. It is the responsibility of the software (not shown) to assure that 10 characters of valid data are stored in the remainder of the storage area.