Echo - Output arguments to the Data Stream

Usage

	result = Echo ( message )
	result = Echo ( point point tag... )
	result = Echo ( Table::name point )

Parameters

	result	The result is always Logical:True
	point	One or more points to be output.
	tag	One or more of the tagged arguments below.

Tagged Arguments

	Buffer::name	Output the contents of the stream buffer name (i.e. buffer declared with Output(Buffer? Id:name)). The contents of the buffer are left intact. This option is also supported with the JSON and Javascript options.
	Include::file	The entire contents of file is included as output.
	Javascript::file	Output the contents file but process as if it were BigText with the 'Javascript' option.
	JSON::name	The arguments are formatted to the named JSON string. See below for examples.
	NoPrefix::name	Same as the Table tag except that output names do not incorporate any Prefix/Suffix given for the table.
	Out::id	Direct the output to the file or Stream specified by id. (See the Output module for details.) The scope of this redirection is limited to this Echo module.
	Table::name	Format an output line for each element in the specified name as defined by name.
	XML::text	Output the the specified text as opening XML/HTML section. The corresponding closing section is automatically added at the end of the output. If the text is 0 length then no begin/end tags are output. If the value is UV4:none then it is ignored.

Description

The Echo module echos each of its points to the device or file currently assigned to the Data stream followed by a newline character.

Note that the UV4:none point is not output.

Examples

Echo("Context value of Year* = " Year*)"

	Echo(XML::td "this is the cell value")	outputs: <td>this is the cell value</td>
	Echo(XML::"p align='center'" "A new paragraph...")	outputs: <p align=center>A new paragraph...</p>
	Enum(Student.. @Echo(Table::Student Student*))	for each point on the Student dimension outputs all columns in Student table
	Echo(JSON::bigArg Include::"hugefile.txt")	Output the entire contents of the file as a single JSON string named 'bigArg'

EchoA - Output an alert message to Standard Ouput

Usage

undef = EchoA ( point point... tagarg )

Parameters

	point	One or more points to be output.
	tagarg	One or more of the optional tagged arguments below.

Tagged Arguments

	Exit::status	The V4 process exits with the specified status integer number.
	URL::url	Defines a URL to be invoked after the alert is handled by the client web page. This option is only effective when output is directed through the xvrestohtml process. If this tagged url is not specified then the xvrestohtml process will return to the prior page after the error pop-up window is acknowledged by the client user.

Description

The EchoA module concatenates its argument points and generates an alert using the result. It does not return a value.

If stdout has been redirected to a file and this module is called then the error message is also sent to the output file. The format of this output is such that all backend processors (Excel addin, converters to HTML, converts to BIFF) will properly interpret and handle the alert.

Examples

EchoA("The server process has been restarted")

EchoD - Output Debugging Results to the Debug Stream

Usage

undef = EchoD ( point point ... )

Parameters

	undef	All of the Echo modules return an undefined value.
	point	One or more points to be output.

Description

The EchoD module echos each of its points to the device or file currently assigned to the Debug stream followed by a newline character. Output points are delimited by a single space. EchoD differs from the other output modules in two ways. First, the output is always to the Debug stream (not the Data stream). Secondly, it always shows each point as a dimension:value pair.

Note - this module never fails. The module evaluates and outputs its arguments one at a time. If the evaluation of an argument fails then a short string is output indicating that the argument failed. See below for an example.

Examples

	EchoD("Context value of Year* =" UYear*)	outputs "Context value of Year" = UYear:yyyy*
	EchoD(123 hohoho Fail("A failure message"))	outputs "123 hohoho ?3:Fail(A fai"

EchoE - Output error message to Standard Ouput

Usage

undef = EchoE ( point point... tagarg )

Parameters

	point	One or more points to be output.
	tagarg	One or more of the optional tagged arguments below.

Tagged Arguments

	Exit::status	The V4 process exits with the specified status integer number.
	URL::url	Defines a URL to be invoked after the error is handled by the client web page. This option is only effective when output is directed through the xvrestohtml process. If this tagged url is not specified then the xvrestohtml process will return to the prior page after the error pop-up window is acknowledged by the client user.

Description

The EchoE module concatenates its argument points and generates a V4 error using the result. It does not return a value. It increments the internal error count by 1 (see Error(Count).

Examples

EchoE("Sorry, you are not allowed to access this analysis")

EchoP - Output arguments to the Data stream (without Newline)

Usage

result = EchoP ( point point tag... )

Parameters

	result	The result is always Logical:True
	point	One or more points to be output.

Description

The EchoP module echos each of its points to the output console but unlike Echo without the terminating newline.

EchoT - Outputs Tab (or other string) Delimited Arguments to Standard Ouput

Usage

result = EchoT ( point point tag... )

Parameters

	result	The result is always Logical:True
	point	One or more points to be output.
	tag	One or more of the tagged arguments below.

Tagged Arguments

	Column::delim	Use the string delim as the argument (column) delimiter instead of the tab character.
	If::logical	Output only if logical evaluates to true. If logical is false then EchoT does not output anything (see Discussion below). Note however that any totaling for recapping (RCV) is still performed. This option can be used to control the level of output detail for reporting.
	Out::id	Direct the output to the file specified by id. (See the Output module for details.)
	RCV::logical	If false then the all following arguments are NOT included in row-column totaling. If true then following arguments are included. Normally arguments are included.

Description

The EchoT module echos each of its points to the output console followed by a newline character. Each point is separated from the others with a tab character. Output from this module can be imported into many spreadsheets and databases.

This module processes its arguments from left to right. Tags are processed with all other arguments. Tags such as If should be the first arguments to be effective.

If an argument is UV4:none then it is ignored.

Examples

	EchoT(Student.Name Student.Advisor Student.GPA Student.Course)	Output four columns, one for each argument
	EchoT(Column::"," Now is the time)	Outputs "Now,is,the,time"

EchoW - Output warning message to Standard Ouput

Usage

undef = EchoW ( point point... tagarg )

Parameters

	point	One or more points to be output.
	tagarg	One or more of the optional tagged arguments below.

Tagged Arguments

	Exit::status	The V4 process exits with the specified status integer number.
	URL::url	Defines a URL to be invoked after the warning is handled by the client web page. This option is only effective when output is directed through the xvrestohtml process. If this tagged url is not specified then the xvrestohtml process will return to the prior page after the error pop-up window is acknowledged by the client user.

Description

The EchoW module concatenates its argument points and generates a warning using the result. It does not return a value. The Error module can be used to see the warning count and last warning message.

Examples

EchoW("Nothing was selected for the report")

Enum - Enumerate Points and Execute

Usage

	respnt = Enum ( list eval tagval )
	value = EnumX ( arguments same as Enum )

Parameters

	respnt	This module normally returns the last point evaluated (except with the Then tag)
	list	A list to be enumerated.
	eval	A point to be evaluated for each point in list. This may be a quoted intersection or a list, in which case each point in the list is evaluated. The Do tag may also be used to denote the eval point.
	tagval	Optional tagged arguments described below.

Tagged Arguments

	After::(pt action)	V4 evaluates pt for every point in the Enum list. If the evaluation of pt changes from one point to the next, then V4 evaluates action after the list point has changed but before the Enum eval is evaluated. The After argument is primarily used to set up headers for the next group of points.
	AWhile::isct	The isct is evaluated after each point in the list (as opposed to If::isct). If the result of the evaluation is Logical:False then Enum terminates.
	Before::(pt action)	This is similar to the After argument except that the action is evaluated before the context has changed to the new point. The Before argument is used primarily to output recapping for the prior point.
	Begin::(pt action)	Before the first point in list is processed, the action associated with this Before argument is evaluated if pt is or evaluates to Logical:True. This can be used to set up titles.
	By::pt	If this tag is given then this module is treated as if it were a Sort module call.
	Calc::int	If the argument is an integer then this specifies the maximum number of Calc values allowed. The default is 4, the maximum is 100.
	Calc::isct	The isct is evaluated for each point in the Enum list and the result is added into the first calc value used by RCV.
	Calc::list	Each value of list is evaluated for each point in the Enum list and the results are added into the calc values used by RCV.
	Columns::int	Defines tha maximum number of columns allowed with nested RCV calls. The default is 100, the maximum is 2048.
	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.
	Do::eval	An alternative way to specify the point to be evaluated.
	End::(pt action)	The action associated with this After argument is evaluated after the last point in the Enum list if pt is or evaluates to Logical:True. This can be used to output grand totals in conjunction with the RCV module.
	Enum::sublist	Nests another level of enumeration within the Enum (i.e. every element in sublist is enumerated for each element in the major list of the Enum
	Every::num	Groups points in the Enum list in sub lists of num points. This sub list is then added to the context and processing proceeds normally. See below for an example.
	First::isct	If specified then isct is evaluated for the first point instead of eval.
	Id::string	The string value is used as an identifier for trace/debugging output. It may also be used with the processing of Continue and End tag points. (see below)
	If::isct	isct is evaluated for each point in the list. If the result is true, then Enum continues processing the point. If false then Enum immediately goes to the next point in the list.
	IfOnce::isct	isct is evaluated for each point in the list. If the result is true, then Enum processes the point and then immediately terminates.
	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.
	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.)
	Last::isct	If specified then isct is evaluated for the last point instead of eval.
	NestRCV::logical	Normally each Enum creates a new set of totals for the RCV module. If this tag is specified as TRUE then this Enum will not create a new set of totals but use the same set as the parent Enum.
	None::isct	If no points of the list are selected, because of If's or the list is empty then the isct is evaluated.
	Num::num	Iterate through the Enum num times. No list is required if this argument is given. If a list is specified then this tag can be used to limit process to the first num elements of the list.
	Parent::isct	The isct is evaluated for each point in the Enum list and placed into the current context. The point is saved internally for use with the PIf argument below. If subsequent points in the Enum result in the same evaluation of isct then the last result of the PIf is used to accept or reject the point.
	PIf::test	The test intersection is tested each time the isct in the Parent argument changes. If the result is true then the Enum continues with its current point. If the result is false then the Enum point is rejected and the next point is obtained. The results are saved for use with the Parent argument above.
	Recap::int	Specifies the maximum number of nested RCV recap levels allowed. The default is 4, the maximum is 32.
	Reverse::pt	If this tag is given then this module is treated as if it were a Sort module call.
	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. See discussion below for more on this option.
	Skip::num	Skip the first num elements of the list. This can be usefull when debugging.
	Sum::pt	The point pt is evaluated for each point in the list. For the first point in the Enum list, the result of evaluating pt is added to the context. For each subsequent point in the Enum list, the result of evaluating pt is added to the value currently in the context. If pt is a list then this process occurs for each point in it. This option can be used to keep running sums of values.
	Then::point	If this tag is specified, then the first valid point (considering If, While, etc. points) does not continue with normal processing but the point is evaluated and returned as the result.
	Try::isct	Evaluation of isct is attempted for each point in list. Processing stops with the first successful evaluation of isct and the result is returned as the value of the Enum. Note that the evaluation of [UV4:IsctFail] does not occur if the isct does not evaluate.
	Until::isct	isct is evaluated for each point in the list. If the result is false, then Enum continues. If it is true, Enum immediately stops processing the point and all subsequent points.
	While::isct	isct is evaluated for each point in the list. If the result is true, then Enum continues. If it is false, Enum immediately stops processing the point and all subsequent points.
	XML::value	Specifies the XML tag to enclose all iterations of the Enum. If value isa 0-length string then no begin/end tags are output. If the value is UV4:none then it is ignored.

Tagged Results

Pop?

When this tag is specified, V4 will pop off the context frame after processing each point in the enumeration. This option should be considered if points of differing dimensions are being enumerated. In this case, a point may unknowingly remain in the context and the Pop? option is the only way to ensure that a single enumeration point resides in the context at a time.

Description

Enum enumerates through the list of points defined by the first argument. Each point in the list is added to the context and then the intersection eval is evaluated. Enum simply evaluates the second argument and in effect discards the resulting points.

The order of the tagged arguments is important as they are processed from left to right for each point in the source list. For example, if the Index tag is specified before an If tag then the index dimension is incremented regardless of the results of the If. If the Index is after the If then it is only incremented when the results of the If are true. A tag may be specified more than once. An Index tag may given both before and after an If tag (with different dimensions).

Normally each numerated point is evaluated if it is an intersection (or module). However when a Shell dimension is given then no evaluation is performed. The points are inserted into the context as-is.

This module alters its normal processing flow whenever a Continue or End point is evaluated. If a Continue point is detected then the Enum processing terminates immediately and the value of the module becomes the Continue point. If an End? point is detected then the module immediately terminates and returns the list entry index last processed. If an End::name point is detected and this name matches the module's Id name then again, the module terminates returning the last index processed. If the name does not match then the module terminates and returns the End::name point as its result.

Examples

	Enum([DeptList] @[DeptReport Dept*])	Enumerates through all points in [DeptList] and evaluates [DeptReport Dept] for each one*
	Enum(Student.. If::{Student.Id = Id} Then::Student)	Enumerates through the Student dimension until a point is found where Student.Id equals the current id. The Student point is then returned as the value.
	Enum(Cus.. If::{Cus.YearlySales >= 150000} @EchoT(Cus.Id .Name .YearlySales))	Echos all customers with YearlySales of at least 150000.
	Enum(Int:1..5 Enum::(a b c) @EchoT(Int* NId*))	Outputs "1 a", "1 b" ... "5 c"
	Enum(Num::10 Index::Dim:Int @Echo(Int*)	outputs 1, 2, ... 10
	Enum(Num::10 Index::101 @Echo(Int*)	outputs 101, 102, ... 110

Enum(SalesDetail.. If::{SalesDetail.Sales.ShipTo.State = State:PA}

@Do( ... ))

Enumerates through all sales detail (line item detail) selecting those shipped to State:PA (via link to Sales to ShipTo customer to State)

If the SalesDetail points are grouped by Sales group then a much more efficient method would be to use the Parent/PIf arguments-

Enum(SalesDetail.. Parent::SalesDetail.Sales PIf::{Sales.ShipTo.State = State:PA}
@Do( ... ))

The example below demonstrates the use of the Every tagged option. The dimension UMonth is typically set to a large number of months. The Every::6 option in the Enum breaks off the months into chunks of 6, creates a temporary point on the List dimension and adds it to the current context. Each of the following EchoS calls then reference the List* to generate values for six columns, one for each month in the grouping.

Example 27 - Example of the Every Tag

[RevExp UMonth..]
Do(Enum(UMonth* Every::6
        (EchoS("" (UMonth* UMonth*)/List*)
         EchoS("Plane" ("Hours" "Rate")/List*)
         Enum(PlId* @EchoS(PlId* ([Hours],[EHExpHours] [HourlyRate],"")/List*))
         EchoS("Revenue" EnumCL(List* (Sum({[Hours],[ExpHours],0 * [HourlyRate],0}/PlId*) "")))
         EchoS()))
   )

EnumCL - Enumerate Points, Execute & Return List

Usage

	reslist = EnumCL ( list eval )
	reslist = EnumCL ( eval / list )

Parameters

	reslist	The resulting list of points from evaluating eval for each point in list.
	list	A list to be enumerated.
	eval	An intersection (quoted) to be evaluated for each point in list.

Tagged Arguments

	Agg::area	Include the specified aggregate area as part of the processing of this module call and remove the area from the runtime context when the processing has completed. area may be a single file specification or a list of file specifications.
	Column::num	Set the default column to num. This is used primarily with the RCV module to initialize to a starting column.
	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.
	Dim::dim	Specifies the dimension of the resulting list. The default is Dim:List. Obviously dim must be of point type List.
	Do::eval	An alternative way to specify the point to be evaluated.
	Enum::list	Multiple sets of input lists may be incorporated into a single EnumCL call. This tag is used to end the prior list and begin a new list. Note that all selection, index, context, etc. tags are reset and must be respecified after this tag.
	First::isct	If specified then isct is evaluated for the first point instead of eval.
	If::isct	The intersection is evaluated for each point in the list. If the result is true, then EnumCL continues processing the point. If false then Enum immediately goes to the next point in the list.
	IfOnce::isct	The isct is evaluated and if the result is True then no further processing is performed on the current list point and processing for the next point is immediately obtained and processed.
	Ignore::point	If the current value is equal to point then ignore it, i.e. do not include it in the resulting list. This option is useful for eliminating bad or failed values from the result.
	Index::dim	The dimension dim is added to the context of the EnumCL and set to the current count as the points in list are enumerated, i.e. dim* references 1 through the number of points in list.
	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.
	Last::isct	If specified then isct is evaluated for the last point instead of eval.
	None::isct	Evaluate isct if no points are selected for output. Multiple None tags may be given, and each one within an Enum group is evaluated. If multiple Enum segments are present then any None tags specified are within the scope of that Enum. In other words, each segment is processed separately, and not cumulative across segments.
	Num::max	Limit the number of points to max. The effect of this depends on the placement of the argument. If it is placed before any conditional arguments then the effect is to limit the number of points from the source list. If it is after any conditionals and immediately before the output specification then the effect is to limit the number of resulting points. The Num option may be used more than once.
	Num::num	Evaluate eval num times. A source list is optional with this parameter.
	Parent::isct	The isct is evaluated for each point in the Enum list and placed into the current context. The point is saved internally for use with the PIf argument below. If subsequent points in the Enum result in the same evaluation of isct then the last result of the PIf is used to accept or reject the point.
	PIf::test	The test intersection is tested each time the isct in the Parent argument changes. If the result is true then the Enum continues with its current point. If the result is false then the Enum point is rejected and the next point is obtained. The results are saved for use with the Parent argument above.
	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.
	Sum::pt	The point pt is evaluated for each point in the list. For the first point in the EnumCL list, the result of evaluating pt is added to the context. For each subsequent point in the EnumCL list, the result of evaluating pt is added to the value currently in the context. If pt is a list then this process occurs for each point in it. This option can be used to keep running sums of values.
	Until::isct	The intersection is evaluated fo reach point in the list. Processing continues until the result evaluates to True (this is the converse of the While tag).
	While::isct	The intersection is evaluated for each point in the list. If the result is true, then Enum continues. If it is false, Enum immediately stops processing the point and all subsequent points.

Tagged Results

	Collapse?	If any of the elements of list are also lists then force each point within the list into the context rather than the list point itself.
	Evaluate?	Normally the eval point is evaluated once for each point in list. If the result is an intersection or special point (e.g. dim) then it is appended, as is, into the resulting list*. The Evaluate? tag can be used to override this default and force an additional evaluation.
	Lazy?	Normally EnumCL performs the necessary calculations when invoked and returns the resultant list. When Lazy? is specified, the module immediately returns with a lazy-list internal structure. Points on this lazy-list are then obtained and returned point-by-point on an as-needed basis. See below for more discussion.
	Pop?	When this tag is specified, V4 will pop off the context frame after processing each point in the enumeration. This option should be considered if points of differing dimensions are being enumerated. In this case, a point may unknowingly remain in the context and the Pop? option is the only way to ensure that a single enumeration point resides in the context at a time.
	SetOf?	If this argument is given then EnumCL returns a set of points, not a list. A set contains no duplicate points.

Description

EnumCL enumerates through the list of points defined by the first argument. Each point in the list is added to the context and then the intersection eval is evaluated. EnumCL creates a list of the points resulting from the repetitive evaluation and returns that list as its result.

A one-to-many mapping from source point to resulting point is possible by specifying multiple resulting points and/or Do arguments-

EnumCL(Int:1..5 @{int* + 100} @{int* * int*})

returns (101 1 102 4 103 9 104 16 105 25)

The Enum may be used to process one or more additional sets of source points. Additional Enum points may be different dimensions. For example if current sales are 'stored' in the Dim:Sales dimension and historical sales are store by customer in the Dim:CusHist dimension, then a list of all sales for a particular customer could be obtained with-

EnumCL(Sales.. If::{Sales.Customer = Customer*} @Sales.Amount Enum::CusHist.. If::{CusHist.Customer = Customer*} CusHis.Amount)

Use of the Lazy? option is recommended when the module is to be used in conjunction with the DotDotToList dimension attribute. Consider the example below-

	Dim Sales AggRef DotDotToList	declare a dimension
	[Dim:Sales UV4:DotDotToList] EnumCL(MakeP(Dim:Sales) If::{some test})	define 'all' points on the dimension
	Tally(Sales.. If::{some other test} ...)	perform a tally on Sales.. with further testing

In the above example, V4 makes a complete pass through the Sales dimension, selects a subset and creates a temporary list when [Dim:Sales UV4:DotDotToList] is evaluated. The Tally module then enumerates through that list and does its own sub-selection. This example makes two passes through the Sales aggregate information and creates an extra list.

The example below is similar except that the EnumCL uses the Lazy? attribute. In this case, the evaluation of [Dim:Sales UV4:DotDotToList] does not make a pass through the Sales aggregates. It just creates a structure that can be later referenced. The Tally module uses this internal structure to scan through the aggregate information. In this example, only one pass is performed and no temporary lists are required.

	Dim Sales AggRef DotDotToList	declare a dimension
	[Dim:Sales UV4:DotDotToList] EnumCL(MakeP(Dim:Sales) If::{some test} Lazy?)	define 'all' points on the dimension
	Tally(Sales.. If::{some other test} ...)	perform a tally on Sales.. with further testing

Note that the slash (/) can be used instead of the module name. The form is eval/list. See below for examples.

Examples

	Sum(EnumCL(Cus.. @[YearlySales Cus* Year*]))	returns the sum of yearly sales for all customers for the current year
	EnumCL(Int:1..10 @Month.Format)	results in a list of Month.Format evaluations for the integer 1 to 10
	Month.Format/Int:1..10	is identical to the above example
	EnumCL(Int:1..100 Num::50 If::{Int* > 48} Num::5)	(49 50)
	EnumCL(Int:1..100 If::{Int* > 48} Num::5)	(49 50 51 52 53)

EQ - Equality Test

Usage

	logical = EQ ( pt1 pt2 )
	logical = EQk ( tp1 pt2 )
	res = EQ ( pt1 pt2 trueval falseval )

Parameters

	logical	Logical:TRUE or FALSE depending on the result of the comparison.
	pt1	Any point.
	pt2	Any point.
	res	The value of trueval if pt1 equals pt2, otherwise the value of falseval.
	trueval	The value returned if the two points are equal.
	falseval	The value returned if the two points are not equal.

Description

EQ compares two points and returns true only if the points are identical - both dimension and value. EQk, or EQual-Kindof, returns true if two points have the same value, but not necessarily the same dimension.

See Real for details on comparing floating point numbers.

Examples

	EQ(Int:100 Real:100	Logical:FALSE
	EQk(Int:100 Real:100	Logical:TRUE
	EQ(Int:3 Int:4 Yes No)	Alpha:No

Error - Manipulates and Accesses the V4 Global Error Code

Usage

respnt = Error ( tag... )

Parameters

	respnt	The result is determined by the tagged arguments.
	tag	One or more of the tagged arguments below.

Tagged Arguments

	Count::num	Sets the V4 error count to num.
	Drawer::dpoint	Inserts the last recorded error message into the Drawer specified by dpoint.
	ListOf::option	Returns a list of error information. If option is CONTEXT then the saved context at the time of the error is returned. If option is STACK then the execution frame stack at the time of the error is returned. Each frame consists of a list of three elements: the error message, the source file and the line number within the source file of the error. Note that this option is only valid after an error dump is output (see discussion below).
	Message::text	Sets the last recorded error to text.
	Warning::num	Sets the warning count to num.

Tagged Results

	Count?	Returns the current V4 error counter.
	Error?	Returns, as a point on Dim:Alpha, the last recorded error message. If no error has been recorded then an empty (zero-length) string is returned. The last recorded error is also returned when this module is called with no arguments.
	Intersection?	Returns, as a point on Dim:Alpha, an image of the intersection that generated the last recorded error message. If no error has been recorded then an empty string is returned.
	Module?	Returns, as a point on Dim:IntMod, the module generating the last recorded error.
	Reset?	Resets (clears) the last recorded error. It also resets the global process error counter to 0. The If Errors command references this error count.
	Warning?	Returns list: (number-of-warning last warning message).

Description

An error within V4 often results in a cascade of subsequent errors as the error failure propagates upward through the nested call frame stack. A high-level error handler written in V4 has the problem of determining what the error actually is and what triggered it. To help in this determination, the V4 runtime keeps a single error message string which it updates whenever an error occurs and the message string is empty. This module allows the user to reference the message string, reset it and explicitly set it.

The 'last recorded error' is automatically cleared under two conditions. In each of the following two conditions the 'last recorded error' must not already be set. The first condition is when an intersection fails but the continued point (i.e. [failed intersection],continuedpoint) succeeds. The second is when the first argument of the Def (or DefQ) module fails. The Reset? tag is used to explicitly clear the error.

This module may also be called with no arguments. Error() is identical to Error(Error?).

Untrapped errors result in an error dump. This consists of a list of all nested stack frames and the context at the time of the error. The information generated by this dump is saved and may be later retrieved with the Error(ListOf::option) call. An error dump may also be triggered with the use of '?' after a module name.

Examples

	Error()	returns the last recorded global error as a point on Dim:Alpha.
	[doThis],Do(? [recoverFromError])	If [doThis] fails then an error dump is generated (?) and [recoverFromError] is evaluated

Eval - Evaluates Intersection and Returns One or More Results

Usage

value = Eval ( isct Tag )

Parameters

	value	The value is determined by the tagged arguments.
	isct	An intersection (quoted) to be evaluated.
	tag	One or more of the tagged arguments below.

Tagged Arguments

	Nest::logical	If true (default) then nest (or chain) all evaluations (i.e. if the isct results in another intersection or V4 module then evaluate it). If false then return the first value without chaining.
	Nth::num	Return the num^th value resulting from the evaluation of isct. A value of 1 returns the best value and is identical to evaluating isct outside of this module. A value of 2 returns the second best value, etc.

Tagged Results

	All?	Return a list of all possible values resulting from the evaluation of the isct in the current context.
	ListOf?	Identical to the All? tag.
	MatchUndef?	Tells the V4 evaluator to allow matching if a point is not in the current context (i.e. is a dimension is not in the context then 'dim..' is assumed to be in the context).

Description

This module permits the user to choose which of the possible values to use from the evaluation of an intersection.

Examples

	Dim A,B,C,D Int	declare 4 new dimensions
	[Foo A:1] Now	Create bindings for each of them
	[Foo B:2] Is
	[Foo C:3] The
	[Foo D:4] Time
	[Foo A:1 B:2 C:3] "for all good men"	Define a binding using combination of dimensions
	Eval Context(A:1 B:2 C:3 D:4)	Add four points to the current context
	= [Foo]	returns "for all good men"
	= Eval(@[Foo] All?)	returns ("for all good men" NId:Time NId:The NId:Is NId:Now)
	= Eval(@[Foo] Nth::3)	NId:The
	[BestPrice Cus.. IM..] Minimum(Eval(@[Price Item* Cus*] All?))	Calculates the best price of an item for a customer by taking the minimum of all possible prices of that item for that customer
	[Square Int..] {Int* * Int*}	Define a binding to calculate squares
	Eval(@[Squares Int:{sample}] Nest:Logical:False)	returns {Int * Int} - i.e. the NON-chained-evaluation value of the binding

EvalAE - Evaluate Arithmetic Expression

Usage

nvalue = EvalAE ( string tag )

Parameters

	nvalue	The resulting number calculated by the module.
	string	A string containing an arithmetic expression to be evaluated.
	value	A value returned if the first argument is not a string.
	pt	A non-string point.

Tagged Arguments

	Dim::dim	An optional dimension name, the result is returned as a point on this dimension. If a dimension is not specified then Dim:Int is assumed.
	Point::point	An optional point to be used in evaluating expression values. If not given then UV4:EvalAE is assumed.
	Problem::logical	If logical is TRUE then the module does not evaluate an expression but checks or validates each component of the expression. It does this by evaluating [UV4:EvalAEVal component] for each component. If the value of the intersection is a string then it is assumed to be an error string and that string is returned as the result of the EvalAE module. If no problems are detected then EvalAE fails (see example below).

Tagged Results

Problem?

Identical to Problem:Logical:True.

Description

This module parses the components of string as a mathematical expression, evaluates each component and then performs the specified operations. The allowed components are:

	integers	integer numbers such as 100, -123
	real	real numbers such as 100.00, 0.9876, 12e10
	intersections	any valid intersection enclosed in brackets
	points	any valid V4 point. The value of a point is taken by inserting the point into an intersection of the form [UV4:EvalAE point] (or whatever Point was specified). If the point specifies multiple points then the sum of each evaluated intersection is taken (see example below).
	points in context	any valid V4 point followed by '\|\|' and then a context point (or list)
	operators	the arithmetic operators: + - / // % ( )*

If the first argument is not a string then EvalAE becomes MakeP and simply converts its first argument to the dimension specified by the second argument according to the semantics of MakeP.

Examples

EvalAE("[UsageFactor] * (GL:5000..5005 + SchAE:Total)" Dim:Int )

The above expression would be calculated as {[UsageFactor] * Sum([UV4:EvalAE GL*]/GL:5000..5005) + [UV4:EvalAE SchAE:Total]}

EchoE("Problems in expression: " EvalAE(Alpha* Problem?)),ok

Checks the expression in Alpha* for problems and generates error message if any found

EvalBL - Return Binding Points as List

Usage

binding = EvalBL ( isct tagargs )

Parameters

	binding	A list of points corresponding to the binding matched in the evaluation of isct.
	isct	An intersection (quoted) to be evaluated.

Tagged Arguments

	Nth::num	Return the list of points associated with the num^th best match. If num is 1 (default) then the best match is used.
	Number::num	Returns the list of points associated with the first thru num^th matches. Points appearing in more than one intersection are NOT duplicated.

Tagged Results

MatchUndef?

Tells the V4 evaluator to allow matching if a point is not in the current context (i.e. is a dimension is not in the context then 'dim..' is assumed to be in the context).

Description

The EvalBL module evaluates its argument which must be a quoted intersection. If the evaluation fails then EvalBL also fails. If the evaluation succeeds, EvalBL returns, as a list, all of the points that were matched during the evaluation. This can be used to determine exactly what points were involved in an evaluation even when context points are used.

Examples

Bind [Square Int:2] Int:4
Context Add Int:2

	EvalBL(@[Square])	returns (NId:Square Int:2)
	EvalBL(@[Cube])	fails because evaluation of [Cube] is undefined
	EvalBL(@[xxx] MatchUndef? Number::5)	returns a list of points of the first 5 intersections containing xxx (assuming the context is empty)
	EvalBL(@[xxx] MatchUndef? Nth::5)	returns a list of points in the 5th intersection
	EnumCL(Int:1..99 While::{ListSize(Context(EvalBL(@[xxx] MatchUndef? Nth::Int),())) > 0} @List)	returns a list of lists, each sub list being the points in an intersection

EvalCmd - Execute V4 Interpreter Command

Usage

true = EvalCmd ( command tag )

Parameters

	true	returns Logical:True if the execution of the command succeeds. The module fails an error occurs while executing the command.
	command	An alpha string to be executed as a V4 command. Multiple arguments are concatenated into a single string.

Tagged Results

Echo?

The V4 command is output to the status stream before it is evaluated by the V4 interpreter.

Description

The EvalCmd module passes its string argument to the V4 interpreter for execution as a V4 command.

Examples

	EvalCmd("Area Read DataAgg Aggregate")	Open DataAgg.v4a as read-only aggregate
	[DataFileName] "DataAgg"	Bind value to intersection
	EvalCmd("Area Read " [DataFileName] " Aggregate")	Same as above

EvalLE - Evaluate a BitMap Expression

Usage

	reslist = EvalLE ( string )
	reslist = EvalLE ( dimpt string )

Parameters

	reslist	returns a list (bitmap) based on the string argument.
	dimpt	A point on the Dim dimension.
	string	A string expression.

Tagged Arguments

Problem::logical

If logical is TRUE then the module does not evaluate an expression but checks or validates each component of the expression. It does this by evaluating [UV4:EvalLEVal component] for each component. If the value of the intersection is a string then it is assumed to be an error string and that string is returned as the result of the EvalLE module. If no problems are detected then EvalLE fails (see example below).

Tagged Results

Problem?

Identical to Problem:Logical:True.

Description

EvalLE is similar to EvalAE in that it parses and evaluates a string expression. Instead of returning a numeric result, EvalLE returns a list of points. Identifiers in the string expression are evaluated with the point UV4:EvalLE. The supported operators are & for logical and, | for logical or, ~ to complement (not), and - for logical/set subtraction. The logical and operator is implied between two consecutive identifiers.

If an identifier appears with the '*' suffix then it is evaluated with UV4:EvalLEStar. This allows the routine to treat star-ed entries as a range of maps to be logically or'ed together.

If the first argument to this module is a point on the Dim dimension then that dimension will be assumed for all points not explicitly assigned to a dimension. Points normally assumed to be on the NId dimension will be assigned to the given dimension.

Examples

	EchoE("Problems in expression: " EvalLE(Alpha* Problem?)),ok	Checks the expression in Alpha for problems and generates error message if any found*
	EvalLE("State:PA Available:Yes (Type:Med \| Method:1)")	identical to..."

List([UV4:EvalLE State:PA] Intersect::[UV4:EvalLE Available:Yes]
Intersect::List([UV4:EvalLE Type:Med Union::[UV4:EvalLE Method:1]))

	EvalLE("Author:King* & Title:Day")	with the proper handlers (see below) would return a list of all authors starting with "King" and containing "Day" in the title
	EvalLE(Dim:Title "Author:King* & Day")	identical to the prior example (i.e. Day is taken to be Title:Day, not NId:Day)

Dim Author Alpha
[UV4:EvalLE Avail..] Do(V4ISOp(V* KeyNum::1 Key::Str("AUT" Author* UC?)) V4ISVal(V* Dim:BM 2))
[UV4:EvalLEStar Author..]
List(`EnumCL(List(V* KeyNum::1 First::V4ISOp(V* KeyNum::1 Get::KeyedPartial Key::Str("AUT" Author* UC?)) While::Str(V4ISVal(V* Dim:Alpha 1) Head::Str("AUT" Author*)))
First::V4ISVal(V* Dim:BM 2) @MakeP(Tag:Union V4ISVal(V* Dim:BM 2))))
Dim Title Alpha
[UV4:EvalLE Title..] Do(V4ISOp(V* KeyNum::1 Key::Str(" " Title* UC?)) V4ISVal(V* Dim:BM 2))
[UV4:EvalLEStar Title..]
List(`EnumCL(List(V* KeyNum::1 First::V4ISOp(V* KeyNum::1 Get::KeyedPartial Key::Str(" " Title* UC?)) While::Str(V4ISVal(V* Dim:Alpha 1) Head::Str(" " Title*)))
First::V4ISVal(V* Dim:BM 2) @MakeP(Tag:Union V4ISVal(V* Dim:BM 2))))

EvalPt - Concatenates Arguments, Parses, and Evaluates as V4 Point

Usage

res = EvalPt ( arg1 arg2 ... )

Parameters

	res	The point resulting from the evaluation of the argument point.
	arg1	One of any number of points to be concatenated into a single point specification.

Tagged Arguments

Token::str

Treats the str as if it were a single token (see examples below).

Tagged Results

Optimize??

After parsing the point, V4 optimizes in the same way that the Do Optimize? option does.

Description

This module takes all of its arguments, concatenates them into a single string, parses the string as a V4 point, and then evaluates that point. The result of the evaluation is returned as the value of the module.

Note - be very careful using this module with input from an untrusted source. If the resulting string is a V4 module then that module will be invoked. The use of this module with input from a web source is not recommended.

Examples

	EvalPt("UDate" "*")	returns the current value of Dim:UDate (i.e. UDate)*
	Context Add "Salary"	Adds Alpha:"Salary" to context
	EvalPt(Alpha* "*")	Creates string "Salary" and evaluates as V4 point*
	EvalPt("[Emp." Alpha* "]")	Creates string "Emp.Salary" and evaluates
	EvalPt("Alpha:" "now is the time")	creates the point Alpha:"now" (characters after first space are ignored)
	EvalPt("Alpha:" Token::"now is the time")	creates the point Alpha:"now is the time"