AIFPORTOPEN

The first time that AIFPORTOPEN is called for a named port that does not exist, it is created by default. If the named port already exists, it is opened. AIFPORTOPEN returns an integer value that must be supplied to all other port AIFs to identify the port being referenced. The default AIFPORTOPEN creates the port as temporary and does not allow for the asynchronous receipt of messages.

An asynchronous port is a port that provides the capability of interrupting the creator upon receipt of a message and transfers control to a user specified handler. To create an asynchronous port specific items must be passed to the AIFPORTOPEN routine. The following example illustrates the creation of an asynchronous port.

readln (user_id);

portname          := 'aifport1        ';

portpass          := 'aifpass1        ';

accessmode        := 1;          { receive access }

itemnum_ports     := Init_Itemnum_Array; { zero array }

item_ports        := Init_Item_Array;

item_status_ports := Init_Item_Status_Array;

createoptions     := 2;          { create new     }

itemnum_ports [1] := 11201;

item_ports [1]    := ADDR(createoptions);

maxmsgsize        := 80;         { message size   }

itemnum_ports [2] := 11202;

item_ports [2]    := ADDR(maxmsgsize);

proc_name         := '#PORTHANDLER#';

proc_file         := '#ASYNC1#';



HPGETPROCPLABEL (proc_name, createhandler, 

	         overall_status, proc_file, False);

if overall_status.all <> 0 then

  ERROR_IN_CALL('HPGETPROCPLABEL',overall_status);



itemnum_ports [3] := 11206;

item_ports [3]    := addr(createhandler); { handler address }

createstate       := True;

itemnum_ports [4] := 11207;  { next element initialized to 0 }  

item_ports [4]    := addr(createstate); { enabled }



portid1 := AIFPORTOPEN(overall_status, portname, portpass, 

		       accessmode,,itemnum_ports, 

		       item_ports, item_status_ports);

if overall_status.all <> 0 then

  ERROR_IN_CALL('AIFPORTOPEN',overall_status,

		 item_status_ports);

The creator of an asynchronous port is the only process that may receive messages from this port, and must provide the handler address when opening the port. If the creating process abnormally terminates, subsequent sends to the port will return an error.

AIF ports that do NOT specify a handler at creation time, receive messages synchronously and allow multiple receivers. In addition, synchronous ports can be permanent, however, asynchronous ports are always temporary.

Handlers for asynchronous ports must be coded to certain conventions in order to function properly. The address of the handler can be acquired by calling the intrinsic HPGETPROCLABEL as shown in the previous example.

When defining the handler routine, the calling sequence must have one parameter. This parameter will contain the portid of the AIF port which received the asynchronous message.

In Pascal/iX, a handler is declared as follows:

procedure INT_HANDLER ( port_id : integer );

In C/iX, it would be:

void INT_HANDLER ( int portid )

Handlers should do only what is absolutely necessary. It is NOT a good idea to do the AIFPORTRECEIVE using the "all ports" option, as this can result in unnecessary delays. When using item 11003 of AIFPORTRECEIVE to retrieve envelope information, be sure to do the actual receive of the message, otherwise the message will remain queued to the port. Also, consider potential traps and escapes and do not allow your handler to be exited in this fashion. If a handler does escape, it will be caught by AIF ports code and will NOT be propagated out to the user.

Finally, a handler may never call AIFPORTCLOSE to close an asynchronous port. This will result in unpredictable behavior, and possible system failure. Handlers that are written in C, may not use the longjump function and must have a return-type of void. Handlers execute at ring level 2 or privileged mode. Calls to GETUSERMODE are not allowed inside the handler, this will cause an IMEM protection trap, which results in a process abort.

The asynchronous receipt of incoming messages has been implemented through Process Interrupts. A process interrupt is generated to signal the arrival of a message on an asynchronous port. The process interrupt will "interrupt" the creator process transferring control to the user supplied interrupt handler. As with other types of process interrupts (eg., Break, Cntrl Y), control will not be transferred to the user's handler until the creator process is in the appropriate state. For asynchronous port interrupts, the process interrupt will be postponed if the creator is critical, in system code, or executing at ring level 0 or 1. This is done to protect critical system operations from being interrupted by the user application.

A waited receive against an asynchronous port takes precedence over notification by a process interrupt. Therefore, a process which blocks, waiting for a message from its asynchronous port has effectively disabled process interrupt notification. Several possible uses of asynchronous ports are described to illustrate the systems behavior.

A process opens an asynchronous port with port interrupt handling enabled. The handler does a nowait receive to get the message and it does not access any global data.

When a send is issued against the port the message is queued by the send request. Messages sent to a process NOT blocked on an asynchronous port receive, will result in a process interrupt. When the receiving process is in the appropriate state (ring level 2 or 3) the user handler will be invoked. It is possible for the user interrupt handler to nest multiple levels deep if additional process interrupts occur. In this case, the user should do a single receive against the port for each call of the handler. The user should also handle error messages appropriately.

However, if the receiver chooses to explicitly wait for the arrival of a message on an asynchronous port, when the send is issued, the dispatcher is notified to unblock the process. When the receiver process is awoken, it will complete the receive operation on a single message. It is possible for multiple messages to queue while the process is blocked. If a user waits on an asynchronous port in this fashion, they are responsible for checking for multiple messages once the receive completes.

The user opens an asynchronous port. AIFPORTINT is called to disable port interrupt handling around critical areas in the user code. Also AIFPORTINT is used in the handler to disable interrupt handling after entry, and later re-enabled before exiting the handling routine.

Again, the message is queued to the port when the send request is issued. If the receiver is not currently waiting on the port, the process interrupt will occur. Further process interrupts will nest until the user calls AIFPORTINT inside their handler. Once interrupt handling is disable, additional messages which arrive will cause a pending count to be incremented and the handler invokation will be delayed. When AIFPORTINT is called to re-enable interrupt handling, the user handler will be called once for each time the pending count was incremented. This is repeated until the pending interrupts have been serviced.

If the user is sitting in a waited receive, multiple messages can be sent, and the receiver will unblock. The receive will return the first message, but the user is responsible for clearing the port. If the user calls AIFPORTINT around the waited receive, it is possible the user can clear messages from the port, and when AIFPORTINT is called to enable interrupt handling, the handler could get invoked for messages which have already been read. Therefore, the handler should be coded to handle the case where no messages exist on the port.

Table 3-23 AIFPORTOPEN Item Descriptions