MivaScript and Miva Merchant Documentation Time Capsule

[burch]

Hello All,

As part of an effort to improve our developer communications, I've been digging through our old archived data in search of some of the documentation that's been lost to the annals of time.

I'm posting what I've found here to act as a temporary archive. Eventually, our plans are to use this forum to accumulate knowledge that will later be cleansed and stuffed into a wiki.

It's worth noting that a lot of this documentation (especially the 5.0 developer prerelease stuff) is likely out of date and/or completely irrelevant to the current state of Miva Merchant 5.5. I'm including it because I think it's interesting from a historical perspective, and I'll try to note the documents that are completely wrong.

[burch]

MM5DB-041029-beta-poster.pdf

This document is a poster-sized PDF diagram of the Miva Merchant v5 database.

It seems a little dated and incomplete. Notably, none of the Template system database tables are included, and it still references MMUI and Portal UI.

I'm attaching the Visio source file, as well as two .PDF versions. MM5DB-041029-beta-letters.pdf is formatted to print on a bunch of letter-sized pages, and MM5DB-041029-beta-poster.pdf is a single poster-sized page.

[burch]

Old VM4_API.pdf

This appears to be fairly comprehensive documentation of the 4.x Virtual Machine's internal API. It covers most of the functions provided by the VM for Configuration, Commerce, Database, and Builtin function library developers.

There are some incomplete sections where it appears Linda was planning on obtaining additional information from development.

Most of this information should apply to the 5.x VM.

[Emma]

Re: MivaScript and Miva Merchant Documentation Time Capsule

Hello Burch :)

What a nice surprise ! Very good stuff you share here. Also a big thanks to the Miva Merchant team for making the Limited Source Kit free. This will surely increase the number of developments for Miva Merchant.

PS: I love how the Old VM4_API.pdf ends :D

Best regards

[burch]

Miva Merchant v5.00 Developer Release Documentation

Attached below are a number of documents that were distributed to developers around the end of 2004 while MM5 was in development/its original beta period.

MM5API-DevRel-Database-20041001.pdf appears to be a textual version of the database diagram above. It too is incomplete and very dated.

MM5API-DevRel-FuncChanges-20041001.pdf describes the Module API changes between 4.x and 5.x. It's basically just a raw list, and includes some things that don't exist any more, such as Template Modules.

MM5API-DevRel-FuncList-20041001.pdf is a list of functions provided to module developers by the core MM5 software. It's notable because this is the period in which we went from xxx_FindFirst/FindNext functions in the database library to xxxList_Load.

MM5API-DevRel-TemplateLang-20041001.pdf is a completely out-of-date description of the original version of the template system. It has little to no relevance to today's template system, but is midly interesting from a historical point of view.

[burch]

CompilerGuide-Windows.pdf

This document appears to be end-user documentation for the MivaScript compiler. It includes information on how to setup your PATH environment variable.

The most interesting parts, IMO, are the command line documentation and list of compilation warning and error codes.

[burch]

Xmas Release Notes from Jon.txt

This is a document that I prepared for the Miva Merchant 5.x beta mailing list detailing changes that were made to the Template system in response to developer requests from the beta program. It's interesting in the context of some of the original 5.x documentation above.

It's text, so I'm just including it inline.

Miva Merchant v5.00 Christmas Developer Release
-----------------------------------------------
Templates
---------
1. Templates are no longer modules.  The MMUI templates will be shipped in
   source code form (in the templates/ subdirectory), and compiled at store
   creation.
2. All template compilation is now done from within the Miva Merchant
   application.  The standalone template compiler has been discontinued, and
   existing versions will not generate compiled Miva Script code that will
   work with the new system.
   It is recommended, but not required, that all template compilation be
   performed through the ManagedTemplate interface (see below).
3. Items are no longer defined within the template source.  There are three
   ways for an item registration to occur:
 a. The Store UI module may register them at store creation.
 b. An end-user may create or modify an item using the "Items" tab
    on the "Pages" screen.
 c. A 3rd party module may register itself as an Item by using the
    TemplateManager API:
 
  i. [ g.Module_Feature_TUI_MGR ].TemplateManager_Create_Item( code, module_code )
   Used to create a new item.  "code" is the code/name of the new item,
      and "module_code" is the code of the component module.
  ii. [ g.Module_Feature_TUI_MGR ].TemplateManager_Delete_Item( item_id )
   Deletes an item.  Will return an error if the item is currently
   referenced by any pages.
4. In addition, the PageItemOverride mechanism has been removed, and replaced
   with the concept of an "Item Extension".  Item Extensions allow a 3rd party
   module to extend (but not replace) ComponentModule_Initialize.  An example
   use would be modifying product prices or making new fields available.
   Item Extensions may be created manually from the "Extensions" tab on the
   Item Edit screen, or programmatically by inserting a record into the
   ItemExtensions database:
 
 [ g.Module_Feature_TUI_MGR ].TemplateManager_Create_ItemExtension( item_code, module_code )
 [ g.Module_Feature_TUI_MGR ].TemplateManager_Delete_ItemExtension( extension_id )
5. Most of the standard component modules now generate template code at
   configuration time.  Most of these components allow the user to modify
   the template code from within the configuration interface, by clicking
   an "Advanced Mode" or "Show Code" link.  All of the components which
   generate template code manage this code through the Managed Template
   interface (see below)
6. The Store UI module is now responsible for registering all "standard" items,
   as well as specifying default settings by page.  3rd party Store UI modules
   are not currently allowed.
7. We will no longer be providing the source code to our "MMUI" components.
   Our desire is that any extensions to these components be made by modifying
   the template code which they generate (either programmatically or by the
   end user), or using the ItemExtensions interface.
Managed Templates
-----------------
The Template Manager (accessible via g.Module_Feature_TUI_MGR) now provides
a mechanism for management, compilation, and version control of template code.
A "Managed Template" is a compiled template file, along with version
information.  Each version contains the template source, a date/time stamp,
(optional) notes, and (optional) configuration settings that were used to
generate the template code.  All of this data is stored in two database tables:
sNN_ManagedTemplates
 id   INTEGER  -- Unique ID
 current_id INTEGER  -- ID of the current version
 filename CHAR( 254 ) -- The name of the compiled output file, with
          extension, but with no path information.
sNN_ManagedTemplateVersions
 id   INTEGER  -- Unique ID
 templ_id INTEGER  -- ManagedTemplate ID
 dtstamp  CHAR( 14 ) -- Creation time (time_t)
 notes  CHAR( 100 ) -- User-specified notes
 source  MEMO  -- Template source
 settings MEMO  -- Serialized configuration settings
The Template Manager automatically separates compiled template code on a store
by store basis.  The compiled files are placed in mm5/5.00/templates/sNN (where
NN is the store id).
[ g.Module_Feature_TUI_MGR ].TemplateManager_Create_ManagedTemplate( source var, settings var, output_file )
[ g.Module_Feature_TUI_MGR ].TemplateManager_Create_ManagedTemplateVersion( managedtemplate var, notes, source var, settings var, compile_error var )
[ g.Module_Feature_TUI_MGR ].TemplateManager_Revert_ManagedTemplateVersion( managedtemplate var, version var, compile_error var )
 Re-compiles a (non-current) Managed Template version, and updates current_id. 
[ g.Module_Feature_TUI_MGR ].TemplateManager_Delete_ManagedTemplate( id )
[ g.Module_Feature_TUI_DB ].ManagedTemplate_Load_ID( id, managedtemplate var )
[ g.Module_Feature_TUI_DB ].ManagedTemplate_Delete_History( templ_id )
 Deletes all non-current Managed Template versions
[ g.Module_Feature_TUI_DB ].ManagedTemplateVersion_Load_ID( id, managedtemplateversion var )
[ g.Module_Feature_TUI_DB ].ManagedTemplateVersion_Load_Template_Current( templ_id, managedtemplateversion var )
[ g.Module_Feature_TUI_DB ].ManagedTemplateVersionList_Load_Template( templ_id, managedtemplateversions var )
See the source code for the component 'cmp-mv-hdft' (included in the developer
release) for an example of the "Miva way" of using Managed Templates.
Miscellaneous
-------------
1. A new module feature, "not_fields" has been added, with the following
   function:
 Module_Notify_StandardFields( module var, standardfields var )
   Modules that implement this feature will be notified whenever the customer
   field settings for a store are changed.  The MMUI Customer Fields component
   uses this feature to automatically regenerate its template code as needed.
2. You may notice that the administrative interface looks a little different.
   We are in the middle of a (long overdue) facelift.  There may be broken
   graphics or some minor user interface oddities.  Please pardon our dust.
3. As in previous developer releases, not all wizards are fully functional.
   We recommend you use advanced mode administration.

[burch]

Compiler Release Notes

I'm going to post all of the release note documents that we have archived. Unfortunately, these are usually going to be the only place to find documentation about new builtin functions or tags that were added over the years.

Here's a list of versions that added notable features or new functions:
v1.00 CONTENT-TYPE attribute for MvCALL
v1.03 MvCOMMIT and MvROLLBACK. Range searches for MvFIND. Default database concept introduced.

[burch]

Compiler Release Notes, Continued

Here's a list of versions that added notable features or new functions:
v1.11 MvINCLUDE
v1.15 "5.00 Developers Release 1". Introduced MivaSQL, MvREFERENCE, MvTRANSACTION, MvDBCOMMAND, s.miva_config system variable, fisdir(), sisdir(), dir() (with incomplete documentation). Also introduced new shorthand MvDO syntax.

[burch]

Compiler Release Notes, Continued

Here's a list of versions that added notable features or new functions:
v1.1501 "5.00 Developers Release 3". MivaSQL MvOPEN syntax documentation, proper dir() documentation, wget(), xml_parse, additional MivaVM API functions.
v1.1504 "5.00 Developers Release 6". miva_template_compile() added but the documentation is in the v4.1504 VM release notes.
v1.1507 "5.00 Developers Release 9". MvCALL TIMEOUT attribute, file_read(), miva_lockfile().
v1.16 "5.00 Developers Release 10". xml_parse() output format change and description.
v1.17 "5.00 Developers Release 11". xml_parse_section() and associated functions.

[burch]

Compiler Release Notes, Continued

Here's a list of versions that added notable features or new functions:
v5.03 MvIFDEF and MvIFNDEF

[burch]

VM Release Notes

There seems to have been some confusion over the years with the documentation of builtin functions. Sometimes newly added builtin functions were documented in the compiler release notes, and sometimes they were only mentioned in the VM release notes. So the VM release notes are oftentimes of interest to developers as well as hosts.

Here's a list of versions that added notable features or new functions:
v0.91 HTTP header control, crypto functions (RSA, Blowfish)
v4.00 MvCALL "XML" and "RAW" methods, optional CONTENT-TYPE attribute. MvELSEIF introduced. ftime(), stime(), trim(), tokenize(), glosub_array(), miva_array_collapse(), additional other builtin functions documented.
v4.03 MvCOMMIT, MvROLLBACK. Default database concept, MvFIND range. MivAPI changes.

[burch]

VM Release Notes, Continued

Here's a list of versions that added notable features or new functions:
v4.05 Configuration setting "maxdocache"

[burch]

VM Release Notes, Continued

Here's a list of versions that added notable features or new functions:
v4.11 MvCALL attributes CERTFILE and CERTTYPE
v4.12 MvCALL attribute HEADERS, MivAPI changes for database libraries, tar_directory(), tar_extract(), wget(), keyword_extract() (and associated other functions), x509_load() (and other X509 certificate functions), crypto_md5_file(), rsa_sign() (and other RSA functions), crypto_last_error(), crypto_last_ssl_error()
v4.1503 s.miva_config:commerce_lookup, s.miva_config:database_lookup
v4.1504 MvDBCOMMAND "subdir_char" for MivaSQL, MvCAPTURE, xml_parse() output changes, miva_member_exists(), miva_element_exists(), ISNULL, miva_template_compile(), includes a description of the template language.
v4.1507 MvCALL TIMEOUT attribute, file_read(), miva_lockfile()

[burch]

VM Release Notes, Continued

Here's a list of versions that added notable features or new functions:
v5.00 xml_parse() documentation, MivaSQL info, fisdir(), sisdir(), MvREFERENCE, MvTRANSACTION, MvDBCOMMAND, mvProgram_ResetGlobalTimeout() (for MivAPI), wdownload(). Rolled up description of the changes in the 5.00 Developer Releases.
v5.02 Shorthand MvDO syntax