Table - Create, Modify, Examine V4 Tables
| respnt = Table ( tag ... ) |
| respnt | The result is based on the tagged arguments. | |
| tag | One or more of the tagged arguments described below. |
| Acceptor::isct | Associates an acceptor routine with a column. | |
| AggKey::logical | Sets the aggregate-key attribute for the column. | |
| Column::name | To reference the column with name within the current table. | |
| Column::integer | To skip over integer columns with the IGNORE option. | |
| Comment::char | Defines one or more comment characters. An input line beginning with any of the characters in this string will be ignored. | |
| Create::table | To create a new table with table as the name. | |
| Decimal::num | Defines the implied number of decimal points for the column. | |
| Default::point | Defines the default value point for the column. | |
| Delimiter::delim | Defines the column delimiter as delim. This may be any character value or one of the following: CSV for comma-separated values, None for no delimiter (i.e. fixed width), or Tab for tab delimited. The difference between specifiy | |
| Description::text | Assigns a description string to the column. | |
| Dim::dimension | Defines the dimension associated with the new column. | |
| Embed::none | NYI | |
| End::column | Defines the ending character position for a column. | |
| Ending::column | See End. | |
| Error::point | Defines an error point value for the column. This value is used if an error occurs while parsing the column value. | |
| Expression::point | Defines a value for the column. This basically defines a virtual column that is not to be parsed from the input. Columns with this attribute are not included in table aggregates. These columns are to be evaluated at runtime. Compare this option with the Point tag. | |
| Filter::isct | Defines a filter intersection to be called for each input line. See the Include command for more information. | |
| FixedLength::num | Defines a fixed length for a column. | |
| Format::option | Sets the formatting option for the column, one of: Default, Internal, YYMMDD, MMDDYY, DDMMMYY, Hex4, Hexadecimal, Money, YYMM, MMYY, MMM, | |
| Header::num | Defines the number of header lines in the input (to be skipped). | |
| Ignore::logical | If TRUE then set this column to be ignored. | |
| Include::xxx | NYI | |
| Index::maskbit | NYI | |
| Link::method | Declares a column to be a linking column. The allowed method values are: NoPrefix and Prefix. | |
| ListOf::what | Returns a list of attributes for a previously specified table: All for a list of all columns (including Ignore columns) in the table, Dim for a list of all associated dimensions, Name for a list of all column names, Position for a list of column starting positions, Width for a list of column widths. Note that Start and Width are not defined for character-delimited columns. Also note that columns with the Ignore attribute are not included in these lists. | |
| Macro::name | Associates the processing macro name with the table. | |
| Mask::bitlist | Sets the inclusion mask for this column. The bitlist is a list of bits between 1 and 32. | |
| Minimum::size | Ignore any input lines fewer than size characters. | |
| Missing::point | Defines a value point to be used if the aggregate 'record' cannot be found. | |
| Name::colname | Specifies the name when defining or specifying a column. | |
| Other::string | Assigns the string as a user-defined value to the table. Use the point UV4:none to clear this value. | |
| Point::point | Assigns a point value to the column. The column value is not taken from the input but from the evaluation of point. Columns assigned a Point value are included in any output aggregates. See also the Expression tag. | |
| Quoted::logical | Sets the 'quoted' option for the column. | |
| Scale::num | Sets the scaling factor for the column. | |
| Start::position | Sets the starting character for the column. | |
| Table::tablename | Specifies a table. | |
| Trim::logical | Set the field trim attribute for the column. | |
| Width::colwidth | Defines the column width for the column. |
| Acceptor? | Returns the acceptor associated with the column, or fails if none defined. | |
| AggKey? | Returns TRUE if the aggregate-key attribute is set for the column, fails otherwise. | |
| Comment? | Returns any comment characters associated with the table, fails if none are defined. | |
| Decimal? | Returns the implied number of decimal points, fails if none given. | |
| Default? | Returns the default value for the column, fails if none given. | |
| Delimiter? | Returns the delimiter (type) associated with the table, fails if none given. | |
| Description? | Returns the description assigned to the column, fails if none given. | |
| Dim? | Returns the dimension associated with a column. | |
| End? | Returns the ending character position, fails if none given. | |
| Ending? | See End?. | |
| Error? | Returns the error point for a column, fails if none given. | |
| Expression? | Returns the value for the column or fails if none defined. | |
| Filter? | Returns the filter point associated with the table, fails if none specified. | |
| FixedLength? | Returns the fixed-length attribute of a column, fails if none defined. | |
| Format? | Returns the format setting for the column, fails if none set. | |
| Header? | Returns the number of header lines, fails if none defined. | |
| Ignore? | Returns TRUE if the column is set to be ignored, fails otherwise. | |
| Index? | NYI | |
| Link? | Returns the link status of a column or fails if no link is defined. | |
| ListOf? | If this is the only argument then a list of all defined tables is returned. If a table has been defined (with the Table tag) then the list of columns for that table is returned. The column names are, by default, returned as points on Dim:NId. This may be overridden with the Dim tagged argument. | |
| Macro? | Returns the processing macro associated with the table, fails if none assigned. | |
| Mask? | Returns the inclusion mask for the column, fails if none specified. | |
| Minimum? | Returns the minimum character input line length, fails if none assigned. | |
| Missing? | Returns the Missing point or fails if none has been defined. | |
| Name? | Returns the name of the current column. | |
| Other? | Returns the user-defined value of the table, fails if no value is assigned. | |
| Point? | Returns the assigned point value, fails if none. | |
| Quoted? | Returns TRUE if the quoted option is set for the column, fails otherwise. | |
| Scale? | Returns the scaling factor for the column, returns 0.0 if none. | |
| Start? | Returns the starting character position for the column, fails if none assigned. | |
| Trim? | Returns the field trim attribute for the column- TRUE is set, fails otherwise. | |
| Type? | Returns the basic column type as a point on Dim:UV4. The returned value will be one of: UV4:Ignore if the column is set to ignore. | |
| Width? | Returns the column width, fails if none given. |
This module is used to create, modify and examine V4 tables. See also the Table and Include commands for more information.
Example 46 - Creating a New Table with Table() Module
|
[makeNewTable] Do(Table(Create::newTable Macro::newTableMacro Header::1 Comment::"!" Filter::@[hohoho] Minimum::5 Delimiter::CSV) Table(newTable Create::col1 Dim:Int Description::"This is column one") Table(newTable Create::col2 Dim:Num Mask::1 Default::Num:3.2 Decimal::2) Table(newTable Create::col3 Dim:UDate Format::yymmdd Error::@[mooo]) Table(newTable Create::col4 Dim:Alpha Quoted::TRUE FixedLength::30 Trim::TRUE) Table(newTable Create::col5 Dim:Cus Missing::Cus:0) ) |
Example 47 - Outputting Table Definition using Table() Module
|
[dumpOutTable tblName..] Do( Echo("Table " tblName* Str(" Comment " Str(Table(tblName* Comment?) Literal?)),"" Str(" Delimiter " Str(Table(tblName* Delimiter?) Literal?)),"" Str(" Filter " Table(tblName* Filter?)),"" Str(" Header " Table(tblName* Header?)),"" Str(" Macro " Table(tblName* Macro?)),"" Str(" Minimum " Table(tblName* Minimum?)),"" ) Enum(Table(tblName* ListOf?) @Do(Echo(" Col " NId* " " Table(tblName* Column::NId* Dim?) Str(" Acceptor " Table(tblName* Column::NId* Acceptor?)),"" If(Table(tblName* Column::NId* AggKey?) Then::" AggKey"),"" Str(" Decimal " Table(tblName* Column::NId* Decimal?)),"" Str(" FixedLength " Table(tblName* Column::NId* FixedLength?)),"" Str(" Default " Format(Table(tblName* Column::NId* Default?) Point?)),"" Str(" Description " Str(Table(tblName* Column::NId* Description?) Literal?)),"" Str(" Start " Table(tblName* Column::NId* Start?)),"" Str(" End " Table(tblName* Column::NId* End?)),"" Str(" Error " Format(Table(tblName* Column::NId* Error?) Point?)),"" Str(" Format " Table(tblName* Column::NId* Format?)),"" If(Table(tblName* Column::NId* Ignore?) Then::" Ignore"),"" Str(" Missing " Format(Table(tblName* Column::NId* Missing?) Point?)),"" Str(" Mask " List(Table(tblName* Column::NId* Mask?) Column::",")),"" If(Table(tblName* Column::NId* Quoted?) Then::" Quoted"),"" If(Table(tblName* Column::NId* Trim?) Then::" Trim"),"" Str(" Width " Table(tblName* Column::NId* Width?)),"" ) )) Echo("EndTable") ) |
Tally - Tally Up Points in a List
| undef = Tally ( list opttag (tallyoption1) (tallyoptions2) ... ) |
| list | A list of points to be tallied. | |
| opttag | One or more tagged arguments as described below. | |
| tallyoption | A list of tally options described below. More than one list may be given in a Tally. |
| Area::file | Output the results of the tally to the intermediate file. The results of several independently run Tally's can be merged into a consolidated result with the TallyM module. | |
| AWhile::isct | Similar to While except that the test is performed after the processing of the list point. | |
| Context::point | For each enumeration point, V4 evaluates and inserts the point into the current context. If the point is UV4:none then nothing is done (i.e. UV4:none is not placed into the context). This point can be inserted into the context by quoting it: Context::@UV4:none. If point is UV4:Skip the current point is ignored entirely. | |
| ContextP::point | This is identical to the Context tag except that if point evaluates to a list then each point in the list is inserted into the context. | |
| Count::dim | Updates the context with a point on dimension dim representing the current count/index into the the source list of points (i.e. updated with 1 on the first point, 2 on the second, etc.) | |
| Dim::dim | Sets the dimension for all resulting points. The default is Dim:Int.: | |
| Do::isct | Evaluate the isct for each selected point in the list. | |
| Hold::isct | Similar to Context except that the point is held constant. | |
| Id::name | Associate the name with the tally. This is used to identify multiple tallies with the Set Trace Tally command. | |
| If::isct | Test each point in list against the evaluation of isct. If isct evaluates to true then use the point in the Tally. If the point evaluates to false then exclude it. If the argument is UV4:none then it is ignored. | |
| Index::dim | The dimension is inserted into the context with each selected point with an integer value representing the ordinal number of the point (i.e. the first selected point is reflected as dim:1, the second as 2, etc.) | |
| Index::point | The point is inserted into the context and incremented by one after each point. This allows one to specify a starting value for an index. | |
| Num::max | Only look at the first max number of points before quitting. This option limits the number of points for the specific tally. The Set PointMax command affects all Tally calls. | |
| Parent::isct | The isct evaluates to a parent point. This is used in conjunction with the PIf::test argument. For each point in the tally, the isct is evaluated and compared to the previous parent point. If the points are identical then the point is either used in the tally or immediately rejected based on the last PIf test. If the point is different then it is entered into the current context and the PIf point is tested. If the argument is UV4:none then it is ignored. | |
| PIf::isct | Evaluates the isct and if true continues with the point in the tally. If the result is false then the point is rejected. If the argument is UV4:none then it is ignored. | |
| Sample::n | Sample, on average, every nth point. This is useful for testing large lists. | |
| Sample::n | Sample, on average, every nth point. This is useful for testing large lists. | |
| Shell::dim | Each point in the list is added to the current context under dimension dim. Note that this dimension should be a shell dimension and should be specified as Dim:dim. When this argument is given the enumerating point is NOT added to the context under its own dimension. | |
| Skip::n | Skips the first n points in the source list. This may be useful for debugging/testing large lists. | |
| Sum::slist | Same as Sum:isct except that the summation is performed for each point in the slist. | |
| Sum::isct | The isct is evaluated with each selected list point. The result of the first evaluation is entered into the current context. For each subsequent point evaluated, the new value is added to the current value in the context. | |
| Values::n | Defines the maximum number of Tally by combinations. In most cases the default number is sufficient. If a Tally results in too many combinations, an error will occur and this option will be required. If a Tally approaches the default limit, performance may suffer but, again, warning messages will be given by the V4 runtime system. | |
| While::isct | Similar to If except that the processing of list stops with the first evaluation of isct which returns false. |
| Prefetch? | Enable prefetching of aggregate data. This option only applies in a multi-processor (or hyperthreaded) environment. Use of this option triggers a separate thread within V4 that reads and buffers aggregate data while the main V4 thread performs the actual Tally operation. This can result in a significant wall-clock performance boost. |
| Array::name | Create an array that may be referenced as [name] and populate it with the current entry values using dimensions as defined by the By points. See below for discussion and examples. Use of this option enables the Listof:num option within the Array module. | |
| Average::point | Calculate the average of all points tallied. If point is a list then separate averages are calculated for each. Note that the number of points must match those in the Bind (i.e. one binding per each average). | |
| Bind::isct | The intersection to use to bind the results of the Average, Sum, Sub, StdDev, or Count. The points in this isct plus those from the By are used to form the final binding to the values. See the BindIf option for control over insertion of specific bindings. Note: if the argument is not an intersection, but a single point then it is automatically converted into an intersection. | |
| BindIf::isct | This option is given to test a binding value before actually creating it. At the end of the Tally operation, V4 creates bindings based on the Bind and By tags. When BindIf is given, V4 inserts the bind value into the context and then evaluates isct. If the result is TRUE then the binding is made, if FALSE then no binding is created and V4 skips to the next Bind/By combination. | |
| Bits::num | The maximum number of bits to allocate for UCount/UList operations. | |
| By::point | A point or list of points to Tally by. This is optional and if not specified then all points in the Tally will be summed, averaged, etc. into a single bucket. | |
| ByIf::test | After processing the main list of points, the Tally module constructs any ByLists as specified by the ByList option below. This argument can be used to control insertion of points into this list. Each point to be added is inserted into the context and test is evaluated. If the result is true then the point is appended to the ByList. If the result is false or undefined then the point is not appended. | |
| ByList::isct | An intersection to be used to save a list of all unique By points found. | |
| Cache::num | Specifies the number of entries in the cache buffer. If the number is an integer then that number becomes the size of the cache. If the number is a decimal between 0 and 1 then the cache size is that number times the number of points in the tally list. | |
| Count::point | Keep a count of the number of points tallied. If point is 1 then the result is the number of points tallied. If it is 2 then it will be twice the number tallied. | |
| Dim::dim | Sets the dimension for all resulting points of this group. The default is Dim:Int or the dimension specified globally (described above). If dim is a List type with the Entries option and the List option is used then a bitmap is created on dim. This can be an extremely efficient method for creating lists of points. | |
| Do::point | Evaluate point if all global and local conditionals are met. | |
| If::isct | Only include the Tally list point for this operation if isct evaluates to true. | |
| IfOnce::isct | Only include the Tally list point for this operation if isct evaluates to true. If it does then do not perform subsequent operations for the point. If isct evaluates to false then continue with subsequent operations. | |
| Ifx::isct | V4 supports three special variations of If- IfA, IfB, and IfC. These are identical to If but also remember their values and can be referenced in other parts of the Tally with IfA?, IfB?, and IfC?. These are provided solely for performance. | |
| ListOf::point | Maintain a list of the points and use that as the value to be associated with the Bind at the end of the tally. | |
| Maximum::point | Keep track of the largest point in the tally. | |
| Minimum::point | Keep track of the smallest point in the tally. | |
| Project::dim | This tag may be used in lieu of the Bind tag. When the tally action is complete, V4 creates projections from the By points onto values of the dim dimension. This option may be used only when a single By value is specified. It is significantly faster than the Bind option. The BindIf option also applies to this tag. | |
| SetOf::point | Similar to ListOf except that only a single copy of each point will be in the resulting list, i.e. there will be no duplicate points. | |
| StdDev::point | Calculate the standard deviation (sample, not population) of points in the tally. | |
| Sub::point | Subtract the points in the tally (same as Sum with the sign reversed). | |
| Sum::point | Sum the points for the tally. | |
| UCount::isct | Maintain a unique count. The results are the same as using the SetOf tag and then taking the ListSize of the result. If the count is the wanted result, UCount is significantly faster than SetOf. The Cache tag can be used to improve performance. | |
| Values::list | The tally operations are not performed on the main tally list but on the list of points specified by this list. See the example below. | |
| WBind::isct | Specifies the binding environment to be used with the With argument. | |
| With::pt | The With and WBind arguments are used with the Min and Max arguments. These allow you to record points associated with minimum and maximum values. See the example below. |
The Tally module is a powerful function of V4 which scans through a list of points, performs a variety of calculations and either returns the results as a list or binds the results to intersections for later reference. A tallyoption is a list containing arguments as described in the Secondary Tagged Argument list.
Actions/operations include any combination of the following-
The arguments Count, Index, Sample, and Skip can be used to reduce the total number of points examined as part of the tally. If a Count dimension is given then the context is updated with a point on that dimension reflecting the current index (1 through the number of points in the tally). Index can be used to select only portions of the source list. For instance Index::Int:<=1000 selects on the first 1000. Index::Int:5000..10000,20000..30000 selects only points 5000 through 10000 and points 20000 through 30000. Sample is used to random select, on average, every nth point. Skip is used to skip over the first n points. Skip::1000 is identical to Index::Int:>1000.
The processing order within a Tally is as follows:
|
Tally( Cus.. (ListOf::Cus* By::Cus.State Bind::[CusBySt] ByList::[StList]) ) |
This example tallies all customers and creates a list of customers by state. A binding of the form-
| Bind [CusBySt State:xx] | list of customers in xx |
Additionally it creates a list of all states seen in the tally and binds that list to [StList].
|
Tally(IM.. If::{IM.LastSale > Date:950101 (Average::(IM.Cost IM.YearSales) By::IM.Class Bind::([AvgClassCost] [AvgClassSales]) )) |
In the above example, the tally selects only those inventory item points (IM) which have a last sale date greater than or equal to 01-Jan-95. It then aggregates the selected points by inventory class (By:IM.Class) and calculates the average cost and average sales for the year. Upon completion it generates bindings of the form:
| Bind [AvgClassCost Class:xx] | average cost for the class | |
| Bind [AvgClassSales Class:xx] | average sales for the class |
The example below simply selects all sales in June 1996 over 15000 and sums them into [TotalSales]-
|
Tally(Sales.. If::{Sales.Amt > 15000 Sales.Date == Date:960601..960630} (Sum::Sales.Amt Bind::[TotalSales])) |
The example below selects all bills-of-materials of type ASSM1 and makes a list of component parts. The Sort then sorts the parts by inventory ID and then displays the part ID and description.
Example 50 - Tally - Roll Up Bill-of-Materials
|
Tally(BOM.. If::{BOM.Type = Type:ASSM1} (Values::BOM.CompList SetOf::BOM.Parts Bind::[PartList])) Sort([PartList] By::IM.Id Do::EchoS(IM.Id IM.Desc)) |
The example below demonstrates the With/WBind options. The Tally enumerates through all sales and generates the minimum sales per state. The With argument additionally records the customer bill-to associated with each minimum in each state. The bindings created are [MinSale State:xxx] and [MinCus State:xxx].
|
Tally(Sales.. (Minimum::Sales.OrderAmt By::Sales.State Bind::[MinSale] With::Sale.BillTo WBind::[MinCus])) |
Example 52 - Tally - Creating a bitmap result
|
Dim BMList List Entries Photo Tally(PhotoAttributes.. (ListOf::PhotoAttributes.Photo By::PhotoAttribute.Value Bind::PhotoList Dim:BMList)) |
This example demonstrates the use of the Array option.
| [ItemSalesByState date..] | generate sales by item (rows) and state (columns) | |
| Do(Tally(sale:(date*) | tally for the specified date range | |
| (Sum::sale.units By::(sale.item sale.state) Array::units) ) | sum units by item and state -> [units] array | |
| Context::Sort(Array([units] ListOf::2) By::state*) | List* = sorted list of selected states | |
| Rpt(Title::"Units Sold By Item / State") | report title | |
| Rpt(Columns::(a b (c ListSize(List*)))) | define report columns (c = set of columns for states) | |
| Rpt(Heading::(a "Item") (b "Description") (c (state*)/List*))) | report headings | |
| Enum(Sort(Array([units] ListOf::1) By::item.id) | enum through all items | |
| @Rpt((a item.id) (b item.description) (c Array([units] item* state*)/List*))) | generate report detail | |
| Rpt(Close?) | close off report | |
| ) |
TallyM - Merge Results of Multiple Tallies
| TallyM "argss" = TallyM ( List ) |
| opttag | One or more tagged arguments as described below. | |
| tallyoption | A list of tally options described below. More than one list may be given in a TallyM. |
| Area::list | This specifies a list of areas to be merged as part of this tally. Each of the areas must have been created by a prior Tally call with the Area option. This tag is mandatory. | |
| Values::n | Defines the maximum number of Tally by combinations. In most cases the default number is sufficient. If a Tally results in too many combinations, an error will occur and this option will be required. If a Tally approaches the default limit, performance may suffer but, again, warning messages will be given by the V4 runtime system. |
The TallyM module takes the results of previous Tally calls and merges them into a single result. There is no (reasonable) limit to the number of areas that may be merged in a single TallyM. The previously run Tally's may have been run on different hardware or operating systems. This module has two main uses. The first is to pre-aggregate a large, non-changing set of points and then quickly merge in a smaller dynamic or recent set of points to get a consolidated answer. The second use is to factor very large Tally's into smaller pieces which can be run concurrently on different machines and then merge the sub-results back into a consolidate result.
|
Tally(OldSales.. Area::File1 (Sum::Sales.Amt By::Sales.ShipTo)) Tally(CurrentSales.. Area::File2 (Sum::Sales.Amt By::Sales.ShipTo)) TallyM(Area::(File1 File2) (Bind::[CusSales] ByList::[CusList])) |
TEQ - Test Equal/In (Quoted)
| value = TEQ ( expression test1 value1 test2 value2 ... dfltvalue ) |
| value | The result of evaluating one of the valuen arguments | |
| expression | A point that must evaluate to a numeric or dictionary type. | |
| test | A point to be compared with the expression. | |
| value | A point to be evaluated if its corresponding test point matches the expression. The evaluated result is returned as the result of the module. | |
| dfltvalue | The evaluated value to be returned if no tests match the expression. |
The TEQ module evaluates its first argument and compares the result with each of the testn arguments until a match is found. The corresponding valuen point is then evaluated and returned as the result for the module. If no test matches the expression then the dfltvalue is evaluated and returned. If no dfltvalue is given then the module fails.
Example 53 - TEQ - Different Recapping
|
TEQ(HowRecap* HowRecap:Name Do(Enum(Sort([EmpList] By::Emp.Id) Do::Emp.CLOut)) HowRecap:Mgr Do(Enum(Sort([EmpList] By::Emp.Mgr.Id By::Emp.Id) Do::Emp.CLOut After::(Emp.Mgr EchoS("" T:=Emp.Mgr.Name))) ) ) |
Example 54 - TEQ - Integer Ranges
|
TEQ({1 + 5} Int:1 Result is 1 Int:2..10 Result is between 2-10 Result is > 10) |
Throw - Throw an Error Exception
| result = Throw ( excstr ctxpt ctxpt ... ) |
| result | The result is the last point evaluated by the V4 Try module Catch point(s). | |
| excstr | An exception to be thrown (string) or list of exceptions separated with commas. | |
| ctxpt | One or more points to be inserted into the context as the exception is thrown. |
The Throw module attempts to throw an exception as defined by excstr. If the string consists of more than one exception (delimited by commas) then V4 attempts to throw the first exception. If no nested Try modules catch the exception then V4 continues with the next exception. If no exceptions are caught then the module fails.
The result of the module is the value point of the last evaluated point within the point or list of points that caught the exception.
The failure within a V4 module may trigger an implicit exception. This may be controlled with the V4 Throw option that enables the automatic throwing of an exception when a specific error occurs within V4.
See also Try() and V4() for additional information.
|
[TryThrowExample] Do(V4(Throw::(ODBCConErr)) Enum(Int:1..10 Id::OnceAgain @Try( Echo(line1) [xxx],Echo(" oops") Echo(line2) Catch::"XDB*" (Echo("Looks like an XDB xxx-xxx = " Error()) hohoho) Catch::(Catch Str("the" "se") if you can) (Echo("Caught this - " Int* " " UDim*) Continue::OnceAgain) Catch::"ThatsEnough" (Echo("Caught this - " Int* " " UDim*) End::OnceAgain) Catch::"TestFail" (Echo("Caught this - " Int* " but going to fail") FAIL) )) ) [xxx] Do(Echo("In xxx-" Int*) If({Int* = 2} Then::Throw("that,those,these,This" 23444)) If({Int* = 3} Then::Echo("XDB = " DBConnect(Dim:O DSN::Freddy))) If({Int* = 4} Then::Throw("TestFail")) If({Int* = 5} Then::Throw("ThatsEnough")) Echo(" still in xxx - " Int*) ) Eval [TryThrowExample] |
Generates the following output
|
line1 In boo-1 still in boo - 1 line2 line1 In boo-2 Caught this - 23444 THESE line1 In boo-3 Looks like an XDB boo-boo = [ODBCConErr] DBConnect() fail - ODBCCon err: State(IM002), Native(0), Msg=[Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified XDB = hohoho still in boo - 3 line2 line1 In boo-4 Caught this - 4 but going to fail oops line2 line1 In boo-5 Caught this - 5 THATSENOUGH V4> D:vicv3>xv4 trythrow V4 1.401 - "Data that thinks like us" (protected by U.S. Patent 6,470,490 - MKS Inc. - 2002) line1 In xxx-1 still in xxx - 1 line2 line1 In xxx-2 Caught this - 23444 THESE line1 In xxx-3 Looks like an XDB xxx-xxx = [ODBCConErr] DBConnect() fail - ODBCCon err: State(IM002), Native(0), Msg=[Microsoft]... XDB = hohoho still in xxx - 3 line2 line1 In xxx-4 Caught this - 4 but going to fail oops line2 line1 In xxx-5 Caught this - 5 THATSENOUGH |
Timer - Time the Evaluation of an Intersection or Schedule Future Context Point
| result = Timer ( v4point tagres ) | |
| result = Timer ( tagged arguments ) |
| result | Depends on the arguments | |
| v4point | The evaluation of this point (usually a quoted intersection or module) is timed | |
| tagres | One of the tagged results below |
| At::time | The time at which the Context point is to be inserted. If time is an integer or real number then it is treated as the number of seconds from now. If time is a universal date-time or calendar point then it is the actual (local) time of the insertion. If it is a UTime point then it is the hours-minutes-seconds from now. | |
| Context::point | The point to be inserted into the context. | |
| Id::point | A point identifying the timer entry. If no Id point is given then a unique point will be created. | |
| Value::type | Returns a value associated with a specific timer entry. If type is Delta then the number of seconds until the timer is triggered is returned. If the type is UDT then the local date-time of the trigger is returned. |
| ConnectTime? | Return the elapsed time required by the evaluation. | |
| CPUTime? | Return the actual CPU time required for the evaluation. | |
| ListOf? | Returns a list of all current timer id's. If no timer entries exist then an empty list is returned. | |
| Remove? | Removes the timer entry specified by the Id tag value. |
This module has two forms. The first is to time the evaluation of a binding. In this form, the first argument is a quoted binding to be timed. Optional remaining arguments specify whether wall-clock, cpu time or both times are to be returned. If no tagged result is specified then a list of both connect time and cpu is returned. If either of ConnectTime? or CPUTime? is given then only that time is returned.
The second form is used to specify the insertion of a point into the context at some future time. The insertion takes place within a separate execution thread independently of the main execution thread. Multiple timer entries are possible.
| Timer(@V4(Sleep::2)) | results in (Num:2.0043 Num:0) meaning 2 seconds (approximately) elapsed, 0 cpu seconds required | |
| Timer(@[Complex] CPUTime?) | results in Num:nnn.nn reflecting actual cpu time | |
| Timer(Context::alarm1 At::30) | specifies that the point NId:alarm1 is to be inserted into the context after 30 seconds | |
| Timer(Id::id1 At::UDT:9/23/14:13:30 Context::dim:value) | specifies that dim:value is to be added to the context at the given date-time | |
| Timer(Value::delta Id::id1) | returns the number of seconds remaining until the trigger identified as id1 is processed | |
| Timer(Id::id1 Remove?) | removes the timer entry |
Transform - Transform Point
| result = Transform ( point tagarg ) |
| result | The resulting transformed point. | |
| point | The point to be transformed. | |
| tagarg | One or more tagged arguments below. |
| All::isct | All values in the point are transformed by this evaluation. | |
| Dim::dim | Specifies a new dimension for the result. The default is the dimension of the first argument. | |
| First::isct | The first point in a range of values for the point is transformed by this evaluation. | |
| Last::isct | The last point in a range of values for the point is transformed by this evaluation. |
| First? | Return the first value in point. | |
| Last? | Return the last value in point. |
The Transform module can be used to alter or change the values of a point specification.
| Transform(UDate:5/20/98..7/10/98 All::DTInfo(UDate* UMonth?) Dim:UMonth) | UMonth:May-98..Jul-98 | |
| Transform(Int:100..200 First::Div(Int* 2) Last::Mult(Int* 3)) | Int:50..600 | |
| Transform(UDate:8/10/98 First::DTInfo(UDate* Month::1 Day::1)) | UDate:01-Jan-98..10-Aug-98 | |
| Transform(UDate:8/10/98 Last::DTInfo(UDate* Day::31)) | UDate:10-Aug-98..31-Aug-98 | |
| Transform(UDate:3/5/2002..5/1/2002 First?) | UDate:05-Mar-02 | |
| Transform(UDate:3/5/02..5/1/02 Last?) | UDate:01-May-02 |
Tree - Tree Manipulation
| value = Tree ( point tag ... ) |
| value | The result depends on the arguments. | |
| point | A dimension or point within an existing tree. | |
| tag | One or more tagged arguments below. |
| Bottom::bisct | Enumerate through the tree and evaluate the intersection bisct for each bottom (leaf) point within a tree. | |
| Child::cisct | Returns a list of all immediate children nodes that satisfy the conditional cisct. Each child node is inserted into the context and cisct is evaluated. If the result is TRUE then the node is included in the returned list. If no children are selected then an empty list is returned. If there are no children nodes then the module fails. | |
| Create::estmax | Create a new tree associated with the dimension specified in the first argument to the module. V4 uses estmax as the estimated maximum number of nodes in the tree. This is just a guideline, not a hard maximum. The return value is the new top-most point/node in the tree. Note that the dimension must be of point type Integer. | |
| Delete::nodespec | If nodespec is CHILD then all children of the current node are removed from the tree. If nodespec is NODE then the current node and all of its children are removed. If the node is the top node of the tree then the entire tree is deallocated from the current runtime environment. | |
| Depth::disct | Search the specified tree (or starting point within a tree) for one or more points such that the evaluation of disct returns TRUE. A depth-first search is performed and the first point satisfying the condition is returned unless the ListOf? argument precedes this argument. In this case a list of all tree points satisfying the condition are returned. | |
| Depth::dim | Updates dimension dim with the current depth of the tree for each node visited in an enumeration. This is used in conjunction with the Enter, Leave, Return, and Bottom arguments. | |
| Enter::eisct | Enumerate through the tree and evaluate the intersection eisct for each node as it is entered. If the node is a leaf (i.e. no children) and a Bottom argument has been given then eisct is not evaluated, only the Bottom:bisct intersection. | |
| Leave::lisct | Similar to the Enter argument except lisct is evaluated when the node is left. | |
| Left::num | Position to the node num nodes to the left of the current node. If num is 0 then position to the left-most sibling node of the current node. | |
| New::pos | Create a new node at the relative position pos to the current node. The allowed values for pos are- Child to create a child node relative to the current node. If the current point already has children then the new point becomes the right-most child, Left to create a node directly to the left of the current node. This fails if the current node is the top-most node of the tree, Right to create a node directly to the right of the current node. Again this fails for the top-most node, Parent to create a node directly above the current. | |
| Return::risct | Enumerate through the tree and evaluate the intersection risct when returning to a node with more than one child. | |
| Right::num | Position to the node num nodes to the right of the current node. If num is 0 then position to the right-most sibling node of the current node. | |
| Swap::node2 | Swap the current node with node2. The two nodes (and each node's children) swap positions within the tree. | |
| Value::point | Set the value of the current node to point. | |
| Width::wisct | Search the specified tree (or starting point within a tree) for one or more points such that the evaluation of wisct returns TRUE. A breadth-first search is performed and the first point satisfying the condition is returned unless the ListOf? argument precedes this argument. In this case a list of all tree points satisfying the condition are returned. |
| Child? | Return a list of all immediate children nodes relative to the current node. | |
| Create? | Create a new tree associated with the dimension specified in the first argument to the module. V4 assumes the tree will be small to modest in size (less than 100000 nodes). The return value is the new top-most point/node in the tree. Note that the dimension must be of point type Integer. | |
| Elevate? | Elevate the children of the current node to become children of the parent node. The current node is removed from the tree. | |
| Hash64? | Returns a 64-bit hash of the tree. If two trees have the same hash value then there is a very high likelyhood that the two trees are identical (although not necessarily the same tree). | |
| Left? | Position to the sibling node to the left of the current node. The module fails if the current node is the left-most node. | |
| ListOf? | Return a list of points in the tree using the current node as the starting point. This option may also be used with the Depth and Width arguments to return a list of all matching points. | |
| Nodes? | Returns the number of nodes currently in the tree. | |
| Parent? | Return the parent node of the current node. The module fails if the current node is the top-most node of the tree. | |
| Quoted? | Returns the value of the specified node. The value is returned as-is. (See the Value? option to force evaluation.) | |
| Remove? | See Remove::NODE. | |
| Right? | Return the node directly to the right of the current node. The module fails if the current node is the right-most node. | |
| Root? | Returns the root, or top-most node, of the tree. | |
| Value? | Returns the value of the specified node. If the value is an intersection or expression then it is evaluated first. (See the Quoted? option to prevent evaluation.) |
This module may be used to create one or more tree structures. Each tree is associated with a integer dimension. Points within the tree are integer points within the dimension. The root (top) of the tree is initially the dim:0 point on the dimension. All enumerations through a tree are left-to-right. A depth-first search starts down the left side of the tree and works its way to the right. A width-first search is left-to-right for each successive level of the tree.
New nodes may be created within the tree and consist of points on the tree's dimension. Any additional information to be associated with a node must be done with bindings incorporating the tree points.
The tagged arguments, Enter, Leave, Return, and Bottom may be used in combination or alone. Note that the Bottom argument overrides the other arguments for leaf nodes (those without children).
Any of the tagged arguments resulting in a single node may be chained. See the example below.
| Tree(TrDim:xxx Child? Right::0 Child?) | Returns the child of the rightmost child to the current node | |
| Dim Exp Int | Create an integer dimension | |
| Tree(Dim:Exp Create?) | Create a tree (returns Exp:0) | |
| [Exp:0 Oper] "*" | Assign an operator to the node | |
| [Exp:0 Func] "Times" | and a function name | |
| Context Add Tree(Exp:0 New::Child) | Add a child to the top node | |
| [Exp* Oper] "+" | Assign an operator and function to the child | |
| [Exp* Func] "Plus" | ||
| Context Add Tree(Exp* New::Child) | Create two children to this node | |
| [Exp* Value] 2 | First child value is 2 | |
| Context Add Tree(Exp* Parent? New::Child) | Create second child | |
| [Exp* Value] 5 | Second child value is 5 | |
| Context Add Tree(Exp:0 New::Child) | Create another child beneath root of tree | |
| [Exp* Oper] "-" | Assign operator and function | |
| [Exp* Func] "Minus" | ||
| Context Add Tree(Exp* New::Child) | Create two children to this node | |
| [Exp* Value] 7 | ||
| Context Add Tree(Exp* Parent? New::Child) | ||
| [Exp* Value] 1 | ||
| [Exp.. Infix] Exp.Oper | Define the "infix" operator | |
| [Exp.. Prefix] Exp.Func | and the "prefix" operator | |
| Tree(Exp:0 ListOf? Return::@Exp.Infix Bottom::@Exp.Value) | (Int:2 "+" Int:5 "*" Int:7 "-" Int:1) | |
| Tree(Exp:0 ListOf? Leave::@Exp.Func Bottom::@Exp.Value) | (Int:2 Int:5 "Plus" Int:7 Int:1 "Minus" "Times") | |
| Echo(`Tree(Exp:0 ListOf? Enter::@Str(Exp.Func "( ") Leave::")" Bottom::@Str(Exp.Value " "))) | Times( Plus( 2 5 )Minus( 7 1 )) |
Trig - Trigonometric Functions
| value = Trig ( tag tag ... ) |
| value | The numeric result. | |
| tag | Tagged arguments as described below. |
| Cos::npt | Specifies the cosine. | |
| Degrees::npt | Specifies the angle in degrees. | |
| Radians::npt | Specifies the angle in radians. | |
| Sin::npt | Specifies the cosine. | |
| Tan::npt | Specifies the tangent. | |
| X::npt | An x value. | |
| Y::npt | A y value. |
| ACos? | Return the arc cosine of the prior X or Cos tagged value. | |
| ASin? | Return the arc sine of the prior X or Sin tagged value. | |
| ATan? | Return the arc tangent of the prior X or Tan tagged value. | |
| ATan2? | Return the arc tangent of the prior Y and X tagged values based on the ratio of y / x. | |
| Cos? | Return the cosine | |
| CosH? | Return the hyperbolic cosine. | |
| Degrees? | Return the angle in degrees | |
| Radians? | Return the angle in radians. | |
| Sin? | Return the sine. | |
| SinH? | Return the hyperbolic sine. | |
| Tan? | Return the tangent. | |
| TanH? | Return the hyperbolic tangent. |
The various permutations of this module can be used to determine most of the trigonometric functions. For a historical overview of these functions visit this site.
| Trig(Degrees::90 Sin?) | Num:1 | |
| Trig(Radians::{3.14159 // 4} Cos?) | cosine of 45° - Num:0.707107250279226 | |
| Trig(Cos::0.707107250279226 Degrees?) | Num:45 (degrees) | |
| Trig(Sin::1 Degrees?) | Num:90 - same as Trig(X::1 ASin?) but with result in degrees, not radians | |
| Trig(X::2 Y::1 ATan2?) | Num:0.463647609 (the tangent of angle between lines from {0,0} to {0,x=2} and {0,0} to {x=2, y=1} |
Try - Evaluate Points with Exception Catching
| result = Try ( arg arg ... catcharg catchpt ... ) |
| result | The resulting point is the value of the last evaluated argument. | |
| arg | One or more points to be evaluated and/or tagged arguments below. | |
| catcharg | One or more Catch tagged arguments. | |
| catchpt | A point or list of points to be evaluated if the prior Catch argument is thrown and caught. |
| Catch::excpat | An exception pattern that consists of a string prefix followed by an asterisk. For example Catch::"XDB*" represents all exceptions starting with "XDB". | |
| Catch::excstr | The excstr specifies one or more exceptions to be caught. If multiple exceptions are given then they must be delimited with commas. |
This module takes the same arguments and performs almost identically to the Do module. It differs in that, after the argument points to be evaluated are one or more arguments with the Catch tag followed by the point to be evaluated.
The result of the last point evaluated is returned as the value of the Throw that generated the exception, or in the case of an internal error, the point that was being evaluated that resulted in the error. In all cases, control is returned to the point of the error after the exception handling finishes. Note however that the End? and Continue? values may be returned to immediately alter the normal flow of execution. The FAIL point (NOp(0)) may also be returned to cause the evaluation generating the exception to fail. The example given with the Throw module shows all these combinations.
See the documentation for Do for a complete list of options.
See the Throw module for instructions on throwing exceptions. See the V4 module's Throw option for instructions on enabling implicit exceptions when an internal V4 error occurs.
The following example evaluates two intersections- [Eval1] and [Eval2]. If any XDB errors occur then the EchoE() module is called. If either of the exceptions MyError or YourError are thrown then the GuiAlert is called and then [Retry] is evaluated. The result of evaluating [Retry] becomes the result of the Throw module throwing the exception.
|
Try( V4(Throw::(ODBCConErr)) [Eval1] [Eval2] Catch::"XDB*" EchoE("A fatal XDB error has been detected") Catch::"MyError,YourError" (GuiAlert("Looks like a problem") [Retry]) ) |