prototype
Sets and gets prototype properties
Format:
TV::prototype action [ object-id ] [ other-args ]
Arguments:
action
The action to perform, as follows:
commands
Lists the subcommands that you can use. The CLI responds by displaying the five subcommands shown here. Do not use other arguments with this subcommand.
create
Creates a new prototype object. The object-id argument is not used; other-args is either Array or Struct, indicating the kind of prototype being created. You can change a prototype's properties up to the time you add it to an image. After being added, you can no longer change them.
get
Gets the values of one or more prototype properties. The other-args argument can include one or more property names. The CLI returns these property values in a list whose order is the same as the property names you entered.
If you use the -all option as an object-id, the CLI returns a list containing one (sublist) element for each object.
properties
Lists the properties that the CLI can access. Do not use other arguments with this subcommand.
set
Sets the values of one or more properties. The other-args argument consists of pairs of property names and values. The argument pairs that you can set are listed later in the section and are described in "Type Transformations".
object-id
The prototype ID. This value is returned when you create a new prototype. For example, 1 represents process 1. If you use the -all option, the subcommand is carried out on all objects of this class in the current focus.
other-args
Arguments required by the get and set subcommands.
Description:
The TV::prototype command lets you examine and set prototype properties and states. See for more information. These states and properties are:
address_callback
Generates the address of the object's elements at run time. It returns either an absolute address, or an addressing expression that is appended to the address of the object to give the address of the field. (Returning an expression is the preferred method.)
For example, you might use a callback if the original data structure contains information on where the next data instance resides.
If you are creating a type for a distributed array, this procedure returns a two-element list. For more information, see Distributed Arrays.
The call structure for an address callback is:
address_callback type_id object_addr index [replication]
where:
type_id: is the type identifier for the type being prototyped.
object_addr: is the address of the object.
index: is the index string for the array element or the index of the field in the structure.
replication: is only used for distributed array objects. It indicates that the result is an address and an index into the distribution to determine the process within which this element resides, since this is a distributed array.
bounds_callback
This is either a string that specifies the bounds statically in the format of the prototype's language, or a callback that TotalView calls when the object's address is known. If you are naming a callback, its call structure is:
bounds_callback type_id object_addr
This function returns a string in the format of the prototype's language that describes the current bounds; for example:
C: [2][40]
Fortran: (-2:10,-5:5)
If the bounds start with a bracket "[" or a parenthesis "(", TotalView assumes they are static; otherwise, TotalView assumes that the returned value is the name of a callback function.
As the bracket characters ([ ]) are special characters in Tcl, you must escape them even in strings; for example \[20\] rather than [20].
distribution_callback
Returns a list of process or thread identifiers that represent (in order) the processes/threads in which elements of this array exist. Only use this callback when your array is distributed over multiple processes. Its call structure is as follows:
distribution_callback type_id object_addr
TotalView calls this callback with a replication index. The returned value must have an index into the distribution as well as an address.
id
The prototype ID.
language
The language for this prototype. It indicates how TotalView parses and generates bounds and indices.
name
The regular expression that TotalView uses to match types. It must be anchored; that is, it must start with a "^" character.
rank_callback
Returns the rank of the array. TotalView calls this function when the prototype is modifying a type. Its call structure is as follows:
rank_callback type_id
type
The type of the prototype. This can be either array or struct.
Lists all possible values for type.
type_callback
(required) TotalView invokes this callback when the prototype is modifying a type. Its format is:
type_callback type_id
The value returned depends on whether this is an array prototype or struct prototype.
Array prototypes: Returns a value that is the type identifier for a single element of the array.
Struct prototypes: Returns a list in the format of the struct_fields property of a type that describes the struct type's fields. If a field in the type requires a callback, the addressing section of its field description should be the string callback rather than an addressing expression. In this case, TotalView uses address_callback to generate the address of this field.
typedef_callback
Defines an new_type_id in terms of the old_type_id. You would use this callback when old_type_id is modified by this prototype. The format is:
typedef_callback new_type_id old_type_id
TotalView ignores any returned value.
validate_callback
(required) TotalView invokes this callback whenever a type that matches the prototype's name is defined. It returns a Boolean value indicating if it should be applied. This callback lets you have more than one prototype match a type name, and then investigate the type to determine if TotalView should apply the prototype.
The call structure for a validation callback is:
validate_callback type_id
where type_id is the type identifier for the type being prototyped.
Description:
You will find an extensive discussion and examples in "Type Transformations".
