<MvCOMMERCE>

Provides communications between a Miva Script application and an external commerce library. It will loop until it no longer receives data, or until it is explicitly halted with the tag.

Syntax
<MvCOMMERCE ACTION = "string: { expression } \| literal" METAMETHOD = "string: { expression } \| literal" FIELDS = "{ expression } \| variable list"> <MvCOMMERCESTOP> <MvCOMMERCECONTINUE> </MvCOMMERCE>	Closed Tag

A Commerce Library is a program file that is stored on the server which allows for secure transactions with other website using Miva Script. Because these files are generally stored in a shared central location on the server, individual site owners usually don't have access to them. They can only be enabled and modified by someone with administrative access to the server. Usually, this would be your host provider. Contact your host and ask them to install the commerce library on your server for you.

ACTION: Optional, URL for the destination server.
METAMETHOD: Required, Identifies the method you are using to contact the server (that is, the type of service you are requesting). Define the METAMETHOD to match the one you have registered in the Miva Engine.
FIELDS: Comma delimited, list of variables that contains the data to be sent to the commerce library.

The commerce library performs its functions and passes the data back to the Miva Script application. The output from the commerce library is a binary tree that allows the library to make results available to a Miva Script application.

This function in this example call a commerce library to process a credit card.

Example:

<MvFUNCTION NAME = "PaymentModule_Authorize" PARAMETERS = "data, total" STANDARDOUTPUTLEVEL = "">
    <MvIF EXPR = "{ NOT Card_Provider_Open_Store() }">
        <MvFUNCTIONRETURN VALUE = 0>
    </MvIF>

   <MvASSIGN NAME = "l.processed" VALUE = 0>

    ... Prepare all the fields ...

    <MIVA MvCOMMERCE_Error = "nonfatal, nodisplay">
    <MvCOMMERCE METAMETHOD = "Card_Provider"
                ACTION = "{ Card_Provider.d.url }"
                FIELDS = "{ l.fields }">
        <MvIF EXPR = "{ s.x_response_code EQ '1' }">
            <MvASSIGN NAME = "l.processed" VALUE = 1>
            <MvASSIGN NAME = "l.ok" VALUE = "{ 
                Card_Provider_Orders_Insert( BasketList.d.order_id,
                    s.x_response_reason_text,
                    s.x_auth_code,
                    s.x_avs_code,
                    s.x_Trans_ID,
                    l.x_Amount,
                    l.x_Card_Num,
                    l.x_First_Name,
                    l.x_Last_Name,
                    l.x_Exp_Date,
                    l.x_Method,
                    l.x_Bank_Name,
                    l.x_Bank_Acct_Num,
                    l.x_Bank_Acct_Type,
                    l.x_Bank_ABA_Code
                )
             }">
            <MvASSIGN NAME = "l.processed" VALUE = 1>
        <MvELSE>
            <MvIF EXPR = "{ len( s.x_response_reason_text ) }">
                <MvASSIGN NAME = "g.Authorization_Failure_Message" 
                          VALUE = "{ encodeentities( s.x_response_reason_text ) }">
            <MvELSE>
                <MvASSIGN NAME = "g.Authorization_Failure_Message" 
                          VALUE = "{ encodeentities( s.x_response_code ) }">
                <MvCOMMERCESTOP>
            </MvIF>
        </MvIF>
    </MvCOMMERCE>
    <MIVA MvCOMMERCE_Error = "fatal, display">

    <MvIF EXPR = "{ MvCOMMERCE_Error }">
        <MvASSIGN NAME = "g.Authorization_Failure_Message" VALUE = "{ MvCOMMERCE_Error }">
    </MvIF>
    <MvASSIGN NAME = "l.ok" VALUE = "{ Card_Provider_Close_Store() }">

    <MvFUNCTIONRETURN VALUE = "{ l.processed }">
</MvFUNCTION>

A commerce library communicates with a Miva Script application through the Miva Engine. When the Miva Engine encounters the <MvCOMMERCE> tag in a Miva Script application, it consults its list of registered commerce libraries. If a matching commerce library is found, the Miva Engine loads the corresponding DLL.

To develop a commerce library for a Miva Script application, the DLL must export the following four functions:

miva_commerce_init

miva_commerce_loop

miva_commerce_cleanup

miva_commerce_error

All communication from a Miva commerce library to the Miva Script application is through these four exported functions.

miva_commerce_init

This function is called when the Miva Engine encounters a <MvCOMMERCE> block. Its purpose is to initialize any data that will be used inside the <MvCOMMERCE> block. The DLL can store any application-specific values in the "data" parameter. This parameter is passed to the other exported functions.

Syntax

Miva_Commerce_Status miva_commerce_init ( Miva_Context context, 
                                          void **data, 
                                          const char *method, const char *action, 
                                          Miva_VariableList input, 
                                          Miva_VariableTree output );

Parameters:

context: a handle to Miva_Context.
data: a placeholder that allows a commerce library to allocate and store instance-specific data. Any value, which you assign to the data parameter, is passed to any subsequent calls to the commerce library.
method: the value of the METHOD attribute that was specified in the <MvCOMMERCE> tag.
action: the value of the ACTION attribute that was specified in the <MvCOMMERCE> tag.
input : a handle to a Miva_VariableList containing all the variables specified in the FIELDS parameter of the <MvCOMMERCE> tag.
output: a handle to a Miva_VariableTree which is used by the commerce library to return values to the module. All variables added to this tree are made available to the module in the form of system variables, which are available only inside the <MvCOMMERCE> block.

Return Value:

MIVA_COMMERCE_OK: successful, then proceeds with executing the code inside the <MvCOMMERCE> block.
MIVA_COMMERCE_ERROR: one of more errors were encountered and the Miva Engine calls miva_commerce_error.

miva_commerce_loop

When miva_commerce_init returns MIVA_COMMERCE_OK, the Miva Engine calls the miva_commerce_loop function. This function is called once per iteration of a <MvCOMMERCE> block. The parameter "iteration" indicates the number of times that miva_commerce_loop has been called.

Syntax

Miva_Commerce_Status miva_commerce_loop ( Miva_Context context, 
                                          void **data, 
                                          const char *method, 
                                          const char *action, 
                                          Miva_VariableList input, 
                                          Miva_VariableTree output, 
                                          int iteration );

Parameters:

context: a handle to Miva_Context
data: a placeholder that was passed to miva_commerce_init. If you assigned a value to it there, it will have the same value here.
method: the value of the METHOD attribute that was specified in the <MvCOMMERCE> tag.
action: the value of the ACTION attribute that was specified in the <MvCOMMERCE> tag.
input: a handle to a Miva_VariableList containing all the variables specified in the FIELDS parameter of the <MvCOMMERCE> tag.
output: a handle to a Miva_VariableTree which is used by the commerce library to return values to the module. All variables added to this tree are made available to the module in the form of system variables only inside the <MvCOMMERCE> block.
iteration: the number of times Miva has executed the code inside the <MvCOMMERCE> block. The first time miva_commerce_loop is called, iteration has a value of 0.

Return Value:

The action that the Miva Engine takes is dependent on the return value of the miva_commerce_loop.

MIVA_COMMERCE_OK: the engine will proceed to execute the code inside the <MvCOMMERCE> block.
MIVA_COMMERCE_ERROR: one of more errors were encountered and the Miva Engine calls miva_commerce_error.
MIVA_COMMERCE_END: the engine will exit the commerce block normally (you would normally return MIVA_COMMERCE_END when your commerce library functions are complete and should stop).

miva_commerce_cleanup

Whenever the Miva Engine has completed using the commerce library, regardless of the return value, it calls miva_commerce_cleanup.

Syntax

void miva_commerce_cleanup ( Miva_Context context, 
                             void **data, 
                             const char *method, 
                             const char *action, 
                             Miva_VariableList input );

Parameters:

context: a handle to Miva_Context. Your commerce library will need this handle to use the networking and file functions provided by the Commerce API.
data: a placeholder that was passed to miva_commerce_init. If you assigned a value to it there, it will have the same value here.
method: the value of the METHOD attribute that was specified in the <MvCOMMERCE> tag.
action: the value of the ACTION attribute that was specified in the <MvCOMMERCE> tag.
input: a handle to a Miva_VariableList containing all the variables specified in the FIELDS parameter of the <MvCOMMERCE> tag.

Return Value:

No return value.

miva_commerce_error

If either miva_commerce_init or miva_commerce_loop returns MIVA_COMMERCE_ERROR, the Miva Engine calls miva_commerce_error to receive a description of the error. It makes this call prior to calling miva_commerce_cleanup.

This function is called by the Miva Engine to receive a description of an error. It is called prior to calling miva_commerce_cleanup.

Syntax

const char * miva_commerce_error ( Miva_Context context, 
                                   void **data, 
                                   const char *method, 
                                   const char *action, 
                                   Miva_VariableList input );

Parameters:

context: a handle to Miva_Context. Your commerce library will need this handle to use the networking and file functions provided by the Commerce API.
data: a placeholder that was passed to miva_commerce_init. If you assigned a value to it there, it will have the same value here.
method: the value of the METHOD attribute that was specified in the <MvCOMMERCE> tag.
action: the value of the ACTION attribute that was specified in the <MvCOMMERCE> tag.
input: a handle to a Miva_VariableList containing all the variables specified in the FIELDS parameter of the <MvCOMMERCE> tag.

Return Value

The text for the error is returned.

+ Add a note

User Annotations: MvCOMMERCE

MivaScript Basics

MivaScript Reference

MivaScript Advanced

<MvCOMMERCE>

Attributes

Example

Example:

Commerce Library Exported Functions

miva_commerce_init

Syntax

Return Value:

miva_commerce_loop

Syntax

Parameters:

Return Value:

miva_commerce_cleanup

Syntax

Parameters:

Return Value:

miva_commerce_error

Syntax

Parameters:

Return Value