• Created by user-2c621, last updated by user-eb51a on Mar 28, 2023 9 minute read

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Current »

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.

  • No labels