1.
Copyright © 2016 M/Gateway Developments Ltd
EWD 3 Training Course
Part 28
Integrating Legacy Mumps Code
with QEWD
Rob Tweed
Director, M/Gateway Developments Ltd
Twitter: @rtweed

2.
Copyright © 2016 M/Gateway Developments Ltd
Integrating Mumps Code
• Use the cache.node function() API
– function() is also available in the NodeM
module for GT.M
• Invokes a Mumps extrinsic function
• May need to create an extrinsic function
wrapper around existing Mumps logic in
order to invoke it from Node.js / JavaScript

3.
Copyright © 2016 M/Gateway Developments Ltd
Equivalent to:
set result=$$myFunc^theRoutine(arg1,arg2)
var result = this.db.function({
function: 'myFunc^theRoutine',
arguments: [ arg1, arg2]
});
Invoking a function

4.
Copyright © 2016 M/Gateway Developments Ltd
The function() result
• The value returned by a function() call can
be a very large string
– So it's possible to use it to return stringified
JSON
• However this would require a Mumps JSON
parser/generator to create the JSON string
– These tend to be slow
– Some are un-reliable

5.
Copyright © 2016 M/Gateway Developments Ltd
Limitations of the function() API
• Arguments are limited to simple variables
– Numeric or strings
• Cannot pass arguments by reference
– So you can't get complex data structures in
and out of a function via arguments

6.
Copyright © 2016 M/Gateway Developments Ltd
Is Legacy Mumps integration possible?
• Yes!
• The trick is to use a temporary Global as a
means of passing complex data in and out
of a Mumps wrapper function
• We can make use of the fact that the
cache.node (and NodeM) interface runs
in-process with Caché (or GT.M)

7.
Copyright © 2016 M/Gateway Developments Ltd
Node.js
Caché
GT.M
CCallinInterface
cache.node
NodeM
In-process Connection

8.
Copyright © 2016 M/Gateway Developments Ltd
Node.js
Caché
GlobalsDB
GT.M
CCallinInterface
cache.node
NodeM
process.pid $job
In-process Connection
One-to-one correspondence

9.
Copyright © 2016 M/Gateway Developments Ltd
Node.js
Caché
GlobalsDB
GT.M
CCallinInterface
cache.node
NodeM
process.pid $job
new this.documentStore.documentNode('temp', [process.pid]) ^temp($job)
In-process Connection
These refer to the same thing!

10.
Copyright © 2016 M/Gateway Developments Ltd
Integrating Legacy Code
• On Node.js side, before calling the legacy
Mumps function:
– Use setDocument() to create complex input
data in a temporary global, subscripted by
process.pid, eg:
var myComplexInputData = { // create your complex input data here};
var temp = new this.documentStore.documentNode('temp', [process.pid]);
temp.setDocument(myComplexInputData);
// now invoke the Mumps function
var result = this.db.function({function: 'myFunc^theRoutine',arguments: []});

11.
Copyright © 2016 M/Gateway Developments Ltd
Integrating Legacy Code
• In the Mumps function:
– The complex input data is accessible in
^temp($j) and its sub-tree of nodes, so:
– Merge out the inputs from ^temp($j)
new inputs
merge inputs=^temp($j)
• You've now picked up the complex input
data for the function!

12.
Copyright © 2016 M/Gateway Developments Ltd
Integrating Legacy Code
• In the Mumps function:
– Invoke your Mumps code to process the inputs
– Put the complex output data into a local array
– Merge the array back into the temporary global, eg
new ouputs
; put your output data into this array, then:
kill ^temp($j) ; clear down the temporary global
merge ^temp($j)=outputs
QUIT 1 ; function has finished

13.
Copyright © 2016 M/Gateway Developments Ltd
Integrating Legacy Code
• Back on the Node.js side
– Pick up the results from the temporary global
using getDocument()
– Delete the temporary global's document node,
eg:
var outputs = temp.getDocument();
temp.delete();

14.
Copyright © 2016 M/Gateway Developments Ltd
Integrating Legacy Code
• Remember that because QEWD uses ewd-
qoper8, it allows us to safely use the
synchronous cache.node APIs
• So invoking a Mumps function is synchronous in
QEWD
• Your JavaScript logic will therefore wait until the
Mumps function has completed before
continuing
– It doesn't matter if the Mumps code Hangs or waits on
a Lock

15.
Copyright © 2016 M/Gateway Developments Ltd
Invoking Legacy Mumps Code
with complex I/O
var myComplexInputData = { // create your complex input data here};
var temp = new this.documentStore.documentNode('temp', [process.pid]);
temp.delete(); // clear it down just in case
temp.setDocument(myComplexInputData);
// now invoke the Mumps function
var result = this.db.function({function: 'myFunc^theRoutine',arguments: []});
// Mumps function has finished – process its outputs
var outputs = temp.getDocument();
temp.delete(); // clear down the temporary global
// the complex output data from the Mumps function is now in the
// outputs object

16.
Copyright © 2016 M/Gateway Developments Ltd
Invoking Legacy Mumps Code
with complex I/O
myFunc()
new inputs,outputs
merge inputs=^temp($j)
; process inputs and put output data into outputs array
; invoke any legacy procedures, functions etc
kill ^temp($j)
merge ^temp($j)=outputs
quit 1
The corresponding Mumps wrapper function