Sending and Receiving Data

Before you can send to or receive data from an X.25 Virtual Circuit, the X.25 Link must be up, the VC ZLU must be enabled and activated, and in the case of an SVC, a call must be established. The zcntl() routine is used to enable and activate the VC ZLU and the ACC X.25 API routines are used to establish a call on an SVC. Once these conditions are met, you may send data using the zsend() routine and read data that has arrived on the application's program ZLU using the zread() routine. Note that before inbound data from a VC ZLU is delivered to an application's program ZLU, you must call the zset_rcvr() routine for each and every VC ZLU whose inbound data is to be delivered to the application.

All application data is transmitted (or received) as the data field of a data packet contained within the I-field of an information frame. All level 2 and level 3 protocol headers and/or trailers are transparently supplied by the protocol for outgoing messages and removed by the protocol for incoming messages. Only the actual data to be transferred is dealt with by the application program.

When reading inbound data from the application's program ZLU queue, care must be taken to examine the type of data that has arrived. The zread() routine returns the ZCOM message header and the message data buffer. The message header contains information on which VC ZLU the data came from and what type of data the message represents. Note that the message could contain inbound data from the VC ZLU, unsolicited status information, or buffer completion status from a previous zsend() call. The following example shows how to enable a VC, setup the VC's receiver for inbound data, read a data message and interpret its meaning:

#include <zcom/zcomsys.h>
#include <zcom/zcomx25.h>
 
int                     rc;          /* General return code. */
int                     rlen;        /* # of bytes returned in rdata. */
unsigned char           rdata[1204]; /* Buffer for inbound data. */
zmhd_type               msghdr;      /* ZCOM Message header structure. */
zaddr_type              l3zlu;       /* Our X.25 Virtual Circuit ZLU. */
zaddr_type              pzlu;        /* Our application's program ZLU. */
 
 
/*
 Issue a request to enable and activate the VC ZLU.  Note:  For the purposes
 of this example, assume that l3zlu and pzlu have already been initialized.
 */
if (rc = zcntl(&l3zlu, 1, ZCOM_MRQCODE_ENB, 0, 0, 0)) {
   /* Handle Error */
}
if (rc = zcntl(&l3zlu, 1, ZCOM_MRQCODE_ACT, 0, 0, 0)) {
   /* Handle Error */
}
 
/*
 Issue request to deliver inbound data and status to this application.
 */
if (rc = zset_rcvr(ZcADD_PRIMARY, &l3zlu, 0, &pzlu)) {
   /* Handle Error */
}
 
while (1)     /* Inifinite loop to read data */
   {
   if (rc = zread(&pzlu, 0, &msghdr, rdata, sizeof(rdata), &rlen, NULL)) {
      /* Handle Error */
      break;
      }
 
   l3zlu = msghdr.mid.mzsrce;   /* ZLU of Virtual Circuit that data came from. */
   switch (msghdr.mid.mstype)
      {
      case ZCOM_MSTYPE_MSLT:    /* (1) Data from local VC ZLU (terminal)   */
         {                 /* rdata[] contains data from remote end of VC. */
         if (msghdr.mrq.mrqtag & 0x10)  /* M-bit set ? */
            {                           /* Yes */
            }
         if (msghdr.mrq.mrqtag & 0x80)  /* Q-bit set ? */
            {                           /* Yes */
            }
         break;
         }
      case ZCOM_MSTYPE_RSLT:    /* (6) Status from local VC ZLU (terminal) */
         {
         if (msghdr.mrq.mrqcode == ZCOM_MRQCODE_STATUS)  /* Unsolicited Status */
            {
 
 
switch (msghdr.mrq.mrqstat)
               {
          case ST26INTPT:     /* Inbound Interrupt (rdata has interrupt data) */
          case ST26ICONF:     /* Transmitted Interrupt confirmation received */
          case ST26LCENB:     /* VC has been enabled. */
          case ST26LCUP:      /* VC is now up.  Ready for data transfer. */
          case ST26LCDN:      /* VC is now down.  E.g. Call clear is done. */
          case ST26CLRCF:     /* Inbound call.  rdata has call packet data. */
          case ST26LCRSR:     /* Inbound Reset.  rdata has cause and diag codes */
          case ST26LCRST:     /* Inbound Reset Confirmation. */
          case ST26LCCLR:     /* Inbound Clear.  rdata has clear packet data. */
          case ST26LCCLC:     /* Inbound Call Accept. rdata has call accept pkt */
          case ZxRESET_TO:    /* Reset Request has timed out. */
          case ZxCLR_CONF:    /* Clear Confirm.  rdata has confirm packet data. */
 
                  /* For each case, add appropriate code to handle event */
 
               }  /* End of inner Switch */
            }  /* End of MRQCODE_STATUS If */
          else if (msghdr.mrq.mrqcode == ZCOM_MRQCODE_WRITE)
            {                        /* Buffer completion status */
               /* Most likely, a zsend request failed - handle error */
            }
         break;
         }
      }  /* End of Switch */
   }  /* End of While-loop. */

Receiving and Confirming Interrupt Data

Inbound interrupt data packets always arrive in unsolicited status messages. Specifically the data returned by zread() will have a message type (mstype) of ZCOM_MSTYPE_RSLT, a message request code (mrqcode) of ZCOM_MRQCODE_STATUS, and a message status code (mrqstat) value of ST26INTPT. From the example above, rlen contains the length of the interrupt data and rdata contains the interrupt data, itself.

In the X.25 protocol, only one unconfirmed Interrupt Data Packet is allowed at any given point in time on a Virtual Circuit. If a second Interrupt Data packet arrives before the first is confirmed, it causes the VC to be reset. The VC option word is used to control how the confirmation is handled for inbound interrupt data. If the INTC bit (bit 1) is set to zero, then the application can simply read the interrupt data with no further action needed. The X.25 firmware running on the card automatically sends an Interrupt Confirm packet immediately upon arrival of an Interrupt Data Packet.

However, if the INTC bit in the option word is set to one, then the application is expected to confirm each and every arriving interrupt packet using the ZCOM API call zx25int_conf(). Further, the application must confirm an inbound interrupt data before the T26 timer expires (nominally 180 seconds). Setting the INTC bit allows two cooperating applications to receive end-to-end acknowledgment for the processing of interrupt data. The following code fragment demonstrates how to confirm and interrupt packet:

#include <zcom/zcomsys.h>
#include <zcom/zcomx25.h>
 
int               rc;           /* General return code. */
zx25info_type     zxi;          /* ZCOM X.25 access data structure. */
zaddr_type        vc_zlu;       /* Our X.25 Virtual Circuit ZLU. */
 
 
/*
 Issue a request to send interrupt confirmation on the VC ZLU.  Note:  For the
 purposes of this example, assume the vc_zlu has already been initialized.
 */
 
if (rc = zx25int_conf(&zxi, &l3zlu)) {
   /* Handle Error */
}

Sending Interrupt Data

To send an X.25 interrupt data packet, you should use the ZCOM API call zx25send_int().

If the X.25 link has been configured for 1980 operations, you may send only one byte of interrupt data. If you are using 1984 or later, you may send up to 32 bytes of interrupt data. After sending an interrupt data packet, you are not allowed to send another interrupt data packet until the interrupt confirmation status is received, or the confirmation times out.

For more information on using the zx25send_int() API call, refer to the call description later in this chapter.




	NOTE: Previous releases of the ACC X.25 Protocol provided a mechanism to send X.25 interrupt data packets via a zcntl() call. This mechanism is now obsoleted, but remains available in this release for backwards compatibility.

Application Use of the M, Q, & D-Bits

Messages can be sent and received with the D, M, and Q bits set. The application program uses the message tag byte in the ZCOM message request header (zmrq_type). The tag byte is defined in this structure as field mrqtag. The tag byte should be set in messages sent and examined in messages received.

Table 4-1 Tag Byte in Send Messages

7	6	5	4	3	2	1	0
Q	D		M

Table 4-2 Tag Byte in Receive Messages

7	6	5	4	3	2	1	0
Q	D		M			Q

M-Bit Handling

If bit-4 of the tag byte is set by the application as it sends a message then the last packet of that message will be transmitted with the M-bit set. It is important, when making use of this facility, that the application send exact multiples of the Level 3 packet size, as a partially complete packet with the "More" bit set is illegal and will not be allowed by the network. Note that the MUX card has a total of 22K bytes of outbound buffer space for each port. The largest contiguous message that may be sent without the M-bit set is approximately 4K bytes.

If the X.25 link option word bit (IRX) to allow fragmenting of received messages has been enabled and the load on the Mux is such that the received packets of an incomplete data sequence are sent to the application, then bit-4 will be set in the tag byte received by the application with the data. This indicates that the inbound data message still has more data to come (e.g. this is a partial data message).

D-Bit Handling

1980 Mode

In this mode, the application can set the D-bit on all packets of an outgoing message by setting bit 6 of the tag byte. Received packets with the D-bit set are acknowledged by the X.25 firmware.

1984/1988 Mode

In this mode, the application can set the D-bit on all packets of an outgoing message by setting bit 6 of the tag byte, provided that the use of the D-bit has been agreed to at CALL setup. D-bit use negotiation can be performed by the application issuing or acknowledging the CALL.

If an outgoing call is being made automatically on enable, then D-bit usage will be negotiated if the parameters in the link option word and the V. C. 'poll' word allow it.

Received packets with the D-bit set to 1 are acknowledged according to the setting of the APD option in the virtual circuit option word.

The X.25 firmware is able to enforce negotiation of the D-bit by setting the ND bit in the X.25 Link POLL word (see “Configuration Parameters Definition” in Chapter 3 “ZX25D X.25 Protocol Driver”). When this bit is set any D-bit packets received will cause a RESET to be sent unless the D-bit usage has been negotiated in the call setup.

Application End-to-End Acknowledgments Disabled (APD=0)

End-to-end application acknowledgment handling is controlled through the VC ZLU's option word APD bit. When this bit is set to zero, application end-to-end acknowledgments are disabled and all data packet D-bit handling is performed by the X.25 firmware running on the ACC card. The implications for the application program are as follows:

For transmitted messages with the D-bit set, the write completion (definite) status is returned when a level two acknowledgment (RR) is received for that data message. That is, if the application called zsend() with a mode parameter of ZcMODE_DEF_STATUS (2), the application would received a write completion status when the HDLC/LAP-B protocol RR'd (ack'd) the data message. There is no way for the application to determine when X.25 level 3 acknowledges the data message (e.g. D-bit ack).
For received messages or message fragments with the D-bit set, the application can determine that the D-bit was set by examining the tag byte. The application has no control over the transmission of the acknowledgment to the D-bit data packets. In fact, the X.25 firmware generally sends the D-bit acknowledgment immediately.

Using Application End-to-End Acknowledgments (APD=1)

Application end-to-end D-bit handling is enabled by setting the APD bit in the VC ZLU's option word. This alters how D-bit data packets are handled by the firmware, imposes certain restrictions on transmission of data messages with the D-bit set, and mandates programming rules by the application in regards to D-bit handling. The implications for the application are as follows:

For transmitted messages with the D-bit set, the write completion (definite) status is returned when the messages receives a level three acknowledgment (RR). Only one message at a time, per VC, may be transmitted with the D-bit set. The application must wait for the D-bit acknowledgment before another zsend() is issued with the D-bit set on that VC. This implies that applications should always use a mode of ZcMODE_DEF_STATUS, ZcMODE_WAIT, or ZcMODE_DEF_STATUS_WBUF when sending data messages with the D-bit.
For received messages or message fragments with the D-bit set, the X.25 firmware does not send an X.25 level 3 acknowledgment for the message. This is now the responsibility of the application. The application must determine whether the D-bit was set by examining the tag byte. For each received message or message fragment with the D-bit set, the application must call the function zx25dbit_ack() to cause a level 3 RR (D-bit acknowledgment) to be transmitted by the firmware for the data packet. If the T25 timer has been configured, the application should call zx25dbit_ack() within the T25 timer value or the VC is reset.

Q-Bit Handling

A complete packet sequence received with the Q-bit set in every packet is passed to the "Alternate Receiver" for the logical channel (refer to the man page on zset_rcvr in the ACC Programmer's Reference Guide). If the same application is Receiver and Alternate Receiver for the logical channel, it can identify a message with the Q-bit set by checking bit 1 of the tag byte. Bit 1 will be set if the message had the Q-bit set.

To send a message with the Q-bit set, the application should set bit 7 of the tag byte.