A macro that uses the AI Object always follows the same lifecycle. Understanding this lifecycle makes every individual method self-explanatory.
The lifecycle
Step
| Method
| What happens
|
|---|
1
| NewConversation (optional)
| Creates a handle in advance. Only needed when you want to attach files or a recordset before asking. For a plain question you can skip this step.
|
2
| AttachFile / AttachRecordset (optional)
| Attaches data context to the handle.
|
3
| Ask
| Submits the question. Returns a handle immediately — does not wait.
|
4
| GetStatus
| Polled in a loop until it no longer returns aiStatusBusy.
|
5
| GetResultStr / GetResultRaw
| Retrieves the answer once the status is aiStatusReady.
|
6
| CloseHandle
| Releases the handle and triggers server-side cleanup of any attachments.
|
The polling loop
The heart of every AI macro is the polling loop. GetStatus contains an internal rate-limiter: it never queries the server more than four times per second, regardless of how often the macro calls it. A tight Do ... Loop with only a DoEvents inside is therefore safe — the object throttles itself.
aiHnd = AI.Ask("Summarise the most recent changes in Dutch VAT law.")
Do
DoEvents
Loop Until AI.GetStatus(aiHnd) <> 1 ' 1 = aiStatusBusy
If AI.GetStatus(aiHnd) = 2 Then ' 2 = aiStatusReady
Debug.Print AI.GetResultStr(aiHnd)
Else
Debug.Print AI.GetErrorMessage(aiHnd)
End If
AI.CloseHandle aiHnd
|
Handles
A handle is a positive number that identifies one conversation. Ask returns a handle greater than zero on success, or 0 when the question could not even be submitted (for example, no connection). When Ask returns 0, inspect LastErrorCode and LastErrorMessage for the reason.
Multi-turn conversations
To ask a follow-up question in the same context, pass the existing handle as the third argument of Ask. The model then remembers the previous exchange. Wait until the handle is no longer busy before submitting the follow-up.
aiHnd = AI.Ask("Give me a SELECT query for all active customers.", aiSQLCopilot)
' ... poll until ready, read result ...
aiHnd = AI.Ask("<span style='color: #800080; font-weight: bold;'>Now</span> sort that by last order date, descending.", , aiHnd)
' ... poll until ready, read result ...
AI.CloseHandle aiHnd
|
Authentication
The AI Object connects to the Tradium service automatically on the first Ask, using the licence credentials supplied to Configure by the host. A macro never has to log in itself. If the session expires during a long-running macro, the object reconnects transparently.
Note. In MacroHandler and AdminMailMain every macro runs in a fresh runtime, so every macro gets its own connection. This is intentional and robust — there is no shared session that could go stale between macros.
|