Maintenance
What to do when things go wrong
No matter how well software is designed and implemented, things can and do go wrong. The best approach, when things go wrong, is to capture essential error information and make it available to who might best be able to understand and fix the problem. Errors that might be caused and fixable by a human initiator of a failed action are reported back to an action originator. The infrastructure uses class gcErrorResult to convey captured error information back to an action originator. Some errors can only be fixed by someone with more knowledge or privilege than an action originator. The infrastructure, for such errors, places error information into a trace file and / or a console message file. An operator or administrator is alerted about an error and examines the error information from the system console file or a program trace file.
An operator or administrator learns about and can fix many typical errors. A more knowledgeable professional must be contacted for less typical errors. The best approach is for a locally accessible support person to be able to understand and fix many types of less typical errors. The objective of this paper is to help an individual with some software background to use the available infrastructure source to better understand and hopefully fix a less typical error. Of course, an error in the infrastructure software must ultimately be reported to and fixed by the infrastructure vendor.
Why place this paper about maintenance on a web site for all to see? This allows a potential user to judge for themselves how easy it might be to maintain this product.
Where to look for error information
The book, contained in the infrastructure introduction product, is a good place for a support person to find the information needed to understand, diagnose, and fix errors reported by the infrastructure. The book contains a chapter on configuring, executing, and analyzing the results of a software system based on the infrastructure. The chapter describes where to find console errors and program trace logs.
Important source locations
The infrastructure source is organized into a set of classes where a specific kind of function is contained in one class. This approach led to much less work to create the infrastructure and results in making it easier to fix an error. Most kinds of error can only happen at one place in the source. The infrastructure class gcErrorResult attribute definitionOwner contains a string that can be used to search the source and find the location where a particular kind of error is generated. The infrastructure consists of several hundred classes of which only about half have source available as part of the introduction product. The remaining classes are part of other available source products. The infrastructure organization means that only a handful of classes need to be understood by a local support professional.
Functions using OS features such as file access and TCP/IP socket layer are localized in the following source classes.
- The class localFileAccess within directory core is used for most file access.
- The class programBase within directory core is extended by a program using the infrastructure. It provides access to basic functions such as file access and generation of a message placed in a log file to trace program execution and report an error condition.
- The class netProgramBase within directory bus extends class programBase. It provides a set of methods used to access program context information needed to configure a program and uniquely identify the program instance within a software system.
- The class gcConvert within directory core is used for transforming data content between text, in memory, and serial format.
- The class netMain, netListen, and netConnect within directory net/io are used to interface with the TCP/IP socket layer.
- The class sfAdmin is used by an administrator as the console command to configure a software system. It contains the functions such as export, exportDefaults, generate, and import. These are described in a chapter on configuration within the book contained in the infrastructure introduction product.
- The class sfStartIntro is used as the console command to start or stop the programs that make up a one computer software system. Further information can be found within the book contained in the infrastructure introduction product.
These classes are the starting point for a console command that call other classes to perform functions such as localFileAccess reading or writing an OS file. An off the shelf debugger tool can be used to step through the execution of a console command and the class instances that are called. Care must be taken to minimize interference in the operation of a multiple computer software system when using a debugger tool.