RealVision home
   
  DxMidi - OMS support  
Summary
Implementation
Availability
Sign In/Out
Setting buffers
Sending events
Receiving events
OMS support
Sysex support
Result codes

DxOMSStudioSetup
DxOMSMidiSetup
DxOMSFilterIN
DxOMSFilterOUT
DxOMSGetNodes
DxOMSPlugOutNode
DxOMSPlugInNode
DxOMSGetNodeOutName
DxOMSDisconnectINNode
DxOMSGetNodeInName

DxOMSNodesINDial
DxOMSGetNodeInUniqueID
DxOMSGetNodeOutUniqueID
DxOMSPlugInUniqueID
DxOMSPlugOutUniqueID
DxOMSWorldChanged

OMS connection system is slightly different than Midi manager. You work with patchbay in the Midi Manager, or you work with «Nodes» into OMS.
The node is either a real input or output (to or from a Midi interface), or a virtual device (software connection to patch, drive data...).
These nodes are managed by OMS as low level, and you can keep control of these connection to patch into them.
DxMidi plugin permits you to connect one IN and one OUT to the OMS MIDI studio.
Call first the DxOMSconnect() method to sign-in, next you can either see the studio, the connections and devices connections made by OMS (call OMSStudioSetup() or OMSMidiSetup()), or get the nodes for IN and OUT sockets to select :

- one or more connections to other nodes
(eg. real interface IN, virtual INs).

- one connection to the output node
(eg. real interface OUT, QuickTime Instruments, etc.).

The DxMidi Patcher in one-Out-connected to simplify the time-access of your app.

To add rich selection for patching studio, OMS provide properties to filter types of nodes.
See interface constants to add themselves for Node-filtration.



Err = DxOMSStudioSetup ()
Err as Boolean

This function activates a high-level function (
OMSOpenCurrentStudioSetup()in the OMS sdk).
OMS recommends that all OMS-compatible applications contain a menu command, Open Current OMS Setup, or OMS Studio Setup..., located immediately before OMS MIDI Setup...
It would be wonderful to add yours in a big final release for «courteous» OMS compatibility.

Err is False if the call generated an error. Never call the function if you are not sure that an OMS connexion is active, this could give you an impredicable arror.



Err = DxOMSMidiSetup ()
Err as Boolean

Final commercial applications may have a MIDI Setup... (or OMS MIDI Setup...) menu command. This function activates a high-level function (
OMSMIDISetupDialog()in the OMS sdk).

Err
is False if the call generated an error. Never call the function if you are not sure that an OMS connexion is active, this could give you an impredicable arror.



Err = DxOMSFilterIN ( filters )
Err as Boolean
filters as Integer

OMSFilterIN sets the node-visibility of the MIDI input socket of your DxMidi connection. You can use different types of constants and add them to create the mode value.

Example :

To see the inputs, real inputs and virtual inputs, set filters:

dim omsIncludeInputs, omsIncludeReal , omsIncludeVirtual as integer
omsIncludeInputs = 1
omsIncludeReal = 4
omsIncludeVirtual = 8
filters = omsIncludeInputs + omsIncludeReal + omsIncludeVirtual


filters = 1 + 4 + 8 = 13).

interface constants :
omsIncludeInputs = 1
omsIncludeOutputs = 2
omsIncludeReal = 4
omsIncludeVirtual = 8
omsIncludeSync = 16
omsIncludeSyncOnly = 32
omsMergeOutputsByPort = 64
omsIncludeSecret = 128

You could define all these constants as properties in a class (may be reusable?) and use these constants to implement your code.

Err returns FALSE if an error occured



Err = DxOMSFilterOUT ( filters )
Err as Boolean
filters as Integer

Like OMSFilterIN,
OMSFilterOUT sets the node-visibility of the MIDI Output socket of your DxMidi connection. You can use different types of constants filters and add them to create the mode value. See interface constants.

Err returns FALSE if an error occured



result = DxOMSGetNodes ( mode )
result as Integer
mode as Integer

To send or receive datas, you must first call nodes to patch your app. The
OMSGetNodes, get information about all available nodes for IN and OUT. Set the filter property before calling method (See DxOMSFilterIN(), DxOMSFilterOUT()).
For Output nodes, set
mode = 0, For inputs, set mode = 1.
The result is the number of nodes found. The nodes list is kept and stay valid in memory from now until a DxOMSWorldChanged() detects modifications in the OMS studio. You are limited to 64 nodes inputs/outputs and can access to nodes by number by the following functions.
Result returns a standard DxMidi error code.



result = DxOMSPlugOutNode ( node )
result as Integer
node as Integer

This connect your OUT OMS MIDI socket to a node specified. Note that the socket can only be connected to ONE NODE at time. But it’s easy to change
node attribution because this method is only a choice, and not a real connection made. You can acces to DxOMSPlugOutNode() anytime and anywhere you like in your program, but remember that you must call DxOMSGetNodes(0) before to create a list of nodes.
Result is the error code.
kOMS_nodeListError indicates that the list is invalid (or not initialized).
Don’t try to plug when DxOMSWorldChanged() detected a modification in the studio... the nodes will be invalid and you could create an OMS error.

NOTE : node parameter starts at 1 :
If DxOMSGetNodes found 3 nodes for example in the result code, the first node will be 1,
the last: 3. You can then call this code :

numberNodes = DxOMSGetNodes(0)
if numberNodes > 0 then
for i = 1 to numberNodes
  result = DxOMSPlugOutNode (i)
  result = DxNoteON (1, 64, 64)
  
// time passes
  result = DxNoteON (1, 64, 0)
next
end if



result = DxOMSPlugInNode ( node )
result as Integer
node as Integer

This call creates a connection between your DxMidi control MIDI OMS IN socket and any nodes detected with DxOMSGetNodes(1). This will create a real connection.
If you call this method with different
nodes, you will connect all theses nodes at the same time.
Call DxOMSDisconnectInNode (node) to cut the connection made.
Don’t connect to a node invalid or obsolete. If you plan to memorize the nodes of your studio into file and create a prefs file for studio, verify the studio compatibility when you restart the app and prevent the user for any moves or modifications.

NOTE :
nodes parameter starts at 1, like OMSPlugOutNode().



name = DxOMSGetNodeOutName( node )
name = DxOMSGetNodeInName( node )
name as String
node as Integer

This call the node listed and identified by his number after DxOMSGetNodes(), and reply the
name. Useful to create a popup with all the nodes detected and let the user choose the nodes.
Remember that there is two lists, one for In and one for OUT.

node : the node number into the INput or OUTput list.


name = DxOMSDisconnectINNode( node )
name as String
node as Integer

This call the node listed and identified by his number after DxOMSGetNodes(), and disconnect the INput connection between OMS and DxMidi. Remember that there is two lists, one for IN (the concerning list) and one for OUT.

node : the node number into the INputs list.



result = DxOMSNodesINDial ( prompt, multi )
prompt as string
multi as Boolean
result as Integer

This is a specific call made to the OMS facilities. It’s not a DxMidi dialog but an OMS service. We added the capability of connecting the ports selected to the OMS IN DxMidi socket.

Call DxOMSFilterIN() to specify the filters.
Call DxOMSDisconnectInNode() to close the ports anytime.

If
multi = true then you let the user selecting multiple nodes.
prompt sets the info text in the OMS dialog.
NOTE : There is no link between this call and the INputs list created with DxOMSGetNodes(1).



result = DxOMSGetNodeInUniqueID ( node )
result = DxOMSGetNodeOutUniqueID ( node )
result as Integer
node as Integer

You can use this to get the unique ID of a member of the
nodes list (after a call to DxOMSGetNodes()), and keep this ID into memory or prefs to create automatic patches in your studio on starting. See examples tips and tricks to implement this. The UniqueID is a value that is not modified by the OMS dynamically. But if you change your location studio, you will need to remap the nodes again because de ID may be different. Result code is 0 when the uniqueID cannot be found.



result = DxOMSPlugInUniqueID( uniqueID )
result = DxOMSPlugOutUniqueID( uniqueID )
result as Integer
uniqueID as Integer

Connection is made by this function with the
uniqueID obtained by DxOMSGetNodeInUniqueID() or DxOMSGetNodeOutUniqueID(). result is 0 if the unique ID cannot be found.


result = DxOMSWorldChanged ()
result as Boolean

If
result = true then OMS prevents your application that the studio structure has changed.
You must reconsider to send DxOMSGetNodes(0) and DxOMSGetNodes(1) again.