Caché MultiValue Basic Reference
SUBR
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Returns a value from an external subroutine.
Synopsis
SUBR(routine[,arg1[,arg2...]])
Arguments
routine The name of an existing subroutine, specified as a quoted string. If an external (user-defined) subroutine, just specify the subroutine name. If a system-supplied subroutine (a system function), prefix the function name with a minus sign. A list of supported system functions is provided below. This syntax for calling system functions is provided for compatibility with UniData systems.
arg Optional — An argument, or comma-separated list of arguments to pass to the subroutine.
Description
The SUBR function calls an existing subroutine. It optionally passes the subroutine one or more argument values. SUBR returns the value supplied by the subroutine.
Commonly, SUBR is used to call user-defined subroutines. You can create a subroutine using the SUBROUTINE statement.
If the routine name begins with an asterisk (*), SUBR first looks it up as a local routine. If not found, SUBR looks it up as a global routine. If still not found, SUBR generates an error. Note that *routine processing is different in UniData emulation, as described below.
SUBR can also be used to call certain system-defined functions, using the following syntax:
SUBR('-funcname',arg1[,arg2])
Note the hyphen appended to funcname. The –funcname must be quoted. This syntax can be used in I-types; Caché MVBasic converts it to the corresponding standard MVBasic function during I-type compilation. The following MVBasic system functions are supported: ADDS, ANDS, CATS, CHARS, COUNTS, DIVS, EQS, FIELDS, FMTS, GES, GTS, ICONVS, IFS, INDEXS, LENS, LES, LTS, MODS, MULS, NES, NOTS, NUMS, OCONVS, ORS, SEQS, SPACES, SPLICE, STRS, SUBS, and SUBSTRINGS. This syntactical form is compatible with UniData.
For example, the following two calls of the MVBasic LENS function are equivalent:
mydyn="Apple":@FM:"Orange":@FM:"Banana"
PRINT LENS(mydyn)
PRINT SUBR('-LENS',mydyn)
The following two CMQL queries are equivalent:
LIST VOC EVAL "SUBR('-OCONV',12345,'D')"
LIST VOC EVAL "OCONV(12345,'D')"
SUBR, CALL, and GOSUB
The SUBR function is used to call an external subroutine that returns a value. The CALL statement is used to call an external subroutine that does not return a value. The GOSUB statement is used to call an internal subroutine.
Examples
The following example uses the SUBR function call a subroutine that computes the cube of a number:
INPUT mynum
x=SUBR('Cube',mynum)
PRINT "the cube of ":mynum:" is ":x
Emulation
In UniData and UDPICK emulations, a routine name with an initial character of * is handled as a global routine name. SUBR removes the leading * and then looks up the resulting routine name as a global routine. If the runtime environment is not a UniData emulation, a normal lookup is done on a routine name with a leading * character.
The use of $OPTIONS UNIDATA in the MVBasic source file does not activate this behavior. The handling of names with leading * is determined by the user setting in the command language at runtime. Therefore, to activate this behavior, the CEMU command must set UniData emulation before running a program that calls a routine name with a leading *.
See Also