Limitations on using Lua functions in column map expressions and procedures

Edit online

Column map expressions and procedures do not support certain data types and Lua functions.

Unsupported data types

The following data types are not supported in column map expressions and procedures:
  • XML
  • CLOB, BLOB and DBCLOB
  • ROWID

Numeric data processed in double-precision format

Column map expressions and procedures process numeric data in double-precision FLOAT format and 64bit signed INTEGER. The INTEGER format will be picked by Lua when the value has no decimal point and it can be accommodated in the 64bit INTEGER without loss of value. Note that when using the FLOAT format loss of precision may occur for decimal values with more than 14 decimal digits. Consult the Lua manuals for more details.

Use the function optim.source.getcolumnasdouble(), or optim.target.getcolumnasdouble(), to get data, in FLOAT format, from columns that have the following data types.
  • DECIMAL
  • DOUBLE
  • FLOAT
  • DECIMAL FLOAT
  • NUMBER

As of APAR PH59465, the integer type values of BIGINT (64bit integer), INTEGER (32bit integer) and SHORT (16bit integer), can be obtained using the optim.source.getcolumnvalue()/optim.target.getcolumnvalue() in the INTEGER format while the optim.source.getcolumnasdouble() and optim.target.getcolumnasdouble() functions will return the data in the FLOAT format. Accordingly, the values returned from the optim.mask() ODPP interface function will be respectively presented, as applicable, as an INTEGER or FLOAT value depending on the DATATYPE specified on the associated FLDDEF definition.

Handling invalid packed decimal value from getcolumnasdouble() function (Legacy)

It is possible to call optim.source.getcolumnasdouble() and have it detect invalid decimal packed data by utilizing the “protected call” pcall() Lua function. When using optim.source.getcolumnasdouble() with pcall(), an error will be returned when an invalid decimal value is determined. In the case where the getcolumnasdouble() function has not been invoked through pcall(), the Optim™ CM Procedure will by default return a CONVERSION ERROR/INVALID DECIMAL VALUE error and drop the row from processing.

A sample Lua chunk can be found in SAMPLIB member FOPLUAH, which demonstrates how to process a packed decimal column which might contain invalid decimal values. The invalid value is being replaced with another valid value.

Encoding

Optim for z/OS® uses native data encoding in internal processing of column map expressions and procedures. This encoding reflects the CCSID of the Optim Db2® plan. Currently an Optim Db2 plan can be bound only with EBCDIC encoding.

Lua special characters or Lua operators override

Lua chunks attached to Column Map Procedures or CM Expressions might contain certain special characters, or Lua operators, which have different (hexadecimal) code point values depending on the CCSID of the terminal session used to enter the Lua chunk. The Lua compiler embedded in Optim has been configured to interpret correctly Lua chunks entered using CCSID 1047/037 and compatible CCSIDs. Compiler errors might be reported when attempting to process Lua chunks entered using different CCSIDs.

To prevent such errors, the Optim Lua compiler has been modified to accept a special dedicated comment statement -- LuaSpcChr, followed by values to define the representation of certain Lua special characters and operators. Comment statement -- LuaSpcChr can appear anywhere in the chunk before the first use of any of the characters #\~¬[]{}.

The special characters must be specified in the following order and all characters have to be specified:
  • -- LuaSpcChr #\~¬[]{} (in the exact order)
  • # = value for the Lua length operator
  • \ = value for the backslash escape character
  • ~ = value for the not inequality operator
  • ¬ = value for the exponentiation operator
  • [ = value for the left square bracket character
  • ] = value for the right square bracket character
  • { = value for the left curly brace character
  • } = value for the right curly brace character
For example, the exponentiation operator (¬) is defined at hexadecimal code point B0 in EBCDIC CCSID 37. However, in EBCDIC CCSID 500 it is defined at code point 5F. In addition, the left and right brackets are defined at code points 4A and 5A in CCSID 500 respectively, instead of at BA and BB as in CCSID 37. Therefore, when using a terminal at CCSID 500, you can specify the following comment for Optim to recognize and process these operators and characters properly in your Lua chunk (hex values listed below characters):
-- LuaSpcChr #\~¬[]{}
664DA8E98C8947EA545CD
0003412733890B01FAA00

Special situation where legacy target is a decimal field

CM Lua will check if a decimal field target is a legacy file and whether the sign was being honored. Function will check whether a legacy file with a decimal packed field expects a signed or un-signed number and set the sign nibble accordingly. For this to work as expected, the legacy table decimal field should be defined with a COBOL copybook and the Picture clause set with the expected result, either signed or un-signed. An export of the legacy table should show that Language C (for COBOL) is specified, and SIGNED value Y or N as desired. An example of a field definition of a decimal field defined as unsigned:
FIELD (DECDATE
   TYPE DECIMAL  LEVEL 5  LENGTH 5
   PRECISION 8
SIGNED N
PICTURE “9(8)” )

Unsupported functions

The following categories of functions are not supported in column map expressions and procedures.
  • Functions for loading and building modules in the Lua package library:
    • module
    • require
    • package.cpath
    • package.loaded
    • package.loaders
    • package.loadlib
    • package.path
    • package.preload
    • package.seeall
  • string.dump()