Exit Code of agent called from C API

HCL Domino Domino Forum
1

I’ve searched the forum and checked the FAQ to no avail.

I’m executing an agent via AgentRun in the C API. I need to detect if the agent runs successfully. I had hoped to use the dwExitCode field in the ODS_ASSISTRUNINFO structure:

typedef struct {

TIMEDATE LastRun; /* Time of last agent run */

DWORD dwProcessed; /* Number of docs processed on last run */

TIMEDATE AssistMod; /* Time of last assistant modification */

TIMEDATE DbID; /* DbID on which assistant was last run */

LONG dwExitCode; /* Exit code when assistant was last run */

DWORD dwSpare[4];

} ODS_ASSISTRUNINFO;

However it always holds a value of Zero. Other fields in this structure all hold reasonable and correct values.

I know that I could use the AgentLog and retrieve the error code if any from there. However it would be much cleaner to simply use the dwExitCode field.

Is this field supported? Perhaps its a bug in 6.5.1?

Many thanks for any assistance.

2

Subject: Exit Code of agent called from C API

Not a bug. This field is not used. Initially there was a thought to use it but it created too many replication storms so the implementation changed. I don’t believe it was ever used in a released product. It has not been used at least since 4.52 when I started.

3

Subject: RE: Exit Code of agent called from C API

Julie,

I began to look into the exit code problem yesterday, but had to drop it because I had other pressing matters to attend to. I found the following source code snippet in the ragents.c file of the Lotus Notes C API that actually references the dwExitCode variable:

/*

  • ODS_ASSISTRUNINFO - contain the Run Information.

  • It is always the first run data object.

*/

if (error = NSFDbReadObject(hDb, objRunInfo.RRV, dwOffset, 

                  ODSLength(_ODS_ASSISTRUNINFO), &hBuffer))

    goto Exit1;

pObject = OSLock (char, hBuffer);

ODSReadMemory( &pObject, _ODS_ASSISTRUNINFO, &RunInfo, 1 );

OSUnlock(hBuffer);

OSMemFree(hBuffer);

(void) ConvertTIMEDATEToText (NULL, NULL, &RunInfo.LastRun, RunTime, 

                                    MAXALPHATIMEDATE, &wLength);

RunTime[wLength] = '\0'; 

fprintf(pAgentsLog, "TimeDate of Execution: %s\n", RunTime);

fprintf(pAgentsLog, "Documents Processed By Formula: %ld\n", RunInfo.dwProcessed);

fprintf(pAgentsLog, "Exit Code: %ld\n\n", RunInfo.dwExitCode);

If the dwExitCode variable is not being used as you wrote, the sample code provided with the Notes C API 5 thru 6.5 and beyond should be updated to not reference the variable. The same goes for the structures in the C API.

James Greene

Jagre Incorporated

4

Subject: RE: Exit Code of agent called from C API

Thanks Julie. It would be good to update the C API documentation to point out that this field is not used.

thanks for your help. So the only way to find the result is to write a special value with it to the agent log and then parse the log for that value?

5

Subject: I was wrong. Exit Code of agent called from C API

Sorry, for misleading you. I confused _ODS_ASSISTRUNINFO with another structure which was part of the agent itself rather than the run time object.

This should work! But the run time object does not always exist and it is cleared if the agent is edited. Check if you get a valid LastRun value.

6

Subject: RE: I was wrong. Exit Code of agent called from C API

No problem. I am getting a valid LastRun value (e.g. 31/05/2004 10:54:04). But still just ‘0’ in the dwExitCode.

I’m now parsing the agent output in order to determine success or failure.

As another aside, when an error does occur the error value as returned by the LotusScript Err function does not seem to line up with the error values expected by the OSLoadString function. For example the LotusScript line:

 Print Err;": ";Error

Might output:

4555: Both the old and the new mail servers must be hierarchical.

But an error value 4555 passed to OSLoadString produces an error string of ‘Prompt_OkCancelListMult’.