Skip to content

MVsharp REST Interface

Details and examples of using MVsharp REST Interface to integrate into the MVsharp environment.

Contents

1 Introduction

2 Pre Requisites

3 Configuring REST Server

4 Calling MVsharp REST Interface

4.1 List of Accounts on the server

4.2 Reading and Writing Records

4.3 Calling Subroutines

4.4 Executing TCL Commands

4.5 Selecting Files

4.6 Compiling Programs

4.7 Cataloging Programs

4.8 Get a List of Active Users

4.9 Send a Message to a User

4.10 Logoff a User

4.11 Checking the status of the REST API Controllers

Introduction

The MVsharp REST API allows external applications to communicate with MVsharp using the REST Web Services protocol. It provides similar functionality to the NetObjects but does not require a library to be loaded on the client application.

The following features are supported in the MVsharp REST Interface:

  • Read and write records from files in an account.
  • Execute TCL statements. If the statement results in a SELECT list being created, the list is also returned.
  • Call Subroutines. Subroutines can be called and arguments can be passed to the subroutine and the resultant arguments are returned.
  • Selecting files.
  • Get statistics of the connections to MVsharp.
  • Managing Users, Locks, Processors.

The REST Interface is hosted in the MVsharp Service and does not require any Web Server to be installed on your systems.

The connection layer between the Web Server and MVsharp uses NetObjects. A pool of connections are created by specifying the MaxPool and MinPool configuration parameters. The connection pool scales up when high request loads are encountered and will scale down to the MinPool value when there are lower requests loads.

Pre Requisites

  1. MVsharp Version 4.

Configuring REST Server

The REST server is installed with the current default parameters and must be configured before REST calls can be made.

File Type Description
MvSharpServer This is defaulted to 'localhost'. You can point the REST server to another instance of MVsharp.
MvSharpUser This is blank by default and needs to be configured with the TCL Command REST.CONFIG. You need to have administrator access to do this.
MvSharpPassword This is blank by default and needs to be configured with the TCL Command REST.CONFIG. You need to have administrator access to do this.
MinPool This is defaulted to 3 as is the number of connectors that are created at startup.
MaxPool This is defaulted to 10 and the maximum number of connectors that can be used for REST calls. Connection are tied to a specific account so if there are a lot of accounts being accessed, increase as required.
RestPort This is defaulted to 9005 and is the port the end points will be listening on.

The TCL command REST.CONFIG can be used to configure these values. You must have Administrative Rights to successfully configure the REST server.

Calling MVsharp REST Interface

The examples below are based on the installation process above. If you have used a different port or virtual directory, the REST calls need to be modified to reflect those changes.

Visual Studio Code has HTTP extensions that will allow you to test REST calls from the IDE. We recommend installing this extension when testing the REST API.

rest_pic_1

List of Accounts on the server

The get a list of Accounts on the server we use the GET command:

http://localhost:9005/accounts

Returns:

HTTP/1.1 200 OK
Content-Length: 348
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 18 Nov 2021 10:49:13 GMT
Connection: close

[
  {
    "AccountName": "MVsharp",
    "AccountPath": "E:\\MVsharp Accounts\\MVsharp"
  },
  {
    "AccountName": "LICENSE",
    "AccountPath": "E:\\MVsharp Accounts\\LICENSE"
  },
  {
    "AccountName": "DEMO",
    "AccountPath": "E:\\MVsharp Accounts/DEMO"
  },
  {
    "AccountName": "MVSYNC",
    "AccountPath": "E:\\MVsharp Accounts/MVSYNC"
  },
  {
    "AccountName": "MVREST",
    "AccountPath": "E:\\MVsharp Accounts/MVREST"
  }
]

Reading and Writing Records

To read a record from a file in MVsharp we use the GET command:

http://localhost:/MVsharprest/database/{Account}/{FileName}/{RecordId}

Database is the REST controller.

Account, Filename and RecordId are the parameters to be passed to the controller and are mandatory.

http://localhost:9005/database/MVsharp/VOC/DICTLIST

Returns:

HTTP/1.1 200 OK
Content-Length: 90
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 18 Nov 2021 14:48:25 GMT
Connection: close

{
"RecordId": "DICTLIST",
"Record": "PHþType Definition Conversion Head Format Depth By LOC"
}

The Record returned is in Multivalue format with Attribute, Value and Subvalue marks.


To write a record to a file in MVsharp we use the POST command:

POST http://localhost:9005/database/MVsharp/VOC/NewRecordId
Content-Type: application/json

{
  "RecordId": "NewRecordId",
  "Record": "Record Sent by MVsharp REST"
}

The RecordId and Record value are passed in the body the HTTP POST command. The Record value contains a delimited string with Attribute marks, Value marks and Subvalue marks


To delete a record from a MVsharp file we use the DELETE command:

DELETE http://localhost:9005/database/MVsharp/VOC/NewRecordId

Calling Subroutines

To call a MVsharp BASIC/Javascript/Python/Typescript Subroutine we use the POST command:

http://localhost:9005/Subroutine/{Account}

Subroutine is the REST controller.

Account is the name of the account where the subroutine is compiled and catalogued.

In this example we have a simple BASIC subroutine that adds to numbers:

SUBROUTINE ADD(Value1,Value2,Answer)
Answer = Value1 + Value2
Return

POST http://localhost:9005/Subroutine/MVsharp
Content-Type: application/json

{
  "SubroutineName":"ADD",
  "Arguments":["25","50",""]
}

NOTE: You must provide an argument for each of the subroutines parameters.

Returns:

HTTP/1.1 200 OK
Content-Length: 16
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 19 Nov 2021 07:26:58 GMT
Connection: close
[
  "25",
  "50",
  "75"
]

Executing TCL Commands

To execute a TCL command we use the POST command:

http://localhost:9005/execute/{Account}

Execute is the REST controller.

Account is the name of the account where the command will be executed.

POST http://localhost:9005/execute/MVsharp
Content-Type: application/json

{
  "TclStatement":"LIST VOC F1 F2 F3 SAMPLE 10"
}

Returns:

HTTP/1.1 200 OK
Content-Length: 933
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 19 Nov 2021 07:32:25 GMT
Connection: close

{
  "ResponseText": [
    "LIST VOC F1 F2 F3 SAMPLE 10 09:32:26 11-19-21 Page 1 ",
    "VOC......... F1..........F2................F3............. ",
    "",
    "!CATS        Program     MVsharp.BP.Lib    !CATS.dll ",
    "!FIELDS      Program     MVsharp.BP.Lib    !FIELDS.dll ",
    "!FMTS        Program     MVsharp.BP.Lib    !FMTS.dll ",
    "!GTS         Program     MVsharp.BP.Lib    !GTS.dll ",
    "!ICONVS      Program     MVsharp.BP.Lib    !ICONVS.dll ",
    "!NES         Program     MVsharp.BP.Lib    !NES.dll ",
    "!OCONVS      Program     MVsharp.BP.Lib    !OCONVS.dll ",
    "!SPLICE      Program     MVsharp.BP.Lib    !SPLICE.dll ",
    "&COMO&       File        &COMO&            D_&COMO& ",
    "&DEVICES&    F           [MVsharp].[dbo]   [MVsharp].[dbo] ",
    "                         .[_&DEVICES&]     .[D__&DEVICES&] ",
    "",
    "10 records listed.",
    ""
  ],
    "ResponseList": [
    ""
  ]
}

If the command results in a select list created, the list is returned in the object ResponseList.

Selecting Files

To select a file with criteria, we use the POST command:

POST http://localhost:9005/Select/{Account}/{FileName}

Select is the REST controller.

Account is the name of the account where the command will be executed and FileName is the file to be selected.

POST http://localhost:9005/Select/MVsharp/VOC
Content-Type: application/json

{
  "Criteria" : "WITH @ID LIKE LIST..."
}

Returns:

HTTP/1.1 200 OK
Content-Length: 190
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 19 Nov 2021 07:35:19 GMT
Connection: close

[
  "LIST",
  "LIST.ACCOUNTS",
  "LIST.CACHE",
  "LIST.DIFF",
  "LIST.INDEX",
  "LIST.INTER",
  "LIST.ITEM",
  "LIST.LOCKS",
  "LIST.READU",
  "LIST.TRIGGER",
  "LIST.UNION",
  "LISTF",
  "LISTFILES",
  "LISTPTR",
  "LISTU",
  "LISTUSER"
]

Compiling Programs

To compile a BASIC program on the server we use the GET command:

http://localhost:9005/compile/{Account}/{FileName}/{ProgramName}[/{Options}]

Compile is the REST controller.

Account, Filename and ProgramName are the parameters to be passed to the controller and are mandatory.

Options is an optional parameter to pass to the BASIC command.

GET http://localhost:9005/compile/MVsharp/MVsharp.BP/ED/D

Returns:

HTTP/1.1 200 OK
Content-Length: 48
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 19 Nov 2021 07:44:17 GMT
Connection: close

{
  "Result": "ED Compiled Successfully",
  "Errors": []
}

Cataloging Programs

To catalog a BASIC program on the server we use the GET command:

http://localhost:9005/catalog/{Account}/{FileName}/{ProgramName}

Catalog is the REST controller.

Account, Filename and ProgramName are the parameters to be passed to the controller and are mandatory.

Options is an optional parameter to pass to the BASIC command.

GET http://localhost:9005/catalog/MVsharp/MVsharp.BP/ED

Returns:

HTTP/1.1 200 OK
Content-Length: 14
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 19 Nov 2021 07:55:44 GMT
Connection: close

"ED Cataloged"

Get a List of Active Users

To get a list of active users we use the GET command:

http://localhost:9005/users

Users is the REST controller.

HTTP/1.1 200 OK
Content-Length: 477
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 19 Nov 2021 10:18:25 GMT
Connection: close

[
  {
    "ProcessId": 32780,
    "UserId": "Grant Hart",
    "AccountName": "MVsharp",
    "Type": "shell",
    "LastCommand": "X",
    "LoginDate": "2021-11-19T12:17:20",
    "IpAddress": ""
  },
  {
    "ProcessId": 26924,
    "UserId": "Grant Hart",
    "AccountName": "MVsharp",
    "Type": "NetObj",
    "LastCommand": "LOGTO MVsharp",
    "LoginDate": "2021-11-19T12:18:14",
    "IpAddress": "127.0.0.1"
  },
  {
    "ProcessId": 37552,
    "UserId": "Grant Hart",
    "AccountName": "MVsharp",
    "Type": "telnet",
    "LastCommand": "X",
    "LoginDate": "2021-11-19T12:17:24",
    "IpAddress": "127.0.0.1"
  }
]

Send a Message to a User

To get a list of active users we use the POST command:

http://localhost:9005/users

Users is the REST controller.

POST http://localhost:9005/Users
Content-Type: application/json

{
  "ProcessId" : "12345",
  "ActionType" : "Message",
  "MessageText" : "This is a message"
}

HTTP/1.1 200 OK
Content-Length: 477
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 19 Nov 2021 10:18:25 GMT
Connection: close

Logoff a User

To logoff a specific user we use the POST command:

http://localhost:9005/users

Users is the REST controller

POST http://localhost:9005/Users

Content-Type: application/json
{
  "ProcessId" : "12345",
  "ActionType" : "Logoff",
}

Returns:

HTTP/1.1 200 OK
Content-Length: 477
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 19 Nov 2021 10:18:25 GMT
Connection: close

Checking the status of the REST API Controllers

To check the status of the controllers we use the GET command:

http://localhost:9005/status

Status is the REST controller.

Returns:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/10.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Fri, 09 Nov 2018 11:27:32 GMT
Content-Length: 345

[{
  "AccountName": "APA",
  "StartTime": "2018-11-09T13:27:22.6990641+02:00",
  "ProcessingRequest": false,
  "LastProcessed": "2018-11-09T13:27:22.6990641+02:00",
  "MessagesProcessed": 1
  }, {
  "AccountName": "MVsharp",
  "StartTime": "2018-11-09T13:15:07.0580597+02:00",
  "ProcessingRequest": false,
  "LastProcessed": "2018-11-09T13:23:37.477586+02:00",
  "MessagesProcessed": 5
}]

A list of each connection to MVsharp is returned.

Resetting the REST Controllers

If the REST server becomes unstable, you can reset all controllers with a GET command:

http://localhost:9005/status/reset

Status is the REST controller.

Returns:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/10.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Fri, 09 Nov 2018 11:27:32 GMT
Content-Length: 345

[{
  "AccountName": "APA",
  "StartTime": "2018-11-09T13:27:22.6990641+02:00",
  "ProcessingRequest": false,
  "LastProcessed": "2018-11-09T13:27:22.6990641+02:00",
  "MessagesProcessed": 1
}, {
  "AccountName": "MVsharp",
  "StartTime": "2018-11-09T13:15:07.0580597+02:00",
  "ProcessingRequest": false,
  "LastProcessed": "2018-11-09T13:23:37.477586+02:00",
  "MessagesProcessed": 5
}]

A list of each connection to MVsharp is returned.

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.