System-supplied subroutines and functions

Synergy DBL provides a set of prewritten external subroutines, functions, and data reference operations. For detailed descriptions of these routines, refer to the following:

System-supplied subroutines

If you are using subroutines from one of the Synergy DBL APIs, use the links above to see if there are files you need to .INCLUDE or ELBs that you must link with.

System-supplied subroutines have the same characteristics and are called in the same way as subroutines you write yourself. See External subroutines for more information.

System-supplied functions

There are two categories of system-supplied functions: intrinsic and external. The intrinsic functions are defined internally and are part of the runtime. The external functions must be declared with the EXTERNAL FUNCTION statement before they can be used. Some of the Synergy DBL API functions are external. Special requirements for functions that are included in any of the Synergy DBL APIs (see list above), such as files that must be included or the need to declare the functions, are documented with the API.

Generally speaking, system-supplied functions have the same characteristics as functions you write yourself. (See Functions and ^VAL functions.) There are, however, some differences that you should be aware of.

You cannot call system-supplied functions as subroutines, unless the subroutine syntax is explicitly specified in the documentation for that function. (For example, the syntax for %DATE shows both formats.)
Most system-supplied functions that return a numeric data type return an integer rather than a decimal. If you pass an intrinsic function’s return value to a subroutine that is expecting a decimal, as in the following example,

xcall sub(^size(fld))

you must either declare the corresponding argument an integer (i) or numeric (n) data type, or use the numeric argument compiler option to map all decimal-type arguments to numeric.

The following two points apply to intrinsic functions only:

In addition to using intrinsic functions any place a literal can appear, you can also use an intrinsic function in a data division expression as long as it can be evaluated at compile time. For example, if an intrinsic function used in a data division expression includes a variable, it cannot be evaluated at compile time and will result in an error.
Intrinsic functions that return integer results default to size i4 for 32-bit machines and i8 for 64-bit machines. If the value doesn’t fit into an i4 value, i8 is used.

Data reference operations

A data reference operation either allows data to be accessed as any valid data type or determines data characteristics. Each data reference operation name is preceded by a caret (^). Although all data reference operations except ^M can also be referenced as functions (for example, you can reference ^ARG as %ARG), we recommend that you always use a caret.

Data reference operations that return integer results default to size i4 for 32-bit machines and i8 for 64-bit machines. If the value doesn’t fit into an i4 value, i8 is used.

Data reference operations can be divided into four categories:

Casting functions, which allow data to be accessed as any valid data type regardless of the actual data type with which it was declared:
^A
^D
^MARRAY
^ARG
^F
^PASSTHRU
^ARGA
^I

^ARGN ^M
Data conversion operations, which convert a piece of data and return a specified type:
^B
^X
^O
Compile-time functions:
^ARGNUM
^VARIANT
^DEFINED
Data characteristic operations, which return data characteristics such as the length of an expression or whether an argument has been passed:
^ADDR
^ARGTYPE
^PASSED
^ARGDIM
^DATATYPE
^SIZE

^A	^D	^MARRAY
^ARG	^F	^PASSTHRU
^ARGA	^I
^ARGN	^M

^ARGNUM	^VARIANT
^DEFINED

^ADDR	^ARGTYPE	^PASSED
^ARGDIM	^DATATYPE	^SIZE