SUBR()

SUBR()

Top  Previous  Next

 

The SUBR() function calls a subroutine as a function in an expression. It is normally only used in dictionary I-type items.

 

 

Format

 

SUBR(name {,arg1 {, arg2...})

 

where

 

nameevaluates to the name of the subroutine to be called.

 

arg1, etcare the arguments to the subroutine.

 

 

The SUBR() function calls catalogued subroutine name, passing arg1, arg2, etc to it as its arguments. The subroutine must be written to have an additional first argument through which it returns its result which is used as the value of the SUBR() function.

 

A statement such as

 

A = B + SUBR("EVALUATE", C, D)

 

is equivalent to

 

CALL EVALUATE(X, C, D)

A = B + X

 

The name argument may be any expression that evaluates to the name of the subroutine. The catalogue look-up process is performed for each execution of the SUBR() function unlike a CALL statement where the look-up is performed just once for each invocation of the calling program.

 

When used from a dictionary I-type expression evaluated by the query processor, the @ID and @RECORD variables will contain the id and data of the record currently being processed. If the subroutine called with SUBR() modifies these variables, perhaps to use the ITYPE() function internally, the original values must be saved and reinstated if the dictionary item is to be usable within the query processor.

 

When used in a QMBasic program, the SUBR() function does not support the MAT keyword to pass a whole matrix as an argument. The CALL statement must be used to achieve this.

 

 

Example

 

  SUBROUTINE CUST.ORD(RESULT, CUST.NO)

  $INCLUDE FILES.H

     SELECTINDEX 'CUST', CUST.NO FROM ORDERS.F TO 1

     READLIST RESULT FROM 1 ELSE NULL

     RETURN

  END

 

The above subroutine takes a customer number as its second argument and uses this to access an alternate key index, returning a list of all orders that were placed by the given customer. This example assumes that the ORDERS.F file variable is in a common block defined in the FILES.H include record and that the file is already open.

 

The subroutine could alternatively be written as a function:

  FUNCTION CUST.ORD(CUST.NO)

  $INCLUDE FILES.H

     SELECTINDEX 'CUST', CUST.NO FROM ORDERS.F TO 1

     READLIST RESULT FROM 1 ELSE NULL

     RETURN RESULT

  END

 

In either case, assuming that the subroutine or function is catalogued as CUST.ORD, it could be used from within a dictionary I-type item by use of a SUBR() function such as:

  SUBR('CUST.ORD', CUST.NO)

where CUST.NO is the name of a field within the data records being processed.