---

SCAN

Scan for a record with a field that matches a pattern, using a name scan file.

---

Format
	SCAN for pattern using facility /Qualifiers ... ]
	pattern	Pattern expression to match
	facility	The facility to use in scanning. The facility can be:
	DATABASE(FIELD) DATABASE(#expr)	The name of a database and field on which to do the scan. This is an implicit opening of a scan file.
	TAGNAME	The name tag of a scan file previously opened with an OPENSCAN statement.
	Before you use the SCAN statement, the scan file must already exist. You can build name scan files with the REBUILD or SCAN options of the MAINTAIN utility.
	NOTE
	The OPENSCAN and SCAN statements are provided mainly to support UserBase format datafiles. If you are using RMS datafiles, you should not need to use these statements. Use the RMS key structure instead.

---

Qualifiers
	/Fail=LABEL	Label to which to branch if the statement fails. If LABEL is %EXIT, exit the routine or loop. If in a loop, and LABEL is %CONTINUE, continue the loop. If not in a loop, and LABEL is %CONTINUE, an error message displays.
	/Succeed=LABEL	Label to which to branch if the statement succeeds. If LABEL is %EXIT, exit the routine or loop. If in a loop, and LABEL is %CONTINUE, continue the loop. If not in a loop, and LABEL is %CONTINUE, an error message displays.
	/Nofail	Do not signal an error. Instead, set the internal variable %FAIL.
	/Flush	Flush the record stream so that the record is physically on disk.
	/Load	Use the load factor of the RMS datafile if specified.
	/Lock=(lock_options, ... )	Use the following lock options to lock the record if it is automatically retrieved (by accessing a field in that record).
	exclusive		Lock against all other record streams except READ_REGARDLESS.
	manual		Records remain locked until explicitly unlocked.
	none		Records are not to be locked.
	nonexistent		Proceed with the operation even if the record does not exist (RMS relative files only).
	nowait		Do not wait if the record is locked (return an error).
	read		Lock the record for reading while allowing other record streams to read but not modify (ignored if write also specified).
	read_regardless		Read records even if another record stream has them locked.
	wait=n		Wait n seconds before returning an error if the record is locked.
	write		Lock the record for writing while allowing other record streams to read but not modify.

---

Example
	Perform ASKPATTERN	! Get the pattern to search for
	! Explicit open of scan file
	Openscan EMPLOYEE(NAME) as EMPNAME
	row = 0
	Loop
	Scan for pattern using EMPNAME/FAIL:DONE
	row = row + 1
	Display Pos(row, 1); EMPLOYEE(NAME)
	End_loop
	DONE: Close EMPNAME
	Message "Done with explicit open"
	! Implicit open of scan file
	Loop
	Scan for pattern using EMPLOYEE(NAME)/Fail:DONEAGAIN
	row = row + 1
	Display Pos(row, 1); EMPLOYEE(NAME)
	End_loop
	DONEAGAIN: Error "That's all, folks!"