Legacy Document

Inside Macintosh: Networking /

Chapter 8 - AppleTalk Session Protocol (ASP) / ASP Reference

Routines / Opening and Closing ASP Sessions

ASPOpenSession

The ASPOpenSession function opens an ASP session between an ASP workstation application and an ASP server application.

FUNCTION ASPOpenSession (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.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
-->	ioRefNum	Integer	The .XPP driver reference number.
-->	csCode	Integer	Always openSess for this function.
<--	sessRefnum	Integer	The session reference number.
-->	aspTimeout	Byte	The retry interval in seconds.
-->	aspRetry	Byte	The number of retries.
-->	serverAddr	AddrBlock	The server socket address.
-->	scbPointer	Ptr	A pointer to the session control block.
-->	attnRoutine	Ptr	A pointer to an attention routine.

Field Description

sessRefnum

A unique number that the .XPP driver assigns to the session that it opens if the function completes successfully.

aspTimeout

The interval in seconds between retries of the open session request.

aspRetry

The number of times that ASP will retry to open a session.

serverAddr

The internet socket address of the socket that the server is using to listen for requests to open a session.

scbPointer

A pointer to a session control block (SCB) that the .XPP driver requires to maintain an open session. The scbMemSize constant defines the size of the session control block. The memory that you allocate for the SCB must be nonrelocatable or locked because it belongs to the .XPP driver for the life of the session.

attnRoutine

A pointer to a routine that ASP calls if the workstation component of ASP receives an attention request from the server or if the session is closed. If you do not want to specify an attention routine to be called, set this pointer to NIL.

DESCRIPTION

To gain access to an ASP server, you must call the ASPOpenSession function to open
a session. Before calling the ASPOpenSession function, you must obtain the internet socket address of the socket that the ASP server uses to listen for incoming session requests. The server uses a session listening socket (SLS) for this purpose. You can use the Name-Binding Protocol (NBP) to get the internet socket address of an SLS. You pass the internet socket address of the SLS as the value of the serverAddr parameter.

You also pass the ASPOpenSession function a pointer to a session control block (SCB) in the scbPointer parameter. The .XPP driver uses the SCB internally to manage the session. Each session requires its own SCB. You must either allocate nonrelocatable memory for the session control block or lock the memory and not modify it for the duration of the session. The SCB size is defined by the constant scbMemSize. The memory belongs to the .XPP driver for the life of the session. You can reuse an SCB after either of the following events occurs:

• You have called the ASPCloseSession function to close the session and it has completed successfully.
• The server end of the ASP session has closed the session or the .XPP driver has closed the session. In both cases, the .XPP driver returns an aspParamErr result code as the result of a call for that session.

You can also pass the ASPOpenSession function a pointer to an attention routine that the .XPP driver calls when it receives an attention request from the server and when the session is closing. ASP provides an attention mechanism that allows the ASP server to notify the ASP workstation application of some event or critical piece of information. As the value of the attnRoutine parameter, you can specify a pointer to your attention routine, and the .XPP driver will call this routine when it receives an attention request from the server or when the server, the workstation, or ASP closes the session; ASP, as implemented in the .XPP driver, will close a session if it cannot successfully open the session before it exhausts the number of retries.

Because the .XPP driver calls your attention routine at interrupt level, you must observe the following interrupt conventions in writing the attention routine:

• An attention routine can change registers A0 through A3 and D0 through D3.
• The routine must not call any Memory Manager routines.

The .XPP driver calls your attention routine with

• D0 (word) equal to the session reference number (sessRefnum) for that session. This is the number that ASP returns on completion of the ASPOpenSession function.
• D1 (word) equal to the attention bytes passed by the server or 0 if the session
  is closing.

To resume normal execution, your attention routine must return with an RTS (return from subroutine) instruction.

If you code your program in a high-level language such as Pascal, you might not want to provide an attention routine written in assembly language. If you do not want to provide an attention routine, you can poll the attention bytes to determine if your ASP work-
station application has received an attention request from the server. The attention bytes are the first 2 bytes of the session control block. When the .XPP driver receives an ASPOpenSession function call, it sets these 2 bytes to 0. When the server sends an attention request to the workstation, the .XPP driver receives the request and sets the first 2 bytes of the SCB to the attention bytes from the packet. (A higher-level protocol that uses the services of ASP defines the attention code that the 2 attention bytes in the packet carry.) If the first 2 bytes of the SCB are nonzero when your Pascal program polls them, the program will know that it has received an attention request from the server. Your program can handle the request, based on the conventions defined by the higher-level protocol, and reset the SCB's attention bytes to 0. However, using this method to determine if the workstation has received an attention request from the server has limitations: two or more attention requests could be received between successive polls and only the last one would be preserved.

When the .XPP driver receives an ASPOpenSession function, it sends a special open session (OpenSession) packet as an ATP request to the SLS; this packet carries the address of the socket that the ASP workstation application or process is using for the session. The open session packet also carries a version number so that both ends can verify that they are using the same version of ASP.

Once you open a session, you can send commands and data to the server and receive command replies from the server. However, before you open an ASP session, you should call the ASPGetParms function to determine the maximum sizes of commands and replies that ASP supports on your node.

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 ASPOpenSession function from assembly language, call the _Control trap macro with a value of openSess 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

aspBadVersNum	-1066	The server cannot support the ASP version number
aspNoMoreSess	-1068	The .XPP driver cannot support another ASP session (the number of sessions that the driver is capable of supporting is dependent on the machine type)
aspNoServers	-1069	There is no server at the specified serverAddr address, or the server did not respond to the request
aspParamErr	-1070	You specified an invalid session reference number, or the session has been closed
aspServerBusy	-1071	The server cannot open another session
reqAborted	-1105	The ASPOpenSession function call was aborted by an ASPAbortOS function call

SEE ALSO

For information on how to use NBP, see the chapter "Name-Binding Protocol (NBP)" in this book.

You can use the ASPAbortOS function described on page 8-25 to cancel an outstanding ASPOpenSession function request before it completes execution.

For the maximum sizes of commands and replies that ASP supports on your node, use the ASPGetParms function, described on page 8-22.