Legacy Document

Inside Macintosh: Networking /

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

Routines / Obtaining Zone Information

GetZoneList

The GetZoneList function returns a complete list of all the zone names on the internet.

FUNCTION GetZoneList (thePBptr: XPPParmBlkPtr; 
                      async: Boolean): OSErr;

thePBptr

A pointer to an XPP parameter block.

async

A Boolean that indicates whether the function should be executed asynchronously or synchronously. Specify TRUE for asynchronous execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
-->	csCode	Integer	Always xCall for this function.
-->	xppSubCode	Integer	Always zipGetZoneList for this function.
-->	xppTimeout	Byte	The retry interval in seconds.
-->	xppRetry	Byte	The retry count.
-->	zipBuffPtr	Ptr	A pointer to data buffer.
<--	zipNumZones	Integer	The number of names returned.
<--	zipLastFlag	Byte	A flag that is nonzero if there are no more names.
-->	zipInfoField	PACKED ARRAY	A data buffer for use by ZIP; first word set to 0.

Field Description

xppSubCode

A routine selector. This field is automatically set by the MPW interface to zipGetZoneList for this function.

xppTimeout

The amount of time, in seconds, that the .ATP driver should wait between attempts to obtain the data. A value of 3 or 4 seconds for the xppTimeout field generally gives good results.

xppRetry

The number of times the .ATP driver should attempt to obtain the data before returning the request failed (reqFailed) result code.
A value of 3 or 4 is usually sufficient.

zipBuffPtr

A pointer to a 578-byte data buffer that you must allocate. ZIP returns the zone names into this buffer as a packed array of
Pascal strings.

zipNumZones

The number of zone names that ZIP placed in the data buffer.

zipLastFlag

A value that indicates if there are more zone names for your network beyond those that ZIP returned in the zipBuffPtr field. The .XPP driver sets this field to 1 if there are no more zone names for your network.

zipInfoField

A 70-byte data buffer that you must allocate for use by ZIP. Typically, you call GetZoneList repeatedly from within a loop. You must set the first word of this buffer to 0 before you call the GetZoneList function the first time through the loop, and you must not change the contents of this field thereafter.

DESCRIPTION

The GetZoneList function returns a complete list of all the zone names on the internet to which the local network of the node running your application belongs. The GetZoneList function uses ATP to retrieve the zone information. The buffer that you allocate to hold the returned zone names is the size of a single ATP response. You must call the GetZoneList function repeatedly until all of the zones for the local network have been returned.

Your application must check the zipLastFlag field to determine if there are more zone names for your network. If the value of this field is 1, there are no more zone names for your local network. If the value of this field is still 0 when the GetZoneList function completes execution, you must empty the data buffer pointed to by the zipBuffPtr parameter and immediately call the GetZoneList function again without changing the value in the zipInfoField parameter.

If you receive a GetZoneList function result of tooManyReqs, wait a minute or so, and then try again; some transactions can take up to 30 seconds to complete.

To obtain a list of only the zone names on the local network, use the GetLocalZones function instead. If you use the GetZoneList function on a nonextended network, the function returns the reqFailed result code.

SPECIAL CONSIDERATIONS

The memory that you allocate for the parameter block and the two buffers required by the GetZoneList function belongs to the .XPP driver until the function completes execution. You can reuse the memory or dispose of it after the operation completes.

ASSEMBLY-LANGUAGE INFORMATION

To execute the GetZoneList function from assembly language, call the _Control trap macro with a value of xCall in the csCode field of the parameter block and a value of zipGetZoneList in the xppSubCode field of the parameter block. To execute this function from assembly language, you must also specify the .XPP driver reference number.

RESULT CODES

noErr	0	No error
noBridgeErr	-93	No router is available
reqFailed	-1096	Request to contact router failed; retry count exceeded
tooManyReqs	-1097	Too many concurrent requests
noDataArea	-1104	Too many outstanding ATP calls

SEE ALSO

For the XPPParamBlock data type, see "The XPP Parameter Block for ZIP" beginning on page 4-10.

To get the correct reference number for the .XPP driver, you can use the Device Manager's OpenDriver function, which returns the driver reference number. For information about the OpenDriver function, see the chapter "Device Manager" in
Inside Macintosh: Devices.