DML Reference
This section contains a full reference for the dynamic message language used in the Generic IBM MQ Mobile Adapter configuration dml files.
Lexical Conventions
A dml configuration consists of one or more files. Each file is processed in turn to generate a sequence of tokens, which are further processed into internal data structures used at run time to generate XML documents and process XML documents.
Syntax notation
In the syntax notation used in this Appendix, syntactic categories are indicated by italic type, and literal words and characters in bold type. An optional part of the syntax is indicated by enclosing it in square brackets ([]). An ellipsis (…) indicates that the preceding part of the syntax can be optionally repeated an arbitrary number of times.
Tokens
There are seven kinds of tokens: names, strings, quoted strings, keywords, operators, and other separators. Blanks, tabs, line feeds, carriage returns, and comments (described below), are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent tokens.
Comments
The character # starts a comment which terminates at the end of the line on which it occurs.
Include Directive
The include directive can appear anywhere in an input file and takes the form:
include file name
The contents of the file name are processed as if they replaced the include directive itself.
Keywords
The following names are reserved for use as keywords and may not be used otherwise:
associate persist BasePath classTable ConfigDoc else elseif for if include InputDoc OutputDoc queue RootElement sortIncidents sqlinsert sqlselect sqlupdate static stop VERSION
The following characters are used as operators or for punctuation:
@ $ & / ! | = : , " ; . ( ) [ ] < > { } +
The following character combinations are used as operators:
== != && ||
Names
A name is an arbitrarily long sequence of letters and digits. The first character must be a letter. The underscore _ counts as a letter. Upper and lower case letters are different. All characters are significant.
Strings
A string is an arbitrarily long sequence of letters and digits. . The underscore _ counts as a letter. Upper and lower case letters are different. All characters are significant.
Quoted Strings
A quoted string is an arbitrarily long sequence of characters, enclosed in double quotes "". To represent the double quote character in a quoted string, use two double quotes "".
Constants
A constant is one of:
• name
• string
• quoted string
Version Directive
The version directive takes the form:
VERSION = string;
The VERSION directive serves to identify the version of the current dml file and must appear outside any document definitions. When this directive is encountered, the current file name and the supplied version string are output to the log.
Basic Concepts
Type(s)
DML is a typeless language, or perhaps more accurately, a singly typed language. All values consist of character strings. DML has no concept of numbers. To illustrate this, strings can be used to pass positive integers to functions. For example:
@truncatedString = substring(@address, 0, 100);
However, quoted strings must be used to pass negative integers. For example:
@lastCharacter = substring(@characters, "-1", 1);
It should be emphasized that it is the function, not the dml that is interpreting the character string as an integer.
In certain contexts, a value is used as a boolean, or logical, value. Any non-empty string is considered true, and the empty string (written as "") is considered false. A boolean expression or function returns "Y" when true and "" when false.
Definitions and References
There are a number of value bearing entities in dml. Apart from one exception (variables), they must be defined before they are referenced. The definition introduces the entity, and defines certain modifiers to the entity. An entity is referenced when its value is used in an expression or when it is assigned to in an assignment statement. When a variable uses the default set of modifiers, it can be implicitly defined when first assigned.
Entities
The entities in a document carry values and have modifiers that change their behavior.
Variables
A variable is used to save intermediate results in a document. A variable definition takes the form:
@name:modifiers
The name must be unique amongst the variables within the document. Other entities can have the same name. The :modifiers is optional.
If the :modifiers are not required, variables can be implicitly defined when they are assigned to.
A variable reference takes the form:
@name
Variables can be set and referenced in all document types.
Elements
An element generates an XML element in Output Documents, and supplies an input XML element value or sub-elements in Input Documents. There are to kinds of element definitions: plain elements and array elements.
plain element definitions and an array element definitions are known collectively as element definitions.
Plain Element Definitions
Plain elements are referred to as elements in the rest of this section.
An element definition takes the form:
&name:modifiers < attribute definitions >
The name of an
element is its XML tag, and must be unique amongst the
elements within its immediately enclosing
element or document. Other entities can have the same name. The
:modifiers and
attribute definitions are optional. The format of
attribute definitions is described below in section
Attributes.
Elements must either have values but no sub-elements or must have sub-elements but no value. (This may be changed in a future version of the adapter).
Array Element Definitions
Array elements can only appear in Input Documents, and are used when more that one element with the same tag can be sub-elements of the same element in the input XML. An array element definition takes one of two forms: with an unspecified index, and with a specified index attribute.
The unspecified index form is:
&name[]:modifiers < attribute definitions >
The specified index form is:
&name[name]:modifiers < attribute definitions > R(constant list)
where the name in square brackets is the name of the index attribute, and R(constant list) is the required index list, which is optional. The required index list defines the values of the index attribute that must be in the input XML before the enclosing Input Document will be used to process the input XML.
Array element modifiers can only contain an alternate name for the array element.
The name of an array
element is its XML tag, and must be unique amongst the
elements within its immediately enclosing
element or document. Other entities can have the same name. The
:modifiers and
attribute definitions are optional. The format of
attribute definitions is described below in section
Attributes. Array
Elements must either have values but no sub-elements or must have sub-elements but no value.
Element References
The values of plain elements with values in Input Documents can be obtained using a plain element reference taking the form:
&element identifier
The element identifier has two forms:
The full element path, which is either the name of the element, if it is not a sub-element of another element, or the full element path of the sub-element's enclosing element, followed by a slash (/) followed by the element's name.
The element's alternate name, which is defined in the element's modifiers.
If the element has an alternate name, the full element path cannot be used.
The values of individual elements in an array element with values can be obtained using an array element reference taking the form:
&element identifier[index value]
The index value is either the value of the index attribute, in the case of a specified index, or a number in the case of an unspecified index, the elements being numbered in the order that the elements were in the input XML, starting at zero.
plain element references and an array element references are known collectively as element references.
Elements can only be referenced in Input Documents.
Attributes
An attribute generates an XML element attribute in Output Documents, and supplies an input XML element attribute value in Input Documents. An attribute definition is part of an element's attribute definitions and takes the form:
name:modifiers
The name of an attribute is its XML attribute, and must be unique amongst the attributes within its immediately enclosing element or document. Other entities can have the same name. The :modifiers are optional.
In Output Documents attributes must have their values assigned to them where they are defined in the form:
NAME:modifiers = expression;
The definition of an attribute in an Input Document takes the form:
NAME:modifiers;
Attributes are defined as part of the attribute definitions of their element as described above in section These attribute definitions are one or more attribute definitions.
The values of an attribute can be obtained using an attribute reference taking the form:
element reference<name>
Attributes can only be referenced in Input Documents.
Entity Modifiers
There are three entity modifiers:
The
flags which modify the behavior of the entity. See section
Flags in the main document for the uses of flags.
The
default value, which is used when entity is referenced but has no value. See section
Defaults in the main document for the circumstances that the default is used.
The
alternate name, which is used to give the entity an alternate name. See section
Alternate Names in the main document for the circumstances that the alternate name is used.
The modifiers are defined in the order flags, default value, alternate name and take the form:
:constant:constant:name
If a modifier at the end of the modifiers is empty the colon (:) must not be present. As a consequence, if all modifiers are empty, the modifiers are not present
External Data
External data is available from the various external data objects, described above in section
The External Objects. All fields in the objects can be read, but some objects or individual fields are read-only (they cannot be written).
A reference to an external object field takes the form:
$external data object identifier.field name
where the external data object identifier is the letter associated with the object and the field name is the name of the field (note that they are separated by a period (.)). Some fields (for example Handles) have sub-fields. A reference to a sub-field takes the form:
$external data object identifier.field name.sub-field name
Most external objects have one instance at a time, but the Incident Object can have zero, one or more, depending on the number of incidents that have grouped to the current event. To reference an individual incident field, an offset to the incident into the array of incidents is required. This offset starts at zero, and is a constant which must only contain digits, known as an offset. The normal order of incidents is the order that they were received by Oracle Utilities Network Management System. This order can be altered by use of the sortIncidents function. A reference to an incident field takes the form:
$I.offset.field name
Incident references can contain sub-fields.
These are known as external field references.
Note that some external object fields are read-only; in other words, they cannot be set by the dml. The read-only status of each external object is listed below:
• The Event Object ('E'): All fields are read-only.
• The Incident Object('I'): All fields are read-only.
• The Global Data Object ('G'): All fields are read/write.
• The Trigger Parameter Object ('T'): All fields are read/write.
Functions
A function is called using the following form:
name([parameter1] [, parameter2] …)
Where
name is the name of the function and parameter2, parameter2, … are
expressions. All functions return a value, but in some cases the value is always the empty string, implying that they are only called for their side effects. The functions available and their parameters are described in
DML Function Calls.
Expressions
An expression is a combination of dml components that yield a value. Expressions are combined using operators. The following table shows the expressions and the operators:
Note: The logical alternation, AND, and OR expressions are evaluated left to right and expressions that do not need to be evaluated are not evaluated, and any side effects (e.g., due to a function call) do not occur. Specifically:
Alternation: expression1 is evaluated. If it is true only expression2 is evaluated, otherwise only expression3 is evaluated.
AND: expression1 is evaluated. If it is false, expression2 is not evaluated.
OR: expression1 is evaluated. If it is true, expression2 is not evaluated.
Lists
Name List
A name list is one or more names separated by commas (,). For example:
h_cls, h_idx
Constant List
A constant list is one or more constants, separated by commas (,). For example:
None, "$%I99", 13, "-3", "This is a ""quoted"" string"
Variable Reference Lists
A variable reference list is one or more variable references, separated by commas (,). For example:
@devPhases, @pole_number, @winter_load, @summer_load
Expression List
A expression list is one or more expressions, separated by commas (,). For example:
@a + @b, formatDateTime(@time), $E.outageHdl.idx, none
Statements
Statements are the basic processing units in dml. Many of them are terminated using the statement terminator, ; (semi-colon).
Statement Blocks
A number of statements require one or more statements grouped together. This is achieved using a statement block, which takes the form:
{
statements
}
Where statements is one or more statements.
Variable Assignment Statement
This statement assigns a value to a variable and takes the form:
variable reference = expression;
Element Definition Statement
Element definitions differ between elements with values (simple elements) and those with sub-elements (compound elements). They also differ between those in Output Documents (output elements) and those in Input Documents (input elements). The four flavors are described in the following sections.
Output Element Definition Statements
These statements are only valid in Output Documents.
Simple Output Element Definition Statement
This statement assigns a value to an element and takes the form:
element definition = expression;
Compound Output Element Definition Statement
This statement defines an element with one or more sub-elements and takes the form:
element definition
statement block
The statement block must contain at least one output element definition statement, but can also contain other statements allowed in Output Documents.
Input Element Definition Statements
These statements are only valid in Input Documents.
Simple Input Element Definition Statement
This statement defines an element that can accept a value from incoming XML documents and takes the form:
element definition;
Compound Input Element Definition Statement
This statement defines an element with sub-elements that can accept values value from incoming XML documents and takes the form:
element definition
statement block
The statement block can only contain input element definition statements and must contain at least one.
External Data Assignment Statement
This statement assigns a value to an external object field and takes the form:
external field reference = expression;
Function Statement
This statement is used to call a function for its side effects and the return value is either the empty string or can be ignored. It takes the form:
function expression;
SQL Select Statement
This statement is used to read data from the database and takes the form:
sqlselect variable reference list | name list | [static] expression [ | expression …] ;
SQL Insert Statements
This statement is used to insert a row of data in a database table and takes the form:
sqlinsert expression | name list | expression list ;
SQL Update Statements
This statement is used to insert or update a row of data in a database table and takes the form:
sqlupdate expression | name list | expression list | name list | expression list ;
If Statement
This statement is used to alter the flow of expression evaluation, and output element selection, based on the value of an expression. It takes the form:
if (expression)
statement block 1
else if (expression)
statement block 2
else
statement block 3
elseif is a synonym for else if.
There can be any number of else if's, including none. The else is optional.
If the expression of the if is true, it's statement block (1 in this example) is evaluated.
Otherwise, if the expression of the first else if, if any, is true, it's statement block (2 in this example) is evaluated.
Otherwise, if the expression of the next else if, if any, is true, it's statement block is evaluated.
Otherwise, the else's statement block (3 in this example) is evaluated.
A maximum of one statement block will be evaluated in any if statement.
For Statement
This statement is use to iterate through all elements in an array element. It can only appear in an Input Document. It takes the form:
for (&element identifier[], variable reference)
statement block
Stop Statement
This statement is used to terminate processing of a document. In addition, it prevents an Output Document from sending its XML. It takes the form:
stop;
Root Element Statement
This statement is used to generate an Output Document's root element and to select the Input Document or Documents that the input XML can be processed by. In an Output Document it is located in the document's statement block. In an Input Document it is located in the input document header. It takes the form:
&RootElement [ < attribute definitions > ] = expression ;
Documents
Output Document Header
The output document header consists of the following specifications, in any order.
Queue Specification
This specification specifies the queue to which the Output Document's XML is directed to, and takes the form:
queue = expression ;
The queue is available to the Output Document's statement block as a variable named queue, and can be assigned to in the following manner:
@queue = expression ;
The queue specification is optional, and defaults to the empty string. If the queue specification is defaulted, it must be set in the Output Document's statement block. There may only be a maximum of one queue specification in the header of each Output Document.
Trigger Specification
An Output Document must have at least one trigger specification, and can have an arbitrary number greater than one.
Association Specification
This specification associates the Output Document with an external object, and takes the form:
associate = external data object identifier ;
The only external data object identifier currently supported is O, the Order Object. One and only one Output Document must be associated with the Order Object.
Persistence Specification
This specification allows you to set the persistence flag for outgoing messages, and takes the form:
persist = "Y" or "N";
If this specification is omitted, the message will have the default persistence setting configured for the queue it is being placed on.
Output Document
This document is used to generate XML and send it to the MDS. It takes the form:
OutputDoc name
output document header
statement block
Input Document Header
The input document header consists of one and only one root element statement and the following specifications, in any order.
Queue Specification
This specification specifies the queue on which the Input Document's XML is received from, and takes the form:
queue = expression ;
The queue is available to the Input Document's statement block as a variable named queue.
There must be one and only one queue specification in the header of each Input Document.
Base Path Specification
The specification specifies the sub-element of the root element of the XML document which contains all elements that will be processed by the Input Document. It takes the form:
BasePath = full element path;
Input Document
This document is used to process input XML from the MDS. It takes the form:
InputDoc name
input document header
statement block
Configuration Document
This document is used to set configuration data and load configuration tables from the database at initialization time. It takes the form:
ConfigDoc name
statement block
Order of Document Processing and Other Considerations
The dml is read during adapter initialization in the order that the files are specified in the command line. Files from the command line must contain only complete documents, but files read using the include directive can contain any valid dml fragment, dependent on the context of the directive.
The processing of statements within a document is strictly from top to bottom in the order the statements were read during initialization, except when altered by a control flow statement (for example, if and for statements). Statements in a document are processed until one of the following situations occur:
The last statement in the document is reached. If the document is an Output Document, the resulting XML is delivered to the queue specified in the document's queue specification.
A stop statement is processed. If the document is a Configuration Document, the adapter sends an error message to the log and then exits.
A run time configuration error occurs. In all cases, the adapter sends an error message to the log and then exits.
An unrecoverable run time error occurs (for example, DBService is not available to read or write a database table). In all cases, the adapter sends an error message to the log and then exits.
The processing of specifications in a document header is not necessarily in top to bottom order. Each document is described below.
Output Documents
Output Document specifications are processed in the following order:
The association specification is processed once during initialization.
The queue specification is evaluated just before the first statement of the document is processed.
When a trigger event occurs, all Output Documents are examined in top to bottom order to determine whether the event should trigger each document.
If the trigger event's type matches at least one trigger specification in the document, the triggers of that type are processed in top to bottom order, until one evaluates to true. In this case, all other triggers have their value set to false, even if they have not been processed. If all triggers evaluate to false the document is not processed due to the trigger event.
If the Output Document is triggered, it is fully processed before the next Output Document is examined in order to determine whether the event should trigger the next document.
Input Documents
All Input Document header specifications are evaluated at initialization, in the order base path specification, queue specification, and then root element specification.
When an input XML document arrives, each Input Document is examined in top to bottom order to determine whether the XML satisfies the root element specification. If no document matches the incoming XML, the XML is discarded. If at least one Input Document is eligible, the elements in the XML are delivered to the documents in the order they appear in the XML document. Once all elements have been delivered, each document is examined in top to bottom order to determine whether all required elements are present, and are processed in top to bottom order if the elements are present. Once all Input Documents have been processed, the XML is discarded.
Configuration Documents
Configuration Documents have no header specifications. All Configuration Documents are processed in top to bottom order. Once they all have been processed successfully, they are discarded.
Ordering of Incidents in the Incident Object
When processing starts for a document, the incidents in the Incident Object are in their normal order, which is the order that they were received by Oracle Utilities Network Management System. This order can be changed during the processing of the document by calling the sortIncidents function. The ordering remains the same during the processing, unless sortIncidents is called again. The order is set back to normal when the document processing finishes.
Interactions between Threads
The adapter is a multi-threaded process. Therefore more than one document can be processed at the same time, increasing performance. There is at least one thread for Output Document processing, and at least one thread for each Input Document queue. More threads can be configured using a Configuration Document. The adapter uses a number of other threads for internal processing.
This has a number of implications.
While trigger events are queued internally in the order that they occur, and are extracted from this queue in the order that they were queued, there is no guarantee that the Output Documents triggered by these events will complete their processing in the order the events were queued. This means the XML messages may be delivered to the MQSeries queue in an unexpected order. If this behavior is inappropriate, it can be eliminated at the expense of performance by using only one output thread, and by setting the config_Event_QueueDelay configuration parameter to zero.
A similar situation exists with input XML documents. They also cannot be guaranteed to update Oracle Utilities Network Management System in the order that they arrive. This situation can be improved at the expense of performance by limiting each input queue to one thread. It may be possible to eliminate it completely if the interface can be configured to use only one input queue.
Note that trigger events and input XML that affect particular Oracle Utilities Network Management System events, Order Objects, and Relationship Objects are processed in the order that they are queued. These situations are discussed below.
Note, however, that there is an inherent race condition in loosely coupled interfaces (the type implemented by the adapter) that use messages to communicate. Events can occur in Oracle Utilities Network Management System and the MDS that alter the state of Oracle Utilities Network Management System events and MDS orders almost simultaneously and it cannot be predicted whether the change on one system affects the other system first, or vice versa. Paradoxically, this situation can be improved by increasing the rate at which messages are processed (by increasing the number of threads.)
The input, output, and internal threads need to coordinate access to various shared resources. Most of this coordination is invisible on the dml level, but a number of aspects of the coordination are worth consideration when writing dml.
One specific means of coordination is known as a mutex (for mutual exclusion). To access a shared resource that is protected by a mutex, the thread requests the mutex. If the mutex is free, the thread acquires the mutex. If another thread requests the mutex, it blocks (is suspended) until it is free. When the original thread has finished accessing the shared resource, it releases the mutex, making it free. The release unblocks one thread waiting for the mutex. When there is the potential for more than one mutex to be in use, there is a danger of a deadlock if one thread enters the mutexes in a different order from another thread. One a deadlock occurs, neither thread will ever run again.
Each thread runs in a separate environment, with a copy of each relevant document, but needs to share a number of resources. The access to these objects must be properly coordinated to prevent inconsistent access due to multiple threads updating the resource at the same time. These resources and the mechanisms used to prevent inconsistent access are:
• The Global Data Object: The update of a single field is atomic (the update will be complete before any other thread can attempt to read or update the field). There is no coordination of updates to multiple fields. To avoid this problem, use a single field.
• The Order Object: There is one Order Object for each order that has been created. Access to an individual Order Object is coordinated so that only one document can access the Order Object at one time. When a document in a thread needs to access an Order Object it calls findOrder. When successful, findOrder acquires the order's mutex, preventing any other thread from accessing the Order Object. The order's mutex is automatically acquired when the order is created by calling createOrder. The order's mutex is automatically released in the following cases: when the document processing is terminated, and when findOrder or createOrder is called. This is to prevent deadlocks. A consequence of this is that if a trigger event triggers two Output Documents needing the same order, or two Input Documents are triggered by one input XML message, the state of the order when the second document starts processing is not guaranteed to be the same, because another thread may have altered its state.
• The Relationship Object: There is one Relationship Object for each relationship that has been created. Access to an individual Relationship Object is coordinated so that only one document can access the Relationship Object at one time. When a document in a thread needs to access a Relationship Object it calls findRelation. When successful, findRelation acquires the relationship's mutex, preventing any other thread from accessing the Relationship Object. The relationship's mutex is automatically acquired when the relationship is created by calling createRelation. The relationship's mutex is automatically released in the following cases: when the document processing is terminated, and when findRelation or createRelation is called. This is to prevent deadlocks. A consequence of this is that if a trigger event triggers two Output Documents using needing the same relationship, or two Input Documents are triggered by one input XML message, the state of the relationship when the second document starts processing is not guaranteed to be the same, because another thread may have altered its state. In addition, when findOrder or createOrder is called, the mutex for the order's relationship is automatically acquired. This has the consequence that calling findOrder or createOrder after calling findRelation causes a configuration error if the order is not in the relationship. Similarly, calling findRelation after calling findOrder or createOrder causes a configuration error if the order is not in the relationship. This behavior is necessary to prevent deadlocks.
• The current event: SRSoutput message for the same event must be processed in the order that they were sent by JMService, otherwise the MDS will not receive up to date data. This prevented by a mutex that is acquired before the SRSoutput message is processed, and released automatically when it has been processed.
DML Function Calls
The importance of meeting the prerequisite specifications for all functions cannot be emphasized too much. If a prerequisite is not met, the adapter will exit with a fatal error message. Some of the prerequisites are written is short form because they are so common. An explanation of how to meet these prerequisites follows:
• The current crew is set: The current crew is set by a successful call to the createCrew function, and by any of the findCrew… functions.
• The current order is set: the current order is set by the createOrder and findOrder functions.
• The current event is set: the current event is set when the current order is set, when an OutputDocument has been triggered by the arrival of an SRSoutput message, and when a call to findEventObject is successful.
• The current damage report is set: the current damage report is set by a call to createDamage, findDamage, findDamageByExternalId, or findOrCreateDamage
In addition, access to the E (event), I (incident), O (order) and R (relation) objects will only work if their prerequisites are met. If these are not met, the adapter does not exit, but all accesses fail, meaning no data can be read or written. Their prerequisites are:
• E: the current event is set.
• I: the current event is set (and it has incidents)
• O: the current order is set.
• R: the current relation is set by a call to findRelation.
List of Functions
Crew Functions
These functions create and update crews.
createCrew
Create a new crew.
SYNOPSIS
createCrew( crew ID, crew field, data, [crew field, data], ...)
PARAMETERS
crew ID The crew ID
crew field The crew field to update.
crewType calls Crew::crewType() API
zoneName calls Crew::zoneName() API
crewSize calls Crew::crewSize() API
contact calls Crew::contact() API
crewId calls Crew::crewId() API
mobileNum calls Crew::mobileNum() API
pagerNum calls Crew::pagerNum() API
zoneHdl calls Crew::zoneHdl() API
crewCategory calls Crew::crewCategory() API
crewCenter calls Crew::crewCenter() API
crewGroup calls Crew::crewGroup() API
crewSupervisor calls Crew::crewSupervisor() API
externalKey calls Crew::externalKey() API
data The data written to the crew field
Note: If the Crew Icons Window is used make sure that the following crew fields: crewType, contact, zoneName, zoneHdl, crewCategory, crewCenter, crewSupervisor, are included otherwise the new crew will not appear in the Window.
PREREQUISITE
The crew field parameters are valid.
DESCRIPTION
Create a new crew with the specified information using the Crew::createCrew API. If successful, set the current crew to the new crew.
RETURN VALUE
True when successful.
False when unsuccessful.
A crew with the specified crew ID exists. This can be determined by a call to findCrewById().
The Crew::createCrew() API call fails.
Note that the current crew is not set if the call fails.
DIAGNOSTICS
Error messages are output to the error log.
deleteCrew
Deletes the crew with the specified crew ID
SYNOPSIS
deleteCrew( crewID )
PARAMETERS
crewID The crew ID.
PREREQUISITE
None.
DESCRIPTION
Deletes the crew with the specified crew ID.
RETURN VALUE
True when successful.
False when unsuccessful.
DIAGNOSTICS
None.
findCrewById
Find an active or inactive crew based on its crew ID
SYNOPSIS
findCrewById( crew ID )
PARAMETERS
crew ID The crew ID.
PREREQUISITE
None.
DESCRIPTION
Find the crew with the specified crew ID.
RETURN VALUE
True when successful. The current crew is set to the crew that was found.
False when unsuccessful.
DIAGNOSTICS
None.
findCrewByExternalKey
Find an active or inactive crew based on its external key
SYNOPSIS
findCrewByExternalKey( externalKey )
PARAMETERS
externalKey The external key.
PREREQUISITE
None.
DESCRIPTION
Find the crew with the specified external key.
RETURN VALUE
True, when successful. The current crew is set to the crew that was found.
False when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
findCrewByIdSubStr
Find an active or inactive crew based on a substring of the crew ID
SYNOPSIS
findCrewByIdSubStr( string )
PARAMETERS
string A string.
PREREQUISITE
None.
DESCRIPTION
Find a crew whose crew ID contains the string.
RETURN VALUE
True when successful. The current crew is set to the crew that was found.
False when unsuccessful.
DIAGNOSTICS
None.
findCrewByExtKeySubStr
Find an active or inactive crew based on a substring of its external key
SYNOPSIS
findCrewByExternalKey( string )
PARAMETERS
string A string.
PREREQUISITE
None.
DESCRIPTION
Find a crew whose external key contains the string.
RETURN VALUE
True, when successful. The current crew is set to the crew that was found.
False when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
findCrewByEventIdx
Find a crew which is associated with the given event.
SYNOPSIS
findCrewByEventIdx( eventIdx )
PARAMETERS
eventIdx Event index.
PREREQUISITE
None.
DESCRIPTION
Find a crew which is assigned (including suspended), en-route or onsite for the event with the given event index.
The first crew found is returned. Assigned/suspended crews are searched first.
RETURN VALUE
True when successful. The current crew is set to the crew that was found.
False when unsuccessful.
DIAGNOSTICS
None.
returnCrewKeyById
Return crew key for the given crew id.
SYNOPSIS
returnCrewKeyById( crewID )
PARAMETERS
crewID Crew ID.
PREREQUISITE
None.
DESCRIPTION
Searches active and inactive crews for a crew with the given crew id. Returns the key of the found crew.
RETURN VALUE
Found crew key of an empty string if nothing was found.
DIAGNOSTICS
None.
updateCrew
Update the current crew's information.
SYNOPSIS
updateCrew( crew field, data, [crew field, data], ..)
PARAMETERS
crew field The crew's field to update.
crewType calls Crew::crewType() API
zoneName calls Crew::zoneName() API
crewSize calls Crew::crewSize() API
contact calls Crew::contact() API
crewId calls Crew::crewId() API
mobileNum calls Crew::mobileNum() API
pagerNum calls Crew::pagerNum() API
zoneHdl calls Crew::zoneHdl() API
crewCategory calls Crew::crewCategory() API
crewCenter calls Crew::crewCenter() API
crewGroup calls Crew::crewGroup() API
crewSupervisor calls Crew::crewSupervisor() API
externalKey calls Crew::externalKey() API
data The data written to the crew field
PREREQUISITE
The current crew is set.
The crew field parameters are valid.
DESCRIPTION
Update the current crew's crew field with data and invoke the Crew::commit() API to commit the changes.
RETURN VALUE
True when successful.
False when unsuccessful.
The Crew::commit() API call fails.
DIAGNOSTICS
Error messages are output to the error log.
dispatchCrew
Dispatch the current crew to the current order
SYNOPSIS
dispatchCrew()
PARAMETERS
None.
PREREQUISITE
The current crew is set.
The current order is set.
DESCRIPTION
If the crew is already dispatched to another event, the previous dispatch is changed to an assignment.
Invoke the Crew::dispatch() API for the order's active event. If the order is aggregated, assign the crew to the other events.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
arriveCrew
Update the current crew's information to reflect that the crew has arrived on site for an order.
SYNOPSIS
arriveCrew()
arriveCrew(time)
PARAMETERS
time The time the crew arrived in internal format. If this parameter is not
supplied, the current time is used.
PREREQUISITE
The current crew is set.
The current order is set.
DESCRIPTION
If the crew is not dispatched to the order, the crew is dispatched to the order, using the logic described in the description of the 'dispatchCrew' function.
If the time is zero or invalid it is set to the current time
Invoke the CrewDispatch::arrived() API for the order's active event.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
assignCrew
Assign the current crew to the current order
SYNOPSIS
assignCrew()
PARAMETERS
None.
PREREQUISITE
The current crew is set.
The current order is set.
DESCRIPTION
If the crew is dispatched to the order, undispatch it.
Invoke the Crew::assign() API for all events associated with the order.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
assignCrewsToAllRelatedEvents
SYNOPSIS
assignCrewsToAllRelatedEvents()
PARAMETERS
None.
PREREQUISITE
The current relation is set.
DESCRIPTION
This function makes sure that if a crew is assigned to one of the related events then it is also assigned to all of the event which are part of the same relation.
RETURN VALUE
'Y' on success, the empty string in current relation is not set.
DIAGNOSTICS
Error messages are output to the error log.
unassignCrew
Unassign the current crew from the current order
SYNOPSIS
unassignCrew()
PARAMETERS
None.
PREREQUISITE
The current crew is set.
The current order is set.
DESCRIPTION
If the crew is assigned or dispatched to any events associated with the order, invoke the Crew::unassign() API or Crew::undispatch API, respectively, for the events.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
unassignCrewByKey
NAME:
unassignCrewByKey Unassign the crew with the given crew key from the current order
SYNOPSIS
unassignCrewByKey(crewKey)
PARAMETERS
crewKey crew key
PREREQUISITE
The current order is set.
DESCRIPTION
Unassign the crew with the given crew key from any events associated with the current order.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
suspendCrew
NAME:
suspendCrew Suspends the current crew from the current order
SYNOPSIS
suspendCrew()
PARAMETERS
None.
PRE-REQUISITE:
The current crew is set.
The current order is set.
DESCRIPTION
Suspends the current crew from the current order.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
activateCrew
NAME:
activateCrew Change the state of the current crew to active or inactive.
SYNOPSIS
activateCrew(state)
PARAMETERS
state The state of the crew.
• Y: Activate the current crew.
• N: Deactivate the current crew, set it off-shift, and remove all crew assignments and jobs.
PREREQUISITE
The current crew is set.
DESCRIPTION
Invoke Crew::setActivation() API.
RETURN VALUE
True when successful.
False when unsuccessful.
The assignments and jobs cannot be removed from the current crew
The Crew::setActivation() API call fails.
DIAGNOSTICS
Error messages are output to the error log.
availableCrew
NAME:
availableCrew Change the availability of the current crew.
SYNOPSIS
availableCrew(state)
PARAMETERS
state The availability of the crew
• Y: Make the current crew available.
• N : Make the current crew unavailable; remove all crew assignments and jobs.
PREREQUISITE
The current crew is set.
DESCRIPTION
Invoke Crew::setAvailability() API.
RETURN VALUE
True when successful.
False when unsuccessful.
The assignments and jobs cannot be removed from the current crew
The Crew::setAvailability() API call fails.
DIAGNOSTICS
Error messages are output to the error log.
setCrewAvailability
NAME:
setCrewAvailability Change the availability of the current crew.
SYNOPSIS
setCrewAvailability(state, when, reason)
PARAMETERS
state The availability of the crew
• Y: Make the current crew available.
• N: Make the current crew unavailable.
when The time when crew availability change.
reason The reason why the crew is unavailable. Only used when state is 'N'.
PREREQUISITE
The current crew is set.
DESCRIPTION
Changes availability of the current crew.
RETURN VALUE
True.
DIAGNOSTICS
Error messages are output to the error log.
releaseCrews
NAME:
releaseCrews Release all crews from the current order.
SYNOPSIS
releaseCrews
PARAMETERS
None.
PREREQUISITE
Current order is set.
DESCRIPTION
Undispatch and unassign all crews related to the current order.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
releaseCrewsLocal
Internally release all crews from the current order.
SYNOPSIS
releaseCrewsLocal
PARAMETERS
None.
PREREQUISITE
Current order is set.
DESCRIPTION
Internally release all crews from the current order and does not send any crew messages to NMS. This function only updates the adapter's memory.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
crewActive
Determine if the current crew is active.
SYNOPSIS
crewActive()
PARAMETERS
None
PREREQUISITE
The current crew is set.
DESCRIPTION
Invoke Crew::isActive() API.
RETURN VALUE
True, when the current crew is active.
False, when current crew is not active.
DIAGNOSTICS
Error messages are output to the error log.
setCrewOnShift
Change the state of the current crew to on shfit or off shift.
SYNOPSIS
setCrewOnShift(onShift, time)
PARAMETERS
onShift The state of the crew
• Y: Set the current crew to on-shift. This will also activate the crew if it is currently inactive.
• N: Set the current crew to off-shift and suspend any jobs.
time The time the crew shift change occurred. If this parameter is not supplied,
the current time is used.
PREREQUISITE
The current crew is set.
DESCRIPTION
Invoke Crew::setOnShift() API.
RETURN VALUE
True when successful.
False when unsuccessful.
The Crew::setOnShift() API call fails.
DIAGNOSTICS
Error messages are output to the error log.
crewOnShift
Determine if the current crew is on shift.
SYNOPSIS
crewOnShift()
PARAMETERS
None
PREREQUISITE
The current crew is set.
DESCRIPTION
Invoke Crew::isOnShift() API.
RETURN VALUE
True, when the current crew is on shift.
False, when current crew is not on shift.
DIAGNOSTICS
Error messages are output to the error log.
crewOutOfRange
Change the out-of-range status state of the current crew.
SYNOPSIS
crewOutOfRange(outOfRange)
PARAMETERS
outOfRange The out-of-range status of the crew
• Y: Set the current crew to be out of range.
• N: Set the current crew to be in range.
PRE-REQUISITE:
The current crew is set.
DESCRIPTION
Sets out-of-range status of the current crew.
RETURN VALUE
True when successful.
False when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
crewIsMobile
Determine if the current crew is mobile.
SYNOPSIS
crewIsMobile()
PARAMETERS
None
PREREQUISITE
The current crew is set.
DESCRIPTION
Checks that mobile flag of the current crew is not equal to N.
RETURN VALUE
True, when the current crew is mobile.
False, when current crew is not mobile.
DIAGNOSTICS
Error messages are output to the error log.
crewIsCurrentlyMobile
Determine if the current crew is mobile at this time.
SYNOPSIS
crewIsCurrentlyMobile()
PARAMETERS
None
PREREQUISITE
The current crew is set.
DESCRIPTION
Checks that mobile flag of the current crew is set to Y. This excludes crews which are normally mobile but are currently overridden to allow dispatching from NMS.
RETURN VALUE
True, when the current crew is currently mobile.
False, when current crew is currently not mobile.
DIAGNOSTICS
Error messages are output to the error log.
setVehicleId
Update the current crew's vehicle information.
SYNOPSIS
setVehicleId( unused, vehicleNumber, vehicleType )
PARAMETERS
unused This parameter is not used.
vehicleNumber The vehicle number.
vehicleType The vehicle type name.
PREREQUISITE
The current crew is set.
The crew field parameters are valid.
DESCRIPTION
Update the current crew`s vehicle information. If crew with given vehicle number exists then it will be used. If existing vehicle is inactive it will be activated. If crew with given vehicle number does not exist then new vehicle record will be created.
RETURN VALUE
True, when successful.
False, when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
updateCrewCoordinates
Update the current crew's coordinates as well as its speed and heading.
SYNOPSIS
updateCrewCoordinates(x, y, speed, heading)
PARAMETERS
x The X coordinate of the current crew.
y The Y coordinate of the current crew.
speed The speed of the current crew.
heading The heading of the current crew (0 to 359, where 0 is North, 90 is East,
180 is South, 270 is West).
PREREQUISITE
The current crew is set.
DESCRIPTION
Updates the current crew's coordinates as well as its speed and heading.
Coordinate values must be in the coordinate system used within NMS. This function does not perform conversion between different coordinate systems.
RETURN VALUE
True when successful.
False when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
orderCrewStatus
Returns the highest crew status for the current order.
SYNOPSIS
orderCrewStatus()
PARAMETERS
None.
PREREQUISITE
The current order is set.
DESCRIPTION
Returns the highest crew status for the current order. Crew status priority (highest to lowest):
• onsite
• en-route
• assigned
RETURN VALUE
'O' if a crew is onsite, 'D' if a crew is en-route, 'A' if a crew is assigned, otherwise empty string.
DIAGNOSTICS
Error messages are output to the error log.
getOrderCrews
Returns comma-separated list of crew ids assigned to the specified order
SYNOPSIS
getOrderCrews(orderNumber)
PARAMETERS
orderNumber The order number.
PREREQUISITE
The current order is set.
DESCRIPTION
Returns comma-separated list of crew ids assigned to the specified order.
RETURN VALUE
Comma-separated list of crew ids.
DIAGNOSTICS
Error messages are output to the error log.
Code Mapping Tables
The code mapping tables and views are used to translate values in Oracle Utilities Network Management System to and from the equivalent values in the messages to and from the MDS. These tables are cached to improve performance.
loadMapConfigTable
Cache the contents of a table supplying information for the mapping tables.
SYNOPSIS
loadMapConfigTable(table)
PARAMETERS
table A table name.
PREREQUISITE
None.
DESCRIPTION
Read and cache table.
RETURN VALUE
True, when successful.
False, otherwise.
DIAGNOSTICS
Error messages are output to the error log.
loadMapTable
Cache the contents of a mapping table.
SYNOPSIS
loadMapTable(name)
PARAMETERS
name The name of the mapping table.
PREREQUISITE
The table, name, exists in the database.
DESCRIPTION
Read the contents of name and cache its values.
RETURN VALUE
True, when successful.
False, otherwise.
DIAGNOSTICS
Error messages are output to the error log.
mapTableStr
Return a string given its reference code
SYNOPSIS
mapTableStr(name, code)
PARAMETERS
name A mapping table name
code A reference code to a string.
PREREQUISITE
The table, name, exists in the database.
DESCRIPTION
Check if the table, name exists in memory, if not, call loadMapTable to load it.
Look up the string that corresponds to code and return the string. If code is not found, but a default string exists, the default value is returned, otherwise return the empty string.
RETURN VALUE
The string when successful.
The empty string when code is not found.
DIAGNOSTICS
Error messages are output to the error log.
mapTableCode
Return a code given its reference string
SYNOPSIS
mapTableCode(name, string)
PARAMETERS
name A mapping table name
string A string
PREREQUISITE
The table (name) exists in the database.
DESCRIPTION
Check if the table name exists in memory; if not, call loadMapTable to load it.
Look up the code that corresponds to string and return the code. If string is not found, but a default code exists, the default code is returned, otherwise return the empty string.
RETURN VALUE
The code when successful.
The empty string when string is not found.
DIAGNOSTICS
Error messages are output to the error log.
Damage Assessment Functions
These functions creates and updates damage reports.
createDamage
Create an empty damage report instance.
SYNOPSIS
createDamage()
PARAMETERS
None.
PREREQUISITE
None.
DESCRIPTION
Creates an empty damage report instance. This function does not create a new damage report in NMS but rather creates damage report object in DML, which can then be populated and saved to actually create new or update existing damage report.
RETURN VALUE
None.
DIAGNOSTICS
None.
findDamage
Load an existing damage report by id.
SYNOPSIS
findDamage(reportId)
PARAMETERS
reportId unique damage report identifier (stored in the
DAMAGE_REPORT.REPORT_ID database column)
PREREQUISITE
None.
DESCRIPTION
Loads damage report for the given identifier. If no damage report with such identifier exists then empty damage report instance is created.
RETURN VALUE
True, if existing damage report was found and loaded.
False, if existing damage report was not found and empty one was created.
DIAGNOSTICS
Error messages are output to the error log.
findDamageByExternalId
Load an existing damage report by external identifier.
SYNOPSIS
findDamageExternalId(externalId)
PARAMETERS
externalId external damage report identifier
PREREQUISITE
None.
DESCRIPTION
Loads damage report for the given external identifier. If no damage report with such identifier exists then empty damage report instance is created.
RETURN VALUE
True, if existing damage report was found and loaded.
False, if existing damage report was not found and empty one was created.
DIAGNOSTICS
Error messages are output to the error log.
findOrCreateDamage
Create a damage report for an device outage
SYNOPSIS
findOrCreateDamage(event)
PARAMETERS
event An event handle.
PREREQUISITE
None.
DESCRIPTION
Load the damage report for event. If no damage report exists for the event, create it.
RETURN VALUE
True, if the damage report was created.
False, if the damage report existed before the call.
DIAGNOSTICS
Error messages are output to the error log.
damageSetCrewId
Update the damage report with a crew ID
SYNOPSIS
damageSetCrewId(crewId)
PARAMETERS
crewId A crew ID.
PREREQUISITE
The current damage report is set.
DESCRIPTION
The crew ID field in the damage report is updated with crewId.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetRadioNum
Update the damage report with a crew mobile ID (radio number)
SYNOPSIS
damageSetRadioNum(mobileId)
PARAMETERS
mobileId A crew mobile ID (radio number).
PREREQUISITE
The current damage report is set.
DESCRIPTION
The Mobile # field in the damage report is updated with mobileId.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetReportTime
Update the damage report with a time
SYNOPSIS
damageSetReportTime(time)
PARAMETERS
time A time.
PREREQUISITE
The current damage report is set
DESCRIPTION
The reported time field in the damage report is updated with time.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetEvent
Set event handle in newly created damage report
SYNOPSIS
damageSetEvent(event)
PARAMETERS
event An event handle.
PREREQUISITE
The current damage report is set.
DESCRIPTION
Sets event handle in newly created damage report. This would cause this damage report to be associated with the specified event. It is an error to call this function for an existing damage report.
RETURN VALUE
None.
DIAGNOSTICS
Error messages are output to the error log.
damageSetExternalId
Set external id in newly created damage report
SYNOPSIS
damageSetEvent(externalId)
PARAMETERS
externalId An external identifier for this damage report.
PREREQUISITE
The current damage report is set.
DESCRIPTION
Sets external identifier in newly created damage report. If provided the external identifier should be unique. It is an error to call this function for an existing damage report.
RETURN VALUE
None.
DIAGNOSTICS
Error messages are output to the error log.
damageSetDevice
Set device alias in damage report
SYNOPSIS
damageSetDevice(deviceAlias)
PARAMETERS
deviceAlias A device alias.
PREREQUISITE
The current damage report is set.
DESCRIPTION
Sets device alias in damage report. For newly created damage report this would cause it to be placed on the specified device unless event handle is also set in which case damage report is placed on the outage device. Setting device alias for an existing damage report would cause it to be moved to the new device.
RETURN VALUE
None.
DIAGNOSTICS
None.
damageSetAddress
Update the damage report with an Address
SYNOPSIS
damageSetAddress(Address)
PARAMETERS
Address An Address.
PREREQUISITE
The current damage report is set
DESCRIPTION
The Address field in the damage report is updated with Address.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetFeederName
Update the damage report with a feeder name
SYNOPSIS
damageSetFeederName(feeder name)
PARAMETERS
feeder name A feeder name.
PREREQUISITE
The current damage report is set
DESCRIPTION
The feeder name field in the damage report is updated with feeder name.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetNcg
Update the damage report with an ncg
SYNOPSIS
damageSetNcg(ncg)
PARAMETERS
ncg An ncg.
PREREQUISITE
The current damage report is set
DESCRIPTION
The ncg field in the damage report is updated with ncg.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetRepairMinutes
Sets repair minutes for a damage report.
SYNOPSIS
damageSetRepairMinutes(number of minutes)
PARAMETERS
minutes The number of minutes.
PREREQUISITE
The current damage report is set
DESCRIPTION
Sets repair minutes for a damage report. Setting to negative values causes repair minutes to be recalculated from the entered damage type information
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetZoneName
Update the damage report with a zone name
SYNOPSIS
damageSetZoneName(zone name)
PARAMETERS
zone name A zone name.
PREREQUISITE
The current damage report is set
DESCRIPTION
The zone name field in the damage report is updated with zone name.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetGrid
Update the damage report with a grid number
SYNOPSIS
damageSetGrid(grid)
PARAMETERS
grid A grid number.
PREREQUISITE
The current damage report is set
DESCRIPTION
The grid field in the damage report is updated with grid.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetCity
Update the damage report with a city name
SYNOPSIS
damageSetCity(city)
PARAMETERS
city A city name.
PREREQUISITE
The current damage report is set
DESCRIPTION
The city field in the damage report is updated with city.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetSection
Update the damage report with the section affected.
SYNOPSIS
damageSetSection(section)
PARAMETERS
section The section affected.
PREREQUISITE
The current damage report is set
DESCRIPTION
The section field in the damage report is updated with section.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetLocation
Update the damage report with the affected location
SYNOPSIS
damageSetLocation(location)
PARAMETERS
location The affected location.
PREREQUISITE
The current damage report is set
DESCRIPTION
The location field in the damage report is updated with location.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetPhase
Update the damage report with the phases affected
SYNOPSIS
damageSetPhase(phase)
PARAMETERS
phase The affected phases.
PREREQUISITE
The current damage report is set
DESCRIPTION
The phase field in the damage report is updated with phase.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetLoadAffected
Update the damage report with the affected load.
SYNOPSIS
damageSetLoadAffected(loadAffected)
PARAMETERS
loadAffected The load affected.
PREREQUISITE
The current damage report is set
DESCRIPTION
The load affected field in the damage report is updated with loadAffected.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetText1 - damageSetText5
NAME:
Update misc_textN in the damage report, where N is a number from 1 to 5.
SYNOPSIS
damageSetTextN(text)
PARAMETERS
text A value.
PREREQUISITE
The current damage report is set
DESCRIPTION
The misc_textN field in the damage report is updated with text.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetOption1 - damageSetOption5
Update misc_optionN field in the damage report, where N is number from 1 to 5.
SYNOPSIS
damageSetOptionN(text)
PARAMETERS
text A value.
PREREQUISITE
The current damage report is set
DESCRIPTION
The misc_optionN field in the damage report is updated with text.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetComment1
Update the damage report with a comment
SYNOPSIS
damageSetComment1(text)
PARAMETERS
text A text.
PREREQUISITE
The current damage report is set
DESCRIPTION
The comment1 field in the damage report is updated with text.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetComment2
NAME:
damageSetComment2 Update the damage report with a comment
SYNOPSIS
damageSetComment2(text)
PARAMETERS
text A text.
PREREQUISITE
The current damage report is set
DESCRIPTION
The comment2 field in the damage report is updated with text.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
damageSetType
Update the damage report with the number of affected items
SYNOPSIS
damageSetType(item, number, accessible)
PARAMETERS
item The type of item damaged.
number Number of item affected.
accessible Indicate whether the damage is accessible.
PREREQUISITE
The current damage report is set
DESCRIPTION
The field containing the number of affected items in the damage report is updated with number and the corresponding accessibility field is updated with accessible
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
saveDamageDetails
Save the damage report
SYNOPSIS
saveDamageDetails()
PARAMETERS
None.
PREREQUISITE
The current damage report is set
DESCRIPTION
Save the current damage report.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
Logging
logLocalError
Log an error message to the local log file
SYNOPSIS
logLocalError(text [, text] … )
PARAMETERS
text Text to include in the error message. Any number of parameters can be
supplied.
PREREQUISITE
None
DESCRIPTION
Concatenate all the parameters (no spaces are inserted between the parameters).
Invoke the logError API.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
EXAMPLE:
logLocalError("This is an ", @example, " of an ", &error, " message");
logFatalError
Log a fatal error message to the local log file and exit
SYNOPSIS
logFatalError(text [, text] … )
PARAMETERS
text Text to include in the error message. Any number of parameters can be
supplied.
PREREQUISITE
None
DESCRIPTION
Concatenate all the parameters (no spaces are inserted between the parameters).
Invoke the logFatal API.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
EXAMPLE:
logFatalError("This is an ", @example, " of a fatal ", &error, " message");
logDebug
Log a debug message
SYNOPSIS
logDebug(level, text)
PARAMETERS
level The minimum debug level at which to log the message. Zero means always.
The debug level of the adapter can be changed by sending it a debug high level
message.
text Text to include in the debug message. Any number of parameters can be
supplied
PREREQUISITE
None
DESCRIPTION
Invoke the debug API.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
EXAMPLE
logDebug(0, "This is an ", @example, " of a ", &debug, " message");
Event Manipulation
These functions read and modify events.
readIncidents
NAME:
readIncidents Populate the Incident Object for the current event
SYNOPSIS
readIncidents()
PARAMETERS
None.
PREREQUISITE
The current event is set.
DESCRIPTION
If the Incident Object for the current event has not been populated previously, and the current event has at least one incident associated with it, invoke the JMS::getCalls API for the current event.
RETURN VALUE
The number of incidents in the Incident Object, when successful.
The empty string, when unsuccessful.
API call fails.
DIAGNOSTICS
Error messages are output to the error log.
clearIncidents
Clear the Incident Object, freeing the memory it uses
SYNOPSIS
clearIncidents()
PARAMETERS
None.
PREREQUISITE
The current event is set.
DESCRIPTION
If the Incident Object for the current event has been populated previously, clear it.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
setCaseNoteInfo
Set the case notes for the current order
SYNOPSIS
setCaseNoteInfo(note)
PARAMETERS
note Text to be entered in the Case Notes.
PREREQUISITE
The current order is set.
DESCRIPTION
Invoke the JMS::setCaseNoteInfo API for all the events associated with the order.
RETURN VALUE
True, when successful.
False, when unsuccessful. API call fails.
DIAGNOSTICS
Error messages are output to the error log.
setOperatorComment
Set the operator comment for the current order
SYNOPSIS
setOperatorComment(comment, append)
PARAMETERS
comment Comment text.
append
• 0 - replace current comment
• 1 - append to the current comment
PREREQUISITE
The current order is set.
DESCRIPTION
Invokes the JMS::setOperatorComment API for all the events associated with the order.
RETURN VALUE
True, when successful.
False, when unsuccessful.
API call fails.
DIAGNOSTICS
Error messages are output to the error log.
getCaseNotesForEvent
Get the case notes for an event
SYNOPSIS
getCaseNotesForEvent(event)
PARAMETERS
event An event handle.
PREREQUISITE
None.
DESCRIPTION
Invoke the JMS::getCaseNotesForEvent API.
RETURN VALUE
The case notes for the event when successful.
The empty string when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
setEventInfo
setEventInfo Set event information for an order.
SYNOPSIS
setEventInfo(outagefield1, value1, [outagefield2, value2], ...)
PARAMETERS
outagefield1 The outage field to update/set.
value1 The value to set.
outagefield2 The outage field to update/set.
value2 The value to set.
PREREQUISITE
The database table 'OUTAGE_FIELD' must be defined and populated. It contains the valid outage fields that can be used in outagefield.
DESCRIPTION
Update outagefield[1,2…] with value[1,2…] for event. Multiple outagefields and values updates are supported. The JMS::setEventInfo(..) API is invoked for all events associated with the order.
RETURN VALUE
True, when successful.
False when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
setEventInfoAPI
setEventInfoAPI Set event information for arbitrary event.
SYNOPSIS
setEventInfoAPI(event, outagefield, value, user)
PARAMETERS
event An event handle.
outagefield The outage field to update/set.
value The value to set.
user The username.
PREREQUISITE
The database table 'OUTAGE_FIELD' must be defined and populated. It contains the valid
outage fields that can be used in outagefield.
DESCRIPTION
Update outagefield with value for the event. The JMS::setEventInfo(..) API is invoked for the event with the specified event handle.
RETURN VALUE
True, when successful.
False when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
completeEvent
NAME:
completeEvent Complete all events associated with the current order
SYNOPSIS
completeEvent()
PARAMETERS
None.
PREREQUISITE
The current order is set.
DESCRIPTION
Restore and complete the event(s) associated with the current order.
Because the state of the event changes when the API's used by this function are called, the Event Object is automatically reloaded after the call. This means that the Incident Object will not be populated. If the Incident Object is required, it must be populated using readIncident().
RETURN VALUE
True, when successful.
False, when unsuccessful.
Could not restore event.
DIAGNOSTICS
Error messages are output to the error log.
closeOutEvent
NAME:
closeOutEvent Close out all events associated with the current order using specified applied rule
SYNOPSIS
closeOutEvent(user, reason, appliedRule, restoreTime)
PARAMETERS
user username
reason reason for closing the event
appliedRule applied rule value to use
restoreTime event restoration time
PREREQUISITE
The current order is set.
DESCRIPTION
Close out the event(s) associated with the current order using specified applied rule value.
If applied rule value is 26 (OUTAGE_PND_COMPLETE) and configuration parameter $G.config_AllowCloseOutEventCancel is set 'Y' then the event(s) will be canceled.
Because the state of the event changes when the API's used by this function are called, the Event Object is automatically reloaded after the call. This means that the Incident Object will not be populated. If the Incident Object is required, it must be populated using readIncident().
RETURN VALUE
True, when successful.
False, when unsuccessful. Could not close event.
DIAGNOSTICS
Error messages are output to the error log.
setGenericField
NAME:
setGenericField Update event information for the current order
SYNOPSIS
setGenericField(field, value, user)
PARAMETERS
field A field to update.
value A value.
user Who initiated the update.
PREREQUISITE
The current order is set.
DESCRIPTION
For all events associated with the current order, update field with value, indicating that user initiated the update.
The JMS API 'setGenericField()' is invoked.
RETURN VALUE
True, when successful.
False, when the API call fails.
DIAGNOSTICS
Error messages are output to the error log.
readGenericField
NAME:
readGenericField Read information for the current event
SYNOPSIS
readGenericField(field)
PARAMETERS
field A field to read.
PREREQUISITE
The current event is set. The value of field is a valid generic field name.
DESCRIPTION
Read the value of field for the current event.
The JMS API 'getGenericField()' is invoked.
RETURN VALUE
The value of field.
DIAGNOSTICS
Error messages are output to the error log.
ert
NAME:
ert Set the estimated restoration time for the current order
SYNOPSIS
ert(time, ert_source, crew_name)
PARAMETERS
time The estimated restoration time in internal format.
est_source The source code for the estimated restoration time. Allowed values: C, U,
'a' through 'z' with the exception of 'm.' This parameter is optional. If not
provided value 'C' is used.
crew_name The name of the crew which is updating the estimated restoration time.
This parameter is optional. If not provided the value specified in the
"$G.config_Username" configuration parameter is used.
PREREQUISITE
The current order is set.
DESCRIPTION
Call the JMS:: setEstRestTime() API for all events associated with the current order.
RETURN VALUE
True, when successful.
False, when the API call fails.
DIAGNOSTICS
Error messages are output to the error log.
requestRowAction
NAME:
requestRowAction Press a button for the current event
SYNOPSIS
requestRowAction(table, button)
PARAMETERS
table The name of the table (work_agenda is most common).
button The name of the button to press.
PREREQUISITE
The current event is set.
DESCRIPTION
Call the JMS::requestRowAction API for the current event.
RETURN VALUE
True, when the API call succeeds.
False, when the API call fails.
DIAGNOSTICS
Error messages are output to the error log.
requestRowActionAll
NAME:
requestRowActionAll Press a button for the current order
SYNOPSIS
requestRowActionAll(table, button)
PARAMETERS
table The name of the table (work_agenda is most common).
button The name of the button to press.
PREREQUISITE
The current order is set.
DESCRIPTION
Call the JMS::requestRowAction API for all events associated with the current order.
RETURN VALUE
True, when the API call succeeds.
False, when the API call fails.
DIAGNOSTICS
Error messages are output to the error log.
eventIsActive
NAME:
eventIsActive Check that the current order has at least one active event
SYNOPSIS
eventIsActive()
PARAMETERS
None.
PREREQUISITE
The current order is set.
DESCRIPTION
Determine if the order has at least one active event.
RETURN VALUE
True, when active.
False, otherwise.
DIAGNOSTICS
Error messages are output to the error log.
confirmDeviceOutage
NAME:
confirmDeviceOutage Confirm a device outage for all events associated with the current order.
SYNOPSIS
confirmDeviceOutage(phases)
PARAMETERS
phases The phases that are out
PREREQUISITE
The current order is set.
DESCRIPTION
For all events associated with the current order, confirm that it is a real device outage by opening the phases on the device, using the DDS::operateState() API.
Because the state of the event changes when these API's are called, the Event Object is automatically reloaded after the call. This means that the Incident Object will not be populated. If the Incident Object is required, it must be populated using readIncident().
RETURN VALUE
True, when confirmation is successful.
False, if an API call fails. This will occur if the device has tags which prevent opening the device.
DIAGNOSTICS
Error messages are output to the error log.
confirmServiceOutage
NAME:
confirmServiceOutage Confirm a service outage for all events associated with the current order.
SYNOPSIS
confirmServiceOutage()
PARAMETERS
None.
PREREQUISITE
The current order is set.
DESCRIPTION
For all events associated with the current order, confirm that the customers described in the incidents read for the event, are individually out using the JMS::processIndivServUpdate() API. Note that no outages are created for customers who are not attached to the device (for example a fuzzy call).
Because the state of the event changes when this API is called, the Event Object is automatically reloaded after the call. This means that the Incident Object will not be populated. If the Incident Object is required, it must be populated using readIncident().
Because this function can create events, lockForEventCreation() should be called if the new events should not have orders created for them. If a pseudo relationship is to be created from the resulting events, it is recommended that createPseudoRelationFromConfirmServiceOutage() as it does not require the use of lockForEventCreation().
SEE ALSO:
createPseudoRelationFromConfirmServiceOutage(), section
createPseudoRelationFromConfirmServiceOutage, and lockForEventCreation() section
lockForEventCreation.
RETURN VALUE
The number of customers confirmed, when confirmation is successful.
False, otherwise.
DIAGNOSTICS
Error messages are output to the error log.
lockForEventCreation
NAME:
lockForEventCreation Prevent the processing of new events until the current document is fully processed.
SYNOPSIS
lockForEventCreation()
PARAMETERS
None.
PREREQUISITE
None.
DESCRIPTION
Prevent new events from being processed until the current document finishes processing. This is required if a call can cause events, e.g., confirmServiceOutage(), and the new events need to be processed, e.g., by createPseudoRelation(). If possible avoid using this function, because it prevents other threads from processing any changes to events.
SEE ALSO:
confirmServiceOutage(), section
confirmServiceOutage, and createPseudoRelation(), section
createPseudoRelation.
RETURN VALUE
The empty string.
False, otherwise.
DIAGNOSTICS
None.
restoreOutage
NAME:
restoreOutage Restore all events for the current order
SYNOPSIS
restoreOutage()
PARAMETERS
None.
PREREQUISITE
The current order is set.
DESCRIPTION
For all events associated with the current order restore the event. If the event is a device outage restore it by closing all of the device's phases using the DDS::operateState() API. If the event is a service outage, restore it using the JMS::processIndivServUpdate() API.
Because the state of the event changes when these API's are called, the Event Object is automatically reloaded after the call. This means that the Incident Object will not be populated. If the Incident Object is required, it must be populated using readIncident().
RETURN VALUE
True, when restoration is successful.
False, if an API fails. This will occur in a device outage if the device has tags which prevent closing the device. This may occur in a service outage if the event has not been acknowledged.
DIAGNOSTICS
Error messages are output to the error log.
setRestoredTime
NAME:
setRestoredTime Updates restoration time for the current order
SYNOPSIS
setRestoredTime(restoreTime)
PARAMETERS
restoreTime Event restoration time.
PREREQUISITE
The current order is set.
DESCRIPTION
Updates restoration time for all event associated with the current order. The events must already be restored.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
picklistCompLog
NAME:
picklistCompLog Update the database table picklist_completion_log for all the events associated with the current order.
SYNOPSIS
picklistCompLog(who, reason)
PARAMETERS
who Who performed the action.
reason What occurred
PREREQUISITE
Current order is set.
DESCRIPTION
For all events associated with the current order, create an entry in the database table 'picklist_completion_log' containing who and reason.
RETURN VALUE
True, when successful.
False, otherwise.
DIAGNOSTICS
Error messages are output to the error log.
picklistInfoUpdTr
NAME:
picklistInfoUpdTr Update the database table picklist_info_upd_tr for the current order.
SYNOPSIS
picklistInfoUpdTr(field1, value1, [field2, value2], ..)
PARAMETERS
field[1,2,..] Fields to update
value[1,2,..] Assignment Values
PREREQUISITE
Current order is set.
DESCRIPTION
For all events associated with the current order, update the fields with values in the database table 'picklist_info_upd_tr'.
RETURN VALUE
Empty string.
DIAGNOSTICS
Error messages are output to the error log.
picklistInfoEqFail
NAME:
picklistInfoEqFail Update the database table picklist_info_eq_fail for the current order.
SYNOPSIS
picklistInfoEqFail(field1, value1, [field2, value2], ..)
PARAMETERS
field[1,2,..] Fields to update.
value[1,2,..] Assignment values.
PREREQUISITE
Current order is set.
DESCRIPTION
For all events associated with the current order, update the fields with values in the database table
'picklist_info_eq_fail'.
RETURN VALUE
Empty string.
DIAGNOSTICS
Error messages are output to the error log.
updateOutageTimes
NAME:
updateOutageTimes Update restoration time for the events associated with the current order.
SYNOPSIS
updateOutageTimes(restoreTime)
PARAMETERS
restoreTime Restoration time.
PREREQUISITE
Current order is set.
DESCRIPTION
For all events associated with the current order, update the outage restoration time. The events must already be restored.
RETURN VALUE
The return value of the JMS::updateOutageTimes API.
DIAGNOSTICS
Error messages are output to the error log.
Relation Functions
These functions manipulate dml and aggregate relationships.
Where these functions take a type parameter, it must be one of: NESTED_OUTAGE, MOMENTARY_OUTAGE, PARTIAL_RESTORATION, and RELATED_OUTAGE. (PSEUDO_ NESTED_OUTAGE, MOMENTARY_OUTAGE, PARTIAL_RESTORATION, and RELATED_OUTAGE are valid, but have the same effect as their non-pseudo counterparts).
findRelation
NAME:
findRelation Find a dml relation by matching the contents of an relation object field. If found, set the current relation object to the relation found.
SYNOPSIS
findRelation(type, fieldname, value)
PARAMETERS
type A relationship type.
fieldname A field name
value A value
PREREQUISITE
The type parameter is valid.
If the current order is set, the current order must be in the relation. (This can be guaranteed by not calling findOrder, or by finding the relation by order's key event using findRelation(event, $O.event).)
DESCRIPTION
Find the relation with a type of type whose fieldname has a value of value.
RETURN VALUE
True, when successful.
False, otherwise.
DIAGNOSTICS
Error messages are output to the error log.
createPseudoRelation
NAME:
createPseudoRelation Create a pseudo (non-Oracle Utilities Network Management System) relationship.
SYNOPSIS
createPseudoRelation(type)
PARAMETERS
type A relationship type.
PREREQUISITE
The current order is set
The type parameter is valid.
The relationship type must have been configured for aggregate processing (this may be changed in a future release).
DESCRIPTION
Create a pseudo relationship of type among all outage events whose device is that of the current order's active event.
RETURN VALUE
True, when successful.
False, when unsuccessful.
No events exist on device.
The order's event is already in another relation.
All the other events on the device are in another relation.
DIAGNOSTICS
Error messages are output to the error log.
createPseudoRelationFromConfirmServiceOutage
NAME:
createPseudoRelationFromConfirmServiceOutage Create a pseudo (non-Oracle Utilities Network Management System) relationship from the results of the confirmation of a service outage.
SYNOPSIS
createPseudoRelationFromConfirmServiceOutage(type)
PARAMETERS
type A relationship type.
PREREQUISITE
See confirmServiceOutage, section
confirmServiceOutage and createPseudoRelation, section
createPseudoRelation.
DESCRIPTION
Confirm a service outage as described in confirmServiceOutage, section
confirmServiceOutage.
Create a pseudo relationship of
type as described in createPseudoRelation, section
createPseudoRelation.
This combined function is recommended rather than calling confirmServiceOutage and then calling createPseudoRelation because:
There is no need to call lockForEventCreation()
If this call is in progress when the adapter exits, it will be completed fully when the adapter restarts.
RETURN VALUE
The number of customers confirmed, when successful.
False, when unsuccessful.
No events exist on device.
The order's event is already in another relation.
All the other events on the device are in another relation.
DIAGNOSTICS
Error messages are output to the error log.
triggerRelationChanged
NAME:
triggerRelationChanged Trigger all output documents with a RelationChanged trigger.
SYNOPSIS
triggerRelationChanged(relation)
PARAMETERS
relation The relation's handle. (If the relation has been found, $R.relation gives this
value).
PREREQUISITE
There is at least one output document with a RelationChanged trigger.
DESCRIPTION
For all events in the relation, trigger all output documents with a RelationChanged trigger, with the event's handle as the trigger argument.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
deleteRelation
NAME:
deleteRelation Delete the current relation.
SYNOPSIS
deleteRelation()
PARAMETERS
None.
PREREQUISITE
The current relation is set.
DESCRIPTION
Delete the current relation. After the deletion, there is no current relation.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
Miscellaneous API Functions
classTable
NAME:
classTable Return the class table for a class.
SYNOPSIS
classTable(class)
PARAMETERS
class The class number
PREREQUISITE
The class parameter must be an integer.
DESCRIPTION
Call the ODS::getTable() API. If the table does not exist an empty string is returned.
RETURN VALUE
The table name, when successful.
The empty string when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
getClassDesc
NAME:
getClassDesc Returns a textual description of the Class.
SYNOPSIS
getClasDesc(class)
PARAMETERS
class The class number
PREREQUISITE
The class parameter must be an integer.
DESCRIPTION
Call the ODS::getClassDesc() API. If the class does not exist an empty string is returned.
RETURN VALUE
The textual description, when successful.
The empty string when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
getCustomersForTransformer
NAME:
getCustomersForTransformer Returns list of customer information records for a transformer.
SYNOPSIS
getCustomersForTransformer(xfm)
PARAMETERS
xfm Transformer device alias.
PREREQUISITE
None
DESCRIPTION
Reads ADDRESS, METER_ID, and DEVICE_ID columns from the CES_CUSTOMERS table for the specified transformer.
RETURN VALUE
A string that contains newline-separated list of customer information records for the specified transformer. Each record contains space-separated address, meter id, and device alias values.
DIAGNOSTICS
Error messages are output to the error log.
getTransformerForCustomer
NAME:
getTransformerForCustomer Returns list of customer information records for a customer address.
SYNOPSIS
getTransformerForCustomer(addr)
PARAMETERS
addr Customer address.
PREREQUISITE
None
DESCRIPTION
Reads ADDRESS, METER_ID, and DEVICE_ID columns from the CES_CUSTOMERS table for the specified customer address.
RETURN VALUE
A string that contains newline-separated list of customer information records for the specified customer address. Each record contains space-separated address, meter id, and device alias values.
DIAGNOSTICS
Error messages are output to the error log.
isCls
NAME:
isCls Check if a class is one of classes in a list.
SYNOPSIS
isCls(class, className1, className2, …)
PARAMETERS
class A class number.
className1, className2, … A list of class names.
PREREQUISITE
None
DESCRIPTION
Read and cache the class numbers for all the className parameters, using the ODS::getClassIndex API.
If class is one of the class numbers, return true, false otherwise.
RETURN VALUE
True, when class is in the list.
False, when class is not in the list.
DIAGNOSTICS
Error messages are output to the error log.
setAlarm
NAME:
setAlarm Send an alarm to the WorkAgenda
SYNOPSIS
setAlarm(deviceHandle, alarmMsg)
PARAMETERS
deviceHandle A device handle.
alarmMsg A alarm message.
PREREQUISITE
None
DESCRIPTION
Send an alarmMsg regarding deviceHandle, using the DDS::sendAlarm API.
RETURN VALUE
None.
DIAGNOSTICS
Error messages are output to the error log.
getGuid
NAME:
getGuid Return a globally unique id.
SYNOPSIS
getGuid()
PARAMETERS
None
PREREQUISITE
None
DESCRIPTION
Invokes GatewayUtil::CreateGuid() API.
RETURN VALUE
The GUID, when successful.
The empty string when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
interfaceUp
NAME:
interfaceUp Register the state of the interface
SYNOPSIS
interfaceUp()
PARAMETERS
None.
PREREQUISITE
None
DESCRIPTION
Register that the interface is currently up. Invoke SMS::registerCallback(), and SMS::registerInterfaceFailed() API.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
interfaceDown
NAME:
interfaceDown Register the state of the interface
SYNOPSIS
interfaceDown()
PARAMETERS
None.
PREREQUISITE
None
DESCRIPTION
Register that the interface is currently down. Invoke SMS::registerCallback(), and SMS::registerInterfaceFailed() API.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
interfaceUpMessage
NAME:
interfaceUpMessage Register the state of the interface
SYNOPSIS
interfaceUpMessage(message)
PARAMETERS
message message to appear in the System Alarms list
PREREQUISITE
None
DESCRIPTION
Register that the interface is currently up. Provided message with appear in the System Alarms list.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
interfaceDownMessage
NAME:
interfaceDownMessage Register the state of the interface
SYNOPSIS
interfaceDownMessage(message)
PARAMETERS
message message to appear in the System Alarms list
PREREQUISITE
None
DESCRIPTION
Register that the interface is currently down. Provided message with appear in the System Alarms list.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
sql
NAME:
sql Execute a non-select SQL statement
SYNOPSIS
sql(sqlStatement)
PARAMETERS
sqlStatement A non-select SQL statement.
PREREQUISITE
None
DESCRIPTION
Execute sqlStatement using the DBS::sql() API.
RETURN VALUE
True, when successful.
False, when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
EXAMPLE:
sql("delete from damage_report where event_cls=" + $E.outageHdl.cls +
" and event_idx=" + $E.outageHdl.idx);
query
NAME:
query Execute SQL query
SYNOPSIS
query(sqlStatement)
PARAMETERS
sqlStatement A select SQL statement.
PREREQUISITE
None
DESCRIPTION
Execute sqlStatement using the DBS::query() API and return first column of the first returned row.
RETURN VALUE
Value of the first column of the first returned row.
DIAGNOSTICS
Error messages are output to the error log.
EXAMPLE:
query("SELECT SYSDATE FROM dual");
Non API Functions
This set of functions does not use the Oracle Utilities Network Management System API.
isSet
NAME:
isSet Check if a parameter has been set.
SYNOPSIS
isSet(param)
PARAMETERS
param The parameter to check.
PREREQUISITE
None
DESCRIPTION
Check if the param has been set.
RETURN VALUE
True, if param has been set.
False, if not.
DIAGNOSTICS
None.
length
NAME:
length Return the number of characters in a string.
SYNOPSIS
length(string)
PARAMETERS
string A string value
PREREQUISITE
None
DESCRIPTION
Determine the length of string.
RETURN VALUE
The length of string.
DIAGNOSTICS
None.
substring
NAME:
substring Return a sub-string of a value
SYNOPSIS
substring(string, start, length)
PARAMETERS
string A string value
start The starting position of the subset in string
length The length of the sub-string to return
PREREQUISITE
None
DESCRIPTION
Return a subset of string whose size equals length, and starts at position start in string.
If length is less than 1, return the empty string.
If start is zero or positive, it is an offset from the start of string.
If start is negative, it is an offset from the end of string.
If there are less than length characters in string starting at start, return all the characters in string starting at start.
Otherwise return length characters from string starting at start.
RETURN VALUE
The sub-string
DIAGNOSTICS
None.
stringbefore
NAME:
stringbefore Return a sub-string of a string value
SYNOPSIS
stringbefore(string, stop)
PARAMETERS
string A string value
stop A string to stop at.
PREREQUISITE
None
DESCRIPTION
Search string for stop and return all characters before stop. If stop does not exist within string return string
RETURN VALUE
The sub-string.
DIAGNOSTICS
None.
stringafter
NAME:
stringafter Return a sub-string of a string value
SYNOPSIS
stringafter(string, start)
PARAMETERS
string A string value
start Characters to start after.
PRE-REQUISITE:
None
DESCRIPTION
Search string for any character in start and return all characters after that point. If start does not exist within string return string.
RETURN VALUE
The sub-string.
DIAGNOSTICS
None.
isDigits
NAME:
isDigits Check if the string is made up of digits only
SYNOPSIS
isDigits(string)
PARAMETERS
string A string value
PREREQUISITE
None
DESCRIPTION
Check if string is made up of purely numeric values (e.g., 0 to 9)
RETURN VALUE
True, if string is all digits.
False, otherwise.
DIAGNOSTICS
Error messages are output to the error log.
readDigits
NAME:
readDigits Read the first continuous block of digits found in the input string.
SYNOPSIS
readDigits(string)
PARAMETERS
string A string value
PREREQUISITE
None
DESCRIPTION
Read the first continuous block of digits found in the input string.
RETURN VALUE
First continuous block of digits found in the input string. Empty string if none are found.
DIAGNOSTICS
None.
stringInString
NAME:
stringInString Check to see whether a sub-string exists in another string
SYNOPSIS
stringInString(string1, string2)
PARAMETERS
string1 A string value
string2 A string value
PREREQUISITE
None
DESCRIPTION
Search string2 for string1.
RETURN VALUE
True, if string1 is found
False, otherwise.
DIAGNOSTICS
None.
trim
NAME:
trim Removes leading and trailing whitespace characters
SYNOPSIS
trim(string)
PARAMETERS
string A string value
PREREQUISITE
None
DESCRIPTION
Removes leading and trailing whitespace characters from string.
RETURN VALUE
String with leading and trailing whitespace characters removed.
DIAGNOSTICS
None.
trimLeft
NAME:
trimLeft Removes leading whitespace characters
SYNOPSIS
trimLeft(string)
PARAMETERS
string A string value
PREREQUISITE
None
DESCRIPTION
Removes leading whitespace characters from string.
RETURN VALUE
String with leading whitespace characters removed.
DIAGNOSTICS
None.
trimRight
NAME:
trimRight Removes trailing whitespace characters
SYNOPSIS
trimRight(string)
PARAMETERS
string A string value
PREREQUISITE
None
DESCRIPTION
Removes trailing whitespace characters from string.
RETURN VALUE
String with trailing whitespace characters removed.
DIAGNOSTICS
None.
removeDelim
NAME:
removeDelim Return a substring without the contents contained within the
delimiters, including the delimiters.
SYNOPSIS
removeDelim(string, start, end)
PARAMETERS
string A string value
start A starting delimiter
end A end delimiter
PREREQUISITE
None
DESCRIPTION
Search string for start, remove all characters found between and including start and end. If start is not found return string. If end is not found, return all characters after and including start.
RETURN VALUE
The sub-string value.
DIAGNOSTICS
Error messages are output to the error log.
diffs
NAME:
diffs Returns string containing tokens present in string1 but not in string2.
SYNOPSIS
diffs(string1, string2, delim)
PARAMETERS
string1 A string of tokens
string2 A string of tokens
delim A delimiter
PREREQUISITE
None
DESCRIPTION
Splits both strings into lists of token using the delimiter. Build a new string containing only the token from string1 which are not present in string2.
RETURN VALUE
String containing tokens present in string1 but not in string2. Tokens are separated by the delimiter.
DIAGNOSTICS
None.
decodeDateTime
NAME:
decodeDateTime Translate a formatted time string into internal format.
SYNOPSIS
decodeDateTime(time)
PARAMETERS
time A time in the format yyyy-mm-ddThh:mm:ss
PREREQUISITE
None
DESCRIPTION
Return time in internal time format. If time is not in the correct format, return the empty string.
RETURN VALUE
The time in internal format, when successful.
False, when unsuccessful.
Format of time is invalid
DIAGNOSTICS
Error messages are output to the error log.
decodeDateShift
NAME:
decodeDateShift Translate a formatted time string into internal format and shift it back by the specified number of hours.
SYNOPSIS
decodeDateShift(time, shift)
PARAMETERS
time A time in the format yyyy-mm-ddThh:mm:ss
shift A number of hours by which to shift the input time backward.
PREREQUISITE
None
DESCRIPTION
Returns the input time shifted backward by the specified number of hours in internal time format. If time is not in the correct format, return the empty string.
RETURN VALUE
The time in internal format, when successful.
False, when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
formatDateTime
NAME:
formatDateTime Translate a time in internal format into a formatted time string.
SYNOPSIS
formatDateTime(time)
PARAMETERS
time A time in internal format.
PREREQUISITE
None
DESCRIPTION
Format time to yyyy-mm-ddThh:mm:ss. If time is not in internal format, return the empty string.
RETURN VALUE
The formatted time, when successful.
False., when unsuccessful
Invalid time supplied.
DIAGNOSTICS
Error messages are output to the error log.
formatDateShift
NAME:
formatDateShift Translate a time in internal format into a formatted time string and shift it forward by specified number of hours.
SYNOPSIS
formatDateShift(time, shift)
PARAMETERS
time A time in internal format.
shift A number of hours by which to shift the input time forward.
PREREQUISITE
None
DESCRIPTION
Shift time forward by the specified number of hours and format it as yyyy-mm-ddThh:mm:ss. If time is not in internal format, return the empty string.
RETURN VALUE
The formatted time, when successful.
False., when unsuccessful
DIAGNOSTICS
Error messages are output to the error log.
reformatDateTime
NAME:
reformatDateTime Translate year, month, day, and time into a formatted time string.
SYNOPSIS
reformatDateTime(year, month, day, time)
PARAMETERS
year Year in yyyy format.
month Month in mm format.
day Day in dd format.
time Time in hh:mm format
PREREQUISITE
None
DESCRIPTION
Format time to yyyy-mm-ddThh:mm:00.
RETURN VALUE
The formatted time.
DIAGNOSTICS
None.
formatDTNow
NAME:
formatDTNow Format the current system time
SYNOPSIS
formatDTNow()
PARAMETERS
None.
PREREQUISITE
None
DESCRIPTION
Return the results of formatDateTime(time()).
RETURN VALUE
The formatted time.
DIAGNOSTICS
None.
time
NAME:
time Return the current system time
SYNOPSIS
time()
PARAMETERS
None
PREREQUISITE
None
DESCRIPTION
Return the current system time
RETURN VALUE
The current time, in internal format.
DIAGNOSTICS
None.
addMinutesToTime
NAME:
addMinutesToTime Return the current system time with specified number of minutes
added to it
SYNOPSIS
addMinutesToTime(minutes)
PARAMETERS
minutes The number of minutes to add to the current time. This parameter
can be negative.
PREREQUISITE
None
DESCRIPTION
Returns the current system time with specified number of minutes added to it.
RETURN VALUE
The resulted time, in internal format.
DIAGNOSTICS
None.
pause
NAME:
pause Pause evaluation for a period of time
SYNOPSIS
pause(seconds)
PARAMETERS
seconds The number of seconds to pause
PREREQUISITE
None
DESCRIPTION
Pause for seconds.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
dmlWait
NAME:
dmlWait Pause evaluation for a period of time
SYNOPSIS
dmlWait(seconds)
PARAMETERS
seconds The number of seconds to pause
PREREQUISITE
None
DESCRIPTION
Execute Isis-aware pause for the specified number of seconds.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
isIn
NAME:
isIn Check if a value exists in a list
SYNOPSIS
isIn(value, item1, item2, item3, …)
PARAMETERS
value A value
item1, item2, item3, … A list of values.
PREREQUISITE
None
DESCRIPTION
Check item1, item2, item3, … for value.
RETURN VALUE
True, when value is found.
False, when not found.
DIAGNOSTICS
None.
selectValue
NAME:
selectValue Select a value based on a input string.
SYNOPSIS
selectValue(string, default, match1, value1, [match2, value2], [match3, value3], …)
PARAMETERS
string A value to match
default A default value
match[123] A list of values to compare to
value[123] The values to return if a match is found
PREREQUISITES:
None
DESCRIPTION
Search match for string and return the corresponding value. If string is not found return default.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
NOTES:
For large lists, the use of a code mapping table would be more appropriate.
EXAMPLE:
@exp = selectValue(3, None, 1, "hello", 2, "goodbye", 3, "later")
Therefore, string = 3, default = None, match = 1, 2, 3 value = hello, goodbye, later
In this example, @exp = later.
triggerOutputDoc
NAME:
triggerOutputDoc Trigger an output document
SYNOPSIS
triggerOutputDoc(doc, trig, [argument1, argument2, …])
PARAMETERS
doc An output document
trig The name of the trigger to fire.
argument Argument required to triggered the output document.
PREREQUISITE
A document named doc must exist.
There must be an OnRequest trigger named trig in doc.
The number of arguments must match the number of arguments expected by trig.DESCRIPTION
Validate doc and argument. Queue doc for processing.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
sortIncidents
NAME:
sortIncidents Sort the incidents in the current event
SYNOPSIS
sortIncidents(field1, sort order1, [field2, sort order2, …])
PARAMETERS
field An incident object field
sort order The order to sort in, 'asc' meaning ascending or 'desc' meaning descending
(this parameter is not case sensitive).
PREREQUISITE
The current event is set.
The
fields parameters must be valid incident fields See
Incident Object Fields, below for the available incident fields.
The order parameters must be valid. If the last order parameter is omitted it defaults to 'asc'
DESCRIPTION
Sort the incidents in the current event. When two incidents are compared, the specified fields are compared in the order they appear in the parameter list. If they differ, the incident with the lower value comes first in the list if it has an ascending order, otherwise the incident with the higher value comes first. If the two fields are equal, the sort order depends on the next field in the parameter list. If all fields are equal, the order of the two incidents is undetermined. To force a consistent order, it is recommended that the last field be the 'getCondHdl' field which always differ (the newer incident having the larger value).
All comparisons are based on the internal types of the fields, in order to give the expected results. Character data is sorted in lexical order, the case being significant.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
highPriTCCategoriesFromClues
NAME:
highPriTCCategoriesFromClues Return the highest priority trouble code categories from all of the supplied clues.
SYNOPSIS
highPriTCCategoriesFromClues(clues)
PARAMETERS
clues The clues to decode
PREREQUISITE
The MDS_HIGH_PRI_CAT table must exist in the database.
DESCRIPTION
If the MDS_HIGH_PRI_CAT table has not been read, read and cache its contents. This table supplies the priority order for each group in the trouble code.
Decode each clue into it's group and numeric value
Find the highest priority for each group in all the clues, and assemble these into a composite trouble code.
RETURN VALUE
The composite trouble code.
DIAGNOSTICS
Error messages are output to the error log.
highPriTCCategoriesFromIncidents
NAME:
highPriTCCategoriesFromIncidents Return the highest priority trouble code categories from all of the incidents for the current event.
SYNOPSIS
highPriTCCategoriesFromIncidents()
PARAMETERS
None.
PREREQUISITE
Current event is set.
The MDS_HIGH_PRI_CAT table must exist in the database.
DESCRIPTION
If the MDS_HIGH_PRI_CAT table has not been read, read and cache its contents. This table supplies the priority order for each group in the trouble code.
Find the highest priority for each group in all the incidents for the current event, and assemble these into a composite trouble code.
RETURN VALUE
The composite trouble code.
DIAGNOSTICS
Error messages are output to the error log.
loadTroubleCodes
NAME:
loadTroubleCodes Cache the trouble codes and their equivalent textual descriptions.
SYNOPSIS
loadTroubleCodes()
PARAMETERS
None.
PREREQUISITE
The table SRS_TROUBLE_CODES exists in the database.
DESCRIPTION
The trouble codes are cached in-groups using the 'group_order' column. For each group the 'code_num' column and the 'short_desc' column are cached. The 'code_num' is used as the trouble codes' reference code and the 'short_desc' is used as the trouble codes' textual description.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
formatClues
NAME:
formatClues Convert a trouble code into a textual description
SYNOPSIS
formatClues(trCode)
PARAMETERS
trCode A trouble code
PREREQUISITE
The table SRS_TROUBLE_CODES exists in the database.
DESCRIPTION
If the SRS_TROUBLE_CODES table has not been read, read and cache its contents by calling loadTroubleCodes().
Convert each digit in trCode to its equivalent textual description. Concatenate the descriptions.
RETURN VALUE
The textual description.
DIAGNOSTICS
None.
phaseStr
NAME:
phaseStr Convert a set of phases in internal bitmap format to a textual representation.
SYNOPSIS
phaseStr(phases)
PARAMETERS
phases The phases in internal bitmap format.
PREREQUISITE
None
DESCRIPTION
Convert the phase bits into 'ABC' format. If the bit for a phase is not set, do not include its letter.
RETURN VALUE
The textual representation.
DIAGNOSTICS
None.
phaseInt
NAME:
phaseInt Convert a set of phases in a textual representation to an internal bitmap format.
SYNOPSIS
phaseInt(phases)
PARAMETERS
phases A textual representation of the phases.
PREREQUISITE
None
DESCRIPTION
Convert the textual phase in 'ABC' format to its internal bitmap format.
RETURN VALUE
The internal bitmap format.
DIAGNOSTICS
None.
setTimeout
NAME:
setTimeout Set a time out to call a function
SYNOPSIS
setTimeout(name, wait, function)
PARAMETERS
name The name of the time out.
wait The time to wait, in seconds.
function The function to call at when the time expires.
PREREQUISITE
The wait parameter must be an integer greater than zero.
The function parameter must be a function call.
DESCRIPTION
If there is an un-expired timeout with the same name, do nothing.
Evaluate all the parameters of the function, if any.
Start a timeout with the specified name.
Call the function when the timeout expires (unless cancelled by cancelTimeout()).
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
cancelTimeout
NAME:
cancelTimeout Cancel a timeout.
SYNOPSIS
cancelTimeout(name)
PARAMETERS
name The name of the timeout to cancel.
PREREQUISITE
None
DESCRIPTION
If there is a timeout with the specified name, cancel it, preventing the timeout's function from being called, otherwise, do nothing.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
createOrder
NAME:
createOrder Create an order.
SYNOPSIS
createOrder()
PARAMETERS
None.
PREREQUISITE
The current event is set(usually due to the arrival of an SRSoutput message).
The current event must not be associated with another order. This can be determined by a call to findOrder(event, $E.outageHdl).
If the current relation is set, the current event must be in the relation. (This can be guaranteed by not calling findRelation, or by finding the relation by relation's key event using findRelation(event, $E.outageHdl.)
DESCRIPTION
Create the order's row in the MDS_ORDER table, and associate the event with the order.
Populate internal data structures for the order.
Set the current order to the order created.
RETURN VALUE
True if successful.
False if unsuccessful (current event already associated with another order).
DIAGNOSTICS
Error messages are output to the error log.
findOrder
NAME:
findOrder Find an order by matching the contents of an order object field. If found, set the current order object to the order found.
SYNOPSIS
findOrder(field, value)
PARAMETERS
field An order object field name.
value The value to match
PREREQUISITE
The field parameter must be a valid order field name.
If the current relation is set, the order must be in the relation. (This can be guaranteed by not calling findRelation, or by finding the order from the relation's key event, using findOrder(event, $R.event).)
DESCRIPTION
Search for an order with a field whose value is value.
If found, set the current order object to the order that was found and return true.
If none is found, return false.
haveOrder
NAME:
haveOrder Determine if there is an order matching the contents of an order object field, without entering any mutexes.
SYNOPSIS
haveOrder(field, value)
PARAMETERS
field An order object field name.
value The value to match
PREREQUISITE
The field parameter must be a valid order field name.
DESCRIPTION
Search for an order with a field whose value is value.
RETURN VALUE
True, when successful.
False, when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
completeOrder
NAME:
completeOrder Complete the current order, making it no longer active.
SYNOPSIS
completeOrder(text)
PARAMETERS
text A description of the why the order is complete. For example, the order could
have been cancelled or completed by the crew.
PREREQUISITE
The current order is set.
DESCRIPTION
Complete the order by setting its 'active' column to 'N', its 'when_completed' column to the current time, and setting its 'comp_reason' column to text in MDS_ORDER table. Clear all data structures relating to the order.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
haveEventOrder
NAME:
haveEventOrder Determine whether these is an order for an event.
SYNOPSIS
haveEventOrder(event)
PARAMETERS
event The event's handle.
PREREQUISITE
None.
DESCRIPTION
Determine whether there is an order for the event handle is event.
RETURN VALUE
True, if the event has an order.
False, if the event does not have an order.
DIAGNOSTICS
None.
findEventObject
NAME:
findEventObject Find the External Event Object for an event.
SYNOPSIS
findEventObject(event)
PARAMETERS
event The event's handle.
PREREQUISITE
None.
DESCRIPTION
Find the event object whose handle is event. If successful, make it the current event.
RETURN VALUE
True, when successful.
False, when unsuccessful.
DIAGNOSTICS
Error messages are output to the error log.
setDocValue
NAME:
setDocValue Change the value of an element, attribute or variable in an active document
SYNOPSIS
setDocValue(object, doc, name, value)
PARAMETERS
object The object identifier character for the object that holds the active document.
Currently only 'O', the order object, is available.
doc The name of the document
name The alternate name of the entity whose value is to be set.
value The value to set the entity to.
PREREQUISITE
object must be a valid object identifier, and it must be a current object (for example, use findOrder()).
doc must be a associated with the object.
name must be the alternate name of an entity in doc.
DESCRIPTION
Find the active document doc in the current object.
In the document set the entity named name to value.
RETURN VALUE
The empty string.
DIAGNOSTICS
Error messages are output to the error log.
printEvntCrew
NAME:
printEvntCrew Print the current assignments/dispatches of crews to orders to the log.
SYNOPSIS
printEvntCrew()
PARAMETERS
None.
PREREQUISITE
None.
DESCRIPTION
Print the crews assigned and dispatched to all orders to the log.
RETURN VALUE
The empty string.
DIAGNOSTICS
None.
removeOldACN
NAME:
removeOldACN Removed strings found in the AUTOMATED_CASENOTES table from the passed string.
SYNOPSIS
removeOldACN(note)
PARAMETERS
note A text string.
PREREQUISITE
AUTOMATED_CASENOTES table exists.
DESCRIPTION
Loads all values from the AUTOMATED_CASE_NOTES column in the AUTOMATED_CASENOTES database table. Checks if any of the loaded strings are present in the input string and removes found occurrences.
RETURN VALUE
Updated input string.
DIAGNOSTICS
Error messages are output to the error log.
xml
NAME:
xml Return the current input xml document, if any.
SYNOPSIS
xml()
PARAMETERS
None.
PREREQUISITE
None.
DESCRIPTION
Return the current input document, or the empty string, if none.
RETURN VALUE
The current input xml document, if any.
The empty string, when an input xml document in not being processed.
DIAGNOSTICS
None.
intendedForMobile
NAME:
intendedForMobile Checks if SRSoutput message is intended for mobile system.
SYNOPSIS
intendedForMobile(typeMask)
PARAMETERS
typeMask Value of the typeMask field from SRSoutput message.
PREREQUISITES:
None
DESCRIPTION
Checks if SRSO_SEND_TO_MOBILE bit is set in typeMask.
RETURN VALUE
"true" is the message is intended for mobile system, otherwise empty string.
DIAGNOSTICS
Error messages are output to the error log.
EXAMPLE:
intendedForMobile($E.typeMask);
getPhasesDesc
NAME:
getPhasesDesc Convert bitmask representing phases into string.
SYNOPSIS
getPhasesDesc(phases)
PARAMETERS
phases Phases bitmask.
PREREQUISITES:
None
DESCRIPTION
Converts phases bitmask into a string using letters A, B, C, and N to designate different phases and the neutral.
RETURN VALUE
String containing names of the phases present in the bitmask.
DIAGNOSTICS
None.
sqlQuoted
NAME:
sqlQuoted Converts string into SQL text literal.
SYNOPSIS
sqlQuoted(str)
PARAMETERS
str text string.
PREREQUISITES:
None
DESCRIPTION
Wraps string in single quotes and escapes single quotes in the string by replacing them with double single quotes.
RETURN VALUE
SQL text literal representation of the passed string.
DIAGNOSTICS
None.
readData
NAME:
readData Reads a data field from the specified object.
SYNOPSIS
readData(dataObject, fieldName, [subFieldName])
PARAMETERS
dataObject The type of object to read data from.
Valid values:
• E - event data
• O - order data
• R - relationship data
• I - incident (call) data
• G - globally available data
• T - trigger argument data
fieldName The name of the field to read.
subFieldName If the field stores NMS handle this parameter specifies which part of the handle to read.
Valid values:
• cls - class number
• idx - instance number
• app - app field
PREREQUISITES:
• If reading event or incident data, then current event needs to be set.
• If reading order data, then current order needs to be set.
• If reading relationship data, then current relation needs to be set.
DESCRIPTION
Reads a data field from the specified object.
RETURN VALUE
Field value.
DIAGNOSTICS
Error messages are output to the error log.
setData
NAME:
setData Sets a data field for the specified object.
SYNOPSIS
setData(dataObject, fieldName, fieldValue)
PARAMETERS
dataObject The type of object to read data from.
Valid values:
• O - order data
• R - relationship data
• G - globally available data
• T - trigger argument data
fieldName The name of the field to set.
fieldValue The value set the field to.
PREREQUISITES:
• If reading order data, then current order needs to be set.
• If reading relationship data, then current relation needs to be set.
DESCRIPTION
Sets a data field for the specified object.
RETURN VALUE
Empty string.
DIAGNOSTICS
Error messages are output to the error log.
readGlobalData
NAME:
readGlobalData Reads the specified globally available data field.
SYNOPSIS
readGlobalData(fieldName)
PARAMETERS
fieldName The name of the field to read.
PREREQUISITES:
None.
DESCRIPTION
Reads the specified globally available data field.
RETURN VALUE
Field value.
DIAGNOSTICS
None.
setGlobalData
NAME:
setGlobalData Sets the specified globally available data field.
SYNOPSIS
setGlobalData(fieldName, fieldValue)
PARAMETERS
fieldName The name of the field to set.
fieldValue The value set the field to.
PREREQUISITES:
None.
DESCRIPTION
Sets the specified globally available data field.
RETURN VALUE
Empty string.
DIAGNOSTICS
None.
eraseGlobalData
NAME:
eraseGlobalData Erases the specified globally available data field.
SYNOPSIS
eraseGlobalData(fieldName)
PARAMETERS
fieldName The name of the field to erase.
PREREQUISITES:
None.
DESCRIPTION
Erases the specified globally available data field.
RETURN VALUE
Empty string.
DIAGNOSTICS
None.
readOrderField
NAME:
readOrderField Finds an order and reads a field from it.
SYNOPSIS
readOrderField(lookupFieldName, lookupFieldValue, orderFieldName)
PARAMETERS
lookupFieldName The name of the lookup field.
lookupFieldValue The value of the lookup field to search for.
orderFieldName The name of the field to read.
PREREQUISITES:
None.
DESCRIPTION
Finds an order with the specified lookup field set to the desired value and reads the specified order field.
RETURN VALUE
Field value. Empty string if order was not found.
DIAGNOSTICS
None.
undefFunc
NAME:
undefFunc Used for debugging to allow undefined functions.
SYNOPSIS
undefFunc()
PARAMETERS
None.
PREREQUISITE
None
DESCRIPTION
Used for debugging to allow undefined functions.
RETURN VALUE
"Undefined function called" string.
DIAGNOSTICS
None.
Obsolete/Deprecated Functions
• updateJobCompleteTime: Updates column JOB_COMPLETE_TIME in the JOBS table directly bypassing JMService.
• updateOverriddenCrewTime: Updates CREW_DISPATCHES table directly bypassing JMService.
• getAltDeviceLocation: Reads generic event field by position. Use 'readGenericField' instead.