V4 DBD Statement Syntax - Revision history

MartyKraimer at 19:53, 2 November 2005

2005-11-02T19:53:04Z

← Older revision		Revision as of 19:53, 2 November 2005
Line 1:		Line 1:
	DBD Statement Syntax November 01 2005		DBD Statement Syntax November 02 2005
	----		----
	= Overview =		= Overview =
Line 247:		Line 247:
	The syntax is:		The syntax is:

	~~field(name,~~link)		link

	Examples:		Examples:
Line 389:		Line 389:

	Examples:		Examples:
	link(processLink)		link(processLink,ProcessLink)
	link(monitorLink,~~MonitorLinkData~~)		link(monitorLink,MonitorLink)

MartyKraimer at 20:49, 1 November 2005

2005-11-01T20:49:53Z

← Older revision		Revision as of 20:49, 1 November 2005
Line 1:		Line 1:
	DBD Statement Syntax ~~Sept 30~~ 2005		DBD Statement Syntax November 01 2005
	----		----
	= Overview =		= Overview =
	This document presents the syntax for V4 database definition files.		This document presents the syntax for V4 database definition files.

			<b>NOTE</b> This version of the database definition and database instance
			syntax does not provide:
			# a direction for links
			# a way to select a subset of the support definitions

			Support can exist for either a link field or a struct field.
			The support definition is just

			support(choiceName,supportStructName)

			When a record instance is created any choiceName can be specified for
			a link or struct field. If an invalid choice is made, an error will
			be issued during initialization.

	<center>		<center>
	= General Statements =		= General Statements =
Line 232:		Line 247:
	The syntax is:		The syntax is:

	~~link~~(~~linkDirection,interface(interfaceName,...))~~		field(name,link)

	~~<b>ANDREW</b>~~
	~~What syntax should we use?~~
	~~The idea is that the record definition gives a list of interfaces it understands.~~

	~~where~~
	* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, ~~or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>~~link~~</tt> that the record instance selects.~~
	* <tt>interface(string,...)~~</tt> : Each interfaceName is the name of an interface implemented by link support and used by record support.~~

	Examples:		Examples:
	field(disableLink,		field(disableLink,link)
	link~~(in,interface ( LinkInt32, LinkFloat64 ))~~		field(process, link)
	)		field(inp,link)
	field(process, link~~(process,interface(ProcessLink)~~)
	field(inp,
	link~~(in, interface (LinkInt32, LinkFloat64, AsynDigital))~~
	)

	== fieldAttribute ==		== fieldAttribute ==
Line 358:		Line 361:

	<center>		<center>
	= ~~link~~ =		= support =
	</center>		</center>

	A <tt>~~link~~</tt> statement describes an implementation of support for a link		A <tt>support</tt> statement describes an implementation of support for a link
	field. ~~the~~ support can be any of the following:		or struct field.
			Link support can be any of the following:
	* A link to another record either local or remote		* A link to another record either local or remote
	* A link to hardware support		* A link to hardware support
Line 369:		Line 373:
	The syntax for these is:		The syntax for these is:

	~~link~~(~~dir,~~ choiceName, ~~dataStructName, interface~~(~~interfaceName~~,~~...)~~)		support(choiceName)
			or
			support(choiceName,supportStructName)

	where		where

	~~; <tt>dir</tt>~~
	~~: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.~~

	; <tt>choiceName</tt>		; <tt>choiceName</tt>
	: UTF-8 string that describes the choice		: UTF-8 string that describes the choice

	; <tt>~~dataStructName~~</tt>		; <tt>supportStructName</tt>
	: The name of a <tt>struct</tt> containing configuration information for the ~~link~~ support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.		: The name of a <tt>struct</tt> containing configuration information for the support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

	~~; <tt>interface</tt>~~		When a record instance is created the choiceName
	~~: A list of the interfaces implemented by the link support~~


	When a record instance is created the choiceName ~~and interfaceName~~
	selects the support to attach to a record link.		selects the support to attach to a record link.
	~~The interfaceName must be one of the~~
	~~interface names the record has listed as a valid type and dir must be compatible~~
	~~with the dir the record type specified.~~
	~~Compatibility means that the dir specified in the link definition is at~~
	~~least as generic as the link definition in the record.~~
	~~If the record link dir is:~~
	~~; <tt>none</tt>~~
	~~: The link definition must also be <tt>none</tt>~~
	~~; <tt>process</tt>~~
	~~: The link definition must also be <tt>process</tt>~~
	~~; <tt>in</tt>~~
	~~: The link definition must be <tt>in</tt> or <tt>inout</tt>~~
	~~; <tt>out</tt>~~
	~~: The link definition must be <tt>out</tt> or <tt>inout</tt>~~
	~~; <tt>inout</tt>~~
	~~: The link definition must be <tt>out</tt> or <tt>inout</tt> or <tt>inout</tt>~~

	Examples:		Examples:
	link(~~process,~~processLink~~,ProcessLinkData,interface(ProcessLink)~~)		link(processLink)
			link(monitorLink,MonitorLinkData)
	link(~~in,~~monitorLink,MonitorLinkData ~~interface(~~
	~~LinkBoolean,~~
	~~LinkInt16,LinkInt32,LinkInt64,~~
	~~LinkFloat32,LinkFloat64,~~
	~~LinkString~~
	))

MartyKraimer: Changed DBD link definition

2005-09-30T15:12:36Z

Changed DBD link definition

← Older revision		Revision as of 15:12, 30 September 2005
Line 1:		Line 1:
	DBD Statement Syntax Sept 28 2005		DBD Statement Syntax Sept 30 2005
	----		----
	= Overview =		= Overview =
Line 232:		Line 232:
	The syntax is:		The syntax is:

	link(linkDirection,interface(~~string~~,...))		link(linkDirection,interface(interfaceName,...))

	<b>ANDREW</b>		<b>ANDREW</b>
Line 240:		Line 240:
	where		where
	* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>link</tt> that the record instance selects.		* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>link</tt> that the record instance selects.
	* <tt>interface(string,...)</tt> : Each ~~string~~ is the name of ~~Link Interface~~ implemented by link support and used by record support.		* <tt>interface(string,...)</tt> : Each interfaceName is the name of an interface implemented by link support and used by record support.

	Examples:		Examples:
Line 369:		Line 369:
	The syntax for these is:		The syntax for these is:

	link(dir, choiceName, interfaceName, ~~dataStructName~~)		link(dir, choiceName, dataStructName, interface(interfaceName,...))

	where		where
Line 378:		Line 378:
	; <tt>choiceName</tt>		; <tt>choiceName</tt>
	: UTF-8 string that describes the choice		: UTF-8 string that describes the choice

	~~; <tt>interfaceName</tt>~~
	~~: The name of an interface via which record support communicates with device support.~~

	; <tt>dataStructName</tt>		; <tt>dataStructName</tt>
	: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.		: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

	When a record instance is created the choiceName selects the support		; <tt>interface</tt>
	to attach to a record link. The interfaceName must be one of the		: A list of the interfaces implemented by the link support


			When a record instance is created the choiceName and interfaceName
			selects the support to attach to a record link.
			The interfaceName must be one of the
	interface names the record has listed as a valid type and dir must be compatible		interface names the record has listed as a valid type and dir must be compatible
	with the dir the record type specified.		with the dir the record type specified.
Line 404:		Line 406:

	Examples:		Examples:
	link(in,~~monitorLinkInt16~~,~~LinkInt16~~,~~MonitorLinkData~~);		link(process,processLink,ProcessLinkData,interface(ProcessLink))
	link(in,~~inputLinkInt16~~,~~LinkInt16~~,~~InputLinkData);~~
	~~link(out~~,~~outputLinkInt16~~,~~LinkInt16~~,~~OutputLinkData);~~		link(in,monitorLink,MonitorLinkData interface(
	~~link(inout~~,~~asynInt32~~,~~LinkInt32,AsynLinkData~~)		LinkBoolean,
			LinkInt16,LinkInt32,LinkInt64,
			LinkFloat32,LinkFloat64,
			LinkString
			))

MartyKraimer at 19:19, 28 September 2005

2005-09-28T19:19:08Z

← Older revision		Revision as of 19:19, 28 September 2005
Line 1:		Line 1:
	DBD Statement Syntax Sept 27 2005		DBD Statement Syntax Sept 28 2005
			----
	= Overview =		= Overview =
	This document presents the syntax for V4 database definition files.		This document presents the syntax for V4 database definition files.
Line 130:		Line 131:

	The syntax for <tt>fieldType</tt> depends of the field type. For the more complex types the field definition needs additional information to be provided, which is given inside parentheses following the type name.		The syntax for <tt>fieldType</tt> depends of the field type. For the more complex types the field definition needs additional information to be provided, which is given inside parentheses following the type name.

	~~<blockquote>~~

	=== Basic types: octet, boolean, numerics, and string ===		=== Basic types: octet, boolean, numerics, and string ===
Line 233:		Line 232:
	The syntax is:		The syntax is:

	link(linkDirection,~~array~~(string~~[])= {name~~,...})		link(linkDirection,interface(string,...))

			<b>ANDREW</b>
			What syntax should we use?
			The idea is that the record definition gives a list of interfaces it understands.

	where		where
	* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>link</tt> that the record instance selects.		* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>link</tt> that the record instance selects.
	* <tt>~~array~~(string[])</tt> : Each string is the name of Link Interface implemented by link support and used by record support.		* <tt>interface(string,...)</tt> : Each string is the name of Link Interface implemented by link support and used by record support.

	Examples:		Examples:
	field(disableLink,		field(disableLink,
	link(in,~~array~~(~~string[4]) = {~~		link(in,interface ( LinkInt32, LinkFloat64 ))
	~~"monitorLinkInt32"~~,
	~~"inputLinkInt32",~~
	~~"monitorLinkFloat64",~~
	~~"inputLinkFloat64"~~
	} ))
	)		)
	field(process, link(process,~~array~~(~~string[1])= {processLink}~~))		field(process, link(process,interface(ProcessLink))
	field(inp,		field(inp,
	link(in, ~~array~~(~~string[3]) = {~~		link(in, interface (LinkInt32, LinkFloat64, AsynDigital))
	~~"monitorLinkInt32"~~,
	~~"inputLinkInt32"~~,
	~~"digitalIO"~~
	}))
	)		)
	~~</blockquote>~~

	~~<b>Andrew: Do we want the above syntax? Another possibility is just:~~
	~~link(linkDirection,interface(string,...))~~
	~~</b>~~

	== fieldAttribute ==		== fieldAttribute ==
Line 386:		Line 375:
	; <tt>dir</tt>		; <tt>dir</tt>
	: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.		: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.
	~~: '''Q: What are the rules?'''~~
	~~:: ''It certainly doesn't seem to make sense to have a none or inout link for instance.''~~

	; <tt>choiceName</tt>		; <tt>choiceName</tt>
Line 396:		Line 383:

	; <tt>dataStructName</tt>		; <tt>dataStructName</tt>
	: The name of a <tt>struct</tt> ~~that~~ the ~~interface understands~~. ~~This interface can contain data and~~ configuration ~~information. The <tt>struct</tt> must be defined before record instances can be created that~~ assign values to ~~it.~~		: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.
	~~:: ''Need to rewrite this paragraph to clarify~~.''

	When a record instance is created the choiceName selects the support		When a record instance is created the choiceName selects the support
Line 403:		Line 389:
	interface names the record has listed as a valid type and dir must be compatible		interface names the record has listed as a valid type and dir must be compatible
	with the dir the record type specified.		with the dir the record type specified.
			Compatibility means that the dir specified in the link definition is at
			least as generic as the link definition in the record.
			If the record link dir is:
			; <tt>none</tt>
			: The link definition must also be <tt>none</tt>
			; <tt>process</tt>
			: The link definition must also be <tt>process</tt>
			; <tt>in</tt>
			: The link definition must be <tt>in</tt> or <tt>inout</tt>
			; <tt>out</tt>
			: The link definition must be <tt>out</tt> or <tt>inout</tt>
			; <tt>inout</tt>
			: The link definition must be <tt>out</tt> or <tt>inout</tt> or <tt>inout</tt>

	Examples:		Examples:
	link(in,"monitorLinkInt16",~~"monitorLinkInt16"~~,MonitorLinkData);		link(in,monitorLinkInt16,LinkInt16,MonitorLinkData);
	link(in,"inputLinkInt16",~~"inputLinkInt16"~~,InputLinkData);		link(in,inputLinkInt16,LinkInt16,InputLinkData);
	link(out,~~"outputLinkFloat64"~~,~~"outputLinkFloat64"~~,OutputLinkData);		link(out,outputLinkInt16,LinkInt16,OutputLinkData);
	link(~~process~~,~~"processLink"~~,~~ProcessLink~~,~~ProcessLinkData~~);		link(inout,asynInt32,LinkInt32,AsynLinkData)

MartyKraimer at 20:02, 27 September 2005

2005-09-27T20:02:43Z

← Older revision		Revision as of 20:02, 27 September 2005
Line 380:		Line 380:
	The syntax for these is:		The syntax for these is:

	~~device~~(dir, choiceName, interfaceName, dataStructName)		link(dir, choiceName, interfaceName, dataStructName)

	where		where

MartyKraimer at 15:16, 27 September 2005

2005-09-27T15:16:38Z

Show changes

MartyKraimer at 13:04, 22 September 2005

2005-09-22T13:04:04Z

Show changes

MartyKraimer at 13:01, 22 September 2005

2005-09-22T13:01:29Z

← Older revision		Revision as of 13:01, 22 September 2005
Line 1:		Line 1:
	DBD Statement Syntax Sept 16 2005		DBD Statement Syntax Sept 21 2005
	= Overview =		= Overview =
	This document presents the syntax for V4 database definition files.		This document presents the syntax for V4 database definition files.
Line 95:		Line 95:

	include "dbCommon.dbd"		include "dbCommon.dbd"
	record(name) extends ~~iocRecord~~ {		record(name) extends RecordCommon {
	field(fieldName, fieldType) {		field(fieldName, fieldType) {
	fieldAttribute(attributeValue)		fieldAttribute(attributeValue)
Line 110:		Line 110:
	; <tt>name</tt>		; <tt>name</tt>
	: The record type name. It must be a valid, unique C identifier.		: The record type name. It must be a valid, unique C identifier.
	; <tt>extends ~~iocRecord~~</tt>		; <tt>extends RecordCommon</tt>
	: This states that the record type extends the set of fields defined in [[V4 ~~DBD dbCommon and iocRecord\|iocRecord]]~~. It should be permissable to name other record types instead of ~~iocRecord~~ here, as long as the inheritance tree starts at ~~iocRecord~~. Inheritance from multiple record types is not supported; you can only have one <tt>extends</tt> phrase.		: This states that the record type extends the set of fields defined in "V4 DB RecordCommon". It should be permissable to name other record types instead of RecordCommon here, as long as the inheritance tree starts at RecordCommon. Inheritance from multiple record types is not supported; you can only have one <tt>extends</tt> phrase.
	; <tt>fieldName</tt>		; <tt>fieldName</tt>
	: Must be a valid C identifier, unique within the context of this particular record type and its parents (extends ...).		: Must be a valid C identifier, unique within the context of this particular record type and its parents (extends ...).
Line 173:		Line 173:

	Example:		Example:
	struct(~~point, Coordinate~~) {		struct(Point) {
	field(x, ~~Coordinate~~)		field(x,float64)
	field(y, ~~Coordinate~~)		field(y,float64)
	field(z, ~~Coordinate~~)		field(z,float64)
	}		}
	...		...
	record(haspoint) extends ~~iocRecord~~ {		record(haspoint) extends RecordCommon {
	...		...
	field(point, struct(point~~, float64~~))		field(point, struct(point))
	}		}

Line 225:		Line 225:

	A link field's choices come from link definitions, and a device field from device definitions - see the [[#link and device\|link and device]] section below for more details. The main difference between links and devices is that iocCore and the record support communicate with all the link implementations via a standard link support interface, but communication with device support uses an explicitly named interface.		A link field's choices come from link definitions, and a device field from device definitions - see the [[#link and device\|link and device]] section below for more details. The main difference between links and devices is that iocCore and the record support communicate with all the link implementations via a standard link support interface, but communication with device support uses an explicitly named interface.

	'''Q: Does the device also have to implement some standard device interface, and if yes how do we find that? If not, only the record type can talk to the device, so it has to get called to change a device address.'''

	The syntax is:		The syntax is:
Line 322:		Line 320:
	Example:		Example:

	record(ao) extends ~~iocRecord~~ {		record(ao) extends RecordCommon {
	field(value, float64) { ... }		field(value, float64) { ... }
	field(outValue, float64) { ... }		field(outValue, float64) { ... }

MartyKraimer at 15:37, 16 September 2005

2005-09-16T15:37:23Z

Show changes

AndrewJohnson: Added template structs and methods

2005-07-08T22:43:21Z

Added template structs and methods

← Older revision		Revision as of 22:43, 8 July 2005
Line 12:		Line 12:
	The file system search path that will be used to look for the file is determined by the build system, and cannot be modified by the DBD file itself.		The file system search path that will be used to look for the file is determined by the build system, and cannot be modified by the DBD file itself.

	~~'''Q: Where is this allowed?'''~~		Include statements can be used at the top level, or inside the braces of a <tt>menu</tt>, <tt>struct</tt> or <tt>record</tt> definition.

	~~Ben: I see no problem in allowing it everywhere~~ at the top level.

	== # comment ==		== # comment ==
Line 60:		Line 58:
	= Structures, Record types, Fields and Views =		= Structures, Record types, Fields and Views =

	Structures and record types have significant commonality in that they both define a data structure type containing fields. The main difference is that you can't create or populate an instance of a structure outside of a record; only records can appear at the very top level. Record types also define views of the record, which is not possible for a structure. ~~'''Q: Should it be?'''~~		Structures and record types have significant commonality in that they both define a data structure type containing fields. The main difference is that you can't create or populate an instance of a structure outside of a record; only records can appear at the very top level. Record types also define views of the record, which is not possible for a structure, while structures can also define templates and provide methods, which records can't.

	== struct ==		== struct ==
Line 71:		Line 69:
	...		...
	}		}
			...
			method("memberFunctionDeclaration;")
	...		...
	}		}
Line 84:		Line 84:
	; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>		; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
	: See [[#fieldAttribute\|fieldAttribute]] below.		: See [[#fieldAttribute\|fieldAttribute]] below.
			; <tt>memberFunctionDeclaration</tt>
			: This string is used to declare a C++ member function for the structure. It will be included in the generated C++ header file exactly as given, inside the <tt>struct</tt> definition body. The member function itself must be defined somewhere, probably in a compiled C++ source file. For very short routines, the code could even be included inside the string, resulting in an inline member function.

			=== struct template ===

			A struct can also be used to create a template structure, as follows:

			struct(name, typeName) {
			field(fieldName, fieldType) {
			fieldAttribute(attributeValue)
			...
			}
			field(fieldName, typeName) {
			fieldAttribute(attributeValue)
			...
			}
			...
			method("memberFunctionDeclaration;")
			...
			}

			where

			; <tt>name</tt>
			: The structure name must be a valid, unique C identifier.
			; <tt>fieldName</tt>
			: Must be a valid C identifier, unique within the context of this particular structure.
			; <tt>typeName</tt>
			: Must be a valid C identifier, unique within the context of this particular structure. This will be used as a template typename in the generated C++ header file. Multiple names can be specified here, separated by commas.
			; <tt>memberFunctionDeclaration</tt>
			: This string is used to declare a C++ member function for the structure. The declaration may use any <tt>typeName</tt> identifiers declared for this particular struct. The string provided will be included in the generated C++ header file exactly as given, inside the <tt>struct</tt> definition body. The member function itself must be defined somewhere, probably in a compiled C++ source file. For very short routines, the code could even be included inside the string, resulting in an inline member function.

	== record ==		== record ==
Line 171:		Line 201:

	where <tt>structName</tt> is the name of a struct which must have been previously defined.		where <tt>structName</tt> is the name of a struct which must have been previously defined.

			If <tt>structName</tt> was defined as a template, the appropriate template parameters must be included inside the parentheses so for a single parameter the type name becomes
			struct(structName, typeName)

	Example:		Example:
	struct(point) {		struct(point, Coordinate) {
	field(x, ~~float64~~)		field(x, Coordinate)
	field(y, ~~float64~~)		field(y, Coordinate)
	field(z, ~~float64~~)		field(z, Coordinate)
	}		}
	...		...
	record(haspoint) extends iocRecord {		record(haspoint) extends iocRecord {
	...		...
	field(point, struct(point))		field(point, struct(point, float64))
	}		}

Line 239:		Line 272:
	This is to allow "private" fields, i.e. fields not meant for use by database or channel access. The syntax is:		This is to allow "private" fields, i.e. fields not meant for use by database or channel access. The syntax is:
	private("typename")		private("typename")
	where <tt>typename</tt> is a valid C typename.		where <tt>typename</tt> is a valid C++ typename.

	Example:		Example:
Line 377:		Line 410:

	= link and device =		= link and device =

			: '''Can we do something to define the interfaces here by using struct methods and member function pointers, rather than making up our own separate interface code?'''

	A <tt>link</tt> statement describes an implementation of the generic link interface, which will be available for use in matching link field instances.		A <tt>link</tt> statement describes an implementation of the generic link interface, which will be available for use in matching link field instances.