SOM manipulations using somId's

A somId is similar to a number that represents a zero-terminated string. A somId is used in SOM to identify method names, class names, and so forth. For example, many of the SOM methods that take a method or class name as a parameter require a value of type somId rather than string. All SOM manipulations using somIds are case insensitive, although the original case of the string is preserved.

During its first use with any of the following functions, a somId is automatically converted to an internal representation (registered). Because the representation of a somId changes, a special SOM type (somId) is provided for this purpose. Names and the corresponding somId can be declared at compile time, as follows:

   string example = "exampleMethodName";
   somId exampleId = &example;

or a somId can be generated at run time, as follows:

   somId myMethodId;
   myMethodId = somIdFromString("exampleMethodName");

SOM provides the following functions that generate or use a somId:

somIdFromString

Finds the somId that corresponds to a string. The method takes a string as its argument, and returns a value of type somId that represents the string. The returned somId must later be freed using SOMFree.
somStringFromId
Obtains the string that corresponds to a somId. The function takes a somId as its argument and returns the string that the somId represents.
somCompareIds
Determines whether two somId values are the same (that is, represent the same string). This function takes two somId values as arguments. It returns TRUE (1) if the somIds represent the same string, or FALSE (0) otherwise.
somCheckId
Determines whether SOM already knows a somId. The function takes a somId as its argument. It verifies whether the somId is registered and in normal form, registers it if necessary, and returns the input somId.
somRegisterId
The same as somCheckId, except it returns TRUE (1) if this is the first time the somId has been registered, or FALSE (0) otherwise.
somUniqueKey
Finds the unique key for a somId. The function takes a somId identifier as its argument, and returns the unique key for the somId-a number that uniquely represents the string that the somId represents. This key is the same as the key for another somId if and only if the other somId refers to the same string as the input somId.
somTotalRegIds
Finds the total number of somIds that have been registered, as an unsigned long. This function is used to determine an appropriate argument to somSetExpectedIds, below, in later executions of the program. The function takes no input arguments.
somSetExpectedIds
Indicates how many unique somIds SOM can expect to use during program execution, which, if accurate, can improve the space and time utilization of the program slightly. This routine must be called before the SOM run-time environment is initialized (that is, before the function somEnvironmentNew is invoked and before any objects are created). This is the only SOM function that can be invoked before the SOM run-time environment is initialized. The input argument is an unsigned long. The function has no return value.
somBeginPersistentIds and somEndPersistentIds
Delimit a time interval for the current thread during which it is guaranteed that (a) any new somIds that are created will refer only to static strings and (b) these strings will not be subsequently modified or freed. These functions are useful because somIds that are registered within a "persistent ID interval" can be handled more efficiently.

See the System Object Model Programming Reference for more information on a specific function.

---

[Back: Memory management]
[Next: SOM IDL and the SOM Compiler]