Miva Merchant Empresa 5 - Developer Notes

Miva Merchant

Development Documentation

Release Notes:

Miva Merchant Empresa - Virtual Machine, version 5.04

These release notes include the new notes for version 5.04, along with prior notes from 5.03 to 5.00, for convenient reference.

Release Notes

Product: Miva Merchant Empresa

Version: 5.04

Supported Platforms

--------------------

As of January 1, 2006, this is the list of supported platforms:

o FreeBSD 4

o Linux (glibc2)

o Solaris (2.6 and 2.8)

o Windows NT/2000/XP

o Windows Server 2003

Miva Merchant-supported commerce libraries

--------------------

As of January 1, 2006, this is the list of Miva Merchant-supported commerce libraries.

Other commerce libraries are available from other vendors.

o Authorize.Net

o CyberCash

o CyberSource ICS2

o LinkPoint

New Features and Functions

--------------------

Miva Merchant Empresa version 5.04 implements these new features:

o New function: crypto_sha1

crypto_sha1( value, output_format, output)

value - value to hash by reference.

output_format - 'hex' or 'binary'. Anything else will result in binary output.

output - sha1 hash value.

returns: 1 on success, 0 on failure (including OpenSSL not being available)

o New function: crypto_hmac_sha1

crypto_hmac_sha1( value, key, output_format, output)

value - value to hash by reference.

key - key to use to calculate the hmac.

output_format - 'hex' or 'binary'. Anything else will result in binary output.

output - hmac_sha1 hash value.

returns: 1 on success, 0 on failure (including OpenSSL not being available)

Bug Fixes

--------------------

The Miva Merchant Empresa version 5.04 fixes these problems:

o The MIVA-SQL interface no longer attempts to add deleted records to new indices. This prevents spurious "Index 'indexfile.mvx' was created with the UNIQUE flag and the key 'keyvalue' already exists in the index file" errors.

o The MIVA-SQL interface now correctly updates or deletes all records in a recordset when one of the fields was part of the selection criteria, and an index is on that field.

o The MIVA-SQL interface now returns up to 2046 fields from a query.

Release Notes

Product: Miva Merchant Empresa

Version: 5.03

New Features and Functions

--------------------

Miva Merchant Empresa version 5.03 implements these new features:

o The MIVA-SQL interface now supports the "ALTER TABLE DROP COLUMN column-name" syntax.

o On Win32 platforms, the commerce libraries that are maintained by Miva Merchant

are included in the installation kits, and are deployed in the COMMERCELIBRARIES

subdirectory of the installation location.

o New function: file_create

file_create( path, location, data )

path - path to the file to create

location - 'data' or 'script', defaulting to 'data'

data - data to write to the given file.

Returns: Number of bytes written to the file (length of 'data') on success,

or -1 on error.

When the specified file already exists, an error is returned.

o New function: file_append

file_append( path, location, data )

path - path to the file to create

location - 'data' or 'script', defaulting to 'data'

data - data to write to the given file.

Returns: Number of bytes written to the file (length of 'data'

on success) or -1 on error.

When the file exists, the data is appended to the file.

When the file doesn't exist, an error is returned.

o New function: tar_create( file, file_loc, dir, dir_loc, flags )

New built-in function:

tar_create( file, file_loc, dir, dir_loc, flags )

file - target output file

file_loc - 'data' or 'script', defaulting to data

dir - Directory to create a tarball of

dir_loc - 'data' or 'script', defaulting to data

flags - comma-separated list of qualifiers, consisting of:

'compress' - The resultant file will be compressed in bzip2 format.

Returns: 1 on success, 0 on failure.

Note that user and group IDs are stored as zero (0).

o Configurable default error settings.

This feature will allow the system administrator to set the default error settings previously set by the <MIVA MvTAGNAME_Error="fatal,display"> tag.

In addition, the new setting "Expression" will allow expression errors such as null array indices to be ignored. This does not warrant that the application will execute as expected, just that the error is not displayed.

1. ENV configuration syntax example:

MvCONFIG_ERRORSETTING_EXPRESSION=fatal,display

MvCONFIG_ERRORSETTING_MvSMTP=none

MvCONFIG_ERRORSETTING_MvMAKEINDEX=display

2. 3x configuration syntax example:

<errorsettings MvMAKEINDEX="display"

MvDO="fatal,display"

Expression = "none">

3. ISAPI and Miva Merchant Mia configuration

In the Default Web Site Properties dialog box, on the Miva Merchant VM tab, the Error Settings... button will display a secondary dialog box,

Error Settings, where default error settings can be added or deleted.

The name of the error setting is the name of the tag (e.g., "MvMAKEINDEX") or "Expression" for setting expression error settings. The value is "fatal", "display", "fatal,display", or none. All other values are ignored.

o New API function

void mvConfig_Set_DefaultErrorSetting( mvConfig config, const char *tagname, int tagname_length, int setting_value)

Setting value is zero or one of the following values ORred together:

MvCONFIG_ERRORSETTING_DISPLAY

An error generated by the named tag will display to the browser.

MvCONFIG_ERRORSETTING_FATAL

An error generated by the named tag will abort program execution.

Bug Fixes

--------------------

The Miva Merchant Empresa version 5.03 fixes these problems:

o MIVA-SQL "create table" statement now checks for pre-existance of a datafile (i.e., .dbf file) before creating a new one.

o MIVA-SQL "drop table" now returns errors on internal file deletion, and does not delete metadata if the data file is not deleted.

o MIVA-SQL now properly handles non-string index-based exact search.

o The LinkPoint commerce library now truncates product attributes at 128 characters, to prevent the error "SGS-005000: The server encountered a database error". The full text of the product attribute is maintained within Miva Merchant, and is unaffected by this change.

o MIVA-SQL now properly deletes index information on record deletion, preventing errors from re-insertion of values when using unique indices.

o Empresa on UNIX platforms now caches the results of whether a given path contains a symbolic link. This will improve initialization of MivaScript programs running on NFS-mounted file systems.

o The template compiler now correctly escapes the contents of mvt:item "parameter" attributes.

o The CERTFILE attribute to the MvCALL now works correctly.

Recommendations

--------------------

We recommend that MIVA-SQL databases be packed after upgrading to Miva Merchant Empresa v5.03.

Miva Merchant Virtual Machine 5.02

Release Notes

Bug Fixes

--------------------

o OpenSSL libraries no longer require RSA_up_ref on CGI-based platforms.

o Variables with spaces in the array index (e.g., "l.varname[ 4 ]") are now correctly parsed and assigned. This was the cause of

certain payment methods failing to capture funds.

o When Address Verification is disabled in LinkPoint, billing addresses are now accepted even when they do not contain street numbers.

o Non-text database fields with numeric text values assigned to them correctly converts and stores the values.

o The MySQL interface has been moved out of the Miva Merchant Empresa release, and is available separately.

Miva Merchant Virtual Machine 5.01

Release Notes

Bug Fixes

--------------------

o User accounts (web sites with ~username in the URL) no longer cause access violations under certain circumstances.

o stm_zone and dyn_stm_zone now consistenly return the correct text.

o The Miva Merchant Mia software_version system variable no longer has an Í character at the end.

o Trailing spaces are no longer trimmed from MEMO fields in MivaSQL.

o The template compiler now reports error messages correctly.

o ALTER TABLE on a MivaSQL table that was used previously in a MvQUERY or MvOPENVIEW query no longer hangs on Win32 platforms.

o ALTER TABLE or CREATE TABLE on MivaSQL resulting in more than 2046 fields no longer creates a corrupt datafile.

o MvCREATE of a table with more than 2046 fields no longer creates

a corrupt datafile.

o Template compiler now gives an error on MVT entities that do not terminate with a semicolon.

o s.miva_config references to database_lookup now work correctly on ISAPI.

o MvCALL with CERTFILE attributes now work correctly on ISAPI.

o The trap for null structure member names at runtime has been taken out.

Miva Merchant Virtual Machine 5.00

Release Notes

New Features

--------------------

o The new built-in function xml_parse takes three parameters.

xml_parse( filepath, location, output var )

filepath - Location of the file to parse.

location - either 'script' or 'data'. Anything else will use the default "data".

output - xml file parsed into an aggregate.

Returns

1 on success, 0 on error.

The output variable has this format:

The variable has one structure member with the name of the root tag as the member name.

This structure (and substructures) contain:

NAME Name of the tag

VALUE text value of the content data.

CHILDREN[n] Children tags [if any] in order in the file TAGS The children tags [if any]; a structure with the tag name as the member name, and the structure has this structure (NAME, CHILDREN[n], etc.)

LINENO Line number in the file

OFFSET Offset in the file that the start tag starts

Character sequences "\n" and "\r" in CDATA sections in xml_parse will be

converted to ascii(10) and ascii(13) respectively.

o MivaSQL is a new database interface that implements most of the ISO SQL92 standard, and the LEFT OUTER JOIN syntax of ISO SQL99, on top of dBase-compatible datafiles and Miva Merchant proprietary format index files.

o The MvPACK tag will pack all tables (.dbf files and attendant .mvx files) for a given schema.

o MivaSQL MvOPEN and MvCREATE syntax is the same as previous external database files, except that the MvCREATE will create the schema and put the metadata (table and index information) in the file specified by the DATABASE attribute. The FIELDS attribute is still required, but can be left blank (e.g.,

<MvCREATE NAME = "Merchant"

DATABASE = "mivamerchant.dbf"

FIELDS = ""

TYPE = "MivaSQL"> )

Tables and indexes are created using the "CREATE TABLE" and "CREATE INDEX" SQL command.

o Two new functions, fisdir and sisdir, will return a zero or one whether the passed filename is a directory relative to the data or script path, respectively.

o The new MvREFERENCE tag will create a reference from one variable to another, such that changes to one will appear to be made to the other. It can be also used to refer to a variable named by an expression, like the miva_variable_value built-in function.

Usage: <MvREFERENCE NAME = "target-name" VARIABLE = "source-name">

Examples: <MvREFERENCE NAME = "l.ref" VARIABLE = "l.othervar">

o The MvTRANSACTION tag will suspend auto-commit settings for a database until a MvCOMMIT or MvROLLBACK tag is executed.

Usage: <MvTRANSACTION NAME = "database-name">

o The MvDBCOMMAND tag is used to issue commands to a database that has already been opened or created via the MvOPEN or MvCREATE tags.

Usage: <MvDBCOMMAND NAME = "database-name" COMMAND = "command-name" ( PARAMETER = "optional-parameter" )>

All database interfaces take these commands:

Command

log

Purpose: Log interface-specific details to a log file.

Parameter: If specified, the name of the file to log to in the data

directory.

The ODBC interface additionally takes these commands:

Command

manualcommit

Purpose: Set the database connection to not automatically execute a commit after every statement.

Parameter: None

autocommit

Purpose: Reset the database connection to automatically execute a commit after every statement.

Parameter: None

truncate

Purpose: Truncate text data to the size of the field before inserting. Only necessary if the database does not do this by itself, and errors are not desired.

Parameter: None

forwardonly

Purpose: Disables attempts to scroll backwards in a view using MvSKIP with a negative ROWS parameter or MvGO.

Parameter: None

The MySQL interface additionally takes these commands:

Command

manualcommit

Purpose: Set the database connection to not automatically execute a commit after every statement.

Parameter: None

autocommit

Purpose: Reset the database connection to automatically execute a commit after every statement.

Parameter: None

The ORACLE interface additionally takes these commands:

Command

Purpose:

Parameter:

o The s.miva_config system variable gives read-only access to information in the configuration.

It is a structure, with the configuration name being the name of the member. In addition to that, two sub-arrays "database_list" and "commerce_list" contain the the names of the configured database types and commerce library types.

o The new api function mvDirectory_Listing returns a directory listing.

int mvDirectory_Listing( mvProgram program, int location, const char *path, int path_length, mvVariableList output )

program - the mvProgram context

location - MVF_SCRIPT, MVF_DATA, or MVF_COMMERCE

path - The path to a directory relative to the location.

path_length - Length of the path string.

output - mvVariableList that will be populated with mvVariables containing the file name.

Returns

Count of entries in the "output" mvVariableList.

The calling program is responsible for calling mvVariable_Free on the variables inserted into the

output mvVariableList.

o The new api function mvProgram_ResetGlobalTimeout() will reset global timeout to zero.

o Miva Merchant Mia will now detect the version of Microsoft Windows used, and use newer file access routines when appropriate.

o The new built-in function "dir" takes three parameters:

dir( path, location, entries var)

path - The path to a directory relative to the location.

location - the value "script" or "data". Anything else will use the default "data".

entries - array of resultant file names.

Returns

Count of entries in the "entries" variable.

o A new built-in function wdownload takes the first three parameters as wget, and acts the same as wget.

It takes in addition a fourth and fifth parameter. If the fourth parameter is not blank, it must be the name of a function defined in the same compiled file as the call to wdownload, which takes three parameters:

functionname( size, total, data var )

size - The current number of bytes read.

total - The expected size of the completed file.

data - The variable passed to wget as it's fifth parameter.

Returns

0 to abort the wget, 1 otherwise.

If the callback is called, the global timeout will be reset when it returns back to wget.

o s.miva_config has two new members, commerce_lookup and database_lookup,

which are in themselves structures with the names of commerce libraries

and database interfaces that are currently configured.

i.e., <MvEVAL EXPR = "{ s.miva_config:database_lookup:MivaSQL }"> will

display 1 if MivaSQL is configured, 0 otherwise.

o The MVC file will be closed after initial read, and only reopened

when needed.

o MvDBCOMMAND for MivaSQL databases now takes a new command: "subdir_char". The MivaSQL database

create tables and indices with this character converted to a directory boundary. The MivaSQL database

will also manage the subdirectories that it creates.

e.g., the statement "CREATE TABLE S01_MMUI_STORESELECTION" will create a datafile called

s01/mmui/storeselection.dbf (and the subdirectories if needed).

o env.so now prepends "http_" on environment variables if a MvCONFIG_

variable is not found.

o MvCALL takes a new attribute "TIMEOUT". This value is used if it

is smaller than the configured MvCONFIG_CALL_TIMEOUT value.

o The MvCAPTURE tag will "capture" the output until the end MvCAPTURE tag, and put it into a variable.

text, expressions, etc.

</MvCAPTURE>

o file_read( filename, location, output )

filename - the file you want read.

location - either "script" or "data". Anything else infers "data".

output - variable by reference to contain the file.

Reads a file.

o miva_lockfile( filename, location )

filename - the name of the lock file you want created.

location - either "script" or "data". Anything else infers "data".

Creates and locks a lockfile. Similar to the behavior of MvLOCKFILE

without the </MvLOCKFILE> behavior. It also creates the exact filename,

rather than appending ".lck" to the filename as MvLOCKFILE does.

Use fdelete or sdelete (depending on "location") to delete the lockfile.

o Two new functions, "miva_member_exists" and "miva_element_exists" return 0 or 1 depending on whether

a given member or array element exists.

Examples:

o A new operator, ISNULL, will return true or false whether or not a given variable is null.

o A new function, miva_template_compile, will compile the contents of a string

into a template file.

miva_template_compile( sig, source, items, targetfile, error )

sig - Any text. The md5 hash value of this text will be

stored in the MVC file.

source - The source to compile into a template file.

items - array of valid item names. The compiler will return an error if an mvt:item tag has a "name" attribute that is not in this list.

target - The name of the file (relative to the script directory) to put the .mvc file.

error - If the function returns 0, this will contain error text.

Example:

<MvASSIGN NAME = "l.sample" VALUE = " <html> <body> ... other template code </body> </html> ">

Error: <MvEVAL EXPR = "{ l.error }">

</MvIF>

A brief description of the template language is at the bottom of this document.

Bug Fixes

--------------------

o MvSMTP now properly reports the current hostname rather than the

hostname it is trying to connect to.

o MvCALL now properly times out at connect time.

o Database libraries that are not configured will now give the error

"Database type '<type>' is not supported or not configured".

o MvCREATE on external database types that aren't configured now will

correctly set MvCREATE_Error.

Template Language

--------------------

The template body can have text, HTML and other tags, and a set of entities and tags specific to the template language. These entities and tags start with "mvt".

An entity must be placed either inside a tag attribute value, or outside of a tag.

"Open" item tags must be matched with "close" item tags, or be empty tags.

Entities

--------------------

Entities start with "&mvt", and have an optional fourth character:

o mvta will attribute encode the value before output.

o mvte will entity encode the value before output.

Examples of using entities:

<quote>

<a href="&mvt:global:secure_sessionurl;Action=LOGO&Screen=SFNT&Store_Code=&mvta:global:Store_Code;">Logout</a><br>

</quote>

The special case "global" will output the value of the global variable named after the

second colon symbol and the semicolon symbol.