SafeArrayWrapper Class

Instances of SafeArrayWrapper are creatable by the user and are returned by OLE methods that return SAFEARRAY values. Available in 3ds Max 8 and higher.

 

Constructor:

SafeArrayWrapper ()

SafeArrayWrapper < data array >

SafeArrayWrapper < data array > < lBounds array >

 

Properties:

<SafeArrayWrapper>.dataArray

Data array. May be 'undefined'. The dataArray is a set of nested arrays. The dataArray must be "square", ie., the number of elements in the dataArray at any given dimension is constant. For example,

dataArray[i].count is constant for i = 1 to dataArray.count, dataArray[i][j].count is constant for j = 1 to dataArray[2].count.

A runtime error will be thrown if dataArray is set to a non-square array. The depth of the array is it's dimension. A dimension 2 array is where dataArray[i][j] is a non-array data value. Setting dataArray will change the number of elements in lBoundsArray to match, with added elements having the value 0.

<SafeArrayWrapper>.lBoundsArray

Lower bounds array. May be 'undefined'. Array of size dimensions, where each element contains the lower bound of one dimension of the array. This array is used for creating the OLE SAFEARRAY value from the SafeArrayWrapper. When setting lBoundsArray, its size must be 'dimensions' or a runtime error will be thrown,

< SafeArrayWrapper >.dimensions

Number of dimensions in data and bounds array. Read only.

 

Methods:

copy < SafeArrayWrapper >

Returns a new SafeArrayWrapper, a deep copy is performed on the data and bounds array

 

Notes:

 

Examples:

Example tests which show in part retrieving data from an SQL database using the GetRows method:

 

-- open sql database and get rows

DogConn = createOLEObject "ADODB.Connection"

DogConn.Open "driver={SQL Server}; server=dsqedb01.autodesk.com; database=MXSTest"

recordSet = createOLEObject "ADODB.Recordset"

recordSet.Open "SELECT * from TestTable" DogConn

a = recordSet.GetRows()

 

-- display data properties

a.dataArray

a.lBoundsArray

a.dimensions

 

-- create a new SafeArrayWrapper using data array and lbounds array

b = SafeArrayWrapper #(#(1, 1.2345, "One point two three four five", undefined, undefined, undefined), #(2, undefined, "Float is null", undefined, undefined, undefined), #(3, 0.0, " ", undefined, undefined, undefined), #(4, 123.4, undefined, undefined, undefined, undefined)) #(0, 0)

b.dataArray

b.lBoundsArray

b.dimensions

 

-- create a new SafeArrayWrapper using data array

d = SafeArrayWrapper a.dataArray

d.dataArray

d.lBoundsArray

d.dimensions

 

-- create a new SafeArrayWrapper via copy, show it is a deep copy

f = copy a

f.dataArray

f.lBoundsArray

f.dimensions

f.dataArray[1][1] = 999999

f.dataArray

a.dataArray

 

 

Example of updating an SQL database, where the update method is passed array or SafeArrayWrapper values:

 

DogConn=createOLEObject "ADODB.Connection"

DogConn.Open "driver={SQL Server}; server=dsqedb01.autodesk.com; database=MXSTest"

recordSet = createOLEObject "ADODB.Recordset"

recordSet.Open "SELECT * from TestTable" DogConn 1 3-- adOpenKeyset adLockOptimistic

fields=recordSet.Fields -- print out column names

count = fields.count

for i = 1 to count do (local item = fields.item (i-1); print item.name)

recordSet.GetRows() -- display current contents

recordSet.AddNew #("arbitraryFloat", "arbitraryChar", "boolean", "arbitraryInt") #(pi,"Hello World",true,42) -- add via array

recordSet.AddNew (SafeArrayWrapper #("arbitraryFloat", "arbitraryChar", "arbitraryInt")) (SafeArrayWrapper #(e/pi,"Merry xmas!", 54321)) -- add via SafeArrayWrapper

recordSet.close()

recordSet.Open "SELECT * from TestTable" DogConn

recordSet.GetRows() -- display current contents

 

Example of getting/setting an ActiveX control property with SafeArrayWrapper:

 

rollout controlR86 "Microsoft Chart Control 6.0 (SP4) (OLEDB)"

(

activeXControl ax "{3A2B370C-BA0A-11D1-B137-0000F8753F5D}" height:200 width:300 align:#left setupEvents:false

)

createdialog ControlR86 height:250 width:350

data = ControlR86.ax.chartdata -- returns SafeArrayWrapper

ControlR86.ax.chartdata = SafeArrayWrapper #(#(undefined, "R1", "R2", "R3", "R4", "R5"), #("C1", 1, 2, 3, 4, 5), #("C2", 1, 2, 3, 4, 5), #("C3", 5, 4, 3, 2, 1), #("C4", -1, 2, 3, 2, 1))

 

Conversion between MAXScript values and OLE variant values:

 

OLE à MAXScript:

VT_EMPTY

VT_NULL

undefined

VT_VOID

OK

VT_UI1

VT_UI2

VT_UI4

VT_I2

VT_I4

VT_INT

Integer

VT_R4

VT_R8

VT_CY

Float

VT_BSTR

String

VT_BOOL

Boolean

VT_DISPATCH

OLEObject

VT_ARRAY | VT_VARIANT

SafeArrayWrapper

 

MAXScript à OLE:

SafeArrayWrapper

Array

VT_ARRAY | VT_VARIANT

Integer

VT_I4

Float

VT_R4

Boolean

VT_BOOL

Color

VT_I4

String

VT_BSTR

Undefined

VT_EMPTY

OLEObject

VT_DISPATCH

 

The following information is taken from the document "Accessing Data with ADO" from MSDN
(ms-help://MS.MSDNQTR.2003OCT.1033/iisref/htm/AccessingDatawithADO.htm)

The following table lists OLE DB connection strings for several common data sources:

Data Source

OLE DB Connection String

Microsoft Access

Provider=Microsoft.Jet.OLEDB.4.0;Data Source=physical path to .mdb file

Microsoft SQL Server

Provider=SQLOLEDB.1;Data Source=path to database on server

Oracle

Provider=MSDAORA.1;Data Source=path to database on server

Microsoft Indexing Service

Provider=MSIDXS.1;Data Source=path to file

To provide for backward compatibility, the OLE DB Provider for ODBC supports ODBC connection string syntax. The following table lists commonly used ODBC connection strings:

Data Source Driver

ODBC Connection String

Microsoft Access

Driver={Microsoft Access Driver (*.mdb)};DBQ=physical path to .mdb file

SQL Server

DRIVER={SQL Server};SERVER=path to server

Oracle

DRIVER={Microsoft ODBC for Oracle};SERVER=path to server

Microsoft Excel

Driver={Microsoft Excel Driver (*.xls)};DBQ=physical path to .xls file; DriverID=278

Microsoft Excel 97

Driver={Microsoft Excel Driver (*.xls)};DBQ=physical path to .xls file;DriverID=790

Paradox

Driver={Microsoft Paradox Driver (*.db)};DBQ=physical path to .db file;DriverID=26

Text

Driver={Microsoft Text Driver (*.txt;*.csv)};DBQ=physical path to .txt file

Microsoft Visual FoxPro (with a database container)

Driver= {MicrosoftVisualFoxProDriver};SourceType=DBC;SourceDb=physical path to .dbc file

Microsoft Visual FoxPro (without a database container)

Driver= {MicrosoftVisualFoxProDriver};SourceType=DBF;SourceDb=physical path to .dbf file