dcDB Overview of Stored Procedures

DivConq Framework’s MUMPS API

Overview of DivConq database handling and Request-Response flow

Linux, Windows Linux Box or OS X Box Java App SSH MUMPS w/ DivConqJava code connects to the MUMPS database via an SSH connection. This keepsthe data secure while in transit.

Linux Box Java App SSH MUMPS w/ DivConqOf course there is no reason why Java cannot run on the same box. SSH is stillused, connecting over the loopback network interface.

Linux, Windows Linux Box or OS X Box Session Java App MUMPS w/ DivConq ChannelsOne SSH session is used. Multiple SSH channels enable greater throughput.Typically DivConq uses three channels, which creates three MUMPS processes.

Linux, Windows Linux Box or OS X Box Java App MUMPS w/ DivConqCommunication is Request-Response only, requests are originated in Java andresponses are supplied by MUMPS code.By using three channels, up to three requests can be processed at once. A longrunning request does not hold up other requests.

Structure Name: [Stored Procedure Name] Kind: “Update” or “Query” Params: [any JSON-like data structure] Example Name: “dctListPeople” Kind: “Query” Params: { “MinAge”: 30, “MaxAge”: 48 }Your code builds a request and submits it to DivConq’s database interface. Arequest must have a name and a kind, parameters are optional. Name = name ofthe stored procedure. Kind will be Update only if it changes data within thedatabase (Insert, Update, Delete), otherwise use Query.

Java App MUMPS DivConq w/ DivConq Database Interface MUMPS Process Request Your Queue MUMPS Database Request Workers Application Verifier Process Code #1 Response MUMPS Verifier Process DivConq Schema#1 - Your code builds a request and submits it. Request submission isasynchronous, so you also must provide a callback to handle the result.

Java App MUMPS DivConq w/ DivConq Database Interface MUMPS Process Request Your Queue MUMPS Database Request Workers Application Verifier Process Code #1 Response MUMPS Verifier Process #2 DivConq Schema#2 – Your request is verified, including validating the parameters with what isdeclared in the schema.

Java App MUMPS DivConq w/ DivConq Database Interface MUMPS Process #3 Request Your Queue MUMPS Database Request Workers Application Verifier Process Code #1 Response MUMPS Verifier Process #2 DivConq Schema#3 – If verification passes your request is put on to the request queue.

Java App MUMPS DivConq w/ DivConq Database Interface MUMPS Process #3 Request #4 Your Queue MUMPS Database Request Workers Application Verifier Process Code #1 Response #4 MUMPS Verifier Process #2 DivConq Schema#4 – When a database worker (channel) is available, it takes the request from thequeue and sends it to MUMPS.

Java App MUMPS DivConq w/ DivConq Database Interface MUMPS Process #3 Request #4 Your Queue MUMPS Database Request Workers Application Verifier Process Code #1 Response #4 MUMPS Verifier and Process #2 #5 DivConq Schema#5 – That worker then reads (blocking) the result and any accompanyingdebug/error messages.

Java App MUMPS DivConq w/ DivConq Database Interface MUMPS Process #3 Request #4 Your Queue MUMPS Database Request Workers Application Verifier Process Code #1 Response #4 MUMPS Verifier and Process #2 #5 #6 DivConq Schema#6 – The response is verified by validating the (JSON-like) result with what isdeclared in the schema. If response does not validate, error messages areadded to messages collected from MUMPS.

Java App MUMPS DivConq w/ DivConq Database Interface MUMPS Process #3 Request #4 Your Queue MUMPS Database Request Workers Application Verifier Process Code #1 Response #4 MUMPS #7 Verifier and Process #2 #5 #6 DivConq Schema#7 – The response and any debug/error messages are delivered to your code viaa the callback you provided at submission.

Request-Response handling within Java

Example RecordStruct ages = new RecordStruct(); ages.setField("MinAge", 3); ages.setField("MaxAge", 8);Parameters are composed of JSON-like structures. In DivConq use RecordStructto compose records (aka Objects in JSON) and ListStruct to compose lists (akaArrays in JSON). Records (aka Objects) have fields – just as in JSON – the fieldvalues may be lists, records or scalars. Above we are using numeric scalars.

Example RecordStruct ages = new RecordStruct(); ages.setField("MinAge", 3); ages.setField("MaxAge", 8); QueryRequest request = new QueryRequest("dctListPeople", ages);Create the request object. The Name and Kind are required. Kind can bederived from the class name (QueryRequest vs UpdateRequest). Name is thefirst parameter to the constructor. The parameters, optionally, follow the name inthe call to the constructor.

ObjectCallback callback = new ObjectCallback() { @Override public void process(ObjectResult result) { System.out.println("Messages:"); TestDb.printPretty(result.getMessages()); System.out.println(); System.out.println("Result:"); TestDb.printPretty(result.getResult()); } };You also need to create a callback object. This example callback simply printsthe messages and results to the console as JSON output. You may call“getResultAsRec” (RecordStruct) or “getResultAsList” (ListStruct) to process theresult using DivConq’s JSON-like API.

Example RecordStruct ages = new RecordStruct(); ages.setField("MinAge", 3); ages.setField("MaxAge", 8); QueryRequest request = new QueryRequest("dctListPeople", ages); ObjectCallback callback = new ObjectCallback() ... Hub.instance.getDatabase().submit(request, callback);Finally, to get the request to the database call the “submit” method and pass inthe request and callback. Your result, even if it is just an error message, will bepresented in the callback’s “process” method.

<Procedure Name="dctListPeople" Execute="listPeople^dctToyTest"> <Description> Get a list of names of all people in test data. Optionally apply an age range filter </Description> <RecRequest> <Field Name="MinAge" Type="Integer" /> <Field Name="MaxAge" Type="Integer" /> </RecRequest> <ListResponse Type="String" /> </Procedure>A DivConq schema file holds custom data types, table declarations, storedprocedure declarations and more. Above is just one snipped from the schema fileshowing the declaration for the stored procedure “dctListPeople”.

<Procedure Name="dctListPeople" Execute="listPeople^dctToyTest"> <Description> Get a list of names of all people in test data. Optionally apply an age range filter </Description> <RecRequest> <Field Name="MinAge" Type="Integer" /> <Field Name="MaxAge" Type="Integer" /> </RecRequest> <ListResponse Type="String" /> </Procedure>Key elements here are the Request and Response which provide the validationrules for this procedure. Expect either a RecRequest (RecordStruct) or aListRequest (ListStruct) for request – those are our options for requestparameters. Likewise, expect a RecResponse or a ListResponse for theresponse.

Request (Params) Examples a: { “MinAge”: 30, “MaxAge”: 48 } b: { “MaxAge”: 48 } c: null Response Examples a: [ “Jim”, “Beth”, “Sandy” ] b: [ ]Note that the params are not marked as required (in the schema), so any of thethree examples for request are valid.The response is a list of strings. No minimum is given, so a list of zero is valid.

Linux Box Windows Java App w/ DivConq MUMPS User w/Web Browser MUMPS Your Process DivConq Application Database Code MUMPS Interface External Process App on DivConq MUMPS Linux Web Server DivConq Schema Process (HTTP + Web Sockets)There are many reasons to “why JSON?” – one of the best is interoperability withweb apps and other external applications. Through HTTP or WebSocket callsJSON parameters can be sent and JSON results can be returned. To minimizeinteroperability hassles DivConq favors JSON-like structures throughout.

Request-Response handling within MUMPS

Java Request (Params) { “MinAge”: 30, “MaxAge”: 48 } MUMPS Params Params(“MinAge”)=30 Params(“MaxAge”)=48JSON can be adopted to MUMPS structures without much effort, details in afuture presentation. As far as this overview is concerned, the key point is thatJSON-like structures get transformed into MUMPS structures before the storedprocedure is called.

Schema Declaration <Procedure Name="dctListPeople" Execute="listPeople^dctToyTest"> MUMPS Code listPeople ; ; w StartList ; start list of people w ScalarStr_“Jim” ; write a scalar w ScalarStr_“Beth” ; write another scalar w EndList ; end list of people ; quitThe schema tells us what MUMPS routine and function to call. Above is a hint atwhat the code has to do – return a list of strings. Note how the result from theprocedure is sent back to Java by using the “write” command.

listPeople n id,minage,maxage,age s minage=Params("MinAge"),maxage=Params("MaxAge") ; w StartList ; start list of people (name only) ; f s id=$o(^dctData("People",id)) q:id="" d . s age=^dctData("People",id,"Age") . i (minage="")&(age<minage) q . i (maxage="")&(age>maxage) q . w ScalarStr_^dctData("People",id,"Name") ; w EndList ; end list of people ; quitYou’ll need to review the dctToyTest routine to get the details on this example, butwhat you can see here is that we loop through all the people an apply the(optional) filter. People who are not filtered are returned as scalars (just names)in the list.

ObjectCallback callback = new ObjectCallback() { @Override public void process(ObjectResult result) { if (result.hasErrors()) { System.out.println("Error in List"); return; } ListStruct names = result.getResultAsList(); for (Struct item : names.getItems()) System.out.println("Name: " + item.toString()); } };Back in Java you can process the result via ListStruct by looping all the items.We know, because of the schema validation and the call to “hasErrors”, that ouritems are all just strings. There are a few ways to work with a string item, butcertainly calling “toString” will work.

There is a lot more to learn about stored procedures, but now you have anoverview of how it works as well as some of the design philosophy.

dcDB Overview of Stored Procedures

by eTimeline, LLC

Accessibility

Categories

Upload Details

Usage Rights

Statistics

dcDB Overview of Stored Procedures Presentation Transcript