1 Overview
1 Overview
1.1 Filename and Identifier Conventions
For readability, the coding standards used by Conroy & Conroy Company define
identifier naming conventions of mixed case (init-capped) identifiers with
underscores used to separate words within identifiers. All-uppercase
identifiers are used for acronyms (such as CPU). This convention allows one to
tell, at a glance, if the identifier is a Subroutine library identifier or one
from Windows or other third-party code.
For abstract class definitions (pure virtual classes, in C++ parlance), the filename begins with an underscore. Including a reference to one of these files does not link in any significant code, although other abstract definitions may be pulled into the compilation.
Hungarian notation is not used. However, all type definitions begin with "T" to distinguish them from other identifiers. "P" is used to denote a pointer to a type. "TCOM" is used for classes that are suitable for COM usage (CORBA-compliant) objects.
File names are limited to 8 characters for the sake of backwards compatibility with older compilers. However, the files in the GUI layer have no name length limit since the only compilers capable of using them support long file names. Like class names, files that consist solely of definitions (abstract classes, constants, etc) begin with underscores. Regression test files for the various units begin with "Test__". These files accompany the rest of the files, but are not technically part of the library. They are separated from the files that they test to keep the test code separate from the production code. This shortens compile time and reduces code bloat.
1.2 Layers
The Subroutine Library is organized into layers. Each layer represents a group
of related functionality. Dependancy rules require that routines only reference
routines that are in the same, or a lower, layer. The lowest layer is layer 0,
which has no dependencies (except upon inherent features of the language). Note that
for languages other than Pascal the subroutine library only includes some of the routines
and layers.
1.2.1 Layer 0 - Object model layer
This layer includes the base class definitions from which all classes of the Subroutine
Library derive. It also includes some basic type and constant definitions, localization
support, and collection classes, which are used by various units in this layer. The following
sections will detail some of the features of this layer.
_ASCII: ASCII definitions
_BIOS: Constants for BIOS
_Colors: Defines TRGB and TWide_RGB color values
_COMInter: Abstract base COM classes
_COMLists: Abstract COM list class
_Common: Abstract base class definitions
_DebugIn: Base debugging interface
_GenVal: Generic value (variant) class definition
_NameVal: Named values classes
_ObjectF: Subroutine object factory
_Octal: Constants for octal values
_Propert: Dynamic property support
_RGB: RGB definitions
_Streams: Abstract base stream interface class definitions
_TE_Interface: Abstract text editor class definition.
_TestInt: Abstract test interface
_TSRs: DOS internals structure definitions
Types: Simple type definitions
_UE: Unified exception
ASCIIDef: ASCII support functions
Basic_Files: Simple text file support functions and classes
Collect: Static collection classes
COMLists: Defines a COM list class
CommBase: Common non-COM base classes that all other subroutine classes derive from.
L10n: Text localization support
Streams: Base stream classes to assist in creating stream descendants.
TypeDefs: Basic type definitions
1.2.1.1 Emancipated Objects
Nearly all subroutine library classes are emancipated (reference-counted in modern
parlance). When you obtain an instance of a class that you want to keep around for
a while (whether you create it or it is returned by another class), you should call
it's Attach() method. When done with it, call the Detach() method. Objects will
destroy themselves when their reference count reaches 0. This is especially important
when dealing with objects passed across EXE/DLL boundaries as attempting to free an
instance created on the other side of the boundary will likely cause a program abend.
Note that platforms (such as C#, PHP, etc), which handle the reference counting themselves,
the Attach() and Detach() methods maintain the internal reference count, but do nothing
else - the objects do not self-destruct as a result.
1.2.1.2 Exceptions
The subroutine library doesn't use platform exceptions, instead opting for the TUnified_Exception
class. Outside of the library, this can be checked for and a platform-appropriate
exception can be generated in response, if desired. The subroutine library uses its
own exception class to support older platforms that either don't support exception
handling compatible with other platforms through which it interacts (including remote systems) or doesn't support
exceptions at all. It also supports modern platforms where normal exceptions aren't
supported (such as stand-alone programs that do not run in the context of an operating
system).
Many methods return an instance of this class if an error occurred (and nil otherwise).
These instances are emancipated and should be treated as such. Most classes support
obtaining the last exception object via the Last_Error() method.
1.2.1.3 Streams
Streams are classes that encapsulate serial I/O. They are abstracted away from files,
although files are often the underlying resource being encapsulated. However, the
code in this layer uses Basic_Files for file input, since streams are largely abstract
in layer 0. Higher layers provide full-featured stream classes, as well as the store
objects for advanced file use.
1.2.1.4 Internationalization
The L10n unit provides internationalization for the subroutine library, although most
of the text is used only in the UI layer. The subroutine library comes with English
text built in. However, the L10n unit allows alternative text to be used.
1.2.1.5 Dynamic Properties
Most Subroutine Library classes support dynamic properties. This is a means of adding
values to instances at run-time, which is helpful when using instances of these
classes (it is not recommended to modify the existing code so the changes are not
lost when a newer version is installed).
1.2.2 Layer 1 - Utility layer
This layer contains various utility classes and functions, such as logging mechanisms,
data cache support, stores, and data conversions.
_AEL: Application Event Logger class definition
_APM: Application Performance monitoring
_ArrayInt: Interfaces to arrays
_Cache: Cache handling class definitions
_CacheMa: Cache manager class definition
_Chars: Abstract character class definition
_Deferred: Deferred execution class definition
_DevMan: O/S Device Manager class definitions.
_Events: Event class definitions
_FacMan: Facility manager class definition
_Fonts: Abstract font characteristic class definition
_Languag: Language support
_Lib: Abstract librarian class definitions
_Loggers: Defines an abstract logging class
_ObjectM: Defines the object manager class
_Stores: Defines abstract store classes
_TPM: Text Presentation Manager class definitions
_Validate: Validator class definition
Behavior: Base Behavior class definitions
BehavMan: Behavior manager class
Cache: Cache control classes
CacheMan: Including this unit creates the cache manager on program startup
Compatib: Provides compatibility across platforms
Compress: Compression/decompression routines
DebugInt: Base classes from which to descend debug interfaces and support routines
Randoms: Random number generator
RGB: RGB to angstrom conversion
TSRs: MSDOS Terminate and Stay Resident function
CommonUt: Common utility routines
CVT: Numeric conversion routines
DebugMa: Standard Debug Manager instance
Disk: Absolute disk read/write routines (MSDOS)
EBCDICs: EBCDIC, BCDIC, and BCD support routines
English: English language support routines
Format: Various text formatting routines
Heaps: Memory heap class
Instrs: Instr and Rinstr functions
MStores: Managed store classes
NameVals: Standard named values implementation
Num1s: Number to string conversion routines
Operatio: Multi-part operation logger
_Buffers: Generic buffer class definition
Radix50s: Radix-50 conversion and support routines
RPG_Character: Abstract classes related to Role-Playing Games
Soundx: Provides the Soundex function
SpellChk: Spell checker
SStreams: String stream classes
Symbols: Symbol table classes
UE: Standard Unified Exception classes
_Applic: Application class definition
Decorations: Class for non-Windows-handle objects that can draw themselves on other controls
Deferred: Standard deferred manager
DPropert: Dynamic Properties class
ExtentSt: Extent store class
_Files: File class definitions.
_FiP: File system interface
FStreams: Stream class for PFiles.
_OS: Operating system interface
Devman: COM wrappers for static Device Manager instances
_FileSys: File system class definition
FSError: File system error codes
Language: Language-related numeric conversion routines
Maths: Arithmetic routines
Stores: Base classes from which to descend stores.
Weather: Wind-chill factor routine
XLate: Wildcard support functions
RAMDisk: An in-memory buffer accessed as a 64-bit store
VCL_Std: Various routines supporting VCL/LCL controls
1.2.3 Layer 2 - Application framework layer
This layer contains classes that support the Subroutine Library Application
Framework. This framework provides a consistent framework for all types
of applications. It includes such things as unit/application testing, debugging
support, and event logging.
_CompInt: Abstract compiler interface class definition
_DebugMa: Debug manager class definition
_TestMa: Test manager class definition
Test: Routines to aid in testing
AEL: Default Application Event Logger class
APM: Default Application Performance Monitor class
TestMan: Test manager implementation
_UOS_File_System: Abstract UOS file system class definition
1.2.4 Layer 3 - Platform abstraction layer
This layer contains classes that provide an abstraction to the underlying hardware/software platform,
including interfaces to the Operating System and File System.
OS_DOS: TOperating_System descendant for the MSDOS operating system. Accessed via O_S unit.
OS_Windows: TOperating_System descendant for the MS Windows operating system. Accessed via O_S unit.
OSWinDeb: Debugger for Windows operating system class
Allocatr: Allocation table classes
Allocatr64: 64-bit Allocation table classes
Allocation_Cluster_Manager: Allocation Cluster Manager
Applic: Standard Application Manager instance
Database: Database class definitions
Dates: Date and time functions
Filestd: File access functions and classes
FileSys: File System server class
FiP: File Processor class. Allows for abstraction of files and file systems.
FSFH: File System and File Heap classes
GetChars: Keyboard input classes
GIO: General I/O functions, such as Log_Error
Intlist64: 64-bit integer list
MSWin: Support for Microsoft Windows programming
O_S: Operating system class instance
Parse: Parsing functions
SMUBIOS: I/O drivers for SMU.
Standard: Misl. common-use functions and classes
UStrings: String utility routines
Wildcard: Filename wildcard routines
WinAPI: Wrapper for Windows
WinEvents: Windows event classes
1.2.5 Layer 4 - Application layer
This layer contains various classes and routines that are built upon the previous layers.
B_Dialog_Button_Nav: Button navigate behavior
B_Dialog_Default_Key: Button default behavior
B_Horizontal_Spacing: Horizontal spacing behavior
BigFH: 64-bit address file heap
Commands: Command object classes
CRCs: Checksum functions
Express: Expression analyzer.
ExtStore: Extendable Store class
GenVal: Simple Generic Value class
HTML: HTML and XML parsing classes
LoadArra: Loads arrays from tables in files
MemStore: In-memory contiguous store class
Menu_Popup_Form: Form for popup menus used in Menu_2D
Misc: Various routines, such as Sleep and Mid.
ObjectFa: Including this in uses constructs a default object factory object
Outlines: Outline class
Performa: Performance monitoring support
SMU: Screen Management Utility
StorHeap: Store heap class (a managed store on a store)
_StoreLis: List-in-a-store class definitions
StoreLis: 64-bit store list class
Structur: Various data structure classes
Tables: Random table class
TDialogs: Base dialog class
UEditor: Text editor class
VCLDebug: Debugger support for VCL/LCL controls
1.2.6 Layer 5 - GUI layer
This layer includes graphical UI components.
ArrayDis: Displays array contents on a Windows control
Array_Display_Main: And array display form with optionsc
Button_2D: 2D GUI speed button class
TPanels: Transparent panel control
Editor_Panel: Windows control for a text Editor.
EditPref: Preferences dialog for editor.
EditWin: Embeddeable Text editor
Linenumb: Line number dialog
Menu_2D: 2D menu class
Output_Panel: Scrolling text output panel
SaveEdit: Save changes dialog
ScrollPanel: Automatically scrolling panel
SMU_Pane: Window that wraps an SMU window.
SReplace: Save/replace dialog
SSearch: Search dialog
1.3 Class structure
The subroutine library class structure has four class lineages. For C++ and Pascal,
these lineages have distinct differences, as described in the table below. For all
other languages, there are four lineages as well, but there is no differences between
them. In fact, they all descend from the same TObject base class. Nevertheless,
for the sake of compatible code across all of the platforms, the lineages still
exist. Most classes in the subroutine library have versions of the class for each
of the first three lineages.
| Lineage base class | Descendent class name prefix | Description |
|---|---|---|
| TObject | TS | Turbo Pascal/Borland Pascal/Delphi static objects. No difference from TDelphi_Object in C++. Does not self-destruct by default, but can be set to self-destruct when no longer referenced. All descendent class names begin with the TS prefix. |
| TDelphi_Object | T | Dynamic objects. Uses String data type. All descendent names begin the the T prefix. |
| TBase_COM_Interface | TCOM_ | CORBA-compliant classes, with stdcall calling convention. Uses char* to pass string data (No shared-memory mechanism needed). These classes are suitable for use across DLL boundaries. They must never be directly destructed - only use Attach/Detach. Descendent names use the TCOM_ prefix. |
| TComponent | T | Delphi/Lazarus VCL/LCL/Firemonkey user-interface components.
1.4 Template files
The Subroutine library contains various support files, including the "x.app" files
which are templates for applications, where "x" is the programming language in question.
For instance, "Pascal.app" contains a template for pascal applications. It simply
makes for a more consistent starting point for code.
1.5 Conditional Compilation
For languages which support conditional compilation symbols, the subroutine library
reserves some symbols that begin with "CC_", as follows. Not all symbols apply to
all platforms.
| Symbol | Description |
|---|---|
| CC_Regression_Test | Surrounds regression test code. If defined, the application will run regression tests when it starts. |
| CC_Balance | Used to validate proper pairing of matched operations (such as allocations and deallocations). |
| CC_Debug | Surrounds debugging code. If defined, debugging code will be included in the compile. This can slow the application down due to the extra work involved with logging data, etc. It may also enable certain options, especially on UI elements. |
| CC_Auto_Free_Application_Manager | If defined, the application manager is automatically destroyed as the application exits. |
| CC_Auto_Free_Operating_System | If defined, the Operating System interface is automatically destroyed as the application exits. |
| CC_Track_Resources | If defined, resources are tracked. |
| CC_Validate | If defined, data is validated. For instance, calls to methods of nil objects is checked for. |
1.6 Units by category
This section lists units by general category of functionality. Some units are listed
in more than one category.