gmSCAttributeClass

Owned by Mark Juras
Last updated: Jul 25, 2018Version comment

The Attribute Service Class

The service class Attribute contains those methods used by both the Xml Script Language processor and the runtime engine to process the values of the entries in attribute classes. The information associated with an attribute class is stored in a linear information vector. There are two types of vectors: word aligned and byte aligned. Each attribute has a binary type, a starting offset, and various processing control flags associated with it.

The method Attribute_Define

Prototype


int Attribute_Define(char* command,int stateRoot,int* info);
The Attribute_Define method processes the Attribute statement which defines an information vector. This statement specifies the information needed to store and retrieve attribute values from Xml-attribute value strings, binary information vectors, and the runtime data queue. Semantically they are distinguished from Properties in that an attribute can be stored and accessed directly based on its location in a binary information vector, its type and its support info. Its initial input conversion does not require any individual runtime support. A property on the other hand is simply a shorthand notation for possibly two different methods -- get and set.

The attributes of the Attribute command are as follows:

Attribute Description
id The identifier of the attribute. This identifier must match the attribute identifier used to specify the value for the attribute in the XML statement or to reference that attribute in an expression via the notation classid.id.
type This attribute specifies the type of the attribute value. It may be void, integer,string, boolean, or the identifier of an enumeration. If omitted, then the type is assumed to be void. If the type is string or boolean, following the type identifier there may be a value enclosed in square-brackets. For strings this value is the maximum length of the string in bytes, and for booleans it is the bit-position of the value within its location.
location Associated with each attribute is the word or byte starting offset in the information structure of the start of its value. This location is normally computed by this method. There are times when a given location in the structure is accessed via two different attributes, either for historical reasons or because there may be different ways in which the same attribute can be specified. When this happens the first attribute using the location should be defined in the normal way and then any following attributes should reference that attribute via a location attribute as in the following for the Select statement 


               <Attribute id="Name" type="string[64]" EditString="on" />
               <Attribute id="ToolName" type="string[64]" location="Name" />
In this case the ToolName identifier is an alternate way of referring to the Select.Name property.
editstring If this attribute is specified as on then upon input it is edited for global variables.
stringoff If this attribute is specified as on then the keyword off can be used during input to indicate that the attribute value is the empty-string.
stringon If this attribute is specified as on then the keyword on can be used to indicate that though the actual attribute value is the empty-string the attribute should nonetheless be considered to have a value.
projectfile If this attribute is specified as on then the value is assumed to identify a project or library file in the primary root of the symbol table. If it is a VBNAME then it becomes the component that is being named.
Opcode If this attribute is specified as on, then the value is assumed to identify one of the primary operation codes in the intermediate language.
Operation If this attribute is specified as on, then the value is assumed to identify an operation code (opcode.subcode) in the intermediate language.
Additive If this attribute is specified as on, then the value is masked into the location rather than being simply stored.
Packed If this attribute is specified as on, then the location of the attribute is assumed to be byte-oriented as opposed to word-oriented.
migName The name of the attribute when it is being referenced in target code.

The members of the tLibComp structure are used as follows by the statement:

Member Description of use
context The various entry attribute flags used to further specify the syntax/semantics of the attribute value.
type Type code or offset in language storage of the enumeration
nReq Size or bit number as specified
refType Constant LIBOBJ_Attribute
subcode Location in structure

Its parameters are as follows:

Parameter Description
command Contains the actual Attribute command as entered in the script.
stateRoot Contains the root of the statement or class containing the attribute.
info Contains an integer vector that contains the control information needed by this method to compute the locations of the attributes in their information vector. The calling method should simply zero this vector. Its words are used as follows:

Word Description of use
ATT_LOCATION The current location in the information vector for the current attribute value. This is computed by the method but may be overridden by the Location attribute of this command
ATT_SIZEBIT The last boolean size value. For booleans this is actually a bit location. The tool needs to track this value to determine when a following boolean value is in the same location as the preceding one.


A zero value is returned by this method if all went well; else a non-zero error code is returned. The errors detected directly by this method are:

Code Description
1232 Attribute command missing required id attribute.
1233 Unable to store attribute vector: id
1234 Attribute command missing required type attribute.
1235 Location attribute not defined.

There may be additional lower level errors detected by the XML processing methods used.

The method Attribute_LoadVector

Prototype


int Attribute_LoadVector(CONST char* statement,char* command,void* vector);
The Attribute_LoadVector method processes script statements that first load an information vector and then use that information to perform some action. Using information about the statement as described in the metalanguage, this method calls the appropriate parsing method to isolate the attribute information and then to load the values. Its parameters are as follows:

Parameter Description
statement Contains the identifier of the statement whose attributes are being processed. Its description is assumed to be stored either under the ToolLang component in the language file or in the gmSLang component.
command Contains that actual statement to be parsed. Note that as information is isolated in this buffer it is null-terminated within the buffer itself therefore, constant strings must not be passed.
vector Receives the information obtained from the command as described by the statement attribute descriptions. Note that this vector is not initialized here since script statements are often used to simply modify already existing information.

If all goes well, this method returns a zero else a one is returned with the error code set.

The method Attribute_PopValue

Prototype


void Attribute_PopValue(int attrRoot,int* vector);
The Attribute_PopValue method pops an information vector value from the runtime data queue and stores it in an information vector. This method is used by the engine when it encounters a set operation on an attribute. Its parameters are as follows:

Parameter Description
attrRoot Specifies the root offset in the language storage area of the information vector describing the attribute.
vector Receives the actual value that was popped.

This method itself returns no value.

The method Attribute_PushValue

Prototype


void Attribute_PushValue(int attrRoot,int* vector);
The Attribute_PushValue method pushes an information vector value into the runtime data queue. This method is used by the engine when it encounters a get operation on an attribute. Its parameters are as follows:

Parameter Description
attrRoot Specifies the root offset in the language storage area of the information vector describing the attribute.
vector Contains the actual value to be pushed.

This method has no return value.

The method Attribute_Select

Prototype


void Attribute_Select(char* command);
The Attribute_Select method executes the Select script command which specifies Select attribute values. It simply uses the Attribute_LoadVector method and then checks for a change to the codeSize attribute, which requires that the code storage area be reallocated. Its parameter is:

Parameter Description
command Contains the source command as entered.

This method has no return value.

The method Attribute_XeqStatements

Prototype


int Attribute_XeqStatements(char* command,int nCommand,int langRoot);
The Attribute_XeqStatements method executes the gmPL Statements statement, which initiates the definition of the statements within an Xml-style language to be processed. Its parameters are:

Parameter Description
command Contains the actual Statements command as entered in a Language definition script. As this method processes the statement and attribute subcommands introduced by this command, it uses this buffer to contain them.
nCommand Specifies the size of the command buffer. It is needed since that buffer is used within in this method to contain its subcommands.
langRoot Specifies the root offset of the METALANGUAGE storage vector for the language being defined.

This method returns a zero value if all went well; else it returns one with the global error code set to a nonzero value.
Table of Contents