IDMRegIniFile Interface

Version: 2.0
Dispatch interface for DMIniFile and DMRegistry objects

GUID: {673AAF0D-9A0B-11D4-B2A4-FD6847C75367}

This interface includes methods and properties for objects used for persistent storage of structured information like application configuration settings.

In the typical scenario you open appropriate object (at this time Items collection will be filled with the names of data records), then you manipulate data records and, finally, delete object or open another data storage.

Members:
Kind Name ID Description
Open 101 Open key/section
Items 102 Return value names collection
Value 103 Change selected value
Delete 104 Delete selected value

Syntax:
function Open(Name, ReadOnly): Boolean

Applies to:
CoCPortLib2, CPortLibX2, DMAppHelper, DMClientSocket, DMComPort, DMComTerminal, DMDLLHelper, DMIEEE488Port, DMIniFile, DMRegistry

For DMINIFile, Open method opens selected INI file (Name parameter) and fills Values collection with either section names or parameter names. Open() includes some name parsing: section name (if any) should be delimited by * character from file name and by # character for URLs.

For DMRegistry, Name parameter must be full path to the selected registry key. Use RegEdit to copy-and-paste appropriate values.

WARNING: because of security reasons, the functionality of DMRegistry intentionally limited to those operations required by DM2003. In particlar, root key is ALWAYS read-only, some other keys are just unavailable.

DMDLLHelper, DMINIFile and DMRegistry Open() returns True if operation successfull, and False otherwise. For URLs DMINIFile.Open always return True, and INI file always is read-only. As of DMForms build #300, DMDLLHelper also supports URLs.

Currently for DMAppHelper, Open member does nothing and does not use parameter. It just returns true if API reference is valid, while actually connects to DM2003 at the control creation moment.


For DMIEEE488Port, DMClientSocket and RS-232 port controls Settings parameters of the Open() method determine port settings. It doesn't return any result. Notice that CPortLibX2, CoCPortLib2, DMClientSocket, DMComPort and DMComTerminal support "binary" mode of communication.

Examples:

' DMINIFile:
if DMINIFile.Open("C:\MyFile.ini", false) then
if DMINIFile.Open("http://server/path/file.txt#Columns", true) then

' DMRegistry:
const Key="HKEY_CURRENT_USER\Software\RRR\DM2003\Data Master" 
if DMRegistry.Open(Key, true) then 


' DMComPort, DMComTerminal:
' open COM4, 9600bps, no parity, 8 data bits, 1 stop bit, 
' character mode, asynchronous write mode
call DMComPort.Open("4,9600,0,8,0,0,-1") ' full string
call DMComPort.Open("4")                 ' short string

' or use array of parameters
dim Settings(5)  ' Settings(6) - for use Async Write mode
Settings(0)=4    ' COM port number 1, 2, ...  
Settings(1)=9600 ' baud rate (110, 300, 600, ... 256000)
Settings(2)=0    ' parity: 0=None, 1=Odd, 2=Even, 3=Mark, 4=Space
Settings(3)=8    ' data bits: 5..8
Settings(4)=0    ' stop bits: 0=OneStopBit, 1=One5StopBits, 2=TwoStopBits
Settings(5)=0    ' mode: -1=binary, 0=character (default)
'Settings(6)=-1    write mode: -1=asynchronous, 0=synchronous (default)
call DMComPort.Open(Settings)

' DMIEEE488Port:
call DMIEEE488Port.Open("IEEECTRL") ' open command file
call DMIEEE488Port.Open(True)       ' open command file
call DMIEEE488Port.Open("IEEEDATA") ' open data file
call DMIEEE488Port.Open(False)      ' open data file

' DMDLLHelper:
if DMDLLHelper.Open("C:\path\APIdescription.ini") then
b=DMDLLHelper.Open("http://datamaster2003.com/samples/dll/dllhelpertest.ini")

' CPortLibX2, CoCPortLib2:
ComPort1.Open 1, 9600, 0, 8, 0

See also:
DMINIFile, DMRegistry, DMComTerminal, DMComPort, DMIEEE488Port test pages.

Syntax:
r/o property Items: PTR

Applies to:
DMComboBox, DMContainer, DMDigitizerContainer, DMExpressionComboBox, DMIniFile, DMLabels, DMListBox, DMListItems, DMRegistry, DMStrings

For DMINIFile, Items return either collection of INI file sections (if no section was defined in the Open method) OR the collection of names of records in the selected section. Use Value() property to access section contents (or Value) of the selected record. For DMRegistry, Items return the collection of names of the records (values) under the selected registry key.

Items collection filled in the Open method and is read-only. Don't try to change it anyway. Use Value() property to change values.

For DMComboBox, DMExpressionComboBox and DMListBox, Items represent a read/write collection of strings in the appropriate control.

For DMContainer and DMDigitizerContainer, Items is a parameterized property - an array of data items ("for each" cycle still can be performed on the object itself). Each data item is a variant array of double-precision numbers. Notice that for DMDigitizerContainer, you can only read Items. For DMContainer, you may assign either variant array OR just a properly formatted string to the Items() property.

For DMListItems and DMStrings, Items is a parameterized property that returns (or changes) a string selected by Index parameter (0..ItemCount-1).

For DMLabels collection, this is a default, parameterized (0..ItemCount-1) property that returns references to the DMLabel objects.

Syntax:
property Value[Name]: Variant

Applies to:
DMFloatEdit, DMIniFile, DMRegistry, DMSpinEdit

For DMINIFile, Value should be used to change either contents of the selected section or the "value" part of the selected record (after "=" character). Section value treated as a bulk text, without Name=Value separation. For DMRegistry, Value() property should be used to change registry values.

If appropriate object was opened in the read-only mode, setting Value will have no effect. Parameter Name is either integer index (ranged from 0 to Items.ItemCount-1) or the string-type name of the value.

For DMSpinEdit and DMFloatEdit, Value property just wraps around appropriate Delphi VCL property. Unlike Text, it has numeric type.

Example:

dim INI, S, Ss
set INI=CreateObject("DMForms.DMINIFile")
S=""
if INI.Open("C:\MyFile.ini*MySection", true) then
  for each Ss in INI.Items
    S=S & Ss
  next
  MsgBox S  
end if

See also:
DMINIFile, DMRegistry test pages.

Syntax:
function Delete(Name): VOID

Applies to:
DMIniFile, DMLabel, DMNotes, DMPlot, DMRegistry, DMSerie, DMWorksheet

For DMRegistry and DMINIFile, Delete method deletes selected Value (or INI file section). Name parameter is either name or index in the Items collection. If object was opened in the Read-Only mode, Delete call will have no effect.

For DMNotes, DMPlot and DMWorksheet objects Delete method has no parameters and should be used to delete selected data range in the appropriate objects: selected text, worksheet cells or "selected" points (points whose coordinates belong to selected plot area) in the current plot serie. Note that for DMPlot, if selection is not visible, all points from the current plot serie will be deleted.

For DMSerie and DMLabel, this method just deletes the object. It acts as the appropriate method of owner collection (DMPlot or DMLabels).