From 9427acb0a11e8a3abcca3f31378a3e2947ddc836 Mon Sep 17 00:00:00 2001 From: Jim Kowalkowski Date: Tue, 29 Oct 1996 15:40:02 +0000 Subject: [PATCH] Much new doc added. Fixed bug in gdd.cc. --- src/gdd/gdd.cc | 5 +- src/gdd/gddref.html | 61 +++-- src/gdd/gddref2.html | 627 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 669 insertions(+), 24 deletions(-) create mode 100644 src/gdd/gddref2.html diff --git a/src/gdd/gdd.cc b/src/gdd/gdd.cc index 18403bafa..1076f946e 100644 --- a/src/gdd/gdd.cc +++ b/src/gdd/gdd.cc @@ -4,6 +4,9 @@ // $Id$ // // $Log$ +// Revision 1.11 1996/08/27 13:05:05 jbk +// final repairs to string functions, put() functions, and error code printing +// // Revision 1.10 1996/08/23 20:29:36 jbk // completed fixes for the aitString and fixed string management // @@ -1475,7 +1478,7 @@ gddStatus gddAtomic::setBoundingBoxOrigin(const aitUint32* const b) gddStatus rc=0; if(dimension()>0) - for(i=0;iGDD Reference Manual

GDD Reference Manual

-gdd
-gddAtomic
-gddScalar
-gddContainer
-gddApplicationTypeTable
+gdd
+gddAtomic
+gddScalar
+gddContainer
+gddApplicationTypeTable

-gddDestructor
-gddBounds
-gddBounds1D gddBounds2D gddBounds3D
-gddCursor
-gddSemaphore
-gddIntLock
+gddDestructor
+gddBounds
+gddBounds1D gddBounds2D gddBounds3D
+gddCursor
+gddSemaphore
+gddIntLock

-aitConvert
-aitTimeStamp
-aitString
-aitTypes/aitEnums
+aitConvert
+aitTimeStamp
+aitString
+aitTypes/aitEnums

-new/delete Free List Management
-Application Type Code Index Labels
-gddStatus - Error Codes
+new/delete Free List Management
+Application Type Code Index Labels
+gddStatus - Error Codes

-DBR To ait Conversion Functions
-gddMakeMapDBR
-gddMapDbr
-gddAitToDbr
-gddDbrToAit
+DBR To ait Conversion Functions
+gddMakeMapDBR
+gddMapDbr
+gddAitToDbr
+gddDbrToAit

User's Guide
@@ -454,6 +454,21 @@ methods, they are meant to adjust the primitive type. +

gddStatus put(const gdd* dbuf);
+Put the data from dbuf into this GDD. Resets all information in this GDD +to match dbuf. +

return codes: +
+
0 - Success +
gddErrorNotSupported - If this GDD or dbuf is a container. Also if + dbuf has dimension greater than one. +
gddErrorOutOfBounds - Attempting to copying more dbuf elements + into this GDD then this GDD can hold. +
gddErrorNotAllowed - If this GDD has no allocated data but has a + destructor registered. +
+
+

void get(ait_xxxxx* dbuf);
void get(void* dbuf, aitEnum dtype);
diff --git a/src/gdd/gddref2.html b/src/gdd/gddref2.html new file mode 100644 index 000000000..5db31d9f8 --- /dev/null +++ b/src/gdd/gddref2.html @@ -0,0 +1,627 @@ +GDD Reference Manual +

GDD Reference Manual

+ +gddAtomic
+gddScalar
+gddContainer
+gddApplicationTypeTable
+

+gddDestructor
+gddBounds
+gddBounds1D gddBounds2D gddBounds3D
+gddCursor
+gddSemaphore
+gddIntLock
+

+aitConvert
+aitTimeStamp
+aitString
+aitTypes/aitEnums
+

+new/delete Free List Management
+Application Type Code Index Labels
+gddStatus - Error Codes
+

+DBR To ait Conversion Functions
+gddMakeMapDBR
+gddMapDbr
+gddAitToDbr
+gddDbrToAit
+

+User's Guide
+ +

gddAtomic

+Specialized subclass of gdd that provides conveniences ways to create +and manage array-type GDDs. + +

#include "gdd.h"

+ +gddAtomic(void)
+gddAtomic(gddAtomic* dd)
+ +Construct a new gdd that is empty or that is a copy of another gddAtomic +instance. + +

+gddAtomic(int ApplicationType);
+gddAtomic(int ApplicationType, aitEnum PrimitiveType);
+gdd(int ApplicationType, aitEnum PrimitiveType, int Dimension, + aitUint32* ElementCounts);
+gddAtomic(int ApplicationType, aitEnum PrimitiveType, int Dimension, ...); +
+ +Construct a new gdd, describing various data properties. If Dimension +is greater that zero, then ElementCounts is an array with Dimension +number of elements in it. Each element of the array describes how many +elements are in that dimension. The ElementCount information is used to +initialize the bounds of a GDD. The last constructor takes a variable +number of arguments which are the upper bounds for each dimension; the +number of variable arguments must be equal to the Dimension argument. + +

+gddStatus getBoundingBoxSize(aitUint32* buf);
+gddStatus getBoundingBoxOrigin(aitUint32* buf);
+gddStatus setBoundingBoxSize(const aitUint32* const buf);
+gddStatus setBoundingBoxOrigin(const aitUint32* const buf);
+Convenience routines for setting bounds information using bounding box +information. The number of elements of buf must be equal to the dimension +defined in the GDD. These methods can be used to set the bounds information +within a GDD in a convenience way by specifying the origin and size. +Bounds in GDDs are descibed (origin,element_count) for each dimension. These +methods provide an alternative method to set all the origins at once or +all the element_counts at once. +

changeType() return codes: +
+
0 - Success +
gddErrorOutOfBounds - If this GDD has dimension zero +
+
+ +

gddScalar

+Specialized subclass of gddAtomic that provides convenient ways to create +and manage scalar-type GDDs. + +

#include "gdd.h"

+ +gddAtomic(void)
+gddAtomic(gddAtomic* dd)
+ +Construct a new gddScalar that is empty or that is a copy of another gddScalar +instance. + +

+gddAtomic(int ApplicationType);
+gddAtomic(int ApplicationType, aitEnum PrimitiveType);
+ +Construct a new gddScalar, describing various data properties. Dimension is +a gddScalar is always zero. + +

gddContainer

+Specialized subclass of gdd that provides convenient ways to create +and manage container-type GDDs. + +

#include "gdd.h"

+ +gddContainer(void)
+gddContainer(gddContainer* dd)
+ +Construct a new gddContainer that is empty or that is a copy of another +gddContainer instance. A gddContainer always has dimension one and a +single bounds structure allocated to tell how many GDDs are in the container. + +

+gddContainer(int ApplicationType);
+gddContainer(int ApplicationType, int total_gdds);
+ +Construct a new gddContainer, describing the application type. The argument +total_gdds sets the number GDDs contained within the gddContainer in +the element count of this GDDs bound structure. The last constructor listed +also creates total_gdds GDDs, puts them together in a linked list and +sets the data field of this GDD to point to the linked list. The last +constructor creates the container with total_gdds empty GDDs in it. + +

+gddStatus insert(gdd* dd);
+gddStatus remove(aitIndex index);
+Insert dd to the container. Care must be taken not to use the insert method +on a flattened container. Remove GDD number index from the container. The +GDD at index is removed from the container and unreferenced. +

remove() return codes: +
+
0 - Success +
gddErrorOutOfBounds - If GDD at index does not exist. +
+
+ +

+gdd* operator[](aitIndex index);
+gdd* getDD(aitIndex index);
+gdd* getDD(aitIndex index, gddScalar*&);
+gdd* getDD(aitIndex index, gddAtomic*&);
+gdd* getDD(aitIndex index, gddContainer*&);
+Return the GDD at index. + +

+gddCursor getCursor(void) const;
+Get a simple linked list iterator which is useful for manipulating containers. +See gddCursor explanation. + +

gddCursor

+A simple class for moving forward through the GDDs stored in a container. + +

#include "gdd.h"

+ +gddCursor(const gddContainer* c)
+Construct a new gddCursor that can be used to walk through gddContainer c. + +

gddStatus first(.....);
+Set this iterator to the first element of the container. Returns the +first GDD in the container. + +

gddStatus next(.....);
+Set this iterator to the next element of the container. Returns the +next GDD in the container. + +

gddStatus current(.....);
+Returns the current GDD that the cursor points to within the container. + +

gddApplicationTypeTable

+A database for registering application type names and retrieving application +type codes. The database also manages GDD prototype structures associated +with application type names. Methods exist for allocating and freeing GDDs +given a type code. See User's Guide for details. + +

#include "gddAppTable.h"

+ +gddApplicationTypeTable(aitUint32 total)
+Construct an application type table capable of holding total amount +of application type codes. The user does not need to create one of these, +the library automatically generates one instance of this class large enough +to hold 512 type codes. This automatically generated instance registers +all the standard EPICS control system type codes, see User's Guide. + +gddStatus registerApplicationType(const char* const name, + aitUint32& app);
+gddStatus registerApplicationTypeWithProto(const char* const name, + gdd* protoDD, aitUint32& app);
+Register an application type name. The type table will return the +application type code in app that the system has assigned to the name. +The latter function allow a prototype GDD to be registered aloong with +the name. This prototype is describes the structure of the data associated +with the application type name. See User's Guide for more details. +

return codes: +
+
0 - Success +
gddErrorAlreadyDefined - If name is already refined, app + still returns the type code assigned to the name. +
gddErrorAtLimit - The type table is filled, no more names can be + stored in it. +
+
+ +aitUint32 getApplicationType(const char* const name) const;
+char* getName(aitUint32 app) const;
+Convert a character string type name to it's integer value. Convert an +integer value to it's character string name. + +gddStatus mapAppToIndex(aitUint32 container_app, + aitUint32 app_to_map, aitUint32& index);
+Special function for converting type codes to container GDD array indexes. +The GDD must be a flattened GDD managed by the application type table for +mapping to take place. The container_app argument is the main +structure that contains app_to_map. The index is populated +with the position where app_to_map is within container_app. +See User's Guide for details. +
return codes: +
+
0 - Success +
gddErrorOutOfBounds - app_to_map cannot be mapped +
gddErrorNotDefined - container_app does not exist or app_to_map not + in container_app +
+
+ +gddStatus smartCopy(gdd* dest, gdd* src);
+Given any GDD dest and any GDD src, copy all the data from src to dest +where application type codes match. The src and dest can be any type of +GDD: scalar, array, or container. The src dset do not need to be the +same type of GDD. If dest and src are both containers. The function will +look through each of the src GDDs to find matches for each of the dest GDDs. +SmartCopy() may result in no data being copied if none of the src type codes +match the dest type codes. The dest and src container GDDs do not need to +be in the same order. +
return codes: +
+
0 - Success +
gddErrorNotAllowed - src or dest is container and is not managed +
other - see put(const gdd*) +
+
+ +gdd* getDD(aitUint32 app);
+Allocate a GDD for the app and return it. If app has a prototype +registered with it, then the returned gdd will be managed and match the +prototype. + +gddStatus freeDD(gdd* dd);
+Free any gdd. The method basically just calls unreference on dd. If the +GDD is managed, then it puts it onto a free list for it's application type +code. + +aitUint32 maxAttributes(void) const;
+aitUint32 totalregistered(void) const;
+Return the total number of names registered in this application type table. +Return the total number of names that can be registered in this application +type table. + +void describe(FILE* fd);
+Print out "#define" statements for each of the names registered in this +table. Also print out container index labels in the form of #defines. See +User's Guide for details. The file gddApps.h is generated using this +function. + +static gddApplicationTypeTable& AppTable(void);
+Return the automatically generated application type table for use in a +program. + +

gddDestructor

+The gdd class knows how to run and manage gddDestructors. User's assign +destructors to gdd by deriving classes from gddDestructor. + +

#include "gdd.h"

+ +gddDestructor(void);
+gddDestructor(void* user_arg);
+Create a gddDestructor, optionally placing an arbitrary pointer in the +destructor which can be referenced when the destructor is actual run. + +gddStatus destroy(void* thing_to_remove);
+virtual void run(void* thing_to_remove);
+The destroy method in invoked by anyone withing to request the destructor +to be run. Destroy invokes the user-written function run when +it's reference count goes to zero. Run should not be invoked +directly by the user. The argument to destroy is the buffer that +needs to be freed by by the destructor. The gdd class invokes destroy +when unreference is called and the gdd's reference count goes to zero. The +default behavior of run is to cast the buffer thing_to_remove to a +character array and delete it. + +void reference(void);
+int refCount(void) const;
+Calling refCount will return the current value in the destructor +reference count. Reference will bump up the reference count of this +destructor. + +

gddBounds

+A simple class to describe the boundaries of a dimension. + +

#include "gdd.h"

+ +void setSize(aitIndex c);
+Sets the number of elements for this bounds. +void set(aitIndex first, aitIndex cnt);
+void get(aitIndex& first, aitIndex& cnt);
+Set and get the first element in this bounds and the number of elements. +aitIndex size(void) const;
+Return the number of element in this bounds. +aitIndex first(void) const;
+Return the first element in this bounds. + +

gddBounds1D gddBounds2D gddBounds3D
+Specialized classes for describing with one, two, and three dimension data. +Since three of less dimension are the most common, bounds array classes for +each type exist and are managed on free lists. All of these classes +overload the new/delete operators so that the memory allocater is not used. +All of these classes are just arrays of gddBounds. Only one method exists +in these classes, gddBounds* boundArray(void), which returns a pointer +to the array of gddBounds. + +

#include "gdd.h"

+ +

gddSemaphore
+Simple wrapper around the underlying OS semphore functions. Implimentation +is OS dependant and is not really relevant in single threaded application. +This is a binary semaphore meant to be used for locking sections of code +or perhaps in a simple producer/consumer program. + +

#include "gddUtils.h"

+ +gddSemaphore(void)
+gddSemaphore(gddSemType init)
+Create a simple binary gddSemaphore which defaults to full. Create a +gddSemaphore which +is set initially to state init. Init is either gddSemEmpty or +gddSemFull. + +void give(void)
+void take(void)
+Operations for manipulating the semaphore. Take will block if the +semaphore is empty, waiting until it is full. Give sets the +semaphore back to full state. + +int take(aitUint32 usec)
+Attempt to perform the semaphore take operation. Only block for usec +microseconds. Returns true if time-out occurred and semaphore is not +really taken. + +

gddIntLock
+A simple wrapper around OS interrupt locking services. + +

#include "gddUtils.h"

+ +

aitConvert
+A set of convenience functions for quickly converting arrays of data from one +aitType to another. The header file for these functions also contains a +set of standard functions for converting each of the ait types from/to +network byte order. + +

#include "aitConvert.h"

+ +void aitConvert(aitEnum desttype, void* dest, + aitEnum srctype, const void* src, aitIndex count)
+Take count number of elements from src of type srctype, +copy then to dest and at the same time convert them to type +desttype. + +void aitConvertToNet(aitEnum desttype, void* dest, + aitEnum srctype, const void* src, aitIndex count)
+void aitConvertFromNet(aitEnum desttype, void* dest, + aitEnum srctype, const void* src, aitIndex count)
+Same as aitConvert but change the byte order or data format to/from +network format. If the local host data format is network data format, +then these function are exactly the same as aitConvert. + +aitLocalNetworkDataFormatSame
+This is a #define which is true if local host byte order is the same +as network byte order, otherwise it is false. + +

aitTimeStamp
+A class for storing and manipulating standard time stamps. This time +is similar to POSIX time stamps, it maintains time in seconds/nanoseconds +past a standard epoch. POSIX defines a time stamp as a long for seconds +and a type time_t for nanoseconds. Time_t is OS dependant and so is a +long. aitTimeStamp forces seconds and nanoseconds to be unsigned 32 bit +integers so the storage size is fixed and known. + +

#include "aitHelpers.h" +Automatically included if aitTypes.h is included.

+ +operator double()
+operator float()
+Convert (cast) the seconds/nanoseconds to a double or float seconds with +decimal fraction of a second past epoch. + +static aitTimeStamp getCurrent();
+Retrieve the current time in aitTimeStamp format. + +void get(unsigned long &tv_secOut,unsigned long &tv_nsecOut);
+Retreive the various parts of the time stamp as separate quantities. + +aitTimeStamp()
+aitTimeStamp(const aitTimeStamp &t)
+aitTimeStamp(const unsigned long sec, const unsigned long nsec)
+Create an aitTimeStamp that is initially zero or set to various values. + +const unsigned NSecPerSec = 1000000000u;
+const unsigned NSecPerUSec = 1000u;
+const unsigned SecPerMin = 60u;
+Various constants for working with time. + + +aitTimeStamp operator+ (const aitTimeStamp &lhs, const aitTimeStamp &rhs);
+aitTimeStamp operator- (const aitTimeStamp &lhs, const aitTimeStamp &rhs);
+int operator>= (const aitTimeStamp &lhs, const aitTimeStamp &rhs);
+ +They are global functions for adding and subtracting and comparing time stamps. + +

aitString
+Standard class for holding and managing a variable length string. Strings +is GDD have two attributes associated with them: length and state. Length +is simply the total length of the string and state either constant or +allocated. + +

#include "aitHelpers.h" +Automatically included if aitTypes.h is included.

+ +aitString(void);
+Construct an aitString that is empty. + + +aitString(char* str); +aitString(aitString* str); +aitString(aitString& str); +
+Construct an aitString which contains a copy of str. The +state of this aitString will be "allocated". + + +aitString(const char* str); +aitString(const aitString* str); +aitString(const aitString& str); +
+Construct an aitString which contains a reference to str. The +state of this aitString will be "constant". + +void clear(void);
+Clear out this aitString, freeing up any storage that may be allocated. + +void dump(void) const;
+void dump(const char* id) const;
+Print the contents of this aitString to stdout in a readable format. Good +tool for debugging or understanding the aitString class. + + +operator const char*(void) const; +operator char*(void) const; +
+Pull out a reference to the string that this aitString is holding. These +are casting operators from aitString to char*. + +int isConstant(void) const;
+Returns true is this aitString hold a constant string. + + +aitUint32 length(void) const; +const char* string(void) const; +
+Return the length of the string in this aitString. Return a reference to +the string in this aitString. + + +aitString& operator=(......);
+int copy(......);
+
+Create a copy of the variable string arguments in this aitString. This +aitString attributes will match that of the arguments. The assignment +operators just invoke copy(......). + +void replaceData(......);
+Replace the data in this aitString with the string in the argument. This +function will only copy this aitStrings length number of bytes into it's +string from the argument string. + +void installString(......);
+Invoke replaceData if this aitString is "constant". Invoke copy if this +aitString is not "constant". + + +static aitUint32 totalLength(aitString* array,aitIndex arraySize);
+static aitUint32 stringsLength(aitString* array,aitIndex arraySize);
+static aitIndex compact(aitString* array, aitIndex arraySize, + void* buf, aitIndex bufSize); +
+totalLength() returns the total number of bytes that an array of aitStrings +requires. This length include the size of all the strings in the aitStrings. +Array is the aitString array, arraySize is the number of +elements in array array. The function stringsLength +returns the total length of all the strings in aitString array array. +The function compact takes aitString array array with +arraySize elements and places all the data contiguously into buffer +buf. The compacted buffer is bufSize number of bytes. The +compact function places all the aitString instances of the array at +the front of buf. The aitStrings in buf reference strings that are +further into the buffer buf. Compact returns the total +number of bytes used in buf. + +

aitTypes/aitEnums
+Standard GDD data types and enumerations for them. This header file contains +many macros for dicovering information about aitTypes. See the header. + +

#include "aitTypes.h"

+ +

+	aitInt8			8 bit signed integer
+	aitUint8			8 bit unsigned integer
+	aitInt16			16 bit signed integer
+	aitUint16		16 bit unsigned integer
+	aitEnum16		16 bit unsigned integer
+	aitInt32			32 bit signed integer
+	aitUint32		32 bit unsigned integer
+	aitFloat32		32 bit floating point number
+	aitFloat64		64 bit floating point number
+	aitIndex			32 bit unsigned integer for indexing arrays
+	aitPointer		largest pointer a system can hold
+	aitStatus		32 bit unsigned integer
+	aitBool			standard "c" enum - value aitTrue or aitFalse
+	aitFixedString	A fixed string of length AIT_FIXED_STRING_SIZE
+	aitTimeStamp	The standard seconds/nanoseconds time stamp
+	aitString		Class for manipulating and storing strings
+
+ + +aitTotal +aitConvertTotal +aitValid(x) +aitConvertValid(x) +
+Value of the first two are the number of valid types. All the ait types +cannot be automatically converted using aitConvert. AitValid(x) returns +true if x has a valid ait type enumeration associated with it. +AitConvertValid(x) returns true if enumerated value x can be converted using +aitConvert. + +aitEnum
+This is an enumerated data type, there is one name per ait types. See +header file for the definition. + +aitType
+Data union of all the ait types. + + +aitSize[aitTotal] +aitName[aitTotal] +aitStringType[aitTotal] +
+Arrays used for discovering information about ait types using the enumerated +ait type name as the index into the array. aitSize returns the size in +bytes of the ait type. aitName returns a character string name of the +ait type. aitStringType returns a string which can be used in sscanf to +read or convert a string into the actual ait type. + +gddStatus - Error Codes
+Error codes returned by various GDD library functions and methods. See header +file. +

#include "gddErrorsCodes.h"

+char* gddErrorMessages[]
+Return an error message string name for an error code. + +

new/delete Free List Management
+

#include "gddNewDel.h"

+A set of generic member function macros that can be added to any class +to allow the class to be managed on a free list using the new/delete +operators. See the header file for details on how to use this +facility. Most GDD library classes use this facility. + +

Application Type Code Index Labels
+

#include "gddApps.h"

+This file is generated from the standard application type table. It +contains all the #define statements for preregistered containers and +application type codes. + +

+

DBR To ait Conversion Functions
+

gddMapDbr
+

gddAitToDbr
+

gddDbrToAit
+

#include "dbMapper.h"

+Large set of utility functions for converting between EPICS DBR data types +and GDD containers. + +void gddMakeMapDBR(gddApplicationTypeTable& table);
+The DBR mapping facility is not initialized automatically. It must be +initialized using this function before any of the functions are called. +It should be passed the standard default +application type table as an argument. + +chtype gddAitToDbr[]
+Given an ait type code, return the equivalent EPICS DBR type code. + +gddDbrToAitTable gddDbrToAit[]
+Given a DBR type code, return a structure that describe the ait/GDD type code +informtion for that DBR type code. The information in gddDbrToAitTable is +the GDD application type code and GDD application type name for a given DBR +type. This information is not extremely useful for simple applications. + +gddDbrMapFuncTable gddMapDbr[]
+Array of conversion functions that convert between DBR structures and GDD +types. The index of this array is always the DBR type code, not the +GDD application type code. Each element of the array contains to functions: +conv_gdd and conv_dbr. Conv_gdd takes a DBR structure and returns a GDD +equivalent to the DBR structure. Conv_dbr takes a GDD and puts all the data +into a DBR structure. + +

+struct gddDbrMapFuncTable {
+	to_gdd conv_gdd;
+	to_dbr conv_dbr;
+};
+
+gdd* to_gdd(void* dbr_data_structure, aitIndex dbr_element_count);
+int to_dbr(void* dbr_data_structure, gdd* gdd_instance); 
+
+ +
Argonne National Laboratory +Copyright +Information
+
Jim Kowalkowski (jbk@aps.anl.gov)
updated 4/12/95 +