Virtual Terminal Run-Time Example

To help understand how virtual terminal APIs are used, the following example shows how the i5/OS^(TM) operating system, server program, client program, and work station device (display and keyboard) interact when processing a system request.

This example starts with the server program waiting for a response from the client program, which is waiting for data from the user (keyboard).

1. System request processing starts when you press the appropriate System Request key on the work station keyboard.
   
   
2. The client program informs the server program that the System Request key has been pressed. The protocol used in this case is unique to the particular implementation of these two programs.
   
   
3. The server program calls the Write to Virtual Terminal (QTVWRTVT) API for a write request. The flag for the System Request key must be set for this write request. No data is sent to the virtual terminal at this time.
   
   
4. The i5/OS licensed program creates a data queue entry for informing the server program that data is available to be read.
   
   
5. The server program removes the entry from the data queue by calling the Receive Data Queue (QRCVDTAQ) API and then calls the Read from Virtual Terminal (QTVRDVT) API for a read request. The Cancel Invite operation code is returned. No data is received from the virtual terminal at this time.

   To prevent the client program from sending anymore data (screens), the server program informs the client program that it is no longer receiving data from the client program.

   The server program calls the QTVWRTVT API for a write request. The Operation Code parameter is set to Cancel Invite. No data is sent to the virtual terminal at this time.

6. The i5/OS licensed program creates a data queue entry for informing the server program that data is available to be read.
   
   
7. The server program removes the entry from the data queue by calling the QRCVDTAQ API and then calls the QTVRDVT API for a read request. A Save Screen operation code is returned. No data is received from the virtual terminal at this time.

   The server program gets the current screen. This may require requesting the current screen from the client program.

   The server program calls the QTVWRTVT API for a write request, sending the current screen to the virtual terminal. The Operation Code parameter must be set to Save Screen.

8. The i5/OS licensed program creates a data queue entry for informing the server program that data is available to be read.
   
   
9. The server program removes the entry from the data queue by calling the QRCVDTAQ API and then calls the QTVRDVT API for a read request. A Put/Get operation code is returned. The data read will be the actual System Request menu.

   The server program sends this data to the client program and waits for a response.

10. The client program updates the display with the System Request menu and waits for a response from the user. The resulting response is sent to the server program.
    
    
11. The response is received from the client program, and the server program calls the QTVWRTVT API for a write request, sending the response to the virtual terminal.

    Note: What happens at this point depends on the response to the System Request menu. Additional data may be received from and sent to the virtual terminal. After the response is processed, the following steps occur.

12. The i5/OS licensed program creates a data queue entry for informing the server program that data is available to be read.
    
    
13. The server program removes the entry from the data queue by calling the QRCVDTAQ API and then performs a call to the QTVRDVT API for a read request. A Put operation code is returned. The data read is the saved (current) screen that was previously written by the server program to the virtual terminal.

    The server program sends the saved screen to the client program but does not wait for a response.

14. The client program updates the work station display with the saved screen.
    
    
15. The i5/OS licensed program creates a data queue entry for informing the server program that data is available to be read.
    
    
16. The server program removes the entry from the data queue by calling the QRCVDTAQ API. An Invite operation code is returned. Note that no data is received from the virtual terminal at this time.
    
    
17. The client program is once again waiting for user data, and the server program is waiting for data from the client program.