Introduction: QMF and JavaScript

Why JavaScript?QMF for TSO has long used Rexx as that scripting language for Procs. Eventually IBM created a version of Rexx for Windows that QMF for Workstation also supported. However this version of Rexx is not exactly the same as the Rexx on the mainframe, and there is no version for Rexx that QMF for WebSphere could use. JavaScript on the other hand can be executed by QMF for Workstation and QMF for WebSphere and the QMF Z client. It is also fast becoming one of the most widely used scripting languages in the world. It is simple and well documented with many free educational resources on the internet.

Why have JavaScript or any scripting in Procs?JavaScript is a simple scripting language that allows conditional branching, iterations, message boxes, text manipulation, and access to the values returned by result sets.The regular QMF Proc is sometimes called a Linear Proc. This is because the commands execute one at a time, in sequence. If any command fails, the proc ends and the rest of the commands are not executed. A JavaScript Proc can check for the existence of objects before running a query against them, or run different queries based on the logic flow of the script.JavaScript Procs allow conditional IF statements to allow the Proc to choose which commands to execute. JavaScript Procs can allow iteration of commands and the extraction of values from a query result. This would allow a query to be run that gets a list of key values. Then a second query that takes any one of those values as input can be run iteratively taking each key value from the first query and making a separate report for each.

Which JavaScript?There are several organizations that have published implementations of JavaScript. QMF uses the Mozilla Rhino implementation. Rhino is for logic, workflow, calculations and data manipulation. It does not supply methods for GUI generation. When looking at JavaScript tutorials online, keep in mind that many of the other JavaScript engines may allow for generating dialog boxes for input or menu options or other UI objects and these will not be applicable in QMF. Instead QMF supplies a set of its own dialogs for interaction when Procs are running

Is JavaScript just in Procs?No. This series will start with useful applications of JavaScript in Procs, but then examples will be given for JavaScript calculated columns in query results that generate data at the QMF client, and new type of object called a JavaScript table. This is a table that is define in JavaScript and designates a web-based data source (many industry and government web sites supply this type of data) and is presented to the user for SQL query access and incorporation into nay QMF analysis, report, or visualization.

These documents will use the QMF Sample tables, and will supply the files for the Procs, Queries, and Forms used. To import these objects, you use the File> Open From menu in QMF for Workstation or QMF for WebSphere component and save the object to the QMF Catalog or to a Workspace folder.

Part One: QMF BasicsThere are just a few QMF specific JavaScript Proc commands built into the QMF for Workstation and QMF for WebSphere components. This example will use the two boxed in below.

Here is a query that may or may not get a result set depending on the value supplied for the prompt.

Here are two Forms. One, JSF_STAFF1, for the case with a result set and one, JSF_STAFF2, for the case with no result set.

The Proc :Prompts for a DEPT value and places it in a GLOBAL VARIABLE for use by the Query.Next it runs the Query.Then it displays the Form that makes the report that is fit for the case when there are results.Then it displays the Form that makes the report that is fit for the case when there are NO results.I would NOT use both of these Forms for the same result set. Therefore, I will add a logical condition to choose one of these reports.Finally it sends me a warning email that the report has failed. Again, I only want this email sent IF the report fails.

SET GLOBAL (DEPT=&Please_Enter_Dept_ValueRUN QUERY DB2ADMIN.JSQ_STAFFDISPLAY FORM DB2ADMIN.JSF_STAFF1DISPLAY FORM DB2ADMIN.JSF_STAFF2MAIL REPORT TO ssullivan@rs.com + (BODY="The report failed with this value of DEPT" + FORMAT=HTML FROM=ssullivan@rs.com + SMTPSERVER=MAIL.ROCKETSOFTWARE.COM + SUBJECT="JSQ Report Failure"

In the Design editor it looks like this: I click Condition and then click above the node where I want the condition.

Here is where I want to add the condition that determines which Form to use and whether to send the email

The condition I want, is that if there are zero rows returned then, do this, otherwise do that. I use the proc.getNumRows() function

Now the flow looks like this:

I drag the DISPLAY and MAIL commands to the appropriate sides of the condition.

Now the flow looks like this:

The Proc text is now like this/*JavaScript*/proc.exec('SET GLOBAL (DEPT=&Please_Enter_Dept_Value');proc.exec('RUN QUERY DB2ADMIN.JSQ_STAFF');if (proc.getNumRows()>0) {

proc.exec('DISPLAY FORM DB2ADMIN.JSF_STAFF1');}else {

proc.exec('DISPLAY FORM DB2ADMIN.JSF_STAFF2');proc.exec('MAIL REPORT TO ssullivan@rs.com (BODY="The report failed with this value of DEPT" FORMAT=HTML FROM=ssullivan@rs.com SMTPSERVER=MAIL.ROCKETSOFTWARE.COM SUBJECT="JSQ Report Failure"');

}

Now a couple of test runs:The value of DEPT =38 is valid and DEPT =39 is not valid and returns zero records.Test run #1

Result

Test run #2

Part 2: General JavaScript Procs Best PracticesThe previous document developed a working JavaScript Proc. This document will try to give some tips for making JavaScript Procs neater and more manageable.

The traditional QMF Proc command gets encased, start to finish, in single quotesFor exampleproc.exec('RUN QUERY DB2ADMIN.JSQ_STAFF');

The continuation character for splitting a line is a plus sign +. To break up a long Proc command follow these steps:

1) Add a single quote BEFORE the carriage return2) Add a plus sign + on the next line 3) Add a single quote right after the +

For example:proc.exec('RUN QUERY '+ 'DB2ADMIN.JSQ_STAFF');

The MAIL command generated by the Design editor is a long single line. You will need to split it into smaller lines for readability and to fit it into the QMF catalog.

Applying continuation character guidelines above to this to the MAIL command:

/*JavaScript*/proc.exec('SET GLOBAL (DEPT=&Please_Enter_Dept_Value');proc.exec('RUN QUERY DB2ADMIN.JSQ_STAFF');if (proc.getNumRows() > 0) {

proc.exec('DISPLAY FORM DB2ADMIN.JSF_STAFF1');}else {

proc.exec('DISPLAY FORM DB2ADMIN.JSF_STAFF2');proc.exec('MAIL REPORT TO ssullivan@rs.com '+ '(BODY="The report failed with this value of DEPT" '+ 'FORMAT=HTML FROM=ssullivan@rs.com '+ 'SMTPSERVER=MAIL.ROCKETSOFTWARE.COM '+ 'SUBJECT="JSQ Report Failure"');

}

Test run and save to the QMF Catalog.

Once I make edits that can’t be replicated in the Design editor, like the continuation characters, I cannot switch back to the Design editor.

The Mail command is the trickiest to manipulate in JavaScript. This is because MAIL commands contain Body text that tends to span multiple lines, and need to be encased in quotes, Subject text that needs to be quoted, and both Subject and Body may want to include values from variables or query results.

The recommended approach is to specify FORMAT=HTML. This refers to the format of the email. With this format, HTML tags can be included to control the look of the body

proc.exec('MAIL REPORT TO ssullivan@rs.com ' +'(BODY="The report failed with this value of DEPT.<br>'       +' The value needs to be<br>'       +' in the org table" '       +'FORMAT=HTML FROM=ssullivan@rs.com '       +'SMTPSERVER=MAIL.ROCKETSOFTWARE.COM '       +'SUBJECT="JSQ Report Failure"');This give an email message like this:

Instead of this:

In order to insert values from Globals or from query results into the email subject or body use the following approach.Define the sections of the MAIL command as variables, and then piece them together with the concatenation symbol. This avoids issues with quotes within quotes and continuation characters.

/*JavaScript*/proc.exec('SET GLOBAL (DEPT=&Please_Enter_Dept_Value');proc.exec('RUN QUERY DB2ADMIN.JSQ_STAFF'); var M ='MAIL REPORT TO ssullivan@rs.com ';var B ='(BODY="The report failed with this value of DEPT "';var F =' FORMAT=HTML FROM=ssullivan@rs.com ';var S =' SMTPSERVER=MAIL.ROCKETSOFTWARE.COM ';var SU =' SUBJECT="JSQ Report Failure for Dept = ' + proc.getVariable('DEPT') + '"' ; if (proc.getNumRows() >0) { proc.exec('DISPLAY FORM DB2ADMIN.JSF_STAFF1');}else { proc.exec('DISPLAY FORM DB2ADMIN.JSF_STAFF2'); proc.exec(M + B + F + S + SU);

}

Notice that the SU variable is made of TWO lines with a continuation character. The first line has the static text and the second line has the input variable used for the query.