YOUSEFUL / FILEMAKER

YsflSched — function reference

Function prefix YsflSc_, 18 functions. Failures return ? message; details through YsflSc_LastError / YsflSc_LastErrorText.

How firing works

YsflSched keeps an in-memory job table for the FileMaker session (nothing survives a restart). Scripts are started only from FileMaker's idle callback, never from inside the calculation that scheduled them. A due job fires when FileMaker reports that no script is running or paused and the moment is safe; otherwise it waits and fires on a later idle tick. Idle ticks arrive roughly once a second while FileMaker is responsive, so treat timing as "no earlier than", not exact.

Common options

Space-separated key=value tokens, or one per line. param= takes the rest of its line, so put it last on a line when the parameter contains spaces.

option	meaning
`file=<name>`	file whose script to run (default: the file that called YsflSched)
`param=<text>`	script parameter
`control=halt\|exit\|resume\|pause`	what happens to a script that is already running (default `pause`, like Perform Script)
`id=<jobId>`	your own job id (default `job1`, `job2`, …)

Timestamps

Accepted: a FileMaker timestamp number (GetAsNumber ( ts )), 2026-09-13 16:05[:00], 9/13/2026 4:05[:00] PM, 9/13/2026, or a time of day 16:05[:00] / 4:05 PM (today, or tomorrow when already past). Times in the past fire on the next idle tick. Reported times use FileMaker's default text form (9/13/2026 16:05:00); nextRunISO and nextRunNumber give the other forms.

Functions

Function	Returns
`YsflSc_RunScript ( scriptName ; {options} )`	job id; runs on the next safe idle tick and is then removed from the table
`YsflSc_ScheduleAt ( scriptName ; when ; {options} )`	job id
`YsflSc_ScheduleIn ( scriptName ; seconds ; {options} )`	job id
`YsflSc_ScheduleEvery ( scriptName ; intervalSeconds ; {options} )`	job id; extra options `start=<when>`, `delay=<seconds>` (default one interval from now), `count=N` fires
`YsflSc_SetCondition ( jobId ; calculation ; scriptName ; {options} )`	job id; the calculation is evaluated on idle ticks (`every=<seconds>`, default 1) and the script fires when the result becomes true (non-zero number, `true`, `yes`); with option `repeat` the job re-arms after the value returns to false
`YsflSc_Cancel ( jobId )`	`0`; `*` removes every job
`YsflSc_Pause ( jobId )`	`0`; `*` pauses all pending jobs
`YsflSc_Resume ( jobId )`	`0`; a repeating job keeps its original anchor and skips the periods it missed
`YsflSc_List ( {filter} )`	`id\|state\|kind\|script\|file\|nextRun\|interval` lines; filter `pending`, `paused`, `done`, `immediate`, `once`, `repeat`, `condition`
`YsflSc_Info ( jobId ; field )`	`file`, `script`, `param`, `control`, `kind`, `state`, `nextRun`, `nextRunISO`, `nextRunNumber`, `interval`, `count`, `runs`, `lastRun`, `lastError`, `condition`, `every`, `repeat`
`YsflSc_SetFieldTrigger ( table ; field ; scriptName ; {options} )`	`0`; binds a field-exit trigger
`YsflSc_ClearFieldTrigger ( table ; field )`	`0`; `*` clears all
`YsflSc_FieldExit ( table ; field ; {parameter} )`	always `1`; when a binding exists its script is queued (the parameter overrides the bound `param`)
`YsflSc_Now ( {format} )`	current timestamp; `iso` or `number` for the other forms
`YsflSc_Version`, `YsflSc_Register`, `YsflSc_LastError`, `YsflSc_LastErrorText`	as other Youseful plugins

States: pending, paused, done. Kinds: immediate, once, repeat, condition.

Field-exit triggers

FileMaker gives plugins no hook on field exit, so YsflSched rides the field's own validation:

YsflSc_SetFieldTrigger ( "Orders" ; "Status" ; "Status Changed" ; "param=" & Orders::ID ) once per session (an OnFirstWindowOpen script is a good place).
In Manage Database, set the field's Validated by calculation to YsflSc_FieldExit ( Get ( LayoutTableName ) ; Get ( ActiveFieldName ) ; Self ) with Validate only if field has been modified.

The validation always passes; the script runs on the next idle tick after the field commits.

Examples

# nightly maintenance at 2 am, every day
Set Variable [ $id ; YsflSc_ScheduleEvery ( "Maintenance" ; 86400 ; "id=maint start=02:00" ) ]

# run a script after the current one finishes, with a parameter
Set Variable [ $r ; YsflSc_RunScript ( "Send Email" ; "control=resume param=" & $recipient ) ]

# fire once when a condition becomes true
Set Variable [ $r ; YsflSc_SetCondition ( "quiet" ; "Get ( RecordOpenCount ) = 0" ; "Commit Batch" ) ]