EWD 3 Training Course Part 28: Integrating Legacy Mumps Code with QEWD

Copyright © 2016 M/Gateway Developments Ltd

EWD 3 Training CoursePart 28

Integrating Legacy Mumps Codewith QEWD

Rob TweedDirector, M/Gateway Developments Ltd

Twitter: @rtweed


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


Equivalent to:

set result=$$myFunc^theRoutine(arg1,arg2)

var result = this.db.function({function: 'myFunc^theRoutine',arguments: [ arg1, arg2]

});

Invoking a function


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


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


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)


Node.jsCaché

GT.M

C C

allin

Inte

rface

cache.node

NodeM

In-process Connection


Node.js

CachéGlobalsDB

GT.M

C C

allin

Inte

rface

cache.node

NodeM

process.pid $job


One-to-one correspondence


Node.js

CachéGlobalsDB

GT.M

C C

allin

Inte

rface

cache.node

NodeM

process.pid $job

new this.documentStore.documentNode('temp', [process.pid]) ^temp($job)


These refer to the same thing!


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 functionvar result = this.db.function({function: 'myFunc^theRoutine',arguments: []});



• 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 inputsmerge inputs=^temp($j)

• You've now picked up the complex input data for the function!



• 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 globalmerge ^temp($j)=outputsQUIT 1 ; function has finished



• 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();


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


Invoking Legacy Mumps Codewith 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 casetemp.setDocument(myComplexInputData);

// now invoke the Mumps functionvar result = this.db.function({function: 'myFunc^theRoutine',arguments: []});

// Mumps function has finished – process its outputsvar outputs = temp.getDocument();temp.delete(); // clear down the temporary global

// the complex output data from the Mumps function is now in the // outputs object


Invoking Legacy Mumps Codewith complex I/O

myFunc()new inputs,outputsmerge inputs=^temp($j); process inputs and put output data into outputs array; invoke any legacy procedures, functions etckill ^temp($j)merge ^temp($j)=outputsquit 1

The corresponding Mumps wrapper function

EWD 3 Training Course Part 28: Integrating Legacy Mumps Code with QEWD

Software

Transcript of EWD 3 Training Course Part 28: Integrating Legacy Mumps Code with QEWD