Abs - Calculate Absolute Value
| result = Abs ( number ) |
| result | The absolute value of the argument. | |
| number | A scaler or complex number. |
This module returns the absolute value of its argument. If the number is greater or equal to zero then the number is returned as the result. If the number is negative then (0-number) is returned. If complex, then the absolute value (modulus) is returned.
| Abs(123) | returns 123 | |
| Abs(-345.44) | returns 345.44 | |
| Abs(Complex:123 231) | returns 261.7054 |
AggDel - Delete an Aggregate Record
| result = AggDel ( key ) |
| result | Returns Logical:True if the aggregate associated with key was deleted. The module fails otherwise. | |
| key | A value representing the aggregate to be deleted. |
This module deletes an aggregate based on the key value.
AggPut - Write Out an Aggregate Record
| result = AggPut ( tagkey valpoint valpoint ... ) |
| result | An indicator specifying where the aggregate was written. Positive numbers indicate Aggregate Areas, negative indicate V4 Areas. The module fails if any problems occur. | |
| tagkey | A tagged value indicating the type of aggregate to be written, see below. | |
| valpoint | One or more value points to be included in the aggregate. |
| Agg::keypoint | Write out an aggregate. | |
| BFAgg::keypoint | Write out a blocked-fixed aggregate. | |
| FAgg::keypoint | Write out a fixed aggregate, all aggregates of this type must be of the same format and length. | |
| New::logpt | If logpt is TRUE (default) then the point written must be new (i.e. must not already exist within the aggregate). If logpt is FALSE then the aggregate, if it already exists, will be replaced with the new set of data points. | |
| Out::id | Output to the aggregate with the specified id. An unique identifier may be associated with an aggregate when it is open. See the Id tag within the V4 module and the 'Id' option within the Area command. |
| Create? | Add the keypoint to the list of known points on the dimension. |
The AggPut module is used to write out aggregates during the evaluation of a V4 intersection. This module is identical to the Aggregate, FAggregate, and BFAggregate commands available within the V4 command processor.
If the keypoint value given as the first argument is a point on Dim:Int then the key value is taken as the keypointth value point.
The following example accesses a sales history relation on another system and loads columns 2 and 4 into a V4 aggregate-
| Dim SH AggVal | Define the Sales History Dimension | |
| Dim O XDB | Define external database Dimension | |
| Eval DBConnect(Dim:O DSN::Sales-History) | Connect to the proper table | |
| Context Add DBGet(SQL:: Select * From SLSDtl) | Grab the rows we want | |
| Eval Enum(O* | Enumerate through all rows | |
| @AggPut(Agg::MakeP(Dim:SH) | Make new aggregate point | |
| dbVal(O* Int:2) dbVal(O* Int:4) )) | Grab columns 2 & 4 for current row |
AggUpd - Update an Aggregate Record
| result = AggUpd ( key dim index value ) |
| result | Returns Logical:True if the aggregate associated with key was updated. The module fails otherwise. | |
| key | The key to the aggregate. | |
| dim | The dimension associated with the value within the aggregate to be updated. | |
| index | The index to the field in the aggregate (1 is the first field). | |
| value | The new value for the field. |
The AggUpd module is used to update a specific field within an aggregate.
AggVal - Return an Element from an Aggregate
| value = AggVal ( key dimension index ) | |
| value = AggVal ( key dimension ) | |
| value = AggVal ( agg dimension index tagarg ) |
| value | The returned value, may be any type of point. | |
| key | The key point used to retrieve the aggregate (the first point in the Aggregate command). | |
| dimension | The dimension of the resulting point. A list of dimensions is also allowed. If more than one dimension is specified then the internal type of the value dictates which dimension is used (see below). | |
| index | The index within the aggregate for the value point. | |
| agg | An aggregate point. | |
| tagarg | One or more optional tagged arguments. |
| EQ::point | Compares aggregate value with point value and returns Logical:True if the values are the same, Logical:False if not the same. Note that the comparison is for numerical results only. The dimensions of the aggregate value and the point need not be the same. | |
| Error::point | If an error occurs when accessing the aggregate (ex: it is not found) then evaluate point and return it as the value. Also see the Missing attribute in the Column command and the #m# tag within the Loop command. | |
| GE::point | Same as EQ but a greater-equal test is performed. | |
| GT::point | Same as EQ but a greater-than test is performed. | |
| LE::point | Same as EQ but a less-equal test is performed. | |
| LT::point | Same as EQ but a less-than test is performed. | |
| NE::point | Same as EQ but a not-equal test is performed. | |
| Nth::point | Tests the Nth bit (as specified by the numeric point) of the resulting aggregate value. If the bit is set then Logical:True is returned. If the bit is not set then Logical:False is returned. |
This module is used to returns point values previously stored via the Aggregate command. It is most often used to relate a field name with a record. If the aggregate corresponding to the key cannot be located then the module fails. If the value corresponding to the index has not been defined then the module fails.
When the first argument is an aggregate point (not a key to an aggregate record), this module extracts the requested field directly out of the point. No access is made to an aggregate record.
If an aggregate value can be more than one internal point type (e.g. UDate or Alpha) then multiple dimensions must be given in the second argument.
If no index is specified then the area constant associated with the key and dimension are returned. See the CAggregate command for setting area constants.
Example 24 - Use of AggVal with V4 Macro
|
[Id Cus..] AggVal( Cus* Dim:CusId 1 ) [Name Cus..] AggVal( Cus* Dim:Alpha 2 ) [Attr Cus..] AggVal(Cus* Dim:Int 3) [IsActive Cus..] AggVal(Cus* Dim:Int 3 Nth::8) [IsTest Cus..] AggVal(Cus* Dim:Int 3 Nth::4) [StartDate Cus..] AggVal(Cus* Dim:UDate Int:4) [IsNew Cus..] AggVal(Cus* Dim:UDate Int:4 GE::DTInfo(UDate:{now} Month::1 Day::1 UDate?)) {/Cus( aId, aName, aAttr, aStart... ) Context Add Cus:{new} ; Aggregate< Cus* aId aName aAttr aStart... > }/Cus |
In this example, the Cus macro is defining fields in a customer record. The key to the aggregate is the current customer, the first entry in the aggregate is the customer id followed by the customer name. The bindings above the macro definition define the Id and Name of any customer as the first and seconds fields in the aggregate for that customer. The Attr field is the third aggregate value. A customer is a test customer if the 4th bit is set in this value. The starting date for a customer is the fourth value. A customer is new if the start date is greater than or equal to the first of the current year.
And - Logical And (Bitwise And)
| logres = And ( value1 value2 ... ) | |
| list = And ( list1 list2 ... ) |
| logres | The logical result of and'ing all of the arguments. | |
| valuen | One or more values to be logically and'ed. Note that any numeric value greater than zero is considered to be Logical:True and any number less than or equal to zero is considered to be Logical:False. | |
| list | The resulting list from logically and'ing all of the bits from each of the argument lists. | |
| listn | A bitmapped list. |
This module returns Logical:True if each of its argument evaluates to true and Logical:False if any of its arguments evaluates to false. Normally all arguments are evaluated before the test is performed. If the evaluation of an argument is expensive then preface it with a quote (see example below) and it will only be evaluated if each of the preceding arguments evaluated to true. If the module is called with no arguments it returns Logical:True.
In the case that the arguments are bitmapped lists, then the corresponding bits from each map are and'ed and the resulting map is returned.
| And(GE(Emp.Age Years:25) @LT(Emp.AvgSalary 35000)) | This example returns Logical:True if the age of the current employee is greater than or equal to 25 and the average salary is less than 35000. Note that the second argument (LT(...)) will not be evaluated if the first argument evaluates to false. | |
| {Emp.Age >= Years:25 & Emp.AvgSalary < 35000} | This is identical to the above example. |
Area - Manipulating V4 Areas
| value = Area ( file tagarg... ) | |
| value = Area ( list tagarg... ) | |
| value = Area ( tagarg ... ) |
| value | The returned value depends on the arguments. | |
| file | The name of the area to be opened or created. | |
| list | A list of filenames to be opened. | |
| tagarg | One or more of the tags decribed below. |
| BucketSize::num | Sets the bucketsize to num for the area being created. In most cases, the default is optimal and this is unecessary. | |
| Close::list | Closes all of the areas specified by the list of previously opened area ids. | |
| Close::aid | Closes the area specified by the previously opened area of id aid. | |
| Error::logical | Determines how errors are to be handled. If logical is TRUE (default) then errors opening areas generate an error, if FALSE then the Area module returns FALSE. | |
| Hierarchy::num | Sets the hierarchy number for the area being created. No two opened area may have the same number. The value, num may be between 1 and 6. The default number is 5. | |
| Id::idpnt | Associates an identifier with the area. The idpnt point must be either an integer or dictionary point. | |
| Index::logical | If TRUE (the default) then open the Aggregate area with indexing. If false then open the created area for data put access only. The area must be indexed before it is read. | |
| Open::mode | Specifies how the area is to be opened. Use Read (default) for read-only access, Create to create a new area file, CreateIf to open an existing file or create it if it does not already exist, Update for update access. | |
| Rebuild::newfile | Rebuild the file specified as the first argument into the new file newfile. | |
| Retry::num | Specifies the number of times to attempt to open an area if the first attempt(s) fail. The default is 3. | |
| Sequential::logical | If TRUE then optimize the opening of the area for sequential access. If FALSE (default) then open normally. | |
| Type::atype | Specifies the type of the area. The allowed values for atype are: Area (default) to open as a normal V4 area, Agg to open as an aggregate, Dictionary, Dict or External to open as an external dictionary. |
| Index? | Create the index for the specified area that was opened with the Index:No option. | |
| ListOf? | Returns a list of all open areas. Each list entry is itself a list consisting of (areaid type file hierarchy) where type is one of: Area, Dictionary or Aggregate. The hierarchy value is given for regular areas, not aggregates. | |
| NoError? | This is identical to Error:FALSE. | |
| Reset? | To reset the area specified by the first argument file. This must be an external dictionary file. This will remove all entries in the dictionary except for dimension values. |
This module duplicates all of the functionality of the Area command.
Array - Multidimensional Array Update & Retrieval
| array = Array ( dimension range1 range2 ... ) | |
| value = Array ( array index1 index2 ... Value::value ) | |
| value = Array ( array index1 index2 ... Add::value ) | |
| value = Array ( array index1 index2 ... ) | |
| value = Array ( array index1 index2 ... If::test ListOf::result ) |
| array | A V4 Array point | |
| dimension | A point on the V4 Dim dimension. This defines the type of point to be stored in the array. | |
| rangen | A range of points or integer number that declares the size and bounds of a dimension of the array. | |
| index | A index value into the corresponding dimension of the array. | |
| value | The value to be assigned (or added) to the element(s) of the array. |
| Add::value | Adds the valueto the specified element or elements in the array. | |
| Distance::num | Specifies the distance to search from a given starting point within an array. This is used with the If and ListOf options. | |
| If::test | Defines a test expression test to be used when search a subset of the array. | |
| ListOf::num | Returns a list of points corresponding to the values of the numth index/dimension of the array. This option is only valid for arrays created via the Tally module. | |
| ListOf::result | Determines what is to be returned on a succesful search of an array subset. The result must be Indexes to return a list of array indexes or Values to return a list of values. If it is Indexes, the result is a list of lists with each inner list being the indexes within the array that matched the If condition. | |
| Value::value | Sets the specified element or elements in the array to value. |
| Release? | Release all memory associated with the array. Any future references to the array will result in an error. |
The Array module creates arrays, updates arrays, and retrieves one or more values from arrays. An array may have up to 16 dimensions. Dimensions may be any point that maps to an integer value including dictionary point types. V4 arrays are provided for efficiency purposes. Solutions implemented with arrays often run considerably faster than those implemented solely with bindings.
The steps involved in using a V4 array are 1) create the array point by calling the Array module with the first argument being a point on the Dim Dimension and the following points being the bounds of the array, 2) Setting value within the array using the Value tagged argument, 3) Referencing values within the array.
It is possible to set array values more than once and to use other array references. One typical use of arrays is for generating cumulating values.
V4 supports an alternative syntax for array declaration, updates and access. The form: 'name[...]' is converted by the V4 compiler to 'Array([name] ...)' and the form 'name[Dim:dimension ...]' is converted to 'BindQE([name] Array(Dim:dimension ...))'. This is allow array usage in V4 to follow more traditional syntactic conventions.
| BindQE([ray] Array(Dim:UDate Udate:1/1/00..12/31/00 10)) | Creates an array of UDate points. The first dimension corresponds to the days from 1-Jan-2000 through 31-Dec-2000. The second dimension corresponds to the integers from 1 through 10." | |
| Array([ray] Value::UDate:11/2/50) | Sets all elements of the array to 2-Nov-1950 | |
| Array([ray] UDate:5/1/01 2 Value::Udate:5/25/01) | Fails - 1-May-2001 not in valid range for first dimension | |
| Array([ray] UDate:4/1/00..5/31/00 Int:3..6) | Returns a sub-array corresponding to dimensions- (1-Apr-2000..31-May-2000 and 3..6) to | |
| Eval Enum(Array([ray] UDate:4/30/00..5/2/00 Int:1..4) @EchoT(UDate*)) | Echos 12 elements from specified sub-array | |
| BindQE([2darray] Array(Dim:Int 100 100)) | Defines a two dimensional array of integer values | |
| Array([2darray] 20 30 Distance::2 If::{Int* <> 0} ListOf::Indexes) | searches the array within the rectangle bounded by (18,32) and (22,28) |
Avg - Returns Average of its Arguments
| result = Avg ( value1 value2 ... ) | |
| result = Avg ( list ) |
| result | The sum of the values divided by the number of values. | |
| valuen | A numeric value. | |
| list | A list of numeric values. |
The Average module simple sums its arguments, divides the sum by the number of arguments and returns that as the result.
| Avg( 1 2 3 4 5 ) | results in Num:3 | |
| [NumList] (1 2 3 4 5) | define a list of numbers | |
| Avg([NumList]) | also results in Num:3 |