9.1 Built-In Function Rules

Long Names

The majority of existing Built In Functions will accept only the Object Identifier when referring to LANSA Objects. Built In Functions which support long names are documented accordingly.

BIF Argument & Return Value Types

An input argument or return value type can be of type A, N, L, U, w or X.

Type Description A Alphanumeric - allows fields of type Alpha, String and Char. N Numeric - allows fields of type Packed, Signed, Float and Integer. L List U Unicode - allows fields of type Alpha, String, Char, NChar and NVarChar. w Any field type except Unicode may be supplied (excluding Lists). This is the same as X, but excluding Unicode. X Any field type may be supplied (excluding Lists).

All other field types like Date, DateTime and BLOB are classed as their own type and thus are not valid for either an argument/return type 'A', or type 'N'. To use these field types they must be coerced into the correct class using intrinsic functions. Refer to Intrinsic Functions for information about intrinsics.

User defined Built-In Functions require exact field type matches for all RDMLX field types. Therefore, if a String is used in the user defined Built-In Function declaration, then that is all that can be used when it is called. An Alpha field cannot be used. But if an argument is declared as Alpha, then String fields may be used. This anomaly exists due to support for backward compatibility. A user defined Built-In Function cannot declare an argument or return value of type X, U or w.

Fields v. Literals

When the length of an Argument is stated as being greater than 50, this is only true for Fields. Literal values are restricted to a maximum length of 50.

FFC Warning instead of FFC Error for some arguments and return values in RDMLX

If an A, u, w or X (Any) argument or return value has a maximum length of 256, and a longer field is passed, this will be a FFC Warning (the BIF may not cope with fields over 256 bytes in length) instead of an error.

If an N argument or return value has a maximum length of 30 and maximum decimals of 9, and a longer field is passed, this will be a FFC Warning (the BIF may not cope with fields over 30,9) instead of an error.

Unlimited maximum length / maximum decimals in RDMLX

Some BIF arguments and return values will be defined with a new maximum length value of 2147483647, meaning unlimited. This will mean there is no need to check the min/max field length.

Some N or X arguments and return values will be defined with a new maximum decimals value of 32767, meaning unlimited. This will mean there is no need to check the min/max decimals length.

Fields of type Integer

Fields of type Integer have a size in bytes rather than a length, have no decimal places, and are accurate.

The following table provides the implied length for each of the possible byte lengths for an Integer. The implied length is equivalent to the actual length of a signed or packed field.

# Bytes Max value (signed) Max value (unsigned) Max # digits (implied length) 1 127 255 3 2 32767 65535* 5 4 2147483647 4294967295* 10 8 9223372036854775807 18446744073709551615* 19 signed, 20 unsigned*

Fields of type Integer may only be used as numeric arguments or return values under the following conditions:

• The minimum decimals for the argument or return value is 0.

• The minimum length for the argument or return value is less than or equal to the implied length of the Integer field. For example, if the minimum length for the argument is 4, an Integer of 1 byte may not be used (as it only has an implied length of 3).

• The maximum length for the argument or return value is 2147483647 OR the maximum length for the argument or return value is greater than or equal to the implied length of the Integer field. For example, if the maximum length for an argument is 4, an Integer of 2, 4, or 8 bytes may not be used (as they have implied lengths of 5 or higher).

Fields of type Float

Fields of type Float have a size in bytes rather than a length, can be assumed to contain decimal places although not of a fixed length, and are accurate to a certain number of digits.

The following table provides the accurate length for each of the possible byte lengths for a Float. The accurate length may be considered equivalent to the actual length of a signed or packed field. The table also notes the possible number of decimal places at runtime.

# Bytes Accurate # digits (accurate length) Possible decimal places 4 6 0 - 6 8 15 0 - 15

As the value for a field of type Float may have anywhere between 0 and 15 decimal places at execution time, it is generally not considered suitable as a numeric argument to a BIF as the actual number of decimal places cannot be predicted. An FFC warning will occur if a field of type Float is used for a numeric argument, unless the maximum length of the argument is 2147483647.

However, a field of type Float is suitable as a numeric return value under the following conditions:

• The maximum length is defined as 2147483647, meaning a number of any size is acceptable, OR The maximum decimals for the return value is 1 or higher, meaning a number with decimal places is normal and accepted.

• The minimum length and the minimum decimals for the return value are less than or equal to the accurate length of the Float field. For example, if the minimum length for the argument is 10, a Float of 4 bytes may not be used (as it is only accurate to 6 digits). Or, if the minimum decimals for the argument is 7 a Float of 4 bytes may not be used (as it is only accurate to 6 decimal places).  This happens as part of normal numeric checking, given that a Float's length is adjusted as per the above table. If minimum length was 10 then a numeric of length 6 will cause an error regardless of the numeric type used. Likewise if the minimum decimal places is 7 then minimum length must be 7, or greater. Thus, a numeric of length 6 will again cause an error.

• Currently, the highest minimum decimals for any of LANSA's shipped BIF is 1. So, why the minimum decimals restriction? Because BIFs may be defined by customers (or new LANSA BIFs) that require a higher minimum # of decimal places.

Rules for Alphanumeric arguments and return values

Where an alphanumeric argument or return value is required, the following general rules apply in addition to the Built-In Function Argument & Return Value Types just listed.

• Fields of type String or Char may be used, as long as the field's length is within the range specified for the argument or return value. Note that if the maximum length is 2147483647, this means any length can be used.

• Fields of type NChar or NVarChar must be coerced to an Alphanumeric argument using the asNativeString intrinsic and have the same length restrictions as above. Refer to asNativeStringfor information about this intrinsic.

• All other RDMLX Field types must be coerced to an Alphanumeric argument using the .asString intrinsic and have the same length restrictions as above. Refer to the Intrinsic Functions for information about Intrinsics.

• Fields of type BLOB and CLOB actually contain a filename (max length 256). To access the filename the syntax #Myblob.Value can be used as well as #Myblob.asString. (It is a developer decision as to whether or not the contents of the BLOB or CLOB filename are valid for the BIF argument or return value.)

• Fields of type Date (length always 10), Time (length always 8), and DateTime (length between 19 and 29) would require asString with length checks as specified. (It is a developer decision as to whether or not the contents of the Date, Time, or DateTime are valid for the BIF argument or return value.)

Rules for Unicode arguments and return values

Argument and return types of X andU support Unicode

The rules for Unicode argument or return values are the same as for Alphanumeric, except :

• In RDML objects, a Unicode argument or return value is treated exactly the same as an Alphanumeric argument or return value.

• In RDMLX objects, fields of type NChar and NVarChar can be used directly and without data loss.

• If a Unicode argument uses a Unicode field, then a Unicode return value must use a Unicode field. This stops implicit data loss when Unicode is converted to native. Note that the reverse is not true. If a Unicode argument uses a native field, a Unicode return value may use either a Unicode field or a native field as there will be no implicit data loss.

Rules for List arguments and return values

The FFC does not check the aggregate byte length for working lists. If a specific aggregate byte length is required by the BIF you must ensure it is correct.

All Multilingual Built-In Functions

Non-DBCS SQL Server may corrupt DBCS data. DBCS SQL Server may corrupt all other language's text. To be sure of no corruption, only change text that is compatible with the database server's character set.

Note that the Visual LANSA integrated development  environment performs database IO in a different way and so avoids corruption.