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_text | The defined name that will be assigned to the argument. If this parameter is omitted then no name will be assigned.
type | The 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):
1 | Number
2 | Text
4 | Logical
8 | Reference
16 | Error
64 | Array
| If this parameter is omitted it defaults to 7.
reference | The 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_test | An 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_text | A defined name that will be used to store the current index.
start_num | The initial value to be assigned to the counter.
end_num | The last value to be assigned to the counter.
step_num | The 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_name | A defined name that will be used to store the current reference.
area_ref | The range of cells to be processed.
| If this parameter is omitted it defaults to the current selection.
skip_blanks | Whether blank cells are to be skipped. The possible values are:
FALSE | All cells in the area are processed
TRUE | Only 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.

reference | The reference of the cell where macro execution is to continue.

HALT([cancel_close])

Terminates all running macros.

cancel_close | Whether, 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_test | An 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_num | The 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_num | The 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):
1 | Number
2 | Text
4 | Logical
8 | Reference
16 | Error
64 | Array
| 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.

value | For custom functions, the value to be returned.

SET.NAME(name_text, [value])

Assigns a defined name to the specified value.

name_text | The defined name to use.
value | The 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.

reference | The cells where the values are to be stored.
values | The values to be stored.

VOLATILE([logical])

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

logical | Whether the function is volatile. The possible values are:
FALSE | The function is not volatile
TRUE | The 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_number | The 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_test | An expression that results in TRUE or FALSE.