The term Report File in this context is referring to the files that contain a relevant snapshot of the Match-IT databases for the purposes of printing something. Such files are also referred to as 'xTx' (pronounced ex-tee-ex) files because their three letter acronym has a 'T' as the middle character. Whenever a document is needed to be printed a set of xTx records is created containing relevant information, for example for a sales order confirmation an STH record is created for the header information and an STL record for each line in the order. These xTx names are what you can see in the variables in the document designer, and expanding them shows all the fields available.

Although the set of fields available in the xTx records is extensive, it does not cover everything possible. However, should you find you want to print something that is not available in the xTx record, there is a mechanism that allows you to add it.

This section describes that mechanism.

Qualifiers

The mechanism exploits the qualifier system within Match-IT. This provides for the ability to add arbitrary fields of your own to almost any Match-IT database. In this context the fields are going to be added to the xTx records.

Steps

To use the mechanism there are four steps that must be completed:

1.Add the qualifier names to the xTx records

2.Write a Lua script to create qualifiers

3.Tell Match-IT where that script is

4.Modify the report paper design to use your new fields

Step 1 - add qualifier names

In order that your extra fields are visible to the document designer they must be added as a vocabulary to the appropriate xTx record. This can either be done using the qaMakeField 'drop' in some setup script, or manually via the Qualifier Maintenance form. The file the qualifier is to be attached to, the name of the qualifier and the type of information it will hold must be specified. Giving it a default value is not necessary.

The following is an example of creating the vocabulary using the qaMakeField 'drop' within a script:

m.qaMakeField(m.wth,'MyClassQualifier',m.Kode ,m.pack(m.void()))

This creates a field called MyClassQualiifer that will contain a Kode and attaches it to the WTH file.

This is what the form would look like to enter the same qualifier using the manual method:

report_file_qualifier_form

 

Step 2 - write the Lua script

The Lua script to perform the extension must consist of functions with names of the form qualifyTLA, where TLA is the label of the report file that is to be extended, e.g. qualifyWTH to extend the WTH file. The existence of the function enables the facility for that file. The function is passed eight parameters when it is called, in order they are:

dFile

The file number of the destination file. This will be the same as the TLA in the functions name. The type is a FileNo.

dRec

The record number in that file. This is the actual xTx record that is being extended. This is of type RecNo.

sFile

The file number of the file that is providing the source for qualifiers being added. The type is a FileNo.

sRec

The record of the source file for qualifiers being added. This will be an object of the type implied by sFile. This means fields in the record can be accessed as sRec.Field

cFile

The 'context' file for the source. The context file is dependant on the source. For example, the context for the SOL (Sales Order Line) is the MCH (Material Catalogue Header) of the product being ordered in that line. This parameter is of type FileNo.

cRec

The record of the context file if there is one, else it's 0. This will be an object of the type implied by cFile. This means fields in the record can be accessed as cRec.Field

PrintOnly

A boolean that will be true if the qualifier set is being produced for printing purposes.

VariantPrefix

This is the variant prefix that is prevailing for the qualifier set being created. This is normally blank when printing.

The function is called whenever qualifiers are being set for the 'TLA' file.

The function must behave as a Lua coroutine, where it 'yields' back to Match-IT for each qualifier it wants to add and then terminates. To add a qualifier, the function populates the QAT file buffer with a record, then yields. It must just populate the QAT file buffer directly, it must not open it. To add fields to the file buffer use assign statements of the form:

m.qat.field = value

Where field is a valid field name in the QAT file, and value is some expression to assign to that field. As a minimum, the Qualifier, Type, Value and IsPrinted fields should be populated.

To yield back to Match-IT use the Lua coroutine.yield function with no parameters. To terminate, just return from the function. The proforma loop for the function is:

function qualifyTLA(dFile,dRec,sFile,sRec,cFile,cRec,PrintOnly,VariantPrefix)

 --initialise

 while NotDone do

         --build record in the QAT

         coroutine.yield()

 end

end

 

Step 3 - set the script name default

To tell Match-IT where the script resides you must set the Qualifier extender Lua script default (in the QA class) to the file you created in step 2.

Step 4 - modify the paper design

Your new fields will appear in the designer as qualifiers attached to the xTx record. Using them is the same as any other field and is fully described in the Document Design Tutorial manual.

Example

There is a very simple (and silly) example script installed with Match-IT that adds a few fields to the WTH record (works order header). It's located in configs\qualify.lua