TS/MP 2.5 Pathsend and Server Programming Manual

Functions of a Context-Sensitive Server
In addition to the functions performed by all Pathway servers, a context-sensitive server must:
• Detect a newly established dialog
• Receive, service, and reply to messages associated with a dialog
• Correlate messages with a dialog
• Continue a dialog
• Terminate a dialog
• Abort a dialog
• Detect an aborted dialog
It is simpler to code a context-sensitive server if you allow only one dialog at a time. To impose
this restriction, you must configure the server-class with a MAXLINKS value of 1. If MAXLINKS is
set to a value other than 1, you must code your server to save multiple dialog contexts and to
switch context, if needed, on each incoming request.
When the server receives an incoming request on $RECEIVE, it can retrieve the sending processes
process handle (phandle) and the file number by calling the FILE_GETRECEIVEINFO_ procedure
or the CRE_Receive_Read_ procedure. The server process uses this information for context
management.
When a server receives a message on $RECEIVE, it checks dialog flag bits <12:13> returned by
the file-system procedure FILE_GETRECEIVEINFO_ or the CRE procedure CRE_Receive_Read_ to
determine whether this is the first message of a new dialog or a message within an existing dialog.
A value of zero in these two bits indicates a context-free send operation. In addition, the server
can check dialog flag bit 14 to determine the model used by the requestor for associating
transactions with dialogs.
For the FILE_GETRECEIVEINFO_ procedure syntax, see the Guardian Procedure Calls Reference
Manual. For the CRE_Receive_Read_ procedure syntax, see the Common Run-Time Environment
(CRE) Programmer’s Guide.
NOTE: CRE_Receive_Read_ and the other CRE routines are callable only from TAL, pTAL,
FORTRAN, and COBOL85 programs and are used when you are writing mixed-language programs.
You cannot use CRE routines along with Guardian procedure calls. For more information about
the use of the CRE routines, see the Common Run-Time Environment (CRE) Programmer’s Guide.
Detecting a Newly Established Dialog
A context-sensitive server detects a newly established dialog by checking bits <12:13> of the
dialog flags returned by the FILE_GETRECEIVEINFO_ or the CRE_Receive_Read_ procedure. If the
value in these bits is 1, the message is the first in a new dialog. This message corresponds to the
call of the requestor to the SERVERCLASS_DIALOG_BEGIN_ procedure. This call starts the dialog
and usually also sends data.
Receiving, Servicing, and Replying to Messages in a Dialog
The server receives, services, and replies to messages in a dialog by doing these:
1. Reads a message from $RECEIVE by using the $RECEIVE reading mechanism for the
programming language, such as a call to the Guardian READUPDATE or READUPDATEX
procedure.
2. Checks bits <12:13> of the dialog flags returned by the FILE_GETRECEIVEINFO_,
FILE_GETRECEIVEINFOL_, or the CRE_Receive_Read_ procedure. If the value in these bits is
1, the message is the first in a new dialog. If the value is 2, the message is for an existing
dialog.
70 Writing Pathway Servers