Documentation

Axis1.Data namespace reference (other)

Please see Programming home for definitions of ponds, fish, and parameters.

AxFishRef

Stores a reference to one fish, for the purpose of mapping a key value to display text. Used with AxTypeRef.

int Key - Key value

string Display - Display text; default is " " (one space)

bool Visible - Controls visibility in dropdown lists (default true)

AxLocalPond

Derived from AxPond, AxLocalPond is a pond that uses a local file to store a database. AxLocalPond instances exclusively lock the file while open.

You must call Close() to close the file; garbage collection will not close it for you.

Refer to AxPond for database-level methods that apply to both local and remote ponds.

AxLocalPond(string filename, bool isWorkstation) - Constructor. Filename is the full path and name, which will be opened exclusively by this process until Close() is called. If isWorkstation is true, Axisbase creates AxPond.LinkedPondCollection and opens all the linked ponds defined in this pond. The Axisbase client sets isWorkstation=true, but most outside utilities and web site code should pass false.

void SaveCopyAs(string filename) - Save a copy of the open pond as the given file name. The copy may be somewhat smaller than the original if compression was possible.

string FilePath - Gets the filename passed to the constructor.

AxObjectBase

An abstract base class that you can derive from to easily implement object-relational mapping. This implements IAxObject.

For example, if you have a record type with properties "alpha" and "beta", and the derived class defines fields named "alpha" and "beta", the fields will be mapped to the record properties with the same name. The derived class may also have additional fields, and it need not have all fields that the record type defines.

This description will use the word "object" to refer to the instance of AxObjectBase, and "fish" to refer to a fish that is stored in the database. The constructor can be used in three ways: (1) to instantiate a new object unlinked to any fish, (2) to create a new fish and object with default values, or (3) to create an object that stores the contents of an existing fish.

When creating a class derived from AxObjectBase, you should provide the two constructors, and in each case, call the base constructor. Please see the tutorial Using Axisbase as an Embedded Database.

AxObjectBase() - Shortcut to passing nulls to the longer constructor. Use this constructor to create an unlinked object.

AxObjectBase(AxPond pond, AxCompoundType t, Hashtable fish) - Constructor for existing or new fish. If the object represents an existing fish, pass a hashtable (pond and t are ignored). The object's fields will be set based on the hashtable entries. If the object is to represent a new fish, pass a null hashtable, and an open pond and the AxCompoundType. In this case, the constructor will create the fish in the pond, and set the object's AxisKey property and all other fields to default values. If pond and fish are both null, creates an unlinked object without setting any default values.

int AxisKey - Gets or sets the object key

bool Save(AxPond pond, AxCompoundType t) - Saves the fish in the given pond, assuming the given record type. If AxisKey==0, first creates the fish in the pond and sets AxisKey.

AxPond

Encapsulates an Axisbase database. Since this is an abstract class, you must create either an AxLocalPond or an AxRemotePond.

void Close() - You must call Close when done with the pond to close the file or connection and release resources. You cannot re-open an instance.

bool Closed - Gets whether this instance is closed

bool HasRight(string typename, RightKind kind) - Gets whether the current user has the given access right. Typename is the unqualified name of a record type in this pond. Kind is one of: View, Edit, Add, Delete. Local ponds always return true, since security is only applied for server connections.

short TypesVersion - Gets the version number of the schema of record types. This number is incremented each time types are changed. If the caller has a cached AxCompoundType, and the TypesVersion has not changed since it was obtained, then it is still valid.

string[] GetLocalTypeNames() - Gets the list of unqualified record type names in this pond, excluding system types

string[] GetLocalTypeNames(bool includeSystemTypes) - Gets the list of unqualified record type names in this pond, and optionally includes system types such as ^user and ^form.

string[] GetAllTypeNames() - Gets the list of qualified record type names in this pond and all linked ponds, excluding system types. Each returned name is prefixed with the AxisID.

string[] GetAllTypeNames(bool includeSystemTypes) - Gets the list of qualified record type names in this pond and all linked ponds, and optionally includes system types such as ^user and ^form. Each returned name is prefixed with the AxisID.

AxCompoundType GetLocalAxisType(string name) - Get a compound type from a local unqualified name. Returns null if not found.

AxCompoundType GetLinkedAxisType(string axisID, string name, out AxPond pond) - Get a compound type from this pond or a linked pond, given the Axis ID and the unqualified type name. The out argument pond is set to the pond where the type was found. Returns null if not found.

AxCompoundType GetLinkedAxisType(string name, out AxPond pond) - Get a compound type from this pond or a linked pond, given the qualified type name, in the form AxisID.name. The out argument pond is set to the pond where the type was found. Returns null if not found.

AxTypeChangeInfo AnalyzeChangeType(AxCompoundType oldt, AxProposedCompoundType newt) - Analyzes the proposed record type change from oldt to newt. The returned object contains fields that explain what properties will be converted, and whether the type change is allowed.

AxCompoundType ChangeType(AxCompoundType oldt, AxProposedCompoundType newt, AxTypeChangeInfo defaultValues, IProgressVisualizer progress) - Changes the record type oldt to newt, and returns the new type. DefaultValues can be obtained from a call to AnalyzeChangeType, and may be updated to include default values for properties that will be added in the type change. Progress may be null or any IProgressVisualizer. ChangeType assumes that any property in newt whose name matches a property in oldt is the same property, regardless of the order in which properties are defined in oldt and newt. If you want to change the name of a property, you must make a separate call to ChangePropertyNames.

void DeleteType(AxCompoundType t) - Deletes a record type. This fails if there are any records, or if the type is used in another type.

void RenameType(AxCompoundType t, string newName, string newComment, Dictionary<string, string> newTypeData) - Renames a type, and updates its comment and dictionary of type level data.

AxCompoundType AddType(AxProposedCompoundType t) - Creates a new record type.

List<AxFieldInfo> GetFieldInfo(AxCompoundType t) - Gets the field information for a record type, which is a list of all the primitives that are stored and the AxProperty objects that they were created from.

void ChangePropertyNames(AxCompoundType t, List<string> oldnames, List<string> newnames) - Change the property names in a record type. For each name in oldnames, change the name to the name found in the corresponding position in newnames.

Hashtable LoadFish(AxCompoundType t, int key) - Load a fish from a known type and key. The hashtable has simple unqualified field names as keys. An exception is thrown if the key does not exist.

Hashtable LoadFish(AxCompoundType t, AxFishnet net) - Load a fish from a known type and fishnet. Only the first row found in the first table loaded by the fishnet is returned, so this is meant to be used with fishnets that filters to one record. Returns null if not found.

object LoadFishObject(string axisType, AxFishnet net, Type objType) - Load a fish from a known type and fishnet, then convert it to an instance of the given objType. The type objType must have a parameterless constructor and have public fields matching the field names in the fish type. Only the first row found in the first table loaded by the fishnet is returned, so this is meant to be used with fishnets that filters to one record. Returns null if not found.

object LoadSingleValue(AxFishnet net) - Calls CatchFish, then returns DataSet.Tables[0].Rows[0][0] with error checking. Returns null if no rows or columns found.

AxDataSet CatchFish(AxFishnet net, AxParameterShed pshed, IFishnetLocator locator, IPreloadedDataLocator preloader, string[] inactivePrompts, IProgressVisualizer progress) - Loads a data set based on a fishnet and parametershed. If the fishnet is based on another fishnet, locator must be a non-null instance of an IFishnetLocator capable of locating other fishnets. If the fishnet is based on preloaded data, then preloader must be set to an instance of IPreloadedDataLocator capable of obtaining that data. If inactivePrompts is non-null, then any filters in the fishnet whose Prompt property match one of the included inactive promts will be ignored, so it will not apply that filter.

AxDataSet CatchFish(AxFishnet net) - Shortcut to the long form of CatchFish, passing all nulls except net.

AxDataSet CatchFish(string typeName, int maxRows, IProgressVisualizer progress) - Loads all records of a given record type from this pond; cannot be used for linked ponds. MaxRows specifies how many to load. TypeName is unqualified.

Hashtable CreateFish(string axisType) - Create a new fish using the given qualified type name. Returns null on bad type name; raises exception on other failures.

Hashtable CreateFish(AxCompoundType t) - Create a new fish of the given record type.

bool SaveFish(AxCompoundType t, Hashtable fish) - Save a fish. It only saves the fields that exist in the hashtable; any other fields are left as they were. Sets fish["^ver"] to the new fish version. If the fish version is supplied in the hashtable and is incorrect, raises exception. Returns true on success.

bool SaveFish(string axisType, Hashtable fish) - Save a fish to this pond or any linked pond. AxisType is a qualified type name, prefixed with the Axis ID. Returns true on success.

void SaveFish(AxDataSet ds) - Short form of SaveFish - see below.

void SaveFish(AxDataSet ds, IProgressVisualizer progress) - Saves changes to a data set, which may contain any number of tables, each with any number of record types, and may contain new, changed, or deleted rows. Determines the affected types by name: any column having the name AXISID.typename.fieldname is assumed to belong to the type AXISID.typename. Writes newly assigned key values back to the dataset. Calls AcceptChanges on each DataRow that is saved to at least one record type. As the dataset is never remoted, changes are visible to the caller. Changes include calls to AcceptChanges and RowError. Caller should check HasChanges and HasErrors after calling SaveFish. All row errors are cleared prior to the save.

void DeleteFish(AxCompoundType t, int key) - Deletes a fish.

string AxisID - Gets or sets the Axis ID of this database.

LinkedPondCollection LinkedPonds - Provides access to linked ponds. This value is null in a server context.

AxPond GetLinkedPond(string axisID) - Get a linked pond by ID, or null if not found.

DisplayTypeCollection DisplayTypes - Provides access to the display types defined in this pond.

AxTypeRef GetCachedReferences(AxCompoundType t) - Gets an AxTypeRef instance for the given record type, to use as a lookup of display values.

long GetCounter(string name, bool increment, out string expr) - Gets a counter value and formatting expression. If increment is false, returns the highest value already used; if true, returns a new value to be used in a new record.

AxRemotePond

Derived from AxPond, AxRemotePond is a pond that uses a network connection to the Axisbase server to communicate with a served database.

Refer to AxPond for database-level methods that apply to both local and remote ponds.

AxRemotePond(string host, int port, string axisID, bool isWorkstation, bool longDuration) - Constructor. Host, port, and axisID identify the host and database to connect to. If isWorkstation is true, it initializes and opens all linked ponds. Pass longDuration=true for desktop applications, and false for web or other applications that open and close connections frequently.

void Authenticate(string user, string pw, out bool shouldChangePassword) - Authenticates a connection. You must create the instance (which establishes a link to the server) and call Authenticate before any other calls will be accepted. User and password (pw) must be defined in the pond, otherwise an exception will be thrown. If shouldChangePassword is set true, this indicates that the user interface should prompt for a password change, but this is not enforced.

void ChangePassword(string oldpw, string newpw) - Change the password for the current user.

bool IsAuthenticated - Gets whether this connection is autenticated.

AxTypeRef

Stores a list of AxFishRef instances for one record type. To obtain an instance, call AxPond.GetCachedReferences.

AxCompoundType CompoundType - Gets the compound type.

AxFieldInfo SearchFieldInfo - Gets the field that is used to search by, from type level data.

void RefreshAll() - Reload refrence list. If there are less than 500, make them visible. Cache the first 500 references.

void PreFetch(object[] keys) - Pre-fetch a list of keys, and make each added item visible. This may be used to reduce the number of server calls that would be made if Get were called repeatedly and had to make a server call each time.

List<AxFishRef> Search(string searchTerm, AxRefSearchMode mode) - Perform a search on records and return a list of matching references. The search mode is one of Equals, Contains, or StartsWith.

void Remove(int key) - Remove a reference by key.

void AddFromSearch(AxFishRef fr) - Call this after a specific reference obtained from Search() is chosen, and you want this reference to be cached.

AxFishRef Get(int key) - Get the reference for the given key. If the reference is not cached, it loads it.

AxFishRef[] GetAll() - Gets all cached references.

bool IsCached(int k) - Determines if a reference for the given key value is cached.

DisplayTypeCollection

A collection of display types. AxPond owns an instance of DisplayTypeCollection, through which you can inspect, change, and create display types. Instead of creating an instance, use AxPond.DisplayTypes. The collection is a lightweight cache of SysDisplayType objects, which are fish of the type ^displaytype.

DisplayTypeCollection(AxPond pond) - Constructor. Loads the display types into a cache.

string[] GetNames() - Return the names of all the display types.

SysDisplayType Get(string name) - Get a display type by name.

void Save(SysDisplayType dtype) - Save a display type that was obtained from Get, or is a new instance. Note that this calls dtype.Save() and updates the cache.

void Delete(SysDisplayType dtype) - Deletes a display type that was obtained from Get. This deletes from the pond as well as from the cache.

FishnetBuilder

A helper class to allow you to build instances of AxFishnet with less code. You typically use one of the constructors or one of the static methods that returns a constructed instance, then if needed, call one or more of the methods that add tables and steps, then finally refer to the Fishnet property to obtain the built instance of AxFishnet.

The tables in the fishnet are numbered starting from zero. The constructor creates table #0 for you. Many of the methods require a table number argument. If your fishnet only has one table, always pass 0 for this argument.

WARNING: Some of the methods expect qualified names (such as "SATURN.peron.name") while others expect unqualified names (such as "name"). The format is explained under each method.

FishnetBuilder(string typename, int maxrows, string sortby) - Full constructor. Creates a one-table fishnet (using table #0). Typename is the qualified name. Maxrows is the maximum number of rows to load (see AxFishnetTableDef.MaxRows). If sortby is a qualified column name, it adds a sort step for this column; if null, no sort step is added.

FishnetBuilder(string typename) - Shortcut to the full constructor for unlimited rows and no sorting.

static FishnetBuilder CreateSingleRow(string typename, stirng uqFilterCol, string val) - Convenience method to construct a FishnetBuilder instance for loading all columns of a single record, using an equality filter. Generally the use for this method is to load a single record when you have one uniquely identifying field value - such as loading a single employee by emploee ID. Typename is the qualified type name. UqFilterCol is the unqualified filter column, such as "id". Val is the value to match.

static FishnetBuilder CreateSingleValue(string typename, stirng uqFilterCol, string val, string uqNarrowCol) - Convenience method to construct a FishnetBuilder instance for loading a single column of a single record, using an equality filter. Generally the use for this method is to load a single value when you have one uniquely identifying field value - such as loading the name of a single employee by emploee ID. You often use the built fishnet from this call as an argument to AxPond.LoadSingleValue. Typename is the qualified type name. UqFilterCol is the unqualified filter column, such as "id". Val is the value to match in the filter column. UqNarrowCol is the unqualified name of the column that you want the value of (such as "name").

AxFishnet Fishnet - Gets the fishnet that the FishnetBuilder is building.

int AddTable(AxTableDef tab) - Adds a table definition to the fishnet, sets the AxTableDef owner, and returns the table number of the added table.

int AddTypedTable(string typename, int maxrows) - Adds a AxTypedTableDef to the fishnet. Wraps AddTable. Typename is the qualified type name.

void AddStep(int tabNo, AxTableStep step) - Adds a step to a table in the fishnet. When possible it is generally it is easier to call the methods for specific step types, like Link, Combine, Sort, and so on.

void Link(int parentTabNo, string parentColName, int childTabNo, string childColName) - Adds a link (master/detail) step to the parent table.

void Combine(int parentTabNo, string parentColName, int childTabNo, string childColName) - Adds a combine (join) step to the parent table.

void Sort(int tabNo, string sortCols) - Adds a sort step.

void FilterEquals(int tabNo, string filterCol, string val, string paramName) - Adds an equality filter step. If paramName is null, the filter will compare against val. If val is null, the filter will use the value of the parameter named by paramName.

void FilterLessThan(int tabNo, string filterCol, bool orEquals, string val, string paramName) - Adds a less-than filter. If orEquals is true, adds a less-than-or-equal-to filter. (See FilterEquals for the use of the other arguments)

void FilterGreaterThan(int tabNo, string filterCol, bool orEquals, string val, string paramName) - Adds a greater-than filter. If orEquals is true, adds a greater-than-or-equal-to filter. (See FilterEquals for the use of the other arguments)

void FilterRange(int tabNo, string filterCol, bool lowerBounded, bool upperBounded, string lowVal, string lowParamName, string hiVal, string hiParamName) - Adds a fast range filter. If lowerBounded or upperBounded are true, the range includes the low and high values respectively. If lowParamName or hiParamName are null, the filter matches lowVal and hiVal respectively. If lowVal or hiVal are null, the filter matches the value of the parameter named by lowParamName or hiParamName.

void FilterLike(int tabNo, string filterCol, string val, string paramName) - Add a starts-with filter for string columns, similar to the SQL LIKE operator. (See FilterEquals for the use of the other arguments)

void FilterComplex(int tabNo, string expr) - Adds a complex filter. Expr is the filter expression, which must evaluate to true or false for each tested row.

void Narrow(int tabNo, List<string> columns) - Add a narrowing step with multiple column names.

void Narrow(int tabNo, string[] columns) - Add a narrowing step with multiple column names.

void Narrow(int tabNo, string column) - Add a narrowing step with one column name.

LinkedPondCollection

A collection of linked ponds. AxPond owns an instance of LinkedPondCollection, through which you can inspect, add, or remove linked ponds. You can use the collection to obtain an instance of AxPond for a linked pond. Use AxPond.LinkedPonds instead of instantiating an instance of LinkedPondCollection. Note that in the Axisbase client, this is only ever used in the workstation context. The server does not pay attention to linked ponds.

Axisbase stores links as records of type ^axislink. SysAxisLink is a class that stores ^axislink records.

Linked ponds may be direct or indirect. A indirectly linked pond is one that is linked through some other pond's linked ponds. For example, if pond A defines a link to pond B, and pond B defines a link to pond C, the links A->B and B->C are direct, and A->C is indirect. When you open pond A in the Axisbase client, you will see record types, records, and building blocks from all three ponds.

string[] GetLinkedAxisIDs(bool includeErrors, bool includeThisPond) - Gets a list of Axis IDs of directly and indirectly linked ponds. If includeErrors is true, includes linked ponds that cannot be opened; otherwise includes all linked ponds. If includeThisPond is true, includes this pond with all linked ponds; otherwise includes only linked ponds.

SysAxisLink GetLink(string axisID) - Get a direct link by name, or null if not found.

SysAxisLink CreateLink() - Create a new direct link.

void DeleteLink(SysAxisLink link) - Delete a direct link, which was obtained from GetLink.

void SaveLink(SysAxisLink link) - Save a link which was obtained from GetLink. You can change the public fields in SysAxisLink before calling SaveLink.

AxPond GetLinkedPond(string axisID) - Get an AxPond instance for a directly or indirectly linked pond by Axis ID, or return null if not found.

bool GetLinkUserInfo(string ID, out string user, out string password) - Get credentials stored in a direct or indirect link.

void CloseAll() - Close all AxPond instances for all linked ponds.

RemotePondPool

Implements a re-usable pool of connected AxRemotePond instances. This mainly exists for web applications, but can be used whenever connections are required for short durations, repeatedly. The pool automatically matches request's host, port, Axis ID, user, and password to an inactive instance and allows you to reuse it without re-connecting.

It is essential to release the instances of AxRemotePond that you obtain from RemotePondPool, by calling the Release method, and don't call AxRemotePond.Close, so that they can be used again. Call Release within a finally block.

RemotePondPool automatically closes and frees the memory associated with connections that are unused for a period of time. However, if your application ends while some AxRemotePond instances are still active in the pool, the pool's background thread will exit, leaving the connections active. In this case, the server will eventually kill those connections and free its memory.

As the class is abstract and the pooled ponds are stored in static variables, use static methods to access the pool.

static AxRemotePond Get(string host, int port, string axisID, string user, string password) - Get a reusable AxRemotePond instance

static void Release(AxRemotePond pond) - Release an AxRemotePond instance that was obtained from Get.

SequenceGenerator

Contains static methods to generate sequences of numbers or dates.

static AxDataTable Generate(string tableName, string columnName, int fromValue, int toValue, int step) - Creates an AxDataTable with one int column. Creates rows with a sequence of integers from fromValue to toValue. Step is normally 1; if step is >1, steps that many numbers for each row.

static AxDataTable Generate(string tableName, string columnName, AxDate fromValue, AxDate toValue, int step) - Creates an AxDataTable with one AxDate column. Creates rows with a sequence of dates from fromValue to toValue. Step is normally 1; if step is >1, steps that many days for each row.

SysAxisLink

A class mapping to the ^axislink record type, for storing linked pond definitions. See LinkedPondCollection.

string AxisID - the AxisID of the linked pond

int LinkType - 1=local path to axis file, 2=local/server path to txt file containing one line in the form "server:port", 3=network host

string PathOrHost - Either the full file path or the host name

string Port - the network port number

string User - the user name (if storing credentials) or "".

string Password - the password (if storing credentials) or "".

SysDisplayType

An object mapping to the ^displaytype record type, for storing instances of display types. Also see DisplayTypeCollection.

string Name - The display type name

string Comment - Optional comment

string ControlString - The control string, as defined by the ControlString class (see Axis1.Forms reference)

(c) 2014-2015 Divergent Labs, Inc.