Legacy Document

Inside Macintosh: Networking /

Chapter 9 - AppleTalk Filing Protocol (AFP) / AFP Reference

Routines /

AFP Write Command Format

You use the write command format for the AFPCommand function to pass the afpWrite command to the .XPP driver to send a data block to the server.

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

thePBptr

A pointer to the XPP parameter block format for the afpWrite command.

async

A Boolean that specifies whether the function is to execute synchronously or asynchronously. Set the async parameter to TRUE to execute the function asynchronously.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
<--	cmdResult	LongInt	The AFP command result.
-->	ioRefNum	Integer	The .XPP driver reference number.
-->	csCode	Integer	Always afpCall for this function.
-->	sessRefnum	Integer	The session reference number.
-->	aspTimeout	Byte	The retry interval in seconds.
-->	cbSize	Integer	The command buffer size.
-->	cbPtr	Ptr	The command buffer.
<->	rbSize	Integer	On input, the reply buffer size. On return, the actual reply size.
-->	rbPtr	Ptr	A pointer to the reply buffer.
<->	wdPtr	Ptr	A pointer to the write data.

Field Description

cmdResult

Four bytes of data returned from the server indicating the result of the AFP command.

sessRefnum

The session reference number, which is a unique number that the .XPP driver assigns to the session and returns in response to an afpLogin command.

aspTimeout

The interval in seconds that the .XPP driver waits between retries of the AFP command call.

cbSize

The size in bytes of the block of data that contains the command and its parameters to be sent to the server across the session. The size of the command block must not exceed the value of aspMaxCmdSize that the ASPGetParms function returns. For information on
the ASPGetParms function, see the chapter "AppleTalk Session
Protocol (ASP)."

cbPtr

A pointer to the beginning of the command block buffer that contains the afpWrite command to be sent across the session to the server. The cbSize field value specifies the command block buffer size. The first byte of the command block must contain the AFP command. The following command block bytes contain the parameters for the command. The "Description" section that follows explains the command block structure that you use for
the afpWrite command to be sent to the server.

rbSize

On input, the size in bytes of the reply buffer that is to hold the expected response to the AFP command. On return, the actual size of the reply that the .XPP driver returned in the buffer.

rbPtr

A pointer to the reply buffer.

wdPtr

A pointer to the write data buffer. The .XPP driver updates this field as it proceeds so that the field always points to the section of data that the .XPP driver is currently writing.

DESCRIPTION

After you open a session, you can use the afpWrite command to send a block of data to the server. The AFPCommand function format for the write command allows you to send more data than a single call to an ASPUserWrite function can send. Instead of using a write-data structure to specify the data to be sent, you specify the beginning of the data to be written and the size in bytes of the data as values within the command block. (You do not specify the size of the write data in the parameter block.)

The command block for the afpWrite command consists of the following fields. The byte offsets for these fields are relative to the location indicated by the command block pointer (cbPtr).

Command block

-->	cmdByte	Byte	The AFP command code.
-->	startEndFlag	Byte	A flag identifying offset relative to fork.
<->	rwOffset	LongInt	The offset within fork to begin writing.
<->	reqCount	LongInt	On input, requested size of data; on return, size of data actually written.

Field Description

cmdByte

The AFP command code, which is always afpWrite for
this command.

startEndFlag

A 1-bit flag (the high bit of the byte) indicating whether the offset specified in the rwOffset field is relative to the beginning or the end of the fork: set the high bit to 0 to specify that the offset is relative to the beginning of the fork; set the high bit to 1 to specify that the offset is relative to the end of the fork. Set all other bits of this byte to 0.

rwOffset

The byte offset within the fork at which the write is to begin. The .XPP driver modifies the value of this field as it proceeds; the field always reflects the current value.

reqCount

On input, the size in bytes of the data to be written. On return, the actual size of the data that was written. The .XPP driver modifies the value of this field as it proceeds; the field always reflects the current value.

SPECIAL CONSIDERATIONS

Note that you must provide the .XPP driver reference number as an input parameter
to this function. You can obtain the driver reference number by calling the Device Manager's OpenDriver function. For more information on the OpenDriver function, see Inside Macintosh: Devices.

The memory that you allocate for the XPP parameter block, command block, and reply buffer belongs to AFP until the function completes execution, after which you can reuse the memory or release it.

ASSEMBLY-LANGUAGE INFORMATION

To execute the AFPCommand function from assembly language, call the _Control trap macro with a value of afpCall in the csCode field of the parameter block.

RESULT CODES

aspBufTooSmall	-1067	The command reply from the server is larger than the response buffer (ASP will fill the buffer and truncate the reply data)
aspParamErr	-1070	You specified an invalid session reference number, or the session has been closed
aspSessClosed	-1072	The session reference number is valid, but the .XPP driver is in the process of closing the session
aspSizeErr	-1073	The size of the command block exceeds the maximum size of aspMaxCmdSize

SEE ALSO

See "AFP Command Block Record" on page 9-5 for the Pascal structure of the command block for an afpWrite command.