MAXScript Tools and Interaction with 3ds Max > OLE Automation >

# 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].countis constant for i = 1 todataArray.count,dataArray[i][j].countis constant for j = 1 todataArray[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:

- SafeArrayWrapper values can be passed to OLE methods as arguments, and can passed to/from ActiveX control methods. Arrays passed to OLE or ActiveX methods are automatically converted to intermediate SafeArrayWrapper values.

- The following additional variant types for values returned by OLE objects can converted to MAXScriptvalues: VT_UI2, VT_UI4, VT_INT, VT_NULL, VT_VOID

- Color values are converted to VT_I4 variant values when passed to OLE objects.

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