Suite.js Documentation

Introduction

• What is Suite.js?
• Technologies Used
• ECMAScript Support
• License
• Roadmap

Getting Started

• Downloading & Installing
• Running
• Examples

Technical Support

• LinkedIn Support Group

Functions

Cryptography
• hashSHA256
• hmacSHA256
• hashSHA512
• hmacSHA512
• hashMD5
• hmacMD5

File System
• fileExists
• fileRead
• fileWrite
• folderExists
• unzip
• zip

Input / Output
• beep
• prompt
• write
• writeln

Networking
• curlExecute
• nsapiExecute

Operating System
• shellExecute

Text Encoding
• base64Decode
• base64Encode

Utilities
• abort / halt / quit
• info
• infoRefresh
• sleep
• stringIndent
• uuidGenerate

Advanced Topics

• Command Line Arguments
• Error Handling
• File Paths
• Includes
• Modules
• Source File Encryption
• TextBlocks

Error Handling

Suite.js includes features that are designed to help you manage errors that occur when your JavaScript code is initially being parsed and when it is running.

Unhandled JavaScript Errors

When a standard JavaScript exception occurs, Suite.js provides as much information as it can about the error, including an error number (when available), a description of the error, as well as the full JavaScript file that was being interpreted (including any "included" files). Note that if an error occurs when an encrypted source file is executed, no JavaScript source is exposed.

For example, consider this very simple JavaScript file.

<span class="kwd">var</span><span class="pln"> x </span><span class="pun">=</span><span class="pln"> foo</span><span class="pun">(</span><span class="pln"> </span><span class="lit">999</span><span class="pln"> </span><span class="pun">);</span>

When the file is run, the following output is generated.

<span class="typ">Error</span><span class="pun">:</span><span class="pln">
</span><span class="pun">•</span><span class="pln"> </span><span class="typ">Number</span><span class="pun">:</span><span class="pln"> </span><span class="lit">0</span><span class="pln">
</span><span class="pun">•</span><span class="pln"> </span><span class="typ">Message</span><span class="pun">:</span><span class="pln"> uncaught</span><span class="pun">:</span><span class="pln"> </span><span class="str">'identifier "foo" undefined'</span><span class="pln">
</span><span class="pun">•</span><span class="pln"> </span><span class="typ">JavaScript</span><span class="pun">:</span><span class="pln"> 
     </span><span class="lit">1</span><span class="pun">:</span><span class="pln"> </span><span class="kwd">var</span><span class="pln"> x </span><span class="pun">=</span><span class="pln"> foo</span><span class="pun">(</span><span class="pln"> </span><span class="lit">999</span><span class="pln"> </span><span class="pun">);</span>

This indicates that the JavaScript engine encountered an error. In this case, the error occurred because a reference to "foo" could not be resolved.

try...catch Support

Suite.js supports standard JavaScript try...catch statements. This gives you the ability to handle exceptions that occur within a specific block of code.

Continuing with the example above, here's the code wrapped in a try...catch statement.

<span class="kwd">try</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
	</span><span class="kwd">var</span><span class="pln"> x </span><span class="pun">=</span><span class="pln"> foo</span><span class="pun">(</span><span class="pln"> </span><span class="lit">999</span><span class="pln"> </span><span class="pun">);</span><span class="pln">
</span><span class="pun">}</span><span class="pln"> </span><span class="kwd">catch</span><span class="pln"> </span><span class="pun">(</span><span class="pln">e</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
	writeln</span><span class="pun">(</span><span class="pln"> </span><span class="str">"Error: "</span><span class="pln"> </span><span class="pun">+</span><span class="pln"> e</span><span class="pun">.</span><span class="pln">message </span><span class="pun">);</span><span class="pln">
</span><span class="pun">}</span>

When the modified file is run, the following output is generated.

<span class="typ">Error</span><span class="pun">:</span><span class="pln"> identifier </span><span class="str">'foo'</span><span class="pln"> </span><span class="kwd">undefined</span>

Unhandled Suite.js Exceptions

In some cases, Suite.js will encounter errors that cause the entire runtime to crash. These "unhandled exceptions" will cause an "UnhandledException" event to occur, and the runtime will terminate.

For example, consider this JavaScript file, which intentionally causes a "divide by zero" error.

<span class="kwd">var</span><span class="pln"> a </span><span class="pun">=</span><span class="pln"> </span><span class="lit">100</span><span class="pun">;</span><span class="pln">
</span><span class="kwd">var</span><span class="pln"> b </span><span class="pun">=</span><span class="pln"> a </span><span class="pun">/</span><span class="pln"> </span><span class="lit">0</span><span class="pun">;</span><span class="pln">
writeln</span><span class="pun">(</span><span class="pln"> b </span><span class="pun">);</span>

When the file is run, the following output is generated.

<span class="typ">UnhandledException</span><span class="pun">:</span><span class="pln">
</span><span class="pun">•</span><span class="pln"> </span><span class="typ">Error</span><span class="pln"> </span><span class="typ">Number</span><span class="pun">:</span><span class="pln"> </span><span class="lit">0</span><span class="pln">
</span><span class="pun">•</span><span class="pln"> </span><span class="typ">Message</span><span class="pun">:</span><span class="pln"> root</span><span class="pun">{</span><span class="str">"error"</span><span class="pun">}{</span><span class="str">"params"</span><span class="pun">}[</span><span class="lit">0</span><span class="pun">]:</span><span class="pln"> </span><span class="typ">Floating</span><span class="pln"> point infinity </span><span class="kwd">is</span><span class="pln"> </span><span class="kwd">not</span><span class="pln"> a valid JSON value

</span><span class="typ">Exception</span><span class="pln"> </span><span class="typ">Message</span><span class="pun">:</span><span class="pln"> root</span><span class="pun">{</span><span class="str">"error"</span><span class="pun">}{</span><span class="str">"params"</span><span class="pun">}[</span><span class="lit">0</span><span class="pun">]:</span><span class="pln"> </span><span class="typ">Floating</span><span class="pln"> point infinity </span><span class="kwd">is</span><span class="pln"> </span><span class="kwd">not</span><span class="pln"> a valid JSON value
</span><span class="typ">Exception</span><span class="pln"> </span><span class="typ">Error</span><span class="pln"> </span><span class="typ">Number</span><span class="pun">:</span><span class="pln"> </span><span class="lit">0</span><span class="pln">
</span><span class="typ">An</span><span class="pln"> exception of </span><span class="kwd">class</span><span class="pln"> </span><span class="typ">JSONException</span><span class="pln"> was </span><span class="kwd">not</span><span class="pln"> handled</span><span class="pun">.</span><span class="pln">  </span><span class="typ">The</span><span class="pln"> application must shut down</span><span class="pun">.</span>

When the error occurs, Suite.js cannot recover from it. The app shuts down.

curl Errors

The curlExecute function has been designed with additional error handling capabilities. For example, if cURL itself encounters an error, such as an invalid host name being referenced, it will return both an error code and error message in its response. If the host itself returns an error (such as a "404 Not Found" error), then the error will be available via the cURL response object (as the "responseCode" attribute).

For additional information, see the curlExecute documentation.