MartyKraimer at 14:49, 4 October 2005

2005-10-04T14:49:23Z

MartyKraimer at 19:41, 28 September 2005

2005-09-28T19:41:08Z

← Older revision		Revision as of 19:41, 28 September 2005
Line 3:		Line 3:
	= Overview =		= Overview =

	<b>THIS WIKI NEEDS LOTS OF WORK</b>		<b>THIS WIKI IS OUT OF SYNC WITH OTHER WIKI PAGES. IT NEEDS LOTS OF WORK</b>

	This document describes the implementation of the record support		This document describes the implementation of the record support

MartyKraimer at 12:57, 22 September 2005

2005-09-22T12:57:23Z

← Older revision		Revision as of 12:57, 22 September 2005
Line 1:		Line 1:
	EPICS V4: RecordCommonSupport - September 16 2005		EPICS V4: RecordCommonSupport - September 22 2005
	----		----
	= Overview =		= Overview =

			<b>THIS WIKI NEEDS LOTS OF WORK</b>

	This document describes the implementation of the record support		This document describes the implementation of the record support
	for RecordCommon, the set if fields associated with ~~all~~ record ~~types~~.		for RecordCommon, i.e. the set of fields associated with every record type.

	For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.		For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.
Line 13:		Line 15:
	This document describes the following:		This document describes the following:

	* ~~A list of the~~ code ~~autimatically~~ generated from dbCommon.dbd and RecordCommon.dbd		* The code automatically generated from dbCommon.dbd and RecordCommon.dbd
	* A proposed implementation of RecordCommonSupport.		* A proposed implementation of RecordCommonSupport.

Line 41:		Line 43:
	See the description of <tt>dbCommon.dbd</tt> in "V4 Design: RecordCommon"		See the description of <tt>dbCommon.dbd</tt> in "V4 Design: RecordCommon"

	Link support must register ~~for~~ each of the <tt>link</tt> definitions.		Link support must register support each of the <tt>link</tt> definitions.

	From <tt>dbCommon.dbd</tt> the following class implementations are generated:		From <tt>dbCommon.dbd</tt> the following class implementations are generated:
Line 102:		Line 104:
	enum Mode {modeNone,modeInput,modeOutput};		enum Mode {modeNone,modeInput,modeOutput};

	public class RecordCommonSupport implements Callback, Common {		public class RecordCommonSupport implements RecordSupport,Callback,Common
			{
	private RecordInstance instance;		private RecordInstance instance;
	private Mode mode;		private Mode mode;
Line 116:		Line 119:

	// Beginning of RecordSupport		// Beginning of RecordSupport
			public destroy() {} // destroy not needed for Java
			public destroy() {} // destroy not needed for Java
	public initialize(int pass) {		public initialize(int pass) {
	if(pass==0) return;		if(pass==0) return;
Line 122:		Line 127:
	alarm.init(instance);		alarm.init(instance);
	}		}
	~~public destroy() {} // destroy not needed for Java~~

	public processState process(processState state) {		public processState process(processState state) {
	switch(state) {		switch(state) {
	case processCancel: mode = modeNone; return processDone;		case processCancel:
			//MUCH MORE NEEDS TO BE DONE
			// MUST CANCAL ANY OUTSTANDING I/O
			mode = modeNone; return processDone;
	case processStart: {		case processStart: {
	mode = modeInput;		mode = modeInput;
Line 307:		Line 314:
	enum Mode {modeNone,modeInput,modeOutput};		enum Mode {modeNone,modeInput,modeOutput};

	public class RecordCommonSupport ~~extends~~ RecordSupport		public class RecordCommonSupport implements RecordSupport,Callback, Common
	~~implements~~ Callback, Common {		{
	private RecordInstance instance;		private RecordInstance instance;
	private Mode mode;		private Mode mode;

MartyKraimer at 15:06, 16 September 2005

2005-09-16T15:06:41Z

New page

EPICS V4: RecordCommonSupport - September 16 2005
----
= Overview =

This document describes the implementation of the record support
for RecordCommon, the set if fields associated with all record types.

For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.
dbCommon.dbd define widely used definitions and RecordCommon.dbd defines
the fields that are common to all record types.

This document describes the following:

* A list of the code autimatically generated from dbCommon.dbd and RecordCommon.dbd
* A proposed implementation of RecordCommonSupport.

This document requires that the reader be familiar with:
# V3 iocCore
# V4 Design: Record Processing
# V4 Design: dbdInterfaces
# V4 Design: Runtime interfaces
# V4 Design: RecordCommon

Unless the reader is familiar with these most of this document will
be very difficult to understand.

Java is used as the example code for two reasons:
# For V4 iocCore it is intended that both C++ and Java implementations will be provided. Since V3 is only implemented in C and C++ the Java implemention of V4 is described first to make sure that the interfaces defined in dbdInterfaces will work for Java.
# Java provides facilities that make it easy to handle strings, arrays, and structures.

An implementaion of RecordCommonSupport is presented for two reasons:
# It demonstrates how to implement code that uses or implements the interface described in "V4 Design: dbdInterfaces" and "V4 Design: Runtime interfaces".
# It helps refine the interfaces described in them

----
<center>
= dbCommon.dbd =
</center>

See the description of <tt>dbCommon.dbd</tt> in "V4 Design: RecordCommon"

Link support must register for each of the <tt>link</tt> definitions.

From <tt>dbCommon.dbd</tt> the following class implementations are generated:
* For the link structures:
** <tt>MonitorLink</tt> and <tt>MonitorLinkData</tt>, and <tt>MonitorLinkSupport</tt>
** <tt>InputLink</tt>, <tt>InputLinkData</tt>, and <tt>InputLinkSupport</tt>
** <tt>OutputLink</tt>, <tt>OutputLinkData</tt>, and <tt>OutputLinkSupport</tt>
** <tt>ProcessLink</tt>, <tt>ProcessLinkData</tt>, and <tt>ProcessLinkSupport</tt>
* For TimeStamp
** <tt>TimeStamp</tt>, <tt>TimeStampData</tt>, and <tt>TimeStampSupport</tt>
* For Scan
** <tt>Scan</tt>, <tt>ScanData</tt>, and <tt>ScanSupport</tt>

See "V4 Design: Runtime interfaces" for an example of how these classes are defined.

----
<center>
= RecordCommon.dbd =
</center>

See the description of <tt>RecordCommon.dbd</tt> in "V4 Design: RecordCommon"

<tt>RecordCommon.dbd</tt> must be part of every record.

Implementations of <tt>Disable</tt>, <tt>DisableData</tt>,
and <tt>DisableDataSupport</tt>
are automatically generated.

An implementations of RecordCommon is also generated.
See "V4 Design: Runtime interfaces" for an example of the generated
classes.
----
<center>
= RecordCommonSupport.java =
</center>

== Overview ==
This section describes the java implementation of RecordCommon
functionality. This code handles processing of the following fields
of RecordCommon:
; <tt>disable</tt>
: Decides if the record is disabled.
; <tt>alarmStatus</tt> and <tt>alarmSeverity</tt>
: The only way to change alarmStatus and alarmSeverity is via interface Common, which is implemented by RecordCommonSupport.
; <tt>processLink</tt>
: This is an array of process links, which replace the V3 <tt>FLNK</tt>

The following subsection contains the complete code for RecordCommonSupport.java.
The remaining subsections discuss each part of the code.

== IocCommon.java ==

This defines
interface Common {
bool setSeverity(AlarmSeverity severity, string status);
}

== RecordCommonSupport.java ==
enum Mode {modeNone,modeInput,modeOutput};

public class RecordCommonSupport implements Callback, Common {
private RecordInstance instance;
private Mode mode;
private Input input;
private Output output;
private Alarm alarm;
private bool requestProcess;

// Constructor
public RecordCommonSupport(RecordInstance instance) {
this.instance = instance;
}

// Beginning of RecordSupport
public initialize(int pass) {
if(pass==0) return;
input.init(instance);
output.init(instance);
alarm.init(instance);
}
public destroy() {} // destroy not needed for Java

public processState process(processState state) {
switch(state) {
case processCancel: mode = modeNone; return processDone;
case processStart: {
mode = modeInput;
requestProcess = false;
LinkWaitResult result = input.disableSupport.getWait(
input.disableInput,0.0,this);
if(result==linkNoop || result==linkDone) return processDone;
requestProcess = true;
}
// fall through to processInputActive
case processInputActive: {
if(requestProcess) return processInputActive;
if(input.disable.disableValue == disable.disableInput)
return processDone;
return processActive;
}
case processDone: {
mode = modeOutput;
output.nextLink = 0;
output.numberLinksActive = 0;

}
// fall through to processOutputActive
case processOutputActive:
LinkWaitResult result = linkWaitParallel;
requestProcess = false;
while(output.nextLink< output.link.length) {
if(result==linkWaitSequential) break;
result = output.link[nextLink].support.processWait(0.0,this);
if(result==linkWaitSequential || result==linkWaitParallel)
output.numberLinksActive++
output.nextLink++;
}
if(output.numberLinksActive==0) {
mode = modeNone;
return processDone;
}
requestProcess = true;
return processOutputActive;
default: throw java.lang.IllegalStateException;
}
}

public bool special(bool after,Dbf[] field) {
int nlevels = field.length;
assert(nlevels>0);
if(index==alarmStatusIndex || index==alarmSeverityIndex) {
if(!alarm.modifyingAlarm) return false;
return true;
}
if(!after) return;
switch(index) {
case disableIndex: {
if(nlevels==1) {
input.init(instance);
} else {
input.special(instance,Dbf[1]);
}
break;
}
case processLinkIndex : output.init(instance); break;
default: printf("Why is special being called?\n");
}
}

// Start of Callback methods
public void done() {
lock(instance);
switch(mode) {
case modeNone:
unlock(instance)
throw java.lang.IllegalStateException;
case modeInput:
if(requestProcess) {
requestProcess = false;
DbAccess.process(instance);
}
break;
case modeOutput:
output.numberLinksActive--;
if(output.numberLinksActive==0 && requestProcess) {
requestProcess = false;
DbAccess.process(instance);
}
if(output.numberLinksActive==0 && requestProcess)
break;
}
unlock(instance)
}
public void failure() { done(); }

// Start of Common methods
bool setSeverity(AlarmSeverity severity, string status) {
Alarm alarm = this.alarm;
if(severity<= alarm.severity) return false;
alarm.severity = severity;
alarm.status = status;
alarm.modifyingAlarm = true;
alarm.alarmSeverity.putIndex(severity);
alarm.alarmStatus.put(status);
alarm.modifyingAlarm = false;
}
}

// Definitions for modeInput
class Input {
DisableData disable;
LinkSupport disableSupport;
DbfInt16 disableInput;
DbfInt16 disableValue;
DbfInt16 alarmSeverity;

void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfLink link = recordAccess.getField("disable.disableLink");
disableSupport = link.getSupport();
DisplayLimitAccess.get(
recordAccess.getField("disable"),disable);
recordAccess.getField("disable.disableInput",disableInput);
}
void special(RecordInstance instance,Dbf field) {
int16 index = Dbf.getIndex();
switch(index) {
case disableValueIndex:
disableValue = ((DbfInt16)Dbf).get(); break;
case disableInputIndex:
disableInput = ((DbfInt16)Dbf).get(); break;
case disableAlarmSeverityIndex:
alarmSeverity = ((dbfMenu)Dbf).getIndex(); break;
case disableLinkIndex:
init(instance); break;
default:
throw java.lang.IllegalStateException;
}
}
}

// Definitions for modeOutput
class OutputLink {
Link link;
LinkSupport support;
void init(RecordInstance instance,String linkFieldName) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfLink link = recordAccess.getField(linkFieldName);
support = link.getSupport();
}
};

class Output {
int nextLink;
int numberLinksActive;
OutputLink[] link;
void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfArray array = recordAccess.getField("processLink");
int n = array.getNelements();
link = new OutputLink[n];
for(i=0; i< n; i++) {
String field = "processLink[" + "i" + "]";
link[i].init(instance,field);
}
}
}

// Definitions for alarm handling
class Alarm {
short severity;
String status;
DbfMenu alarmSeverity;
DbfString alarmStatus;
bool modifyingAlarm;
void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
alarmSeverity = recordAccess.getField("alarmSeverity");
alarmStatus = recordAccess.getField("alarmStatus");
}
}

== Beginning of class definition ==
enum Mode {modeNone,modeInput,modeOutput};

public class RecordCommonSupport extends RecordSupport
implements Callback, Common {
private RecordInstance instance;
private Mode mode;
private Input input;
private Output output;
private Alarm alarm;
private bool requestProcess;

// Constructor
public RecordCommonSupport(RecordInstance instance) {
this.instance = instance;
}

RecordCommonSupport implements the following interfaces:
; <tt>RecordSupport</tt>
: Record support for the fields in RecordCommon.
; <tt>Callback</tt>
: The callbacks called by link support
; <tt>Common</tt>
: For now this just has the method <tt>setSeverity</tt>

It has the following private fields:
* <tt>instance</tt> - The record instance to which it is attached. <tt>RecordCommonSupport</tt> has a single constructor which is passed the <tt>RecordInstance</tt> to which it is attached.
* <tt>mode</tt> - This keeps the state for record processing:
** <tt>modeNone</tt> - The record is not being processed.
** <tt>modeInput</tt> - The disable link is active but not complete.
** <tt>modeOutput</tt> - The processLinks are active but not complete.
* <tt>input</tt> - Input is a private class that provides access to the fields of disable.
* <tt>output</tt> - Output is a private class that provides access to processLink.
* <tt>alarm</tt> - Alarm is a private class that provides access to fields alarmSeverity and alarmStatus.
* <tt>requestProcess</tt> - This is used by callback to decide if a request should be made to process the record.

Notes about <tt>Input</tt>, <tt>Output</tt>, and <tt>Alarm</tt>.
* Each of these is a private class to RecordCommonSupport.
* Each makes fields available to RecordCommonSupport.
* Each has "introspection" code that gets the values of the private fields from RecordCommon fields during record initialization of if the an RecordCommon fields is changed via a call to <tt>Dbf.put</tt>.
* The implementations of each of these private classes is given after the implementaion of RecordCommonSupport.

== RecordSupport Methods ==
=== initialize ===

public initialize(int pass) {
if(pass==0) return;
input.init(instance);
output.init(instance);
alarm.init(instance);
}

During the first pass of initialization, nothing needs to be done.
Before initialize is called on pass 1, iocInit has
already called link support so that it connects.
Initialize just calls its private class init methods. They get the
current values of their private fields.

=== destroy ===
public destroy() {} // destroy not needed for Java

Since Java does garbage collection destroy is not needed.
Note that iocCore will call all the link support destroy methods.

=== process ===

<tt>process</tt> is called by dbProcess at the beginning of record processing
and after the record specific record support completes.
During the beginning of record processing
process takes care of field <tt>disable</tt>
During the end of record processing process
takes care of field <tt>processLink</tt>.

A few features of <tt>process</tt> are:
* implements a state machine that handles the links.
* interacts with Callback, which is called by link support when links complete.
* interacts with special, which is called when fields in RecordCommon are modified.

public processState process(processState state) {
switch(state) {
case processCancel: mode = modeNone; return processDone;
case processStart: {
mode = modeInput;
requestProcess = false;
LinkWaitResult result = input.disableSupport.getWait(
input.disableInput,0.0,this);
if(result==linkNoop || result==linkDone) return processDone;
requestProcess = true;
}
// fall through to processInputActive
case processInputActive: {
if(requestProcess) return processInputActive;
if(input.disable.disableValue == disable.disableInput)
return processDone;
return processActive;
}
case processDone: {
mode = modeOutput;
output.nextLink = 0;
output.numberLinksActive = 0;

}
// fall through to processOutputActive
case processOutputActive:
LinkWaitResult result = linkWaitParallel;
requestProcess = false;
while(output.nextLink< output.link.length) {
if(result==linkWaitSequential) break;
result = output.link[nextLink].support.processWait(0.0,this);
if(result==linkWaitSequential || result==linkWaitParallel)
output.numberLinksActive++
output.nextLink++;
}
if(output.numberLinksActive==0) {
mode = modeNone;
return processDone;
}
requestProcess = true;
return processOutputActive;
default: throw java.lang.IllegalStateException;
}
}

=== special ===
<tt>special</tt> is called when any of the fields in <tt>disable</tt>,
<tt>alarmStatus</tt>, <tt>alarmSeverity</tt>, or <tt>processLink</tt> are changed.
public bool special(bool after,Dbf[] field) {
int nlevels = field.length;
assert(nlevels>0);
if(index==alarmStatusIndex || index==alarmSeverityIndex) {
if(!alarm.modifyingAlarm) return false;
return true;
}
if(!after) return;
switch(index) {
case disableIndex: {
if(nlevels==1) {
input.init(instance);
} else {
input.special(instance,Dbf[1]);
}
break;
}
case processLinkIndex : output.init(instance); break;
default: printf("Why is special being called?\n");
}
}

== Private Class Methods ==
=== Callback methods ===
These are the callback methods that are called by link support.
// Start of Callback methods
public void done() {
lock(instance);
switch(mode) {
case modeNone:
unlock(instance);
throw java.lang.IllegalStateException;
case modeInput:
if(requestProcess) {
requestProcess = false;
DbAccess.process(instance);
}
break;
case modeOutput:
output.numberLinksActive--;
if(output.numberLinksActive==0 && requestProcess) {
requestProcess = false;
DbAccess.process(instance);
}
return;
}
unlock(instance);
}
public void failure() { done(); }

=== Common methods ===
For now the only method is <tt>setSeverity,</tt>
The only way code can change severity and status is to call this method.

// Start of Common methods
bool setSeverity(AlarmSeverity severity, string status) {
Alarm alarm = this.alarm;
if(severity<= alarm.severity) return false;
alarm.severity = severity;
alarm.status = status;
alarm.modifyingAlarm = true;
alarm.alarmSeverity.putIndex(severity);
alarm.alarmStatus.put(status);
alarm.modifyingAlarm = false;
}
}

=== Input ===
This is a private class for RecordCommonSupport.
It directly accesses the fields in this class.
The init and special methods are called to get values for the private fields.

// Definitions for modeInput
class Input {
DisableData disable;
LinkSupport disableSupport;
DbfInt16 disableInput;
DbfInt16 disableValue;
DbfInt16 alarmSeverity;

void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfLink link = recordAccess.getField("disable.disableLink");
disableSupport = link.getSupport();
DisplayLimitAccess.get(
recordAccess.getField("disable"),disable);
recordAccess.getField("disable.disableInput",disableInput);
}
void special(RecordInstance instance,Dbf field) {
int16 index = Dbf.getIndex();
switch(index) {
case disableValueIndex:
disableValue = ((DbfInt16)Dbf).get(); break;
case disableInputIndex:
disableInput = ((DbfInt16)Dbf).get(); break;
case disableAlarmSeverityIndex:
alarmSeverity = ((dbfMenu)Dbf).getIndex(); break;
case disableLinkIndex:
init(instance); break;
default:
throw java.lang.IllegalStateException;
}
}
}

=== OutputLink and Output ===
Output is a private class for RecordCommonSupport.
It directly accesses the fields in this class.
The init method is called to get values for the private fields.
OutputLink is used by Output.

// Definitions for modeOutput
class OutputLink {
Link link;
LinkSupport support;
void init(RecordInstance instance,String linkFieldName) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfLink link = recordAccess.getField(linkFieldName);
support = link.getSupport();
}
};

class Output {
int nextLink;
int numberLinksActive;
OutputLink[] link;
void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfArray array = recordAccess.getField("processLink");
int n = array.getNelements();
link = new OutputLink[n];
for(i=0; i< n; i++) {
String field = "processLink[" + "i" + "]";
link[i].init(instance,field);
}
}
}

=== Alarm ===
This is a private class for RecordCommonSupport.
It directly accesses the fields in this class.
The init method is called to get values for the private fields.

// Definitions for alarm handling
class Alarm {
short severity;
String status;
DbfMenu alarmSeverity;
DbfString alarmStatus;
bool modifyingAlarm;
void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
alarmSeverity = recordAccess.getField("alarmSeverity");
alarmStatus = recordAccess.getField("alarmStatus");
}
}

== RecordCommonSupportFactory ==
This is the factory for creating an RecordCommonSupport.
It is called by dbLoadRecords.

public class RecordCommonSupportFactory implements RecordSupportFactory{
RecordSupport create(RecordInstance instance) {
return new RecordCommonSupport(instance);
}
void destroy(RecordSupport support) {
RecordCommonSupport RecordCommonSupport = support;
RecordCommonSupport.destroy();
}
}

public final class RecordCommonSupportFactoryRegister {
static public createAndRegister() {
RecordCommonSupportFactory factory = new RecordCommonSupportFactory;
RegisterSupport.record(factory,"RecordCommon");
}
}

<b>Question</b>
Who calls RecordCommonSupportFactoryRegister.createAndRegister?

V4 Design: RecordCommon Support - Revision history

MartyKraimer at 14:49, 4 October 2005

MartyKraimer at 19:41, 28 September 2005

MartyKraimer at 12:57, 22 September 2005

MartyKraimer at 15:06, 16 September 2005