Shipped U_BIF Macros

You are here:

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.