Inside Macintosh: Networking /

Chapter 4 - Zone Information Protocol (ZIP)

Using ZIP

The Zone Information Protocol provides three functions that you can use to obtain the names of registered zones. You can use these functions to obtain

• the name of the zone to which your application and its node belong
• the names of the zones in your local network or the names of all the zones that exist throughout the AppleTalk internet to which your local network belongs

Applications running on nodes connected to both extended and nonextended networks can use ZIP to get the name of their node's zone. An application running on a node that belongs to an extended network can call ZIP to get a list of all the zone names associated with that network. For example, a network administration application might use ZIP to provide an administrator with a list of the zones for a particular network so that the administrator can select the correct zone for a node when adding nodes to a network.

You can use ZIP in conjunction with NBP. For example, you can use ZIP to look up zones on the network, then use NBP to look up names in each zone.

ZIP sends the GetMyZone, GetLocalZones, and GetZoneList functions as AppleTalk Transaction Protocol (ATP) requests. These requests always ask for a single response.
For example, when you call ZIP to request zone name information, the portion of ZIP implemented on the node running your application sends a request using the transaction-
based services of ATP to the portion of ZIP implemented on a local router that contains the zone information table; using ATP, ZIP on the router node transmits a response to your request.

When you call GetMyZone to get the name of your node's zone, ZIP returns the complete zone name in a single ATP response and writes that zone name to the buffer you provide. However, when you want to retrieve a list of zone names belonging
either to your local network or to all of the networks forming the internet, ZIP may not
always be able to return the complete list of names in a single ATP response. In this
case, you need to call the ZIP function repeatedly in a loop in order to retrieve all of the
zone names.

The GetMyZone, GetLocalZones, and GetZoneList functions each use a parameter block of type XPPParamBlock to contain input and output values for the call. You use the xCallParam variant record to the XPP parameter block for the ZIP functions. This parameter block contains an ioRefNum field, which the MPW interface sets to the .XPP driver reference number.

The parameter block for each of the three ZIP functions includes a csCode field and an xppSubCode field. You do not need to set these field values before you call the function; the MPW interface fills in the value for each of these fields. The value for the csCode field is always xCall. The xppSubCode field value identifies the specific ZIP function, and it differs for each of the three functions.

For the three ZIP functions, you specify timeout and retry values that determine the behavior of the ATP transaction that the ZIP call relies on. You need to set values for these fields before you call the ZIP function. You use the parameter block's xppTimeout field to set the timeout value and the xppRetry field to set the retry value. The timeout tells ATP how long in seconds to wait between each attempt, and the retry value tells it how may retries it should attempt. For information on how ATP uses these values, see the chapter "AppleTalk Transaction Protocol (ATP)" in this book.

For each function, you supply a buffer to hold the returned zone name data and a buffer that ZIP requires for its own use. These two buffers and the XPPParamBlock parameter block that you allocate for the function belong to ZIP for the life of the call; you must not manipulate them or alter their contents during the operation. The memory for these buffers and the parameter block belongs to the function until the function completes execution.

If you set the function's async Boolean parameter to TRUE, either you must provide a completion routine or your application must poll the parameter block's ioResult field to determine when the function completes the operation. See the chapter "Introduction to AppleTalk" in this book for a discussion of synchronous and asynchronous execution as it applies to the Boolean parameter.

---

Subtopics

Getting the Name of Your Application's Zone

Getting a List of Zone Names for Your Local Network or Its Internet