Legacy Document

Inside Macintosh: Networking /

Chapter 4 - Zone Information Protocol (ZIP) / Using ZIP

Getting the Name of Your Application's Zone

Your application can get the name of the zone for the node on which it is running by calling the GetMyZone function. The zone name is a data structure of type Str32,
and the GetMyZone function writes the zone name to a buffer that you supply. You
set the parameter block's zipBuffPtr field to a pointer for a buffer that must be at
least 33 bytes in size.

You also supply a buffer that is 70 bytes in size as the value of the zipInfoField. You must set the first word of this buffer to 0 before you call the function. This buffer is for ZIP to use.

Listing 4-1 shows the application-defined DoGetMyZone function, which illustrates the use of the GetMyZone function. The DoGetMyZone function declares the parameter block and the return buffer. Then it assigns values to the some of parameter block fields and initializes to 0 the first word of the zipInfoField parameter before it calls GetMyZone. The MPW interface fills in the XPP parameter block ioRefNum, csCode, and xppSubCode fields, so the DoGetMyZone function doesn't need to assign these values.

Listing 4-1 Using the GetMyZone function

FUNCTION DoGetMyZone(VAR myZoneName: Str32): OSErr;
VAR
   xppPB: XPPParamBlock;
   myZoneName:    ARRAY[1..33] OF Char;
BEGIN
   WITH xppPB DO
      BEGIN 
         xppTimeout := 3;           {timeout interval}
         xppRetry := 4;             {retry count for ZIP requests}
         zipBuffPtr := @myZoneName; {buffer for returned zone name}
         zipInfoField[1] := 0;      {initialize first word to 0}
         zipInfoField[2] := 0;
      END;
   DoGetMyZone := GetMyZone(@xppPB, FALSE);
END;

If there is no router present in the network, the function returns a function result of noBridgeErr. If the retry count is exceeded before the ATP transaction that ZIP relies on receives a valid response, the function returns a function result of reqFailed. The function returns a function result of tooManyReq when too many concurrent ATP requests have been made. If you receive a function result of tooManyReq, wait a minute or so, and then try again; some transactions can take up to 30 seconds to complete. For the complete list of function results, see the description of the function GetMyZone beginning on page 4-12.