TCP/UDP/IP API (Pascal Language)

This chapter describes the Pascal language application program interface (API) provided with TCP/IP for z/VM. This interface allows programmers to write application programs that use the TCP, UDP, and IP layers of the TCP/IP protocol suite.

You should have experience in Pascal language programming and be familiar with the principles of internetwork communication to use the Pascal language API.

Your program uses procedure calls to initiate communication with the TCPIP virtual machine. Most of these procedure calls return with a code that indicates success, or the type of failure incurred by the call. The TCPIP virtual machine starts asynchronous communication by sending you notifications.

The general sequence of operations is:

  1. Start TCP/UDP/IP service (BeginTcpIp, StartTcpNotice).
  2. Specify the set of notifications that TCP/UDP/IP may send you (Handle).
  3. Establish a connection (TcpOpen, UdpOpen, RawIpOpen, TcpWaitOpen).

    If using TcpOpen, you must wait for the appropriate notification that a connection has been established.

  4. Transfer data buffer to or from the TCPIP virtual machine (TcpSend, TcpFSend, TcpWaitSend, TcpReceive, TcpFReceive, TcpWaitReceive, UdpSend, UdpNReceive, RawIpSend, RawIpReceive).
    Note: TcpWaitReceive and TcpWaitSend are synchronous calls.
  5. Check the status returned from the TCPIP virtual machine in the form of notifications (GetNextNote).
  6. Repeat the data transfer operations (steps 4 and 5) until the data is exhausted.
  7. Terminate the connection (TcpClose, UdpClose, RawIpClose).

    If using TcpClose, you must wait for the connection to terminate.

  8. Terminate the communication service (EndTcpIp).

Control is returned to you, in most instances, after the initiation of your request. When appropriate, some procedures have alternative wait versions that return only after completion of the request. The bodies of the Pascal procedures are in the TCPIP ATCPPSRC file.

A sample program is supplied with the TCP/IP program, see Sample Pascal Program.