Cisco Mobile Wireless Fault Mediator 2.0.1 - Topology and Platform Modeling Reference Guide - Language Prerequisites [Network Management for Mobile Wireless]

Table Of Contents

Language Prerequisites

Introduction

Use of quotes in OQL and the Stitcher language

Double quotes ( " ")

Single forward quotes ( ' ' )

Quotation marks within eval statements

Summary

Single straight back quotes ( ` ` )

General rules of the quotation mark hierarchy

What is scope?

Scope significance: an analogy of enclosure

Conclusion

Language Prerequisites

This chapter provides information that should be read prior to reading the syntax of the languages that are defined in the Cisco Mobile Wireless Fault Mediator 2.0.1 - Topology and Platform Modeling Reference Guide.

Introduction

This chapter introduces the languages section of the Cisco Mobile Wireless Fault Mediator 2.0.1 - Topology and Platform Modeling Reference Guide. You will be introduced to some fundamental topics concerning the two languages that are available to you in the NMOS, i.e., the Object Query Language (OQL) and the Stitcher language. A powerful function called the eval statement is common to both languages.

The topics that will be covered in this chapter are:

•Use of quotes in OQL and the Stitcher language

•Quotation marks within eval statements

•What is scope?

•Scope significance: an analogy of enclosure

Use of quotes in OQL and the Stitcher language

There are three types of quotes available in OQL and the Stitcher language. The quotes enclose different language syntax. In order of the restrictions they apply these available quotes are listed below:

•The forward single quotes ( ' ' )

•The double quotes ( " " )

•The single straight back quotes ( ` ` )

Each quote is interpreted differently depending on the context of its use, i.e., within OQL, the Stitcher language, or an eval statement. The following sections describe how they should be used.

Double quotes ( " ")

Double quotes have different meanings in the context of OQL language and the Stitcher language.

Double quotes within OQL

Double quotes are used in OQL, to enclose TEXT data type. Some examples of the use of double quotes in this context are:

insert into snifferFinder.configuration

(

m_NumThreads,

m_LoopTimes,

m_Interfaces

)

values

(

1,

200,

["hme0"]

);

insert into translations.boolean values ( 0,"False" );

insert into translations.boolean values ( 1,"True" );

Note Numerical data types, e.g., integers are not enclosed in quotation marks

.

insert into disco.managedProcesses values

(

"riv_d_helpserv",

[ "-debug", 4 ],

"romanus"

);

The above example shows a standard add-on to DiscoSchema.cfg in the OQL language.

Note Literal values that are to be taken "as is" are enclosed in double quotation marks.

Note LIST data types are not enclosed within quotation marks; however, the individual data that constitute the list are enclosed within double quotes.

Double quotes within the Stitcher language

In the context of the Stitcher language, these are the least restrictive of the available quotes because of the order in which the Stitcher language syntax is parsed.

•When the Stitcher language parser looks through the code, any text enclosed in a set of double quotes that comes after the ExecuteOQL keyword is left alone and passed across (with the double quotation marks removed) to the OQL language parser for interpretation. An example of this is shown below:

ExecuteOQL

(

"select m_Name into ATMLayer.entityByName

from

workingEntities.entityByName

where

(

m_Creator = 'ATMAgent'

);"

);

Note The OQL statement is enclosed within a single pair of double quotes.

•Double quotes that do not come after the ExecuteOQL keyword can be used in conjunction with the Stitcher language trigger conditions to specify which Agents and Stitchers need to have finished their execution before the present Stitcher starts, as shown by the examples below:
DiscoRequiresAgents( "CiscoSwitchSnmp" , "AccelarSwitch" , 
"CentillionSwitch" , "StandardSwitch" );
DiscoRequiresAgents( "AccelarSwitch" );
ActOnTableInsert("IpRoutingTable", "returns");
ActOnTableInsert("CentillionSwitch", "returns");
CAVEAT

There is an inherent potential problem with the interpretation of double quotes within the Stitcher language. What happens if you use double quotes to denote OQL syntax within a Stitcher but you also wish to embed literal values such as TEXT data types that require double quotes in OQL? This problem is solved by the use of single quotes, which are discussed below.

Single forward quotes ( ' ' )

The interpretation of single quotes is also subject to the context of their use, i.e., in the Stitcher language or the Object Query Language.

Single quotes within OQL

When used within the OQL language, their interpretation is similar to double quotes as they can also be used to enclose literal values that require no processing. An example is shown below:

insert into system.snoopers values

(

'RIVERSOFT.3.0.MODEL.NOTIFY','kernel','modelLog',

'modelCreate','modelUpdate','modelDelete'

);

The above example shows a standard add-on to StoreSchema.cfg within the OQL language. Literal values that are to be taken "as is" are enclosed in single quotation marks.

Single quotes within the Stitcher language

Single quotes when used in the Stitcher language can be used to pass literal values to the Stitcher language parser as shown by the example below:

ExecuteStitcher('RefreshLayer2Database');

Single quotes are very useful in the Stitcher language when you wish to embed OQL fragments using the ExecuteOQL keyword. Any OQL fragments that are introduced by the ExecuteOQL keyword are enclosed in double quotes, which means you cannot use double quotes to enclose literal values. In such instances, single quotes are used as substitutes for double quotation marks within OQL fragments defined in the Stitcher language. An example of this is shown below:

ExecuteOQL

(

"select m_Name into ATMLayer.entityByName

from

workingEntities.entityByName

where

(

m_Creator = 'ATMAgent'

);"

);

Quotation marks within eval statements

The eval keyword and its statements provide very powerful ways of interrogating database records as well as investigating the Containment Model. The eval statement is always in the generic form shown below:

eval ( <cast_operator> , <evaluation_clause> )

When the evaluation clause occurs in the Stitcher language and is embedded within an OQL fragment which is itself embedded within double quotes, the evaluation clause must always be enclosed within single quotes, as shown by the following examples (exceptions to this rule are discussed further on):

•m_CompareDb = eval(text,'&m_Creator')

•m_LocalNbr = eval(object type vbList, '&m_LocalNbr')

•m_IpAddress = eval(text,'&m_IpAddress')

•eval(int, '$LocalNeighbor')

•m_LocalNbr->m_IpAddress = eval(text, '&m_RemoteNbr->m_RemoteNbrIpAddr')

•m_Name = eval(text, '&m_RemoteNbr->m_Name')

When the eval statement occurs within OQL or the Stitcher language, and is not already embedded within a set of either single or double quotes, the evaluation clause should be enclosed in double quotation marks:

•int haveAccess=eval(int, "&m_HaveAccess")

•int lastRec=eval(int, "&m_LastRecord");

•int portNum = eval(int, "&m_LocalNbr->m_LocalNbrPort")

Summary

As a general rule, if the eval statement occurs within a sequence of already embedded quotes in either OQL or the Stitcher language, the quotes embedding the evaluation clause must be of the alternate type to the quotes used to embed the whole statement within which it occurs. By default, when the eval statement does not occur within an embedded fragment double quotes are used to enclose the evaluation clause.

insert into system.stateRules values

(

'modelCreate','',

'insert into kernel.activeModel values ( eval(text,"$RECORD" ));',

1

);

Single straight back quotes ( ` ` )

Single straight back quotes are used to enclose absolute values. Absolute values are not interpretated by the language parsers, unlike literal values that are enclosed in double or single quotes (and must therefore directly evaluate to a valid OQL or Stitcher language data type, valid NMOS variable or database record reference). The absolute value is particularly useful when using the Containment Model evaluators to construct lists from evaluated database records or variable references using the CAT keyword, as shown in the following examples.

•eval(text, 'CAT(&m_Name,`[ 0 [ `,&m_LocalNbr->m_IfIndex,` ] ]`)')

•eval(text, 'CAT(&m_IpAddress,`[ 0 [ `,&m_LocalNbr->m_IfIndex,` ] ]`)')

•eval(text, 'CAT(&m_Name,`[ `,&m_LocalNbr->m_LocalNbrCard,` [ `,&m_LocalNbr->m_LocalNbrPort,` ] ]`)')

General rules of the quotation mark hierarchy

The rules of single or double quotation mark usage, are summarised below:

•Single quotes can be used to nest or contain double quotes; it is also possible for double quotes to enclose statements that contain single quotes

•Single quotes cannot contain single quotes

•Double quotes cannot contain double quotes

•Single straight back quotes are used to ensure that the enclosed text is never interpreted by the language parsers.

The next section of this chapter discusses the meaning of the term scope, particularly how it relates to the eval statements.

What is scope?

During the course of describing some of the functionality of the eval statements, especially with regards to the database reference identifiers (ampersanded operators), you will often come across the term scope. This section describes what is meant by this term with the help of a simple example.

A scope, for the purposes of the definition of programming syntax, is anything enclosed within matching curly brackets {} on the same hierarchical level. Thus it is possible to define sub-scopes within an existing scope by enclosing the sub-scope within a new subset of matching curly brackets. This concept is demonstrated by the example below:

Start of Syntax

{

Start of the first scope (SCOPE1)

..............

{

Start of the middle scope (SCOPE2)

..............

{

Start of lower middle scope (SCOPE3)

..............

{

Start of innermost scope (SCOPE4)

.......

.......

End of innermost scope (SCOPE4)

}

..............

End of lower middle scope (SCOPE3)

}

..............

..............

End of the middle scope (SCOPE2)

}

...........

End of the first scope (SCOPE1)

}

You can clearly identify four scopes at different levels in this example. When you are in any scope, database records that are known by the scope are said to be local. Any other database references that are not local to the current scope are said to be outside.

Scope significance: an analogy of enclosure

The eval operator allows you to reference database records that are local to the present scope as well as outside of the present scope. The only restriction is that you cannot reference database records of scopes that are nested within the present scope, because as far as the present scope is concerned, the records of the nested scope are yet to be defined or have been destroyed upon exit from their scope.

An analogy of scope is that of enclosure that shows boxes containing boxes, which themselves contain other boxes as shown by Figure 32-1, we shall for the purposes of this analogy refer to each box as a scope.

Figure 32-1 Analogy of scope—Enclosure

The ampersand operator (&) allows you to reference records local to outer scopes; this can be seen with the aid of the following example.

With reference to the enclosure analogy Figure 32-1, if your operation embedded within the scope defined as SCOPE3 references a named field of the local database records such as EntityName, you would do so simply as EntityName. However, if from within SCOPE3 you wish to access the EntityName field of a database record in SCOPE2, you must use the single ampersand operator, i.e., &EntityName. Similarly, if you wish to access the EntityName field of the database records local to SCOPE1 from within SCOPE3, you will have to do so by using the multiple ampersand operators, i.e., &&EntityName.

Note It is not possible for your operation to access the database records of the innermost scope, i.e., SCOPE4. This is because, as far as SCOPE3 is concerned, the records within SCOPE4 have either not been created or have been destroyed. However, it is possible for SCOPE4 to access all records in the outer scopes SCOPE3 - SCOPE1 as well as its local records by using the appropriate number of ampersand operators.

Conclusion

This chapter introduced a few important issues in the use of the OQL and Stitcher language syntax.

The next chapter describes the full syntax (with examples) of the Object Query Language (OQL), which can be used to interrogate and make modifications to the NMOS databases, and to embed OQL statements within the Stitcher language when writing rules for text-defined Stitchers.