Library Reference

#include ``libruncontrol.h''

runControlInit

int runControlInit(char *pv, char *desc, float timeout, char *handle, RUNCONTROL_INFO *rcInfo, double pendIOtime);

Grab control of the specified EPICS runcontrol record, and load it with various application information, such as process-id, hostname, username, and start time. A specific record may be given via the pv argument, or NULL may be given and the next free runcontrol record will be found for you.

• pv - ptr to null terminated string containing pv name, not to exceed 39 characters, or NULL if you want library to find next free runcontrol record for you.
• desc - ptr to null terminated string (<= 39 chars) which identifies your application.
• timeout - timeout interval for ping in milliseconds. Your application must call runControlPing periodically within this interval, or the runcontrol record will timeout, and your application will have to exit.
• handle - ptr to zero length, preallocated string of 255 bytes. Function will copy in an identifier which is to be used in the other library calls.
• rcInfo - ptr to RUNCONTROL_INFO which is used internally by runcontrol.
• pendIOtime - timeout interval used by client incase IOC is unresponsive.

Returns:

• RUNCONTROL_OK - application is registered, proceed
• RUNCONTROL_DENIED - another application (or application instance) is using the same runcontrol record, or has the same description string.
• RUNCONTROL_ERROR - unable to communicate with runcontrol record

runControlPing

int runControlPing(char *handle, RUNCONTROL_INFO *rcInfo);

Notifies runcontrol record that you application is still alive. Also provides a means for runcontrol record to suspend you, or request that you abort. The return codes from this call must be checked and acted on properly.

• handle - ptr to string initialized by runControlInit() call.
• rcInfo - ptr to RUNCONTROL_INFO which is used internally by runcontrol.

Returns:

• RUNCONTROL_OK - all is well, continue
• RUNCONTROL_ABORT - your application should clean up and exit
• RUNCONTROL_TIMEOUT - your application didn't ping the record within the timeout interval and should clean up and exit.
• RUNCONTROL_ERROR - unable to communicate with record, you should attempt another runControlInit(), or exit.

runControlExit

int runControlExit(char *handle, RUNCONTROL_INFO *rcInfo);

Release control of the runcontrol record.

• handle - ptr to string initialized by runControlInit() call.
• rcInfo - ptr to RUNCONTROL_INFO which is used internally by runcontrol.

Returns:

• RUNCONTROL_OK - all is well
• RUNCONTROL_ERROR - unable to communicate with record

runControlLogMessage

int runControlLogMessage(char *handle, char *message, short severity, RUNCONTROL_INFO *rcInfo);

Log a message and new alarm severity to the runcontrol record. The runcontrol record will enter given alarm state.

• handle - ptr to string initialized by runControlInit() call.
• message - ptr to null terminated string (<= 39 chars) with status message.
• severity - NO_ALARM, MINOR_ALARM, MAJOR_ALARM, INVALID_ALARM
• rcInfo - ptr to RUNCONTROL_INFO which is used internally by runcontrol.

Returns:

• RUNCONTROL_OK - all is well
• RUNCONTROL_ERROR - unable to communicate with record