MI Program standard

Subject: Writing MI programs From:

To:

Abstract

Written by Date Version Status Approved by Date File

Bjrn Pettersson 2008-11-11 1.1 Active MI Programs

MI Programs Introduction

Introduction
This document describes how MI programs for M3 Java are constituted. The standard described here is developed for M3 13.1. In 13.1, other MI programs exist as well that are of older standards but are utilizing parts of this standard. This standard introduces externally described transactions. Further more, a common object is developed and named MICommon. This object provides commonly used methods for error handling, transaction manipulation, data conversion etc.

Main loop
An MI program consists primarily of a main loop and a number of transaction methods. The main loop deals with receiving the inbound transactions and route them to the appropriate transaction method. Each transaction is usually handled in one primary method but subroutines are common as well.

When the program is started it enters in the movexMain method and different initiation routines are executed. There are the MICommon routines that must be executed and one optional INIT() that are internal to the program that may handle program specific initiations. The remaining time of program execution the program reside in the main loop, waiting on the MICommon.read() method for the client to send a transaction. The program exits when a Close command is sent from the client. Upon receiving a transaction, the program runs through the if statements. When the transaction is found the transaction method is called and when it returns the program calls the MICommon.write() method to return the transaction result to the client. If an erroneous transaction is sent, the MICommon.setTransactionError() is excuted, the client notified and the program returns to the MICommon.read() method. When Close is sent by the client, the program exits the loop and executes MICommon.close(). Program related exit actions may be carried out in the program specific SETLR() method.

Copyright Lawson

Page 2 of 6

MI Programs Introduction

Transaction methods
Each transaction method starts out by retrieving its external transaction descriptions. Usually both inbound and outbound transactions are used but transactions can be defined without either inbound or outbound descriptions.

The program then carries out its unique tasks handling error conditions, doing data conversions etc. If data is to be returned to the client the program call MICommon.setData() to prepare the outbound transaction. In the end of the main loop the data is sent to the client. The transaction method above is a single transaction meaning that only one single record is returned to the client. Multiple transactions that return multiple records contain some form of loop to handle multiple replies. Because there is several records to send, the MI program must call the MICommon.reply() method to send each record. After having leaved the loop but before returning from the transaction method, MICommon.clearBuffer() shall be called to remove data from the ending OK transaction sent in the end of the main loop.

Copyright Lawson

Page 3 of 6

MI Programs Introduction

Error handling
NOTE: These error routines does only work with complete MICommon usage, i.e. when the main loop is according to the new standard. Error handling in MI programs is a matter of returning an error message to the client. Aside from the message the message ID is to be returned. When applicable, the erroneous field name shall be returned as well. MICommon contains a number of methods to set these different values. They have different signatures to be used in different situations depending upon what information you have and want to display. The MICommon.setError() methods take these variables as parameters, set the error condition, retrieve the message string and see to that the complete message is returned. Example:

Here, a message containing replaceable data is used. Also, it is good practice to also include a comment of the message. When a message contains more than one replaceable data point, you handle that by concatenating the data into one single string. Data length should be as defined for the message.

In the version of setError above, there is no input for field name. A version exists that takes only field name if you want to add that specifically.

Further more, you can set and error code specifically (.i.e. the two digit code positioned at 14 and 15 in the returning NOK.

Copyright Lawson

Page 4 of 6

MI Programs Introduction

Data conversions
MICommon provide different methods for conversion to and from Alpha and Numeric as well a Date and Time. Inbound data, i.e. from alpha to numeric is carried out in two steps to provide for error handling. Outbound data, where integers and others are normally taken from database tables that thus are already validated, is carried out in one single step. For example an inbound double:

You need only enter the number of decimals prefered as extra parameter. In the case of an error only the field name is set. The message ID is set in MICommon. An outbound double conversion:

Integers are simpler yet to handle. The length is automatically measured so you need only give the value.

Outbound:

Dates are handled in a similar way. Inbound:

And outbound:

Copyright Lawson

Page 5 of 6

MI Programs Introduction

Handling Upd/Chg transactions for ?

There are helper functions in MICommon to test for the ? character that according to the MI standard is used to blank fields. For standard text fields:

A similar approach is used for numeric fields, both integers and doubles:

These methods blanks the field if that is required by the client or, if any value is passed, sets the new value in the field.

Copyright Lawson

Page 6 of 6