What's New in Director 8.5 > Using the Shockwave Multiuser Server and Xtra > Using groups > Working with group attributes |  |

Working with group attributes

You may wish to keep track of the traits of a group or set of groups. For example, for groups of people working for two different companies that are collaborating, you might want to store the name of the leader of each group. If the groups are negotiating the price of a contract, you might store the current amount of each group's bid. In a gaming scenario, each team might choose a mascot, a theme song, or a starting location in a virtual world. Each of these can be stored as an attribute of a group as long as the group exists. Attributes can be set to any of the Lingo values that can be sent using `sendNetMessage`. Group attributes persist as long as the group exists on the server. To store information that must persist indefinitely on the server, use databases instead; see Using databases for more information.

You use `setAttribute` to add an attribute or update its value and `getAttribute` to determine the current value of the attribute. These commands are specified in the `#recipient` parameter of a `sendNetMessage()`, and the attributes you wish to access are specified in the `#content` parameter of the message.

The Lingo to define the current location and mascot of the group @RedTeam looks like this:

    errCode = gMultiuserInstance.sendNetMessage("system.group.setAttribute", "anySubject", [#group: "@RedTeam", #attribute: [#currentLocation: "New York City", #mascot: "dalmatian", #lastUpdateTime: "1999/07/27 15:52:11.123456"]])

When you use `setAttribute` the `#content` parameter of your message contains a `#group` property and an `#attribute` property. The `#group` property indicates which group you are setting attributes for. The `#attribute` property indicates which attributes you are setting. The names of the attributes you set should always be symbols beginning with the `#` character. In the example above, the `#group` is @RedTeam and the `#attribute` is a list of two attributes, `#currentLocation` and `#mascot`.

The `#lastUpdateTime` property is optional and lets you determine whether some other user has updated the attributes of the group since you last checked them with `getAttribute`. When you use `getAttribute` the server responds with the values of the attributes you requested plus a `#lastUpdateTime` property, which indicates the moment in time when the server read the values of those attributes for the group you requested. The `#lastUpdateTime` property is a string containing the year, month, day, hour, minutes, seconds, and microseconds on the server. By sending this same string with your `setAttribute` command, you allow the server to check whether the attributes for the group have been updated since you last checked them.

If the server determines that any attributes for the group have been updated by someone else since you checked them, it responds with an `#errorCode`, indicating a concurrency error. If no one else has updated the attributes since you checked them, the server responds with a new `#lastUpdateTime` for the group, indicating that you have just updated the attributes.

This statement gets the values of the attributes `#currentLocation` and `#mascot` for the group @RedTeam:

    errCode = gMultiuserInstance.sendNetMessage("system.group.getAttribute", "anySubject", [#group: "@RedTeam", #attribute: [#currentLocation, #mascot]])

The server's response looks like this:

    [#errorCode: 0, #recipients: ["Bob"], #senderID: "system.group.getAttribute", #subject: "anySubject", #content: ["@RedTeam": [#currentLocation: "New York City", #mascot: "dalmatian", #lastUpdateTime: "1999/07/27 15:53:32.123456"]]]

You can get attributes for more than one group at a time by including multiple group names in your request:

    errCode = gMultiuserInstance.sendNetMessage("system.group.getAttribute", "anySubject", [#group: ["@RedTeam", "@BlueTeam"], #attribute: [#currentLocation, #mascot]])

When you make a request for multiple groups, it is possible that part of the request will succeed while part of it produces errors. In the example above, attributes are requested for the group @BlueTeam. If this group has not yet been created, the server response will include errors in both the `#errorCode` property of the response and the attributes list for @BlueTeam. If a requested attribute has not been set, no error is generated and the attribute is simply omitted from the response.

The server's response looks something like this:

    [#errorCode: -2147216173, #recipients: ["Bob"], #senderID: "system.group.getAttribute", #subject: "anySubject", #content: ["@RedTeam": [#currentLocation: "New York City", #mascot: "dalmatian", #lastUpdateTime: "1999/07/27 15:53:32.123456"], "@BlueTeam": [#errorCode: [-2147216194]]]]

The first of these error codes indicates that the `#content` property of the message contains errors that you should check. The second error code indicates that the group @BlueTeam does not exist. (See getNetErrorString() for a list of error codes and their strings.)

If you want to determine exactly what attributes have been declared for a particular group, use `getAttributeNames`. It returns a list of the attribute names for the group:

    errCode = gMultiuserInstance.sendNetMessage ("system.group.getAttributeNames", "anySubject", [#group: "@RedTeam"])

To remove an attribute from the attribute list for a group, use `deleteAttribute`. The following example deletes the `#mascot` property from the group @RedTeam:

    errCode = gMultiuserInstance.sendNetMessage("system.group.deleteAttribute", "anySubject", [#group: "@RedTeam", #attribute: #mascot])

Keep in mind that the attributes you define for groups will persist only while the group exists. If you want this kind of information to be stored indefinitely so that it can be recalled from one multiuser session to the next, use database commands.