This is the complete list of functions available to the Lua Language wizard expressions.

For brevity, the Lua syntax does not show the match_it table prefix. The actual usage in a script will be of the form match_it.name where name is the function name in this list.

The function name lines are of the form: name(parameters),results where name is the name of the function, parameters are 0 or more parameters required and results are 0 or 1 or more results returned by the function. The parameter and result names used here are typically the data type name involved. Parameters enclosed in [] are optional. The data type of bool represents a native Lua boolean data type and the data type of number represents a native Lua number, otherwise type names are Match-IT logical types.

Unless the functions explicitly return an error code, any internal error will cause the script to abort. Such errors can be 'caught' using the pcall function (see the Lua reference manual).

Assign(dObject,sObject)

This function changes the value of the dObject to that of the sObject. The objects must be of the same type. This differs from a Lua dObject = sObject assign statement in that the Lua assign changes the LType referenced by dObject to be sObject, i.e after the Lua assign dObject and sObject are references to the same LType object. The assign operation here preserves the two objects but just makes their value the same.

This is most useful from within callback functions in a GUILE page, where it can be used to change the original value of controls.

Beep()

This function just makes the system default attention sound.

Bool(A),bool

This function will coerce its operand into a Lua boolean if possible. Note the following for the cases when the operand (A) is a Match-IT type:

•an empty Str is FALSE, any other Str is TRUE

•an empty RecNo is FALSE, a non-empty RecNo is TRUE

•any numeric type that is 0 is FALSE, else it's TRUE

Call(Template),Object

This function will call the given template. The object returned is the result of the template or 0 if it failed. Parameters can be passed to and from templates using the GetReg and PutReg functions.

Children(Object,Type),RecNoQ

This function returns a new 'RecNoQ' of all objects of the given type that are referencing the given object. An 'object' is a record in one of the the Match-IT databases. Only child references are returned, use LINKS to find all non-child references.

Clear(File)

This clears the file buffer for the given file. After calling this function all file buffer fields are empty.

Close(File)

This function closes a file that has been opened using the Open() function. It always returns a TRUE flag. If this was a nested open, the context of the outer open is restored to allow subsequent Next() functions to continue where it left off.

The File must refer to a file variable (see the file function). An outer close does not destroy a virtual file.

All open files are automatically closed when the script stops (for whatever reason).

ComStart(),Depth

Start the Windows COM sub-system. A call to this must be made before any attempt to use COM services in a script, e.g. those provided via luaCOM. A corresponding ComStop() call should be made just before the script terminates to turn it off again (although it will be automatically stopped if the script terminates without doing so). ComStart/Stop calls can be nested. Returns a native Lua number that is the COM start nesting depth prior to this call (so 0 means it was not started before).

ComStop(),Depth

Stops the Windows COM sub-system. A call to this should be made for each call to ComStart(). The COM sub-system is only actually stopped by the 'outer' stop call. Returns a native Lua number that is the COM start nesting depth after this call (so 0 means it is now stopped). Calling ComStop() when it is already stopped is benign.

Confirm(Message,[MessageName],[WindowTitle],[OrCancel]),Result

Ask a simple yes/no/cancel question of the user. Returns a native Lua number with a value of gxYes, gxNo or gxCancel to reflect the user selection. If MessageName is given, it is shown above the Message. If WindowTitle is not given, then 'Confirm' is used. If OrCancel (a boolean) is given, pressing the Cancel button does not ask for a further confirmation (use this if your script performs some specific action on cancel). If OrCancel is not given and the user presses the Cancel button, a further confirmation is asked warning the user the script is going to terminate and giving them the opportunity to change their mind (use this if your script terminates on cancel).

Console([options][,pause])

This starts (or re-starts) an interactive console session. If options are given, these are passed to the console (use '-?' to get the usage). If pause is present and TRUE an 'OK' message is shown before the outer console is closed. This allows examination of its contents before it disappears.

The console function provides a command line interface where you can type commands and print results to a console window. It's intended as a debug aid. If you call Console() from within your script you can then use the debugger to examine variables, try things out, etc. (Use require('debugger') to load a simple debug tool.) The [console:drRunScriptUI] can also be started directly from Match-IT.

When a console is started (by whatever means), the Lua initialisation string is evaluated before any options you pass. This is useful to initialise things you want done every time without having to type them.

Note: an options parameter of "-e print('message') -i" is useful when debugging to give you an indication of where the console was invoked from.

Convert(Measure,Unit[,Date][,Flag]),Measure

Returns the given Measure in the units of the given Unit. This can be used on money and time values as well as measures (e.g. to convert between currencies). If the optional Date is given it means perform the conversion for the given date, otherwise it's performed for today. This is significant when converting currencies. If the Flag is present and TRUE it means be silent about conversion errors. This is useful when probing for conversion possibilities. A conversion error will return a result of 'undefined' (test by comparing its digits to umInfinity).

Copy(object1),object2

This creates a copy of the given object. An ordinary assignment of a Match-IT object in Lua creates a new reference to the same object. This copy function creates a new object that has the same value. The significance of this is best illustrated with an example.

a = m.measure('Each,1')

b = a

After the above assignments b is a, so changing the value of a will also change the value of b. Whereas,

a = m.measure('Each,1')

b = m.copy(a)

Here, b is a copy of a, so changing a will not affect b.

Cost(Material),Money

This function causes the cost of a material to be (re-)calculated. The Material parameter is an expression that must evaluate to a material that exists in the catalogue. This function is identical to pushing the 'Re-Cost' button in the UI. The money figure it comes back with is the unit cost calculated, no setup costs will be included.

Create(File,[NoValidate]),Object

This function creates the record in the file as constructed in its file buffer. It returns the RecNo of the object created or aborts if there was an error. The file parameter must refer to a file variable created by the file function. The file must be open. If a record has been reserved (see the reserve function), then that reserved record is written, otherwise a new record is written. If NoValidate is present and true, the usual record validation is by-passed when a reserved record is written (use with caution - it becomes your responsibility to ensure value rules are not violated).

The Object RecNo is returned in the form of an LType appropriate to the file involved.

CreateCSV(File,PathName,[DoFields]),RecordCount

This function creates a CSV file from the current contents of the given virtual file

•File is a file variable. The file must be closed.

•PathName is the name of the file to create the records in.

•DoFields is a flag that iff TRUE will export the first line as the field list, otherwise the first line is the first record.

The returned RecordCount is a count of the number of output records created (excluding the field list). It's a native Lua number.

Delete(File)

Delete the current record in the file.

DestroyVFile(File,[Undeclare])

This function destroys a virtual file and, if undeclare is true, destroys its field declarations too. The file must be closed. Destroying a virtual file deletes all its records. All virtual files are destroyed when the wizard declaring them terminates (for whatever reason).

File must refer to a file variable that is a virtual file ID (ie. one of V01..V99).

Digits(Measure),Real

This function extracts the numbers from a measure. E.g. 1.6 from 1.6 Kg. The returned Real is a native Lua number.

Duplicates(RecNoQ1,RecNoQ2)

This function removes all members from RecNoQ1 that are not also members of RecNoQ2. Both RecNoQs must be of the same type.

Edit(Object),bool

This function will bring up the edit form for the 'object' referenced. An editor is typically a tlaView:Up procedure. It returns TRUE (1) if the user saved, or FALSE (0) if the user cancelled the edit. The editor runs in the same thread as the template. Template execution is suspended until you close the edit form. (Contrast this with View.)

Eq(A,B),bool

This is the same as the Lua '==' operator except the operands (A,B) can be mixed Lua and Match-IT types. This is useful for those cases where you do not know the type of the operands being compared.

Error(Message,[level])

Show the given message and/or terminate the script.

If level is nil or 0, then the user is asked if they want to carry on or abort.

If level is 1 or true, then the message is shown and the script is aborted.

If level is 2, then the script is aborted immediately.

Any other value for level is the same as 0.

When a script is aborted, the last protected function call is terminated, If no protected call is active then the whole script is terminated.

Note: When terminating, if the Lua start console on error default is set to YES, a console session will be started. This is useful to diagnose what went wrong. If your script includes a line "require('debugger')" then you can examine the local variables of the function raising the error.

Exclude(RecNoQ,Member)

This function removes the Member from the RecNoQ.

Exec(Command,[Directory],[IsDocument],[Wait]),ErrorCode

This function will execute an arbitrary command, or open an arbitrary document.

•Command is the command or document name to execute.

•Directory is the working directory to set.

•IsDocument is a flag that if set TRUE indicates a document is to be opened, otherwise a command is run.

•Wait is a flag that if set TRUE will wait for the command to complete or the document to close, otherwise the function returns as soon as the document opens.

•ErrorCode will be non-zero if the function failed to run the command or open the document. It's a native Lua number.

Existing(File[,KeyNo][,Flag]),Object

This function determines if the identified record exists already in the file system. It returns the RecNo of the object referenced if the record does exist, or 0 otherwise. The referenced record is constructed as if it was going to be 'created'. The constructed record is then checked for a duplicate in the file system. A 'duplicate' means at least one key is the same. Note: This does not mean that all fields are the same.

The Object RecNo is returned in the form of an LType appropriate to the file involved.

The file must be open. If KeyNo is not given, then all keys are checked, otherwise just the specified key is checked (in which case only its key fields need be set in the file buffer). If Flag is present and TRUE it means check for the existence of any record with the key set, if not present or FALSE it means check if a duplicate key would be posted if an 'add' or 'put' was attempted. This applies to keys that do not tolerate duplicates.

Field(File,FieldName,FieldType),FieldNo

This function declares a field in a virtual file. The File must refer to a file variable that is a virtual file. It creates a field with name FieldName and type FieldType. Once created the field name persists until the file declaration is destroyed. The field can be referenced in the conventional way.

The function returns the field number it was given. It's a native Lua number.

FieldExists(File,FieldName[,Mode]),bool

This function determines if the identified field actually exists. It returns TRUE (1) if the field does exist, or FALSE (0) otherwise.

This is only meaningful when applied to fields that are defined as qualifiers. Fields defined as part of the native file record always exist.

The Mode parameter specifies:

•0(default) = look for the name on the object, if it does not exist there look in its context, if it does not exist there look for its default

•1  = do not look for its default

•2  = only look on the object itself

File(FileNo),FileRef

This function creates a file variable and associates it with the file buffer identified by FileNo. Fields in the file buffer can then be accessed by indexing the file variable. E.g.

mch = m.file(match_it.mch)

mch.name = 'a material name' --updates the field

mypart = mch.material        --reads the field

FileOf(Object),FileNo

This function extracts the file number associated with the given object. If the object does not represent a record in a file then a file number of 0 is returned.

This function is useful when using operations that require a FileNo/RecNo pair as parameters. E.g. if 'thing' is some object in your script then:

FileOf(Thing),Thing

is the FileNo/RecNo pair representing that object.

Find(File,[KeyNo],[FieldNo],[TypeNo]),RecNoQ

This function performs a Set(File,KeyNo,FieldNo), then performs Next()'s until the whole file has been scanned, placing each object found in the new RecNoQ. The file must be open, and the appropriate key fields populated. See set for an explanation of the significance of the KeyNo and FieldNo parameters.

When no TypeNo is given the LType of the RecNoQ entries will be that implied by the file being accessed. In cases where this is ambiguous (because the file has several types), the TypeNo can be specified as the type to use. It must be appropriate.

FindMaterial(Class[,Field1Name,Value1][,Field2Name,Value2][,Field3Name,Value3][,CompareOp]),Material

This searches the material catalogue for a material with up to 3 fields (native or qualifier) that meet the given search criteria. It returns the Material found or a void if none where found. If more than one field is given, the match is an 'AND' of all the fields given. The CompareOp only applies to the last field. Other fields (if given) are always matched exactly.

The search criteria is defined by the parameters as:

•Class - defines the stock class of the materials to be searched

•Field#Name - defines the field names to look for

•Value# - an 'expression' that evaluates to the value to look for

•CompareOp - defines the type of test to apply to candidates

The possibilities for CompareOp are:

•drFindAbove = find the material whose field value is above or equal the given value by the smallest margin

•drFindBelow = find the material whose field value is below or equal the given value by the smallest margin

•drFindExact = find the material whose field value is exactly the given value (implied if CompareOp omitted)

A CompareOp of drFindAbove or drFindBelow is only valid when the field is a measure.

Hint: To find the first available material of a class, just provide the class and no fields.

FreeQ(RecNoQ)

This function frees the RecNoQ. This releases the memory it's using. The RecNoQ cannot be referenced after a FreeQ() operation. To do so will cause an evaluation error. The function returns a void RecNoQ. If a void RecNoQ is given to FreeQ it has no effect.

Get(FileRef,KeyNo,[NoWatch]),Object

This function reads the first record from the File that matches the given KeyNo. The fields of the key must have been set in the file buffer. The file must be open.

If Watch is TRUE, the record is read ready for a subsequent update. If an attempt is made to update the record without this, an error will be raised.

The result is an object of an LType that embeds a RecNo from the file read. If a record containing the required key does not exist then nil is returned.

Include(RecNoQ,Member)

This function adds the Member to the RecNoQ if it's not there already. If member was already present the function has no effect.

Item(RecNoQ,Number),Object

This function returns the Number'th object from the given RecNoQ.

Items(RecNoQ),Count

This function returns a count of the number of members in the given RecNoQ. It's a native Lua number.

Join(RecNoQ1,RecNoQ2)

This function adds all the unique members of RecNoQ2 to RecNoQ1. The given RecNoQs must be for the same type.

KillState()

This function marks the Lua state the script is running in for 'demolition'. This means the Lua state will be completely closed and destroyed when the script terminates. If this function is not called and the script terminates without error, then the Lua state is kept in a state pool for re-use later. This considerably speeds up the execution of scripts, particularly where the same script is called repeatedly (e.g. when used for PPS expressions).

KodeClass(Kode),KClass

This function extracts the class from a Kode. The class of a kode can usually be determined even if the kode is empty (i.e. has no instance).

KodeFirst(ClassName),KClass

This function returns the first instance of a Kode with the given class name. This is usually the class record. Note: This function returns its result a KClass not a Kode. To turn it into a Kode use a form like k = m.KodeMake(nil,KodeFirst(ClassName)).

KodeInstance(Kode),KInst

This function extracts the instance from a Kode. If the Kode is empty the instance is empty (i.e. a void).

KodeMake(KClass,KInst),Kode

This function constructs a Kode from its parts. If KInst is null, an empty Kode of the given KClass is created. If both are null, an anonymous Kode is created.

Le(A,B),bool

This is the same as the Lua '<=' operator except the operands (A,B) can be mixed Lua and Match-IT types. This is useful for those cases where you do not know the type of the operands being compared.

Links(Object,Type),RecNoQ

This function returns a new 'RecNoQ' of all objects of the given type that are referencing the given object. An 'object' is a record in one of the the Match-IT databases. Only non-child references are returned, use CHILDREN to find all child references.

Load(File,Object,[Watch])

This function reads the record from the File for the record defined by the Object. The Object must represent a RecNo in some file. The file must be open.

If Watch is TRUE, the record is loaded ready for a subsequent update. If an attempt is made to update the record without this, an error will be raised.

Attempting to load a record that does not exist will throw an error and the script will abort unless the error is caught using a 'pcall' (see the Lua language reference manual).

LoadCSV(File,PathName,[IgnoreLine1]),RecordCount

This function loads all the records of a CSV file into the given virtual file. The virtual file is emptied first.

•File must refer to a file variable that is a virtual file.

•PathName is the name of the file to load the records from.

•IgnoreLine1 is a flag that iff TRUE will ignore the first line of the CSV file (assumed to be a field name list).

The returned RecordCount is a count of the number of records loaded. It's a native Lua number.

Lookup(Class,Dimension1,Dimension2,Field,[AllowNil],[NoMake]),Value

This looks up a value in the 2D 'dependence' table. If the addressed item is not present in the table, the user is asked to define it on the spot unless NoMake is asserted. It is placed in the table for future reference.

The lookup is directed by the parameters as:

•Class = the lookup table class code to look in

•Dimension1 = the 'object' to form the first 'dimension' in the lookup

•Dimension2 = ditto for the second dimension

•Field = a qualifier name to lookup

The function returns the value of the qualifier addressed if it exists. If it does not exist an error is thrown unless AllowNil is asserted, in which case the function returns a void().

Lt(A,B),bool

This is the same as the Lua '<' operator except the operands (A,B) can be mixed Lua and Match-IT types. This is useful for those cases where you do not know the type of the operands being compared.

Make(Unit,Real),Measure

This function constructs a Measure from its parts. The following identity holds: Make(Units(A),Digits(A)) == A

Member(RecNoQ,Member),bool

This function returns TRUE iff the given member exists in the given RecNoQ.

Members(RecNoQ),Function

This function creates an iterator function that can be used to traverse a RecNoQ. Typical usage is this

for item in members(RecNoQ) do

 ... whatever

end

Message(msg,[title],[delay])

Show a gxMessage. msg is the message to show. title is the message title or nil. delay is the maximum time to wait for a response (in seconds), 0 or nil means forever.

MonitorStart(Title),bool

This function starts a monitor session with the given title. It returns TRUE iff the session started successfully. This function is only allowed in the context of executing a wizard, it cannot be used by isolated expressions (e.g. a PPS expression). Monitor sessions are automatically stopped when the wizard completes. Nested starts are permitted.

This function will terminate the script if the monitor cannot be started. Thus it always returns TRUE.

MonitorStep([Message][,StopOnInterrupt]),bool

This function issues a monitor step message. It returns (a native bool) TRUE if the user is asking to interrupt the operation and FALSE otherwise. The function is a no-op, returning FALSE, unless a monitor session is active (by whatever means).

If StopOnInterrupt is present and true, the script will be terminated if the user cancels the operation, otherwise the function will return false.

MonitorStop()

This function stops a monitor session started by a previous call to MonitorStart. It always returns TRUE. If no sesion was active then nothing happens.

NewQ(Type),RecNoQ

This function creates a new empty RecNoQ that can contain objects of the given type.

Next(File),Object

This function finds the next (or first) record in the scan defined by the associated Open() (or Set()) function. It returns the RecNo of the record found or 0 otherwise. The RecNo is returned in the form of an LType appropriate to the file (e.g. a Material for the MCH file).

The file must refer to a file variable and the file must be open and have been set to an appropriate key.

NextMaterial(MaterialGroup,PreviousMaterial),NextMaterial

This function finds the next, or first, material that is a member of the given MaterialGroup. If PreviousMaterial is Void(), the first member is found. Otherwise the next member after the one given is found. The one given is usually the result of some previous call to this function. If there are no more members, then NextMaterial is returned as a Void().

NextResource(ResourceGroup,PreviousResource),NextResource

This function finds the next, or first, resource that is a member of the given ResourceGroup. If PreviousResource is Void(), the first member is found. Otherwise the next member after the one given is found. The one given is usually the result of some previous call to this function. If there are no more members, then NextResource is returned as a Void().

Normalise(Material,Quantity,[Length],[Width],[Height]),Measure

This function takes an 'abstracted' quantity of a material and converts it into the reference quantity units for the material. For 0D materials this is just a units conversion (e.g. Grams to Kilos). For 1D and 2D materials it may involve de-abstracting. E.g. for a 1D material of Bars of 3 Metres, a quantity of 10.5 Metres will be converted to 3.5 Bars.

The result is the Measure returned. If no normalisation is possible, the returned measure will have the value of Undefined.

Now(),Clock

This function returns the current time.

Time is represented as centi-seconds since midnight. You can perform arithmetic on time. E.g. adding 6000 to a time will advance it by 1 minute, and subtracting 3000 will take it back 30 seconds. The behaviour of a time less than 0 is undefined. 0 itself is interpreted as 'no time'.

Number(A),number

This function will coerce its operand into a native Lua number if possible.

Open(File)

Open the given file. File must refer to a file variable. Opens may be nested with no loss of context provided each is matched with a close.

This does not do a Set() on the file. You must explicitly set a key using the set function.

Pack(object),RawValue

This function returns the raw value of the object as a native Lua string. NB: The string will contain binary data, including nulls. Use string.byte(s,i).. to look at it. This function can be used when passing values to functions that require arbitrary typed values in their packed form (e.g. qaMakeField).

Page(PageTable),ReturnCode

This function creates user interface (UI) pages that display information and/or ask questions (prompts). See the GUILE manual for details on the usage of this function.

Parents(RecNoQ),RecNoQ

This function translates all the members of RecNoQ into their parents. A 'parent' of an object is the object it is attached to in the database. For example, the parent of a sales order line is its sales order header.

NOTE: The 'type' of the RecNoQ is changed by this operation.

Path([FileName]),FullPath

When a FileName is given, the function returns the fully expanded pathname for the file. A relative FileName is interpreted as being relative to the folder that Match-IT was started in (this may not be the same as the current path). If the FileName contains %registry% elements, that element is replaced by the location of the Match-IT registry.

If the FileName is enclosed in colons (:), it has special meaning as follows:

When a FileName is not given, the function returns the folder in which Match-IT was started.

The returned path is a native Lua string.

Populate(File[,NoClear])

This populates the file buffer for the given file with its default values. Unless NoClear is TRUE the file buffer is cleared first (see Clear() above).

Previous(File),Object

This function finds the previous (or last) record in the scan defined by the associated Open() function. It returns the RecNo of the record found or 0 otherwise. The RecNo is returned in the form of an LType appropriate to the file (e.g. a Material for the MCH file).

The file must refer to a file variable and the file must be open and have been set to an appropriate key.

Prop(Control,Property),Value

Prop(Control,Property,Value)

This function reads (first form) or writes (second form) properties associated with controls on pages constructed using the page function. See the GUILE manual for details on the usage of this function.

Remove(RecNoQ1,RecNoQ2)

This function removes all the members of RecNoQ2 from RecNoQ1. Both RecNoQs must be of the same type.

Reserve(File,[Parent]),Object

This function must be called prior to a Create() to allocate a record in the file. If the record is a child of some parent (e.g. a sales line is a child of the associated sales order), then Parent must be an object that represents the parent. Parent can be omitted only iff the record is not a [CHILD]. The 'parent' is ignored for non [CHILD] records. The function returns the RecNo allocated (as an approp LType).

Round(Measure,Order),Measure

This function will round the given measure to the power of ten defined by the order parameter. E.g. Round(101.12,1) will yield 101, Round(101.12,10) will yield 100, Round(101.12,.1) will yield 101.1, etc.

Run(Process,[Param1],[Param2])

This function performs the same action as a ribbon menu button. It will run the indicated process and pass it Param1 and Param2 as parameters. If either Param1 or Param2 is not required use the Void() function in its place.

The Process must refer to a menu runnable process. Param1 and Param2 must evaluate to something appropriate to the process referenced.

ScaleFactor(TargetQty,Quantity,[Length],[Width],[Height],[Weight]),Real

TargetQty, Quantity, Length, Width, Height and Weight are measures.

This function determines how many items are implied by the TargetQty. If Length is 0, the items are assumed to be 0D (descrete things). If Length is not 0 and Width is 0, the items are assumed to be 1D (rods, bars, liquids, etc.). If Length is not 0 and Width is not 0, the items are assumed to be 2D (sheets, panels, etc.). The TargetQty can be expressed in the units of Quantity, or Length or Weight or Area (Length*Width). The function returns how many items are required to make the TargetQty. For 1D and 2D cases, this might not be a whole number. If it cannot be determined, due to missing conversions, 0 is returned. This can be exploited to test for the existance of conversions.

The returned Real is a native Lua number.

Select(OldSelection,[Title],[Protected],[Context]),NewSelection

Brings up the selector for the object implied by OldSelection and allows a new selection to be made.

Selected(RecNoQ),Object

This function returns the currently selected object from the given RecNoQ. An object is selected by any of: a Filter iteration, user selection (when the RecNoQ is a prompt).

SelfScript(),ScriptFileName

This function returns the name of the last script run on this thread by drLuaRunScript. For scripts started via ThreadStart() this will be the script name given to ThreadStart(). For scripts started from the Match-IT UI, it will be the name of the script so started. The script name returned is a native Lua string.

Set(File,[KeyNo],[FieldNo],[Limit])

This functions sets the key that a subsequent Next() or Previous() will use. KeyNo defines the key to be used, omitted means scan in physical order. FieldNo defines the field to fix on, omitted means no fix field. Limit sets the maximum number of records to SELECT, omitted means no limit. The file buffer must have been populated with the appropriate key field values.

SetDefault(DefaultName,Value,[Object])

All parameters are arbitrary expressions.

If an object is not given it sets the system default to the value given. If an object is given, it sets the instance default for that object (use this form to set, for e.g., customer specific defaults).

The default name must be the system name of the default. This can be found by looking at the Detail of the default in the System Defaults list.

The default is set in memory and in the database. This means the default value will remain in force even if Match-IT is shut-down and re-started.

SetPath(NewPath),OldPath

Set the current working directory to NewPath and return what it used to be (as a native Lua string).

SetVFile(File,PropertyName,PropertyValue)

This function sets a property of a Virtual File. A virtual file is a memory (only) based structure that behaves like a real file. They are intended to be useful in constructing arbitrary lists. All wizard functions that accept file objects as parameters can accept a virtual file, e.g. View.

The File parameter must refer to a file variable. The PropertyName defines the property that is to be set. It must be one of 'Name' to set a logical name for the file; 'Title' to set a display title when viewing; 'Description' to set a description when viewing. The PropertyValue is the value of the property to set.

ShortPath(LongPath),ShortPath

Return the short name for the given filename. The short name is the equivalent file name in DOS 8.3 format. The given filename must exist and be accessable. If the filename is already in its short form it's just returned unaltered. The returned short name is a native Lua string.

Signal(ThreadName),bool

This function sends a 'signal' to the thread identified by 'ThreadName'. The function returns TRUE (as a native Lua boolean) if the signal was sent, or FALSE otherwise (which means the thread does not exist). It's an interface to ztSignal() and can be used to terminate an m.wait() call in some other Lua thread.

String(A),string

This function will coerce its operand into a native Lua string. Note: any Match-IT type that is an object will translate into its name.

Symbols(A),string

This function will translate its operand into a native Lua string containing its symbols. The symbols of an object are a comma separated list of components that can be used to reconstruct the object. E.g. for a measure of 2 metres, its symbols are: Metre,2. This is useful when exporting fields to some file that you want to import again. Such symbols can be blindly assigned to a file field and they will be re-constructed into the proper value for the field.

ThreadGet(),Object

This function waits for and gets a message sent to this thread. The message can consist of any LType value. If no message is available the thread will stall until one is. Use the ThreadReady() function to determine if a message is available before calling this function. Use the Type() function to determine the type of object received.

ThreadName(),Name

This function returns the name of this thread. If this thread was not started by the ThreadStart() function it returns nil. Otherwise it returns the name of the thread as returned by ThreadStart(). This can be used in 'generic' scripts to determine if it is running as the parent or one of its children. The returned name is a native Lua string.

ThreadPut(ThreadName,Object)

This function sends a message to the thread identified by ThreadName. The message sent is the value of the LType identified by Object. Messages are added to a queue for the destination thread. The sending thread does not stall.

ThreadReady(),bool

This function determines if a message is ready to be read from the message queue for this thread. It returns (a native Lua) 'true' if there is or nil otherwise. Use ThreadGet() to retrieve the message.

ThreadRelock()

This should be called immediately after calling some 3rd party library that contains its own windows message loop (e.g. IUP).

ThreadRunning(ThreadName),bool

This function determines if the identified thread is running. The thread is identified by the name returned by ThreadStart(). If the thread is running the function returns (a native Lua) true, otherwise it returns nil.

ThreadSleep(SleepTime)

This function puts the calling thread to sleep for SleepTime centiseconds. During this time other threads may execute.

ThreadStart(ScriptFileName,ThreadName),ThreadName

This function starts a new thread, gives it the name ThreadName and attempts to execute the script specified by ScriptFileName. The thread terminates when the script terminates. The thread runs in its own independent Lua state and runs indepedently of the starting parent thread. In particular, the child thread will continue to run even if the parent thread terminates. Threads can communicate values of any LType using the ThreadGet() and ThreadPut() functions. The function returns the name of the thread started as a native Lua string.

ThreadUnlock()

This should be called immediately before calling some 3rd party library that contains its own windows message loop (e.g. IUP). A call to ThreadRelock() should be made immedaitely on return from the 3rd party library. While a thread is un-locked, the script must not call any native Clarion run-time library functions, in particular it must not call any UI functions. If the library calls a 'call-back' function into your script and that function requires access to the Clarion RTL, it must temporarily re-lock and un-lock the thread while it does it.

Today(),Date

This function returns the current date.

Dates are held as a day number from a (historical) reference date. Adding a number to a date advances the date by that number of days. Subtracting a number moves the date back by that number of days.

ToType(Object,LuaTypeName),NativeThing

Convert a Match-IT LType value into the equivalent native Lua value if possible. If not the result is nil.

TransAbort(Cause),ErrorCode

This function will explicitly abort the current transaction. All file write actions from here on, up to the TransEnd will be ignored. When the TransEnd  function is executed, the whole transaction will be discarded. The error message shown at the TransEnd will be whatever was set by the Cause given  to this function. The ErrorCode returned is the error that will be shown when the transaction ends. In Lua, it's a native Lua number.

TransAborted()

This function returns the error code associated with the current transaction. If the current transaction has been aborted, implicitly or explicitly, an error code will be returned. If there is no error, 0 is returned. It's a native Lua number.

NB: Lua does not interpret 0 as false, so do this: if m.TransAborted() ~= 0 then... and not if m.TransAborted() then...

TransBegin(),ErrorCode

This function initiates the current transaction. It returns an error code or 0 if successful. In Lua, it's a native Lua number. Every file that is going to be written to in the tranaction, either explicitly or implicitly, must have first been included. If a file write is attempted without first performing a TransInclude, the transaction will abort with an error when the TransEnd is performed. A TransPrepare must have already been performed.

TransEnd(Silent),ErrorCode

This function terminates the current transaction. It returns an error code or 0 if successful. It's a native Lua number. A TransPrepare, TransInclude(s) and a TransBegin must have already been performed. All the file write actions performed since the TransBegin function are either committed or discarded by this function. If any error was detected, or the transaction was explicitly aborted, the file write actions will be discarded. Otherwise the actions are committed and the Match-IT databases are updated all at once. At the end of this function, either all the actions will be done or none of them. If the Silent option is given and set to true, then no error message is shown, otherwise an error message is shown if the transaction failed.

TransFast(),Depth

This function puts the transaction system into {\i fast} mode. In this mode transactions are not atomic and an error during a transaction could leave the file system in an inconsistent state. BEWARE! For every call to TransFast there must be a corresponding call to TransSafe. The TransFast function is intended to be used during complex import operations and in a context where you know how to recover should it fail. In fast mode transaction performance is improved because records are not flushed to the disk immediately, they are saved in memory and flushed en-masse every now and then. I.e. fast but very dangerous. USE WITH CAUTION.

The Depth returned is the fast nesting depth. It's a native Lua number.

TransInclude(FileRef,[AccessType],[Object]),ErrorCode

TransInclude(FileNo,[AccessType],[Object]),ErrorCode

This function adds the given file to the current transaction. It returns an error code or 0 if successful. It's a native Lua number. Every file that is going to be written to in the transaction, either explicitly or implicitly, must be included between the TransPrepare and the TranBegin. If a file write is attempted  without first performing a TransInclude, the transaction will abort with an error when the TransEnd is performed. A TransPrepare must have already been performed.

The file must be specified by an open FileRef (as returned by the File function) or a FileNo. The latter form is useful when the script must include the file but does not access the file buffer directly.

AccessType defines the action that will be done on the file. Possibilities are:

•(B)are - just do a bare trInclude

•(C)reate  - records are going to be added to the file

•(U)pdate - records are going to be updated

•(D)elete - records are going to be deleted

They are defined by a string containing the above ()'d characters. If omitted 'CUD' is assumed.

Object defines the object that is going to be deleted. If present the files necessary to delete that record are auto included. If not present then all files that could possibly have a reference to the file are auto included. If the Object is a FileNo then the record currently in the file buffer is to be deleted. Object is ignored for access types other than delete.

TransPrepare(Title),ErrorCode

This function prepares a new transaction with the given title. It returns an error code or 0 if successful. In Lua, it's a native Lua number. Transactions are automatically ended when the script completes. Nested prepares are permitted provided each is bracketed by a corresponding TransEnd.

No user interaction is allowed between a TransPrepare/TransEnd pair. Performing functions that result in user interaction, either directly or indirectly, will have an undefined, and propably undesirable, effect.

There is a protocol to using the 'Trans' functions. A transaction is a set of file write actions that are to be performed atomically (i.e. all or nothing). Transactions are also much faster than 'one at a time' file write actions. The protocol is:

1.TransPrepare

2.TransInclude for each file that is to be written to (including implied writes)

3.TransBegin

4.(the file write actions as required)

5.TransEnd

Failure to follow this protocol will result in an error and the script will terminate.

TransSafe(),Depth

This function must be called subsequent to every call to TransFast to restore the transaction system to its usual safe mode. Safe mode is restored automatically when the wizard terminates (for whatever reason) but you should not rely on this, as other threads cannot perform normal transactions while the transaction system is in fast mode.

The Depth returned is the fast mode nesting depth remaining. It's a native Lua number.

Type(Object,[no-coercion]),Name

This function returns the Match-IT name for the type of the object given as a native Lua string. If the no-coercion option is present and TRUE, then the name returned for a non-Match-IT object will be blank, otherwise the name of the nearest equivalent Match-IT type will be returned. E.g. a Lua Boolean will return a name of Flag when coercing or blank when not (NB: It returns an empty name, not nil).

TypeOf(Object),TypeNo

This function extracts the type number associated with the given object.

Units(Measure),Unit

This function extracts the units from a measure. E.g. Kilo from 1.6 Kg.

UnPack(RawValue,type),Object

Turns a raw packed value into an object of the given type. The raw packed value should be the result of some previous pack(object) call. The raw packed value is assumed to be appropriate to the type being created. NO CHECKING IS PERFORMED. It's is assumed you know what you are doing if you use this function.

One semi-legitimate use is:

RecNo = m.unpack(m.pack(m.int(1234)),m.Material)

This will create a material object referencing record number 1234 (whatever that might be). Sometimes useful for performing data recovery exercises when you know the RecNo's involved from somewhere else.

Unreserve(File)

This undoes the effect of the last {\i reserve} if the record is not going to be created. Unreserve is not required if Create() is performed on the file.

Update(File,[NoValidate]),Object

Update the current record (only) for the given file. The file parameter must refer to a file variable created by the file function. The file must be open. The Object RecNo is returned in the form of an LType appropriate to the file involved. If NoValidate is present and true, the usual record validation is by-passed when  the record is updated (use with caution - it becomes your responsibility to ensure value rules are not violated).

Validate(File),bool

This function will validate the record implied by the File. The function returns a TRUE flag (1) if the validation is successful, or FALSE if not. Validation is automatic when a record is Created or Updated (unless inhibited). If the validation fails the user is shown an error message.

View(Object)

This function will bring up the viewer browse for the 'object' referenced. A viewer is typically a tlaView procedure. It always returns TRUE. A viewer called up like this runs in a separate thread. It will continue to run even after the template finishes unless you explicitly close it. (Contrast this with Edit.)

ViewVFile(File),Object

This function displays the current contents of a virtual file. The current file position will be selected. The returned Object is the record selected from the list. The File must refer to a file variable for a virtual file.

Void(),Void

This function just returns a Void LType. This can be used for functions that require parameters and you don't want to give it one. A Void() can stand for anything. It's a 'god' - hands out anything you want.

Wait([TimeLimit]),ThreadName

This function waits for either the specified amount of time or until it receives a signal. It's an interface to ztWait(). It returns the ThreadName (as a native Lua string) of the signal sender if it got a signal or nil if it just timed out. If no time limit is given it'll wait forever (not a good idea!).

Watch(File)

Watch() must be called prior to a Load/Next/Previous if a subsequent update is expected. Watch() is implied when in a transaction.