fis-gtm-jswrite.tar.gz is an npm package containing four ^%JSWRITE reference implementations and three examples for the ^%JSWRITE utility routine. It also includes a utility class called JSWRITE.js to help process the output of the ^%JSWRITE utility routine for use in a JavaScript runtime environment and convert JavaScript objects to SET @ arguments.

The fis-gtm-jswrite.tar.gz package is available only for supported GT.M customers from the FIS Client Portal (https://my.fisglobal.com/products/gtm). Being a supported GT.M customer entitles you to receive package patches and upgrades under the terms of your support agreement. Note that the license for the fis-gtm-jswrite.tar.gz does not permit redistribution. You may use the fis-gtm-jswrite.tar.gz package as-is or modify as appropriate to suit your needs. In both the cases, you must adequately test the reference implementations and the utility class before using them in a production environment. Please contact gtmsupport@fisglobal.com or your support channel for more information on obtaining this package.

The ^%JSWRITE reference implementations are:

The examples are:

Step 1: Install node.js and npm

curl -sL https://deb.nodesource.com/setup_13.x | sudo -E bash -
sudo apt-get install -y nodejs
curl -L https://www.npmjs.com/install.sh | sh

Step 2: Install the fis-gtm-jswrite npm package

cd $project_dir
npm install /path/to/fis-gtm-jswrite.tar.gz # This command installs the @fis-gtm/jswrite package and the relevant %JSWRITE reference implementation dependencies. 
npm audit --fix

Step 3: Run the %JSWRITE reference implementations

# The following reference implementations use the "STDIN^%JSWRITE singlesub" entry point and require the gtmposix plugin.
export gtmroutines="node_modules/@fis-gtm/jswrite/reference_implementations $gtmroutines"      # include the reference_implementations directory in the search list
node node_modules/@fis-gtm/jswrite/reference_implementations/gtmjsjnlchain.js  # journal file chain status sheet  
node node_modules/@fis-gtm/jswrite/reference_implementations/gtmjsaccessbg.js  # %dirty buffer dashboard 
node node_modules/@fis-gtm/jswrite/reference_implementations/gtmjsdbjnl.js     # displays the size of the database and journal files 
# Set the environment variable LC_ALL to a UTF8 locale (needed for the %JSWRITE Sparkline Chart (GTMJSGVSTATS.m/gtmjsgvstats.js) reference implementation)
node node_modules/@fis-gtm/jswrite/reference_implementations/gtmjsgvstats.js   # By default, this reference implementation displays a sparkline chart for SETs and GETs. For monitoring other statistics, open gtmjsgvstats.js and update the STAT array to include the list of statistics which require sparkline chart style monitoring.  

Step 4: Run the examples

Create a sandbox environment for GT.M and run the following commands:

$gtm_dist/mupip set -key_size=1019 -region "*"
$gtm_dist/mupip load node_modules/@fis-gtm/jswrite/examples/sample.zwr
$gtm_dist/mupip load node_modules/@fis-gtm/jswrite/examples/sampletree.zwr
export "gtmroutines=node_modules/@fis-gtm/jswrite/examples/ $gtmroutines"
 
# The following example uses the do ^%JSWRITE("^sample","[*]") entry point. This uses the lodash library to merge the nodes coming from %JSWRITE. 
npm install lodash@latest
node node_modules/@fis-gtm/jswrite/examples/gtmjstree.js     # loads sample.zwr in the tree format
# The following two examples use the STDIN^%JSWRITE entry point of the %JSWRITE utility routine and then use the getter methods of the JSWRITE.js helper class to create the SQL queries. 
npm install alasql@latest
node node_modules/@fis-gtm/jswrite/examples/gtmjs-sql1.js
npm install sqlite3@latest
node node_modules/@fis-gtm/jswrite/examples/gtmjs-sql2.js
# The following example uses the @fis-gtm/jswrite helper class (JSWRITE.js) to send data back to GT.M in SET @ argument form using shelljs.
npm install shelljs@latest
node node_modules/@fis-gtm/jswrite/examples/gtmjs-to-gtm.js

The dynamic journal file progress bar displays the size progress of a journal file till it reaches the autoswitch limit. It also displays an estimation of time and speed at which a journal file reaches its autoswitch limit. This can be use for benchmarking purposes or as a tool for GT.M performance tuning.

This %JSWRITE reference implementation uses the STDIN^%JSWRITE singlesub entrypoint of the %JSWRITE utility routine.

Example:

$ node node_modules/@fis-gtm/jswrite/reference_implementations/gtmjsjnlprogress.js
Press <Ctrl> + c to terminate. refreshInterval is 3 seconds
DEFAULT [===-------------------------------------] 7% | Size: 303.7 MiB | Autoswitch: 4095 MiB | ETA: 5m40s | Speed: 15.233 MiB/s
REGIONA [=========-------------------------------] 21% | Size: 876 MiB | Autoswitch: 4095 MiB | ETA: 5m15s | Speed: 14 MiB/s
REGIONB [=========-------------------------------] 23% | Size: 962 MiB | Autoswitch: 4095 MiB | ETA: 4m40s | Speed: 15 MiB/s
REGIONC [=========-------------------------------] 21% | Size: 876.12 MiB | Autoswitch: 4095 MiB | ETA: 5m15s | Speed: 14.04 MiB/s

This %JSWRITE reference implementation monitors the size of the journal files and displays an estimate of time and speed for reaching the autoswitch limit.

The journal file chain report display the journal file chain starting from the current journal file for reach region. This reference implementation also displays the "out-of-chain" journal files, that is, those journal files which are broken and do not participate in journal recovery in normal circumstances. These out-of-chain journal files can be removed at the discretion of the GT.M database administrator to make space available.

This %JSWRITE reference implementation uses the STDIN^%JSWRITE singlesub entrypoint of the %JSWRITE utility routine.

Example:

$ node node_modules/@fis-gtm/jswrite/reference_implementations/gtmjsjnlchain.js
# Journal File Chain Report
| Region     | Journal File                          | Size (MiB) | Switch Date          | Back link                    | Chain status |
| :--------- | :------------------------------------ | ---------: | :------------------- | :--------------------------- | ------------ |
| GTMWIZARDS | /path/to/gtmwizards.mjl               |       0.07 | current              | gtmwizards.mjl_2020063121042 | In chain     |
| GTMWIZARDS | /path/to/gtmwizards.mjl_2020063121042 |       0.07 | 03-MAR-2020 12:10:42 | gtmwizards.mjl_2020063121035 | In chain     |
| GTMWIZARDS | /path/to/gtmwizards.mjl_2020063121035 |       0.07 | 03-MAR-2020 12:10:35 | -                            | In chain     |
| REGIONA    | /path/to/regiona.mjl                  |       0.07 | current              | regiona.mjl_2020063121042    | In chain     |
| REGIONA    | /path/to/regiona.mjl_2020063121042    |       0.07 | 03-MAR-2020 12:10:42 | regiona.mjl_2020063121035    | In chain     |
| REGIONA    | /path/to/regiona.mjl_2020063121035    |       0.07 | 03-MAR-2020 12:10:35 | -                            | In chain     |
| REGIONB    | /path/to/regionb.mjl                  |       0.07 | current              | regionb.mjl_2020063121042    | In chain     |
| REGIONB    | /path/to/regionb.mjl_2020063121042    |       0.07 | 03-MAR-2020 12:10:42 | regionb.mjl_2020063121035    | In chain     |
| REGIONB    | /path/to/regionb.mjl_2020063121035    |       0.07 | 03-MAR-2020 12:10:35 | -                            | In chain     |
| REGIONC    | /path/to/regionc.mjl                  |       0.07 | current              | regionc.mjl_2020063121042    | In chain     |
| REGIONC    | /path/to/regionc.mjl_2020063121042    |       0.07 | 03-MAR-2020 12:10:42 | regionc.mjl_2020063121035    | In chain     |
| REGIONC    | /path/to/regionc.mjl_2020063121035    |       0.07 | 03-MAR-2020 12:10:35 | -                            | In chain     |
| N/A        | /path/to/gtmwizards.mjl_2020063120753 |       0.07 | 03-MAR-2020 12:07:53 | -                            | Out of chain |
| N/A        | /path/to/gtmwizards.mjl_2020063120800 |       0.07 | 03-MAR-2020 12:08:00 | -                            | Out of chain |
| N/A        | /path/to/gtmwizards.mjl_2020063120801 |       0.07 | 03-MAR-2020 12:08:01 | gtmwizards.mjl_2020063120800 | Out of chain |
| N/A        | /path/to/gtmwizards.mjl_2020063120812 |       0.07 | 03-MAR-2020 12:08:12 | gtmwizards.mjl_2020063120801 | Out of chain |
| N/A        | /path/to/gtmwizards.mjl_2020063120822 |       0.07 | 03-MAR-2020 12:08:22 | gtmwizards.mjl_2020063120812 | Out of chain |
| N/A        | /path/to/gtmwizards.mjl_2020063121026 |       0.07 | 03-MAR-2020 12:10:26 | gtmwizards.mjl_2020063120822 | Out of chain |
| N/A        | /path/to/regiona.mjl_2020063120753    |       0.07 | 03-MAR-2020 12:07:53 | -                            | Out of chain |
| N/A        | /path/to/regiona.mjl_2020063120800    |       0.07 | 03-MAR-2020 12:08:00 | -                            | Out of chain |
| N/A        | /path/to/regiona.mjl_2020063120801    |       0.07 | 03-MAR-2020 12:08:01 | regiona.mjl_2020063120800    | Out of chain |
| N/A        | /path/to/regiona.mjl_2020063120812    |       0.07 | 03-MAR-2020 12:08:12 | regiona.mjl_2020063120801    | Out of chain |
| N/A        | /path/to/regiona.mjl_2020063120822    |       0.07 | 03-MAR-2020 12:08:22 | regiona.mjl_2020063120812    | Out of chain |
| N/A        | /path/to/regiona.mjl_2020063121026    |       0.07 | 03-MAR-2020 12:10:26 | regiona.mjl_2020063120822    | Out of chain |
| N/A        | /path/to/regionb.mjl_2020063120753    |       0.07 | 03-MAR-2020 12:07:53 | -                            | Out of chain |
| N/A        | /path/to/regionb.mjl_2020063120800    |       0.07 | 03-MAR-2020 12:08:00 | -                            | Out of chain |
| N/A        | /path/to/regionb.mjl_2020063120801    |       0.07 | 03-MAR-2020 12:08:01 | regionb.mjl_2020063120800    | Out of chain |
| N/A        | /path/to/regionb.mjl_2020063120812    |       0.07 | 03-MAR-2020 12:08:12 | regionb.mjl_2020063120801    | Out of chain |
| N/A        | /path/to/regionb.mjl_2020063120822    |       0.07 | 03-MAR-2020 12:08:22 | regionb.mjl_2020063120812    | Out of chain |
| N/A        | /path/to/regionb.mjl_2020063121026    |       0.07 | 03-MAR-2020 12:10:26 | regionb.mjl_2020063120822    | Out of chain |
| N/A        | /path/to/regionc.mjl_2020063120753    |       0.07 | 03-MAR-2020 12:07:53 | -                            | Out of chain |
| N/A        | /path/to/regionc.mjl_2020063120800    |       0.07 | 03-MAR-2020 12:08:00 | -                            | Out of chain |
| N/A        | /path/to/regionc.mjl_2020063120801    |       0.07 | 03-MAR-2020 12:08:01 | regionc.mjl_2020063120800    | Out of chain |
| N/A        | /path/to/regionc.mjl_2020063120812    |       0.07 | 03-MAR-2020 12:08:12 | regionc.mjl_2020063120801    | Out of chain |
| N/A        | /path/to/regionc.mjl_2020063120822    |       0.07 | 03-MAR-2020 12:08:22 | regionc.mjl_2020063120812    | Out of chain |
| N/A        | /path/to/regionc.mjl_2020063121026    |       0.07 | 03-MAR-2020 12:10:26 | regionc.mjl_2020063120822    | Out of chain |
# Out of chain journal files:
 /path/to/gtmwizards.mjl_2020063120753 /path/to/gtmwizards.mjl_2020063120800 /path/to/gtmwizards.mjl_2020063120801 /path/to/gtmwizards.mjl_2020063120812 /path/to/gtmwizards.mjl_2020063120822 /path/to/gtmwizards.mjl_2020063121026 /path/to/regiona.mjl_2020063120753 /path/to/regiona.mjl_2020063120800 /path/to/regiona.mjl_2020063120801 /path/to/regiona.mjl_2020063120812 /path/to/regiona.mjl_2020063120822 /path/to/regiona.mjl_2020063121026 /path/to/regionb.mjl_2020063120753 /path/to/regionb.mjl_2020063120800 /path/to/regionb.mjl_2020063120801 /path/to/regionb.mjl_2020063120812 /path/to/regionb.mjl_2020063120822 /path/to/regionb.mjl_2020063121026 /path/to/regionc.mjl_2020063120753 /path/to/regionc.mjl_2020063120800 /path/to/regionc.mjl_2020063120801 /path/to/regionc.mjl_2020063120812 /path/to/regionc.mjl_2020063120822 /path/to/regionc.mjl_2020063121026
# Out of chain total        : 1.68 MiB
# Summary
| Region     | Size Total (MiB) | Recoverability up to |
| ---------- | ---------------- | -------------------- |
| GTMWIZARDS | 0.21             | 03-MAR-2020 12:10:35 |
| REGIONA    | 0.21             | 03-MAR-2020 12:10:35 |
| REGIONB    | 0.21             | 03-MAR-2020 12:10:35 |
| REGIONC    | 0.21             | 03-MAR-2020 12:10:35 |

The %dirty global buffer dashboard displays the region-wise percentage of global buffers vs dirty global buffers in a bar graph and the number of global buffers in a table. A large number of global buffers implies a large number of dirty global buffers to be flushed at an epoch. This dashboard along with the dynamic journal file chain can be used to determine an appropriate epoch interval / tapering settings for the application and help troubleshoot I/O spikes and process hangs during high loads.

This %JSWRITE reference implementation uses the STDIN^%JSWRITE singlesub entrypoint of the %JSWRITE utility routine.

Example:

$ node node_modules/@fis-gtm/jswrite/reference_implementations/gtmjsaccessbg.js

%YGBLSTAT Sparkline shows region-wise sparkline charts for the specified collection of statistics. Typically, you would group statistics by their relevance, for example, TR0,TR1,TR2,TR3, and TR4 can be grouped together to visualize variations for TP Restarts in a condensed form.

This %JSWRITE reference implementation uses the STDIN^%JSWRITE singlesub entrypoint of the %JSWRITE utility routine.

Example:

# Set the environment variable LC_ALL to a UTF8 locale (needed for the %JSWRITE Sparkline Chart (GTMJSGVSTATS.m/gtmjsgvstats.js) reference implementation)
node node_modules/@fis-gtm/jswrite/reference_implementations/gtmjsgvstats.js   # By default, this reference implementation displays a sparkline chart for SETs and GETs. For monitoring other statistics, open gtmjsgvstats.js and update the STAT array to include the list of statistics which require sparkline chart style monitoring. 

GTMJSGVSTATS.m is routine used in the %YGBLSTAT sparkline chart reference implementation. You can use the same routine to create a JSON file which can be imported to spreadsheet software such as Excel. The following command creates gvstats.json which includes all statistics produced with the %YGBLSTAT utility for all regions which have opted for statistics sharing.

$gtm_dist/mumps -r ^GTMJSGVSTATS | $gtm_dist/mumps -r STDIN^%JSWRITE singlesub > /src/toExcel/gvstats.json

You can also choose the statistics that you want in the JSON file with the following:

$gtm_dist/mumps -r ^GTMJSGVSTATS TR0,TR1,TR2,TR3,TR4 | $gtm_dist/mumps -r STDIN^%JSWRITE singlesub > /src/toExcel/gvstats.json

You can import gvstats.json in Excel using the "Data->Get Data->From File->From JSON" option of Excel.

This %JSWRITE reference implementation uses the STDIN^%JSWRITE singlesub entrypoint of the %JSWRITE utility routine.

JSWRITE.js is a utility class for managing objects created with the ^%JSWRITE utility routine of GT.M. It helps with object mutation and cases when you need to round-trip data back to GT.M. The use of JSWRITE.js is optional and is provided as a convenience to JavaScript developers working on ^%JSWRITE utility routine.

The constructor of JSWRITE.js takes one argument which can be an array collection object from %JSWRITE(glvn,[#]|[*]), one object string %JSWRITE(glvn,#|*), or an empty object. After instantiation, the object has the following getter function.

GTM>zwrite
A("One","Two","Three","Four")="Demo"
GTM>do ^%JSWRITE("A","*")
{"A":{"One":{"Two":{"Three":{"Four":"Demo"}}}}}

> var JSWRITE=require("@fis-gtm/jswrite")
> JSObj=new JSWRITE({"A":{"One":{"Two":{"Three":{"Four":"Demo"}}}}})

Examples:

.toZWR()

>var JSWRITE=require("@fis-gtm/jswrite")
undefined
> JSObj=new JSWRITE({})
undefined
> JSObj.toZWR({"A":{"A1":[1,2,{"C":"C3"},4]}})
undefined
> JSObj.getZWRLines
[
  'A("A1","0")="1"',
  'A("A1","1")="2"',
  'A("A1","2","C")="C3"',
  'A("A1","3")="4"'
]
>

.customZWR()

> JSObj.customZWR("A",[1,2,3,4,5],"ABCD\n")
undefined
> JSObj.getZWRLines
[ 'A(1,2,3,4,5)="ABCD"_$C(10)_""' ]