Command Language > Preprocessor > Preprocessor subroutines

Subroutines are used for part of a CL script that is to be reused with different parameters each time.

For most purposes using *INSERT is preferred to a subroutine, see Preprocessor inserting scripts.

The commands used are *SBDEF, *SBEND, and *SBCALL.

Subroutines are defined between *SBDEF and *SBEND commands. To use a subroutine *SBCALL is used.

Subroutines must be defined before they are called.

Any number of calls can be made to a subroutine. Subroutines can be called within a subroutine.

The code within a subroutine is not parsed until it is called.

*SBDEF

This begins the subroutine definition. The form of this command is:

[*SBDEF snindex]

[*SBDEF snindex = para, para, ... ,para]

The snindex is the name of the subroutine.

The para is the name of an index to be used in the subroutine.

When the subroutine is called the value each para is replaced with the value of the respective index used in the *SBCALL command.

*SBEND

This ends the subroutine definition. The form of this command is:

[*SBEND snindex]

The snindex is the name of the subroutine used in the *SBDEF command.

*SBCALL

This command causes the subroutine code to be included at this point. The form of the command is:

[*SBCALL snindex]

[*SBCALL snindex = para, para, ... ,para]

The snindex subroutine called must be defined beforehand.

There must be the same number of para as was used in the *SBDEF command.

Subroutine examples

A simple subroutine without parameters could be defined as follows:

[*sbdef snRepeat]

[*set RepeatCalls = RepeatCalls + 1]

! this subroutine has been called [RepeatCalls] times

[*sbend snRepeat]

And could be used later like this:

[*set RepeatCalls = 0]

[*sbcall snRepeat]

In the above example RepeatCalls can be used in the subroutine even though it is not set until after the definition because the definition is only used when it is called.

A subroutine call can pass over indices as parameters:

[*sbdef snShow=spWhich,spValue]

! This is [spWhich] which has a value of [spValue]

[*sbend snShow]

And could be used later like this:

[*set ThisOne=56,ThisValue=10]

[*sbcall snShow=ThisOne,ThisValue]

[*set ThisOne='Last',ThisValue=99]

[*sbcall snShow=ThisOne,ThisValue]

This will output two lines:

! This is 56 which has a value of 10

! This is Last which has a value of 99

Any changes made to the values of parameters will change the passed index value:

[*sbdef snReturn=spDataSet,spWhich,spValue]

[*set spValue=[spDataSet.spWhich]]

[*sbend snReturn]

Could be used later like this:

[*data dsMyList=1,5,7]

[*set MyValue=0,MyWanted=2]

[*sbcall snReturn=dsMyList,MyWanted,MyValue]

! Value set to [MyValue]

will output:

! Value set to 5