About the Script Step Reference

The script step reference is a detailed guide to all the FileMaker Pro script steps. It is similar in layout to FileMakers online help system, but adds more detailed examples and commentary where possible. The listing for each script step also indicates its platform compatibility, any menu equivalent, and whether the script step is web compatible. A number of web-compatible steps are marked with an asterisk. This indicates that although the step as a whole is web compatible, one or more specific options of the step are not.

A note on menu equivalents: With the introduction of custom menu sets in FileMaker Pro 8 Advanced, its possible to customize the look and behavior of FileMakers menus almost completely. Accordingly, the menu equivalents listed here all assume that the standard FileMaker menu set is active.

For further discussion of custom menus, see Special Edition Using FileMaker 8, Chapter 13, "Advanced Interface Techniques."

Add Account

Compatibility:

Menu Equivalent: None

Syntax:

Add Account [Account Name: <account name>; Password:

; Privilege Set: "

"; Expire password]

Options:

Account Name is the account name. Literal text can be entered or Specify can be clicked to create a new account name from a calculation.

Password is the new password. Literal text can be entered or Specify can be clicked to create a new password from a calculation.

Privilege Set allows you to assign a pre-existing privilege set for the user or to create a new one. (Full Access cannot be assigned via this script step. Accounts with Full Access must be created manually.)

User Must Change Password on Next Login: When selected, this option forces users to change their password the next time they log in to the database.

Examples:

[View full width]

Add Account [Account Name: "User_Account"; Password: "User_Password"; Privilege Set: "[Data Entry Only]"; Expire password]

Description:

This script step adds an account name, password, and privilege set to a databases security configuration. Account and password text may be defined in a calculation or typed into the script step itself. The account name must be unique, and full access to the file is required to execute this step.

Comments:

It might be desirable to allow access to this functionality via a script if certain users or user groups have limited access to the FileMaker menus because of security configurations. See the Change Password script step for a fuller discussion.

Note that there are circumstances where you should not set an account to force the user to change his password at next login. If the user will not have a direct means to do this, the option should not be set. The best example is an account that will be used to access a FileMaker database via Instant Web Publishing: IWP provides no means for a user to change her password, so this setting will lock the user out of the database. Similarly, if the account is externally authenticated, it may be risky to tie the account to a privilege set requiring that the password be changed at some point, or have a minimum length.

Adjust Window

Compatibility:

Menu Equivalent: None

Syntax: Adjust Window [Resize to fit/Maximize/Minimize/Restore/Hide]

Options:

Resize to Fit shrinks a window to the minimum possible size while including all layout elements.

Maximize expands the current window to the size of the users screen or the application window in Windows. In Windows, the database window controls and scroll bar will disappear and be incorporated into the application window.

Minimize minimizes the current window to an icon or a minimized window bar at the bottom of the application window in Windows.

Restore returns the current window to the size it was before the last resize.

Hide hides the current database window.

Examples:

Go to Layout ["Detail"] Adjust Window [Maximize]

Description:

This script step hides or otherwise controls the size of the current database window. It is important to note that the size and position of a window cannot be relied upon unless one has explicitly set them, or users are explicitly prohibited from modifying them.

Note that in Windows, FileMaker opens all database windows within an application window. The Adjust Window script step will affect only database windows. There are no controls by which a developer can manipulate the application-level window.

Note also that in Windows if a user minimizes or resizes an existing window or opens a new window, any maximized window will be restored to its previous state. In solutions where you expect to use multiple windows, we recommend against using the maximize command.

Allow Toolbars

Compatibility:

Menu Equivalent: None

Syntax: Allow Toolbars []

Options:

On allows FileMakers native toolbars to be utilized.

Off hides and makes inaccessible FileMakers toolbars as well as the toolbar submenu options in the view menu.

Examples:

Allow Toolbars [Off]

Description:

This script step hides and shows the FileMaker Pro toolbars and menu options. This is often used to control the amount of screen space available in a given database screen. This script step takes effect only while the file that calls this script is active. This option has no effect in Kiosk mode because toolbars are always hidden in Kiosk mode.

Allow User Abort

Compatibility:

Menu Equivalent: None

Syntax: Allow User Abort []

Options:

On allows users to halt the execution of a script by pressing the Esc key (or images/U2318.jpg border=0>-period on Mac OS machines).

Off disables the halting of scripts by users.

Examples:

Allow User Abort[Off]

Description:

Allow User Abort is used to control the users ability to cancel scripts by using the Esc key (or the -period key combination on Mac OS systems). This script step is typically used in scripts whose operation should not be arbitrarily canceled by the user, such as login logic, data import/export, or any script that must process a set of records without any interruption. Most of FileMakers menu options are also unavailable while a script is running in the Allow User Abort [Off] state.

Comments:

If a script involves any processes that could work with large record sets, such as sorting, looping, or running a Replace script step, the user sees a progress dialog for the duration of that operation. If Allow User Abort is on, as it is by default, users can cancel the script and disrupt those operations, leaving them partially complete. If a script contains any process that must not be interrupted before completion, it should use Allow User Abort[Off] to ensure that these processes are able to finish without user interruption.

Arrange All Windows

Compatibility:

Menu Equivalent: Windows (various choices)

Syntax:

Arrange All Windows [Tile Horizontally/Tile Vertically/Cascade Window/Bring All to Front]

Options:

Tile Horizontally positions open windows from left to right across the screen. They are resized to avoid any overlaps.

Tile Vertically positions open windows from top to bottom down the screen. They are resized to avoid any overlaps.

Cascade Window positions windows overlapping diagonally from upper left to lower right. The idea of this arrangement is, presumably, to allow the reading of the title bar of each window. The windows are resized to fit the available screen space.

Bring All to Front (Mac OS only) brings all open windows to the front without resizing or otherwise moving or rearranging them. In the event that any open FileMaker windows have been hidden by (that is, are behind) any other applications windows, this step ensures that all FileMaker windows are above other application windows.

Examples:

[View full width]

New Window [Name: "Trees"; Height: 200; Width: 600; Top: 16; Left: 16] Arrange All Windows [Tile Vertically]

Description:

This script step resizes and/or repositions open windows, but does not affect which window has focus. The active record also remains the same.

Beep

Compatibility:

Menu Equivalent: None

Syntax: Beep

Options:

None

Examples:

[View full width]

Set Error Capture [On] Perform Find [Restore] If [Get (FoundCount) = 0] Beep Show Custom Dialog ["No records were found that match your find criteria."] End

Description:

This script step plays a beep noise. The beep is played at the default volume of the machine on which it is played.

Comments:

You may want to use the beep as an extra alert noise. (Weve even heard of an intrepid FileMaker developer, on the road without an alarm clock, who programmed himself an alarm clock in FileMaker with the Beep step.)

Change Password

Compatibility:

Menu Equivalent: File, Change Password

Syntax:

Change Password [Old Password: ; New Password: ; No dialog]

Options:

Old Password is the current accounts current password. It can be the result of a specified calculation or typed in.

New Password is the desired new password for the current account. It can be the result of a specified calculation or typed in.

Perform Without Dialog suppresses the Change Password dialog for this action. Rather than prompting the user for old and new passwords, the script step will use whatever values have been specified and stored with the script step.

Examples:

The following script uses a custom Change Password dialog, rather than the standard dialog used by FileMaker.

[View full width]

Change Password [Old Password: ldpassw0rd; New Password: New_Password; No Dialog] // Change Password can be used in conjunction with "Show Custom Dialog" to cascade password changes throughout several files: Allow User Abort [ Off ] Set Error Capture [ On ] # Show Custom Dialog [ Title: "Password Change"; Buttons: "OK", "Cancel"; Input #1: zgPassword_Old. t, "Old Password:"; Input #2: zgPassword_New. t, "New Password:" ] # If [ Get(LastMessageChoice)=1 ] Change Password [ Old Password: zgPassword_Old. t; New Password: zgPassword_New. t ] # send password change to other files Perform Script [ "Change Password"; from file "Contacts" Parameter: zgPassword_Old. t&"¶"&zgPassword_New. t ] Perform Script [ "Change Password"; from file "Invoices" Parameter: zgPassword_Old. t&"¶"&zgPassword_New. t ] End If # be sure to clear the globals for security reasons Set Field [zgPassword_Old. t; ""] Set Field [zgPassword_New. t; ""]

Description:

This script step changes the password for the current account. By default, a Change Password dialog is displayed unless the Perform Without Dialog option is selected. If Error Capture has been enabled (in the Set Error Capture script step) and Perform Without Dialog is not selected, then the user is given five attempts at changing his password. If Error Capture has not been enabled and Perform Without Dialog is not selected, then the user is given only one attempt at changing the password. Run Script with Full Access Privileges enables a user to change the password for the current account even if she lacks the explicit permission to do so.

Comments:

A number of FileMaker script steps perform functions similar or identical to choices that are available in the FileMaker menus. For reasons of security or solution design, a developer might choose to limit user access to the FileMaker menus. Menu access can be configured differently for each privilege set in a file. If access to menus is limited, it may be necessary or desirable to reproduce some functionality available through menus by creating a scripted interface instead. A user without access to menus might instead then see a Change Password button or clickable link, which invokes the Change Password script step.

When programming for the Web, be sure to select Perform Without Dialog. Leaving the box unchecked is not web compatible and does not work on the Web.

Check Found Set

Compatibility:

Menu Equivalent: Edit, Spelling, Check All

Syntax: Check Found Set

Options:

None

Examples:

Perform Find [Restore] Check Found Set

Description:

This script step uses FileMaker Pros spelling checker to check the spelling of the contents of text fields in all the records currently being browsed. The step checks spelling in all fields of type Text, and all calculation fields with a calculation result type of Text. It is an interactive script step that displays the familiar spelling dialog for every questionable spelling that the system finds.

Comments:

This option is normally available via the FileMaker menus. If one or more users have limited access to menu items, it may be necessary to write scripts that give them access to functionality normally available through menus, such as spell check functions. See the Change Password script step for further discussion of this point.

Check Record

Compatibility:

Menu Equivalent: Edit, Spelling, Check Record

Syntax: Check Record

Options:

None

Examples:

Go to Record/Request/Page [First] Loop Check Record Go to Record/Request/Page [Next; Exit after last] End Loop

Description:

This script step uses FileMaker Pros spelling checker to check the spelling of the contents of text fields in every record in the current record. The step checks spelling in all fields of type Text, and all calculation fields with a calculation result type of Text. It is an interactive script step that displays the familiar spelling dialog for every questionable spelling that the system finds. See also the Check Found Set script step for further discussion.

Comments:

This option is normally available via the FileMaker menus. If one or more users have limited access to menu items, it may be necessary to write scripts that give them access to functionality normally available through menus, such as spell check functions. See the Change Password script step for further discussion of this point.

Check Selection

Compatibility:

Menu Equivalent: Edit, Spelling, Check Selection

Syntax: Check Selection [Select; table::field]

Options:

Select Entire Contents checks the spelling of the entire contents of the designated field. If this option is not chosen, then only the text that has been selected (highlighted) is checked.

Go to Target Field allows for the selection of the field to spell check.

Examples:

Check Selection [Select; Product::Description]

Description:

This script step uses FileMaker Pros spelling checker to check the spelling of the contents of a single field. The step can check spelling in all fields of type Text, and all calculation fields with a calculation result type of Text. It is an interactive script step that displays the familiar spelling dialog for every questionable spelling that the system finds.

Comments:

This option is normally available via the FileMaker menus. If one or more users have limited access to menu items, it may be necessary to write scripts that give them access to functionality normally available through menus, such as spell check functions. See the Change Password script step for further discussion of this point.

Clear

Compatibility:

Menu Equivalent: Edit, Clear

Syntax: Clear [Select; ]

Options:

Select Entire Contents allows for the deletion of the entire contents of a field, regardless of what portion of its contents have been selected (highlighted) by the user.

Go to Target Field specifies which field is to have its contents or selected contents deleted.

Examples:

[View full width]

#The following example clears the values in a repeating field with three repetitions. Clear [Select, table::field[3]] Clear [Select, table::field[2]] Clear [Select, table::field]

Description:

This script step removes either the entire contents of a field (if the Select Entire Contents option has been designated) or the selected portion of a field (if the Select Entire Contents option has not been designated). It is important to note that Clear is distinct from the Cut operation in that it does not place the deleted content on the clipboard. In a web-published database, it is necessary to use a Commit Record/Request script step to update the record that had one (or more) of its fields cleared.

Comments:

Clear is one of a number of script steps that depend on the presence of specific fields on the current layout. For these steps to take effect, the targeted field must be present on the current layout and the current mode must be Browse mode. Note, however, that these script steps take effect even if the field has been marked as not enterable in Browse mode. Other script steps with the same limitations include Cut, Copy, Paste, and Set Selection.

Close File

Compatibility:

Menu Equivalent: File, Close

Syntax: Close File [Current File/""]

Options:

Specify allows you to select a FileMaker Pro file to close from among the list of existing predefined file references.

Add File Reference allows the selection of a file to close while at the same time adding it to the list of defined file references.

Define File References allows for existing file references to be modified or deleted.

Examples:

Close ["Line_Items"]

Description:

This script step closes the specified file. The target file may be specified via a file reference. If no file reference is designated, then the file in which the script is running is closed. (This also has the effect of halting the execution of the script that contains the Close File step.)

Comments:

If you used File, File Options to specify a script that should run when a file is closed, that script is triggered when the Close File script step is run.

Close Window

Compatibility:

Menu Equivalent: None

Syntax: Close Window [Current Window or Name: ]

Options:

Specify allows you to choose a window to close, either by typing its name explicitly, or by drawing the name from a calculation.

Current file only causes FileMaker to search only within windows based on table occurrences from within the current file.

Examples:

Close Window [Name: "Sales records"]

Description:

This script step closes either the currently active window or a window designated by name. The name may be a string literal typed into the script itself or generated as the result of a calculation.

Comments:

Closing the last open window in a database closes the database and halts execution of the currently running script. This also triggers any script that has been set to run when the file closes.

Current file only is a window management option thats new to FileMaker 8. In FileMaker 7, window management script steps could sometimes be "fooled" by the presence of windows from other files with the same name as the desired script step target, causing the script step to act on a window different from the desired one. In FileMaker 8, the developer can restrict the scope of window management script steps to consider only windows based on the current file.

Comment

Compatibility:

Menu Equivalent: None

Syntax: #

Options:

Specify allows for the entry of comment text in a dialog box.

Examples:

# Clear Globals for Login # # Script authored by : Tom # Last modified on 1/12/2004 # Clear [Select, table::gCurrentUserID] Clear [Select, table::gCurrentUserName] Clear [Select, table::gCurrentUserEmail]

Description:

This script step allows for the addition of comments to scripts. You can see these comments only when a script is viewed in ScriptMaker, or when a script is printed and the comments are bold text preceded by a #. Comments print as italics.

Comments:

Properly commented code helps greatly in legibility and debugging. Script comments are somewhat different from calculation comments, in that calculation comments are inserted in the body of a calculations text, and can be preceded with // or wrapped in /* . . . */ comment delimiters.

Commit Records/Requests

Compatibility:

Menu Equivalent: None

Syntax: Commit Records/Requests [No dialog]

Options:

Skip Data Entry Validation will override any data entry validation options set for fields and commit the record regardless of any errors. This option skips validation only for fields set with the Only During Data Entry validation option in the Options for Field dialog box; fields set to Always Validate still validate, even if the Skip Data Entry Validation option is selected in this script step.

Examples:

Show Custom Dialog ["Commit record?"; "Click Commit to save your changes."] If [Get(LastMessageChoice) = 1] Commit Records/Requests Else Revert Record/Request [No dialog] End

Description:

This script step commits a record. In other words, it exits the current record or find request and updates the field data for the record. It has the effect of causing the user to exit the record, in the sense that no field will be active on the current layout once the record is committed. Exiting a record in this fashion will also have the effect of saving any changes made to it. Exiting/committing a record can be accomplished in many nonscripted ways as well, including changing to another record or merely clicking on a layout outside of any field so that no field is selected. See the Revert Record/Request script step for more discussion.

Comments:

While a user is editing a record, any changes she makes to the record can be seen by other users of the database. Only when she commits the record are her changes saved to the database and broadcast to other users. This script step has wide applicability. Any time you change data in a record via a script, its a good idea to commit the record explicitly. This is especially true if the changes will result in significant screen updates. For example, if data changes in a record would lead to different data being displayed in a portal on the current layout, its very important to make sure the data changes are explicitly committed. As a best practice we recommend using this step in any script where record data is altered. Its also necessary (not just desirable) to add this script step to scripts that are called from the Web, if those scripts change record data.

Its also critical to use this step liberally when the Set Field step is used in a script. Lack of an appropriate commit can leave a record in a locked state. For example, if the last step in a script is a Set Field step, you should finish the script with a Commit Records/Requests step. Otherwise, the affected record will remain "open" and will be locked until committed. Similarly, we recommend you perform Commit Records/Requests after any Set Field steps that may precede a Perform Script step to ensure the changes take effect before the next script runs. Problems with record locking in these circumstances are common in complex, scripted systems converted from FileMaker Pro 6.

When programming for the Web, be sure to select Perform Without Dialog. Leaving the box unchecked is not web compatible and does not work on the Web.

Constrain Found Set

Compatibility:

Menu Equivalent: Requests, Constrain Found Set

Syntax: Constrain Found Set [Restore]

Options:

Specify Find Requests creates and stores a find request with the script step. See the Perform Find script step for more information.

Examples:

# Find all employees older than 60 years of age. Enter Find Mode [ ] Set Field [Age; ">60" ] Perform Find [] # Now find which of these want early retirement Enter Find Mode [ ] Set Field [Early_Retire; "Yes" ] Constrain Found Set[]

Description:

This script step specifies a find request that will be used to narrow the current found set. This is equivalent to applying the last find request with the new find request appended via a logical AND operator.

Comments:

Constrain[] is useful when searching unindexed fields as part of a complex find. If a search includes criteria for both stored and unstored fields, a performance gain may be achieved by first performing a find on the indexed fields, and then using Constrain[] to limit the search for the unindexed criteria to the smaller found set.

Convert File

Compatibility:

Menu Equivalent: None

Syntax: Convert File [""]

Options:

Specify Data Source allows for the designation of a data source to be converted into a FileMaker Pro 7 file.

The possible data sources are File, XML, and ODBC.

Examples:

Convert File ["datafile.fp5"]

Description:

This script step converts a file from a variety of supported formats into a FileMaker 7 file. This command works on only one file at a time. Supported data formats are BASIC format, Comma-Separated Text format, dBase III and IV DBF format, DIF format, FileMaker Pro format, HTML Table format, Lotus 1-2-3 WK1/WKS formats, Merge format, Microsoft Excel format, SYLK format, Tab-Separated Text format, and XML format. Designation of various data sources follows the same procedures as an import. See the Import Records script step for further discussion.

Comments:

This step is analogous to the effects of using File, Open to open a non-FileMaker 7/8 file. A variety of formats can be opened/converted, each with its own set of options.

Copy

Compatibility:

Menu Equivalent: Edit, Copy

Syntax: Copy [Select; ]

Options:

Select Entire Contents copies the entire contents of a field to the Clipboard rather than just the selected portion of the designated fields contents.

Go to Target Field or Specify allow you to select the field from which you wish to copy the contents to the clipboard. If no field is specified and nothing is selected, FileMaker Pro copies the values from all fields of the current record.

Examples:

Go To Layout[ "Customer Entry" (Customer)] Copy [Select; CustomerTable::Shipping_Address] Paste [Select; CustomerTable::Billing_Address]

Description:

This script step places the contents of the specified field onto the clipboard. If no field is specified, all fields from the current record are copied, causing the step to function identically to the Copy Record step.

Comments:

Copy is generally a poor way to move data within scripts. It requires that the current layout contain the field to be copied. (This is fragile because the script malfunctions if the field is removed.) Additionally, the contents of the clipboard are overwritten, without the consent of the user. Copy does have some interesting uses, however. When in Preview Mode, Copy takes an image of the screen, and this image can then be pasted into a container field. Copy is one of a number of script steps that depend on the presence of specific fields on the current layout. Other script steps with the same limitations include Cut, Copy, Paste, and Set Selection.

Copy All Records/Requests

Compatibility:

Menu Equivalent: None

Syntax: Copy All Records/Requests

Options:

None

Examples:

# Copy Records in Found Set Go To Layout ["Detail"] Copy All Records/Requests # Place all records in log field Go To Layout ["Log"] New Record/Request Paste [Select; Log Table::Log]

Description:

This script step copies the values of all fields in all the records in the current found set to the clipboard in a tab-delimited export format. Styles and formatting are not copied. The field values are exported in the order in which they appear on the current layout. Only those fields that appear in the current layout are included. With a record, individual fields are separated by tabs, and records are delimited by carriage returns. Repeating field values are separated by a group separator character between each repetition. Carriage returns within a field are copied to the clipboard as the "vertical tab" character (ASCII value 11), just as they are when being exported.

Comments:

Copy All Records/Requests is one of a number of script steps that depend on the presence of specific fields on the current layout. Other script steps with the same limitations include Cut, Copy, Paste, and Set Selection.

In previous versions of FileMaker it was often necessary to use this script step to copy a set of record keys and paste them into a field that would act as a "multikey," capable of relating to many records in another file at once. This technique was often used to navigate multistep relationship chains. The new relational capabilities of FileMaker 7 make it unlikely that this step will need to be used in this way, and the new Go to Related Records from found set capability of FileMaker 8 probably further limit the earlier need for such a technique. It does remain a very handy feature for copying record data in order to paste it into a program like Microsoft Word or Excel, where it can readily be formatted as a table.

Copy Record/Request

Compatibility:

Menu Equivalent: None

Syntax: Copy Record/Request

Options:

None

Examples:

# Copy Current Record Go To Layout ["Detail"] Copy Record/Request # Place record in log field Go To Layout ["Log"] New Record/Request Paste [Select; Log Table::Log]

Description:

This script step copies the values of all fields in the current record to the clipboard in a tab-delimited export format. Styles and formatting are not copied. The field values are exported in the order in which they appear on the current layout. Only those fields that appear in the current layout are included. With a record, individual fields are separated by tabs, and records are delimited by carriage returns. Repeating field values are separated by a group separator character between each repetition. Carriage returns within a field are copied to the clipboard as the "vertical tab" character (ASCII value 11), just as they are when being exported.

Comments:

Copy Record/Request is one of a number of script steps that depend on the presence of specific fields on the current layout. Other script steps with the same limitations include Cut, Copy, Paste, and Set Selection.

Correct Word

Compatibility:

Menu Equivalent: Edit, Spelling, Correct Word

Syntax: Correct Word

Options:

None

Examples:

Check Selection [Select; Product::Description] Correct Word

Description:

This script step opens the spelling dialog box to allow for the correction of the spelling of a word that has been identified as having been misspelled by the FileMaker Pro spell check operation. The option to Check Spelling As You Type must be selected. A word can be corrected only if FileMaker has identified it as being misspelled.

Comments:

This option is normally available via the FileMaker menus. If one or more users have limited access to menu items, it may be necessary to write scripts that give them access to functionality normally available through menus, such as spell check functions. See the Change Password script step for further discussion of this point.

Cut

Compatibility:

Menu Equivalent: Edit, Cut

Syntax: Cut [Select; ]

Options:

Select Entire Contents copies the entire contents of a field to the Clipboard, rather than just the selected portion of the designated fields contents. The field is cleared of its contents.

Go to Target Field or Specify allow you to select the field from which you wish to cut the contents to the clipboard. If no field is specified and nothing is selected, FileMaker Pro cuts the values from all fields of the current record.

Examples:

Enter Browse Mode [ ] Cut [Select, Table1::Recent Notes] Paste [Table1::Previous Notes]

Description:

This script step places the contents of the selected field (or of all fields on the current layout if no field is selected or designated within the script itself) onto the clipboard and then clears the contents of that field.

Comments:

Cut is generally a script step that bears avoiding. It requires that the current layout contain the field to be cut. (This is fragile because the script malfunctions if the field is removed.) Additionally, the contents of the clipboard are overwritten without the consent of the user. Think carefully about whether the intended effect could be accomplished in a layout-independent, less intrusive fashion. Other script steps with the same limitations include Copy, Paste, and Set Selection.

Delete Account

Compatibility:

Menu Equivalent: None

Syntax: Delete Account [Account Name: <account name>]

Options:

Specify allows for the selection or input of the account to be deleted.

Examples:

Delete Account [Account Name: "Regional Sales"]

Description:

This script step deletes the specified account in the current database. Full access is required to complete this operation and an account with full access may not be deleted with this script step. It is possible to specify Run Script with Full Access Privileges to ensure that any user can execute this script. However, care must be taken to ensure that such usage does not create a security hole. After Run Script with Full Access Privileges has been checked, any user who can see the script can run it, including those who have external access from other FileMaker files and web access.

Comments:

It might be desirable to allow access to this functionality via a script if certain users or user groups have limited access to the FileMaker menus because of security configurations. See the Change Password script step for a fuller discussion.

Delete All Records

Compatibility:

Menu Equivalent: Records, Delete All Records

Syntax: Delete All Records [No dialog]

Options:

Perform Without Dialog allows for the deletion of all records in the current found set without user intervention.

Examples:

[View full width]

Show All Records Delete All Records // use a custom dialog to warn user before deleting all records Allow User Abort [ Off ] Set Error Capture [ On ] Show Custom Dialog [ Title: "Delete All Records"; Message: "Are you really sure you want to delete all records?"; Buttons: "Cancel", "Delete" ] If [Get(LastMessageChoice)=2 ] # the user still wants to delete Show Custom Dialog [ Title: "Delete All Records"; Message: "Do you have a current backup?"; Buttons: "No", "Yes" ] If [ Get(LastMessageChoice)=2 ] # after they confirmed twice, go ahead with delete Show All Records Delete All Records[ No dialog ] End If End If

Description:

This script step deletes all records in the current found set. It can be set to operate without user approval if you select the Perform Without Dialog option. Special care should be exercised in the use of this script step because it is not possible to undo the operation after it has been completed.

Comments:

Note that any records that are "in use" by other users are not deleted by this step. Records are considered to be in use if other users are actively editing them and have not committed/saved their changes, or if they have been left open as a result of script actions. You may want to check explicitly whether this has occurred, either by using the Get (RecordOpenCount) function, or by using Get(LastError) to check for a script error. You should also decide how you want to handle cases where the step doesn execute completely for reasons such as these. Note that this script step is context-dependent. The current layout determines which table is active, which determines from which table the records are deleted.

When programming for the Web, be sure to select Perform Without Dialog. Leaving the box unchecked is not web compatible and does not work on the Web.

Delete Portal Row

Compatibility:

Menu Equivalent: None

Syntax: Delete Portal Row [No dialog]

Options:

Perform Without Dialog allows for the deletion of the current related record without user approval.

Examples:

Go to Portal Row [Last] Delete Portal Row [No dialog]

Description:

This script step deletes the currently selected portal row. In other words, it deletes a record thats related to the current record, and is displayed in a portal on the current layout. It can be set to operate without user approval if you select the Perform Without Dialog option. Special care should be exercised in the use of this script step because it is not possible to undo the operation after it has been completed.

Comments:

Performance of this step can be inhibited if the record represented by the specified portal row is in use by another user. See the Delete All Records script step for further discussion. Note that this script step deletes a portal row even if the Allow Deletion of Portal Records check box in the Portal Setup dialog box is unchecked.

When programming for the Web, be sure to select Perform Without Dialog. Leaving the box unchecked is not web compatible and does not work on the Web.

Delete Record/Request

Compatibility:

Menu Equivalent: Records, Delete Record/Request

Syntax: Delete Record/Request [No dialog]

Options:

Perform Without Dialog allows for the deletion of the current record or find request without user approval.

Examples:

Go to Record/Request [Last] Delete Record/Request [No dialog]

Description:

This script step deletes the current record (when in Browse mode) or current find request (when in Find mode). It can be set to operate without user approval if you select the Perform Without Dialog option. Special care should be exercised in the use of this script step because it is not possible to undo the operation after it has been completed.

Comments:

If the current layout has a portal and a portal row is selected, the user is prompted to specify whether the master record or the related record should be deleted. If the step is performed without a dialog, the action automatically applies to the master record. If a portal row is selected and the portal is not set to Allow Deletion of Portal Records, the option to delete a related record never appears. Note that this is in contrast to the Delete Portal Row step, which deletes an active portal row regardless of whether Allow Deletion of Portal Records is enabled or not. Performance of this step can be inhibited if the record is in use by another user. See the Delete All Records script step for further discussion. Note that this script step is context-dependent. The current layout determines which table is active, which determines from which table the record is deleted.

When programming for the Web, be sure to select Perform Without Dialog. Leaving the box unchecked is not web compatible and does not work on the Web.

Dial Phone

Compatibility:

Menu Equivalent: None

Syntax: Dial Phone [No dialog;

]

Options:

Perform Without Dialog prevents the Dial Phone dialog from displaying when this script step executes.

Specify displays the Dial Phone options.

Examples:

Dial Phone [No Dialog, Contacts::Phone_Home]

Description:

This script step allows FileMaker Pro to dial a telephone number from within a script. The number to be dialed may be entered within the script itself, contained within a field, or generated by a specified calculation. Current telephone dialing preferences can be applied optionally based on location information. Letters within telephone numbers are translated into the appropriate numbers (q and z being, of course, omitted). Note: This script step does not work on Mac OS.

Comments:

You might use this script step if you want to be able to dial the phone numbers of people or organizations whose contact information is stored in FileMaker. You might also use it to perform more low-level serial-line tasks, in conjunction with a plug-in that can communicate directly with a computers serial port.

Duplicate Record/Request

Compatibility:

Menu Equivalent: Records, Duplicate Record/Request

Syntax: Duplicate Record/Request

Options:

None

Examples:

Go to Portal Row [Last] Duplicate Record/Request

Description:

This script step duplicates the current record while in Browse mode and the current find request in Find mode. Values in fields with auto-entry options are not duplicated; new values are generated for these fields, according to the details of the specific auto-entry options. If this script step is used when a portal row is selected, and the portal relationship allows for the creation of related records, then the related record is duplicated, rather than the master record.

Comments:

If there are certain fields you want to make certain are never duplicated, you can set them to auto-enter an empty string (""). On duplication, the auto-entry option will take effect and clear the field in the new record.

Edit User Dictionary

Compatibility:

Menu Equivalent: Edit, Spelling, Edit User Dictionary

Syntax: Edit User Dictionary

Options:

None

Examples:

Show Custom Dialog ["Edit the user dictionary?"] If [Get (LastMessageChoice) = 1] Edit User Dictionary End If

Description:

This script step opens the User Dictionary dialog box. This is often used to display the User Dictionary dialog box when user privileges do not allow for the dialog to be chosen directly from the FileMaker menus.

Else

Compatibility:

Menu Equivalent: None

Syntax: Else

Options:

None

Examples:

If [gUsername = "Tom"] Show Custom Dialog ["Hello Tom"] Else If [gUsername = "Raul"] Show Custom Dialog ["Hola Raul"] Else If [gUsername = "Guido"] Show Custom Dialog ["Ciao Guido"] Else Show Custom Dialog ["I don know who you are!"] End If

Description:

This script step can be placed after an If or Else If statement and immediately before an End If statement. The designated code block for the Else statement is executed only if all the previous If and Else If statements have evaluated as false. It is thus often used as a way to deal with values that do not fit within expected parameters or as a default action.

Else If

Compatibility:

Menu Equivalent: None

Syntax: Else If []

Options:

Specify allows for any available fields, functions, and operators to be used to enter the Boolean calculation into the Specify Calculation dialog box. Only a zero (0), false, or null (empty) result is construed as a Boolean false.

Examples:

If [gUsername = "Tom"] Show Custom Dialog ["Hello Tom"] Else if [gUsername = "Raul"] Show Custom Dialog ["Hola Raul"] Else If [gUsername = "Guido"] Show Custom Dialog ["Ciao Guido"] Else Show Custom Dialog ["I don know who you are!"] End If

Description:

This script step must follow the If script step or the Else If script step. It performs an action or actions based on the value of the Boolean calculation. The statements in the Else If block are executed only if none of the previous If or Else If statements are true.

Comments:

There can be an arbitrary number of Else If statements between an If statement and an End If statement. Their Boolean calculations are evaluated in the sequence in which they appear. If one should happen to evaluate to True, then its code block is executed and all subsequent Else If and Else clauses that appear before the End If are ignored.

Enable Account

Compatibility:

Menu Equivalent: None

Syntax: Enable Account [Account Name: <account name>; Activate/Deactivate]

Options:

Specify displays the Enable Account Options dialog box.

Examples:

[View full width]

Enable Account [Account Name:"UserAccount"; Activate/Deactivate]

Description:

This script step enables or disables a specific pre-existing account. For this script step to be performed, the user must be assigned the Full Access privilege set or the Run Script with Full Access Privileges option must be selected. Accounts with Full Access may not be deactivated with this script step.

Comments:

It might be desirable to allow access to this functionality via a script if certain users or user groups have limited access to the FileMaker menus because of security configurations. See the Change Password script step for a fuller discussion.

End If

Compatibility:

Menu Equivalent: None

Syntax: End If

Options:

None

Examples:

If [gUsername = "Tom"] Show Custom Dialog ["Hello Tom"] Else If [gUsername = "Raul"] Show Custom Dialog ["Hola Raul"] Else If [gUsername = "Guido"] Show Custom Dialog ["Ciao Guido"] Else Show Custom Dialog ["I don know who you are!"] End If

Description:

This script step designates the end of an If/Else If/Else structure. See Else and Else If for more information.

End Loop

Compatibility:

Menu Equivalent: None

Syntax: End Loop

Options:

None

Examples:

Set Variable [$counter; "0"] Loop New Record/Request Set Variable [$counter; $counter + 1] Exit Loop If [$counter > 10] End Loop

Description:

This script step marks the end of a Loop structure. The steps between Loop and End Loop are executed until the loop is explicitly exited. This step passes control to the step immediately following the Loop command preceding it.

Comments:

Note that this step doesn cause a loop to stop executing. Without termination logic, a loop will run forever. Use the Exit Loop If script step to establish the conditions under which the loop will stop running and control will pass to the script step immediately following.

Enter Browse Mode

Compatibility:

Menu Equivalent: View, Browse Mode

Syntax: Enter Browse Mode [Pause]

Options:

Pause stops the script steps execution to allow for user data entry and record navigation. The user may resume the script by clicking the Continue button in the Status Area, or by executing a Resume Script script step through a button or directly through the FileMaker Scripts menu.

Examples:

Allow User Abort [Off] Set Error Capture [On] Go To Layout ["Monthly Report] Enter Preview Mode [Pause] Go to Layout [Original Layout] Enter Browse Mode []

Description:

This script step places the current window into Browse mode.

Enter Find Mode

Compatibility:

Menu Equivalent: View, Find Mode

Syntax: Enter Find Mode [Restore; Pause]

Options:

Pause stops the script steps execution to allow for user data entry and record navigation. The user may resume the script by clicking the Continue button in the Status Area, or executing a Resume Script script step through a button or directly through the FileMaker Scripts menu.

Specify Find Requests enables you to create and edit find requests for use with the script step.

Examples:

[View full width]

#an example of a find that is executed from requests stored with the script Go to Layout ["Detail View"] Enter Find Mode [Restore] Perform Find [] #this example waits for the user to enter find criteria and execute the find Go to Layout ["Detail View"] Enter Find Mode [Pause] Perform Find[]

Description:

This script step places the current layout into Find mode. In Find mode, find requests may be created, edited, deleted, and duplicated. In addition, find requests can be stored with the script step if you check the Restore check box and using the Specify dialog. String multiple find requests together to create complex find requests. A single find request may either omit records from or add them to the existing found set.

Comments:

Enter Find Mode is one of several script steps that is capable of saving complex options along with the script step. Other such script steps are Perform Find, Sort Records, Import Records, Export Records, and Print Setup. Use the Pause option if you want the user to be able to enter his own search criteria, or modify a search thats saved with the script. If the status area is visible, the user sees a Continue button, as well as a Cancel button if Allow User Abort is set to "on" in the script. Be sure to set Allow User Abort to "off" if you don want to offer an option to cancel the script at that point. If the status area is hidden, these buttons won be accessible, and the user needs to either show the status area or use keyboard equivalents for Continue (Enter or Return) or Cancel (Escape or images/U2318.jpg border=0>-period).

Enter Preview Mode

Compatibility:

Menu Equivalent: View, Preview Mode

Syntax: Enter Preview Mode [Pause]

Options:

Pause stops the script steps execution to allow for user inspection of the preview for the designated layout. The user may resume the script by clicking the Continue button.

Examples:

Enter Preview Mode [Pause]

Description:

This script step places the current layout into Preview mode, where an approximation of what a layout will look like when it is printed out is displayed. Preview mode is helpful for viewing layouts that use special layout parts for reporting, title headers, leading grand summaries, subsummaries, trailing grand summaries, and title footers. Preview is the only FileMaker mode that displays all layout parts correctly. (Subsummary parts do not display correctly in Browse mode.)

Comments:

Use the Pause option if you want the user to be able to spend time in Preview mode working with the displayed data. If the status area is visible, the user sees a Continue button, as well as a Cancel button, if Allow User Abort is set to "on" in the script. Be sure to set Allow User Abort to "off" if you don want to offer an option to cancel the script at that point. If the status area is hidden, these buttons aren accessible, and the user needs to either show the status area or use keyboard equivalents for Continue (Enter or Return) or Cancel (Escape or images/U2318.jpg border=0>-period).

Execute SQL

Compatibility:

Menu Equivalent: None

Syntax:

Execute SQL [No Dialog; ODBC: ; ]

Options:

Perform Without Dialog prevents the Specify SQL dialog box, the Select ODBC Data Source dialog box, and the Password dialog box from displaying when the script step executes.

Specify displays the Specify SQL dialog box, where you can set the following options:

Examples:

[View full width]

Execute SQL [No Dialog; ODBC: SQL_Server; "UPDATE Customers SET Status = " & Customer::Status & " where CustID = " & Customer ::CustomerID & " ;"]

Description:

This script step executes a designated SQL query over a selected ODBC connection. This allows for manipulation of SQL data sources through standard queries. A script can contain multiple Execute SQL steps that act on different SQL data sources.

Comments:

The Execute SQL step opens a great many avenues in FileMaker development.

Exit Application

Compatibility:

Menu Equivalent: FileMaker Pro, Quit FileMaker Pro (Mac OS); File, Exit (Windows)

Syntax: Exit Application

Options:

None

Examples:

Exit Application

Description:

This script step closes all open files and exits the FileMaker Pro Application.

Comments:

The Exit application triggers the closing scripts of any files that have a closing script attached.

Exit Loop If

Compatibility:

Menu Equivalent: None

Syntax: Exit Loop If []

Options:

Specify allows for the definition of the Boolean calculation that decides whether the loop is exited or not.

Examples:

Set Field [Table1::gCounter; "0"] Loop New Record/Request Set Field [Table1::gCounter; Table1::gCounter + 1] Exit Loop If [gCounter > 10] End

Description:

This script step terminates a loop if the Boolean calculation evaluates to True (non-zero and non-null). Upon termination, control is passed to the next script step after the End Loop script step that applies to the current script step. If the Boolean calculation evaluates to False (zero or null), then control is passed to the next script step, or to the step at the beginning of the loop if no further steps are specified within the loop.

Comments:

Youll probably want to have at least one Exit Loop If script step inside any loop you write. Without at least one such statement, its difficult to exit the loop, except by performing a subscript that performs a Halt Script or using a Go To Record/Request/Page [Next; Exit after last] script step.

Exit Script

Compatibility:

Menu Equivalent: None

Syntax: Exit Script [Result]

Options:

You can use Specify to specify a value to be returned from the script as the script result. This result will be accessible via the Get(ScriptResult) function.

Examples:

Perform Find [Restore] If [Get (CurrentFoundCount)=0] Show All Records Go to Layout ["Detail View"] Exit Script Else Print [] End

Description:

Exit Script forces the current script to stop executing. No further script steps in the current script will execute. If the current script was called by another script, the remaining script steps in the calling script will continue to execute.

Comments:

Its important to distinguish this script step from the related script step Halt Script. Halt Script forces the termination of all currently running scripts, whereas Exit Script simply exits the current script.

The capability to return a script result is an important new feature of FileMaker 8. A script result is accessed via the Get(ScriptResult) function. Note that the Exit Script step is the only way to return a result from a script.

Export Field Contents

Compatibility:

Menu Equivalent: Edit, Export Field Contents

Syntax: Export Field Contents [; ""]

Options:

Specify Target Field allows for the specification of the field whose contents are to be exported.

Specify Output File allows the desired filename and file path for the exported data to be specified.

Examples:

[View full width]

Go to Layout [Pictures::Agent_Picture] Export Field Contents [Pictures::Picture_Full; Pictures::filename]

Description:

Export Field Contents creates a named file on disk with the contents of the specified field.

Comments:

Export Field Contents is a very powerful and flexible command when used in conjunction with container fields. FileMaker Pro allows the user to store a file of any type in a container field (including FileMaker Pro files). Export Field Contents writes the file out to disk in its native format, where the file can then be opened with the appropriate application. Any type of file, including images, of course, can be saved in a FileMaker database and written out to disk.

Using the new script variables feature of FileMaker 8, it is possible to set the name and path of the output file dynamically, rather than hard-coding a file reference within the script.

Export Records

Compatibility:

Menu Equivalent: File, Export Records

Syntax: Export records [No dialog; ""]

Options:

Perform Without Dialog prevents the display of dialog boxes that let the user set new export criteria when the script step executes.

Specify Output File allows the desired filename and file path for the exported data to be specified as well as its file type. If XML Export is selected, then the XML Export Options dialog is displayed and allows the selection of an appropriate XML grammar and stylesheet for the export.

In FileMaker 8, you can export records directly to the Excel file format by choosing Excel from among the available file types. Specify Export Order displays the export order that was in effect when you added the script step. The last export order used in the file appears as the default and can be edited or deleted.

Examples:

Export Records [No dialog, "Contracts"]

Description:

This script step exports records from the current found set to a specified file in a specified format. The current sort order of the found set is used for the export order of the records. Note that Group By works only for fields that are included in the current sort order. (Sorted fields appear in the Group By box; check off any fields in which you want to group by.)

Comments:

Using the new script variables feature of FileMaker 8, it is possible to set the name and path of the output file dynamically, rather than hard-coding a file reference within the script.

Because its possible to create FileMaker field names that are not valid names for XML elements, use extreme caution when exporting in the FMPDSORESULT grammar; the resulting XML may be invalid. FMPDSORESULT is deprecated in this version of FileMaker Pro and should probably be avoided.

Extend Found Set

Compatibility:

Menu Equivalent: Requests, Extend Found Set

Syntax: Extend Found Set [Restore]

Options:

Specify Find Requests allows for the creation and storage of find requests with the script step.

Examples:

[View full width]

#This script finds employees that are local or have a specific zip code Set Error Capture [On] Allow User Abort [Off] Enter Find Mode [ ] Set Field [Local; "Yes"] Perform Find [ ] Enter Find Mode [ ] Set Field [Zip; "94965"] Extend Found Set[]

Description:

This script step allows the current found set to be extended if you append additional search criteria to the previous search or, put differently, if you apply designated search criteria only to records not included in the current found set. (This is equivalent to a logical OR search combined with the results of the previously executed search.)

Comments:

Similar to the Constrain Found Set script step, this step enables you to combine the results of more than one search. Whereas Constrain Found Set enables you to limit the results of one found set by the results of a second search (an operation known as an intersection), the Extend Found Set command enables you to add the results of one search to the results of another search (an operation known as a union).

Flush Cache to Disk

Compatibility:

Menu Equivalent: None

Syntax: Flush Cache to Disk

Options:

None

Examples:

[View full width]

Replace Field Contents [Line_Items::ProductID; Line_Items::NewProductID] Flush Cache to Disk

Description:

This script step causes FileMaker Pros internal disk cache to be written to disk. This operation is normally performed periodically or after structural changes such as defining fields or modifying calculation definitions. Flush Cache to Disk enables the developer to explicitly write out the contents of memory.

Comments:

Note that this script step flushes the contents of the cache for a local client copy of FileMaker Pro. It has no effect on the cache of any instance of FileMaker Server.

Freeze Window

Compatibility:

Menu Equivalent: None

Syntax: Freeze Window

Options:

None

Examples:

[View full width]

Freeze Window Replace Field Contents [Line_Items::ProductID; Line_Items::NewProductID] Sort [Restore; No Dialog] Refresh Window

Description:

This script step halts the updating of the active window as script steps are performed. The window resumes refreshing either at the end of the script where it was frozen or after a Refresh Window script step is executed within a script.

Comments:

Freeze Window is useful in creating more professional-looking applications because it prevents the screen from flashing or redrawing while other script steps execute (for example, those that navigate to "utility" layouts, perform some work there, and then return to a main interface layout). Its also possible to realize some performance gains from freezing a window; scripts that would otherwise cause changes to the contents or appearance of the active window run more quickly if the active window doesn need to be refreshed.

Go to Field

Compatibility:

Menu Equivalent: None

Syntax: Go to Field [Select/perform; ]

Options:

Select/Perform directs FileMaker to select all contents of the designated field. If the field is a container field and an action is associated with that field (such as playing a movie or sound file), then that action is performed.

Go to Target Field allows for the specification of the field to go to, using the standard FileMaker Pro field selection dialog box.

Examples:

Enter Browse Mode [] Go to Layout ["Contracts"] New Record/Request Go to Field [Contracts::Signatory]

Description:

This script step selects a specified field in the current layout. If the Select/Perform option is selected, then if an action is associated with a field, that action is performed. (Actions would be associated with container field types, such as sound files or moviesin these cases, the associated action would be to play the sound or movie file.) In cases where there is no implied action, the entire contents of the field are selected.

Comments:

Go to Field allows the developer to insert the cursor into a specific field after a record has been created from a script.

Like other script steps such as Cut, Copy, and Paste, this step depends on the specified field being present on the current layout.

Go to Layout

Compatibility:

Menu Equivalent: None

Syntax: Go to Layout [""]

Options:

Specify allows the target layout to be selected. The following choices are available:

An existing layout may also be specified directly by name.

Examples:

Go to Layout ["Contracts"] Copy [Select; DataTable1::ID_Number] Go To Layout [Original Layout]

Description:

This script step makes the specified layout active in the current file. This step can navigate only to layouts in the currently active file. In the case where multiple layouts have the same name, the first match is selected for a calculated layout name.

Comments:

This script step is vital for establishing the proper context for any subsequent script steps that operate on record data. Any script steps that directly deal with FileMaker data or records will do so in the context of the table occurrence of the currently active layout.

Its also possible to draw either the name or the number of a layout from a calculation.

Go to Next Field

Compatibility:

Menu Equivalent: None

Syntax: Go to Next Field

Options:

None

Examples:

Go to Field [Table1::First Name] Set Field [Table1::gCounter; "0"] Loop Set Field [Table1::gCounter; Table1::gCounter + 1] Exit Loop If [gCounter > Table1::ActiveField] Go To Next Field End Loop

Description:

This script step moves to the next field in the established tab order for the current layout. If no field is selected, the first field in the established tab order for the current layout is selected. If the user regains control, either by pausing in Browse mode or by exiting the script, the cursor remains in the selected field. If there is no tab order on the layout, the fields are traversed in the order in which they were added to the layout.

Comments:

Note that this script can override the effect of field behaviors that prevent entry into a field.

Go to Portal Row

Compatibility:

Menu Equivalent: None

Syntax: Go to Portal Row []

Options:

First selects the first row of the currently active portal.

Last selects the last row of the currently active portal.

Previous selects the previous row of the currently active portal. If the Exit After Last option is selected and the script is currently performing a loop, then an Exit Loop action is performed when the first row in the designated portal is reached.

Next selects the next row of the currently active portal. If the Exit After Last option is selected and the script is currently performing a loop, then an Exit Loop action is performed when the last row in the designated portal is reached.

By Calculation selects the row number determined by the designated calculation.

Examples:

Go to Portal Row [Select, First]

Description:

This script step allows navigation among related records in the active portal on the current layout. If no portal is active, then the first portal in the layout stacking order is assumed. This step attempts to maintain the selected portal field when it changes rows. If no field is selected, the first enterable field is selected in the new row.

Go to Previous Field

Compatibility:

Menu Equivalent: None

Syntax: Go to Previous Field

Options:

None

Examples:

Go to Previous Field

Description:

This script step moves focus to the previous field in the current layouts tab order. If no field is selected, then the last field in the current layouts tab order is selected. If the user regains control, either by pausing in Browse mode or by exiting the script, the cursor will remain in the selected field. If there is no tab order on the layout, the fields are traversed in the order in which they were added to the layout.

Comments:

Note that this script can override the effect of field behaviors that prevent entry into a field.

Go to Record/Request/Page

Compatibility:

Menu Equivalent: None

Syntax: Go to Record/Request/Page []

Options:

First moves to the first record in the current found set, displays the first find request, or moves to the first page of the currently displayed report if in Preview mode.

Last moves to the last record in the current found set, displays the last find request, or moves to the last page of the currently displayed report.

Previous moves to the previous record in the current found set, displays the previous find request, or moves to the previous page of the currently displayed report. If the Exit After Last option is selected and the script is currently performing a loop, then an Exit Loop action is performed when the first record is reached; otherwise no action is taken. If the record pointer is already on the first page, FileMaker generates an error code of 101, which is not reported to the user.

Next moves to the next record in the current found set, displays the next find request, or moves to the next page of the currently displayed report. If the Exit After Last option is selected and the script is currently performing a loop, then an Exit Loop action is performed when the last record is reached; otherwise no action is taken. If the record pointer is already on the last page, FileMaker generates an error code of 101, which is not reported to the user.

By Calculation selects the record, find request, or report page determined by the designated calculation.

Examples:

[View full width]

# A very inefficient way of counting records Go To Record/Request/Page [First] Set Variable [$count; "0"] Loop Set Variable [$count; $count + 1] Go To Record/Request/Page [Next; Exit After Last] End Loop # $count now contains the number of records in the found set. # This could have been more easily accomplished by: # Set Variable [$count; Get(FoundCount)]

Description:

This script step moves to a record in the found set if the file running the script is in Browse mode, to a find request if it is in Find mode, and to a report page if it is in Preview mode. This step can also be configured to exit a loop when either the first or last record has been reached.

Go to Related Record

Compatibility:

Menu Equivalent: None

Syntax:

Go to Related Record [From table: "

"; Using layout ""]

Options:

Get Related Record From allows the selection of a table thats related to the current table. If an appropriate table is not in the list or if you need to add or change a relationship, Define Database displays the Define Database dialog box, where you can create or edit relationships.

Use External Tables Layouts opens the file containing the external table you specify and displays any related record(s), using the specified layout in that file.

Show Record Using Layout displays related record(s), using the specified layout in the current file.

Show Related Records Only creates a found set in the related table containing only related records. For example, if you use this script step on a relationship that has four matching records in Table B for the current record in Table A, this option replaces any current found set in Table B with a new found set of just these four records. If the relationship has a sort order applied in the table occurrence to which you e navigating, this option causes the found set to be sorted by the relationships sort criteria. If the Show Related Records Only option is not selected, the resulting found set is not sorted.

Match current record only will find only those records in the related table that are a match for the current record in the current table. This corresponds to the behavior of the Go To Related Records script step in previous versions of FileMaker.

Match all records in the current found set will find records in the related table that are a match for any record in the current found set in the current table. This capability is new in FileMaker 8.

Examples:

[View full width]

#The following example goes to a related record in the table "LineItems" and shows a found set of related records only. Go to Related Record [Show only related records; From table: "LineItems"; Using layout: "List View"]

Description:

This script step goes to the table designated by the relationship selected in the script step, bringing its window to the foreground and selecting the first related record in the process. This step also works with portals. If a portal row is selected and the Go to Related Record stepspecifying the portals relationshipis executed, then the related table is brought to the forefront and the row that was selected in the portal corresponds to the record that is selected in the related table. This step may also use relationships to external files so that when the step is executed, the selected external file is opened and brought to the forefront, with its found set consisting of related records only. Further, if a layout was selected, then the records are displayed in that layout.

Comments:

This script step goes to one or more records in a related table (that is, a table that is related to the currently active table by one or more relationships in the Relationships Graph). There are a number of options to this script step, and they relate in somewhat complex ways. If more than one record in the target table is related to the current record in the table where the script is being called, FileMaker selects the first related record in the target table. If the relationship has a sort order on the target table, that sort order is used to determine which is the first of several related records. For example, if you have a table of Customers and a table of Orders, and a relationship between the two that is sorted on the Order side by OrderDate ascending, then the "first" related record when navigating from a specific customer to related orders is a given customers earliest order. If the relationship has no sort order specified on the target table, then the first record is determined based on the creation order of the related records.

As part of this script step, you need to determine the layout that should be used to display the related records. Most likely, youll want it to be a layout tied to a table occurrence thats based on the target table. If the target table is part of an externally referenced file, you may choose to display the records on a layout in the external file. If you choose to do so, that file comes to the forefront. You may also choose to display the related record set in a new window. If you choose to do so, you can specify a set of new window options, such as the window name, height, width, and screen position. One unfortunate limitation is that you can direct the related records to appear in an existing window other than the currently active one. If you had to have that effect, you could select the desired target window, capture its name, dimensions, and positions into global fields, and then close that window and create a new window with exactly the same dimensions and use that as the target of this script step.

If the option to Show Related Records Only is checked, FileMaker creates a found set in the target table that contains only those records that are related to the current record or the current found set in the table in which the script is executing. For example, given a table of Salespeople and a table of Orders related to Salespeople by a SalespersonID field, if you issue a Go to Related Record[From table:"Orders"; Using layout ""][Show only related records] while on a record in Salespeople, you end up with a found set of only those Orders related to the current Salesperson by the SalespersonID. If the option to Show Only Related Records is unchecked, the behavior is more complex: If theres a found set on the target layout and the first related record is within that found set, the found set is unchanged. If theres a found set on the target layout and the first related record is outside that found set, all records in the target table are found (though only the first related record is selected). If there is no found set on the target layout (that is, all records are currently found), that remains the case. No matter whether Show Related Records Only is checked or not, and no matter what the state of any found set on the target layout is, the first related record is always selected. If there are no related records, no navigation takes place, and a FileMaker Error of 101 is generated.

Halt Script

Compatibility:

Menu Equivalent: None

Syntax: Halt Script

Options:

None

Examples:

[View full width]

# Example of using Halt Script to return control immediately back to the user. Show Custom Dialog ["Print Report?"] If [Get (LastMessageChoice) = 2] Halt Script End If Print[]

Description:

This script step causes all script activity to stop immediately. All scripts, subscripts, and external scripts are canceled and the system is left in whatever state it was in when the Halt step was executed. Halt Script is different from Exit Script in that the latter merely aborts the current subscript and allows the script that called the subscript to continue running, whereas the former stops all script activity, whether it is run from a subscript, a sub-subscript, and so on.

If

Compatibility:

Menu Equivalent: None

Syntax: If []

Options:

Specify allows the definition of the Boolean calculation by which the If step determines its branching.

Examples:

If [gUsername = "Tom"] Show Custom Dialog ["Hello Tom"] Else if [gUsername = "Raul"] Show Custom Dialog ["Hola Raul"] Else If [gUsername = "Guido"] Show Custom Dialog ["Ciao Guido"] Else Show Custom Dialog ["I don know who you are!"] End If

Description:

The If step introduces a block of conditional logic. It needs to be used with an End If statement and, optionally, one or more Else and Else If statements. This script step contains a calculation, which should perform a logical true/false test. If the specified Boolean calculation results in a 1 (or any number greater than 1), the specified action(s) will be performed. If the specified Boolean calculation results in a 0 (or nothing or any non-number), then the specified action(s) will be skipped and control passed to the next Else If or Else clause. If there are no more such clauses, then control passes to the End If step and proceeds to any subsequent steps. Else If and Else clauses are optional. End If is required when If is used.

Comments:

If you don provide a Boolean test in the If step, it defaults to a result of False.

Import Records

Compatibility:

Menu Equivalent: File, Import Records

Syntax:

Import Records [No dialog; ""; Add/Update existing/Update matching;

]

Options:

Perform Without Dialog prevents the display of FileMaker Pros Import Records dialog box, which enables the user to select a file from which to import, to set new import criteria, to map fields from import to target fields, and to see a summary of facts about the import after it has been successfully completed.

Specify Data Source allows for the selection of the source for the data to be imported. Data can be imported into FileMaker Pro from a file, a folder of files, a digital camera (Mac OS), an XML data source, or an ODBC data source.

Specify Import Order allows the order in which FileMaker imports records to be set. The last import order is used as the default for the subsequent import. This option allows control of how FileMaker is to handle repeating field data, either by splitting it among new records or keeping it together as a repeating field in the destination table. Also, the import can be made to add new records with the imported data, to replace the records in the found set with the imported data, or to attempt to reconcile data by matching keys (ID fields).

Examples:

[View full width]

Import Records [Restore; No dialog; "Contacts"; Mac Helvetica]

Description:

This script step imports records from another file or data source specified either dynamically through the Import Records dialog or within the script step configuration itself. Import order can be specified as either manually defined or based on matching field names. (It is important to note that when import source fields and target fields are mapped with matching names, field name matching is performed dynamically each time the script step is performed.)

FileMaker Pro 8 has the capability to create a new table in the target database when importing data. When this option is selected, the imported data will be used to create a new table. The field names in the new table will depend on the data sourceif its a data source, such as an XML file or an Excel file with headers, that contains field name information, FileMaker will use the provided field names. Otherwise, FileMaker will name the fields f1, f2, f3, and so on.

Note that this capability is different from the one in FileMaker Pro 8 Advanced to import table definitions from another file. That technique will import only the table definition, not any data within the table, whereas specifying a new table as an import target will always populate the new table with the imported data.

Insert Calculated Result

Compatibility:

Menu Equivalent: None

Syntax: Insert Calculated Result [Select; ; ]

Options:

Select Entire Contents replaces the contents of a field. If this option is not selected, Insert Calculated Result replaces only the selected portion of the current field, or inserts the result at the insertion point. The default insertion point is at the end of the fields data.

Go to Target Field allows the selection of the field into which the result of the specified calculation is to be inserted. The specified field must be available and modifiable on the current layout for this script step to operate properly.

Calculated Result allows the definition of a calculation whose result is inserted into the specified target field by this script step.

Examples:

[View full width]

Insert Calculated Result [Books::Author; Get (AccountName)]

Description:

This script step pastes the result of a calculation into the current (or specified) field on the current layout.

Comments:

In a web-published database, use a Commit Record/Request script step after an Insert Calculated Result script step to update the record in the browser window. All of the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker will generate an internal error of 102.

Insert Current Date

Compatibility:

Menu Equivalent: Insert, Current Date

Syntax: Insert Current Date [Select; ]

Options:

Select Entire Contents replaces the contents of the selected field with the current date. If this option is not selected, then the current date is appended to the end of the current contents of the field.

Go to Target Field allows for the selection of the field into which the current date will be inserted.

Examples:

New Record/Request Go To Layout ["Invoice"] Insert Current Date [Select; Invoices::Invoice Date]

Description:

This script step pastes the current system date into the specified field on the current layout.

Comments:

In a web-published database, use a Commit Record/Request script step after an Insert Current Date script step to update the record in the browser window. All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Insert Current Time

Compatibility:

Menu Equivalent: Insert, Current Time

Syntax: Insert Current Time [Select; ]

Options:

Select Entire Contents replaces the contents of the selected field with the current time. If this option is not selected, then the current time is appended to the end of the current contents of the field.

Go to Target Field allows for the selection of the field into which the current time is to be inserted.

Examples:

New Record/Request Go To Layout ["Invoice"] Insert Current Date [Select; Invoices::Invoice Date] Insert Current Time [Select; Invoices::Invoice Time]

Description:

This script step pastes the current system time into the specified field on the current layout.

Comments:

In a web-published database, use a Commit Record/Request script step after an Insert Current Time script step to update the record in the browser window. All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Insert Current User Name

Compatibility:

Menu Equivalent: Insert, Current User Name

Syntax: Insert Current User Name [Select; ]

Options:

Select Entire Contents replaces the contents of the selected field with the current username. If this option is not selected, then the current username is appended to the end of the current contents of the field.

Go to Target Field allows for the selection of the field into which the current user name is to be inserted.

Examples:

[View full width]

New Record/Request Go To Layout ["Invoice"] Insert Current Date [Select; Invoices::Invoice Date] Insert Current Time [Select; Invoices::Invoice Time] Insert Current User Name [Select; Invoices: :Entered_By]

Description:

This script step pastes the current username into the specified field on the current layout.

Comments:

In a web-published database, use a Commit Record/Request script step after an Insert Current User Name script step to update the record in the browser window. All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Insert File

Compatibility:

Menu Equivalent: Insert, File

Syntax: Insert File [Reference; ; ""]

Options:

Store Only a Reference instructs FileMaker Pro to store only a link to a file in the container field, rather than the entire file. This option may reduce the size of your FileMaker Pro file, but if you move or delete the file being referenced, FileMaker Pro can display it.

Select Go to Target Field or click Specify to specify the container field into which to insert the selected file.

Select Specify Source File or click Specify to designate the file to be inserted.

Examples:

Go To Field [Photos::Thumbnail] Insert File ["house_thumb. jpg"]

Description:

This script step inserts a file into a selected container field on the current layout. Files may be stored in their entirety within FileMaker Pro, or you may choose to store only a file reference. File references certainly take up much less space within the database but they remove an element of control over a databases behavior. Files stored by reference can be moved or deleted, whereas this is much more difficult to achieve within FileMaker itself.

Comments:

All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Insert from Index

Compatibility:

Menu Equivalent: Insert, From Index

Syntax: Insert From Index [Select; ]

Options:

Select Entire Contents replaces the contents of the selected field. If this option is not selected, then the selected index value is appended to the end of the current contents of the field if the field does not contain the cursor, or at the current cursor position if it does.

Go to Target Field allows for the selection of the field into which the selected index value is to be inserted.

Examples:

Enter Find Mode [ ] Insert From Index [Users::User_Name] Perform Find [ ]

Description:

This script step displays the index (if one exists) of the designated field in a dialog box and allows one of its values to be inserted into the field. If the Select Entire Contents option is selected, the contents of the field will be replaced with the selected value. If this option is not selected, then the value is inserted either at the position of the cursor in the field or appended to the end of the fields contents, depending on whether or not the field has the cursor in it. Note: If the specified field does not exist on the layout where the script is being performed or indexing has been disabled for the selected field, Insert from Index returns an error code, which can be captured with the Get(LastError) function.

Comments:

All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Insert from Last Visited

Compatibility:

Menu Equivalent: Insert, From Last Visited Record

Syntax: Insert From Last Visited [Select; ]

Options:

Select Entire Contents replaces the contents of the selected field. If this option is not selected, then the value from the last visited field is appended to the end of the current contents of the field if the field does not contain the cursor, or at the current cursor position if it does.

Go to Target Field allows for the selection of the field into which the last visited field value is to be inserted.

Examples:

Go to Record/Request/Page [Next] Go to Field [Vendor Name] Insert From Last Visited [] #Will use vendor from previous record

Description:

This script step pastes the value of the specified field from the same field in the last active record. This step is compatible with both Find and Browse mode. A record is considered as having been active if it has been operated upon by FileMaker Pro in some way.

Comments:

In a web-published database, use a Commit Record/Request script step after an Insert From Last Visited script step to update the record in the browser window. All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Insert Object

Compatibility:

Menu Equivalent: Insert, Object

Syntax: Insert Object [""]

Options:

Specify displays the Insert Object dialog box.

Object Type allows the selection of the type of object to embed or link from the list of available file and application types.

Create New embeds a blank object of the specified object type.

Create from File allows the specification of the name of an existing file as the object to be embedded or linked.

When Create from File has been selected, Link can be selected to indicate that the object should be a linked object. When Link is not selected, the object is embedded instead.

Display As Icon tells FileMaker Pro not to display the embedded or linked object completely, but to display an icon that represents the object. The Change Icon button can be used to select a different icon for display. When Display As Icon is not selected, the complete object is displayed in the container field.

Examples:

Go to Field [Profile::Greeting] Insert Object ["Video Clip"]

Description:

This Windows-specific script step allows the user, through the Insert Object dialog box, to select an OLE object and insert it into the current container field. If the specified object/file does not exist on the computer on which the script is being run, Insert Object returns an error code that can be captured with the Get(LastError) function.

Comments:

All of the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102. Insert Object works only on the Windows platform. Insert Object returns an error code if run on the Mac OS.

Insert Picture

Compatibility:

Menu Equivalent: Insert, Picture

Syntax: Insert Picture [Select; ]

Options:

Store Only a Reference to the File allows graphics to be stored by file system reference, thereby alleviating the need to store the actual image in the database. However, if the file is moved from the designated file path, FileMaker Pro can no longer display it.

Specify Source File or Specify allow the designation of the file path to the desired image file.

Examples:

Go to Field [Profile::Greeting] Insert Picture ["headshot.jpg"]

Description:

This script step imports an image file into the current container field. The desired field must be selected before this script is run. If the desired image file has not been specified, the user is given the Insert Picture dialog box.

Comments:

All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Insert QuickTime

Compatibility:

Menu Equivalent: Insert, QuickTime

Syntax: Insert QuickTime [""]

Options:

Specify Source File or Specify allow the designation of the file path to the desired QuickTime file.

Examples:

Go to Field [Profile::Interview] Insert Picture ["Interview_Video"]

Description:

This step imports a QuickTime movie or sound file into the current container field. A container field must be selected before this step can function. If an appropriate QuickTime file has not been designated, a dialog box is presented to the user, through which she may select and preview the file to be imported. This step requires that QuickTime be installed on the system being used to import the desired file.

Comments:

All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Insert Text

Compatibility:

Menu Equivalent: None

Syntax: Insert Text [Select; ; ""]

Options:

Select Entire Contents replaces the contents of a field. If this option is not selected, Insert Text inserts the specified value at the end of the fields data.

Use Go to Target Field or click Specify to specify the field to receive the pasted information. If no field is selected, the Insert Text command places the specified text after the insertion point. If no field is active at the time the command executes, it has no effect. If the selected field is not present on the current layout, the Insert Text command has no effect.

Specify displays the Specify dialog box where you can enter the text to be pasted.

Examples:

Insert Text [Select; Profile::Favorite_Color; "Red"]

Description:

This script step inserts text into the selected text field in the current record. If the Select Entire Contents option has not been selected, then the designated text is inserted at the cursor position or at the end of the fields contents, depending on whether or not there is a cursor in the field. The text to be inserted needs to be specified explicitly. If you want to insert variable text data, use the Insert Calculated Result script step or the Set Field script step.

Comments:

In a web-published database, use a Commit Record/Request script step after an Insert Text script step to update the record in the browser window. All the Insert... functions depend on the presence of fields on the current layout. If the correct field is not present, FileMaker generates an internal error of 102.

Install Menu Set

Compatibility:

Menu Equivalent: None

Syntax: Install Menu Set [specified menu set name]

Options:

Use As File Default will cause the specified menu set to be used as the default menu set for the current file, for the duration of the current user session. The default menu set will be displayed in all circumstances where it is not overridden by a more specific menu set. Examples of "more specific" settings include menu sets that are specified at the individual layout level, and menu sets installed by later invocations of the Install Menu Set script step.

Examples:

# Install a user-specific menu set If [$userRole = "Sales"] Install Menu Set["SalesMenus"] Else Install Menu Set["RegularMenus"] End If

Description:

This script step will install a new menu set based on the specified menu set name. This may be a custom menu set (defined by a developer using FileMaker Pro Advanced) or it may be the default FileMaker menu set.

Comments:

This script step affects only the current user. Others who may be using the file simultaneously will not see a change of menu sets, unless they too invoke a script containing this step. Likewise, when the current user closes the file, the effects of this step will be terminated.

Loop

Compatibility:

Menu Equivalent: None

Syntax: Loop

Options:

None

Examples:

# Create 10 new blank records Set Field [Table1::gCounter; "0"] Loop New Record/Request Set Field [Table1::gCounter; Table1::gCounter + 1] Exit Loop If [gCounter > 10] End

Description:

This script step marks the beginning of a Loop structure. The end of the Loop structure is defined by a matching End Loop step. Script control passes from the Loop step through all intervening steps to the End Loop step and back again until an Exit Loop directive is encountered or until a Halt Script or Exit Script step is encountered. The Exit Loop directive is available as an option with the Exit Loop If step, the Go To Record/Request/Page step, and the Go To Portal Row step. Loops are often used to perform an action over a group of records or portal rows.

Modify Last Find

Compatibility:

Menu Equivalent: Records, Modify Last Find

Syntax: Modify Last Find

Options:

None

Examples:

[View full width]

Modify Last Find Set Field [Contacts::Birthdate; "1/1/1974. . 1/1 /1985"] Perform Find[]

Description:

This script step activates Find mode and then recalls the last find request(s) used. The find request(s) may then be modified and executed with the Perform Find script step.

Move/Resize Window

Compatibility:

Menu Equivalent: None

Syntax:

Move/Resize Window [Current Window or Name: ; Height: ; Width: ; Top: ; Left: ]

Options:

Specify allows the setting of the move/resize options.

Current Window causes the changes to be performed on the current window.

Window Name causes the changes to be performed on an open window, specified by name. Literal text may be entered or Specify clicked to create a window name from a calculation.

Current File Only causes FileMaker to search only within windows based on table occurrences from within the current file.

Height is the height of the adjusted window in pixels. A number may be entered or Specify can be clicked to generate a number from a calculation.

Width is the width of the adjusted window in pixels. A number may be entered or Specify can be clicked to generate a number from a calculation.

Distance from Top is the adjusted windows distance in pixels from the top of the screen (Mac OS) or top of the FileMaker Pro window (Windows). A number may be entered or Specify clicked to generate a number from a calculation.

Distance from Left is the adjusted windows distance in pixels from the left of the screen (Mac OS) or left of the FileMaker Pro window (Windows). A number may be entered or Specify clicked to generate a number from a calculation.

Examples:

[View full width]

Move/Resize Window [Name:Invoices ; Height: 400; Width: 600; Top: 16; Left: 16]

Description:

This script step adjusts the size and location of the selected window. Every other aspect of the window, including found set, current table, and current record remain unchanged. Where an option is left without a value, the current value of that option is used. If position or size options exceed or fall below allowable minimums or maximums for a machines particular operating system and configuration, the allowed minimums or maximums are used instead of the chosen values. In multiple-monitor environments, the use of negative position values makes it possible to position a window on monitors other than the main monitor. Note for Windows: FileMaker Pro orients the moved window to the top-left corner of the visible part of the application window. Note that this may not be the (0, 0) point of the window, depending on how the current file window is positioned (for example, if half of the file window extends past the left border of the application window, you would need to scroll to the left to see the [0, 0] point of the application window).

Current File Only is a window management option thats new to FileMaker 8. In FileMaker 7, window management script steps could sometimes be "fooled" by the presence of windows from other files with the same name as the desired script step target, causing the script step to act on a window different from the desired one. In FileMaker 8, the developer can restrict the scope of window management script steps to consider only windows based on the current file.

New File

Compatibility:

Menu Equivalent: File, New Database

Syntax: New File

Options:

None

Examples:

New File

Description:

This script step enables the user to create a new database file in FileMaker Pros usual Create New File dialog box. If the Show Templates in New Database Dialog Box preference is selected, then the script step shows the New Database dialog box.

Comments:

The user is taken to the Define Database dialog. When hes finished defining the new database, and has closed the Define Database dialog, the script that invoked the New File command continues. The new database stays open, but it is not activated.

New Record/Request

Compatibility:

Menu Equivalent: Records, New Record

Syntax: New Record/Request

Options:

None

Examples:

# Create 10 new blank records Set Variable [$counter; "0"] Loop New Record/Request Set Variable [$counter; $counter + 1] Exit Loop If [$counter > 10] End

Description:

This script step creates a new, blank record if the system is in Browse mode, and a new find request if the system is in Find mode.

Comments:

Note that this script step is context-dependent. The current layout determines which table is active, which determines in which table the record is created.

New Window

Compatibility:

Menu Equivalent: Window, New Window

Syntax:

New Window [Name: ; Height: n; Width: n; Top: n; Left: n]

Options:

Specify allows the setting of options for the new window.

Window Name is the name specified for the new window. Literal text may be entered or Specify clicked to create a window name from a calculation.

Height is the height of the new window in pixels. A number may be entered or Specify clicked to generate a number from a calculation.

Width is the width of the new window in pixels. A number may be entered or Specify clicked to generate a number from a calculation.

Distance from Top is the new windows distance in pixels from the top of the screen (Mac OS) or top of the FileMaker Pro window (Windows). A number may be entered or Specify clicked to generate a number from a calculation.

Distance from Left is the new windows distance in pixels from the left of the screen (Mac OS) or left of the FileMaker Pro window (Windows). A number may be entered or Specify clicked to generate a number from a calculation.

Examples:

[View full width]

New Window [Name: "Profile"; Height: 500; Width: 700; Top: 25; Left: 25]

Description:

This script step creates a new window based on the current window. The new window is the same as the current window except in the specified options. In the case where an option is left without a value, the default value (as specified in the Window menu, New Window command) for that option is used. If position or size options exceed or fall below allowable minimums or maximums for a machines particular operating system and configuration, the allowed minimums or maximums are used instead of the chosen values. In multiple monitor environments, the use of negative position values makes it possible to position a window on alternate monitors. Note for Windows: FileMaker Pro orients the moved window to the top-left corner of the visible part of the application window. Note that this may not be the (0, 0) point of the window, depending on how the current file window is positioned. (For example, if half of the file window extends past the left border of the application window, you would need to scroll to the left to see the [0, 0] point of the application window.)

Omit Multiple Records

Compatibility:

Menu Equivalent: Records, Omit Multiple

Syntax: Omit Multiple Records [No dialog; ]

Options:

Perform Without Dialog prevents a dialog box from displaying when the script step executes. Without this option selected, the user sees a dialog that allows the user to enter the number of records to be omitted.

When Perform Without Dialog is selected, if a number of records to omit is not specified, only the current record is omitted.

Selecting Specify Records or clicking Specify allows the entry of the exact number of records to omit. The Specify button may also be clicked in the Options dialog box to allow for the entry of a calculation. The calculation result must be a number.

Examples:

Perform Find [Restore] # Omit only the current record Omit Multiple Records [No Dialog]

Description:

This script step omits the specified number of records from the found set, leaving the next available record as the current record. Omitted records are not deleted; they are just excluded from the found set. They remain in the database, as can be easily verified if you re-execute the Find Request that generated the found set in the first place.

Comments:

When programming for the Web, be sure to select Perform Without Dialog. Leaving the box unchecked is not web compatible and does not work on the Web.

Omit Record

Compatibility:

Menu Equivalent: Records, Omit Record

Syntax: Omit Record

Options:

None

Examples:

# Omit records marked for omission Go To Record/Request/Page [First] Loop If [Contacts::Omit] Omit Record End If Go To Record/Request/Page [Next; Exit After Last] End Loop

Description:

This script step omits the current record from the current found set when executed in Browse mode. The next available record becomes the new current record. Omitted records are not deleted. They are merely removed from the current found set. If this script step is executed while in Find mode, the current find requests Omit check box is toggled. (If it was checked, it will be unchecked and if it is unchecked it will be checked.) A find request that has the omit checkbox checked becomes an omit request that subtracts from rather than adds to the found set.

Open Define Database

Compatibility:

Menu Equivalent: File, Define, Database

Syntax: Open Define Database

Options:

None

Examples:

If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open Define Database End If

Description:

This script step opens the Define Database dialog box, where the user can create or edit tables, fields, and relationships. This script step is not performed if the users account does not have the Full Access privilege set. (The script may be set to Run Script With Full Access Privileges in the ScriptMaker menu.) When the user closes the dialog box, the remaining steps in the script, if any, are executed.

Open Define File References

Compatibility:

Menu Equivalent: File, Define, File References

Syntax: Open Define File References

Options:

None

Examples:

[View full width]

Show Custom Dialog ["Do you want to create or edit a file reference?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open Define File References End If

Description:

This script step opens the Define File References dialog box, where the user can create or edit references to files used throughout the database. This script step is not performed if the users account does not have the Full Access privilege set. (The script may be set to Run Script With Full Access Privileges in the ScriptMaker menu.) When the user closes the dialog box, the remaining steps in the script, if any, are executed.

Open Define Value Lists

Compatibility:

Menu Equivalent: File, Define, Value Lists

Syntax: Open Define Value Lists

Options:

None

Examples:

[View full width]

Show Custom Dialog ["Do you want to create or edit a value list?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open Define Value Lists End If

Description:

This script step opens the Define Value Lists dialog box, where the user can define new or edit existing value lists. This script step is not performed if the users account does not have the Full Access privilege set. (The script may be set to Run Script With Full Access Privileges in the ScriptMaker menu.) When the user closes the dialog box, the remaining steps in the script, if any, are executed.

Open File

Compatibility:

Menu Equivalent: File, Open

Syntax: Open File [Open hidden; ""]

Options:

Open Hidden causes FileMaker Pro to open the specified database hidden (that is, with its window minimized).

Specify allows the selection of a FileMaker Pro database to be opened. Within the Specify menu, Add File Reference provides a dialog box to assist in the location and selection of a filename. After a file is selected, it is added to the Specify list. In the same menu, Define File References allows one to modify or delete a file reference already added to the list.

Examples:

Open File [Open Hidden; "Tempfile. fp7"]

Description:

This script step opens the specified file or allows the user to select a file to open in the Open File dialog box. The Open File dialog box is invoked when no file is specified in the script step or if the specified file cannot be found. The active file before the Open File step is executed remains active after it has completed.

Open File Options

Compatibility:

Menu Equivalent: File, File Options

Syntax: Open File Options

Options:

None

Examples:

Show Custom Dialog ["Open File Options dialog box?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open File Options End If

Description:

This script step opens the File Options dialog box to the General Preferences area. This script step is not performed if the users account does not have the Full Access privilege set. (The script may be set to Run Script With Full Access Privileges in the ScriptMaker menu.)

Open Find/Replace

Compatibility:

Menu Equivalent: Edit, Find/Replace, Find/Replace

Syntax: Open Find/Replace

Options:

None

Examples:

[View full width]

Show Custom Dialog ["Open the Find/Replace dialog box?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open Find/Replace End If

Description:

This script step opens the Find/Replace dialog box. The remaining steps in the script, if any, are executed after the user closes the dialog box or completes a search.

Open Help

Compatibility:

Menu Equivalent: Help, FileMaker Pro Help

Syntax: Open Help

Options:

None

Examples:

[View full width]

Show Custom Dialog ["Do you want to open onscreen Help?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open Help End If

Description:

This script step opens the FileMaker Pro Help system. By default, the user is placed in the Help System Contents screen.

Comments:

The Help dialog is non-modal, so any additional script steps after the Open Help step execute right away, possibly pushing the help window into the background.

Open Preferences

Compatibility:

Menu Equivalent: Edit, Preferences (Windows) or FileMaker Pro, Preferences (Mac OS)

Syntax: Open Preferences

Options:

None

Examples:

Show Custom Dialog ["Open Preferences dialog box?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open Preferences End If

Description:

This script step opens the Preferences dialog box. The General Preferences area is selected by default.

Comments:

When the user closes the dialog box, the remaining steps in the script, if any, are executed.

Open Record/Request

Compatibility:

Menu Equivalent: None

Syntax: Open Record/Request

Options:

None

Examples:

[View full width]

Perform Find [Restore] Go to Record/Request/Page [First] Open Record/Request If [ Get(LastError) = 200 or Get(LastError) = 300] Show Custom Dialog ["An error has ocurred. This record is locked or you do not have sufficient permission to access it."] End If

Description:

This script step attempts to acquire exclusive access to the current record. Exclusive access prevents other users from editing the record. It has the same effect as a user selecting a data field on a layout (by clicking or tabbing) and then beginning to enter or edit field data. These actions either give exclusive access to that user or, if another user has already acquired exclusive access (otherwise known as a "lock"), the user attempting to gain control of the record sees an error message with a warning that another user has control of the record. It can be useful to try to gain exclusive access to a record in the course of a script. If you are looping over records and need to change each one, if a user is editing one of the records, your script may be prevented from changing it. Open Record/Request cannot override another users access, but if the script step fails it generates an error that your script can inspect with the Get(LastError) statement.

Open Remote

Compatibility:

Menu Equivalent: File, Open Remote

Syntax: Open Remote

Options:

None

Examples:

[View full width]

Show Custom Dialog ["Do you want to look for a networked database?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open Remote End If

Description:

This script step opens the Open Remote dialog box to allow the opening of a shared FileMaker Pro database over a network connection.

Comments:

When the user closes the dialog box, the remaining steps in the script, if any, are executed.

Open ScriptMaker

Compatibility:

Menu Equivalent: Scripts, ScriptMaker

Syntax: Open ScriptMaker

Options:

None

Examples:

Show Custom Dialog ["Open ScriptMaker?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open ScriptMaker End If

Description:

This script step opens the ScriptMaker dialog box, which enables a user to create, edit, rename, and duplicate scripts. When this script step is performed, FileMaker halts the current script because if any currently executing scripts were to be edited, the resulting behavior could be unpredictable.

Open Sharing

Compatibility:

Menu Equivalent: Edit, Sharing, FileMaker Network (Windows) or FileMaker Pro, Sharing, FileMaker Network (Mac OS)

Syntax: Open Sharing

Options:

None

Examples:

[View full width]

Show Custom Dialog ["Do you want to open the sharing dialog?"] If [Get (LastMessageChoice) = 1] #1=Yes, 2=No Open Sharing End If

Description:

This script step opens the FileMaker Network Settings dialog box where users can configure network database sharing.

Open URL

Compatibility:

Menu Equivalent: None

Syntax: Open URL [No dialog; ]

Options:

Perform Without Dialog prevents the Open URL Options dialog box from displaying when the script step executes.

Specify may be selected to display the Open URL Options dialog box, where the URL can be typed directly into the text entry area or created by a calculation.

Examples:

[View full width]

Open URL [No dialog; "http://www. apple. com/"] Open URL [No dialog; "file://c:/addresses. txt"] Open URL [No dialog; "mailto:no-one@name. net"] Open URL [No dialog; "fmp7://system:password@192. 168. 10. 46:591/WebDB"] #Note about the last example: "system" is the FileMaker Pro account name, "password" is that accounts password, and "WebDB" is the FileMaker Pro filename.

Description:

This script step allows an URL to be opened in the appropriate application. Supported schemes include HTTP, FTP, file, mailto, HTTPS, and fmp7 for opening FileMaker files. FileMaker consults the operating system preferences to help decide which application to use to service a particular URL scheme.

Comments:

This could be one effective means to an asset management solution. If the solution stores only references to the files, and the files are stored in a web server directory, FileMaker can construct a full URL to the file based on the reference in the database, and bring the file up in the users browser with an Open URL command.

When programming for the Web, be sure to select Perform Without Dialog. Leaving the box unchecked is not web compatible and does not work on the Web.

Paste

Compatibility:

Menu Equivalent: Edit, Paste

Syntax: Paste [Select; No style; ]

Options:

Select Entire Contents replaces the contents of a field with the contents of the Clipboard. If Select Entire Contents is not used, Paste copies the contents of the Clipboard to the currently selected portion of the field.

Paste Without Style tells FileMaker Pro to ignore all text style and formatting associated with the Clipboard contents.

Select Go to Target Field or click Specify to specify the field into which to paste.

Link If Available (Windows only) tells FileMaker Pro to choose a link over other formats on the clipboard. If both a link and an embedded object are present on the clipboard, the link is selected. If a link is available, it is selected over other formats.

Examples:

Go to Record/Request/Page [First] Copy [Select; Customer::ZipCode] Loop Go to Record/Request/Page [Next; Exit after last] Paste [Select; No style; Customer::ZipCode] End Loop

Description:

This script step pastes the contents of the clipboard into the specified field in the current record. If the data type of the data being pasted does not match the type of the field being pasted into, FileMaker Pro displays the customary validation alert when the record is committed. (Its also possible that the script that calls the Paste step may leave the record in an uncommitted state, in which case the error dialog appears later, when the record is committed.) If the field is not on the current layout, FileMaker Pro returns an error code, which can be captured with the Get(LastError) function. In a web-published database, use a Commit Record/Request script step after a Paste script step to update the record in the browser window.

Comments:

Paste is one of a number of script steps that depend on the presence of specific fields on the current layout. Other script steps with the same limitations include Cut, Copy, Paste, and Set Selection.

Pause/Resume Script

Compatibility:

Menu Equivalent: None

Syntax: Pause/Resume Script [Duration (seconds) ]

Options:

Specify displays the Pause/Resume Options dialog box, where the following options can be set.

Select Indefinitely to pause the script until the user clicks the Continue button in the Status Area.

Select For Duration to enter the number of seconds to pause the script.

Select For Duration and click Specify to create a calculation that determines the number of seconds to pause.

Examples:

Perform Find [Restore] Pause/Resume Script [Indefinitely] Set Field [Contacts::Status; "Ready for Review"]

Description:

This script step pauses a script for a specified period of time or indefinitely. This enables the user to perform data entry or other tasks before continuing the script. This step brings the active window of the file in which the script step is running to the foreground if it is not already there. The duration of a pause must be a number and represents the number of seconds that the pause will last before resuming execution for the script. Most FileMaker Pro menu options are not available to users while in a paused script. While paused, a script displays a Continue button in the status bar. The pause is terminated when a user clicks this button. There is also a Cancel button, which appears only if the Allow User Abort option is set to On. This button exits the currently running script. In the case where the status bar is hidden, the Enter key performs the same function as the Continue button. Buttons that run other scripts function while the current script is paused. A script run in this way is run as a subscript of the paused script.

Perform AppleScript

Compatibility:

Menu Equivalent: None

Syntax: Perform AppleScript ["<applescript text>"]

Options:

Specify to display the Perform AppleScript Options dialog box, where the following options can be set:

Calculated AppleScript lets you draw the AppleScript code from the result of a calculation.

Native AppleScript allows you to enter an AppleScript by hand (up to 30,000 characters long).

Examples:

[View full width]

#This example sets the primary monitor to its minimum bit depth. Perform AppleScript ["tell application "Finder" to set bounds of window "My Files" to {100, 100, 100, 100}"]

Description:

This script step sends AppleScript commands to an AppleScript-aware application. The AppleScript may be typed in manually or generated as the result of a specified calculation. Calculated scripts are compiled every time the script is run, whereas typed-in scripts are compiled only when the script is edited. Obviously, the latter is a faster process, but creating AppleScript code via a calculation provides much greater flexibility.

Comments:

Perform AppleScript is supported only on the Mac OS. The script step generates an error on Windows. For more information on AppleScript and AppleEvents, see the "Apple Events Reference" included with FileMaker Pro.

Perform Find

Compatibility:

Menu Equivalent: None

Syntax: Perform Find [Restore]

Options:

Select Specify Find Requests or click Specify to create or edit one or more find requests that will be stored with the script steps.

New opens a dialog box that enables you to create and specify a new find request to be stored with the script step.

Edit opens a selected find request from the existing list for editing.

Duplicate duplicates one or more selected find requests from the list and adds them to the stored set.

Delete deletes one or more selected find requests from the list.

Use the Edit Find Request dialog box to work with find request criteria.

Use Find Records or Omit Records to specify the behavior of the request. Selecting Omit Records is equivalent to checking the Omit check box in a find request in Find mode. Finding records adds them to the current found set. Omitting records excludes them. As in Find mode, use multiple requests if its necessary to both find and omit records in the course of a single stored search.

Find Records When (or Omit Records When) shows a list of the fields in your current table. To construct a find request, begin by selecting a field from this list.

To select a field from a related table, click the name of the current table at the top of the list and select the related table you want. Select a related field from this new list.

Change the value in Repetition to specify a particular cell of a repeating field.

Type the search criteria for the selected field in the Criteria area.

Click Add to add criteria to the find request.

To change existing criteria, select the line containing the field and criteria from the top of the dialog box, and make the changes to the field and/or criteria. Click Change to store changes.

To delete existing criteria, select the line containing the field and criteria from the top of the dialog box and click Remove.

Examples:

[View full width]

Set Error Capture [On] Perform Find [Restore] #check for a "no records" error If [Get (LastError) = 401] Show Custom Dialog ["Sorry, no records were found. "] End If

Description:

This script step places the system in Find mode and performs the search request(s) that have been designated for this step. If no find requests have been designated, then the last find request(s) that the system performed is performed. If the system is in Find mode when Perform Find is executed, then the currently entered find request is performed. This behavior is often used in conjunction with the Enter Find Mode step with the Pause option selected to allow a user to define a search request or group of search requests and then perform them. If FileMaker Pro doesn find any records that match the find criteria when a script is performed, the script can be stopped, execution of the script can be resumed with zero records in the current found set, and the find criteria can be changed. With the Set Error Capture script step and the Get(LastError) function, a script to handle such situations can be written.

Perform Find/Replace

Compatibility:

Menu Equivalent: None

Syntax:

Perform Find/Replace [No dialog; ""; ""; Find Next/Replace & Find/Replace/Replace All]

Options:

Perform Without Dialog inhibits the display of the Find/Replace Summary dialog box at the end of the Find/Replace operation. This option also prevents display of the confirmation dialog box when a Replace All operation is executed.

If it is desired that the user be able to enter find or replace criteria, use the Open Find/Replace script step.

Specify displays the Specify Find/Replace dialog box, where search options, as well as the type of find/replace operation to be performed, can be set.

Examples:

Perform Find/Replace ["hte"; "the"; Replace All]

Description:

This script step looks for the specified text in one or more fields and records of the current found set and, if directed, replaces it with either literal text or the result of a calculation. The scope of the operation can be defined to be the current record or the entire found set. The Find/Replace can span all fields in a layout or just the current field. The operation can be defined to proceed forward or backward in the current found set (as sorted). Finally, options are available for the matching of whole words only instead of parts of words, and for the matching of case.

Perform Script

Compatibility:

Menu Equivalent: None

Syntax: Perform Script ["