You must write your own framing routine and load it into nonpaged pool. Because it is in nonpaged pool, the framing routine must be written in position- independent code. You pass the address of your routine to the driver when you start the line.

The address of the framing routine is kept in the driver’s database for the line. The driver also maintains for each GENBYTE line a context quadword, which is used by the framing interface for keeping state information while it is framing the receive message. The context quadword and the value of the incoming character constitute the total amount of information given to the framing routine. Thus, any protocol-specific context held by the framing routine must be kept in the context quadword since there is no other per-line data available to the framing routine.

The value of the context quadword at the start of the frame is defined in the SETMODE QIO P2 buffer. The framing routine can make use of the quadword in any way it wishes (for example, to hold counts and finite state machine states indicating which characters to expect next). At the end of each frame, the context quadword is reset to its initial value.

The driver calls your framing routine using a JSB instruction in the following manner:

Your framing routine must preserve all the registers it uses (except R0 and R1). It may update the context quadword, but must not change any other system data structures.

On return to the driver, the framing routine holds the following parameters:

Bits set in R0 signify:

So the following values of the least significant byte of R0 indicate:

Note that the framing routine should execute as few instructions as possible for each character, otherwise data may be lost. Ten instructions is a typical upper limit.

Select GENBYTE by setting the NMA$C_LINPR_PRO parameter in the SETMODE startup QIO to the value NMA$C_LINPR_BSY. (Since GENBYTE does not distinguish between line and circuit, the IO$M_CTRL subfunction modifier must always be specified in the startup QIO.)

Note that your process requires CMKRNL privilege to select GENBYTE mode, since access to system code in nonpaged pool is implied.

An IO$_CLEAN QIO stops all outstanding transmit and receive I/O operations.

The driver for a DMA device operates in a degraded mode when running in GENBYTE. This is because it has to examine repeatedly the contents of the receive buffer that is in progress to check whether there are new characters to be passed to the framing routine. Thus, the maximum line speed that the device driver supports in GENBYTE mode is less than that supported by other protocols used by the driver. An upper limit of 9.6K baud for GENBYTE is typical.

Writing a framing routine for GENBYTE is relatively straightforward. Getting it loaded into system space, and providing the address of the framing routine, needs care. Remember that a GENBYTE framing routine effectively augments the VMS executive on line. Take great care to ensure that you have designed the GENBYTE interface correctly: an improperly designed interface can crash the system.

Example techniques you might use are as follows:

Once the framing routine had been loaded into nonpaged pool and its entry point address has been identified, a CMKRNL-privileged process (the "starter-process") can issue an IO$_SETMODE QIO to start up the line into GENBYTE mode. If the starter-process is the only process that will perform data transfers over the line, then it can proceed to issue IO$_WRITELBLK and IO$_READLBLK QIOs. If other user-processes are required to transfer data over the line, then either they must have SHARE privilege, or else run images installed with SHARE privilege. SHARE privilege is required so that the process can assign to the line at the same time as the starter-process.

Section B.5, ''A Sample GENBYTE Macro-32 Framing Routine for a Subset of the IBM BISYNC Protocol'' contains an example GENBYTE routine.

/*
**
** INCLUDE FILES
**
**/

#include  <stdio.h>
#include <starlet.h>
#include iodef
#include descrip
#include ssdef
#include "xmdef.h"
#include "nmadef.h"
#include "dl_external.h"
#include "dll_external.h"
 
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  This program sends data to a device using the WANdriver interface
**  to the DECnet/OSI datalinks
**  The program requires the HDLC module with link name ’HDLCL1’ and
**  logical station name ’LS2’.
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES
**
**  Success/Fail codes
**
**
**  SIDE EFFECTS:
**
**  none
**--
**/
void ATT_AST(long status);  /* Function declaration */
/***********************************************************************/

typedef struct                    /* Definition of structure  */
         {                        /* of io status block       */
         short cond_value;        /* Word length condition value */
         short count;             /* No of bytes of data transfered */
         int info;                /* Device specific information */
         } io_statblk;
/***********************************************************************/
typedef struct                  /* Definition of structure of item list */
         {
         short item_length;
         short item_code;
         int item_value;
         } p2_param_item;
/***********************************************************************/

p2_param_item p2_list = {       /* Initialising item list */
                        6,
                        dll$K_PROTOCOLID,
                        0x0103
                        };
int p2_desc[2]      =   {       /* Definition of P2 */
                         6,     /* descriptor of item list  */
                         &p2_list
                        };
int status;
int message_no = 0;
int i = 0;              /* loop count for write */
short assgnd_chan;
io_statblk   iosb,iosb2,iosb3,iosb4;
char secstr[12];
/**************************************************
*              MAIN ROUTINE                      *
**************************************************/
main()
{
      $DESCRIPTOR (terminal, "wan0:");
      $DESCRIPTOR (datalink, "HDLC.HDLCL1.LS2");
/*****************************************
*   ASSIGN A CHANNEL FOR QIO         *
*****************************************/
      if (((status = SYS$ASSIGN(&terminal, &assgnd_chan, 0, 0)) & 1) != 1)
           LIB$STOP( status);
/*****************************************
*   OPEN A PORT                       *
*****************************************/
      if (((status = SYS$QIOW( 0, assgnd_chan, (IO$_CREATE),
                      &iosb,0,0,&datalink,&p2_desc,0,0,0,0 )) & 1) != 1)
           LIB$STOP( status);
/*****************************************
*   START THE DATALINK PROTOCOL *
*****************************************/
      if (((status = SYS$QIOW( 0, assgnd_chan, (IO$_SETMODE | IO$M_STARTUP),
                      &iosb2,0,0,0,0,0,0,0,0 )) & 1) != 1)
           LIB$STOP( status);
/*****************************************
*   ENABLE ATTENTION AST             *
*****************************************/
      if (((status = SYS$QIOW( 0, assgnd_chan, (IO$_SETMODE | IO$M_ATTNAST),
                      &iosb3,0,0,ATT_AST,200,0,0,0,0 )) & 1) != 1)
           LIB$STOP( status);
/*****************************************
*   WRITE DATA                       *
*****************************************/

      for (i = 0; i < 20; i++) {
           sprintf(secstr,"MESSAGE %03d",i);
           if (((status = SYS$QIOW(0, assgnd_chan, IO$_WRITEVBLK, &iosb4, 0,
                          0, secstr, sizeof(secstr)-1,0, 32,0, 0)) & 1) != 1)
                 LIB$STOP( status);
           if (iosb4.cond_value != 1) {
               LIB$STOP (iosb4.cond_value);
               printf("Write not successful\n");
           }
     }
}
/*************** End of main ***************************/
 
/**********************************************************************
*  Attention Asynchronous System Trap routine                         *
***********************************************************************/
void ATT_AST(long status)
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  Attention Asynchronous System Trap routine called when an
**  attention AST is posted
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES:
**
**  none
**
**  SIDE EFFECTS:
**
**  none
**
**--
**/
{
        if ((status && dll$m_sts_active) == 1 )
             printf("LINK IS UP\n");
        else
             printf("LINK IS DOWN");
        if ((status && dll$m_sts_receive_data_ready) == 0)
             printf("There is received data waiting to be read\n");
        else
            ;
        if ((status && dll$m_sts_physical_loopback) == 0)
             printf("Data is looping back at the physical layer\n");
        else
            ;
        if ((status && dll$m_err_remote_restart) == 0)
             printf("The remote station is restarting\n");
        else
            ;
        if ((status && dll$m_err_insuff_resources) == 0)
             printf("There are insufficient system resources to provide the service called\n");
        else
            ;
        if ((status && dll$m_err_physical_layer_down) == 0)
             printf("The DECnet/OSI physical layer is not available\n");
        else
            ;
        if ((status && dll$m_err_negotiation_failure) == 0)
             printf("There has been a negotiation failure\n");
        else
            ;
        if ((status && dll$m_err_maintenance_mode) == 0) printf("The modem has been set to maintenance mode\n");
        else
            ;
        if ((status && dll$m_err_disabled) == 0)
             printf("The device is disabled\n");
        else
            ;
        if ((status && dll$m_err_threshold_exceeded) == 0)
             printf("A system resource has been exceeded\n");
        else
            ;
/*****************************************
*   RE-ENABLE ATTENTION AST *
*****************************************/
        if (((status = SYS$QIOW( 0, assgnd_chan, (IO$_SETMODE | IO$M_ATTNAST),
                       &iosb3,0,0,ATT_AST,200,0,0,0,0 )) & 1) != 1)
           LIB$STOP( status);
}
/********** End of ATT_AST routine *****************************/
/**********************************************************************/
/*  END OF PROGRAMME                                             */
/**********************************************************************/

/*
**
** INCLUDE FILES
**
**/

#include  <stdio.h>
#include <starlet.h>
#include iodef
#include descrip
#include ssdef
#include "xmdef.h"
#include "nmadef.h"
#include "dl_external.h"
#include "dll_external.h"
** INCLUDE FILES
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  This program sends data to a device using the WANdriver interface
**  to the DECnet/OSI datalinks
**  The program requires the HDLC module with link name ’HDLCL1’ and
**  logical station name ’LS2’.
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES
**
**  Success/Fail codes
**
**
**  SIDE EFFECTS:
**
**  none
**--
**/
void ATT_AST(long status);  /* Function declarations */
void ast(char *string);
/***********************************************************************/

typedef struct                    /* Definition of structure  */
         {                        /* of io status block       */
         short cond_value;        /* Word length condition value  */
         short count;             /* No of bytes of data transfered  */
         int info;                /* Device specific information  */
         } io_statblk;
typedef struct                    /* Definition of structure of item list */
         {
         short item_length;
         short item_code;
         int item_value;
         } p2_param_item;
/***********************************************************************/
p2_param_item p2_list = {
                        6,
                        dll$K_PROTOCOLID,
                        0x0103
                        };
int p2_desc[2] = {                 /* Definition of P2 */
                  6,               /* descriptor of item list   */
                  &p2_list
                 };
int i = 0;
int status;
short assgnd_chan;
io_statblk iosb,iosb2,iosb3,iosb4;
char secstr[12];
/**************************************************
*   MAIN ROUTINE                               *
**************************************************/
main()
{
      $DESCRIPTOR (pseudo_driver, "wan0:");
      $DESCRIPTOR (datalink, "HDLC.HDLCL1.LS2");
/*****************************************
*   ASSIGN A CHANNEL FOR QIO         *
*****************************************/
      if (((status = SYS$ASSIGN(&pseudo_driver, &assgnd_chan, 0, 0)) & 1) != 1)
            LIB$STOP( status);
/*****************************************
*   OPEN A PORT                       *
*****************************************/
      if (((status = SYS$QIOW( 0, assgnd_chan, (IO$_CREATE),
                     &iosb2,0,0,&datalink,&p2_desc,0,0,0,0 )) & 1) != 1)
            LIB$STOP( status);
/*****************************************
*   START THE DATALINK PROTOCOL *
*****************************************/
      if (((status = SYS$QIOW( 0, assgnd_chan, (IO$_SETMODE | IO$M_STARTUP),
                     &iosb3,0,0,0,0,0,0,0,0 )) & 1) != 1)
            LIB$STOP( status);
/*****************************************
*   ENABLE ATTENTION AST              *
*****************************************/
if (((status = SYS$QIOW( 0, assgnd_chan, (IO$_SETMODE | IO$M_ATTNAST), &iosb,0,0,ATT_AST,200,0,0,0,0 )) & 1) != 1)
LIB$STOP( status);
/*****************************************
*   READ DATA   *
*****************************************/
      if (((status = SYS$QIO(0, assgnd_chan, IO$_READVBLK, &iosb4, ast, secstr,
                     secstr, sizeof(secstr)-1,0, 0,0, 0)) & 1) != 1)
            LIB$STOP( status);
     SYS$HIBER();
}
/********** End of MAIN **********************************************/
/**********************************************************************
*  Attention Asynchronous System Trap routine                         *
***********************************************************************/
void ATT_AST(long status)
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  Attention Asynchronous System Trap routine called when an
**  attention AST is posted
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES:
**
**  none
**
**  SIDE EFFECTS:
**
**  none
**
**--
**/
{
        if ((status && dll$m_sts_active) == 1 )
             printf("LINK IS UP\n");
        else
             printf("LINK IS DOWN");
        if ((status && dll$m_sts_receive_data_ready) == 0)
             printf("There is received data waiting to be read\n");
        else
            ;
        if ((status && dll$m_sts_physical_loopback) == 0)
             printf("Data is looping back at the physical layer\n");
        else
            ;
        if ((status && dll$m_err_remote_restart) == 0)
             printf("The remote station is restarting\n");
        else
            ;
        if ((status && dll$m_err_insuff_resources) == 0)
             printf("There are insufficient system resources to provide the
  service called\n");
        else
            ;
        if ((status && dll$m_err_physical_layer_down) == 0)
             printf("The DECnet/OSI physical layer is not available\n");
        else
            ;
        if ((status && dll$m_err_negotiation_failure) == 0)
             printf("There has been a negotiation failure\n");
        else
            ;
        if ((status && dll$m_err_maintenance_mode) == 0)
             printf("The modem has been set to maintenance mode\n");
        else
            ;
        if ((status && dll$m_err_disabled) == 0)
             printf("The device is disabled\n");
        else
            ;
        if ((status && dll$m_err_threshold_exceeded) == 0)
             printf("A system resource has been exceeded\n");
        else
            ;
/*****************************************
*   RE-ENABLE ATTENTION AST           *
*****************************************/
        if (((status = SYS$QIOW( 0, assgnd_chan, (IO$_SETMODE | IO$M_ATTNAST),
                       &iosb3,0,0,ATT_AST,200,0,0,0,0 )) & 1) != 1)
              LIB$STOP( status);
}
/********** End of ATT_AST routine *****************************/
/**********************************************************************
*  Asynchronous System Trap routine                                   *
***********************************************************************/
void ast(char *strng)
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  Asynchronous System Trap routine called when an AST is posted
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES:
**
**  none
**
**  SIDE EFFECTS:
**
**  none
**
**--
**/
{
    i++;
    printf("Received data is: %s\n",strng);
/*****************************************
*   RE-ISSUE READ                     *
*****************************************/
        if (iosb4.cond_value != 1) {
            LIB$STOP (iosb4.cond_value);
            printf("Device write not successful\n");
}
        if (((status = SYS$QIO(0, assgnd_chan, IO$_READVBLK, &iosb4, ast, secstr,
               secstr, sizeof(secstr)-1,0, 0,0, 0)) & 1) != 1)
              LIB$STOP( status);
        if (i == 20) {
            SYS$WAKE();
            exit();
        }
}
/******************** End of AST routine ****************************/
/**********************************************************************/
/*  END OF PROGRAMME                                              */
/**********************************************************************/

/*
**
** INCLUDE FILES
**
**/

#include    <stdio.h>
#include    iodef
#include    descrip
#include    ssdef
#include    "xmdef.h"
#include    "nmadef.h"
#define MAX_SIZE    1030
#define DST32_DEVICE   0
#define DMB32_DEVICE   1
#define DMF32_DEVICE   2
#define DSH32_DEVICE...3
#define DSB32_DEVICE   4
#define DSV11_DEVICE   5
#define DSF32_DEVICE   6
#define DSW_DEVICE   7
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  This program sends data to a device using the QIO interface
**  It is an example of interfacing to the hdlc framing routine
**  and is not meant to provide a reliable datalink between two machines
**
**  FORMAL PARAMETERS:
**
**   Command line parameters: Program name set up as a symbol
**                            e.g prog :== $sys$sysroot:[sysmgr]prog.c
**                            Device name on which program is being run
**                            e.g SJA0:
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES
**
**  Success/Fail codes
**
**
**  SIDE EFFECTS:
**
**  none
**--
**/

void get_device_name(void);     /* Declaration of functions       */
void send_data(void);           /*                                */
/*******************************************************************/
typedef struct                    /* Definition of structure */
              {                   /* of longword (6 bytes)   */
              short int device;
              unsigned char controller;
              unsigned char unit;
              }dev_name;
dev_name string_of_devices[7] = {      /* Initialisation of array */
                                ’si’,  /* of structures */
                                10,
                                1,
    ’xg’,
    10,
    1,
    ’zs’,
    1,
    2,
    ’sl’,
    10,
    2,
    ’sj’,
    5,
    2,
    ’sf’,
    10,
    2,
    ’zt’,
    3,
    2
    };
/*******************************************************************/
typedef struct                     /* Definition of structure  */
         {                         /* of io status block       */
         short cond_value;         /* Word length condition value  */
         short count;              /* No of bytes of data transfered  */
         int info;                 /* Device specific information  */
         } io_statblk;
/***********************************************************************/
typedef struct                     /* Definition of structure  */
         {                         /* of parameter P1          */
         short not_used1;          /* Un-used                  */
         short max_mess_size;      /* Max message size         */
         short characteristics;    /* Defines operational mode of driver */
         short not_used2;          /* Un-used                  */
         } p1_param;            
/**********************************************************************/
typedef struct                     /* definition of structure */
         {                         /* of parameter P2 */
         short int pr_col_mode;    /* Protocol identifier */
         int pr_col_val;           /* Protocol value */
         short int dev_mode;       /* Device mode */
         int dev_value;            /* Associated mode value */
         short int cloc_gen;       /* Internal clock mode */
         int cloc_val;             /* Associated clockvalue */
         short int full_dup;       /* Full-duplex mode */
         int dup_val;              /* Associated mode value */
         short int buf_nums;       /* No of receive buffers */
         int buf_val;              /* Associated number */
         short int max_tr_rec;     /* Max transmit $ Receive size */
         int max_tr_rec_val;       /* Value */
         short int num_synchar;    /* Number of synch characters */
         int synchar_val;          /* Value */
         short int encod_tech;     /* Encoding Technique */
         int tech_val;             /* Associated value */
         short int clock_speed;    /* Clock speed */
         int speed_val;            /* Value */
         } p2_param;            
/********************************************************************/
p2_param    p2 = {                         /* initialisation of P2 */
                      NMA$C_PCLI_PRO, NMA$C_LINPR_LAPB, /* p2 buffer */
                      NMA$C_PCLI_CON, NMA$C_LINCN_NOR,
                      NMA$C_PCLI_CLO, NMA$C_LINCL_EXT,
                      NMA$C_PCLI_DUP, NMA$C_DPX_FUL,
                      NMA$C_PCLI_BFN, 4,
                      NMA$C_PCLI_BUS, MAX_SIZE,
                      NMA$C_PCLI_NMS, 6,
                      NMA$C_PCLI_NRZI, NMA$C_STATE_OFF,
                      NMA$C_PCLI_LNS, 19200
                 };
io_statblk  iosb,iosb2,iosb3;       /* I/O status blocks              */
int status;                         /* holds status return value      */
short assgnd_chan;                  /* Holds channel number returned  */
                                    /* from SYS$ASSIGN                */
char str1[2] = ":",str2[6],str3[9]; /* General purpose strings       */
int device_flag = -1;
int number_of_devices = 7;
short int *input_arg;               /* Number of command line arguments */
int unit,mat;
unsigned char type_of_device[2],contrl;
int c,l = 0,i = 0;
char message_1[1024] = "This is message 1";       /* Data to be sent */
char message_2[1024] = "This is message 2";
char message_3[1024] = "This is message 3";
char message_4[1024] = "This is message 4";

struct dsc$descriptor_s p2_desc = {           /* Definition of P2 */
                                  sizeof(p2), /* descriptor */
                                  DSC$K_DTYPE_T,
                                  DSC$K_CLASS_S,
                                  &p2
                                  };
/**************************************************
*        MAIN ROUTINE                             *
**************************************************/
main(int argc, char *argv[])
{
     $DESCRIPTOR (terminal, str3);           /* Defines devic */
     for ( i=1; i<1023; i++) message_1[i]=66;
     mat=sscanf(argv[1], "%2c%c%d", &type_of_device, &contrl, &unit);
     sprintf(str3,"%c%c%c%d:",type_of_device[0],type_of_device[1],
             contrl,unit);
     terminal.dsc$w_length = strlen(str3);
     get_device_name();  /* Obtain name of device over which program */
                         /* is to be run */
/*****************************************
*      ASSIGN A CHANNEL FOR QIO         *
*****************************************/
     if (((status = SYS$ASSIGN(&terminal, &assgnd_chan, 0, 0)) & 1) != 1)
           LIB$STOP( status);
/****************************************
*     SHUT DOWN OF CONTROLLER           *
****************************************/
     if (((status =
           SYS$QIOW(0,assgnd_chan,(IO$_SETMODE|IO$M_CTRL|IO$M_SHUTDOWN),
           &iosb,0,0,0,0,0,0,0,0 )) & 1) != 1)
           LIB$STOP( status);
     if (iosb.cond_value != 1) {
         printf("Shutdown not successful\n");
         LIB$STOP (iosb.cond_value);
     }
/******************************************
*      START UP OF CONTROLLER             *
******************************************/
     if (((status =
           SYS$QIOW(0,assgnd_chan,(IO$_SETMODE|IO$M_CTRL|IO$M_STARTUP),
           &iosb,0,0,0,&p2_desc,4,0,0,0)) & 1) != 1)
           LIB$STOP( status);
     if (iosb.cond_value != 1) {               /* Check for success */
         printf("Physical layer startup not successful\n");
         LIB$STOP (iosb.cond_value);
     }
     send_data();     /* Transmit data */
}
/************** End of main ***********************************/
/**************************************************************
*         FUNCTION get_device_name                           *
**************************************************************/
void get_device_name(void)
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  This function obtains the name of the device and sets the
**  appropriate flag. It also rejects invalid inputs
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  sets variable ’device_flag’
**
**  COMPLETION CODES:
**
**  none
**
**  SIDE EFFECTS:
**
**  none
**
**--
**/
{
input_arg = type_of_device;
for (i = 0; i < number_of_devices; i++) {
     if (string_of_devices[i].device == *input_arg) {
         if ((contrl >= ’a’) &&
  (contrl < (’a’+ string_of_devices[i].controller))) {
             if ((unit >= 0) && (unit < string_of_devices[i].unit)) {
                  device_flag = i;
                  break;
             }
             else {
                  printf("Invalid device unit\n");
                  break;
             }
         }
         else {
              printf("Invalid device controller\n");
              break;
         }
   }
   else if (i == (number_of_devices-1))
            printf("Invalid device name\n");
 }
if (device_flag >= 0) {
    switch(device_flag) {
           case 0: device_flag = DMB32_DEVICE;
                   break;
           case 1: device_flag = DMF32_DEVICE;
                   break;
           case 2: device_flag = DST32_DEVICE;
                   break;
           case 3: device_flag = DSB32_DEVICE;
                   break;
           case 4: device_flag = DSV11_DEVICE;
                   break;
           case 5: device_flag = DSF32_DEVICE;
                   break;
           case 6: device_flag = DSW_DEVICE;
                   break;
                  }
              }
              else
                  exit();
}
/*********** End of function get_device_name ***************/
/***********************************************************
*        FUNCTION SEND_DATA                                *
************************************************************/
void send_data(void)
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  This function writes data to a device
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES:
**
**  Success/fail code
**
**  SIDE EFFECTS:
**
**  none
**
**--
**/
{
           printf("Sending data: \n");     /* Send Data */
           if (((status = SYS$QIOW(0,assgnd_chan,IO$_WRITEVBLK,&iosb3,0,0,
                          message_1,sizeof(message_1)-1,0,32,0,0))&1) != 1)
                 LIB$STOP(status);
           if (((status = SYS$QIOW(0,assgnd_chan,IO$_WRITEVBLK,&iosb3,0,0,
                          message_2,sizeof(message_2)-1,0,32,0,0))&1) != 1)
                 LIB$STOP(status);
           if (((status = SYS$QIOW(0,assgnd_chan,IO$_WRITEVBLK,&iosb3,0,0,
                          message_3,sizeof(message_3)-1,0,32,0,0))&1) != 1)
                 LIB$STOP(status);
           if (((status = SYS$QIOW(0,assgnd_chan,IO$_WRITEVBLK,&iosb3,0,0,
                          message_4,sizeof(message_4)-1,0,32,0,0))&1) != 1)
                 LIB$STOP(status);
}
/**************** End of function send_data *************************/
/*********************************************************************
*              END OF PROGRAM                                        *
*********************************************************************/

/* 
**
** INCLUDE FILES
**
**/

#include    <stdio.h>
#include    iodef
#include    descrip
#include    ssdef
#include    "xmdef.h"
#include    "nmadef.h"
#define MAX_SIZE    1030
#define DST32_DEVICE   0
#define DMB32_DEVICE   1
#define DMF32_DEVICE   2
#define DSH32_DEVICE...3
#define DSB32_DEVICE   4
#define DSV11_DEVICE   5
#define DSF32_DEVICE   6
#define DSW_DEVICE   7
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  This program sends data from a device using the QIO interface
**  It is an example of interfacing to the hdlc framing routine
**  and is not meant to provide a reliable datalink between two machines
**
**  FORMAL PARAMETERS:
**
**   Command line parameters: Program name set up as a symbol
**                            e.g prog :== $sys$sysroot:[sysmgr]prog.c
**                            Device name on which program is being run
**                            e.g SJA0:
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES
**
**  Success/Fail codes
**
**
**  SIDE EFFECTS:
**
**  none
**--
**/

void ast(char *);            /*                           */ 
void get_device_name(void);  /* Declaration of functions  */ 
void send_data(void);        /*                           */ 
void read_data();            /*                           */ 
/*******************************************************************/
typedef struct               /* Definition of structure */
              {              /* of longword (6 bytes)   */
              short int device;
              unsigned char controller;
              unsigned char unit; 
              }dev_name; 

dev_name string_of_devices[7] = {     /* Initialisation of array */
                                ’si’, /* of structures           */
                                10, 
                                1, 
    ’xg’,
    10,
    1, 
    ’zs’,
    1,
    2,
    ’sl’,
    10,
    2,
    ’sj’,
    5,
    2,
    ’sf’,
    10,
    2,
    ’zt’,
    3,
    2
    };
/*******************************************************************/ 
typedef struct                    /* Definition of structure  */
         {                        /* of io status block       */
         short cond_value;        /* Word length condition value */
         short count;             /* No of bytes of data transfered */
         int info;                /* Device specific information */
         } io_statblk;

/***********************************************************************/ 
typedef struct                    /* Definition of structure */
         {                        /* of parameter P1         */
         short not_used1;         /* Un-used                 */
         short max_mess_size;     /* Max message size        */
         short characteristics;   /* Defines operational mode of driver */
         short not_used2;         /* Un-used                 */ 
         } p1_param; 
/**********************************************************************/
typedef struct                    /* definition of structure */
         {                        /* of parameter P2         */
         short int pr_col_mode;   /* Protocol identifier     */
         int pr_col_val;          /* Protocol value          */
         short int dev_mode;      /* Device mode             */
         int dev_value;           /* Associated mode value   */
         short int cloc_gen;      /* Internal clock mode     */
         int cloc_val;            /* Associated clockvalue   */
         short int full_dup;      /* Full-duplex mode        */
         int dup_val;             /* Associated mode value   */
         short int buf_nums;      /* No of receive buffers   */
         int buf_val;             /* Associated number       */
         short int max_tr_rec;    /* Max transmit $ Receive size */
         int max_tr_rec_val;      /* Value                       */
         short int num_synchar;   /* Number of synch characters  */
         int synchar_val;         /* Value                       */
         short int encod_tech;    /* Encoding Technique          */
         int tech_val;            /* Associated value            */
         short int clock_speed;   /* Clock speed                 */
         int speed_val;           /* Value                       */
         } p2_param; 
/********************************************************************/
p2_param       p2 = {                          /* initialisation of P2 */
                         NMA$C_PCLI_PRO, NMA$C_LINPR_LAPB, /* p2 buffer */
                         NMA$C_PCLI_CON, NMA$C_LINCN_NOR, 
                         NMA$C_PCLI_CLO, NMA$C_LINCL_EXT,
                         NMA$C_PCLI_DUP, NMA$C_DPX_FUL,
                         NMA$C_PCLI_BFN, 4,
                         NMA$C_PCLI_BUS, MAX_SIZE,
                         NMA$C_PCLI_NMS, 6,
                         NMA$C_PCLI_NRZI, NMA$C_STATE_OFF,
                         NMA$C_PCLI_LNS, 19200 
                    };
io_statblk   iosb,iosb2,iosb3;                 /* I/O status blocks */
int status;                                    /* Holds status return value */
short assgnd_chan;                             /* Holds channel number      */ 
                                               /* returned from SYS$ASSIGN */
char str1[2] = ":",str2[6],str3[9],strng[150]; /* General purpose strings */
int device_flag = -1;
int number_of_devices = 7;
short int *input_arg;          /* Number of command line arguments */
int unit,mat;
unsigned char type_of_device[2],contrl;
int c,l = 0,i = 0; 

struct dsc$descriptor_s p2_desc = {            /* Definition of P2 */
                                   sizeof(p2), /* descriptor       */
                                   DSC$K_DTYPE_T, 
                                   DSC$K_CLASS_S, 
                                   &p2 
                                  };
/**************************************************
*         MAIN ROUTINE                            *
**************************************************/
main(int argc, char *argv[])
{
     $DESCRIPTOR (terminal, str3);               /* Defines device */
     mat=sscanf(argv[1], "%2c%c%d", &type_of_device, &contrl, &unit);
     sprintf(str3,"%c%c%c%d:",type_of_device[0],type_of_device[1],
             contrl,unit);
     terminal.dsc$w_length = strlen(str3);
     get_device_name();                       /* Obtain name of device over */
                                              /* which program is to be run*/
/*****************************************
*       ASSIGN A CHANNEL FOR QIO          *
*****************************************/
     if (((status = SYS$ASSIGN(&terminal, &assgnd_chan, 0, 0)) & 1) != 1)
           LIB$STOP( status);
/****************************************
*   SHUT DOWN OF CONTROLER              *
****************************************/
     if (((status = SYS$QIOW( 0, assgnd_chan, 
                              (IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN),
                              &iosb,0,0,0,0,0,0,0,0 )) & 1) != 1)
           LIB$STOP( status);
     if (iosb.cond_value != 1) {
         printf("Shutdown not successful\n");
         LIB$STOP (iosb.cond_value); 
} 
/******************************************
*   START UP OF CONTROLLER                 *
******************************************/
     if (((status = SYS$QIOW(0, assgnd_chan,
                             (IO$_SETMODE|IO$M_CTRL|IO$M_STARTUP),
                             &iosb,0,0,0,&p2_desc,4,0,0,0)) & 1) != 1)
           LIB$STOP( status);
     if (iosb.cond_value != 1) {              /* Check for success */
         printf("Physical layer startup not successful\n");
         LIB$STOP (iosb.cond_value);
     }
     read_data();      /* Read data from device */
}
/************ END OF MAIN ************************************/

/**********************************************************************
*  Asynchronous System Trap routine                                   *
***********************************************************************/
void ast(char *strng)
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  Asynchronous System Trap routine called when an AST is posted
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES:
**
**  none
**
**  SIDE EFFECTS:
**
**  none
**
**--
**/
{
    printf("Received data is: %s\n",strng);
}
/******************** End of AST routine ****************************/ 

/************************************************************** 
*          FUNCTION get_device_name                            *
**************************************************************/ 
void get_device_name(void)
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  This function obtains the name of the device and sets the
        appropriate flag. It also rejects invalid inputs 
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  sets variable ’device_flag’
**
**  COMPLETION CODES:
**
**  none
**
**  SIDE EFFECTS:
**
**  none
**
**--
**/
{
    input_arg = type_of_device;
    for (i = 0; i < number_of_devices; i++) {
         if (string_of_devices[i].device == *input_arg) {
             if ((contrl >= ’a’) &&
     (contrl < (’a’+ string_of_devices[i].controller))) {
                if ((unit >= 0) && (unit < string_of_devices[i].unit)) {
                     device_flag = i;
                     break;
                }
                else {
                     printf("Invalid device unit\n");
                     break;
                } 
           }
           else {
                printf("Invalid device controller\n");
                break;
           }
        }
        else if (i == (number_of_devices-1))
                 printf("Invalid device name\n");
}
        if (device_flag >= 0) {
            switch(device_flag) {
                   case 0: device_flag = DMB32_DEVICE;
                           break;
                   case 1: device_flag = DMF32_DEVICE;
                    break;
            case 2: device_flag = DST32_DEVICE;
                    break;
                  case 3: device_flag = DSB32_DEVICE;
                    break;
            case 4: device_flag = DSV11_DEVICE;
                    break;
            case 5: device_flag = DSF32_DEVICE;
                    break;
            case 6: device_flag = DSW_DEVICE;
                    break;
                   }
               }
               else
                   exit();
}
/*********** End of function get_device_name ***************/

/***********************************************************
*            FUNCTION READ_DATA                             *
*************************************************************/
void read_data(void) 
/*
**++
**  FUNCTIONAL DESCRIPTION:
**
**  This function reads data from a device
**
**  FORMAL PARAMETERS:
**
**  none
**
**  IMPLICIT INPUTS:
**
**  none
**
**  IMPLICIT OUTPUTS:
**
**  none
**
**  COMPLETION CODES:
**
**  Success/fail code
**
**  SIDE EFFECTS:
**
**  none
**
**--
**/
{

               /*   Read Data   */
           if (((status = SYS$QIOW(0,assgnd_chan,IO$_READVBLK,&iosb2,
                          ast,strng,strng,sizeof(strng)-1,0,0,0,0))&1) != 1)
                 LIB$STOP(status);

 
           if (((status = SYS$QIOW(0,assgnd_chan,IO$_READVBLK,&iosb2,
                          ast,strng,strng,sizeof(strng)-1,0,0,0,0))&1) != 1)
                 LIB$STOP(status);
           if (((status = SYS$QIOW(0,assgnd_chan,IO$_READVBLK,&iosb2,
                          ast,strng,strng,sizeof(strng)-1,0,0,0,0))&1) != 1)
                 LIB$STOP(status);
           if (((status = SYS$QIOW(0,assgnd_chan,IO$_READVBLK,&iosb2,
                          ast,strng,strng,sizeof(strng)-1,0,0,0,0))&1) != 1)
                 LIB$STOP(status);
}
/**************** End of function read_data *************************/

/*********************************************************************
*                END OF PROGRAM                                      *
*********************************************************************/

 

This function sets and (optionally) starts the drivers. For DDCMP operation, both the drivers and the DDCMP protocol must be initialized and started. See Section Section D.3.2, ''Set DDCMP Mode'' for instructions on starting the DDCMP protocol.

VMS provides four combinations of function code and modifier:

If the modifier IO$M_STARTUP is specified, the driver is started and the modem is enabled. If IO$M_STARTUP is not specified, the driver characteristics are simply modified.

The parameters for the function codes are:

Note that if both the P1 and P2 parameters are specified, the P2 parameter values supersede the P1 parameter values. The P2 parameter NMA$C_PCLI_ BFN (see Table D.3, ''P2 Extended Characteristics Values'') also supersedes any P3 parameter.

Parameters P1, P2, and P3 are described in more detail in Section D.3.1.1, ''P1 Parameter'', Section D.3.1.2, ''P2 Parameter'', and Section D.3.1.3, ''P3 Parameter''.

D.3.1.1. P1 Parameter

P1 is the virtual address of a quadword characteristics buffer. This parameter is used only for DDCMP. Figure D.1, ''P1 Characteristics Buffer (Set Controller)'' shows the format of this buffer.

The second word of the first longword (‘maximum message size’) holds the maximum length for transmitted and received messages.

The first word of the second longword (‘characteristics’) defines the operational mode of the driver.

Table D.2, ''Driver Characteristics'' lists the driver characteristics that can be set in the second longword. The $XMDEF macro defines these values.

Characteristic	Meaning
XM$M_CHR_LOOPB	Sets loopback mode
XM$M_CHR_HDPLX	Sets half-duplex operation

D.3.1.2. P2 Parameter

P2 is optional. It is the address of a descriptor that defines an extended characteristics buffer.

The extended characteristics buffer that P2 points to consists of a series of 6-byte entries. The first word contains the parameter identifier (ID), and the longword that follows contains a value that can be associated with that parameter ID. Figure D.2, ''P2 Extended Characteristics Buffer'' shows the format of this buffer.

Table D.3, ''P2 Extended Characteristics Values'' shows the parameter IDs and possible values that can be specified in the P2 buffer (the notes referred to are at the end of the table). The $NMADEF macro defines these values.

Parameter ID	Meaning
NMA$C_PCLI_PRO	Protocol mode. The following values can be specified:
	NMA$C_LINPR_POI NMA$C_LINPR_BISYNC NMA$C_LINPR_BSY NMA$C_LINPR_LAPB NMA$C_LINPR_LAPBE NMA$C_LINPR_SDLC NMA$C_LINPR_SWIFT NMA$C_LINPR_CHIPS	DDCMP point-to-point (default) IBM bisynchronous protocol (see Note 1 GENBYTE operation (see Note 2) HDLC operation (LAPB) HDLC operation (LAPBE) SDLC bit stuff mode SWIFT BISYNC variant - DSF32 only CHIPS BISYNC variant - DSF32 only
NMA$C_PCLI_DUP	Duplex mode (see Note 3 for defaults). The following values can be specified:
	NMA$C_DPX_FUL	Full-duplex Half-duplex (see Section D.2, ''Write'')
NMA$C_PCLI_CON	Device mode. The following values can be specified:
	NMA$C_LINCN_NOR NMA$C_LINCN_LOO	Normal (default) Loopback
NMA$C_PCLI_BFN	Number of Receive buffers to preallocate (minimum = 1; for defaults, see Note 5). May be provided here or as P3 argument (see Section D.3.1.3, ''P3 Parameter''). If included, supersedes the P3 argument.
NMA$C_PCLI_BUS	Maximum Transmit and Receive message length (for defaults and maximum values, see Note 6).
NMA$C_PCLI_NMS	Number of sync characters to precede message. The number used is protocol-dependent (default = 8).
NMA$C_PCLI_CODE	Character code used for IBM bisynchronous protocol. See Note 7.
NMA$C_PCLI_CRC	Type of CRC. The following values can be specified:
	0	CRC–CCITT preset to 1s
	1	CRC–CCITT preset to 0s
	2	LRC/VRC odd
	3	CRC–16
	4	VRC odd
	5	VRC even
	6	LRC/VRC even
	7	Nor error control
	For defaults and possible values, see Note 8.
NMA$C_PCLI_NRZI	Data encoding technique. The following values can be specified:
	NMA$C_STATE_OFF NMA$C_STATE_ON	NRZ encoding (default) NRZI encoding
NMA$C_PCLI_CLO	Controls generation of a clock signal. The following values can be specified (see Note 9):
	NMA$C_LINCL_EXT NMA$C_LINCL_INT	Clock signal disabled (default) Clock signal enabled
NMA$C_PCLI_LNS	Controls the speed of the clock signal enabled by NMA$C_PCLI_CLO. Values vary according to the device concerned.
NMA$C_PCLI_RTT	Retransmit timer for full-duplex point-to-point mode and selection timer for half-duplex point-to-point mode. DDCMP only. Specify time in milliseconds (default = 3000).
NMA$C_PCLI_TRI	Tributary mode address. Values in the range 0 to 255 are valid. Value 255 represents the multicast address and, when specified, will only allow reception of frames with an address of 255. If SDLC is operating, tributary mode is set automatically.

Notes:

1. BISYNC is supported by the DSV11, DPV11, DUP11, DMB32, DMF32, DSF32, DSH32, DST32, DSW21, DSW41, and DSW42.

2. GENBYTE is supported by the DMF32, DMB32, DPV, and DUP only.

3. The default duplex mode for each protocol is:
   

   • DDCMP-Full-duplex
   • DDCMP-Full-duplex
   • HDLC-Full-duplex (no half-duplex mode with HDLC)
   • SDLC-Half-duplex
   • BISYNC-Half-duplex

4. Default number of buffers allocated:

   • DDCMP-4
   • HDLC-6
   • SDLC-4
   • BISYNC-2

5. Default message length (in bytes):

   • DDCMP-576
   • HDLC-128
   • SDLC-280
   • BISYNC-280

   Maximum message length (in bytes)

   • DDCMP-4096
   • HDLC-4106
   • SDLC-4106
   • BISYNC-4106
6. Indicate EBCDIC character coding for the DSV11 using the value NMA$C_ CODE_EBCDIC. For the DUP11, the DPV11, the DMB32, the DMF32, and the DSF32, the following values can be specified:
   

   Value	Meaning
   NMA$C_CODE_ASCII	ASCII character code
   NMA$C_CODE_EBCDIC	EBCDIC character code (default)

7. Default values and possible values for the CRC depend on the line protocol:
   

   • DDCMP: CRC–16 only
   • HDLC: CRC-CCITT preset to 1s only
   • SDLC: CRC-CCITT preset to 1s only
   • BISYNC: CRC-16 only
   • GENBYTE: None

8. Digital recommends that NMA$C_PCLI_CLO be left at its default value. Set the line speed using the NMA$C_PCLI_LNS parameter only when NMA$_ PCLI_CLO sets the internal clock. Setting the line speed with NMA$_PCLI_ LNS when NMA$_PCLI_CLO sets an external clock has no effect on the line speed used by the device. Note that there is no method of obtaining the current value of the line speed parameter.

9. NMA$C_PCLI_LNS controls the speed of the clock signal enabled by NMA$C_ PCLI_CLO. Table D.4, ''Clock Speed Values (hertz)'' lists the values allowed.

   DSB32 Values	DSH32 and DST32 Values	DSF32 Values	DSV11 Values	DSW21, DSW41, and DSW42 Values
   0?	0	0	0	0
   600	600	-	-	-
   1200	1200	1200	-	-
   1800	-	-	-	-
   2000	2000	2000	-	-
   2400	2400	2400	-	-
   4800	4800	4800	-	-
   9600§	9600	9600	9600§	9600
   14400	-	-	-	-
   19200	19200	19200	19200	19200
   -	38400	38400	38400	38400?
   48000	-	-	-	-
   56000	-	-	-	-
   64000	-	-	-	-
   -	-	-	72000	-
   76800	-	-	-	-
   96000	-	-	-	-
   128000	-	-	128000	128000
   -	-	-	256000	256000
   -	-1?	-1	-	-1

The Set DDCMP Mode function allows you to set and start the DDCMP protocol. Specifically, the information in this section explains how you set up DDCMP circuit parameters (hence, the parameter ID codes described contains the PCCI identifier).

Four combinations of function doe and modifier are provided:

These codes take the following arguments:

The following characteristic can be set in the second longword of the P1 Characteristics Buffer:

XM$V_CHR_MOP – set DDCMP to maintenance mode

The P2 buffer consists of a series of 6-byte entries. The first word contains the parameter identifier (ID), and the longword that follows contains one of the values that can be associated with the parameter ID. Figure D.2, ''P2 Extended Characteristics Buffer'' shows the format for this buffer.

Table D.5, ''P2 Extended Characteristics Values'' lists the parameter IDs and values that can be specified in the P2 buffer.

If both P1 and P2 characteristics are specified, the P2 characteristics supersede the P1 characteristics.

On receipt of the QIO request for a device, the driver starts the protocol.

This function ends driver operations and halts the protocol and the line. To restart the driver, issue a IO$_SETMODE!IO$M_CTRL!IO$M_STARTUP or IO$_SETCHAR!IO$M_CTRL!IO$M_STARTUP request (see Section D.3.1, ''Set Controller Mode'').

Note that the defaults are not reset on shutdown, but only on DEASSIGN. The WAN Device Drivers use their previous settings on a restart after a shutdown. To change the settings after a shutdown, use the P2 parameter as described in Section Section D.3.1.2, ''P2 Parameter''.

VMS provides two combinations of function code and modifier:

This function halts the DDCMP protocol. The attached device cannot be used until DDCMP is restarted.

VMS provides two combinations of function code and modifier:

These codes take no arguments.

This function requests that an attention AST is delivered to the requesting process after one of the following events:

All outstanding attention ASTs are delivered after one of these events.

You may use the Enable Attention AST function at any time after the line is started, regardless of the condition of the driver and line status bits.

VMS provides two combinations of function code and modifier:

The parameters for the two function codes are:

After an AST occurs, it must be reenabled by another Enable Attention AST function before an AST can occur again. Note that the AST quota (ASTLM) for your process limits how many ASTs can be requested.

The HDLC, SDLC, BISYNC and GENBYTE protocols do not have the concept of line and circuit. Therefore, only $QIO requests that include the function modifier IO$M_CTRL are allowed. VMS does not acknowledge the characteristics set in either P1 or P3 for this mode of operation.

Note that you must have CMKRNL privilege to run either the DMF32 or the DMB32 in GENBYTE mode.

For HDLC and SDLC, an IO$_CLEAN function stops all outstanding Transmits. In both cases, the status return is SS$_ABORT. Use of IO$_CLEAN does not affect any modem signals.

The driver characteristic bits govern the DDCMP operating mode. These bits are defined by the $XMDEF macro and can be set using a Set Mode function or read by a Sense Mode function).

Table D.12, ''DSB32, DSF32, DSH32, DST32, DSV11, DSW21, DSW41, and DSW42 Driver Characteristics'' lists the values and meanings of the driver characteristics.

These bits show the status of the driver and of the line. Set or clear these bits only when the driver and the circuit are inactive.

Table D.13, ''DSB32, DSF32, DSH32, DST32, DSV11, DSW21, DSW41, and DSW42 Device and Line Status'' lists the status values and their meanings. The values are defined by the $XMDEF macro.

The driver error summary bits are set when an error occurs. They are read-only bits. Errors (other than XM$M_ERR_LOST) cause shutdown of the DDCMP circuit. The circuit needs to be restarted.

Table D.14, ''DSB32, DSF32, DSH32, DST32, DSV11, DSW21, DSW41 and DSW42 Error Summary'' lists the error values and their meanings.

Previous versions of the WAN Device Drivers were independent of DECnet: it was possible to run them without running DECnet. DECnet did not need to be involved with the drivers, although in many networks, DECnet ran over WAN Device Drivers links provided by previous versions of the WAN Device Drivers.

The generic WAN Device Drivers are integrated with DECnet. For WAN Device Drivers to run, you need only install and configure DECnet/OSI.

The ADD command allows you to add one or two physical controllers to a failover set. Your quadword buffer must contain one entry only, detailing which physical controllers to add. Figure F.1, ''Format of Quadword Buffer'' shows the format of the quadword buffer.

The Code byte takes the following values:

Use the Controller 1 and Controller 2 bytes to specify the physical controller you are adding to the failover set. When you are adding only one physical controller, the Controller 2 byte is ignored.

Use the following constants in the Controller 1 or the Controller 2 byte to specify the physical controller:

If the failover set is not empty, the SFDRIVER will ensure that only one physical controller can be added. If the failover set is already full, the SFDRIVER will reject your command. The SFDRIVER will return an invalid quadword buffer format error if any other values are found in the buffer.

The REMOVE command allows you to remove one or two members from a failover set. The buffer must contain one entry, detailing which physical controllers you wish removed. The format of the quadword buffer is the same as shown in Figure F.1, ''Format of Quadword Buffer''.

The Code byte takes the following values:

Use the Controller 1 and Controller 2 bytes to specify the physical controller you are removing from the failover set. When you are removing only one physical controller, the Controller 2 byte is ignored.

Use the following constants in the Controller 1 or the Controller 2 byte to specify the physical controller:

The SET/CURRENT command allows you to change which physical controller is currently active in a failover set. The SET/CURRENT command causes a manual failover of the failover set from one physical controller to the one specified in your buffer. Figure F.2, ''Format of Individual SET/CURRENT Entry'' shows the format of the SET/CURRENT entry. Figure F.2, ''Format of Individual SET/CURRENT Entry'' shows the format of the SET/CURRENT entry.

The Code byte must contain the value DSF$K_ITEM_PC.

The New Controller byte must indicate a valid physical controller: that is, one made a member of the failover set by a previous ADD command. If the New Controller byte does not indicate a valid physical controller, the SFDRIVER returns an invalid buffer error.

Use the following constants in the New Controller byte to specify the new physical controller of the failover set:

The SHOW command allows you to obtain information about the current state of the failover set. This command requires a three longword format item-list. The item-list consists of a series of information entries and is terminated by a longword set to zero. The format of each item-list entry is shown in Figure F.3, ''Format of Individual SHOW Entry''. The programming libraries shipped on the kit supply the structure definitions you require to access the item-list.

The request codes can have the following values:

F.3.4.1. Failover Set State

When you request Failover Set State, the driver returns zero, one, or two longwords of information. The number of nonzero longwords returned tells you the number of members currently in the failover set. The driver will clear any longwords not used, and will not assume they are supplied as zero. The format of each longword is shown in Figure F.4, ''Failover Set State Longword''.

The low byte contains a constant identifying the physical device which is a member of this Failover Set. The state field contains the state of the physical unit. Possible values are listed below:

• DSF$K_STANDBY which means that the physical device is standing by

• DSF$K_CURRENT which means that the physical device is currently the active controller for this Failover Set

• DSF$K_FAILED which means that the physical device is broken

The flags field contains the following flags:

• DSF$M_INIT which means the physical device has completed its initialization successfully

F.3.4.2. Cable State

When Cable State is requested, the driver returns zero, one, or two longwords of information. One longword will be initialised for each current physical member of the failover set. The format of each longword is shown in Figure F.5, ''Cable State Longword''.

The Controller byte contains a constant identifying the physical device to which the cable state information refers.

The 20-pin Partner and 100-pin Partner bytes contain constants identifying the physical devices connected through the 20-pin and 100 pin cables, respectively.

The top byte is split into two 4-bit fields: the 20-pin field and the 100-pin field. The values in these fields indicate the current state of the 20-pin and the 100-pin connections.

For the 20-pin connection, the values are as follows:

• DSF$K_20_GOOD-there is a good connection between the physical device and the partner at the other end of the 20-pin cable.

• DSF$K_20_NONE-there is no 20-pin cable connection (in this case, the 20-pin byte is set to 0).

• DSF$K_20_UNKNOWN-the state of the 20-pin connection is unknown (in this case, the 20-pin byte is set to 0).

For the 100-pin connection, the values are as follows:

• DSF$K_100_GOOD-there is a good connection between the physical device and the partner at the other end of the 100-pin cable.

• DSF$K_100_NONE-there is no 100-pin cable connection (in this case, the 100-pin byte is set to 0).

• DSF$K_100_UNKNOWN-the state of the 100-pin connection is unknown (in this case, the 100-pin byte is set to 0).

F.3.4.3. Failover Set Configuration State

When Failset Configuration State is requested, the driver returns one longword of information in the second longword of the item-list. The format of this longword is shown in Figure F.6, ''Failover Set Configuration State Longword''.

The state field describes the current state of the failover set. Possible values for this field are as follows:

• DSF$K_NULL which means that the failset is empty

• DSF$K_SINGLE which means that the failset contains one physical controller

• DSF$K_PARTNERED which means the failset contains two physical members in separate zones

• DSF$K_INVALID which means the failset state is invalid

The CABLE_CONFIG field describes the driver’s perception of the validity of the physical cabling of the failover set. Possible values which may be returned are shown below:

• DSF$K_GOOD which means the cable configuration is good

• DSF$K_BAD which means the cable configuration is bad

• DSF$K_UNKNOWN which means the cable setup cannot be determined (for example, if one zone is stopped the cable state can not be determined)

The VSI DECnet/OSI for Open VMS Installation and Configuration describes the correct configuration of cables.