PSL Built-in Functions for PATROL Agent
PSL includes a number of built-in functions that provide PATROL-specific actions such as creating and manipulating PATROL objects and general-purpose functions such as mathematical, logical, and I/O functions. The functions are described in detail in PSL Built-in Functions
The following section summarizes the PSL built-in functions.
Locking Functions for Concurrency Control
PSL includes the lock(), unlock(), cond_signal(), and cond_wait() built-in functions for enforcing concurrency control. These functions are typically used to linearize accesses by different PSL parameters, commands, and processes to shared data structures. These shared data structures include the object hierarchy accessed by the PSL set() and get() functions and external resources such as files.
All PSL processes attempting to linearize accesses to a resource must cooperate by requesting locks of a given lock name. It is the responsibility of each PSL process to access a resource only when it holds the required lock.
Set Functions for PSL Lists
PSL includes the following functions for performing set operations on PSL lists:
- difference() - returns the list of different elements between lists
- intersection() - returns a list of elements common between lists
- sort() - returns a list in ascending or descending element order
- subset() - verifies that one list is contained within another
- union() - returns a list that is a combination of elements of two or more lists, with duplicate elements eliminated
- unique() - returns a list of elements such that each appears only once in the list
These functions process PSL lists as sets of elements. Each member of a list is a text string that ends with a newline character. (The text string cannot contain embedded newline characters.) Although the set functions will properly handle lists where the last element does not end with a newline character, BMC Software recommends that all elements, including the last element, are followed by a new-line character.
The NULL set [""] is the equivalent of the null or empty set (f) in set theory. The NULL set is treated by the PSL set functions as a proper set that contains no elements.
The NULL string  is a PSL list element with no characters. The PSL set functions allow lists to contain NULL strings, but BMC Software discourages their use because their unique characteristics can produce unexpected results.
The PSL concept of a set is similar to that found in set theory. It is not a unique list of ascending or descending elements. In many cases, the PSL lists contain duplicate elements arranged in no particular order. A PSL list can be transformed into an ordered set using the unique() function to remove duplicates and the sort() function to arrange the elements in ascending or descending order.
PSL Mathematical Functions
PSL supports a basic subset of mathematical functions. These functions are all based on the standard C mathematical functions and include the peculiarities that those functions display in the standard C libraries on any given platform.
Although most issues involving the C mathematical functions are standardized, there are platform-specific differences such as levels of accuracy. The different handling of various out-of-range conditions may cause these functions to behave differently on different platforms.
All PSL functions except one have the same name as the corresponding C function. The exception is the
loge() function that corresponds to C's
log() function because PSL already has a
log() function used for logging events. The PSL
log() function has been augmented to return a run-time error when it receives a numeric value. This error message reduces the likelihood of accidentally calling the
log() function when the
loge() function is required.
log() function has been replaced by the
event_trigger() function, but the
log() function is still supported for backward compatibility.
The PSL mathematical functions include some run-time error checking for range and domain. Both conditions result in a run-time error message that sets the PSL errno variable to an appropriate value.
Additionally, any nonnumeric values produced by printing the result of the function call, such as
Nan or -
Inf, are converted to
0.0 to prevent the return value from being interpreted by PSL as a nonnumeric character string. A PSL function also returns a run-time error message when it performs the conversion.
Some PSL domain errors may not exactly match those of the standard C library:
- PSL functions and argument ranges may raise a domain error and return zero.
- C functions may raise a range error and/or return a nonnumeric representation of the result such as infinity in the following cases:
log10(x)when x <= 0
sqrt(x)when x < 0