Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 10 - eMate Multi-User Mode / Reference

Functions and Methods /

GenSoupName

HomePage:GenSoupName(soupName, currentUser)

Returns a string that can be used as the soup name for a given user.

soupName

A string identifying a soup. This string must not contain more than 20 characters.

currentUser

A string identifying the current user. This string must not contain more than 19 characters.

return value

A string formed by concatenating soupName with currentUser, with a semicolon between them. If currentUser is nil (indicating that the unit is not in multi-user mode), soupName is returned without being modified.

DISCUSSION

The result of this method can be used as the soup name for a soup holding data for a particular user, when the unit is in multi-user mode.

If the soupName string contains a colon followed by a signature, *GenSoupName moves the colon and signature to the end of the string it returns, so it follows the currentUser portion of the returned string. Here is an example of this situation:

 soupName := "WidgetPlanner:mySig"; currentUser := "Anna";

GetRoot().HomePage:GenSoupName(soupName,currentUser);

// return value
 "WidgetPlanner;Anna:mySig"

If the soupName string does not contain a colon, then the two strings are simply concatenated, separated by a semicolon, as shown in this example:

 soupName := "WidgetPlanner"; currentUser := "Anna";

GetRoot().HomePage:GenSoupName(soupName,currentUser);

// return value
 "WidgetPlanner;Anna"

If the soupName string is more than 20 characters long (signature included) and the currentUser string is exactly 19 characters, then *GenSoupName returns a string longer than 39 characters. If you pass this string to a function that creates a soup, the system truncates the soup name to 39 characters, which truncates the developer signature. It is imperative that the soupName string be 20 characters or fewer. *GenSoupName does not check for length.

Note that the system automatically limits the length of user names to a maximum of 19 characters.