MVsharp JavaScript Integration
How to integrate your existing BASIC application with server side JavaScript Scripting.
Contents
3 Configuring Visual Studio Code For JavaScript
Introduction
JavaScript is a powerful scripting language that is extensively used by millions of programmers around the world. It also have a rich set of libraries to perform many functions that are freely available.
The purpose of integrating JavaScript with MVsharp is to allow software development houses the ability to use JavaScript programmers to achieve application functionality seamlessly in your MVsharp environment.
JavaScript is also a interpreted language that does not require compilation before it is executed making deployment of your software simple and easy.
Our JavaScript engine is the Chrome V8 engine which is the same JavaScript engine used by Chrome and Microsoft's Edge browsers. When a script is executed, the V8 engine is loaded into your .Net process.
- Because the script is executed in the same process and there is no IPC calls to another process, it is lightning fast.
- You entire session is available in the JavaScript script.
- The entire MVsharp Runtime (BASIC Runtime) is available as functions inside your JavaScript script. You can open files, read records, do oconvs etc. In fact every single BASIC function is available.
- JavaScript scripts are seamless to your existing application, you can CALL a JavaScript script and pass arguments exactly the same way you call a BASIC subroutine.
- Conversely you can call a BASIC subroutine from JavaScript.
There are no extensions or runtime that need to be installed in order to use JavaScript scripts. It is all built into the MVsharp runtime.
In order to differentiate JavaScript scripts from BASIC programs, all JavaScript scripts must end with the suffix ".js".
e.g. HelloWorld.js
Creating JavaScript scripts
JavaScript scripts are stored in any directory file and can co-exist with your BASIC programs in the same file.
For the purposes of this document, we are going to create a separate file called JavaScripts where we will store our JavaScript scripts.
>CREATE.FILE JavaScript Type=Directory
JavaScript scripts can be create using ED or Visual Studio Code. Visual Studio Code has the advantage of code highlighting, linting formatting etc.
Installing the JavaScript Demo Programs
Download the JavaScript.zip file from the Documentation folder.
Extract the contents to the file created above and run the following commands:
Configuring Visual Studio Code For JavaScript
There is a JavaScript extension for Visual Studio Code that will enrich your JavaScript development with MVsharp. You can install the extension by type typing "JavaScript" and select the JavaScript extensions from Microsoft. Also install the JavaScript Debugger extensions which MVsharp uses for visual debugging.
MVsharp comes with installed Intellisense for the MVsharp Runtime, Dynamic Array and Session objects. This enables you to use intellisense and linting on all of the MVsharp Runtime in JavaScript.
To configure the path add the following at the top of each JavaScript File:
/// <reference path="C:/Program Files (x86)/Prosol Group/MVsharp/MVsharp.d.ts"/>
hw = "hello world"
Console.WriteLine(hw)
The above path is relative to where you initially installed MVsharp.
Creating Scripts
HelloWorld.js
Conforming to convention, our first script is to display "Hello World" on the terminal. In Visual Studio Code, create a new file called HelloWorld.js with the following:
We can test the script by running it:
We can also CATALOG the script so that we can call it straight from the command line:
Creating and calling JavaScript Functions
Using JavaScript with MVsharp gives the best of both the JavaScript World and the .Net world. The entire MVsharp as well as any JavaScript libraries are available in your JavaScript script.
Probably most MV developers have spent far too much time managing JSON documents. The following example highlights using the correct language to easily decode a JSON document into Dynamic Array.
It also illustrates using standard MVsharp BASIC functionality inside of a JavaScript script.
/// <reference path="C:/Program Files (x86)/Prosol Group/MVsharp/MVsharp.d.ts"/>
function decodeConnection(jsonString,dynarr) {
var conn = JSON.parse(jsonString.ToString());
Functions.CRT(conn.AccountName,false);
dynarr.setAttribute(1,conn.AccountName);
dynarr.setAttribute(2,conn.LastProcessed);
dynarr.setAttribute(3,conn.MessagesProcessed.toString());
dynarr.setAttribute(4,conn.ProcessingRequest.toString());
dynarr.setAttribute(5,conn.StartTime);
}
// {
// \"AccountName\": \"mvSHARP\",
// \"StartTime\": \"0001-01-01T00:00:00\",
// \"ProcessingRequest\": false,
// \"LastProcessed\": \"2021-11-22T13:24:44.5216517+02:00\",
// \"MessagesProcessed\": 1
// }
This script will be called from a BASIC subroutine by passing 2 arguments to the script:
Program TestJson
jstring = '{"AccountName":"MVsharp","StartTime":"0001-01-01T00:00:00","ProcessingRequest": false,"LastProcessed": "2021-11-22T13:24:44.5216517+02:00","MessagesProcessed": 1 }'
Call DecodeJson.decodeConnection(jstring,ans)
Crt ans
End
When you pass a Dynamic Array to the JavaScript function as an argument, it behaves exactly the same as a BASIC subroutine, any changes to the arguments are returned to the calling program.
Call DecodeJson.decodeConnection(jstring,answer)
JavaScript functions are called the same way as BASIC Subroutines.
Functions.CRT(conn.AccountName,false);
The above statement in the JavaScript script invokes the MVsharp BASIC CRT function, giving total interoperability between JavaScript and BASIC. This simplifies doing things in JavaScript. The entire BASIC runtime engine is available in JavaScript including Intellisense to assist.
A JavaScript script may contain more than 1 function inside the script. To catalog a specific function inside the script the following syntax is used:
Using MVsharp BASIC runtime in JavaScript
As mentioned previously, you can use the entire BASIC runtime inside your JavaScript script. Consider the following example: We need to produce a JSON document from a CUSTOMER record. In the example we will use as many BASIC functions that we can.
// First define the class with a constructor
class Customer {
constructor(firstName, lastName, address, postCode,birthDate) {
this.firstName = firstName;
this.lastName = lastName;
this.address = [];
// extract each multi value and add to address
address.split(String.fromCharCode(253)).forEach(line => {
this.address.push(line);
});
this.postCode = postCode;
this.birthDate = birthdate;
}
}
// create a function to open a MVsharp file, read a record, populate a class and return a JSON string
function CustToJson(customerId, jsonCust) {
// create MVsharp dynamic arrays
var fileVariable = new DynamicArray();
var fileName = new DynamicArray("CUSTOMER");
var customerRecord = new DynamicArray();
var readv = new DynamicArray(-1);
var dateConv = new DynamicArray("D4-");
if (Functions.OPEN(new DynamicArray(), fileName, fileVariable)) {
// all arguments must be of type DynamicArray
Functions.READ(fileVariable, customerId, customerRecord, readv, false, false, false);
// use MVsharp OCONV to covert pick internal date
var birthDate = new DynamicArray(customerRecord.getAttribute(5));
birthDate.SetValue(Functions.OCONV(birthDate,dateConv));
// create an instance of the Customer class with data
var customer = new Customer(customerRecord.getAttribute(1),
customerRecord.getAttribute(2),
customerRecord.getAttribute(3),
customerRecord.getAttribute(4),
birthDate.ToString());
// convert customer to JSON and return in the second argument
jsonCust.SetValue(JSON.stringify(customer,null,' '));
}
}
Debugging Scripts
We use the VSCODE JavaScript debugger to debug our scripts. The debugger extension has to be installed. Locate and install the extension in VSCODE.
The following applies to debugging MVsharp JavaScript:
- The extension does not run in a Workspace, you will need to open the path to the MVsharp directory.
- Launch setting need to be configured before the debugger can be used.
In VSCODE open User settings and add the following:
{
"update.mode": "none",
"launch": {
"version": "0.2.0",
"configurations": [
{
"name": "Attach to ClearScript V8 on port 9292",
"type": "node",
"request": "attach",
"protocol": "inspector",
"address": "localhost",
"port": 9292
}
]
}
}
Save and reload VSCODE.
Launching the debugger
1 - First run your script from MVsharp to setup the connection between VSCODE and MVsharp. This only needs to be done once in a session.
2 - Open the JavaScript script in VSCODE. Add the debugger statement in your code:
function CustToJson(customerId, jsonCust). {
// create MVsharp dynamic arrays
debugger
var fileVariable = new DynamicArray();
3 - Press F5 to enable to debugger. The Debug status bar should look like this:
4 - The red connectors mean the debugger is active.
5 - Run your MVsharp program that calls the script and the debugger will be activated.
All VSCODE debugging features are now available.
NOTE:
Sometimes the debugger gets a little confused and your script wont connect to the debugger. If this happens, close all instances of the MVsharp shell, start a new shell and try again.
Copyright © 2018 Prosol Group
All rights reserved.
Prosol Group make no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Prosol Group or an authorised sub licensor.
Neither Prosol Group nor its employees are responsible for any errors that may appear in this publication. The information in this publication is subject to change without notice.
All other trademarks and service marks are property of their respective holders.