              <<< NOTED::NOTES$7:[NOTES$LIBRARY]HACKERS.NOTE;1 >>>
                               -< ** Hackers ** >-
================================================================================
Note 1073.16    Documentation for DECnet NICE or NML$ interface?        16 of 18
XDELTA::HOFFMAN "Steve, OpenVMS Engineering"        445 lines  12-AUG-1996 11:13
                                   -< NICE >-
--------------------------------------------------------------------------------
:    can anyone point me in the appropriate direction to find out the $qio
:incantations when talking to netacp ?

   You're asking for _documentation_ in hackers?  You mean there exists
   something better than the source listings?  :-)

:    I want to be able to perform "set/sho/clear/purge node x" commands from
:a program. I'd really rather not spawn dcl commands to do this, so am looking
:at talking direct to the netacp process.

   The documented -- yes, I know this is hackers -- solution is the use
   of the (specific to DECnet Phase IV) NICE protocol.  Undocumented and
   unsupported solutions include use of the NML interface -- an interface
   that generates NICE packets -- or the use of the DECnet network driver
   IO$_ACPCONTROL interface -- an interface that directly communicates
   with the NETACP. 

   Of the three, I would recommend using NICE.  There are various NICE
   examples in this notes string and over in the DECnet notes conference
   (at BULOVA::DECNETVAX).  I've attached an (old, VAX C) example, too:

$
$!  compile and link the NICE program
$
$ CC NICE/Debug/NoOpt
$ Link NICE,Sys$Input/Opt/Debug
Sys$Share:VAXCRTL/Share
$

	--

/*
**  NICE.C
**  An example program that speaks Phase IV NICE protocol.  This NICE
**  example is basically useless on ADVANTAGE-NETWORKS (DECnet Phase V
**  networks) -- as a different management protocol, MICE, is used.
**
**  Author:
**	Stephen Hoffman (XDELTA::HOFFMAN, STAR::SHOFFMAN)
**	DIGITAL EQUIPMENT CORPORATION, NASHUA, NH
**
**  $
**  $! NICE.COM
**  $
**  $!  compile and link the NICE program
**  $
**  $ CC NICE/Debug/NoOpt
**  $ Link NICE,Sys$Input/Opt/Debug
**  Sys$Share:VAXCRTL/Share
**  $
**
**
**  This procedure chats with the Network Management Layer of DECnet
**  to retrieve node information.  It is intended as a learning tool.
**
**  See the Network Mgmt Func Spec, AA-X437A-TK, for the technical
**  details of the NICE protocol.  This functional specification is
**  available online at FILES::NET$ARCH:[APPROVED] or [OBSOLETE].
*/
#include    iodef
#include    ssdef
#include    stsdef
#include    descrip

#define	NICE$K_NICEVER	    4
#define	NICE$K_DECECO	    0
#define	NICE$K_USERECO	    0

/*
**  Return status codes -- found in first byte.
*/
#define NICE$K_SUCCESS	    ((unsigned char) 1)
#define NICE$K_ACCEPTED	    ((unsigned char) 2)
#define NICE$K_PARTIAL	    ((unsigned char) 3)
#define NICE$K_NOPRIV	    ((unsigned char) -3)
#define NICE$K_UNRECCOMP    ((unsigned char) -8)
#define NICE$K_FILEOPENERR  ((unsigned char) -13)
#define NICE$K_OPFAILED	    ((unsigned char) -25)
#define NICE$K_DONE	    ((unsigned char) -128)
#define NICE$K_NOSTATUS	    ((unsigned short int) ~0)

/*
**  entity type number
*/
#define NICE$K_EN_NODE	    0
#define NICE$K_EN_LINE	    1
#define NICE$K_EN_LOGGING   2
#define NICE$K_EN_CIRCUIT   3
#define NICE$K_EN_MODULE    4
#define NICE$K_EN_AREA	    5

/*
**  Node identification stuff
**  if >0 then it's the start of the ASCIC nodename string.
*/
#define	NICE$K_NI_SIGNIFICANT	((unsigned char) -5)
#define	NICE$K_NI_ADJACENT	((unsigned char) -4)
#define	NICE$K_NI_LOOP		((unsigned char) -3)
#define	NICE$K_NI_ACTIVE	((unsigned char) -2)
#define	NICE$K_NI_KNOWN		((unsigned char) -1)
#define	NICE$K_NI_ADDRESS	((unsigned char) 0)
#define	NICE$M_NI_EXECUTOR	((unsigned char) 1 << 7)


/*
** Change Option bitmasks
*/
#define	NICE$M_CO_PERMANENT     (1 << 7)    /* volative if zero */
#define	NICE$M_CO_CLEARPURGE	(1 << 6)    /* set/define if zero */
#define	NICE$M_CO_ENTITYTYPE    (0x07)	    /* entity type field */

/*
**  NICE operation codes.
*/	    
#define NICE$K_OP_WRITE	19
#define NICE$K_OP_READ	20

#define RUNT$S_BUFFER	512
#define	RUNT$S_NCBDATA	17
#define	RUNT$S_CHANNEL	2
main()
    {
    unsigned char *src_node = "VOX";
    unsigned char *trg_node = "XDELTA";
    unsigned char *nodename = "XDELTA";
    unsigned char *nice = calloc( 1, RUNT$S_BUFFER );
    unsigned char *ncb	= calloc( 1, RUNT$S_BUFFER );
    unsigned char *index;
    unsigned long int node16;
    unsigned long int area6;
    unsigned long int number10;
    unsigned long int retstat;
    struct dsc$descriptor dncb =
	{
	0,
	DSC$K_DTYPE_T, DSC$K_CLASS_S,
	ncb
	};
    unsigned short int src_chan;
    unsigned short int trg_chan;
    unsigned short int iosb[4];

    /*
    **	Build the NCB
    */
    strcpy( ncb, src_node );
    strcat( ncb, "::\"NML=/" );

    dncb.dsc$w_length = strlen( ncb );
    ncb[dncb.dsc$w_length++] = 0;
    ncb[dncb.dsc$w_length++] = 0;

    ncb[dncb.dsc$w_length++] = 3;
    ncb[dncb.dsc$w_length++] = NICE$K_NICEVER;
    ncb[dncb.dsc$w_length++] = NICE$K_DECECO;
    ncb[dncb.dsc$w_length++] = NICE$K_USERECO;
    dncb.dsc$w_length = strlen( ncb ) + RUNT$S_CHANNEL + RUNT$S_NCBDATA;
    ncb[dncb.dsc$w_length++] = '\"';

    retstat = SYS$ASSIGN( &dncb, &src_chan, 0, 0 );
    if ( !$VMS_STATUS_SUCCESS( retstat ))
	return( retstat );

    /*
    **	Build a NICE "show node" request
    */
    dncb.dsc$w_length = 0;
    ncb[dncb.dsc$w_length++] = NICE$K_OP_READ;
    ncb[dncb.dsc$w_length++] = 0x0;
    ncb[dncb.dsc$w_length++] = strlen( nodename );
    strcpy( &(ncb[dncb.dsc$w_length]), nodename );
    dncb.dsc$w_length += strlen( nodename );

    retstat = SYS$QIOW( 0, src_chan, IO$_WRITEVBLK, iosb, 0, 0,
	ncb, dncb.dsc$w_length, 0, 0, 0, 0 );

    retstat = SYS$QIOW( 0, src_chan, IO$_READVBLK, iosb, 0, 0,
	ncb, RUNT$S_BUFFER, 0, 0, 0, 0 );

    if ( *ncb != NICE$K_ACCEPTED )
	    return( SS$_ABORT );

    retstat = SYS$QIOW( 0, src_chan, IO$_READVBLK, iosb, 0, 0,
	ncb, RUNT$S_BUFFER, 0, 0, 0, 0 );

    /*
    **	Did we get it?
    */
    if ( *ncb != NICE$K_SUCCESS )
	    return( SS$_ABORT );

    /*
    **	Is the status reasonable?
    */
    if ( *(unsigned short int *) (ncb + 1 ) != NICE$K_NOSTATUS )
	return( SS$_ABORT );

    /*
    **	Now that we've got it, parse it.
    */
    if ( *(unsigned char *)(ncb + 3 ) == NICE$K_NI_ADDRESS )
	{
	node16 = *(unsigned short int*)(ncb + 4);
	area6 = node16 >> 10;

	number10 = node16 & 0x03ff;
	printf("Node _%s:: is at address %d.%d.\n",
	    nodename, area6, number10 );
	}
    else
	return( SS$_ABORT );

    if ( *(unsigned char *)(ncb + 6 ) & NICE$M_NI_EXECUTOR )
	printf("(executor)\n" );

    retstat = SYS$QIOW( 0, src_chan, IO$_READVBLK, iosb, 0, 0,
	ncb, RUNT$S_BUFFER, 0, 0, 0, 0 );

    if ( *ncb != NICE$K_DONE )
	    return( SS$_ABORT );

    retstat = SYS$DASSGN( src_chan );

    return( SS$_NORMAL );

    }

/*
**  == == == == == == == == == == == == == == == == == == == == == == ==
**
**  The following NICE packet traces were obtained by defining the
**  following logical name: 'DEFINE NML$LOG "FF"'  This undocumented
**  logical name causes the NCP utility to enable NICE packet tracing.
**
**  == == == == == == == == == == == == == == == == == == == == == == ==
**
**
**  The following is the result of an NCP "SET NODE 5.775 NAME XDELTA"
**  command...  As seen from the perspective of NML.
**
NICE message received by NML (length = 14 bytes)
00004154 4C454458 0601F417 07008013 	.....�..XDELTA..

				 13	write
                               80	volatile (item class node)
                             00		node address code
                        17 07		the address
                    01F4	        data ID (500, nodename)
                  06			ASCIC nodename count
     4154 4C454458		        "XDELTA"
0000					trash

NICE message transmitted by NML (length = 4 bytes)
00000000 00000000 00000000 00FFFF02 	................

                                 02 	accepted
                             FFFF	no error deatil
00000000 00000000 00000000 00		trash

NICE message transmitted by NML (length = 4 bytes)
00000000 00000000 00000000 00FFFF01 	................

				 01 	success
			     FFFF	no error detail
00000000 00000000 00000000 00		trash

NICE message transmitted by NML (length = 1 bytes)
00000000 00000000 00000000 00000080     ................

                                 80	all done
00000000 00000000 00000000 000000	trash

** **************************************************************************
**
**  The following is the (partial) result of an NCP "SHOW KNOW NODE"
**  command...  Again, as seen from the perspective of NML.
**

NICE message received  (length = 3 bytes)
00000000 00000000 00000000 00FF0014 	................
				 14	show
                               00	show nodes
                             FF		show known nodes
00000000 00000000 00000000 00

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 00FFFF02 	................
                                 02	command accepted
                             FFFF	status
00000000 00000000 00000000 00		extra

NICE message transmitted  (length = 48 bytes)
00640081 0000584F 56831445 00FFFF01 	....E..VOX....d.
2E355620 5841562D 74656E43 45441E40 	@.DECnet-VAX V5.
2032542D 312E3556 20534D56 20202C30 	0,  VMS V5.1-T2 

                                 01	partial response
                             FFFF	status
                           00		address code
                      1445		address value
		    83		        count - bit seven means executor
             584F 56                    node name
00640081 0000                           baggage
2E355620 5841562D 74656E43 45441E40     baggage
2032542D 312E3556 20534D56 20202C30	baggage

NICE message transmitted  (length = 34 bytes)
40033631 3054454E 45060401 00FFFF01 	.......ENET016.@
414C0440 140F02C2 033E302D 414E4205 	.BNA-0>.�...@.LA
00000000 00000000 00000000 00003552 	R5..............

                                 01	partial
                             FFFF	status
                           00		node address code
                      0401		node address value
      31 3054454E 4506                  ASCIC nodename
400336					baggage
414C0440 140F02C2 033E302D 414E4205 	more baggage
00000000 00000000 00000000 00003552 	yet more baggage

NICE message transmitted  (length = 34 bytes)
40033632 3054454E 45060402 00FFFF01 	.......ENET026.@
414C0440 140F02C2 033E302D 414E4205 	.BNA-0>.�...@.LA
00000000 00000000 00000000 00003552 	R5..............

....

NICE message transmitted  (length = 1 bytes)
00000000 00000000 00000000 00000080 	................

                                 80	all done...


Known Node Volatile Summary as of  1-DEC-1988 00:00:31
 
Executor node = 5.69 (VOX)
 
State                    = on
Identification           = DECnet-VAX V5.0,  VMS V5.1-T2

 
    Node           State      Active  Delay   Circuit     Next node
                              Links
 
 1.1 (ENET01)                                 BNA-0         5.15 (LAR5)
 1.2 (ENET02)                                 BNA-0         5.15 (LAR5)

	ad naseum...


** **************************************************************************
**
** "PURGE NODE ENET01 ALL"

NICE message received  (length = 9 bytes)
00000000 00000031 3054454E 4506C013 	.�.ENET01.......
				 13 	
                               C0	clear/purge permanent
               31 3054454E 4506		ascic nodename
00000000 000000

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 00FFFF02 	................

NICE message transmitted  (length = 52 bytes)
45444345 522D492D 4C4D4E25 27FFFF01 	...'%NML-I-RECDE
6E652065 73616261 74614420 2C54454C 	LET, Database en
4E450604 01646574 656C6564 20797274 	try deleted...EN
00000000 00000000 00000000 31305445 	ET01............

NICE message transmitted  (length = 1 bytes)
00000000 00000000 00000000 00000080 	................

** **************************************************************************
**
** "DEFINE NODE 1.1 NAME ENET01"

NICE message received  (length = 14 bytes)
00003130 54454E45 0601F404 01008013 	.....�..ENET01..

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 00FFFF02 	................

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 00FFFF01 	................

NICE message transmitted  (length = 1 bytes)
00000000 00000000 00000000 00000080 	................

** **************************************************************************
**
** "PURGE NODE 1.1 ALL"

NICE message received  (length = 5 bytes)
00000000 00000000 00000004 0100C013 	.�..............

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 00FFFF02 	................

NICE message transmitted  (length = 52 bytes)
45444345 522D492D 4C4D4E25 27FFFF01 	...'%NML-I-RECDE
6E652065 73616261 74614420 2C54454C 	LET, Database en
4E450604 01646574 656C6564 20797274 	try deleted...EN
00000000 00000000 00000000 31305445 	ET01............

NICE message transmitted  (length = 1 bytes)
00000000 00000000 00000000 00000080 	................

** **************************************************************************
**
** "PURGE NODE ENET01 ALL"

NICE message received  (length = 9 bytes)
00000000 00000031 3054454E 4506C013 	.�.ENET01.......

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 00FFFF02 	................

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 000000F8 	�...............

                                 F8 	Unrecognized component, Node
                           000000

NICE message transmitted  (length = 1 bytes)
00000000 00000000 00000000 00000080 	................

** **************************************************************************
**
** "DEFINE NODE 1.1 NAME ENET01"

NICE message received  (length = 14 bytes)
00003130 54454E45 0601F404 01008013 	.....�..ENET01..

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 00FFFF02 	................

NICE message transmitted  (length = 4 bytes)
00000000 00000000 00000000 00FFFF01 	................

NICE message transmitted  (length = 1 bytes)
00000000 00000000 00000000 00000080 	................


*/
