Class Documentation

Name:Inspector
Version:1.1
ID:ID_INSPECTOR
Status:Unspecified
Category:Tool
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2001. All rights reserved.
Short:  This class allows the user to inspect the system structure.



Description

Inspector is a tool-based class that can be used as a command or implemented as an application. It is designed for user interactivity and can execute a wide variety of commands that can be used to 'inspect' the underlying system structure. As well as providing facilities for system analysis, support for the manipulation of public objects is also provided.

To create a valid Inspector object, all you need to do is set the Output field, decide whether the object should be Static or not, and set the Command field as and when a new command needs to be executed. If you are creating an application based on the Inspector class, you should set-up an input box connected to the Command field so that the user can type in commands for the Inspector object to execute. An example of an existing Inspector application can be found in the scripts:development/monitors/ directory.

To find out what commands Inspector supports, open the existing Inspector application and type 'help' into the input box. This will provide you with a list of all supported commands and the arguments that can be passed to them.

Actions

The Inspector class supports the following actions:

Activate  Executes the instructions specified in the Command string.
ClosingTag  If the object is non-static, this action will execute the requested command and then the object will self-destruct.

Methods

The Inspector class implements the following methods:

About  Prints general information about the Inspector class and what it does.
Help  Prints instructions on how to use Inspector.
HexDump  Dumps public memory block information in hex format.
ListMemory  Lists all public memory blocks that exist in the system.
ListObjects  Lists all public objects that exist in the system.
ListResources  Can list the resources belonging to any specific public object.
MemoryInfo  Can print information on any specific public memory block.
TextDump  Dumps shared memory blocks in text format.
Tree  Prints a tree-like view of an object's contents.
ViewObject  Interrogates public objects for information and prints their details.

Structure

The Inspector object consists of the following public fields:

Command  Set this field prior to activation for a command to be executed.
Output  Set this field to the object that is to receive Inspector's output.
Quit  If Inspector is used as an application, point this field to the application's window.
Action:Activate
Short:Executes the instructions specified in the Command string.

Activating an Inspector object causes it to analyse the Command field and print the results to the object specified in the Output field.

 

Method:About()
Short:Prints general information about the Inspector class and what it does.

Executing the About method will print general information about the Inspector class, such as who wrote it and what it is designed for.

Result
ERR_Okay  The method executed successfully.
ERR_FieldNotSet  The Output field has not been set.

 

Method:Help()
Short:Prints instructions on how to use Inspector.

The Help method prints a list of commands that can be used to interact with Inspector, as well as details on their supported arguments and a short summary of what the commands do.

Result
ERR_Okay  The method executed successfully.
ERR_FieldNotSet  The Output field has not been set.

 

Method:HexDump()
Short:Dumps public memory block information in hex format.
Arguments:
MEMORYID MemoryID  The memory ID to be hex-dumped must be specified here.
LONG Length  The maximum number of bytes to be printed.

This method can be used to get a hex-based read-out of a public memory area. This is extremely useful for getting a closer peek at what a memory block actually contains. The printed information is laid out in the standard format for hex dumping, that is in lines of 16 numbers followed by the text-based equivalent of each number. The maximum number of bytes to be printed by the method must be specified in the Length argument, which prevents too much information from being printed in the case of large memory blocks.

Result
ERR_Okay  The method executed successfully.
ERR_Args  Invalid arguments were detected.
ERR_FieldNotSet  The Output field has not been set.
ERR_AllocMemory  An attempt to allocate sufficient buffer space failed.
ERR_AccessMemory  The given memory ID could not be accessed.

 

Method:ListMemory()
Short:Lists all public memory blocks that exist in the system.

The ListMemory method prints a list of all public memory blocks that have been allocated within the system. The information covers the memory ID, byte size, access-count and the ID of the owner for each memory block.

After obtaining a memory list, further analysis can be done by using commands such as HexDump, TextDump and MemoryInfo.

Result
ERR_Okay  The method executed successfully.
ERR_FieldNotSet  The Output field has not been set.
ERR_GVBaseDenied  An attempt to gain access to the GVBase failed.
ERR_AllocMemory  An attempt to allocate sufficient buffer space failed.

 

Method:ListObjects()
Short:Lists all public objects that exist in the system.

The ListObjects method prints a list of all public objects that exist within the system. Information is given for the class, object ID, and memory ID of the object structure.

After obtaining a list of objects, further information on individual objects can be gained by using the View command.

Result
ERR_Okay  The method executed successfully.
ERR_FieldNotSet  The Output field has not been set.
ERR_AccessMemory  The method could not gain access to the PublicObjects table.
ERR_GVBaseDenied  The method could not gain access to the GVBase.
ERR_AllocMemory  The system is low on memory.

 

Method:ListResources()
Short:Can list the resources belonging to any specific public object.
Arguments:
OBJECTID ObjectID  This parameter must refer to the object that is to be analysed.

The ListResources method can be used to list the memory and children that belong to a public object. All you need to supply is the public ID of the object you want to analyse.

Result
ERR_Okay  The method executed successfully.
ERR_Args  Invalid argument settings were detected.
ERR_ExclusiveDenied  Inspector could not gain access to the Output object.

 

Method:MemoryInfo()
Short:Can print information on any specific public memory block.
Arguments:
MEMORYID MemoryID  This argument must refer to the public memory block that you want to analyse.

If you require detailed information on a public memory block, this method can be used to obtain the byte size and owner of the block.

Result
ERR_Okay  The method executed successfully.
ERR_Args  Invalid arguments were detected.
ERR_Memory  Inspector failed to obtain memory information for the given ID.
ERR_AllocMemory  A call to AllocMemory() failed.

 

Method:TextDump()
Short:Dumps shared memory blocks in text format.
Arguments:
MEMORYID MemoryID  The memory ID to be text-dumped must be specified here.
LONG Length  The maximum number of characters to be printed.

This method can be used to get a text-based read-out of a public memory area. This is extremely useful for getting a closer peek at what a memory block actually contains. The printed information is laid out in a stream of 48 bytes per line. The maximum number of bytes to be printed by the method must be specified in the Length argument, which prevents too much information from being printed in the case of large memory blocks.

Result
ERR_Okay  The method executed successfully.
ERR_Args  Invalid arguments were detected.
ERR_FieldNotSet  The Object field has not been set.
ERR_AccessMemory  Inspector could not gain access to the given memory ID.

 

Method:Tree()
Short:Prints a tree-like view of an object's contents.
Arguments:
OBJECTID ObjectID  The ID of the object you wish to examine, or NULL if you are specifying a Name.
STRING Name  The name of the object you wish to examine, or NULL if you are specifying an ID.

This method can examine any public object and print a complete, hierarchical list of all other objects that belong to it. For instance, if you were to view a tree of a Window on the display, you would get a read-out of all objects within it - i.e. gadgets, graphical objects, interactive objects and so forth. With such an overview you can then examine certain objects in more detail by using the View command.

Result
ERR_Okay  The method executed successfully.
ERR_Args  Invalid arguments detected.
ERR_FieldNotSet  The Output field has not been set.

 

Method:ViewObject()
Short:Interrogates public objects for information and prints their details.
Arguments:
OBJECTID ObjectID  The object to be viewed must be referred to in this field.

The ViewObject method is a field analyser for public objects. Simply provide it with a valid object ID and the method will list all of the fields that belong to the object, as well as the values associated with each field. This functionality is especially useful for debugging purposes and manipulating the system when used in conjunction with the 'setfield' command.

You may notice that some field-types are not printed, e.g. pointer-based fields. This is because the memory addresses used by public objects are dynamic, which means that memory pointers can 'shift'. Other field types that have no read-access are also marked as being unreadable.

Result
ERR_Okay  The method executed successfully.
ERR_Args  Invalid arguments were detected.
ERR_FieldNotSet  The Output field has not been set.
ERR_ExclusiveDenied  Inspector could not gain exclusive access to the given object.

 

Field:Command
Short:Set this field prior to activation for a command to be executed.
Type:STRING
Status:Read/Write

Prior to activating an Inspector object, you must specify the command that you want to be executed. Valid commands and their arguments are:

  HexDump [MemoryID] [Length]
  ListObjects
  ListMemory
  ListResources [ObjectID]
  MemoryInfo [MemoryID]
  SetField [ObjectID] [Name] [Value]
  TextDump [MemoryID] [Length]
  View [ObjectID]
  Quit

More information on each command can be obtained by using 'help'. If an invalid command is used then an error will be printed when the Inspector object is activated.

 

Field:Output
Short:Set this field to the object that is to receive Inspector's output.
Type:OBJECTID
Status:Read/Write

The Output field must be set in order for an Inspector object to process the commands and output them to the user. If this field is not set then commands will not be executed when the Inspector object is Activated.

The Output object must accept text-based information via data channels in order for the data to be interpreted correctly. If the Output object does not support text based information, the Inspector object will still process the command but the user will not receive any text based output.

It is recommended that this field points to an object that is a member of the TextList class.

 

Field:Quit
Short:If Inspector is used as an application, point this field to the application's window.
Type:OBJECTID
Status:Read/Write

When the 'quit' command is used, the default action for an Inspector object is for it to self-destruct. This can be undesirable, and a more appropriate reaction may be to destroy the application window that contains the Inspector object.

By setting this field, you will force the Inspector object to free the external reference when the 'quit' command is used.