Since: API Level v2
public final class

ServicePlugin

com.webmbt.plugin.ServicePlugin

Class Overview

provides callable service to external resources including database, web services, files, etc..

Database Access:

all database operations operate on the pre-declared datasource (dbID) in the current model MScript tag. The tag is normally defined in MBT_Start trigger but it can be anywere in MScript as long as it gets executed before any of the db access functions are called to this plugin.

You can perform simple SQL select, update, delete, and call stored procedures.

The SQL statement can be dynamically constructed using MScript

The results from db access is normally returned in a string.

Example:

  • $dbSelect('db1', 'select lastname from employee where empid=[var1]')
  • $dbInsert('db1', 'insert into employee (lastname, firstname) values (\'john\',\'smith\')')

REST Service Call:

Simple REST service call and data extraction from the response can be achieved with:

  • $RestSubmit('','get','http://example.com/xyz...','') to invoke REST svc
  • $RestGetItem('','abc.yxz') to extract json attribute 'abc.xyz'

All REST functions are prefixed with "Rest".

For complex REST service call, you also need to do the following before calling RestSubmit():

  • set parameters - RestSetParam(), RestSetQueryParam(), ...
  • set headers - RestSetHeader()
  • set cookies - RestSetCookie()
  • set authentication - RestSetBasicAuth(), RestSetFormAuth(), RestSetOAuth(), RestSetOAuth2()

You may prepare multiple connections by passing a name in "connKey_p" parameter. Pass '' to access default connection. Be sure to use a consistent connection key.

You can store response for later validation or comparison by supplying a "respKey" when calling RestSubmit().

For REST service that requires sessionId, you can call RestSetSessionId() to copy the sessionId from current response to the current connection or named connection. This is a one time operation for each connection.

Responses can be json or xml. Use the appropriate data path to extract data from the response by calling RestGetItem():

  • xml - use xpath, like $RestGetItem('','/patient/demo/gender')
  • json - use javascript (dotted notation), like $RestGetItem('patient.demo.gender')

SOAP Service Call:

SOAP calls are supported using REST functions. For example use $RestSetHeader() if you need to set a header or $RestSetBasicAuth() if you need to use authentication.

Below is a simple example:

  • create/reset connection: $RestNewConnection('con1')
  • add namespace: $SoapAddNameSpace('con1','example', 'http://ws.cdyne.com/')
  • add body element: $SoapAddElem('con1','VerifyEmail', 'example')
  • add element param: $SoapAddElemParam('con1','example','VerifyEmail', 'email', 'mutantninja@gmail.com')
  • add element param: $SoapAddElemParam('con1','example','VerifyEmail', 'LicenseKey', '123')
  • set SOAPAction: $SoapSetAction('con1','http://ws.cdyne.com/VerifyEmail')
  • set content type: $RestSetContentType('con1','text/xml; charset=utf-8')
  • submit SOAP request: $SoapSubmit('con1','http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx','result')
  • retrieve request text: $RestGetRequestText('con1')
  • retrieve response text: $RestGetResponseText('result')
  • retrieve data from response: $RestGetItem('result','/Envelope/Body/VerifyEmailResponse/VerifyEmailResult/ResponseText')
  • retrieve data from response: $RestGetItem('result','//ResponseText')
The above mscript generates the following SOAP request xml message:
  <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
  					  xmlns:example="http://ws.cdyne.com/">
     <SOAP-ENV:Header/>
     <SOAP-ENV:Body>
       <example:VerifyEmail>
         <example:email>mutantninja@gmail.com
         <example:LicenseKey>123
       </example:VerifyEmail>
     </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

All SOAP specific function names have prefix of "Soap".

Make sure to use consistent connection name for each SOAP call.

Soap responses is always xml. You may store response with an assigned response key for access later. The response data can be accessed by calling $RestGetItem(), $RestItemPresent(), etc.

If you are using https (SSL), you will need to import/install SSL certificate for the server you are trying to test. The command to import/ install SSL certificate is: keytool -import -file amirssw.cer -keystore cacerts.

Copyright © 2008 - 2017 TestOptimal LLC. All Rights Reserved.

Summary

Public Constructors
ServicePlugin()
Public Methods
int RestClearConnectionList()
clears all cached connections.
int RestClearResponseList()
clears all responses and return the number of responses cleared from the cache.
boolean RestCopyCookie(String connKey_p, String cookieName_p, String respKey_p)
copies the cookie from last response to the current connection.
void RestCopySessionId(String connKey_p, String fromRespKey_p)
copies the http SESSIONID from the current response to the current session.
long RestElapseTime(String respKey_p)
returns the elapse time the REST call took in milliseconds.
void RestEncodeURL(String connKey_p, String encode_p)
turn on / off url encoding on future requests.
String RestGetContentType(String respKey_p)
retrieves content type from the specified response.@return
String RestGetCookie(String respKey_p, String cookieName_p)
retrieves cookie from the specified response@return
String RestGetHeader(String respKey_p, String headerName_p)
retrieves a header from the specified response.@return
String RestGetItem(String respKey_p, String itemPath_p)
retrieves the item from the specified response using the specified item path.@return
String RestGetRequestText(String connKey_p)
retrieves SOAP request text (xml)
String RestGetResponseText(String respKey_p)
retrieve the response text string from the specified response on the current connection.@return
boolean RestItemPresent(String respKey_p, String itemPath_p)
test if the item exists in the specified response using the item path passed in.
String[] RestListCookies(String respKey_p)
list cookies from the specified response.
void RestNewConnection(String connKey_p)
creates a new REST connection and assigned the connKey_p.
void RestRelaxedHttps(String connKey_p, String protocol_p)
suppress https validation error with invalid certificates on the specified protocol e.g.
void RestRelaxedHttps(String connKey_p)
suppress https validation error caused by invalid certificate on SSL protocol.
void RestRemoveConnection(String connKey_p)
removes a specific connection from cache.
boolean RestRemoveResponse(String respKey_p)
removes a specified response.
boolean RestResponseContain(String respKey_p, String text_p)
test if the response text of the specified response key contains the text.
boolean RestResponseMatch(String respKey_p, String regExpr_p)
test if response text of the specified response key matches the regular expression.
void RestResponseToFile(String respKey_p, String filePath_p)
write the response text from the specified response on the current connection to the specified file.@return
void RestSetBasicAuth(String connKey_p, String userName_p, String password_p)
sets up the Basic authentication on the specified connection.
void RestSetBodyText(String connKey_p, String bodyText_p)
sets the request body to the text string passed in on the specified connection.
void RestSetContentType(String connKey_p, String contentType_p)
sets the content type on the specified connection.
void RestSetCookie(String connKey_p, String cookieName_p, String cookieValue_p)
sets the cookie to the specified connection.
void RestSetDigestAuth(String connKey_p, String userName_p, String password_p)
sets up the Digest based authentication on the specified connection.
void RestSetFormAuth(String connKey_p, String userName_p, String password_p)
sets up the Form based authentication on the specified connection.
void RestSetFormParam(String connKey_p, String paramKey_p, String paramValList_p, String delimiter_p)
sets the REST request form parameter with multiple values on the specified connection.
void RestSetFormParam(String connKey_p, String paramKey_p, String paramVal_p)
sets the REST form parameter on the specified connection
void RestSetHeader(String connKey_p, String headerKey_p, String headerVal_p)
sets header value on the specified connection.
void RestSetMultiPartFile(String connKey_p, String partKey_p, String filePath_p)
sets the multi-part file on the specified connection.
void RestSetOAuth1(String connKey_p, String consumerKey, String consumerSecret, String accessToken, String secretToken)
sets up the OAuth (version 1) on the specified connection.
void RestSetOAuth2(String connKey_p, String secToken_p, String authSig_p)
sets up the OAuth2 authentication on the specified connection using security token and the specified signature.
void RestSetOAuth2(String connKey_p, String secToken_p)
sets up the OAuth2 authentication on the specified cconnection using security token.
void RestSetParam(String connKey_p, String paramKey_p, String paramValList_p, String delimiter_p)
sets the REST request parameter on the specified connection.
void RestSetParam(String connKey_p, String paramKey_p, String paramVal_p)
sets the REST request parameter on the specified connection.
void RestSetPathParam(String connKey_p, String paramKey_p, String paramVal_p)
sets REST request path parameter on the specified connection.
void RestSetQueryParam(String connKey_p, String paramKey_p, String paramVal_p, String delimiter_p)
sets the REST request query parameter with multiple values on the specified connection.
void RestSetQueryParam(String connKey_p, String paramKey_p, String paramVal_p)
sets the REST request query parameter on the specified connection.
void RestSetSessionId(String connKey_p, String sessionId_p)
sets the http SESSIONID on the specified connection to the value passed in.
void RestStaticProxy(String svrHost_p, String svrPort_p)
sets up the static proxy server that applies to all connections.
int RestSubmit(String connKey_p, String method_p, String url_p, String respKey_p)
submits a REST request using the specified connection and stores the response in the response key.
boolean RestValidateDTD(String respKey_p, String dtd_p)
validates the xml response using the specified dtd.
void SoapAddElem(String connKey_p, String elemName_p, String ns_p)
adds an element to the soap request body with namespace specified.
void SoapAddElemParam(String connKey_p, String nameSpace_p, String elemName_p, String paramName_p, String paramVal_p)
adds a parameter to an element with name space.
void SoapAddNameSpace(String connKey_p, String nsName_p, String nsVal_p)
Adds a namespace.
void SoapReset(String connKey_p)
resets current soap request.
void SoapSetAction(String connKey_p, String soapAction_p)
sets SOAPAction to the header, prepare for SOAP call.
int SoapSubmit(String connKey_p, String url_p, String respKey_p)
submits a soap call and store the response in the specified respKey_p.
String dbCallSP(String dbID_p, String stmt_p, String colSeparator_p, String rowSeparator_p, String columnLabel_p)
calls a stored procedure with parameters fully specified in the stmt_p and return the result in a csv format with the specified separators.
String dbCallSP(String dbID_p, String stmt_p, String colSeparator_p, String rowSeparator_p)
calls a stored procedure with parameters fully specified in the stmt_p and return the result in a csv format with the specified separators.
String dbCallSp(String dbID_p, String stmt_p)
calls a stored procedure with parameters fully specified in the stmt_p.
int dbCount(String dbID_p, String tableName_p)
counts number of rows in the table specified.
int dbCountDistinct(String dbID_p, String tableName_p, String colName_p)
counts number of distinct values in the specified column for the table specified.
String dbDelete(String dbID_p, String stmt_p)
executes delete statement and returns the number of rows affected (deleted).
String dbDelete(String dbID_p, String tableName_p, String whereClause_p)
deletes rows from the table specified which the colValue_p for the specified column colName_p.
void dbDumpTable(String dbID_p, String tableName_p, String fileName_p)
dumps the entire table into a file specified in tab delimited format.
void dbDumpTable(String dbID_p, String tableName_p, String fileName_p, String colSeparator_p, String rowSeparator_p, String columnLabel_p)
dumps the entire table into a file specified in tab delimited format.
String dbExecFile(String dbID_p, String fileName_p)
Executes a batch of sql statements stored in a file and return the output of the execution.
String dbInsert(String dbID_p, String stmt_p)
executes insert statement and returns the number of rows inserted.
void dbLoadTable(String dbID_p, String tableName_p, String fileName_p)
loads the data from the specified file into the table.
void dbSQL(String dbID_p, String stmt_p)
executes sql statement without returning a value.
String dbSelect(String dbID_p, String stmt_p, String colSeparator_p, String rowSeparator_p)
executes sql select statement and returns the result in a text string formatted with the specified column and row separator string.
String dbSelect(String dbID_p, String stmt_p)
executes sql select statement and returns the result in xml string.
String dbSelect(String dbID_p, String stmt_p, String colSeparator_p, String rowSeparator_p, String columnLabel_p)
executes sql select statement and returns the result in a text string formatted with the specified column and row separator string.
String dbUpdate(String dbID_p, String stmt_p)
executes update statement and returns the number of rows affected (updated).
void fileAppend(String content_p, String fileName_p)
appends the content_p to the file specified.
void fileAppend(String content_p, String fileName_p, String newLine_p)
appends the content _p to the file specified with the option to add or not to add linefeed before the new content.
String fileDiff(String fileName1_p, String fileName2_p)
compares two files line by line and returns number of rows that are different.
String fileRead(String fileName_p)
reads the file content and return the content as they are read from the file.
void fileWrite(String content_p, String fileName_p)
saves the content_p to the file specified.
String getFileName(String filePath_p)
extract file name from the fiel path passed in.
String getFolderName(String filePath_p)
extract the folder name from the file path passed in.
String getFolderPath(String filePath_p)
extract file path before the file name.
boolean isAlphabet(String val_p)
returns true if val_p passed in contains only A-Z.@return
boolean isBinary(String val_p)
returns true if val_p passed in contains a binary string.
boolean isBoolean(String val_p)
returns true if val_p passed is a boolean value.
boolean isFloat(String val_p)
returns true if val_passed in contains a real number.@return
boolean isInRange(String val_p, String begin_p, String end_p)
returns true if val_p passed in is within the interval passed in: begin_p and end_p inclusive on both ends.
boolean isInteger(String val_p)
returns true if val_p passed in contains an integer.@return
String webSvcRest(String url_p)
calls the REST web service specified in the url and returns the result in an XML string.
String webSvcRest(String url_p, String params_p)
calls the REST web service specified in the url with additional parameters and returns the result in an XML string.
int xmlCount(String xmlString_p, String xpath_p)
returns the count of the elements found with the xpath in the xml string passed in.
String xmlExtract(String xmlString_p, String xpath_p, String outSeparator_p)
extracts elements specified by the xpath passed in from the xml string specified.
String xmlExtractElement(String xmlString_p, String xpath_p)
extracts elements in xml specified by the xpath passed in from the xml string specified.

Public Constructors

public ServicePlugin ()

Since: API Level v2

Public Methods

public int RestClearConnectionList ()

Since: API Level v2

clears all cached connections. returns # of connections cleared.

public int RestClearResponseList ()

Since: API Level v2

clears all responses and return the number of responses cleared from the cache.

Returns
  • number of responses cleared.

public boolean RestCopyCookie (String connKey_p, String cookieName_p, String respKey_p)

Since: API Level v2

copies the cookie from last response to the current connection.

Parameters
connKey_p name of connection to copy cookie to
respKey_p name of response to copy cookie from
Returns
  • boolean true if cookie is found in fromRespKey_p and successfully copied to the conection

public void RestCopySessionId (String connKey_p, String fromRespKey_p)

Since: API Level v2

copies the http SESSIONID from the current response to the current session.

Throws
Exception
Exception

public long RestElapseTime (String respKey_p)

Since: API Level v2

returns the elapse time the REST call took in milliseconds.

Parameters
respKey_p name of response to retrieve the elapse time
Returns
  • number of milliseconds
Throws
Exception
Exception

public void RestEncodeURL (String connKey_p, String encode_p)

Since: API Level v2

turn on / off url encoding on future requests.

Parameters
encode_p y/n

public String RestGetContentType (String respKey_p)

Since: API Level v2

retrieves content type from the specified response.@return

Throws
Exception
Exception

public String RestGetCookie (String respKey_p, String cookieName_p)

Since: API Level v2

retrieves cookie from the specified response@return

Throws
Exception
Exception

public String RestGetHeader (String respKey_p, String headerName_p)

Since: API Level v2

retrieves a header from the specified response.@return

Throws
Exception
Exception

public String RestGetItem (String respKey_p, String itemPath_p)

Since: API Level v2

retrieves the item from the specified response using the specified item path.@return

Parameters
itemPath_p json path (aa.bb) for json response or xpath for xml response.
Throws
Exception
Exception

public String RestGetRequestText (String connKey_p)

Since: API Level v2

retrieves SOAP request text (xml)

Parameters
connKey_p connection name

public String RestGetResponseText (String respKey_p)

Since: API Level v2

retrieve the response text string from the specified response on the current connection.@return

Throws
Exception
Exception

public boolean RestItemPresent (String respKey_p, String itemPath_p)

Since: API Level v2

test if the item exists in the specified response using the item path passed in.

Parameters
respKey_p response key
itemPath_p json path (aa.bb) for json response or xpath for xml response.
Returns
  • true or false
Throws
Exception
Exception

public String[] RestListCookies (String respKey_p)

Since: API Level v2

list cookies from the specified response.

Returns
  • list of cookie names
Throws
Exception
Exception

public void RestNewConnection (String connKey_p)

Since: API Level v2

creates a new REST connection and assigned the connKey_p. The connection holds cookie, headers, content type, etc. which can also be changed before each RestSubmit() calls.

Parameters
connKey_p unique id assigned to the connection. blank is acceptable name.

public void RestRelaxedHttps (String connKey_p, String protocol_p)

Since: API Level v2

suppress https validation error with invalid certificates on the specified protocol e.g. TLS

public void RestRelaxedHttps (String connKey_p)

Since: API Level v2

suppress https validation error caused by invalid certificate on SSL protocol.

public void RestRemoveConnection (String connKey_p)

Since: API Level v2

removes a specific connection from cache.

public boolean RestRemoveResponse (String respKey_p)

Since: API Level v2

removes a specified response.

Returns
  • true if response is found and removed. false if response was not found in the cache

public boolean RestResponseContain (String respKey_p, String text_p)

Since: API Level v2

test if the response text of the specified response key contains the text. This test is case insensitive.

Returns
  • true or false
Throws
Exception
Exception

public boolean RestResponseMatch (String respKey_p, String regExpr_p)

Since: API Level v2

test if response text of the specified response key matches the regular expression.

Returns
  • true or false
Throws
Exception
Exception

public void RestResponseToFile (String respKey_p, String filePath_p)

Since: API Level v2

write the response text from the specified response on the current connection to the specified file.@return

Throws
Exception
Exception

public void RestSetBasicAuth (String connKey_p, String userName_p, String password_p)

Since: API Level v2

sets up the Basic authentication on the specified connection.

public void RestSetBodyText (String connKey_p, String bodyText_p)

Since: API Level v2

sets the request body to the text string passed in on the specified connection.

request body is only valid for PUT, POST and DELETE. Do not call this function for GET request. Once body is set, the connection can not be used for GET.

public void RestSetContentType (String connKey_p, String contentType_p)

Since: API Level v2

sets the content type on the specified connection.

public void RestSetCookie (String connKey_p, String cookieName_p, String cookieValue_p)

Since: API Level v2

sets the cookie to the specified connection.

public void RestSetDigestAuth (String connKey_p, String userName_p, String password_p)

Since: API Level v2

sets up the Digest based authentication on the specified connection.

public void RestSetFormAuth (String connKey_p, String userName_p, String password_p)

Since: API Level v2

sets up the Form based authentication on the specified connection.

public void RestSetFormParam (String connKey_p, String paramKey_p, String paramValList_p, String delimiter_p)

Since: API Level v2

sets the REST request form parameter with multiple values on the specified connection.

public void RestSetFormParam (String connKey_p, String paramKey_p, String paramVal_p)

Since: API Level v2

sets the REST form parameter on the specified connection

public void RestSetHeader (String connKey_p, String headerKey_p, String headerVal_p)

Since: API Level v2

sets header value on the specified connection.

public void RestSetMultiPartFile (String connKey_p, String partKey_p, String filePath_p)

Since: API Level v2

sets the multi-part file on the specified connection. Multiple file is used for uploading a file.

Parameters
filePath_p absolute file path
Throws
Exception
Exception

public void RestSetOAuth1 (String connKey_p, String consumerKey, String consumerSecret, String accessToken, String secretToken)

Since: API Level v2

sets up the OAuth (version 1) on the specified connection.

public void RestSetOAuth2 (String connKey_p, String secToken_p, String authSig_p)

Since: API Level v2

sets up the OAuth2 authentication on the specified connection using security token and the specified signature.

public void RestSetOAuth2 (String connKey_p, String secToken_p)

Since: API Level v2

sets up the OAuth2 authentication on the specified cconnection using security token.

public void RestSetParam (String connKey_p, String paramKey_p, String paramValList_p, String delimiter_p)

Since: API Level v2

sets the REST request parameter on the specified connection.

public void RestSetParam (String connKey_p, String paramKey_p, String paramVal_p)

Since: API Level v2

sets the REST request parameter on the specified connection.

public void RestSetPathParam (String connKey_p, String paramKey_p, String paramVal_p)

Since: API Level v2

sets REST request path parameter on the specified connection. Path parameters are parameter token embedded in the url. For example,

http://test.com/{p1}/{p2}

where p1 and p2 are path parmameters which will be dynamically replaced with the pathParam.

public void RestSetQueryParam (String connKey_p, String paramKey_p, String paramVal_p, String delimiter_p)

Since: API Level v2

sets the REST request query parameter with multiple values on the specified connection.

Parameters
delimiter_p delimiter character used to serapate multiple values in paramVal_p

public void RestSetQueryParam (String connKey_p, String paramKey_p, String paramVal_p)

Since: API Level v2

sets the REST request query parameter on the specified connection.

public void RestSetSessionId (String connKey_p, String sessionId_p)

Since: API Level v2

sets the http SESSIONID on the specified connection to the value passed in.

public void RestStaticProxy (String svrHost_p, String svrPort_p)

Since: API Level v2

sets up the static proxy server that applies to all connections.

public int RestSubmit (String connKey_p, String method_p, String url_p, String respKey_p)

Since: API Level v2

submits a REST request using the specified connection and stores the response in the response key.

Parameters
method_p get, post, put, delete
respKey_p key to store the response
Returns
  • http response status code
Throws
Exception
Exception

public boolean RestValidateDTD (String respKey_p, String dtd_p)

Since: API Level v2

validates the xml response using the specified dtd.

Returns
  • true if validation is successful. false else, error can be found in Server/MScript Log.
Throws
Exception

public void SoapAddElem (String connKey_p, String elemName_p, String ns_p)

Since: API Level v2

adds an element to the soap request body with namespace specified. Body elements are the top level xml element to contain service parameters. You may add more than one body elements. To create a nested element, specify the element path in elemName_p separated by "/".

Example:

$SoapAddElem('','VerifyContact/ContactInfo', 'example')
The above expression will create "ContactInfo" element inside "VerifyContact" element. Use the same syntax when adding parameters to the element.

Parameters
ns_p name space. Use $SoapAddNameSpace() to define namespace first. Pass blank if no name space is required.

public void SoapAddElemParam (String connKey_p, String nameSpace_p, String elemName_p, String paramName_p, String paramVal_p)

Since: API Level v2

adds a parameter to an element with name space. Element name is the name of the element or path to the element.

Example:

$SoapAddElemParam('','VerifyContact/ContactInfo','email','tester@test.com')

The above expression will add a parameter to "ContactInfo" element nested inside "VerifyContact" body element (element at the root).

Name space must have been set with $SoapAddNameSpace('','nsCode','nsURI')

Parameters
connKey_p name of the connection
nameSpace_p name space key, pass in blank if no name space is required.
elemName_p name of the element, use $SoapAddElem() to add the body element first.
Throws
Exception
Exception

public void SoapAddNameSpace (String connKey_p, String nsName_p, String nsVal_p)

Since: API Level v2

Adds a namespace.

Parameters
nsVal_p name space uri

public void SoapReset (String connKey_p)

Since: API Level v2

resets current soap request. Call this function to discard the request that you have prepared so far to start a new request.

public void SoapSetAction (String connKey_p, String soapAction_p)

Since: API Level v2

sets SOAPAction to the header, prepare for SOAP call. SOAPAction is the method name to call.

Parameters
connKey_p connection key
soapAction_p SOAPAction name

public int SoapSubmit (String connKey_p, String url_p, String respKey_p)

Since: API Level v2

submits a soap call and store the response in the specified respKey_p. You must have set the content type appropriately as SOAP 1.0, 1.1 and 1.2 requires content type to be set to a different value or as appropriate for your SOAP service provider.

For SOAP 1.0 and 1.0, set the content type to 'text/xml; charset=utf-8' while for SOAP 1.2 and above set the content type to 'application/soap+xml; charset=UTF-8;' or other value as appropriate.

Parameters
connKey_p connection name
url_p endpoint url
respKey_p response key to store the response returned from the soap call
Returns
  • http call return code - 200 for success
Throws
Exception

public String dbCallSP (String dbID_p, String stmt_p, String colSeparator_p, String rowSeparator_p, String columnLabel_p)

Since: API Level v2

calls a stored procedure with parameters fully specified in the stmt_p and return the result in a csv format with the specified separators.

Example:

$callSP('db1', 'mySP(\'101\')','[tab]','[newline]','true')

Parameters
columnLabel_p true/false if to write the column label to the output as the first row.
Throws
Exception

public String dbCallSP (String dbID_p, String stmt_p, String colSeparator_p, String rowSeparator_p)

Since: API Level v2

calls a stored procedure with parameters fully specified in the stmt_p and return the result in a csv format with the specified separators.

Example:

$callSP('db1', 'mySP(\'101\')','[tab]','[newline]','true')

Throws
Exception

public String dbCallSp (String dbID_p, String stmt_p)

Since: API Level v2

calls a stored procedure with parameters fully specified in the stmt_p.

Example:

$callSP('db1', 'mySP(\'101\')')

Returns
  • status returned from the stored procedure or xml string describing the result set.
Throws
Exception

public int dbCount (String dbID_p, String tableName_p)

Since: API Level v2

counts number of rows in the table specified.

Example:

$dbCount('db2','table2')
@return

Throws
Exception

public int dbCountDistinct (String dbID_p, String tableName_p, String colName_p)

Since: API Level v2

counts number of distinct values in the specified column for the table specified.

Example:

$dbCountDistinct('db2','table2','col2')
@return

Throws
Exception

public String dbDelete (String dbID_p, String stmt_p)

Since: API Level v2

executes delete statement and returns the number of rows affected (deleted).

Example:

$dbDelete('db1','delete from table1 where col1<20')

Parameters
dbID_p db id
stmt_p sql delete statement
Returns
  • number of rows deleted
Throws
Exception

public String dbDelete (String dbID_p, String tableName_p, String whereClause_p)

Since: API Level v2

deletes rows from the table specified which the colValue_p for the specified column colName_p. Returns the number of rows deleted.

Example:

$dbDelete('db1','table1','col2>20')
@return

Throws
Exception

public void dbDumpTable (String dbID_p, String tableName_p, String fileName_p)

Since: API Level v2

dumps the entire table into a file specified in tab delimited format. This file can then be reloaded into table. Column labels are always included as the first row. The tab is used as column delimiter and newline at the end of each row.

Example:

$dbDumpTable('db2','table1','file1.txt')
@return

Throws
Exception

public void dbDumpTable (String dbID_p, String tableName_p, String fileName_p, String colSeparator_p, String rowSeparator_p, String columnLabel_p)

Since: API Level v2

dumps the entire table into a file specified in tab delimited format. This file can then be reloaded into table.

Example:

$dbDumpTable('db2','table1','file1.txt','[tab]','[newline]','true')
@return

Parameters
columnLabel_p true/false if to write the column label to the output as the first row.
Throws
Exception

public String dbExecFile (String dbID_p, String fileName_p)

Since: API Level v2

Executes a batch of sql statements stored in a file and return the output of the execution.

Example:

$dbExecFile('myDS', 'batch.sql')

Parameters
dbID_p - data source id
fileName_p - name of the file that contains the sql statements. If absolute file path is used, it will read the file using the absolute path. However it is recommended to place the file in "data" folder or the model folder for better portability of the models.

The file may contain comments (lines starting with #, -- or // are considered comments). You may also add variables and then use the normal mscript variable notation [var] in the sql statement. The variables must be defined one var per line with this format: @var1=value string.

Returns
  • String that contains the output from the sql execution as well as any errors. Any error or execution from the sql statements are recorded in the return but will not trigger failure.
Throws
Exception - invalid variable definition.

public String dbInsert (String dbID_p, String stmt_p)

Since: API Level v2

executes insert statement and returns the number of rows inserted.

Example:

$dbInsert('db2','insert into table2(col1,col2) values(123, \'xxx\')')
@return

Throws
Exception

public void dbLoadTable (String dbID_p, String tableName_p, String fileName_p)

Since: API Level v2

loads the data from the specified file into the table. It assumes the file uses tab as the column separator and has line feed at the end of each line. Currently supported dbms: oracle, mysql, db2. For other dbms, you can use dbSQL() function.

Example:

$dbLoadTable('myDB','table2','f1.txt')

Returns
  • number of rows inserted
Throws
Exception

public void dbSQL (String dbID_p, String stmt_p)

Since: API Level v2

executes sql statement without returning a value. Use this to execute grant permission, drop table, etc.

Example:

$dbSQL('db2','grant all on table abc to group yyy')
@return

Throws
Exception

public String dbSelect (String dbID_p, String stmt_p, String colSeparator_p, String rowSeparator_p)

Since: API Level v2

executes sql select statement and returns the result in a text string formatted with the specified column and row separator string. This function does not return the column labels.

Example:

$dbSelect('db1','select * from table1','|','[newline]')

@return

Throws
Exception

public String dbSelect (String dbID_p, String stmt_p)

Since: API Level v2

executes sql select statement and returns the result in xml string.

Example:

$dbSelect('db1','select col3 from table1 where price>200')
$dbSelect('db1','select col3 from table1 where name=\'John\'')

@return

Throws
Exception

public String dbSelect (String dbID_p, String stmt_p, String colSeparator_p, String rowSeparator_p, String columnLabel_p)

Since: API Level v2

executes sql select statement and returns the result in a text string formatted with the specified column and row separator string.

Example:

$dbSelect('db1','select * from table1','|','[newline]','true')

@return

Parameters
columnLabel_p true or false to write column labels as the first row.
Throws
Exception

public String dbUpdate (String dbID_p, String stmt_p)

Since: API Level v2

executes update statement and returns the number of rows affected (updated).

Example:

$dbUpdate('db1','update table1 set col1=2 where col4=10')

Returns
  • number of rows updated/affected.
Throws
Exception

public void fileAppend (String content_p, String fileName_p)

Since: API Level v2

appends the content_p to the file specified. If file does not exist, it creates the file and append the new content to the end of the file.

It does always adds newline if necessary to ensure the new content is written on a separate line. If the file is empty, it will not add the new line.

Example:

$fileAppend('$getText('f2')','f2.txt')
@return

Parameters
content_p content to be appended to the file. You may use replacement token to insert special characters like [tab], [newline], etc.
fileName_p name of the file in the model folder or absolute file path.
Throws
Exception

public void fileAppend (String content_p, String fileName_p, String newLine_p)

Since: API Level v2

appends the content _p to the file specified with the option to add or not to add linefeed before the new content. If true is passed in for newLine_p, it will append a new line before the new content unless the file is empty.

Example:

$fileAppend('c1[tab]c2','a.txt', 'true')

Parameters
content_p content to be appended to the file. You may use replacement token to insert special characters like [tab], [newline], etc.
fileName_p name of the file in the model folder or absolute file path.
Throws
Exception

public String fileDiff (String fileName1_p, String fileName2_p)

Since: API Level v2

compares two files line by line and returns number of rows that are different.

Example:

$fileDiff('f1.txt','f2.txt')
@return

Throws
Exception

public String fileRead (String fileName_p)

Since: API Level v2

reads the file content and return the content as they are read from the file. It will look for the file as passed in first (i.e. treat it as an absolute path), if file is not found as specified, it tries to find the file in the model folder.

Example:

$fileRead('c:/test.txt') or $fileRead('test.txt')

Returns
  • content of the file or NOT FOUND if file does not exist.
Throws
Exception

public void fileWrite (String content_p, String fileName_p)

Since: API Level v2

saves the content_p to the file specified. If file already exists, it will be deleted and replaced with the new content. File is saved to the model folder.

Example:

$fileWrite('$getText('f2')','file.txt')

Parameters
fileName_p name of the file.
Throws
Exception

public String getFileName (String filePath_p)

Since: API Level v2

extract file name from the fiel path passed in.

Example:

$getFileName('[outFilePath]') 
If the user variable 'outFilePath' has the value of 'c:/temp/dir1/test.txt', the above example will return 'test.txt'.@return

Throws
Exception

public String getFolderName (String filePath_p)

Since: API Level v2

extract the folder name from the file path passed in.

Example:

$getFolderName('[outFilePath]')
If the user variable 'outFilePath' has the value of 'c:/temp/dir1/test.txt', the above example will return 'dir1'.@return

Throws
Exception

public String getFolderPath (String filePath_p)

Since: API Level v2

extract file path before the file name.

Example:

$getFileName('[outFilePath]')
If the user variable 'outFilePath' has the value of 'c:/temp/dir1/test.txt', the above example will return 'c:/temp/dir1'.@return

Throws
Exception

public boolean isAlphabet (String val_p)

Since: API Level v2

returns true if val_p passed in contains only A-Z.@return

Throws
Exception

public boolean isBinary (String val_p)

Since: API Level v2

returns true if val_p passed in contains a binary string. That is it has all 0 and 1.@return

Throws
Exception

public boolean isBoolean (String val_p)

Since: API Level v2

returns true if val_p passed is a boolean value. A value is considered boolean if it is one of the following:

  1. true
  2. false
  3. T
  4. F

Returns
  • true or false
Throws
Exception

public boolean isFloat (String val_p)

Since: API Level v2

returns true if val_passed in contains a real number.@return

Throws
Exception

public boolean isInRange (String val_p, String begin_p, String end_p)

Since: API Level v2

returns true if val_p passed in is within the interval passed in: begin_p and end_p inclusive on both ends.

The value being checked can be integer, float, alphabet etc. The range must have matching data type. Ascii string is compared lexicographically.@return

Parameters
begin_p left end of the interval, inclusive
end_p right end of the interval, inclusive
Throws
Exception

public boolean isInteger (String val_p)

Since: API Level v2

returns true if val_p passed in contains an integer.@return

Throws
Exception

public String webSvcRest (String url_p)

Since: API Level v2

calls the REST web service specified in the url and returns the result in an XML string.

Example:

$webSvcRest('http://my.com/app?p1=abc&p2=123')
@return

public String webSvcRest (String url_p, String params_p)

Since: API Level v2

calls the REST web service specified in the url with additional parameters and returns the result in an XML string.

Example:

$webSvcRest('http://my.com/app','p1=abc&p2=123')
@return

public int xmlCount (String xmlString_p, String xpath_p)

Since: API Level v2

returns the count of the elements found with the xpath in the xml string passed in.

Example:

$xmlCount('$getData('ds','f1')','/book/title')
@return

Throws
Exception

public String xmlExtract (String xmlString_p, String xpath_p, String outSeparator_p)

Since: API Level v2

extracts elements specified by the xpath passed in from the xml string specified. The output is returned with all elements strung together with the separator specified.

Example:

$xmlExtract('$getText('id=resp')','/book/title')
@return

Throws
Exception

public String xmlExtractElement (String xmlString_p, String xpath_p)

Since: API Level v2

extracts elements in xml specified by the xpath passed in from the xml string specified. The output is returned with all elements strung together with the separator specified.

Example:

$xmlExtractElement('$getText('id=resp')','/book[author=\'John Smith\']')
@return

Throws
Exception