Namespace dim

Namespace for extension functions dealing with the DIM network.
Defined in: dim.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	dim

Field Summary
Field Attributes	Field Name and Description
<static>	dim.onchange Callback in case of state changes.
<static> <constant>	dim.version DIM version number

Method Summary
Method Attributes	Method Name and Description
<static>	dim.alarm(argument) Posts a message to the dim network with alarm severity.
<static>	dim.getDescription(service) Returns a description for one service The returned array has objects with the properties: name, description and unit.
<static>	dim.getServices(service, isCommand) Returns a list of all known services The returned array has objects with the properties: name, server, service, command and (optional) format.
<static>	dim.getStates(server) Returns a list of all known state of a given server.
<static>	dim.log(argument) Post a message into the dim log stream.
<static>	dim.send(commandId, argument) Send a dim command to a dim client.
<static>	dim.state(name) Returns the state of the given server.
<static>	dim.wait(name, state, timeout) Wait for the given state of a server.

Namespace Detail

dim

Author: Thomas Bretz.

Field Detail

<static> {Array[Function]} dim.onchange

Callback in case of state changes. To install a callback in case the state of a server changes. set the corresponding property of this array to a function. The argument provided to the function is identical with the object returned by dim.state(). In addition the name of the server is added as the 'name' property and the comment sent with the state change as 'comment' property. For the code executed, the same rules apply than for a thread created with Thread.

If a state change is defined for a server for which no callback has been set, the special entry '*' is checked.

    dim.onchange['*'] = function(state) { console.out("State change from "+state.name+" received"); }
    dim.onchange['DIM_CONTROL'] = function(state) { console.out(JSON.stringify(state); }
    ...
    delete dim.onchange['DIM_CONTROL']; // to remove the callback

<static> <constant> {Integer} dim.version

DIM version number

Method Detail

<static> dim.alarm(argument)

Posts a message to the dim network with alarm severity. Similar to dim.log, but the message is posted to the network with alarm severity. This means that it is displayed in red and the smartfact web-gui will play an alarm sound. The alarm state will stay valid (displayed in the web-gui) until it is reset.

    dim.alarm("Alarm for 30 seconds!");
    v8.sleep(30000);
    dim.alarm();

Parameters:
argument: Any kind of argument can be given. If it is not a String, it is converted using the toString() member function.
. . . Optional: Any number of additional arguments. Each argument will appear as individual alarm.

<static> dim.getDescription(service)

Returns a description for one service The returned array has objects with the properties: name, description and unit. The last two are optional. The array itself has the properties name, server, service, isCommand and optionally format.

    var s = dim.getDescription("TNG_WEATHER/DATA");
    console.out("Name="+s.name);
    console.out("Server="+s.server);
    console.out("Service="+s.service);
    console.out("Format="+s.format);
    console.out("Description="+s.name);
    console.out("IsCommand="+s.isCommand);
    console.out(JSON.stringify(s));

Parameters:
{String} service: String specifying the name of the service to be returned.

Throws:
: If number or type of arguments is wrong

<static> {Array[Object]} dim.getServices(service, isCommand)

Returns a list of all known services The returned array has objects with the properties: name, server, service, command and (optional) format.

    // Return all services of the FAD_CONTROL starting with E
    var services = dim.getServices("FAD_CONTROL/E");
    console.out(JSON.stringify(services));

Parameters:
{String} service Optional, Default: '*': String a service has to start with to be returned. The default is to return all available services. An empty string or '*' are wildcards for all services.
{Boolean} isCommand Optional, Default: undefined: If no second argument is specified, data services and commands are returned. With true, only commands, with false, only data-services are returned.

Throws:
: If number or type of arguments is wrong

<static> {Object[StringObject]} dim.getStates(server)

Returns a list of all known state of a given server. The returned object has all states with their index as property. Each state is returned as a String object with the property description.

    var states = dim.getStates("SERVER");
    console.out(JSON.stringify(states));
    for (var index in states)
        console.out(index+"="+states[index]+": "+states[index].description);

Parameters:
{String} server Optional, Default: 'DIM_CONTROL': Name of the server for which states should be listed. The states of the DIM_CONTROl server are the default.

Throws:
: If number or type of arguments is wrong

<static> dim.log(argument)

Post a message into the dim log stream. It will be logged by the datalogger, displayed on the console and in the smartfact web-gui.

    dim.log("Five="+5, "--- new line ---");

Parameters:
argument: Any kind of argument can be given. If it is not a String, it is converted using the toString() member function.
. . . Optional: Any number of additional arguments. Each argument will appear in a new line.

<static> dim.send(commandId, argument)

Send a dim command to a dim client.

    dim.send('DRIVE_CONTROL/TRACK_SOURCE 0.5 180 "Mrk 421"');
    dim.send('DRIVE_CONTROL/TRACK_SOURCE', 0.5, 180, 'Mrk 421');

Parameters:
{String} commandId: The command id is a string and usually compiles like 'SERVER/COMMAND'
argument: Any kind of argument can be given. Arguments are internally converted into strings using toString() and processed as if they were typed on th console.
. . . Optional: Any number of additional arguments.

Returns:: A boolean value is returned whether the command was succesfully posted into the network or not. Note that true does by no means mean that the command was sucessfully received or even processed.

<static> {Object} dim.state(name)

Returns the state of the given server.

Parameters:
{String} name: The name of the server of which you want to get the state.

Throws:
: If number or type of arguments is wrong

Returns:: {Object} An object with the properties 'index' {Integer} and 'name' {String} is returned if a connection to the server is established and state information have been received, 'undefined' otherwise. If the time of the last state change is available, it is stored in the 'property'. If a server disconnected, a valid object will be returned, but without any properties.

<static> {Boolean} dim.wait(name, state, timeout)

Wait for the given state of a server. Note that the function is internally asynchornously checking the state, that means that theoretically, a state could be missed if it changes too fast. If this can happen callbacks have to be used.

Parameters:
{String} name: The name of the server of which you want to wait for a state. The name must not contain quotation marks. To wait for "not the given state", prefix the server name with an exclamation mark, e.g. "!DIM_CONTROL"
{String|Integer} state: The state you want to wait for. It can either be given as an Integer or as the corresponding short name. If given as String it must not contain quotation marks.
{Integer} timeout Optional: An optional timeout. If no timeout is given or a timeout of undefined, waiting will not stop until the condition is fulfilled. A timeout of 0 is allowed and will essentially just check if the server is in this state or not. If a negative value is given, exceptions are suppressed and false is returned in case of timeout. As timeout the absolute value is used.

Throws:
: If number or type of arguments is wrong
If no connection to the server is established or no state has been received yet. This is identical to dim.state() returning 'undefined' (only in case a positive timeout is given)

Returns:: {Boolean} true if the state was achived within the timeout, false otherwise.

Classes

Namespace dim