RunTime Adaptor User Guide / Specification for the MainSpace SDK

Welcome to the Mainframe Cloud (MfC) RunTime Adaptor User Guide. The MfC RunTime Adaptor is a Web Service Agent (WS Agent) that allows web app developers to build applications for the mainframe in web languages such as JavaScript and HTML5. This release of RunTime Adaptor supports a DB2 Interface.

This guide is intended for users who want to rapidly write web apps for the MfC WS Agent using the MainSpace SDK.

The MainSpace SDK allows web app developers to code web service calls using MainSpace JavaScript functions instead of URL GET / POST request structures.

To write a web app using the MainSpace SDK, you need to do the following:

  1. Create an MFCAgentRequest object.
  2. Nominate a callback function.
  3. Set your z/OS login credentials.
  4. Set the Mainframe Cloud Web Service Agent URL.
  5. Set the z/OS DB2 subsystem identifier you wish to interrogate (for a DB2 web app).
  6. Execute the required API method (e.g., runSQL to execute a query to DB2).

See MFCAgentRequest.newObject for details and to create your first web app.

See runSQL for more examples and best practices.



MFCAgentRequest

The MFCAgentRequest object provides API methods to perform web service calls to the Mainframe Cloud Web Service Agent.

Method Summary

newObject() → {MFCAgentRequest.thisObject}
Creates a new instance of the MFCAgentRequest object. This object provides API methods to perform web service calls to the mainframe.
connectDB2()
Executes a DB2 connection SQL statement.
disconnectDB2()
Terminates the session with DB2.
executePipe(sqls, endonwarnopt)
Executes the SQL statements in the sqls  array parameter (the SQL pipe).
executeQPE(tables1, tables2, arg1)
Executes the stored SQL rules loaded at QPE initialization.
initQPE(sqltext, sqlcallbacks, endonwarnopt)
Initializes the Query Process Engine (QPE).
logoff()
Terminates the active web application session.
runSQL(runsql_input, connectedopt)
Executes the SQL statement in the runsql_input  parameter.
runUpdateSQL(runsql_input)
"One-shot" SQL update call which executes the SQL update statement in the runsql_input  parameter.
setDB2SSID(db2ssid)
Sets the z/OS DB2 subsystem identifier you wish to interrogate.
setLogin(userid, password)
Sets your z/OS TSO login credentials.
setLogoffSession(logoffsession)
Sets the auto-logoff property used for "one-shot" SQL calls (single SQL statement requests), Pipes, and QPE rules.
setSQLTERM(sqlterm)
Sets the SQL termination character.
setURL(url)
Sets the web service URL.

Property Summary

callbackFunction
The callbackFunction property is used to define the JavaScript function to execute when an API call is complete.
pipeSQLs
The pipeSQLs property is the array of SQL statements to execute in a Pipe (the SQL pipe).
qpeResponse
The qpeResponse property is an array of thisObject.response  objects returned from each API call executed in a QPE process.
response
The response property is the JSON object returned from an API call.

Method Detail

(static) newObject() → {MFCAgentRequest.thisObject}

Creates a new instance of the MFCAgentRequest object. This object provides API methods to perform web service calls to the mainframe. The first request executed by a new object instance will perform an implicit logon using the credentials defined by setLogin. This validates the logon credentials and creates an active session for the web application.

The example code below executes a simple SQL query and displays the return response object as an unformatted string.

Example Explained
To run the example; select, copy, and paste the content into a new HTML file. Then change Lines 19 to 21 to suit your sites requirements using the explanations below to assist.
Lines 1 to 15 and Lines 29 to 31 contain the HTML code required to run the example as a standalone web page.
Line 17 - Creates the API object to work with. A new MFCAgentRequest object instance is created and assigned to variable obj1.
Line 18 - Nominates the callback function to be executed when the API call is complete. The callback function definition specifies a function name "simpleCallBack" and the input object thisObject.response to feed to that function.
Line 19 - Sets your z/OS TSO login credentials. See setLogin.
Line 20 - Sets the web service URL. See setURL.
Line 21 - Sets the z/OS DB2 subsystem identifier you wish to interrogate. See setDB2SSID.
Line 22 - Executes a single SQL query to DB2 on the mainframe. This is a "one-shot" SQL call. See runSQL.
On the mainframe the following actions occur:
   1. Because this is the first request performed by the object, a logon is performed and a new session is created for the web application.
   2. Because this is a "one-shot" SQL call, an automatic DB2 connect is performed before executing the SQL query, followed by a disconnect, and logoff when the SQL query is complete.
Line 25 - When the API call is complete, the callback function specified in Line 18 will execute. This function defines local variable response, which will be populated by the API call response thisObject.response. The simple callback function example converts the response data into a raw string and populates the web page "container" element.
Returns:
Type
MFCAgentRequest.thisObject
Example
<!DOCTYPE html>
<!--
    Mainframe Cloud Pty Ltd MAINSPACE WEB APP EXAMPLE
-->
<html>
  <body>
    <div id="container"></div>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- MainSpace API JS library                                        -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script type="text/javascript" src="https://www.mainframecloudplatform.com/applibs/mainspace-webmf.js"></script>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- JavaScript control code section                                 -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    
      var obj1 = MFCAgentRequest.newObject();
      obj1.callbackFunction = "simpleCallBack( thisObject.response );";
      obj1.setLogin( "TSOUSER", "TSOPASS" );
      obj1.setURL( "http://hostname:port/" );
      obj1.setDB2SSID( "DBBG" );
      obj1.runSQL( "SELECT * FROM DSN81110.EMP FETCH FIRST 20 ROWS ONLY" );
    
      // Simple app callback function. Display JSON response in raw format.
      function simpleCallBack( response ) {
          document.getElementById("container").innerHTML = JSON.stringify( response );
      }
    
    </script>
  </body>
</html>

connectDB2()

Executes a DB2 connection SQL statement. This connects to the DB2 subsystem identifier defined by setDB2SSID.
After a successful connection, subsequent SQL statements can be executed on the same DB2 session.

NOTE: For "one-shot" SQL calls (single SQL statement requests), Pipes, and QPE rules; an automatic connect, disconnect, and logoff is already performed.
For more information see:
1. "One-shot" SQL calls for queries
2. "One-shot" SQL calls for updates
3. Pipes
4. QPE

The example code below connects to DB2, executes 3 SQL queries on the same DB2 session, then terminates the connected DB2 session and the active web application session. This example does not execute a "one-shot" SQL call therefore there is no automatic connect, disconnect, or logoff performed.

Example Explained
To run the example; select, copy, and paste the content into a new HTML file. Then change Lines 20 to 22 to suit your sites requirements using the explanations below to assist.
Lines 1 to 15 and Lines 34 to 36 contain the HTML code required to run the example as a standalone web page.
Line 17 - Initializes the variable counter cnt  used to control the number of SQL queries executed.
Line 18 - Creates the API object to work with. A new MFCAgentRequest object instance is created and assigned to variable obj1.
Line 19 - Nominates the callback function to be executed when the API call is complete. The callback function definition specifies a function name "callBack" and the input object thisObject  to feed to that function.
Line 20 - Sets your z/OS TSO login credentials. See setLogin.
Line 21 - Sets the web service URL. See setURL.
Line 22 - Sets the z/OS DB2 subsystem identifier you wish to interrogate. See setDB2SSID.
Line 23 - Executes a DB2 connection SQL statement. Because this is the first request performed by the object, a logon is performed and a new session is created for the web application.
Line 26 - When the API call is complete, the callback function specified in Line 19 will execute. This function defines local variable msobj, which will be populated by the API call response thisObject.
Line 27 - The callback function example converts the response data into a raw string and populates the web page "container" element.
Line 28 - The variable counter cnt  is incremented and evaluated to determine if it is greater than 3.
Line 31 - Executes an SQL query on the existing DB2 session. The connected  parameter is set to true therefore this is not a "one-shot" SQL call. See runSQL.
When the API call is complete, the callback function will execute again and process Lines 27 to 31. This will occur 3 times.
On the 3rd callback function execution, the variable counter cnt  is greater than 3, therefore (in Line 29) the callback function definition is updated to the API logoff method thisObject.logoff()
When the next SQL query API call is complete, the new callback function thisObject.logoff() executes and terminates the connected DB2 session and the active web application session.
See:
  • Pipes and QPE for more efficient methods for executing multiple SQL statements within a DB2 session.
Example
<!DOCTYPE html>
<!--
    Mainframe Cloud Pty Ltd MAINSPACE WEB APP EXAMPLE
-->
<html>
  <body>
    <div id="container"></div>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- MainSpace API JS library                                        -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script type="text/javascript" src="https://www.mainframecloudplatform.com/applibs/mainspace-webmf.js"></script>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- JavaScript control code section                                 -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    
      var cnt  = 0;
      var obj1 = MFCAgentRequest.newObject();
      obj1.callbackFunction = "callBack( thisObject );";
      obj1.setLogin( "TSOUSER", "TSOPASS" );
      obj1.setURL( "http://hostname:port/" );
      obj1.setDB2SSID( "DBBG" );
      obj1.connectDB2();
    
      // App callback function. Execute SQL after initial connect, repeat 3 times, then logoff.
      function callBack( msobj ) {
          document.getElementById("container").innerHTML += '<br><br>' + JSON.stringify( msobj.response );
          if ( ++cnt > 3 ) {
              msobj.callbackFunction = "thisObject.logoff();";
          }
          msobj.runSQL( "SELECT * FROM DSN81110.EMP FETCH FIRST 20 ROWS ONLY", true );
      }
    
    </script>
  </body>
</html>

disconnectDB2()

Terminates the session with DB2. If there are any pending SQL updates, a commit SQL statement must first be issued to commit the updates permanently.
A DB2 disconnect does not terminate the application session created at logon, a logoff is required to terminate the active web application session.

NOTE: For "one-shot" SQL calls (single SQL statement requests), Pipes, and QPE rules; an automatic connect, commit (if applicable), disconnect, and logoff is already performed.
For more information see:
1. "One-shot" SQL calls for queries
2. "One-shot" SQL calls for updates
3. Pipes
4. QPE

The example code below contains a runQueries function and a logoff function. Both functions are triggered by HTML button elements "Run" and "Logoff".
The runQueries function connects to DB2, executes 3 SQL queries on the same DB2 session, then terminates the session with DB2. It does not terminate the active web application session.
The first time the runQueries function runs, a logon is performed and a new session is created for the web application.
Each subsequent runQueries function run executes within the same active web application session.
The logoff function issues a logoff to terminate the active web application session.
The next time the runQueries function runs (after logoff), a logon is performed and a new session is created for the web application.

Example Explained
To run the example; select, copy, and paste the content into a new HTML file. Then change Lines 24 to 26 to suit your sites requirements using the explanations below to assist.
Lines 1 to 20 and Lines 49 to 51 contain the HTML code required to run the example as a standalone web page.
Line 23 - Creates the API object to work with. A new MFCAgentRequest object instance is created and assigned to variable obj1.
Line 24 - Sets your z/OS TSO login credentials. See setLogin.
Line 25 - Sets the web service URL. See setURL.
Line 26 - Sets the z/OS DB2 subsystem identifier you wish to interrogate. See setDB2SSID.
Line 29 - The runQueries function:
Line 30 - Initializes the object variable uservar.count  used to control the number of SQL queries executed.
Line 31 - Nominates the callback function to be executed when the API call is complete. The callback function definition specifies a function name "callBack" and the input object thisObject  to feed to that function.
Line 32 - Executes a DB2 connection SQL statement. Because this is the first request performed by the object, a logon is performed and a new session is created for the web application.
Line 36 - When the API call is complete, the callback function specified in Line 31 will execute. This function defines local variable msobj, which will be populated by the API call response thisObject.
Line 37 - The callback function example converts the response data into a raw string and populates the web page "container" element.
Line 38 - The object variable uservar.count  is incremented and evaluated to determine if it is greater than 3.
Line 41 - Executes an SQL query on the existing DB2 session. The connected  parameter is set to true therefore this is not a "one-shot" SQL call. See runSQL.
When the API call is complete, the callback function will execute again and process Lines 37 to 41. This will occur 3 times.
On the 3rd callback function execution, the object variable uservar.count  is greater than 3, therefore (in Line 39) the callback function definition is updated to the API disconnectDB2 method thisObject.disconnectDB2()
When the next SQL query API call is complete, the new callback function thisObject.disconnectDB2() executes and terminates the DB2 session.
Line 45 - The logoff function:
Line 46 - Executes the API logoff method. This terminates the active web application session.
See:
  • Pipes and QPE for more efficient methods for executing multiple SQL statements within a DB2 session.
Example
<!DOCTYPE html>
<!--
    Mainframe Cloud Pty Ltd MAINSPACE WEB APP EXAMPLE
-->
<html>
  <body>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- Web page elements                                               -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <INPUT type=button value="Run" onclick="runQueries();" title="Run queries.">
    <INPUT type=button value="Logoff" onclick="logoff();" title="Logoff session.">
    <div id="container"></div>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- MainSpace API JS library                                        -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script type="text/javascript" src="https://www.mainframecloudplatform.com/applibs/mainspace-webmf.js"></script>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- JavaScript control code section                                 -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    
      // Initialize API variables.
      var obj1 = MFCAgentRequest.newObject();
      obj1.setLogin( "TSOUSER", "TSOPASS" );
      obj1.setURL( "http://hostname:port/" );
      obj1.setDB2SSID( "DBBG" );
    
      // Initiate SQL query process.
      function runQueries() {
          obj1.uservar = { "count": 0 };
          obj1.callbackFunction = "callBack( thisObject );";
          obj1.connectDB2();
      }
    
      // App callback function. Execute SQL after initial connect, repeat 3 times, then disconnect from DB2.
      function callBack( msobj ) {
          document.getElementById("container").innerHTML += '<br><br>' + JSON.stringify( msobj.response );
          if ( ++msobj.uservar.count > 3 ) {
              msobj.callbackFunction = "thisObject.disconnectDB2();";
          }
          msobj.runSQL( "SELECT * FROM DSN81110.EMP FETCH FIRST 20 ROWS ONLY", true );
      }
    
      // Terminate web service application session.
      function logoff() {
          obj1.logoff();
      }
    
    </script>
  </body>
</html>

executePipe(sqls, endonwarnopt)

Executes the SQL statements in the sqls  array parameter (the SQL pipe).
A Pipe is used to execute multiple SQL statements in sequence within a DB2 session. After each SQL statement is complete, the next SQL statement in the Pipe is executed.
Web applications using the executePipe method are required to provide a pipeResponse JavaScript function. This function is executed after each SQL API call is complete. The pipeResponse function is how your web page can be updated with the response data returned from each SQL API call.

The optional endonwarn  parameter defines if Pipe processing should end when an API call returns with warnings. The default behaviour is to end processing if an API call returns with warnings.

NOTE: Pipes support automatic connect, disconnect, and logoff. The executePipe method performs the following:
1. Executes a DB2 connection SQL statement, to create a new DB2 session.
2. Executes the SQL statements in sqls, on the new DB2 session.
3. Executes a DB2 disconnect or logoff, depending on the auto-logoff flag set in setLogoffSession.

The example code below connects to DB2, executes 3 SQL queries on the same DB2 session, then terminates the connected DB2 session and the active web application session.

Example Explained
To run the example; select, copy, and paste the content into a new HTML file. Then change Lines 25 to 27 to suit your sites requirements using the explanations below to assist.
Lines 1 to 15 and Lines 36 to 38 contain the HTML code required to run the example as a standalone web page.
Line 18 - Initializes the array variable sqls  with the list of SQL queries to execute.
Line 24 - Creates the API object to work with. A new MFCAgentRequest object instance is created and assigned to variable obj1.
Line 25 - Sets your z/OS TSO login credentials. See setLogin.
Line 26 - Sets the web service URL. See setURL.
Line 27 - Sets the z/OS DB2 subsystem identifier you wish to interrogate. See setDB2SSID.
Line 29 - Executes SQL pipe sqls  defined in Line 18. This performs the following:
   1. Executes a DB2 connection SQL statement. Because this is the first request performed by the object, a logon is performed and a new session is created for the web application.
   2. Once connected to DB2, the first SQL query in the Pipe executes.
   3. When the first Pipe API call is complete, the second SQL query in the Pipe executes.
   4. When the second Pipe API call is complete, the third (final) SQL query in the Pipe executes.
   5. When the final Pipe API call is complete, a logoff is performed to terminate the connected DB2 session and the active web application session.
Line 32 - When each Pipe API call is complete, the pipeResponse function executes. This function defines local variable response, which will be populated by the API call response thisObject.response.
Line 33 - The pipeResponse function example converts the response data into a raw string and populates the web page "container" element.
Parameters:
Name Type Attributes Default Description
sqls Array.<String> The array of SQL statements to execute (the SQL pipe).
endonwarn Boolean | Array.<Boolean> <optional>
true True to end processing if an API call returns with warnings, false to continue processing.
Example
<!DOCTYPE html>
<!--
    Mainframe Cloud Pty Ltd MAINSPACE WEB APP EXAMPLE
-->
<html>
  <body>
    <div id="container"></div>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- MainSpace API JS library                                        -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script type="text/javascript" src="https://www.mainframecloudplatform.com/applibs/mainspace-webmf.js"></script>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- JavaScript control code section                                 -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    
      // Set the SQL pipe to execute.
      var sqls = [ "SELECT * FROM DSN81110.EMP FETCH FIRST 20 ROWS ONLY",
                   "SELECT * FROM DSN81110.EMP FETCH FIRST 20 ROWS ONLY",
                   "SELECT * FROM DSN81110.EMP FETCH FIRST 20 ROWS ONLY"
                 ];
    
      // Initialize API object.
      var obj1 = MFCAgentRequest.newObject();
      obj1.setLogin( "TSOUSER", "TSOPASS" );
      obj1.setURL( "http://hostname:port/" );
      obj1.setDB2SSID( "DBBG" );
      // Execute Pipe.
      obj1.executePipe( sqls );
    
      // Pipe response function. Display JSON response in raw format.
      function pipeResponse( response ) {
          document.getElementById("container").innerHTML += '<br><br>' + JSON.stringify( response );
      }
    
    </script>
  </body>
</html>

executeQPE(tables1, tables2, arg1)

Executes the stored SQL rules loaded at QPE initialization.
This translates QPE SQL rules into SQL statements using criteria objects passed at runtime (tables*  and arg*  parameters), then executes the SQL statements in an SQL pipe.

See initQPE to learn how to use the Query Process Engine (QPE).
Parameters:
Name Type Description
tables1 Array.<String> Criteria table list 1.
tables2 Array.<String> Criteria table list 2.
arg1 String Criteria argument 1.

initQPE(sqltext, sqlcallbacks, endonwarnopt)

Initializes the Query Process Engine (QPE) by performing the following:
1. Loads the SQL rules defined in the sqltext  parameter.
2. Loads the SQL callback definitions defined in the sqlcallbacks  array parameter. The sqlcallbacks  parameter contains user-defined functions to execute after select QPE API calls.

The optional endonwarn  parameter defines if QPE processing should end when an API call returns with warnings. The default behaviour is to end processing if an API call returns with warnings.

What is QPE
Similar to Pipes, QPE is used to execute multiple SQL statements in sequence within a DB2 session. After each SQL statement is complete, the next QPE SQL statement is executed.
Also, QPE allows web applications to perform the following user-defined input data and output data manipulation at runtime:
1. Input data manipulation via executeQPE method criteria parameters.
2. Output data manipulation via SQL callback definitions defined in the sqlcallbacks  array parameter.

Using QPE
For a web application to use QPE, the following method calls are required:
1. initQPE to initialize QPE.
2. executeQPE to execute QPE.
Web applications using QPE are required to provide the following:
1. A qpeSuccess JavaScript function. This function is executed after the final QPE API call is complete. The qpeSuccess function is how your web page can be updated with the qpeResponse data array returned from QPE.
2. A qpeError JavaScript function. This function is executed if QPE ends due to an API call error. The qpeError function is how your web page can be updated with the response data returned from the API call that ended QPE with a non-zero sqlcode.

NOTE: QPE supports automatic connect, disconnect, and logoff. The executeQPE method performs the following:
1. Executes a DB2 connection SQL statement, to create a new DB2 session.
2. Executes QPE SQL statements on the new DB2 session.
3. Executes a DB2 disconnect or logoff, depending on the auto-logoff flag set in setLogoffSession.

Example Explained

To run the example:
   1. Select, copy, and paste the content into a new HTML file. Then change Lines 26 to 28 to suit your sites requirements using the explanations below to assist.
   2. Download the SQL Rules file (QPE-Example-SQL-Rules.sql) and save it to the same web server directory as the example HTML file.
   3. Create the DB2 sample table "DSN81110.EMP" used in this example. See QPE-Sample-Table for details.

Lines 1 to 19 and Lines 127 to 129 contain the HTML code required to run the example as a standalone web page.
Line 22 - Initializes the variable filter_department  with the criteria argument to pass to the executeQPE method in Line 56.
Line 25 - Creates the API object to work with. A new MFCAgentRequest object instance is created and assigned to variable obj1.
Line 26 - Sets your z/OS TSO login credentials. See setLogin.
Line 27 - Sets the web service URL. See setURL.
Line 28 - Sets the z/OS DB2 subsystem identifier you wish to interrogate. See setDB2SSID.

Initialize QPE
Line 30 - Executes the initialize function (Line 33) to initialize QPE with arguments "QPE-Example-SQL-Rules.sql" and getSqlCallBacks(). This executes the getSqlCallBacks function (Line 60) and passes the return object to the initialize function call. See initialize and getSqlCallBacks function descriptions below.

Line 33 - The initialize function:   (called in Line 30)
Lines 35 to 44 - Uses an XMLHttpRequest object to read the contents of the sqlfile  and assign the return response string to the sqlfile_content  variable in line 38.
Line 40 - When the XMLHttpRequest call is complete, the API initQPE method executes. This loads to QPE; the SQL rules from the sqlfile_content  variable, and the SQL callback definitions passed in the sqlcallbacks  parameter.

Execute QPE
Line 48 - The runQueries function:   (triggered by "Run" HTML button element in Line 10)
Lines 50 to 53 - Initializes the array variable tables1  with the table list criteria argument to pass to the executeQPE method in Line 56.
Line 54 - Initializes the variable tables2  to an empty array.
Line 56 - Executes the API executeQPE method with arguments tables1, tables2, and filter_department. This performs the following:
   1. Steps through each QPE SQL rule and translates the <%TABLE1%> field to the value in the corresponding tables1  array element.
   2. Performs no <%TABLE2%> translation because the tables2  array is empty.
   3. Translates all QPE SQL rule <%ARG1%> fields to the value in the filter_department  variable.
   4. Executes the translated SQL statements in an SQL pipe.

QPE Example SQL Rules Explained
   - The SQL Rules file (QPE-Example-SQL-Rules.sql) contains three rules.
   - Every rule contains <%TABLE1%> fields. These require replacement values in the executeQPE method tables1  array parameter.
   - The executeQPE method also supports <%TABLE2%> field rule translations via the executeQPE method tables2  array parameter.
   - The first two rules contain <%ARG1%> fields. These require replacement values in the executeQPE method arg1  parameter.
   - The last rule contains an <%ARG2%> field. This field is translated further down the SQL pipe by an SQL callback definition function (Line 78).

QPE Pipe Flow Explained
The executeQPE method executes the translated SQL statements in an SQL pipe. This performs the following:
   1. Executes a DB2 connection SQL statement. Because this is the first request performed by the object, a logon is performed and a new session is created for the web application.
   2. Once connected to DB2, the first SQL query in the Pipe executes.
   3. When the first Pipe API call is complete*, QPE executes the following:
        - The first SQL callback definition function (Line 64). This function defines local variable msobj, which will be populated by the API call response thisObject.
        - The second SQL query in the Pipe.
   4. When the second Pipe API call is complete*, QPE executes the following:
        - The second SQL callback definition function (Line 68). This function defines local variable msobj, which will be populated by the API call response thisObject.
        - The third (final) SQL query in the Pipe.
   5. When the third (final) Pipe API call is complete*, QPE executes the following:
        - The third SQL callback definition function (Line 83). This function defines local variable msobj, which will be populated by the API call response thisObject.
        - A logoff to terminate the connected DB2 session and the active web application session.
        - The qpeSuccess function (Line 105). This function defines local array variable response, which will be populated by the qpeResponse data array returned from QPE.
   * When each Pipe API call is complete, the API call response object and associated SQL callback definition function return object are added to the qpeResponse data array.

Line 60 - The getSqlCallBacks function:   (called in Line 30)
Line 62 - Initializes the SQL callback definitions list object array sqlcb.
Line 64 - Defines the first SQL callback definition function (array element index 0) called by QPE when the first Pipe API call is complete. This function defines local variable msobj, which will be populated by the API call response thisObject.
Line 65 - Calls the auCurrencyFormat function (Line 98) to format the response object field "TOTAL_SALARY" in the first row.
Line 68 - Defines the second SQL callback definition function (array element index 1) called by QPE when the second Pipe API call is complete. This function defines local variable msobj, which will be populated by the API call response thisObject.
Line 69 - Initializes the object variable rows  with the API call response row object.
Lines 71 to 76 - Initializes the object variable respdata  with fields from the first row.
Line 75 - Calls the auCurrencyFormat function (Line 98) to format the response object field "SALARY" in the first row.
Line 78 - Translates the third QPE SQL rule <%ARG2%> field to the value in the respdata.JOB  object variable defined in Line 74.
Line 83 - Defines the third SQL callback definition function (array element index 2) called by QPE when the third Pipe API call is complete. This function defines local variable msobj, which will be populated by the API call response thisObject.
Line 84 - Initializes the object variable rows  with the API call response row object.
Lines 85 to 89 - Initializes the object variable respdata  with fields from the first row.
Line 88 - Calls the auCurrencyFormat function (Line 98) to format the response object field "SALARY" in the first row.
Line 94 - Returns the new SQL callback definitions list object array sqlcb to the caller.

Line 98 - The auCurrencyFormat function:   (called by SQL callback definitions defined in the getSqlCallBacks function)
This is a general JavaScript function used to format the fldvalue  input parameter into AUD currency.

Line 105 - The qpeSuccess function:   (executed after the final QPE API call is complete)
Lines 107 to 119 - Updates the web page "container" element with data extracted from the response array returned from QPE.

Line 123 - The qpeError function:   (executed if QPE ends due to an API call error)
Line 124 - Converts the response data returned from QPE into a raw string and populates the web page "container" element.
Parameters:
Name Type Attributes Default Description
sqltext String The QPE SQL rules to load.
sqlcallbacks Array.<Object> The QPE SQL callback definitions to load.
endonwarn Boolean | Array.<Boolean> <optional>
true True to end processing if an API call returns with warnings, false to continue processing.
See:
Example
<!DOCTYPE html>
<!--
    Mainframe Cloud Pty Ltd MAINSPACE WEB APP EXAMPLE
-->
<html>
  <body>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- Web page elements                                               -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <INPUT type=button value="Run" onclick="runQueries();" title="Run queries.">
    <div id="container"></div>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- MainSpace API JS library                                        -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script type="text/javascript" src="https://www.mainframecloudplatform.com/applibs/mainspace-webmf.js"></script>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- JavaScript control code section                                 -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    
      // INPUT FILTER
      var filter_department = 'D11';
    
      // Initialize API object.
      var obj1 = MFCAgentRequest.newObject();
      obj1.setLogin( "TSOUSER", "TSOPASS" );
      obj1.setURL( "http://hostname:port/" );
      obj1.setDB2SSID( "DBBG" );
      // Initialize QPE.
      initialize( "QPE-Example-SQL-Rules.sql", getSqlCallBacks() );
    
      // Initialize QPE SQL Rules and CallBacks.
      function initialize( sqlfile, sqlcallbacks ) {
          // Get SQL rules file.
          var xhttp = new XMLHttpRequest();
          xhttp.onreadystatechange = function() {
              if ( this.readyState == 4 && this.status == 200 ) {
                  var sqlfile_content = this.responseText;
                  // Initialize QPE.
                  obj1.initQPE( sqlfile_content, sqlcallbacks );
              }
          };
          xhttp.open( "GET", sqlfile, true );
          xhttp.send();
      }
    
      // Execute QPE.
      function runQueries() {
          // Resolve table names used for input to SQL rules.
          var tables1 = [ 'DSN81110.EMP',
                          'DSN81110.EMP',
                          'DSN81110.EMP'
                        ];
          var tables2 = [];
          // Execute SQL Rules.
          obj1.executeQPE( tables1, tables2, filter_department );
      }
    
      // Generate SQL callback definitions list.
      function getSqlCallBacks() {
          // Initialize new object.
          var sqlcb = [];
          // SQL callback definition index 0 - Perform data manipulation on returned API response object.
          sqlcb[0] = function( msobj ) {
              return auCurrencyFormat( msobj.response.sqlresp.resultset[0].row[0].TOTAL_SALARY );
          };
          // SQL callback definition index 1 - Perform data manipulation on returned API response object and update SQL rule index 2.
          sqlcb[1] = function( msobj ) {
              var rows = msobj.response.sqlresp.resultset[0].row;
              // Converted data response.
              var respdata = {
                  LASTNAME  : rows[0].LASTNAME,
                  WORKDEPT  : rows[0].WORKDEPT,
                  JOB       : rows[0].JOB,
                  SALARY    : auCurrencyFormat( rows[0].SALARY )
              };
              // Update SQL rule index 2.
              msobj.pipeSQLs[2] = msobj.pipeSQLs[2].replace( /<%ARG2%>/g, respdata.JOB );
              // Return converted data.
              return respdata;
          };
          // SQL callback definition index 2 - Perform data manipulation on returned API response object.
          sqlcb[2] = function( msobj ) {
              var rows = msobj.response.sqlresp.resultset[0].row;
              var respdata = {
                  WORKDEPT  : rows[0].WORKDEPT,
                  JOB       : rows[0].JOB,
                  SALARY    : auCurrencyFormat( rows[0].SALARY )
              };
              // Return converted data.
              return respdata;
          };
          // Return the generated object.
          return sqlcb;
      }
    
      // General function - Convert passed value to AU currency format.
      function auCurrencyFormat( fldvalue ) {
          var nmdata = Number( fldvalue );
          if ( isNaN( nmdata ) ) nmdata = 0;
          return nmdata.toLocaleString( 'en-AU', { style: 'currency', currency: 'AUD' } );
      }
    
      // QPE success function. Display data extracted from QPE response array.
      function qpeSuccess( response ) {
          // Display response data.
          document.getElementById( "container" ).innerHTML =
              '<br><strong>Department:</strong> '   + filter_department +
              '<br><strong>Salary total:</strong> ' + response[0].sqlresp.resultset[1] +
              '<br><br><strong>Highest salary in department</strong>' +
              '<br>Last Name: '  + response[1].sqlresp.resultset[1].LASTNAME  +
              '<br>Job Title: '  + response[1].sqlresp.resultset[1].JOB       +
              '<br>Salary: '     + response[1].sqlresp.resultset[1].SALARY    +
              '<br>Department: ' + response[1].sqlresp.resultset[1].WORKDEPT  +
              '<br><br><strong>Highest salary for that job title in whole organization</strong>' +
              '<br>Job Title: '  + response[2].sqlresp.resultset[1].JOB       +
              '<br>Salary: '     + response[2].sqlresp.resultset[1].SALARY    +
              '<br>Department: ' + response[2].sqlresp.resultset[1].WORKDEPT  +
              '<br>';
      }
    
      // QPE error function. Display JSON response in raw format.
      function qpeError( response ) {
          document.getElementById("container").innerHTML += '<br><br>' + JSON.stringify( response );
      }
    
    </script>
  </body>
</html>

logoff()

Terminates the active web application session. If DB2 is currently connected, an automatic rollback SQL statement (if applicable) will be issued, followed by a DB2 disconnect.
A logoff should always be issued as the final web application action, to clean up and terminate the current session gracefully.
NOTE: For "one-shot" SQL calls (single SQL statement requests), Pipes, and QPE rules; an automatic logoff is already performed and therefore not required.

Best Practices
For best practices using logoff with multiple SQL statements, see runSQL.

Examples
1. See disconnectDB2 Example showing how logoff is used.
2. See MFCAgentRequest.newObject Example showing where logoff is not required.

runSQL(runsql_input, connectedopt)

Executes the SQL statement in the runsql_input  parameter.
The runSQL method is used to execute "one-shot" SQL calls (single SQL statement requests), or multiple SQL statements within a DB2 session.

The optional connected  parameter controls the DB2 session where the SQL statement executes.
If set to true, the SQL statement will execute within the current DB2 session. See Multiple SQL Statements below.
If omitted or set to false, a "one-shot" SQL call executes on a new DB2 session. See "One-shot" SQL Calls below.

"One-shot" SQL Calls
The "one-shot" SQL call is a convenience method that bundles a single SQL statement with automatic connect, disconnect, and logoff calls; thus, removing the need for developers to have to code DB2 connect, DB2 disconnect, and logoff methods required for DB2 API calls.
To run a "one-shot" SQL call, execute the runSQL method with the connected  parameter omitted or with connected  parameter false.
For example:
1. runSQL( runsql_input ), or
2. runSQL( runsql_input, false )
The "one-shot" SQL call performs the following:
1. Executes a DB2 connection SQL statement, to create a new DB2 session.
2. Executes the SQL statement in runsql_input, on the new DB2 session.
3. Executes a DB2 disconnect or logoff, depending on the auto-logoff flag set in setLogoffSession.

"One-shot" SQL Updates
The "one-shot" SQL update call is a convenience method that bundles a single SQL update statement with automatic connect, commit, disconnect, and logoff calls.
To run a "one-shot" SQL update call, execute the runUpdateSQL method. See runUpdateSQL.

Multiple SQL Statements
To run multiple SQL statements within a DB2 session, execute the runSQL method with connected  parameter true for each SQL call. Setting the connected  parameter to true indicates that the SQL call will be performed on the connected DB2 session.
This mode of operation requires the following:
1. A currently active DB2 session. See connectDB2.
2. A disconnectDB2 to be issued after the required group of SQL statements have completed. See disconnectDB2.
3. A logoff to be issued as the final web application action. See logoff.

Best Practices
Single SQL Statements
The practices below minimize effort and user error by handling prerequisite actions for developers.
   1. For running one-off SQL queries, use runSQL with the connected  parameter omitted. See runSQL.
   2. For running one-off SQL updates with auto-commit, use runUpdateSQL. See runUpdateSQL.
Multiple SQL Statements
The practices below are advised for minimizing overhead when executing multiple SQL statements.
   1. For running multiple SQL statements use Pipes. See Pipes.
   2. For running multiple SQL statements with more advanced data handling capabilities, use the Query Process Engine (QPE). See QPE.
   3. For running multiple Pipe or QPE processors; switch auto-logoff to false using setLogoffSession, and issue a logoff as the final web application action. See setLogoffSession.
   4. For running multiple SQL statements without using Pipes or QPE, use the runSQL method with connected  parameter true.
       See connectDB2 Example showing multiple SQL statements followed by logoff.
       See disconnectDB2 Example showing grouped SQL statements with DB2 disconnect, and logoff on-demand.

Examples
1. See MFCAgentRequest.newObject Example showing a "one-shot" SQL call using runSQL method with the connected  parameter omitted.
2. See connectDB2 Example showing multiple SQL statements using runSQL method with connected  parameter true.
3. See the example code below showing the runSQL method with the runsql_input  parameter as a JSON object. This example is identical to the example shown in MFCAgentRequest.newObject, except for Lines 18 to 23 which define the callbackFunction, url, db2ssid, and sql  properties in the json_inputargs object. This object is then passed to the runSQL method in Line 25.
Parameters:
Name Type Attributes Default Description
runsql_input String | Object A String that is the SQL statement to be executed, or a JSON object with the following properties:
Properties
Name Type Attributes Description
sql String The SQL statement to be executed.
url String <optional>
The web service URL. See setURL.
NOTE: Passing the runsql_input.url  JSON parameter is equivalent to executing the setURL method. If this parameter is populated, the setURL method is not required in your code.
db2ssid String <optional>
The z/OS DB2 subsystem identifier you wish to interrogate. See setDB2SSID.
NOTE: Passing the runsql_input.db2ssid  JSON parameter is equivalent to executing the setDB2SSID method. If this parameter is populated, the setDB2SSID method is not required in your code.
callbackFunction String <optional>
The callback function to execute when the API call is complete. See callbackFunction.
NOTE: Passing the runsql_input.callbackFunction  JSON parameter is equivalent to setting the callbackFunction property. If this parameter is populated, there is no need to set the callbackFunction property in your code.
connected Boolean <optional>
false The DB2 connected parameter. True to execute the SQL statement within the current DB2 session. Omit for "one-shot" SQL calls.
Example
<!DOCTYPE html>
<!--
    Mainframe Cloud Pty Ltd MAINSPACE WEB APP EXAMPLE
-->
<html>
  <body>
    <div id="container"></div>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- MainSpace API JS library                                        -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script type="text/javascript" src="https://www.mainframecloudplatform.com/applibs/mainspace-webmf.js"></script>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- JavaScript control code section                                 -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    
      var obj1 = MFCAgentRequest.newObject();
      var json_inputargs = {
          "callbackFunction":"simpleCallBack( thisObject.response );",
          "url":"http://hostname:port/",
          "db2ssid":"DBBG",
          "sql":[ "SELECT * FROM DSN81110.EMP FETCH FIRST 20 ROWS ONLY" ]
      };
      obj1.setLogin( "TSOUSER", "TSOPASS" );
      obj1.runSQL( json_inputargs );
    
      // Simple app callback function. Display JSON response in raw format.
      function simpleCallBack( response ) {
          document.getElementById("container").innerHTML = JSON.stringify( response );
      }
    
    </script>
  </body>
</html>

runUpdateSQL(runsql_input)

Executes the SQL update statement in the runsql_input  parameter. The runUpdateSQL method executes a "one-shot" SQL update call which performs the following:
1. Executes a DB2 connection SQL statement, to create a new DB2 session.
2. Executes the SQL update statement in runsql_input, on the new DB2 session.
3. Executes a commit SQL statement to commit the update.
4. Executes a DB2 disconnect or logoff, depending on the auto-logoff flag set in setLogoffSession.

Example Explained
The example code below is identical to the example shown in MFCAgentRequest.newObject, except for Line 22 which uses the runUpdateSQL method.
Parameters:
Name Type Description
runsql_input String | Object A String that is the SQL statement to be executed, or a JSON object with the following properties:
Properties
Name Type Attributes Description
sql String The SQL statement to be executed.
url String <optional>
The web service URL. See setURL.
NOTE: Passing the runsql_input.url  JSON parameter is equivalent to executing the setURL method. If this parameter is populated, the setURL method is not required in your code.
db2ssid String <optional>
The z/OS DB2 subsystem identifier you wish to interrogate. See setDB2SSID.
NOTE: Passing the runsql_input.db2ssid  JSON parameter is equivalent to executing the setDB2SSID method. If this parameter is populated, the setDB2SSID method is not required in your code.
callbackFunction String <optional>
The callback function to execute when the API call is complete. See callbackFunction.
NOTE: Passing the runsql_input.callbackFunction  JSON parameter is equivalent to setting the callbackFunction property. If this parameter is populated, there is no need to set the callbackFunction property in your code.
Example
<!DOCTYPE html>
<!--
    Mainframe Cloud Pty Ltd MAINSPACE WEB APP EXAMPLE
-->
<html>
  <body>
    <div id="container"></div>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- MainSpace API JS library                                        -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script type="text/javascript" src="https://www.mainframecloudplatform.com/applibs/mainspace-webmf.js"></script>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- JavaScript control code section                                 -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    
      var obj1 = MFCAgentRequest.newObject();
      obj1.callbackFunction = "simpleCallBack( thisObject.response );";
      obj1.setLogin( "TSOUSER", "TSOPASS" );
      obj1.setURL( "http://hostname:port/" );
      obj1.setDB2SSID( "DBBG" );
      obj1.runUpdateSQL( "UPDATE DSN81110.EMP SET JOB = 'CTO' WHERE EMPNO = '000010'" );
    
      // Simple app callback function. Display JSON response in raw format.
      function simpleCallBack( response ) {
          document.getElementById("container").innerHTML = JSON.stringify( response );
      }
    
    </script>
  </body>
</html>

setDB2SSID(db2ssid)

Sets the z/OS DB2 subsystem identifier you wish to interrogate.
Parameters:
Name Type Description
db2ssid String The DB2 subsystem identifier.
See:

setLogin(userid, password)

Sets your z/OS TSO login credentials.
Parameters:
Name Type Description
userid String Your z/OS TSO User ID.
password String Your z/OS TSO password.
See:

setLogoffSession(logoffsession)

Sets the auto-logoff property used for "one-shot" SQL calls (single SQL statement requests), Pipes, and QPE rules.
If set to true, a logoff is performed at the end of the process.
If set to false, the web application session is left active, and a logoff must be issued as the final web application action.

Best Practices
For web applications that need to perform more than one Pipe or QPE process; set the auto-logoff property to false and issue a logoff as the final web application action.
Parameters:
Name Type Description
logoffsession Boolean The auto-logoff flag. True to terminate the active web application session, false to keep the web application session active.
Default Value:
  • true
See:

setSQLTERM(sqlterm)

Sets the SQL termination character. This character is used in the QPE feature to identify the end of an SQL statement within a file of multiple SQL statements.
Parameters:
Name Type Description
sqlterm String The SQL termination character.
Default Value:
  • ;
See:

setURL(url)

Sets the web service URL, http://hostname:port/ where hostname is the IP Address or Host Name of the z/OS LPAR where the web service is running, and port is the TCP/IP port that the web service listens for requests on.
Parameters:
Name Type Description
url String The web service URL, http://hostname:port/
See:

Property Detail

callbackFunction :String

The callbackFunction property is used to define the JavaScript function to execute when an API call is complete.

In the example code below:
Line 1 defines callbackFunction property with function name "simpleCallBack" and input object thisObject.response.
Line 3 defines function "simpleCallBack" with function parameter response.

When the MFCAgentRequest object instance obj1  API call is complete, the JavaScript function  simpleCallBack( thisObject.response )  will execute.
At runtime, the input object is resolved, and the function parameter response  is populated. That is, object variable thisObject.response  is passed to the simpleCallBack function, and the local variable response  is populated with the API call response data referenced by thisObject.response.

At runtime, the variables available include:
1. Global variables
2. thisObject - used to reference the MFCAgentRequest object instance (in this case obj1)
Type:
  • String
Example
obj1.callbackFunction = "simpleCallBack( thisObject.response );";
// Simple app callback function. Display JSON response in raw format.
function simpleCallBack( response ) {
    document.getElementById("container").innerHTML = JSON.stringify( response );
}
 

pipeSQLs :Array.<String>

The pipeSQLs property is the array of SQL statements to execute in a Pipe (the SQL pipe).
The property is available for use in QPE SQL callback definitions if required.

See initQPE for more information about the Query Process Engine (QPE) and how to work with QPE SQL callback definitions.
Type:
  • Array.<String>

qpeResponse :Array.<Object>

The qpeResponse property is an array of thisObject.response  objects returned from each API call executed in a QPE process.
The property is available for use in QPE SQL callback definitions if required.

See initQPE for more information about the Query Process Engine (QPE) and how to work with QPE SQL callback definitions.
Type:
  • Array.<Object>
See:

response :Object

The response property is the JSON object returned from an API call.
Type:
  • Object
Properties:
Name Type Description
rc Number The HTTP status code that is returned.
message Array.<String> Contains any error or informational messages pertaining to the general request. For example, messages from security verification or session management.
agentVersion String Identifies the version of the Mainframe Cloud Web Service Agent. This should be advised when making support calls to Mainframe Cloud.
sqlresp Object The DB2 SQL specific API call response.
Properties
Name Type Description
sql String The SQL statement received on the request.
sqlcode Number The sqlcode property contains the SQL return code. The code can be zero (0), negative or positive. 0 means that the execution was successful. Negative values indicate an unsuccessful execution with an error. A positive value means a successful execution with a warning. These (SQLCODEs) are detailed in IBM DB2 documentation.
message Array.<String> Contains any messages pertaining to the DB2 SQL API call.
resultset Array.<Object>
Properties
Name Type Description
column Array.<Object> The column object array contains the attributes of the returned columns. The following attributes are returned for each column. Attributes without a value are suppressed.
Properties
Name Type Description
title String The name of the column.
type String Indicates the column data type. These are detailed in IBM DB2 documentation.
nullable Boolean Value of TRUE or FALSE, indicates whether a null value is allowed or not.
unsupported Boolean Value of TRUE indicates that the DB2 type of this column is unsupported.
precision Number For numeric columns only, indicates the maximum number of digits for the column, i.e. 1234567.89 has a precision of 9.
scale Number For numeric columns only, indicates the maximum number of decimal places for the column, i.e. 1234567.89 has a scale of 2.
length Number Indicates the maximum number of characters for the column.
ccsid Number Indicates the coded character set identifier of the column.
format String See BASE64 Handling in the MfC RunTime Adaptor Reference Guide on the Mainframe Cloud User Resources page.
row Array.<Object> The row object array contains the returned table data content.
To access the data use the row object array element index for the row number (where index begins at 0), and use the column title for the row object JSON name.
The example code below shows different approaches to accessing row object data.

Approach 1 (Line 33): Using column title reference as a variable: ROWOBJECT[3][COLUMNOBJECT[1].title]
EXAMPLE OUTPUT: Row 3, Column 1, DATA = JOHN, Column Title = FIRSTNME

Approach 2 (Line 38): Using column title reference as a static value: ROWOBJECT[3].FIRSTNME
EXAMPLE OUTPUT: Row 3, Column 1, DATA = JOHN
Example
<!DOCTYPE html>
<!--
    Mainframe Cloud Pty Ltd MAINSPACE WEB APP EXAMPLE
-->
<html>
  <body>
    <div id="container"></div>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- MainSpace API JS library                                        -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script type="text/javascript" src="https://www.mainframecloudplatform.com/applibs/mainspace-webmf.js"></script>
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- JavaScript control code section                                 -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    
      var obj1 = MFCAgentRequest.newObject();
      obj1.callbackFunction = "callBack( thisObject.response );";
      obj1.setLogin( "TSOUSER", "TSOPASS" );
      obj1.setURL( "http://hostname:port/" );
      obj1.setDB2SSID( "DBBG" );
      obj1.runSQL( "SELECT * FROM DSN81110.EMP FETCH FIRST 5 ROWS ONLY" );
    
      // App callback function. Display table data extracted from JSON response.
      function callBack( response ) {
          // Assign column and row object arrays to local variables to make the code easier to read.
          var respcol = response.sqlresp.resultset[0].column;
          var resprow = response.sqlresp.resultset[0].row;
          // Set the variable to display on the web page.
          var webcontent = "Using column title reference as a variable: " +
                           "<CODE><i>ROWOBJECT</i>[3][<i>COLUMNOBJECT</i>[1].title]</CODE>" +
                           "<BR>" + // NEW LINE
                           "Row 3, Column 1, DATA = " + resprow[3][respcol[1].title] + ", Column Title = "  + respcol[1].title +
                           "<BR>" + // NEW LINE
                           "<BR>" + // NEW LINE
                           "Using column title reference as a static value: <CODE><i>ROWOBJECT</i>[3].FIRSTNME</CODE>" +
                           "<BR>" + // NEW LINE
                           "Row 3, Column 1, DATA = " + resprow[3].FIRSTNME;
          // Update the web page.
          document.getElementById("container").innerHTML = webcontent;
      }
    
    </script>
  </body>
</html>