EXCEL macro functions tutorial with examples


Télécharger EXCEL macro functions tutorial with examples

Formation Excel en ligne par vidéo

205 leçons vidéos + 20 Livres PDF + 20 TP + Sous supervision + Certificat de réussite à la fin du cours



★★★★★★★★★★3.5 étoiles sur 5 basé sur 1 votes.
Votez ce document:

Télécharger aussi :


 
 
 

CONTENTS

Introduction .. 22

A1.R1C1 . 23

ABSREF 23

ACTIVATE . 24

, . 25

26

. 27

ADD.ARROW . 27

28

ADD.CHART.AUTOFORMAT . 28

ADD.COMMAND 29

ADDIN.MANAGER .. 33

. 34

.. 34

ADD.OVERLAY 36

36

ADD.TOOLBAR .. 39

ALERT . 40

ALIGNMENT 42

ANOVA1 .. 44

ANOVA2 .. 45

ANOVA3 .. 46

APP.ACTIVATE 46

APP.ACTIVATE.MICROSOFT 48

APPLY.NAMES . 48

APPLY.STYLE 50

APP.MAXIMIZE .. 50

APP.MINIMIZE 50

. 51

APP.RESTORE . 52

52

APP.TITLE . 53

ARGUMENT . 53 . 55

.OBJECT .. 57

.. 57

. 58

ATTACH.TOOLBARS 59

AUTO.OUTLINE . 59

AXES 60

BEEP . 60

BORDER .. 61

BREAK 62

.FRONT . 62

CALCULATE.DOCUMENT .. 63

.. 63

CALCULATION 63

CALLER . 65

. 67

. 67

CELL.PROTECTION .. 68

. 69

69

CHART.TREND 70

CHART.WIZARD .. 72

CHECKBOX.PROPERTIES 74

CHECK.COMMAND 75

CLEAR 76

CLEAR.OUTLINE .. 78

. 78

CLOSE 78

.. 79

COLOR.PALETTE . 80

COLUMN.WIDTH . 80

COMBINATION .. 81

CONSOLIDATE .. 82

CONSTRAIN.NUMERIC 84 COPY 84

COPY.CHART 85

COPY.PICTURE .. 85

. 87

CREATE.NAMES 87

CREATE.OBJECT .. 88

CREATE.PUBLISHER .. 92

CUSTOMIZE.TOOLBAR .. 94

CUSTOM.REPEAT 95

. 96

CUT 97

DATA.DELETE . 97

.. 98

, . 98

98

DATA.LABEL .. 99

DATA.SERIES .. 99

.. 101

DEFINE.STYLE . 103

DEFINE.STYLE Syntax 1 103

DEFINE.STYLE Syntaxes 2 - 7 . 104

DELETE.ARROW 106

106

DELETE.CHART.AUTOFORMAT . 106

DELETE.COMMAND .. 107

DELETE.FORMAT .. 108

. 108

.. 109

DELETE.OVERLAY 109

DELETE.STYLE . 109

.. 110

DELETE.TOOLBAR .. 110

DEMOTE 111

DEREF . 111 DESCR 112

. 113

DIRECTORY . 116

DISABLE.INPUT . 117

DISPLAY 117

DISPLAY Syntax 1 . 117

DISPLAY Syntax 2 . 118

DOCUMENTS . 120

DUPLICATE .. 121

ECHO 121

EDITBOX.PROPERTIES 122

EDIT.COLOR .. 122

EDIT.DELETE . 123

EDITION.OPTIONS 124

EDIT.OBJECT . 127

EDIT.REPEAT . 128

EDIT.SERIES . 128

129

ELSE .. 130

.. 130

EMBED 131

ENABLE.COMMAND .. 131

ENABLE.OBJECT 132

ENABLE.TIPWIZARD .. 133

.. 133

133

.. 134

ERROR 135

ERRORBAR.X, ERRORBAR.Y 136

EVALUATE . 139

EXEC . 139

EXECUTE . 141

EXPON . 142

EXTEND.POLYGON 143 EXTRACT .143

FCLOSE . 144

FILE.CLOSE . 144

FILE.DELETE .. 145

FILES 146

. 148

, , FILL.RIGHT, 149

FILL.GROUP . 149

FILTER 150

FILTER.ADVANCED .. 151

. 151

.. 151

FONT . 152

FONT.PROPERTIES 152

FOPEN . 154

FOR . 155

156

157

FORMAT.CHART . 159

FORMAT.CHARTTYPE . 161

. 162

FORMAT.LEGEND 164

. 165

167

Syntax 1 . 168

Syntax 2 . 169

Syntax 3 . 169

FORMAT.NUMBER .. 170

FORMAT.OVERLAY . 170

FORMAT.SHAPE . 172

.. 174

Syntax 1 . 174

Syntax 2 . 174

.. 175 FORMULA 177

FORMULA Syntax 1 .. 177

FORMULA Syntax 2 .. 179

FORMULA.ARRAY . 180

FORMULA.CONVERT 181

. 182

.. 182

, . 184

184

FORMULA.REPLACE . 185

FOURIER .. 187

FPOS . 187

FREAD . 188

FREADLN . 189

FREEZE.PANES 189

FSIZE 190

FTESTV .. 191

FULL .. 191

FULL.SCREEN 191

FUNCTION.WIZARD . 192

FWRITE . 192

FWRITELN . 192

193

193

GALLERY.3D.COLUMN .. 194

.. 194

.. 194

GALLERY.3D.SURFACE 194

194

.. 195 GALLERY.COLUMN . 195

GALLERY.CUSTOM . 196

GALLERY.DOUGHNUT 196

. 196 .197

GALLERY.RADAR .. 197

GALLERY.SCATTER 198

.. 198

Syntax 1 . 198

Syntax 2 . 199

200

206

.. 209

GET.DOCUMENT 210

GET.FORMULA . 220

.. 221

. 222

.. 223

GET.OBJECT 224

GET.PIVOT.FIELD 233

.. 235

GET.PIVOT.TABLE .. 237

.. 239

GET.TOOLBAR . 241

GET.WINDOW .. 243

GET.WORKBOOK . 246

GET.WORKSPACE 250

.. 257

GOTO 258

GRIDLINES .. 259

GROUP 259

ECHO 260

EDITBOX.PROPERTIES 260

EDIT.COLOR .. 261

EDIT.DELETE . 262

EDITION.OPTIONS 263

EDIT.OBJECT . 266

EDIT.REPEAT . 266 EDIT.SERIES .266

268

ELSE .. 268

.. 268

EMBED 269

ENABLE.COMMAND .. 270

ENABLE.OBJECT 271

ENABLE.TIPWIZARD .. 271

.. 271

272

.. 272

ERROR 273

ERRORBAR.X, ERRORBAR.Y 275

EVALUATE . 277

EXEC . 278

EXECUTE . 279

EXPON . 281

EXTEND.POLYGON 281

EXTRACT . 282

FCLOSE . 282

FILE.CLOSE . 283

FILE.DELETE .. 284

FILES 285

. 286

, , FILL.RIGHT, 287

FILL.GROUP . 288

FILTER 288

FILTER.ADVANCED .. 289

. 290

.. 290

FONT . 290

FONT.PROPERTIES 290

FOPEN . 292

FOR . 294 295

296

FORMAT.CHART . 298

FORMAT.CHARTTYPE . 300

. 301

FORMAT.LEGEND 303

. 304

306

Syntax 1 . 307

Syntax 2 . 308

Syntax 3 . 308

FORMAT.NUMBER .. 309

FORMAT.OVERLAY . 309

FORMAT.SHAPE . 311

.. 313

Syntax 1 . 313

Syntax 2 . 313

.. 314

FORMULA 316

FORMULA Syntax 1 .. 316

FORMULA Syntax 2 .. 318

FORMULA.ARRAY . 319

FORMULA.CONVERT 320

. 321

.. 321

, . 323

323

FORMULA.REPLACE . 324

FOURIER .. 326

FPOS . 326

FREAD . 327

FREADLN . 328

FREEZE.PANES 328

FSIZE 329 FTESTV ..329

FULL .. 330

FULL.SCREEN 330

FUNCTION.WIZARD . 330

FWRITE . 331

FWRITELN . 331

332

332

GALLERY.3D.COLUMN .. 332

.. 333

.. 333

GALLERY.3D.SURFACE 333

333

.. 334

GALLERY.COLUMN . 334

GALLERY.CUSTOM . 334

GALLERY.DOUGHNUT 335

. 335

. 336

GALLERY.RADAR .. 336

GALLERY.SCATTER 336

.. 337

Syntax 1 . 337

Syntax 2 . 337

339

345

.. 348

GET.DOCUMENT 349

GET.FORMULA . 359

.. 360

. 361

.. 362

GET.OBJECT 363

GET.PIVOT.FIELD 372 ..374

GET.PIVOT.TABLE .. 376

.. 378

GET.TOOLBAR . 380

GET.WINDOW .. 382

GET.WORKBOOK . 385

GET.WORKSPACE 389

.. 396

GOTO 397

GRIDLINES .. 398

GROUP 398

HALT .. 399

HELP .. 399

HIDE .. 401

HIDE.DIALOG .. 401

HIDE.OBJECT 401

HISTOGRAM 402

HLINE .. 403

HPAGE . 404

HSCROLL . 404

IF 405

Tips . 405

INITIATE . 406

INPUT .. 407

INSERT .. 409

INSERT.OBJECT 410

INSERT.PICTURE . 411

INSERT.TITLE .. 412

JUSTIFY . 413

LABEL.PROPERTIES . 413

LAST.ERROR .. 414

LEGEND . 414

LINE.PRINT .. 415

LINK.COMBO . 417 LINK.FORMAT ..418

LINKS .. 418

LISTBOX.PROPERTIES . 419

LIST.NAMES 420

MACRO.OPTIONS 421

.MAILER . 421

MAIL.DELETE.MAILER .. 422

.MAILER 422

MAIL.FORWARD 423

MAIL.LOGOFF 423

MAIL.LOGON . 423

.LETTER .. 424

MAIL.REPLY . 424

425

.MAILER . 425

MAIN.CHART . 425

426

MCORREL 426

MCOVAR .. 427

MENU.EDITOR . 428

MERGE.STYLES .. 428

MESSAGE 428

MOVE 429

MOVEAVG .. 430

. 430

NAMES 431

NEW 432

NEW.WINDOW 434

NEXT . 434

NOTE . 434 OBJECT.PROPERTIES 435

OBJECT.PROTECTION .. 436

. 436

ON.DOUBLECLICK . 438 ON.ENTRY .438

.. 439

ON.RECALC . 442

ON.SHEET . 443

.. 443

ON.WINDOW . 444

OPEN . 445

OPEN.DIALOG .. 448

OPEN.LINKS 449

.. 450

.. 451

OPTIONS.CALCULATION .. 452

OPTIONS.CHART . 453

454

OPTIONS.GENERAL .. 455

. 456

OPTIONS.LISTS.DELETE .. 457

.. 457

OPTIONS.TRANSITION 458

.. 459

OUTLINE .. 460

OVERLAY . 461

PAGE.SETUP .. 461

PARSE . 467

PASTE .. 468

. 468

PASTE.PICTURE . 469

469

PASTE.SPECIAL . 469

PASTE.SPECIAL Syntax 1 470

PASTE.SPECIAL Syntax 2 471

PASTE.SPECIAL Syntax 3 472

PASTE.SPECIAL Syntax 4 473

.. 474 PATTERNS .475

PAUSE . 482

483

.FIELDS .. 485

PIVOT.FIELD .. 486

PIVOT.FIELD.GROUP . 487

PIVOT.FIELD.PROPERTIES . 489

PIVOT.FIELD.UNGROUP . 492

. 493

.PROPERTIES 494

PIVOT.REFRESH 495

.PAGES . 495

PIVOT.TABLE.WIZARD 496

PLACEMENT . 498

POKE . 498

PRECISION .. 499

PREFERRED . 500

.. 500

PRINT .. 500

PRINTER.SETUP 503

PRINT.PREVIEW 503

PROMOTE 503

PROTECT.DOCUMENT .. 504

PTTESTM . 505

PTTESTV .. 506

PUSHBUTTON.PROPERTIES . 507

.. 507

QUERY.REFRESH . 508

QUIT .. 509

RANDOM .. 509 RANKPERC 511

REFTEXT .. 512

REGISTER .. 513

REGRESS 515 RELREF ..517

. 517

.BREAK . 518

RENAME.COMMAND 518

RENAME.OBJECT . 519

.. 519

REPORT.DEFINE 520

REPORT.DELETE .. 520

.. 521

REPORT.PRINT 522

REQUEST 522

.. 523

RESET.TOOLBAR .. 524

RESTART . 524

RESULT . 525

RESUME 526

RETURN . 526

ROUTE.DOCUMENT .. 527

527

ROW.HEIGHT 529

RUN . 530

SAMPLE . 531

SAVE . 532

.. 532

535

SAVE.DIALOG .. 536

SAVE.TOOLBAR . 537

SAVE.WORKBOOK . 537

SAVE.WORKSPACE 538

SCALE .. 538 SCALE Syntax 1 538

SCALE Syntax 2 539

SCALE Syntax 3 540

SCALE Syntax 4 541 SCALE Syntax 5 541

. 542

SCENARIO.CELLS 543

SCENARIO.DELETE .. 544

544

.. 545

SCENARIO.MERGE . 546

.. 546

546

SCENARIO.SUMMARY 547

SCROLLBAR.PROPERTIES .. 547

SELECT .. 548

SELECT Syntax 1 . 548

SELECT Syntax 2 . 550

SELECT Syntax 3 . 551

. 553

SELECT.CHART .. 554

.. 554

SELECTION .. 555

.. 556

557

. 557

SELECT.SPECIAL . 557

.. 559

.. 560

.. 561

SERIES .. 561

562

SERIES.ORDER .. 562

SERIES.X 562

SERIES.Y . 563

SET.CONTROL.VALUE .. 563

SET.CRITERIA . 564

SET.DATABASE .. 564 SET.DIALOG.DEFAULT .564

SET.DIALOG.FOCUS 565

SET.EXTRACT 565

565

. 566

.BREAK 567

SET.PREFERRED .. 568

.. 568

SET.PRINT.TITLES . 569

SET.UPDATE.STATUS 570

SET.VALUE 571

SHORT.MENUS 572

572

.. 572

SHOW.CLIPBOARD 574

SHOW.DETAIL . 574

SHOW.DIALOG 575

575

SHOW.LEVELS . 575

SHOW.TOOLBAR .. 576

SIZE .. 578

.. 578

.. 579

SLIDE.DEFAULTS 579

579

. 580

580

SLIDE.PASTE . 581

583

. 583

. 584

SOLVER.CHANGE 586

SOLVER.DELETE .. 586

SOLVER.FINISH . 586 ..587

. 589

. 589

SOLVER.OPTIONS .. 590

SOLVER.RESET .. 591

.. 591

SOLVER.SOLVE .. 592

SORT . 593

595

. 596

SPELLING 597

SPELLING.CHECK 598

SPLIT 598

.. 598

SQL.CLOSE .. 600

SQL.ERROR . 600

.QUERY 602

.SCHEMA .. 603

.. 605

SQL.RETRIEVE 607

. 609

611

STANDARD.WIDTH .. 611

STEP .. 611

STYLE .. 612

.. 612

SUBTOTAL.CREATE .. 613

SUBTOTAL.REMOVE 614

. 615

TABLE .. 615 TAB.ORDER . 616

TERMINATE . 616

.. 617

TEXTREF .. 617 .COLUMNS ..618

TRACER.CLEAR .. 620

TRACER.DISPLAY 620

TRACER.ERROR . 620

TRACER.NAVIGATE .. 621

TTESTM . 622

UNDO 622

UNGROUP .. 622

UNHIDE . 623

, .. 623

UNREGISTER . 623

625

625

.ADDIN .. 626

VIEW.3D .. 626

VIEW.DEFINE 627

VIEW.DELETE .. 628

.. 628

.. 629

VLINE 630

VOLATILE 630

VPAGE . 631

VSCROLL . 631

WAIT . 632

WHILE . 633

WINDOW.MAXIMIZE .. 633

WINDOW.MINIMIZE 634

634

WINDOW.RESTORE . 635

WINDOWS . 636

637

WINDOW.TITLE . 638

WORKBOOK.ACTIVATE .. 639

639 .640

WORKBOOK.DELETE .. 640

.. 641

WORKBOOK.INSERT .. 641

642

643

643

. 644

WORKBOOK.OPTIONS . 644

. 644

WORKBOOK.PROTECT . 645

WORKBOOK.SCROLL . 645

WORKBOOK.SELECT .. 645

.SPLIT . 646

WORKBOOK.UNHIDE . 646

WORKGROUP 647

WORKSPACE .. 647

ZOOM .. 649

ZTESTM . 649

More resources 651

About . 653

Thanks .. 653

INTRODUCTION

Before Visual Basic for Applications, there were Excel macros, or XLM.  

VBA was introduced in Excel version 5.0 so these older XLM macros are also known as Excel 4 Macros.

To use an Excel 4.0 macro does not require any programming.  You use them like a function e.g.

(64,A1). This gives you the ColorIndex of the background of cell A1.

However you can’t just stick them into your worksheet.  If you combine them with defined names they can be very useful and can do things that would normally require a VBA solution.

The definitions for the macro functions in this book are taken from the official Microsoft Excel 4.0 Macros help file.  

When I was looking for a reference for these macros I could not easily find one as the old help files are no longer supported in Windows 10.

So I thought I’d put this book together and make it available to anyone that wants it.

Excel 4.0 macros are still working in Excel up to version 2016.  That is no guarantee that they will continue to be supported.

             

A1.R1C1

Displays row and column headings and cell references in either the R1C1 or A1 reference style. A1 is the Microsoft Excel default reference style.

Syntax

A1.R1C1(logical)

Logical    is a logical value specifying which reference style to use. If logical is TRUE, all worksheets and macro sheets use A1 references; if FALSE, all worksheets and macro sheets use R1C1 references.

Example

The following macro formula displays an alert box asking you to select either A1 or R1C1 reference style. This is useful in an Auto_Open macro if several persons who prefer different reference styles must maintain the same workbook.

A1.R1C1(ALERT("Click OK for A1 style; Cancel for R1C1", 1))

ABSREF

Returns the absolute reference of the cells that are offset from a reference by a specified amount. You should generally use OFFSET instead of ABSREF. This function is provided for users who prefer to supply an absolute reference in text form.

Syntax

ABSREF(ref_text, reference)

Ref_text    specifies a position relative to reference. Think of ref_text as "directions" from one range of cells to another. 

•   Ref_text must be an R1C1-style relative reference in the form of text, such as "R[1]C[1]".

•   Ref_text is considered relative to the cell in the upper-left corner of reference. 

Reference    is a cell or range of cells specifying a starting point that ref_text uses to locate another range of cells. Reference can be an external reference.

Remarks 

•   If you use ABSREF in a function or operation, you will usually get the values contained in the reference instead of the reference itself because the reference is automatically converted to the contents of the reference.

•   If you use ABSREF in a function that requires a reference argument, then Microsoft Excel does not convert the reference to a value.

•   If you want to work with the actual reference, use the REFTEXT function to convert the active-cell reference to text, which you can then store or manipulate (or convert back to a reference with TEXTREF). See the third example following. 

Examples

ABSREF("R[-2]C[-2]", C3) equals $A$1

ABSREF(RELREF(A1, C3), D4) equals $B$2

REFTEXT(ABSREF("R[-2]C[-2]:R[2]C[2]", C3:G7), TRUE) is equivalent to

REFTEXT(ABSREF("R[-2]C[-2]:R[2]C[2]", C3), TRUE), which equals "$A$1:$E$5"

In Microsoft Excel for Windows ABSREF("R[-2]C[-2]", []Sheet1!C3) equals []Sheet1!$A$1.

In Microsoft Excel for the Macintosh ABSREF("R[-2]C[-2]", [FINANCE]Sheet1!C3) equals [FINANCE]Sheet1!$A$1

Related Function

RELREF   Returns a relative reference

ACTIVATE

Switches to a window if more than one window is open, or a pane of a window if the window is split and its panes are not frozen. Switching to a pane is useful with functions such as VSCROLL, HSCROLL, and GOTO, which operate only on the active pane.

Syntax

ACTIVATE(window_text, pane_num)

ACTIVATE?(window_text, pane_num)

Window_text    is text specifying the name of a window to switch to: for example, "Book1" or "Book1:2". 

•   If a workbook is displayed in more than one window and window_text does not specify which window to switch to, the first window containing that workbook is switched to.

•   If window_text is omitted, the active window is not changed. 

Pane_num    is a number from 1 to 4 specifying which pane to switch to. If pane_num is omitted and the window has more than one pane, the active pane is not changed.

Pane_num

 

Activates

1          Upper-left pane of the active sheet. If the window is not split, this is the only pane. If the window is split only horizontally, this is the upper pane. If the window is split only vertically, this is the left pane.

2          Upper-right pane of the active sheet. If the window is split only vertically, this is the right pane. If the window is split only horizontally, an error occurs.

3          Lower-left pane of the active sheet. If the window is split only horizontally, this is the lower pane. If the window is split only vertically, an error occurs.

4          Lower-right pane of the active sheet. If the window is split into only two panes either vertically or horizontally, an error occurs.

Related Functions

   Switches to the next window, or switches to the next sheet in a workbook

   Switches to the previous window, or switches to the previous sheet in a workbook

DOCUMENTS   Returns the names of the specified open workbooks

FREEZE.PANES   Freezes the panes of a window so that they do not scroll

ON.WINDOW   Runs a macro when you switch to a window

SPLIT   Splits a window

WINDOWS   Returns the names of all open windows

WORKBOOK.SELECT   Select a sheet in a workbook

,

Switches to the next or previous window, respectively, or switches to the next or previous sheet in a workbook.

Syntax

(workbook_text)

(workbook_text)

Workbook_text    is the name of the workbook for which you want to activate a window. 

•   If workbook_text is specified, and are equivalent to pressing CTRL+PAGE DOWN and CTRL+PAGE UP (in Microsoft Excel for Windows) or COMMAND+PAGE DOWN and COMMAND+PAGE UP (in

Microsoft Excel for the Macintosh). These functions switch to the next and previous sheets, respectively.

•   If workbook_text is omitted, these functions are equivalent to pressing

CTRL+TAB or CTRL+SHIFT+TAB (in Microsoft Excel for Windows) or COMMAND+M or COMMAND+SHIFT+M (in Microsoft Excel for the Macintosh). These functions switch to the next and previous windows, respectively. 

Related Functions

ACTIVATE   Switches to a window

ON.WINDOW   Runs a macro when you switch to a window

   Switches to the next sheet in a workbook

   Switches to the previous sheet in a workbook

WORKBOOK.SELECT   Select a sheet in a workbook

Returns the reference of the active cell in the selection as an external reference.

Syntax

( )

Remarks 

•    If an object is selected, returns the #N/A error value.

•    If a chart sheet is active, returns a zero value.

•    If you use in a function or operation, you will usually get the value contained in the active cell instead of its reference, because the reference is automatically converted to the contents of the reference. See the third example following.

•    If you use in a function that requires a reference argument, then Microsoft Excel does not convert the reference to a value.

•    If you want to work with the actual reference, use the REFTEXT XLM function to convert the active-cell reference to text, which you can then store or manipulate (or convert back to a reference with TEXTREF). See the second example following.

Tip   Use the following macro formula to verify that the current selection is a cell or range of cells:

=ISREF(( ))

Examples

The following macro formula assigns the name Sales to the active cell:

("Sales", ())

In this example, note that "Sales" refers to a cell on the active worksheet, but the name itself exists only in the macro sheet's list of names. In other words, the preceding formula does not define a name on the worksheet or in the workbook's global list of names.

The following macro formula puts the reference of the active cell into the cell named Temp:

FORMULA("="&REFTEXT(()), Temp)

The following macro formula checks the contents of the active cell. If the cell contains only the letter "c" or "s", the macro branches to an area named FinishRefresh:

IF(OR(()="c", ()="s"), GOTO(FinishRefresh))

In Microsoft Excel for Windows, if the sheet in the active window is named SALES and A1 is the active cell, then:

() equals SALES!$A$1

In Microsoft Excel for the Macintosh, if the sheet in the active window is named SALES 1 and A1 is the active cell, then:

() equals 'SALES 1'!$A$1

Related Function

SELECT   Selects a cell, worksheet object, or chart item

Equivalent to formatting individual characters in a cell.

Syntax

(font, font_style, size, strikethrough, superscript, subscript, outline, shadow, underline, color, normal, background, start_char, char_count)

The arguments for this function are the same as those for FONT.PROPERTIES.

Related Function

FONT.PROPERTIES   Applies a font and other attributes to the selection

ADD.ARROW

Equivalent to clicking the Arrow button on the Drawing toolbar. Adds an arrow to the active chart. If a chart is not the active window, displays an error value.

Syntax

ADD.ARROW( )

Remarks

After you create an arrow with ADD.ARROW, the arrow remains selected, so you can use the arrow form of the PATTERNS function to format the arrow and the and functions to change the position and size of the arrow.

Related Functions

CREATE.OBJECT   Creates an object

DELETE.ARROW   Deletes the selected arrow

   Moves the selected object

   Changes the size of the selected object

PATTERNS   Changes the appearance of the selected object

Creates a new menu bar and returns the bar ID number. Use the bar ID number to identify the menu in functions that display and add menus and commands to the menu bar. You can also use to restore a built-in menu bar with its original menus and commands.

Syntax

(bar_num)

Bar_num    is the number of a built-in menu bar that you want to restore. Use

(bar_num) to restore an unaltered version of a built-in menu bar after you have made changes to the menu bar's menus and commands. See ADD.COMMAND for a list of ID numbers for built-in menu bars.

Important   Restoring a built-in menu bar will remove menus and commands added by other macros. Use ADD.COMMAND and to restore individual commands and menus.

Remarks 

•    just creates a new menu bar; it does not display it. Use to display a menu bar. The argument to the function should be the number returned by or a reference to the cell containing .

•    You can define up to 15 custom menu bars at one time. If you carry out an function when more than 15 custom menu bars are already defined, Microsoft Excel returns the #VALUE! error value.

Example

The following formula creates a new menu bar and returns a bar ID number:

()

Related Functions

ADD.COMMAND   Adds a command to a menu

   Adds a menu to a menu bar

   Deletes a menu bar

   Displays a menu bar

ADD.CHART.AUTOFORMAT

Adds the format of the currently active chart in the current window to the list of custom formats in the Custom Types tab in the Chart Type dialog box.

Syntax

ADD.CHART.AUTOFORMAT(name_text, desc_text)

Name_text    is the name you want to appear in the list of custom formats.

Desc_text    is the description you want to appear when the custom format is selected.

Related Function

DELETE.CHART.AUTOFORMAT   Deletes a custom template

ADD.COMMAND

Adds a command to a menu. ADD.COMMAND returns the position number on the menu of the added command. Use ADD.COMMAND to add one or more custom menu commands to a menu on a built-in or custom menu bar. You can also use ADD.COMMAND to restore a deleted builtin command to its original menu.

Syntax

ADD.COMMAND(bar_num, menu, command_ref, position1, position2)

Bar_num    is the number corresponding to a menu bar or a type of shortcut menu to which you want to add a command. 

•   Bar_num can be the ID number of a built-in or custom menu bar. The ID number of a custom menu bar is the number returned by the function.

•   Bar_num can also refer to a type of shortcut menu; use menu to identify the specific shortcut menu. 

The ID numbers of the built-in menu bars and the types of shortcut menus are listed in the following tables. Short menus are abbreviated versions of the normal Microsoft Excel menus. To turn on short menus, use the SHORT.MENUS function.

Bar_num

 

Built-in menu bar

1           Worksheet and macro sheet (Microsoft Excel 4.0 or later)

2           Chart (Microsoft Excel 4.0 or later)

3           Null (the menu displayed when no workbooks are open)

4           Info

5           Worksheet and macro sheet (short menus, Microsoft Excel 3.0 and earlier)

6           Chart (short menus, Microsoft Excel 3.0 and earlier)

7           Cell, toolbar, and workbook (shortcut menus)

8           Object (shortcut menus)

9           Chart (Microsoft Excel 4.0 or later shortcut menus)

10        Worksheet and macro sheet

11        Chart

12        Visual Basic

Menu    is the menu to which you want the new command added. 

•   Menu can be either the name of a menu as text or the number of a menu.

•   If bar_num is 1 through 6, menus are numbered starting with 1 from the left of the menu bar.

•   If bar_num is 7, 8, or 9, menu refers to a built-in shortcut menu. The combination of bar_num and menu determines which shortcut menu to modify, as shown in the following table. 

Bar_num          Menu        Shortcut menu

7                      1              Toolbars

7                      2              Toolbar buttons

7                      3              Workbook paging icons in Microsoft Excel 4.0

7                      4              Cells (worksheet)

7                      5              Column selections

7                      6               Row selections

7                      7              Workbook tabs

7                      8              Cells (macro sheet)

7                      9              Workbook title bar

7                      10             Desktop (Microsoft Excel for Windows only)

7                      11             Module

7                      12             Watch pane

7                      13             Immediate pane

7         14 Debug code pane

8         1    Drawn or imported objects on worksheets, dialog sheets, and

charts

8                      2              Buttons on sheets

8                      3              Text boxes

8         4    Dialog sheet

9         1    Chart series

9                      2               Chart and axis titles

9                      3               Chart plot area and walls

9                      4              Entire chart

9                      5              Chart axes

9                      6               Chart gridlines

9                      7              Chart floor and arrows

9                      8              Chart legend

Note   Any commands that you add to the toolbar buttons, watch pane, immediate pane or debug code pane shortcut menus will be dimmed.

Command_ref    is an array or a reference to an area on the macro sheet that describes the new command or commands. 

•   Command_ref must be at least two columns wide. The first column specifies command names; the second specifies macro names. Optional columns can be specified for shortcut keys (in Microsoft Excel for the Macintosh), status bar messages, and custom Help topics, in that order.

•   Command_ref is similar to menu_ref in . For more information about command_ref, see the description of menu_ref in .

•   Command_ref can be the name, as text, of a previously deleted built-in command that you want to restore. You can also use the value returned by the DELETE.COMMAND formula that deleted the command. 

Position1    specifies the placement of the new command. 

•   Use a hyphen (-) to represent a line separating commands on a menu. If you want to place a command before the second separator on a menu, use two hyphens (--), three hyphens for the third separator, and so on.

•   Position1 can be a number indicating the position of the command on the menu. Commands are numbered from the top of the menu starting with 1.

•   Position1 can be the name of an existing command, as text, above which you want to add the new command.

•   If position1 is omitted, the command is added to the bottom of the menu.

•   For the toolbar shortcut menu (bar_num 7, menu 1) and the shortcut menu for workbook paging icons in Microsoft Excel version 4.0 (bar_num 7, menu 3), you cannot add commands to the middle of the toolbar name list or the middle of the workbook contents list. 

Position2    specifies the placement of the new command on a submenu. 

•   Position2 can be a number indicating the position of the command on the submenu. Commands are numbered from the top of the menu starting with 1.

•   Position2 can be the name of an existing command, as text, above which you want to add the new command.

•   If position2 is omitted, the command is added to the main menu, not the submenu.

•   To add a command to the bottom of a submenu, use 0 for position2.

Tip   In general, use menu and command names rather than numbers for arguments. The numbers assigned to menus and commands change as you add and delete menus and commands. Using names ensures that your menu and command macro functions always refer to the correct items.

Example

The following macro formula adds the command described in cells G16:J16 to the bottom of the worksheet cells shortcut menu:

ADD.COMMAND(7, 4, G16:J16)

Related Functions

   Adds a menu bar

   Adds a menu to a menu bar

   Adds one or more buttons to a toolbar

ADD.TOOLBAR   Creates a toolbar with the specified tools

DELETE.COMMAND   Deletes a command from a menu

ENABLE.COMMAND   Enables or disables a menu or custom command

GET.TOOLBAR   Retrieves information about a toolbar

RENAME.COMMAND   Changes the name of a command or menu

ADDIN.MANAGER

Equivalent to clicking the Add-Ins command on the Tools menu. Adds or removes an installed add-in from the working set. The add-in file must already be installed.

Syntax

ADDIN.MANAGER(operation_num, addinname_text, copy_logical)

ADDIN.MANAGER?(operation_num, addinname_text, copy_logical)

Operation_num    determines the operation that the add-in manager will perform.

Operation_num

 

Operation

1              Adds an add-in to the working set, using the descriptive name in the

Add-Ins dialog box.

2              Removes an add-in from the working set, using the descriptive name

in the Add-Ins dialog box.

3              Adds a new add-in to the list of add-ins that Microsoft Excel knows about. Equivalent to clicking on the Browse button in the Add-Ins dialog box and clicking a file.

Addinname_text    specifies the name of the add-in. If operation_num is 1 or 2, use the descriptive name of the add-in, such as "SOLVER". If operation_num is 3, this contains the filename of the add-in.

Copy_logical    specifies whether the add-in should be copied to the library directory. This argument is only used if operation_num is 3. If omitted, and the file is on removable media, the user will be asked if they want to copy it to removable media.

Adds an item in a list box or drop-down control on a worksheet or dialog sheet control.

Syntax

(text, index_num)

Text    specifies the text of the item to be added. Instead of text, an empty string may be inserted.

Index_num    is the list index to be used for the new item. Blank entries are created from the end of the current list to the new item index. If index_num is omitted the new item is appended to the list.

Remarks

If the list box or drop-down box was already filled using the LISTBOX.PROPERTIES function, then adding an item with causes the fillrange contents to be discarded in favor of the new list.

Related Functions

   Removes an item in a list box or drop-down box

   Selects an item in a list box or in a group box

Adds a menu to a menu bar. Use to add a custom menu to a built-in or custom menu bar. You can also use to restore built-in menus you have deleted with

. returns the position number in the menu bar of the new menu.

Syntax

(bar_num, menu_ref, position1, position2)

Bar_num    is the menu bar to which you want a menu added. Bar_num can be the ID number of a built-in or custom menu bar. See ADD.COMMAND for a list of ID numbers for built-in menu bars.

Menu_ref    is an array or a reference to an area on the macro sheet that describes the new menu or the name of a deleted built-in menu you want to restore. 

•   Menu_ref must be made up of at least two rows and two columns of cells. The upper-left cell of menu_ref specifies the menu title, which is displayed in the menu bar. In the following example, the range A3:E10 is a valid menu_ref. 

The rest of the first column indicates the names of the commands. The corresponding rows in the second column give the names of the macros that run when the commands are chosen.

•   You can also specify status-bar text and Help topics in the fourth and fifth columns of menu_ref. In Microsoft Excel for the Macintosh, you can specify shortcut keys in the third column of menu_ref. 

Position1    specifies the placement of the new menu. Position can be the name of a menu, as text, or the number of a menu. Menus are numbered from left to right starting with 1. Menus are added to the left of the position specified. 

•   Use a hyphen (-) to represent a line separating commands on a menu. If you want to place a command before the second separator on a menu, use two hyphens (--), three hyphens for the third separator, and so on.

•   If position1 is omitted, the menu is added to the end of the menu bar.

•   If there is already a menu at position1, that menu is shifted to the right and the new menu is added in its place.

•   If you are using to restore a deleted built-in menu, you can use the position argument to put it back in its original place on the menu bar. For example, to restore the Data menu on the worksheet and macro sheet menu bar, use position 7. If position1 is omitted, the menu is added to the right of the last menu restored. 

Position2    specifies the placement of a submenu. 

•   Use a hyphen (-) to represent a line separating commands on a menu. If you want to place a command before the second separator on a menu, use two hyphens (--), three hyphens for the third separator, and so on.

•   Position2 can be a number indicating the position of the submenu on the menu. Commands are numbered from the top of the menu starting with 1 and include separators.

•   Position2 can also be the name, as text, of an existing command above which you want to add the new command.

•   If position2 is omitted, the command is added to the main menu, not the submenu. 

Example

The following macro formula adds a new menu to the end of the worksheet menu bar, where A10:B15 is the menu_ref describing the menu:

(1, A10:B15)

Related Functions

   Adds a menu bar

ADD.COMMAND   Adds a command to a menu

   Deletes a menu

ENABLE.COMMAND   Enables or disables a menu or custom command

ADD.OVERLAY

Equivalent to clicking the Add Overlay command on the Chart menu in Microsoft Excel version 4.0. Adds an overlay to a 2-D chart. If the active chart already has an overlay, ADD.OVERLAY takes no action and returns TRUE. In Microsoft Excel version 5.0 or later, ADD.OVERLAY works with charts that have only one chart type.

Syntax

ADD.OVERLAY( )

Related Functions

ADD.ARROW   Adds an arrow to a chart

LEGEND   Adds a legend to a chart

Adds one or more buttons to a toolbar.

Syntax

(bar_id, position, tool_ref)

Bar_id    is either a number specifying one of the built-in toolbars or the name of a custom toolbar.

Bar_id

 

Built-in toolbar

1       Standard

2       Formatting

3       Query and Pivot

4       Chart

5       Drawing

6       TipWizard

7       Forms

8       Stop Recording

9       Visual Basic

10       Auditing

11       WorkGroup

12       Microsoft

13       Full Screen

Position    specifies the position of the button within the toolbar. Position starts with 1 at the left side (if horizontal) or at the top (if vertical).

Tool_ref    is either a number specifying a built-in button or a reference to an area on the macro sheet that defines a custom button or set of buttons (or an array containing this information).

For customized buttons, the following example shows the components of a button reference area on a macro sheet and defines custom tools. The range A1:I5 is a valid tool_ref. Row 1 refers to a built-in tool. Row 2 defines a gap. For this illustration, values are displayed instead of formulas so that text can wrap in cells.

•   Tool_id is a number associated with the tool. A zero specifies a gap on the toolbar. To specify a custom button, use a name, or a number between 201 and 231.

•   Macro is the name of, or a quoted R1C1-style reference to, the macro you want to run when the button is clicked.

•   Down is a logical value specifying the default image of the tool. If down is TRUE, the button appears depressed into the screen; if FALSE or omitted, it appears normal (up).

•   Enabled is a logical value specifying whether the button can be used. If enabled is TRUE, the button is enabled; if FALSE, it is disabled.

•   Face specifies a face associated with the tool. Face must be a reference to a picture-type object, for example "Picture 1". If face is omitted, Microsoft Excel uses the default face for the tool.

•   Status_text is the text, if any, that you want displayed in the status bar when the button is selected.

•   Balloon_text is the balloon help text, if any, associated with the tool.

Balloon_text is available only in Microsoft Excel for the Macintosh using system software version 7.0 or later.

•   Help_topics is a reference to a topic in a Help file, in the form

"filename!topic_number". Help_topics must be text. If help_topics is omitted, HELP displays the Contents topic for Microsoft Excel Help.

•   Tip_text is the text, if any, that you want displayed as a ToolTip when the mouse pointer moves over a tool button. 

To indicate that a particular component of tool_ref is not used, clear the contents of the corresponding cell.

Remarks 

•   If you do not want to reserve a section of your macro sheet to define the buttons, you can use an array as the tool_ref argument as shown in the following syntax: 

(bar_id, position, {tool_id1, macro1, down1, enabled1, face1, status_text1, balloon_text1, help_topics1;tool_id2, macro2, down2, enabled2, face2, status_text2, balloon_text2, help_topics2; })

•   Picture objects can be created with the camera button or pasted in from another application. In Microsoft Excel for Windows, the graphic object must be either a Windows bitmap or picture object. In Microsoft Excel for the Macintosh, the object must be a picture object. 

Examples

The following macro formula adds a button to Toolbar5. The cell range B6:I6 contains tool_ref.

("Toolbar5", 6, B6:I6)

The following macro formula adds the New Macro Sheet button to the fifth position on the Standard toolbar:

(1, 5, 6)

Related Functions

ADD.COMMAND   Adds a command to a menu

ADD.TOOLBAR   Creates a toolbar with the specified tools

   Deletes a button from a toolbar

DELETE.TOOLBAR   Deletes custom toolbars

RESET.TOOLBAR   Resets a built-in toolbar to its default initial setting

ADD.TOOLBAR

Creates a new toolbar with the specified buttons.

Syntax

ADD.TOOLBAR(bar_name, tool_ref)

Bar_name    is a text string identifying the toolbar you want to create.

Tool_ref    is either a number specifying a built-in button or a reference to an area on the macro sheet that defines a custom button or set of buttons (or an array containing this information).

For a complete description of tool_ref, see .

Remarks

If you create a toolbar without buttons, use to add them. Use SHOW.TOOLBAR to display the toolbar.

Example

The following macro formula creates Toolbar9 with one button in it. The cell range B7:I7 contains tool_ref.

ADD.TOOLBAR("Toolbar9", B7:I7)

Related Functions

   Adds a button to a toolbar

   Deletes a button from a toolbar

DELETE.TOOLBAR   Deletes custom toolbars

RESET.TOOLBAR   Resets a built-in toolbar to its default initial setting

SHOW.TOOLBAR   Hides or displays a toolbar

ALERT

Displays a dialog box and message and waits for you to click a button. Use ALERT instead of MESSAGE if you want to interrupt the flow of a macro and force the user to make a choice or to notice an important message.

Syntax

ALERT(message_text, type_num, help_ref)

Message_text    is the message displayed in the dialog box.

Type_num    is a number from 1 to 3 specifying which type of dialog box to display. If you omit type_num, it is assumed to be 2. 

•   If type_num is 1, ALERT displays a dialog box containing the OK and Cancel buttons. Click a button to continue or cancel an action. ALERT returns TRUE if you click the OK button and FALSE if you click the Cancel button. See the last example below.

•   If type_num is 2 or 3, ALERT displays a dialog box containing an OK button. Click the button to continue, and ALERT returns TRUE. The only difference between specifying 2 or 3 is that ALERT displays a different icon on the left side of the dialog box as shown in the examples below. So, for example, you could use 2 for notes or to present general information, and 3 for errors or warnings. 

Help_ref    is a reference to a custom online Help topic, in the form "filename! topic_number". 

•   If help_ref is present, a Help button appears in the lower-right corner of the alert message. Clicking the Help button starts Help and displays the specified topic.

•   If help_ref is omitted, no Help button appears.

•   Help_ref must be given in text form. 

Note   In Microsoft Excel for the Macintosh, the ALERT dialog box is not a movable window.

Examples

The following dialog boxes show the results of using ALERT with type_num 1, 2, and 3. The first and fourth examples include a Help button.

In Microsoft Excel for Windows, the following macro formulas display these three dialog boxes.

ALERT("Are you sure you want to delete this item?", 1,

"!101")

ALERT("The number should be between 1 and 100", 2)

ALERT("Your debits and credits are not equal; do not end this transaction.", 3)

In Microsoft Excel for the Macintosh, the following macro formulas display these three dialog boxes.

ALERT("Are you sure you want to delete this item?", 1, "'Custom Help'!101")

ALERT("The number should be between 1 and 100", 2)

ALERT("Your debits and credits are not equal; do not end this transaction.", 3)

A common use of the ALERT function is to give the user a choice of two actions. The following macro formula in an Auto_Open macro asks which reference style to use when the workbook is opened.

A1.R1C1(ALERT("Click OK for A1 style; Cancel for R1C1", 1))

Related Functions

INPUT   Displays a dialog box for user input

MESSAGE   Displays a message in the status bar

ALIGNMENT

Equivalent to clicking the Alignment tab in the Format Cells dialog box, which is displayed when you click the Cells command on the Format menu. Aligns the contents of the selected cells.

Syntax

ALIGNMENT(horiz_align, wrap, vert_align, orientation, add_indent, shrink_to_fit, merge_cells)

ALIGNMENT?(horiz_align, wrap, vert_align, orientation, add_indent, shrink_to_fit, merge_cells)

Horiz_align    is a number from 1 to 7 specifying the type of horizontal alignment, as shown in the following table. If horiz_align is omitted, horizontal alignment does not change.

Horiz_align

 

Horizontal alignment

1           General

2           Left

3           Center

4           Right

5           Fill

6           Justify

7           Center across selection

Wrap    is a logical value corresponding to the Wrap Text check box in the Alignment tab. If wrap is TRUE, Microsoft Excel selects the check box and wraps text in cells; if FALSE, Microsoft Excel clears the check box and does not wrap text. If wrap is omitted, wrapping does not change.

Vert_align    is a number from 1 to 4 specifying the vertical alignment of the text. If vert_align is omitted, vertical alignment does not change.

Vert_align

 

Vertical alignment

1        Top

2        Center

3        Bottom

4        Justify

Orientation    is a number from 0 to 4 specifying the orientation of the text. If orientation is omitted, text orientation does not change.

Orientation

 

Text orientation

0            Horizontal

1            Vertical

2            Upward

3            Downward

4            Automatic (applies to only chart tick labels)

Add_indent     This argument is for only Far East versions of Microsoft Excel.

Shrink_to_fit    is a logical value corresponding to the Shrink To Fit check box in the Alignment tab. 

Merge_cells    is a logical value corresponding to the Merge Cells check box in the Alignment tab. If merge_cells is TRUE, Microsoft Excel selects the check box and merges the selected cells; the merged cell contains the value of the left-most cell that was merged. If FALSE, Microsoft Excel clears the check box and unmerges the selected cells; the left-most cell takes the formula or value of the cell that was unmerged. If merge_cells is omitted, cell mergers do not change.

Related Function

   Formats a worksheet text box or a chart text item

ANOVA1

Performs single-factor analysis of variance, which tests the hypothesis that means from several samples are equal.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

ANOVA1(inprng, outrng, grouped, labels, alpha) ANOVA1?(inprng, outrng, grouped, labels, alpha)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Grouped    is a text character that indicates whether the data in the input range is organized by row or column. 

•   If grouped is "C" or omitted, then the data is organized by column.

•   If grouped is "R", then the data is organized by row.

Labels    is a logical value that describes where the labels are located in the input range, as shown in the following table:

Labels

 

Grouped

 

Labels are in

TRUE                          "C"                First row of the input range.

TRUE                          "R"                First column of the input range.

FALSE or omitted         (ignored)        No labels. All cells in the input range are data.

Alpha    is the significance level at which to evaluate critical values for the F statistic. If omitted, alpha is 0.05.

Related Functions

ANOVA2   Performs two-factor analysis of variance with replication

ANOVA3   Performs two-factor analysis of variance without replication

ANOVA2

Performs two-factor analysis of variance with replication.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

ANOVA2(inprng, outrng, sample_rows, alpha)

ANOVA2?(inprng, outrng, sample_rows, alpha)

Inprng    is the input range. The input range should contain labels in the first row and column.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Sample_rows    is the number of rows in each sample.

Alpha    is the significance level at which to evaluate critical values for the F statistic. If omitted, alpha is 0.05.

Related Functions

ANOVA1   Performs single-factor analysis of variance

ANOVA3   Performs two-factor analysis of variance without replication

ANOVA3

Performs two-factor analysis of variance without replication.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

ANOVA3(inprng, outrng, labels, alpha) ANOVA3?(inprng, outrng, labels, alpha)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Labels    is a logical value. 

•   If labels is TRUE, then the first row and column of the input range contain labels.

•   If labels is FALSE or omitted, all cells in inprng are considered data. Microsoft Excel will then generate the appropriate data labels for the output table. 

Alpha    is the significance level at which to evaluate critical values for the F statistic. If omitted, alpha is 0.05.

Related Functions

ANOVA1   Performs single-factor analysis of variance

ANOVA2   Performs two-factor analysis of variance with replication

APP.ACTIVATE

Switches to an application. Use APP.ACTIVATE to switch to another application that is already running or that you have started by using EXEC.

Syntax

APP.ACTIVATE(title_text, wait_logical)

Important   Microsoft Excel for the Macintosh requires system software version 7.0 or later for this function.

Title_text    is the name of an application as displayed in its title bar. 

•   If title_text is omitted, APP.ACTIVATE switches to Microsoft Excel.

•   If title_text is not a currently running application, APP.ACTIVATE returns the #VALUE! error value and interrupts the macro.

•   Title_text is not necessarily the name of the application file. Use the text that appears in the title bar of the application, which might include the name of the open workbook and path information.

•   In Microsoft Excel for the Macintosh, title_text can also refer to the Process Serial Number (PSN) that is returned by an EXEC function. 

Wait_logical    is a logical value determining when to switch to the application specified by title_text. 

•   If wait_logical is TRUE, Microsoft Excel waits to be switched to before switching to the application specified by title_text.

•   If wait_logical is FALSE or omitted, Microsoft Excel immediately switches to the application specified by title_text. 

Remarks

If you are running an application using Microsoft Excel macros, and you want to switch to a third application without switching to Microsoft Excel first, use FALSE as the wait_logical argument. With FALSE, you can use the application title_text without having to switch to Microsoft Excel first.

Examples

The following macro formula switches to Microsoft Word, which is currently displaying the workbook in full screen mode:

APP.ACTIVATE("MICROSOFT WORD - ")

In Microsoft Excel for the Macintosh, the following macro formula switches to Microsoft Word:

APP.ACTIVATE("MICROSOFT WORD")

Tip   Use an IF statement with APP.ACTIVATE to run an EXEC function if the application you want to switch to is not yet running.

Related Functions

The first five functions following are only for Microsoft Excel for Windows.

APP.MAXIMIZE   Maximizes the Microsoft Excel application window

APP.MINIMIZE   Minimizes the Microsoft Excel application window

   Moves the Microsoft Excel application window

APP.RESTORE   Restores the Microsoft Excel application window

   Changes the size of the Microsoft Excel application window EXEC   Starts another application


APP.ACTIVATE.MICROSOFT

Activates a Microsoft application. If the application is not already activated, this function will load the application into memory.

Syntax

APP.ACTIVATE.MICROSOFT(app_id)

App_id    is the ID number associated with the Microsoft Application.

App_id

 

Application

1        Microsoft Word

2        Microsoft PowerPoint

3        Microsoft Mail

4        Microsoft Access (for Microsoft Windows only)

5        Microsoft Fox Pro

6        Microsoft Project

7        Microsoft Schedule +

Remarks

Returns TRUE if the application is activated successfully. Returns FALSE if the application is not activated successfully.

Related Function

APP.ACTIVATE   Switches to an application.

APPLY.NAMES

Equivalent to clicking the Apply command on the Name submenu on the Insert menu. Replaces definitions with their respective names. If no names are defined in the current selection, APPLY.NAMES returns the #VALUE! error value. Use APPLY.NAMES to replace references and values in formulas with names.

Syntax

APPLY.NAMES(name_array, ignore, use_rowcol, omit_col, omit_row, order_num, append_last)

APPLY.NAMES?(name_array, ignore, use_rowcol, omit_col, omit_row, order_num, append_last)

Name_array    is the name or names to apply as text elements in an array. 

•   To give more than one name as the argument, you must use an array. For example:

•   APPLY.NAMES({"DataRange", "CriteriaRange"})

•   If the names indicated by the argument name_array have already replaced all of the appropriate references or values, the #VALUE! error value is returned. 

The next four arguments correspond to check boxes and options in the Apply Names dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box.

Ignore    corresponds to the Ignore Relative/Absolute check box.

Use_rowcol    corresponds to the Use Row And Column Names check box. If use_rowcol is FALSE, the next three arguments are ignored.

Omit_col    corresponds to the Omit Column Name If Same Column check box.

Omit_row    corresponds to the Omit Row Name If Same Row check box.

Order_num    determines which range name is listed first when a cell reference is replaced by a row-oriented and a column-oriented range name, as shown in the following table.

Order_num

 

Order of range names

1          Row Column

2          Column Row

Append_last    determines whether the names most recently defined are also replaced. 

•   If append_last is TRUE, Microsoft Excel replaces the definitions of the names in name_array and also replaces the definitions of the last names defined.

•   If append_last is FALSE or omitted, Microsoft Excel replaces the definitions of the names in name_array only. 

Related Functions

CREATE.NAMES   Creates names automatically from text labels on a sheet

   Defines a name in the active workbook

LIST.NAMES   Lists names and their associated information

APPLY.STYLE

Equivalent to clicking the Style command on the Format menu, selecting a style, and clicking the OK button. Applies a previously defined style to the current selection.

Syntax

APPLY.STYLE(style_text)

APPLY.STYLE?(style_text)

Style_text    is the name, as text, of a previously defined style. If style_text is not defined, APPLY.STYLE returns the #VALUE! error value and interrupts the macro. If style_text is omitted, the Normal style is applied to the selection.

Related Functions

DEFINE.STYLE   Defines a cell style

DELETE.STYLE   Deletes a cell style

MERGE.STYLES   Imports styles from another workbook into the active workbook

APP.MAXIMIZE

Equivalent to clicking the Maximize command on the Control menu for the application window. Maximizes the Microsoft Excel window.

Syntax

APP.MAXIMIZE( )

Note   This function is only for Microsoft Excel for Windows. You can use this function in macros created with Microsoft Excel for the Macintosh, but it will return the #N/A error value.

Related Functions

APP.ACTIVATE   Switches to an application

APP.MINIMIZE   Minimizes the Microsoft Excel application window

   Moves the Microsoft Excel application window

APP.RESTORE   Restores the Microsoft Excel application window

   Changes the size of the Microsoft Excel application window

FULL.SCREEN   Controls full screen display

APP.MINIMIZE

Equivalent to clicking the Minimize command on the Control menu for the application window. Minimizes the Microsoft Excel window.

Syntax

APP.MINIMIZE( )

Note   This function is only for Microsoft Excel for Windows. You can use this function in macros created with Microsoft Excel for the Macintosh, but it will return the #N/A error value.

Related Functions

APP.ACTIVATE   Switches to an application

APP.MAXIMIZE   Maximizes the Microsoft Excel application window

   Moves the Microsoft Excel application window

APP.RESTORE   Restores the Microsoft Excel application window

   Changes the size of the Microsoft Excel application window

Equivalent to clicking the Move command on the Control menu for the application window. Moves the Microsoft Excel window. In Microsoft Excel for Windows, if the application window is already maximized returns the #VALUE! error value and interrupts the macro.

Syntax

(x_num, y_num)

?(x_num, y_num)

Note   This function is only for Microsoft Excel for Windows. You can use this function in macros created with Microsoft Excel for the Macintosh, but it will return the #N/A error value.

X_num    specifies the horizontal position of the Microsoft Excel window measured in points from the left edge of your screen to the left side of the Microsoft Excel window.

Y_num    specifies the vertical position of the Microsoft Excel window measured in points from the top edge of your screen to the top of the Microsoft Excel window.

Remarks 

•    ?, the dialog-box form of the function, doesn't display a dialog box. Instead, it is equivalent to pressing ALT + SPACEBAR, M or to dragging the title bar with the mouse. With ?, you can move the window with the keyboard or mouse.

•    If you specify x_num and/or y_num in the dialog-box form of the function, the window is moved according to the specified coordinates, and you are left in move mode.

Related Functions

APP.ACTIVATE   Switches to an application

APP.MAXIMIZE   Maximizes the Microsoft Excel application window

APP.MINIMIZE Minimizes the Microsoft Excel application window APP.RESTORE   Restores the Microsoft Excel application window

   Changes the size of the Microsoft Excel application window

APP.RESTORE

Equivalent to clicking the Restore command on the Control menu for the application window. Restores the Microsoft Excel window to its previous size and location.

Syntax

APP.RESTORE( )

Note   This function is only for Microsoft Excel for Windows. You can use this function in macros created with Microsoft Excel for the Macintosh, but it will return the #N/A error value.

Related Functions

APP.ACTIVATE   Switches to an application

APP.MAXIMIZE   Maximizes the Microsoft Excel application window

APP.MINIMIZE   Minimizes the Microsoft Excel application window

   Moves the Microsoft Excel application window

   Changes the size of the Microsoft Excel application window

Equivalent to choosing the Size command from the Control menu for the application window. Changes the size of the Microsoft Excel window.

Syntax

(x_num, y_num)

?(x_num, y_num)

Note   This function is only for Microsoft Excel for Windows. You can use this function in macros created with Microsoft Excel for the Macintosh, but it will return the #N/A error value.

X_num    specifies the width of the Microsoft Excel window in points.

Y_num    specifies the height of the Microsoft Excel window in points.

?, the dialog-box form of the function, doesn't display a dialog box. Instead, it is equivalent to pressing ALT, SPACEBAR, S or to dragging a window border with the mouse. Using ?, you can size the window with the keyboard or mouse. If you specify x_num and/or y_num in the dialog-box form of the function, the window is sized according to the specified coordinates, and you are left in size mode.

Related Functions

APP.ACTIVATE   Switches to an application

APP.MAXIMIZE   Maximizes the Microsoft Excel application window

APP.MINIMIZE   Minimizes the Microsoft Excel application window

   Moves the Microsoft Excel application window

APP.RESTORE   Restores the Microsoft Excel application window

APP.TITLE

Changes the title of the Microsoft Excel application workspace to the title you specify. The title appears at the top of the application window. Use APP.TITLE to control the application title when you're using Microsoft Excel to create a custom application. This function does not apply to Microsoft Excel for the Macintosh.

Syntax

APP.TITLE(text)

Text    is the title you want to assign to the Microsoft Excel application workspace. If text is omitted, it is restored to Microsoft Excel.

Remarks 

•    The custom application title, followed by the individual workbook title, will appear in the application title bar if the workbook is maximized.

•    APP.TITLE does not affect DDE communications. You will still refer to the application as "Excel". 

Related Function

WINDOW.TITLE   Changes the title of the active window

ARGUMENT

Describes the arguments used in a custom function, which is a type of macro, or in a subroutine. A custom function or subroutine must contain one ARGUMENT function for each argument in the macro itself. There are two forms of the ARGUMENT function. In the first form, only name_text is required; in the second form, only reference is required. Use the first form if you want to store the argument as a name. Use the second form if you want to store the argument in a specific cell or cells.

Syntax 1

For name storage

ARGUMENT(name_text, data_type_num)

Syntax 2

For cell storage

ARGUMENT(name_text, data_type_num, reference)

Name_text    is the name of the argument or of the cells containing the argument. Name_text is required if you omit reference.

Data_type_num    is a number that determines what type of values Microsoft Excel accepts for the argument. The following table lists the possible data types.

Data_type_num

 

Type of value


1             Number

2             Text

4                            Logical

8                            Reference

16                          Error

64                          Array

•   Data_type_num can be a sum of the preceding different numbers to allow for more than one possible type of data. For example, if data_type_num is 7, which is the sum of 1, 2, and 4, then the value can be a number, text, or logical value.

•   Data_type_num is an optional argument. If you omit data_type_num, it is assumed to be 7.

•   If the value that is passed to the function macro is not of the type specified by data_type_num, Microsoft Excel first attempts to convert it to the specified type. If the value cannot be converted, the macro returns the #VALUE! error value. 

Reference    is the cell or cells in which you want to store the argument's value. 

•   If you specify reference, the value that is passed to ARGUMENT is entered as a constant in the specified cell, and name_text becomes an optional argument because you can refer to the cell with either reference or name_text.

•   If you omit reference, name_text is defined on the macro sheet and refers to the value that is passed to ARGUMENT. Once name_text is defined, you can use it in formulas. 

Remarks 

•   Custom functions and subroutines can accept from 1 to 29 arguments.

•   If a macro contains an ARGUMENT function and you omit the corresponding argument in the function that starts the macro, the macro uses the #N/A error value as the value of the argument. 

Examples

To create a custom function that calculates profit, use the following functions to specify arguments for cost, sales, and sales volume:

ARGUMENT("UnitsSold", 1) ARGUMENT("UnitCost", 1)

ARGUMENT("UnitPrice", 1)

Related Functions

RESULT   Specifies the data type a custom function returns

VOLATILE   Makes custom functions recalculate automatically

Equivalent to clicking the Arrange command on the Window menu. Rearranges open windows and icons and resizes open windows. Also can be used to synchronize scrolling of windows of the active sheet.

Syntax

(arrange_num, active_doc, sync_horiz, sync_vert)

?(arrange_num, active_doc, sync_horiz, sync_vert)

Arrange_num    is a number from 1 to 7 specifying how to arrange the windows.

Arrange_num

 

Result

1             or omitted    Tiled (also used to arrange icons in Microsoft Excel for Windows)

2             Horizontal

3             Vertical

4             None

5             Horizontally arranges and sizes the windows based on the position of

the active cell.

6             Vertically arranges and sizes the windows based on the position of the

active cell.

7             Arranges windows so that they cascade from the upper left to the bottom right of the application workspace.

If you want to change whether the windows are synchronized for scrolling but not how they are arranged, make sure arrange_num is 4.

Active_doc    is a logical value specifying which windows to arrange. If active_doc is TRUE, Microsoft Excel arranges only windows on the active workbook; if FALSE or omitted, all open windows are arranged.

Sync_horiz    is a logical value corresponding to the Sync Horizontal check box in Microsoft Excel version 4.0. 

•   If sync_horiz is TRUE, Microsoft Excel selects the check box and synchronizes horizontal scrolling.

•   If sync_horiz is FALSE or omitted, Microsoft Excel clears the check box, and windows will not be synchronized when you scroll horizontally.

•   This argument is used only when active_doc is TRUE. 

Sync_vert    is a logical value corresponding to the Sync Vertical check box in Microsoft Excel version 4.0. 

•   If sync_vert is TRUE, Microsoft Excel selects the check box and synchronizes vertical scrolling.

•   If sync_vert is FALSE or omitted, Microsoft Excel clears the check box, and windows will not be synchronized when you scroll vertically.

•   This argument is used only when active_doc is TRUE. 

Note   If arguments are omitted in the dialog box form of this function, the default values are the previous settings, if any; otherwise the default values are as described above.

Remarks 

•   After arranging windows, the top or leftmost window is active.

•   In Microsoft Excel for Windows, if all windows are minimized, ignores its arguments, if any, and arranges the corresponding icons horizontally along the bottom of the workspace. 

Tip   You can use synchronized horizontal or vertical scrolling when you need to scroll while viewing macro formulas in one window and corresponding macro values in another window of the same macro sheet.

Related Function

ACTIVATE   Switches to a window

.OBJECT

Assigns a macro to the currently select object.

Syntax

.OBJECT(macro_ref)

.OBJECT?(macro_ref)

Macro_ref    is the name of, or a reference to, the macro you want to run when the object is clicked. If macro_ref is omitted, Microsoft Excel no longer runs the previously specified macro (.OBJECT is turned off).

Remarks 

•    If an object is not selected, .OBJECT returns the #VALUE! error value and interrupts the macro.

•    To change the macro assigned to an object, select the object and use

.OBJECT again, using the reference to the new macro as macro_ref. The previous macro is replaced with the new macro. 

Related Functions

CREATE.OBJECT   Creates an object

RUN   Runs a macro

Assigns a macro to be run when a button is clicked with the mouse.

Syntax

(bar_id, position, macro_ref)

Bar_id    specifies the number or name of a toolbar to which you want to assign a macro. For more information about bar_id, see .

Position    specifies the position of the button within the toolbar. Position starts with 1 at the left side (if horizontal) or at the top (if vertical).

Macro_ref    is the name of, or a reference to, the macro you want to run when the button is clicked. If macro_ref is omitted, Microsoft Excel no longer runs the previously specified macro. After canceling the macro, if the button is a built-in button, Microsoft Excel performs the normal default action when the button is clicked. If the button is a custom button, Microsoft Excel displays the Assign Macro dialog box when the button is clicked.

Related Functions

   Adds one or more buttons to a toolbar

   Returns information about a button or buttons on a toolbar

Attaches text to certain parts of the selected chart. Use to attach text as a title or as a label for an axis or data point.

Syntax

(attach_to_num, series_num, point_num)

?(attach_to_num, series_num, point_num)

Attach_to_num    specifies which item on a chart to attach text to. Attach_to_num is different for 2-D and 3-D charts. Attach_to_num values for 2-D charts are shown in the following table.

Attach_to_num

 

Attaches text to

1            Chart title

2            Value (y) axis

3            Category (x) axis

4            Series and data point

5            Secondary value (y) axis

6            Secondary category (x) axis

Attach_to_num values for 3-D charts are shown in the following table.

Attach_to_num

 

Attaches text to

1            Chart title

2            Value (z) axis

3            Series (y) axis

4            Category (x) axis

5            Series and data point

Series_num    specifies the series number if attach_to_num specifies a series or data point. If attach_to_num specifies a series or data point and series_num is omitted, the macro is interrupted.

Point_num    specifies the number of the data point, but only if you specify a series number. Point_num is required if series_num is specified, unless the chart is an area chart.

Remarks

When you record adding an axis title or a chart title, Microsoft Excel records both an

function to attach the text and a FONT.PROPERTIES function to make the text bold.

Example

The following macro functions attach the text "Quarterly Sales" to the x (category) axis of the selected chart:

(3)

FORMULA("Quarterly Sales")

Related Functions

DATA.LABEL   Assigns text labels to point on a chart

FORMULA   Enters values into a cell or range or onto a chart

ATTACH.TOOLBARS

Displays the Attach Toolbars dialog box, which you use to attach or associate toolbars with documents. The Attach Toolbars dialog box is available when you click the Customize command (View menu, Toolbars submenu), click the Toolbars tab, and then click the Attach button.

Syntax

ATTACH.TOOLBARS?( )

AUTO.OUTLINE

Equivalent to clicking the Auto Outline command on the Group And Outline submenu of the Data menu. Creates an outline within the selection. If a single cell is selected, creates an outline for the entire sheet.

Syntax

AUTO.OUTLINE( )

Related Functions

CLEAR.OUTLINE   Removes outlining from the current sheet

OUTLINE   Creates an outline and defines settings for automatically creating outlines

AXES

Controls whether the axes on a chart are visible. There are two syntax forms of this function. Syntax 1 is for 2-D charts; syntax 2 is for 3-D charts.

Syntax 1

For 2-D charts

AXES(x_primary, y_primary, x_secondary, y_secondary)

AXES?(x_primary, y_primary, x_secondary, y_secondary)

Syntax 2

For 3-D charts

AXES(x_primary, y_primary, z_primary)

AXES?(x_primary, y_primary, z_primary)

Arguments are logical values corresponding to the check boxes in the Axes dialog box. 

•   If an argument is TRUE, Microsoft Excel selects the check box and displays the corresponding axis.

•   If an argument is FALSE, Microsoft Excel clears the check box and hides the corresponding axis.

•   If an argument is omitted, the display of that axis is unchanged. 

X_primary    corresponds to the primary category (x) axis.

Y_primary    corresponds to the primary value (y) axis.

Z_primary    corresponds to the value (z) axis on the primary 3-D chart.

X_secondary    corresponds to the secondary category (x) axis on a 2-D chart only.

Y_secondary    corresponds to the secondary value (y) axis on a 2-D chart only.

If a 2-D chart has no secondary axis, only the first two arguments are used.

Related Function

GRIDLINES   Controls whether chart gridlines are visible

BEEP

Sounds a tone. Use BEEP to signal a message, a dialog box, or the end of a macro, or whenever you need to get the user's attention.

Syntax

BEEP(tone_num)

Tone_num    is a number from 1 to 4 specifying the tone to be played. 

•   On most computers, all numbers produce the same sound, the sound that you hear when an error occurs or when you click outside some dialog boxes.

•   If tone_num is omitted, it is assumed to be 1. 

Remarks 

•   With a Macintosh, you can control the volume of the tone by using the Control Panel desk accessory.

•   With Microsoft Windows version 3.0 or later, you can turn off the tone by using the Control Panel. 

Related Functions

ALERT   Displays a dialog box and a message

MESSAGE   Displays a message in the status bar

BORDER

Equivalent to clicking the Border tab in the Format Cells dialog box, which appears when you click the Cells command on the Format menu. Adds a border to the selected cell or range of cells.

Syntax

BORDER(outline, left, right, top, bottom, shade, outline_color, left_color, right_color, top_color, bottom_color)

BORDER?(outline, left, right, top, bottom, shade, outline_color, left_color, right_color, top_color, bottom_color)

Outline, left, right, top, and bottom are numbers from 0 to 7 corresponding to the line styles in the Border dialog box, as shown in the following table.

Argument

 

Line type

0          No border

1          Thin line

2          Medium line

3          Dashed line

4          Dotted line

5          Thick line

6          Double line

7          Hairline

Note   For compatibility with earlier versions of Microsoft Excel, TRUE and FALSE values for the above arguments create a thin border or no border, respectively.

Shade    corresponds to the Shade check box in the Border dialog box of Microsoft Excel version 4.0. This argument is included for compatibility only.

Outline_color, left_color, right_color, top_color, and bottom_color are numbers from 1 to 56 corresponding to the Color box in the Border dialog box. Zero corresponds to automatic color.

BREAK

Interrupts a FOR-NEXT, a -NEXT, or a WHILE-NEXT loop. If BREAK is encountered within a loop, that loop is terminated and the macro proceeds to the statement following the NEXT statement at the end of the current loop.

Syntax

BREAK( )

Example

Use BREAK to test for conditions not anticipated by the FOR or WHILE statement. For example, use the BREAK nested in an IF statement to exit a WHILE-NEXT loop when a certain value is encountered:

=IF(Counter=8, BREAK())

Related Functions

FOR   Starts a FOR-NEXT loop

   Starts a -NEXT loop

NEXT   Ends a FOR-NEXT, -NEXT, or WHILE-NEXT loop

WHILE   Starts a WHILE-NEXT loop

.FRONT

Puts the selected object or objects on top of all other objects. For example, if some worksheet

objects are covering part of an embedded chart, you can select the chart and use .FRONT to display the chart on top of the worksheet objects.

Syntax

.FRONT( )

If the selection is not an object or a group of objects, .FRONT returns the #VALUE!

error value.

Related Function

   Sends selected objects behind other objects

CALCULATE.DOCUMENT

Equivalent to choosing the Calc Sheet button in the Calculation tab on the Options dialog, which appears when you choose the Options command from the Tools menu. Calculates only the active worksheet.

Syntax

CALCULATE.DOCUMENT( )

Remarks

If a chart is active, CALCULATE.DOCUMENT returns the #VALUE! error value.

Related Functions

   Calculates all open workbooks immediately

CALCULATION   Controls calculation settings

Equivalent to clicking the Calculation tab in the Options dialog box and then clicking the Calc Now button. Calculates all sheets in all open workbooks. Use to calculate all open workbooks when calculation is set to manual.

Syntax

( )

Related Functions

CALCULATE.DOCUMENT   Calculates the active sheet only

CALCULATION   Controls calculation settings

CALCULATION

Controls when and how formulas in open workbooks are calculated. This function is included for compatibility with Microsoft Excel version 4.0. For controlling calculation in Microsoft Excel version 5.0 or later, see OPTIONS.CALCULATION.

Syntax

CALCULATION(type_num, iter, max_num, max_change, update, precision, date_1904, calc_save, save_values, alt_exp, alt_form)

CALCULATION?(type_num, iter, max_num, max_change, update, precision, date_1904, calc_save, save_values, alt_exp, alt_form)

Arguments correspond to check boxes and options in the Calculation dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box.

Type_num    is a number from 1 to 3 indicating the type of calculation.

Type_num

 

Type of calculation

1        Automatic

2        Automatic except tables

3        Manual

Iter    corresponds to the Iteration check box. The default is FALSE.

Max_num    is the maximum number of iterations. The default is 100.

Max_change    is the maximum change of each iteration. The default is 0.001.

Update    corresponds to the Update Remote References check box. The default is TRUE.

Precision    corresponds to the Precision As Displayed check box. The default is FALSE.

Date_1904    corresponds to the 1904 Date System check box. The default is FALSE in Microsoft Excel for Windows and TRUE in Microsoft Excel for the Macintosh.

Calc_save    corresponds to the Recalculate Before Save check box. If calc_save is FALSE, the workbook is not recalculated before saving when in manual calculation mode. The default is TRUE.

Save_values    corresponds to the Save External Link Values check box. The default is TRUE.

Alt_exp    corresponds to the Transition Formula Evaluation check box in the Transition tab of the Options dialog box. 

•   If alt_exp is TRUE, Microsoft Excel uses a set of rules compatible with that of Lotus 1-2-3 when calculating formulas. Text is treated as 0; TRUE and FALSE are treated as 1 and 0; and certain characters in database criteria ranges are interpreted the same way Lotus 1-2-3 interprets them.

•   If alt_exp is FALSE or omitted, Microsoft Excel calculates normally. 

Alt_form    corresponds to the Transition Formula Entry check box in the Transition tab of the Options dialog box. 

•   This argument is available only in Microsoft Excel for Windows.

•   If alt_form is TRUE, Microsoft Excel accepts formulas entered in Lotus 1-2-3 style.

•   If alt_form is FALSE or omitted, Microsoft Excel only accepts formulas entered in Microsoft Excel style. 

Note   Microsoft Excel for Windows and Microsoft Excel for the Macintosh use different date systems as their default. Excel for Windows uses the 1900 date system, in which serial numbers correspond to the dates January 1, 1900, through December 31, 9999. Excel for the Macintosh uses the 1904 date system, in which serial numbers correspond to the dates January 1, 1904, through December 31, 9999.

Remarks

Use GET.DOCUMENT to return the current calculation settings for your workbook. For more information, see GET.DOCUMENT.

Related Functions

CALCULATE.DOCUMENT   Calculates the active sheet only

   Calculates all open workbooks immediately

GET.DOCUMENT   Returns information about a workbook

OPTIONS.CALCULATION   Controls calculation

OPTIONS.TRANSITION   Controls transition options

CALLER

Returns information about the cell, range of cells, command on a menu, tool on a toolbar, or object that called the macro that is currently running. Use CALLER in a subroutine or custom function whose behavior depends on the location, size, name, or other attribute of the caller. Syntax

CALLER( )

Remarks 

•    If the custom function is entered in a single cell, CALLER returns the reference of that cell.

•    If the custom function was part of an array formula entered in a range of cells, CALLER returns the reference of the range.

•    If CALLER appears in a macro called by an Auto_Open, Auto_Close, Auto_Activate, or Auto_Deactivate macro, it returns the name of the calling sheet.

•    If CALLER appears in a macro called by a command on a menu, it returns a horizontal array of three elements including the command's position number, the menu number, and the menu bar number.

•    If CALLER appears in a macro called by an assigned-to-object macro, it returns the object identifier.

•    If CALLER appears in a macro called by a tool on a toolbar, it returns a horizontal array containing the position number and the toolbar name.

•    If CALLER appears in a macro called by an ON.DOUBLECLICK or ON.ENTRY function, CALLER returns the name of the chart object identifier or cell reference, if applicable, to which the ON.DOUBLECLICK or ON.ENTRY macro applies.

•    If CALLER appears in a macro that was run manually, or for any reason not described above, it returns the #REF! error value. 

Examples

If the custom function MACROS!VALUEONE is entered in cell B3 on a sheet named SALES, the nested CALLER function returns the following values.

Nested function

 

Returns

COLUMN(CALLER())          2

COLUMNS(CALLER())         1

(1, CALLER()) SALES!$B$3

ROW(CALLER())               3

ROWS(CALLER())              1

If the same custom function was entered into an array in cells B2:C3, the following values would be returned.

 

Nested function

 

Returns

COLUMN(CALLER())       2

COLUMNS(CALLER()) 2

ROW(CALLER())            2

ROWS(CALLER())           2

Related Functions

   Returns the name or position number of menu bars, menus, and commands

   Returns information about the specified cell

Equivalent to pressing ESC in Microsoft Excel for Windows or ESC or COMMAND+PERIOD in Microsoft Excel for the Macintosh to cancel the marquee after you copy or cut a selection.

Syntax

(render_logical)

Render_logical    is a logical value that, if TRUE, places the contents of the Microsoft Excel Clipboard on the Clipboard or, if FALSE or omitted, does not place them on the Clipboard. Render_logical is available only in Microsoft Excel for the Macintosh.

Disables macro interruption, or specifies a macro to run when a macro is interrupted. Use to control what happens when a macro is interrupted.

Syntax

(enable, macro_ref)

Enable    specifies whether the macro can be interrupted by pressing ESC in Microsoft Excel for Windows or ESC or COMMAND+PERIOD in Microsoft Excel for the Macintosh.

If enable is

 

Then

 

FALSE

Pressing ESC or COMMAND+PERIOD does not interrupt a macro

 

 

TRUE and macro_ref is omitted

Pressing ESC or COMMAND+PERIOD interrupts a macro

 

 

TRUE and macro_ref is specified

Macro_ref runs when ESC or COMMAND+PERIOD is pressed

 

           

Macro_ref    is a reference to a macro, as a cell reference or a name, that runs when enable is TRUE and ESC or COMMAND+PERIOD is pressed.

Remarks 

•    affects only the macro that is currently running. Once the macro is stopped by a RETURN or HALT function, ESC or COMMAND+PERIOD is reactivated.

•    When is in effect, users can still cancel a dialog box displayed while the macro is running. 

Examples

The following macro formula prevents the macro from being interrupted by pressing ESC or COMMAND+PERIOD:

(FALSE)

The following macro formula reactivates ESC or COMMAND+PERIOD to cancel macro execution:

(TRUE)

The following line in a macro runs CheckCancel when ESC or COMMAND+PERIOD is pressed:

(TRUE, CheckCancel)

Related Functions

ERROR   Specifies an action to take if an error occurs while a macro is running

   Runs a macro when a specified key is pressed

   Runs a macro at a specified time

CELL.PROTECTION

Equivalent to choosing the Protection tab in the Format Cells dialog box, which appears when you choose the Cells command from the Format menu. Allows you to control cell protection and display.

Arguments are logical values corresponding to check boxes in the Protection tab. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted and the setting has been previously changed from the defaults, the setting is not changed.

Syntax

CELL.PROTECTION(locked, hidden)

CELL.PROTECTION?(locked, hidden)

Locked    corresponds to the Locked check box. The default is TRUE.

Hidden    corresponds to the Hidden check box. The default is FALSE.

Remarks

Options selected in the Protection tab of the Format Cells dialog box or with the

CELL.PROTECTION function are activated only when the Protect Sheet command is chosen from the Protection submenu on the Tools menu or the PROTECT.DOCUMENT function is used to select protection. Related Functions

PROTECT.DOCUMENT   Controls protection for the active sheet

   Saves a workbook and allows you to specify the name, file type, password, backup file, and location of the workbook

Equivalent to clicking the Change Source button in the Links dialog box, which appears when you click the Links command on the Edit menu. Changes a link from one supporting workbook to another.

Syntax

(old_text, new_text, type_of_link)

?(old_text, new_text, type_of_link)

Old_text    is the path of the link from the active dependent workbook you want to change.

New_text    is the path of the link you want to change to.

Type_of_link    is the number 1 or 2 specifying what type of link you want to change.

Type_of_link

 

Link document type

1           or omitted         Microsoft Excel link

2           DDE/OLE link

Remarks

The workbook whose links you want to change must be active when this function is calculated.

Related Functions

   Returns information about a link

LINKS   Returns the name of all linked workbooks

OPEN.LINKS   Opens specified supporting workbooks

SET.UPDATE.STATUS   Controls the update status of a link

   Updates a link to another workbook

Equivalent to dragging data from a worksheet onto a chart. Adds data to an existing chart.

Syntax

(ref, rowcol, titles, categories, replace, series)

Ref    is the cell reference for the data that is being dragged onto the chart

Rowcol    is the number 1 or 2 and specifies whether the values corresponding to a particular data series are in rows or columns. Enter 1 for rows or 2 for columns.

Titles    is a logical value corresponding to the Series Names In First Column check box (or First Row, depending on the value of rowcol) in the Paste Special dialog box. 

•   If titles is TRUE, Microsoft Excel selects the check box and uses the contents of the cell in the first column of each row (or first row of each column) as the name of the data series in that row (or column).

•   If titles is FALSE, Microsoft Excel clears the check box and uses the contents of the cell in the first column of each row (or first row of each column) as the first data point of the data series.

Categories    is a logical value corresponding to the Categories (X Labels) In First Row (or First Column, depending on the value of rowcol) check box in the Paste Special dialog box. 

•   If categories is TRUE, Microsoft Excel selects the check box and uses the contents of the first row (or column) of the selection as the categories for the chart.

•   If categories is FALSE, Microsoft Excel clears the check box and uses the contents of the first row (or column) as the first data series in the chart. 

Replace    is a logical value corresponding to the Replace Existing Categories check box in the Paste Special dialog box. 

•   If replace is TRUE, Microsoft Excel selects the check box and applies categories while replacing existing categories with information from the copied cell range.

•   If replace is FALSE, Microsoft Excel clears the check box and applies new categories without replacing any old ones.

Series    is a number specifying how cells are added to a chart.

Series

 

Added as

1      New series

2      New point(s)

CHART.TREND

A trendline can be added only to these chart types: bar, column, stacked column, scatter, line, and area.

Syntax

CHART.TREND(type, ord_per, forecast, backcast, intercept, equation, r_squared, name) Type    is the type of trend or regression.

Number

 

Type used

1        Linear

2        Logarithmic

3        Polynomial

4        Power

5        Exponential

6        Moving Average

Ord_per    depends on type. If type is 3, then ord_per is the order of the polynomial. If type is 6, ord_per is the number of periods for the moving average. If type is neither 3 nor 6, then ord_per is ignored.

Forecast    is the number of periods or units to extrapolate the trendline in the positive or forward direction. This argument is ignored for moving averages (type 6). The default is zero.

Backcast    is a number specifying the number of periods or units to extrapolate the trendline in the negative or backward direction. This argument is ignored for moving averages (type 6). The default is zero.

Intercept    is a number specifying the value of the y-intercept of the trendline, if it is already known. If FALSE or omitted, Microsoft Excel will calculate the y-intercept . This argument is ignored for moving averages.

Equation    is a logical value specifying whether the trend equation should be displayed on the chart. If TRUE, the equation will be displayed on the chart. If FALSE or omitted, the equation will not be displayed on the chart.

R_squared    is a logical value specifying whether the r-squared equation should be displayed on the chart. If TRUE, the value will be displayed on the chart. If FALSE or omitted, the equation will not be displayed on the chart.

Name    is a text string specifying the custom name of the trendline. Can also be a logical value. If TRUE or omitted, the automatic name will be used instead.

Remarks 

•    A trendline can not be added to a 3-D chart, a stacked chart, or an 100% chart.

•    The linear model calculates the least squares fit for a line represented by the equation y = mx + b, where m is the slope and b is the intercept.

•    The logarithmic model calculates the least squares fit through points using the equation y = c*ln(x) + b, where c and b are constants.

•    The exponential model calculates the least squares fit through points using the following equation: 

where c and b are constants.

•    The polynomial model calculates the least squares fit through points using the following equation: 

where b, c1, c2, c3, etc. are constants.

•    The power model calculates the least squares fit through points using the following equation: 

where b and c are constants.

Related Function

CHART.WIZARD   Equivalent to clicking the ChartWizard button on the Standard toolbar

CHART.WIZARD

Equivalent to clicking the ChartWizard button on the standard or chart toolbar. Creates a chart. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

CHART.WIZARD(long, ref, gallery_num, type_num, plot_by, categories, ser_titles, legend, title, x_title, y_title, z_title, number_cats, number_titles)

CHART.WIZARD?(long, ref, gallery_num, type_num, plot_by, categories, ser_titles, legend, title, x_title, y_title, z_title, number_cats, number_titles)

Long    is a logical value that determines which type of ChartWizard button CHART.WIZARD is equivalent to. 

•   If long is TRUE, CHART.WIZARD is equivalent to using the five-step ChartWizard button.

•   If long is FALSE or omitted, CHART.WIZARD is equivalent to using the two-step ChartWizard button, and gallery_num, type_num, legend, and the title arguments are ignored. 

Ref    is a reference to the range of cells on the active worksheet that contains the source data for the chart, or the object identifier of the chart if it has already been created.

Gallery_num    is a number from 1 to 15 specifying the type of chart you want to create.

Gallery_num

 

Chart

1           Area

2           Bar

3           Column

4           Line

5           Pie

6           Radar

7           XY (scatter)

8           Combination

9           3-D area

10           3-D bar

11           3-D column

12           3-D line

13           3-D pie

14           3-D surface

15           Doughnut

Type_num    is a number identifying a formatting option. The first formatting option in any gallery is 1.

Plot_by    is the number 1 or 2 and specifies whether the data for each data series is in rows or columns. 1 specifies rows; 2 specifies columns. If plot_by is omitted, Microsoft Excel uses the appropriate value for the chart you're creating.

Categories    is the number 1 or 2 and specifies whether the first row or column contains a list of x-axis labels, or data for the first data series. 1 specifies x-axis labels; 2 specifies the first data series. If categories is omitted, Microsoft Excel uses the appropriate value for the chart you're creating. If number_cats is specified, this argument is ignored.

Ser_titles    is the number 1 or 2 and specifies whether the first column or row contains series titles, or data for the first data point in each series. 1 specifies series titles; 2 specifies the first data point. If ser_titles is omitted, Microsoft Excel uses the appropriate value for the chart you're creating. If number_titles is specified, this argument is ignored.

Legend    is the number 1 or 2 and specifies whether to include a legend. 1 specifies a legend; 2 specifies no legend. If legend is omitted, Microsoft Excel does not include a legend.

For the following arguments, if an argument is omitted or is empty text (""), no title is specified.

Title    is text that you want to use as a chart title.

X_title    is text that you want to use as an x-axis title.

Y_title    is text that you want to use as a y-axis title.

Z_title    is text that you want to use as a z-axis title.

Number_cats    specifies the number of rows or columns (depending on the value of plot_by) to use for the category labels in the chart. This argument overrides the categories argument.

Number_titles    specifies the number of rows or columns (depending on the value of plot_by) to use for the series labels in the chart. This argument overrides the ser_title argument.

Remarks

If you are using the macro recorder, Microsoft Excel records a CREATE.OBJECT and a COPY function when the chart is created and a CHART.WIZARD function when the chart is formatted. You must precede this function with a CREATE.OBJECT function if you are not using the macro recorder.

Related Function

CREATE.OBJECT   Creates an object

CHECKBOX.PROPERTIES

Sets various properties of check box and option box controls on a worksheet or dialog sheet.

Syntax

CHECKBOX.PROPERTIES(value, link, accel_text, 3d_shading, accel_text2)

CHECKBOX.PROPERTIES?(value, link, accel_text, 3d_shading, accel_text2,)

Value    is the value of the check box or option button setting that determines whether it is selected or not.

Value

 

Box or Button Setting

0         or FALSE Off

1         or TRUE        On

2         Mixed

Link    is the cell on the sheet to which the check box or option button value is linked. Whenever one of these two controls is changed, the value of the control is entered into the cell. Similarly, whenever the value in the cell is changed, the setting for the corresponding check box or option button is also changed. To clear the link, set this value to an empty string. For example, entering "TRUE" into a cell linked to a check box will select that check box.

3d_shading    is a logical value that specifies whether the check box appears as 3-D. If TRUE, the check box will appear as 3-D. If FALSE or omitted, the check box will not be 3-D. This argument is available for only worksheets.

Accel_text    is a text string containing the character to use as the control's accelerator key on a dialog sheet. The character is matched against the text of the control, and the first matching character is underlined. When the user presses ALT+accel_text in Microsoft Excel for Windows or COMMAND+accel_text in Microsoft Excel for the Macintosh, the control is clicked.

Accel_text2    is a text string containing the second accelerator key on a dialog sheet. This argument is for only Far East versions of Microsoft Excel.

Remarks

Only controls on dialog sheets can have accelerator keys. Worksheet controls cannot have accelerator keys.

Related Functions

PUSHBUTTON.PROPERTIES   Sets the properties of the push button control

EDITBOX.PROPERTIES   Sets the properties of an edit box on a worksheet or dialog sheet

LABEL.PROPERTIES   Sets the accelerator property of the label and group box control

LISTBOX.PROPERTIES   Sets the properties of a list box and drop-down box controls on a worksheet or dialog sheet

CHECK.COMMAND

Adds or removes a check mark to or from a command name on a menu. A check mark beside a command indicates that the command has been chosen.

Syntax

CHECK.COMMAND(bar_num, menu, command, check, position)

Bar_num    is the menu bar containing the command. Bar_num can be the ID number of a built-in or custom menu bar.

Menu    is the menu containing the command. Menu can be either the name of a menu as text or the number of a menu. Menus are numbered starting with 1 from the left of the screen.

Command    is the command you want to check or the submenu containing the command you want to check. Command can be the name of the command as text or the number of the command; the first command on a menu is in position 1.

Check    is a logical value corresponding to the check mark. If check is TRUE, Microsoft Excel adds a check mark to the command; if FALSE, Microsoft Excel removes the check mark.

position    is the name of a command on a submenu that you want to check.

Remarks 

•    The check mark doesn't affect execution of the command. Microsoft Excel automatically adds and deletes check marks to some commands, such as the name of the active workbook in the Window menu. If you have assigned a check mark to a built-in command that Microsoft Excel automatically changes in response to the user's actions, the check mark will be added or removed as appropriate, and any check marks you have added or deleted with CHECK.COMMAND will be ignored.

•    If you use CHECK.COMMAND with a command on a Microsoft Excel version 4.0 menu bar, the corresponding command on the Microsoft Excel version 5.0 or later menu bar will not be effected. 

Example

The following macro formula adds a check mark to the Sales command on the Weekly menu on a custom menu bar created by the function in a cell named Reports:

CHECK.COMMAND(Reports, "Weekly", "Sales", TRUE)

Related Functions

ADD.COMMAND   Adds a command to a menu

DELETE.COMMAND   Deletes a command from a menu

ENABLE.COMMAND   Enables or disables a menu or custom command

RENAME.COMMAND   Changes the name of a command or menu

CLEAR

Equivalent to clicking the Clear command on the Edit menu. Clears contents, formats, notes, or all of these from the active worksheet or macro sheet. Clears series or formats from the active chart.

Syntax

CLEAR(type_num)

CLEAR?(type_num)

Type_num    is a number from 1 to 4 specifying what to clear. Only values 1, 2, and 3 are valid if the selected item is a chart.

On a worksheet or macro sheet, or if an entire chart is selected, the following occurs.

Type_num

 

Clears

1          All

2          Formats (if a chart, clears the chart format or clears pictures)

3          Contents (if a chart, clears all data series)

4          Comments (this does not apply to charts)

On a chart, if a single point, an entire data series, error bars, or a trend line is selected, the following occurs.

Type_num

 

Clears

1         Selected series, error bars, or trend line

2         Format in the selected point, series, error bars, or trend line

If type_num is omitted, the default values are set as shown in the following table.

Active sheet

 

Type_num

Worksheet                          3

Macro sheet                        3

Chart (with no selection)       1

Chart (with item selected) Deletes the selected item

Related Function

EDIT.DELETE   Removes cells from a sheet

CLEAR.OUTLINE

Equivalent to clicking the Clear Outline command on the Group And Outline submenu of the Data menu. Clears the outline within the selection. If a single cell is selected, it clears the outline from the entire sheet.

Syntax

CLEAR.OUTLINE( )

Related Functions

AUTO.OUTLINE   Creates an outline

OUTLINE   Creates an outline and defines settings for automatically creating outlines

Equivalent to the Clear button in the Routing Slip dialog box. Clears the routing slip.

Syntax

(reset_only_logical)

Reset_only_logical    is a logical value that specifies whether the routing slip should be cleared. 

•   This option is valid only after every recipient on the routing slip has received and forwarded the workbook. Setting reset_only_logical to TRUE in this case is equivalent to the Reset button in the routing slip dialog.

•   If some recipients have not received or routed the workbook, reset_only_logical is ignored.

•   If reset_only_logical is FALSE or omitted and the workbook has been routed to all recipients, then the routing slip is removed from the workbook. A new slip can be subsequently added using .

CLOSE

Closes the active window. In Microsoft Excel for Windows, CLOSE is equivalent to clicking the Close command on the Document Control menu. In Microsoft Excel for the Macintosh, CLOSE is equivalent to clicking the close box.

Syntax

CLOSE(save_logical, route_logical)

Save_logical    is a logical value that specifies whether to save the file before closing the window.

Save_logical

 

Result

TRUE                     Saves the file

FALSE

Does not save the file

Omitted

If you've made changes to the file, displays a dialog box asking if you want to save the file

Route_logical    is a logical value that specifies whether to route the file after closing it. This argument is ignored if there is not a routing slip present.

Route_logical

 

Result

 

TRUE

Routes the file

 

 

FALSE

Does not route the file

 

 

Omitted

If you've specified recipients for routing, displays a dialog box asking if you want to save the file

 

           

Remarks

Users of Microsoft Excel versions earlier than 4.0 should note that if the macro sheet containing the function is the active sheet, CLOSE now closes the workbook.

Note   When you use the CLOSE function, Microsoft Excel does not run any Auto_Close macros before closing the workbook. Related Functions

   Closes all windows

FILE.CLOSE   Closes the active workbook

SAVE   Saves the active workbook

Equivalent to clicking the Close All command on the File menu. The Close All command appears when you hold down SHIFT while selecting the File menu. Closes all protected and unprotected windows and all hidden windows. If unsaved changes have been made to the workbook in one or more windows, a message is displayed asking if you want to save each workbook. Syntax

( )

Related Functions

CLOSE   Closes the active window

FILE.CLOSE   Closes the active workbook

QUIT   Ends a Microsoft Excel session

SAVE   Saves the active workbook

COLOR.PALETTE

Copies a color palette from an open workbook to the active workbook. Use COLOR.PALETTE to share color palettes between workbooks.

Syntax

COLOR.PALETTE(file_text)

COLOR.PALETTE?(file_text)

File_text    is the name of a workbook, as a text string, that you want to copy a color palette from. The workbook specified by file_text must be open, or COLOR.PALETTE returns the #VALUE! error value and interrupts the macro. If file_text is empty text (""), then COLOR.PALETTE sets colors to the default values.

Related Function

EDIT.COLOR   Defines a color on the color palette

COLUMN.WIDTH

Equivalent to choosing the Width command on the Column submenu of the Format menu. Changes the width of the columns in the specified reference.

Syntax

COLUMN.WIDTH(width_num, reference, standard, type_num, standard_num)

COLUMN.WIDTH?(width_num, reference, standard, type_num, standard_num)

Width_num    specifies how wide you want the columns to be in units of one character of the font corresponding to the Normal cell style. Width_num is ignored if standard is TRUE or if type_num is provided.

Reference    specifies the columns for which you want to change the width. 

•   If reference is specified, it must be either an external reference to the active worksheet, such as !$A:$C or !Database, or an R1C1-style reference in the form of text, such as "C1:C3", "C[-4]:C[-2]", or "Database".

•   If reference is a relative R1C1-style reference in the form of text, it is assumed to be relative to the active cell.

•   If reference is omitted, it is assumed to be the current selection. 

Standard_num    is a logical value corresponding to the Standard Width command from the Column submenu on the Format menu. 

•   If standard is TRUE, Microsoft Excel sets the column width to the currently defined standard (default) width and ignores width_num.

•   If standard is FALSE or omitted, Microsoft Excel sets the width according to width_num or type_num. 

Type_num    is a number from 1 to 3 corresponding to the Hide, Unhide, or AutoFit Selection commands, respectively, on the Column submenu of the Format menu.

Type_num

 

Action taken

1           Hides the column selection by setting the column width to 0

2           Unhides the column selection by setting the column width to the value set before the selection was hidden

3           Sets the column selection to a best-fit width, which varies from column to column depending on the length of the longest data string in each column

Standard_num    specifies how wide the standard width is, and is measured in points. If standard_num is omitted, the standard width setting remains unchanged.

Remarks 

•    Changing the value of standard_num changes the width of all columns except those that have been set to a custom value.

•    If any of the argument settings conflict, such as when standard is TRUE and type_num is 3, Microsoft Excel uses the type_num argument and ignores any arguments that conflict with type_num.

•    If you are recording a macro while using a mouse and you change column widths by dragging the column border, Microsoft Excel records the references of the columns using R1C1-style references in the form of text. 

Related Function

ROW.HEIGHT   Changes the heights of rows

COMBINATION

Changes the format of the active chart to one of six built-in combination chart types.

Syntax

COMBINATION(type_num)

COMBINATION?(type_num)

Type_num    is a number corresponding to the combination chart you want.

Type_num

 

Result

1           Column chart overlaid by a line chart

2           Column chart overlaid by a line chart with an independent y-axis scale

3           Line chart overlaid by a line chart with an independent y-axis scale

4           Area chart overlaid by a column chart

5           Column chart overlaid by a line chart containing three data series (for showing stock volumes related to high, low, and closing prices)

6           Column chart overlaid by a line chart containing four data series (for showing stock volumes related to open, high, low, and closing prices

Related Functions

   Formats a main chart

FORMAT.OVERLAY   Formats an overlay chart

CONSOLIDATE

Equivalent to clicking the Consolidate command on the Data menu. Consolidates data from multiple ranges on multiple worksheets into a single range on a single worksheet.

Syntax

CONSOLIDATE(source_refs, function_num, top_row, left_col, create_links)

CONSOLIDATE?(source_refs, function_num, top_row, left_col, create_links)

Source_refs    are references to areas that contain data to be consolidated on the destination worksheet. Source_refs must be in text form and include the full path of the file and the cell reference or named ranges in the workbook to be consolidated. Source_refs are usually external references and must be given as an array, for example: {"SHEET1!IncomeOne", "SHEET2!IncomeTwo"}.

To add or delete source_refs from an existing consolidation on a worksheet, reuse the CONSOLIDATE function, specifying the new source_refs.

Function_num    is a number from 1 to 11 that specifies one of the 11 functions you can use to consolidate data. If function_num is omitted, the SUM function, number 9, is used. The functions and their corresponding numbers are listed in the following table.

Function_num

 

Function

1            AVERAGE

2            COUNT

3            COUNTA

4            MAX

5            MIN

6            PRODUCT

7            STDEV

8            STDEVP

9            SUM

10            VAR

11            VARP

The following arguments correspond to text boxes and check boxes in the Consolidate dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box.

Top_row    corresponds to the Top Row check box. The default is FALSE.

Left_col    corresponds to the Left Column check box. The default is FALSE.

If top_row and left_col are both FALSE or omitted, the data is consolidated by position.

Create_links    corresponds to the Create Links To Source Data check box.

Remarks 

•    If you use the CONSOLIDATE function with no arguments and there is a consolidation on the active worksheet, Microsoft Excel reconsolidates, using the sources, function, and position attributes used to create the existing consolidation.

•    If you use the CONSOLIDATE function with no arguments and there is no consolidation on the active worksheet, the function returns the #VALUE! error value. 

Related Functions

   Changes supporting workbook links

LINKS   Returns the names of all linked workbooks

OPEN.LINKS   Opens specified supporting workbooks

   Updates a link to another workbook

CONSTRAIN.NUMERIC

Equivalent to pressing the Constrain Numeric button. The Constrain Numeric button can be found in the Insert category on the Commands tab (Customize dialog box). The Customize dialog box appears when you choose the Toolbars command from the View menu and then choose the Customize command. Constrains handwriting recognition to numbers and punctuation only. Use this function in a macro to improve the accuracy of handwriting recognition when the user is entering a series of numbers or formulas.

Note   This function is only available if you are using Microsoft Windows for Pen Computing.

Syntax

CONSTRAIN.NUMERIC(numeric_only)

Numeric_only    is a logical value that turns the numeric constraint on or off. If numeric_only is TRUE, only numbers and digits are recognized; if FALSE, all characters are recognized as usual. if numeric_only is omitted, the numeric constraint is toggled.

Remarks

When the numeric constraint is on, Microsoft Excel recognizes only the following symbols:

0 1 2 3 4 5 6 7 8 9 $ # @ % ( ) - + = { } : < > , ? | .

Tip   Use GET.WORKSPACE(45) to make sure you're running Microsoft Windows for Pen Computing.

COPY

Equivalent to clicking the Copy command on the Edit menu. Copies and pastes data or objects.

Syntax

COPY(from_reference, to_reference)

From_reference    is a reference to the cell or range of cells you want to copy. If from_reference is omitted, it is assumed to be the current selection.

To_reference    is a reference to the cell or range of cells where you want to paste what you have copied. 

•   To_reference should be a single cell or an enlarged multiple of from_reference. For example, if from_reference is a 2 by 4 rectangle, to_reference can be a 4 by 8 rectangle.

•   To_reference can be omitted so that you can subsequently paste using the PASTE, , or PASTE.SPECIAL functions. 

Related Functions

CUT   Cuts or moves data or objects

PASTE   Pastes cut or copied data

   Pastes copied data or objects and establishes a link to the source of the data or object

PASTE.SPECIAL   Pastes specific components of copied data

COPY.CHART

Equivalent to choosing the Copy Chart command from the Edit menu in Microsoft Excel for the Macintosh version 1.5 or earlier. This function is included only for macro compatibility. You can copy a chart with the COPY.PICTURE function by omitting the appearance_num argument.

Syntax

COPY.CHART(size_num)

Size_num    is a number describing how to copy the picture and is only available if the current selection is a chart.

Size_num

 

Action

1            or omitted         Copies the chart in the same size as the window on which it is displayed

2            Copies what you would see if you printed the chart

Related Function

COPY.PICTURE   Creates a picture of the current selection for use in another program

COPY.PICTURE

Equivalent to choosing the Copy Picture command from the Edit menu. The Copy Picture command appears if you hold down SHIFT while choosing the Edit menu. It copies a chart or range of cells to the Clipboard as a graphic. Use COPY.PICTURE to create an image of the current selection or chart for use in another program.

Syntax

COPY.PICTURE(appearance_num, size_num, type_num)

COPY.PICTURE?(appearance_num, size_num, type_num)

Remarks

Graphics are created differently on screen and on a printer. Thus, the printed picture may look different from the one on screen.

Appearance_num    is a number describing how to copy the picture.

Appearance_num

 

Action

1               or omitted        Copies a picture as closely as possible to the picture displayed on your screen

2               Copies what you would see if you printed the selection

Size_num    is a number describing how to copy the picture and is only available if the current selection is a chart.

Size_num

 

Action

1            or omitted         Copies the chart in the same size as the window on which it is displayed

2            Copies what you would see if you printed the chart

Type_num    is a number specifying the format of the picture. This argument is available only in Microsoft Excel for Windows.

Type_num

 

Format of the picture

1          or omitted Picture

2          Bitmap

Related Functions

COPY   Copies and pastes data or objects

CUT   Cuts or moves data or objects

PASTE   Pastes cut or copied data

   Pastes a linked picture of the currently copied area

PASTE.SPECIAL   Pastes specific components of copied data

Copies a button face to the Clipboard.

Syntax

(bar_id, position)

Bar_id    specifies the number or name of a toolbar from which you want to copy the button face. For detailed information about bar_id, see .

Position    specifies the position of the button within the toolbar. Position starts with 1 at the left side (if horizontal) or at the top (if vertical).

Related Functions

   Adds one or more buttons to a toolbar

   Returns information about a button or buttons on a toolbar

   Pastes a button face from the Clipboard to a specified position on a toolbar

CREATE.NAMES

Equivalent to clicking the Create command on the Name submenu of the Insert menu. Use CREATE.NAMES to quickly create names from text labels on a sheet.

Arguments are logical values corresponding to check boxes in the Create Names dialog box. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE or omitted, Microsoft Excel clears the check box.

Syntax

CREATE.NAMES(top, left, bottom, right) CREATE.NAMES?(top, left, bottom, right)

Top    corresponds to the Top Row check box.

Left    corresponds to the Left Column check box.

Bottom    corresponds to the Bottom Row check box.

Right    corresponds to the Right Column check box.

Remarks

The cell containing the label text that Microsoft Excel uses to create the names is not included in the resulting named range.

Related Functions

APPLY.NAMES   Replaces references and values with their corresponding names

   Defines a name on the active sheet or macro sheet

   Deletes a name

   Selects a named area or reference on any open workbook

CREATE.OBJECT

Draws an object on a sheet or macro sheet and returns a value identifying the object created. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax 1

Lines, rectangles, ovals, arcs, pictures, text boxes, and buttons

CREATE.OBJECT(obj_type, ref1, x_offset1, y_offset1, ref2, x_offset2, y_offset2, text, fill, editable)

Syntax 2

Polygons

CREATE.OBJECT(obj_type, ref1, x_offset1, y_offset1, ref2, x_offset2, y_offset2, array, fill)

Syntax 3

Embedded charts

CREATE.OBJECT(obj_type, ref1, x_offset1, y_offset1, ref2, x_offset2, y_offset2, xy_series, fill, gallery_num, type_num, plot_visible)

Obj_type    is a number specifying the type of object to create.

Obj_type

 

Object

1        Line

2        Rectangle

3        Oval

4        Arc

5        Embedded chart

6        Text box

7        Button

8        Picture (created with the camera tool)

9        Closed polygon

10        Open polygon 11      Check box

12        Option button

13        Edit box

14        Label

15        Dialog frame

16        Spinner

17        Scroll bar

18        List box

19        Group box

20        Drop down list box

Ref1    is a reference to the cell from which the upper-left corner of the object is drawn, or from which the upper-left corner of the object's bounding rectangle is defined.

X_offset1    is the horizontal distance from the upper-left corner of ref1 to the upper-left corner of the object or to the upper-left corner of the object's bounding rectangle. X_offset1 is measured in points. A point is 1/72nd of an inch. If x_offset1 is omitted, it is assumed to be 0.

Y_offset1    is the vertical distance from the upper-left corner of ref1 to the upper-left corner of the object or to the upper-left corner of the object's bounding rectangle. Y_offset1 is measured in points. If y_offset1 is omitted, it is assumed to be 0.

Ref2    is a reference to the cell from which the lower-right corner of the object is drawn, or from which the lower-right corner of the object's bounding rectangle is defined.

X_offset2    is the horizontal distance from the upper-left corner of ref2 to the lower-right corner of the object or to the lower-right corner of the object's bounding rectangle. X_offset2 is measured in points. If x_offset2 is omitted, it is assumed to be 0.

Y_offset2    is the vertical distance from the upper-left corner of ref2 to the lower-right corner of the object or to the lower-right corner of the object's bounding rectangle. Y_offset2 is measured in points. If y_offset2 is omitted, it is assumed to be 0.

Text    specifies the text that appears in a text box or button. If text is omitted for a button, the button is named "Button n", where n is a number. If obj_type is not 6 or 7, text is ignored.

Fill    is a logical value specifying whether the object is filled or transparent. If fill is TRUE, the object is filled; if FALSE, the object is transparent; if omitted, the object is filled with an applicable pattern for the object being created.

Array    is an n by 2 array of values, or a reference to a range of cells containing values, that indicate the position of each vertex in a polygon, relative to the upper-left corner of the polygon's bounding rectangle. 

•   A vertex is a point that is defined by a pair of coordinates in one row of array.

•   If the polygon contains many vertices, one array may not be sufficient to define it. If the number of characters in the formula exceeds 1024, you must include one or more EXTEND.POLYGON functions. If you're recording a macro, Microsoft Excel automatically records EXTEND.POLYGON functions as needed. For more information, see EXTEND.POLYGON. 

Xy_series    is a number from 0 to 3 that specifies how data is arranged in a chart and corresponds to options in the Paste Special dialog box.

Xy_series

 

Result

0          Displays a dialog box if the selection is ambiguous

1          or omitted        First row/column is the first data series

2          First row/column contains the category (x) axis labels

3          First row/column contains the x-values; the created chart is an xy

(scatter) chart

•   Xy_series is ignored unless obj_type is 5 (chart).

•   If you want more control over how the data is arranged, use the plot_by, categories, and ser_titles arguments to the CHART.WIZARD function. For more information, see CHART.WIZARD. 

Gallery_num    is a number from 1 to 15 specifying the type of embedded chart you want to create.

Gallery_num

 

Chart

1           Area

2           Bar

3           Column

4           Line

5           Pie

6           Radar

7           XY (scatter)

8           Combination

9           3-D area

10           3-D bar

11           3-D column

12           3-D line

13           3-D pie

14           3-D surface

15           Doughnut

Type_num    is a number identifying a formatting option for a chart. The formatting options are shown in the dialog box of the AutoFormat command that corresponds to the type of chart you're creating. The first formatting option in any gallery is 1.

Plot_visible    is a logical value that corresponds to the Plot Visible Cells Only checkbox in the Chart tab of the Options dialog box. If FALSE or omitted, all values are plotted.

Editable    is a logical value that determines whether the drop down list box is editable or not. If TRUE, the drop down list box is editable. If FALSE, the drop down list box is not editable. If obj_type is not 20, this argument is ignored.

Remarks 

•    CREATE.OBJECT returns the object identifier of the object it created. Object identifiers include text describing the object, such as "Text" or "Oval", and a number indicating the order in which the object was created. For example, CREATE.OBJECT returns "Oval 3" after creating an oval that is the third object in the workbook.

•    If the offsets are not specified, the object is drawn from the upper-left corner of ref1 to the upper-left corner of ref2.

•    If the object is not a picture and either ref1 or ref2 is omitted, CREATE.OBJECT returns the #VALUE! error value and does not create the object.

•    CREATE.OBJECT also selects the object.

•    You must use the COPY function before the CREATE.OBJECT function to create a chart or a picture. 

Tip   To assign a macro to an object, use the .OBJECT function immediately after creating the object.

Related Functions

.OBJECT   Assigns a macro to an object

EXTEND.POLYGON   Adds vertices to a polygon

   Moves the selected object

FORMAT.SHAPE   Inserts, moves, or deletes vertices of the selected polygon

   Sizes an object

GET.OBJECT   Returns information about an object

OBJECT.PROPERTIES   Determines an object's relationship to underlying cells    Replaces text in a text box

CREATE.PUBLISHER

Equivalent to clicking the Create Publisher command on the Publishing submenu of the Edit menu. Publishes the selected range or chart to an edition file for use by other Macintosh applications.

Important   This function is only available if you are using Microsoft Excel for the Macintosh with system software version 7.0 or later.

Syntax

CREATE.PUBLISHER(file_text, appearance, size, formats)

CREATE.PUBLISHER?(file_text, appearance, size, formats)

File_text    is a text string to be used as the name of the new file that will contain the selected data. If file_text is omitted, Microsoft Excel uses the format "<WorkbookName> Edition #n", where WorkbookName is the name of the workbook from which the publisher is being created, Edition indicates that the file is an edition file, and n is a unique integer.

For example, if you omit file_text and are publishing a selection from a workbook named Seasonal, and it is your third publisher from that workbook in the current work session, the default name of the publisher would be "Seasonal Edition #3".

Appearance    specifies whether the selection is to be published as shown on screen or as shown when printed. The default value for appearance is 1 if the selection is a sheet and 2 if the selection is a chart.

Appearance

 

Selection is published

1           As shown on screen

2           As shown when printed

Size    specifies the size at which to publish a chart. Size is only available if a chart is to be published.

Size

 

Chart is published

1          or omitted As shown on screen

2          As shown when printed

Formats    is number specifying what file format or formats CREATE.PUBLISHER should use when it creates the Edition file.

Formats

 

File format

1        PICT

2        BIFF

4                RTF

8                VALU

•   You can also use the sum of the allowable file formats for formats. For example, a value of 6 specifies BIFF and RTF.

•   If formats is omitted and the document is a sheet, formats is assumed to be 15 (all formats); if the document is a chart, formats is assumed to be 1 (PICT). 

Related Functions

EDITION.OPTIONS   Sets publisher and subscriber options

   Returns information about a link

   Inserts contents of an edition into the active workbook

   Updates a link to another workbook

CUSTOMIZE.TOOLBAR

Equivalent to choosing the Toolbars command from the View menu and choosing the

Customize button in Microsoft Excel 95. Displays the Customize Toolbars dialog box. In Microsoft Excel 97 or later, this function displays the Commands tab on the Customize dialog box. The Customize dialog box appears when you choose the Toolbars command from the View menu and then choose the Customize command. This function has a dialog-box syntax only.

Syntax

CUSTOMIZE.TOOLBAR?(category)

Category    is a number that specifies which category of tools you want displayed in the dialog box. If omitted, the previous setting is used. This argument is for compatibility with Microsoft Excel 95.

Category

 

Category of tools

1       File

2       Edit

3       Formula

4       Formatting

5       Text Formatting

6       Drawing

7       Macro

8       Charting

9       Utility

10       Data

11       TipWizard

12       Auditing

13       Forms

14       Custom

Related Functions

ADD.TOOLBAR   Creates a new toolbar with the specified tools

SHOW.TOOLBAR   Hides or displays a toolbar

CUSTOM.REPEAT

Allows custom commands to be repeated using the Repeat tool or the Repeat command on the Edit menu. Also allows custom commands to be recorded using the macro recorder.

Syntax

CUSTOM.REPEAT(macro_text, repeat_text, record_text)

Macro_text    is the name of, or a reference to, the macro you want to run when the Repeat command is chosen. If macro_text is omitted, no repeat macro is run, but the custom command can still be recorded.

Repeat_text    is the text you want to use as the repeat command on the Edit menu (for example, "Repeat Reports"). You can omit repeat_text and macro_text if you only want to record the formula specified by record_text when using the macro recorder.

Record_text is the formula you want to record. For example, if the user clicks a command named Run Reports in Macro 1, the record_text argument would be

"=Macro1!RunReports()", where RunReports is the name of the macro called by the Run Reports command. 

•   References in record_text must be in R1C1 format.

•   If record_text is omitted, the macro recorder records normally (a RUN function with the first cell of the macro as its argument).

•   If you are not recording a macro, record_text is ignored. 

Tip   Place CUSTOM.REPEAT at the end of the macro you will want to repeat. If you place it before the end, then the macro formulas that follow CUSTOM.REPEAT may interfere with the desired effects of CUSTOM.REPEAT. The Repeat tool and the Repeat command continue to change as you click subsequent commands that can be repeated.

Example

The following macro formula specifies that the macro RepeatReport on the MenuMacros macro sheet in the current workbook will be run when the Repeat Report command is chosen:

CUSTOM.REPEAT("MenuMacros!RepeatReport", "Repeat Report")

Related Function

   Specifies a macro to run to undo a custom command

Creates a customized Undo tool and Undo or Redo command on the Edit menu for custom commands.

Syntax

(macro_text, undo_text)

Macro_text    is the name of, or an R1C1-style reference to, the macro you want to run when the Undo command is chosen. Macro_text can be the name or cell reference of a macro.

Undo_text    is the text you want to use as the Undo command.

Example

The following macro function runs the UndoMult macro when the user clicks the Undo Times100 command, a custom command that multiples the current cell by 100.

("UndoMult", "&Undo Times100")

Tip   Use directly after the macro functions you want to be able to repeat, because other macro functions following might reset the Undo command.

Related Function

CUSTOM.REPEAT   Specifies a macro to run to repeat a custom command


CUT

Equivalent to choosing the Cut command from the Edit menu. Cuts or moves data or objects.

Syntax

CUT(from_reference, to_reference)

From_reference    is a reference to the cell or range of cells you want to cut. If from_reference is omitted, it is assumed to be the current selection.

To_reference    is a reference to the cell or range of cells where you want to paste what you have cut. 

•   To_reference should be a single cell or an enlarged multiple of from_reference. For example, if from_reference is a 2 by 4 rectangle, to_reference can be a 4 by 8 rectangle.

•   To_reference can be omitted so that you can paste from_reference later using the PASTE or PASTE.SPECIAL functions. 

Remarks

The following information may be helpful if you're having problems with CUT updating references in unexpected ways. When you move cells using CUT, formulas that referred to from_reference will refer to to_reference, and formulas that referred to to_reference may return #REF! error values. However, if from_reference or to_reference contains references that are calculated at runtime (for example, CUT((), !B1)), then Microsoft Excel does not update those references when the CUT function is run, so no error values are returned.

Related Functions

COPY   Copies and pastes data or objects

PASTE   Pastes cut or copied data

DATA.DELETE

Equivalent to clicking the Delete command on the Data menu in Microsoft Excel version 4.0. Deletes data that matches the current criteria in the current database.

In the dialog-box form, DATA.DELETE?, Microsoft Excel displays a message warning you that matching records will be permanently deleted, and you can approve or cancel. In the plain form, DATA.DELETE, matching records are deleted without any message being displayed.

Syntax

DATA.DELETE( )

DATA.DELETE?( )

Equivalent to clicking the Find and Exit Find commands on the Data menu in Microsoft Excel version 4.0. Selects records in the database range which match criteria in the criteria range.

Syntax

(logical)

Logical    is a logical value that specifies whether to enter or exit the Data Find mode. If logical is TRUE, Microsoft Excel carries out the Find command; if FALSE, Microsoft Excel carries out the Exit Find command. If logical is omitted, the function toggles between Find and Exit Find.

Related Functions

   Finds next matching record in a database

   Finds previous matching record in a database

,

Equivalent to pressing the DOWN ARROW or UP ARROW key after the Find command has been chosen from the Data menu in Microsoft Excel version 4.0. Finds the next or previous matching record in a database. If the function cannot find a matching record, it returns the logical value FALSE.

Syntax

( ) ( )

Related Function

   Enters or exits Data Find mode

Equivalent to clicking the Form command on the Data menu. Displays the data form.

If Microsoft Excel cannot determine what database or list of information to use, the function returns the #VALUE! error value and interrupts the macro.

Syntax

( )

Remarks 

•    You can still use custom data forms created in Microsoft Excel version 4.0 or earlier. To edit the definition table of the custom data form, use the Dialog Editor from Microsoft Excel version 4.0.

•    The data form can handle up to 32 fields. 

DATA.LABEL

Specifies label contents and position.

Syntax

DATA.LABEL(show_option, auto_text, show_key)

Show_option    is a number that specifies what type of labels to display.

Show_option

 

Type displayed

1            none

2            Show value

3            Show percent

4            Show label

5            Show label and percent

Auto_text    is a logical value that corresponds the Automatic Checkbox in the Data Labels dialog box. If TRUE, resets a chart's data labels back to their actual values. If FALSE, they are not reset. The Automatic Text checkbox appears only if the label has been selected and its value changed.

Show_key    is a logical value that specified whether to show the legend key next to the label. If TRUE, displays the legend key. If FALSE or omitted, does not display the legend key.

DATA.SERIES

Equivalent to clicking the Series command on the Fill submenu of the Edit menu. Use DATA.SERIES to enter an interpolated or incrementally increasing or decreasing series of numbers or dates on a sheet or macro sheet.

Syntax

DATA.SERIES(rowcol, type_num, date_num, step_value, stop_value, trend)

DATA.SERIES?(rowcol, type_num, date_num, step_value, stop_value, trend)

Rowcol    is a number that specifies where the series should be entered. If rowcol is omitted, the default value is based on the size and shape of the current selection.


Rowcol

 

Enter series in

1      Rows

2      Columns

Type_num    is a number from 1 to 4 that specifies the type of series.

Type_num

 

Type of series

1  or omitted Linear

2  Growth 3 Date

4                     AutoFill

Date_num    is a number from 1 to 4 that specifies the date unit of the series, as shown in the following table. To use the date_num argument, the type_num argument must be 3.

Date_num

 

Date unit

1          or omitted Day

2          Weekday

3          Month

4          Year

Step_value    is a number that specifies the step value for the series. If step_value is omitted, it is assumed to be 1.

Stop_value    is a number that specifies the stop value for the series. If stop_value is omitted, DATA.SERIES continues filling the series until the end of the selected range.

Trend    is a logical value corresponding to the Trend check box. If trend is TRUE, Microsoft Excel generates a linear or exponential trend; if FALSE or omitted, Microsoft Excel generates a standard data series.

Remarks 

•    If you specify a positive value for stop_value that is lower than the value in the active cell of the selection, DATA.SERIES takes no action.

•    If type_num is 4 (AutoFill), Microsoft Excel performs an AutoFill operation just as if you had filled the selection by dragging the fill selection handle or had used the macro function. 

Related Function

   Copies cells or automatically fills a selection

Equivalent to clicking the Define command on the Name submenu of the Insert menu. Defines a name on the active sheet or macro sheet. Use instead of when you want to define a name on the active sheet.

Syntax

(name_text, refers_to, macro_type, shortcut_text, hidden, category, local)

?(name_text, refers_to, macro_type, shortcut_text, hidden, category, local)

Name_text    is the text you want to use as the name. Names cannot include spaces, and cannot look like cell references.

Refers_to    describes what name_text should refer to, and can be any of the following values.

If refers_to is

 

Then name_text is

A number, text, or logical value                             Defined to refer to that value

An external reference, such as !$A$1 or Defined to refer to those cells SALES!$A$1:$C$3

A formula in the form of text, such as                    Defined to refer to that formula

"=2*PI()/360" (if the formula contains references, they must be R1C1-style references, such as

"=R2C2*(1+RC[-1])")

Omitted                                                            Defined to refer to the current selection

The next two arguments, macro_type and shortcut_text, apply only if the sheet in the active window is a macro sheet.

Macro_type    is a number from 1 to 3 that indicates the type of macro.

Macro_type

 

Type of macro

1           Custom function (also known as a function macro)

2           Command macro.

3           or omitted None (that is, name_text does not refer to a macro)

Shortcut_text    is a text value that specifies the macro shortcut key. Shortcut_text must be a single letter, such as "z" or "Z".

Hidden    is a logical value specifying whether to define the name as a hidden name. If hidden is TRUE, Microsoft Excel defines the name as a hidden name; if FALSE or omitted, Microsoft Excel defines the name normally.

Category    is a number or text identifying the category of a custom function and corresponds to categories in the Function Category list box. 

•   Categories are numbered starting with 1, the first category in the list.

•   If category is text but is not one of the existing function types, Microsoft Excel creates a new category and assigns your custom function to it.

Local    is a logical value which, if TRUE, defines the name on just the current sheet or macro sheet. If FALSE or omitted, defines the name for all sheets in the workbook.

Remarks 

•   You can use hidden names to define values that you want to prevent the user from seeing or changing; they do not appear in the Define Name, Paste Name, or Goto dialog boxes. Hidden names can only be created with the macro function.

•   If you are recording a macro and you define a name to refer to a formula, Microsoft Excel converts A1-style references to R1C1-style references. For example, if the active cell is C2, and you define the name Previous to refer to =B2, Microsoft Excel records that command as ("Previous","=RC[-1]").

•   In ?, the dialog-box form of the function, if refers_to is not specified, the current selection is proposed in the Refers To box. Also, if a name is not specified, text in the active cell is proposed as the name. 

Related Functions

   Deletes a name

   Returns a name matching a definition

   Returns the definition of a name

NAMES   Returns the names defined in a workbook

   Defines a name as a value

DEFINE.STYLE

Equivalent to clicking the Define button in the Style dialog box, which appears when you click the Style command on the Format menu. Creates and changes cell styles. There are seven syntax forms of this function. Use syntax 1 of DEFINE.STYLE to define styles based on the format of the active cell. To create a style by specifying number, font, and other formats, use syntaxes 2 through 7 of DEFINE.STYLE.

Syntax 1

Syntaxes 2-7

DEFINE.STYLE SYNTAX 1

Equivalent to clicking the Define button in the Style dialog box, which appears when you click the Style command on the Format menu. Creates and changes cell styles. There are seven syntax forms of this function. Use syntax 1 of DEFINE.STYLE to define styles based on the format of the active cell. To create a style by specifying number, font, and other formats, use syntaxes 2 through 7 of DEFINE.STYLE.

Syntax

DEFINE.STYLE(style_text, number, font, alignment, border, pattern, protection)

DEFINE.STYLE?(style_text, number, font, alignment, border, pattern, protection)

Style_text    is the name, as text, that you want to assign to the style.

The following arguments are logical values corresponding to check boxes in the Style dialog box. If an argument is TRUE, Microsoft Excel selects the check box and uses the corresponding format of the active cell in the style; if FALSE, Microsoft Excel clears the check box and omits formatting descriptions for that attribute. If style_text is omitted and all selected cells have identical formatting, the default is TRUE; if cells have different formatting, the default is FALSE.

Number    corresponds to the Number check box.

Font    corresponds to the Font check box.

Alignment    corresponds to the Alignment check box.

Border    corresponds to the Border check box.

Pattern    corresponds to the Pattern check box.

Protection    corresponds to the Protection check box.

Related Functions

DEFINE.STYLE Syntaxes 2-7

APPLY.STYLE   Applies a style to the selection

DELETE.STYLE   Deletes a cell style

MERGE.STYLES   Imports styles from another workbook into the active workbook

DEFINE.STYLE SYNTAXES 2 - 7

Equivalent to clicking the Define button in the Style dialog box, which appears when you click the Style command on the Format menu. Creates and changes cell styles. Use one of the following syntax forms of DEFINE.STYLE to select cell formats for a new style or to alter the formats of an existing style. Use syntax 1 of DEFINE.STYLE to define styles based on the format of the active cell.

Syntax 2

Number format, using the arguments from the FORMAT.NUMBER function

DEFINE.STYLE(style_text, attribute_num, format_text)

Syntax 3

Font format, using the arguments from the and FONT.PROPERTIES functions

DEFINE.STYLE(style_text, attribute_num, name_text, size_num, bold, italic, underline, strike, color, outline, shadow, superscript, subscript)

Syntax 4

Alignment, using the arguments from the ALIGNMENT function

DEFINE.STYLE(style_text, attribute_num, horiz_align, wrap, vert_align, orientation) Syntax 5

Border, using the arguments from the BORDER function

DEFINE.STYLE(style_text, attribute_num, left, right, top, bottom, left_color, right_color, top_color, bottom_color)

Syntax 6

Pattern, using the arguments from the cell form of the PATTERNS function

DEFINE.STYLE(style_text, attribute_num, apattern, afore, aback)

Syntax 7

Cell protection, using the arguments from the CELL.PROTECTION function

DEFINE.STYLE(style_text, attribute_num, locked, hidden)

Style_text    is the name, as text, that you want to assign to the style.

Attribute_num    is a number from 2 to 7 that specifies which attribute of the style, such as its font, alignment, or number format, you want to designate with this function.

Attribute_num

 

Specifies

2             Number format

3             Font format

4             Alignment

5             Border

6             Pattern

7             Cell protection

Remarks 

•    The remaining arguments are different for each form and are identical to arguments in the corresponding function. For example, form 2 of DEFINE.STYLE defines the number format of a style and corresponds to the FORMAT.NUMBER function. The exception is form 5, which does not include every argument for BORDER. For details on the values you can use for these arguments, see the description under the corresponding function.

•    If you define a style using one of these forms, then any attributes you don't explicitly define are not changed. 

Related Functions

DEFINE.STYLE Syntax 1

ALIGNMENT   Aligns or wraps text in cells

APPLY.STYLE   Applies a style to the selection

BORDER   Adds a border to the selected cell or object

CELL.PROTECTION   Allows you to control cell protection and display

DELETE.STYLE   Deletes a cell style

FONT.PROPERTIES   Applies a font to the selection

FORMAT.NUMBER   Formats numbers, dates, and times in the selected cells

MERGE.STYLES   Imports styles from another workbook into the active workbook

PATTERNS   Changes the appearance of the selected object

DELETE.ARROW

Deletes the selected arrow, either drawn as an arrow with the arrow tool or as a line that is later formatted as an arrow. In Microsoft Excel version 5.0 or later, arrows are named lines.

Syntax

DELETE.ARROW( )

If the selection is not an arrow or a line formatted as an arrow, or if the active window is not a chart, DELETE.ARROW interrupts the macro.

Tip   Use the SELECT function (chart syntax), with the number of the arrow (or line) you want to delete in order to select the arrow before using the DELETE.ARROW function. For example, SELECT ("Line 1"). You can also use the CLEAR function to delete the arrow.

Related Functions

CLEAR   Clears specified information from the selected cells or chart

DELETE.OVERLAY   Deletes the overlay on a chart

Deletes a custom menu bar.

Syntax

(bar_num)

Bar_num    is the ID number of the custom menu bar you want to delete.

Tip   Rather than trying to discover the ID number of the menu bar you want to delete, use a reference to the function that created the bar. For example, the following macro formula deletes the menu bar created by the function in the cell named ReportsBar:

(ReportsBar)

Related Functions

   Adds a menu bar

   Displays a menu bar

DELETE.CHART.AUTOFORMAT

Deletes a custom format from the list of formats shown in the Custom Types tab in the Chart Type dialog box.

Syntax

DELETE.CHART.AUTOFORMAT(name_text)

Name_text    is the template name you want to delete from the list of custom templates.

Related Function

ADD.CHART.AUTOFORMAT   Adds a custom template

DELETE.COMMAND

Deletes a command from a custom or built-in menu. Use DELETE.COMMAND to remove commands you don't want the user to have access to or to remove custom commands that you have added.

Syntax

DELETE.COMMAND(bar_num, menu, command, subcommand)

Bar_num    is the menu bar from which you want to delete the command. Bar_num can be the ID number of a built-in or custom menu bar. See ADD.COMMAND for a list of ID numbers for built-in menu bars and shortcut menus.

Menu    is the menu from which you want to delete the command. Menu can be the name of a menu as text or the number of a menu. Menus are numbered starting with 1 from the left of the screen.

Command    is the command you want to delete, or the name of a submenu. Command can be the name of the command as text or the number of the command; the first command on a menu is in position 1.

Subcommand    is the command you want to delete from a submenu. If you use subcommand, you must use command as the name of the submenu.

Remarks 

•    If the specified command does not exist, DELETE.COMMAND returns the #VALUE! error value and interrupts the macro.

•    After a command is deleted, the command number for all commands below that command is decreased by one.

•    When you delete a built-in command, DELETE.COMMAND returns a unique ID number for that command. You can use this ID number with ADD.COMMAND to restore the built-in command to the original menu. 

Example

The following macro formula removes the Compile Reports command from the Reports menu on a custom menu bar created by the function in a cell named Financials.

DELETE.COMMAND(Financials, "Reports", "Compile Reports ")

Related Functions

ADD.COMMAND   Adds a command to a menu

CHECK.COMMAND   Adds or deletes a check mark to or from a command

ENABLE.COMMAND   Enables or disables a menu or custom command

RENAME.COMMAND   Changes the name of a command or menu

DELETE.FORMAT

Equivalent to deleting the specified format in the Number tab in the Format Cells dialog box, which appears when you click the Cells command on the Format menu, or in the Number tab for selected chart objects. Deletes a specified built-in or custom number format.

Syntax

DELETE.FORMAT(format_text)

Format_text    is the format given as a text string, for example, "000-00-0000".

Remarks

When you delete a custom number format, all numbers formatted with that number format are formatted with the General format.

Related Functions

FORMAT.NUMBER   Applies a number format to the selection

   Returns information about the specified cell

Deletes a menu or submenu. Use to delete menus you have added to menu bars when the supporting macro sheet is closed (using an Auto_Close macro), or any time you want to remove a menu.

Syntax

(bar_num, menu, submenu)

Bar_num    is the menu bar from which you want to delete the menu. Bar_num can be the number of a Microsoft Excel built-in menu bar or the number returned by a previously run function. For a list of ID numbers for built-in menu bars, see ADD.COMMAND.

Menu    is the menu you want to delete. Menu can be either the name of a menu as text or the number of a menu. Menus are numbered starting with 1 from the left of the screen. If the specified menu does not exist, returns the #VALUE! error value and interrupts the macro. After a menu is deleted, the menu number for each menu to the right of that menu is decreased by 1.

Submenu    is the name of the submenu you want to delete or the number of the menu in the list of commands.

Remarks

You cannot delete a shortcut menu. Instead, use ENABLE.COMMAND to prevent the user from accessing a shortcut menu.

Example

The following macro formula deletes the Reports menu from the custom menu bar created by the function in a cell named Financials:

(Financials, "Reports")

Related Functions

   Adds a menu to a menu bar

   Adds a menu bar

   Deletes a menu bar

DELETE.COMMAND   Deletes a command from a menu

ENABLE.COMMAND   Enables or disables a menu or custom command

Equivalent to clicking the Delete button in the Define Name dialog box, which appears when you click the Define command on the Name submenu of the Insert menu. Deletes the specified name.

Syntax

(name_text)

Name_text    is a text value specifying the name that you want to delete.

Important   Formulas that use names in their arguments may return incorrect or error values when a name used in the formula is deleted.

Related Functions

   Defines a name in the active workbook

   Returns the definition of a name

   Defines a name as a value

DELETE.OVERLAY

Equivalent to clicking the Delete Overlay command on the Chart menu in Microsoft Excel version 4.0. Deletes all overlays from a chart. If the chart has no overlay, DELETE.OVERLAY takes no action and returns TRUE.

Syntax

DELETE.OVERLAY( )

DELETE.STYLE

Equivalent to choosing the Delete button from the Style dialog box, which appears when you choose the Style command from the Format menu. Deletes a style from a workbook. Cells formatted with the deleted style revert to the Normal style.

Syntax

DELETE.STYLE(style_text)

Style_text    is the name of a style to be deleted. If style_text does not exist, DELETE.STYLE returns the #VALUE! error value and interrupts the macro.

Remarks

You can only delete styles from the active workbook. External references are not permitted as part of the style_text argument.

Related Functions

APPLY.STYLE   Applies a style to the selection

DEFINE.STYLE   Creates or changes a cell style

MERGE.STYLES   Merges styles from another workbook into the active workbook

Equivalent to selecting a button and dragging it to an area other than a toolbar. Deletes a button from a toolbar.

Syntax

(bar_id, position)

Bar_id    specifies the name or number of a toolbar from which you want to delete a button. For detailed information about bar_id, see .

Position    specifies the position of the button within the toolbar. Position starts with 1 at the left side (if horizontal) or at the top (if vertical).

Related Functions

   Adds one or more buttons to a toolbar

ADD.TOOLBAR   Creates a new toolbar with the specified buttons

DELETE.TOOLBAR   Deletes custom toolbars

DELETE.TOOLBAR

Equivalent to clicking the Delete button in the Toolbars dialog box, which appears when you click the Customize command (View menu, Toolbars submenu). Deletes a custom toolbar.

Syntax

DELETE.TOOLBAR(bar_name)

Bar_name    specifies the name of the toolbar that you want to delete. For detailed information about bar_name, see .

Remarks 

•    You cannot delete built-in toolbars.

•    If DELETE.TOOLBAR successfully deletes the toolbar, it returns TRUE. If you try to delete a built-in toolbar, DELETE.TOOLBAR returns the #VALUE! error value, interrupts the macro, and takes no other action. 

Related Functions

   Adds or more buttons to a toolbar

ADD.TOOLBAR   Creates a new toolbar with the specified buttons

RESET.TOOLBAR   Resets a built-in toolbar to its initial default setting

DEMOTE

Equivalent to clicking the Group tool. Demotes, or groups, the selected rows or columns in an outline. Use DEMOTE to change the configuration of an outline by grouping rows or columns of information.

Syntax

DEMOTE(row_col)

DEMOTE?(row_col)

Row_col    specifies whether to group rows or columns.

Row_col

 

Demotes

1          or omitted Rows

2          Columns

Remarks 

•    If the selection consists of an entire row or rows, then rows are demoted even if row_col is 2. Similarly, selection of an entire column overrides row_col 1.

•    If the selection is unambiguous (an entire row or column), then DEMOTE? will not display the dialog box. 

Related Functions

PROMOTE   Promotes the selection in an outline

SHOW.DETAIL   Expands or collapses a portion of an outline

SHOW.LEVELS   Displays a specific number of levels of an outline

DEREF

Returns the value of the cells in a reference.

Syntax

DEREF(reference)

Reference    is the cell or cells from which you want to obtain a value. If reference is the reference of a single cell, DEREF returns the value of that cell. If reference is the reference of a range of cells, DEREF returns the array of values in those cells. If reference refers to the active sheet, it must be an absolute reference. Relative references are converted to absolute references.

Remarks

In most formulas, there is no difference between using a value and using the reference of a cell containing that value. The reference is automatically converted to the value, as necessary. For example, if cell A1 contains the value 2, then the formula =A1+1, like the formula =2+1, returns the result 3, because the reference A1 is converted to the value 2. However, in a few functions, such as the function, references are not automatically converted to values. Instead, those functions behave differently depending on whether an argument is a reference or a value.

Example

See the sixth example for .

Related Function

   Defines a names as a value

DESCR

Generates descriptive statistics for data in the input range.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

DESCR(inprng, outrng, grouped, labels, summary, ds_large, ds_small, confid) DESCR?(inprng, outrng, grouped, labels, summary, ds_large, ds_small, confid)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Grouped    is a text character that indicates whether the data in the input range is organized by row or column. 

•   If grouped is "C" or omitted, then the data is organized by column.

•   If grouped is "R" then the data is organized by row. 

Labels    is a logical value that describes where the labels are located in the input range, as shown in the following table:

Labels

 

Grouped

 

Labels are in

TRUE                          "C"                First row of the input range.

TRUE                          "R"                First column of the input range.

FALSE or omitted         (ignored)        No labels. All cells in the input range are data.

Summary    is a logical value. If TRUE, DESCR reports the summary statistics. If FALSE or omitted, no summary statistics are reported.

Ds_large    is an integer k. If ds_large is present, DESCR reports the k-th largest data point. If ds_large is omitted, the value is not reported.

Ds_small    is an integer k. If ds_small is present, DESCR reports the k-th smallest data point. If ds_small is omitted, the value is not reported.

Confid    is the confidence level of the mean. If confid is given, DESCR reports the confidence interval for the input range. If confid is omitted, the confidence interval is 95%.

Displays the dialog box described in a dialog box definition table.

Syntax

(dialog_ref)

Dialog_ref    is a reference to a dialog box definition table on sheet, or an array containing the definition table. 

•   If an OK button in the dialog box is chosen, enters values in fields as specified in the dialog_ref area and returns the position number of the button chosen. The position numbers start with 1 in the second row of the dialog box definition table.

•   If the Cancel button in the dialog box is chosen, returns FALSE. 

The dialog box definition table must be at least seven columns wide and two rows high. The definitions of each column in a dialog box definition table are listed in the following table.

Column type

 

Column number

 

Item number

1

 

 

Horizontal position

2

 

 

Vertical position

3

 

 

Item width

4

 

 

Item height

5

 

 

Text

6

 

           

Initial value or result 7

The first row of dialog_ref defines the position, size, and name of the dialog box. It can also specify the default selected item and the reference for the Help button. The position is specified in columns 2 and 3, the size in columns 4 and 5, and the name in column 6. To specify a default item, place the item's position number in column 7. You can place the reference for the Help button in row 1, column 1 of the table, but the preferred location is column 7 in the row where the Help button is defined. Row 1, column 1 is usually left blank.

The following table lists the numbers for the items you can display in a dialog box.

Dialog-box item

 

Item number

Default OK button                                            1

Cancel button                                                  2

OK button                                                       3

Default Cancel button                                       4

Static text                                                      5

Text edit box                                                   6

Integer edit box                                               7

Number edit box                                              8

Formula edit box                                              9

Reference edit box                                           10

Option button group                                         11

Option button                                                  12

Check box                                                      13

Group box

14

List box

15

Linked list box

16

Icons

17

Linked file list box (Windows only)

18

Linked drive and directory box (Windows only)

19

Directory text box

20

Drop-down list box

21

Drop-down combination edit/list box

22

Picture button

23

Help button

24

Remarks 

•    Add 100 to an item number in the above table to define the item as a trigger. A trigger is a dialog box item that, when chosen, returns to your macro (as clicking OK would) but continues to display the dialog box, allowing your macro to change the dialog box definition or display an alert message or another dialog box. The Help button, edit boxes, group boxes, static text, and icons cannot be triggers.

•    Add 200 to an item number to define it as dimmed. A dimmed (gray) item cannot be chosen or selected. For example, 203 is a dimmed OK button. You can use item 223 to include a picture in your dialog box that does not behave like a button.

•    If a trigger has been chosen and you still want to clear a dynamic dialog box from the screen, use (FALSE). This is useful if you want to confirm that the dialog box has been filled out correctly before dismissing it.

•    The dialog box definition table can be an array. If dialog_ref is an array instead of a reference, returns a modified copy of that array, along with the results of the dialog box in the seventh column. (The first item in the seventh column is the position number of the chosen button or of a triggered item.) This is useful if you want to preserve the original dialog box definition table since does not modify the original array argument. If you cancel the dialog box, or if a dialog box error occurs, returns FALSE instead of an array. 

Related Functions

ALERT   Displays a dialog box and a message

INPUT   Displays a dialog box for user input

DIRECTORY

Sets the current drive and directory or folder to the specified path and returns the name of the new directory or folder as text. Use DIRECTORY to get the name of the current directory or folder for use with the OPEN and functions or to specify a directory or folder from which to return a list of files with the FILES function.

Syntax

DIRECTORY(path_text)

Path_text    is the drive and directory or folder you want to change to. 

•   If path_text is not specified, DIRECTORY returns the name of the current directory or folder as text.

•   If path_text does not specify a drive, the current drive is assumed. 

Examples

In Microsoft Excel for Windows, the following macro formula sets the directory to \EXCEL\MODELS on the current drive and returns the value "drive:\EXCEL\MODELS":

DIRECTORY("\EXCEL\MODELS")

The following macro formula sets the current drive to E and sets the directory to \EXCEL\MODELS on E. It returns the value "E:\EXCEL\MODELS":

DIRECTORY("E:\EXCEL\MODELS")

In Microsoft Excel for the Macintosh, the following macro formula sets the folder to HARD DISK: APPS:EXCEL:FINANCIALS and returns the value "HARD DISK:APPS:EXCEL:FINANCIALS":

DIRECTORY("HARD DISK:APPS:EXCEL:FINANCIALS")

Related Function

FILES   Returns the filenames in the specified directory or folder

DISABLE.INPUT

Blocks all input from the keyboard and mouse to Microsoft Excel (except input to displayed dialog boxes). Use DISABLE.INPUT to prevent input from the user or from other applications.

Syntax

DISABLE.INPUT(logical)

Logical    is a logical value specifying whether input is currently disabled. If logical is TRUE, input is disabled; if FALSE, input is reenabled.

Remarks

Disabling input can be useful if you are using dynamic data exchange (DDE) to communicate with Microsoft Excel from another application.

Important   Be sure to end any macro that uses DISABLE.INPUT(TRUE) with a

DISABLE.INPUT(FALSE) function. If you do not include DISABLE.INPUT(FALSE) to allow nondialog-box input, you will not be able to take any actions on your computer after the macro has finished.

Related Functions

   Disables macro interruption

   Turns Data Entry mode on and off

WORKSPACE   Changes workspace settings

DISPLAY

Controls whether the screen displays formulas, gridlines, row and column headings, and other screen attributes. There are two syntax forms of this function. Use syntax 1 to control screen display. Use syntax 2 to control the display of the Info Window.

Syntax 1   Controls screen display

Syntax 2   Controls display of Info Window

DISPLAY SYNTAX 1

Controls whether the screen displays formulas, gridlines, row and column headings, and other screen attributes. There are two syntax forms of this function. Use syntax 1 to control screen display. This function is provided for compatibility with Microsoft Excel version 4.0. To control screen display in Microsoft Excel version 5.0 or later, see .

Arguments for this syntax form correspond to options and check boxes in the Display Options dialog box in Microsoft Excel version 4.0. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, no action is taken.

Syntax

DISPLAY(formulas, gridlines, headings, zeros, color_num, reserved, outline, page_breaks, object_num)

DISPLAY?(formulas, gridlines, headings, zeros, color_num, reserved, outline, page_breaks, object_num)

Formulas    corresponds to the Formulas check box. The default is FALSE on worksheets and TRUE on macro sheets.

Gridlines    corresponds to the Gridlines check box. The default is TRUE.

Headings    corresponds to the Row & Column Headings check box. The default is TRUE.

Zeros    corresponds to the Zero Values check box. The default is TRUE.

Color_num    is a number from 0 to 56 corresponding to the gridline and heading colors in the Display Options dialog box; 0 corresponds to automatic color and is the default value.

Reserved    is reserved for certain international versions of Microsoft Excel.

Outline    corresponds to the Outline Symbols check box. The default is TRUE.

Page_breaks    corresponds to the Automatic Page Breaks check box. The default is FALSE.

Object_num    is a number from 1 to 3 corresponding to the display options in the Object box.

Object_num

 

Corresponds to

1         or omitted          Show All

2         Show Placeholders

3         Hide

Related Functions

   Controls display

WORKSPACE   Changes workspace settings

ZOOM   Enlarges or reduces a sheet in the active window

Syntax 2   Controls display of Info Window

DISPLAY SYNTAX 2

Equivalent to clicking the commands on the Info menu when the Info Window is active. Controls which commands on the Info Window are in effect. There are two syntax forms of this function. Use syntax 2 to control the display of the Info Window. The Info Window must be active to use this form of DISPLAY. This function is included for compatibility with Microsoft Excel 95 or earlier; the Info Window is not available in Microsoft Excel 97 or later.

Arguments in this syntax form correspond to commands on the Info menu with the same names.

For these arguments: 

•    If the argument is TRUE, Microsoft Excel displays the corresponding Info item.

•    If the argument is FALSE, Microsoft Excel does not display the corresponding Info item.

•    If the argument is omitted, the status of the item is unchanged.

Syntax

For controlling Info Window display

DISPLAY(cell, formula, value, format, protection, names, precedents, dependents, note)

Cell    is a logical value that corresponds to the Cell command and controls the display of cell information in the Info Window. If TRUE, cell information will be displayed; if FALSE, cell information will not be displayed.

Formula    is a logical value that corresponds to the Formula command and controls the display of formula information in the Info Window. If TRUE, formula information will be displayed; if FALSE, formula information will not be displayed.

Value    is a logical value that corresponds to the Value command and controls the display of value information in the Info Window. If TRUE, value information will be displayed; if FALSE, value information will not be displayed.

Format    is a logical value that corresponds to the Format command and controls the display of format information in the Info Window. If TRUE, format information will be displayed; if FALSE, format information will not be displayed.

Protection    is a logical value that corresponds to the Protection command and controls the display of protection information in the Info Window. If TRUE, protection information will be displayed; if FALSE, protection information will not be displayed.

Names    is a logical value that corresponds to the Names command and controls the display of name information in the Info Window. If TRUE, name information will be displayed; if FALSE, name information will not be displayed.

Precedents    is a number from 1 to 3 that specifies which precedents to list, according to the following table.

Dependents    is a number from 1 to 3 that specifies which dependents to list, according to the following table.

Precedents or dependents

 

List

0                    None

1                    Direct only

2                    All levels

Note    is a logical value that corresponds to the Note command and controls the display of note information in the Info Window. If TRUE, note information will be displayed; if FALSE, note information will not be displayed.

Related Functions

   Controls the display of the Info Window

ZOOM   Enlarges or reduces a sheet in the active window

Syntax 1   Controls screen display

DOCUMENTS

Returns, as a horizontal array in text form, the names of the specified open workbooks. Use DOCUMENTS to retrieve the names of open workbooks to use in other functions that manipulate open workbooks.

Syntax

DOCUMENTS(type_num, match_text)

Type_num is a number specifying whether to include add-in workbooks in the array of workbooks, according to the following table.

Type_num

 

Returns

1          or omitted Names of all open workbooks except add-in workbooks

2          Names of add-in workbooks only

3          Names of all open workbooks

Match_text specifies the workbooks whose names you want returned and can include wildcard characters. If match_text is omitted, DOCUMENTS returns the names of all open workbooks.

Remarks 

•    Use the INDEX function to select individual workbook names from the array to use in other functions that take workbook names as arguments.

•    Use COLUMNS to count the number of entries in the horizontal array.

•    Use TRANSPOSE to change a horizontal array to a vertical one.

•    Since the DOCUMENTS function only returns actual workbook names, it ignores any changes made by the WINDOW.TITLE function. 

Examples

In Microsoft Excel for Windows, if your workspace contains windows named , CHART1, :1, :2, and , then:

DOCUMENTS (1) equals the four-cell array {"", "",

"", "CHART1"}

("Document_array", DOCUMENTS()) defines the name, Document_array, as {"", "", "", "CHART1"}

In Microsoft Excel for the Macintosh, if your workspace contains windows named BUDGET CHART1, ACTUALS, ACTUALS:2, and BOOK then:

DOCUMENTS(1) equals the four-cell array {"ACTUALS", "BOOK", "BUDGET", "CHART1"}

Related Functions

FILES   Returns the filenames in the specified directory or folder

GET.DOCUMENT   Returns information about a workbook

GET.WINDOW   Returns information about a window

WINDOWS   Returns the names of all open windows

DUPLICATE

Duplicates the selected object. If an object is not selected, returns the #VALUE! error value and interrupts the macro.

Syntax

DUPLICATE( )

Related Functions

COPY   Copies and pastes data or objects

PASTE   Pastes cut or copied data

ECHO

Controls screen updating while a macro is running. If a large macro uses many commands that update the screen, use ECHO to make the macro run faster.

Syntax

ECHO(logical)

Logical    is a logical value specifying whether screen updating is on or off. 

•   If logical is TRUE, Microsoft Excel selects screen updating.

•   If logical is FALSE, Microsoft Excel clears screen updating.

•   If logical is omitted, Microsoft Excel changes the current screen update condition. 

Remarks 

•   Screen updating is always turned back on when a macro ends.

•   You can use GET.WORKSPACE to determine whether screen updating is on or off. 

Related Function

GET.WORKSPACE   Returns information about the workspace

EDITBOX.PROPERTIES

Sets the properties of an edit box on a dialog sheet.

Syntax

EDITBOX.PROPERTIES(validation_num, multiline_logical, vscroll_logical, password_logical)

EDITBOX.PROPERTIES?(validation_num, multiline_logical, vscroll_logical, password_logical)

Validation_num    is the validation applied to the edit box when the dialog is dismissed. If the edit box contains a value other than the type specified (or validation), an error is returned.

Validation_num

 

Type

1            Text

2            Integer

3            Number (allows floating point)

4            Reference

5            Formula

Multiline_logical    is a logical value specifying whether word wrapping is allowed in the edit box control. If TRUE, word wrapping is allowed. If FALSE, word wrapping is not allowed

Vscroll_logical    is a logical value specifying whether edit box displays a vertical scrollbar. If TRUE, a scrollbar is displayed. If FALSE, a scrollbar is not displayed.

Password_logical    is a logical value specifying whether edit box displays characters as the user types. If TRUE, asterisks (*) are displayed as the user types. If FALSE, no asterisks are displayed.

Related Functions

CHECKBOX.PROPERTIES   Sets various properties of check box and option box controls

PUSHBUTTON.PROPERTIES   Sets the properties of the push button control

EDIT.COLOR

Equivalent to clicking the Modify button on the Color tab, which appears when you click the Options command on the Tools menu. Defines the color for one of the 56 color palette boxes.

Use EDIT.COLOR if you want to use a color that is not currently on the palette and if your system hardware has more than 56 colors available. After you set the color for the color box, any items previously formatted with that color are displayed in the new color.

Syntax

EDIT.COLOR(color_num, red_value, green_value, blue_value)

EDIT.COLOR?(color_num, red_value, green_value, blue_value)

Color_num    is a number from 1 to 56 specifying one of the 56 color palette boxes for which you want to set the color.

Red_value, green_value, and blue_value    are numbers that specify how much red, green, and blue are in each color. 

•   In Microsoft Excel for Windows, red_value, green_value, and blue_value are numbers from 0 to 255.

•   In Microsoft Excel for the Macintosh, red_value, green_value, and blue_value are also numbers from 0 to 255. However, the color editing dialog box displays numbers from 0 to 65, 535. Microsoft Excel automatically converts the numbers between the two ranges. This allows you to display similar colors in all operating environments without modifying your macros.

•   If red_value, green_value, and blue_value are all set to 255, the resulting color is white. If they are all set to zero, the resulting color is black.

•   If red_value, green_value, or blue_value is omitted, Microsoft Excel assumes it to be the appropriate value for that color_num. 

Remarks 

•   Your system hardware determines the number of unique colors that you can choose from and the number of colors that can be displayed on the screen at the same time.

•   EDIT.COLOR does not use hue, saturation, or brightness values. If you are using the macro recorder and set the color of a color palette box using hue, saturation, and luminance, Microsoft Excel records the corresponding red, green, and blue values instead.

•   The dialog-box form of this function, EDIT.COLOR?(color_num), displays your system's color editing dialog box. The default red_value, green_value, and blue_value are determined by the current settings for the color_num you specify. Color_num is a required argument for the dialog-box form of this function. 

Related Function

COLOR.PALETTE   Copies a color palette from one workbook to another

EDIT.DELETE

Equivalent to clicking the Delete command on the Edit menu. Removes the selected cells from the worksheet and shifts other cells to close up the space.

Syntax

EDIT.DELETE(shift_num)

EDIT.DELETE?(shift_num)

Shift_num    is a number from 1 to 4 specifying whether to shift cells left or up after deleting the current selection or else to delete the entire row or column.

Shift_num

 

Result

1        Shifts cells left

2        Shifts cells up

3        Deletes entire row

4        Deletes entire column

•   If shift_num is omitted and if one cell or a horizontal range is selected, EDIT.DELETE shifts cells up.

•   If shift_num is omitted and a vertical range is selected, EDIT.DELETE shifts cells left. 

Related Function

CLEAR   Clears specified information from the selected cells or chart

EDITION.OPTIONS

Sets options in, or performs actions on, the specified publisher or subscriber. In Microsoft Excel for Windows, EDITION.OPTIONS also allows you to cancel a publisher or subscriber created in Microsoft Excel for the Macintosh.

Syntax

EDITION.OPTIONS(edition_type, edition_name, reference, option, appearance, size, formats)

Edition_type    is the number 1 or 2 specifying the type of edition.

Edition_type

 

Type of edition

1          Publisher

2          Subscriber

Edition_name    is the name of the edition you want to change the edition options for or to perform actions on. If edition_name is omitted, reference is required.

Reference    specifies the range (given in text form as a name or an R1C1-style reference) occupied by the publisher or subscriber. 

•   Reference is required if you have more than one publisher or subscriber of edition_name on the active workbook. Use reference to specify the location of the publisher or subscriber for which you want to set options.

•   If edition_type is 1 and the publisher is an embedded chart, or if edition_type is 2 and the subscriber is a picture, reference is the object identifier as displayed in the reference area.

•   If reference is omitted, edition_name is required. 

Option    is a number from 1 to 6 specifying the edition option you want to set or the action you want to take, according to the following two tables. Options 2 to 6 are only available if you are using Microsoft Excel for the Macintosh with system software version 7.0 or later.

If a publisher is specified, then option applies as follows.

Option

 

Action

1       Cancels the publisher

2       Sends the edition now

3       Selects the range or object published to the specified edition

4       Automatically updates the edition when the file is saved

5       Updates the edition on request only

6       Changes the edition file as specified by appearance, size, and formats

If a subscriber is specified, then option applies as follows.

Option

 

Action

1        Cancels the subscriber

2        Gets the latest edition

3        Opens the publisher workbook

4        Automatically updates when new data is available

5        Update on request only

The following three arguments are available only when option is 6.

Appearance    specifies whether the selection is published as shown on screen or as shown when printed. The default value for appearance is 1 if the selection is a sheet or macro sheet and 2 if the selection is a chart.

Appearance

 

Selection is published

1           As shown on screen

2           As shown when printed

Size    specifies the size of a published chart. Size is only available if a chart is to be published.

Size

 

Chart size is published

1          or omitted As shown on screen

2          As shown when printed

Formats    is a number specifying the format of the file.

Formats

 

File format

1          or omitted PICT

2          BIFF

4                    RTF

8                     VALU

You can also use the sum of the allowable file formats. For example, a value of 6 specifies BIFF and RTF.

Example

The following macro formula opens the workbook (and application) that published the edition named Monthly Totals:

EDITION.OPTIONS(2, "Monthly Totals", , 3)

Related Functions

CREATE.PUBLISHER   Creates a publisher from the selection

   Returns information about a link

   Inserts contents of an edition into the active workbook

EDIT.OBJECT

Equivalent to clicking the Edit command on the (selected object) Object submenu of the Edit menu. Starts the application associated with the selected object and makes the object available for editing or other actions.

Syntax

EDIT.OBJECT(verb_num)

Verb_num    is a number specifying which verb to use while working with the object, that is, what you want to do with the object. 

•   The available verbs are determined by the object's source application. 1 often specifies "edit, " and 2 often specifies "play" (for sound, animation, and so on). For more information, consult the documentation for the object's application to see how it supports object linking and embedding (OLE).

•   If the object does not support multiple verbs, verb_num is ignored.

•   If verb_num is omitted, it is assumed to be 1. 

Remarks

Your macro pauses while you're editing the object and resumes when you return to Microsoft Excel.

Related Function

INSERT.OBJECT   Creates an object of a specified type

EDIT.REPEAT

Equivalent to clicking the Repeat command on the Edit menu. Repeats certain actions and commands. EDIT.REPEAT is available in the same situations as the Repeat command.

Syntax

EDIT.REPEAT( )

EDIT.SERIES

Equivalent to clicking the Edit Series command on the Chart menu in Microsoft Excel version

4.0. Creates or changes chart series by adding a new SERIES formula or modifying an existing SERIES formula in the topmost chart type. Chart types are displayed in the following order from top to bottom: XY (Scatter), Line, Column, Bar, Area.

Syntax

EDIT.SERIES(series_num, name_ref, x_ref, y_ref, z_ref, plot_order)

EDIT.SERIES?(series_num, name_ref, x_ref, y_ref, z_ref, plot_order)

Series_num    is the number of the series you want to change. If series_num is 0 or omitted, Microsoft Excel creates a new data series.

Name_ref    is the name of the data series. It can be an external reference to a single cell, a name defined as a single cell, or a name defined as a sequence of characters. Name_ref can also be text (for example, "Projected Sales").

X_ref    is an external reference to the name of the sheet and the cells that contain one of the following sets of data: 

•   Category labels for all charts except xy (scatter) charts

•   X-coordinate data for xy (scatter) charts

Y_ref    is an external reference to the name of the sheet and the cells that contain values (or y-coordinate data in xy (scatter) charts) for all 2-D charts. Y_ref is required in 2-D charts but does not apply to 3-D charts.

Z_ref    is an external reference to the name of the sheet and the cells that contain values for all 3-D charts. Z_ref is required in 3-D charts but does not apply to 2-D charts.

Plot_order    is a number specifying whether the data series is plotted first, second, and so on, in the chart type. 

•   If you assign a plot_order to a series, Microsoft Excel plots that series in the order you specify, and the series that previously had that plot order (and any series following it) has its plot order increased by one.

•   If you add a series to a chart with an overlay, the number of series in the main chart does not change, so if the series is added to the main chart, then the series that was plotted last in the main chart will be plotted first in the overlay chart. To change which series is plotted first in the overlay chart, use the (chart type) Group command from the Format menu, and then select the Series Order

tab in the Format (chart type) Group dialog box. You can also use the FORMAT.OVERLAY function.

•   If you omit plot_order when you add a new series, then Microsoft Excel plots that series last and assigns it the correct plot_order value.

•   The maximum value for plot_order is 255.

Remarks

To change where a series is plotted within a chart, you can change the chart type, using the FORMAT.CHART function, or the plot order. Plot order affects where the series appears within the chart type only.

X_ref, y_ref, and z_ref can be arrays or references to a nonadjacent selection, although they cannot be names that refer to a nonadjacent selection. If you specify a nonadjacent selection for any of these arguments, make sure to enclose the reference to the selection in parentheses so that Microsoft Excel does not treat the components of the references as separate arguments.

Tip   To delete a data series, use the SELECT("Sn") macro function, where n is the series number, followed by the FORMULA("") macro function. You can also use the CLEAR function instead of FORMULA. Related Function

FORMAT.CHART

Displays the Button Editor dialog box, which you use to change the appearance of a button on a toolbar.

Syntax

(bar_id, position)

Bar_id    is the number of the toolbar containing the button you want to edit. For a list of toolbar numbers, see . Use the GET.TOOLBAR function to return the information about a toolbar.

Position    is the position on the toolbar of the button you want to edit. Buttons are numbered from the left starting at 1. Gaps between buttons are counted as positions.

Related Functions

   Adds a button to a toolbar

GET.TOOLBAR   Returns information about a toolbar

ELSE

Used with IF, , and to control which functions are carried out in a macro. ELSE signals the beginning of a group of formulas in a macro sheet that will be carried out if the results of all preceding statements and the preceding IF statement are FALSE. Use ELSE with IF, , and when you want to perform multiple actions based on a condition. This method is preferable to using GOTO because it makes your macros more structured.

Syntax

ELSE( )

Remarks

ELSE must be entered in a cell by itself. In other words, the cell can contain only "=ELSE()".

For more information about ELSE, , , and IF, and for examples of these functions, see form 2 of the IF function.

Related Functions

   Specifies an action to take if an IF or another function returns FALSE

   Ends a group of macro functions started with an IF statement

IF   Specifies an action to take if a logical test is TRUE

Used with IF, ELSE, and to control which functions are carried out in a macro. signals the beginning of a group of formulas in a macro sheet that will be carried out if the preceding IF or function returns FALSE and if logical_test is TRUE. Use with IF, ELSE, and when you want to perform multiple actions based on a condition. This method is preferable to using GOTO because it makes your macros more structured.

Syntax

(logical_test)

Logical_test    is a logical value that uses to determine what functions to carry out next—that is, where to branch. 

•   If logical_test is TRUE, Microsoft Excel carries out the functions between the function and the next , ELSE, or function.

•   If logical_test is FALSE, Microsoft Excel immediately branches to the next , ELSE, or function. 

Remarks 

•   must be entered in a cell by itself.

•   Logical_test will always be evaluated, even if the section is not reached (due to a previous IF or logical_test evaluating to TRUE). For this reason, you should not use formulas that carry out actions for logical_test. If you need to base the condition on the return value of a formula that carries out an action, use the form "ELSE, IF(logical_test), and " in place of "(logical_test)." 

For more information about ELSE, , , and IF, and for examples of these functions, see form 2 of the IF function.

Related Functions

ELSE   Specifies an action to take if an IF function returns FALSE

   Ends a group of macro functions started with an IF statement

IF   Specifies an action to take if a logical test is TRUE

EMBED

Displayed in the formula bar when an embedded object is selected. EMBED cannot be entered on a sheet or used in a macro.

Syntax

EMBED(object_class, item)

Object_class    is the name of the application and document type that created the embedded object. For example, the object_class arguments used when Microsoft Excel sheets are embedded in other applications are "Excel.sheet.5" and "Excel.Chart.5".

Item    is the area selected to copy, and determines the view on the embedded document. When item is empty text (""), EMBED creates a view on the entire document.

Remarks

If you delete the EMBED formula, the embedded object remains on the sheet as a graphic, and the link to the creating application is deleted. Double-clicking the object no longer starts the creating application.

ENABLE.COMMAND

Enables or disables a custom command or menu. Disabled commands appear dimmed and can't be chosen. Use ENABLE.COMMAND to control which commands the user can click in a menu bar.

Syntax

ENABLE.COMMAND(bar_num, menu, command, enable, subcommand)

Bar_num    is the menu bar in which a command resides. Bar_num can be the number of a built-in menu bar or the number returned by a previously run function. See ADD.COMMAND for a list of the built-in menu bar numbers.

Menu    is the menu on which the command resides. Menu can be either the name of a menu as text or the number of a menu. Menus are numbered starting with 1 from the left of the screen.

Command    is the command you want to enable or disable. Command can be either the name of the command as text or the number of the command. The top command on a menu is command 1. If command is 0, ENABLE.COMMAND enables or disables the entire menu.

Enable    is a logical value specifying whether the command should be enabled or disabled. If enable is TRUE, Microsoft Excel enables the command; if FALSE, it disables the command.

Subcommand    is the name of the command on a submenu that you want to enable. If you use subcommand, you must use command as the name of the submenu. Use subcommand 0 to enable an entire submenu.

Remarks 

•    You cannot disable built-in commands. If the specified command is a built-in command or does not exist, ENABLE.COMMAND returns the #VALUE! error value and interrupts the macro.

•    You can hide any shortcut menu from users by using ENABLE.COMMAND with command set to 0. 

Example

The following macro formula disables a custom command that had been added previously to the View menu on the worksheet and macro sheet menu bar:

ENABLE.COMMAND(10, "View", "Audit ", FALSE)

Related Functions

   Adds a menu bar

ADD.COMMAND   Adds a command to a menu

CHECK.COMMAND   Adds or deletes a check mark to or from a command

DELETE.COMMAND   Deletes a command from a menu

RENAME.COMMAND   Changes the name of a command or menu

ENABLE.OBJECT

Enables or disables a drawing object or the selected drawing object. A disabled object will not run any macro events assigned to it, and the controls will be grayed out.

Syntax

ENABLE.OBJECT(object_id_text, enable_logical)

Object_id_text    is the name of the object(s) as text. If omitted, the selected object(s) are assumed.

Enable_logical    is a logical value that specifies whether the object is to be enabled. If TRUE, the object is enabled. If FALSE, the object is disabled.

Examples

ENABLE.OBJECT("Button 2",FALSE) disables the button with object name Button 2 on the dialog box.

Related Function

SET.CONTROL.VALUE   Changes the value of the active control

ENABLE.TIPWIZARD

This function should not be used. The TipWizard has been removed from Microsoft Excel.

Enables or disables a button on a toolbar. An enabled button can be accessed by the user. Disabled buttons may still be visible but cannot be accessed. Use to control which buttons the user can click in a particular situation.

Syntax

(bar_id, position, enable)

Bar_id    is the number or name of a toolbar on which the button resides. For detailed information about bar_id, see .

Position    specifies the position of the button on the toolbar. Position starts with 1 at the left side (if horizontal) or from the top (if vertical).

Enable    specifies whether the button can be accessed. If enable is TRUE or omitted, the user can access the button; if FALSE, the user cannot access it.

Remarks

Microsoft Excel sounds a tone if you click a disabled button.

Example

The following macro formula enables the fourth button in Toolbar1:

("Toolbar1", 4, TRUE)

Related Function

   Returns information about a button or buttons on a toolbar

Ends a block of functions associated with the preceding IF function. You must include one and only one function for each macro-sheets-only syntax form (syntax 2) of the IF function in a macro. Syntax 1 of the IF function, which can be used on both worksheets and macro sheets, does not require an function. Use with IF, ELSE, and when you want to perform multiple actions based on a condition. This method is preferable to using GOTO because it makes your macros more structured.

Syntax

( )

Remarks 

•    If you accidentally omit an function, your macro will end with an error at the cell containing the first IF function that does not have a corresponding function.

•    must be entered in a cell by itself.

•    For more information about ELSE, , , and IF, and for examples of these functions, see form 2 of the IF function. 

Related Functions

ELSE   Specifies an action to take if an IF function returns FALSE

   Specifies an action to take if an IF or another function returns FALSE

IF   Specifies an action to take if a logical test is TRUE

Turns on Data Entry mode and allows you to select and to enter data into the unlocked cells in the current selection only (the data entry area). Use when you want to enter data only in a specific part of your sheet. You can then use that part of the sheet as a simple data form.

Syntax

(logical)

Logical    is a logical value that turns Data Entry mode on or off. 

•   If logical is TRUE, Data Entry mode is turned on; if FALSE, Data Entry mode is turned off and data entry, cell movement, and cell selection return to normal. If logical is omitted, toggles Data Entry mode.

•   Logical can also be the number 2. This setting turns on Data Entry mode and prevents the ESC key from turning it off.

•   Logical can also be a reference. Using a reference for this argument turns on Data Entry mode for the supplied reference. 

Remarks 

•   In Data Entry mode, you can move the active cell and select cell ranges only in the data entry area. The arrow keys and the TAB and SHIFT+TAB keys move from one unlocked cell to the next. The HOME and END keys move to the first and last cell in the data entry area, respectively. You cannot select entire rows or columns, and clicking a cell outside the data entry area does not select it.

•   The only commands available in Data Entry mode are commands normally available to protected workbooks.

•   To turn off Data Entry mode, press ESC (unless logical is 2), activate another sheet in the active workbook window, or use another function. If you use another function, you will usually design your macros in one of two ways: 

•   The macro turns on Data Entry mode, pauses while you enter data, resumes, and then turns off Data Entry mode.

•   The macro turns on Data Entry mode and ends. After entering data, another macro turns off Data Entry mode; this latter macro could be assigned to a "Finished" button, for example.

With either method, you can use Microsoft Excel's ON functions to resume or run other macros based on an event, such as pressing the CONTROL+D keys. 

Tips 

•   Normally you use Data Entry mode to enter data, but you can also prevent someone from entering data or moving the active cell by locking all the cells in the current selection before turning on Data Entry mode. This is useful if you want a user to view a range of cells but not change it or move the active cell. Similarly, if you unlock certain cells, you can restrict the user's movement to the Data Entry area only.

•   To prevent someone from activating another workbook, which would turn off Data Entry mode, use the ON.WINDOW function or an Auto_Deactivate macro.

Related Functions

DISABLE.INPUT   Blocks all input to Microsoft Excel

FORMULA   Enters values into a cell or range or onto a chart

ERROR

Specifies what action to take if an error is encountered while a macro is running. Use ERROR to control whether Microsoft Excel error messages are displayed, or to run your own macro when an error is encountered.

Syntax

ERROR(enable_logical, macro_ref)

Enable_logical    is a logical value or number that selects or clears error-checking. 

•   If enable_logical is FALSE or 0, all error-checking is cleared. If error-checking is cleared and an error is encountered while a macro is running, Microsoft Excel ignores it and continues. Error-checking is selected again by an ERROR(TRUE) statement, or when the macro stops running.

•   If enable_logical is TRUE or 1, you can either select normal error-checking (by omitting the other argument) or specify a macro to run when an error is encountered by using the macro_ref argument. When normal error-checking is active, the Macro Error dialog box is displayed when an error is encountered. You can halt the macro, start single-stepping through the macro, continue running the macro normally, or go to the macro cell where the error occurred.

•   If enable_logical is 2 and macro_ref is omitted, error-checking is normal except that if the user clicks the Cancel button in an alert message, ERROR returns FALSE and the macro is not interrupted.

•   If enable_logical is 2 and macro_ref is given, the macro goes to that macro_ref when an error is encountered. If the user clicks the Cancel button in an alert message, FALSE is returned and the macro is not interrupted. 

Macro_ref    specifies a macro to run if enable_logical is TRUE, 1, or 2 and an error is encountered. It can be either the name of the macro or a cell reference. If enable_logical is FALSE or 0, macro_ref is ignored.

Important   Both ERROR(FALSE) and ERROR(TRUE, macro_ref ) keep Microsoft Excel from displaying any messages at all, including the message asking whether to save changes when you close an unsaved workbook. If you want alert messages but not error messages to be displayed, use ERROR(2, macro_ref ).

Remarks

You can use GET.WORKSPACE to determine whether error-checking is on or off. Examples

ERROR(FALSE) clears error-checking.

ERROR(TRUE, Recover) selects error-checking and runs the macro named Recover when an error is encountered.

The following macro runs the macro ForceMenus if an error occurs in the current macro:

=ERROR(TRUE, ForceMenus)

Related Functions

   Disables macro interruption

LAST.ERROR   Returns the reference of the cell where the last error occurred

   Runs a macro when a specified key is pressed

ERRORBAR.X, ERRORBAR.Y

Adds error bars to the selected series in a chart. ERRORBAR.X adds bars showing the error factor for the X (category) axis and works for XY (scatter) charts only. ERRORBAR.Y adds bars showing the error factor for the Y (value) axis for all charts.

Syntax

ERRORBAR.X(include, type, amount, minus)

ERRORBAR.Y(include, type, amount, minus)

Include    specifies the type of error value to include:

Include

 

Type of error value

1          or omitted Plus and minus

2          Plus

3          Minus

4          None

Type    specifies the type of error bars to display:

Type

 

Type of error displayed

1          or omitted Fixed amount

2          Percent

3          Multiplying factor standard deviation (default value is 1)

4          Standard error

5          Custom

Amount    is the range of error values to display. This argument depends on the value of type:

If type is

 

then amount

1          or omitted Can be any number greater than 0

2          Can be any number greater than 0

3          Can be any number greater than or 0

4          Not required

5          Is the positive amount for custom error bars

Minus    is the negative amount for custom error bars. Applicable only if type is 5.

Remarks

For the amount argument, standard deviation(s) can be calculated using this equation:

The standard deviation is multiplied by the value specified by amount and the error bars are placed this distance from the arithmetic mean. Therefore, these error bars are plotted along the arithmetic mean, not attached to data series.

Microsoft Excel calculates the standard error using the following equation:

Both the standard deviation and standard error functions use the following variables:

Variable

 

Equals

s                Series number

i                 Point number in series s

m       Number of series for point y in chart

n         Number of points in each series

Yi                Data value of series s and the ith point

Ny              Total number of data values in all series

M                Arithmetic mean

EVALUATE

Evaluates a formula or expression that is in the form of text and returns the result. To run a macro or subroutine, use the RUN function.

Syntax

EVALUATE(formula_text)

Formula_text    is the expression in the form of text that you want to evaluate.

Remarks

Using EVALUATE is similar to selecting an expression within a formula in the formula bar and pressing the Recalculate key (F9 in Microsoft Excel for Windows and COMMAND+= in Microsoft Excel for the Macintosh). EVALUATE replaces an expression with a value.

Example

Suppose you want to know the value of a cell named LabResult1, LabResult2, or LabResult3, where the 1, 2, or 3 is specified by the name TrialNum whose value may change as the macro runs. You can use the following formula to calculate the value:

EVALUATE("LabResult"&TrialNum)

Related Function

RUN   Runs a macro

EXEC

Starts a separate program. Use EXEC to start other programs with which you want to communicate. Use EXEC with Microsoft Excel's other DDE functions (INITIATE, EXECUTE, and ) to create a channel to another program and to send keystrokes and commands to the program. ( is available only in Microsoft Excel for Windows.)

Syntax 1 is for Microsoft Excel for Windows. Syntax 2 is for Microsoft Excel for the Macintosh.

Syntax 1

For Microsoft Excel for Windows

EXEC(program_text, window_num)

Syntax 2

For Microsoft Excel for the Macintosh

EXEC(program_text, , background, preferred_size_only)

Important   Microsoft Excel for the Macintosh requires system software version 7.0 or later for the last two arguments of this function.

Program_text    is the name, as a text string, of any executable file or, in Microsoft Excel for Windows, any data file that is associated with an executable file. 

•   Use paths when the file or program to be started is not in the current directory or folder.

•   In Microsoft Excel for Windows, program_text can include any arguments and switches that are accepted by the program to be started. Also, if program_text is

the name of a file associated with a specific installed program, EXEC starts the program and loads the specified file. 

Note   In Microsoft Excel for the Macintosh, you must use an extra comma after the program_text argument. This skips the window_num argument that does not apply to the Macintosh.

Window_num    is a number from 1 to 3 that specifies how the window containing the program should appear. Window_num is only available for use with Microsoft Excel for Windows. The window_num argument is allowed on the Macintosh, but it is ignored.

Window_num

 

Window appears

1          Normal size

2          or omitted        Minimized size

3          Maximized size

Background    is a logical value that determines whether the program specified by program_text is opened as the active program or in the background, leaving Microsoft Excel as the active program. If background is TRUE, the program is started in the background; if FALSE or omitted, the program is started in the foreground. Background is only available for use with Microsoft Excel for the Macintosh and system software version 7.0 or later.

Preferred_size_only    is a logical value that determines the amount of memory allocated to the program. If preferred_size_only is TRUE, the program is opened with its preferred memory allocation; if FALSE or omitted, it opens with the available memory if greater than its minimum requirement. Preferred_size_only is only available for use with Microsoft Excel for the Macintosh and system software version 7.0 or later. For information about changing the preferred memory size, see your Macintosh documentation.

Remarks

In Microsoft Excel for Windows and in Microsoft Excel for the Macintosh with system software version 7.0, if the EXEC function is successful, it returns the task ID number of the started program. The task ID number is a unique number that identifies a program. Use the task ID number in other macro functions, such as APP.ACTIVATE, to refer to the program. In Microsoft Excel for the Macintosh with system software version 6.0, if EXEC is successful, it returns TRUE. If EXEC is unsuccessful, it returns the #VALUE! error value.

Examples

In Microsoft Excel for Windows, the following macro formula starts the program . Use paths when the file or program to be started is not in the current directory:

EXEC("C:\WINDOWS\")

The following macro formula starts Microsoft Word for Windows and loads the document :

EXEC("C:\WINWORD\ C:\MYFILES\")

In Microsoft Excel for the Macintosh, the following macro formula starts Microsoft Word:

EXEC("HARD DISK:APPS:WORD")

Related Functions

APP.ACTIVATE   Switches to another application

EXECUTE   Carries out a command in another application

INITIATE   Opens a channel to another application

   Sends a key sequence to an application

TERMINATE   Closes a channel to another application

REQUEST   Requests an array of a specific type of information from an application with which you have a dynamic data exchange (DDE) link

POKE   Sends data to another application with which you have a dynamic data exchange (DDE) link

EXECUTE

Carries out commands in another program with which you have a dynamic data exchange

(DDE) link. Use with EXEC, INITIATE, and to run another program through Microsoft Excel. ( is available only in Microsoft Excel for Windows.)

Important   Microsoft Excel for the Macintosh requires system software version 7.0 or later for this function.

Syntax

EXECUTE(channel_num, execute_text)

Channel_num    is a number returned by a previously run INITIATE function. Channel_num refers to a channel through which Microsoft Excel communicates with another program.

Execute_text    is a text string representing commands you want to carry out in the program specified by channel_num. The form of execute_text depends on the program you are referring to. To include specific key sequences in execute_text, use the format described under key_text in the function.

If EXECUTE is not successful, it returns one of the following error values:

Value returned

 

Situation

 

#VALUE!

Channel_num is not a valid channel number.

 

 

#N/A

The program you are accessing is busy.

 

 

#DIV/0!

The program you are accessing does not respond after a certain length of time or you have pressed ESC to cancel.

 

 

#REF!

The keys specified in execute_text are refused by the application which you want to access.

 

             

Remarks

Commands sent to another program with EXECUTE will not work when a dialog box is displayed in the program. In Microsoft Excel for Windows, you can use to send commands that make selections in a dialog box.

Examples

The following macro formula sends the number 25 and a carriage return to the application identified by channel_num 14:

EXECUTE(14, "25~")

Related Functions

EXEC   Starts another application

INITIATE   Opens a channel to another application

POKE   Sends data to another application

REQUEST   Returns data from another application

   Sends a key sequence to an application

TERMINATE   Closes a channel to another application

EXPON

Predicts a value based on the forecast for the prior period, adjusted for the error in that prior forecast.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

EXPON(inprng, outrng, damp, stderrs, chart)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Damp    is the damping factor. If omitted, damp is 0.3.

Stderrs    is a logical value. If TRUE, standard error values are included in the output table. If FALSE, standard errors are not included.

Chart    is a logical value. If TRUE, EXPON generates a chart for the actual and forecast values. If FALSE, the chart is not generated.

Related Function

MOVEAVG   Returns values along a moving average trend

EXTEND.POLYGON

Adds vertices to a polygon. This function must immediately follow a CREATE.OBJECT function or another EXTEND.POLYGON function. Use multiple EXTEND.POLYGON functions to create arbitrarily complex polygons. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

EXTEND.POLYGON(array)

Array    is an array of values, or a reference to a range of cells containing values, that indicate the position of vertices in the polygon. The position is measured in points and is relative to the upper-left corner of the polygon's bounding rectangle. 

•   A vertex is a point. Each vertex is defined by a pair of coordinates in one row of array.

•   The polygon is defined by the array argument to the CREATE.OBJECT function and to all the immediately following EXTEND.POLYGON functions.

•   If the polygon contains many vertices, one array may not be sufficient to define it. If the number of elements in the formula exceeds 1024, you must include additional EXTEND.POLYGON functions. If you're recording a macro, Microsoft

Excel automatically records additional EXTEND.POLYGON functions as needed.

Related Functions

CREATE.OBJECT   Creates an object

FORMAT.SHAPE   Inserts, moves, or deletes vertices of the selected polygon

EXTRACT

Equivalent to choosing the Extract command from the Data menu in Microsoft Excel version 4.0. Finds database records that match the criteria defined in the criteria range and copies them into a separate extract range.

Syntax

EXTRACT(unique)

EXTRACT?(unique)

Unique    is a logical value corresponding to the Unique Records Only check box in the Extract dialog box. 

•   If unique is TRUE, Microsoft Excel selects the check box and excludes duplicate records from the extract list.

•   If unique is FALSE or omitted, Microsoft Excel clears the check box and extracts all records matching the criteria. 

Related Functions

   Finds records in a database

SET.CRITERIA   Defines the name Criteria for the selected range on the active sheet

SET.DATABASE   Defines the name Database for the selected range on the active sheet

SET.EXTRACT   Defines the name Extract for the selected range on the active sheet

FCLOSE

Closes the specified file.

Syntax

FCLOSE(file_num)

File_num    is the number of the file you want to close. File_num is returned by the FOPEN function that originally opened the file. If file_num is not a valid file number, FCLOSE halts the macro and returns the #VALUE! error value.

Examples

The following function closes the file identified by FileNumber:

FCLOSE(FileNumber)

Related Functions

CLOSE   Closes the active window

FILE.CLOSE   Closes the active workbook

FOPEN   Opens a file with the type of permission specified

FILE.CLOSE

Equivalent to clicking the Close command on the File menu. Closes the active workbook.

Syntax

FILE.CLOSE(save_logical, route_logical)

Save_logical    is a logical value specifying whether to save the file before closing it.

Save_logical

 

Result

 

TRUE

Saves the workbook

 

 

FALSE

Does not save the workbook

 

           

Omitted               If you've made changes to the workbook, displays a dialog box asking if you want to save the workbook

Route_logical    is a logical value that specifies whether to route the file after closing it. This argument is ignored if there is not a routing slip present.

Route_logical

 

Result

 

TRUE

Routes the file

 

 

FALSE

Does not route the file

 

           

Omitted   If you've specified recipients for routing, displays a dialog box asking if you want to save the file

Remarks

If you make any changes to the structure of a workbook, such as the name of sheets, their order, and so on, then a message will be displayed reminding you that there are unsaved changes, regardless of the save_logical value.

Note   When you use the FILE.CLOSE function, Microsoft Excel does not run any Auto_Close macros before closing the workbook.

Related Functions

CLOSE   Closes the active window

   Closes all unprotected windows

FCLOSE   Closes a text file

FILE.DELETE

Deletes a file from the disk. Although you will normally delete files manually, you can, for example, use FILE.DELETE in a macro to delete temporary files created by the macro.

Syntax

FILE.DELETE(file_text)

FILE.DELETE?(file_text)

File_text    is the name of the file to delete.

Remarks 

•    If Microsoft Excel can't find file_text, it displays a message saying that it cannot delete the file. To avoid this, include the entire path in file_text. See the following second and fifth examples. You can also use FILES to generate an array of filenames and then check if the file you want to delete is in the array.

•    If a file is open when you delete it, the file is removed from the disk but remains open in Microsoft Excel.

•    In the dialog-box form, FILE.DELETE?, you can use an asterisk (*) to represent any series of characters and a question mark (?) to represent any single character. See the following third and sixth examples. 

Examples

In Microsoft Excel for Windows, the following macro formula deletes a file called from the current directory:

FILE.DELETE("")

The following macro formula deletes a file called kept in the EXCEL\SALES subdirectory:

FILE.DELETE("C:\EXCEL\SALES\")

The following macro formula displays the Delete dialog box listing all documents whose extensions begin with the letters "XL":

FILE.DELETE?("*.XL?")

In Microsoft Excel for the Macintosh, the following macro formula deletes a file called CHART1 from the current folder:

FILE.DELETE("CHART1")

The following macro formula deletes a file called 1992 INFO kept in a series of nested folders:

FILE.DELETE("HARD DISK:EXCEL 5:SALES WORKSHEETS:1992 INFO")

The following macro formula displays the Delete dialog box listing all documents beginning with the word "Clients":

FILE.DELETE?("Clients*")

Related Functions

FILE.CLOSE   Closes the active workbook

FILES   Returns the filenames in the specified directory or folder

FILES

Returns a horizontal text array of the names of all files in the specified directory or folder. Use FILES to build a list of filenames upon which you want your macro to operate.

Syntax

FILES(directory_text)

Directory_text    specifies which directories or folders to return filenames from. 

•   Directory_text accepts an asterisk (*) to represent a series of characters and a question mark (?) to represent a single character in filenames.

•   If directory_text is not specified, FILES returns filenames from the current directory. 

Remarks

If you enter FILES in a single cell, only one filename is returned. You will normally use FILES with to assign the returned array to a name. See the last example below.

Tips   You can use COLUMNS to count the number of entries in the returned array. You can use TRANSPOSE to change a horizontal array to a vertical one.

Examples

In Microsoft Excel for Windows, the following macro formula returns the names of all files starting with the letter F in the current directory or folder:

FILES("F*.*")

When entered as an array formula in several cells, the following macro formula returns the filenames in the current directory to those cells. If the directory contains fewer files than can fit in the selected cells, the #N/A error value appears in the extra cells.

FILES()

In Microsoft Excel for Windows, the following macro formula returns all files starting with "SALE" and ending with the .XLS extension in the \EXCEL\CHARTS subdirectory:

FILES("C:\EXCEL\CHARTS\SALE*.XLS")

In Microsoft Excel for the Macintosh, the following macro formula returns all files starting with "SALE" in the nested CHART folder:

FILES("DISK:EXCEL:CHART:SALE*")

The following macro stores the names of the files in the current directory in the named array FileArray

("FileArray",FILES())

Related Functions

DOCUMENTS   Returns the names of the specified open workbooks

FILE.DELETE   Deletes a file

OPEN   Opens a workbook

   Defines a name as a value

Equivalent to copying cells or automatically filling a selection by dragging the fill selection handle with the mouse (the AutoFill feature).

Syntax

(destination_ref, copy_only)

Destination_ref    is the range of cells into which you want to fill data. The top, bottom, left, or right end of destination_ref must include all of the cells in the source reference (the current selection).

Copy_only    is a number specifying whether to copy cells or perform an AutoFill operation.

 

Value

 

Result

 

0 or omitted

Normal AutoFill

 

 

1 or TRUE

Copy cells

 

 

2

Copy formats

 

 

3

Fill values

 

 

4

Increment

 

 

5

Increment by day

 

 

6

Increment by weekday

 

 

7

Increment by month

 

 

8

Increment by year

 

 

9

Linear trend

 

 

10

Growth trend

 

         

Related Functions

COPY   Copies and pastes data or objects

DATA.SERIES   Fills a range of cells with a series of numbers or dates

, , FILL.RIGHT,

Equivalent to clicking the Down, Left, Right, and Up commands, respectively, on the Fill submenu of the Edit menu.

Syntax

( )

( )

FILL.RIGHT( )

( )

copies the contents and formats of the cells in the top row of a selection into the rest of the rows in the selection.

copies the contents and formats of the cells in the right column of a selection into the rest of the columns in the selection.

FILL.RIGHT copies the contents and formats of the cells in the left column of a selection into the rest of the columns in the selection.

copies the contents and formats of the cells in the bottom row of a selection into the rest of the rows in the selection.

Remarks

If you have a multiple selection, each range in the selection is filled separately with the contents of the source range.

Related Functions

COPY   Copies and pastes data or objects

DATA.SERIES   Fills a range of cells with a series of numbers or dates

   Copies cells or automatically fills a selection

   Enters a formula in the specified range

FILL.GROUP

Equivalent to choosing the Across Worksheets command from the Fill submenu on the Edit menu. Copies the contents of the active worksheet's selection to the same area on all other worksheets in the group. Use FILL.GROUP to fill a range of cells on all worksheets in a group at once.

Syntax

FILL.GROUP(type_num)

FILL.GROUP?(type_num)

Type_num    is a number from 1 to 3 that corresponds to the choices in the Fill Across Worksheets dialog box.

Type_num

 

Type of information filled

1        All

2        Contents

3        Formats

Related Functions

NEW   Creates a new workbook

WORKBOOK.SELECT   Selects one or more sheets in a workbook

FILTER

Filters lists of data one column at a time. Only one list can be filtered on any one sheet at a time.

Syntax

FILTER(field_num, criteria1, operation, criteria2)

FILTER?(field_num, criteria1, operation, criteria2)

Field_num    is the number of the field that you want to filter. Fields are numbered from left to right starting with 1.

Criteria1    is a text string specifying criteria for filtering a list, such as ">2". If you want to include all items in the list, omit this argument.

Operation    is a number that specifies how you want criteria2 used with criteria1:

Number

 

Operation Used

1        AND

2        OR

Criteria2    is a text string specifying criteria for filtering a list, such as ">2". If you include this argument, operation is required.

Remarks

If you omit all arguments, FILTER toggles the display of filter arrows.

Related Function

FILTER.ADVANCED   Lets you set options for filtering a list

FILTER.ADVANCED

Equivalent to choosing the Advanced Filter command from the Filter submenu on the Data menu. Lets you set options for filtering a list.

Syntax

FILTER.ADVANCED(operation, list_ref, criteria_ref, copy_ref, unique)

FILTER.ADVANCED?(operation, list_ref, criteria_ref, copy_ref, unique)

Operation    is a number specifying whether to copy the filter list to a new location. To filter a list without copying, use 1; to copy the filter list to a new location, use 2.

List_ref    specifies the location of the list to be filtered. If operation is 1, then list_ref must be on the active sheet.

Criteria_ref    is a reference to a range containing criteria for filtering the list. If omitted, uses "All" as the criteria.

Copy_ref    is a reference on the active sheet where you want the filtered list copied. Ignored if operation is 1.

Unique    is a logical value that specifies whether only unique records are displayed. To display only unique records, use TRUE. To display all records that match the criteria, use FALSE or omit this argument.

Related Function

FILTER   Filters lists of data one column at a time

Equivalent to choosing the Show All command from the Filter submenu on the Data menu. Displays all items in a filtered list.

Syntax

()

Equivalent to choosing the Find File command from the File menu in Microsoft Excel version 5.0. Lets you search for files based on criteria such as author or creation date.

Syntax

?( )

Remarks

This function has a dialog-box form only.

FONT

Equivalent to clicking the Font command on the Options menu in Microsoft Excel for the Macintosh version 1.5 or earlier. This function is included only for macro compatibility. Sets the font for the Normal style. Microsoft Excel now uses the FONT.PROPERTIES and DEFINE.STYLE functions. For more information, see FONT.PROPERTIES and DEFINE.STYLE.

Syntax

FONT(name_text, size_num)

FONT?(name_text, size_num)

Related Functions

DEFINE.STYLE   Creates or changes a cell style

FONT.PROPERTIES   Sets various font properties

FONT.PROPERTIES

Equivalent to choosing the Cells command from the Format menu. Applies a font and other attributes to the selection. Applies to cells, charts, and text boxes and buttons on worksheets and macro sheets.

Syntax

FONT.PROPERTIES(font, font_style, size, strikethrough, superscript, subscript, outline, shadow, underline, color, normal, background, start_char, char_count)

FONT.PROPERTIES?(font, font_style, size, strikethrough, superscript, subscript, outline, shadow, underline, color, normal, background, start_char, char_count)

Arguments correspond to check boxes or options in the Font tab on the Format Cells dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the format is not changed.

Font    is the name of the font as it appears on the Font tab. For example, Courier is a font name.

Font_style    is the name of the font style as it appears on the Font tab. For example, Bold Italic is a font style.

Size    is the font size, in points.

Strikethrough    corresponds to the Strikethrough check box.

Superscript    corresponds to the Superscript check box

Subscript    corresponds to the Subscript check box

Outline    corresponds to the Outline check box. Outline fonts are available in Microsoft Excel for the Macintosh. For macro compatibility, this argument is ignored by Microsoft Excel for Windows..

Shadow    corresponds to the Shadow check box. Shadow fonts are available in Microsoft Excel for the Macintosh. For macro compatibility, this argument is ignored by Microsoft Excel for Windows.

Note   For macro compatibility with Microsoft Excel for the Macintosh, the presence of the outline and shadow arguments do not prevent the macro from working on Microsoft Excel for Windows, nor does their absence prevent it from working on the Macintosh.

Underline    corresponds to the Underline Drop-down box.

Underline

 

Type applied

0         None

1         Single

2         Double

3         Single Accounting

4         Double Accounting

Color    is a number from 0 to 56 corresponding to the colors listed in the Color box; 0 corresponds to automatic color.

Normal    corresponds to the Normal Font check box. Applies the default font for your system

Background    is a number from 1 to 3 specifying which type of background to apply to text in a chart.

Background

 

Type of background applied

1         Automatic

2         Transparent

3         Opaque

Start_char    specifies the first character to be formatted. If start_char is omitted, it is assumed to be 1 (the first character in the cell or text box).

Char_count    specifies how many characters to format. If char_count is omitted, Microsoft Excel formats all characters in the cell or text box starting at start_char.

Remarks

Some extended TrueType styles do not have corresponding arguments to FONT.PROPERTIES. To access an extended TrueType font style, append the style name to the font name in the font argument. For example, the font Taipei can be formatted in an upside-down style by specifying "Taipei Upside-down" as the font argument. For more information about TrueType, see your Microsoft Windows documentation.

Related Functions

ALIGNMENT   Aligns or wraps text in cells

FORMAT.NUMBER   Applies a number format to the selection

   Formats a worksheet text box or a chart text item

FOPEN

Opens a file with the type of permission specified. Unlike OPEN, FOPEN does not load the file into memory and display it; instead, FOPEN establishes a channel with the file so that you can exchange information with it. If the file is opened successfully, FOPEN returns a file ID number. If it can't open the file, FOPEN returns the #N/A error value. Use the file ID number with other file functions (such as FREAD, FWRITE, and FSIZE) when you want to get information from or send information to the file.

Syntax

FOPEN(file_text, access_num)

File_text    is the name of the file you want to open.

Access_num    is a number from 1 to 3 specifying what type of permission to allow to the file:

Access_num

 

Type of permission

1          or omitted        Can read and write to the file (read/write permission)

2          Can read the file, but can't write to the file (read-only permission)

3          Creates a new file with read/write permission

•   If the file doesn't exist and access_num is 3, FOPEN creates a new file.

•   If the file does exist and access_num is 3, FOPEN replaces the contents of the file with any information you supply using the FWRITE or FWRITELN functions.

•   If the file doesn't exist and access_num is 1 or 2, FOPEN returns the #N/A error value. 

Remarks

Use FCLOSE to close a file after you finish using it.

Example

The following function opens a file identified as FileName using read-only permission:

FOPEN(FileName, 2)

Related Functions

FCLOSE   Closes a text file

FREAD   Reads characters from a text file

FWRITE   Writes characters to a text file

OPEN   Opens a workbook

FOR

Starts a FOR-NEXT loop. The instructions between FOR and NEXT are repeated until the loop counter reaches a specified value. Use FOR when you need to repeat instructions a specified number of times. Use when you need to repeat instructions over a range of cells.

Syntax

FOR(counter_text, start_num, end_num, step_num)

Counter_text    is the name of the loop counter in the form of text.

Start_num    is the value initially assigned to counter_text.

End_num    is the last value assigned to counter_text.

Step_num    is a value added to the loop counter after each iteration. If step_num is omitted, it is assumed to be 1.

Remarks 

                ?     Microsoft Excel follows these steps as it executes a FOR-NEXT loop:

Step

 

Action

1       Sets counter_text to the value start_num.

2       If counter_text is greater than end_num (or less than end_num if step_num is negative), the loop ends, and the macro continues with the function after the NEXT function. 

If counter_text is less than or equal to end_num (or greater than or equal to end_num if step_num is negative), the macro continues in the loop.

3       Carries out functions up to the following NEXT function. The NEXT function must be below the FOR function and in the same column.

4       Adds step_num to the loop counter.

5       Returns to the FOR function and proceeds as described in step 2.

                ?    You can interrupt a FOR-NEXT loop by using the BREAK function. 

Example

The following macro starts a FOR-NEXT loop that is executed once for every open window:

FOR("Counter", 1, COLUMNS(WINDOWS()))

Related Functions

BREAK   Interrupts a FOR-NEXT, -NEXT, or WHILE-NEXT loop

   Starts a -NEXT loop

NEXT   Ends a FOR-NEXT, -NEXT, or WHILE-NEXT loop

WHILE   Starts a WHILE-NEXT loop

Starts a -NEXT loop. This function is similar to FOR, except that the instructions between and NEXT are repeated over a range of cells, one cell at a time, and there is no loop counter.

Syntax

(ref_name, area_ref, skip_blanks)

Ref_name    is the name in the form of text that Microsoft Excel gives to the one cell in the range that is currently being operated on; ref_name refers to a new cell during each loop.

Area_ref    is the range of cells on which you want the -NEXT loop to operate and can be a multiple selection. If area_ref is omitted, it is assumed to be the current selection.

Skip_blanks    is a logical value specifying whether Microsoft Excel skips blank cells as it operates on the cells in area_ref.

Skip_blanks

 

Result

TRUE                     Skips blank cells in area_ref

FALSE or omitted Operates on all cells in area_ref

Remarks

operates on each cell in a row from left to right one area at a time before moving to the next row in the selection.

Example

The following macro starts a -NEXT loop and uses the name CurrentCell to refer to the cell in the range that is currently being operated on:

("CurrentCell", SELECTION(), TRUE)

Related Functions

BREAK   Interrupts a FOR-NEXT, -NEXT, or WHILE-NEXT loop

FOR   Starts a FOR-NEXT loop

NEXT   Ends a FOR-NEXT, -NEXT, or WHILE-NEXT loop

WHILE   Starts a WHILE-NEXT loop

Equivalent to clicking the AutoFormat command on the Format menu when a worksheet is active or clicking the AutoFormat button. Formats the selected range of cells from a built-in gallery of formats.

Syntax

(format_num, number, font, alignment, border, pattern, width)

?(format_num, number, font, alignment, border, pattern, width)

Format_num    is a number from 1 to 17 corresponding to the formats in the Table Format list box in the AutoFormat dialog box.

Format_num

 

Table Format

0           None

1           or omitted         Classic 1

2           Classic 2

3           Classic 3

4           Accounting 1

5           Accounting 2

6           Accounting 3

7           Colorful 1

8           Colorful 2

9           Colorful 3

10           List 1

11           List 2

12           List 3

13           3D Effects 1

14           3D Effects 2

15           Japan 1 (Far East versions of Microsoft Excel only) 16         Japan 2 (Far East versions of Microsoft Excel only)

17           Accounting 4

18           Simple

The following arguments are logical values corresponding to the Formats To Apply check boxes in the AutoFormat dialog box. If an argument is TRUE or omitted, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box.

Number    corresponds to the Number check box.

Font    corresponds to the Font check box.

Alignment    corresponds to the Alignment check box.

Border    corresponds to the Border check box.

Pattern    corresponds to the Pattern check box.

Width    corresponds to the Column Width/Row Height check box.

Related Functions

ALIGNMENT   Aligns or wraps text in cells

BORDER   Adds a border to the selected cell or object

FONT.PROPERTIES   Applies a font to the selection

FORMAT.NUMBER   Applies a number format to the selection

PATTERNS   Changes the appearance of the selected object

FORMAT.CHART

Equivalent to choosing the Options button in the Chart Type dialog box, which is available when you choose the Chart Type command from the Format menu when a chart is active. Formats the chart according to the arguments you specify.

Syntax

FORMAT.CHART(layer_num, view, overlap, angle, gap_width, gap_depth, chart_depth, doughnut_size, axis_num, drop, hilo, up_down, series_line, labels, vary)

FORMAT.CHART?(layer_num, view, overlap, angle, gap_width, gap_depth, chart_depth, doughnut_size, axis_num, drop, hilo, up_down, series_line, labels, vary)

Several of the following arguments are logical values corresponding to check boxes in the Options tab of Format (chart type) Group dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged.

Layer_num    is a number specifying which chart you want to change.

View    is a number specifying one of the subtypes in the Subtype tab of the Format (type) Group dialog box. The subtype varies depending on the type of chart.

Overlap    is a number from -100 to 100 specifying how you want bars or columns to be positioned. It corresponds to the Overlap edit box in the Options tab on the Format Bar Group Dialog box, which appears when you choose the Bar Group from the Format menu. Overlap is ignored if type_num is not 2 or 3 (bar or column chart). 

•   If overlap is positive, it specifies the percentage of overlap you want for bars or columns. For example, 50 would cause one-half of a bar or column to be covered by an adjacent bar or column. A value of zero prevents bars or columns from overlapping.

•   If overlap is negative, then bars or columns are separated by the specified percentage of the maximum available distance between any two bars or columns.

•   If overlap is omitted, it is assumed to be 0 (bars or columns do not overlap), or it is unchanged if a value was previously set.

Angle    is a number from 0 to 360 specifying the angle of the first pie or doughnut slice (in degrees) if the chart is a pie or doughnut chart. If angle is omitted, it is assumed to be 0, or it is unchanged if a value was previously set.

Gap_width    is a number from 0 to 500 specifying the space between bar or column clusters as a percentage of the width of a bar or column. It corresponds to the Gap Width edit box in the Options tab on the Format Bar Group Dialog box, which appears when you choose the Bar Group from the Format menu. 

•   Gap_width is ignored if type_num is not 2, 3, 8, or 12 (bar or column chart).

•   If Gap_width is omitted, it is assumed to be 50, or it is unchanged if a value was previously set. 

The next two arguments are for 3-D charts only, and correspond to check boxes in the Options tab of Format (chart type) Group dialog box.

Gap_depth    is a number from 0 to 500 specifying the depth of the gap in front of and behind a bar, column, area, or line as a percentage of the depth of the bar, column, area, or line. 

•   Gap_depth is ignored if the chart is a pie chart or if it is not a 3-D chart.

•   If gap_depth is omitted and the chart is a 3-D chart, gap_depth is assumed to be 50, or it is unchanged if a value was previously set. If gap_depth is omitted and the view is side-by-side, stacked, or stacked 100%, gap_depth is assumed to be 0, or it is unchanged if a value was previously set. 

Chart_depth    is a number from 20 to 2000 specifying the visual depth of the chart as a percentage of the width of the chart. 

•   Chart_depth is ignored if the chart is not a 3-D chart.

•   If Chart_depth is omitted, it is assumed to be 100, or it is unchanged if a value was previously set. 

Doughnut_size    specifies the size of the hole in a doughnut chart. Can be a value from 10% - 90%. Default is 50%.

Axis_num    is a number specifying whether to plot the chart on the primary axis or the secondary axis.

Drop    corresponds to the Drop Lines check box. Drop is available only for area and line charts.

Hilo    corresponds to the Hi-Lo Lines check box. Hilo is available only for 2-D line charts.

The next four arguments are logical values corresponding to check boxes in the Options tab of the Format (chart type) Group dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged.

Up_down    corresponds to the Up/Down Bars check box. Up_down is available only for 2-D line charts.

Series_line    corresponds to the Series Lines check box. Series_line is available only for 2-D stacked bar and column charts.

Labels    corresponds to the Radar Axis Labels check box. Labels is available only for radar charts.

Vary    corresponds to the Vary Colors By Point check box. Vary applies only to charts with one data series and is not available for area charts.

Related Functions

   Formats a chart according to the arguments you specify

FORMAT.OVERLAY   Formats an overlay chart

FORMAT.CHARTTYPE

Changes the chart type for a selected data series, a group of data series, or an entire chart.

Syntax

FORMAT.CHARTTYPE(apply_to, group_num, dimension, type_num)

FORMAT.CHARTTYPE?(apply_to, group_num, dimension, type_num)

Apply_to    is a number from 1 to 3 specifying what part of a chart the new chart type effects.

Value

 

Part of chart

1     Selected data series

2     Group of data series

3     Entire chart

Group_num    corresponds to the number of the group you want to change as listed in the Group list box of the Chart Type dialog box, which appears when you click Chart Type from the Format menu while a chart is active. Groups are numbered starting with 1 for the group at the top of the list. This argument is required if apply_to equals 2; otherwise it is ignored.

Dimension    specifies whether to apply a 2-D or 3-D chart type. Use 1 for a 2-D chart type or 2 for a 3-D chart type. If omitted, uses the same dimension as the series, group, or chart to be changed.

Type_num    specifies the chart type to apply. Meaning of type_num varies depending on the value of dimension:

Type_num

 

Chart type if dimension is 1

1        Area or 3-D area

2        Bar or 3-D bar

3        Column or 3-D column

4        Line or 3-D line

5        Pie or 3-D pie

6        Doughnut or 3-D surface

7        Radar

8        XY (scatter)

Related Function

FORMAT.CHART   Formats the selected chart

Equivalent to choosing the Cells command from the Format menu, and then selecting Font tab from the Format Cells dialog box. This function is included for compatibility with Microsoft Excel version 4.0. Use FONT.PROPERTIES to set various font properties. has three syntax forms. Syntax 1 is for cells; syntax 2 is for text boxes and buttons; syntax 3 is used with all chart items (axes, labels, text, and so on).

Syntax 1

Cells

(name_text, size_num, bold, italic, underline, strike, color, outline, shadow)

?(name_text, size_num, bold, italic, underline, strike, color, outline, shadow) Syntax 2

Text boxes and buttons on worksheets and macro sheets

(name_text, size_num, bold, italic, underline, strike, color, outline, shadow, object_id_text, start_num, char_num)

?(name_text, size_num, bold, italic, underline, strike, color, outline, shadow, object_id_text, start_num, char_num)

Syntax 3

Chart items including unattached chart text

(color, backgd, apply, name_text, size_num, bold, italic, underline, strike, outline, shadow, object_id_text, start_num, char_num)

?(color, backgd, apply, name_text, size_num, bold, italic, underline, strike, outline, shadow, object_id_text, start_num, char_num)

Arguments correspond to check boxes and list box items in the Font tab on the Format Cells dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the format is not changed.

Name_text    is the name of the font as it appears in the Font tab. For example, Courier is a font name.

Size_num    is the font size, in points.

Bold    corresponds to the Bold item in the Font Style list box. Makes the selection bold, if applicable.

Italic    corresponds to the Italic item in the Font Style list box. Makes the selection italic, if applicable.

Underline    corresponds to the Underline check box.

Strike    corresponds to the Strikethrough check box.

Color    is a number from 0 to 56 corresponding to the colors in the Font tab; 0 corresponds to automatic color.

Outline    corresponds to the Outline check box. Outline fonts are available in Microsoft Excel for the Macintosh. For macro compatibility, this argument is ignored by Microsoft Excel for Windows.

Shadow    corresponds to the Shadow check box. Shadow fonts are available in Microsoft Excel for the Macintosh. For macro compatibility, this argument is ignored by Microsoft Excel for Windows.

Note   For macro compatibility with Microsoft Excel for the Macintosh, the presence of the outline and shadow arguments do not prevent the macro from working on Microsoft Excel for Windows, nor does their absence prevent it from working on the Macintosh.

Object_id_text    identifies the text box you want to format (for example, "Text 1", "Text 2", and so on). You can also use the object number alone without the text identifier. For compatibility with earlier versions of Microsoft Excel. This argument is ignored in Microsoft Excel version 5.0 or later.

Start_num    specifies the first character to be formatted. If start_num is omitted, it is assumed to be 1 (the first character in the text box).

Char_num    specifies how many characters to format. If char_num is omitted, Microsoft Excel formats all characters in the text box starting at start_num.

Backgd    is a number from 1 to 3 specifying which type of background to apply to text in a chart.

Backgd

 

Type of background applied

1      Automatic

2      Transparent

3      Opaque

Apply    corresponds to the Apply To All check box. This argument applies to data labels only.

Remarks

Some extended TrueType styles do not have corresponding arguments to . To access an extended TrueType font style, append the style name to the font name in name_text. For example, the font Taipei can be formatted in an upside-down style by specifying "Taipei Upside-down" as the name_text argument. For more information about TrueType, see your Microsoft Windows documentation.

Related Functions

ALIGNMENT   Aligns or wraps text in cells

FONT.PROPERTIES   Sets various font attributes

FORMAT.NUMBER   Applies a number format to the selection

   Formats a worksheet text box or a chart text item

FORMAT.LEGEND

Equivalent to clicking the Selected Legend command on the Format menu when a chart is active. Determines the position and orientation of the legend on a chart and returns TRUE; returns an error message if the legend is not already selected.

Syntax

FORMAT.LEGEND(position_num)

FORMAT.LEGEND?(position_num)

Position_num    is a number from 1 to 5 specifying the position of the legend.

Position_num

 

Position of legend

1          Bottom

2          Corner

3          Top

4          Right

5          Left

Related Functions

   Moves the selected object

   Sizes an object

LEGEND   Adds or deletes a chart legend

Equivalent to clicking the Main Chart command on the Format menu in Microsoft Excel version 4.0. Formats a chart according to the arguments you specify. This function is included for compatibility with Microsoft Excel version 4.0. In Microsoft Excel version 5.0 or later, this is equivalent to clicking the Chart Type command on the Format menu. You can also use the FORMAT.CHART function.

Syntax

(type_num, view, overlap, gap_width, vary, drop, hilo, angle, gap_depth, chart_depth, up_down, series_line, labels, doughnut_size)

?(type_num, view, overlap, gap_width, vary, drop, hilo, angle, gap_depth, chart_depth, up_down, series_line, labels, doughnut_size) Type_num    is a number specifying the type of chart.

Type_num

 

Chart

1        Area

2        Bar

3        Column

4        Line

5        Pie

6        XY (Scatter)

7        3-D Area

8        3-D Column

9        3-D Line

10        3-D Pie

11        Radar

12        3-D Bar

13        3-D Surface

14        Doughnut

View    is a number specifying one of the views in the Data View box in the Main Chart dialog box. The view varies depending on the type of chart.

Overlap    is a number from -100 to 100 specifying how you want bars or columns to be positioned. It corresponds to the Overlap box in the Main Chart dialog box. Overlap is ignored if type_num is not 2 or 3 (bar or column chart). 

•   If overlap is positive, it specifies the percentage of overlap you want for bars or columns. For example, 50 would cause one-half of a bar or column to be covered by an adjacent bar or column. A value of zero prevents bars or columns from overlapping.

•   If overlap is negative, then bars or columns are separated by the specified percentage of the maximum available distance between any two bars or columns.

•   If overlap is omitted, it is assumed to be 0 (bars or columns do not overlap), or it is unchanged if a value was previously set.

Gap_width    is a number from 0 to 500 specifying the space between bar or column clusters as a percentage of the width of a bar or column. It corresponds to the Gap Width box in the Main Chart dialog box. 

•   Gap_width is ignored if type_num is not 2, 3, 8, or 12 (bar or column chart).

•   If gap_width is omitted, it is assumed to be 50, or it is unchanged if a value was previously set.

Several of the following arguments are logical values corresponding to check boxes in the Main Chart dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged.

Vary    corresponds to the Vary By Categories check box. Vary applies only to charts with one data series and is not available for area charts.

Drop    corresponds to the Drop Lines check box. Drop is available only for area and line charts.

Hilo    corresponds to the Hi-Lo Lines check box. Hilo is available only for line charts.

Angle    is a number from 0 to 360 specifying the angle of the first pie slice (in degrees) if the chart is a pie chart. If angle is omitted, it is assumed to be 0, or it is unchanged if a value was previously set.

The next two arguments are for 3-D charts only.

Gap_depth    is a number from 0 to 500 specifying the depth of the gap in front of and behind a bar, column, area, or line as a percentage of the depth of the bar, column, area, or line. 

•   Gap_depth is ignored if the chart is a pie chart or if it is not a 3-D chart.

•   If gap_depth is omitted and the chart is a 3-D chart, gap_depth is assumed to be 50, or it is unchanged if a value was previously set. If gap_depth is omitted and the view is side-by-side, stacked, or stacked 100%, gap_depth is assumed to be 0, or it is unchanged if a value was previously set. 

Chart_depth    is a number from 20 to 2000 specifying the visual depth of the chart as a percentage of the width of the chart. Chart_depth corresponds to the Chart Depth box in the Main Chart dialog box. 

•   Chart_depth is ignored if the chart is not a 3-D chart.

•   If chart_depth is omitted, it is assumed to be 100, or it is unchanged if a value was previously set. 

The next three arguments are logical values corresponding to check boxes in the Main Chart dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged. The final argument is for compatibility with Microsoft Excel version 4.0.

Up_down    corresponds to the Up/Down Bars check box. Up_down is available only for line charts.

Series_line    corresponds to the Series Lines check box. Series_line is available only for stacked bar and column charts.

Labels    corresponds to the Radar Axis Labels check box. Labels is available only for radar charts.

Doughnut_size    specifies the size of the hole in a doughnut chart. Can be a value from 10% - 90%. Default is 50%

Related Functions

FORMAT.CHART   Formats a chart

FORMAT.OVERLAY   Formats an overlay chart

Equivalent to moving an object with the mouse. Moves the selected object to the specified position and, if successful, returns TRUE. If the selected object cannot be moved,

returns FALSE. There are three syntax forms of this function. Use syntax 1 to move worksheet objects. Use syntax 2 to move chart items. Use syntax 3 to move pie-chart and doughnut-chart items. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax 1   Moves worksheet items

Syntax 2   Moves chart items

Syntax 3   Moves pie-chart and doughnut-chart items

SYNTAX 1

Equivalent to moving an object with the mouse. Moves the selected object to the specified position and, if successful, returns TRUE. If the selected object cannot be moved,

returns FALSE. There are three syntax forms of this function. Use syntax 1 to move worksheet objects. Use syntax 2 to move chart items. Use syntax 3 to move pie-chart and doughnut-chart items. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(x_offset, y_offset, reference)

?(x_offset, y_offset, reference)

X_offset    specifies the horizontal position to which you want to move the object and is measured in points from the upper-left corner of the object to the upper-left corner of the cell specified by reference. A point is 1/72nd of an inch.

Y_offset    specifies the vertical position to which you want to move the object and is measured in points from the upper-left corner of the object to the upper-left corner of the cell specified by reference.

Reference    specifies which cell or range of cells to place the object in relation to. 

•   If reference is a range of cells, only the upper-left cell is used.

•   If reference is omitted, it is assumed to be cell A1. 

Remarks

The position of an object is based on its upper-left corner. For ovals and arcs, the position is based on the upper-left corner of the bounding rectangle of the object.

Example

The following macro formula moves an object on the active worksheet so that it is 10 points horizontally offset and 15 points vertically offset from cell D4:

(10, 15, !$D$4)

Related Functions

CREATE.OBJECT   Creates an object

   Sizes an object

   Moves a window

Syntax 2   Moves chart items

Syntax 3   Moves pie-chart and doughnut-chart items

SYNTAX 2

Equivalent to moving an object with the mouse. Moves the base of the selected object to the specified position and, if successful, returns TRUE. If the selected object cannot be moved, returns FALSE. There are three syntax forms of this function. Use syntax 3 to move pie-chart and doughnut-chart items. Use syntax 1 to move worksheet objects. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(x_pos, y_pos)

?(x_pos, y_pos)

X_pos    specifies the horizontal position to which you want to move the object and is measured in points from the base of the object to the lower-left corner of the window. A point is 1/72nd of an inch.

Y_pos    specifies the vertical position to which you want to move the object and is measured in points from the base of the object to the lower-left corner of the window.

Remarks 

•    The base of a text label on a chart is the lower-left corner of the text rectangle.

•    The base of an arrow is the end without the arrowhead.

•    The base of a pie slice is the point. 

Example

On a chart, the following macro formula moves the base of the selected chart object 10 points to the right of and 20 points above the lower-left corner of the window:

(10, 20)

Related Functions

   Sizes an object

   Moves a window

Syntax 1   Moves worksheet items

Syntax 3   Moves pie-chart and doughnut-chart items

SYNTAX 3

Equivalent to exploding by moving a pie-chart or doughnut-chart slice with the mouse. Sets the percentage of pie-chart or doughnut-chart slice explosion, and, if successful, returns TRUE. If the selected object cannot be exploded, returns FALSE. There are three syntax forms of this function. Use syntax 1 to move worksheet items. Use syntax 2 to move chart items. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(explosion_num)

Explosion_num    is a number specifying the explosion percentage for the selected pie slice or the entire chart (if the series is selected). Zero is no explosion (the tip of the slice is in the center of the pie).

Related Functions

   Sizes an object

Syntax 1   Moves worksheet items

Syntax 2   Moves chart items

   Moves a window

FORMAT.NUMBER

Equivalent to choosing the Number tab in the Format Cells dialog box, which appears when you choose Cells from the Format menu. Formats numbers, dates, and times in the selected cells, data labels, and axis labels on charts. Use FORMAT.NUMBER to apply built-in formats or to create and apply custom formats.

Syntax

FORMAT.NUMBER(format_text)

FORMAT.NUMBER?(format_text)

Format_text    is a format string, such as "#, ##0.00", specifying which format to apply to the selection.

Related Functions

DELETE.FORMAT   Deletes the specified custom number format

FONT.PROPERTIES   Applies a font to the selection

   Formats a sheet text box or a chart text item

FORMAT.OVERLAY

Equivalent to clicking the Overlay command on the Format menu in Microsoft Excel version 4.0. Formats the overlay chart according to the arguments you specify.

Syntax

FORMAT.OVERLAY(type_num, view, overlap, gap_width, vary, drop, hilo, angle, series_dist, series_num, up_down, series_line, labels)

FORMAT.OVERLAY?(type_num, view, overlap, gap_width, vary, drop, hilo, angle, series_dist, series_num, up_down, series_line, labels)

Type_num    is a number specifying the type of chart.

Type_num

 

Chart

1        Area

2        Bar

3        Column

4        Line

5        Pie

6        XY (Scatter)

11                  Radar

14                  Doughnut

View    is a number specifying one of the views in the Data View box in the Overlay dialog box. The view varies depending on the type of chart.

Overlap    is a number from -100 to 100 specifying how you want bars or columns to be positioned. It corresponds to the Overlap box in the Overlay dialog box. Overlap is ignored if type_num is not 2 or 3 (bar or column chart). 

•   If overlap is positive, it specifies the percentage of overlap you want for bars or columns. For example, 50 would cause one-half of a bar or column to be covered by an adjacent bar or column.

•   If overlap is negative, then bars or columns are separated by the specified percentage of the maximum available distance between any two bars or columns.

•   If overlap is omitted, it is assumed to be 0 (bars or columns do not overlap), or it is unchanged if a value was previously set. 

Gap_width    is a number from 0 to 500 specifying the space between bar or column clusters as a percentage of the width of a bar or column. 

•   Gap_width is ignored if type_num is not 2 or 3 (bar or column chart).

•   If gap_width is omitted, it is assumed to be 50, or it is unchanged if a value was previously set. 

Several of the following arguments are logical values corresponding to check boxes in the Overlay dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged.

Vary    corresponds to the Vary By Categories check box. Vary is not available for area charts.

Drop    corresponds to the Drop Lines check box. Drop is available only for area and line charts.

Hilo    corresponds to the Hi-Lo Lines check box. Hilo is available only for line charts.

Angle    is a number from 0 to 360 specifying the angle of the first pie slice (in degrees) if the chart is a pie chart. If angle is omitted, it is assumed to be 0, or it is unchanged if a value was previously set.

Series_dist    is the number 1 or 2 and specifies automatic or manual series distribution. 

•   If series_dist is 1 or omitted, Microsoft Excel uses automatic series distribution.

•   If series_dist is 2, Microsoft Excel uses manual series distribution, and you must specify which series is first in the distribution by using the series_num argument. 

Series_num    is the number of the first series in the overlay chart and corresponds to the First Overlay Series box in the Overlay dialog box. If series_dist is 1 (automatic series distribution), this argument is ignored.

Up_down    corresponds to the Up/Down Bars check box. Up_down is available only for line charts.

Series_line    corresponds to the Series Lines check box. Series_line is available only for stacked bar and column charts.

Labels    corresponds to the Radar Axis Labels check box. Labels is available only for radar charts.

Related Functions

DELETE.OVERLAY   Deletes the overlay on a chart

FORMAT.CHART   Formats a chart

FORMAT.SHAPE

Equivalent to clicking the reshape button on the Drawing toolbar and then inserting, moving, or deleting vertices of the selected polygon. A vertex is a point defined by a pair of coordinates in one row of the array that defines the polygon. The array is created by CREATE.OBJECT and EXTEND.POLYGON functions.

Syntax

FORMAT.SHAPE(vertex_num, insert, reference, x_offset, y_offset)

Vertex_num    is a number corresponding to the vertex you want to insert, move, or delete.

Insert    is a logical value specifying whether to insert a vertex, or move or delete a vertex. 

•   If insert is TRUE, Microsoft Excel inserts a vertex between the vertices vertex_num and vertex_num-1. The number of the new vertex then becomes vertex_num. The number of the vertex previously identified by vertex_num becomes vertex_num+1, and so on.

•   If insert is FALSE, Microsoft Excel deletes the vertex (if the remaining arguments are omitted) or moves the vertex to the position specified by the remaining arguments. 

Reference    is the reference from which the vertex you are inserting or moving is measured; that is, the cell or range of cells to use as the basis for the x and y offsets. 

•   If reference is a range of cells, only the upper-left cell is used.

•   If reference is omitted, the vertex is measured from the upper-left corner of the polygon's bounding rectangle. 

X_offset    is the horizontal distance from the upper-left corner of reference to the vertex. X_offset is measured in points. A point is 1/72nd of an inch. If reference is omitted, x_offset specifies the horizontal distance from the upper-left corner of the polygon bounding rectangle.

Y_offset    is the vertical distance from the upper-left corner of reference to the vertex. Y_offset is measured in points. If reference is omitted, y_offset specifies the vertical distance from the upper-left corner of the polygon bounding rectangle. Remarks

You cannot delete a vertex if only two vertices remain.

Examples

The following macro formula deletes the second vertex of the selected polygon:

FORMAT.SHAPE(2, FALSE)

The following macro formula moves the thirteenth vertex 6 points to the right and 4 points below the upper-left corner of cell B5 on the active worksheet:

FORMAT.SHAPE(13, FALSE, !$B$5, 6, 4)

The following macro formula inserts a new vertex between vertices 2 and 3. The new vertex is 60 points to the right and 75 points below the upper-left corner of the polygon's bounding rectangle:

FORMAT.SHAPE(3, TRUE, , 60, 75)

Related Functions

CREATE.OBJECT   Creates an object

EXTEND.POLYGON   Adds vertices to a polygon

Equivalent to sizing an object with the mouse. Sizes the selected object and returns TRUE. If the selected chart object cannot be sized, returns FALSE. There are two syntax forms of this function. Use syntax 1 to size worksheet objects and chart items absolutely. Use syntax 2 relative to a cell or range of cells to size only worksheet objects. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax 1   Sizes worksheet objects and chart items

Syntax 2   Sizes worksheet objects relative to a cell or range

SYNTAX 1

Equivalent to sizing an object with the mouse. Sizes the selected object and returns TRUE. If the selected chart object cannot be sized, returns FALSE. There are two syntax forms of this function. Use syntax 1 to size worksheet objects and chart items absolutely. Use syntax 2 relative to a cell or range of cells to size only worksheet objects. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(width, height)

?(width, height)

Width    specifies the width of the selected object, measured in points. A point is 1/72nd of an inch.

Height    specifies the height of the selected object, measured in points.

You do not always have to use both arguments. For example, if you specify height and not width, the height changes but the width does not.

Remarks 

•    The base of a text label on a chart is the lower-left corner of the text rectangle.

•    The base of an arrow is the end without the arrowhead. 

Related Functions

   Moves the selected object

SIZE   Changes the size of a window

Syntax 2   Sizes worksheet objects relative to a cell or range

SYNTAX 2

Equivalent to sizing an object with the mouse. Sizes the selected worksheet object and returns TRUE. If the selected object cannot be sized, returns FALSE. There are two syntax forms of this function. Use syntax 2 to size worksheet objects relative to a cell or range of cells. Use syntax 1 to size worksheet objects and chart items. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(x_off, y_off, reference)

?(x_off, y_off, reference)

X_off    specifies the width of the selected object and is measured in points from the lowerright corner of the object to the upper-left corner of reference. A point is 1/72nd of an inch. If omitted, x_off is assumed to be 0. If reference is omitted, x_off specifies the horizontal size.

Y_off    specifies the height of the selected object and is measured in points from the lowerright corner of the object to the upper-left corner of reference. If omitted, y_off is assumed to be 0. If reference is omitted, y_off specifies the vertical size.

Reference    specifies the cell or range of cells to use as the basis for the offset and for sizing. If reference is a range of cells, only the upper-left cell in the range is used.

Related Functions

   Moves the selected object

SIZE   Changes the size of a window

Syntax 1   Sizes worksheet objects and chart items

Formats the selected worksheet text box or button or any text item on a chart.

Syntax

(x_align, y_align, orient_num, auto_text, auto_size, show_key, show_value, add_indent)

?(x_align, y_align, orient_num, auto_text, auto_size, show_key, show_value, add_indent)

Arguments correspond to check boxes or options in the various tabs on Format Object dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box; if omitted, the current setting is used.

X_align    is a number from 1 to 4 specifying the horizontal alignment of the text.

X_align

 

Horizontal alignment

1       Left

2       Center

3       Right

4       Justify

Y_align    is a number from 1 to 4 specifying the vertical alignment of the text.

Y_align

 

Vertical alignment

1       Top

2       Center

3       Bottom

4       Justify

Orient_num    is a number from 0 to 3 specifying the orientation of the text.

Orient_num

 

Text orientation

0         Horizontal

1         Vertical

2         Upward

3         Downward

Auto_text    corresponds to the Automatic Text check box. If the selected text was created with the Data Labels command from the Insert menu and later edited, this option restores the original text. Auto_text is ignored for text boxes on worksheets and macro sheets.

Auto_size    corresponds to the Automatic Size check box. If you have changed the size of the border around the selected text, this option restores the border to automatic size. Automatic size makes the border fit exactly around the text no matter how you change the text.

Show_key    corresponds to the Show Legend Key Next to Label check box in the Data Labels dialog box. This argument applies only if the selected text is an attached data label on a chart.

Show_value    corresponds to the Show Value option button in the Format Data Labels dialog box. This argument applies only if the selected text is an attached data label on a chart.

The following list summarizes which arguments apply to each type of text item.

Add_indent   This argument is for only Far East versions of Microsoft Excel.

Text item

 

Arguments that apply

Worksheet text box or button X_align, y_align, orient_num, auto_size

Attached data label                   All arguments

Unattached text label                 X_align, y_align, orient_num, auto_size

Tickmark label                          Orient_num

Related Functions

CREATE.OBJECT   Creates an object

FONT.PROPERTIES   Applies a font to the selection

FORMULA   Enters values into a cell or range or onto a chart

FORMULA

Enters a formula in the active cell or in a reference. There are two syntax forms of this function. Use syntax 1 to enter numbers, text, references, and formulas in a worksheet. Although syntax 1 can also be used to enter values on a macro sheet, you will not generally use FORMULA for this purpose. Use syntax 2 to enter a formula in a chart. For information about setting values on a macro sheet, see "Remarks" in the following topics.

Syntax 1   Enters numbers, text, references, and formulas in a worksheet Syntax 2   Enters formulas in a chart

FORMULA SYNTAX 1

Enters a formula in the active cell or in a reference. If the active sheet is a worksheet, using FORMULA is equivalent to entering formula_text in the cell specified by reference. Formula_text is entered just as if you typed it in the formula bar.

There are two syntax forms of this function. Use syntax 1 to enter numbers, text, references, and formulas in a worksheet. Although syntax 1 can also be used to enter values on a macro sheet, you will not generally use FORMULA for this purpose. Use syntax 2 to enter a formula in a chart. For information about setting values on a macro sheet, see "Remarks" later in this topic.

Syntax

FORMULA(formula_text, reference)

Formula_text    can be text, a number, a reference, or a formula in the form of text, or a reference to a cell containing any of the above. 

•   If formula_text contains references, they must be R1C1-style references, such as "=RC[1]*(1+R1C1)". If you are recording a macro when you enter a formula, Microsoft Excel converts A1-style references to R1C1-style references. For example, if you enter the formula =B2*(1+$A$1) in cell C2 while recording, Microsoft Excel records that action as =FORMULA("=RC[-1]*(1+R1C1)").

•   If formula_text is a formula, the formula is entered. Text arguments must be surrounded by double sets of quotation marks. For example, to enter the formula =IF($A$1="Hello World", 1, 0) in the active cell with the FORMULA function, you would use the formula FORMULA("=IF(R1C1=""Hello World"", 1, 0)")

•   If formula_text is a number, text, or logical value, the value is entered as a constant.

Reference    specifies where formula_text is to be entered. It can be a reference to a cell in the active workbook or an external reference to a workbook. If reference is omitted, formula_text is entered in the active cell.

Remarks

Consider the following guidelines as you choose a function to set values on a worksheet or macro sheet: 

•   Use FORMULA to enter formulas and change values in a worksheet cell.

•   SET.VALUE changes values on the macro sheet. Use SET.VALUE to assign initial values to a reference and to store values during the calculation of the macro.

•   creates names on the macro sheet. Use to create a name and immediately assign a value to the name. 

Examples

If the active sheet is a worksheet, the following macro formula enters the number constant 523 in the active cell:

FORMULA(523)

If the active sheet is a worksheet, the following macro formula enters the result of the INPUT function in cell A5:

FORMULA(INPUT("Enter a formula:", 0), !$A$5)

If you're using R1C1-style references and the active sheet is a worksheet, the following macro formula enters the formula =RC[-1]*(1+R1C1) in the active cell:

FORMULA("=RC[-1]*(1+R1C1)")

If the active sheet is a worksheet, the following macro formulas enter the number 1000 in the cell two rows down and three columns right from the active cell. The R1C1-style formula is shorter, but the OFFSET method may provide faster performance in larger macro sheets.

FORMULA(1000, OFFSET((), 2, 3))

FORMULA(1000, "R[2]C[3]")

The following macro formula enters the phrase "Year to Date" in cell B4 on the sheet named SALES 1993:

FORMULA("Year to Date", 'SALES 1993'!B4)

Related Functions

FORMULA.ARRAY   Enters an array

   Enters a formula in the specified range

SET.VALUE   Sets the value of a cell on a macro sheet

FORMULA Syntax 2   Enters formulas in a chart

FORMULA SYNTAX 2

Enters a text label or SERIES formula in a chart. To enter formulas on a worksheet or macro sheet, use syntax 1 of this function.

Syntax

FORMULA(formula_text)

Formula_text    is the text label or SERIES formula you want to enter into the chart.

 

If

 

Then

 

Formula_text can be treated as a text label and the current selection is a text label

The selected text label is replaced with formula_text.

 

 

Formula_text can be treated as a text label and there is no current selection or the current selection is not a text label

Formula_text creates a new unattached text label.

 

 

Formula_text can be treated as a SERIES formula and the current selection is a

SERIES formula

The selected SERIES formula is replaced with formula_text.

 

 

Formula_text can be treated as a SERIES formula and the current selection is not a

SERIES formula

Formula_text creates a new SERIES formula.

 

         

Remarks

You would normally use the EDIT.SERIES function to create or edit a chart series. For more information, see EDIT.SERIES.

Example

The following macro formula enters a SERIES formula on the chart. If the current selection is a SERIES formula, it is replaced:

FORMULA("=SERIES(""Title"", , {1, 2, 3}, 1)")

Related Functions

EDIT.SERIES   Creates or changes a chart series

FORMULA, Syntax 1   Enters numbers, text, references, and formulas in a worksheet

FORMULA.ARRAY

Enters a formula as an array formula in the range specified or in the current selection. Equivalent to entering an array formula while pressing CTRL+SHIFT+ENTER in Microsoft Excel for Windows or COMMAND+ENTER in Microsoft Excel for the Macintosh.

Syntax

FORMULA.ARRAY(formula_text, reference)

Formula_text    is the text you want to enter in the array. For more information on formula_text, see the first form of FORMULA.

Reference    specifies where formula_text is entered. It can be a reference to a cell on the active worksheet or an external reference to a named workbook. Reference must be a R1C1-style reference in text form. If reference is omitted, formula_text is entered in the active cell.

Examples

If the selection is D25:E25, the following macro formula enters the array formula {=D22:E22+D23:E23} in the range D25:E25:

FORMULA.ARRAY("=R[-3]C:R[-3]C[1]+R[-2]C:R[-2]C[1]")

Regardless of the selection, the following macro formula enters the array formula {=D22:E22+D23:E23} in the range D25:E25:

FORMULA.ARRAY("=R[-3]C:R[-3]C[1]+R[-2]C:R[-2]C[1]", "R25C4:R25C5")

To use FORMULA.ARRAY to put an array in a specific workbook, specify the name of the workbook as an external reference in the reference argument. Using

"[]North!R25C3:R25C4" as the reference argument in the preceding example would enter the array in cells C25:D25 on the worksheet named North in the workbook . Using "SALES!R25C3:R25C4" as the reference argument would enter the array in the same cells in the worksheet named SALES.

Related Functions

FORMULA   Enters values into a cell or range or onto a chart

   Enters a formula in the specified range

FORMULA.CONVERT

Changes the style and type of references in a formula between A1 and R1C1 and between relative and absolute. Use FORMULA.CONVERT to convert references of one style or type to another style or type.

Syntax

FORMULA.CONVERT(formula_text, from_a1, to_a1, to_ref_type, rel_to_ref)

Formula_text    is the formula, given as text, containing the references you want to change. Formula_text must be a valid formula, and an equal sign must be included.

From_a1    is a logical value specifying whether the references in formula_text are in A1 or R1C1 style. If from_a1 is TRUE, references are in A1 style; if FALSE, references are in R1C1 style.

To_a1    is a logical value specifying the form for the references FORMULA.CONVERT returns. If to_a1 is TRUE, references are returned in A1 style; if FALSE, references are returned in R1C1 style. If to_a1 is omitted, the reference style is not changed.

To_ref_type    is a number from 1 to 4 specifying the reference type of the returned formula. If to_ref_type is omitted, the reference type is not changed.

To_ref_type

 

Reference type returned

1         Absolute

2         Absolute row, relative column

3         Relative row, absolute column

4         Relative

Rel_to_ref    is an absolute reference that specifies what cell the relative references are or should be relative to.

Examples

Use FORMULA.CONVERT to convert relative references entered by the user in an INPUT function or custom dialog box into absolute references. The following macro formula converts the given formula to an absolute, R1C1-style reference:

FORMULA.CONVERT("=A1:A10", TRUE, FALSE, 1) equals "=R1C1:R10C1"

The following macro formula converts the references in the given formula to relative, A1-style references:

FORMULA.CONVERT("=SUM(R10C2:R15C2)", FALSE, TRUE, 4) equals "=SUM(B10:B15)"

Tip   To put the converted formula into a cell or range of cells, use the FORMULA.CONVERT function as the formula_text argument to the FORMULA function.

Related Functions

ABSREF   Returns the absolute reference of a range of cells to another range

FORMULA   Enters values into a cell or range or onto a chart

RELREF   Returns a relative reference

Enters a formula in the range specified or in the current selection. Equivalent to entering a formula in a range of cells while pressing CTRL+ENTER in Microsoft Excel for Windows or OPTION+ENTER in Microsoft Excel for the Macintosh.

Syntax

(formula_text, reference)

Formula_text    is the text with which you want to fill the range. For more information on formula_text, see FORMULA.

Reference    specifies where formula_text is entered. It can be a reference to a range in the active worksheet or an external reference to a named workbook. If omitted, formula_text is entered in the current selection.

Related Functions

DATA.SERIES   Fills a range of cells with a series of numbers or dates

FORMULA   Enters values into a cell or range or onto a chart

FORMULA.ARRAY   Enters an array

Equivalent to clicking the Find command on the Edit menu. Selects the next or previous cell containing the specified text and returns TRUE. If a matching cell is not found, returns FALSE and displays a message.

Syntax

(text, in_num, at_num, by_num, dir_num, match_case)

?(text, in_num, at_num, by_num, dir_num, match_case)

Text    is the text you want to find. Text corresponds to the Find What box in the Find dialog box.

In_num    is a number from 1 to 3 specifying where to search.

In_num

 

Searches

1        Formulas

2        Values

3        Notes

At_num    is the number 1 or 2 and specifies whether to find cells containing only text or also cells containing text within a longer string of characters.

At_num

 

Searches for text as

1        A whole string (the only value in the cell)

2        Either a whole string or part of a longer string

By_num    is the number 1 or 2 and specifies whether to search by rows or by columns.

By_num

 

Searches by

1        Rows

2        Columns

Dir_num    is the number 1 or 2 and specifies whether to search for the next or previous occurrence of text.

Dir_num

 

Searches for

1          or omitted The next occurrence of text

2          The previous occurrence of text

Match_case    is a logical value corresponding to the Match Case check box in the Find dialog box. If match_case is TRUE, Microsoft Excel matches characters exactly, including uppercase and lowercase; if FALSE or omitted, matching is not case-sensitive.

Remarks 

•    In Microsoft Excel for Windows, the dialog-box form of is equivalent to pressing SHIFT+F5.

•    If more than one cell is selected when you use , Microsoft Excel searches only that selection. 

,

Finds the next and previous cells on the worksheet, as specified in the Find dialog box, and returns TRUE. (To see the Find dialog box, click Find on the Edit menu.) If a matching cell is not found, the functions return FALSE. For more information see .

Syntax

( ) ( )

Related Functions

   Selects records in a database that match the specified criteria

   Finds text in a workbook

Equivalent to clicking the Go To command on the Edit menu or to pressing F5. Scrolls through the worksheet and selects a named area or reference. Use to select a range on any open workbook; use SELECT to select a range on the active workbook.

Syntax

(reference, corner)

?(reference, corner)

Reference    specifies where to scroll and what to select. 

•   Reference should be either an external reference to a workbook, an R1C1-style reference in the form of text (see the second example following), or a name.

•   If the Go To command has already been carried out, reference is optional. If reference is omitted, it is assumed to be the reference of the cells you selected before the previous Go To command or macro function was carried out. This feature distinguishes from SELECT. 

Corner    is a logical value that specifies whether to scroll through the window so that the upper-left cell in reference is in the upper-left corner of the active window. If corner is TRUE, Microsoft Excel places reference in the upper-left corner of the window; if FALSE or omitted, Microsoft Excel scrolls through normally.

Tip   Microsoft Excel keeps a list of the cells you've selected with previous functions or Go To commands. When you use with GET.WORKSPACE(41), which returns a horizontal array of previous Go To selections, you can backtrack through multiple previous selections. See the last example below.

Remarks 

•   If you are recording a macro when you click the Go To command, the reference you enter in the Reference box of the Go To dialog box is recorded as text in the R1C1 reference style.

•   If you are recording a macro when you double-click a cell that has precedents on another worksheet, Microsoft Excel records a function. Examples

Each of the following macro formulas goes to cell A1 on the active worksheet:

(!$A$1)

("R1C1")

Each of the following macro formulas goes to the cells named Sales on the active worksheet and scrolls through the worksheet so that the upper-left corner of Sales is in the upper-left corner of the window:

(!Sales, TRUE)

("Sales", TRUE)

The following macro formula goes to the cells that were selected by the third most recent function or Go To command:

(INDEX(GET.WORKSPACE(41), 1, 3))

Related Functions

GOTO   Directs macro execution to another cell

HSCROLL   Horizontally scrolls through a sheet by percentage or by column or row number

SELECT   Selects a cell, worksheet object, or chart item

VSCROLL   Vertically scrolls through a sheet by percentage or by column or row number

FORMULA.REPLACE

Equivalent to clicking the Replace command on the Edit menu. Finds and replaces characters in cells on your worksheet.

Syntax

FORMULA.REPLACE(find_text, replace_text, look_at, look_by, active_cell, match_case)

FORMULA.REPLACE?(find_text, replace_text, look_at, look_by, active_cell, match_case)

Find_text    is the text you want to find. You can use the wildcard characters, question mark (?) and asterisk (*), in find_text. A question mark matches any single character; an asterisk matches any sequence of characters. If you want to find an actual question mark or asterisk, type a tilde (~) before the character.

Replace_text    is the text you want to replace find_text with.

Look_at    is a number specifying whether you want find_text to match the entire contents of a cell or any string of matching characters.

Look_at

 

Looks for find_text

1          or omitted As the entire contents of a cell

2          As part of the contents of a cell

Look_by    is a number specifying whether to search horizontally (through rows) or vertically (through columns).

Look_by

 

Looks for find_text

1          or omitted By rows

2          By columns

Active_cell    is a logical value specifying the cells in which find_text is to be replaced. 

•   If active_cell is TRUE, find_text is replaced in the active cell only.

•   If active_cell is FALSE, find_text is replaced in the entire selection, or, if the selection is a single cell, in the entire sheet. 

Match_case    is a logical value corresponding to the Match Case check box in the Replace dialog box. If match_case is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If match_case is omitted, the status of the check box is unchanged.

Remarks 

•   In FORMULA.REPLACE?, the dialog-box form of the function, omitted arguments are assumed to be the same arguments used in the previous replace operation. If there was no previous replace operation, omitted text arguments are assumed to be "" (empty text).

•   The result of FORMULA.REPLACE must be a valid cell entry. For example, you cannot replace "=" with "= =" at the beginning of a formula.

•   If more than a single cell is selected before you use FORMULA.REPLACE, only the selected cells are searched. 

Related Function

   Finds text in a workbook

FOURIER

Performs a Fourier transform.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

FOURIER(inprng, outrng, inverse, labels)

FOURIER?(inprng, outrng, inverse, labels)

Inprng    is the input range. The number of cells in the input range must be equal to a power of two (2, 4, 8, 16, ).

Outrng    is the first cell in the output range or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Inverse    is a logical value. If TRUE, an inverse Fourier transform is performed. If FALSE or omitted, a forward Fourier transform is performed.

Labels    is a logical value. 

•   If labels is TRUE, then the first row or column of inprng contains labels.

•   If labels is FALSE or omitted, all cells in inprng are considered data. Microsoft Excel generates appropriate data labels for the output table. 

Related Function

SAMPLE   Samples data

FPOS

Sets the position of a file. The position of a file is where a character is read from or written to by an FREAD, FREADLN, FWRITE, or FWRITELN function. Use FPOS when you want to write characters to or read characters from specific locations. For example, to append text to the end of a file, you must set the position to the end of the file; otherwise, you might accidentally overwrite existing characters in the file.

Syntax

FPOS(file_num, position_num)

File_num    is the unique ID number of the file for which you want to set the position. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FPOS returns the #VALUE! error value.

Position_num    is the location in the file that a character will be read from or written to. 

•   The first position in a file is 1, the location of the first byte.

•   The last position in the file is the same as the value returned by FSIZE. For example, the last position in a file with 280 bytes is 280.

•   If position_num is omitted, FPOS returns the current position of the file—that is, the number corresponding to where the next character will be read from or written to. 

Whenever you read a character from or write a character to a file, the file's position is automatically incremented.

Examples

The following statement starts a loop that executes until the position in the open file identified as FileNumber reaches the end of the file:

=WHILE(FPOS(FileNumber)<=FSIZE(FileNumber))

Related Functions

FCLOSE   Closes a text file

FOPEN   Opens a file with the type of permission specified

FREAD   Reads characters from a text file

FREADLN   Reads a line from a text file

FWRITE   Writes characters to a text file

FWRITELN   Writes a line to a text file

FREAD

Reads characters from a file, starting at the current position in the file. (For more information about a file's position, see FPOS.) If FREAD is successful, it returns the text to the cell containing FREAD and set's the file's position to the start of the following line. If the end of the file is reached or if FREAD can't read the file, it returns the #N/A error value. Use FREAD instead of FREADLN when you need to read a specific number of characters from a text file.

Syntax

FREAD(file_num, num_chars)

File_num    is the unique ID number of the file you want to read data from. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FREAD returns the #VALUE! error value.

Num_chars    specifies how many bytes to read from the file. FREAD can read up to 255 bytes at a time.

Example

The following function reads the next 200 bytes from the open file identified as FileNumber:

FREAD(FileNumber, 200)

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FREADLN   Reads a line from a text file

FWRITE   Writes characters to a text file

FREADLN

Reads characters from a file, starting at the current position in the file and continuing to the end of the line, placing the characters in the cell containing FREADLN. (For more information about a file's position, see FPOS.) If FREADLN is successful, it returns the text it read, up to but not including the carriage-return and linefeed characters at the end of the line (in Microsoft Excel for Windows) or the carriage-return character at the end of the line (in Microsoft Excel for the Macintosh). If the current file position is the end of the file or if FREADLN can't read the file, it returns the #N/A error value.

Syntax

FREADLN(file_num)

File_num    is the unique ID number of the file you want to read data from. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FREADLN returns the #VALUE! error value.

Example

The following function reads the next line from the open file identified as FileNumber:

FREADLN(FileNumber)

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FREAD   Reads characters from a text file

FWRITE   Writes characters to a text file

FWRITELN   Writes a line to a text file

FREEZE.PANES

Equivalent to clicking the Freeze Panes or Unfreeze Panes command on the Window menu. Splits the active window into panes, creates frozen panes, or freezes or unfreezes existing panes. Use FREEZE.PANES to keep row or column titles on the screen while scrolling to other parts of the sheet.

Syntax

FREEZE.PANES(logical, col_split, row_split)

Logical    is a logical value specifying which command FREEZE.PANES is equivalent to. 

•   If logical is TRUE, the function is equivalent to the Freeze Panes command. It freezes panes if they exist, or creates them, splits them at the specified position,

and freezes them if they do not exist. If the panes are already frozen, FREEZE.PANES takes no action.

•   If logical is FALSE, the function is equivalent to the Unfreeze Panes command. If no panes exist, FREEZE.PANES takes no action.

•   If logical is omitted, FREEZE.PANES creates and then freezes panes if no panes exist, freezes existing panes if they're not currently frozen, or unfreezes existing panes if they're currently frozen. 

Col_split    specifies where to split the window vertically and is measured in columns from the left of the window.

Row_split    specifies where to split the window horizontally and is measured in rows from the top of the window.

Col_split and row_split are ignored unless logical is TRUE and split panes do not exist.

Remarks

To create panes without freezing or unfreezing them, use the SPLIT function. You can freeze the panes later using the FREEZE.PANES function.

Related Functions

ACTIVATE   Switches to a window

SPLIT   Splits a window

FSIZE

Returns the number of bytes in a file. Use FSIZE to determine the size of the file, which is the same as the position of the last byte in the file.

Syntax

FSIZE(file_num)

File_num    is the unique ID number of the file whose size you want to know. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FSIZE returns the #VALUE! error value.

Example

The following function returns the size in bytes of the open file identified as FileNumber:

FSIZE(FileNumber)

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FTESTV

Performs a two-sample F-test.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

FTESTV(inprng1, inprng2, outrng, labels)

FTESTV?(inprng1, inprng2. outrng, labels) Inprng1    is the input range for the first data set.

Inprng2    is the input range for the second data set.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Labels    is a logical value. 

•   If labels is TRUE, then the first row or column of inprng1 and inprng2 contain labels.

•   If labels is FALSE or omitted, all cells in inprng1 and inprng2 are considered data. Microsoft Excel generates appropriate data labels for the output table.

FULL

Equivalent to pressing CTRL+F10 (full size) and CTRL+F5 (previous size) or double-clicking the title bar in Microsoft Excel for Windows version 3.0 or earlier. Equivalent to double-clicking the title bar or clicking the zoom box in Microsoft Excel for the Macintosh version 3.0 or earlier. This function is included only for macro compatibility. To perform the equivalent of a FULL(TRUE) function in Microsoft Excel version 4.0 or later, use the WINDOW.MAXIMIZE function. To perform the equivalent of a FULL(FALSE) function in Microsoft Excel version 4.0 or later, use the WINDOW.RESTORE function.

Syntax

FULL(logical)

FULL.SCREEN

Equivalent to clicking the Full Screen command on the View menu.

Syntax

FULL.SCREEN(logical)

Logical    switches to full screen if TRUE or omitted; exits full screen mode if FALSE.

FUNCTION.WIZARD

Displays the Paste Function dialog box, which you can use to enter functions into cells.

Syntax

FUNCTION.WIZARD?( )

Remarks

If you know the function or formula that you want to insert into a cell, use the FORMULA function.

Related Function

FORMULA   Enters values into a cell or range or onto a chart

FWRITE

Writes text to a file, starting at the current position in that file. (For more information about a file's position, see FPOS.) If FWRITE can't write to the file, it returns the #N/A error value.

Syntax

FWRITE(file_num, text)

File_num    is the unique ID number of the file you want to write data to. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FWRITE returns the #VALUE! error value.

Text    is the text you want to write to the file.

Example

The following function writes the current month to the open file identified as FileNumber:

FWRITE(FileNumber, TEXT(MONTH(NOW()),"mmmm"))

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FREAD   Reads characters from a text file

FWRITELN   Writes a line to a text file

FWRITELN

Writes text, followed by a carriage return and linefeed, to a file, starting at the current position in that file. (For more information about a file's position, see FPOS.) If FWRITELN can't write to the file, it returns the #N/A error value. Use FWRITELN instead of FWRITE when you want to append a carriage return and linefeed to each group of characters that you write to a text file.

Syntax

FWRITELN(file_num, text)

File_num    is the unique ID number of the file you want to write data to. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FWRITELN returns the #VALUE! error value.

Text    is the text you want to write to the file.

Remarks

In Microsoft Excel for Windows, FWRITELN writes text followed by a carriage return and a line feed. In Microsoft Excel for the Macintosh, FWRITELN writes text followed by a carriage return only.

Example

The following function writes the current month to the open file identified as FileNumber and starts a new line in the file:

FWRITELN(FileNumber, TEXT(MONTH(NOW()),"mmmm"))

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FREAD   Reads characters from a text file

FWRITE   Writes characters to a text file

Changes the format of the active chart to a 3-D area chart.

Syntax

(type_num)

?(type_num)

Type_num    is the number of the 3-D Area format that you want to apply to the chart.

Changes the active chart to a 3-D bar chart.

Syntax

(type_num)

?(type_num)

Type_num    is the number of the 3-D Bar format that you want to apply to the chart.

GALLERY.3D.COLUMN

Changes the format of the active chart to a 3-D column chart.

Syntax

GALLERY.3D.COLUMN(type_num)

GALLERY.3D.COLUMN?(type_num)

Type_num    is the number of the 3-D Column format that you want to apply to the chart.

Changes the format of the active chart to a 3-D line chart.

Syntax

(type_num)

?(type_num)

Type_num    is the number of the 3-D Line format that you want to apply to the chart.

Changes the format of the active chart to a 3-D pie chart.

Syntax

(type_num)

?(type_num)

Type_num    is the number of the 3-D Pie format that you want to apply to the chart.

GALLERY.3D.SURFACE

Changes the active chart to a 3-D surface chart.

Syntax

GALLERY.3D.SURFACE(type_num)

GALLERY.3D.SURFACE?(type_num)

Type_num    is the number of the 3-D Surface format that you want to apply to the chart.

Changes the format of the active chart to an area chart.

Syntax

(type_num, delete_overlay)

?(type_num, delete_overlay)

Type_num    is the number of a format in the AutoFormat dialog box when a chart is active dialog box that you want to apply to the area chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

Changes the format of the active chart to a bar chart.

Syntax

(type_num, delete_overlay)

?(type_num, delete_overlay)

Type_num    is the number of the format that you want to apply to the bar chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

GALLERY.COLUMN

Changes the format of the active chart to a column chart.

Syntax

GALLERY.COLUMN(type_num, delete_overlay)

GALLERY.COLUMN?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the column chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

GALLERY.CUSTOM

Changes the format of the active chart to the custom format.

Syntax

GALLERY.CUSTOM(name_text)

Name_text    is the name of the custom template you want to apply.

Related Functions

ADD.CHART.AUTOFORMAT   Formats a chart using a custom gallery

DELETE.CHART.AUTOFORMAT   Deletes a custom gallery

GALLERY.DOUGHNUT

Changes the format of the active chart to a doughnut chart.

GALLERY.DOUGHNUT(type_num, delete_overlay)

GALLERY.DOUGHNUT?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the doughnut chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

Changes the format of the active chart to a line chart.

Syntax

(type_num, delete_overlay)

?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the line chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

Changes the format of the active chart to a pie chart.

Syntax

(type_num, delete_overlay)

?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the pie chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

GALLERY.RADAR

Changes the format of the active chart to a radar chart.

Syntax

GALLERY.RADAR(type_num, delete_overlay)

GALLERY.RADAR?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the radar chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

GALLERY.SCATTER

Changes the format of the active chart to an xy (scatter) chart.

Syntax

GALLERY.SCATTER(type_num, delete_overlay)

GALLERY.SCATTER?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the xy (scatter) chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

Returns the number of the active menu bar. There are two syntax forms of . Use syntax 1 to return information that you can use with other functions that manipulate menu bars. Use syntax 2 to return information that you can use with functions that add, delete, or alter menu commands.

Syntax 1   Returns the number of the active menu bar

Syntax 2   Returns the name or position number of a specified command on a menu or of a specified menu on a menu bar

SYNTAX 1

Returns the number of the active menu bar. There are two syntax forms of . Use syntax 1 to return information that you can use with other functions that manipulate menu bars. For a list of the ID numbers for Microsoft Excel's built-in menu bars, see ADD.COMMAND. Syntax

( )

Example

The following macro formula assigns the name OldBar to the number of the active menu bar. This is useful if you will need to restore the current menu bar after displaying another custom menu bar.

("OldBar", ())

Related Functions

   Adds a menu bar

   Displays a menu bar

Syntax 2   Returns the name or position number of a specified command on a menu or of a specified menu on a menu bar

SYNTAX 2

Returns the name or position number of a specified command on a menu or of a specified menu on a menu bar. There are two syntax forms of . Use syntax 2 to return information that you can use with functions that add, delete, or alter menu commands.

Syntax

(bar_num, menu, command, subcommand)

Bar_num    is the number of a menu bar containing the menu or command about which you want information. Bar_num can be the number of a built-in menu bar or the number returned by a previously run function. For a list of the ID numbers for Microsoft Excel's built-in menu bars, see ADD.COMMAND.

Menu    is the menu on which the command resides or the menu whose name or position you want. Menu can be the name of the menu as text or the number of the menu. Menus are numbered starting with 1 from the left of the menu bar.

Command    is the command or submenu whose name or number you want returned. Command can be the name of the command from the menu as text, in which case the number is returned, or the number of the command from the menu, in which case the name is returned. Commands are numbered starting with 1 from the top of the menu. If command is 0, the name or position number of the menu is returned. If an ellipsis ( ) follows a command name, such as the Open command on the File menu, then you must include the ellipsis when referring to that command. See the following examples.

Subcommand    returns the name (if number is used for subcommand) or position (if name is used for subcommand) of a command on a submenu. If the command argument refers to an empty submenu, or is a command instead of a submenu, then using subcommand returns #N/A.

Remarks 

•    If an ampersand is used to indicate the access key in the name of a custom command, the ampersand is included in the name returned by . All built-in commands have an ampersand before the letter used as the access key.

•    If the command name or position specified does not exist, returns the #N/A error value. 

Examples

In the default worksheet and macro sheet menu bar:

(10, "File", "Print ") equals 14

(10, "File", 14) equals "&Print ^tCTRL+P" (where ^t is a tab character)

(10, 1, "Open") equals #N/A

(10, 1, "Open ") equals 2

Related Functions

ADD.COMMAND   Adds a command to a menu

DELETE.COMMAND   Deletes a command from a menu

GET.TOOLBAR   Retrieves information about a toolbar

RENAME.COMMAND   Changes the name of a command or menu

GETBAR Syntax 1   Returns the number of the active menu bar

Returns information about the formatting, location, or contents of a cell. Use in a macro whose behavior is determined by the status of a particular cell.

Syntax

(type_num, reference)

Type_num    is a number that specifies what type of cell information you want. The following list shows the possible values of type_num and the corresponding results.

Type_num

 

Returns

1                  Absolute reference of the upper-left cell in reference, as text

in the current workspace reference style.

2                  Row number of the top cell in reference.

3                  Column number of the leftmost cell in reference.

4                  Same as TYPE(reference).

5                  Contents of reference.

6                  Formula in reference, as text, in either A1 or R1C1 style

depending on the workspace setting.

7                  Number format of the cell, as text (for example, "m/d/yy" or

"General").

8                  Number indicating the cell's horizontal alignment: 

1  = General

2  = Left

3  = Center

4  = Right

5  = Fill

6  = Justify

7  = Center across cells

9                  Number indicating the left-border style assigned to the cell: 

0  = No border

1  = Thin line

2  = Medium line

3  = Dashed line

4  = Dotted line

5  = Thick line

6  = Double line

7  = Hairline

10                  Number indicating the right-border style assigned to the cell.

See type_num 9 for descriptions of the numbers returned.

11                  Number indicating the top-border style assigned to the cell.

See type_num 9 for descriptions of the numbers returned.

12                  Number indicating the bottom-border style assigned to the

cell. See type_num 9 for descriptions of the numbers returned.

13                  Number from 0 to 18, indicating the pattern of the selected

cell as displayed in the Patterns tab of the Format Cells dialog box, which appears when you click the Cells command on the Format menu. If no pattern is selected, returns 0.

14                  If the cell is locked, returns TRUE; otherwise, returns FALSE.

15                  If the cell's formula is hidden, returns TRUE; otherwise,

returns FALSE.

16                  A two-item horizontal array containing the width of the active

cell and a logical value indicating whether the cell's width is set to change as the standard width changes (TRUE) or is a custom width (FALSE).

17                  Row height of cell, in points.

18                  Name of font, as text.

19                  Size of font, in points.

20                  If all the characters in the cell, or only the first character, are bold, returns TRUE; otherwise, returns FALSE.

21                  If all the characters in the cell, or only the first character, are italic, returns TRUE; otherwise, returns FALSE.

22                  If all the characters in the cell, or only the first character, are underlined, returns TRUE; otherwise, returns FALSE.

23                  If all the characters in the cell, or only the first character, are struck through, returns TRUE; otherwise, returns FALSE.

24                  Font color of the first character in the cell, as a number in

the range 1 to 56. If font color is automatic, returns 0.

25                  If all the characters in the cell, or only the first character, are outlined, returns TRUE; otherwise, returns FALSE. Outline font format is not supported by Microsoft Excel for Windows.

26                  If all the characters in the cell, or only the first character, are shadowed, returns TRUE; otherwise, returns FALSE. Shadow font format is not supported by Microsoft Excel for Windows.

27                  Number indicating whether a manual page break occurs at

the cell: 

0  = No break

1  = Row

2  = Column

3  = Both row and column

28                  Row level (outline)

29                  Column level (outline).

30                  If the row containing the active cell is a summary row,

returns TRUE; otherwise, returns FALSE.

31                  If the column containing the active cell is a summary column,

returns TRUE; otherwise, returns FALSE.

32                  Name of the workbook and sheet containing the cell If the

window contains only a single sheet that has the same name as the workbook without its extension, returns only the name of the book, in the form . Otherwise, returns the name of the sheet in the form "[Book1]Sheet1".

33                  If the cell is formatted to wrap, returns TRUE; otherwise,

returns FALSE.

34                  Left-border color as a number in the range 1 to 56. If color is

automatic, returns 0.

35                  Right-border color as a number in the range 1 to 56. If color

is automatic, returns 0.

36                  Top-border color as a number in the range 1 to 56. If color is

automatic, returns 0.

37                  Bottom-border color as a number in the range 1 to 56. If

color is automatic, returns 0.

38                  Shade foreground color as a number in the range 1 to 56. If

color is automatic, returns 0.

39                  Shade background color as a number in the range 1 to 56. If

color is automatic, returns 0.

40                  Style of the cell, as text.

41                  Returns the formula in the active cell without translating it

(useful for international macro sheets).

42                  The horizontal distance, measured in points, from the left

edge of the active window to the left edge of the cell. May be a negative number if the window is scrolled beyond the cell.

43                  The vertical distance, measured in points, from the top edge

of the active window to the top edge of the cell. May be a negative number if the window is scrolled beyond the cell.

44                  The horizontal distance, measured in points, from the left

edge of the active window to the right edge of the cell. May be a negative number if the window is scrolled beyond the cell.

45                  The vertical distance, measured in points, from the top edge

of the active window to the bottom edge of the cell. May be a negative number if the window is scrolled beyond the cell.

46                  If the cell contains a text note, returns TRUE; otherwise,

returns FALSE.

47                  If the cell contains a sound note, returns TRUE; otherwise,

returns FALSE.

48                  If the cells contains a formula, returns TRUE; if a constant,

returns FALSE.

49                  If the cell is part of an array, returns TRUE; otherwise,

returns FALSE.

50                  Number indicating the cell's vertical alignment: 

1  = Top

2  = Center

3  = Bottom

4  = Justified

51                  Number indicating the cell's vertical orientation: 

0  = Horizontal

1  = Vertical

2  = Upward

3  = Downward

52                  The cell prefix (or text alignment) character, or empty text

("") if the cell does not contain one.

53                  Contents of the cell as it is currently displayed, as text,

including any additional numbers or symbols resulting from the cell's formatting.

54                  Returns the name of the PivotTable report containing the

active cell.

55                  Returns the position of a cell within the PivotTable report. 

0  = Row header

1  = Column header

2  = Page header

3  = Data header

4  = Row item

5  = Column item

6  = Page item

7  = Data item

8  = Table body

56                  Returns the name of the field containing the active cell

reference if inside a PivotTable report.

57                  Returns TRUE if all the characters in the cell, or only the first

character, are formatted with a superscript font; otherwise, returns FALSE.

58                  Returns the font style as text of all the characters in the cell,

or only the first character as displayed in the Font tab of the Format Cells dialog box: for example, "Bold Italic".

7                                          Returns the number for the underline style: 

1  = None

2  = Single

3  = Double

4  = Single accounting

5  = Double accounting

60                  Returns TRUE if all the characters in the cell, or only the first

character, are formatted with a subscript font; otherwise, it returns FALSE.

61                  Returns the name of the PivotTable item for the active cell,

as text.

62                  Returns the name of the workbook and the current sheet in

the form "[Book1]Sheet1".

63                  Returns the fill (background) color of the cell.

64                  Returns the pattern (foreground) color of the cell.

65                  Returns TRUE if the Add Indent alignment option is on (Far

East versions of Microsoft Excel only); otherwise, it returns FALSE.

66                  Returns the book name of the workbook containing the cell in the form .

Reference    is a cell or a range of cells from which you want information. 

•   If reference is a range of cells, the cell in the upper-left corner of the first range in reference is used.

•   If reference is omitted, the active cell is assumed. 

Tip   Use (17) to determine the height of a cell and (44) - (42) to determine the width.

Examples

The following macro formula returns TRUE if cell B4 on sheet Sheet1 is bold:

(20, Sheet1!$B$4)

You can use the information returned by to initiate an action. The following macro formula runs a custom function named BoldCell if the formula returns FALSE:

IF((20, Sheet1!$B$4), , BoldCell())

Related Functions

ABSREF   Returns the absolute reference of a range of cells to another range

   Returns the reference of the active cell

GET.FORMULA   Returns the contents of a cell

   Returns the definition of a name

   Returns characters from a note

RELREF   Returns a relative reference

Returns the vertical or horizontal position of a point on a chart item. Use these position numbers with and to change the position and size of chart items. Position is measured in points; a point is 1/72nd of an inch.

Syntax

(x_y_index, point_index, item_text)

X_y_index    is a number specifying which of the coordinates you want returned.

X_y_index

 

Coordinate returned

1        Horizontal coordinate

2        Vertical coordinate

Point_index    is a number specifying the point on the chart item. These indexes are described below. If point_index is omitted, it is assumed to be 1. 

•   If the specified item is a point, point_index must be 1.

•   If the specified item is any line other than a data line, use the following values for point_index.

Point_index

 

Chart item position

1         Lower or left

2         Upper or right

?      If the selected item is a legend, plot area, chart area, or an area in an area chart, use the following values for point_index.

Point_index

 

Chart item position

1         Upper left

2         Upper middle

3         Upper right

4         Right middle

5         Lower right

6         Lower middle

7         Lower left

8         Left middle

?      If the selected item is an arrow in Microsoft Excel 4.0, use the following values for point_index. In Microsoft Excel version 5.0 or later, arrows are named lines, and the arrowhead position returned is equivalent to the end of a line where the arrowhead begins.

Point_index

 

Chart item position

1         Arrow shaft

2         Arrowhead

                     ?       If the selected item is a pie slice, use the following values for point_index.

Point_index

 

Chart item position

1         Outermost counterclockwise point

2         Outer center point

3         Outermost clockwise point

4         Midpoint of the most clockwise radius

5         Center point

6         Midpoint of the most counterclockwise radius

Item_text    is a selection code that specifies which item of a chart to select. See the chart form of SELECT for the item_text codes to use for each item of a chart. 

•   If item_text is omitted, it is assumed to be the currently selected item.

•   If item_text is omitted and no item is selected, returns the #VALUE! error value.  

Remarks

If the specified item does not exist, or if a chart is not active when the function is carried out, the #VALUE! error value is returned.

Examples

The following macro formulas return the horizontal and vertical locations, respectively, of the top of the main-chart value axis:

(1, 2, "Axis 1")

(2, 2, "Axis 1")

You could then use to move a floating text item to the position returned by these two formulas.

Related Functions

GET.DOCUMENT   Returns information about a workbook

GET.FORMULA   Returns the contents of a cell

Returns the name, as text, that is defined for a particular area, value, or formula in a workbook. Use to get the name corresponding to a definition. To get the definition of a name, use .

Syntax

(def_text, document_text, type_num)

Def_text    can be anything you can define a name to refer to, including a reference, a value, an object, or a formula. 

•   References must be given in R1C1 style, such as "R3C5".

•   If def_text is a value or formula, it is not necessary to include the equal sign that is displayed in the Refers To box in the Define Name dialog box, which appears when you choose the Name command from the Define submenu on the Insert Menu.

•   If there is more than one name for def_text, returns the first name. If no name matches def_text, returns the #NAME? error value.

Document_text    specifies the sheet or macro sheet that def_text is on. If document_text is omitted, it is assumed to be the active macro sheet.

Type_num    is a number from 1 to 3 specifying which types of names are returned.

Type_num

 

Returns

1          or omitted Normal names only

2          Hidden names only

3          All names

Examples

If the specified range in Sheet4 is named Sales, the following macro formula returns "Sales":

("R2C2:R9C6", "Sheet4")

If the value 100 in Sheet4 is defined as Constant, the following macro formula returns "Constant":

("100", "Sheet4")

If the specified formula in Sheet4 is named SumTotal, the following macro formula returns "SumTotal":

("SUM(R1C1:R10C1)", "Sheet4")

If 3 is defined as the hidden name Counter on the active macro sheet, the following macro formula returns "Counter":

("3", , 2)

Related Functions

   Returns information about the specified cell

   Returns the definition of a name

   Returns characters from a note

NAMES   Returns the names defined on a workbook

GET.DOCUMENT

Returns information about a sheet in a workbook.

Syntax

GET.DOCUMENT(type_num, name_text)

Type_num    is a number that specifies what type of information you want. The following lists show the possible values of type_num and the corresponding results.

Type_num

 

Returns

1                     Returns the name of the workbook and worksheet as

text. If there is only one sheet in the workbook and the sheet name is the same as the workbook name less any extension, returns the name of the book. The book name does not include the drive, directory or folder, or window number. Otherwise, returns the book and sheet name in the form "[]Sheet1". It is usually best to use GET.DOCUMENT(76) and GET.DOCUMENT(88) to return the name of the active worksheet and the active workbook.

2                     Path of the directory or folder containing name_text, as

text. If the workbook name_text hasn't been saved yet, returns the #N/A error value.

3                     Number indicating the type of sheet. If name_text is a

sheet, then the return value is one of the following numbers. If name_text is a book, then the return value is always 5. If name_text is omitted, then the sheet type is returned. If the book has one sheet that is named the same as the book, then the sheet type is returned. 

1  = Worksheet

2  = Chart

3  = Macro sheet

4  = Info window if active

5  = Reserved

6  = Module

7  = Dialog

4                     If changes have been made to the sheet since it was last

saved, returns TRUE; otherwise, returns FALSE.

5                     If the sheet is read-only, returns TRUE; otherwise,

returns FALSE.

6                     If the sheet is password protected, returns TRUE;

otherwise, returns FALSE.

7                     If cells in a sheet, the contents of a sheet, or the series in

a chart are protected, returns TRUE; otherwise, returns FALSE.

8                     If the workbook windows are protected, returns TRUE;

otherwise, returns FALSE.

The next four values of type_num apply only to charts.

Type_num

 

Returns

9                     Number indicating the type of the main chart: 

1  = Area

2  = Bar

3  = Column

4  = Line

5  = Pie

6  = XY (scatter)

7  = 3-D area

8  = 3-D column

9  = 3-D line

10  = 3-D pie

11  = Radar

12  = 3-D bar

13  = 3-D surface

14  = Doughnut

10                     Number indicating the type of the overlay chart. Same as

1, 2, 3, 4, 5, 6, 11, and 14 for main chart above. If there is no overlay chart, returns the #N/A error value.

11                     Number of series in the main chart.

12                     Number of series in the overlay chart.

The next values of type_num apply to worksheets and macro sheets and to charts when appropriate.

Type_num

 

Returns

9                     Number of the first used row. If the sheet is empty,

returns 0.

10                  Number of the last used row. If the sheet is empty,

returns 0.

11                  Number of the first used column. If the sheet is empty,

returns 0.

12                  Number of the last used column. If the sheet is empty,

returns 0.

13                  Number of windows.

14                  Number indicating calculation mode: 

1  = Automatic

2  = Automatic except tables

3  = Manual

15                  If the Iteration check box is selected in the Calculation tab

of the Options dialog box, returns TRUE; otherwise, returns FALSE.

16                  Maximum number of iterations.

17                  Maximum change between iterations.

18                  If the Update Remote References check box is selected in

the Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

19                  If the Precision As Displayed check box is selected in the

Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

20                  If the 1904 Date System check box is selected in the

Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

Type_num values of 21 through 29 correspond to the four default fonts in previous versions of Microsoft Excel. These values are provided only for macro compatibility.

The next values of type_num apply to worksheets and macro sheets, and to charts if indicated.

Type_num

 

Returns

30                  Horizontal array of consolidation references for the current

sheet, in the form of text. If the list is empty, returns the #N/A error value.

31                  Number from 1 to 11, indicating the function used in the

current consolidation. The function that corresponds to each number is listed under the CONSOLIDATE function. The default function is SUM.

32                  Three-item horizontal array indicating the status of the

check boxes in the Data Consolidate dialog box. An item is TRUE if the check box is selected or FALSE if the check box is cleared. The first item indicates the Top Row check box, the second the Left Column check box, and the third the Create Links To Source Data check box.

33                  If the Recalculate Before Save check box is selected in the

Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

34                  If the workbook is read-only recommended, returns TRUE;

otherwise, returns FALSE.

35                  If the workbook is write-reserved, returns TRUE;

otherwise, returns FALSE.

36                  If the workbook has a write-reservation password and it is

opened with read/write permission, returns the name of the user who originally saved the file with the writereservation password. If the file is opened as read-only, or if a password has not been added to the workbook, returns the name of the current user.

37                  Number corresponding to the file type of the workbook as

displayed in the Save As dialog box. See the function for a list of all the file types that Microsoft Excel recognizes.

38                  If the Summary Rows Below Detail check box is selected

in the Outline dialog box, returns TRUE; otherwise, returns FALSE.

39                  If the Summary Columns To Right Of Detail check box is

selected in the Outline dialog box, returns TRUE; otherwise, returns FALSE.

40                  If the Always Create Backup check box is selected in the

Save Options dialog box, returns TRUE; otherwise, returns FALSE.

41                  Number from 1 to 3 indicating whether objects are

displayed: 

1  = All objects are displayed

2  = Placeholders for pictures and charts

3  = All objects are hidden

42                  Horizontal array of all objects in the sheet. If there are no

objects, returns the #N/A error value.

43                  If the Save External Link Values check box is selected in

the Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

44                  If objects in a workbook are protected, returns TRUE;

otherwise, returns FALSE.

45                  A number from 0 to 3 indicating how windows are

synchronized:

0  = Not synchronized

1  = Synchronized horizontally

2  = Synchronized vertically

3  = Synchronized horizontally and vertically

46                  A seven-item horizontal array of print settings that can be

set by the LINE.PRINT macro function: 

Setup text

Left margin

Right margin

Top margin

Bottom margin

Page length

A logical value indicating whether output will be formatted

(TRUE) or unformatted (FALSE) when printed

47                  If the Transition Formula Evaluation check box is selected

in the Transition tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

48                  The standard column width setting.

The next values of type_num correspond to printing and page settings.

Type_num

 

Returns

49                  The starting page number, or the #N/A error value if none

is specified or if "Auto" is entered in the First page Number text box on the Page tab of the Page Setup dialog box.

50                  The total number of pages that would be printed based on

current settings, excluding notes, or 1 if the document is a chart.

51                  The total number of pages that would be printed if you

print only notes, or the #N/A error value if the document is a chart.

52                  Four-item horizontal array indicating the margin settings

(left, right, top, bottom) in the currently specified units.

53                  A number indicating the orientation: 

1  = Portrait

2  = Landscape

54                  The header as a text string, including formatting codes.

55                  The footer as a text string, including formatting codes.

56                  Horizontal array of two logical values corresponding to

horizontal and vertical centering.

57                  If row or column headings are to be printed, returns

TRUE; otherwise, returns FALSE.

58                  If gridlines are to be printed, returns TRUE; otherwise,

returns FALSE.

59                  If the sheet is printed in black and white only, returns

TRUE; otherwise, returns FALSE.

60                  A number from 1 to 3 indicating how the chart will be

sized when it's printed: 

1  = Size on screen

2  = Scale to fit page

3  = Use full page

61                  A number indicating the pagination order: 

1  = Down, then over 2 = Over, then down

Returns the #N/A error value if the document is a chart.

62                  Percentage of reduction or enlargement, or 100% if none

is specified. Returns the #N/A error value if not supported by the current printer or if the document is a chart.

63                  A two-item horizontal array indicating the number of pages to which the printout should be scaled to fit, with the first item equal to the width (or #N/A if no width scaling is specified) and the second item equal to the height (or #N/A if no height scaling is specified). #N/A is also returned if the document is a chart.

64                  An array of row numbers corresponding to rows that are

immediately below a manual or automatic page break.

65                  An array of column numbers corresponding to columns

that are immediately to the right of a manual or automatic page break.

Note   GET.DOCUMENT(62) and GET.DOCUMENT(63) are mutually exclusive. If one returns a value, then the other returns the #N/A error value.

The next values of type_num correspond to various workbook settings.

Type_num

 

Returns

66                  In Microsoft Excel for Windows, if the Transition Formula

Entry check box is selected in the Transition tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

67                  Microsoft Excel version 5.0 or later always returns TRUE

here.

68                  Microsoft Excel version 5.0 or later always returns the

book name.

69                  Returns TRUE if Page Breaks is chosen in the View tab of

the Options dialog box; otherwise, returns FALSE.

70                  Returns the names of all PivotTable reports in the current

sheet as a horizontal array.

71                  Returns an horizontal array of all the styles in a workbook. 72 Returns an horizontal array of all chart types displayed on

the current sheet.

73                  Returns an array of the number of series in each chart of

the current sheet.

74                  Returns the object ID of the control that currently has the

focus on a running user-defined dialog (based on the dialog sheet).

75                  Returns the object ID of the object that is the current

default button on a running user-defined dialog (based on the dialog sheet).

76                  Returns the name of the active sheet or macro sheet in

the form [Book1]Sheet1.

77                  In Microsoft Excel for Windows, returns the paper size, as

integer: 

1  = Letter 8.5 x 11 in

2  = Letter Small 8.5 x 11 in

5 = Legal 8.5 x 14 in

9  = A4 210 x 297 mm

10  = A4 Small 210 x 297 mm

13 = B5 182 x 257 mm

18 = Note 8.5 x 11 in

78                  Returns the print resolution, as a horizontal array of two numbers.

79                  Returns TRUE if the Draft Quality check box has been

selected from the sheet tab in the Page Setup dialog box; otherwise, returns FALSE.

80                  Returns TRUE if the Comments checkbox has been

selected on the Sheet tab in the Page Setup dialog box; otherwise, returns FALSE.

81                  Returns the Print Area from the Sheet tab of the Page

Setup dialog box as a cell reference.

82                  Returns the Print Titles from the Sheet tab of the Page

Setup dialog box as an array of cell references.

83                  Returns TRUE if the worksheet is protected for scenarios;

otherwise, returns FALSE.

84                  Returns the value of the first circular reference on the

sheet, or #N/A if there are no circular references.

85                  Returns the advanced filter mode state of the sheet. This

is the mode without drop-down arrows on top. Returns TRUE if the list has been filtered by clicking Filter, then Advanced Filter on the Data menu. Otherwise, returns FALSE.

86                  Returns the automatic filter mode state of the sheet. This

is the mode with drop-down arrows on top. Returns TRUE if you have chosen Filter, then AutoFilter from the Data menu and the filter drop-down arrows are displayed. Otherwise, returns FALSE.

87                  Returns the position number of the sheet. The first sheet

is position 1. Hidden sheet are included in the count.

88                  Returns the name of the active workbook in the form

"Book1".

Name_text    is the name of an open workbook. If name_text is omitted, it is assumed to be the active workbook.

Examples

The following macro formula returns TRUE if the contents of the active workbook are protected:

GET.DOCUMENT(7)

In Microsoft Excel for Windows, the following macro formula returns the number of windows in :

GET.DOCUMENT(13, "")

In Microsoft Excel for the Macintosh, the following macro formula returns 3 if the overlay chart on SALES CHART is a column chart:

GET.DOCUMENT(10, "SALES CHART")

To find out if SHEET1 is password-protected and if its contents and windows are protected, enter the following formula in a three-cell horizontal array:

GET.DOCUMENT({6, 7, 8}, "SHEET1")

Related Functions

   Returns information about the specified cell

GET.WINDOW   Returns information about a window

GET.WORKSPACE   Returns information about the workspace

GET.FORMULA

Returns the contents of a cell as they would appear in the formula bar. The contents are given as text, for example, "=2*PI()/360". If the formula contains references, they are returned as R1C1-style references, such as "=RC[1]*(1+R1C1)". Use GET.FORMULA to get a formula from a cell in order to edit its arguments. Use (6) to get a formula in either A1 or R1C1 format, depending on the workspace setting.

Syntax

GET.FORMULA(reference)

Reference    is a cell or range of cells on a sheet or macro sheet. 

•   If a range of cells is selected, GET.FORMULA returns the contents of the upperleft cell in reference.

•   Reference can be an external reference.

•   Reference can be the object identifier of a picture created by the camera tool.

•   Reference can also be a reference to a chart series in the form "Sn" where n is the number of the series. When a chart series is specified, GET.FORMULA returns the series formula using R1C1-style references.

Tip   If you want to get the formula in the active cell, use the function as the reference argument.

Examples

If cell A3 on the active sheet contains the number 523, then:

GET.FORMULA(!$A$3) equals "523"

If cell C2 on the active sheet contains the formula =B2*(1+$A$1), then:

GET.FORMULA(!$C$2) equals "=RC[-1]*(1+R1C1)"

The following macro formula returns the contents of the active cell on the active sheet:

GET.FORMULA(())

Related Functions

   Returns information about the specified cell

Returns a name matching a definition    Returns the definition of a name

   Returns characters from a comment

Returns information about the specified link. Use to get information about the update settings of a link.

Syntax

(link_text, type_num, type_of_link, reference)

Link_text    is the path of the link as displayed in the Links dialog box, which appears when you choose the Links command from the Edit menu. The path to the file you wish to return DDE information on must be surrounded by single quotes.

Type_num    is a number that specifies what type of information about the currently selected link to return. Type_num 2 applies only to publishers and subscribers in Microsoft Excel for the Macintosh.

Type_num

 

Returns

1          If the link is set to automatic update, returns 1; otherwise 2.

2          Date of the latest edition as a serial number. Returns #N/A if link_text is not a publisher or a subscriber.

Type_of_link    is a number from 1 to 6 that specifies what type of link you want to get information about.

Type_of_link

 

Link document type

1           Not applicable

2           DDE link (Microsoft Windows)

3           Not applicable

4           Not applicable

5           Publisher (Macintosh)

6           Subscriber (Macintosh)

Reference    specifies the cell range in R1C1 format of the publisher or subscriber that you want information about. Reference is required if you have more than one publisher or subscriber of a single edition name on the active workbook. Use reference to specify the location of the subscriber you want to return information about. If the subscriber is a picture, or if the publisher is an embedded chart, reference is the number of the object as displayed in the Name box.

Remarks 

•    If Microsoft Excel cannot find link_text, or if type_of_link does not match the link specified by link_text, returns the #VALUE! error value.

•    If you have more than one subscriber to the edition link_text or if the same area is published more than once, you must specify reference.  

Example

In Microsoft Excel for Windows, the following macro formula returns information about a DDE link to a Microsoft Word for Windows document. The document is named .

("WinWord|'C:\WINWORD\'!DDE_LINK1", 1, 2)

In Microsoft Excel for the Macintosh, the following macro formula returns information about a link to a publisher defined in cells A1:C3 on a workbook named New Products.

("A1:C3 New Products Edition #1", 2, 5, "'New Products'!R1C1:R3C3")

Related Functions

CREATE.PUBLISHER   Creates a publisher from the selection

   Inserts contents of an edition into the active workbook

   Updates a link to another workbook

Returns the definition of a name as it appears in the Refers To box of the Define Name dialog box, which appears when you choose the Define command from the Name submenu on the Insert menu. If the definition contains references, they are given as R1C1-style references. Use to check the value defined by a name. To get the name corresponding to a definition, use .

Syntax

(name_text, info_type)

Name_text    can be a name defined on the macro sheet; an external reference to a name defined on the active workbook, for example, "!Sales"; or an external reference to a name defined on a particular open workbook, for example, "[Book1]SHEET1!Sales". Name_text can also be a hidden name.

Info_type     specifies the type of information to return about the name. If 1 or omitted, the definition is returned. If 2, returns TRUE if the name is defined for just the sheet, FALSE if the name is defined for the entire workbook.

Remarks

If the Contents check box has been selected in the Protect Sheet dialog box to protect the workbook containing the name, returns the #N/A error value. To see the Protect Sheet dialog box, choose the Protect Sheet command on the Protection submenu from the Tools menu.

Examples

If the name Sales on a macro sheet is defined as the number 523, then:

("Sales") equals "=523"

If the name Profit on the active sheet is defined as the formula =Sales-Costs, then:

("!Profit") equals "=Sales-Costs"

If the name Database on the active sheet is defined as the range A1:F500, then:

("!Database") equals "=R1C1:R500C6"

Related Functions

   Defines a name on the active or macro sheet

   Returns information about the specified cell

   Returns a name matching a definition

NAMES   Returns the names defined in a workbook

   Defines a name as a value

Returns characters from a comment.

Syntax

(cell_ref, start_char, num_chars)

Cell_ref    is the cell to which the note is attached. If cell_ref is omitted, the comment attached to the active cell is returned.

Start_char    is the number of the first character in the comment to return. If start_char is omitted, it is assumed to be 1, the first character in the comment.

Num_chars    is the number of characters to return. Num_chars must be less than or equal to 255. If num_chars is omitted, it is assumed to be the length of the comment attached to cell_ref.

Examples

The following macro formula returns the first 200 characters in the comment attached to cell A3 on the active sheet:

(!$A$3, 1, 200)

In Microsoft Excel for Windows, the following macro formula returns the 10th through the 39th characters of the comment attached to cell C2 on :

("[]Sheet1!R2C3", 10, 30)

In Microsoft Excel for the Macintosh, the following macro formula returns the 10th through the 39th characters of the comment attached to cell C2 on SALES:

("[SALES]Sheet1!R2C3", 10, 30)

Use with the NOTE function to move the contents of a comment to a cell or text box or to another comment attached to a cell:

NOTE((!$B$10),())

Related Functions

   Returns information about the specified cell

NOTE   Creates or changes a comment.

GET.OBJECT

Returns information about the specified object. Use GET.OBJECT to return information you can use in other macro formulas that manipulate objects.

Syntax

GET.OBJECT(type_num, object_id_text, start_num, count_num, item_index)

Type_num    is a number specifying the type of information you want returned about an object. GET.OBJECT returns the #VALUE! error value (and the macro is halted) if an object isn't specified or if more than one object is selected.

Type_num

 

Returns

2            If the object is locked, returns TRUE; otherwise FALSE.

3            Z-order position (layering) of the object; that is, the relative position of the overlapping objects, starting with 1 for the object that is most under the others.

4            Reference of the cell under the upper-left corner of the object as text in

R1C1 reference style; for a line or arc, returns the start point.

5            X offset from the upper-left corner of the cell under the upper-left corner of the object, measured in points.

6            Y offset from the upper-left corner of the cell under the upper-left corner of the object, measured in points.

7            Reference of the cell under the lower-right corner of the object as text in R1C1 reference style; for a line or arc, returns the end point.

8            X offset from the upper-left corner of the cell under the lower-right corner of the object, measured in points.

9            Y offset from the upper-left corner of the cell under the lower-right corner of the object, measured in points.

10            Name, including the filename, of the macro assigned to the object. If no macro is assigned, returns FALSE.

11            Number indicating how the object moves and sizes:

1  = Object moves and sizes with cells

2  = Object moves with cells

3  = Object is fixed

Values 12 to 21 for type_num apply only to text boxes and buttons. If another type of object is selected, GET.OBJECT returns the #VALUE! error value.

 

Type_num

 

Returns

12            Text starting at start_num for count_num characters.

13            Font name of all text starting at start_num for count_num characters. If the text contains more than one font name, returns the #N/A error value.

14            Font size of all text starting at start_num for count_num characters. If the text contains more than one font size, returns the #N/A error value.

15            If all text starting at start_num for count_num characters is bold, returns TRUE. If text contains only partial bold formatting, returns the #N/A error value.

16            If all text starting at start_num for count_num characters is italic, returns TRUE. If text contains only partial italic formatting, returns the #N/A error value.

17            If all text starting at start_num for count_num characters is underlined, returns TRUE. If text contains only partial underline formatting, returns the #N/A error value.

18            If all text starting at start_num for count_num characters is struck through, returns TRUE. If text contains only partial struck-through formatting, returns the #N/A error value.

19            In Microsoft Excel for the Macintosh, if all text starting at start_num for count_num characters is outlined, returns TRUE. If text contains only partial outline formatting, returns the #N/A error value. Always returns FALSE in Microsoft Excel for Windows.

20            In Microsoft Excel for the Macintosh, if all text starting at start_num for

count_num characters is shadowed, returns TRUE. If text contains only partial shadow formatting, returns the #N/A error value. Always returns FALSE in Microsoft Excel for Windows.

21            Number from 0 to 56 indicating the color of all text starting at start_num for count_num characters; if color is automatic, returns 0. If more than one color is used, returns the #N/A error value.

Values 22 to 25 for type_num also apply only to text boxes and buttons. If another type of object is selected, GET.OBJECT returns the #N/A error value.

Type_num

 

Returns

23          Number indicating the vertical alignment of text:

1  = Top

2  = Center

3  = Bottom

4  = Justified

24          Number indicating the orientation of text:

0  = Horizontal

1  = Vertical

2  = Upward

3  = Downward

25          If button or text box is set to automatic sizing, returns TRUE; otherwise FALSE.

The following values for type_num apply to all objects, except where indicated.

Type_num

 

Returns

27          Number indicating the type of the border or line:

0  = Custom

1  = Automatic

2  = None

28          Number indicating the style of the border or line as shown in the Patterns tab in the Format Objects dialog box:

0  = None

1  = Solid line

2  = Dashed line

3  = Dotted line

4  = Dashed dotted line

5  = Dashed double-dotted line

6  = 50% gray line

7  = 75% gray line

8  = 25% gray line

29          Number from 0 to 56 indicating the color of the border or line; if the border is automatic, returns 0.

30          Number indicating the weight of the border or line:

1  = Hairline

2  = Thin

3  = Medium

4  = Thick

31          Number indicating the type of fill:

0  = Custom

1  = Automatic

2  = None

32          Number from 1 to 18 indicating the fill pattern as shown in the Format Object dialog box.

33          Number from 0 to 56 indicating the foreground color of the fill pattern; if the fill is automatic, returns 0. If the object is a line, returns the #N/A error value.

34          Number from 0 to 56 indicating the background color of the fill pattern; if the fill is automatic, returns 0. If the object is a line, returns the #N/A error value.

35          Number indicating the width of the arrowhead:

1  = Narrow

2  = Medium

3  = Wide

If the object is not a line, returns the #N/A error value.

36          Number indicating the length of the arrowhead:

1  = Short

2  = Medium

3  = Long

If the object is not a line, returns the #N/A error value.

37          Number indicating the style of the arrowhead:

1  = No head

2  = Open head

3  = Closed head

4  = Open double-ended head

5  = Closed double-ended head

If the object is not a line, returns the #N/A error value.

38          If the border has round corners, returns TRUE; if the corners are square, returns FALSE. If the object is a line, returns the #N/A error value.

39          If the border has a shadow, returns TRUE; if the border has no shadow, returns FALSE. If the object is a line, returns the #N/A error value.

40          If the Lock Text check box in the Protection Tab of the Format Object dialog box is selected, returns TRUE; otherwise FALSE.

41          If objects are set to be printed, returns TRUE; otherwise FALSE.

42          The horizontal distance, measured in points, from the left edge of the active window to the left edge of the object. May be a negative number if the window is scrolled beyond the object.

43          The vertical distance, measured in points, from the top edge of the active window to the top edge of the object. May be a negative number if the window is scrolled beyond the object.

44          The horizontal distance, measured in points, from the left edge of the active window to the right edge of the object. May be a negative number if the window is scrolled beyond the object.

45          The vertical distance, measured in points, from the top edge of the active window to the bottom edge of the object. May be a negative number if the window is scrolled beyond the object.

46          The number of vertices in a polygon, or the #N/A error value if the object is not a polygon.

47          A count_num by 2 array of vertex coordinates starting at start_num in a polygon's array of vertices.

48          If the object is a text box, returns the cell reference that the text box is linked to. If the object is a control on a worksheet, returns the cell reference that the control's value is linked to. This information is returned as a string.

49          Returns the ID number of the object. For example, "Rectangle 5" returns

5. Note that the name of the object may not have this index in it if the object has been renamed by the user.

50          Returns the object's classname. For example, "Rectangle".

51          Returns the object name. By default, object names are the classname

followed by the ID. For example, "Rectangle 1" is an object name, of which "Rectangle" is the classname, and 1 is the ID number. The object can also be renamed, in which case the name picked by the user is returned.

52          Returns the distance from cell A1 to the Left of the object bounding rectangle in points

53          Returns the distance from Cell A1 to the top of the object bounding rectangle in points

54          Returns the width of object bounding rectangle in points

55          Returns the height of object bounding rectangle in points 56        If the object is enabled, returns TRUE; otherwise, it returns FALSE.

57          Returns the shortcut key assignment for the control object, as text.

58          Returns TRUE is the button control on a dialog sheet is the default button of the dialog; otherwise, returns FALSE

59          Returns TRUE if the button control on the dialog sheet is clicked when the user presses the ESCAPE Key; otherwise, returns FALSE.

60          Returns TRUE if the button control on a dialog sheet will close the dialog box when pressed; otherwise, returns FALSE

61          Returns TRUE if the button control on a dialog sheet will be clicked when the user presses F1.

62          Returns the value of the control. For a check box or radio button, Returns

1  if it is selected, zero if it is not selected, or 2 if mixed. For a List box or dropdown box, returns the index number of the selected item, or zero if no item is selected. For a scroll bar, returns the numeric value of the scroll bar.

63          Returns the minimum value that a scroll bar or spinner button can have

64          Returns the maximum value that a scroll bar or spinner button can have

65          Returns the step increment value added or subtracted from the value of a scroll bar or spinner. This value is used when the arrow buttons are pressed on the control.

66          Returns the large, or "page" step increment value added or subtracted from the value of a scroll bar when it is clicked in the region between the thumb and the arrow buttons.

67          Returns the input type allowed in an edit box control:

1  = Text

2  = Integer

3  = Number (what type)

4  = Cell reference

5  = Formula

68          Returns TRUE if the edit box control allows multi-line editing with wrapped text; otherwise, it returns FALSE.

69          Returns TRUE if the edit box has a vertical scroll bar; otherwise, it returns FALSE.

70          Returns the object ID of the object that is linked to a list box or edit box. For a dropdown combo box that has an editable entry field, returns the object ID of itself. A dropdown box that can't be edited, returns FALSE.

71          Returns the number of entries in a List box, dropdown List box, or dropdown combo box.

72          Returns the text of the selected entry in a List box, dropdown List box, or dropdown combo box.

73          Returns the range used to fill the entries in a List box, dropdown List box, or dropdown combo box, as text. If an empty string is returned, then the control isn't filled from a range.

74          Returns the number of list lines displayed when a dropdown control is dropped.

75          Returns TRUE the object is displayed as 3-D; otherwise, it returns FALSE.

76          Returns the Far East phonetic accelerator key as text. Used for Far East versions of Microsoft Excel.

77          Returns the select status of the list box:

0  = single

1  = simple multi-select

2  = extended multi-select

78          Returns an array of TRUE and FALSE values indicating which items are

selected in a list box. If TRUE, the item is selected; If FALSE, the item is not selected.

79          Returns TRUE if the add indent attribute is on for alignment. Returns FALSE if the add indent attribute is off for alignment. Used for only Far East versions of Microsoft Excel.

Object_id_text    is the name and number, or number alone, of the object you want information about. Object_id_text is the text displayed in the reference area when the object is selected. If object_id_text is omitted, it is assumed to be the selected object. If object_id_text is omitted and no object is selected, GET.OBJECT returns the #REF! error value and interrupts the macro.

Start_num    is the number of the first character in the text box or button or the first vertex in a polygon you want information about. Start_num is ignored unless a text box, button, or polygon is specified by type_num and object_id_text. If start_num is omitted, it is assumed to be 1.

Count_num    is the number of characters in a text box or button, or the number of vertices in a polygon, starting at start_num, that you want information about. Count_num is ignored unless a text box, button, or polygon is specified by type_num and object_id_text. If count_num is omitted, it is assumed to be 255.

Item_index    is the index number or position of the item in the list box or drop-down box that you want information about, ranging from 1 to the number of items in the list box or drop-down box.

Tip   Use GET.OBJECT(45) - GET.OBJECT(43) to determine the height of an object and GET.OBJECT(44) - GET.OBJECT(42) to determine the width.

Examples

The following macro formula returns the reference of the cell under the upper-left corner of the object Oval 3 (assume the cell is E2):

GET.OBJECT(4, "Oval 3") returns "R2C5"

The following macro formula changes the protection status of the object Rectangle 2 if it is locked:

IF(GET.OBJECT(2, "Rectangle 2"), OBJECT.PROTECTION(FALSE))

The following macro formula returns characters 25 through 185 from the object Text 5:

GET.OBJECT(12, "Text 5", 25, 160)

Related Functions

CREATE.OBJECT   Creates an object

FONT.PROPERTIES   Applies a font to the selection

OBJECT.PROTECTION   Controls how an object is protected

PLACEMENT   Determines an object's relationship to underlying cells

GET.PIVOT.FIELD

Returns information about a field in a PivotTable report.

Syntax

GET.PIVOT.FIELD(type_num, pivot_field_name, pivot_table_name)

Type_num    is a value from 1 to 17 that returns the following types of information:

Type_num

 

Value



1          Returns an array of all the items which make up pivot_field_name. The array is made up of text constants, dates or numbers depending on the field.

2          Returns an array of all items which are set to show with the pivot_field_name. The array is made up of text constants, dates or numbers depending on the field. The array is returned in the order that the items are displayed in the PivotTable report. If pivot_field_name is a page field, then the array contains only one element, the value corresponding to the active page (this could be all if the All item is showing).

3          Returns an array of all items which are hidden in the pivot_field_name. The array is made up of text constants, dates or numbers depending on the field. If pivot_field_name is a data field or the data header name, this function returns the #N/A! error value.

4          Returns an integer describing where the field is displayed in the active PivotTable report (either row or column): 

0  = Hidden

1  = Row

2  = Col

3  = Page

4  = Data

5          Returns an array of all items in pivot_field_name that are group parents. The array is made up of text constants, dates or numbers depending on the field. The array is returned in the order which these items appear in the PivotTable report. Returns #N/A if there are no group parents and if the pivot_field_name is a data field or the data field header.

6          Returns a number between 0 and 4095 which describes the subtotals attached to the field. The number is the sum of the values associated with each subtotal function. See PIVOT.FIELD.PROPERTIES for a list of all the values associated with subtotal calculations. If the field is showing as a data field or data field header, #N/A! is returned.

7          Returns an integer describing the type of data contained in the field:  

0  = Text

1  = Number

2  = Date

8          Returns an array five columns wide and one row high describing the summary function's custom calculation shown with the specified field (Data field) in the PivotTable report. The array will look as follows: {function, calculation, base field, base item, number format}. If pivot_field_name is not showing in the active PivotTable report as a data field, #N/A! is returned.

9          Returns a reference to all of pivot_field_name's items currently showing in the active PivotTable report. If pivot_field_name is hidden, #N/A! is returned. If pivot_field_name is a page field, the reference to the currently showing page item is returned. If pivot_field_name is a data field, a reference to all the data for this field in the PivotTable report is returned. The references are returned as text.

10          Returns a reference to the header cell for pivot_field_name. If pivot_field_name is a data field, a reference to all the headers in the data row or column is returned. If pivot_field_name is hidden, #N/A! is returned. The reference is returned as text.

11          Returns the number of grouped fields in the grouped field set which includes pivot_field_name. If pivot_field_name is neither a parent field nor a child field, 1 is returned. If pivot_field_name is a data field or data header name, the function returns the #N/A! error value.

12          Returns the level of pivot_field_name in the grouped field set which includes pivot_field_name. Returns 1 for the highest level parent field, 2 for its child field, and so on. If pivot_field_name is neither a parent field nor a child field, 1 is returned. If pivot_field_name is a data field or data header name, the function returns the #N/A! error value.

13          Returns the name of the parent field for pivot_field_name as a text

constant. If pivot_field_name is not a child field, #N/A! is returned.

14          Returns the name of the child field for pivot_field_name as a text constant. If pivot_field_name is not a parent field, #N/A! is returned.

15          Returns a text constant representing the original name of the field in the data source.

16          Returns the position of the field among all the other fields in its orientation. For instance, a 1 would be returned if the field was the first row field.

17          Returns an array of all items in pivot_field_name that are group children. The array is made up of text constants, dates or numbers depending on the field. The array is returned in the order which these items appear in the PivotTable report. Returns #N/A if there are no group children, and if the pivot_field_name is a data field or the data field header.

Pivot_field_name    is the name of the field that you want information about. If there is no field named pivot_field_name in the PivotTable report, returns #VALUE!.

Pivot_table_name    is the name of a PivotTable report containing the field that you want information about. If omitted, the PivotTable report containing the active cell is used. If the active cell is not in a PivotTable report, the #VALUE! error value is returned.

Related Functions

   Returns information about an item in a PivotTable report.

GET.PIVOT.TABLE   Returns information about a PivotTable report.

Returns information about an item in a PivotTable report.

Syntax

(type_num, pivot_item_name, pivot_field_name, pivot_table_name)

Type_num    is a value from 1 to 9 the represents the type of information you want about an item in a PivotTable report.

Type_num

 

Information

1          Returns the position of the item in its field. Returns #N/A if

pivot_field_name is a data field. Returns #N/A! if the item is hidden.

2          Returns the reference to all the cells in the PivotTable header currently containing pivot_item_name. This reference is returned as text. If pivot_item_name is currently not showing in the PivotTable report, #N/A! is returned.

3          Returns the reference to all the data in the PivotTable report which is qualified by pivot_item_name. This reference is returned as text. If pivot_item_name is currently not showing in the PivotTable report, #N/A! is returned.

4          Returns an array of text constants representing the children of pivot_item_name if pivot_item_name is a parent. Otherwise the function returns #N/A!.

5          Returns a text constant representing the parent of pivot_item_name, if pivot_item_name exists as part of a group. Otherwise the function returns #N/A!.

6          Returns TRUE if pivot_item_name is a member of a group which is currently expanded to show detail. Returns FALSE if pivot_item_name is a member of a group currently collapsed to hide detail. If pivot_item_name is not a member of a group, the function returns #N/A!.

7          Returns TRUE if pivot_item_name is expanded to show detail. Returns

FALSE if pivot_item_name is collapsed to hide detail.

8          Returns TRUE if the item pivot_item_name is currently visible, FALSE if it is hidden.

9          Returns the name of the item as it appeared in the original at a source. This will differ from the current item name only if the user changes the name of the item after creating the PivotTable report.

Pivot_item_name    is the name of the item that you want information about. If there is no item named pivot_item_name in the PivotTable report, returns #VALUE!.

Pivot_field_name    is the name of the field that you want information about. If there is no field named pivot_field_name in the PivotTable report, returns #VALUE!.

Pivot_table_name    is the name of a PivotTable report containing the field that you want information about. If omitted, uses the PivotTable report containing the active cell. If the active cell is not in a PivotTable report, the #VALUE! error value is returned.

Related Functions

GET.PIVOT.FIELD   Returns information about an item in a PivotTable report.

GET.PIVOT.TABLE   Returns information about a PivotTable report.

GET.PIVOT.TABLE

Returns information about a PivotTable report.

Syntax

GET.PIVOT.TABLE(type_num,pivot_table_name)

Type_num is a value from 1 to 22 that represents a type of information you want about a PivotTable report.

Type_num

 

Information

1                   Returns the name of the person who last updated the

PivotTable report, as a text constant.

2                   Returns the date the PivotTable report was last updated, as

a serial number.

3                   Returns a horizontal array of text constants representing all

the fields in the PivotTable report.

4                   Returns an integer representing the number of fields in the

PivotTable report.

5                   Returns a horizontal array of text constants representing all

the visible fields in the PivotTable report (rows, columns, pages or data)

6                   Returns a horizontal array of text constants representing all

the hidden fields in the PivotTable report. Return #N/A if no hidden fields.

7                   Returns a horizontal array of text constants representing

the names of all the fields currently showing in the PivotTable report as row fields. Returns #N/A if there are no row fields.

8                   Returns a horizontal array of text constants representing all

the fields currently showing in the PivotTable report as column fields. Returns #N/A if no column fields exist. 9     Returns a horizontal array of text constants representing all

the fields currently showing in the PivotTable report as page fields. Return #N/A if no page fields exist.

10                   Returns a horizontal array of text constants representing all

the fields currently showing in the PivotTable report as data fields. Returns #N/A if there are no data fields.

11                   Returns the smallest rectangular reference which bounds

the PivotTable report and all headers (not including the page header). This reference is returned as text.

12                   Returns the smallest rectangular reference which bounds

the PivotTable report and all headers (including the page headers). This reference is returned as text.

13                   Returns the reference to the row header area as text. The

row header area includes each row field header along with all the items in each row field. Returns #N/A if there are no row headers.

14                   Returns the reference to the column header area as text.

The column header area includes each column field header along with all the items in each column field. Returns #N/A if there are no column headers.

15                   Returns the reference to the data header area as text. The

data header area includes the data field header along with all the headers in the data row/col. Returns #N/A if there is no data field.

16                   Returns a reference to all the page headers as text.

17                   Returns the reference to the PivotTable report data area as

text.

18                   Returns TRUE if the PivotTable report is set to show row

grand totals.

19                   Returns TRUE if the PivotTable report is set to show column

grand totals.

20                   Returns TRUE if the user is saving data with the PivotTable

report.

21                   Returns TRUE if the PivotTable report is set up to

Autoformat on pivoting.

22                   Returns the data source of the PivotTable report. The kind of information returned depends on the data source: 

If the data source is a Microsoft Excel list or database, the cell reference is returned as text.

If the data source is an external data source, then an array is returned. Each row consists of a SQL connection string with the remaining elements as the query string broken down into 200 character segments.

If the data source is Multiple Consolidation ranges, then a two dimensional array is returned, each row of which consists of a reference and associated page field items.

If the data source is another PivotTable report, then one of the above three kinds of information is returned.

Pivot_table_name    is the name of a PivotTable report containing the field that you want information about. If omitted, uses the PivotTable report containing the active cell.

Remarks

Returns #VALUE! error value when pivot_table_name is not a valid PivotTable name on the active sheet and the active cell is not within a PivotTable report.

Related Functions

GET.PIVOT.FIELD   Returns information about an item in a PivotTable report.

   Returns information about a PivotTable report.

Returns information about a button or buttons on a toolbar. Use to get information about a button to use with functions that add, delete, or alter buttons.

Syntax

(type_num, bar_id, position)

Type_num    specifies what type of information you want to return.

Type_num

 

Returns

1                    The button's ID number. Gaps are represented by zeros.

2                    The reference of the macro assigned to the button. If no

macro is assigned, returns the #N/A error value.

3                    If the button is down, returns TRUE. If the button is up,

returns FALSE.

4                    If the button is enabled, returns TRUE. If the button is

disabled, returns FALSE.

5                    A logical value indicating the type of the face on the

button:

                                                  TRUE = bitmap

                                                  FALSE = a default button face

6                    The help_text reference associated with the custom

button. If the button is built-in, returns #N/A.

7                    The balloon_text reference associated with the custom

button. If the button is built-in, returns the #N/A error value.

8                    The Help context string associated with the custom

button.

9                    The Tip_text associated with the custom button.

Bar_id    specifies the number or name of the toolbar for which you want information. For detailed information about bar_id, see .

Position    specifies the position of the button on the toolbar. Position starts with 1 at the left side (if horizontal) or at the top (if vertical). A position can be occupied by a button or a gap.

Example

The following macro formula requests the help text associated with the third button in Toolbar2:

(6, "Toolbar2", 3)

Related Functions

   Adds one or more buttons to a toolbar

   Deletes a button from a toolbar

   Enables or disables a button on a toolbar

GET.TOOLBAR   Retrieves information about a toolbar

GET.TOOLBAR

Returns information about one toolbar or all toolbars. Use GET.TOOLBAR to get information about a toolbar to use with functions that add, delete, or alter toolbars.

Syntax

GET.TOOLBAR(type_num, bar_id)

Type_num    specifies what type of information to return. If type_num is 8 or 9, GET.TOOLBAR returns an array of names or numbers of all visible or hidden toolbars. Otherwise, bar_id is required, and GET.TOOLBAR returns the requested information about the specified toolbar.

Type_num

 

Returns

1                      A horizontal array of all tool IDs on the toolbar,

ordered by position. Gaps are represented by zeros.

2                      Number indicating the horizontal position (x-

coordinate) of the toolbar in the docked or floating region. For more information, see SHOW.TOOLBAR.

3                      Number indicating the vertical position (y-

coordinate) of the toolbar in the docked or floating region.

4                      Number indicating the width of the toolbar in points.

5                      Number indicating the height of the toolbar in points.

6                      Number indicating the toolbar location:

1  = Top dock in the workspace

2  = Left dock in the workspace

3  = Right dock in the workspace

4  = Bottom dock in the workspace

5  = Floating

7                      If the toolbar is visible, returns TRUE. If the toolbar

is hidden, returns FALSE.

8                      An array of toolbar IDs (names or numbers in the bar_id array) for all toolbars, visible and hidden.

9                      An array of toolbar IDs (names or numbers in the

bar_id array) for all visible toolbars.

10                      If the toolbar is visible in full-screen mode, returns

TRUE; otherwise, returns FALSE.

Bar_id    specifies the number or name of a toolbar for which you want information. If type_num is 8 or 9, Microsoft Excel ignores bar_id. For detailed information about bar_id, see .

Remarks

If you request position information for a hidden toolbar, Microsoft Excel returns the position where the toolbar would appear if shown.

Examples

The following macro formula returns information about the width of Toolbar1:

GET.TOOLBAR(4, "Toolbar1")

When the following macro formula is entered as an array with CTRL+SHIFT+ENTER, the IDs of all visible toolbars are returned, and the array is named All_Bar_Ids:

("All_Bar_Ids", GET.TOOLBAR(9))

Related Functions

   Adds one or more buttons to a toolbar

ADD.TOOLBAR   Creates a new toolbar with the specified tools

DELETE.TOOLBAR   Deletes custom toolbars

   Returns information about a tool or tools on a toolbar

SHOW.TOOLBAR   Hides or displays a toolbar

GET.WINDOW

Returns information about a window. Use GET.WINDOW in a macro that requires the status of a window, such as its name, size, position, and display options.

Syntax

GET.WINDOW(type_num, window_text)

Type_num    is a number that specifies what type of window information you want. The following list shows the possible values of type_num and the corresponding results:

Type_num

 

Returns

1                         Name of the workbook and sheet in the window as text. For compatibility with Microsoft Excel version 4.0, if the window contains only a single sheet that has the same name as the workbook without its extension, returns only the name of the book. Otherwise, returns the name of the sheet in the form "[Book1]Sheet1".

2                         Number of the window.

3                         X position, measured in points from the left edge of the workspace (in Microsoft Excel for Windows) or screen (in Microsoft Excel for the Macintosh) to the left edge of the window.

4                         Y position, measured in points from the bottom edge of the formula bar to the top edge of the window.

5                         Width, measured in points.

6                         Height, measured in points.

7                         If window is hidden, returns TRUE; otherwise, returns FALSE.

The rest of the values for type_num apply only to worksheets and macro sheets, except where indicated:

Type_num

 

Returns

8                         If formulas are displayed, returns TRUE; otherwise, returns FALSE.

9                         If gridlines are displayed, returns TRUE; otherwise, returns FALSE.

10                         If row and column headings are displayed, returns TRUE; otherwise, returns FALSE.

11                         If zeros are displayed, returns TRUE; otherwise, returns FALSE.

12                         Gridline and heading color as a number in the range 1 to 56, corresponding to the colors in the View tab of the Options dialog box; if color is automatic, returns 0.

Values 13 to 16 for type_num return arrays that specify which rows or columns are at the top and left edges of the panes in the window and the widths and heights of those panes. 

•   The first number in the array corresponds to the first pane, the second number to the second pane, and so on.

•   If the edge of the pane occurs at the boundary between rows or columns, the number returned is an integer.

•   If the edge of the pane occurs within a row or column, the number returned has a fractional part that represents the fraction of the row or column visible within the pane.

•   The numbers can be used as arguments to the SPLIT function to split a window at specific locations.

Type_num

 

Returns

13                         Leftmost column number of each pane, in a

horizontal numeric array

14                         Top row number of each pane, in a horizontal

numeric array.

15                         Number of columns in each pane, in a horizontal

numeric array.

16                         Number of rows in each pane, in a horizontal

numeric array.

17                         Number indicating the active pane: 

1  = Upper, left, or upper-left

2  = Right or upper-right

3  = Lower or lower-left

4  = Lower-right

18                         If window has a vertical split, returns TRUE;

otherwise, returns FALSE.

19                         If window has a horizontal split, returns TRUE;

otherwise, returns FALSE.

20                         If window is maximized, returns TRUE; otherwise,

returns FALSE.

21                         Reserved

22                         If the Outline Symbols check box is selected in

the View tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

23                         Number indicating the size of the window

(including charts): 

1  = Restored

2  = Minimized (displayed as an icon)

3  = Maximized

24                         If panes are frozen on the active window, returns

TRUE; otherwise, returns FALSE.

25                         The numeric magnification of the active window

(as a percentage of normal size) as set in the Zoom dialog box, or 100 if none is specified.

26                         Returns TRUE if horizontal scrollbars are displayed in the active window; otherwise, returns FALSE.

27                         Returns TRUE if vertical scrollbars are displayed in

the active window; otherwise, returns FALSE.

28                         Returns the tab ratio of workbook tabs to

horizontal scrollbar, from 0 to 1. The default is .6.

29                         Returns TRUE if workbook tabs are displayed in

the active window; otherwise, returns FALSE.

30                         Returns the title of the active sheet in the window

in the form "[Book1]Sheet1".

31                         Returns the name of a workbook only, without

read/write indicated. For example, if is read only, then "" will be returned without "[Read Only]" appended.

Window_text    is the name that appears in the title bar of the window that you want information about. If window_text is omitted, it is assumed to be the active window. Examples

If the active window contains the workbook Book1, then:

GET.WINDOW(1) equals "Book1"

If the title of the active window is Macro1:3, then:

GET.WINDOW(2) equals 3

In Microsoft Excel for Windows, the following macro formula returns the gridline and heading color of :

GET.WINDOW(12, "")

In Microsoft Excel for the Macintosh, the following macro formula returns the gridline and heading color of REPORT MASTER:

GET.WINDOW(12, "REPORT MASTER")

Related Functions

GET.DOCUMENT   Returns information about a workbook

GET.WORKSPACE   Returns information about the workspace

GET.WORKBOOK

Returns information about a workbook.

Syntax

GET.WORKBOOK(type_num, name_text)

Type_num    is a number that specifies what type of workbook information you want.

Type_num

 

Returns

1                    The names of all sheets in the workbook, as a horizontal

array of text values. Names are returned as [book]sheet.

2                    This will always return the #N/A error value.

3                    The names of the currently selected sheets in the workbook,

as a horizontal array of text values.

4                    The number of sheets in the workbook.

5                    TRUE if the workbook has a routing slip; otherwise, FALSE.

6                    The names of all of the workbook routing recipients who

have not received the workbook, as a horizontal array of text values.

7                    The subject line for the current routing slip, as text.

8                    The message text for the routing slip, as text.

9                    If the workbook is to be routed to recipients one after

another, returns 1. If it is to be routed all at once, returns 2.

10                 TRUE, if the Return When Done check box in the Routing

Slip dialog box is selected; otherwise, FALSE.

11                 TRUE, if the current recipient has already forwarded the

current workbook; otherwise, FALSE.

12                 TRUE, if the Track Status checkbox in the Routing Slip

dialog box is selected; otherwise, FALSE.

13                 Status of the workbook routing slip: 

0  = Unrouted

1  = Routing in progress, or the workbook has been routed to a user

2  = Routing is finished

14                 TRUE, if the workbook structure is protected; otherwise,

FALSE.

15                 TRUE, if the workbook windows are protected; otherwise,

FALSE.

16                 Name of the workbook as text. The workbook name does

not include the drive, directory or folder, or window number.

17                 TRUE if the workbook is read only; otherwise, FALSE. This is

the equivalent of GET.DOCUMENT(34).

18                 TRUE if sheet is write-reserved; otherwise, FALSE. This is

the equivalent of GET.DOCUMENT(35).

19                 Name of the user with current write permission for the

workbook. This is the equivalent of GET.DOCUMENT(36).

20                 Number corresponding to the file type of the document as

displayed in the Save As dialog box. This is the equivalent of GET.DOCUMENT(37).

21                 TRUE if the Always Create Backup check box is selected in

the Save Options dialog box; otherwise, FALSE. This is the equivalent of GET.DOCUMENT(40).

22                 TRUE if the Save External Link Values check box is selected

in the Calculation tab of the Options dialog box. This is the equivalent of GET.DOCUMENT(43).

23                 TRUE if the workbook has a PowerTalk mailer; otherwise,

FALSE. Returns #N/A if no OCE mailer is installed.

24                 TRUE if changes have been made to the workbook since the

last time it was saved; FALSE if book is unchanged (or when closed, will not prompt to be saved).

25                 The recipients on the To line of a PowerTalk mailer, as a horizontal array of text.

26                 The recipients on the Cc line of a PowerTalk mailer, as a

horizontal array of text.

27                 The recipients on the Bcc line of a PowerTalk mailer, as a

horizontal array of text.

28                 The subject of the PowerTalk mailer, as text.

29                 The enclosures of the PowerTalk mailer, as a horizontal

array of text.

30                 TRUE, if the PowerTalk mailer has been received from

another user (as opposed to just being added but not sent). FALSE, if the mailer has not been received from another user.

31                 The date and time the PowerTalk mailer was sent, as a

serial number. Returns the #N/A error value if the mailer has not yet been sent.

32                 The sender name of the PowerTalk mailer, as text. Returns

the #N/A error value if the mailer has not yet been sent.

33                 The title of the workbook as displayed on the Summary tab

of the Properties dialog box, as text.

34                 The subject of the workbook as displayed on the Summary

tab of the Properties dialog box, as text.

35                 The author of the workbook as displayed on the Summary

tab of the Properties dialog box, as text.

36                 The keywords for the workbook as displayed on the

Summary tab of the Properties dialog box, as text.

37                 The comments for the workbook as displayed on the

Summary tab of the Properties dialog box, as text.

38                 The name of the active sheet.

Name_text    is the name of an open workbook. If name_text is omitted, it is assumed to be the active workbook.

Example

The following macro formula returns the name of the active sheet in the workbook named :

GET.WORKBOOK(38, "")

Related Functions

GET.DOCUMENT   Returns information about a workbook

WORKBOOK.SELECT   Selects the specified documents in a workbook

GET.WORKSPACE

Returns information about the workspace. Use GET.WORKSPACE in a macro that depends on the status of the workspace, such as the environment, version number, and available memory.

Syntax

GET.WORKSPACE(type_num)

Type_num    is a number specifying the type of workspace information you want. The following list shows the type_num values and their corresponding results.

Type_num

 

Returns

1                  Name of the environment in which Microsoft Excel is running, as

text, followed by the environment's version number.

2                  The version number of Microsoft Excel, as text (for example,

"5.0").

3                  If fixed decimals are set, returns the number of decimals;

otherwise, returns 0.

4                  If in R1C1 mode, returns TRUE; if in A1 mode, returns FALSE.

5                  If scroll bars are displayed, returns TRUE; otherwise, returns FALSE. See also GET.WINDOW(26) and GET.WINDOW(27).

6                  If the status bar is displayed, returns TRUE; otherwise, returns

FALSE.

7                  If the formula bar is displayed, returns TRUE; otherwise,

returns FALSE.

8                  If remote DDE requests are enabled, returns TRUE; otherwise,

returns FALSE.

9                  Returns the alternate menu key as text; if no alternate menu

key is set, returns the #N/A error value.

10               Number indicating special modes:

1  = Data Find

2  = Copy

3  = Cut

4  = Data Entry

5  = Unused

6  = Copy and Data Entry

7  = Cut and Data Entry

If no special mode is set, returns 0.

11               X position of the Microsoft Excel workspace window, measured

in points from the left edge of the screen to the left edge of the window. In Microsoft Excel for the Macintosh, always returns 0.

12               Y position of the Microsoft Excel workspace window, measured

in points from the top edge of the screen to the top edge of the window. In Microsoft Excel for the Macintosh, always returns 0.

13               Usable workspace width, in points.

14               Usable workspace height, in points.

15               Number indicating maximized or minimized status of Microsoft

Excel:

1  = Neither

2  = Minimized

3  = Maximized

Microsoft Excel for the Macintosh always returns 3.

16               Amount of memory free (in kilobytes).

17               Total memory available to Microsoft Excel (in kilobytes).

18               If a math coprocessor is present, returns TRUE; otherwise,

returns FALSE.

19               If a mouse is present, returns TRUE; otherwise, returns FALSE.

In Microsoft Excel for the Macintosh, always returns TRUE.

20               If a group is present in the workspace, returns a horizontal

array of sheets in the group; otherwise returns the #N/A error value.

21               If the Standard toolbar is displayed, returns TRUE; otherwise,

returns FALSE.

22               DDE-application-specific error code.

23               Full path of the default startup directory or folder.

24               Full path of the alternate startup directory or folder; returns the

#N/A error value if no alternate path has been specified.

25               If Microsoft Excel is set for relative recording, returns TRUE; if set for absolute recording, returns FALSE.

26               Name of user.

27               Name of organization.

28               If Microsoft Excel menus are switched to by the transition menu

or help key, returns 1; if Lotus 1-2-3 Help is switched to, returns 2.

29               If transition navigation keys are enabled, returns TRUE.

30               A nine-item horizontal array of global (default) print settings

that can be set by the LINE.PRINT function: 

Setup text

Left margin

Right margin

Top margin

Bottom margin

Page length

Logical value indicating whether to wait after printing each page (TRUE) or use continuous form feeding (FALSE)

Logical value indicating whether the printer has automatic line feeding (TRUE) or requires line feed characters (FALSE)

The number of the printer port

31               If a currently running macro is in single step mode, returns

TRUE; otherwise, returns FALSE.

32               The current location of Microsoft Excel as a complete path.

33               A horizontal array of the names in the New list, in the order

they appear.

34               A horizontal array of template files (with complete paths) in the

New list, in the order they appear (returns the names of custom template files and the #N/A error value for built-in document types).

35               If a macro is paused, returns TRUE; FALSE otherwise.

36               If the Allow Cell Drag And Drop check box is selected in the Edit tab of the Options dialog box that appears when you click the Options command on the Tools menu, returns TRUE; otherwise, returns FALSE.

37               A 45-item horizontal array of the items related to country

versions and settings. Use the following macro formula to return a specific item, where number is a number in the list below:

INDEX(GET.WORKSPACE(37), number)

                                        These values apply to country codes:

1  = Number corresponding to the country version of Microsoft Excel.

2  = Number corresponding to the current country setting in the Microsoft Windows Control Panel or the country number as determined by your Apple system software

                                        These values apply to number separators:

3  = Decimal separator

4  = Zero (or 1000) separator

5  = List separator

                                        These values apply to R1C1-style references:

6  = Row character

7  = Column character

8  = Lowercase row character

9  = Lowercase column character

10   = Character used instead of the left bracket ([) 11 = Character used instead of the right bracket (])

                                        These values apply to array characters:

12  = Character used instead of the left bracket ({)

13  = Character used instead of the right bracket (})

14  = Column separator

15  = Row separator

16  = Alternate array item separator to use if the current array separator is the same as the decimal separator

                                        These values apply to format code symbols:

17  = Date separator

18  = Time separator

19  = Year symbol

20  = Month symbol

21  = Day symbol

22  = Hour symbol

23  = Minute symbol

24  = Second symbol

25  = Currency symbol

26  = "General" symbol

                                        These values apply to format codes:

27  = Number of decimal digits to use in currency formats 28 = Number indicating the current format for negative currencies:

0  = ($currency) or (currency$)

1  = -$currency or -currency$

2  = $-currency or currency-$    3 = $currency- or currency$- where currency is any number and the $ represents the current currency symbol.

29   = Number of decimal digits to use in noncurrency number formats

30   = Number of characters to use in month names 31 = Number of characters to use in weekday names 32 = Number indicating the date order:

0  = Month-Day-Year

1  = Day-Month-Year

2  = Year-Month-Day

                                        These values apply to logical format values:

33 = TRUE if using 24-hour time; FALSE if using 12-hour time. 34 = TRUE if not displaying functions in English; otherwise, returns FALSE.

35   = TRUE if using the metric system; FALSE if using the English measurement system.

36   = TRUE if a space is added before the currency symbol; otherwise, returns FALSE.

37   = TRUE if currency symbol precedes currency values; FALSE if it follows currency values.

38   = TRUE if using minus sign for negative numbers; FALSE if using parentheses.

39   = TRUE if trailing zeros are displayed for zero currency values; otherwise, returns FALSE.

40   = TRUE if leading zeros are displayed for zero currency values; otherwise, returns FALSE.

41   = TRUE if leading zero is displayed in months (when months are displayed as numbers); otherwise, returns FALSE. 42 = TRUE if leading zero is shown in days (when days are displayed as numbers); otherwise, returns FALSE.

43   = TRUE if using four-digit years; FALSE if using two-digit years.

44   = TRUE if date order is month-day-year when displaying dates in long form; FALSE if date order is day-month-year. 45 = TRUE if leading zero is shown in the time; otherwise, returns FALSE.

38               The number 0, 1, or 2 indicating the type of error-checking as

set by the ERROR function. For more information, see ERROR.

39               A reference in R1C1-text form to the currently defined error-

handling macro (set by the ERROR function), or the #N/A error value if none is specified.

40               If screen updating is turned on (set by the ECHO function),

returns TRUE; otherwise, returns FALSE.

41               A horizontal array of cell ranges, as R1C1-style text, that were previously selected with the Go To command from the Edit menu or the macro function. If the book has multiple sheets, or if the single sheet in the workbook is named differently than the workbook itself, returns names as [Book]Sheet.

42               If your computer is capable of playing sounds, returns TRUE;

otherwise, returns FALSE.

43               If your computer is capable of recording sounds, returns TRUE;

otherwise, returns FALSE.

44               A three-column array of all currently registered procedures in

dynamic link libraries (DLLs). The first column contains the names of the DLLs that contain the procedures (in Microsoft Excel for Windows) or the names of the files that contain the code resources (in Microsoft Excel for the Macintosh). The second column contains the names of the procedures in the DLLs (in Microsoft Excel for Windows) or code resources (in Microsoft Excel for the Macintosh). The third column contains text strings specifying the data types of the return values, and the number and data types of the arguments. For more information about DLLs and code resources and data types, see

Using the CALL and REGISTER functions in Microsoft Excel Help.

45               If Microsoft Windows for Pen Computing is running, returns

TRUE; otherwise, returns FALSE.

46               If the Move Selection After Enter check box is selected in the

Edit tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

47               Reserved.

48               Path to the library subdirectory for Microsoft Excel, as text.

49               MAPI session currently in use, returned as a string of hex digits

encoding the mail session value.

50               If the Full Screen mode is on, returns TRUE; otherwise, FALSE.

51               If the formula bar is displayed in Full Screen mode, returns

TRUE; otherwise, FALSE.

52               If the status bar is displayed in Full Screen mode, returns TRUE; otherwise, FALSE.

53               The name of the topmost custom dialog sheet currently running

in a modal window, or #N/A if no dialog sheet is currently running.

54               If the Edit Directly In Cell check box is selected on the Edit tab in the Options dialog box, returns TRUE; otherwise, returns FALSE.

55               TRUE if the Alert Before Overwriting Cells check box in the Edit

tab on Options dialog box is selected; otherwise, FALSE.

56               Standard font name in the General tab in the Options dialog

box, as text.

57               Standard font size in the General tab in the Options dialog box, as a number

58               If the Recently Used File list check box in the General tab on the

Options dialog box is selected, returns TRUE; otherwise, FALSE.

59               If the Display Old Menus check box in the General tab on the

Options dialog box is selected, returns TRUE; otherwise, FALSE.

60               If the Tip Wizard is enabled, returns TRUE; otherwise, FALSE.

61               Number of custom list entries listed in the Custom Lists tab of

the Options dialog box.

62               Returns information about available file converters.

63               Returns the type of mail system in use by Excel:

0  = No mail transport detected

1  = MAPI based transport

2  = PowerTalk based transport (Macintosh only)

64               If the Ask To Update Automatic Links check box in the Edit tab

of the Options dialog box is selected, returns TRUE; otherwise, FALSE.

65               If the Cut, Copy, And Sort Objects With Cells check box in the

Edit tab on the Options dialog box is selected, returns TRUE; otherwise, FALSE.

66               Default number of sheets in a new workbook, as a number,

from the General tab on Options dialog box.

67               Default file directory location, as text, from the General tab in

the Options dialog box.

68               If the Show ScreenTips On Toolbars check box in the Options

tab in the Customize dialog box is selected, returns TRUE; otherwise, FALSE.

69               If the Large Icons check box in the Options tab in the Customize

dialog box is selected, returns TRUE; otherwise, FALSE.

70               If the Prompt For Workbook Properties check box in the General

tab on the Options dialog box is selected, returns TRUE; otherwise, FALSE.

71               TRUE if Microsoft Excel is open for in-place object editing (OLE).

If FALSE, it is opened normally.

72               TRUE if the Color Toolbars check box is selected in the Toolbars dialog box. FALSE if the Color Toolbars check box is not selected. This argument is for compatibility with Microsoft Excel version 5.0.

Related Functions

GET.DOCUMENT   Returns information about a workbook

GET.WINDOW   Returns information about a window

Equivalent to clicking the Goal Seek command on the Tools menu. Calculates the values necessary to achieve a specific goal. If the goal is an amount returned by a formula, the function calculates values that, when supplied to your formula, cause your formula to return the amount you want.

Syntax

(target_cell, target_value, variable_cell)

?(target_cell, target_value, variable_cell)

Target_cell    corresponds to the Set Cell box in the Goal Seek dialog box and is a reference to the cell containing the formula. If target_cell does not contain a formula, Microsoft Excel displays an error message.

Target_value    corresponds to the To Value box in the Goal Seek dialog box and is the value you want the formula in target_cell to return. This value is called a goal.

Variable_cell    corresponds to the By Changing Cell box in the Goal Seek dialog box and is the single cell that you want Microsoft Excel to change so that the formula in target_cell returns target_value. Target_cell must depend on variable_cell; if it does not, Microsoft Excel will not be able to find a solution.

Remarks

The max_num and max_change values set with the CALCULATION function can be used to change the solution process. Max_num sets the number of iterations; max_change determines the precision of the solution.

Tip   You can also use Microsoft Excel Solver to help solve your math equations for optimal values.

Related Functions

Related functions include the SOLVER functions, such as SOLVER.OPTIONS, SOLVER.SOLVE, and so on.

GOTO

Directs a macro to continue running at the upper-left cell of reference. Use GOTO to direct macro execution to another cell or a named range.

Syntax

GOTO(reference)

Reference    is a cell reference or a name that is defined as a reference. Reference can be an external reference to another macro sheet. If that macro sheet is not open, GOTO displays a message.

Tip   It's often preferable to use IF, ELSE, , and instead of GOTO when you want to perform multiple actions based on a condition because the IF method makes your macros more structured.

Examples

If A1 contains the #N/A error value, then when the following formula is calculated, the macro branches to C3:

IF(ISERROR($A$1), GOTO($C$3))

You can also use macro names with GOTO statements. The following macro formula branches macro execution to a macro named Compile:

GOTO(Compile)

Because Compile is a named range, it should not be enclosed in quotation marks.

Related Function

   Selects a named area or reference on any open workbook

GRIDLINES

Allows you to turn chart gridlines on and off.

Arguments are logical values corresponding to the check boxes in the Gridlines dialog box. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If omitted, the setting is not changed. If a chart is not active, produces a error and halts the macro.

Syntax

GRIDLINES(x_major, x_minor, y_major, y_minor, z_major, z_minor, 2D_effect) GRIDLINES?(x_major, x_minor, y_major, y_minor, z_major, z_minor, 2D_effect)

X_major    corresponds to the Category (X) Axis: Major Gridlines check box.

X_minor    corresponds to the Category (X) Axis: Minor Gridlines check box.

Y_major    corresponds to the Value (Y) Axis: Major Gridlines check box. On 3-D charts, y_major corresponds to the Series (Y) Axis: Major Gridlines check box.

Y_minor    corresponds to the Value (Y) Axis: Minor Gridlines check box. On 3-D charts, y_minor corresponds to the Series (Y) Axis: Minor Gridlines check box.

Z_major    corresponds to the Value (Z) Axis: Major Gridlines check box (3-D only).

Z_minor    corresponds to the Value (Z) Axis: Minor Gridlines check box (3-D only).

2D_effect    corresponds to the 2-D Walls and Gridlines check box (3-D only).

GROUP

Creates a single object from several selected objects and returns the object identifier of the group (for example, "Group 5"). Use GROUP to combine a number of objects so that you can move or resize them together.

If no object is selected, only one object is selected, or a group is already selected, GROUP returns the #VALUE! error value and interrupts the macro.

Syntax

GROUP( )

Related Function

UNGROUP   Separates a grouped object

ECHO

Controls screen updating while a macro is running. If a large macro uses many commands that update the screen, use ECHO to make the macro run faster.

Syntax

ECHO(logical)

Logical    is a logical value specifying whether screen updating is on or off. 

•   If logical is TRUE, Microsoft Excel selects screen updating.

•   If logical is FALSE, Microsoft Excel clears screen updating.

•   If logical is omitted, Microsoft Excel changes the current screen update condition. 

Remarks 

•   Screen updating is always turned back on when a macro ends.

•   You can use GET.WORKSPACE to determine whether screen updating is on or off. 

Related Function

GET.WORKSPACE   Returns information about the workspace

EDITBOX.PROPERTIES

Sets the properties of an edit box on a dialog sheet.

Syntax

EDITBOX.PROPERTIES(validation_num, multiline_logical, vscroll_logical, password_logical)

EDITBOX.PROPERTIES?(validation_num, multiline_logical, vscroll_logical, password_logical)

Validation_num    is the validation applied to the edit box when the dialog is dismissed. If the edit box contains a value other than the type specified (or validation), an error is returned.

Validation_num

 

Type

1            Text

2            Integer

3            Number (allows floating point)

4            Reference

5            Formula

Multiline_logical    is a logical value specifying whether word wrapping is allowed in the edit box control. If TRUE, word wrapping is allowed. If FALSE, word wrapping is not allowed

Vscroll_logical    is a logical value specifying whether edit box displays a vertical scrollbar. If TRUE, a scrollbar is displayed. If FALSE, a scrollbar is not displayed.

Password_logical    is a logical value specifying whether edit box displays characters as the user types. If TRUE, asterisks (*) are displayed as the user types. If FALSE, no asterisks are displayed.

Related Functions

CHECKBOX.PROPERTIES   Sets various properties of check box and option box controls

PUSHBUTTON.PROPERTIES   Sets the properties of the push button control

EDIT.COLOR

Equivalent to clicking the Modify button on the Color tab, which appears when you click the Options command on the Tools menu. Defines the color for one of the 56 color palette boxes.

Use EDIT.COLOR if you want to use a color that is not currently on the palette and if your system hardware has more than 56 colors available. After you set the color for the color box, any items previously formatted with that color are displayed in the new color.

Syntax

EDIT.COLOR(color_num, red_value, green_value, blue_value)

EDIT.COLOR?(color_num, red_value, green_value, blue_value)

Color_num    is a number from 1 to 56 specifying one of the 56 color palette boxes for which you want to set the color.

Red_value, green_value, and blue_value    are numbers that specify how much red, green, and blue are in each color. 

•   In Microsoft Excel for Windows, red_value, green_value, and blue_value are numbers from 0 to 255.

•   In Microsoft Excel for the Macintosh, red_value, green_value, and blue_value are also numbers from 0 to 255. However, the color editing dialog box displays numbers from 0 to 65, 535. Microsoft Excel automatically converts the numbers between the two ranges. This allows you to display similar colors in all operating environments without modifying your macros.

•   If red_value, green_value, and blue_value are all set to 255, the resulting color is white. If they are all set to zero, the resulting color is black.

•   If red_value, green_value, or blue_value is omitted, Microsoft Excel assumes it to be the appropriate value for that color_num. 

Remarks 

•   Your system hardware determines the number of unique colors that you can choose from and the number of colors that can be displayed on the screen at the same time.

•   EDIT.COLOR does not use hue, saturation, or brightness values. If you are using the macro recorder and set the color of a color palette box using hue, saturation, and luminance, Microsoft Excel records the corresponding red, green, and blue values instead.

•   The dialog-box form of this function, EDIT.COLOR?(color_num), displays your system's color editing dialog box. The default red_value, green_value, and blue_value are determined by the current settings for the color_num you specify. Color_num is a required argument for the dialog-box form of this function. 

Related Function

COLOR.PALETTE   Copies a color palette from one workbook to another

EDIT.DELETE

Equivalent to clicking the Delete command on the Edit menu. Removes the selected cells from the worksheet and shifts other cells to close up the space.

Syntax

EDIT.DELETE(shift_num)

EDIT.DELETE?(shift_num)

Shift_num    is a number from 1 to 4 specifying whether to shift cells left or up after deleting the current selection or else to delete the entire row or column.

Shift_num

 

Result

1        Shifts cells left

2        Shifts cells up

3        Deletes entire row

4        Deletes entire column

•   If shift_num is omitted and if one cell or a horizontal range is selected, EDIT.DELETE shifts cells up.

•   If shift_num is omitted and a vertical range is selected, EDIT.DELETE shifts cells left. 

Related Function

CLEAR   Clears specified information from the selected cells or chart

EDITION.OPTIONS

Sets options in, or performs actions on, the specified publisher or subscriber. In Microsoft Excel for Windows, EDITION.OPTIONS also allows you to cancel a publisher or subscriber created in Microsoft Excel for the Macintosh.

Syntax

EDITION.OPTIONS(edition_type, edition_name, reference, option, appearance, size, formats)

Edition_type    is the number 1 or 2 specifying the type of edition.

Edition_type

 

Type of edition

1          Publisher

2          Subscriber

Edition_name    is the name of the edition you want to change the edition options for or to perform actions on. If edition_name is omitted, reference is required.

Reference    specifies the range (given in text form as a name or an R1C1-style reference) occupied by the publisher or subscriber. 

•   Reference is required if you have more than one publisher or subscriber of edition_name on the active workbook. Use reference to specify the location of the publisher or subscriber for which you want to set options.

•   If edition_type is 1 and the publisher is an embedded chart, or if edition_type is 2 and the subscriber is a picture, reference is the object identifier as displayed in the reference area.

•   If reference is omitted, edition_name is required. 

Option    is a number from 1 to 6 specifying the edition option you want to set or the action you want to take, according to the following two tables. Options 2 to 6 are only available if you are using Microsoft Excel for the Macintosh with system software version 7.0 or later.

If a publisher is specified, then option applies as follows.

Option

 

Action

1       Cancels the publisher

2       Sends the edition now

3       Selects the range or object published to the specified edition

4       Automatically updates the edition when the file is saved

5       Updates the edition on request only

6       Changes the edition file as specified by appearance, size, and formats

If a subscriber is specified, then option applies as follows.

Option

 

Action

1        Cancels the subscriber

2        Gets the latest edition

3        Opens the publisher workbook

4        Automatically updates when new data is available

5        Update on request only

The following three arguments are available only when option is 6.

Appearance    specifies whether the selection is published as shown on screen or as shown when printed. The default value for appearance is 1 if the selection is a sheet or macro sheet and 2 if the selection is a chart.

Appearance

 

Selection is published

1           As shown on screen

2           As shown when printed

Size    specifies the size of a published chart. Size is only available if a chart is to be published.

Size

 

Chart size is published

1          or omitted As shown on screen

2          As shown when printed

Formats    is a number specifying the format of the file.

Formats

 

File format

1          or omitted PICT

2          BIFF

4                    RTF

8                     VALU

You can also use the sum of the allowable file formats. For example, a value of 6 specifies BIFF and RTF.

Example

The following macro formula opens the workbook (and application) that published the edition named Monthly Totals:

EDITION.OPTIONS(2, "Monthly Totals", , 3)

Related Functions

CREATE.PUBLISHER   Creates a publisher from the selection

   Returns information about a link

   Inserts contents of an edition into the active workbook

EDIT.OBJECT

Equivalent to clicking the Edit command on the (selected object) Object submenu of the Edit menu. Starts the application associated with the selected object and makes the object available for editing or other actions.

Syntax

EDIT.OBJECT(verb_num)

Verb_num    is a number specifying which verb to use while working with the object, that is, what you want to do with the object. 

•   The available verbs are determined by the object's source application. 1 often specifies "edit, " and 2 often specifies "play" (for sound, animation, and so on). For more information, consult the documentation for the object's application to see how it supports object linking and embedding (OLE).

•   If the object does not support multiple verbs, verb_num is ignored.

•   If verb_num is omitted, it is assumed to be 1. 

Remarks

Your macro pauses while you're editing the object and resumes when you return to Microsoft Excel.

Related Function

INSERT.OBJECT   Creates an object of a specified type

EDIT.REPEAT

Equivalent to clicking the Repeat command on the Edit menu. Repeats certain actions and commands. EDIT.REPEAT is available in the same situations as the Repeat command.

Syntax

EDIT.REPEAT( )

EDIT.SERIES

Equivalent to clicking the Edit Series command on the Chart menu in Microsoft Excel version

4.0. Creates or changes chart series by adding a new SERIES formula or modifying an existing SERIES formula in the topmost chart type. Chart types are displayed in the following order from top to bottom: XY (Scatter), Line, Column, Bar, Area.

Syntax

EDIT.SERIES(series_num, name_ref, x_ref, y_ref, z_ref, plot_order) EDIT.SERIES?(series_num, name_ref, x_ref, y_ref, z_ref, plot_order)

Series_num    is the number of the series you want to change. If series_num is 0 or omitted, Microsoft Excel creates a new data series.

Name_ref    is the name of the data series. It can be an external reference to a single cell, a name defined as a single cell, or a name defined as a sequence of characters. Name_ref can also be text (for example, "Projected Sales").

X_ref    is an external reference to the name of the sheet and the cells that contain one of the following sets of data: 

•   Category labels for all charts except xy (scatter) charts

•   X-coordinate data for xy (scatter) charts

Y_ref    is an external reference to the name of the sheet and the cells that contain values (or y-coordinate data in xy (scatter) charts) for all 2-D charts. Y_ref is required in 2-D charts but does not apply to 3-D charts.

Z_ref    is an external reference to the name of the sheet and the cells that contain values for all 3-D charts. Z_ref is required in 3-D charts but does not apply to 2-D charts.

Plot_order    is a number specifying whether the data series is plotted first, second, and so on, in the chart type. 

•   If you assign a plot_order to a series, Microsoft Excel plots that series in the order you specify, and the series that previously had that plot order (and any series following it) has its plot order increased by one.

•   If you add a series to a chart with an overlay, the number of series in the main chart does not change, so if the series is added to the main chart, then the series that was plotted last in the main chart will be plotted first in the overlay chart. To change which series is plotted first in the overlay chart, use the (chart type) Group command from the Format menu, and then select the Series Order

tab in the Format (chart type) Group dialog box. You can also use the FORMAT.OVERLAY function.

•   If you omit plot_order when you add a new series, then Microsoft Excel plots that series last and assigns it the correct plot_order value.

•   The maximum value for plot_order is 255.

Remarks

To change where a series is plotted within a chart, you can change the chart type, using the FORMAT.CHART function, or the plot order. Plot order affects where the series appears within the chart type only.

X_ref, y_ref, and z_ref can be arrays or references to a nonadjacent selection, although they cannot be names that refer to a nonadjacent selection. If you specify a nonadjacent selection for any of these arguments, make sure to enclose the reference to the selection in parentheses so that Microsoft Excel does not treat the components of the references as separate arguments.

Tip   To delete a data series, use the SELECT("Sn") macro function, where n is the series number, followed by the FORMULA("") macro function. You can also use the CLEAR function instead of FORMULA. Related Function

FORMAT.CHART

Displays the Button Editor dialog box, which you use to change the appearance of a button on a toolbar.

Syntax

(bar_id, position)

Bar_id    is the number of the toolbar containing the button you want to edit. For a list of toolbar numbers, see . Use the GET.TOOLBAR function to return the information about a toolbar.

Position    is the position on the toolbar of the button you want to edit. Buttons are numbered from the left starting at 1. Gaps between buttons are counted as positions.

Related Functions

   Adds a button to a toolbar

GET.TOOLBAR   Returns information about a toolbar

ELSE

Used with IF, , and to control which functions are carried out in a macro. ELSE signals the beginning of a group of formulas in a macro sheet that will be carried out if the results of all preceding statements and the preceding IF statement are FALSE. Use ELSE with IF, , and when you want to perform multiple actions based on a condition. This method is preferable to using GOTO because it makes your macros more structured.

Syntax

ELSE( )

Remarks

ELSE must be entered in a cell by itself. In other words, the cell can contain only "=ELSE()".

For more information about ELSE, , , and IF, and for examples of these functions, see form 2 of the IF function.

Related Functions

   Specifies an action to take if an IF or another function returns FALSE

   Ends a group of macro functions started with an IF statement

IF   Specifies an action to take if a logical test is TRUE

Used with IF, ELSE, and to control which functions are carried out in a macro. signals the beginning of a group of formulas in a macro sheet that will be carried out if the preceding IF or function returns FALSE and if logical_test is TRUE. Use with IF, ELSE, and when you want to perform multiple actions based on a condition. This method is preferable to using GOTO because it makes your macros more structured.

Syntax

(logical_test)

Logical_test    is a logical value that uses to determine what functions to carry out next—that is, where to branch. 

•   If logical_test is TRUE, Microsoft Excel carries out the functions between the function and the next , ELSE, or function.

•   If logical_test is FALSE, Microsoft Excel immediately branches to the next , ELSE, or function. 

Remarks 

•   must be entered in a cell by itself.

•   Logical_test will always be evaluated, even if the section is not reached (due to a previous IF or logical_test evaluating to TRUE). For this reason, you should not use formulas that carry out actions for logical_test. If you need to base the condition on the return value of a formula that carries out an action, use the form "ELSE, IF(logical_test), and " in place of "(logical_test)." 

For more information about ELSE, , , and IF, and for examples of these functions, see form 2 of the IF function.

Related Functions

ELSE   Specifies an action to take if an IF function returns FALSE

   Ends a group of macro functions started with an IF statement

IF   Specifies an action to take if a logical test is TRUE

EMBED

Displayed in the formula bar when an embedded object is selected. EMBED cannot be entered on a sheet or used in a macro.

Syntax

EMBED(object_class, item)

Object_class    is the name of the application and document type that created the embedded object. For example, the object_class arguments used when Microsoft Excel sheets are embedded in other applications are "Excel.sheet.5" and "Excel.Chart.5".

Item    is the area selected to copy, and determines the view on the embedded document. When item is empty text (""), EMBED creates a view on the entire document.

Remarks

If you delete the EMBED formula, the embedded object remains on the sheet as a graphic, and the link to the creating application is deleted. Double-clicking the object no longer starts the creating application.

ENABLE.COMMAND

Enables or disables a custom command or menu. Disabled commands appear dimmed and can't be chosen. Use ENABLE.COMMAND to control which commands the user can click in a menu bar.

Syntax

ENABLE.COMMAND(bar_num, menu, command, enable, subcommand)

Bar_num    is the menu bar in which a command resides. Bar_num can be the number of a built-in menu bar or the number returned by a previously run function. See ADD.COMMAND for a list of the built-in menu bar numbers.

Menu    is the menu on which the command resides. Menu can be either the name of a menu as text or the number of a menu. Menus are numbered starting with 1 from the left of the screen.

Command    is the command you want to enable or disable. Command can be either the name of the command as text or the number of the command. The top command on a menu is command 1. If command is 0, ENABLE.COMMAND enables or disables the entire menu.

Enable    is a logical value specifying whether the command should be enabled or disabled. If enable is TRUE, Microsoft Excel enables the command; if FALSE, it disables the command.

Subcommand    is the name of the command on a submenu that you want to enable. If you use subcommand, you must use command as the name of the submenu. Use subcommand 0 to enable an entire submenu.

Remarks 

•    You cannot disable built-in commands. If the specified command is a built-in command or does not exist, ENABLE.COMMAND returns the #VALUE! error value and interrupts the macro.

•    You can hide any shortcut menu from users by using ENABLE.COMMAND with command set to 0. 

Example

The following macro formula disables a custom command that had been added previously to the View menu on the worksheet and macro sheet menu bar:

ENABLE.COMMAND(10, "View", "Audit ", FALSE)

Related Functions

   Adds a menu bar

ADD.COMMAND   Adds a command to a menu

CHECK.COMMAND   Adds or deletes a check mark to or from a command

DELETE.COMMAND   Deletes a command from a menu

RENAME.COMMAND   Changes the name of a command or menu

ENABLE.OBJECT

Enables or disables a drawing object or the selected drawing object. A disabled object will not run any macro events assigned to it, and the controls will be grayed out.

Syntax

ENABLE.OBJECT(object_id_text, enable_logical)

Object_id_text    is the name of the object(s) as text. If omitted, the selected object(s) are assumed.

Enable_logical    is a logical value that specifies whether the object is to be enabled. If TRUE, the object is enabled. If FALSE, the object is disabled.

Examples

ENABLE.OBJECT("Button 2",FALSE) disables the button with object name Button 2 on the dialog box.

Related Function

SET.CONTROL.VALUE   Changes the value of the active control

ENABLE.TIPWIZARD

This function should not be used. The TipWizard has been removed from Microsoft Excel.

Enables or disables a button on a toolbar. An enabled button can be accessed by the user. Disabled buttons may still be visible but cannot be accessed. Use to control which buttons the user can click in a particular situation.

Syntax

(bar_id, position, enable)

Bar_id    is the number or name of a toolbar on which the button resides. For detailed information about bar_id, see .

Position    specifies the position of the button on the toolbar. Position starts with 1 at the left side (if horizontal) or from the top (if vertical).

Enable    specifies whether the button can be accessed. If enable is TRUE or omitted, the user can access the button; if FALSE, the user cannot access it.

Remarks

Microsoft Excel sounds a tone if you click a disabled button.

Example

The following macro formula enables the fourth button in Toolbar1:

("Toolbar1", 4, TRUE)

Related Function

   Returns information about a button or buttons on a toolbar

Ends a block of functions associated with the preceding IF function. You must include one and only one function for each macro-sheets-only syntax form (syntax 2) of the IF function in a macro. Syntax 1 of the IF function, which can be used on both worksheets and macro sheets, does not require an function. Use with IF, ELSE, and when you want to perform multiple actions based on a condition. This method is preferable to using GOTO because it makes your macros more structured.

Syntax

( )

Remarks 

•    If you accidentally omit an function, your macro will end with an error at the cell containing the first IF function that does not have a corresponding function.

•    must be entered in a cell by itself.

•    For more information about ELSE, , , and IF, and for examples of these functions, see form 2 of the IF function. 

Related Functions

ELSE   Specifies an action to take if an IF function returns FALSE

   Specifies an action to take if an IF or another function returns FALSE

IF   Specifies an action to take if a logical test is TRUE

Turns on Data Entry mode and allows you to select and to enter data into the unlocked cells in the current selection only (the data entry area). Use when you want to enter data only in a specific part of your sheet. You can then use that part of the sheet as a simple data form.

Syntax

(logical)

Logical    is a logical value that turns Data Entry mode on or off. 

•   If logical is TRUE, Data Entry mode is turned on; if FALSE, Data Entry mode is turned off and data entry, cell movement, and cell selection return to normal. If logical is omitted, toggles Data Entry mode.

•   Logical can also be the number 2. This setting turns on Data Entry mode and prevents the ESC key from turning it off.

•   Logical can also be a reference. Using a reference for this argument turns on Data Entry mode for the supplied reference. 

Remarks 

•   In Data Entry mode, you can move the active cell and select cell ranges only in the data entry area. The arrow keys and the TAB and SHIFT+TAB keys move from one unlocked cell to the next. The HOME and END keys move to the first and last cell in the data entry area, respectively. You cannot select entire rows or columns, and clicking a cell outside the data entry area does not select it.

•   The only commands available in Data Entry mode are commands normally available to protected workbooks.

•   To turn off Data Entry mode, press ESC (unless logical is 2), activate another sheet in the active workbook window, or use another function. If you use another function, you will usually design your macros in one of two ways: 

•   The macro turns on Data Entry mode, pauses while you enter data, resumes, and then turns off Data Entry mode.

•   The macro turns on Data Entry mode and ends. After entering data, another macro turns off Data Entry mode; this latter macro could be assigned to a "Finished" button, for example.

With either method, you can use Microsoft Excel's ON functions to resume or run other macros based on an event, such as pressing the CONTROL+D keys. 

Tips 

•   Normally you use Data Entry mode to enter data, but you can also prevent someone from entering data or moving the active cell by locking all the cells in the current selection before turning on Data Entry mode. This is useful if you want a user to view a range of cells but not change it or move the active cell. Similarly, if you unlock certain cells, you can restrict the user's movement to the Data Entry area only.

•   To prevent someone from activating another workbook, which would turn off Data Entry mode, use the ON.WINDOW function or an Auto_Deactivate macro.

Related Functions

DISABLE.INPUT   Blocks all input to Microsoft Excel

FORMULA   Enters values into a cell or range or onto a chart

ERROR

Specifies what action to take if an error is encountered while a macro is running. Use ERROR to control whether Microsoft Excel error messages are displayed, or to run your own macro when an error is encountered.

Syntax

ERROR(enable_logical, macro_ref)

Enable_logical    is a logical value or number that selects or clears error-checking. 

•   If enable_logical is FALSE or 0, all error-checking is cleared. If error-checking is cleared and an error is encountered while a macro is running, Microsoft Excel ignores it and continues. Error-checking is selected again by an ERROR(TRUE) statement, or when the macro stops running.

•   If enable_logical is TRUE or 1, you can either select normal error-checking (by omitting the other argument) or specify a macro to run when an error is encountered by using the macro_ref argument. When normal error-checking is active, the Macro Error dialog box is displayed when an error is encountered. You can halt the macro, start single-stepping through the macro, continue running the macro normally, or go to the macro cell where the error occurred.

•   If enable_logical is 2 and macro_ref is omitted, error-checking is normal except that if the user clicks the Cancel button in an alert message, ERROR returns FALSE and the macro is not interrupted.

•   If enable_logical is 2 and macro_ref is given, the macro goes to that macro_ref when an error is encountered. If the user clicks the Cancel button in an alert message, FALSE is returned and the macro is not interrupted. 

Macro_ref    specifies a macro to run if enable_logical is TRUE, 1, or 2 and an error is encountered. It can be either the name of the macro or a cell reference. If enable_logical is FALSE or 0, macro_ref is ignored.

Important   Both ERROR(FALSE) and ERROR(TRUE, macro_ref ) keep Microsoft Excel from displaying any messages at all, including the message asking whether to save changes when you close an unsaved workbook. If you want alert messages but not error messages to be displayed, use ERROR(2, macro_ref ).

Remarks

You can use GET.WORKSPACE to determine whether error-checking is on or off. Examples

ERROR(FALSE) clears error-checking.

ERROR(TRUE, Recover) selects error-checking and runs the macro named Recover when an error is encountered.

The following macro runs the macro ForceMenus if an error occurs in the current macro:

=ERROR(TRUE, ForceMenus)

Related Functions

   Disables macro interruption

LAST.ERROR   Returns the reference of the cell where the last error occurred

   Runs a macro when a specified key is pressed

ERRORBAR.X, ERRORBAR.Y

Adds error bars to the selected series in a chart. ERRORBAR.X adds bars showing the error factor for the X (category) axis and works for XY (scatter) charts only. ERRORBAR.Y adds bars showing the error factor for the Y (value) axis for all charts.

Syntax

ERRORBAR.X(include, type, amount, minus)

ERRORBAR.Y(include, type, amount, minus)

Include    specifies the type of error value to include:

Include

 

Type of error value

1          or omitted Plus and minus

2          Plus

3          Minus

4          None

Type    specifies the type of error bars to display:

Type

 

Type of error displayed

1          or omitted Fixed amount

2          Percent

3          Multiplying factor standard deviation (default value is 1)

4          Standard error

5          Custom

Amount    is the range of error values to display. This argument depends on the value of type:

If type is

 

then amount

1          or omitted Can be any number greater than 0

2          Can be any number greater than 0

3          Can be any number greater than or 0

4          Not required

5          Is the positive amount for custom error bars

Minus    is the negative amount for custom error bars. Applicable only if type is 5.

Remarks

For the amount argument, standard deviation(s) can be calculated using this equation:

The standard deviation is multiplied by the value specified by amount and the error bars are placed this distance from the arithmetic mean. Therefore, these error bars are plotted along the arithmetic mean, not attached to data series.

Microsoft Excel calculates the standard error using the following equation:

Both the standard deviation and standard error functions use the following variables:

Variable

 

Equals

s                Series number

i                 Point number in series s

m       Number of series for point y in chart

n         Number of points in each series

Yi                Data value of series s and the ith point

Ny              Total number of data values in all series

M                Arithmetic mean

EVALUATE

Evaluates a formula or expression that is in the form of text and returns the result. To run a macro or subroutine, use the RUN function.

Syntax

EVALUATE(formula_text)

Formula_text    is the expression in the form of text that you want to evaluate.

Remarks

Using EVALUATE is similar to selecting an expression within a formula in the formula bar and pressing the Recalculate key (F9 in Microsoft Excel for Windows and COMMAND+= in Microsoft Excel for the Macintosh). EVALUATE replaces an expression with a value.

Example

Suppose you want to know the value of a cell named LabResult1, LabResult2, or LabResult3, where the 1, 2, or 3 is specified by the name TrialNum whose value may change as the macro runs. You can use the following formula to calculate the value:

EVALUATE("LabResult"&TrialNum)

Related Function

RUN   Runs a macro

EXEC

Starts a separate program. Use EXEC to start other programs with which you want to communicate. Use EXEC with Microsoft Excel's other DDE functions (INITIATE, EXECUTE, and ) to create a channel to another program and to send keystrokes and commands to the program. ( is available only in Microsoft Excel for Windows.)

Syntax 1 is for Microsoft Excel for Windows. Syntax 2 is for Microsoft Excel for the Macintosh.

Syntax 1

For Microsoft Excel for Windows

EXEC(program_text, window_num)

Syntax 2

For Microsoft Excel for the Macintosh

EXEC(program_text, , background, preferred_size_only)

Important   Microsoft Excel for the Macintosh requires system software version 7.0 or later for the last two arguments of this function.

Program_text    is the name, as a text string, of any executable file or, in Microsoft Excel for Windows, any data file that is associated with an executable file. 

•   Use paths when the file or program to be started is not in the current directory or folder.

•   In Microsoft Excel for Windows, program_text can include any arguments and switches that are accepted by the program to be started. Also, if program_text is the name of a file associated with a specific installed program, EXEC starts the program and loads the specified file. 

Note   In Microsoft Excel for the Macintosh, you must use an extra comma after the program_text argument. This skips the window_num argument that does not apply to the Macintosh.

Window_num    is a number from 1 to 3 that specifies how the window containing the program should appear. Window_num is only available for use with Microsoft Excel for Windows. The window_num argument is allowed on the Macintosh, but it is ignored.

Window_num

 

Window appears

1          Normal size

2          or omitted        Minimized size

3          Maximized size

Background    is a logical value that determines whether the program specified by program_text is opened as the active program or in the background, leaving Microsoft Excel as the active program. If background is TRUE, the program is started in the background; if FALSE or omitted, the program is started in the foreground. Background is only available for use with Microsoft Excel for the Macintosh and system software version 7.0 or later.

Preferred_size_only    is a logical value that determines the amount of memory allocated to the program. If preferred_size_only is TRUE, the program is opened with its preferred memory allocation; if FALSE or omitted, it opens with the available memory if greater than its minimum requirement. Preferred_size_only is only available for use with Microsoft Excel for the Macintosh and system software version 7.0 or later. For information about changing the preferred memory size, see your Macintosh documentation.

Remarks

In Microsoft Excel for Windows and in Microsoft Excel for the Macintosh with system software version 7.0, if the EXEC function is successful, it returns the task ID number of the started program. The task ID number is a unique number that identifies a program. Use the task ID number in other macro functions, such as APP.ACTIVATE, to refer to the program. In Microsoft Excel for the Macintosh with system software version 6.0, if EXEC is successful, it returns TRUE. If EXEC is unsuccessful, it returns the #VALUE! error value.

Examples

In Microsoft Excel for Windows, the following macro formula starts the program . Use paths when the file or program to be started is not in the current directory:

EXEC("C:\WINDOWS\")

The following macro formula starts Microsoft Word for Windows and loads the document :

EXEC("C:\WINWORD\ C:\MYFILES\")

In Microsoft Excel for the Macintosh, the following macro formula starts Microsoft Word:

EXEC("HARD DISK:APPS:WORD")

Related Functions

APP.ACTIVATE   Switches to another application

EXECUTE   Carries out a command in another application

INITIATE   Opens a channel to another application

   Sends a key sequence to an application

TERMINATE   Closes a channel to another application

REQUEST   Requests an array of a specific type of information from an application with which you have a dynamic data exchange (DDE) link

POKE   Sends data to another application with which you have a dynamic data exchange (DDE) link

EXECUTE

Carries out commands in another program with which you have a dynamic data exchange

(DDE) link. Use with EXEC, INITIATE, and to run another program through Microsoft Excel. ( is available only in Microsoft Excel for Windows.)

Important   Microsoft Excel for the Macintosh requires system software version 7.0 or later for this function.

Syntax

EXECUTE(channel_num, execute_text)

Channel_num    is a number returned by a previously run INITIATE function. Channel_num refers to a channel through which Microsoft Excel communicates with another program.

Execute_text    is a text string representing commands you want to carry out in the program specified by channel_num. The form of execute_text depends on the program you are referring to. To include specific key sequences in execute_text, use the format described under key_text in the function.

If EXECUTE is not successful, it returns one of the following error values:

Value returned

 

Situation

 

#VALUE!

Channel_num is not a valid channel number.

 

 

#N/A

The program you are accessing is busy.

 

 

#DIV/0!

The program you are accessing does not respond after a certain length of time or you have pressed ESC to cancel.

 

 

#REF!

The keys specified in execute_text are refused by the application which you want to access.

 

           

Remarks

Commands sent to another program with EXECUTE will not work when a dialog box is displayed in the program. In Microsoft Excel for Windows, you can use to send commands that make selections in a dialog box.

Examples

The following macro formula sends the number 25 and a carriage return to the application identified by channel_num 14:

EXECUTE(14, "25~")

Related Functions

EXEC   Starts another application

INITIATE   Opens a channel to another application

POKE   Sends data to another application

REQUEST   Returns data from another application

   Sends a key sequence to an application

TERMINATE   Closes a channel to another application

EXPON

Predicts a value based on the forecast for the prior period, adjusted for the error in that prior forecast.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

EXPON(inprng, outrng, damp, stderrs, chart)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Damp    is the damping factor. If omitted, damp is 0.3.

Stderrs    is a logical value. If TRUE, standard error values are included in the output table. If FALSE, standard errors are not included.

Chart    is a logical value. If TRUE, EXPON generates a chart for the actual and forecast values. If FALSE, the chart is not generated.

Related Function

MOVEAVG   Returns values along a moving average trend

EXTEND.POLYGON

Adds vertices to a polygon. This function must immediately follow a CREATE.OBJECT function or another EXTEND.POLYGON function. Use multiple EXTEND.POLYGON functions to create arbitrarily complex polygons. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

EXTEND.POLYGON(array)

Array    is an array of values, or a reference to a range of cells containing values, that indicate the position of vertices in the polygon. The position is measured in points and is relative to the upper-left corner of the polygon's bounding rectangle. 

•   A vertex is a point. Each vertex is defined by a pair of coordinates in one row of array.

•   The polygon is defined by the array argument to the CREATE.OBJECT function and to all the immediately following EXTEND.POLYGON functions.

•   If the polygon contains many vertices, one array may not be sufficient to define it. If the number of elements in the formula exceeds 1024, you must include additional EXTEND.POLYGON functions. If you're recording a macro, Microsoft

Excel automatically records additional EXTEND.POLYGON functions as needed.

Related Functions

CREATE.OBJECT   Creates an object

FORMAT.SHAPE   Inserts, moves, or deletes vertices of the selected polygon

EXTRACT

Equivalent to choosing the Extract command from the Data menu in Microsoft Excel version 4.0. Finds database records that match the criteria defined in the criteria range and copies them into a separate extract range.

Syntax

EXTRACT(unique)

EXTRACT?(unique)

Unique    is a logical value corresponding to the Unique Records Only check box in the Extract dialog box. 

•   If unique is TRUE, Microsoft Excel selects the check box and excludes duplicate records from the extract list.

•   If unique is FALSE or omitted, Microsoft Excel clears the check box and extracts all records matching the criteria. 

Related Functions

   Finds records in a database

SET.CRITERIA   Defines the name Criteria for the selected range on the active sheet

SET.DATABASE   Defines the name Database for the selected range on the active sheet

SET.EXTRACT   Defines the name Extract for the selected range on the active sheet

FCLOSE

Closes the specified file.

Syntax

FCLOSE(file_num)

File_num    is the number of the file you want to close. File_num is returned by the FOPEN function that originally opened the file. If file_num is not a valid file number, FCLOSE halts the macro and returns the #VALUE! error value.

Examples

The following function closes the file identified by FileNumber:

FCLOSE(FileNumber)

Related Functions

CLOSE   Closes the active window

FILE.CLOSE   Closes the active workbook

FOPEN   Opens a file with the type of permission specified

FILE.CLOSE

Equivalent to clicking the Close command on the File menu. Closes the active workbook.

Syntax

FILE.CLOSE(save_logical, route_logical)

Save_logical    is a logical value specifying whether to save the file before closing it.

Save_logical

 

Result

 

TRUE

Saves the workbook

 

 

FALSE

Does not save the workbook

 

 

Omitted

If you've made changes to the workbook, displays a dialog box asking if you want to save the workbook

 

           

Route_logical    is a logical value that specifies whether to route the file after closing it. This argument is ignored if there is not a routing slip present.

Route_logical

 

Result

 

TRUE

Routes the file

 

 

FALSE

Does not route the file

 

           

Omitted   If you've specified recipients for routing, displays a dialog box asking if you want to save the file

Remarks

If you make any changes to the structure of a workbook, such as the name of sheets, their order, and so on, then a message will be displayed reminding you that there are unsaved changes, regardless of the save_logical value.

Note   When you use the FILE.CLOSE function, Microsoft Excel does not run any Auto_Close macros before closing the workbook.

Related Functions

CLOSE   Closes the active window

   Closes all unprotected windows

FCLOSE   Closes a text file

FILE.DELETE

Deletes a file from the disk. Although you will normally delete files manually, you can, for example, use FILE.DELETE in a macro to delete temporary files created by the macro.

Syntax

FILE.DELETE(file_text)

FILE.DELETE?(file_text)

File_text    is the name of the file to delete.

Remarks 

•    If Microsoft Excel can't find file_text, it displays a message saying that it cannot delete the file. To avoid this, include the entire path in file_text. See the following second and fifth examples. You can also use FILES to generate an array of filenames and then check if the file you want to delete is in the array.

•    If a file is open when you delete it, the file is removed from the disk but remains open in Microsoft Excel.

•    In the dialog-box form, FILE.DELETE?, you can use an asterisk (*) to represent any series of characters and a question mark (?) to represent any single character. See the following third and sixth examples. 

Examples

In Microsoft Excel for Windows, the following macro formula deletes a file called from the current directory:

FILE.DELETE("")

The following macro formula deletes a file called kept in the EXCEL\SALES subdirectory:

FILE.DELETE("C:\EXCEL\SALES\")

The following macro formula displays the Delete dialog box listing all documents whose extensions begin with the letters "XL":

FILE.DELETE?("*.XL?")

In Microsoft Excel for the Macintosh, the following macro formula deletes a file called CHART1 from the current folder:

FILE.DELETE("CHART1")

The following macro formula deletes a file called 1992 INFO kept in a series of nested folders:

FILE.DELETE("HARD DISK:EXCEL 5:SALES WORKSHEETS:1992 INFO")

The following macro formula displays the Delete dialog box listing all documents beginning with the word "Clients":

FILE.DELETE?("Clients*")

Related Functions

FILE.CLOSE   Closes the active workbook

FILES   Returns the filenames in the specified directory or folder

FILES

Returns a horizontal text array of the names of all files in the specified directory or folder. Use FILES to build a list of filenames upon which you want your macro to operate.

Syntax

FILES(directory_text)

Directory_text    specifies which directories or folders to return filenames from. 

•   Directory_text accepts an asterisk (*) to represent a series of characters and a question mark (?) to represent a single character in filenames.

•   If directory_text is not specified, FILES returns filenames from the current directory. 

Remarks

If you enter FILES in a single cell, only one filename is returned. You will normally use FILES with to assign the returned array to a name. See the last example below.

Tips   You can use COLUMNS to count the number of entries in the returned array. You can use TRANSPOSE to change a horizontal array to a vertical one.

Examples

In Microsoft Excel for Windows, the following macro formula returns the names of all files starting with the letter F in the current directory or folder:

FILES("F*.*")

When entered as an array formula in several cells, the following macro formula returns the filenames in the current directory to those cells. If the directory contains fewer files than can fit in the selected cells, the #N/A error value appears in the extra cells.

FILES()

In Microsoft Excel for Windows, the following macro formula returns all files starting with "SALE" and ending with the .XLS extension in the \EXCEL\CHARTS subdirectory:

FILES("C:\EXCEL\CHARTS\SALE*.XLS")

In Microsoft Excel for the Macintosh, the following macro formula returns all files starting with "SALE" in the nested CHART folder:

FILES("DISK:EXCEL:CHART:SALE*")

The following macro stores the names of the files in the current directory in the named array FileArray

("FileArray",FILES())

Related Functions

DOCUMENTS   Returns the names of the specified open workbooks

FILE.DELETE   Deletes a file

OPEN   Opens a workbook

   Defines a name as a value

Equivalent to copying cells or automatically filling a selection by dragging the fill selection handle with the mouse (the AutoFill feature).

Syntax

(destination_ref, copy_only)

Destination_ref    is the range of cells into which you want to fill data. The top, bottom, left, or right end of destination_ref must include all of the cells in the source reference (the current selection).

Copy_only    is a number specifying whether to copy cells or perform an AutoFill operation.

Value

 

Result

0          or omitted Normal AutoFill

1          or TRUE      Copy cells

2          Copy formats

3          Fill values

4          Increment

5          Increment by day

6          Increment by weekday

7          Increment by month

8          Increment by year

9          Linear trend

10          Growth trend

Related Functions

COPY   Copies and pastes data or objects

DATA.SERIES   Fills a range of cells with a series of numbers or dates

, , FILL.RIGHT,

Equivalent to clicking the Down, Left, Right, and Up commands, respectively, on the Fill submenu of the Edit menu.

Syntax

( )

( )

FILL.RIGHT( )

( )

copies the contents and formats of the cells in the top row of a selection into the rest of the rows in the selection.

copies the contents and formats of the cells in the right column of a selection into the rest of the columns in the selection.

FILL.RIGHT copies the contents and formats of the cells in the left column of a selection into the rest of the columns in the selection.

copies the contents and formats of the cells in the bottom row of a selection into the rest of the rows in the selection.

Remarks

If you have a multiple selection, each range in the selection is filled separately with the contents of the source range.

Related Functions

COPY   Copies and pastes data or objects

DATA.SERIES   Fills a range of cells with a series of numbers or dates

   Copies cells or automatically fills a selection

   Enters a formula in the specified range

FILL.GROUP

Equivalent to choosing the Across Worksheets command from the Fill submenu on the Edit menu. Copies the contents of the active worksheet's selection to the same area on all other worksheets in the group. Use FILL.GROUP to fill a range of cells on all worksheets in a group at once.

Syntax

FILL.GROUP(type_num)

FILL.GROUP?(type_num)

Type_num    is a number from 1 to 3 that corresponds to the choices in the Fill Across Worksheets dialog box.

Type_num

 

Type of information filled

1        All

2        Contents

3        Formats

Related Functions

NEW   Creates a new workbook

WORKBOOK.SELECT   Selects one or more sheets in a workbook

FILTER

Filters lists of data one column at a time. Only one list can be filtered on any one sheet at a time.

Syntax

FILTER(field_num, criteria1, operation, criteria2)

FILTER?(field_num, criteria1, operation, criteria2)

Field_num    is the number of the field that you want to filter. Fields are numbered from left to right starting with 1.

Criteria1    is a text string specifying criteria for filtering a list, such as ">2". If you want to include all items in the list, omit this argument.

Operation    is a number that specifies how you want criteria2 used with criteria1:

Number

 

Operation Used

1        AND

2        OR

Criteria2    is a text string specifying criteria for filtering a list, such as ">2". If you include this argument, operation is required.

Remarks

If you omit all arguments, FILTER toggles the display of filter arrows.

Related Function

FILTER.ADVANCED   Lets you set options for filtering a list

FILTER.ADVANCED

Equivalent to choosing the Advanced Filter command from the Filter submenu on the Data menu. Lets you set options for filtering a list.

Syntax

FILTER.ADVANCED(operation, list_ref, criteria_ref, copy_ref, unique)

FILTER.ADVANCED?(operation, list_ref, criteria_ref, copy_ref, unique)

Operation    is a number specifying whether to copy the filter list to a new location. To filter a list without copying, use 1; to copy the filter list to a new location, use 2.

List_ref    specifies the location of the list to be filtered. If operation is 1, then list_ref must be on the active sheet.

Criteria_ref    is a reference to a range containing criteria for filtering the list. If omitted, uses "All" as the criteria.

Copy_ref    is a reference on the active sheet where you want the filtered list copied. Ignored if operation is 1.

Unique    is a logical value that specifies whether only unique records are displayed. To display only unique records, use TRUE. To display all records that match the criteria, use FALSE or omit this argument.

Related Function

FILTER   Filters lists of data one column at a time

Equivalent to choosing the Show All command from the Filter submenu on the Data menu. Displays all items in a filtered list.

Syntax

()

Equivalent to choosing the Find File command from the File menu in Microsoft Excel version 5.0. Lets you search for files based on criteria such as author or creation date.

Syntax

?( )

Remarks

This function has a dialog-box form only.

FONT

Equivalent to clicking the Font command on the Options menu in Microsoft Excel for the Macintosh version 1.5 or earlier. This function is included only for macro compatibility. Sets the font for the Normal style. Microsoft Excel now uses the FONT.PROPERTIES and DEFINE.STYLE functions. For more information, see FONT.PROPERTIES and DEFINE.STYLE.

Syntax

FONT(name_text, size_num)

FONT?(name_text, size_num)

Related Functions

DEFINE.STYLE   Creates or changes a cell style

FONT.PROPERTIES   Sets various font properties

FONT.PROPERTIES

Equivalent to choosing the Cells command from the Format menu. Applies a font and other attributes to the selection. Applies to cells, charts, and text boxes and buttons on worksheets and macro sheets.

Syntax

FONT.PROPERTIES(font, font_style, size, strikethrough, superscript, subscript, outline, shadow, underline, color, normal, background, start_char, char_count)

FONT.PROPERTIES?(font, font_style, size, strikethrough, superscript, subscript, outline, shadow, underline, color, normal, background, start_char, char_count)

Arguments correspond to check boxes or options in the Font tab on the Format Cells dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the format is not changed.

Font    is the name of the font as it appears on the Font tab. For example, Courier is a font name.

Font_style    is the name of the font style as it appears on the Font tab. For example, Bold Italic is a font style.

Size    is the font size, in points.

Strikethrough    corresponds to the Strikethrough check box.

Superscript    corresponds to the Superscript check box

Subscript    corresponds to the Subscript check box

Outline    corresponds to the Outline check box. Outline fonts are available in Microsoft Excel for the Macintosh. For macro compatibility, this argument is ignored by Microsoft Excel for Windows..

Shadow    corresponds to the Shadow check box. Shadow fonts are available in Microsoft Excel for the Macintosh. For macro compatibility, this argument is ignored by Microsoft Excel for Windows.

Note   For macro compatibility with Microsoft Excel for the Macintosh, the presence of the outline and shadow arguments do not prevent the macro from working on Microsoft Excel for Windows, nor does their absence prevent it from working on the Macintosh.

Underline    corresponds to the Underline Drop-down box.

Underline

 

Type applied

0         None

1         Single

2         Double

3         Single Accounting

4         Double Accounting

Color    is a number from 0 to 56 corresponding to the colors listed in the Color box; 0 corresponds to automatic color.

Normal    corresponds to the Normal Font check box. Applies the default font for your system

Background    is a number from 1 to 3 specifying which type of background to apply to text in a chart.

Background

 

Type of background applied

1         Automatic

2         Transparent

3         Opaque

Start_char    specifies the first character to be formatted. If start_char is omitted, it is assumed to be 1 (the first character in the cell or text box).

Char_count    specifies how many characters to format. If char_count is omitted, Microsoft Excel formats all characters in the cell or text box starting at start_char.

Remarks

Some extended TrueType styles do not have corresponding arguments to FONT.PROPERTIES. To access an extended TrueType font style, append the style name to the font name in the font argument. For example, the font Taipei can be formatted in an upside-down style by specifying "Taipei Upside-down" as the font argument. For more information about TrueType, see your Microsoft Windows documentation.

Related Functions

ALIGNMENT   Aligns or wraps text in cells

FORMAT.NUMBER   Applies a number format to the selection

   Formats a worksheet text box or a chart text item

FOPEN

Opens a file with the type of permission specified. Unlike OPEN, FOPEN does not load the file into memory and display it; instead, FOPEN establishes a channel with the file so that you can exchange information with it. If the file is opened successfully, FOPEN returns a file ID number. If it can't open the file, FOPEN returns the #N/A error value. Use the file ID number with other file functions (such as FREAD, FWRITE, and FSIZE) when you want to get information from or send information to the file.

Syntax

FOPEN(file_text, access_num)

File_text    is the name of the file you want to open.

Access_num    is a number from 1 to 3 specifying what type of permission to allow to the file:

Access_num

 

Type of permission

1          or omitted        Can read and write to the file (read/write permission)

2          Can read the file, but can't write to the file (read-only permission)

3          Creates a new file with read/write permission

•   If the file doesn't exist and access_num is 3, FOPEN creates a new file.

•   If the file does exist and access_num is 3, FOPEN replaces the contents of the file with any information you supply using the FWRITE or FWRITELN functions.

•   If the file doesn't exist and access_num is 1 or 2, FOPEN returns the #N/A error value. 

Remarks

Use FCLOSE to close a file after you finish using it.

Example

The following function opens a file identified as FileName using read-only permission:

FOPEN(FileName, 2)

Related Functions

FCLOSE   Closes a text file

FREAD   Reads characters from a text file

FWRITE   Writes characters to a text file

OPEN   Opens a workbook

FOR

Starts a FOR-NEXT loop. The instructions between FOR and NEXT are repeated until the loop counter reaches a specified value. Use FOR when you need to repeat instructions a specified number of times. Use when you need to repeat instructions over a range of cells.

Syntax

FOR(counter_text, start_num, end_num, step_num)

Counter_text    is the name of the loop counter in the form of text.

Start_num    is the value initially assigned to counter_text.

End_num    is the last value assigned to counter_text.

Step_num    is a value added to the loop counter after each iteration. If step_num is omitted, it is assumed to be 1.

Remarks 

                ?     Microsoft Excel follows these steps as it executes a FOR-NEXT loop:

Step

 

Action

1       Sets counter_text to the value start_num.

2       If counter_text is greater than end_num (or less than end_num if step_num is negative), the loop ends, and the macro continues with the function after the NEXT function. 

If counter_text is less than or equal to end_num (or greater than or equal to end_num if step_num is negative), the macro continues in the loop.

3       Carries out functions up to the following NEXT function. The NEXT function must be below the FOR function and in the same column.

4       Adds step_num to the loop counter.

5       Returns to the FOR function and proceeds as described in step 2.

                ?    You can interrupt a FOR-NEXT loop by using the BREAK function. 

Example

The following macro starts a FOR-NEXT loop that is executed once for every open window:

FOR("Counter", 1, COLUMNS(WINDOWS()))

Related Functions

BREAK   Interrupts a FOR-NEXT, -NEXT, or WHILE-NEXT loop

   Starts a -NEXT loop

NEXT   Ends a FOR-NEXT, -NEXT, or WHILE-NEXT loop

WHILE   Starts a WHILE-NEXT loop

Starts a -NEXT loop. This function is similar to FOR, except that the instructions between and NEXT are repeated over a range of cells, one cell at a time, and there is no loop counter.

Syntax

(ref_name, area_ref, skip_blanks)

Ref_name    is the name in the form of text that Microsoft Excel gives to the one cell in the range that is currently being operated on; ref_name refers to a new cell during each loop.

Area_ref    is the range of cells on which you want the -NEXT loop to operate and can be a multiple selection. If area_ref is omitted, it is assumed to be the current selection.

Skip_blanks    is a logical value specifying whether Microsoft Excel skips blank cells as it operates on the cells in area_ref.

Skip_blanks

 

Result

TRUE                     Skips blank cells in area_ref

FALSE or omitted Operates on all cells in area_ref

Remarks

operates on each cell in a row from left to right one area at a time before moving to the next row in the selection.

Example

The following macro starts a -NEXT loop and uses the name CurrentCell to refer to the cell in the range that is currently being operated on:

("CurrentCell", SELECTION(), TRUE)

Related Functions

BREAK   Interrupts a FOR-NEXT, -NEXT, or WHILE-NEXT loop

FOR   Starts a FOR-NEXT loop

NEXT   Ends a FOR-NEXT, -NEXT, or WHILE-NEXT loop

WHILE   Starts a WHILE-NEXT loop

Equivalent to clicking the AutoFormat command on the Format menu when a worksheet is active or clicking the AutoFormat button. Formats the selected range of cells from a built-in gallery of formats.

Syntax

(format_num, number, font, alignment, border, pattern, width)

?(format_num, number, font, alignment, border, pattern, width)

Format_num    is a number from 1 to 17 corresponding to the formats in the Table Format list box in the AutoFormat dialog box.

 

Format_num

 

Table Format

0           None

1           or omitted         Classic 1

2           Classic 2

3           Classic 3

4           Accounting 1

5           Accounting 2

6           Accounting 3

7           Colorful 1

8           Colorful 2

9           Colorful 3

10           List 1

11           List 2

12           List 3

13           3D Effects 1

14           3D Effects 2

15           Japan 1 (Far East versions of Microsoft Excel only) 16         Japan 2 (Far East versions of Microsoft Excel only)

17           Accounting 4

18           Simple

The following arguments are logical values corresponding to the Formats To Apply check boxes in the AutoFormat dialog box. If an argument is TRUE or omitted, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box.

Number    corresponds to the Number check box.

Font    corresponds to the Font check box.

Alignment    corresponds to the Alignment check box.

Border    corresponds to the Border check box.

Pattern    corresponds to the Pattern check box.

Width    corresponds to the Column Width/Row Height check box.

Related Functions

ALIGNMENT   Aligns or wraps text in cells

BORDER   Adds a border to the selected cell or object

FONT.PROPERTIES   Applies a font to the selection

FORMAT.NUMBER   Applies a number format to the selection

PATTERNS   Changes the appearance of the selected object

FORMAT.CHART

Equivalent to choosing the Options button in the Chart Type dialog box, which is available when you choose the Chart Type command from the Format menu when a chart is active. Formats the chart according to the arguments you specify.

Syntax

FORMAT.CHART(layer_num, view, overlap, angle, gap_width, gap_depth, chart_depth, doughnut_size, axis_num, drop, hilo, up_down, series_line, labels, vary)

FORMAT.CHART?(layer_num, view, overlap, angle, gap_width, gap_depth, chart_depth, doughnut_size, axis_num, drop, hilo, up_down, series_line, labels, vary)

Several of the following arguments are logical values corresponding to check boxes in the Options tab of Format (chart type) Group dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged.

Layer_num    is a number specifying which chart you want to change.

View    is a number specifying one of the subtypes in the Subtype tab of the Format (type) Group dialog box. The subtype varies depending on the type of chart.

Overlap    is a number from -100 to 100 specifying how you want bars or columns to be positioned. It corresponds to the Overlap edit box in the Options tab on the Format Bar Group Dialog box, which appears when you choose the Bar Group from the Format menu. Overlap is ignored if type_num is not 2 or 3 (bar or column chart). 

•   If overlap is positive, it specifies the percentage of overlap you want for bars or columns. For example, 50 would cause one-half of a bar or column to be covered by an adjacent bar or column. A value of zero prevents bars or columns from overlapping.

•   If overlap is negative, then bars or columns are separated by the specified percentage of the maximum available distance between any two bars or columns.

•   If overlap is omitted, it is assumed to be 0 (bars or columns do not overlap), or it is unchanged if a value was previously set.

Angle    is a number from 0 to 360 specifying the angle of the first pie or doughnut slice (in degrees) if the chart is a pie or doughnut chart. If angle is omitted, it is assumed to be 0, or it is unchanged if a value was previously set.

Gap_width    is a number from 0 to 500 specifying the space between bar or column clusters as a percentage of the width of a bar or column. It corresponds to the Gap Width edit box in the Options tab on the Format Bar Group Dialog box, which appears when you choose the Bar Group from the Format menu. 

•   Gap_width is ignored if type_num is not 2, 3, 8, or 12 (bar or column chart).

•   If Gap_width is omitted, it is assumed to be 50, or it is unchanged if a value was previously set. 

The next two arguments are for 3-D charts only, and correspond to check boxes in the Options tab of Format (chart type) Group dialog box.

Gap_depth    is a number from 0 to 500 specifying the depth of the gap in front of and behind a bar, column, area, or line as a percentage of the depth of the bar, column, area, or line. 

•   Gap_depth is ignored if the chart is a pie chart or if it is not a 3-D chart.

•   If gap_depth is omitted and the chart is a 3-D chart, gap_depth is assumed to be 50, or it is unchanged if a value was previously set. If gap_depth is omitted and the view is side-by-side, stacked, or stacked 100%, gap_depth is assumed to be 0, or it is unchanged if a value was previously set. 

Chart_depth    is a number from 20 to 2000 specifying the visual depth of the chart as a percentage of the width of the chart. 

•   Chart_depth is ignored if the chart is not a 3-D chart.

•   If Chart_depth is omitted, it is assumed to be 100, or it is unchanged if a value was previously set. 

Doughnut_size    specifies the size of the hole in a doughnut chart. Can be a value from 10% - 90%. Default is 50%.

Axis_num    is a number specifying whether to plot the chart on the primary axis or the secondary axis.

Drop    corresponds to the Drop Lines check box. Drop is available only for area and line charts.

Hilo    corresponds to the Hi-Lo Lines check box. Hilo is available only for 2-D line charts.

The next four arguments are logical values corresponding to check boxes in the Options tab of the Format (chart type) Group dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged.

Up_down    corresponds to the Up/Down Bars check box. Up_down is available only for 2-D line charts.

Series_line    corresponds to the Series Lines check box. Series_line is available only for 2-D stacked bar and column charts.

Labels    corresponds to the Radar Axis Labels check box. Labels is available only for radar charts.

Vary    corresponds to the Vary Colors By Point check box. Vary applies only to charts with one data series and is not available for area charts.

Related Functions

   Formats a chart according to the arguments you specify

FORMAT.OVERLAY   Formats an overlay chart

FORMAT.CHARTTYPE

Changes the chart type for a selected data series, a group of data series, or an entire chart.

Syntax

FORMAT.CHARTTYPE(apply_to, group_num, dimension, type_num)

FORMAT.CHARTTYPE?(apply_to, group_num, dimension, type_num)

Apply_to    is a number from 1 to 3 specifying what part of a chart the new chart type effects.

Value

 

Part of chart

1     Selected data series

2     Group of data series

3     Entire chart

Group_num    corresponds to the number of the group you want to change as listed in the Group list box of the Chart Type dialog box, which appears when you click Chart Type from the Format menu while a chart is active. Groups are numbered starting with 1 for the group at the top of the list. This argument is required if apply_to equals 2; otherwise it is ignored.

Dimension    specifies whether to apply a 2-D or 3-D chart type. Use 1 for a 2-D chart type or 2 for a 3-D chart type. If omitted, uses the same dimension as the series, group, or chart to be changed.

Type_num    specifies the chart type to apply. Meaning of type_num varies depending on the value of dimension:

Type_num

 

Chart type if dimension is 1

1        Area or 3-D area

2        Bar or 3-D bar

3        Column or 3-D column

4        Line or 3-D line

5        Pie or 3-D pie

6        Doughnut or 3-D surface

7        Radar

8        XY (scatter)

Related Function

FORMAT.CHART   Formats the selected chart

Equivalent to choosing the Cells command from the Format menu, and then selecting Font tab from the Format Cells dialog box. This function is included for compatibility with Microsoft Excel version 4.0. Use FONT.PROPERTIES to set various font properties. has three syntax forms. Syntax 1 is for cells; syntax 2 is for text boxes and buttons; syntax 3 is used with all chart items (axes, labels, text, and so on).

Syntax 1

Cells

(name_text, size_num, bold, italic, underline, strike, color, outline, shadow)

?(name_text, size_num, bold, italic, underline, strike, color, outline, shadow) Syntax 2

Text boxes and buttons on worksheets and macro sheets

(name_text, size_num, bold, italic, underline, strike, color, outline, shadow, object_id_text, start_num, char_num)

?(name_text, size_num, bold, italic, underline, strike, color, outline, shadow, object_id_text, start_num, char_num)

Syntax 3

Chart items including unattached chart text

(color, backgd, apply, name_text, size_num, bold, italic, underline, strike, outline, shadow, object_id_text, start_num, char_num)

?(color, backgd, apply, name_text, size_num, bold, italic, underline, strike, outline, shadow, object_id_text, start_num, char_num)

Arguments correspond to check boxes and list box items in the Font tab on the Format Cells dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the format is not changed.

Name_text    is the name of the font as it appears in the Font tab. For example, Courier is a font name.

Size_num    is the font size, in points.

Bold    corresponds to the Bold item in the Font Style list box. Makes the selection bold, if applicable.

Italic    corresponds to the Italic item in the Font Style list box. Makes the selection italic, if applicable.

Underline    corresponds to the Underline check box.

Strike    corresponds to the Strikethrough check box.

Color    is a number from 0 to 56 corresponding to the colors in the Font tab; 0 corresponds to automatic color.

Outline    corresponds to the Outline check box. Outline fonts are available in Microsoft Excel for the Macintosh. For macro compatibility, this argument is ignored by Microsoft Excel for Windows.

Shadow    corresponds to the Shadow check box. Shadow fonts are available in Microsoft Excel for the Macintosh. For macro compatibility, this argument is ignored by Microsoft Excel for Windows.

Note   For macro compatibility with Microsoft Excel for the Macintosh, the presence of the outline and shadow arguments do not prevent the macro from working on Microsoft Excel for Windows, nor does their absence prevent it from working on the Macintosh.

Object_id_text    identifies the text box you want to format (for example, "Text 1", "Text 2", and so on). You can also use the object number alone without the text identifier. For compatibility with earlier versions of Microsoft Excel. This argument is ignored in Microsoft Excel version 5.0 or later.

Start_num    specifies the first character to be formatted. If start_num is omitted, it is assumed to be 1 (the first character in the text box).

Char_num    specifies how many characters to format. If char_num is omitted, Microsoft Excel formats all characters in the text box starting at start_num.

Backgd    is a number from 1 to 3 specifying which type of background to apply to text in a chart.

Backgd

 

Type of background applied

1      Automatic

2      Transparent

3      Opaque

Apply    corresponds to the Apply To All check box. This argument applies to data labels only.

Remarks

Some extended TrueType styles do not have corresponding arguments to . To access an extended TrueType font style, append the style name to the font name in name_text. For example, the font Taipei can be formatted in an upside-down style by specifying "Taipei Upside-down" as the name_text argument. For more information about TrueType, see your Microsoft Windows documentation.

Related Functions

ALIGNMENT   Aligns or wraps text in cells

FONT.PROPERTIES   Sets various font attributes

FORMAT.NUMBER   Applies a number format to the selection

   Formats a worksheet text box or a chart text item

FORMAT.LEGEND

Equivalent to clicking the Selected Legend command on the Format menu when a chart is active. Determines the position and orientation of the legend on a chart and returns TRUE; returns an error message if the legend is not already selected.

Syntax

FORMAT.LEGEND(position_num)

FORMAT.LEGEND?(position_num)

Position_num    is a number from 1 to 5 specifying the position of the legend.

Position_num

 

Position of legend

1          Bottom

2          Corner

3          Top

4          Right

5          Left

Related Functions

   Moves the selected object

   Sizes an object

LEGEND   Adds or deletes a chart legend

Equivalent to clicking the Main Chart command on the Format menu in Microsoft Excel version 4.0. Formats a chart according to the arguments you specify. This function is included for compatibility with Microsoft Excel version 4.0. In Microsoft Excel version 5.0 or later, this is equivalent to clicking the Chart Type command on the Format menu. You can also use the FORMAT.CHART function.

Syntax

(type_num, view, overlap, gap_width, vary, drop, hilo, angle, gap_depth, chart_depth, up_down, series_line, labels, doughnut_size)

?(type_num, view, overlap, gap_width, vary, drop, hilo, angle, gap_depth, chart_depth, up_down, series_line, labels, doughnut_size) Type_num    is a number specifying the type of chart.

Type_num

 

Chart

1        Area

2        Bar

3        Column

4        Line

5        Pie

6        XY (Scatter)

7        3-D Area

8        3-D Column

9        3-D Line

10        3-D Pie

11        Radar

12        3-D Bar

13        3-D Surface

14        Doughnut

View    is a number specifying one of the views in the Data View box in the Main Chart dialog box. The view varies depending on the type of chart.

Overlap    is a number from -100 to 100 specifying how you want bars or columns to be positioned. It corresponds to the Overlap box in the Main Chart dialog box. Overlap is ignored if type_num is not 2 or 3 (bar or column chart). 

•   If overlap is positive, it specifies the percentage of overlap you want for bars or columns. For example, 50 would cause one-half of a bar or column to be covered by an adjacent bar or column. A value of zero prevents bars or columns from overlapping.

•   If overlap is negative, then bars or columns are separated by the specified percentage of the maximum available distance between any two bars or columns.

•   If overlap is omitted, it is assumed to be 0 (bars or columns do not overlap), or it is unchanged if a value was previously set.

Gap_width    is a number from 0 to 500 specifying the space between bar or column clusters as a percentage of the width of a bar or column. It corresponds to the Gap Width box in the Main Chart dialog box. 

•   Gap_width is ignored if type_num is not 2, 3, 8, or 12 (bar or column chart).

•   If gap_width is omitted, it is assumed to be 50, or it is unchanged if a value was previously set.

Several of the following arguments are logical values corresponding to check boxes in the Main Chart dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged.

Vary    corresponds to the Vary By Categories check box. Vary applies only to charts with one data series and is not available for area charts.

Drop    corresponds to the Drop Lines check box. Drop is available only for area and line charts.

Hilo    corresponds to the Hi-Lo Lines check box. Hilo is available only for line charts.

Angle    is a number from 0 to 360 specifying the angle of the first pie slice (in degrees) if the chart is a pie chart. If angle is omitted, it is assumed to be 0, or it is unchanged if a value was previously set.

The next two arguments are for 3-D charts only.

Gap_depth    is a number from 0 to 500 specifying the depth of the gap in front of and behind a bar, column, area, or line as a percentage of the depth of the bar, column, area, or line. 

•   Gap_depth is ignored if the chart is a pie chart or if it is not a 3-D chart.

•   If gap_depth is omitted and the chart is a 3-D chart, gap_depth is assumed to be 50, or it is unchanged if a value was previously set. If gap_depth is omitted and the view is side-by-side, stacked, or stacked 100%, gap_depth is assumed to be 0, or it is unchanged if a value was previously set. 

Chart_depth    is a number from 20 to 2000 specifying the visual depth of the chart as a percentage of the width of the chart. Chart_depth corresponds to the Chart Depth box in the Main Chart dialog box. 

•   Chart_depth is ignored if the chart is not a 3-D chart.

•   If chart_depth is omitted, it is assumed to be 100, or it is unchanged if a value was previously set. 

The next three arguments are logical values corresponding to check boxes in the Main Chart dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged. The final argument is for compatibility with Microsoft Excel version 4.0.

Up_down    corresponds to the Up/Down Bars check box. Up_down is available only for line charts.

Series_line    corresponds to the Series Lines check box. Series_line is available only for stacked bar and column charts.

Labels    corresponds to the Radar Axis Labels check box. Labels is available only for radar charts.

Doughnut_size    specifies the size of the hole in a doughnut chart. Can be a value from 10% - 90%. Default is 50%

Related Functions

FORMAT.CHART   Formats a chart

FORMAT.OVERLAY   Formats an overlay chart

Equivalent to moving an object with the mouse. Moves the selected object to the specified position and, if successful, returns TRUE. If the selected object cannot be moved,

returns FALSE. There are three syntax forms of this function. Use syntax 1 to move worksheet objects. Use syntax 2 to move chart items. Use syntax 3 to move pie-chart and doughnut-chart items. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax 1   Moves worksheet items

Syntax 2   Moves chart items

Syntax 3   Moves pie-chart and doughnut-chart items

SYNTAX 1

Equivalent to moving an object with the mouse. Moves the selected object to the specified position and, if successful, returns TRUE. If the selected object cannot be moved,

returns FALSE. There are three syntax forms of this function. Use syntax 1 to move worksheet objects. Use syntax 2 to move chart items. Use syntax 3 to move pie-chart and doughnut-chart items. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(x_offset, y_offset, reference)

?(x_offset, y_offset, reference)

X_offset    specifies the horizontal position to which you want to move the object and is measured in points from the upper-left corner of the object to the upper-left corner of the cell specified by reference. A point is 1/72nd of an inch.

Y_offset    specifies the vertical position to which you want to move the object and is measured in points from the upper-left corner of the object to the upper-left corner of the cell specified by reference.

Reference    specifies which cell or range of cells to place the object in relation to. 

•   If reference is a range of cells, only the upper-left cell is used.

•   If reference is omitted, it is assumed to be cell A1. 

Remarks

The position of an object is based on its upper-left corner. For ovals and arcs, the position is based on the upper-left corner of the bounding rectangle of the object.

Example

The following macro formula moves an object on the active worksheet so that it is 10 points horizontally offset and 15 points vertically offset from cell D4:

(10, 15, !$D$4)

Related Functions

CREATE.OBJECT   Creates an object

   Sizes an object

   Moves a window

Syntax 2   Moves chart items

Syntax 3   Moves pie-chart and doughnut-chart items

SYNTAX 2

Equivalent to moving an object with the mouse. Moves the base of the selected object to the specified position and, if successful, returns TRUE. If the selected object cannot be moved, returns FALSE. There are three syntax forms of this function. Use syntax 3 to move pie-chart and doughnut-chart items. Use syntax 1 to move worksheet objects. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(x_pos, y_pos)

?(x_pos, y_pos)

X_pos    specifies the horizontal position to which you want to move the object and is measured in points from the base of the object to the lower-left corner of the window. A point is 1/72nd of an inch.

Y_pos    specifies the vertical position to which you want to move the object and is measured in points from the base of the object to the lower-left corner of the window.

Remarks 

•    The base of a text label on a chart is the lower-left corner of the text rectangle.

•    The base of an arrow is the end without the arrowhead.

•    The base of a pie slice is the point. 

Example

On a chart, the following macro formula moves the base of the selected chart object 10 points to the right of and 20 points above the lower-left corner of the window:

(10, 20)

Related Functions

   Sizes an object

   Moves a window

Syntax 1   Moves worksheet items

Syntax 3   Moves pie-chart and doughnut-chart items

SYNTAX 3

Equivalent to exploding by moving a pie-chart or doughnut-chart slice with the mouse. Sets the percentage of pie-chart or doughnut-chart slice explosion, and, if successful, returns TRUE. If the selected object cannot be exploded, returns FALSE. There are three syntax forms of this function. Use syntax 1 to move worksheet items. Use syntax 2 to move chart items. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(explosion_num)

Explosion_num    is a number specifying the explosion percentage for the selected pie slice or the entire chart (if the series is selected). Zero is no explosion (the tip of the slice is in the center of the pie).

Related Functions

   Sizes an object

Syntax 1   Moves worksheet items

Syntax 2   Moves chart items

   Moves a window

FORMAT.NUMBER

Equivalent to choosing the Number tab in the Format Cells dialog box, which appears when you choose Cells from the Format menu. Formats numbers, dates, and times in the selected cells, data labels, and axis labels on charts. Use FORMAT.NUMBER to apply built-in formats or to create and apply custom formats.

Syntax

FORMAT.NUMBER(format_text)

FORMAT.NUMBER?(format_text)

Format_text    is a format string, such as "#, ##0.00", specifying which format to apply to the selection.

Related Functions

DELETE.FORMAT   Deletes the specified custom number format

FONT.PROPERTIES   Applies a font to the selection

   Formats a sheet text box or a chart text item

FORMAT.OVERLAY

Equivalent to clicking the Overlay command on the Format menu in Microsoft Excel version 4.0. Formats the overlay chart according to the arguments you specify.

Syntax

FORMAT.OVERLAY(type_num, view, overlap, gap_width, vary, drop, hilo, angle, series_dist, series_num, up_down, series_line, labels)

FORMAT.OVERLAY?(type_num, view, overlap, gap_width, vary, drop, hilo, angle, series_dist, series_num, up_down, series_line, labels)

Type_num    is a number specifying the type of chart.

Type_num

 

Chart

1        Area

2        Bar

3        Column

4        Line

5        Pie

6        XY (Scatter)

11                  Radar

14                  Doughnut

View    is a number specifying one of the views in the Data View box in the Overlay dialog box. The view varies depending on the type of chart.

Overlap    is a number from -100 to 100 specifying how you want bars or columns to be positioned. It corresponds to the Overlap box in the Overlay dialog box. Overlap is ignored if type_num is not 2 or 3 (bar or column chart). 

•   If overlap is positive, it specifies the percentage of overlap you want for bars or columns. For example, 50 would cause one-half of a bar or column to be covered by an adjacent bar or column.

•   If overlap is negative, then bars or columns are separated by the specified percentage of the maximum available distance between any two bars or columns.

•   If overlap is omitted, it is assumed to be 0 (bars or columns do not overlap), or it is unchanged if a value was previously set. 

Gap_width    is a number from 0 to 500 specifying the space between bar or column clusters as a percentage of the width of a bar or column. 

•   Gap_width is ignored if type_num is not 2 or 3 (bar or column chart).

•   If gap_width is omitted, it is assumed to be 50, or it is unchanged if a value was previously set. 

Several of the following arguments are logical values corresponding to check boxes in the Overlay dialog box. If an argument is TRUE, Microsoft Excel selects the corresponding check box; if FALSE, Microsoft Excel clears the check box. If an argument is omitted, the setting is unchanged.

Vary    corresponds to the Vary By Categories check box. Vary is not available for area charts.

Drop    corresponds to the Drop Lines check box. Drop is available only for area and line charts.

Hilo    corresponds to the Hi-Lo Lines check box. Hilo is available only for line charts.

Angle    is a number from 0 to 360 specifying the angle of the first pie slice (in degrees) if the chart is a pie chart. If angle is omitted, it is assumed to be 0, or it is unchanged if a value was previously set.

Series_dist    is the number 1 or 2 and specifies automatic or manual series distribution. 

•   If series_dist is 1 or omitted, Microsoft Excel uses automatic series distribution.

•   If series_dist is 2, Microsoft Excel uses manual series distribution, and you must specify which series is first in the distribution by using the series_num argument. 

Series_num    is the number of the first series in the overlay chart and corresponds to the First Overlay Series box in the Overlay dialog box. If series_dist is 1 (automatic series distribution), this argument is ignored.

Up_down    corresponds to the Up/Down Bars check box. Up_down is available only for line charts.

Series_line    corresponds to the Series Lines check box. Series_line is available only for stacked bar and column charts.

Labels    corresponds to the Radar Axis Labels check box. Labels is available only for radar charts.

Related Functions

DELETE.OVERLAY   Deletes the overlay on a chart

FORMAT.CHART   Formats a chart

FORMAT.SHAPE

Equivalent to clicking the reshape button on the Drawing toolbar and then inserting, moving, or deleting vertices of the selected polygon. A vertex is a point defined by a pair of coordinates in one row of the array that defines the polygon. The array is created by CREATE.OBJECT and EXTEND.POLYGON functions.

Syntax

FORMAT.SHAPE(vertex_num, insert, reference, x_offset, y_offset)

Vertex_num    is a number corresponding to the vertex you want to insert, move, or delete.

Insert    is a logical value specifying whether to insert a vertex, or move or delete a vertex. 

•   If insert is TRUE, Microsoft Excel inserts a vertex between the vertices vertex_num and vertex_num-1. The number of the new vertex then becomes vertex_num. The number of the vertex previously identified by vertex_num becomes vertex_num+1, and so on.

•   If insert is FALSE, Microsoft Excel deletes the vertex (if the remaining arguments are omitted) or moves the vertex to the position specified by the remaining arguments. 

Reference    is the reference from which the vertex you are inserting or moving is measured; that is, the cell or range of cells to use as the basis for the x and y offsets. 

•   If reference is a range of cells, only the upper-left cell is used.

•   If reference is omitted, the vertex is measured from the upper-left corner of the polygon's bounding rectangle. 

X_offset    is the horizontal distance from the upper-left corner of reference to the vertex. X_offset is measured in points. A point is 1/72nd of an inch. If reference is omitted, x_offset specifies the horizontal distance from the upper-left corner of the polygon bounding rectangle.

Y_offset    is the vertical distance from the upper-left corner of reference to the vertex. Y_offset is measured in points. If reference is omitted, y_offset specifies the vertical distance from the upper-left corner of the polygon bounding rectangle. Remarks

You cannot delete a vertex if only two vertices remain.

Examples

The following macro formula deletes the second vertex of the selected polygon:

FORMAT.SHAPE(2, FALSE)

The following macro formula moves the thirteenth vertex 6 points to the right and 4 points below the upper-left corner of cell B5 on the active worksheet:

FORMAT.SHAPE(13, FALSE, !$B$5, 6, 4)

The following macro formula inserts a new vertex between vertices 2 and 3. The new vertex is 60 points to the right and 75 points below the upper-left corner of the polygon's bounding rectangle:

FORMAT.SHAPE(3, TRUE, , 60, 75)

Related Functions

CREATE.OBJECT   Creates an object

EXTEND.POLYGON   Adds vertices to a polygon

Equivalent to sizing an object with the mouse. Sizes the selected object and returns TRUE. If the selected chart object cannot be sized, returns FALSE. There are two syntax forms of this function. Use syntax 1 to size worksheet objects and chart items absolutely. Use syntax 2 relative to a cell or range of cells to size only worksheet objects. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax 1   Sizes worksheet objects and chart items

Syntax 2   Sizes worksheet objects relative to a cell or range

SYNTAX 1

Equivalent to sizing an object with the mouse. Sizes the selected object and returns TRUE. If the selected chart object cannot be sized, returns FALSE. There are two syntax forms of this function. Use syntax 1 to size worksheet objects and chart items absolutely. Use syntax 2 relative to a cell or range of cells to size only worksheet objects. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(width, height)

?(width, height)

Width    specifies the width of the selected object, measured in points. A point is 1/72nd of an inch.

Height    specifies the height of the selected object, measured in points.

You do not always have to use both arguments. For example, if you specify height and not width, the height changes but the width does not.

Remarks 

•    The base of a text label on a chart is the lower-left corner of the text rectangle.

•    The base of an arrow is the end without the arrowhead. 

Related Functions

   Moves the selected object

SIZE   Changes the size of a window

Syntax 2   Sizes worksheet objects relative to a cell or range

SYNTAX 2

Equivalent to sizing an object with the mouse. Sizes the selected worksheet object and returns TRUE. If the selected object cannot be sized, returns FALSE. There are two syntax forms of this function. Use syntax 2 to size worksheet objects relative to a cell or range of cells. Use syntax 1 to size worksheet objects and chart items. It is generally easier to use the macro recorder to enter this function on your macro sheet.

Syntax

(x_off, y_off, reference)

?(x_off, y_off, reference)

X_off    specifies the width of the selected object and is measured in points from the lowerright corner of the object to the upper-left corner of reference. A point is 1/72nd of an inch. If omitted, x_off is assumed to be 0. If reference is omitted, x_off specifies the horizontal size.

Y_off    specifies the height of the selected object and is measured in points from the lowerright corner of the object to the upper-left corner of reference. If omitted, y_off is assumed to be 0. If reference is omitted, y_off specifies the vertical size.

Reference    specifies the cell or range of cells to use as the basis for the offset and for sizing. If reference is a range of cells, only the upper-left cell in the range is used.

Related Functions

   Moves the selected object

SIZE   Changes the size of a window

Syntax 1   Sizes worksheet objects and chart items

Formats the selected worksheet text box or button or any text item on a chart.

Syntax

(x_align, y_align, orient_num, auto_text, auto_size, show_key, show_value, add_indent)

?(x_align, y_align, orient_num, auto_text, auto_size, show_key, show_value, add_indent)

Arguments correspond to check boxes or options in the various tabs on Format Object dialog box. Arguments that correspond to check boxes are logical values. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box; if omitted, the current setting is used.

X_align    is a number from 1 to 4 specifying the horizontal alignment of the text.

X_align

 

Horizontal alignment

1       Left

2       Center

3       Right

4       Justify

Y_align    is a number from 1 to 4 specifying the vertical alignment of the text.

Y_align

 

Vertical alignment

1       Top

2       Center

3       Bottom

4       Justify

Orient_num    is a number from 0 to 3 specifying the orientation of the text.

Orient_num

 

Text orientation

0         Horizontal

1         Vertical

2         Upward

3         Downward

Auto_text    corresponds to the Automatic Text check box. If the selected text was created with the Data Labels command from the Insert menu and later edited, this option restores the original text. Auto_text is ignored for text boxes on worksheets and macro sheets.

Auto_size    corresponds to the Automatic Size check box. If you have changed the size of the border around the selected text, this option restores the border to automatic size. Automatic size makes the border fit exactly around the text no matter how you change the text.

Show_key    corresponds to the Show Legend Key Next to Label check box in the Data Labels dialog box. This argument applies only if the selected text is an attached data label on a chart.

Show_value    corresponds to the Show Value option button in the Format Data Labels dialog box. This argument applies only if the selected text is an attached data label on a chart.

The following list summarizes which arguments apply to each type of text item.

Add_indent   This argument is for only Far East versions of Microsoft Excel.

Text item

 

Arguments that apply

Worksheet text box or button X_align, y_align, orient_num, auto_size

Attached data label                   All arguments

Unattached text label                 X_align, y_align, orient_num, auto_size

Tickmark label                          Orient_num

Related Functions

CREATE.OBJECT   Creates an object

FONT.PROPERTIES   Applies a font to the selection

FORMULA   Enters values into a cell or range or onto a chart

FORMULA

Enters a formula in the active cell or in a reference. There are two syntax forms of this function. Use syntax 1 to enter numbers, text, references, and formulas in a worksheet. Although syntax 1 can also be used to enter values on a macro sheet, you will not generally use FORMULA for this purpose. Use syntax 2 to enter a formula in a chart. For information about setting values on a macro sheet, see "Remarks" in the following topics.

Syntax 1   Enters numbers, text, references, and formulas in a worksheet Syntax 2   Enters formulas in a chart

FORMULA SYNTAX 1

Enters a formula in the active cell or in a reference. If the active sheet is a worksheet, using FORMULA is equivalent to entering formula_text in the cell specified by reference. Formula_text is entered just as if you typed it in the formula bar.

There are two syntax forms of this function. Use syntax 1 to enter numbers, text, references, and formulas in a worksheet. Although syntax 1 can also be used to enter values on a macro sheet, you will not generally use FORMULA for this purpose. Use syntax 2 to enter a formula in a chart. For information about setting values on a macro sheet, see "Remarks" later in this topic.

Syntax

FORMULA(formula_text, reference)

Formula_text    can be text, a number, a reference, or a formula in the form of text, or a reference to a cell containing any of the above. 

•   If formula_text contains references, they must be R1C1-style references, such as "=RC[1]*(1+R1C1)". If you are recording a macro when you enter a formula, Microsoft Excel converts A1-style references to R1C1-style references. For example, if you enter the formula =B2*(1+$A$1) in cell C2 while recording, Microsoft Excel records that action as =FORMULA("=RC[-1]*(1+R1C1)").

•   If formula_text is a formula, the formula is entered. Text arguments must be surrounded by double sets of quotation marks. For example, to enter the formula =IF($A$1="Hello World", 1, 0) in the active cell with the FORMULA function, you would use the formula FORMULA("=IF(R1C1=""Hello World"", 1, 0)")

•   If formula_text is a number, text, or logical value, the value is entered as a constant.

Reference    specifies where formula_text is to be entered. It can be a reference to a cell in the active workbook or an external reference to a workbook. If reference is omitted, formula_text is entered in the active cell.

Remarks

Consider the following guidelines as you choose a function to set values on a worksheet or macro sheet: 

•   Use FORMULA to enter formulas and change values in a worksheet cell.

•   SET.VALUE changes values on the macro sheet. Use SET.VALUE to assign initial values to a reference and to store values during the calculation of the macro.

•   creates names on the macro sheet. Use to create a name and immediately assign a value to the name. 

Examples

If the active sheet is a worksheet, the following macro formula enters the number constant 523 in the active cell:

FORMULA(523)

If the active sheet is a worksheet, the following macro formula enters the result of the INPUT function in cell A5:

FORMULA(INPUT("Enter a formula:", 0), !$A$5)

If you're using R1C1-style references and the active sheet is a worksheet, the following macro formula enters the formula =RC[-1]*(1+R1C1) in the active cell:

FORMULA("=RC[-1]*(1+R1C1)")

If the active sheet is a worksheet, the following macro formulas enter the number 1000 in the cell two rows down and three columns right from the active cell. The R1C1-style formula is shorter, but the OFFSET method may provide faster performance in larger macro sheets.

FORMULA(1000, OFFSET((), 2, 3))

FORMULA(1000, "R[2]C[3]")

The following macro formula enters the phrase "Year to Date" in cell B4 on the sheet named SALES 1993:

FORMULA("Year to Date", 'SALES 1993'!B4)

Related Functions

FORMULA.ARRAY   Enters an array

   Enters a formula in the specified range

SET.VALUE   Sets the value of a cell on a macro sheet

FORMULA Syntax 2   Enters formulas in a chart

FORMULA SYNTAX 2

Enters a text label or SERIES formula in a chart. To enter formulas on a worksheet or macro sheet, use syntax 1 of this function.

Syntax

FORMULA(formula_text)

Formula_text    is the text label or SERIES formula you want to enter into the chart.

 

If

 

Then

 

Formula_text can be treated as a text label and the current selection is a text label

The selected text label is replaced with formula_text.

 

 

Formula_text can be treated as a text label and there is no current selection or the current selection is not a text label

Formula_text creates a new unattached text label.

 

 

Formula_text can be treated as a SERIES formula and the current selection is a

SERIES formula

The selected SERIES formula is replaced with formula_text.

 

 

Formula_text can be treated as a SERIES formula and the current selection is not a

SERIES formula

Formula_text creates a new SERIES formula.

 

         

Remarks

You would normally use the EDIT.SERIES function to create or edit a chart series. For more information, see EDIT.SERIES.

Example

The following macro formula enters a SERIES formula on the chart. If the current selection is a SERIES formula, it is replaced:

FORMULA("=SERIES(""Title"", , {1, 2, 3}, 1)")

Related Functions

EDIT.SERIES   Creates or changes a chart series

FORMULA, Syntax 1   Enters numbers, text, references, and formulas in a worksheet

FORMULA.ARRAY

Enters a formula as an array formula in the range specified or in the current selection. Equivalent to entering an array formula while pressing CTRL+SHIFT+ENTER in Microsoft Excel for Windows or COMMAND+ENTER in Microsoft Excel for the Macintosh.

Syntax

FORMULA.ARRAY(formula_text, reference)

Formula_text    is the text you want to enter in the array. For more information on formula_text, see the first form of FORMULA.

Reference    specifies where formula_text is entered. It can be a reference to a cell on the active worksheet or an external reference to a named workbook. Reference must be a R1C1-style reference in text form. If reference is omitted, formula_text is entered in the active cell.

Examples

If the selection is D25:E25, the following macro formula enters the array formula {=D22:E22+D23:E23} in the range D25:E25:

FORMULA.ARRAY("=R[-3]C:R[-3]C[1]+R[-2]C:R[-2]C[1]")

Regardless of the selection, the following macro formula enters the array formula {=D22:E22+D23:E23} in the range D25:E25:

FORMULA.ARRAY("=R[-3]C:R[-3]C[1]+R[-2]C:R[-2]C[1]", "R25C4:R25C5")

To use FORMULA.ARRAY to put an array in a specific workbook, specify the name of the workbook as an external reference in the reference argument. Using

"[]North!R25C3:R25C4" as the reference argument in the preceding example would enter the array in cells C25:D25 on the worksheet named North in the workbook . Using "SALES!R25C3:R25C4" as the reference argument would enter the array in the same cells in the worksheet named SALES.

Related Functions

FORMULA   Enters values into a cell or range or onto a chart

   Enters a formula in the specified range

FORMULA.CONVERT

Changes the style and type of references in a formula between A1 and R1C1 and between relative and absolute. Use FORMULA.CONVERT to convert references of one style or type to another style or type.

Syntax

FORMULA.CONVERT(formula_text, from_a1, to_a1, to_ref_type, rel_to_ref)

Formula_text    is the formula, given as text, containing the references you want to change. Formula_text must be a valid formula, and an equal sign must be included.

From_a1    is a logical value specifying whether the references in formula_text are in A1 or R1C1 style. If from_a1 is TRUE, references are in A1 style; if FALSE, references are in R1C1 style.

To_a1    is a logical value specifying the form for the references FORMULA.CONVERT returns. If to_a1 is TRUE, references are returned in A1 style; if FALSE, references are returned in R1C1 style. If to_a1 is omitted, the reference style is not changed.

To_ref_type    is a number from 1 to 4 specifying the reference type of the returned formula. If to_ref_type is omitted, the reference type is not changed.

To_ref_type

 

Reference type returned

1         Absolute

2         Absolute row, relative column

3         Relative row, absolute column

4         Relative

Rel_to_ref    is an absolute reference that specifies what cell the relative references are or should be relative to.

Examples

Use FORMULA.CONVERT to convert relative references entered by the user in an INPUT function or custom dialog box into absolute references. The following macro formula converts the given formula to an absolute, R1C1-style reference:

FORMULA.CONVERT("=A1:A10", TRUE, FALSE, 1) equals "=R1C1:R10C1"

The following macro formula converts the references in the given formula to relative, A1-style references:

FORMULA.CONVERT("=SUM(R10C2:R15C2)", FALSE, TRUE, 4) equals "=SUM(B10:B15)"

Tip   To put the converted formula into a cell or range of cells, use the FORMULA.CONVERT function as the formula_text argument to the FORMULA function.

Related Functions

ABSREF   Returns the absolute reference of a range of cells to another range

FORMULA   Enters values into a cell or range or onto a chart

RELREF   Returns a relative reference

Enters a formula in the range specified or in the current selection. Equivalent to entering a formula in a range of cells while pressing CTRL+ENTER in Microsoft Excel for Windows or OPTION+ENTER in Microsoft Excel for the Macintosh.

Syntax

(formula_text, reference)

Formula_text    is the text with which you want to fill the range. For more information on formula_text, see FORMULA.

Reference    specifies where formula_text is entered. It can be a reference to a range in the active worksheet or an external reference to a named workbook. If omitted, formula_text is entered in the current selection.

Related Functions

DATA.SERIES   Fills a range of cells with a series of numbers or dates

FORMULA   Enters values into a cell or range or onto a chart

FORMULA.ARRAY   Enters an array

Equivalent to clicking the Find command on the Edit menu. Selects the next or previous cell containing the specified text and returns TRUE. If a matching cell is not found, returns FALSE and displays a message.

Syntax

(text, in_num, at_num, by_num, dir_num, match_case)

?(text, in_num, at_num, by_num, dir_num, match_case)

Text    is the text you want to find. Text corresponds to the Find What box in the Find dialog box.

In_num    is a number from 1 to 3 specifying where to search.

In_num

 

Searches

1        Formulas

2        Values

3        Notes

At_num    is the number 1 or 2 and specifies whether to find cells containing only text or also cells containing text within a longer string of characters.

At_num

 

Searches for text as

1        A whole string (the only value in the cell)

2        Either a whole string or part of a longer string

By_num    is the number 1 or 2 and specifies whether to search by rows or by columns.

By_num

 

Searches by

1        Rows

2        Columns

Dir_num    is the number 1 or 2 and specifies whether to search for the next or previous occurrence of text.

Dir_num

 

Searches for

1          or omitted The next occurrence of text

2          The previous occurrence of text

Match_case    is a logical value corresponding to the Match Case check box in the Find dialog box. If match_case is TRUE, Microsoft Excel matches characters exactly, including uppercase and lowercase; if FALSE or omitted, matching is not case-sensitive.

Remarks 

•    In Microsoft Excel for Windows, the dialog-box form of is equivalent to pressing SHIFT+F5.

•    If more than one cell is selected when you use , Microsoft Excel searches only that selection. 

,

Finds the next and previous cells on the worksheet, as specified in the Find dialog box, and returns TRUE. (To see the Find dialog box, click Find on the Edit menu.) If a matching cell is not found, the functions return FALSE. For more information see .

Syntax

( ) ( )

Related Functions

   Selects records in a database that match the specified criteria

   Finds text in a workbook

Equivalent to clicking the Go To command on the Edit menu or to pressing F5. Scrolls through the worksheet and selects a named area or reference. Use to select a range on any open workbook; use SELECT to select a range on the active workbook.

Syntax

(reference, corner)

?(reference, corner)

Reference    specifies where to scroll and what to select. 

•   Reference should be either an external reference to a workbook, an R1C1-style reference in the form of text (see the second example following), or a name.

•   If the Go To command has already been carried out, reference is optional. If reference is omitted, it is assumed to be the reference of the cells you selected before the previous Go To command or macro function was carried out. This feature distinguishes from SELECT. 

Corner    is a logical value that specifies whether to scroll through the window so that the upper-left cell in reference is in the upper-left corner of the active window. If corner is TRUE, Microsoft Excel places reference in the upper-left corner of the window; if FALSE or omitted, Microsoft Excel scrolls through normally.

Tip   Microsoft Excel keeps a list of the cells you've selected with previous functions or Go To commands. When you use with GET.WORKSPACE(41), which returns a horizontal array of previous Go To selections, you can backtrack through multiple previous selections. See the last example below.

Remarks 

•   If you are recording a macro when you click the Go To command, the reference you enter in the Reference box of the Go To dialog box is recorded as text in the R1C1 reference style.

•   If you are recording a macro when you double-click a cell that has precedents on another worksheet, Microsoft Excel records a function. Examples

Each of the following macro formulas goes to cell A1 on the active worksheet:

(!$A$1)

("R1C1")

Each of the following macro formulas goes to the cells named Sales on the active worksheet and scrolls through the worksheet so that the upper-left corner of Sales is in the upper-left corner of the window:

(!Sales, TRUE)

("Sales", TRUE)

The following macro formula goes to the cells that were selected by the third most recent function or Go To command:

(INDEX(GET.WORKSPACE(41), 1, 3))

Related Functions

GOTO   Directs macro execution to another cell

HSCROLL   Horizontally scrolls through a sheet by percentage or by column or row number

SELECT   Selects a cell, worksheet object, or chart item

VSCROLL   Vertically scrolls through a sheet by percentage or by column or row number

FORMULA.REPLACE

Equivalent to clicking the Replace command on the Edit menu. Finds and replaces characters in cells on your worksheet.

Syntax

FORMULA.REPLACE(find_text, replace_text, look_at, look_by, active_cell, match_case)

FORMULA.REPLACE?(find_text, replace_text, look_at, look_by, active_cell, match_case)

Find_text    is the text you want to find. You can use the wildcard characters, question mark (?) and asterisk (*), in find_text. A question mark matches any single character; an asterisk matches any sequence of characters. If you want to find an actual question mark or asterisk, type a tilde (~) before the character.

Replace_text    is the text you want to replace find_text with.

Look_at    is a number specifying whether you want find_text to match the entire contents of a cell or any string of matching characters.

Look_at

 

Looks for find_text

1          or omitted As the entire contents of a cell

2          As part of the contents of a cell

Look_by    is a number specifying whether to search horizontally (through rows) or vertically (through columns).

Look_by

 

Looks for find_text

1          or omitted By rows

2          By columns

Active_cell    is a logical value specifying the cells in which find_text is to be replaced. 

•   If active_cell is TRUE, find_text is replaced in the active cell only.

•   If active_cell is FALSE, find_text is replaced in the entire selection, or, if the selection is a single cell, in the entire sheet. 

Match_case    is a logical value corresponding to the Match Case check box in the Replace dialog box. If match_case is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If match_case is omitted, the status of the check box is unchanged.

Remarks 

•   In FORMULA.REPLACE?, the dialog-box form of the function, omitted arguments are assumed to be the same arguments used in the previous replace operation. If there was no previous replace operation, omitted text arguments are assumed to be "" (empty text).

•   The result of FORMULA.REPLACE must be a valid cell entry. For example, you cannot replace "=" with "= =" at the beginning of a formula.

•   If more than a single cell is selected before you use FORMULA.REPLACE, only the selected cells are searched. 

Related Function

   Finds text in a workbook

FOURIER

Performs a Fourier transform.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

FOURIER(inprng, outrng, inverse, labels)

FOURIER?(inprng, outrng, inverse, labels)

Inprng    is the input range. The number of cells in the input range must be equal to a power of two (2, 4, 8, 16, ).

Outrng    is the first cell in the output range or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Inverse    is a logical value. If TRUE, an inverse Fourier transform is performed. If FALSE or omitted, a forward Fourier transform is performed.

Labels    is a logical value. 

•   If labels is TRUE, then the first row or column of inprng contains labels.

•   If labels is FALSE or omitted, all cells in inprng are considered data. Microsoft Excel generates appropriate data labels for the output table. 

Related Function

SAMPLE   Samples data

FPOS

Sets the position of a file. The position of a file is where a character is read from or written to by an FREAD, FREADLN, FWRITE, or FWRITELN function. Use FPOS when you want to write characters to or read characters from specific locations. For example, to append text to the end of a file, you must set the position to the end of the file; otherwise, you might accidentally overwrite existing characters in the file.

Syntax

FPOS(file_num, position_num)

File_num    is the unique ID number of the file for which you want to set the position. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FPOS returns the #VALUE! error value.

Position_num    is the location in the file that a character will be read from or written to. 

•   The first position in a file is 1, the location of the first byte.

•   The last position in the file is the same as the value returned by FSIZE. For example, the last position in a file with 280 bytes is 280.

•   If position_num is omitted, FPOS returns the current position of the file—that is, the number corresponding to where the next character will be read from or written to. 

Whenever you read a character from or write a character to a file, the file's position is automatically incremented.

Examples

The following statement starts a loop that executes until the position in the open file identified as FileNumber reaches the end of the file:

=WHILE(FPOS(FileNumber)<=FSIZE(FileNumber))

Related Functions

FCLOSE   Closes a text file

FOPEN   Opens a file with the type of permission specified

FREAD   Reads characters from a text file

FREADLN   Reads a line from a text file

FWRITE   Writes characters to a text file

FWRITELN   Writes a line to a text file

FREAD

Reads characters from a file, starting at the current position in the file. (For more information about a file's position, see FPOS.) If FREAD is successful, it returns the text to the cell containing FREAD and set's the file's position to the start of the following line. If the end of the file is reached or if FREAD can't read the file, it returns the #N/A error value. Use FREAD instead of FREADLN when you need to read a specific number of characters from a text file.

Syntax

FREAD(file_num, num_chars)

File_num    is the unique ID number of the file you want to read data from. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FREAD returns the #VALUE! error value.

Num_chars    specifies how many bytes to read from the file. FREAD can read up to 255 bytes at a time.

Example

The following function reads the next 200 bytes from the open file identified as FileNumber:

FREAD(FileNumber, 200)

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FREADLN   Reads a line from a text file

FWRITE   Writes characters to a text file

FREADLN

Reads characters from a file, starting at the current position in the file and continuing to the end of the line, placing the characters in the cell containing FREADLN. (For more information about a file's position, see FPOS.) If FREADLN is successful, it returns the text it read, up to but not including the carriage-return and linefeed characters at the end of the line (in Microsoft Excel for Windows) or the carriage-return character at the end of the line (in Microsoft Excel for the Macintosh). If the current file position is the end of the file or if FREADLN can't read the file, it returns the #N/A error value.

Syntax

FREADLN(file_num)

File_num    is the unique ID number of the file you want to read data from. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FREADLN returns the #VALUE! error value.

Example

The following function reads the next line from the open file identified as FileNumber:

FREADLN(FileNumber)

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FREAD   Reads characters from a text file

FWRITE   Writes characters to a text file

FWRITELN   Writes a line to a text file

FREEZE.PANES

Equivalent to clicking the Freeze Panes or Unfreeze Panes command on the Window menu. Splits the active window into panes, creates frozen panes, or freezes or unfreezes existing panes. Use FREEZE.PANES to keep row or column titles on the screen while scrolling to other parts of the sheet.

Syntax

FREEZE.PANES(logical, col_split, row_split)

Logical    is a logical value specifying which command FREEZE.PANES is equivalent to. 

•   If logical is TRUE, the function is equivalent to the Freeze Panes command. It freezes panes if they exist, or creates them, splits them at the specified position,

and freezes them if they do not exist. If the panes are already frozen, FREEZE.PANES takes no action.

•   If logical is FALSE, the function is equivalent to the Unfreeze Panes command. If no panes exist, FREEZE.PANES takes no action.

•   If logical is omitted, FREEZE.PANES creates and then freezes panes if no panes exist, freezes existing panes if they're not currently frozen, or unfreezes existing panes if they're currently frozen. 

Col_split    specifies where to split the window vertically and is measured in columns from the left of the window.

Row_split    specifies where to split the window horizontally and is measured in rows from the top of the window.

Col_split and row_split are ignored unless logical is TRUE and split panes do not exist.

Remarks

To create panes without freezing or unfreezing them, use the SPLIT function. You can freeze the panes later using the FREEZE.PANES function.

Related Functions

ACTIVATE   Switches to a window

SPLIT   Splits a window

FSIZE

Returns the number of bytes in a file. Use FSIZE to determine the size of the file, which is the same as the position of the last byte in the file.

Syntax

FSIZE(file_num)

File_num    is the unique ID number of the file whose size you want to know. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FSIZE returns the #VALUE! error value.

Example

The following function returns the size in bytes of the open file identified as FileNumber:

FSIZE(FileNumber)

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FTESTV

Performs a two-sample F-test.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

FTESTV(inprng1, inprng2, outrng, labels)

FTESTV?(inprng1, inprng2. outrng, labels) Inprng1    is the input range for the first data set.

Inprng2    is the input range for the second data set.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Labels    is a logical value. 

•   If labels is TRUE, then the first row or column of inprng1 and inprng2 contain labels.

•   If labels is FALSE or omitted, all cells in inprng1 and inprng2 are considered data. Microsoft Excel generates appropriate data labels for the output table.

FULL

Equivalent to pressing CTRL+F10 (full size) and CTRL+F5 (previous size) or double-clicking the title bar in Microsoft Excel for Windows version 3.0 or earlier. Equivalent to double-clicking the title bar or clicking the zoom box in Microsoft Excel for the Macintosh version 3.0 or earlier. This function is included only for macro compatibility. To perform the equivalent of a FULL(TRUE) function in Microsoft Excel version 4.0 or later, use the WINDOW.MAXIMIZE function. To perform the equivalent of a FULL(FALSE) function in Microsoft Excel version 4.0 or later, use the WINDOW.RESTORE function.

Syntax

FULL(logical)

FULL.SCREEN

Equivalent to clicking the Full Screen command on the View menu.

Syntax

FULL.SCREEN(logical)

Logical    switches to full screen if TRUE or omitted; exits full screen mode if FALSE.

FUNCTION.WIZARD

Displays the Paste Function dialog box, which you can use to enter functions into cells.

Syntax

FUNCTION.WIZARD?( )

Remarks

If you know the function or formula that you want to insert into a cell, use the FORMULA function.

Related Function

FORMULA   Enters values into a cell or range or onto a chart

FWRITE

Writes text to a file, starting at the current position in that file. (For more information about a file's position, see FPOS.) If FWRITE can't write to the file, it returns the #N/A error value.

Syntax

FWRITE(file_num, text)

File_num    is the unique ID number of the file you want to write data to. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FWRITE returns the #VALUE! error value.

Text    is the text you want to write to the file.

Example

The following function writes the current month to the open file identified as FileNumber:

FWRITE(FileNumber, TEXT(MONTH(NOW()),"mmmm"))

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FREAD   Reads characters from a text file

FWRITELN   Writes a line to a text file

FWRITELN

Writes text, followed by a carriage return and linefeed, to a file, starting at the current position in that file. (For more information about a file's position, see FPOS.) If FWRITELN can't write to the file, it returns the #N/A error value. Use FWRITELN instead of FWRITE when you want to append a carriage return and linefeed to each group of characters that you write to a text file.

Syntax

FWRITELN(file_num, text)

File_num    is the unique ID number of the file you want to write data to. File_num is returned by a previously executed FOPEN function. If file_num is not valid, FWRITELN returns the #VALUE! error value.

Text    is the text you want to write to the file.

Remarks

In Microsoft Excel for Windows, FWRITELN writes text followed by a carriage return and a line feed. In Microsoft Excel for the Macintosh, FWRITELN writes text followed by a carriage return only.

Example

The following function writes the current month to the open file identified as FileNumber and starts a new line in the file:

FWRITELN(FileNumber, TEXT(MONTH(NOW()),"mmmm"))

Related Functions

FOPEN   Opens a file with the type of permission specified

FPOS   Sets the position in a text file

FREAD   Reads characters from a text file

FWRITE   Writes characters to a text file

Changes the format of the active chart to a 3-D area chart.

Syntax

(type_num)

?(type_num)

Type_num    is the number of the 3-D Area format that you want to apply to the chart.

Changes the active chart to a 3-D bar chart.

Syntax

(type_num)

?(type_num)

Type_num    is the number of the 3-D Bar format that you want to apply to the chart.

GALLERY.3D.COLUMN

Changes the format of the active chart to a 3-D column chart.

Syntax

GALLERY.3D.COLUMN(type_num)

GALLERY.3D.COLUMN?(type_num)

Type_num    is the number of the 3-D Column format that you want to apply to the chart.

Changes the format of the active chart to a 3-D line chart.

Syntax

(type_num)

?(type_num)

Type_num    is the number of the 3-D Line format that you want to apply to the chart.

Changes the format of the active chart to a 3-D pie chart.

Syntax

(type_num)

?(type_num)

Type_num    is the number of the 3-D Pie format that you want to apply to the chart.

GALLERY.3D.SURFACE

Changes the active chart to a 3-D surface chart.

Syntax

GALLERY.3D.SURFACE(type_num)

GALLERY.3D.SURFACE?(type_num)

Type_num    is the number of the 3-D Surface format that you want to apply to the chart.

Changes the format of the active chart to an area chart.

Syntax

(type_num, delete_overlay)

?(type_num, delete_overlay)

Type_num    is the number of a format in the AutoFormat dialog box when a chart is active dialog box that you want to apply to the area chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

Changes the format of the active chart to a bar chart.

Syntax

(type_num, delete_overlay)

?(type_num, delete_overlay)

Type_num    is the number of the format that you want to apply to the bar chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

GALLERY.COLUMN

Changes the format of the active chart to a column chart.

Syntax

GALLERY.COLUMN(type_num, delete_overlay)

GALLERY.COLUMN?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the column chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

GALLERY.CUSTOM

Changes the format of the active chart to the custom format.

Syntax

GALLERY.CUSTOM(name_text)

Name_text    is the name of the custom template you want to apply.

Related Functions

ADD.CHART.AUTOFORMAT   Formats a chart using a custom gallery

DELETE.CHART.AUTOFORMAT   Deletes a custom gallery

GALLERY.DOUGHNUT

Changes the format of the active chart to a doughnut chart.

GALLERY.DOUGHNUT(type_num, delete_overlay)

GALLERY.DOUGHNUT?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the doughnut chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

Changes the format of the active chart to a line chart.

Syntax

(type_num, delete_overlay)

?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the line chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

Changes the format of the active chart to a pie chart.

Syntax

(type_num, delete_overlay)

?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the pie chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

GALLERY.RADAR

Changes the format of the active chart to a radar chart.

Syntax

GALLERY.RADAR(type_num, delete_overlay)

GALLERY.RADAR?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the radar chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

GALLERY.SCATTER

Changes the format of the active chart to an xy (scatter) chart.

Syntax

GALLERY.SCATTER(type_num, delete_overlay)

GALLERY.SCATTER?(type_num, delete_overlay)

Type_num    is the number of the format you want to apply to the xy (scatter) chart.

Delete_overlay    is a logical value specifying whether to delete an overlay chart. 

•   If delete_overlay is TRUE, Microsoft Excel deletes all overlays, if present, and applies the new format to the main chart.

•   If delete_overlay is FALSE or omitted, Microsoft Excel applies the new format to either the main chart or the overlay, depending on the location of the selected series. 

Returns the number of the active menu bar. There are two syntax forms of . Use syntax 1 to return information that you can use with other functions that manipulate menu bars. Use syntax 2 to return information that you can use with functions that add, delete, or alter menu commands.

Syntax 1   Returns the number of the active menu bar

Syntax 2   Returns the name or position number of a specified command on a menu or of a specified menu on a menu bar

SYNTAX 1

Returns the number of the active menu bar. There are two syntax forms of . Use syntax 1 to return information that you can use with other functions that manipulate menu bars. For a list of the ID numbers for Microsoft Excel's built-in menu bars, see ADD.COMMAND. Syntax

( )

Example

The following macro formula assigns the name OldBar to the number of the active menu bar. This is useful if you will need to restore the current menu bar after displaying another custom menu bar.

("OldBar", ())

Related Functions

   Adds a menu bar

   Displays a menu bar

Syntax 2   Returns the name or position number of a specified command on a menu or of a specified menu on a menu bar

SYNTAX 2

Returns the name or position number of a specified command on a menu or of a specified menu on a menu bar. There are two syntax forms of . Use syntax 2 to return information that you can use with functions that add, delete, or alter menu commands.

Syntax

(bar_num, menu, command, subcommand)

Bar_num    is the number of a menu bar containing the menu or command about which you want information. Bar_num can be the number of a built-in menu bar or the number returned by a previously run function. For a list of the ID numbers for Microsoft Excel's built-in menu bars, see ADD.COMMAND.

Menu    is the menu on which the command resides or the menu whose name or position you want. Menu can be the name of the menu as text or the number of the menu. Menus are numbered starting with 1 from the left of the menu bar.

Command    is the command or submenu whose name or number you want returned. Command can be the name of the command from the menu as text, in which case the number is returned, or the number of the command from the menu, in which case the name is returned. Commands are numbered starting with 1 from the top of the menu. If command is 0, the name or position number of the menu is returned. If an ellipsis ( ) follows a command name, such as the Open command on the File menu, then you must include the ellipsis when referring to that command. See the following examples.

Subcommand    returns the name (if number is used for subcommand) or position (if name is used for subcommand) of a command on a submenu. If the command argument refers to an empty submenu, or is a command instead of a submenu, then using subcommand returns #N/A.

Remarks 

•    If an ampersand is used to indicate the access key in the name of a custom command, the ampersand is included in the name returned by . All built-in commands have an ampersand before the letter used as the access key.

•    If the command name or position specified does not exist, returns the #N/A error value. 

Examples

In the default worksheet and macro sheet menu bar:

(10, "File", "Print ") equals 14

(10, "File", 14) equals "&Print ^tCTRL+P" (where ^t is a tab character)

(10, 1, "Open") equals #N/A

(10, 1, "Open ") equals 2

Related Functions

ADD.COMMAND   Adds a command to a menu

DELETE.COMMAND   Deletes a command from a menu

GET.TOOLBAR   Retrieves information about a toolbar

RENAME.COMMAND   Changes the name of a command or menu

GETBAR Syntax 1   Returns the number of the active menu bar

Returns information about the formatting, location, or contents of a cell. Use in a macro whose behavior is determined by the status of a particular cell.

Syntax

(type_num, reference)

Type_num    is a number that specifies what type of cell information you want. The following list shows the possible values of type_num and the corresponding results.

Type_num

 

Returns

1                  Absolute reference of the upper-left cell in reference, as text

in the current workspace reference style.

2                  Row number of the top cell in reference.

3                  Column number of the leftmost cell in reference.

4                  Same as TYPE(reference).

5                  Contents of reference.

6                  Formula in reference, as text, in either A1 or R1C1 style

depending on the workspace setting.

7                  Number format of the cell, as text (for example, "m/d/yy" or

"General").

8                  Number indicating the cell's horizontal alignment: 

1  = General

2  = Left

3  = Center

4  = Right

5  = Fill

6  = Justify

7  = Center across cells

9                  Number indicating the left-border style assigned to the cell: 

0  = No border

1  = Thin line

2  = Medium line

3  = Dashed line

4  = Dotted line

5  = Thick line

6  = Double line

7  = Hairline

10                  Number indicating the right-border style assigned to the cell.

See type_num 9 for descriptions of the numbers returned.

11                  Number indicating the top-border style assigned to the cell.

See type_num 9 for descriptions of the numbers returned.

12                  Number indicating the bottom-border style assigned to the

cell. See type_num 9 for descriptions of the numbers returned.

13                  Number from 0 to 18, indicating the pattern of the selected

cell as displayed in the Patterns tab of the Format Cells dialog box, which appears when you click the Cells command on the Format menu. If no pattern is selected, returns 0.

14                  If the cell is locked, returns TRUE; otherwise, returns FALSE.

15                  If the cell's formula is hidden, returns TRUE; otherwise,

returns FALSE.

16                  A two-item horizontal array containing the width of the active

cell and a logical value indicating whether the cell's width is set to change as the standard width changes (TRUE) or is a custom width (FALSE).

17                  Row height of cell, in points.

18                  Name of font, as text.

19                  Size of font, in points.

20                  If all the characters in the cell, or only the first character, are bold, returns TRUE; otherwise, returns FALSE.

21                  If all the characters in the cell, or only the first character, are

italic, returns TRUE; otherwise, returns FALSE.

22                  If all the characters in the cell, or only the first character, are underlined, returns TRUE; otherwise, returns FALSE.

23                  If all the characters in the cell, or only the first character, are struck through, returns TRUE; otherwise, returns FALSE.

24                  Font color of the first character in the cell, as a number in

the range 1 to 56. If font color is automatic, returns 0.

25                  If all the characters in the cell, or only the first character, are outlined, returns TRUE; otherwise, returns FALSE. Outline font format is not supported by Microsoft Excel for Windows.

26                  If all the characters in the cell, or only the first character, are shadowed, returns TRUE; otherwise, returns FALSE. Shadow font format is not supported by Microsoft Excel for Windows.

27                  Number indicating whether a manual page break occurs at

the cell: 

0  = No break

1  = Row

2  = Column

3  = Both row and column

28                  Row level (outline)

29                  Column level (outline).

30                  If the row containing the active cell is a summary row,

returns TRUE; otherwise, returns FALSE.

31                  If the column containing the active cell is a summary column,

returns TRUE; otherwise, returns FALSE.

32                  Name of the workbook and sheet containing the cell If the

window contains only a single sheet that has the same name as the workbook without its extension, returns only the name of the book, in the form . Otherwise, returns the name of the sheet in the form "[Book1]Sheet1".

33                  If the cell is formatted to wrap, returns TRUE; otherwise,

returns FALSE.

34                  Left-border color as a number in the range 1 to 56. If color is

automatic, returns 0.

35                  Right-border color as a number in the range 1 to 56. If color

is automatic, returns 0.

36                  Top-border color as a number in the range 1 to 56. If color is

automatic, returns 0.

37                  Bottom-border color as a number in the range 1 to 56. If

color is automatic, returns 0.

38                  Shade foreground color as a number in the range 1 to 56. If

color is automatic, returns 0.

39                  Shade background color as a number in the range 1 to 56. If

color is automatic, returns 0.

40                  Style of the cell, as text.

41                  Returns the formula in the active cell without translating it

(useful for international macro sheets).

42                  The horizontal distance, measured in points, from the left

edge of the active window to the left edge of the cell. May be a negative number if the window is scrolled beyond the cell.

43                  The vertical distance, measured in points, from the top edge

of the active window to the top edge of the cell. May be a negative number if the window is scrolled beyond the cell.

44                  The horizontal distance, measured in points, from the left

edge of the active window to the right edge of the cell. May be a negative number if the window is scrolled beyond the cell.

45                  The vertical distance, measured in points, from the top edge

of the active window to the bottom edge of the cell. May be a negative number if the window is scrolled beyond the cell.

46                  If the cell contains a text note, returns TRUE; otherwise,

returns FALSE.

47                  If the cell contains a sound note, returns TRUE; otherwise,

returns FALSE.

48                  If the cells contains a formula, returns TRUE; if a constant,

returns FALSE.

49                  If the cell is part of an array, returns TRUE; otherwise,

returns FALSE.

50                  Number indicating the cell's vertical alignment: 

1  = Top

2  = Center

3  = Bottom

4  = Justified

51                  Number indicating the cell's vertical orientation: 

0  = Horizontal

1  = Vertical

2  = Upward

3  = Downward

52                  The cell prefix (or text alignment) character, or empty text

("") if the cell does not contain one.

53                  Contents of the cell as it is currently displayed, as text,

including any additional numbers or symbols resulting from the cell's formatting.

54                  Returns the name of the PivotTable report containing the

active cell.

55                  Returns the position of a cell within the PivotTable report. 

0  = Row header

1  = Column header

2  = Page header

3  = Data header

4  = Row item

5  = Column item

6  = Page item

7  = Data item

8  = Table body

56                  Returns the name of the field containing the active cell

reference if inside a PivotTable report.

57                  Returns TRUE if all the characters in the cell, or only the first

character, are formatted with a superscript font; otherwise, returns FALSE.

58                  Returns the font style as text of all the characters in the cell,

or only the first character as displayed in the Font tab of the Format Cells dialog box: for example, "Bold Italic".

7                                          Returns the number for the underline style: 

1  = None

2  = Single

3  = Double

4  = Single accounting

5  = Double accounting

60                  Returns TRUE if all the characters in the cell, or only the first

character, are formatted with a subscript font; otherwise, it returns FALSE.

61                  Returns the name of the PivotTable item for the active cell,

as text.

62                  Returns the name of the workbook and the current sheet in

the form "[Book1]Sheet1".

63                  Returns the fill (background) color of the cell.

64                  Returns the pattern (foreground) color of the cell.

65                  Returns TRUE if the Add Indent alignment option is on (Far

East versions of Microsoft Excel only); otherwise, it returns FALSE.

66                  Returns the book name of the workbook containing the cell in the form .

Reference    is a cell or a range of cells from which you want information. 

•   If reference is a range of cells, the cell in the upper-left corner of the first range in reference is used.

•   If reference is omitted, the active cell is assumed. 

Tip   Use (17) to determine the height of a cell and (44) - (42) to determine the width.

Examples

The following macro formula returns TRUE if cell B4 on sheet Sheet1 is bold:

(20, Sheet1!$B$4)

You can use the information returned by to initiate an action. The following macro formula runs a custom function named BoldCell if the formula returns FALSE:

IF((20, Sheet1!$B$4), , BoldCell())

Related Functions

ABSREF   Returns the absolute reference of a range of cells to another range

   Returns the reference of the active cell

GET.FORMULA   Returns the contents of a cell

   Returns the definition of a name

   Returns characters from a note

RELREF   Returns a relative reference

Returns the vertical or horizontal position of a point on a chart item. Use these position numbers with and to change the position and size of chart items. Position is measured in points; a point is 1/72nd of an inch.

Syntax

(x_y_index, point_index, item_text)

X_y_index    is a number specifying which of the coordinates you want returned.

X_y_index

 

Coordinate returned

1        Horizontal coordinate

2        Vertical coordinate

Point_index    is a number specifying the point on the chart item. These indexes are described below. If point_index is omitted, it is assumed to be 1. 

•   If the specified item is a point, point_index must be 1.

•   If the specified item is any line other than a data line, use the following values for point_index.

Point_index

 

Chart item position

1         Lower or left

2         Upper or right

?      If the selected item is a legend, plot area, chart area, or an area in an area chart, use the following values for point_index.

Point_index

 

Chart item position

1         Upper left

2         Upper middle

3         Upper right

4         Right middle

5         Lower right

6         Lower middle

7         Lower left

8         Left middle

?      If the selected item is an arrow in Microsoft Excel 4.0, use the following values for point_index. In Microsoft Excel version 5.0 or later, arrows are named lines, and the arrowhead position returned is equivalent to the end of a line where the arrowhead begins.

Point_index

 

Chart item position

1         Arrow shaft

2         Arrowhead

                     ?       If the selected item is a pie slice, use the following values for point_index.

Point_index

 

Chart item position

1         Outermost counterclockwise point

2         Outer center point

3         Outermost clockwise point

4         Midpoint of the most clockwise radius

5         Center point

6         Midpoint of the most counterclockwise radius

Item_text    is a selection code that specifies which item of a chart to select. See the chart form of SELECT for the item_text codes to use for each item of a chart. 

•   If item_text is omitted, it is assumed to be the currently selected item.

•   If item_text is omitted and no item is selected, returns the #VALUE! error value. 

Remarks

If the specified item does not exist, or if a chart is not active when the function is carried out, the #VALUE! error value is returned.

Examples

The following macro formulas return the horizontal and vertical locations, respectively, of the top of the main-chart value axis:

(1, 2, "Axis 1")

(2, 2, "Axis 1")

You could then use to move a floating text item to the position returned by these two formulas.

Related Functions

GET.DOCUMENT   Returns information about a workbook

GET.FORMULA   Returns the contents of a cell

Returns the name, as text, that is defined for a particular area, value, or formula in a workbook. Use to get the name corresponding to a definition. To get the definition of a name, use .

Syntax

(def_text, document_text, type_num)

Def_text    can be anything you can define a name to refer to, including a reference, a value, an object, or a formula. 

•   References must be given in R1C1 style, such as "R3C5".

•   If def_text is a value or formula, it is not necessary to include the equal sign that is displayed in the Refers To box in the Define Name dialog box, which appears when you choose the Name command from the Define submenu on the Insert Menu.

•   If there is more than one name for def_text, returns the first name. If no name matches def_text, returns the #NAME? error value.

Document_text    specifies the sheet or macro sheet that def_text is on. If document_text is omitted, it is assumed to be the active macro sheet.

Type_num    is a number from 1 to 3 specifying which types of names are returned.

Type_num

 

Returns

1          or omitted Normal names only

2          Hidden names only

3          All names

Examples

If the specified range in Sheet4 is named Sales, the following macro formula returns "Sales":

("R2C2:R9C6", "Sheet4")

If the value 100 in Sheet4 is defined as Constant, the following macro formula returns "Constant":

("100", "Sheet4")

If the specified formula in Sheet4 is named SumTotal, the following macro formula returns "SumTotal":

("SUM(R1C1:R10C1)", "Sheet4")

If 3 is defined as the hidden name Counter on the active macro sheet, the following macro formula returns "Counter":

("3", , 2)

Related Functions

   Returns information about the specified cell

   Returns the definition of a name

   Returns characters from a note

NAMES   Returns the names defined on a workbook

GET.DOCUMENT

Returns information about a sheet in a workbook.

Syntax

GET.DOCUMENT(type_num, name_text)

Type_num    is a number that specifies what type of information you want. The following lists show the possible values of type_num and the corresponding results.

Type_num

 

Returns

1                     Returns the name of the workbook and worksheet as

text. If there is only one sheet in the workbook and the sheet name is the same as the workbook name less any extension, returns the name of the book. The book name does not include the drive, directory or folder, or window number. Otherwise, returns the book and sheet name in the form "[]Sheet1". It is usually best to use GET.DOCUMENT(76) and GET.DOCUMENT(88) to return the name of the active worksheet and the active workbook.

2                     Path of the directory or folder containing name_text, as

text. If the workbook name_text hasn't been saved yet, returns the #N/A error value.

3                     Number indicating the type of sheet. If name_text is a

sheet, then the return value is one of the following numbers. If name_text is a book, then the return value is always 5. If name_text is omitted, then the sheet type is returned. If the book has one sheet that is named the same as the book, then the sheet type is returned. 

1  = Worksheet

2  = Chart

3  = Macro sheet

4  = Info window if active

5  = Reserved

6  = Module

7  = Dialog

4                     If changes have been made to the sheet since it was last

saved, returns TRUE; otherwise, returns FALSE.

5                     If the sheet is read-only, returns TRUE; otherwise,

returns FALSE.

6                     If the sheet is password protected, returns TRUE;

otherwise, returns FALSE.

7                     If cells in a sheet, the contents of a sheet, or the series in

a chart are protected, returns TRUE; otherwise, returns FALSE.

8                     If the workbook windows are protected, returns TRUE;

otherwise, returns FALSE.

The next four values of type_num apply only to charts.

Type_num

 

Returns

9                     Number indicating the type of the main chart: 

1  = Area

2  = Bar

3  = Column

4  = Line

5  = Pie

6  = XY (scatter)

7  = 3-D area

8  = 3-D column

9  = 3-D line

10  = 3-D pie

11  = Radar

12  = 3-D bar

13  = 3-D surface

14  = Doughnut

10                     Number indicating the type of the overlay chart. Same as

1, 2, 3, 4, 5, 6, 11, and 14 for main chart above. If there is no overlay chart, returns the #N/A error value.

11                     Number of series in the main chart.

12                     Number of series in the overlay chart.

The next values of type_num apply to worksheets and macro sheets and to charts when appropriate.

Type_num

 

Returns

9                     Number of the first used row. If the sheet is empty,

returns 0.

10                  Number of the last used row. If the sheet is empty,

returns 0.

11                  Number of the first used column. If the sheet is empty,

returns 0.

12                  Number of the last used column. If the sheet is empty,

returns 0.

13                  Number of windows.

14                  Number indicating calculation mode: 

1  = Automatic

2  = Automatic except tables

3  = Manual

15                  If the Iteration check box is selected in the Calculation tab

of the Options dialog box, returns TRUE; otherwise, returns FALSE.

16                  Maximum number of iterations.

17                  Maximum change between iterations.

18                  If the Update Remote References check box is selected in

the Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

19                  If the Precision As Displayed check box is selected in the

Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

20                  If the 1904 Date System check box is selected in the

Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

Type_num values of 21 through 29 correspond to the four default fonts in previous versions of Microsoft Excel. These values are provided only for macro compatibility.

The next values of type_num apply to worksheets and macro sheets, and to charts if indicated.

Type_num

 

Returns

30                  Horizontal array of consolidation references for the current

sheet, in the form of text. If the list is empty, returns the #N/A error value.

31                  Number from 1 to 11, indicating the function used in the current consolidation. The function that corresponds to each number is listed under the CONSOLIDATE function. The default function is SUM.

32                  Three-item horizontal array indicating the status of the

check boxes in the Data Consolidate dialog box. An item is TRUE if the check box is selected or FALSE if the check box is cleared. The first item indicates the Top Row check box, the second the Left Column check box, and the third the Create Links To Source Data check box.

33                  If the Recalculate Before Save check box is selected in the

Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

34                  If the workbook is read-only recommended, returns TRUE;

otherwise, returns FALSE.

35                  If the workbook is write-reserved, returns TRUE;

otherwise, returns FALSE.

36                  If the workbook has a write-reservation password and it is

opened with read/write permission, returns the name of the user who originally saved the file with the writereservation password. If the file is opened as read-only, or if a password has not been added to the workbook, returns the name of the current user.

37                  Number corresponding to the file type of the workbook as

displayed in the Save As dialog box. See the function for a list of all the file types that Microsoft Excel recognizes.

38                  If the Summary Rows Below Detail check box is selected

in the Outline dialog box, returns TRUE; otherwise, returns FALSE.

39                  If the Summary Columns To Right Of Detail check box is

selected in the Outline dialog box, returns TRUE; otherwise, returns FALSE.

40                  If the Always Create Backup check box is selected in the

Save Options dialog box, returns TRUE; otherwise, returns FALSE.

41                  Number from 1 to 3 indicating whether objects are

displayed: 

1  = All objects are displayed

2  = Placeholders for pictures and charts

3  = All objects are hidden

42                  Horizontal array of all objects in the sheet. If there are no

objects, returns the #N/A error value.

43                  If the Save External Link Values check box is selected in

the Calculation tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

44                  If objects in a workbook are protected, returns TRUE;

otherwise, returns FALSE.

45                  A number from 0 to 3 indicating how windows are

synchronized:

0  = Not synchronized

1  = Synchronized horizontally

2  = Synchronized vertically

3  = Synchronized horizontally and vertically

46                  A seven-item horizontal array of print settings that can be

set by the LINE.PRINT macro function: 

Setup text

Left margin

Right margin

Top margin

Bottom margin

Page length

A logical value indicating whether output will be formatted

(TRUE) or unformatted (FALSE) when printed

47                  If the Transition Formula Evaluation check box is selected

in the Transition tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

48                  The standard column width setting.

The next values of type_num correspond to printing and page settings.

Type_num

 

Returns

49                  The starting page number, or the #N/A error value if none is specified or if "Auto" is entered in the First page Number text box on the Page tab of the Page Setup dialog box.

50                  The total number of pages that would be printed based on

current settings, excluding notes, or 1 if the document is a chart.

51                  The total number of pages that would be printed if you

print only notes, or the #N/A error value if the document is a chart.

52                  Four-item horizontal array indicating the margin settings

(left, right, top, bottom) in the currently specified units.

53                  A number indicating the orientation: 

1  = Portrait

2  = Landscape

54                  The header as a text string, including formatting codes.

55                  The footer as a text string, including formatting codes.

56                  Horizontal array of two logical values corresponding to

horizontal and vertical centering.

57                  If row or column headings are to be printed, returns

TRUE; otherwise, returns FALSE.

58                  If gridlines are to be printed, returns TRUE; otherwise,

returns FALSE.

59                  If the sheet is printed in black and white only, returns

TRUE; otherwise, returns FALSE.

60                  A number from 1 to 3 indicating how the chart will be

sized when it's printed: 

1  = Size on screen

2  = Scale to fit page

3  = Use full page

61                  A number indicating the pagination order: 

1  = Down, then over 2 = Over, then down

Returns the #N/A error value if the document is a chart.

62                  Percentage of reduction or enlargement, or 100% if none

is specified. Returns the #N/A error value if not supported by the current printer or if the document is a chart.

63                  A two-item horizontal array indicating the number of pages to which the printout should be scaled to fit, with the first item equal to the width (or #N/A if no width scaling is specified) and the second item equal to the height (or #N/A if no height scaling is specified). #N/A is also returned if the document is a chart.

64                  An array of row numbers corresponding to rows that are

immediately below a manual or automatic page break.

65                  An array of column numbers corresponding to columns

that are immediately to the right of a manual or automatic page break.

Note   GET.DOCUMENT(62) and GET.DOCUMENT(63) are mutually exclusive. If one returns a value, then the other returns the #N/A error value.

The next values of type_num correspond to various workbook settings.

Type_num

 

Returns

66                  In Microsoft Excel for Windows, if the Transition Formula

Entry check box is selected in the Transition tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

67                  Microsoft Excel version 5.0 or later always returns TRUE

here.

68                  Microsoft Excel version 5.0 or later always returns the

book name.

69                  Returns TRUE if Page Breaks is chosen in the View tab of

the Options dialog box; otherwise, returns FALSE.

70                  Returns the names of all PivotTable reports in the current

sheet as a horizontal array.

71                  Returns an horizontal array of all the styles in a workbook. 72 Returns an horizontal array of all chart types displayed on

the current sheet.

73                  Returns an array of the number of series in each chart of

the current sheet.

74                  Returns the object ID of the control that currently has the

focus on a running user-defined dialog (based on the dialog sheet).

75                  Returns the object ID of the object that is the current

default button on a running user-defined dialog (based on the dialog sheet).

76                  Returns the name of the active sheet or macro sheet in

the form [Book1]Sheet1.

77                  In Microsoft Excel for Windows, returns the paper size, as

integer: 

1  = Letter 8.5 x 11 in

2  = Letter Small 8.5 x 11 in

5 = Legal 8.5 x 14 in

9  = A4 210 x 297 mm

10  = A4 Small 210 x 297 mm

13 = B5 182 x 257 mm

18 = Note 8.5 x 11 in

78                  Returns the print resolution, as a horizontal array of two numbers.

79                  Returns TRUE if the Draft Quality check box has been

selected from the sheet tab in the Page Setup dialog box; otherwise, returns FALSE.

80                  Returns TRUE if the Comments checkbox has been

selected on the Sheet tab in the Page Setup dialog box; otherwise, returns FALSE.

81                  Returns the Print Area from the Sheet tab of the Page

Setup dialog box as a cell reference.

82                  Returns the Print Titles from the Sheet tab of the Page

Setup dialog box as an array of cell references.

83                  Returns TRUE if the worksheet is protected for scenarios;

otherwise, returns FALSE.

84                  Returns the value of the first circular reference on the

sheet, or #N/A if there are no circular references.

85                  Returns the advanced filter mode state of the sheet. This

is the mode without drop-down arrows on top. Returns TRUE if the list has been filtered by clicking Filter, then Advanced Filter on the Data menu. Otherwise, returns FALSE.

86                  Returns the automatic filter mode state of the sheet. This

is the mode with drop-down arrows on top. Returns TRUE if you have chosen Filter, then AutoFilter from the Data menu and the filter drop-down arrows are displayed. Otherwise, returns FALSE.

87                  Returns the position number of the sheet. The first sheet

is position 1. Hidden sheet are included in the count.

88                  Returns the name of the active workbook in the form

"Book1".

Name_text    is the name of an open workbook. If name_text is omitted, it is assumed to be the active workbook.

Examples

The following macro formula returns TRUE if the contents of the active workbook are protected:

GET.DOCUMENT(7)

In Microsoft Excel for Windows, the following macro formula returns the number of windows in :

GET.DOCUMENT(13, "")

In Microsoft Excel for the Macintosh, the following macro formula returns 3 if the overlay chart on SALES CHART is a column chart:

GET.DOCUMENT(10, "SALES CHART")

To find out if SHEET1 is password-protected and if its contents and windows are protected, enter the following formula in a three-cell horizontal array:

GET.DOCUMENT({6, 7, 8}, "SHEET1")

Related Functions

   Returns information about the specified cell

GET.WINDOW   Returns information about a window

GET.WORKSPACE   Returns information about the workspace

GET.FORMULA

Returns the contents of a cell as they would appear in the formula bar. The contents are given as text, for example, "=2*PI()/360". If the formula contains references, they are returned as R1C1-style references, such as "=RC[1]*(1+R1C1)". Use GET.FORMULA to get a formula from a cell in order to edit its arguments. Use (6) to get a formula in either A1 or R1C1 format, depending on the workspace setting.

Syntax

GET.FORMULA(reference)

Reference    is a cell or range of cells on a sheet or macro sheet. 

•   If a range of cells is selected, GET.FORMULA returns the contents of the upperleft cell in reference.

•   Reference can be an external reference.

•   Reference can be the object identifier of a picture created by the camera tool.

•   Reference can also be a reference to a chart series in the form "Sn" where n is the number of the series. When a chart series is specified, GET.FORMULA returns the series formula using R1C1-style references.

Tip   If you want to get the formula in the active cell, use the function as the reference argument.

Examples

If cell A3 on the active sheet contains the number 523, then:

GET.FORMULA(!$A$3) equals "523"

If cell C2 on the active sheet contains the formula =B2*(1+$A$1), then:

GET.FORMULA(!$C$2) equals "=RC[-1]*(1+R1C1)"

The following macro formula returns the contents of the active cell on the active sheet:

GET.FORMULA(())

Related Functions

   Returns information about the specified cell

Returns a name matching a definition    Returns the definition of a name

   Returns characters from a comment

Returns information about the specified link. Use to get information about the update settings of a link.

Syntax

(link_text, type_num, type_of_link, reference)

Link_text    is the path of the link as displayed in the Links dialog box, which appears when you choose the Links command from the Edit menu. The path to the file you wish to return DDE information on must be surrounded by single quotes.

Type_num    is a number that specifies what type of information about the currently selected link to return. Type_num 2 applies only to publishers and subscribers in Microsoft Excel for the Macintosh.

Type_num

 

Returns

1          If the link is set to automatic update, returns 1; otherwise 2.

2          Date of the latest edition as a serial number. Returns #N/A if link_text is not a publisher or a subscriber.

Type_of_link    is a number from 1 to 6 that specifies what type of link you want to get information about.

Type_of_link

 

Link document type

1           Not applicable

2           DDE link (Microsoft Windows)

3           Not applicable

4           Not applicable

5           Publisher (Macintosh)

6           Subscriber (Macintosh)

Reference    specifies the cell range in R1C1 format of the publisher or subscriber that you want information about. Reference is required if you have more than one publisher or subscriber of a single edition name on the active workbook. Use reference to specify the location of the subscriber you want to return information about. If the subscriber is a picture, or if the publisher is an embedded chart, reference is the number of the object as displayed in the Name box.

Remarks 

•    If Microsoft Excel cannot find link_text, or if type_of_link does not match the link specified by link_text, returns the #VALUE! error value.

•    If you have more than one subscriber to the edition link_text or if the same area is published more than once, you must specify reference.  

Example

In Microsoft Excel for Windows, the following macro formula returns information about a DDE link to a Microsoft Word for Windows document. The document is named .

("WinWord|'C:\WINWORD\'!DDE_LINK1", 1, 2)

In Microsoft Excel for the Macintosh, the following macro formula returns information about a link to a publisher defined in cells A1:C3 on a workbook named New Products.

("A1:C3 New Products Edition #1", 2, 5, "'New Products'!R1C1:R3C3")

Related Functions

CREATE.PUBLISHER   Creates a publisher from the selection

   Inserts contents of an edition into the active workbook

   Updates a link to another workbook

Returns the definition of a name as it appears in the Refers To box of the Define Name dialog box, which appears when you choose the Define command from the Name submenu on the Insert menu. If the definition contains references, they are given as R1C1-style references. Use to check the value defined by a name. To get the name corresponding to a definition, use .

Syntax

(name_text, info_type)

Name_text    can be a name defined on the macro sheet; an external reference to a name defined on the active workbook, for example, "!Sales"; or an external reference to a name defined on a particular open workbook, for example, "[Book1]SHEET1!Sales". Name_text can also be a hidden name.

Info_type     specifies the type of information to return about the name. If 1 or omitted, the definition is returned. If 2, returns TRUE if the name is defined for just the sheet, FALSE if the name is defined for the entire workbook.

Remarks

If the Contents check box has been selected in the Protect Sheet dialog box to protect the workbook containing the name, returns the #N/A error value. To see the Protect Sheet dialog box, choose the Protect Sheet command on the Protection submenu from the Tools menu.

Examples

If the name Sales on a macro sheet is defined as the number 523, then:

("Sales") equals "=523"

If the name Profit on the active sheet is defined as the formula =Sales-Costs, then:

("!Profit") equals "=Sales-Costs"

If the name Database on the active sheet is defined as the range A1:F500, then:

("!Database") equals "=R1C1:R500C6"

Related Functions

   Defines a name on the active or macro sheet

   Returns information about the specified cell

   Returns a name matching a definition

NAMES   Returns the names defined in a workbook

   Defines a name as a value

Returns characters from a comment.

Syntax

(cell_ref, start_char, num_chars)

Cell_ref    is the cell to which the note is attached. If cell_ref is omitted, the comment attached to the active cell is returned.

Start_char    is the number of the first character in the comment to return. If start_char is omitted, it is assumed to be 1, the first character in the comment.

Num_chars    is the number of characters to return. Num_chars must be less than or equal to 255. If num_chars is omitted, it is assumed to be the length of the comment attached to cell_ref.

Examples

The following macro formula returns the first 200 characters in the comment attached to cell A3 on the active sheet:

(!$A$3, 1, 200)

In Microsoft Excel for Windows, the following macro formula returns the 10th through the 39th characters of the comment attached to cell C2 on :

("[]Sheet1!R2C3", 10, 30)

In Microsoft Excel for the Macintosh, the following macro formula returns the 10th through the 39th characters of the comment attached to cell C2 on SALES:

("[SALES]Sheet1!R2C3", 10, 30)

Use with the NOTE function to move the contents of a comment to a cell or text box or to another comment attached to a cell:

NOTE((!$B$10),())

Related Functions

   Returns information about the specified cell

NOTE   Creates or changes a comment.

GET.OBJECT

Returns information about the specified object. Use GET.OBJECT to return information you can use in other macro formulas that manipulate objects.

Syntax

GET.OBJECT(type_num, object_id_text, start_num, count_num, item_index)

Type_num    is a number specifying the type of information you want returned about an object. GET.OBJECT returns the #VALUE! error value (and the macro is halted) if an object isn't specified or if more than one object is selected.

Type_num

 

Returns

2            If the object is locked, returns TRUE; otherwise FALSE.

3            Z-order position (layering) of the object; that is, the relative position of the overlapping objects, starting with 1 for the object that is most under the others.

4            Reference of the cell under the upper-left corner of the object as text in

R1C1 reference style; for a line or arc, returns the start point.

5            X offset from the upper-left corner of the cell under the upper-left corner of the object, measured in points.

6            Y offset from the upper-left corner of the cell under the upper-left corner of the object, measured in points.

7            Reference of the cell under the lower-right corner of the object as text in R1C1 reference style; for a line or arc, returns the end point.

8            X offset from the upper-left corner of the cell under the lower-right corner of the object, measured in points.

9            Y offset from the upper-left corner of the cell under the lower-right corner of the object, measured in points.

10            Name, including the filename, of the macro assigned to the object. If no macro is assigned, returns FALSE.

11            Number indicating how the object moves and sizes:

1  = Object moves and sizes with cells

2  = Object moves with cells

3  = Object is fixed

Values 12 to 21 for type_num apply only to text boxes and buttons. If another type of object is selected, GET.OBJECT returns the #VALUE! error value.

 

Type_num

 

Returns

12            Text starting at start_num for count_num characters.

13            Font name of all text starting at start_num for count_num characters. If the text contains more than one font name, returns the #N/A error value.

14            Font size of all text starting at start_num for count_num characters. If the text contains more than one font size, returns the #N/A error value.

15            If all text starting at start_num for count_num characters is bold, returns TRUE. If text contains only partial bold formatting, returns the #N/A error value.

16            If all text starting at start_num for count_num characters is italic, returns TRUE. If text contains only partial italic formatting, returns the #N/A error value.

17            If all text starting at start_num for count_num characters is underlined, returns TRUE. If text contains only partial underline formatting, returns the #N/A error value.

18            If all text starting at start_num for count_num characters is struck through, returns TRUE. If text contains only partial struck-through formatting, returns the #N/A error value.

19            In Microsoft Excel for the Macintosh, if all text starting at start_num for count_num characters is outlined, returns TRUE. If text contains only partial outline formatting, returns the #N/A error value. Always returns FALSE in Microsoft Excel for Windows.

20            In Microsoft Excel for the Macintosh, if all text starting at start_num for

count_num characters is shadowed, returns TRUE. If text contains only partial shadow formatting, returns the #N/A error value. Always returns FALSE in Microsoft Excel for Windows.

21            Number from 0 to 56 indicating the color of all text starting at start_num for count_num characters; if color is automatic, returns 0. If more than one color is used, returns the #N/A error value.

Values 22 to 25 for type_num also apply only to text boxes and buttons. If another type of object is selected, GET.OBJECT returns the #N/A error value.

Type_num

 

Returns

23          Number indicating the vertical alignment of text:

1  = Top

2  = Center

3  = Bottom

4  = Justified

24          Number indicating the orientation of text:

0  = Horizontal

1  = Vertical

2  = Upward

3  = Downward

25          If button or text box is set to automatic sizing, returns TRUE; otherwise FALSE.

The following values for type_num apply to all objects, except where indicated.

Type_num

 

Returns

27          Number indicating the type of the border or line:

0  = Custom

1  = Automatic

2  = None

28          Number indicating the style of the border or line as shown in the Patterns tab in the Format Objects dialog box:

0  = None

1  = Solid line

2  = Dashed line

3  = Dotted line

4  = Dashed dotted line

5  = Dashed double-dotted line

6  = 50% gray line

7  = 75% gray line

8  = 25% gray line

29          Number from 0 to 56 indicating the color of the border or line; if the border is automatic, returns 0.

30          Number indicating the weight of the border or line:

1  = Hairline

2  = Thin

3  = Medium

4  = Thick

31          Number indicating the type of fill:

0  = Custom

1  = Automatic

2  = None

32          Number from 1 to 18 indicating the fill pattern as shown in the Format Object dialog box.

33          Number from 0 to 56 indicating the foreground color of the fill pattern; if the fill is automatic, returns 0. If the object is a line, returns the #N/A error value.

34          Number from 0 to 56 indicating the background color of the fill pattern; if the fill is automatic, returns 0. If the object is a line, returns the #N/A error value.

35          Number indicating the width of the arrowhead:

1  = Narrow

2  = Medium

3  = Wide

If the object is not a line, returns the #N/A error value.

36          Number indicating the length of the arrowhead:

1  = Short

2  = Medium

3  = Long

If the object is not a line, returns the #N/A error value.

37          Number indicating the style of the arrowhead:

1  = No head

2  = Open head

3  = Closed head

4  = Open double-ended head

5  = Closed double-ended head

If the object is not a line, returns the #N/A error value.

38          If the border has round corners, returns TRUE; if the corners are square, returns FALSE. If the object is a line, returns the #N/A error value.

39          If the border has a shadow, returns TRUE; if the border has no shadow, returns FALSE. If the object is a line, returns the #N/A error value.

40          If the Lock Text check box in the Protection Tab of the Format Object dialog box is selected, returns TRUE; otherwise FALSE.

41          If objects are set to be printed, returns TRUE; otherwise FALSE.

42          The horizontal distance, measured in points, from the left edge of the active window to the left edge of the object. May be a negative number if the window is scrolled beyond the object.

43          The vertical distance, measured in points, from the top edge of the active window to the top edge of the object. May be a negative number if the window is scrolled beyond the object.

44          The horizontal distance, measured in points, from the left edge of the active window to the right edge of the object. May be a negative number if the window is scrolled beyond the object.

45          The vertical distance, measured in points, from the top edge of the active window to the bottom edge of the object. May be a negative number if the window is scrolled beyond the object.

46          The number of vertices in a polygon, or the #N/A error value if the object is not a polygon.

47          A count_num by 2 array of vertex coordinates starting at start_num in a polygon's array of vertices.

48          If the object is a text box, returns the cell reference that the text box is linked to. If the object is a control on a worksheet, returns the cell reference that the control's value is linked to. This information is returned as a string.

49          Returns the ID number of the object. For example, "Rectangle 5" returns

5. Note that the name of the object may not have this index in it if the object has been renamed by the user.

50          Returns the object's classname. For example, "Rectangle".

51          Returns the object name. By default, object names are the classname

followed by the ID. For example, "Rectangle 1" is an object name, of which "Rectangle" is the classname, and 1 is the ID number. The object can also be renamed, in which case the name picked by the user is returned.

52          Returns the distance from cell A1 to the Left of the object bounding rectangle in points

53          Returns the distance from Cell A1 to the top of the object bounding rectangle in points

54          Returns the width of object bounding rectangle in points

55          Returns the height of object bounding rectangle in points 56        If the object is enabled, returns TRUE; otherwise, it returns FALSE.

57          Returns the shortcut key assignment for the control object, as text.

58          Returns TRUE is the button control on a dialog sheet is the default button of the dialog; otherwise, returns FALSE

59          Returns TRUE if the button control on the dialog sheet is clicked when the user presses the ESCAPE Key; otherwise, returns FALSE.

60          Returns TRUE if the button control on a dialog sheet will close the dialog box when pressed; otherwise, returns FALSE

61          Returns TRUE if the button control on a dialog sheet will be clicked when the user presses F1.

62          Returns the value of the control. For a check box or radio button, Returns

1  if it is selected, zero if it is not selected, or 2 if mixed. For a List box or dropdown box, returns the index number of the selected item, or zero if no item is selected. For a scroll bar, returns the numeric value of the scroll bar.

63          Returns the minimum value that a scroll bar or spinner button can have

64          Returns the maximum value that a scroll bar or spinner button can have

65          Returns the step increment value added or subtracted from the value of a scroll bar or spinner. This value is used when the arrow buttons are pressed on the control.

66          Returns the large, or "page" step increment value added or subtracted from the value of a scroll bar when it is clicked in the region between the thumb and the arrow buttons.

67          Returns the input type allowed in an edit box control:

1  = Text

2  = Integer

3  = Number (what type)

4  = Cell reference

5  = Formula

68          Returns TRUE if the edit box control allows multi-line editing with wrapped text; otherwise, it returns FALSE.

69          Returns TRUE if the edit box has a vertical scroll bar; otherwise, it returns FALSE.

70          Returns the object ID of the object that is linked to a list box or edit box. For a dropdown combo box that has an editable entry field, returns the object ID of itself. A dropdown box that can't be edited, returns FALSE.

71          Returns the number of entries in a List box, dropdown List box, or dropdown combo box.

72          Returns the text of the selected entry in a List box, dropdown List box, or dropdown combo box.

73          Returns the range used to fill the entries in a List box, dropdown List box, or dropdown combo box, as text. If an empty string is returned, then the control isn't filled from a range.

74          Returns the number of list lines displayed when a dropdown control is dropped.

75          Returns TRUE the object is displayed as 3-D; otherwise, it returns FALSE.

76          Returns the Far East phonetic accelerator key as text. Used for Far East versions of Microsoft Excel.

77          Returns the select status of the list box:

0  = single

1  = simple multi-select

2  = extended multi-select

78          Returns an array of TRUE and FALSE values indicating which items are

selected in a list box. If TRUE, the item is selected; If FALSE, the item is not selected.

79          Returns TRUE if the add indent attribute is on for alignment. Returns FALSE if the add indent attribute is off for alignment. Used for only Far East versions of Microsoft Excel.

Object_id_text    is the name and number, or number alone, of the object you want information about. Object_id_text is the text displayed in the reference area when the object is selected. If object_id_text is omitted, it is assumed to be the selected object. If object_id_text is omitted and no object is selected, GET.OBJECT returns the #REF! error value and interrupts the macro.

Start_num    is the number of the first character in the text box or button or the first vertex in a polygon you want information about. Start_num is ignored unless a text box, button, or polygon is specified by type_num and object_id_text. If start_num is omitted, it is assumed to be 1.

Count_num    is the number of characters in a text box or button, or the number of vertices in a polygon, starting at start_num, that you want information about. Count_num is ignored unless a text box, button, or polygon is specified by type_num and object_id_text. If count_num is omitted, it is assumed to be 255.

Item_index    is the index number or position of the item in the list box or drop-down box that you want information about, ranging from 1 to the number of items in the list box or drop-down box.

Tip   Use GET.OBJECT(45) - GET.OBJECT(43) to determine the height of an object and GET.OBJECT(44) - GET.OBJECT(42) to determine the width.

Examples

The following macro formula returns the reference of the cell under the upper-left corner of the object Oval 3 (assume the cell is E2):

GET.OBJECT(4, "Oval 3") returns "R2C5"

The following macro formula changes the protection status of the object Rectangle 2 if it is locked:

IF(GET.OBJECT(2, "Rectangle 2"), OBJECT.PROTECTION(FALSE))

The following macro formula returns characters 25 through 185 from the object Text 5:

GET.OBJECT(12, "Text 5", 25, 160)

Related Functions

CREATE.OBJECT   Creates an object

FONT.PROPERTIES   Applies a font to the selection

OBJECT.PROTECTION   Controls how an object is protected

PLACEMENT   Determines an object's relationship to underlying cells

GET.PIVOT.FIELD

Returns information about a field in a PivotTable report.

Syntax

GET.PIVOT.FIELD(type_num, pivot_field_name, pivot_table_name)

Type_num    is a value from 1 to 17 that returns the following types of information:

Type_num

 

Value

1          Returns an array of all the items which make up pivot_field_name. The array is made up of text constants, dates or numbers depending on the field.

2          Returns an array of all items which are set to show with the pivot_field_name. The array is made up of text constants, dates or numbers depending on the field. The array is returned in the order that the items are displayed in the PivotTable report. If pivot_field_name is a page field, then the array contains only one element, the value corresponding to the active page (this could be all if the All item is showing).

3          Returns an array of all items which are hidden in the pivot_field_name. The array is made up of text constants, dates or numbers depending on the field. If pivot_field_name is a data field or the data header name, this function returns the #N/A! error value.

4          Returns an integer describing where the field is displayed in the active PivotTable report (either row or column): 

0  = Hidden

1  = Row

2  = Col

3  = Page

4  = Data

5          Returns an array of all items in pivot_field_name that are group parents. The array is made up of text constants, dates or numbers depending on the field. The array is returned in the order which these items appear in the PivotTable report. Returns #N/A if there are no group parents and if the pivot_field_name is a data field or the data field header.

6          Returns a number between 0 and 4095 which describes the subtotals attached to the field. The number is the sum of the values associated with each subtotal function. See PIVOT.FIELD.PROPERTIES for a list of all the values associated with subtotal calculations. If the field is showing as a data field or data field header, #N/A! is returned.

7          Returns an integer describing the type of data contained in the field:  

0  = Text

1  = Number

2  = Date

8          Returns an array five columns wide and one row high describing the summary function's custom calculation shown with the specified field (Data field) in the PivotTable report. The array will look as follows: {function, calculation, base field, base item, number format}. If pivot_field_name is not showing in the active PivotTable report as a data field, #N/A! is returned.

9          Returns a reference to all of pivot_field_name's items currently showing in the active PivotTable report. If pivot_field_name is hidden, #N/A! is returned. If pivot_field_name is a page field, the reference to the currently showing page item is returned. If pivot_field_name is a data field, a reference to all the data for this field in the PivotTable report is returned. The references are returned as text.

10          Returns a reference to the header cell for pivot_field_name. If pivot_field_name is a data field, a reference to all the headers in the data row or column is returned. If pivot_field_name is hidden, #N/A! is returned. The reference is returned as text.

11          Returns the number of grouped fields in the grouped field set which includes pivot_field_name. If pivot_field_name is neither a parent field nor a child field, 1 is returned. If pivot_field_name is a data field or data header name, the function returns the #N/A! error value.

12          Returns the level of pivot_field_name in the grouped field set which includes pivot_field_name. Returns 1 for the highest level parent field, 2 for its child field, and so on. If pivot_field_name is neither a parent field nor a child field, 1 is returned. If pivot_field_name is a data field or data header name, the function returns the #N/A! error value.

13          Returns the name of the parent field for pivot_field_name as a text

constant. If pivot_field_name is not a child field, #N/A! is returned.

14          Returns the name of the child field for pivot_field_name as a text constant. If pivot_field_name is not a parent field, #N/A! is returned.

15          Returns a text constant representing the original name of the field in the data source.

16          Returns the position of the field among all the other fields in its orientation. For instance, a 1 would be returned if the field was the first row field.

17          Returns an array of all items in pivot_field_name that are group children. The array is made up of text constants, dates or numbers depending on the field. The array is returned in the order which these items appear in the PivotTable report. Returns #N/A if there are no group children, and if the pivot_field_name is a data field or the data field header.

Pivot_field_name    is the name of the field that you want information about. If there is no field named pivot_field_name in the PivotTable report, returns #VALUE!.

Pivot_table_name    is the name of a PivotTable report containing the field that you want information about. If omitted, the PivotTable report containing the active cell is used. If the active cell is not in a PivotTable report, the #VALUE! error value is returned.

Related Functions

   Returns information about an item in a PivotTable report.

GET.PIVOT.TABLE   Returns information about a PivotTable report.

Returns information about an item in a PivotTable report.

Syntax

(type_num, pivot_item_name, pivot_field_name, pivot_table_name)

Type_num    is a value from 1 to 9 the represents the type of information you want about an item in a PivotTable report.

Type_num

 

Information

1          Returns the position of the item in its field. Returns #N/A if

pivot_field_name is a data field. Returns #N/A! if the item is hidden.

2          Returns the reference to all the cells in the PivotTable header currently containing pivot_item_name. This reference is returned as text. If pivot_item_name is currently not showing in the PivotTable report, #N/A! is returned.

3          Returns the reference to all the data in the PivotTable report which is qualified by pivot_item_name. This reference is returned as text. If pivot_item_name is currently not showing in the PivotTable report, #N/A! is returned.

4          Returns an array of text constants representing the children of pivot_item_name if pivot_item_name is a parent. Otherwise the function returns #N/A!.

5          Returns a text constant representing the parent of pivot_item_name, if pivot_item_name exists as part of a group. Otherwise the function returns #N/A!.

6          Returns TRUE if pivot_item_name is a member of a group which is currently expanded to show detail. Returns FALSE if pivot_item_name is a member of a group currently collapsed to hide detail. If pivot_item_name is not a member of a group, the function returns #N/A!.

7          Returns TRUE if pivot_item_name is expanded to show detail. Returns

FALSE if pivot_item_name is collapsed to hide detail.

8          Returns TRUE if the item pivot_item_name is currently visible, FALSE if it is hidden.

9          Returns the name of the item as it appeared in the original at a source. This will differ from the current item name only if the user changes the name of the item after creating the PivotTable report.

Pivot_item_name    is the name of the item that you want information about. If there is no item named pivot_item_name in the PivotTable report, returns #VALUE!.

Pivot_field_name    is the name of the field that you want information about. If there is no field named pivot_field_name in the PivotTable report, returns #VALUE!.

Pivot_table_name    is the name of a PivotTable report containing the field that you want information about. If omitted, uses the PivotTable report containing the active cell. If the active cell is not in a PivotTable report, the #VALUE! error value is returned.

Related Functions

GET.PIVOT.FIELD   Returns information about an item in a PivotTable report.

GET.PIVOT.TABLE   Returns information about a PivotTable report.

GET.PIVOT.TABLE

Returns information about a PivotTable report.

Syntax

GET.PIVOT.TABLE(type_num,pivot_table_name)

Type_num is a value from 1 to 22 that represents a type of information you want about a PivotTable report.

Type_num

 

Information

1                   Returns the name of the person who last updated the

PivotTable report, as a text constant.

2                   Returns the date the PivotTable report was last updated, as

a serial number.

3                   Returns a horizontal array of text constants representing all

the fields in the PivotTable report.

4                   Returns an integer representing the number of fields in the

PivotTable report.

5                   Returns a horizontal array of text constants representing all

the visible fields in the PivotTable report (rows, columns, pages or data)

6                   Returns a horizontal array of text constants representing all

the hidden fields in the PivotTable report. Return #N/A if no hidden fields.

7                   Returns a horizontal array of text constants representing

the names of all the fields currently showing in the PivotTable report as row fields. Returns #N/A if there are no row fields.

8                   Returns a horizontal array of text constants representing all

the fields currently showing in the PivotTable report as column fields. Returns #N/A if no column fields exist. 9     Returns a horizontal array of text constants representing all

the fields currently showing in the PivotTable report as page fields. Return #N/A if no page fields exist.

10                   Returns a horizontal array of text constants representing all

the fields currently showing in the PivotTable report as data fields. Returns #N/A if there are no data fields.

11                   Returns the smallest rectangular reference which bounds

the PivotTable report and all headers (not including the page header). This reference is returned as text.

12                   Returns the smallest rectangular reference which bounds

the PivotTable report and all headers (including the page headers). This reference is returned as text.

13                   Returns the reference to the row header area as text. The

row header area includes each row field header along with all the items in each row field. Returns #N/A if there are no row headers.

14                   Returns the reference to the column header area as text.

The column header area includes each column field header along with all the items in each column field. Returns #N/A if there are no column headers.

15                   Returns the reference to the data header area as text. The

data header area includes the data field header along with all the headers in the data row/col. Returns #N/A if there is no data field.

16                   Returns a reference to all the page headers as text.

17                   Returns the reference to the PivotTable report data area as

text.

18                   Returns TRUE if the PivotTable report is set to show row

grand totals.

19                   Returns TRUE if the PivotTable report is set to show column

grand totals.

20                   Returns TRUE if the user is saving data with the PivotTable

report.

21                   Returns TRUE if the PivotTable report is set up to

Autoformat on pivoting.

22                   Returns the data source of the PivotTable report. The kind of information returned depends on the data source: 

If the data source is a Microsoft Excel list or database, the cell reference is returned as text.

If the data source is an external data source, then an array is returned. Each row consists of a SQL connection string with the remaining elements as the query string broken down into 200 character segments.

If the data source is Multiple Consolidation ranges, then a two dimensional array is returned, each row of which consists of a reference and associated page field items.

If the data source is another PivotTable report, then one of the above three kinds of information is returned.

Pivot_table_name    is the name of a PivotTable report containing the field that you want information about. If omitted, uses the PivotTable report containing the active cell.

Remarks

Returns #VALUE! error value when pivot_table_name is not a valid PivotTable name on the active sheet and the active cell is not within a PivotTable report.

Related Functions

GET.PIVOT.FIELD   Returns information about an item in a PivotTable report.

   Returns information about a PivotTable report.

Returns information about a button or buttons on a toolbar. Use to get information about a button to use with functions that add, delete, or alter buttons.

Syntax

(type_num, bar_id, position)

Type_num    specifies what type of information you want to return.

Type_num

 

Returns

1                    The button's ID number. Gaps are represented by zeros.

2                    The reference of the macro assigned to the button. If no

macro is assigned, returns the #N/A error value.

3                    If the button is down, returns TRUE. If the button is up,

returns FALSE.

4                    If the button is enabled, returns TRUE. If the button is

disabled, returns FALSE.

5                    A logical value indicating the type of the face on the

button:

                                                  TRUE = bitmap

                                                  FALSE = a default button face

6                    The help_text reference associated with the custom

button. If the button is built-in, returns #N/A.

7                    The balloon_text reference associated with the custom

button. If the button is built-in, returns the #N/A error value.

8                    The Help context string associated with the custom

button.

9                    The Tip_text associated with the custom button.

Bar_id    specifies the number or name of the toolbar for which you want information. For detailed information about bar_id, see .

Position    specifies the position of the button on the toolbar. Position starts with 1 at the left side (if horizontal) or at the top (if vertical). A position can be occupied by a button or a gap.

Example

The following macro formula requests the help text associated with the third button in Toolbar2:

(6, "Toolbar2", 3)

Related Functions

   Adds one or more buttons to a toolbar

   Deletes a button from a toolbar

   Enables or disables a button on a toolbar

GET.TOOLBAR   Retrieves information about a toolbar

GET.TOOLBAR

Returns information about one toolbar or all toolbars. Use GET.TOOLBAR to get information about a toolbar to use with functions that add, delete, or alter toolbars.

Syntax

GET.TOOLBAR(type_num, bar_id)

Type_num    specifies what type of information to return. If type_num is 8 or 9, GET.TOOLBAR returns an array of names or numbers of all visible or hidden toolbars. Otherwise, bar_id is required, and GET.TOOLBAR returns the requested information about the specified toolbar.

Type_num

 

Returns

1                      A horizontal array of all tool IDs on the toolbar,

ordered by position. Gaps are represented by zeros.

2                      Number indicating the horizontal position (x-

coordinate) of the toolbar in the docked or floating region. For more information, see SHOW.TOOLBAR.

3                      Number indicating the vertical position (y-

coordinate) of the toolbar in the docked or floating region.

4                      Number indicating the width of the toolbar in points.

5                      Number indicating the height of the toolbar in points.

6                      Number indicating the toolbar location:

1  = Top dock in the workspace

2  = Left dock in the workspace

3  = Right dock in the workspace

4  = Bottom dock in the workspace

5  = Floating

7                      If the toolbar is visible, returns TRUE. If the toolbar

is hidden, returns FALSE.

8                      An array of toolbar IDs (names or numbers in the bar_id array) for all toolbars, visible and hidden.

9                      An array of toolbar IDs (names or numbers in the

bar_id array) for all visible toolbars.

10                      If the toolbar is visible in full-screen mode, returns

TRUE; otherwise, returns FALSE.

Bar_id    specifies the number or name of a toolbar for which you want information. If type_num is 8 or 9, Microsoft Excel ignores bar_id. For detailed information about bar_id, see .

Remarks

If you request position information for a hidden toolbar, Microsoft Excel returns the position where the toolbar would appear if shown.

Examples

The following macro formula returns information about the width of Toolbar1:

GET.TOOLBAR(4, "Toolbar1")

When the following macro formula is entered as an array with CTRL+SHIFT+ENTER, the IDs of all visible toolbars are returned, and the array is named All_Bar_Ids:

("All_Bar_Ids", GET.TOOLBAR(9))

Related Functions

   Adds one or more buttons to a toolbar

ADD.TOOLBAR   Creates a new toolbar with the specified tools

DELETE.TOOLBAR   Deletes custom toolbars

   Returns information about a tool or tools on a toolbar

SHOW.TOOLBAR   Hides or displays a toolbar

GET.WINDOW

Returns information about a window. Use GET.WINDOW in a macro that requires the status of a window, such as its name, size, position, and display options.

Syntax

GET.WINDOW(type_num, window_text)

Type_num    is a number that specifies what type of window information you want. The following list shows the possible values of type_num and the corresponding results:

Type_num

 

Returns

1                         Name of the workbook and sheet in the window as text. For compatibility with Microsoft Excel version 4.0, if the window contains only a single sheet that has the same name as the workbook without its extension, returns only the name of the book. Otherwise, returns the name of the sheet in the form "[Book1]Sheet1".

2                         Number of the window.

3                         X position, measured in points from the left edge of the workspace (in Microsoft Excel for Windows) or screen (in Microsoft Excel for the Macintosh) to the left edge of the window.

4                         Y position, measured in points from the bottom edge of the formula bar to the top edge of the window.

5                         Width, measured in points.

6                         Height, measured in points.

7                         If window is hidden, returns TRUE; otherwise, returns FALSE.

The rest of the values for type_num apply only to worksheets and macro sheets, except where indicated:

Type_num

 

Returns

8                         If formulas are displayed, returns TRUE; otherwise, returns FALSE.

9                         If gridlines are displayed, returns TRUE; otherwise, returns FALSE.

10                         If row and column headings are displayed, returns TRUE; otherwise, returns FALSE.

11                         If zeros are displayed, returns TRUE; otherwise, returns FALSE.

12                         Gridline and heading color as a number in the range 1 to 56, corresponding to the colors in the View tab of the Options dialog box; if color is automatic, returns 0.

Values 13 to 16 for type_num return arrays that specify which rows or columns are at the top and left edges of the panes in the window and the widths and heights of those panes. 

•   The first number in the array corresponds to the first pane, the second number to the second pane, and so on.

•   If the edge of the pane occurs at the boundary between rows or columns, the number returned is an integer.

•   If the edge of the pane occurs within a row or column, the number returned has a fractional part that represents the fraction of the row or column visible within the pane.

•   The numbers can be used as arguments to the SPLIT function to split a window at specific locations.

Type_num

 

Returns

13                         Leftmost column number of each pane, in a

horizontal numeric array

14                         Top row number of each pane, in a horizontal

numeric array.

15                         Number of columns in each pane, in a horizontal

numeric array.

16                         Number of rows in each pane, in a horizontal

numeric array.

17                         Number indicating the active pane: 

1  = Upper, left, or upper-left

2  = Right or upper-right

3  = Lower or lower-left

4  = Lower-right

18                         If window has a vertical split, returns TRUE;

otherwise, returns FALSE.

19                         If window has a horizontal split, returns TRUE;

otherwise, returns FALSE.

20                         If window is maximized, returns TRUE; otherwise,

returns FALSE.

21                         Reserved

22                         If the Outline Symbols check box is selected in

the View tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

23                         Number indicating the size of the window

(including charts): 

1  = Restored

2  = Minimized (displayed as an icon)

3  = Maximized

24                         If panes are frozen on the active window, returns

TRUE; otherwise, returns FALSE.

25                         The numeric magnification of the active window

(as a percentage of normal size) as set in the Zoom dialog box, or 100 if none is specified.

26                         Returns TRUE if horizontal scrollbars are displayed

in the active window; otherwise, returns FALSE.

27                         Returns TRUE if vertical scrollbars are displayed in

the active window; otherwise, returns FALSE.

28                         Returns the tab ratio of workbook tabs to

horizontal scrollbar, from 0 to 1. The default is .6.

29                         Returns TRUE if workbook tabs are displayed in

the active window; otherwise, returns FALSE.

30                         Returns the title of the active sheet in the window

in the form "[Book1]Sheet1".

31                         Returns the name of a workbook only, without

read/write indicated. For example, if is read only, then "" will be returned without "[Read Only]" appended.

Window_text    is the name that appears in the title bar of the window that you want information about. If window_text is omitted, it is assumed to be the active window. Examples

If the active window contains the workbook Book1, then:

GET.WINDOW(1) equals "Book1"

If the title of the active window is Macro1:3, then:

GET.WINDOW(2) equals 3

In Microsoft Excel for Windows, the following macro formula returns the gridline and heading color of :

GET.WINDOW(12, "")

In Microsoft Excel for the Macintosh, the following macro formula returns the gridline and heading color of REPORT MASTER:

GET.WINDOW(12, "REPORT MASTER")

Related Functions

GET.DOCUMENT   Returns information about a workbook

GET.WORKSPACE   Returns information about the workspace

GET.WORKBOOK

Returns information about a workbook.

Syntax

GET.WORKBOOK(type_num, name_text)

Type_num    is a number that specifies what type of workbook information you want.

Type_num

 

Returns

1                    The names of all sheets in the workbook, as a horizontal

array of text values. Names are returned as [book]sheet.

2                    This will always return the #N/A error value.

3                    The names of the currently selected sheets in the workbook,

as a horizontal array of text values.

4                    The number of sheets in the workbook.

5                    TRUE if the workbook has a routing slip; otherwise, FALSE.

6                    The names of all of the workbook routing recipients who

have not received the workbook, as a horizontal array of text values.

7                    The subject line for the current routing slip, as text.

8                    The message text for the routing slip, as text.

9                    If the workbook is to be routed to recipients one after

another, returns 1. If it is to be routed all at once, returns 2.

10                 TRUE, if the Return When Done check box in the Routing

Slip dialog box is selected; otherwise, FALSE.

11                 TRUE, if the current recipient has already forwarded the

current workbook; otherwise, FALSE.

12                 TRUE, if the Track Status checkbox in the Routing Slip

dialog box is selected; otherwise, FALSE.

13                 Status of the workbook routing slip: 

0  = Unrouted

1  = Routing in progress, or the workbook has been routed to a user

2  = Routing is finished

14                 TRUE, if the workbook structure is protected; otherwise,

FALSE.

15                 TRUE, if the workbook windows are protected; otherwise,

FALSE.

16                 Name of the workbook as text. The workbook name does

not include the drive, directory or folder, or window number.

17                 TRUE if the workbook is read only; otherwise, FALSE. This is

the equivalent of GET.DOCUMENT(34).

18                 TRUE if sheet is write-reserved; otherwise, FALSE. This is

the equivalent of GET.DOCUMENT(35).

19                 Name of the user with current write permission for the

workbook. This is the equivalent of GET.DOCUMENT(36).

20                 Number corresponding to the file type of the document as

displayed in the Save As dialog box. This is the equivalent of GET.DOCUMENT(37).

21                 TRUE if the Always Create Backup check box is selected in

the Save Options dialog box; otherwise, FALSE. This is the equivalent of GET.DOCUMENT(40).

22                 TRUE if the Save External Link Values check box is selected

in the Calculation tab of the Options dialog box. This is the equivalent of GET.DOCUMENT(43).

23                 TRUE if the workbook has a PowerTalk mailer; otherwise,

FALSE. Returns #N/A if no OCE mailer is installed.

24                 TRUE if changes have been made to the workbook since the

last time it was saved; FALSE if book is unchanged (or when closed, will not prompt to be saved).

25                 The recipients on the To line of a PowerTalk mailer, as a horizontal array of text.

26                 The recipients on the Cc line of a PowerTalk mailer, as a

horizontal array of text.

27                 The recipients on the Bcc line of a PowerTalk mailer, as a

horizontal array of text.

28                 The subject of the PowerTalk mailer, as text.

29                 The enclosures of the PowerTalk mailer, as a horizontal

array of text.

30                 TRUE, if the PowerTalk mailer has been received from

another user (as opposed to just being added but not sent). FALSE, if the mailer has not been received from another user.

31                 The date and time the PowerTalk mailer was sent, as a

serial number. Returns the #N/A error value if the mailer has not yet been sent.

32                 The sender name of the PowerTalk mailer, as text. Returns

the #N/A error value if the mailer has not yet been sent.

33                 The title of the workbook as displayed on the Summary tab

of the Properties dialog box, as text.

34                 The subject of the workbook as displayed on the Summary

tab of the Properties dialog box, as text.

35                 The author of the workbook as displayed on the Summary

tab of the Properties dialog box, as text.

36                 The keywords for the workbook as displayed on the

Summary tab of the Properties dialog box, as text.

37                 The comments for the workbook as displayed on the

Summary tab of the Properties dialog box, as text.

38                 The name of the active sheet.

Name_text    is the name of an open workbook. If name_text is omitted, it is assumed to be the active workbook.

Example

The following macro formula returns the name of the active sheet in the workbook named :

GET.WORKBOOK(38, "")

Related Functions

GET.DOCUMENT   Returns information about a workbook

WORKBOOK.SELECT   Selects the specified documents in a workbook

GET.WORKSPACE

Returns information about the workspace. Use GET.WORKSPACE in a macro that depends on the status of the workspace, such as the environment, version number, and available memory.

Syntax

GET.WORKSPACE(type_num)

Type_num    is a number specifying the type of workspace information you want. The following list shows the type_num values and their corresponding results.

Type_num

 

Returns

1                  Name of the environment in which Microsoft Excel is running, as

text, followed by the environment's version number.

2                  The version number of Microsoft Excel, as text (for example,

"5.0").

3                  If fixed decimals are set, returns the number of decimals;

otherwise, returns 0.

4                  If in R1C1 mode, returns TRUE; if in A1 mode, returns FALSE.

5                  If scroll bars are displayed, returns TRUE; otherwise, returns FALSE. See also GET.WINDOW(26) and GET.WINDOW(27).

6                  If the status bar is displayed, returns TRUE; otherwise, returns

FALSE.

7                  If the formula bar is displayed, returns TRUE; otherwise,

returns FALSE.

8                  If remote DDE requests are enabled, returns TRUE; otherwise,

returns FALSE.

9                  Returns the alternate menu key as text; if no alternate menu

key is set, returns the #N/A error value.

10               Number indicating special modes:

1  = Data Find

2  = Copy

3  = Cut

4  = Data Entry

5  = Unused

6  = Copy and Data Entry

7  = Cut and Data Entry

If no special mode is set, returns 0.

11               X position of the Microsoft Excel workspace window, measured

in points from the left edge of the screen to the left edge of the window. In Microsoft Excel for the Macintosh, always returns 0.

12               Y position of the Microsoft Excel workspace window, measured

in points from the top edge of the screen to the top edge of the window. In Microsoft Excel for the Macintosh, always returns 0.

13               Usable workspace width, in points.

14               Usable workspace height, in points.

15               Number indicating maximized or minimized status of Microsoft

Excel:

1  = Neither

2  = Minimized

3  = Maximized

Microsoft Excel for the Macintosh always returns 3.

16               Amount of memory free (in kilobytes).

17               Total memory available to Microsoft Excel (in kilobytes).

18               If a math coprocessor is present, returns TRUE; otherwise,

returns FALSE.

19               If a mouse is present, returns TRUE; otherwise, returns FALSE.

In Microsoft Excel for the Macintosh, always returns TRUE.

20               If a group is present in the workspace, returns a horizontal

array of sheets in the group; otherwise returns the #N/A error value.

21               If the Standard toolbar is displayed, returns TRUE; otherwise,

returns FALSE.

22               DDE-application-specific error code.

23               Full path of the default startup directory or folder.

24               Full path of the alternate startup directory or folder; returns the

#N/A error value if no alternate path has been specified.

25               If Microsoft Excel is set for relative recording, returns TRUE; if set for absolute recording, returns FALSE.

26               Name of user.

27               Name of organization.

28               If Microsoft Excel menus are switched to by the transition menu

or help key, returns 1; if Lotus 1-2-3 Help is switched to, returns 2.

29               If transition navigation keys are enabled, returns TRUE.

30               A nine-item horizontal array of global (default) print settings

that can be set by the LINE.PRINT function: 

Setup text

Left margin

Right margin

Top margin

Bottom margin

Page length

Logical value indicating whether to wait after printing each page (TRUE) or use continuous form feeding (FALSE)

Logical value indicating whether the printer has automatic line feeding (TRUE) or requires line feed characters (FALSE)

The number of the printer port

31               If a currently running macro is in single step mode, returns

TRUE; otherwise, returns FALSE.

32               The current location of Microsoft Excel as a complete path.

33               A horizontal array of the names in the New list, in the order

they appear.

34               A horizontal array of template files (with complete paths) in the

New list, in the order they appear (returns the names of custom template files and the #N/A error value for built-in document types).

35               If a macro is paused, returns TRUE; FALSE otherwise.

36               If the Allow Cell Drag And Drop check box is selected in the Edit tab of the Options dialog box that appears when you click the Options command on the Tools menu, returns TRUE; otherwise, returns FALSE.

37               A 45-item horizontal array of the items related to country

versions and settings. Use the following macro formula to return a specific item, where number is a number in the list below:

INDEX(GET.WORKSPACE(37), number)

                                        These values apply to country codes:

1  = Number corresponding to the country version of Microsoft Excel.

2  = Number corresponding to the current country setting in the Microsoft Windows Control Panel or the country number as determined by your Apple system software

                                        These values apply to number separators:

3  = Decimal separator

4  = Zero (or 1000) separator

5  = List separator

                                        These values apply to R1C1-style references:

6  = Row character

7  = Column character

8  = Lowercase row character

9  = Lowercase column character

10   = Character used instead of the left bracket ([) 11 = Character used instead of the right bracket (])

                                        These values apply to array characters:

12  = Character used instead of the left bracket ({)

13  = Character used instead of the right bracket (})

14  = Column separator

15  = Row separator

16  = Alternate array item separator to use if the current array separator is the same as the decimal separator

                                        These values apply to format code symbols:

17  = Date separator

18  = Time separator

19  = Year symbol

20  = Month symbol

21  = Day symbol

22  = Hour symbol

23  = Minute symbol

24  = Second symbol

25  = Currency symbol

26  = "General" symbol

                                        These values apply to format codes:

27  = Number of decimal digits to use in currency formats 28 = Number indicating the current format for negative currencies:

0  = ($currency) or (currency$)

1  = -$currency or -currency$

2  = $-currency or currency-$    3 = $currency- or currency$- where currency is any number and the $ represents the current currency symbol.

29   = Number of decimal digits to use in noncurrency number formats

30   = Number of characters to use in month names 31 = Number of characters to use in weekday names 32 = Number indicating the date order:

0  = Month-Day-Year

1  = Day-Month-Year

2  = Year-Month-Day

                                        These values apply to logical format values:

33 = TRUE if using 24-hour time; FALSE if using 12-hour time. 34 = TRUE if not displaying functions in English; otherwise, returns FALSE.

35   = TRUE if using the metric system; FALSE if using the English measurement system.

36   = TRUE if a space is added before the currency symbol; otherwise, returns FALSE.

37   = TRUE if currency symbol precedes currency values; FALSE if it follows currency values.

38   = TRUE if using minus sign for negative numbers; FALSE if using parentheses.

39   = TRUE if trailing zeros are displayed for zero currency values; otherwise, returns FALSE.

40   = TRUE if leading zeros are displayed for zero currency values; otherwise, returns FALSE.

41   = TRUE if leading zero is displayed in months (when months are displayed as numbers); otherwise, returns FALSE. 42 = TRUE if leading zero is shown in days (when days are displayed as numbers); otherwise, returns FALSE.

43   = TRUE if using four-digit years; FALSE if using two-digit years.

44   = TRUE if date order is month-day-year when displaying dates in long form; FALSE if date order is day-month-year. 45 = TRUE if leading zero is shown in the time; otherwise, returns FALSE.

38               The number 0, 1, or 2 indicating the type of error-checking as

set by the ERROR function. For more information, see ERROR.

39               A reference in R1C1-text form to the currently defined error-

handling macro (set by the ERROR function), or the #N/A error value if none is specified.

40               If screen updating is turned on (set by the ECHO function),

returns TRUE; otherwise, returns FALSE.

41               A horizontal array of cell ranges, as R1C1-style text, that were previously selected with the Go To command from the Edit menu or the macro function. If the book has multiple sheets, or if the single sheet in the workbook is named differently than the workbook itself, returns names as [Book]Sheet.

42               If your computer is capable of playing sounds, returns TRUE;

otherwise, returns FALSE.

43               If your computer is capable of recording sounds, returns TRUE;

otherwise, returns FALSE.

44               A three-column array of all currently registered procedures in

dynamic link libraries (DLLs). The first column contains the names of the DLLs that contain the procedures (in Microsoft Excel for Windows) or the names of the files that contain the code resources (in Microsoft Excel for the Macintosh). The second column contains the names of the procedures in the DLLs (in Microsoft Excel for Windows) or code resources (in Microsoft Excel for the Macintosh). The third column contains text strings specifying the data types of the return values, and the number and data types of the arguments. For more information about DLLs and code resources and data types, see

Using the CALL and REGISTER functions in Microsoft Excel Help.

45               If Microsoft Windows for Pen Computing is running, returns

TRUE; otherwise, returns FALSE.

46               If the Move Selection After Enter check box is selected in the

Edit tab of the Options dialog box, returns TRUE; otherwise, returns FALSE.

47               Reserved.

48               Path to the library subdirectory for Microsoft Excel, as text.

49               MAPI session currently in use, returned as a string of hex digits

encoding the mail session value.

50               If the Full Screen mode is on, returns TRUE; otherwise, FALSE.

51               If the formula bar is displayed in Full Screen mode, returns

TRUE; otherwise, FALSE.

52               If the status bar is displayed in Full Screen mode, returns TRUE; otherwise, FALSE.

53               The name of the topmost custom dialog sheet currently running

in a modal window, or #N/A if no dialog sheet is currently running.

54               If the Edit Directly In Cell check box is selected on the Edit tab in the Options dialog box, returns TRUE; otherwise, returns FALSE.

55               TRUE if the Alert Before Overwriting Cells check box in the Edit

tab on Options dialog box is selected; otherwise, FALSE.

56               Standard font name in the General tab in the Options dialog

box, as text.

57               Standard font size in the General tab in the Options dialog box, as a number

58               If the Recently Used File list check box in the General tab on the

Options dialog box is selected, returns TRUE; otherwise, FALSE.

59               If the Display Old Menus check box in the General tab on the

Options dialog box is selected, returns TRUE; otherwise, FALSE.

60               If the Tip Wizard is enabled, returns TRUE; otherwise, FALSE.

61               Number of custom list entries listed in the Custom Lists tab of

the Options dialog box.

62               Returns information about available file converters.

63               Returns the type of mail system in use by Excel:

0  = No mail transport detected

1  = MAPI based transport

2  = PowerTalk based transport (Macintosh only)

64               If the Ask To Update Automatic Links check box in the Edit tab

of the Options dialog box is selected, returns TRUE; otherwise, FALSE.

65               If the Cut, Copy, And Sort Objects With Cells check box in the

Edit tab on the Options dialog box is selected, returns TRUE; otherwise, FALSE.

66               Default number of sheets in a new workbook, as a number,

from the General tab on Options dialog box.

67               Default file directory location, as text, from the General tab in

the Options dialog box.

68               If the Show ScreenTips On Toolbars check box in the Options

tab in the Customize dialog box is selected, returns TRUE; otherwise, FALSE.

69               If the Large Icons check box in the Options tab in the Customize

dialog box is selected, returns TRUE; otherwise, FALSE.

70               If the Prompt For Workbook Properties check box in the General

tab on the Options dialog box is selected, returns TRUE; otherwise, FALSE.

71               TRUE if Microsoft Excel is open for in-place object editing (OLE).

If FALSE, it is opened normally.

72               TRUE if the Color Toolbars check box is selected in the Toolbars dialog box. FALSE if the Color Toolbars check box is not selected. This argument is for compatibility with Microsoft Excel version 5.0.

Related Functions

GET.DOCUMENT   Returns information about a workbook

GET.WINDOW   Returns information about a window

Equivalent to clicking the Goal Seek command on the Tools menu. Calculates the values necessary to achieve a specific goal. If the goal is an amount returned by a formula, the function calculates values that, when supplied to your formula, cause your formula to return the amount you want.

Syntax

(target_cell, target_value, variable_cell)

?(target_cell, target_value, variable_cell)

Target_cell    corresponds to the Set Cell box in the Goal Seek dialog box and is a reference to the cell containing the formula. If target_cell does not contain a formula, Microsoft Excel displays an error message.

Target_value    corresponds to the To Value box in the Goal Seek dialog box and is the value you want the formula in target_cell to return. This value is called a goal.

Variable_cell    corresponds to the By Changing Cell box in the Goal Seek dialog box and is the single cell that you want Microsoft Excel to change so that the formula in target_cell returns target_value. Target_cell must depend on variable_cell; if it does not, Microsoft Excel will not be able to find a solution.

Remarks

The max_num and max_change values set with the CALCULATION function can be used to change the solution process. Max_num sets the number of iterations; max_change determines the precision of the solution.

Tip   You can also use Microsoft Excel Solver to help solve your math equations for optimal values.

Related Functions

Related functions include the SOLVER functions, such as SOLVER.OPTIONS, SOLVER.SOLVE, and so on.

GOTO

Directs a macro to continue running at the upper-left cell of reference. Use GOTO to direct macro execution to another cell or a named range.

Syntax

GOTO(reference)

Reference    is a cell reference or a name that is defined as a reference. Reference can be an external reference to another macro sheet. If that macro sheet is not open, GOTO displays a message.

Tip   It's often preferable to use IF, ELSE, , and instead of GOTO when you want to perform multiple actions based on a condition because the IF method makes your macros more structured.

Examples

If A1 contains the #N/A error value, then when the following formula is calculated, the macro branches to C3:

IF(ISERROR($A$1), GOTO($C$3))

You can also use macro names with GOTO statements. The following macro formula branches macro execution to a macro named Compile:

GOTO(Compile)

Because Compile is a named range, it should not be enclosed in quotation marks.

Related Function

   Selects a named area or reference on any open workbook

GRIDLINES

Allows you to turn chart gridlines on and off.

Arguments are logical values corresponding to the check boxes in the Gridlines dialog box. If an argument is TRUE, Microsoft Excel selects the check box; if FALSE, Microsoft Excel clears the check box. If omitted, the setting is not changed. If a chart is not active, produces a error and halts the macro.

Syntax

GRIDLINES(x_major, x_minor, y_major, y_minor, z_major, z_minor, 2D_effect) GRIDLINES?(x_major, x_minor, y_major, y_minor, z_major, z_minor, 2D_effect)

X_major    corresponds to the Category (X) Axis: Major Gridlines check box.

X_minor    corresponds to the Category (X) Axis: Minor Gridlines check box.

Y_major    corresponds to the Value (Y) Axis: Major Gridlines check box. On 3-D charts, y_major corresponds to the Series (Y) Axis: Major Gridlines check box.

Y_minor    corresponds to the Value (Y) Axis: Minor Gridlines check box. On 3-D charts, y_minor corresponds to the Series (Y) Axis: Minor Gridlines check box.

Z_major    corresponds to the Value (Z) Axis: Major Gridlines check box (3-D only).

Z_minor    corresponds to the Value (Z) Axis: Minor Gridlines check box (3-D only).

2D_effect    corresponds to the 2-D Walls and Gridlines check box (3-D only).

GROUP

Creates a single object from several selected objects and returns the object identifier of the group (for example, "Group 5"). Use GROUP to combine a number of objects so that you can move or resize them together.

If no object is selected, only one object is selected, or a group is already selected, GROUP returns the #VALUE! error value and interrupts the macro.

Syntax

GROUP( )

Related Function

UNGROUP   Separates a grouped object

HALT

Stops all macros from running. Use HALT instead of RETURN to prevent a macro from returning to the macro that called it.

Syntax

HALT(cancel_close)

Cancel_close    is a logical value that specifies whether a macro sheet, when encountering the HALT function in an Auto_Close macro, is closed. 

•   If cancel_close is TRUE, Microsoft Excel halts the macro and prevents the workbook from being closed.

•   If cancel_close is FALSE or omitted, Microsoft Excel halts the macro and allows the workbook to be closed.

•   If cancel_close is specified in a macro that is not an Auto_Close macro, it is ignored and the HALT function simply stops the current macro. 

Remarks

You can prevent an Auto_Close or Auto_Open macro from running by holding down the SHIFT key while opening or closing the workbook.

Examples

If A1 contains the #N/A error value, then when the following macro formula is calculated, the macro halts:

IF(ISERROR(A1), HALT(), GOTO(D4))

The following macro formula at the end of an Auto_Close macro ends the macro and prevents the workbook from being closed:

HALT(TRUE)

Related Functions

BREAK   Interrupts a FOR-NEXT, -NEXT, or WHILE-NEXT loop

RETURN   Ends the currently running macro

HELP

Starts or switches to Help and displays the specified custom Help topic. Use HELP with custom Help files to create your own Help system, which can be used just like the built-in Microsoft Excel Help.

Syntax

HELP(help_ref)

Help_ref    is a reference to a topic in a Help file, in the form "filename!topic_number". 

•   Help_ref must be given as text. 

Remarks 

•   Microsoft Excel for Windows does not support the use of Help files in the text file format for custom Help.

•   In Microsoft Excel for the Macintosh, custom Help files are plain text files or text files with line breaks. 

Tips 

•   In Microsoft Excel for Windows, the following macro formula switches back to Microsoft Excel when Help is active:

APP.ACTIVATE()

•   The following macro formula closes Help when Help is active:

("%{F4}")

Examples

In Microsoft Excel for Windows, the following macro formula displays the Help topic numbered 101 in the file . The Help window remains open if the user switches to another window or application.

HELP("!101")

If the custom Help file is not in the current directory, specify the full path along with the name of the file. For example:

HELP("C:\EXCEL\!101")

In Microsoft Excel for the Macintosh, the following macro formula displays the Help topic numbered 101 in the file CUSTOM HELP:

HELP("CUSTOM HELP!101")

If the custom Help file is not in the current folder, specify the full path along with the name of the file. For example:

HELP("HARD DISK:EXCEL:HELP:CUSTOM HELP!101")

HIDE

Equivalent to clicking the Hide command on the Window menu. Hides the active window.

Syntax

HIDE( )

Tip   Hiding windows can speed up your macros. You can switch to hidden windows with the ACTIVATE function. You can continue to use functions that refer to specific sheets, such as FORMULA and the GET functions, even when those sheets are hidden.

Related Function

UNHIDE   Displays a hidden window

HIDE.DIALOG

Closes the dialog box that has the current focus.

Syntax

HIDE.DIALOG(cancel_logical)

Cancel_logical    is a logical value that specifies whether to close the dialog box and validate any edit boxes. If FALSE, the dialog box is closed and edit boxes are validated, or checked to determine if they contain a valid data type. If TRUE, the dialog box is closed and the edit boxes are not validated.

Remarks

If the edit box does not contain a valid data type when the dialog box is closed, the dialog will remain open. For example, if the edit box is supposed to contain integer values, and a text value is entered, the dialog box will not close. This applies to only those dialog boxes that must be closed before any further user action can happen.

Examples

HIDE.DIALOG(FALSE) closes the dialog box and checks to see if the edit box contains a valid data type (validated)

Related Functions

EDITBOX.PROPERTIES Sets the properties of an edit box on a worksheet or dialog sheet SHOW.DIALOG Runs a dialog on a dialog sheet

HIDE.OBJECT

Hides or displays the specified object.

Syntax

HIDE.OBJECT(object_id_text, hide)

Object_id_text    is the name and number, or number alone, of the object, as text, as it appears in the reference area when the object is selected. The name of the object is also the text returned by the CREATE.OBJECT function, so object_id_text can be a reference to a cell containing CREATE.OBJECT. To give the name of more than one object, use the following format for object_id_text:

"oval 3, text 2, arc 5"

If object_id_text is omitted, the function operates on all selected objects. If no object is selected or if the object specified by object_id_text does not exist, HIDE.OBJECT returns the #VALUE! error value.

Hide    is a logical value that specifies whether to hide or display the specified object. If hide is TRUE or omitted, Microsoft Excel hides the object; if FALSE, Microsoft Excel displays the object.

Remarks

Objects are not automatically selected after they are unhidden.

Examples

The following macro formula hides the selected object:

HIDE.OBJECT(, TRUE)

The following macro formula displays the object named Oval 3:

HIDE.OBJECT("Oval 3", FALSE)

The following macro formula displays the three specified objects:

HIDE.OBJECT("oval 3, text 2, arc 5", FALSE)

Related Functions

CREATE.OBJECT   Creates an object

DISPLAY   Controls how an object is displayed

HISTOGRAM

Calculates individual and cumulative percentages for a range of data and a corresponding range of data bins.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

HISTOGRAM(inprng, outrng, binrng, pareto, chartc, chart, labels) HISTOGRAM?(inprng, outrng, binrng, pareto, chartc, chart, labels)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Binrng    is an optional set of numbers that define the bin ranges. The values must be in ascending order. The values are interpreted as more than value A up to value B, more

than value B up to value C, and so on. One additional bin is created for values for less than the minimum value specified in binrng.

Pareto    is a logical value. 

•   If pareto is TRUE, data in the output table is presented in both ascending-bin order and descending-frequency order.

•   If pareto is FALSE or omitted, data in the output table is presented in ascendingbin order only. 

Chartc    is a logical value. If chartc is TRUE, HISTOGRAM generates a cumulative percentages column in the output table. If both chartc and chart are TRUE, HISTOGRAM also includes a cumulative percentage line in the histogram chart. If omitted, chartc is FALSE.

Chart    is a logical value. If chart is TRUE, HISTOGRAM generates a histogram chart in addition to the output table. If omitted, chart is FALSE.

Labels    is a logical value. 

•   If labels is TRUE, then the first row or column of inprng contains labels.

•   If labels is FALSE or omitted, all cells in inprng are considered data. Microsoft Excel generates appropriate data labels for the output table.

HLINE

Scrolls through the active window by a specific number of columns. Returns the #VALUE! error value if the active sheet is a chart.

Syntax

HLINE(num_columns)

Num_columns    is the number of columns in the active worksheet or macro sheet you want to scroll through horizontally. 

•   If num_columns is positive, HLINE scrolls to the right.

•   If num_columns is negative, HLINE scrolls to the left.

•   Num_columns must be between -256 and 256, inclusive. 

Example

The following function scrolls the active window by one-half window to the right:

HLINE(GET.WINDOW(15)/2)

Related Functions

HPAGE   Horizontally scrolls through the active window one window at a time

HSCROLL   Horizontally scrolls through a sheet by percentage or by column number

VLINE   Vertically scrolls through the active window by rows

VPAGE   Vertically scrolls through the active window one window at a time

VSCROLL   Vertically scrolls through a sheet by percentage or by row number

HPAGE

Horizontally scrolls through the active window one window at a time. Use HPAGE to change the displayed area of a worksheet or macro sheet.

Syntax

HPAGE(num_windows)

Num_windows    specifies the number of windows to scroll through the active window horizontally. A window is defined as the number of visible columns. If three columns are visible in the window, HPAGE scrolls through in increments of three columns. 

•   If num_windows is positive, HPAGE scrolls to the right.

•   If num_windows is negative, HPAGE scrolls to the left. 

Related Functions

HLINE   Horizontally scrolls through the active window by columns

HSCROLL   Horizontally scrolls through a worksheet by percentage or by column number

VLINE   Vertically scrolls through the active window by rows

VPAGE   Vertically scrolls through the active window one window at a time

VSCROLL   Vertically scrolls through a worksheet by percentage or by row number

HSCROLL

Horizontally scrolls through the active sheet by percentage or by column number.

Syntax

HSCROLL(position, col_logical)

Position    specifies the column you want to scroll to. Position can be an integer representing the column number or a fraction or percentage representing the horizontal position of the column in the sheet. If position is 0, HSCROLL scrolls through your sheet to its leftmost edge. If position is 1, HSCROLL scrolls through your sheet to its rightmost edge. For charts that do not size with the window, use a fraction or percentage.

Col_logical    is a logical value specifying how the function scrolls. 

•   If col_logical is TRUE, HSCROLL scrolls through the sheet to column position.

•   If col_logical is FALSE or omitted, then HSCROLL scrolls through the sheet to the horizontal position represented by the fraction position. 

Remarks 

•   To scroll to a specific column n, either use HSCROLL(n, TRUE) or use

HSCROLL(n/256). To scroll to column 38, for example, use HSCROLL(38, TRUE) or HSCROLL(38/256).

•   If you are recording a macro and move the scroll box several times in a row, the recorder only records the final location of the scroll box, omitting any intermediate steps. Remember that scrolling does not change the active cell or the selection. 

Related Functions

HLINE   Horizontally scrolls through the active window by columns

HPAGE   Horizontally scrolls through the active window one window at a time

VLINE   Vertically scrolls through the active window by rows

VPAGE   Vertically scrolls through the active window one window at a time

VSCROLL   Vertically scrolls through a sheet by percentage or row number

IF

Used with ELSE, , and to control which formulas in a macro are executed. There are two syntax forms of the IF function. The following syntax can be used on macro sheets only; use it when you want your macro to branch to a particular set of functions based on the outcome of a logical test. The worksheet form of this function can be used on worksheets and macro sheets. Syntax

IF(logical_test)

Logical_test    is a logical value that IF uses to determine which functions to carry out next— that is, where to branch. 

•   If logical_test is TRUE, Microsoft Excel carries out the functions between the IF function and the next ELSE, , or function. Instructions between or ELSE and are not carried out.

•   If logical_test is FALSE, Microsoft Excel immediately branches to the next , ELSE, or function.

•   If logical_test produces an error, the macro halts.

TIPS

•    Use IF with ELSE, , and when you want to perform multiple actions based on a condition. This method is preferable to using GOTO because it makes your macros more structured.

•    If your macro ends with an error at a cell containing this form of the IF function, make sure there is a corresponding function.

Example

The following macro runs the macro CompleteEntry if the user clicks OK:

IF(ALERT("Are you done with this entry?", 1), CompleteEntry(), )

Tip   You can indent formulas in a macro. To indent a formula, type as many spaces as you want between the equal sign and the first letter of the formula.

Related Functions

ELSE   Specifies an action to take if an IF function returns FALSE

   Specifies an action to take if an IF or another function returns FALSE

   Ends a group of macro functions started with an IF statement

ERROR   Specifies what action to take if an error occurs while a macro is running

INITIATE

Opens a dynamic data exchange (DDE) channel to an application and returns the number of the open channel. Once you have opened a channel to another application with INITIATE, you can use EXECUTE and to control the other application from a Microsoft Excel macro. ( is available only with Microsoft Excel for Windows.) If INITIATE is successful, it returns the number of the open channel. All the subsequent DDE macro functions use this number to specify the channel. If INITIATE is unsuccessful, FALSE is returned.

Important   Microsoft Excel for the Macintosh requires system software version 7.0 or later for this function.

Syntax

INITIATE(app_text, topic_text)

App_text    is the DDE name of the application with which you want to begin a DDE session, in text form. The form of app_text depends on the application you are accessing. The DDE name of Microsoft Excel, for example, is "Excel".

Topic_text    describes something, such as a document or a record in a database, in the application that you are accessing; the form of topic_text depends on the application you are accessing. Microsoft Excel accepts the names of the current documents as topic_text, as well as the name "System".

Remarks 

•    You can specify an instance of an application by appending the application's task ID number to the app_text argument. If you start an application by using the EXEC function, EXEC returns the task ID number for that instance of the application.

•    If more than one instance of an application is running and you do not specify which instance you would like to open a channel to, INITIATE displays a dialog box from which you can choose the instance you want. You can prevent this dialog box from appearing by disabling or redirecting errors with the ERROR function. 

Example

The following macro formula opens a channel to the document named MEMO in the application named WORD:

INITIATE("WORD", "MEMO")

Related Functions

POKE   Sends data to another application

REQUEST   Returns data from another application

TERMINATE   Closes a channel to another application

EXECUTE   Carries out a command in another application

EXEC   Starts a separate program

INPUT

Displays a dialog box for user input. Returns the information entered in the dialog box. Use INPUT to display a simple dialog box for the user to enter information to be used in a macro.

The dialog box has an OK and a Cancel button. If you click the OK button, INPUT returns the default value specified or the value typed in the edit box. If you click the Cancel button, INPUT returns FALSE.

Syntax

INPUT(message_text, type_num, title_text, default, x_pos, y_pos, help_ref)

Message_text    is the text to be displayed in the dialog box. Message_text must be enclosed in quotation marks.

Type_num    is a number specifying the type of data to be entered.

Type_num

 

Data type

0        Formula

1        Number

2        Text

4                    Logical

8                   Reference

16                  Error

64                  Array

You can also use the sum of the allowable data types for type_num. For example, for an input box that can accept formulas, text, or numbers, set type_num equal to 3 (the sum of 0, 1, and 2, which are the type specifiers for formula, number, and text). If type_num is omitted, it is assumed to be 2. 

•   If type_num is 0, INPUT returns the formula in the form of text, for example, "=2*PI()/360".

•   To enter a formula, include an equal sign at the beginning of the formula; otherwise the formula is returned as text.

•   If the formula contains references, they are returned as R1C1-style references, for example, "=RC[-1]*(1+R1C1)".

•   If type_num is 8, INPUT returns an absolute reference to the specified cells.

•   If you enter a single-cell reference in the dialog box, the value in that cell is returned by the INPUT function.

•   If the information entered in the dialog box is not of the correct data type, Microsoft Excel attempts to convert it to the specified type. If the information can't be converted, Microsoft Excel displays an error message. 

Title_text    is text specifying a title to be displayed in the title bar of the dialog box. If title_text is omitted, it is assumed to be "Input".

Default    specifies a value to be shown in the edit box when the dialog box is initially displayed. If default is omitted, the edit box is left empty.

X_pos, y_pos    specify the horizontal and vertical position, in points, of the dialog box. A point is 1/72nd of an inch. If either or both arguments are omitted, the dialog box is centered in the corresponding direction.

Help_ref    is a reference to a custom online Help topic in a text file, in the form "filename!topic_number". 

•   If help_ref is present, a Help button appears in the lower-right corner of the dialog box. Clicking the Help button starts Help and displays the specified topic.

•   If help_ref is omitted, no Help button appears.

•   Help_ref must be given as text. 

For more information about custom Help topics, see HELP.

Remarks

Relative references entered in formulas in the INPUT dialog box are relative to the active cell at the time the INPUT function is calculated. If you are using the reference entered into the dialog box in a cell other than the active cell, it may not refer to the cells you intend it to. For example, if the active cell is A3 and you enter the formula "=A1+A2" in an INPUT dialog box, intending to add the values in those cells, and then use the FORMULA function to enter the formula in cell B3, the formula in cell B3 will read "=B1+B2" because you gave a relative reference. You can use FORMULA.CONVERT to solve this problem.

Examples

In Microsoft Excel for Windows, the following macro formula displays the following dialog box:

INPUT("Enter the inflation rate:", 1, "Inflation Rate", , , , "!101")

If you then enter 12%, INPUT returns the value 0.12.

In Microsoft Excel for the Macintosh, the following macro formula displays the following dialog box:

INPUT("Enter the inflation rate:", 1, "Inflation Rate", , , , "CUSTOM HELP!101")

If you then enter 12%, INPUT returns the value 0.12.

If the active cell is C2 and you enter the formula =B2*(1+$A$1) in response to the following macro formula:

INPUT("Enter your monthly increase formula:", 0)

INPUT returns "=RC[-1]*(1+R1C1)"

If you select the range $A$2:$A$8 in the INPUT dialog box:

REFTEXT|USA|002|001|001|common|UREFTEXT(INPUT("Please make your selection.", 8)) returns R2C1:R8C1

Related Functions

ALERT   Displays a dialog box and a message

   Displays a custom dialog box

FORMULA.CONVERT Changes the style and type of references in a formula HELP   Displays a custom Help topic

INSERT

Inserts a blank cell or range of cells or pastes cells from the Clipboard into a sheet. Shifts the selected cells to accommodate the new ones. The size and shape of the inserted range are the same as those of the current selection.

Syntax

INSERT(shift_num)

INSERT?(shift_num)

Shift_num    is a number from 1 to 4 specifying which way to shift the cells. If an entire row or column is selected, shift_num is ignored. If shift_num is omitted, Microsoft Excel shifts cells in the logical direction based on the selection.

Shift_num

 

Direction

1        Shift cells right

2        Shift cells down

3        Shift entire row

4        Shift entire column

Remarks

If you have just cut or copied information to the Clipboard, INSERT performs both an insert and a paste operation. First, Microsoft Excel inserts new blank cells into the sheet; then, Microsoft Excel pastes information from the Clipboard into the newly inserted cells. If you have used the INSERT function in macros written for Microsoft Excel version 2.2 or earlier, make sure you consider this feature when you use your old macros with later versions of Microsoft Excel.

Related Functions

COPY   Copies and pastes data or objects

CUT   Cuts or moves data or objects

EDIT.DELETE   Removes cells from a sheet

PASTE   Pastes cut or copied data

INSERT.OBJECT

Equivalent to choosing the Object command from the Insert menu, and then selecting an object type and choosing the OK button. Creates an embedded object whose source data is supplied by another application. Also starts an application of the appropriate class for the specified object type.

Syntax

INSERT.OBJECT(object_class, file_name, link_logical, display_icon_logical, icon_file, icon_number, icon_label)

INSERT.OBJECT?(object_class, file_name, link_logical, display_icon_logical, icon_file, icon_number, icon_label)

Object_class    is a text string containing the classname for the object you want to create. 

•   Object_class is the classname corresponding to the Object Type selection in the Insert Object dialog box.

•   For more information about object classnames, consult the documentation for your source application to see how it supports object linking and embedding (OLE). 

File_name    is a text string specifying the file from which to create an OLE object.

Link_logical    is a logical value indicating whether the new object based on file_name should be linked to file_name. If it is not linked, the object is created as a copy or the file. Link_logical is ignored if file_name is not specified. If link_logical is FALSE or omitted, then no link is established.

Display_icon_logical    is a logical value corresponding to the Display as Icon checkbox. If it is FALSE or omitted, then the regular picture for the object is displayed. If it is TRUE, then the icon icon_number found in icon_file is displayed with the label icon_label. If display_icon_logical is not TRUE, then icon_file, icon_number, and icon_label are ignored.

Icon_file    is the name of the file where the icon to display is located.

Icon_number    is the number of the icon within icon_file that should be used.

Icon_label    is a text string indicating a label to display beneath the icon. If the parameter is an empty string ("") or is omitted, no label is displayed.

Remarks 

•    If INSERT.OBJECT starts another application, your macro pauses. Your macro resumes when you return to Microsoft Excel.

•    Although you will not normally use Microsoft Excel class names in a Microsoft Excel macro, you may need them in macros written for other applications. Microsoft Excel uses classnames "Excel.Sheet.5" and "Excel.Chart.5". 

Related Function

EDIT.OBJECT   Edits an object

INSERT.PICTURE

Equivalent to clicking the Picture command on the Insert menu. This function is available for Microsoft Excel for Windows only .

Syntax

INSERT.PICTURE(file_name, filter_number)

INSERT.PICTURE?(file_name, filter_number)

File_name    is the name, as text, of the file containing the picture that you want to insert into your workbook.

Filter_number    is a number specifying which converter Microsoft Excel will use to open the file.

Convert_type

 

Converter and filename extension

1          Windows Bitmaps (bmp)

2          Windows Metafile (wmf)

3          DrawPerfect (wpg)

4          Micrografix Designer/Draw (drw)

5          AutoCAD Format 2-D (dxf)

6          HP Graphics Language (hgl)

7          Computer Graphics Metafile (cgm)

8          Encapsulated Postscript (eps)

9          Tagged Image Format (tif)

10          PC PaintBrush (pcx)

11          Lotus 1-2-3 Graphic (pic)

12          AutoCAD Plot Files (plt)

13          Macintosh PICT (pct)

INSERT.TITLE

Attaches text to various parts of a chart.

Syntax

2-D charts

INSERT.TITLE(chart, y_primary, x_primary, y_secondary, x_secondary)

3-D charts

INSERT.TITLE(chart, z_primary, x_primary, y_primary)

Chart    is a logical value specifying whether to attach a title to the chart.

Y_primary    is a logical value specifying whether to attach a title to the value (y) axis of a 2-D chart or the series (y) axis of a 3-D chart.

X_primary    is a logical value specifying whether to attach a title to the category (x) axis of the chart.

Z_primary    is a logical value specifying whether to attach a title to the value (z) axis of a 3-D chart.

Y_secondary    is a logical value specifying whether to attach a title to the second value (y) axis of a chart containing more than one chart type.

X_secondary    is a logical value specifying whether to attach a title to the second category (x) axis of a chart containing more than one chart type.

Remarks

To change the text in a selected title, use the FORMULA function.

Related Function

FORMULA   Enters formulas in a chart

JUSTIFY

Equivalent to clicking the Justify command on the Fill submenu of the Edit menu. Rearranges the text in a range so that it fills the range evenly.

Syntax

JUSTIFY()

Related Function

ALIGNMENT   Aligns the contents of the selected cells

LABEL.PROPERTIES

Sets the accelerator property of the label and group box controls on a worksheet or dialog sheet.

Syntax

LABEL.PROPERTIES(accel_text, accel_text2, 3d_shading)

LABEL.PROPERTIES?(accel_text, accel_text2, 3d_shading)

Accel_text    is a text string containing the character to use as the label's accelerator key on a dialog sheet. The character is matched against the text of the control, and the first matching character is underlined. When the user presses ALT+accel_text in Microsoft Excel for Windows or COMMAND+accel_text in Microsoft Excel for the Macintosh, the control is clicked. This argument is ignored for controls on worksheets.

Accel_text2    is a text string containing the second accelerator key on a dialog sheet. This argument is for only Far East versions of Microsoft Excel.

3d_shading    is a logical value that specifies whether the list box appears as 3-D. If TRUE, the list box will appear as 3-D. If FALSE or omitted, the list box will not be 3-D. This argument is available for only worksheets.

Related Functions

CHECKBOX.PROPERTIES   Sets various properties of check box and option box controls

SCROLLBAR.PROPERTIES   Sets the properties of the scroll bar and spinner controls

PUSHBUTTON.PROPERTIES   Sets the properties of the push button control

LAST.ERROR

Returns the reference to the cell where the last macro sheet error occurred. If no error has occurred, LAST.ERROR returns the #N/A error value. Use LAST.ERROR in conjunction with the REFTEXT function to quickly locate errors.

Syntax

LAST.ERROR( )

Related Function

ERROR   Specifies what action to take if an error is encountered while a macro is running

LEGEND

Adds a legend to or removes a legend from a chart. This is also equivalent to clicking the Legend button on the Chart toolbar when a chart is active.

Syntax

LEGEND(logical)

Logical    is a logical value specifying which command LEGEND is equivalent to.  

•   If logical is TRUE or omitted, LEGEND is equivalent to the Legend command on the Insert menu.

•   If logical is FALSE, LEGEND is equivalent to the Delete command on the Edit menu.

•   If logical is FALSE and the active chart has no legend, LEGEND takes no action. 

Related Function

FORMAT.LEGEND   Determines the position and orientation of the legend on a chart

LINE.PRINT

Prints the active worksheet using methods compatible with those of Lotus 1-2-3. LINE.PRINT does not use the Microsoft Windows printer drivers. Unless you have a specific need for the LINE.PRINT function, use the PRINT function instead.

Note   This function is only available in Microsoft Excel for Windows.

Syntax 1

Go, Line, Page, Align, and Clear

LINE.PRINT(command, file, append)

Syntax 2

Worksheet settings

LINE.PRINT(command, setup_text, leftmarg, rightmarg, topmarg, botmarg, pglen, formatted) Syntax 3

Global settings

LINE.PRINT(command, setup_text, leftmarg, rightmarg, topmarg, botmarg, pglen, wait, autolf, port, update)

Command    is a number corresponding to the command you want LINE.PRINT to carry out. For syntax 2, command must be 5. For syntax 3, command must be 6.

Command

 

Command that is carried out

1          Go

2          Line

3          Page

4          Align

5          Worksheet settings

6          Global settings (saved in )

7          Clear (change to current global settings)

File    is the name of a file to which you want to print. If omitted, Microsoft Excel prints to the printer port determined by the current global settings.

Append    is a logical value specifying whether to append text to file. If TRUE, the file you are printing is appended to file; if FALSE or omitted, the file you are printing overwrites the contents of file.

Setup_text    is text that includes a printer initialization sequence or other control codes to prepare your printer for printing. If omitted, no setup text is used.

Leftmarg    is the size of the left margin measured in characters from the left side of the page. If omitted, it is assumed to be 4.

Rightmarg    is the size of the right margin measured in characters from the left side of the page. If omitted, it is assumed to be 76.

Topmarg    is the size of the top margin measured in lines from the top of the page. If omitted, it is assumed to be 2.

Botmarg    is the size of the bottom margin measured in lines from the bottom of the page. If omitted, it is assumed to be 2.

Pglen    is the number of lines on one page. If omitted, it is assumed to be 66 (11 inches with 6 lines per inch). If you're using an HP LaserJet or compatible printer, set pglen to 60 (the printer reserves six lines).

Formatted    is a logical value specifying whether to format the output. If TRUE or omitted, the output is formatted; if FALSE, it is not formatted.

Wait    is a logical value specifying whether to wait after printing a page. If TRUE, Microsoft Excel waits; if FALSE or omitted, Microsoft Excel continues printing.

Autolf    is a logical value specifying whether your printer has automatic line feeding. If TRUE, Microsoft Excel prints lines normally; if FALSE or omitted, Microsoft Excel sends an additional line feed character after printing each line.

Port    is a number from 1 to 8 specifying which port to use when printing.

Port

 

Port used when printing

1          or omitted LPT1

2          COM1

3          LPT2

4          COM2

5          LPT1

6          LPT2

7          LPT3

8          LPT4

Update    is a logical value specifying whether to update and save global settings. If TRUE, the settings are saved in the file; if FALSE or omitted, the global settings are not saved.

Remarks

The default values for print settings on your worksheet are determined by the current global settings.

Example

The following macro formula prints the currently defined print area to the currently defined printer port:

LINE.PRINT(1)

Related Function

PRINT   Prints the active sheet

LINK.COMBO

Links an edit box and a list box control into a linked combination box group. The resulting linked controls track each other's selection and contents. Linked edit and list box combinations are similar to an editable drop-down list box, except that the list box is permanently visible and dropped down.

Syntax

LINK.COMBO(link_logical)

Link_logical    is a logical value that specifies whether the controls are linked or unlinked. If TRUE, the controls will become linked. If FALSE, the controls will be unlinked.

Remarks

To use this function, first select the list box and edit box to be linked or unlinked. You can do this with SELECT("list box 1,Edit box 2").

Examples

LINK.COMBO(FALSE) will unlink a list box and an edit box.

Related Functions

   Adds an item in a list box or drop-down control on a worksheet or dialog sheet control

   Selects an item in a list box or in a group box

LINK.FORMAT

Links the number format of the selected data label to the worksheet cell or range containing the data label text.

Syntax

LINK.FORMAT( )

LINKS

Returns, as a horizontal array of text values, the names of all workbooks referred to by external references in the workbook specified. Use LINKS with OPEN.LINKS to open supporting workbooks.

Syntax

LINKS(document_text, type_num)

Document_text    is the name of a workbook, including its path. If document_text is omitted, LINKS operates on the active workbook. If the workbook specified by document_text is not open, LINKS returns the #N/A error value.

Type_num    is a number from 1 to 6 specifying the type of linked workbooks to return.

 

Type_num

 

Returns

1          or omitted Microsoft Excel link

2          DDE/OLE link (Microsoft Excel for Windows)

3          Reserved

4          Not applicable

5          Publisher (Microsoft Excel for the Macintosh)

6          Subscriber (Microsoft Excel for the Macintosh)

Remarks 

•    If the active workbook contains no external references, LINKS returns the #N/A error value.

•    With the INDEX function, you can select individual workbook names from the array for use in other functions that take workbook names as arguments.

•    The names of the workbook are always returned in alphabetic order. If supporting workbooks are open, LINKS returns the names of the workbooks; if supporting workbooks are closed, LINKS includes the full path of each workbook.

•    If type_num is 5 or 6, LINKS returns a two-row array in which the first row contains the edition name and the second row contains the reference.

Examples

If a chart named Chart1 is open and contains links to workbook Data1 and Data2, and the LINKS function shown below is entered as an array into a two-cell horizontal range:

LINKS("Chart1") equals "Data1" in the first cell of the range and "Data2" in the second cell.

In Microsoft Excel for Windows, if the chart named is open and contains data series that refer to workbook named and , then:

OPEN.LINKS(LINKS("")) opens and .

In Microsoft Excel for the Macintosh, if the workbook named SALES 1991 is open and contains references to the workbook WEST SALES, SOUTH SALES, and EAST SALES, then:

OPEN.LINKS(LINKS("SALES 1991")) opens WEST SALES, SOUTH SALES, and EAST SALES.

Related Functions

   Changes supporting workbook links

   Returns information about a link

OPEN.LINKS   Opens specified supporting workbook

   Updates a link to another workbook

LISTBOX.PROPERTIES

Sets the properties of a list box and drop-down controls on a worksheet or dialog sheet.

Syntax

LISTBOX.PROPERTIES(range, link, drop_size, multi_select, 3d_shading)

LISTBOX.PROPERTIES?(range, link, drop_size, multi_select, 3d_shading)

Range    is the cell range that the initial contents of the list box are taken from. If blank (empty text), the list box is initially unfilled.

Link    is the cell on the sheet to which the list box is linked, and indicates the numeric position of the currently selected item in the list box. Whenever an item in the list box is selected, its numeric position is entered into the linked cell on the sheet.

Drop_size    is the number of lines shown when a drop-down control is dropped. This value is ignored when applied to a non-drop-down list box.

Multi_select    is a number that specifies the selection mode of the list box. Zero is single selection. 1 is simple multi-select. 2 is extended multi-select.

3d_shading    is a logical value that specifies whether the list box appears as 3-D. If TRUE, the list box will appear as 3-D. If FALSE or omitted, the list box will not be 3-D. This argument is available for only worksheets.

Related Functions

   Adds an item in a list box or drop-down control on a worksheet or dialog sheet control

   Selects an item in a list box or in a group box

CHECKBOX.PROPERTIES   Sets various properties of check box and option box controls

SCROLLBAR.PROPERTIES   Sets the properties of the scroll bar and spinner controls

PUSHBUTTON.PROPERTIES   Sets the properties of the push button control

LIST.NAMES

Equivalent to clicking the Paste command on the Name submenu of the Insert menu and selecting the Paste List option button. Lists all names (except hidden names) defined in your workbook. LIST.NAMES also lists the cells to which the names refer; whether a macro corresponding to a particular name is a command macro or a custom function; the shortcut key for each command macro; and the category of the custom functions.

Syntax

LIST.NAMES( )

Remarks 

•    If the current selection is a single cell or five or more columns wide, LIST.NAMES pastes all five types of information about worksheet names into five columns. The first column contains cell names. The second column contains the corresponding cell references. The third column contains the number 1 if the name refers to a custom function, the number 2 if it refers to a command macro, or 0 if it refers to anything else. The fourth column lists the shortcut keys for command macros. The fifth column contains a category name for custom functions or the number of the built-in category.

•    If the selection includes fewer than five columns, LIST.NAMES omits the information that would have been pasted into the other columns.

•    When you use LIST.NAMES, Microsoft Excel completely replaces the contents of the cells it pastes into. 

Related Functions

   Returns a name matching a definition

   Returns the definition of a name

NAMES   Returns the names defined in a workbook

MACRO.OPTIONS

Equivalent to clicking the Options button in the Macro dialog box, which appears when you click the Macros command (Tools menu, Macro submenu).

Syntax

MACRO.OPTIONS(macro_name, description, menu_on, menu_text, shortcut_on, shortcut_key, function_category, status_bar_text, help_id, help_file)

Macro_name    is the name of the macro that you want to set options for, including the name of the workbook and sheet containing the macro.

Description    is the description of the macro displayed in the Macro dialog box.

Menu_on    is a logical value indicating whether a menu item is automatically added for this macro. If TRUE, menu_text must be specified. If FALSE or omitted, no menu item is added. If the macro already has a menu item, setting this argument to FALSE removes the menu item.

Menu_text    is the text of the menu item to be added for the macro. Ignored unless menu_on is TRUE.

Shortcut_on    is a logical value indicating whether a shortcut key is assigned to the macro. If TRUE, shortcut_key must be specified. If FALSE or omitted, no shortcut key is assigned. If the macro already has a shortcut key, setting this argument to FALSE removes the shortcut key.

Shortcut_key    is the letter of the shortcut key for the macro. Ignored if shortcut_key is FALSE.

Function_category    is the number of the category in the Paste Function dialog box that the macro is assigned to. Categories are numbered starting at 1 for the category at the top of the list in the Paste Function dialog box.

Status_bar_text    the text displayed in the status bar when a menu item or toolbar button assigned to this macro is clicked on. Be sure to enclose the text in quotes.

Help_id    is the numerical ID for the help topic associated with this macro and any related menu items or toolbar buttons.

Help_file    is the pathname of the help file for the macro.

.MAILER

Equivalent to clicking the Add Mailer command on the Mail submenu of the File menu. Adds a new PowerTalk mailer to the active workbook. Use this command to add addressing or subject information to a workbook that you want to send to another user.

Note   This function is available on Macintosh computers with Microsoft Excel and Apple PowerTalk only.

Syntax

.MAILER( )

Remarks

If there is already a mailer, this command fails and returns the #VALUE! error value.

Related Function

MAIL.DELETE.MAILER   Deletes an existing mailer from the active workbook

MAIL.DELETE.MAILER

Equivalent to clicking the Delete Mailer command on the Mail submenu of the File menu. Deletes an existing mailer from the active workbook.

Note   This function is available on Macintosh computers with Microsoft Excel and Apple PowerTalk only.

Syntax

MAIL.DELETE.MAILER( )

Remarks

If there is no mailer, returns the #VALUE! error value.

Related Function

.MAILER   Adds a new PowerTalk mailer to the active workbook

.MAILER

Equivalent to clicking the Mailer button when mailer is attached to the current workbook. Allows you to edit a PowerTalk mailer attached to the active workbook

Note   This function is available on Macintosh computers with Microsoft Excel and Apple PowerTalk only.

Syntax

.MAILER(to_recipients, cc_recipients, bcc_recipients, subject, enclosures, which_address)

.MAILER?(to_recipients, cc_recipients, bcc_recipients, subject, enclosures, which_address)

To_recipients    is the name of the person to whom you want to send the mail. The name should be given as text. To specify more than one name, give the list of names as an array.

Cc_recipients    is the name of those recipients to be carbon copied. A single name should be given as text. To specify more than one name, give the list of names as an array.

Bcc_recipients    is the name of the recipients to be added as blind carbon copies.

Subject     is a text string containing the subject text for the mail messages.

Enclosures    is an array of strings specifying enclosures as file names.

Which_address    indicates which type of address to use, as a text string, specifying the address type for all recipients. For example, "Fax".

Remarks

If there is no mailer, returns the #VALUE! error value.

Related Functions

MAIL.DELETE.MAILER   Adds a new PowerTalk mailer to the active workbook

.MAILER   Adds a new PowerTalk mailer to the active workbook

MAIL.FORWARD

Equivalent to clicking the Forward command on the Mail submenu of the File menu. Creates a new mailer to replace the previous version and brings up the mailer dialog.

Note   This function is available on Macintosh computers with Microsoft Excel and Apple PowerTalk only.

Syntax

MAIL.FORWARD( )

Remarks 

•    Returns the #VALUE! error value or #N/A if the current workbook has no mailer.

•    This function is available only when the current workbook is open and has been received by PowerTalk with a piece of mail to forward.

Related Functions

.MAILER   Allows you to edit a PowerTalk mailer attached to the active workbook

MAIL.DELETE.MAILER   Deletes a new PowerTalk mailer to the active workbook

.MAILER   Adds a new PowerTalk mailer to the active workbook

MAIL.LOGOFF

Ends the current mail session.

Important   To use MAIL.LOGOFF in Microsoft Excel for Windows, you must be using a mail client that supports the Messaging Applications Programming Interface (MAPI) or VendorIndependent Messaging (VIM). The function is available for only Microsoft Excel for Windows.

Syntax

MAIL.LOGOFF( )

Remarks

Returns TRUE if the session was ended, or #VALUE! if there was no session.

MAIL.LOGON

Starts a mail session.

Important   To use MAIL.LOGON in Microsoft Excel for Windows, you must be using a mail client that supports the Messaging Applications Programming Interface (MAPI) or VendorIndependent Messaging (VIM). The function is available for only Microsoft Excel for Windows.

Syntax

MAIL.LOGON(name_text, password_text, download_logical)

MAIL.LOGON?(name_text, password_text, download_logical)

Name_text    is the username of the mail account or Microsoft Exchange profile name. If omitted, prompts for username.

Password_text    is the password for the account. If omitted, prompts for password. Ignored when the dialog box form is used. This argument is ignored in Microsoft Exchange.

Download_logical    specifies whether to download new mail. Use TRUE to download new mail; use FALSE or leave blank to skip downloading new mail.

Remarks

Returns FALSE if you cancel the dialog box or #VALUE! if you can't log on.

If you omit both name_text and password_text, Microsoft Excel tries to log on using an existing mail session.

Related Function

MAIL.LOGOFF   Ends the current mail session

.LETTER

Equivalent to clicking the Next Letter command on the Mail submenu of the File menu. Opens the oldest unread Microsoft Excel workbook from the In Tray as a new window.

Note   This function is available on Macintosh computers with Microsoft Excel and Apple PowerTalk only.

Syntax

.LETTER( )

Remarks

Returns #VALUE! on error, and #N/A if there are no more letters in the In Tray to open.

Related Functions

.MAILER   Allows you to edit a PowerTalk mailer attached to the active workbook

MAIL.DELETE.MAILER   Adds a new PowerTalk mailer to the active workbook

.MAILER   Adds a new PowerTalk mailer to the active workbook

MAIL.REPLY

Equivalent to clicking the Reply command on the Mail submenu of the File menu. Replies to the sender of the current letter.

Note   This function is available on Macintosh computers with Microsoft Excel and Apple PowerTalk only.

Syntax

MAIL.REPLY( )

Remarks 

•    Returns the #VALUE! error value or #N/A if the current workbook has no mailer.

•    The letter must currently be open.

Related Functions

.MAILER   Allows you to edit a PowerTalk mailer attached to the active workbook

MAIL.DELETE.MAILER   Deletes a new PowerTalk mailer to the active workbook

.MAILER   Adds a new PowerTalk mailer to the active workbook

Equivalent to clicking the Reply All command on the Mail submenu of the File menu. Replies to the sender and all recipients of the current letter.

Note   This function is available on Macintosh computers with Microsoft Excel and Apple PowerTalk only.

Syntax

( )

Remarks

Returns the #VALUE! error value or #N/A if the current workbook has no mailer.

Related Functions

.MAILER   Allows you to edit a PowerTalk mailer attached to the active workbook

MAIL.DELETE.MAILER   Deletes a new PowerTalk mailer to the active workbook

.MAILER   Adds a new PowerTalk mailer to the active workbook

.MAILER

Equivalent to clicking the Send Mailer command on the Mail submenu of the File menu. Sends a PowerTalk mailer.

Note   This function is available on Macintosh computers with Microsoft Excel and Apple PowerTalk only.

Syntax

.MAILER( )

MAIN.CHART

Equivalent to clicking the Main Chart command on the Format menu when a chart sheet is active in Microsoft Excel version 2.2 or earlier. This function is included only for macro compatibility.

Syntax

MAIN.CHART(type_num, stack, 100, vary, overlap, drop, hilo, overlap%, cluster, angle)

MAIN.CHART?(type_num, stack, 100, vary, overlap, drop, hilo, overlap%, cluster, angle)

Equivalent to clicking the Main Chart Type command on the Chart menu in Microsoft Excel for the Macintosh version 1.5 or earlier. This function is included only for macro compatibility.

Syntax

(type_num)

MCORREL

Returns a correlation matrix that measures the correlation between two or more data sets that are scaled to be independent of the unit of measurement.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

MCORREL(inprng, outrng, grouped, labels) MCORREL?(inprng, outrng, grouped, labels)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Grouped    is a text character that indicates whether the data in the input range is organized by row or column. 

•   If grouped is "C" or omitted, then the data is organized by column.

•   If grouped is "R", then the data is organized by row. 

Labels    is a logical value that describes where the labels are located in the input range, as shown in the following table:

Labels

 

Grouped

 

Labels are in

 

TRUE

"C"

First row of the input range.

 

 

TRUE

"R"

First column of the input range.

 

                 

FALSE or omitted        (ignored)        No labels. All cells in the input range are data.

Related Function

MCOVAR   Returns the covariance between two or more data sets

MCOVAR

Returns a covariance matrix that measures the covariance between two or more data sets.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

MCOVAR(inprng, outrng, grouped, labels) MCOVAR?(inprng, outrng, grouped, labels)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Grouped    is a text character that indicates whether the data in the input range is organized by row or column. 

•   If grouped is "C" or omitted, then the data is organized by column.

•   If grouped is "R", then the data is organized by row. 

Labels    is a logical value that describes where the labels are located in the input range, as shown in the following table:

Labels

 

Grouped

 

Labels are in

TRUE                        "C"                First row of the input range

TRUE                        "R"                First column of the input range

FALSE or omitted        (ignored)        No labels. All cells in the input range are data.

Related Function

MCORREL   Returns the correlation coefficient of two or more data sets that are scaled to be independent of the unit of measurement

MENU.EDITOR

This function should not be used in Microsoft Excel 97 or later because the Menu Editor is only available in Microsoft Excel 95 and Microsoft Excel version 5.0.

MERGE.STYLES

Equivalent to clicking the Merge button in the Style dialog box, which appears when you click the Style command on the Format menu. Merges all the styles from another workbook into the active workbook. Use MERGE.STYLES when you want to import styles from another sheet in another workbook.

Syntax

MERGE.STYLES(document_text)

Document_text is the name of a sheet in a workbook from which you want to merge styles into the active workbook.

Remarks 

•    If any styles from the workbook being merged have the same name as styles in the active workbook, a dialog box appears asking if you want to replace the existing definitions of the styles with the "merged" definitions of the styles. If you click the Yes button, all the definitions are replaced; if you click the No button, all the original definitions in the active workbook are retained.

•    When you move a sheet with styles to another workbook with styles, any styles with identical names but conflicting definitions have the sheet name added to the style name. 

Related Functions

DEFINE.STYLE   Creates or changes a cell style

DELETE.STYLE   Deletes a cell style

MESSAGE

Displays and removes messages in the message area of the status bar. MESSAGE is useful for displaying text that doesn't need a response, such as descriptions of commands in userdefined menus.

Syntax

MESSAGE(logical, text)

Logical    is a logical value specifying whether to display or remove a message. 

•   If logical is TRUE, Microsoft Excel displays text in the message area of the status bar.

•   If logical is FALSE, Microsoft Excel removes any messages, and the status bar is returned to normal (that is, command help messages are displayed).

Text    is the message you want to display in the status bar. If text is "" (empty text), Microsoft Excel removes any messages currently displayed in the status bar.

Remarks 

•   Only one message can be displayed in the status bar at a time. Messages are always displayed in the same place.

•   MESSAGE works the same way whether the status bar is displayed or not. You can, for example, use MESSAGE while the status bar isn't displayed. As soon as you display the status bar, you see your message.

•   If you display any message (even empty text) and don't remove it with MESSAGE(FALSE), that message is displayed until you quit Microsoft Excel.

•   You can also use the ALERT function to get the user's attention; however, this interrupts the macro and requires the user's intervention before the macro can continue. 

Example

The following lines in a macro display a message warning that you must wait for a moment while the macro calls a subroutine.

MESSAGE(TRUE, "One moment please ")

Related Functions

ALERT   Displays a dialog box and a message

BEEP   Sounds a tone

MOVE

Equivalent to moving a window by dragging its title bar in Microsoft Excel version 3.0 or earlier. MOVE is also equivalent to choosing the Move command from the Control menu in Microsoft Windows. This function is included only for macro compatibility and will be converted to when you open older macro sheets. For more information, see .

Syntax

MOVE(x_pos, y_pos, window_text)

MOVE?(x_pos, y_pos, window_text)

Related Functions

   Sizes a window

   Moves a window

MOVEAVG

Projects values in a forecast period, based on the average value of the variable over a specific number of preceding periods.

If this function is not available, you must install the Analysis ToolPak add-in.

Syntax

MOVEAVG(inprng, outrng, interval, stderrs, chart, labels) MOVEAVG?(inprng, outrng, interval, stderrs, chart, labels)

Inprng    is the input range.

Outrng    is the first cell (the upper-left cell) in the output table or the name, as text, of a new sheet to contain the output table. If FALSE, blank, or omitted, places the output table in a new workbook.

Interval    is the number of values to include in the moving average. If omitted, interval is 3.

Stderrs    is a logical value. 

•   If stderrs is TRUE, standard error values are included in the output table.

•   If stderrs is FALSE or omitted, standard errors are not included in the output table. 

Chart    is a logical value. 

•   If chart is TRUE, then MOVEAVG generates a chart for the actual and forecast values.

•   If chart is FALSE or omitted, the chart is not generated. 

Labels    is a logical value. 

•   If labels is TRUE, then the first row or column of inprng contains labels.

•   If labels is FALSE or omitted, all cells in inprng are considered data. Microsoft Excel generates appropriate data labels for the output table.

Moves or copies a button from one toolbar to another.

Syntax

(from_bar_id, from_bar_position, to_bar_id, to_bar_position, copy, width)

From_bar_id    specifies the number or name of a toolbar from which you want to move or copy the button. For detailed information, see the description of bar_id in .

From_bar_position    specifies the current position of the button within the toolbar.

From_bar_position starts with 1 at the left side (if horizontal) or at the top (if vertical).

To_bar_id    specifies the number or name of a toolbar to which you want to move or paste the button. For detailed information, see the description of bar_id in . To_bar_id is optional if you are moving a button within the same toolbar.

To_bar_position    specifies where you want to move or paste the button within the toolbar.

To_bar_position starts with 1 at the left side (if horizontal) or at the top (if vertical). To_bar_position is optional if you are only adjusting the width of a drop-down list.

Copy    is a logical value specifying whether to copy the button. If copy is TRUE, the button is copied; if FALSE or omitted, the button is moved.

Width    is the width, measured in points, of a drop-down list. If the button you are moving is not a drop-down list, width is ignored.

Related Functions

   Adds one or more buttons to a toolbar

   Copies a button face to the Clipboard

   Returns information about a button or buttons on a toolbar

NAMES

Returns, as a horizontal array of text, the specified names defined in the specified workbook. The returned array lists the names in alphabetic order. Use NAMES instead of LIST.NAMES when you want to return the names to the macro sheet instead of to the active worksheet.

Syntax

NAMES(document_text, type_num, match_text)

Document_text    is text that specifies the workbook whose names you want returned. If document_text is omitted, it is assumed to be the active workbook.

Type_num    is a number from 1 to 3 that specifies whether to include hidden names in the returned array.

If type_num is

 

NAMES returns

1             or omitted       Normal names only

2             Hidden names only

3             All names

Match_text    is text that specifies the names you want returned and can include wildcard characters. If match_text is omitted, all names are returned.

Remarks 

•    Hidden names are defined using the macro function and do not appear in the Paste Name, Define Name, or Go To dialog boxes.

•    NAMES returns a horizontal array, so you will normally enter this function as an array in several horizontal cells or define a name to refer to the array that NAMES returns. If you want the names in a vertical array instead, use the TRANSPOSE function.

•    You can use the COLUMNS function to count the number of entries in the horizontal array. 

Example

The following macro formula returns all names on the active workbook starting with the letter P.

NAMES(, 3, "P*")

Related Functions

   Defines a name on the active worksheet or macro sheet

   Deletes a name

   Returns a name matching a definition

   Returns the definition of a name

LIST.NAMES   Lists names and their associated information

   Defines a name as a value

NEW

Equivalent to clicking the New command on the File menu. Creates a new Microsoft Excel workbook or opens a template.

Syntax

NEW(type_num, xy_series, add_logical)

NEW?(type_num, xy_series, add_logical)

Type_num    specifies the type of workbook to create, as shown in the following table. Type_num is most often 5 or quoted text; other values are mainly for compatibility with Microsoft Excel version 4.0.

Type_num

 

Workbook

Omitted             New workbook with a single worksheet of the same type as the active worksheet

1          New workbook with one worksheet

2          New workbook with one chart based on the current selection

3          New workbook with one macro sheet

4          New workbook with one international macro sheet

5          New workbook with 16 worksheets or based on the default workbook

6          New workbook with one Visual Basic module

7          New workbook with one dialog sheet

Quoted text          Template.

Xy_series    is a number from 0 to 3 that specifies how data is arranged in a chart.

Xy_series

 

Result

0          Displays a dialog box if the selection is ambiguous.

1          or omitted        The first row/column is the first data series.

2          The first row/column contains the category (x) axis labels.

3          The first row/column contains the x-values; the created chart is an xy

(scatter) chart.

Add_logical    specifies whether or not to add the sheet type to the open workbook. If add_logical is TRUE, the sheet type is inserted before the current sheet; if FALSE or omitted, it is not inserted. This argument is for compatibility with Microsoft Excel version 4.0.

Add_logical is ignored if type_num is 5.

Remarks

You can also use NEW to create new sheets from templates that exist in the startup directory or folder, using for type_num the text that appears in the File New list box. To create new sheets from any template that is not in the start-up directory, use the OPEN function.

Related Functions

NEW.WINDOW   Creates a new window for an existing worksheet or macro sheet

OPEN   Opens a workbook

NEW.WINDOW

Equivalent to clicking the New Window command on the Window menu. Creates a new window for the active workbook.

Syntax

NEW.WINDOW( )

After you use NEW.WINDOW, use the , , and functions to size and position the new window.

Related Functions

   Arranges all displayed windows to fill the workspace and synchronizes windows for scrolling

   Moves a window

   Changes the size of a window

NEXT

Ends a FOR-NEXT, -NEXT, or WHILE-NEXT loop and continues carrying out the current macro with the formula that follows the NEXT function.

Syntax

NEXT( )

Related Functions

FOR   Starts a FOR-NEXT loop

   Starts a -NEXT loop

WHILE   Starts a WHILE-NEXT loop

NOTE

Equivalent to choosing the Comment command from the Insert menu. Creates a comment or replaces text characters in a comment.

Syntax

NOTE(add_text, cell_ref, start_char, num_chars)

NOTE?( )

Add_text    is text of up to 255 characters you want to add to a comment. Add_text must be enclosed in quotation marks. 

•   If add_text is omitted, it is assumed to be "" (empty text). 

Cell_ref    is the cell to which you want to add the comment text. If cell_ref is omitted, add_text is added to the active cell's comment.

Start_char    is the number of the character at which you want add_text to be added. If start_char is omitted, it is assumed to be 1. If there is no existing comment, start_char is ignored.

Num_chars    is the number of characters that you want to replace in the comment. If num_chars is omitted, it is assumed to be equal to the length of the comment.

Remarks 

•   NOTE returns the number of the last character entered in the comment. This is useful if you want to know how many characters are in the text string.

•   The dialog-box form of this function, NOTE?, takes no arguments.

•   NOTE() deletes the comment attached to the active cell. 

To find out if a cell has a comment attached to it, use .

Related Function

   Returns characters from a comment

OBJECT.PROPERTIES

Determines how the selected object or objects are attached to the cells beneath them and whether they are printed. The way an object is attached to the cells beneath it affects how the object is moved or sized whenever you move or size the cells.

OBJECT.PROPERTIES(placement_type, print_object)

OBJECT.PROPERTIES?(placement_type, print_object)

Placement_type    is a number from 1 to 3 specifying how to attach the selected object or objects. If placement_type is omitted, the current status is unchanged.

If placement_type is

 

The selected object is

1                Moved and sized with cells.

2                Moved but not sized with cells.

3                Free-floating—it is not affected by moving and sizing cells.

Print_object    is a logical value specifying whether to print the selected object or objects. If TRUE or omitted, the objects are printed; if FALSE, they are not printed.

Remarks

If an object is not selected, OBJECT.PROPERTIES interrupts the macro and returns the #VALUE! error value.

Related Functions

CREATE.OBJECT   Creates an object

   Moves the selected object

   Changes the size of the selected object

OBJECT.PROTECTION

Changes the protection status of the selected object.

Syntax

OBJECT.PROTECTION(locked, lock_text)

OBJECT.PROTECTION?(locked, lock_text)

Locked    is a logical value that determines whether the selected object is locked or unlocked. If locked is TRUE, Microsoft Excel locks the object; if FALSE, Microsoft Excel unlocks the object.

Lock_text    is a logical value that determines whether text in a text box or button can be changed. Lock_text applies only if the object is a text box, button, or worksheet control. If lock_text is TRUE or omitted, text cannot be changed; if FALSE, text can be changed.

Remarks 

•    You cannot lock or unlock an individual object with OBJECT.PROTECTION when protection is selected for objects in the Protect Sheet dialog box.

•    If an object is not selected, the function returns the #VALUE! error value and halts the macro.

•    In order for an object to be protected, you must use the PROTECT.DOCUMENT(, , , TRUE) function after changing the object's status with OBJECT.PROTECTION. 

Related Functions

PROTECT.DOCUMENT   Controls protection for the active worksheet

WORKBOOK.PROTECT   Controls protection for the active workbook

Runs a specified macro when another application sends data to a particular workbook via dynamic data exchange (DDE) or via Publish and Subscribe on the Macintosh. Workbook links to other applications are called remote references.

Syntax

(document_text, macro_text)

Important   Microsoft Excel for the Macintosh requires system software version 7.0 or later for this function.

Document_text    is the name of the sheet to which remote data will be sent or the name of the source of the remote data. 

•   If document_text is the name of the remote data source, it must be in the form app|topic!item. You can use the form app|topic to include all items for a particular topic, or app| to specify an app alone, but you must include the | to indicate that you are specifying the name of a data source.

•   If document_text is omitted, the macro specified by macro_text is run whenever remote data is sent to any sheet not already assigned to another function.

•   In Microsoft Excel for the Macintosh, document_text can also be the name of a published edition file. Unless the file is in the current folder, document_text must include the complete path. 

Macro_text    is the name of, or an R1C1-style reference to, a macro that you want to run when data comes into the workbook or from the source specified by document_text. The name or reference must be in text form. 

•   If macro_text is omitted, the function is turned off for the specified workbook or source. 

Remarks 

•   remains in effect until you either clear it or quit Microsoft Excel. You can clear by specifying document_text and omitting the macro_text argument.

•   If the macro sheet containing macro_text is closed when data is sent to document_text, an error is returned.

•   If the incoming data causes recalculation, Microsoft Excel first runs the macro macro_text and then performs the recalculation. 

Examples

In Microsoft Excel for Windows, the following macro formula runs the macro AddOrders when data is sent to the sheet New in the workbook :

("[]New", "AddOrders")

In Microsoft Excel for the Macintosh, the following macro formula runs the macro beginning at cell R2C3 when data is sent to the sheet North in the workbook SALES DATABASE:

("[SALES DATABASE]North", "R2C3")

Related Functions

ERROR   Specifies what action to take if an error is encountered while a macro is running

INITIATE   Opens a channel to another application

ON.ENTRY   Runs a macro when data is entered

ON.RECALC   Runs a macro when a workbook is recalculated

ON.DOUBLECLICK

Runs a macro when you double-click any cell or object on the specified sheet or macro sheet or double-click any item on the specified chart.

Syntax

ON.DOUBLECLICK(sheet_text, macro_text)

Sheet_text    is a text value specifying the name of a sheet in a workbook. If sheet_text is omitted, the macro is run whenever you double-click any sheet not specified by a previous ON.DOUBLECLICK formula. Sheet_text must be in the form "[book1]sheet1".

Macro_text    is the name of, or an R1C1-style reference to, a macro you want to run when you double-click the sheet specified by sheet_text. The name or reference must be in text form. If macro_text is omitted, double-clicking reverts to its normal behavior, and any macros assigned by previous ON.DOUBLECLICK functions are turned off.

Remarks 

•    ON.DOUBLECLICK overrides Microsoft Excel's normal double-click behavior, such as displaying cell notes, displaying the Patterns dialog box, or allowing editing cell text directly in cells.

•    To determine what cell, object, or chart item has been double-clicked, use a CALLER function in the macro specified by macro_text.

•    ON.DOUBLECLICK does not affect objects to which .OBJECT macros have already been assigned. Use ON.DOUBLECLICK (TRUE) to make Microsoft Excel carry out the action that would normally occur if you double-click on the current selection. 

Related Functions

.OBJECT   Assigns a macro to an object

ON.WINDOW   Runs a macro when you switch to a window

ON.ENTRY

Runs a macro when you enter data into any cell on the specified sheet.

Syntax

ON.ENTRY(sheet_text, macro_text)

Sheet_text    is a text value specifying the name of a sheet in a workbook. If sheet_text is omitted, the macro is run whenever you enter data into any sheet or macro sheet.

Macro_text    is the name of, or an R1C1-style reference to, a macro you want to run when you enter data into the sheet specified by sheet_text. The name or reference must be in text form. If macro_text is omitted, entering data reverts to its normal behavior, and any macros assigned by previous ON.ENTRY functions are turned off.

Remarks 

•    The macro is run only when you enter data in a cell, not when you use edit commands or macro functions.

•    To determine what cell had data entered into it, use a CALLER function in the macro specified by macro_text. 

Related Functions

   Turns Data Entry mode on or off

ON.RECALC   Runs a macro when a workbook is recalculated

Runs a specified macro when a particular key or key combination is pressed.

Syntax

(key_text, macro_text)

Key_text    can specify any single key, or any key combined with ALT, CTRL, or SHIFT, or any combination of those keys (in Microsoft Excel for Windows) or COMMAND, CTRL, OPTION, or SHIFT or any combination of those keys (in Microsoft Excel for the Macintosh). Each key is represented by one or more characters, such as "a" for the character a, or "{ENTER}" for the ENTER key.

To specify characters that aren't displayed when you press the key, such as ENTER or TAB, use the codes shown in the following table. Each code in the table represents one key on the keyboard.

Key

 

Code

BACKSPACE                       "{BACKSPACE}" or "{BS}"

BREAK                              "{BREAK}"

CAPS LOCK "{CAPSLOCK}" CLEAR         "{CLEAR}"

DELETE or DEL                   "{DELETE}" or "{DEL}"

DOWN        "{DOWN}" END        "{END}"

ENTER (numeric keypad) "{ENTER}"

ENTER

"~" (tilde)

ESC

"{ESCAPE} or {ESC}"

HELP

"{HELP}"

HOME

"{HOME}"

INS

"{INSERT}"

LEFT

"{LEFT}"

NUM LOCK

"{NUMLOCK}"

PAGE DOWN

"{PGDN}"

PAGE UP

"{PGUP}"

RETURN

"{RETURN}"

RIGHT

"{RIGHT}"

SCROLL LOCK

"{SCROLLLOCK}"

TAB

"{TAB}"

UP

"{UP}"

F1 through F15

"{F1}" through "{F15}"

In Microsoft Excel for Windows, you can also specify keys combined with SHIFT and/or CTRL and/or ALT. In Microsoft Excel for the Macintosh, you can also specify keys combined with SHIFT and/or CTRL and/or OPTION and/or COMMAND. To specify a key combined with another key or keys, use the following table.

To combine with

 

Precede the key code by

 

SHIFT

"+" (plus sign)

 

 

CTRL

"^" (caret)

 

 

ALT or OPTION

"%" (percent sign)

 

 

COMMAND

"*" (asterisk)

 

           

To assign a macro to one of the special characters (+, ^, %, and so on), enclose the character in brackets. For example, ("^{+}", "InsertItem") assigns a macro named InsertItem to the key sequence CTRL+PLUS SIGN.

Macro_text    is the name of a macro that you want to run when key_text is pressed. The reference must be in text form. 

•   If macro_text is "" (empty text), nothing happens when key_text is pressed. This form of disables the normal meaning of keystrokes in Microsoft Excel.

•   If macro_text is omitted, key_text reverts to its normal meaning in Microsoft Excel, and any special key assignments made with previous functions are cleared. 

Remarks 

•   remains in effect until you clear it or quit Microsoft Excel. You can clear by specifying key_text and omitting the macro_text argument.

•   If the macro sheet containing macro_text is closed when you press key_text, an error is returned.

•   If another macro is running when you press key_text, macro_text will not run. 

Examples

Suppose you wanted the key combination SHIFT+CTRL+RIGHT to run the macro Print. You use the following macro formula:

("+^{RIGHT}", "Print")

To return SHIFT+CTRL+RIGHT to its normal meaning, you would use the following macro formula:

("+^{RIGHT}")

To disable SHIFT+CTRL+RIGHT altogether, you would use the following macro formula:

("+^{RIGHT}", "")

Related Functions

   Disables macro interruption

ERROR   Specifies what action to take if an error is encountered while a macro is running

   Sends a key sequence to an application

ON.RECALC

Runs a macro when a specific sheet is recalculated. Use ON.RECALC to perform an operation on a sheet each time the sheet is recalculated, such as checking that a certain condition is still being met.

Syntax

ON.RECALC(sheet_text, macro_text)

Sheet_text    is the name of a sheet, given as text. If sheet_text is omitted, the macro is run whenever any open sheet not specified by a previous ON.RECALC formula is recalculated. Only one ON.RECALC formula can be run for each recalculation.

Macro_text    is the name of, or an R1C1-style reference to, a macro you want to run when the sheet specified by sheet_text is recalculated. The name or reference must be in text form. The macro will be run each time the sheet is recalculated until ON.RECALC is cleared. If macro_text is omitted, recalculating reverts to its normal behavior, and any macros assigned by previous ON.RECALC functions are turned off.

Remarks

A macro specified to be run by ON.RECALC is not run by actions taken by other macros. For example, a macro specified by ON.RECALC will not be run after the function is carried out, but will be run if you change data in a sheet set to calculate automatically or choose the Calc Now button in the Calculation panel of the Options dialog box, which appears when you choose the Options command from the Tools menu.

Examples

In Microsoft Excel for Windows, the following macro formula specifies that the macro Printer on the macro sheet be run when the worksheet named is recalculated:

ON.RECALC("", "!Printer")

In Microsoft Excel for the Macintosh, the following macro formula turns off ON.RECALC for the workbook named SALES: ON.RECALC("SALES")

Related Functions

CALCULATE.DOCUMENT   Calculates the active sheet only

   Calculates all open workbooks immediately

CALCULATION   Controls calculation settings

ON.ENTRY   Runs a macro when data is entered

ON.SHEET

Starts a macro whenever the specified sheet is activated from another sheet.

Syntax

ON.SHEET(sheet_text, macro_text, activate_logical)

Sheet_text    is the name of the sheet that triggers a macro when it is activated, in the form "[Book1]Sheet1". If omitted, then when any sheet in any book is activated, macro_text will run.

Macro_text    is the name of the macro to run when the specified sheet is activated. If omitted, then the triggering of a macro on the specified sheet is cancelled.

Activate_logical    is a logical value that specifies if the macro is run when the sheet is activated or deactivated. If TRUE or omitted, the macro is run when the sheet is activated. If FALSE, the macro is run when the sheet is deactivated.

Examples

ON.SHEET("[]Sheet1","WeeklyCalc") will run the macro "WeeklyCalc" when "[]Sheet1" is activated.

ON.SHEET(,"WeeklyCalc") runs "WeeklyCalc" when any sheet in the book is activated.

ON.SHEET("[]Sheet1") cancels the triggering of "WeeklyCalc" when Sheet1 in the book is activated.

ON.SHEET("[]","WeeklyCalc") runs "WeeklyCalc" when any sheet in the book

is activated

Related Function

ON.WINDOW   Runs a specified macro when you switch to a particular window.

Runs a macro at a specified time. Use to run a macro at a specific time of day or after a specified period has passed.

Syntax

(time, macro_text, tolerance, insert_logical)

Time    is the time and date, given as a serial number, at which the macro is to be run. If time does not include a date (that is, if time is a serial number less than 1), the macro is run the next time this time occurs.

Macro_text    is the name of, or an R1C1-style reference to, a macro to run at the specified time and every subsequent day at that time.

Tolerance    is the time and date, given as a serial number, that you are willing to wait until and still have the macro run. For example, if Microsoft Excel is not in Ready, Copy, Cut, or Find mode at time, because another macro is running, but is in Ready mode 15 seconds later, and tolerance is set to time plus 30 seconds, the macro specified by macro_text will

run. If Microsoft Excel was not in Ready mode within 30 seconds, the macro would not run. If tolerance is omitted, it is assumed to be infinite.

Insert_logical    is a logical value specifying whether you want every day macro_text to run at time. Use insert_logical when you want to clear a previously set formula. If insert_logical is TRUE or omitted, the macro specified by macro_text is carried out at time. If insert_logical is FALSE and macro_text is not set to run at time, returns the #VALUE error value.

Examples

The following macro formula runs a macro called Test at 5:00:00 P.M. every day when Microsoft Excel is in Ready mode:

("5:00:00 PM", "Test")

The following macro formula runs a macro called Test 5 seconds after the formula is evaluated:

(NOW()+"00:00:05", "Test")

The following macro formula runs a macro called Test 10 seconds after the formula is evaluated. If Microsoft Excel is not in Ready mode at that time (because it is in Edit mode, for example), the tolerance argument specifies 5 seconds of additional time to wait to run the macro. If Microsoft Excel is still not in Ready mode at that time, macro_text is not run.

(NOW()+"00:00:10", "Test", NOW()+"00:00:15")

ON.WINDOW

Runs a specified macro when you switch to a particular window.

Syntax

ON.WINDOW(window_text, macro_text)

Window_text    is the name of a window in the form of text. If window_text is omitted, ON.WINDOW starts the macro whenever you switch to any window, except for windows that are named in other ON.WINDOW statements.

Macro_text    is the name of, or an R1C1-style reference to, a macro to run when you switch to window_text. If macro_text is omitted, switching to window_text no longer runs the previously specified macro.

Remarks 

•    A macro specified to be run by ON.WINDOW is not run when other macros switch to the window or when a command to switch to a window is received through a DDE channel. Instead, ON.WINDOW responds to a user's actions, such as clicking a window with the mouse, clicking the Copy command on the Edit menu, and so on.

•    If a sheet or macro sheet has an Auto_Activate or Auto_Deactivate macro defined for it, those macros will be run after the macro specified by ON.WINDOW. 

Examples

In Microsoft Excel for Windows, the following macro formula runs the macro beginning at cell R1C2 when you switch to the window :

ON.WINDOW("", "R1C2")

The following macro formula stops the macro from running when you switch to :

ON.WINDOW("")

In Microsoft Excel for the Macintosh, the following macro formula runs the macro named ShowAlert when you switch to the window MAIN WINDOW:

ON.WINDOW("MAIN WINDOW", "ShowAlert")

The following macro formula stops the macro from running when you switch to MAIN WINDOW:

ON.WINDOW("MAIN WINDOW")

Related Functions

GET.WINDOW   Returns information about a window

   Runs a macro when a specified key is pressed

ON.SHEET   Triggers a macro whenever the specified sheet is activated from another sheet

WINDOWS   Returns the names of all open windows

OPEN

Equivalent to clicking the Open command on the File menu. Opens an existing workbook.

Syntax

OPEN(file_text, update_links, read_only, format, prot_pwd, write_res_pwd, ignore_rorec, file_origin, custom_delimit, add_logical, editable, file_access, notify_logical, converter)

OPEN?(file_text, update_links, read_only, format, prot_pwd, write_res_pwd, ignore_rorec, file_origin, custom_delimit, add_logical, editable, file_access, notify_logical, converter)

File_text    is the name, as text, of the workbook you want to open. File_text can include a drive and path, and can be a network pathname. In the dialog-box form in Microsoft Excel for Windows, file_text can include an asterisk (*) to represent any sequence of characters and a question mark (?) to represent any single character.

Update_links    specifies whether and how to update external and remote references. If update_links is omitted, Microsoft Excel displays a message asking if you want to update l