You are here: SwitchKit® Development Environment - Installation and Maintenance Guide > 5 Building a Configuration File > Building a Configuration File

Building a Configuration File

Overview

The format of the configuration file is a series of configuration message specifications. The order of the parameters does not matter and white space and comments (delimited by #) are allowed. Example configuration files are provided in the folder: sample/cfg.

Some parameters of each SwitchKit configuration message are optional. The parameters used depend on the form of the message you are using, and which AIBs are being populated. Depending on the parameter, the value can be an integer (for example, 3), a quoted string (e.g., "hello there"), an unsigned data array, or a range.

Important! Configuration files should be created using CSA. If you create a configuration file by hand or alter one created by CSA, be certain the data for each message is properly assigned. Errors in data format can cause SwitchManager to fail.

Syntax

Configuration messages are not case sensitive. A message specification has the following format:

message_name(parameter1=value1, parameter2=value2,...);

Example

AssignSpan(node = 0, span = 1, slot=1, offset=0);

Message Format

The message formats are specified in the Messages.api.h file for C Structures and CMessages.api.h file for C++ classes. You can reference these file to see what the message and parameter names are. In the configuration file, the XL_, SK_, XLC_, and SKC_ prefix is always omitted.

AddLLCNode

The AddLLCNode message specifies the node ID and CSP Matrix Series 3 card IP addresses for each node. For configuration messages (such as AnswerSupervision) that use the range parameter, the node ID can be specified in the message but will be validated by the node ID in the AssignSpan message. Configuration messages such as, AssignSpan must have the node ID that is assigned with the AddLLCNode message.

All-In-Service and All-Out- of-Service

The AllInService and AllOutOfService messages allow you to bring all components (for example, spans and channels) of your configuration in or out of service with one message. These messages can be added to any configuration file. If these messages are included in a configuration file, SwitchManager brings all components out of service prior to any configuration and brings all components back into service after configuration is complete. If your configuration requires that some components remain out of service after configuration, you can add individual ServiceStateConfigure messages for each component in your configuration file.

Range Parameter

For configuration messages that apply to a range of channels, instead of specifying the range with four different parameters, you can use the special range parameter. The range argument can contain the name of a channel group. This channel group must be defined in the same configuration file; it cannot refer to a previously-defined channel group in a different configuration file. By using this feature, you can set up your channel groups only once in your file, and all other messages can just refer to those groups.

The range parameter has the following format:

StartSpan:StartChannel - EndSpan:EndChannel.

Example: TrunkTypeConfig from Span 0, Channel 0, to Span 6, Channel 23, would be specified as:

TrunkTypeConfig(range = 0:0 - 6:23, trunkType = 0x01)

Data Array

To specify a data array as an argument, list all the bytes individually, separated by a colon (:). The data array must be preceded by the Number of Data Locations.

Example: To do a SystemConfig with a Data array of the bytes 0x01 0x00 0x0a, specify it as:

SystemConfig(

ConfigType = 0x03,

Data = 0x00:0x01:0x01:0x01:0x05:0x01:0x00:0x0a;

Configuration Stages

SwitchManager automatically re-orders all the messages in the file into a legal configuration sequence. To force a certain ordering, use ConfigStage directives. Sets of messages can be grouped into stages. SwitchManager first sorts all the stages in numerical order, and then, within each stage, re-orders the messages into a legal sequence. All messages in stage n are guaranteed to be sent before any message in stage n+1 is sent.

In the example below, Messages 1 and 2 might be re-ordered, and Messages 3 and 4 might be reordered, but both Messages 1 and 2 are guaranteed to be sent before either Messages 3 or 4.

ConfigStage 1:

msg1();

msg2();

ConfigStage 2:

msg3();

msg4();

Poll Interval

Excel recommends that the poll interval between LLC and the switch be between one and five seconds. If the poll interval is not set, it defaults to two seconds. Turning off polls will disable some of the SwitchKit functionality and is strongly discouraged.

Configuration Notification

Many applications require the CSP configuration to be complete prior to custom setup or call processing. To determine when the configuration is complete, an application may register for Configuration Status messages. When the configuration is complete, the LLC broadcasts a Configuration Status message (ConfigStatusMsg) to the registered applications. You register an application to receive Configuration Status messages using the Message Register function (sk_msgRegister).

The Configuration Status message contains the following information:

• Event = (Configuration Begin, Configuration End or Configuration File Parse Error)

• ConfigType = (initial configuration, dynamic configuration, Card Reconfig, ConfigTagReset, etc.)

• Number of messages sent

• Number of messages receiving a Negative Acknowledgement (NACK)

This information can be used to synchronize an application with the Configuration Status as determined by SwitchManager.

Configuration Status messages are sent to the applications before DS0 status changes are returned by the switch.

Configurable Message Timeout

If a message is not completed within the message timeout period, the LLC times out. The typical message timeout value is 15 seconds, although it varies by message type. In most cases, the timeout value determined by the LLC is sufficient. However, it may not be sufficient when you are sending a large number of configuration messages to a single node. If you experience LLC timeouts during configuration, you can increase the default timeout value.

To increase the default Message Timeout value, issue the AdjustMessageTimeout message. The value you enter is added to the default value. For example, if the default value is 15 seconds and you enter 10 seconds, LLC will time out if it does not receive an acknowledgment message from the switch within 25 seconds (15 + 10).

SwitchManager adjusts the timeout values when configuring a multi-node system. Once configuration is complete, the timeout value is returned to the default.

See Converged Services Administrator.
Internet Protocol. Part of the TCP/IP family of protocols used to route messages and tracks the addresses of nodes.
Range of channels provided by T1 or E1 transmission service. A physical span is a group of channels taking up a single physical wire. A logical span is a group of channels taking up less than a single logical wire, or carried over more than one physical wire.
Negative acknowledgement to a message.