Skip to content

Visual Studio Code MVsharp Extensions

How to use Visual Studio Code as the MVsharp Development Environment.

Contents

1 Introduction

2 Pre Requisites

3 Installing Visual Studio Code

4 Configuring Visual Studio Code for MVsharp#

5 Connecting to a MVsharp# Server

5.1 Testing the connection

5.2 Associating Programs with MVsharp#

5.3 Additional MV# Developer Settings

6 MV# Developer Features

6.1 Syntax Highlighting

6.2 Intellisense

6.3 Find All References

6.4 Goto/Peek Definition

6.5 Internal Subroutine lookup

6.6 Compiling and Cataloging your programs

6.7 Formatting Programs

7 Connecting to other MV Platforms

7.1 Universe

7.2 Unidata

7.3 OpenQM

7.4 jBASE

7.5 D3

7.6 Testing remote connectivity

7.7 Debugging remote connection issues

8 MV# Debugger Extension

8.1 Starting the debugger

8.2 Debugging features

8.3 Call Stack

9 MV# TCL Extension

9.1 Establishing a TCL session

9.2 TCL Features

9.2.1 Intellisense

9.2.2 Automatically execute script lines

9.2.3 Error highlighting

9.2.4 Dictionary details display

Introduction

Visual Studio code is a feature rich IDE that allows programmers to develop and debug code is various languages. MVsharp provides developers with the ability to program their MV applications with a variety of program languages including BASIC, C#, Python, JavaScript and Typescript. This makes Visual Studio Code and ideal IDE as it supports all the above languages.

In order to fully utilize the power of VSCODE, Prosol Group has built a set of extensions to cater for MVsharp# BASIC language. There are also extensions to support all the MVsharp supported languages.

This extensions includes the following features

  1. Code highlighting for MV# BASIC Programs

  2. Intellisense for the MV# BASIC Statements and Functions

  3. Code folding

  4. Code formatting

  5. Goto/Peek Definition. Automatically jump to and peek internal subroutines

  6. Goto/Peek Definition. Automatically peek/load CALL, CHAIN and INCLUDE routines

  7. Syntax checking for GOTO/GOSUB's, LOOPS, CASE STATEMENTS and IF THE/ELSE statements

  8. Access your remote MVsharp# files and programs

  9. Find all References of a word in current program

  10. A visual debugger

Visual Studio Code is available on Windows, Linux and Mac OSX.

Pre Requisites

The following environment is required in order to use Visual Studio Code.

  1. Windows, Linux or Mac OSX machine.

Installing Visual Studio Code

Visual Studio Code can be downloaded from the following link:

https://code.visualstudio.com/Download

You can select the version for operating system. This guide describes how to install the Windows version of Visual Studio Code.

Depending on your Window operating system, run either the 32 bit VSCodeUserSetup-ia32-1.62.2.exe or the 64 bit VSCodeUserSetup-x64-1.62.2.exe.

vs_code_pic_1

Select Next.

vs_code_pic_2

Accept the License Agreement and select Next.

vs_code_pic_3

Accept the defaults or specify your folder and select Next.

vs_code_pic_4

Select the options you would like to include in the install and select Next.

vs_code_pic_5

Visual Studio Code is now installed.

Configuring Visual Studio Code for MVsharp.

Before we can start using the MVsharp features for Visual Studio Code, we need to install the extensions. VSCODE has a automated download and installation process for extensions.

Start VSCODE and select the Extensions button.

vs_code_pic_6

In the search box, type MV and press enter:

vs_code_pic_7

You can select the Developer Extension and the Debugger extension by selecting the download image.

Once the extensions are installed we are ready to start accessing our MVsharp server.

Connecting to a MVsharp Server

The extension allows us to connect to connect to remote MVsharp servers and edit BASIC programs. We need to configure a Workspace that will contain all the parameters required to connect and login to the remote MVsharp Server.

The simplest method is to create a directory on your machine where we will save the Workspace definitions. If we have multiple server and multiple accounts on each server, we can create multiple Workspace's that points to a a particular server and account.

In order to connect to a MVsharp# Server, we required the following information:

  1. Hostname or IP Address of the MVsharp# server.

  2. User name to login into the server

  3. Password for the user above.

  4. Account name to connect to on the MVsharp# Server

To create a new Workspace, select "Save Workspace As" from File Menu. I have created a Folder called VSCODE on the E: drive where I store all my Workspace definitions.

vs_code_pic_8

The will create a blank Workspace called Demo that we can now configure to point to our MVsharp# server.

To configure the connection parameters , select File, Preference, Setting from the menu.

vs_code_pic_9

This will bring up the Settings pane in VSCODE, make sure you select the Workspace Tab, and then type MVsharp in the search box. This will display a list off all the parameters that can be set for the MV# Developer extension.

Hover your mouse over a parameter and you will be given the option to Edit and Copy to Settings.

vs_code_pic_10

After adding all the parameters to the workspace, you setting should be like this:

{
    "folders":[
        {
            "uri": "RestFS:/",
            "name": "Account - DEMO",
        }       
    ],
    "settings": {
        "MVsharp.RestPath": "http://localhost/MVsharprest/",
    }
}

You can copy and paste the above and make the necessary changes for your system.

This is the base settings required to connect to your MVsharp# Server. Press Ctl-S to save your settings.

Testing the connection

We can test to if our connection to MVsharp# works by Pressing F1. VSCODE will prompt you for the command to run. Type Connect to display all commands with Connect in it and is displays:

vs_code_pic_11

Select Connect to MVsharp# REST FS and the extension will connect to the server and retrieve a list of Directory files from the server.

If the connection is successful, the following 3 messages will appear at the bottom left of the screen.

vs_code_pic_12

Associating Programs with MVsharp

Most programming languages have an extension that say what language it is. Python is .py, C# is .cs etc and MV BASIC does not follow this concept.

In order to know that we are editing a BASIC program to enable Syntax highlighting. Intellisense and Linting, we need to tell VSCODE that files in the Workspace are linked to MVsharp#. This is achieved by adding the following setting to your Workspace settings.

{
    "folders":[
        {
            "uri": "RestFS:/",
            "name": "Account - DEMO",
        }       
    ],
    "settings": {
        "MVsharp.RestPath": "http://localhost/MVsharprest",
        "files.associations": {"*":"MVsharp"}
    }
}

Additional MV# Developer Settings

The following settings are available to customise your VSCODE MV# Developer experience.

Setting Description
MVsharp.margin The number of characters to use as a margin when formatting.
MVsharp.indent The number of characters to use when indenting code blocks.
MVsharp.useCamelCase Use Camelcase for Intellisense keywords.
MVsharp.ignoreGotoScope The linter will not highlight goto that jump into the middle of loops.
MVsharp.formattingEnabled Set to false to disable code formatting.

MV# Developer Features

The following is a list of features that the extensions offer MV Developers when using VSCODE.

Syntax Highlighting

!
*-----Insert Text
!
CASE UPCASE(ANS) = 'I' OR UPCASE(ANS) = 'IB' OR UPCASE(ANS) MATCHES "'I '0X" OR UPCASE(ANS) MATCHES "'IB '0X"
GOSUB 1030
!
*-----Toggle Block Confirm
!
CASE UPCASE(ANS) = 'BLOCK'
  IF BLOCK THEN
    BLOCK = FALSE
    CRT 'BLOCK operation verification = disabled.'
  END ELSE
    BLOCK = TRUE
    CRT 'BLOCK operation verification = enabled.'
  END
  GOSUB 1000

Code is highlighted based on the current theme selected for VSCODE.

Intellisense

As you type your program, you will be prompted with available statements and functions including the syntax and description.

vs_code_pic_13

Find All References

You can find all references to a word in your program by right clicking on a word and selecting Find All References from the menu.

The display consists of 2 panels, the right containing the line that the word is in and the actual code block is in the left. Clicking on a line in the right panel will take you to the code block.

vs_code_pic_14

Goto/Peek Definition.

If you right click on a internal or external subroutine name and select Peek Definition, a window appears showing the internal or external subroutine.

vs_code_pic_15

If you select Goto Definition, the cursor is moved to start of the subroutine.

Internal Subroutine lookup

Pressing "Ctl-space" after the word GOTO, GOSUB or GO TO, will allow you to select from defined internal subroutines in your program.

vs_code_pic_16

Compiling and Cataloging your programs.

Right Clicking inside the code window allows you to select 3 options:

  1. Catalog Basic Program -- catalogs the BASIC program
  2. Compile Basic Program -- compiles the basic program.
  3. Compile Basic Program with Debug -- compiles with the debug flag set.

vs_code_pic_17

After the option is selected, the results will be displayed in message box at the bottom of the screen. If an error is detected, the editor will place the cursor on the line where error occurs.

Formatting Programs

Right Clicking and selecting Format Document, will format your BASIC program. The formatting is based on the 2 settings, MVsharp.indent and MVsharp.margin that have default values of 3 and 5.

Connecting to other MV Platforms

The VSCODE MV# Developer extensions all you to connect to the most MV platforms and provides all the features described above. The MVsharpGetway is a windows service that acts as a router to access each of the different MV platforms.

As each platform might require different parameters, a Workspace configuration example is provided for each of the following MV platforms.

  1. Universe
  2. Unidata
  3. OpenQM
  4. jBASE
  5. D3
  6. MvBase

The path to the Gateway Installation media is:

C:\Users\{User Name}\.vscode\extensions\ongroup.MVsharp-1.85.0\Gateway

It is a standard Windows installer module. Copy the installer to the machine that is going to run the Gateway and install. The Gateway exposes a REST File System that can be accessed via VSCODE. The port that REST pipeline is listening on is defaulted to 9005.

Universe

{
  "folders":[
  {
    "uri": "RestFS:/",
    "name": "Account - Universe",
  }
],
    "settings": {
        "MVsharp.RestPath": "http://localhost:9005/,
        "MVsharp.UseGateway": true,
        "MVsharp.RemoteHost": "192.168.137.102",
        "MVsharp.GatewayType": "Universe",
        "MVsharp.UserName": "MVsharp",
        "MVsharp.Password": "MVsharp#",
        "MVsharp.Account": "SUPER-GROUP",
        "files.associations": {"*":"MVsharp"}
    }
}
Setting Description
MVsharp.useGateway true Indicate that the gateway must be used.
MVsharp.RestPath http://localhost:9005 Path to Gateway.
MVsharp.remoteHost 192.168.137.102 The servers IP/Host name that is running the Universe Database.
MVsharp.gatewayType Universe Connecting to a Universe server.
MVsharp.UserName MVsharp The Windows/UNIX user id to log into the server.
MVsharp.Password MVsharp# The password for the user above.
MVsharp.Account SUPER-GROUP The account name on Universe to connect to. This must be defined in the UV.ACCOUNT file in the UV account.

Unidata

{
  "folders":[
  {
    "uri": "RestFS:/",
    "name": "Account -- SUPER-GROUP",
  }
],
    "settings": {
        "MVsharp.UseGateway": true,
        "MVsharp.RemoteHost": "192.168.137.102",
        "MVsharp.gatewayType": "Unidata",
        "MVsharp.UserName": "MVsharp",
        "MVsharp.Password": "MVsharp#",
        "MVsharp.Account": "SUPER-GROUP",
        "MVsharp.AccountPath": "/usr/data/SUPER-GROUP",
        "files.associations": {"*":"MVsharp"}
    }
}
Setting Description
MVsharp.UseGateway true Indicate that the gateway must be used.
MVsharp.RestPath http://localhost:9005 Path to Gateway.
MVsharp.RemoteHost 192.168.137.102 The servers IP/Host name that is running the Unidata Database.
MVsharp.GatewayType Unidata Connecting to a Unidata server.
MVsharp.Password MVsharp# The password for the user above.
MVsharp.Account SUPER-GROUP A name for this account.
MVsharp.AccountPath /usr/SUPER-GROUP The path on the Unidata machine to the Unidata account.

OpenQM

{
  "folders":[
  {
    "uri": "RestFS:/",
    "name": "Account - PRC",
  }
],
    "settings": {
        "MVsharp.UseGateway": true,
        "MVsharp.RemoteHost": "192.168.137.102",
        "MVsharp.gatewayType": "QM",
        "MVsharp.UserName": "MVsharp",
        "MVsharp.Password": "MVsharp#",
        "MVsharp.Account": "PRC",
        "files.associations": {"*":"MVsharp"}
    }
}
Setting Description
MVsharp.useGateway true Indicate that the gateway must be used.
MVsharp.remoteHost 192.168.137.102 The servers IP/Host name that is running the OpenQM Database.
MVsharp.gatewayType QM Connecting to a OpenQM server.
MVsharp.UserName MVsharp The Windows/UNIX user id to log into the server.
MVsharp.Password MVsharp# The password for the user above.
MVsharp.Account PRC The account name on the QM server to connect to. This must be defined in the ACCOUNTS file in the QMSYS account.

jBASE

{
  "folders":[
  {
    "uri": "GatewayFS:/",
    "name": "Account - PRC",
  }
],
    "settings": {
        "MVsharp.useGateway": true,
        "MVsharp.remoteHost": "192.168.137.102",
        "MVsharp.gatewayType": "jBASE",
        "MVsharp.gatewayPort": 9004,
        "MVsharp.gatewayHost": "154.73.73.6",
        "MVsharp.UserName": "MVsharp",
        "MVsharp.Password": "MVsharp#",
        "MVsharp.Account": "",
        "files.associations": {"*":"MVsharp"}
    }
}
Setting Description
MVsharp.useGateway true Indicate that the gateway must be used.
MVsharp.remoteHost 192.168.137.102 The servers IP name that is running the jBASE Database.
MVsharp.gatewayType jBASE Connecting to a jBASE server.
MVsharp.gatewayPort 9004 The default port number that the Gateway is listening for connections on.
MVsharp.UserName MVsharp The Windows/UNIX user id to log into the server.
MVsharp.Password MVsharp# The password for the user above.
MVsharp.Account This is blank, jBASE uses the default path of the user for the account.

A record in the MD called MVsharpFILES can used as a list of available files, alternatively all files are displayed.

D3

{
  "folders":[
  {
    "uri": "GatewayFS:/",
    "name": "Account - DM",
  }
],
    "settings": {
        "MVsharp.useGateway": true,
        "MVsharp.remoteHost": "192.168.137.102",
        "MVsharp.gatewayType": "D3",
        "MVsharp.gatewayPort": 9004,
        "MVsharp.gatewayHost": "154.73.73.6",
        "MVsharp.UserName": "dm",
        "MVsharp.AccountPassword": "",
        "MVsharp.Account": "dm",
        "files.associations": {"*":"MVsharp"}
    }
}
Setting Description
MVsharp.useGateway true Indicate that the gateway must be used.
MVsharp.remoteHost 192.168.137.102 The servers IP name that is running the D3 Database.
MVsharp.gatewayType D3 Connecting to a D3 server.
MVsharp.gatewayPort 9004 The default port number that the Gateway is listening for connections on.
MVsharp.UserName dm The D3 User name to log in with.
MVsharp.AccountPassword Specify the account password if a password is set on
MVsharp.Account dm The D3 account to connect to.

MSVP must be configured for the above account and the user must have MSVP access. A record in the MD called VSCODEFILES can used as a list of available files, alternatively all files are displayed.

Testing remote connectivity

Once your Workspace is configured for your MV platform, you can connect to your MV Platform by pressing F1 in VSCODE and type Connect in the search field.

vs_code_pic_18

Select the Connect to MVsharp# Gateway option. Once the connection is successful, a list of files will be displayed in the Files pane.

Debugging remote connection issues

There is an additional parameter that can be specified in your Workspace

"MVsharp.gatewayDebug": true

When this is specified, the MVsharp# Gateway will write a log of any issues encountered while connecting to your remote MV platform. This can be used to identify any setup issues:

The log file is created in c:\temp called MVsharpGateway.log

vs_code_pic_19

MV# Debugger Extension

The MVsharp# Debugger extension enables powerful visual debugging of your MVsharp# BASIC programs. This feature is ONLY available for MVsharp# as MVsharp# supports the real time debugging protocol required by VSCODE.

In order to debug BASIC programs in VSCODE, they programs need to be compiled using the debug option. You can select Compile Basic program with Debug by right clicking in the code editor or alternatively you can compile from the command line using:

BASIC BP XX (D

To enable debugging in VSCODE when need to tell our MVsharp# environment that the VSCODE debugging is available. An entry VSCODEDEBUG must added to the MVsharp.CONFIG if the VOC

>CT VOC MVsharp.CONFIG
MVsharp.CONFIG
0001 VSCODEDEBUG

Starting the debugger

You need to first load the subroutine that you wish to debug into the code editor. Place a DEBUG statement just prior top where you want the debugging to start and compile the program with debug.

vs_code_pic_20

We start the debugger by pressing F5 in the editor window and selecting MVsharp# Debug from the drop down list:

vs_code_pic_21

The debug menu bar will appear to indicate the the debugger is now active.

You can now run you BASIC program and when the program gets the DEBUG point , VSCODE will automatically display the debug panel and the current line of code will be highlighted .

Debugging features

You can step through your code by pressing F10, the debugger will move to the next line to be executed. Pressing F5, will continue with the program until the next DEBUG statement, breakpoint or the rpgram terminates

vs_code_pic_22

If you hover your cursor above a variable, the contents of the variable are displayed in a panel.

A list of all variables and their contents are displayed in the Variables pane on the left hand side:

vs_code_pic_23

These values are automatically updated as you step through your code.

Call Stack

The call stack is powerful feature of the MVsharp# debugger. It shows the trace of all the programs called and the line number that they were called on >

vs_code_pic_24

If no line number is displayed, the program was not compiled with the DEBUG flag.

The call stack is interactive and if you select an entry from the call stack, the editor automatically loads the program and shows you the line where the program was called from

vs_code_pic_25

All variable information for the entire call stack is passed to the debugger so you can interrogate any variable in any of the programs in the call stack.

MV# TCL Extension

The MV# TCL Extension gives intellisense, syntax highlighting and syntax checking to a TCL session. It also starts an interactive terminal session where you can execute and see the results of your TCL statements.

Currently the TCL language support is based on MVsharp#, other MV dialects will be included in the future.

You must have already created the correct settings to connect to your MV platform as described in the above section of the document.

A TCL session is created by opening or creating a document that has a .tcl suffix.

If your target MV platform is not MVsharp#, you will also need to install the MVsharpGateway as described in the above section. The Gateway must be the latest that can be found in the path:

C:\Users\{UserName}\.vscode\extensions\ongroup.tcl-0.1.0\Gateway

The following additional setting need to be configured for the TCL extension

Setting Description
tcl.sshCommand The command to invoke a session on your MV platform. This can be telnet of ssh if your platform supports it.
tcl.parameters Parameters to pass to the session once it has been established. This could include login credentials and a LOGTO the account you wish the TCL session to be active in. 
"tcl.parameters": [
  "Grant Hart",
  "xxxxxxx$",
  "LOGTO PRC"
],
"tcl.sshCommand": "telnet localhost 2023",

Establishing a TCL session.

Open a document with the suffix of .tcl. and right click in the editor window:

vs_code_pic_26

Select the Connect to MV TCL option from the menu bar. This will open a new terminal session and execute the command you configured in the tcl settings.

vs_code_pic_27

You can right click on the editor window and select Send Parameters to TCL shell from the menu bar to pass the parameters to the session. This automatically connects to you MV platform and loads a list of files that exist in the specified account.

TCL Features

Intellisense

As you begin typing a list of available TCL commands are displayed for your selection. It also display the syntax that will be required.

vs_code_pic_28

The intellisense takes cognisance of the type of TCL sentence you are creating and will display a list of filenames, dictionary names and item names if your sentence requires them.

vs_code_pic_29

vs_code_pic_30

Automatically execute script lines

You can execute the current statement by pressing F5 on the line you wish to execute:

vs_code_pic_31

Multiple statements can be executed by select the lines you wish to execute and then pressing F5.

Error highlighting

You extension evaluates you statement and highlights any errors it have found like invalid files names and invalid dictionary items.

vs_code_pic_32

Dictionary details display

If you hover your mouse over a dictionary item, the details of that dictionary item are displayed.

vs_code_pic_33

Copyright © 2011 Prosol Group (Pty) Ltd

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.