If you do a find by hand, any kind of find, then you go to Script editor and create a new script and add the perform find step and click on "Specify find requests", you will get pre-coded exactly the last find you did.
You can play a bit with this method, I'm sure you'll get how it works.
but "Perform Find" on the other hand, has always been annoyingly stubborn to work with, often having the wrong or unexpected results
The confusion may stem from the fact that Perform Find can be used in two ways:
1. With pre-specified requests as part of the script step [Restore]
2. As a fancy way of pressing the enter/return key while you're in Find mode [no restore], i.e. start (perform) the Find as specified beforehand
The second usage is preferred by developers, since a) it allows you to circumvent the Define Request dialog of the script step (well, that's a reason for me, anyway), and b) the script lists explicitly your search criteria. The pattern looks like this …
Enter Find Mode [ no pause ]
Go to Layout ( SomeLayout ( SomeTable ) ]
Set Field [ target field: SomeTable::fieldToSearch ; calculated value: some expression ]
# [ set more fields for an AND search, or create new request(s) for an OR search, then set field(s) ]
Perform Find [ no restore ]
… and is exactly what you would do manually: enter Find mode, type values into fields, press enter/return.
Scripted finds 101 (the script steps)
1. Perform Find - can be with 'saved' criteria, or at the END of a scripted find
a. if you use 'saved' criteria (with RESTORE), then you may not need any other steps
b. my preference is to NOT use 'saved' criteria
2. Enter Find Mode - can be with 'pause' at the BEGINNING of a scripted find
a. pausing the find will allow user entry until the return/enter key is pressed or a script step to Resume
b. can also have 'saved' criteria, but is still at the beginning of the scripted find
c. my preference is to not pause, add criteria with Set Field, and end with Perform Find
3. Changing the manual or scripted find with these steps:
a. Modify Last Find
b. Constrain Found Set
c. Extend Found Set
d. Omit Record/Omit Multiple Records
e. Show Omitted Only
4. There is a test to see if nothing gets returned (after the Perform Find):
If ( Get ( FoundCount ) = 0 )
... do something here ...
... do another thing here ...
5. You can use global fields to get the "find criteria" and push into scripted finds (Set Field after Enter Find Mode). You can also push variables into the Set Field.
That makes a lot more sense - from what I read, this script function is basically used as a work around then instead of what it's supposed to be used for according to the site. I can imagine that considering how annoying it is to set up.
Thank you for your in-depth explanation. Most of the links I found myself but it's good to have an overview of the different elements - it gives me something to work from.