HyperDoc is primarily a database integrator tool. It provides drawing and document management capability, integrated redlining, Object Overlay, hyper navigation and hyper linking, right into any business database environment. That’s fine but, quite immediately, a lot of questions must be answered. What database, what are documents attributes, what business objects are supported. The only answer you need here is quite simple: whatever you may need, as HyperDoc is fully configurable and customizable.
The process of developing a new HyperDoc application typically consists of the following steps:
Designing a hierarchical representation of a business object database, including fields for each object
Defining document types and their specific attributes
Creating linking tables for all required types of HyperDoc links
Filling the necessary information into HyperDoc configuration tables
Developing connections with external databases, both in terms of data and functions
Developing HyperDoc AddIns to handle extensions and customized functions.
This chapter is intended for integrators, developers and advanced users who might want to explore HyperDoc closer, customize existing applications and develop new ones. This is a typical reference manual, so most of it you will never read, but I hope that it contains the information that you may need one day.
HyperDoc requires a database to run. It also requires its configuration tables to be filled properly. This chapter provides information how to do it. HyperDoc configuration is easiest to understand by using the demo database that is installed by the SETUP program as an example.
All table names below are defaults. The actual name of HDocConfiguration table can be stored in HDoc.ini file. The names of the other tables are stored in the HDocConfiguration table itself or in other configuration tables (hierarchy definition, document types).
HDocConfiguration | Main configuration table |
HDocUserConfig | Table with user-specific configuration data (optional) |
HDocHierarchyDefinition | Hierarchy definition |
HDocObjectFields | Form definition for objects |
HDocDocumentTypes | List of document types |
HDocDocumentTypeDefs | Document types definition |
HDocDocumentFields | Document fields definition |
HDocDocFieldWidths | Widths of document fields on grid |
HDocLinkTables | Linking tables definition |
The following tables are necessary for proper HyperDoc operation.
HDocAddIns | List of add-ins to be loaded when HyperDoc starts |
HDocParams | User-specific parameters |
HDocSecClassRights | Access rights to security classes |
HDocSecurityClasses | List of security classes |
HDocDocumentSets | List of document sets |
HDocDocSetObjects | List of documents in document sets |
HDocObjectSets | List of object sets |
HDocUserRights | Global access rights |
HDocSpots | Spots definitions |
The names of object tables, and the way they are linked to form a hierarchy, are stored in the HDocHierarchyDefinition table and in additional hierarchy tables (if any).
Information about base hierarchy is described in HDocHierarchyDefinition table.
If the table HDocUserConfig exists, it can contain information about additional hierarchies.
The HDocUserConfig table has the same set of fields as HDocParams table.
If a record from HDocUserConfig table has ParamID field beginning with ‘HierarchyTable’ text,
then tParam field contains a name of a table that defines additional hierarchy in similar way as HDocHierarchyDefinition table does.
HDocDocuments | Document table |
HDocVersionContents | Document versions contents information |
HDocVersions | Document versions |
HDocLogDevs | Logical devices definition |
HyperDoc presents one or more hierarchies of business objects. Such hierarchy represents data taken from HyperDoc database. Each level of the hierarchy consists of one or more database tables. Each of these tables must have a single field key. This key need not be a primary key, but to achieve decent performance, this field must be the first (most significant) segment of an index. Records are linked to the upper level of the hierarchy with a linking field. The linking field must have the same type and length as the key field in the upper level table. This field should also be indexed to achieve good performance. (The upper level table is in a 1-N relationship to the lower level table). One of the fields of each table is designated to be displayed in the hierarchy tree.
The hierarchy definition is stored in HDocHierarchyDefinition table or in a table, which name is specified in HDocUserConfig table.
HDocHierarchyDefinition table structure:
Field name | Description |
Sequence | Ordinal number |
ObjectClass | Table name |
ParentClass | Parent table name |
PrimaryKeyField | Key field in this table |
ForeignKeyField | Link field to parent table |
LabelField | Field to be displayed |
LabelText | Prefix for displayed field |
DisplayName | Name used for UI |
The fields contain the following information:
ObjectClass | The name of the table with actual data for this class of objects (also used to identify this class of objects in other contexts) |
ParentClass | Parent object class |
PrimaryKeyField | Name of the field in ObjectClass table containing the primary key of this table |
ForeignKeyField | Name of the field in ObjectClass table containing link to the parent table |
LabelField | Name of the field to be displayed in the hierarchy |
LabelText | The actual text used as a prefix to the displayed field data |
DisplayName | Name of the object class as shown to the user in various contexts |
Sequence | Sequence number used to determine the order in which classes on the same hierarchy level are displayed |
One record in HDocHierarchyDefinition table has a special meaning.
When the ObjectClass field equals a reserved value “Root”, this record defines the root of the hierarchy.
All the other fields should be empty except for the LabelText field which should contain the text to be displayed in the root node.
In case of additional hierarchies LabelField should contain the text to be displayed as a hierarchy tab caption.
The first level object classes should have “Root” as their parent class and an empty ForeignKeyField field.
HyperDoc always displays all records from the first level tables.
Example:
Sequence | ObjectClass | ParentClass | PrimaryKeyField | ForeignKeyField | LabelField | LabelText | DisplayName |
0 | Root | - | Root_ID | - | - | NetMan | Root |
1-1 | CommLinks | Root | CommLink_ID | - | CommLink_Name | CL: | Comm Link |
1-2 | Regions | Root | Region_ID | - | Region_Name | - | Region |
2-0 | Backbones | Regions | Backbone_ID | Region_ID | Backbone_Name | - | Backbone |
2-1 | Buildings | Regions | Building_ID | Region_ID | Building_Name | - | Building |
3-0 | RentalUnits | Buildings | RentalUnit_ID | Building_ID | RentalUnit_Name | RU: | Rental Unit |
3-1 | Floors | Buildings | Floor_ID | Building_ID | Floor_Name | - | Floor |
4-1 | Rooms | Floors | Room_ID | Floor_ID | Room_Name | - | Room |
4-2 | Xpanels | Floors | Xpanel_ID | Floor_ID | Xpanel_Name | - | Xpanel |
5-1 | Equipment | Rooms | Equipment_ID | Room_ID | Equipment_Name | - | Equipment |
5-2 | Cables | Rooms | Cable_ID | Room_ID | Cable_Name | - | Cable |
5-3 | Hubs | Xpanels | Hub_ID | Xpanel_ID | Hub_Name | - | Hub |
6-1 | Ports | Hubs | Port_ID | Hub_ID | Port_Name | - | Port |
HyperDoc allows the user to create new business objects and edit existing object's properties. The object property forms which are shown to the user are created on-the-fly according to information stored in HDocObjectFields configuration table.
HDocObjectFields table structure:
Field name | Description |
ObjectClass | Object class |
Sequence | Sequence number |
FieldName | Field name |
LabelText | Text of preceding label |
DictTable | Dictionary table |
DictDisplayField | Dictionary display field |
DictLinkField | Dictionary ID field |
The fields contain the following information:
ObjectClass - The name of the object class
FieldName - The name of the field to be displayed
LabelText - The text of the label preceding the field on a form
Sequence - Sequence number used to determine order of fields on a form
DictTable - Dictionary table name
DictDisplayField - Dictionary display field name
DictLinkField - Dictionary ID field name
When displaying form for a given object class HyperDoc reads all records from this table having the appropriate value in the ObjectClass field and sorts them according to the Sequence field.
Example:
ObjectClass | Sequence | FieldName | LabelText | DictTable | DictDisplayField | DictLinkField |
Backbones | 1 | Backbone_ID | ID: | - | - | - |
Backbones | 2 | Backbone_Name | Name: | - | - | - |
Backbones | 3 | Backbone_Description | Description: | - | - | - |
Buildings | 1 | Building_ID | ID: | - | - | - |
Buildings | 2 | Building_Name | Name: | - | - | - |
Buildings | 3 | Building_Address | Address: | - | - | - |
Cables | 1 | Cable_ID | ID: | - | - | - |
Cables | 2 | Cable_Name | Name: | - | - | - |
Cables | 3 | Date_Ordered | Ordered: | - | - | - |
Cables | 4 | Ordered_By | Who ordered: | - | - | - |
CommLinks | 1 | CommLink_ID | ID: | - | - | - |
CommLinks | 2 | CommLink_Name | Name: | - | - | - |
CommLinks | 3 | CommLink_Description | Description: | - | - | - |
Equipment | 1 | Equipment_ID | ID: | - | - | - |
Equipment | 2 | Equipment_Name | Name: | - | - | - |
Equipment | 3 | Date_Ordered | Ordered: | - | - | - |
Equipment | 4 | Delivered_By | Source: | - | - | - |
Floors | 1 | Floor_ID | ID: | - | - | - |
Floors | 2 | Floor_Name | Name: | - | - | - |
Floors | 3 | Floor_Description | Description: | - | - | - |
Hubs | 1 | Hub_ID | ID: | - | - | - |
Hubs | 2 | Hub_Name | Name: | - | - | - |
Hubs | 3 | Hub_Description | Description: | - | - | - |
Ports | 1 | Port_ID | ID: | - | - | - |
Ports | 2 | Port_Name | Name: | - | - | - |
Ports | 3 | Port_Description | Description: | - | - | - |
Regions | 1 | Region_ID | ID: | - | - | - |
Regions | 2 | Region_Name | Name: | - | - | - |
Regions | 3 | Region_Description | Description: | - | - | - |
RentalUnits | 1 | RentalUnit_ID | ID: | - | - | - |
RentalUnits | 2 | RentalUnit_Name | Name: | - | - | - |
RentalUnits | 3 | RentalUnit_Description | Description: | - | - | - |
Rooms | 1 | Room_ID | ID: | - | - | - |
Rooms | 2 | Room_Name | Name: | - | - | - |
Rooms | 3 | Room_Description | Description: | - | - | - |
Xpanels | 1 | Xpanel_ID | ID: | - | - | - |
Xpanels | 2 | Xpanel_Name | Name: | - | - | - |
Xpanels | 3 | Xpanel_Description | Description: | - | - | - |
With the above example data HyperDoc displays the following form to allow the user to create a new Building object:
HyperDoc manages documents. It stores document attributes in its database. Each document has associated exactly one row in the Main Document table. This table has at least two obligatory fields: Document_ID [for example typically varchar(50) in MS SQL Server] and Document_Type_ID (integer). It can also have more fields for document attributes. Depending on the type of particular document it must also have exactly one record associated in one of additional configurable tables called Document Type tables. These tables must have a single field key (we suggest it to be primary key) of the same type and length as the key in Document table.
Each document in HyperDoc belongs to one of document types. Document type determines the way document attributes are defined, stored and displayed. Configuration information concerning document types is stored in the following tables: HDocDocumentTypeDefs, HDocDocumentFields, HDocDocFieldWidths, and HDocDocumentTypes. From this set of tables only the HDocDocFieldWidths table is filled by HyperDoc itself and needs no manual data-entering. For HyperDoc to run, other mentioned tables must be filled according to rules described later.
Each document type must have a unique ID.
The document type ID (later in this paper referred to just as ‘type ID’) is used in the fields named Type_ID in the tables mentioned above.
The type ID is also used in the Document_Type_ID field of the Main Document table.
For each row in the Main Document table there must be corresponding row in HDocDocumentTypeDefs table with the same value of the type ID.
The ‘-1’ value of the type ID in HDocDocumentTypeDefs table is an exception, because it means documents of all types.
So the first step of the process of document type configuration is to fill HDocDocumentTypeDefs table with appropriate data. Each field of this table has type ‘varchar(50)’ except for Type_ID, which has an integer type.
HDocDocumentTypeDefs table structure:
Field name | Description |
Type_ID | Type ID |
DTName | Type name (UI) |
DTNameSingular | Type name singular (UI) |
DTDocIDField | ID field |
DTTypeField | Type field |
DTRawTable | Table name |
Sequence | Sequence number used to determine the order in which document type tabs are displayed |
Example:
Type_ID | DTName | DTNameSingular | DTDocIDField | DTTypeField | DTRawTable | Sequence |
-1 | All | - | Document_ID | Document_Type_ID | Document | 0 |
1 | Drawings | Drawing | Document_ID | - | Drawing | 1 |
2 | Contracts | Contract | Document_ID | - | Contract | 2 |
The primary key in the HDocDocumentTypeDefs table is the Type_ID field. It contains the type ID.
The -1 value in this field is reserved for the main document type.
The DTName field contains the name of document type as seen by HyperDoc users e.g. in the tab labels above of the document list.
The DTNameSingular field is the singular name of document belonging to given document type.
For example if the DTName field is Drawings then DTNameSingular field could be Drawing.
The DTDocIDField field is the name of primary key field in table indicated by the DTRawTable field.
The DTTypeField field is the name of the field in the document table that contains the type ID.
This field should be filled for main type only.
The DTRawTable field contains the name of database table that contains document attributes specific for the given type ID.
This table (one for each document type) can be created in the process of manual HyperDoc configuration or it can be a table existing in the HyperDoc database prior to installing HyperDoc, e.g. as a heritage from the former document management system.
The primary key in this table must be comprised of a single field of the same type as in the main document table.
The next step is to fill the HDocDocumentFields table.
This table determines what fields are shown on various tabs of the main HyperDoc document list and what fields are shown on the form used in New Document, Edit Document and View Document HyperDoc commands.
Each field of this table has type varchar 50 except for Type_ID and GridWidth fields,
which have an integer type and MainTable, which has a Boolean type.
HDocDocumentFields table structure:
Field name | Description |
Type_ID | Type ID |
DataField | Field name in Main Document table or Document Type table |
MainTable | Flag indicating DataField location: Yes - Main Document table No - Document Type table |
DictTable | Dictionary table |
DictDisplayField | Dictionary display field |
DictLinkField | Dictionary ID field |
FormLabel | Label of the field on the form |
FormSequence | Sequence number used to determine the order in which fields are displayed on the form |
GridLabel | Grid column heading in Document List Window |
GridWidth | Grid column width in Document List Window |
GridSequence | Sequence number used to determine the order in which fields are displayed in Document List Window |
Example:
Type ID | DataField | Main Table | DictTable | Dict DisplayField | DictLinkField | Form Label | Form Sequence | Grid Label | Grid Width | Grid Sequence |
-1 | Document_ID | Yes | - | - | - | ID: | 01 | ID | 1200 | 01 |
-1 | Document_ Type_ID | Yes | Document_Types | Type_Name | Type_ID | Category: | 02 | Type | 1200 | 02 |
1 | Document_ID | No | - | - | - | ID: | 11 | ID | 1200 | 11 |
1 | Drawing_Info | No | - | - | - | Info: | 12 | Info | 1200 | 12 |
1 | Drawing_Date | No | - | - | - | Date: | 13 | - | - | - |
The primary key in this table contains two fields: Type_ID and DataField.
The Type_ID field is document type ID.
The DataField field contains the name of the field that contains given document attribute.
The table this field comes from is determined by the MainTable field.
If the MainTable field is Yes, then the respective field comes from main document table.
If the MainTable field is No, then the respective field comes from the specific document table.
The next three fields: DictTable, DictDisplayField and DictLinkField determine the presentation of given document attribute. If the DictTable field is empty, then the contents of the field indicated in the DataField field is displayed on the form ‘as it is’. If the DictTable field is not empty, then it is assumed that there exists a table with a name as in the DictTable field, with unique index as in DictLinkField field and with a field as in DictDisplayField. In such a case the value of the DataField field is used to find a row in DictTable with the same value in the DictLinkField field and HyperDoc displays on the form the contents of the DictDisplayField field of the found row in the DictTable table. This method allows saving database space - longer texts do not need to be repeated in every document record - only short IDs of these texts are repeated. It also helps to maintain the consistency of attributes used to categorize the documents.
The FormLabel field contains the label, which precedes edit box for editing document attribute on the form. The FormSequence determines the sequence, in which document attributes are displayed on the document attributes form. If the FormSequence field is empty the field is not displayed on the editing form.
The GridLabel contains the label of the column in the grid where the content of the field is displayed. The GridWidth attribute is the default width of this column. Each user can enforce his own column width by resizing a column on the screen. Column widths are stored per user in the HDocDocFieldWidths table, which HyperDoc fills automatically. The GridSequence field determines the sequence, in which document attributes are displayed on the main document list. If the GridSequence field is empty the field is not displayed on the document grid.
The Main Document table is not a configuration table at all. It contains document data. It is shown here just for reference. The Document_Type_ID field of this table must contain values, which are also in the Type_ID field of one of rows in the HDocDocumentTypeDefs table. These values care inserted to the Document_Type_ID field of Document table automatically by HyperDoc during execution of New Document command.
Document table structure:
Field Name | Comment |
Document_ID | Unique document ID in document table |
Document_Type_ID | Document type ID |
The names of linking tables are stored in the HDocLinkTables table. The suggested names follow the convention: Object1_Object2_Link.
HyperDoc supports four types of links between various entities. Types of links and associated tables are defined in HDocLinkTables table. The types of links are:
DL - document link - links documents to business objects (many to many relationship), used for hierarchy (domain) navigation;
HN- hyper-navigation - links spots on documents to documents (many to many relationship), used for hyper-navigation;
IS- InfoScope - links spots to business objects (many to many relationship), used for InfoScope functions;
OS - object set link - links public object sets to business objects (one to many relationship), used for making access to object sets easier.
HDocLinkTables table structure:
Field Name | Description |
Link_Table | Name of table defining links between various objects |
Link_Type_ID | Link type |
A_Table_Name | Name of table A |
A_Primary_Key | Name of primary key for table A |
B_Table_Name | Name of table B |
B_Primary_Key | Name of primary key for table B |
Example:
Link_Table | Link_Type_ID | A_Table_Name | A_Primary_Key | B_Table_Name | B_Primary_Key |
CommLink_OSet_Link | OS | CommLinks | CommLink_ID | HDocObjectSets | SetID |
Document_Backbone_Link | DL | Backbones | Backbone_ID | Document | Document_ID |
Document_Building_Link | DL | Buildings | Building_ID | Document | Document_ID |
Document_Cable_Link | DL | Cables | Cable_ID | Document | Document_ID |
Document_CommLink_Link | DL | CommLinks | CommLink_ID | Document | Document_ID |
Document_Equipment_Link | DL | Equipment | Equipment_ID | Document | Document_ID |
Document_Floor_Link | DL | Floors | Floor_ID | Document | Document_ID |
Document_Hub_Link | DL | Hubs | Hub_ID | Document | Document_ID |
Document_Port_Link | DL | Ports | Port_ID | Document | Document_ID |
Document_Region_Link | DL | Regions | Region_ID | Document | Document_ID |
Document_RentalUnit_Link | DL | RentalUnits | RentalUnit_ID | Document | Document_ID |
Document_Room_Link | DL | Rooms | Room_ID | Document | Document_ID |
Document_Xpanel_Link | DL | Xpanels | Xpanel_ID | Document | Document_ID |
RentalUnit_OSet_Link | OS | RentalUnits | RentalUnit_ID | HDocObjectSets | SetID |
Root_Document_Link | DL | Root | Root_ID | Document | Document_ID |
Spot_Backbone_Link | IS | HDocSpots | Spot_ID | Backbones | Backbone_ID |
Spot_Building_Link | IS | HDocSpots | Spot_ID | Buildings | Building_ID |
Spot_Cable_Link | IS | HDocSpots | Spot_ID | Cables | Cable_ID |
Spot_CommLink_Link | IS | HDocSpots | Spot_ID | CommLinks | CommLink_ID |
Spot_Document_Link | HN | HDocSpots | Spot_ID | Document | Document_ID |
Spot_Equipment_Link | IS | HDocSpots | Spot_ID | Equipment | Equipment_ID |
Spot_Floor_Link | IS | HDocSpots | Spot_ID | Floors | Floor_ID |
Spot_Hub_Link | IS | HDocSpots | Spot_ID | Hubs | Hub_ID |
Spot_Port_Link | IS | HDocSpots | Spot_ID | Ports | Port_ID |
Spot_Region_Link | IS | HDocSpots | Spot_ID | Regions | Region_ID |
Spot_RentalUnit_Link | IS | HDocSpots | Spot_ID | RentalUnits | RentalUnit_ID |
Spot_Room_Link | IS | HDocSpots | Spot_ID | RentalUnits | RentalUnit_ID |
Spot_Xpanel_Link | IS | HDocSpots | Spot_ID | Xpanels | Xpanel_ID |
For each business object class there should be a corresponding link (DL) defined in HDocLinkTables table and the corresponding linking table (usually with XXX_Document_Link name).
Each link table for DL links should have the following structure:
Field name | Description |
XXX_ID | XXX object ID (same field name as key in business object table) |
Document_ID | Unique document ID in Document table |
Default | Flag indicating the default document |
Xmin | X coordinate of left lower corner of the default view |
Ymin | Y coordinate of left lower corner of the default view |
Xmax | X coordinate of right upper corner of the default view |
Ymax | Y coordinate of right upper corner of the default view |
For hyper-navigation a single record in HDocLinkTables table is necessary - exactly as the one shown in the example. It also implies that two additional tables are needed: Spot_Document_Link and HDocSpots.
Spot_Document_Link table structure:
Field name | Description |
Spot_ID | Unique Spot ID in HdocSpots table |
Document_ID | Unique Document ID in Document table |
Default | Flag indicating the default Document used when spot is activated |
HDocSpots table structure:
Field name | Description |
Spot_ID | Unique Spot ID |
Document_ID | Spot owner |
Entity_ID | Vector entity ID |
To allow InfoScope links for each business object class there should be a corresponding IS entry in HDocLinkTables table (see example above) and a separate table - Spot_XXX_Link of the following structure.
Spot_XXX_Link table structure:
Field name | Description |
Spot_ID | Unique Spot ID in HDocSpots table |
XXX_ID | Unique XXX object ID (the same field name as the key in business object table) |
Default | Tag indicating default XXX object used when spot is activated |
To allow linking object sets to business objects of a particular class, there should be appropriate record in the HDocLinkTables table with
OS text in Link_Type_ID field as shown above.
Each link table for OS link (suggested name: XXX_OSet_Link where XXX is object class name) should have the following structure:
XXX_OSet_Link table structure:
Field name | Description |
XXX_ID | Unique XXX object ID in appropriate object table (the same field name as the key in the business object table) |
SetID | Object set ID |
The following tables are optional. They can be created by a database administrator.
HDocObjectSets | List of object sets |
HDocObjectSetXXX | Tables with object sets contents (one per object class) |
HDocSCXXX | Tables with security class IDs for objects (one per object class) |
HDocDynamicTextMacros | List of dynamic text macros |
HDocPresentations | List of vector object presentations |
HDocPresentationFilters | List of filters for vector object presentations |
Object set data is stored on two levels.
First level is HDocObjectSets table, which contains one record for each object set.
Second level are HDocObjectSetXXX tables (where XXX is object class name), which store one record for each element of each object set.
Star near the field name means it is a part of the primary key.
HDocObjectSets table structure:
Field name | Data type | Description |
SetID * | int(4) | Unique object set ID |
UserID | varchar(50) | User ID for private OSes, empty for public OSes |
SetName | varchar(255) | Object set name |
HDocObjectSetXXX table structure:
Field name | Data type | Description |
SetID * | int(4) | Unique object set ID |
XXX_ID * | Same as key in XXX | Business object ID (field name is concatenation of business object class name and an ‘_ID’ suffix) |
HDocSCXXX table structure:
Field name | Data type | Description |
SetID * | int(4) | Unique object set ID |
XXX_ID * | Same as key in XXX | Business object ID (field name is concatenation of business object class name and an ‘_ID’ suffix) |
HDocSCXXX table structure:
Field name | Data type | Description |
SecurityClassID | int(4) | Unique security class ID |
XXX_ID * | The same as key in XXX | Business object ID (field name is the same as the key in XXX) |
Presentation data is stored on two levels. First level is HDocPresentations table which stores one record for each presentation.
Second level is HDocPresentationFilters table which contains one record for each filter of each presentation.
HDocPresentations table structure:
Field name | Data type | Description |
ID * | varchar(50) | Presentation ID |
Name | varchar(255) | Presentation name |
Descr | varchar(255) | Presentation description |
Automatic | Boolean | Is it an automatic presentation? |
HDocPresentationFilters table structure:
Field name | Data type | Description |
Presentation_ID * | varchar(50) | Presentation ID |
ObjectClass * | varchar(50) | Class of object connected to spot affected by presentation tool |
Sequence * | varchar(50) | Ordinal number text |
Tool_ID | varchar(50) | Presentation tool name |
FromSQL | varchar(255) | Additional tables used in the WhereSQL field |
WhereSQL | varchar(255) | Condition for applying presentation tool from Tool_ID field |
Label | varchar(50) | Legend label |
Layer | varchar(50) | Vector drawing layer name. If not empty, limits affected spots. |
GroupBy | varchar(255) | SQL expression used to generate filters from the filter template (for an automatic presentation only). |
HDocDynamicTextMacros table structure:
Field name | Data type |
ObjectClass | The name of the object class |
MacroName | The name of the macro |
MacroExpansion | SQL query text to be used when resolving the macro |
HyperDoc uses the following algorithm to resolve dynamic text macros:
For the given spot it determines the object to be used by examining a link between the spot and the object.
It uses the class of the found object and the macro name specified in the text definition to retrieve the SQL query text for macro expansion from
HDocDynamicTextMacrostable.Replaces all occurrences of the
%1in the query definition with the primary key value of the object found in the first stepExecutes the query and returns the first column of the first row of the returned data as the macro expansion
Example:
ObjectClass | MacroName | MacroExpansion |
Floors | Building name | SELECT Buildings.Building_Name FROM Buildings, Floors WHERE Buildings.Building_ID = Floors.Building_ID AND Floors.Floor_ID = '%1' |
Floors | Floor description | SELECT Floor_Description FROM Floors WHERE Floor_ID = '%1' |
Floors | Floor number | SELECT Floor_Name FROM Floors WHERE Floor_ID = '%1' |
Rooms | Room description | SELECT Room_Description FROM Rooms WHERE Room_ID = '%1' |
Rooms | Room name | SELECT '* ' + Room_Name + ' *' AS RName FROM Rooms WHERE Room_ID = '%1' |
During its operation HyperDoc uses temporary tables.
When HyperDoc works with Microsoft SQL Server database, these tables are created with the standard mechanism and are automatically removed by the SQL server at the end of the session (even when HyperDoc session terminates abnormally).
When HyperDoc works with Access database, it creates ordinary tables which are deleted at the end of the HyperDoc session. These tables have names beginning with “T_”. When HyperDoc session does not terminate in a regular way, these tables are left in the database. The administrator can open the database in exclusive mode and safely remove all the “semi-temporary” tables.
Some parts of HyperDoc depend on referential integrity for proper operation.
All Spot_XXX_Link must have many-to-one relations to the Spot table on Spot_ID field
(i.e. the record from Spot table must not be removable when there are records referencing this spot in one of Spot_XXX_Link tables).
HyperDoc is an open system. It can be easily programmed via OLE Automation (later named ActiveX) interface. You can start and control HyperDoc from an external application. You can extend HyperDoc functionality adding custom developed modules called Add-Ins. The Add-In can add his own menu items to HyperDoc menu, which implement new functions specific to user requirements. The external application and Add-Ins modules can respond to HyperDoc events. The picture below presents general structure of HyperDoc programmability model.
HyperDoc can be started for example with following VB code:
Set HDoc = CreateObject(“HyperDoc.Application”)
HDoc.Init sFileName, sUserName, sPasswordThe Init method MUST be called after creating HyperDoc.Application object. The sFileName parameter contains the name of the INI file with HyperDoc startup parameters (database name, etc.). sUserName and sPassword are login parameters.
When HyperDoc is started directly from the shell, it uses the INI file specified as a command line parameter.
When INI file is not specified as argument, then HyperDoc tries to find INI file in an application directory (the one with HDoc32.exe file).
If HDoc.INI is not found there, then INI from Windows directory is used.
During its start-up HyperDoc reads OLE object class identifiers from HDocAddIns table. For each class HyperDoc performs the following VB code sequence:
Set AddIns(i) = CreateObject (ClassIdentifier)
AddIns(i).Init (i, Me) ‘ Me means the running
instance of the
‘ HyperDoc.Application object
‘ i is an index in the AddIns collectionThe ClassIdentifier argument uses the syntax "appname.objectname" and has these parts:
appname - The name of the application providing the object.
objectname - The type or class of object to create.
Before closing HyperDoc informs all Add-Ins and external applications using the following function:
AddIns(i).FinalExit
The Add-In module receives reference to HyperDoc.Application object and has access to HyperDoc properties and methods.
The Add-In can define appropriate methods for handling HyperDoc events.
Field name | Field type | Description |
ProgID | String | Class ID used to create add-in object |
DisplayName | String | User-visible name of the add-in; optional |
Users | String | Semicolon separated list of allowed users; optional |
FileName | String | Used to register ProgID for object creation; optional |
Sequence | String | Allows to control add-in loading sequence; optional |
You can start HyperDoc from an external application as described above.
The external application has full access to HyperDoc properties and methods using reference to HyperDoc.Application object.
In order to handle HyperDoc events the external application has to register a Notification Object using RegisterNotificationObject.
The Notification Object should expose methods that HyperDoc will call to signal events (see description of HyperDoc events).
The sample program HDocTest demonstrates HyperDoc starting and initialization, usage of documents and objects related methods and handling HyperDoc events via a notification object.
The full listing of a sample program main form (HDocTest.Frm) is the following:
Option Explicit
Public HDoc As Object
Dim NotifObj As Notif
Public RegNObj As Boolean
Public HDStart As Object
Private Sub AddObj_Click()
Dim ObjectC As String
Dim KeyV As Variant
HDoc.GetCurrentObject ObjectC, KeyV
ObjList.AddItem ObjectC & ";" & KeyV
End Sub
Private Sub Form_Load()
Me.Move 0, 0
Set NotifObj = New Notif
RegNObj = False
End Sub
Private Sub Form_Unload(Cancel As Integer)
If RegNObj Then
HDoc.UnRegisterNotificationObject "HDocTest"
End If
Set HDStart = Nothing
End Sub
Private Sub ShowObj_Click()
Dim ObjectC As String
Dim KeyV As Variant
Dim i As Integer
ObjectC = ObjList.Text
i = InStr(1, ObjectC, ";")
KeyV = Mid(ObjectC, i + 1)
ObjectC = Left(ObjectC, i - 1)
HDoc.SetCurrentObject ObjectC, KeyV
HDoc.ResetMarked
HDoc.MarkObject ObjectC, KeyV, False
HDoc.DocMode = 0
HDoc.RefreshView
End Sub
Private Sub ShowUnit_Click()
Dim lSetID As Long
Dim ObjID As Object
Dim ObjSet As Object
Dim sName As String
Dim InfoS As Object
Dim fTmp As Boolean
Dim FirstObj As Object
HDoc.SetCurrentObject "Unit", UnitID
Set ObjID = HDoc.CreateObjectID
ObjID.m_ObjectClass = "Unit"
ObjID.m_KeyValue = UnitID
lSetID = HDoc.GetLinkedObjectSetID(ObjID)
If lSetID <> 0 Then
Set ObjSet = HDoc.DBOSS
sName = HDoc.ObjectSet_GetSetName(lSetID)
ObjSet.RemoveAll
If ObjSet.Load(sName, "") = 0 Then
HDoc.ShowObjectInfoscope
Set InfoS = HDoc.InfoScope
ObjSet.MoveFirst
Set FirstObj = ObjSet.GetCurrent
Set FirstObj = FirstObj.m_ObjID
fTmp = HDoc.ObjectInfoScope_AutoShow
HDoc.ObjectInfoScope_AutoShow = True
If InfoS.SetCurrentObject(FirstObj) Then
End If
HDoc.ObjectInfoScope_AutoShow = fTmp
End If
End If
End Sub
Private Sub StartHDoc_Click()
Dim UserName As String
Dim Password As String
UserName = LoginName.Text
Password = LoginPassword.Text
If HDoc Is Nothing Then
'If no connection to HyperDoc, connect to running instance
'or start HyperDoc if necessary
Set HDStart = GetObject("", "HDStart.App")
If HDStart Is Nothing Then
MsgBox "Cannot start HDStart"
Exit Sub
End If
Set HDoc = HDStart.GetHDoc()
End If
If Not HDoc.Initialized Then
' This HyperDoc instance has not been initialized
HDoc.Init "", UserName, Password
Else
'This HyperDoc instance is initialized --> check
'if proper user
If UCase(HDoc.CurrentUser) <> UCase(UserName) Then
' Wrong user --> re-initialize
HDoc.Init "", UserName, Password
End If
End If
HDStart.Register
' Force certain screen location
If HDoc.MainForm.WindowState <> 0 Then
HDoc.MainForm.WindowState = 0
End If
HDoc.MainForm.Move Me.Width, 0, Screen.Width - Me.Width, _
Screen.Height * 4 / 5
If HDoc.RegisterNotificationObject(NotifObj, "HDocTest") Then
RegNObj = True
End If
End Sub
Private Sub GetCurrent_Click()
DocList.AddItem HDoc.GetCurrentDocument()
End Sub
Private Sub SetCurrent_Click()
HDoc.SetCurrentDocument DocList.Text, True
End Sub
The full listing of a sample program notification class is the following:
Option Explicit
Public Sub CurrentObjectChanged(ObjClass As String, _
KeyVal As Variant)
HDocTest.CurrObj = ObjClass & ";" & KeyVal
End Sub
Public Sub EndOfHDoc()
HDocTest.HDoc.UnRegisterNotificationObject "HDocTest"
HDocTest.RegNObj = False
Set HDocTest.HDoc = Nothing
If Not HDocTest.HDStart Is Nothing Then
Set HDocTest.HDStart = Nothing
End If
End Sub
Public Sub VectorEntityChanged(VectorDrw As Object, _
VectorEntityId As Long)
' find modified element DISPATCH interface
Dim vdbent As Object
Dim vdbiter As Object
Dim Id As Long
HDocTest.VectorEntity = ""
Set vdbiter = VectorDrw.GetElemIter(0)
If Not vdbiter Is Nothing Then
Set vdbent = vdbiter.GetNext
Do While Not (vdbent Is Nothing)
Id = vdbent.GetLongID
If Id = VectorEntityId Then Exit Do
Set vdbent = vdbiter.GetNext
Loop
If Not vdbent Is Nothing Then
HDocTest.VectorEntity = vdbent.GetArea
End If
End If
End SubYou can use Visual Basic to create Add-In modules. Use the following procedure to create your own HyperDoc Add-In:
Open new project in VB
Insert new class module and set its properties
Add obligatory methods:
Public Function Init(Index As Integer, HDOc As Object) As Boolean Init = True End Function Public Sub FinalExit() End Sub
Add methods for handling HyperDoc events
Public Sub PreInitPaperSpace(DocID As Variant) End Sub
Set the following project attributes using command Options from Tools menu
Insert new module with Main subroutine
Public Sub Main() End Sub
Make OLE DLL file
Add new record to HdocAddIns table in HyperDoc database:
SampleAddIn.AddInTest
Sample Add-In
Start HyperDoc and test your code
The full listing of a sample Add-In is presented below.
This Add-In modifies print template contents.
It replaces text $User with text RYR.
It adds menu command Handle print events to enable/disable print events handling.
Option Explicit
Dim HDocRef As Object
Dim MyIndex As Integer
Dim EventsEnabled As Boolean
Public Sub PreInitPaperSpace(DocID As Variant)
If EventsEnabled Then
' HDocRef.PrintTemplate = "your own print template file"
End If
End Sub
Public Sub PostInitPaperSpace(ByVal VectorDrw As Object)
Dim vdbobj As Object
Dim vdbiter As Object
Dim cont As String
Dim typ As Integer
If EventsEnabled Then
' resolve macro $User
Set vdbiter = VectorDrw.GetElemIter(0)
Set vdbobj = vdbiter.GetNext
While Not (vdbobj Is Nothing)
typ = vdbobj.GetType
If typ = 6 Then
' Text
cont = vdbobj.Contents
If cont = "$User" Then
vdbobj.Contents = "RYR"
End If
End If
Set vdbobj = vdbiter.GetNext
Wend
End If
End Sub
Public Function Init(Index As Integer, HDoc As Object) As Boolean
HDoc.AddCustomMenuItem Index, "AddInMenuItem", _
"Handle print events"
MyIndex = Index
Set HDocRef = HDoc
Init = True
End Function
Public Sub FinalExit()
End Sub
Public Sub CustomMenuItemExpand()
Dim MenuItem As Object
Set MenuItem = HDocRef.CustomMenuItem(MyIndex, "AddInMenuItem")
MenuItem.Checked = EventsEnabled
End Sub
Sub CustomMenuClick(MenuItem As String)
If MenuItem = "AddInMenuItem" Then
EventsEnabled = Not EventsEnabled
End If
End Sub
Private Sub Class_Initialize()
EventsEnabled = False
End Sub