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>

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.

Attributes

Attribute	Description
ACTION	(Optional) URL for the destination server.
METAMETHOD	(Required) Identifies the method you are using to contact the server (i.e., 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.

Commerce Library Exported Functions

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

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.

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 subsequent calls.
• method: the value of the METHOD attribute specified in the <MvCOMMERCE> tag.
• action: the value of the ACTION attribute specified in the <MvCOMMERCE> tag.
• input: a handle to a Miva_VariableList containing all the variables specified in the FIELDS parameter.
• output: a handle to a Miva_VariableTree used by the commerce library to return values to the module. All variables added to this tree are available to the module as system variables inside the <MvCOMMERCE> block.

Return Value

• MIVA_COMMERCE_OK: successful; proceeds with executing the code inside the <MvCOMMERCE> block.
• MIVA_COMMERCE_ERROR: one or more errors were encountered; the Miva Engine calls miva_commerce_error.

miva_commerce_loop

When miva_commerce_init returns MIVA_COMMERCE_OK, the Miva Engine calls miva_commerce_loop once per iteration of the <MvCOMMERCE> block. The iteration parameter indicates how many times it has been called (starting at 0).

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: the placeholder passed to miva_commerce_init.
• method: the METHOD attribute value.
• action: the ACTION attribute value.
• input: a handle to the Miva_VariableList with FIELDS variables.
• output: a handle to the Miva_VariableTree for returning values.
• iteration: the number of times code inside the <MvCOMMERCE> block has executed (first call = 0).

Return Value

• MIVA_COMMERCE_OK: proceed with executing the code inside the block.
• MIVA_COMMERCE_ERROR: errors encountered; the Miva Engine calls miva_commerce_error.
• MIVA_COMMERCE_END: exit the commerce block normally.

miva_commerce_cleanup

Called after the Miva Engine has finished using the commerce library, regardless of return value.

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.
• data: the placeholder from miva_commerce_init.
• method: the METHOD attribute value.
• action: the ACTION attribute value.
• input: a handle to the Miva_VariableList with FIELDS variables.

Return Value

• None.

miva_commerce_error

Called if miva_commerce_init or miva_commerce_loop returns MIVA_COMMERCE_ERROR, to receive an error description, prior to miva_commerce_cleanup.

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.
• data: the placeholder from miva_commerce_init.
• method: the METHOD attribute value.
• action: the ACTION attribute value.
• input: a handle to the Miva_VariableList with FIELDS variables.

Return Value

• The text for the error is returned.

Example

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

<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>