Miva Merchant Empresa/Mia/Script Compiler v5.18 Release Notes
-------------------------------------------------------------
Bugs Fixed
----------
10177: Builtins: string: gettoken() fails to retrieve tokens after an ASCII NULL when NULLs are contained in the "string" parameter
10281: Builtins: system: miva_array_next/previous return incorrect values when asked for the next/previous element of a non-existent array element
10323: Builtins: system: miva_variable_value returns fatal error when variable name contains "[]"
10415: Builtins: system: miva_array_search does not provide any information when an invalid filter expression is provided
10065: Builtins: template: mvt:if with empty expr results in a stack underflow at runtime
10414: Compiler: Nested MvFOREACH that reuses an index from a previous version results in incorrect looping
10503: Compiler: Nested MvFOR that reuses an index from a previous version results in incorrect looping
10151: Diagnostic Application: Directories are not properly identified during the Script Directory Contents test if diag6.mvc is in a subdirectory
10327: Miva Mia: s.remote_host does not behave like other variables
9701: MivaSQL: MvOPEN errors cause the internal connection context to be leaked
9708: MivaSQL: Invalid read of size 1 when DATABASE is an empty string
9694: MySQL Connector: Frequent crashes at address 0x0001fbf3 in MVDMYSQL.DLL when connecting to a MySQL server
9700: MySQL Connector: MvOPEN errors cause the internal connection context to be leaked
10351: MySQL Connector: Connection string does not properly handle IPv6 addresses
10222: Profiling Tool: Segmentation fault when processing log with mismatched call/return
6414: Virtual Machine: MvSMTP reports server errors missing the first character
9704: Virtual Machine: External database API does not provide a mechanism to clean up mvDatabase data after MvOPEN or MvCLOSE errors
9729: Virtual Machine: Empresa should support IPv6
9993: Virtual Machine: dBase MvOPEN with empty DATABASE attribute reads past end of buffer by 1 byte
10005: Virtual Machine: Non-fatal MvDO_Errors sometimes cause a fatal "illegal instruction" error
10006: Virtual Machine: MvEXIT is not properly handled when an MvDOne file MvDOs into itself
10120: Virtual Machine: When accessing a URL with an IPV6 address, s.documenturl does not include square brackets.
10187: Virtual Machine: http opcodes do not properly validate PUT and POST method restriction when the FILES attribute is present
10271: Virtual Machine: MvDO (inline or tag) of a file/directory that exists but is not a valid compiled MivaScript file leads to a crash
10288: Virtual Machine: Special system variables are not properly protected against all array and reference operations
10325: Virtual Machine: Special system variables incorrectly report IsNULL and IsTrue
10326: Virtual Machine: MvEXPORT_Error is not cleared after a successful operation
10344: Virtual Machine: CGI VM: Cannot run any scripts using a ~user URL when absolute paths are allowed for the script directory
New Features
------------
- IPv6 is now supported for all network operations. Within MySQL connection
strings and URLs, IPv6 addresses must be enclosed in square brackets.
Note: IPv6 addresses are not supported in MySQL connection strings on Windows.
- The MvSMTP tag now supports transport encryption, alternate port numbers and
authentication. The new functionality is accessed via new attributes to the
MvSMTP tag. Below is an example of MvSMTP with all supported attributes:
<MvSMTP FROM = "[email protected]"
TO = "[email protected]"
CC = "[email protected]"
SUBJECT = "Subject"
FLAGS = "comma,separated,list"
MAILHOST = "mail.host.com"
PORT = "25"
USERNAME = "username"
PASSWORD = "password">
The FLAGS attribute contains a comma separated list of one or more of the
following flags:
tls Specifies that implicit TLS/SSL should be used for transport
encryption
starttls Specifies that the SMTP STARTTLS command should be used for
transport encryption
noheaders Prevents the default headers (Date, From, To, CC, X-Mailer
and Subject) from being included in the message body. MvSMTP
users that supply this flag must manually generate those
headers.
If PORT is not specified, 25 is used by default. Otherwise the connection
is made on the specified port.
If USERNAME and PASSWORD are specified, SMTP authentication will be used.
MvSMTP supports the following authentication schemes. The scheme used will
be the first scheme from this list which is supported by the mail server.
DIGEST-MD5
CRAM-MD5
PLAIN
LOGIN
When the new attributes are used, if the -C flag is not specified with a
version of 5.17 or older, the compiler will tag the resulting .mvc file
as incompatible with engine versions older than 5.18.
If -C 5.17 (or older) is specified, the compiler will output code that
allows the MvSMTP block to be executed by older engines with the new
attributes ignored. The engine version determination is made at runtime.
Thereore, the new attributes will have effect when running on 5.18 or newer,
and the MvSMTP tag will behave as if those attributes were not specified
when running on 5.17 and older.
- Debug logging of network traffic caused by MvSMTP is now possible by
including MvCONFIG_LOG_MvSMTP (2097152) in the configured log level.
- Debug logging may now be restricted by cookie. New configuration directive
MvCONFIG_LOG_COOKIE (environment based configuration) or "logcookie" (3.x
configuration) controls this setting. When a value is configured, only
requests from browsers with a "mivalogcookie" cookie containing the
specified value will be logged.
- diag6.mvc has been expanded to include tools for setting and clearing the
mivalogcookie cookie and decoding logged network traffic. The new tool
is named diagtool.mvc.
- POST content types other than application/x-www-form-urlencoded and
multipart/form-data are now supported. This allows XML and other non-form
based data to be POSTed directly to a MivaScript application. To prevent
DOS attacks, the maximum length of unknown content types may be controlled
by the MvCONFIG_MAX_UNKNOWN_CONTENT_LENGTH (environment based configuration)
or "maxunknowncontentlength" (3.x configuration) directive, which limits the
maximum number of bytes of content that may be submitted. The default value
is 1MB. A value of 0 allows an unlimited amount of content (still subject
to the POST timeout) and a value of -1 disables acceptance of unknown
content altogether.
The POST content is not parsed any way and is made available to the script
in system variable "s.content_data".
- New tag <MvASSEMBLY> allows MivaScript assembly code to be interleaved with
tradititional MivaScript. Example:
<MvEVAL EXPR = "Before assembly">
<MvASSEMBLY>
... assembly code here ...
</MvASSEMBLY>
<MvEVAL EXPR = "After assembly">
The content of the MvASSEMBLY tag is passed unmodified to the MivaScript
assembler.
- New compiler options allow the default STANDARDOUTPUTLEVEL to be overridden
for functions that do not have an explicit STANDARDOUTPUTLEVEL attribute:
-f Enable whitespace compression by default for functions
-F Disable text and html output by default for functions
StoreMorph Changes
------------------
- All builtin functions registered in the underlying VM may now be called
within expressions.
- New tag mvt:assign allows variables to be created or modified directly
within templates:
<mvt:assign name="variable_name" value="value_expr" />
The name attribute is always a literal string containing a variable name.
Normal MivaScript scoping rules apply.
The value attribute is always an expression. To assign a static string
value to a variable, single quotes must be included:
<mvt:assign name="g.variable" value="'Hello, world!'" />
Local variables may be created outside of l.settings, but they will only be
present within the scope of the current compiled template and will not
propagate to sub or parent templates.
- New tag mvt:while allows non-array loops to be constructed:
<mvt:while expr="g.variable LT 100">
<mvt:assign name="g.variable" value="g.variable + 1" />
</mvt:while>
- New tag mvt:miva allows templates to control whitespace compression and
disable all non-explicit output:
<mvt:miva output="on|off" compresswhitespace="on|off" />
If output is disabled, only StoreMorph tokens and explicit <mvt:eval> tags
will generate output.
- New tag mvt:eval allows expressions to be directly output:
<mvt:eval expr="value_expr" />
The expr attribute behaves as the value attribute of mvt:assign, in that it
is always an expression.
New Builtin Functions
---------------------
- crypto_hmac_md5( buffer var, key, format, result var )
Performs an HMAC-MD5 on "buffer" using key "key", storing the result in
"result". "format" is one of "hex" or "binary".
Returns 1 on success, 0 on error.
This function is available even if OpenSSL is not configured.
- miva_array_clear( array var, start, count )
Removes "count" elements from "array", starting at position "start". The
elements are removed from the array, but the array is not collapsed.
Returns the number of elements remaining in the array.
- miva_array_delete( array var, start, count )
Removes "count" elements from "array", starting at position "start". The
array is collapsed after the elements are removed.
Returns the number of elements remaining in the array.
- miva_array_merge( source var, sstart, scount, dest var, dpos )
- miva_array_merge_ref( source var, sstart, scount, dest var, dpos )
Copies "scount" elements from "source" into "dest", starting with "sstart"
and inserting the elements at "dpos". Existing elements in "dest" past
"dpos" are pushed forward by "scount" elements.
miva_array_merge_ref inserts references to the source elements into the
destination array. miva_array_merge copies the elements.
If "dpos" is -1, the elements are appended to the end of "dest".
Returns the number of elements in the "dest" array after the merge.
- miva_array_copy( source var, sstart, scount, dest var, dpos )
- miva_array_copy_ref( source var, sstart, scount, dest var, dpos )
Copies "scount" elements from "source" into "dest", starting with "sstart"
and placing the elements at "dpos". Existing elements in "dest" are
overwritten.
miva_array_copy_ref inserts references to the source elements into the
destination array. miva_array_copy copies the elements.
If "dpos" is -1, the elements are appended to the end of "dest".
Returns the number of elements in the "dest" array after the copy.
- miva_array_insert( array var, element, pos )
- miva_array_insert_var( array var, element var, pos )
- miva_array_insert_ref( array var, element var, pos )
Inserts single element "element" into "array" at position "pos".
miva_array_insert_ref inserts a reference to "element" into "array".
The other variations copy "element".
If "pos" is -1, the element is inserted at the end of "array".
Returns the number of elements in "array" after the insertion.
- miva_array_pop( array var )
Removes and returns the last element of "array".
- miva_array_pop_ref( array var, element var )
Makes "element" a reference to the last element of "array", then removes it
from the array.
Returns the number of elements remaining in "array".
- miva_array_shift( array var )
Removes and returns the first element of "array".
- miva_array_shift_ref( array var, element var )
Makes "element" a reference to the first element of "array", then removes
it from the array.
Returns the number of elements remaining in "array".
- miva_array_find( needle, haystack var, offset )
Performs an exhaustive search for "needle" in array "haystack", starting
at "offset". Comparison is equivalent to the EQ operator.
Returns the index of "needle" in "haystack" or 0 if the element was not
found.
- miva_array_search( array var, offset, element var, filter_expr )
Performs an exhaustive search in array "array", starting at "offset".
Comparison is made by evaluating "filter_expr" for each element.
"filter_expr" is an expression similar to the EXPR attribute to MvFILTER.
The expression is executed in the same state as the caller of
miva_array_search. All local variables within that context are available,
and function calls are permitted.
Returns the index of the first element in "array" for which filter_expr
evaluated as true, or 0 if no elements met this condition.
- miva_array_binarysearch( key, array var, callback, data var )
Performs a binary search for "key" in "array". "array" must have been
previously sorted.
"callback" is the name of a callback function with the following
parameters:
CallbackFunc( key var, element var, data var )
The callback function should return the following:
-1 key is less than element
0 key is equal to element
1 key is greater than element
Parameter "data" to miva_array_binarysearch is passed unmodified to
each execution of the callback function.
Returns the index of "key" in "array" or 0 if no match was found.
API Changes
-----------
- MV_EL_DATABASE_VERSION has been incremented to 6 and new function db_cleanup
has been added to the database library API.
void ( *db_cleanup )( mvDatabase db )
This function is called to allow a library to free any memory associated
with a mvDatabase handle. This allows memory allocated in db_open to be
freed when db_open returns non-success.
- const MV_EL_Function *mvProgram_Lookup_ExternalFunction( mvProgram program, const char *function, int function_len )
Searches the list of registered builtin functions for "function" returning
the associated MV_EL_Function record or NULL.
- int mvProgram_FatalError( mvProgram program, const char *error, int error_length )
Triggers a Fatal Error which will terminate script execution.
- mvVariable mvVariable_Allocate_Copy( mvVariable variable )
Allocates and returns a new variable which is a copy of "variable".
- mvVariable mvVariable_NextIdentity( mvVariable variable )
If "variable" is a reference, returns its immediate reference value.
- mvVariable mvVariable_RealIdentity( mvVariable variable )
Follows a reference chain starting with "variable" and returns the
final non-reference end of the chain.
- void mvVariableHash_ReplaceVariable( mvVariableHash hash, mvVariable variable )
Inserts "variable" into "hash", replacing any existing variable with the
same name.
- void mvVariable_Make_Reference( mvVariable variable, mvVariable value )
Makes "variable" a reference to "value".
- int mvProgram_Compare( mvProgram program, mvVariable left, mvVariable right )
Compares two variables using semantics equivalent to the EQ operator and
returns one of the following:
-1 left is less than right
0 left is equal to right
1 left is greater than right
- void mvVariable_Array_Copy( mvVariable source, int spos, int scount, mvVariable dest, int dpos, int copy )
Copies "scount" elements from "source" into "dest", starting with "sstart"
and placing the elements at "dpos". Existing elements in "dest" are
overwritten.
If "dpos" is -1, the elements are appended to the end of "dest".
If "copy" is true, copies of the source elements are placed into "dest".
Otherwise, references are made to the original elements.
- void mvVariable_Array_Merge( mvVariable source, int spos, int scount, mvVariable dest, int dpos, int copy )
Copies "scount" elements from "source" into "dest", starting with "sstart"
and inserting the elements at "dpos". Existing elements in "dest" past
"dpos" are pushed forward by "scount" elements.
If "dpos" is -1, the elements are appended to the end of "dest".
If "copy" is true, copies of the source elements are placed into "dest".
Otherwise, references are made to the original elements.
- void mvVariable_Delete_Array_Elements( int start, int count, int collapse, mvVariable agg )
Removes "count" elements from "array", starting at position "start". If
"collapse" is true, the array is collapsed after the elements are removed.
- void mvVariable_Insert_Array_Element( int index, mvVariable value, mvVariable agg )
Inserts "value" into array "agg" at position "index". Existing elements
at "index" and beyond are moved forward one position.
- mvDynamicExpression mvProgram_Compile_Dynamic_Expression( mvProgram program, const char *expr, int expr_length, char **error, int *error_length )
Compiles expression "expr", returning a handle that may be passed to one
of the execution functions below. If a compilation error occurs and
non-NULL values are passed for "error" and "error_length", a textual
description of the compilation error is provided.
Dynamic expression handles are tied to the mvProgram in which they were
compiled and may not be executed with any other mvProgram.
Returns a dynamic expression handle or NULL on error.
- int mvProgram_Execute_Dynamic_Expression_Boolean( mvProgram program, mvDynamicExpression expr, mvVariableHash localvar_hash, int *result )
Executes dynamic expression "expr", storing a boolean result in "result".
If "localvar_hash" is NULL, the expression is executed with access to the
local variables of the calling context. Otherwise, "localvar_hash" is
a VariableHash containing the local variables that will be made available
to the expression.
Returns 1 on success or 0 on error. Most error returns will result in the
VM terminating execution when control is returned to the VM.
- int mvProgram_Execute_Dynamic_Expression( mvProgram program, mvDynamicExpression expr, mvVariableHash localvar_hash, mvVariable result )
Executes dynamic expression "expr", storing the result in "result".
If "localvar_hash" is NULL, the expression is executed with access to the
local variables of the calling context. Otherwise, "localvar_hash" is
a VariableHash containing the local variables that will be made available
to the expression.
Returns 1 on success or 0 on error. Most error returns will result in the
VM terminating execution when control is returned to the VM.
-------------------------------------------------------------
Bugs Fixed
----------
10177: Builtins: string: gettoken() fails to retrieve tokens after an ASCII NULL when NULLs are contained in the "string" parameter
10281: Builtins: system: miva_array_next/previous return incorrect values when asked for the next/previous element of a non-existent array element
10323: Builtins: system: miva_variable_value returns fatal error when variable name contains "[]"
10415: Builtins: system: miva_array_search does not provide any information when an invalid filter expression is provided
10065: Builtins: template: mvt:if with empty expr results in a stack underflow at runtime
10414: Compiler: Nested MvFOREACH that reuses an index from a previous version results in incorrect looping
10503: Compiler: Nested MvFOR that reuses an index from a previous version results in incorrect looping
10151: Diagnostic Application: Directories are not properly identified during the Script Directory Contents test if diag6.mvc is in a subdirectory
10327: Miva Mia: s.remote_host does not behave like other variables
9701: MivaSQL: MvOPEN errors cause the internal connection context to be leaked
9708: MivaSQL: Invalid read of size 1 when DATABASE is an empty string
9694: MySQL Connector: Frequent crashes at address 0x0001fbf3 in MVDMYSQL.DLL when connecting to a MySQL server
9700: MySQL Connector: MvOPEN errors cause the internal connection context to be leaked
10351: MySQL Connector: Connection string does not properly handle IPv6 addresses
10222: Profiling Tool: Segmentation fault when processing log with mismatched call/return
6414: Virtual Machine: MvSMTP reports server errors missing the first character
9704: Virtual Machine: External database API does not provide a mechanism to clean up mvDatabase data after MvOPEN or MvCLOSE errors
9729: Virtual Machine: Empresa should support IPv6
9993: Virtual Machine: dBase MvOPEN with empty DATABASE attribute reads past end of buffer by 1 byte
10005: Virtual Machine: Non-fatal MvDO_Errors sometimes cause a fatal "illegal instruction" error
10006: Virtual Machine: MvEXIT is not properly handled when an MvDOne file MvDOs into itself
10120: Virtual Machine: When accessing a URL with an IPV6 address, s.documenturl does not include square brackets.
10187: Virtual Machine: http opcodes do not properly validate PUT and POST method restriction when the FILES attribute is present
10271: Virtual Machine: MvDO (inline or tag) of a file/directory that exists but is not a valid compiled MivaScript file leads to a crash
10288: Virtual Machine: Special system variables are not properly protected against all array and reference operations
10325: Virtual Machine: Special system variables incorrectly report IsNULL and IsTrue
10326: Virtual Machine: MvEXPORT_Error is not cleared after a successful operation
10344: Virtual Machine: CGI VM: Cannot run any scripts using a ~user URL when absolute paths are allowed for the script directory
New Features
------------
- IPv6 is now supported for all network operations. Within MySQL connection
strings and URLs, IPv6 addresses must be enclosed in square brackets.
Note: IPv6 addresses are not supported in MySQL connection strings on Windows.
- The MvSMTP tag now supports transport encryption, alternate port numbers and
authentication. The new functionality is accessed via new attributes to the
MvSMTP tag. Below is an example of MvSMTP with all supported attributes:
<MvSMTP FROM = "[email protected]"
TO = "[email protected]"
CC = "[email protected]"
SUBJECT = "Subject"
FLAGS = "comma,separated,list"
MAILHOST = "mail.host.com"
PORT = "25"
USERNAME = "username"
PASSWORD = "password">
The FLAGS attribute contains a comma separated list of one or more of the
following flags:
tls Specifies that implicit TLS/SSL should be used for transport
encryption
starttls Specifies that the SMTP STARTTLS command should be used for
transport encryption
noheaders Prevents the default headers (Date, From, To, CC, X-Mailer
and Subject) from being included in the message body. MvSMTP
users that supply this flag must manually generate those
headers.
If PORT is not specified, 25 is used by default. Otherwise the connection
is made on the specified port.
If USERNAME and PASSWORD are specified, SMTP authentication will be used.
MvSMTP supports the following authentication schemes. The scheme used will
be the first scheme from this list which is supported by the mail server.
DIGEST-MD5
CRAM-MD5
PLAIN
LOGIN
When the new attributes are used, if the -C flag is not specified with a
version of 5.17 or older, the compiler will tag the resulting .mvc file
as incompatible with engine versions older than 5.18.
If -C 5.17 (or older) is specified, the compiler will output code that
allows the MvSMTP block to be executed by older engines with the new
attributes ignored. The engine version determination is made at runtime.
Thereore, the new attributes will have effect when running on 5.18 or newer,
and the MvSMTP tag will behave as if those attributes were not specified
when running on 5.17 and older.
- Debug logging of network traffic caused by MvSMTP is now possible by
including MvCONFIG_LOG_MvSMTP (2097152) in the configured log level.
- Debug logging may now be restricted by cookie. New configuration directive
MvCONFIG_LOG_COOKIE (environment based configuration) or "logcookie" (3.x
configuration) controls this setting. When a value is configured, only
requests from browsers with a "mivalogcookie" cookie containing the
specified value will be logged.
- diag6.mvc has been expanded to include tools for setting and clearing the
mivalogcookie cookie and decoding logged network traffic. The new tool
is named diagtool.mvc.
- POST content types other than application/x-www-form-urlencoded and
multipart/form-data are now supported. This allows XML and other non-form
based data to be POSTed directly to a MivaScript application. To prevent
DOS attacks, the maximum length of unknown content types may be controlled
by the MvCONFIG_MAX_UNKNOWN_CONTENT_LENGTH (environment based configuration)
or "maxunknowncontentlength" (3.x configuration) directive, which limits the
maximum number of bytes of content that may be submitted. The default value
is 1MB. A value of 0 allows an unlimited amount of content (still subject
to the POST timeout) and a value of -1 disables acceptance of unknown
content altogether.
The POST content is not parsed any way and is made available to the script
in system variable "s.content_data".
- New tag <MvASSEMBLY> allows MivaScript assembly code to be interleaved with
tradititional MivaScript. Example:
<MvEVAL EXPR = "Before assembly">
<MvASSEMBLY>
... assembly code here ...
</MvASSEMBLY>
<MvEVAL EXPR = "After assembly">
The content of the MvASSEMBLY tag is passed unmodified to the MivaScript
assembler.
- New compiler options allow the default STANDARDOUTPUTLEVEL to be overridden
for functions that do not have an explicit STANDARDOUTPUTLEVEL attribute:
-f Enable whitespace compression by default for functions
-F Disable text and html output by default for functions
StoreMorph Changes
------------------
- All builtin functions registered in the underlying VM may now be called
within expressions.
- New tag mvt:assign allows variables to be created or modified directly
within templates:
<mvt:assign name="variable_name" value="value_expr" />
The name attribute is always a literal string containing a variable name.
Normal MivaScript scoping rules apply.
The value attribute is always an expression. To assign a static string
value to a variable, single quotes must be included:
<mvt:assign name="g.variable" value="'Hello, world!'" />
Local variables may be created outside of l.settings, but they will only be
present within the scope of the current compiled template and will not
propagate to sub or parent templates.
- New tag mvt:while allows non-array loops to be constructed:
<mvt:while expr="g.variable LT 100">
<mvt:assign name="g.variable" value="g.variable + 1" />
</mvt:while>
- New tag mvt:miva allows templates to control whitespace compression and
disable all non-explicit output:
<mvt:miva output="on|off" compresswhitespace="on|off" />
If output is disabled, only StoreMorph tokens and explicit <mvt:eval> tags
will generate output.
- New tag mvt:eval allows expressions to be directly output:
<mvt:eval expr="value_expr" />
The expr attribute behaves as the value attribute of mvt:assign, in that it
is always an expression.
New Builtin Functions
---------------------
- crypto_hmac_md5( buffer var, key, format, result var )
Performs an HMAC-MD5 on "buffer" using key "key", storing the result in
"result". "format" is one of "hex" or "binary".
Returns 1 on success, 0 on error.
This function is available even if OpenSSL is not configured.
- miva_array_clear( array var, start, count )
Removes "count" elements from "array", starting at position "start". The
elements are removed from the array, but the array is not collapsed.
Returns the number of elements remaining in the array.
- miva_array_delete( array var, start, count )
Removes "count" elements from "array", starting at position "start". The
array is collapsed after the elements are removed.
Returns the number of elements remaining in the array.
- miva_array_merge( source var, sstart, scount, dest var, dpos )
- miva_array_merge_ref( source var, sstart, scount, dest var, dpos )
Copies "scount" elements from "source" into "dest", starting with "sstart"
and inserting the elements at "dpos". Existing elements in "dest" past
"dpos" are pushed forward by "scount" elements.
miva_array_merge_ref inserts references to the source elements into the
destination array. miva_array_merge copies the elements.
If "dpos" is -1, the elements are appended to the end of "dest".
Returns the number of elements in the "dest" array after the merge.
- miva_array_copy( source var, sstart, scount, dest var, dpos )
- miva_array_copy_ref( source var, sstart, scount, dest var, dpos )
Copies "scount" elements from "source" into "dest", starting with "sstart"
and placing the elements at "dpos". Existing elements in "dest" are
overwritten.
miva_array_copy_ref inserts references to the source elements into the
destination array. miva_array_copy copies the elements.
If "dpos" is -1, the elements are appended to the end of "dest".
Returns the number of elements in the "dest" array after the copy.
- miva_array_insert( array var, element, pos )
- miva_array_insert_var( array var, element var, pos )
- miva_array_insert_ref( array var, element var, pos )
Inserts single element "element" into "array" at position "pos".
miva_array_insert_ref inserts a reference to "element" into "array".
The other variations copy "element".
If "pos" is -1, the element is inserted at the end of "array".
Returns the number of elements in "array" after the insertion.
- miva_array_pop( array var )
Removes and returns the last element of "array".
- miva_array_pop_ref( array var, element var )
Makes "element" a reference to the last element of "array", then removes it
from the array.
Returns the number of elements remaining in "array".
- miva_array_shift( array var )
Removes and returns the first element of "array".
- miva_array_shift_ref( array var, element var )
Makes "element" a reference to the first element of "array", then removes
it from the array.
Returns the number of elements remaining in "array".
- miva_array_find( needle, haystack var, offset )
Performs an exhaustive search for "needle" in array "haystack", starting
at "offset". Comparison is equivalent to the EQ operator.
Returns the index of "needle" in "haystack" or 0 if the element was not
found.
- miva_array_search( array var, offset, element var, filter_expr )
Performs an exhaustive search in array "array", starting at "offset".
Comparison is made by evaluating "filter_expr" for each element.
"filter_expr" is an expression similar to the EXPR attribute to MvFILTER.
The expression is executed in the same state as the caller of
miva_array_search. All local variables within that context are available,
and function calls are permitted.
Returns the index of the first element in "array" for which filter_expr
evaluated as true, or 0 if no elements met this condition.
- miva_array_binarysearch( key, array var, callback, data var )
Performs a binary search for "key" in "array". "array" must have been
previously sorted.
"callback" is the name of a callback function with the following
parameters:
CallbackFunc( key var, element var, data var )
The callback function should return the following:
-1 key is less than element
0 key is equal to element
1 key is greater than element
Parameter "data" to miva_array_binarysearch is passed unmodified to
each execution of the callback function.
Returns the index of "key" in "array" or 0 if no match was found.
API Changes
-----------
- MV_EL_DATABASE_VERSION has been incremented to 6 and new function db_cleanup
has been added to the database library API.
void ( *db_cleanup )( mvDatabase db )
This function is called to allow a library to free any memory associated
with a mvDatabase handle. This allows memory allocated in db_open to be
freed when db_open returns non-success.
- const MV_EL_Function *mvProgram_Lookup_ExternalFunction( mvProgram program, const char *function, int function_len )
Searches the list of registered builtin functions for "function" returning
the associated MV_EL_Function record or NULL.
- int mvProgram_FatalError( mvProgram program, const char *error, int error_length )
Triggers a Fatal Error which will terminate script execution.
- mvVariable mvVariable_Allocate_Copy( mvVariable variable )
Allocates and returns a new variable which is a copy of "variable".
- mvVariable mvVariable_NextIdentity( mvVariable variable )
If "variable" is a reference, returns its immediate reference value.
- mvVariable mvVariable_RealIdentity( mvVariable variable )
Follows a reference chain starting with "variable" and returns the
final non-reference end of the chain.
- void mvVariableHash_ReplaceVariable( mvVariableHash hash, mvVariable variable )
Inserts "variable" into "hash", replacing any existing variable with the
same name.
- void mvVariable_Make_Reference( mvVariable variable, mvVariable value )
Makes "variable" a reference to "value".
- int mvProgram_Compare( mvProgram program, mvVariable left, mvVariable right )
Compares two variables using semantics equivalent to the EQ operator and
returns one of the following:
-1 left is less than right
0 left is equal to right
1 left is greater than right
- void mvVariable_Array_Copy( mvVariable source, int spos, int scount, mvVariable dest, int dpos, int copy )
Copies "scount" elements from "source" into "dest", starting with "sstart"
and placing the elements at "dpos". Existing elements in "dest" are
overwritten.
If "dpos" is -1, the elements are appended to the end of "dest".
If "copy" is true, copies of the source elements are placed into "dest".
Otherwise, references are made to the original elements.
- void mvVariable_Array_Merge( mvVariable source, int spos, int scount, mvVariable dest, int dpos, int copy )
Copies "scount" elements from "source" into "dest", starting with "sstart"
and inserting the elements at "dpos". Existing elements in "dest" past
"dpos" are pushed forward by "scount" elements.
If "dpos" is -1, the elements are appended to the end of "dest".
If "copy" is true, copies of the source elements are placed into "dest".
Otherwise, references are made to the original elements.
- void mvVariable_Delete_Array_Elements( int start, int count, int collapse, mvVariable agg )
Removes "count" elements from "array", starting at position "start". If
"collapse" is true, the array is collapsed after the elements are removed.
- void mvVariable_Insert_Array_Element( int index, mvVariable value, mvVariable agg )
Inserts "value" into array "agg" at position "index". Existing elements
at "index" and beyond are moved forward one position.
- mvDynamicExpression mvProgram_Compile_Dynamic_Expression( mvProgram program, const char *expr, int expr_length, char **error, int *error_length )
Compiles expression "expr", returning a handle that may be passed to one
of the execution functions below. If a compilation error occurs and
non-NULL values are passed for "error" and "error_length", a textual
description of the compilation error is provided.
Dynamic expression handles are tied to the mvProgram in which they were
compiled and may not be executed with any other mvProgram.
Returns a dynamic expression handle or NULL on error.
- int mvProgram_Execute_Dynamic_Expression_Boolean( mvProgram program, mvDynamicExpression expr, mvVariableHash localvar_hash, int *result )
Executes dynamic expression "expr", storing a boolean result in "result".
If "localvar_hash" is NULL, the expression is executed with access to the
local variables of the calling context. Otherwise, "localvar_hash" is
a VariableHash containing the local variables that will be made available
to the expression.
Returns 1 on success or 0 on error. Most error returns will result in the
VM terminating execution when control is returned to the VM.
- int mvProgram_Execute_Dynamic_Expression( mvProgram program, mvDynamicExpression expr, mvVariableHash localvar_hash, mvVariable result )
Executes dynamic expression "expr", storing the result in "result".
If "localvar_hash" is NULL, the expression is executed with access to the
local variables of the calling context. Otherwise, "localvar_hash" is
a VariableHash containing the local variables that will be made available
to the expression.
Returns 1 on success or 0 on error. Most error returns will result in the
VM terminating execution when control is returned to the VM.
Comment