~~CLOSETOC~~
<html><font color=#990000 size="+2"><b>SLANG Shell Tutorial</b></font></html>

The application fabric provides a command line interface that allows users to interact with fabric components and the entity repository using an extensible, session based language environment called SLANG.  The acronym stands for Semantic Language and Annotations Generator and provides a way for users to call many of the application fabric’s API functions that allow for configuration, query, command and control of hosted application services and federated data spaces.  The SLANG environment is extensible. When interacting with service components developers may define their own language verbs and command sequences that call logic functions and include such commands in the common language processor, thereby creating a domain-specific language tailored to their system implementation.

The language processor is context sensitive, meaning that the command set changes depending on which fabric components are being used.  For example if the SLANG session’s context is set to the fabric runtime of a given node the language processor will recognize relevant runtime commands for querying and configuring component state.  When session context switches to a specific data space the processor will recognize commands for dealing with data collection and processing SQL queries.   

====SLANG Command-Line Arguments and Getting Help====

Similar to a standard command shell the SLANG environment provides extensive on-line help, tag-based searches and auto-completion capabilities.  To access context specific lists of commands users should ''USE'' the appropriate context and key in ''help'' or ''?''.  For help on command-line arguments of any StreamScape component specify <wrap hi>-h</wrap> or <wrap hi>-help</wrap>.  For example to see what arguments are available for SLANG do the following:

<code>
C:\StreamScape\bin>slang -h

    TruFabric Semantic Language Tool

    SLANG Tool: Release 3.4 b50 (Fabric Runtime 3.4 b48)
    Copyright (c) 2007-2014 StreamScape Technologies

    Usage: slang [ -version ]

                 [ -dir <working_directory> ]
                 [ -java-cfg <jvm_options_filename> ]
                 [ -java-args "<jvm_options>" ]
                 [ -java-home <java_home_directory> ]
                 [ -url <url> ]
                 [ -u <user_name> ]
                 [ -p <user_password> ]
                 [ -timeout <timeout> ]
                 [ -diag | -diagnostic ]
                 [ -noprompt ]
                 [ -debug ]
                 [ -java-console ]
                 [ -nocolor ]
                 [ -cygwin ]
                 [ -shellpath <path>]
                 [ -tty ]
                 [ -h | -help ]

    -version       Displays version information.

    -dir           Working directory of the node.
                   Default is the current directory. Values containing spaces must be quoted.

    -java-cfg      Path to the file containing JVM options.
                   Default is slang.conf. Values containing spaces must be quoted.

    -java-args     List of JVM options (e.g. "-Xmx256m"). Options must be quoted.

    -java-home     Path to Java Home directory (e.g. "C:/Program Files/Java/jre1.7.0_11").
                   If this parameter is not specified, a standard Java installation will be searched.
                   On Windows platform the registry will be used. The runtime expects a minimum of
                   version JDK/JRE 1.7. Values containing spaces must be quoted.

    -log           Allows the tool to write trace messages to a specified log file.
                   Default is slang.log. Values containing spaces must be quoted.

    -url           URL used during a connecting to the Fabric at start-up.

    -u             User name used during a connecting to the Fabric at start-up.
                   This parameter will be used only if -url parameter is specified.

    -p             User password used during a connecting to the Fabric at start-up.
                   This parameter will be used only if -url parameter is specified.

    -timeout       Time (in seconds) of waiting for connection establishment.
                   Default is 10 seconds. This parameter will be used only if -url parameter is specified.

    -diag          Creates a diagnostic session to the Fabric at start-up.
    -diagnostic    This parameter will be used only if -url parameter is specified.

    -noprompt      Disables a printing of the prompts.

    -debug         Prints launcher debug information to a debug.log file.

    -java-console  Uses a standard Java console.

    -nocolor       Uses a monochrome console.

    -cygwin        Works in Cygwin mode (uses a specific version of a console).

    -shellpath     Path to sh.exe for Cygwin mode. Values containing spaces must be quoted.

    -tty           Parameter tty for Cygwin mode.

    -h             Displays help information.
    -help
</code> 

The SLANG environment is intended to be interactive, allowing users to discover components, objects, clients and other information available within the application fabric.  As such the set of functions and commands is quite large

===Search Tags===

===Auto-Completion===

===Context-Sensitive Commands and Help===


====Starting the SLANG Environment====

You can start a standard language processor session in several ways.  Simply executing <color gray>**slang**</color> or running the shell script <color gray>**slang.sh**</color> will start the environment and allow you to ''connect'' to the application fabric or perform other operations.  The SLANG tool provides more than just connectivity to application fabric nodes.  It also includes commands for generating Fabric Resource Modules, working with Deployment Descriptors and specifying available Access Points.

Alternatively users may specify the connection URL inline, similar to traditional database tools.  There are pros and cons to doing things either way.  IN general it is expected that inline URL are more applicable to unattended scripting tasks.

===Specifying URLs Inline===

Inline URL can be specified in the following way:

<code>
  slang -url tlp://vmtxas:500 -u Admin -p admin
  ..
  TNode1>
</code>

Note that it is possible to in-stream password information from a file that is not readable to users, or call scripts that are not visible to users, thereby hiding the actual security credentials and allowing only specific OS users to execute the given scripts.

===SLANG Configuration File===

The Java environment may be configured via a file specified at start-up:

<code>
  slang -java-cfg ./slang.conf
</code>

In addition to Java properties the configuration file allows runtime-specific properties to be specified.  These properties may override certain runtime settings or provide additional client information.  See [[Advanced Topics]] for a list of specific properties that may be used.  A sample <color gray>**slang.conf**</color> file may be found in the ''$STROOT/bin'' directory.

===Auto-Discovery of Access Points===

Client applications typically use a direct URL or URL list to connect to service engine Access Points.  However SLANG allows users to load and make use of Discovery Modules for finding available Access Points.  This allows Application Fabric nodes and SLANG to share available discovery mechanisms and Directory Services regardless of whether Discovery Modules are the default ones provided with the platform or those written by users.  See [[basic_concepts#Discovery Module]] for additional information on how to create your own directory service plug-ins.

Discovery Module names and their parameters can be specified via the SLANG configuration file. The Discovery Module that is enabled by default is file based.  It allows nodes and SLANG clients to share a Directory Table and also (alternatively) make use of UDP to find available Access Points and Links.

==UDP Broadcast==

SLANG configurtion file may specify UDP usage in the following way:

<WRAP box gray>
<color green>-Dstreamscape.discovery.multicast.enabled=true</color>

<color green>-Dstreamscape.discovery.multicast.address=230.0.0.0:8888</color>

<color green>-Dstreamscape.discovery.multicast.waiting.time=1</color>
</WRAP>

UDP discovery is useful when available nodes are on the same network sub-net and SLANG users do not want to maintain lists of access points or manage their own links.
With UDP enabled the client may auto-discover nodes that are configured to respond using the same multicast address:

<code>
  slang> discover

  Node    Link
  ----    ----
  TNode-1 tlp://localhost:7777
  TNode-2 tlp://127.0.0.1:5000
</code>


==Local Directory Table==

For file-based configuration the location of the Directory Table object must be specified:

<WRAP box gray>
<color green>-Dstreamscape.discovery.fabric.directory=C:\StreamScape\Test\DirectoryTable.xdo</color>
</WRAP>

By default SLANG looks for the directory table artifact in it's start-up directory.  Using the property above instructs SLANG to look for it in an alternate location.  The shell automatically loads a local version of ''DirectoryTable.xdo'' if it exists at the specified location.  It inspects all the LINK definitions and constructs a list of available [[basic_concepts#Access Points|access points]].

The following command will display the available links and general session information:

<code>
  slang> show session

  Property            Value
  ------------------  --------------------------------------------
  Access Points       [tlp://localhost:7777, tlp://localhost:5000]
  Reconnect Attempts  -1
  Reconnect Interval  30
</code>
===Verifying Access Points===

You can check if a particular Access Point URL is available for connection by using the PING command:

<code>
  slang> ping tlp://192.168.215.107:7055

  AVAILABLE
</code>

This command is safe and does not require security credentials.

===Fault Tolerance===

SLANG session connections are fault-tolerant and reliable.  When users connect to a given Access Point the SLANG environment starts a connection observer mechanism that monitors the state of the connection.  In the event if a network problem the SLANG session suspends operations and attempts to automatically re-establish the connection, providing reliable connectivity. To set reconnect and retry behavior the following commands may be used:

<code dsql>
  set reconnect attempts
  set reconnect interval
</code>

SLANG connections may also use a list of URLs to connect.  In this case standard fault-tolerant reconnect mechanisms of the client will first attempt re-connection to the initial URL and the roll-over to alternate Access Points, trying them all before the list is exhausted.  The following commands allow users to manage SLANG access points dynamically:

<code dsql>
  add access point
  remove access point
  show session
</code>

When a Directory Table exists or UDP has been enabled for discovery these commands will list the available Access Points that have been loaded by the Discovery Module.

====SL Session Basics====

SLANG Sessions are fully interactive and in the context of Dataspaces they are also Transactional.

===Declaring Variables===

<code dsql>
  string var1 = ''
  ..
  set var1 = 'hello apps!'
  ..
  select @var1
  
  var1
  ----
  hello apps!
</code>
 
So whats happening here? Where does the variable exist and where is the script actually executed?  The SLANG session is context-oriented, meaning that the session itself is an abstraction managed by the node that the user initially connected to.  If a resource is used the session's local variables are managed by the remote resource.  Local resources of the SLANG client will do stuff like cache result sets, prototypes and data objects, manage connection state and keep track of context.  However all the so-called heavy-lifting is done at the remote node in the memory space of the JVM.  

This means that sessions are fault-tolerant and their session-local storage is not discarded when a connection to the fabric is lost.  This is true for all protocols including HTTP, allowing web clients to maintain Session State. Applications can declare complex variables such as objects, ''TABLE'' or ''MAP'' collections that are visible only to the current session, detach from an active session and then re-connect.  The session's information will be preserved event if the client is disconnected.  Decoupled sessions are covered in greater detail in [[Advanced Topics]]. 
===Output Piping===

SLANG allows users to pipe the output of a query or 

===Disabling Interactive Prompts===

Use the -noprompt option to disable prompt printing whr 


====Running SLANG scripts====

<code dsql>
  slang < myscript.slang > slang.out
</code>


<WRAP round tip >
When starting the language environment it may be useful to display version and environment information as part of the output prior to the prompt.  A simple trick is to wrap version and SLANG executable in a parent script or batch.  For example on windows users can create a launch script such as:

@echo off

slang -version

slang
</WRAP>

====Language Request API====

Users may access the language processor thru the SLANG API.  The ''com.streamscape.slex.slang.SLSession'' object is accessible from the fabric connection and allows users to invoke language requests.  To send a language request users may pass plain text or use the ''com.streamscape.slex.slang.SLStatement'' object and send requests to the appropriate components.  The resulting   ''com.streamscape.slex.slang.SLResponse'' object is derived from a RowSet and presents all results in tabular format.

<code dsql>
  // Create a fabric connection
  FabricConnection connection = connectionFactory.createConnection();
  connection.open();
  // Create a SLANG session
  SLSession session = connection.createSLSession();
  // Make a SLANG text request with a 1000 ms timout
  SLResponse response = session.slangRequest("list nodes", 1000);
</code>

====Runtime Context Commands====

The runtime context commands are accessible by switching session context to that of the specific runtime via the USE command.  For example, if the runtime of a node is named MyNode it can be accessed via a SLANG command USE RUNTIME.MyNode regardless of whether the session is connected directly to the node.  Runtime context switches occur transparently by opening proxy accessors to neighboring nodes for administrative purposes.

====Service Context Commands====

Service context commands are those supported by all service components.  In general the service context provides operations for working with event handlers, event triggers and service state.  Issuing a help or ? command will display all available commands within the context.  If a service-specific DSL Provider has been implemented by the service developer then additional commands will also be added to the list and shown as available service operations.

====Table Space Context Commands====

Table space context commands are accessible by switching session context to that of the specific table space via the USE command.  For example, if the table space is named MySpace it can be accessed by the SLANG command USE TSPACE.MySpace. Data space context switches occur by opening accessor sessions to a specific space.  Data space accessor sessions are transactional and fully support COMMIT and ROLLBACK semantics.  

Data spaces are akin to database schemas and in fact they appear as Schema Objects in the JDBC interface.  Table spaces support a broad range of commands typically found in SQL compliant databases and support Table, View, Map, Array, Array Map and Event Table collections.

Certain data space commands are inherited from the runtime context and perform the same functions.  They are supported by the language parser for convenience, allowing users to invoke the requests without switching context.

====Queue Space Context Commands====

====SLANG Session Commands====

The SLANG environment uses a special type of Accessor (a Language Processing Accessor) to invoke language commands in a session-based manner.  The language session supports a number of settings that controls the overall behavior.