Macro control functions

[ ] indicates optional parameters

ARGUMENT([name_text], [type], [reference])
BREAK()
ELSE()
ELSE.IF(logical_test)
END.IF()
FOR(counter_text, start_num, end_num, [step_num])
FOR.CELL(ref_name, [area_ref], [skip_blanks])
GOTO(reference)
HALT([cancel_close])
IF(logical_test)
NEXT()
RESTART([level_num])
RESULT([type_num])
RETURN([value])
SET.NAME(name_text, [value])
SET.VALUE(reference, values)
VOLATILE([logical])
WAIT([serial_number])
WHILE(logical_test)


ARGUMENT([name_text], [type], [reference])

Defines an argument for a custom function.

name_textThe defined name that will be assigned to the argument. If this parameter is omitted then no name will be assigned.
typeThe acceptable data type(s) for the argument value. It can be any combination of the following (to specify more than one value, add the numbers together):
1Number
2Text
4Logical
8Reference
16Error
64Array
If this parameter is omitted it defaults to 7.
referenceThe cell reference where the argument value will be stored. If this parameter is omitted then the argument value will not be stored.


BREAK()

Ends the processing of a FOR, FOR.CELL or WHILE loop. The macro will continue with the statement after the NEXT function.



ELSE()

Introduces the block of statements to be processed when the corresponding IF or ELSE.IF condition is false.



ELSE.IF(logical_test)

Specifies another logical test that conditions a block of statements when the corresponding IF or ELSE.IF condition is false.

logical_testAn expression that results in TRUE or FALSE.


END.IF()

Specifies the end of the block of statements conditioned by the corresponding IF or ELSE.IF.



FOR(counter_text, start_num, end_num, [step_num])

Performs a group of instructions a specified number of times. The end of the group is indicated by a NEXT function.

counter_textA defined name that will be used to store the current index.
start_numThe initial value to be assigned to the counter.
end_numThe last value to be assigned to the counter.
step_numThe value to be added to the counter each time around the loop. If this parameter is omitted it defaults to 1.


FOR.CELL(ref_name, [area_ref], [skip_blanks])

Performs a group of instructions for each cell in a specified area. The end of the group is indicated by a NEXT function.

ref_nameA defined name that will be used to store the current reference.
area_refThe range of cells to be processed.
If this parameter is omitted it defaults to the current selection.
skip_blanksWhether blank cells are to be skipped. The possible values are:
FALSEAll cells in the area are processed
TRUEOnly the non-blank cells in the area are processed
If this parameter is omitted it defaults to FALSE.


GOTO(reference)

Forces the macro to continue with the statement at the reference.

referenceThe reference of the cell where macro execution is to continue.


HALT([cancel_close])

Terminates all running macros.

cancel_closeWhether, in an Auto_Close macro, to prevent the workbook from being closed (not currently implemented).


IF(logical_test)

Specifies a logical test that conditions the execution of a block of statements.

logical_testAn expression that results in TRUE or FALSE.


NEXT()

Specifies the end of the block of statements contained in a FOR, FOR.CELL or WHILE loop.



RESTART([level_num])

Specifies the number of levels that will be skipped when this macro returns.

level_numThe number of levels to skip. If this parameter is omitted then all levels are skipped.


RESULT([type_num])

Specifies the return type of a user-defined function.

type_numThe preferred data type(s) for the return value. It can be any combination of the following (to specify more than one value, add the numbers together):
1Number
2Text
4Logical
8Reference
16Error
64Array
If this parameter is omitted it defaults to 7.


RETURN([value])

Forces the macro to end, and if it is a custom function then to return the specified value.

valueFor custom functions, the value to be returned.


SET.NAME(name_text, [value])

Assigns a defined name to the specified value.

name_textThe defined name to use.
valueThe value to be associated with the name. If this parameter is omitted then the name is deleted.


SET.VALUE(reference, values)

Stores the specified values in the specified cells on the macro sheet. Do not use this function to try to update cells on a worksheet.

referenceThe cells where the values are to be stored.
valuesThe values to be stored.


VOLATILE([logical])

Specifies whether a user-defined function is to be recalculated each time the worksheet changes.

logicalWhether the function is volatile. The possible values are:
FALSEThe function is not volatile
TRUEThe function is volatile
If this parameter is omitted it defaults to TRUE.


WAIT([serial_number])

Forces the macro to wait until the date/time specified by the serial number.

serial_numberThe date/time when the macro is to resume. If this parameter is omitted the macro does not wait.


WHILE(logical_test)

Specifies a logical test that conditions the execution of a block of statements multiple times. The statements between the WHILE and NEXT functions will be repeated as long as the logical test returns the value TRUE.

logical_testAn expression that results in TRUE or FALSE.