19.2.8 Shipped U_BIF Macros
To assist you in coding User Defined Built-In Functions, the following U_BIF macros are shipped with Visual LANSA.
Please note that these macros were specifically designed to make programming user defined Built-In Functions easier, and to insulate them from future changes.
They do not have a high degree of error handling and are not designed to be "bullet proof". It is assumed that the developer using them will be capable and will understand how to use them effectively.
The U_BIF macros are defined in header file X_BIF000.H that is supplied on the LANSA Windows product CD. Do not change this file as it is totally replaced every time that Visual LANSA is upgraded and your changes will be lost.
Note that the arguments must be specified in the order they are listed in the Arguments column.
| Macro Name | Arguments | Description/ Comments |
|
U_BIF_COLUMN_ERROR |
None |
Fatal error message text string |
|
U_BIF_LIST_ERROR |
None |
Fatal error message text string |
|
U_BIF_LANSA_FUNCTION |
None |
Name of current function. |
|
U_BIF_LANSA_FUNCTION_DESC |
None |
Description of current function. |
|
U_BIF_LANSA_PROCESS |
None |
Name of current process. |
|
U_BIF_LANSA_PROCESS_DESC |
None |
Description of current process. |
|
U-BIF-GET_HAB |
_R=HAB |
Returns current HAB into _R. |
|
U-BIF-GET_HMQ |
_R=HMQ |
Returns current HMQ into _R.. |
|
U_BIF_GET_HWND |
_R = HWND |
Returns current HWND into _R. |
|
U_BIF_FATAL_ERROR |
None |
Tests for fatal error state as in "if (U_BIF_FATAL_ERROR)" |
|
U_BIF_ISSUE_FATAL_ERROR |
_T = "text" or X_PVCHAR |
Issues a fatal error and returns control to the caller. |
|
U_BIF_HANDLE_FATAL_ERROR |
None |
Tests for fatal error state and issues a return if one exists. |
|
U_BIF_SET_GOOD_RETURN |
None |
Indicates BIF ended normally to the calling RDML function. |
|
U_BIF_SET_BAD_RETURN |
None |
Indicates BIF ended abnormally to the calling RDML function. |
|
U_BIF_RETURN |
None |
Returns control to the calling RDML function. Issues a C return. |
|
U_BIF_SHUTDOWN_REQUEST |
None |
Tests for a Built-In Function shutdown request as in the example "if (U_BIF_SHUTDOWN_REQUEST)" |
|
U_BIF_STANDARD_PARAMETERS |
None |
Defines the standard parameter list for a user defined Built-In Function. |
|
U_BIF_STANDARD_ARGUMENTS |
None |
Defines the standard set of arguments to be passed to a user defined Built-In Function. |
|
U_BIF_OPERATING_SYSTEM_WIN95 |
None |
Use in a C #ifdef or #elif to test compilation under Windows 9x/200x. |
|
U_BIF_OPERATING_SYSTEM_WIN |
None |
Use in a C #ifdef or #elif to test compilation under either Windows 9x/200x. |
|
U_BIF_OPERATING_SYSTEM_UNIX |
None |
Use in a C #ifdef or #elif to test compilation under UNIX(Linux) operating system. |
|
U_BIF_GET_ARGUMENT_COUNT |
_N = X_SHORT |
Returns a count of the total number of arguments passed into the Built-In in _N. |
|
U_BIF_ARGUMENT_PASSED |
_N = X_SHORT |
Used in an "if ()" statement to test whether argument number _N was passed by the caller. |
|
U_BIF_GET_RETURN_COUNT |
_N = X_SHORT |
Returns a count of the total number of return values requested by the caller in _N. |
|
U_BIF_RETURN_REQUIRED |
_N = X_SHORT |
Used in an "if ()" statement to test whether return values _N was requested by the caller. |
|
U_BIF_GET_ARG_AS_SHORT |
_N = X_SHORT _S = X_SHORT |
Retrieves argument number _N as an X_SHORT value into _S. If _N is invalid, or argument _N was not passed, _S is not changed by the operation. _N is the argument number in the C style numbered from 0. |
|
U_BIF_GET_ARG_AS_LONG |
_N = X_SHORT _L = X_LONG |
Retrieves argument number _N as an X_LONG value into _S. If _N is invalid, or argument _N was not passed, _L is not changed by the operation. _N is the argument number in the C style numbered from 0. |
|
U_BIF_GET_ARG_AS_DOUBLE |
_N = X_SHORT _D = X_DOUBLE |
Retrieves argument number _N as an X_DOUBLE value into _S. If _N is invalid, or argument _N was not passed, _D is not changed by the operation. _N is the argument number in the C style numbered from 0. |
|
U_BIF_GET_ARG_AS_VCHAR |
_N = X_SHORT _V = X_VCHAR |
Retrieves argument number _N as an X_VCHAR value into _V. If _N is invalid, or argument _N was not passed, _V is not changed by the operation. _N is the argument number in the C style numbered from 0. |
|
U_BIF_SET_RET_FROM_SHORT |
_N = X_SHORT _S = X_SHORT |
Sets return value number _N from the X_SHORT value specified by _S. If _N is invalid, or return value _N is not required, the entire request is ignored. _N is the return value number in the C style numbered from 0. |
|
U_BIF_SET_RET_FROM_LONG |
_N = X_SHORT _L = X_LONG |
Sets return value number _N from the X_LONG value specified by _L. If _N is invalid, or return value _N is not required, the entire request is ignored. _N is the return value number in the C style numbered from 0. |
|
U_BIF_SET_RET_FROM_DOUBLE |
_N = X_SHORT _D = X_DOUBLE |
Sets return value number _N from the X_DOUBLE value specified by _D. If _N is invalid, or return value _N is not required, the entire request is ignored. _N is the return value number in the C style numbered from 0. |
|
U_BIF_SET_RET_FROM_VCHAR |
_N = X_SHORT _V = X_VCHAR |
Sets return value number _N from the X_VCHAR value specified by _V. If _N is invalid, or return value _N is not required, the entire request is ignored. _N is the return value number in the C style numbered from 0. |
|
U_BIF_DECLARE_LIST_POINTER |
_L = C Name |
Declares a pointer to a working list received as an argument or to be returned. This is a declarative operation so it must be positioned accordingly. Names like pListArg1, pListArg7, and pListRet5 are recommended. A declared list pointer must be set before any attempt is made to reference this list in any way. |
|
U_BIF_SET_ARG_LIST_POINTER |
_L = C Name _A = X_SHORT |
Initializes a list pointer that has been previously declared by U_BIF_DECLARE_LIST_POINTER(_L). _A is the argument number of the Built-In Function argument that contains the working list. If _A is invalid, or argument _A was not passed, a fatal error will result, terminating the Built-In Function. |
|
U_BIF_SET_RET_LIST_POINTER |
_L = C Name _A = X_SHORT |
Initializes a list pointer that has been previously declared by U_BIF_DECLARE_LIST_POINTER(_L). _A is the return value number of the Built-In Function return value that contains the working list. If _A is invalid, or return value _A is not required, a fatal error will result, terminating the Built-In Function. |
|
U_BIF_GET_ENTRY_FROM_LIST |
_L = C Name _E = X_LIST_COUNT _R = X_CHAR |
Retrieves entry number _E from the working list pointed to by _L. If the entry was found _R is returned as YES('Y'), otherwise it is returned as NO('N'). List entries are numbered from 1 to N. This is different to most other U_BIF macros that number in the C style from 0 to (N - 1). |
|
U_BIF_CLEAR_LIST |
_L = C Name |
Clears all entries from the list pointed to by _L. |
|
U_BIF_ADD_ENTRY_TO_LIST |
_L = C Name |
Adds a new entry to the list pointed to by _L. |
|
U_BIF_UPDATE_ENTRY_IN_LIST |
_L = C Name |
Updates the current entry in the working list pointed to by _L. |
|
U_BIF_GET_LIST_CURRENT_ENTRYS |
_L = C Name _R = X_LIST_COUNT |
Returns into _R a count of the current number of entries in the working list pointed to by _L. |
|
U_BIF_GET_LIST_MAXIMUM_ENTRYS |
_L = C Name _R = X_LIST_COUNT |
Returns into _R the maximum number of entries allowed in the working list pointed to by _L. |
|
U_BIF_GET_LIST_ENTRY_LENGTH |
_L = C Name _R = X_LIST_COUNT |
Returns into _R the aggregate byte length of an entry in the working list pointed to by _L. |
|
U_BIF_GET_LIST_COLUMN_TOTAL |
_L = C Name _R = X_SHORT |
Returns into _R the total number of columns defined in the working list pointed to by _L. |
|
U_BIF_GET_LIST_COLUMN_ATTRIBS |
_L = C Name _C = X_SHORT _T = X_CHAR _E = X_ULONG _D = X_SHORT _B = X_SHORT |
Queries the definition of column number _C (in 0 -> (N-1) style) of the working list pointed to by _L and returns : _T : The column type _E : The column length/total digits _D : The number of decimal positions _B : The byte length _T is returned according to these types defined in X_FUNSTR.H .... X_TYPE_ALPHA= Alphanumeric, X_TYPE_CHAR = Char or String, X_TYPE_PACKED = Packed Decimal, X_TYPE_SIGNED = Signed Decimal, X_TYPE_FLOAT = Float, X_TYPE_INTEGER = Integer, X_TYPE_LONG= X_LONG format, X_TYPE_DOUBLE = X_DOUBLE format, X_TYPE_DATETIME = DateTime, X_TYPE_DATE = Date , X_TYPE_TIME = Time, X_TYPE_BOOLEAN= Boolean, X_TYPE_BINARY = Binary or VarBinary, X_TYPE_CLOB = CLOB, X_TYPE_BLOB = BLOB. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. For X_TYPE_CLOB or X_TYPE_BLOB _E is the maximum length that the file name can be, not the content of the file.
|
|
U_BIF_LIST_COLUMN_NAME_LEN |
None |
Defines the length of column name (i.e. currently 10 bytes). |
|
U_BIF_GET_LIST_COLUMN_NAME |
_L = C Name _C = X_SHORT _R = X_VCHAR |
Queries the definition of column number _C (in 0 -> (N-1) style) of the working list pointed to by _L and returns the name of the column (i.e. the RDML field name). _R must be of type X_VCHAR and must be at least (U_BIF_COLUMN_NAME_LEN + 1) bytes long. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. |
|
U_BIF_GET_LIST_COLUMN_AS_SHORT |
_L = C Name _C = X_SHORT _R = X_SHORT |
Returns the value of column number _C (in 0 -> (N-1) style) from the current entry of the working list pointed to by _L. The value is returned in _R which must be of type X_SHORT. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. |
|
U_BIF_GET_LIST_COLUMN_AS_LONG |
_L = C Name _C = X_SHORT _R = X_LONG |
Returns the value of column number _C (in 0 -> (N-1) style) from the current entry of the working list pointed to by _L. The value is returned in _R which must be of type X_LONG. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. |
|
U_BIF_GET_LIST_COLUMN_AS_LONGLONG |
_L = C Name _C = X_SHORT _R = X_LONGLONG |
Returns the value of column number _C (in 0 -> (N-1) style) from the current entry of the working list pointed to by _L. The value is returned in _R which must be of type X_LONGLONG. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. |
|
U_BIF_GET_LIST_COLUMN_AS_DOUBLE |
|
Returns the value of column number _C (in 0 -> (N-1) style) from the current entry of the working list pointed to by _L. The value is returned in _R which must be of type X_DOUBLE. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. |
|
U_BIF_GET_LIST_COLUMN_AS_VCHAR |
_L = C Name _C = X_SHORT _R = X_VCHAR |
Returns the value of column number _C (in 0 -> (N-1) style) from the current entry of the working list pointed to by _L. The value is returned in _R which must be of type X_VCHAR. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. |
|
U_BIF_SET_LIST_COLUMN_FROM_SHORT |
_L = C Name _C = X_SHORT _R = X_SHORT |
Sets the value of column number _C (in 0 -> (N-1) style) into the current entry of the working list pointed to by _L. The value is set from _R which must be of type X_SHORT. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. The current entry in a list must be subsequently inserted or updated for it to actually be applied to the stored list. |
|
U_BIF_SET_LIST_COLUMN_FROM_LONG |
_L = C Name _C = X_SHORT _R = X_LONG |
Sets the value of column number _C (in 0 -> (N-1) style) into the current entry of the working list pointed to by _L. The value is set from _R which must be of type X_LONG. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. The current entry in a list must be subsequently inserted or updated for it to actually be applied to the stored list. |
|
U_BIF_SET_LIST_COLUMN_FROM_LONG |
_L = C Name _C = X_SHORT _R = X_LONGLONG |
Sets the value of column number _C (in 0 -> (N-1) style) into the current entry of the working list pointed to by _L. The value is set from _R which must be of type X_LONGLONG. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. The current entry in a list must be subsequently inserted or updated for it to actually be applied to the stored list. |
|
U_BIF_SET_LIST_COLUMN_FROM_DOUBLE |
_L = C Name _C = X_SHORT _R = X_DOUBLE |
Sets the value of column number _C (in 0 -> (N-1) style) into the current entry of the working list pointed to by _L. The value is set from _R which must be of type X_DOUBLE. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. The current entry in a list must be subsequently inserted or updated for it to actually be applied to the stored list. |
|
U_BIF_SET_LIST_COLUMN_FROM_VCHAR |
_L = C Name _C = X_SHORT _R = X_VCHAR |
Sets the value of column number _C (in 0 -> (N-1) style) into the current entry of the working list pointed to by _L. The value is set from _R which must be of type X_VCHAR. If _C is an invalid column number a fatal error will result, terminating the Built-In Function. The current entry in a list must be subsequently inserted or updated for it to actually be applied to the stored list. |