HUGEARR.DLL Huge array support for Microsoft Visual Basic from Microsoft Product Support Services 6/4/91 with additions by various authors The following information applies to Microsoft Visual Basic programming system version 1.0 for Microsoft Windows, and to Microsoft Windows 3.0 Software Development Kit (SDK). HUGEARR.DLL is a dynamic-link library (DLL) which contains functions for creation, maintenance, and deletion of arrays larger than 64K from Microsoft Visual Basic version 1.00 for Windows. This DLL also gives the ability to create arrays with more than 32,767 (32K) elements per dimension, and to redimension arrays while preserving the data inside of the arrays. To use the functions in HUGEARR.DLL, simply copy the declarations contained in HUGEARR.VBG into your global module in Visual Basic, copy the declarations in HUGEARR.VBM into any module, and copy HUGEARR.DLL to your Windows directory. The functions can then be used like any other Windows DLL function. HUGEARR.DLL allocates memory using the Windows API function GlobalAlloc. This means that the largest array that can be allocated is 1 MB in standard mode, and 64 MB in 386 enhanced mode for Windows. The following routines are contained in HUGEARR.DLL. For a complete description of the parameters and/or return values of these routines, see Visual Basic's Declare statement for the routine in question in the file HUGEARR.VBM. HUGEARR.DLL Language Reference: ------------------------------ ------------------------------------------------------------------------- VBHugeDim: Action: Dimensions an array and returns a handle to that array. Syntax: VBHugeDim(recsize%, limit&) Argument Description -------- ----------- recsize% The size of each element in the array. (i.e. an integer would be 2, a double would be 8.) You can use the Len() function to determine the size of any data type if you are unsure. limit& The upper bound of the array. The lower bound of all arrays is 0, so for example: 'VBHugeDim(2, 10)' would create an integer array of elements 0 through 10. Remarks: ------- You should not try to create a huge array of variable-length strings, or of a user-defined type that contains variable-length strings. Visual Basic's string handling routines would not know of the existence of any string that was controlled by HUGEARR.DLL, and a UAE ("Unrecoverable Application Error") would probably result. Fixed-length strings are okay though. VBHugeDim returns a handle to the array that was created, and that handle is used when referring to that array with other commands. If an error occurred (such as out of memory), it will return a negative number. Error codes are detailed below under the section entitled 'Error Codes'. Example: ------- Sub Command1_Click() Dim hArray as integer Dim variable as SomeUserDefinedType hArray = VBHugeDim(Len(variable), 10) If hArray < 0 Then print "Error dimensioning array:"; hArray Stop End If . . . i% = VBHugeErase(hArray) End Sub ------------------------------------------------------------------------- VBHugeErase: Action: Erases an array that was previously dimensioned using VBHugeDim. Syntax: VBHugeErase(hArray%) Argument Description -------- ----------- hArray% The handle to the array. (The same handle that was returned by VBHugeDim.) Remarks: -------- You should be sure to VBHugeErase all arrays that were VBHugeDim'd. Failing to do so would cause the memory used by the array to not be freed up until the application quits. If many arrays are dimensioned but never erased memory would keep being allocated without being freed, eventually degrading system performance. Example: Refer to the example for VBHugeDim. ------------------------------------------------------------------------- VBHugeRedim: Action: Redimensions an array created with VBHugeDim to a different size. Syntax: VBHugeRedim(hArray%, limit&) Argument Description -------- ----------- hArray% The handle to the array to redimension. limit& The new upper bound of the array. Remarks: -------- VBHugeRedim, unlike Visual Basic's ReDim, preserves all the data in the array. If you want to erase the contents of the array, you should erase it and the dimension it again. If the size of the array would go over 64K when it is redimensioned, it is subject to the same size restrictions detailed in the discussion of VBHugeDim. You cannot change the size of the elements in the array, only the number of elements. Example: -------- Sub Command1_Click() . . i% = VBHugeRedim(hArray, 50) if i% < 0 then print "error redimensioning array:"; hArray stop End If e% = VBHugeErase(hArray) End Sub ------------------------------------------------------------------------- VBHugeGet, VBHugeSet: Action: Gets or sets the contents of an array element. Syntax: VBHugeGet(hArray%, el&, variable) VBHugeSet(hArray%, el&, variable) Argument Description -------- ----------- hArray% The handle to the array. el& The element of the array to set or get the data from. variable The variable to get into, or to set the array from. Remarks: -------- It is extremely important that the type for the variable passed to VBHugeGet or VBHugeSet matches that type of the variable used in the VBHugeDim statement, if the types are of different lengths, you will mostly likely get a UAE or overwrite other data. If you want to be sure that the types match you can use the Alias keyword when you declare the function to introduce type checking. Refer to the section below entitled 'Aliasing' for more information on aliases. Example: -------- Sub Command2_Click() . . . hArray = VBHugeDim(len(i%), 10) If hArray < 0 Then Stop e% = VBHugeSet(hArray, 1, 54%) ' puts 54 into element #1 If e% < 0 Then Stop ' check error code e% = VBHugeGet(hArray, 1, i%) ' get element #1 into i% Print i% e% = VBHugeErase(hArray) End Sub ------------------------------------------------------------------------- VBHugeGetNum, VBHugeSetNum: Action: Gets or sets the contents of multiple array elements. Syntax: VBHugeGetNum(hArray%, el&, nelem%, variable) VBHugeSetNum(hArray%, el&, nelem%, variable) Argument Description -------- ----------- hArray% The handle to the array. el& The first element of the array to set or get the data from. nelem% The number of elements to be set or fetched. variable The variable to get into, or to set the array from. Remarks: -------- See the Remarks for VBHugeGet, VBHugeSet. Example: -------- Sub Command2_Click() . . Dim VBArray() as Double ReDim VBArray(1 to 1000) ' Assign something to the elements in VBArray. . . hArray = VBHugeDim(len(i#), 1000) If hArray < 0 Then Stop ' Copy 1000 elements from VB array VBArray(1...1000) to huge array. e% = VBHugeSetNum(hArray, 1, 1000, VBArray(1)) ' check error code If e% < 0 Then Stop ' Copy 1000 elements from huge array to VB array VBArray(1...1000). e% = VBHugeGetNum(hArray, 1, 1000, VBArray(1)) e% = VBHugeErase(hArray) End Sub ------------------------------------------------------------------------ VBHugeSave: Action: Saves the specified number of elements of a huge array to the named file. Syntax: VBHugeSave(hArray%, NEl&, RecLen%, Fn$) Remarks: ------- The number of elements to save as well as the size of each element, together with the full filename of the file to be written to must be spupplied. Example: -------- Sub Command6_Click() ErrCode& = VBHugeSave(hArray, hArrayElements&, hArryRecLen%, "FILE.ARR") If ErrCode& < 0 Then Stop End Sub --------------------------------------------------------------------------- VBHugeLoad: Action: Loads a huge array from the named file. Syntax: VBHugeLoad(hArray%, RecLen%, Fn$) Remarks: ------- The file is read until EOF is found. The number of element read are returned unless an error occurs. The Array to be loaded must be allocated sufficient space to hold the array before this function is called. Example: -------- Sub Command7_Click() Open "MYFILE.ARR" For Random As #1 Len = hArrayRecLen% hArrayElements& = LOF(1) / hArrayRecLen% Close #1 hArray = VBHugeDim(hArrayRecLen%, hArrayElements&) If hMain > 0 Then hArrayElements& = VBHugeLoad(hArray, hArrayRecLen%, "MYFILE.ARR") If hArrayElements& < 0& Then Stop Else Stop End If End Sub ----------------------------------------------------------------------- VBHugeInt: VBHugeLong: VBHugeSingle: VBHugeDouble: VBHugeCurrency: Action: Retrieves an element from an array of a given type. Syntax: VBHugeInt(hArray%, el&) VBHugeLong(hArray%, el&) VBHugeSingle(hArray%, el&) VBHugeDouble(hArray%, el&) VBHugeCurrency(hArray%, el&) Argument Description -------- ----------- hArray% The handle to the array. el& The element to retrieve. Remarks: -------- This family of functions is provided as a shortcut alternative to VBHugeGet to retrieve a given data type while in an expression. For example: value = VBHugeDouble(hArray, 0) * VBHugeDouble(hArray, 1) The example above could have been done using VBHugeGet; however, the values returned by the two VBHugeDouble calls would have to be assigned to variables, and then the variables would be used in the expression. The example below expands more on this. IMPORTANT: None of these functions return error codes, so you should use them only if you are positive that the value of hArray% and el& are legal values. If a error does occur (such as a "Subscript Out of Range"), you will get meaningless results. You should use VBHugeGet if you need to be able to check error codes. Example: -------- Sub Command3_Click() Dim hArray As Integer hArray = VBHugeDim(len(i%), 10) If hArray < 0 Then Stop e% = VBHugeSet(hArray, 0, 3%) ' Put 3 in element #0 If e% < 0 Then Stop ' Check for errors e% = VBHugeSet(hArray, 1, 4%) ' Put 4 in element #1 If e% < 0 Then Stop e% = VBHugeGet(hArray, 0, i%) ' Get value of element #0 If e% < 0 Then Stop e% = VBHugeGet(hArray, 1, j%) ' Get value of element #1 If e% < 0 Then Stop Print Sqr(i% ^ 2 + j ^ 2) ' Alternate (and faster) ' way of doing the above. Print Sqr(VBHugeInt(hArray, 0) ^ 2 + VBHugeInt(hArray, 1) ^ 2) e% = VBHugeErase(hArray) End Sub ------------------------------------------------------------------------- VBHugeUbound: Action: Returns the upper bound of a give array. Syntax: VBHugeUbound(hArray%) Argument Description -------- ----------- hArray% The handle to the array. Remarks: -------- This function is the same as Basic's 'Ubound' function. It is used to return the current upper bound of an array. If VBHugeUbound returns an negative value, it represents an error code. Example: -------- Sub Command4_Click() Dim hArray as integer hArray = VBHugeDim(len(i%), 23) If hArray < 0 Then Stop for J& = 0 to VBHugeUbound(hArray) ' Initialize array to 10's ErrCode% = VBHugeSet(hArray, J&, 10%) If ErrCode% < 0 Then Stop Next J& . . . End Sub ------------------------------------------------------------------------ VBHugeNumArrays: Action: Returns the number of free huge arrays available. Syntax: VBHugeNumArrays() Remarks: ------- This command is included mostly for debugging purposes. It is used to find out how many array could be dimensioned at that time by the program. Example: -------- Sub Command5_Click() Debug.Print VBHugeNumArrays() End Sub --------------------------------------------------------------------------- Error Codes: All functions (except for VBHugeInt, VBHugeLong, VBHugeSingle, VBHugeDouble, and VBHugeCurrency) return error codes as described below. The possible error codes are: 0 The function was successful. -1 "Out of Memory" There is not enough global memory for the VBHugeDim or VBHugeRedim -2 "To Many Arrays" There are no free arrays left to be dimensioned. -3 "Bad Element Size" This error condition is no longer possible. -4 "Subscript out of Range" The array element you are trying to access is outside the bounds of the array. -5 "Illegal Array Handle" The array that was referenced is not a valid array. Either it is not dimensioned, or the handle value is illegal. -7 "Error Opening File" The file specified could not be opened. -8 "Error Writing to File" An error occurred during a file write operation -9 "Error Reading File" An error occurred during a file read operation ------------------------------------------------------------------------ Aliasing: The VBHugeGet and VBHugeSet functions transfer data back and forth from an array. Because these functions must work with any data type, they are declared 'As Any' in their declarations. This has the disadvantage that it defeats Basic's built-in type checking, and allows the posibility of passing the wrong data type. To work around this potential problem, you can use Basic's 'Alias' keyword in the declaration. For example, if you wanted VBHugeGet to work with the data type 'UserType', you might rename the function to 'GetUserType', and alias it to 'VBHugeGet'. The declaration for VBHugeGet contained in "HUGEARR.BAS" is: Declare Function VBHugeGet Lib "hugearr.dll" (ByVal Index%, ByVal el&, buffer As Any) As Integer To force Basic to do type checking on the call, you would rewrite the declaration to be: Declare Function GetUserType Lib "hugearr.dll" Alias "VBHugeGet" (ByVal Index%, ByVal el&, buffer As UserType) As Integer Note that the 'buffer As Any' has been changed to 'buffer As UserType'. Because the function no longer has the 'As Any' type Basic will be able to raise an error if you try to pass the wrong data type. A function can be aliased any number of times, so you may want to create an alias for each data type that you are using. ----------------------------------------------------------------------- Constants: The VBHugeSet routine is used to assign values to an array. For example, the following statement i% = VBHugeSet(hArray, 1, v%) would assign the value stored in v% to element #1 of the array hArray. However, a problem can arise when you try to use a constant in place of the 'v%' above. For example: i% = VBHugeSet(hArray, 1, 15) In this case, Visual Basic would assume that the number 15 is an integer constant and would pass a pointer to an integer to the VBHugeSet routine; even if hArray is a (for instance) array of double-precision numbers. To work around this potential problem, you should always use a type suffix when passing constants to VBHugeSet. If you wanted to assign the value of 15 to a double precision array, you would use the statement: i% = VBHugeSet(hArray, 1, 15#) -------------------------------------------------------------------------- HUGEARR.DLL Memory and Capacity: HUGEARR.DLL allocates memory using the Windows API function GlobalAlloc. This means that the largest array that can be allocated is 1 MB in standard mode, and 64 MB in 386 enhanced mode. If you forget to VBHugeErase an array that was allocated with VBHugeDim, Windows will automatically deallocate the memory after your application terminates. However, HUGEARR.DLL keeps the information it needs to maintain the arrays in it's own private area. This means that any array which is not VBHugeErase'd will not have it's information released, and the array will not be marked as free. If two applications are both using the DLL, and the first application VBHugeDim's all of the arrays and then quits without VBHugeEraseing them, the second application will not be able to create any arrays. -------------------------------------------------------------------------- References: HUGEARR.DLL is written in Microsoft C, and the C source code is provided with this application note in HUGEARR.C and HUGEARR.H. The following references discuss how to program Windows 3.0 DLL routines: 1. "Programming Windows: the Microsoft Guide to Writing Applications for Windows 3," by Charles Petzold (published by Microsoft Press, 1990) 2. Microsoft Windows 3.0 Software Development Kit