Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Networking /
Chapter 8 - AppleTalk Session Protocol (ASP) / ASP Reference
Routines / Sending Commands and Writing Data From the Workstation to the Server


ASPUserWrite

The ASPUserWrite function transfers data from the workstation to the server across a specific session.

FUNCTION ASPUserWrite (thePBptr: XPPParmBlkPtr;
                       async: Boolean): OSErr;
thePBptr
A pointer to an XPP parameter block.
async
A Boolean that specifies whether the function should be executed asynchronously or synchronously. Specify TRUE for asynchronous execution.
-->ioCompletionProcPtrA pointer to a completion routine.
<--ioResultOSErrThe function result.
<--cmdResultLongIntThe ASP command result.
-->ioRefNumIntegerThe .XPP driver reference number.
-->csCodeIntegerAlways userWrite for this function.
-->sessRefnumIntegerThe session reference number.
-->aspTimeoutByteThe retry interval in seconds.
-->cbSizeIntegerThe command block size.
-->cbPtrPtrA pointer to command blocks.
<->rbSizeIntegerThe reply buffer size and reply size.
-->rbPointerPtrA pointer to the reply buffer.
<->wdSizeIntegerThe write data size.
-->wdPtrPtrThe write data pointer.
<--ccbStartArrayThe beginning of memory for the CCB.

Field Description
cmdResult
The ASP command result consisting of 4 bytes of data returned by the server. The ASP client application defines the contents of the command result field. For example, AFP defines this field to specify the result of the AFP command. This field is valid if no system-level error is returned in the ioResult field.
sessRefnum
The reference number of the session that you want to use to transfer data. The session reference number is the unique number that the .XPP driver assigned to this session when you opened the session by calling the ASPOpenSession function.
aspTimeout
The time in seconds after which ASP is to retry to send data across the session.
cbSize
The size in bytes of the command data that ASP is to transfer across the session.
cbPtr
A pointer to the buffer containing the command data to be transferred.
rbSize
On input, the size in bytes of the buffer that you allocated to contain the command reply that you expect to receive from the server. On return, the size in bytes of the reply data that was actually returned.
rbPointer
A pointer to the buffer for the reply data.
wdSize
On input, the size in bytes of the of the write data that the command is to send. On return, the size in bytes of the write data that was actually sent.
wdPtr
A pointer to the buffer containing the data to be written.
ccbStart
The beginning of the memory for the command control block (CCB) that the .XPP driver is to use. The maximum size of this block
is 296 bytes. The CCB is an array that is part of the .XPP
parameter block.
DESCRIPTION
The ASPUserWrite function allows you to transfer a variable-size block of data to the server end of the ASP session and receive a reply. If you have previously called the ASPUserCommand function to send a command that directs the ASP server to open a file, you can call the ASPUserWrite function to write data to the file.

The .XPP driver uses the memory at the end of the XPP parameter block defined as
a CCBStart array as an internal command control block (CCB). To ensure that the function executes successfully, you can specify the maximum size for this array as indicated in particular for the function that uses it. If you want to limit the amount
of memory used for the CCB, you can specify the minimum amount of memory
required for this array.

A command result error is returned in the cmdResult field. All other types of errors
are returned in the function's parameter block ioResult field. Error reporting for
the ASPUserWrite function is the same as for the ASPUserCommand.

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.

ASSEMBLY-LANGUAGE INFORMATION
To execute the ASPUserWrite function from assembly language, call the _Control trap macro with a value of userWrite in the csCode field of the parameter block. You must also specify the .XPP driver reference number. To execute the _Control trap asynchronously, include the value ,ASYNC in the operand field.

RESULT CODES
aspBufTooSmall-1067The reply data exceeds the size of the reply buffer; the .XPP driver will fill the buffer and truncate
the data
aspParamErr-1070You specified an invalid session reference number,
or the session has been closed
aspSessClosed-1072The .XPP driver is in the process of closing
the session
aspSizeErr-1073The size of the command block exceeds the
maximum size of 296 bytes
SEE ALSO
To send a command to the server to direct it to perform a prerequisite action before you use the ASPUserWrite command to write data, use the ASPUserCommand function, described on page 8-15. To determine the minimum amount of memory required for the CCB or to find out more about the possible types of error conditions for which errors are returned and how these error results are reported, see the description of the ASPUserCommand function.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996