Getting Started

At this point you should have installed the Smart Card Scripting Environment for Eclipse.

We recommend to also download and install the OpenSCDP Script Collection. It contains valuable sample scripts.

Start by opening the SSE4E Development perspective. Select "Window" / "Open Perspective" / "Other" / "SSE4E Development". You will now see the SSE4E Project Browser on the left and the Console view on the bottom. In the Console view press the "Open Console" drop-down button and select "SSE4E Smart Card Shell" from the list.

After you started the Smart Card Shell you can enter commands at the shell prompt.

To end the shell, you can either enter "quit". This will terminate the shell, but it will not close the Console view. You can later restart the shell using the "Open Console" button in the Console view.

Quick Start

Insert a smart card into your reader and enter:

> r

If everythings is installed correctly, then you should see the Answer to Reset (ATR) for your card.

Understanding the Shell Concept

The Smart Card Shell uses a JavaScript interpreter and compiler to execute scripts. JavaScript is a typeless, object-oriented programming language commonly used in web browsers for active HTML pages. The language syntax is very similar to Java and C.

The shell is directly connected to the JavaScript interpreter, so any input in the text area must be valid JavaScript code. Whenever you enter a command into the shell, this command is evaluated by the interpreter, executed and the resulting value displayed to the user. Give it a try and enter:

> 1000 + 2000

After pressing ENTER the shell will display

3000
>

and is ready to accept the next command.

Invoking functions is as simple. To print something on the command line or from within a script you can invoke the print() function. The print() function will print all passed arguments separated by a whitespace and a final line break.

> print("Value", 100, 200);

will result in

Value 100 200
>

When entering a function name without parentheses, the shell will invoke this function with the result of the previous command as argument. This can be quite handy, if you define functions which shall continue processing on the output of the previous function. However this functionality is only available when entering commands in the shell. When writing scripts, you need to store the result in a variable instead.

The help() function can be invoked with or without parentheses and it will display a short help text. The function itself is defined in the CONFIG.JS script, which is run as the initial configuration script when you start the shell.

Don't be surprised, if only a few commands are build-in commands. Most of the time you will write and use scripts to do something with the Smart Card Shell.

Variables can be assigned a value without prior declaration. The script interpreter will take care of the best storage type and any conversion necessary.

You can define global and local variables. Global variables are created when you first assign a value to it:

> globalVariable = "Test";

creates a global variable named globalVariable and with a string value "Test". Local variable are declared with a var prefix:

> var localVariable = "Hello";

Local variables are only valid within the function in which they are defined.

Running Scripts

A script can be compiled and executed using the load() method build into the scripting enviroment.

The load() method accepts a string as the script name:

> load("myproject/test.js");

Remember, that all commands entered in the shell must be valid JavaScript code. Specifying a full path requires you to escape the backslash character with an additional backslash, because this notation is required for string literals:

> load("c:\\myscripts\\explore.js");

For your own convenience and better portability to other operating systems, we recommend to use the forward slash instead. This does not need to be escaped:

> load("c:/myscripts/explore.js");

You can also run scripts from the "SSE4E" menu item or the context menu associated with a .js file in the project browser.

The shell is using a simple scheme to map file names used in scripts to files in the operating environment. As a rule of thumb, all file names are resolved relative to the location of the script which is currently running. If a file cannot be found relative to the location of the script, then in turn the working directory and the installation directory is searched. See Locating Files for details.

The scripts supplied with the Smart Card Shell are located in directories underneath the plug-in directory. The tools directory contains a number of scripts that provide support for common tasks.

Interrupting Scripts

If a script locks up in an endless loop, then you can try to interrupt the script by entering "." followed by return on the shell.

Selecting a Card Reader

Unless you explicitly selected a card reader from the "Windows" / "Preferences" / "SSE4E Preferences" configuration page, the shell will use the first card reader in the system as default reader. Once you select a card reader, the JavaScript variable _scsh3.reader will be set to the name of the reader. You can reference this configuration variable in your own scripts.

Defining and Using Objects

JavaScript supports object-oriented programming, but uses prototype objects rather than classes. A prototype object contains the common properties of all instances of the same object. Common properties can be, for example, constants and methods.

Objects are created using the new operator. Following the new operator you can define a function that acts as a constructor. You can pass arguments to this function to initialize the newly created object.

Constructor functions in JavaScript are similar to classes in Java. By defining a constructor function and assigning other functions to the prototype of a constructor you can build your own objects and methods. The following code shows the concept:

//
// Define constructor and class Point
//
function Point(x, y) {
        this.x = x;
        this.y = y;
}

//
// Define method add() and assign to the prototype object, making it available
// for all instances created with the Point constructor function
//
Point.prototype.add = function(x, y) {
        this.x += x;
        this.y += y;
}

//
// Define a toString() method
//
Point.prototype.toString = function() {
        return("y = " + this.x + ", y = " + this.y);
}

var p = new Point(10, 20);

p.add(20, 10);
print(p);

The Smart Card Shell supports a large number of predefined classes (aka constructor functions) and methods to work with smart cards, cryptographic material, data structures and PKI services. See the main page for a complete reference of Global Platform and shell scripting classes.