HP OpenVMS I/O User's Reference Manual

Local Area Network (LAN) Device Drivers

LAN Device Information

I/O Status Block

LAN Function Codes  

Table 34   LAN I/O Functions

Function Code	Arguments	Type1	Function Modifiers	Function
IO$_READLBLK2	P1,P2,[P5]	L	IO$M_NOW	Read logical block.
IO$_READVBLK3	P1,P2,[P5]	V	IO$M_NOW	Read virtual block.
IO$_READPBLK	P1,P2,[P5]	P	IO$M_NOW	Read physical block.
IO$_WRITELBLK4	P1,P2,[P4],P5	L	IO$M_RESPONSE	Write logical block.
IO$_WRITEVBLK	P1,P2,[P4],P5	V	IO$M_RESPONSE	Write virtual block.
IO$_WRITEPBLK	P1,P2,[P4],P5	P	IO$M_RESPONSE	Write physical block.
IO$_SETMODE	P1,[P2],P3	L	IO$M_CTRL IO$M_STARTUP IO$M_SHUTDOWN IO$M_ATTNAST IO$M_SET_MAC IO$M_UPDATE_MAP IO$M_ROUTE	Set controller characteristicsand controller state for subsequent operations.
IO$_SETCHAR	P1,[P2],P3	P	IO$M_CTRL IO$M_STARTUP IO$M_SHUTDOWN IO$M_ATTNAST IO$M_SET_MAC IO$M_UPDATE_MAP IO$M_ROUTE	Set controller characteristicsand controller state for subsequent operations.
IO$_SENSEMODE	[P1],[P2]	L	IO$M_CTRL IO$M_SENSE_MAC IO$M_SHOW_MAP IO$M_SHOW_ROUTE	Sense controller characteristicsand return them in specified buffers.
IO$_SENSECHAR	[P1],[P2]	P	IO$M_CTRL IO$M_SENSE_MAC IO$M_SHOW_MAP IO$M_SHOW_ROUTE	Sense controller characteristics andreturn them in specified buffers.

Although the LAN device drivers do not differentiate amonglogical, virtual, and physical I/O functions (all are treated identically),you must have the required privilege to issue the request. (LogicalI/O functions do not require I/O privilege.)

Read  

Read functions directlytransfer data from a packet received from another port on the Ethernetinto the virtual memory address space of the user process. The operatingsystem provides the following function codes:

• IO$_READLBLK--Read logicalblock



• IO$_READVBLK--Read virtual block



• IO$_READPBLK--Read physical block

Received messages are buffered in system memory and then copiedto the user's buffer when a read operation is performed.

The read functions take the following device- or function-dependentarguments:

• P1--The starting virtual addressof the buffer that is to receive data. On OpenVMS Alpha systems,P1 can be a 64-bit address.



• P2--The size of the receive buffer in bytes.



• P5--The address of a buffer where the LANdriver returns packet header information. This is an optional argument.The information returned depends on the packet format enabled withthe set mode QIO. The size of the buffer must be 14 bytes for anEthernet format packet, 16 bytes for an IEEE 802 format packet, and20 bytes for an 802 extended format packet. Note that the informationreturned is not the entire packet header but the header informationless any length or size fields. The IOSB, if specified, is where thepacket length information is returned. For FDDI, if received accesscontrol (RAC) is on, then 1 byte must be added to these sizes.
  
  On Alpha systems, Token Ring requires that this buffer beat least 54 bytes long due to a possible variable length sourcerouting header.
  
  If NMA$C_PCLI_PRM (see P2 Attributes) is enabled, the P5 buffer must be at least 20 bytesfor CSMA/CD and 21 bytes for FDDI. Read Function P5 Buffer shows the format of the three buffers. On OpenVMSAlpha systems, P5 can be a 64-bit address.

Figure 21  Read Function P5 Buffer

The P1 and P2 arguments must always be specified; the P5 argumentis optional. However, if P5 is not specified, you will be unableto determine the source of the received message.

If the size of the user data in a receive message is largerthan the value of the NMA$C_PCLI_BUS parameter, the message is notgiven to the user, even if there is sufficient space in the user'sreceive buffer.

If the size of the user data in a receive message is largerthan the size specified in P2 (and less than or equal to the valueof the NMA$C_PCLI_BUS parameter), the P1 buffer is filled and SS$_DATAOVERUNis returned in the I/O status block.

Maximum User Data Sizes for CSMA/CD, FDDI, and Token Ring lists themaximum user data sizes that can be received for CSMA/CD, FDDI,and Token Ring protocols. ⁵

Table 35   Maximum User Data Sizes for CSMA/CD, FDDI, and Token Ring

Packet Format	CSMA/CD	FDDI	Token Ring
Ethernet formatwithout padding	1500	4470	4418
Ethernet formatwith padding	1498	4468	4416
802 formatwith 1-byte CTL field	1497	4475	4423
802 formatwith 2-byte CTL field	1496	4474	4422
802E format	1492	4470	4418

On Alpha systems, Maximum User Data Sizes for LAN Emulation over ATM (Alpha Only) lists the maximum user data sizes that can be receivedfor LAN emulation over ATM protocol.

Table 36   Maximum User Data Sizes for LAN Emulation over ATM (AlphaOnly)

Packet Format	ATM ELAN size:	1516	4544	9234
Ethernet formatwithout padding		1500	4528	9218
Ethernet formatwith padding		1498	4526	9216
802 formatwith 1-byte CTL field		1497	4525	9215
802 formatwith 2-byte CTL field		1496	4524	9214
802E format		1492	4520	9210

For 802 format packets, the P5 buffer always contains theDSAP and SSAP in the bytes at offset 12 and 13. The next one ortwo bytes (offsets 14 and 15) following the SSAP contain the controlfield value. For Class I service, the control field value is always1 byte in length and will always be placed in the byte at offset14 of this buffer. For user-supplied service, you have to determinethe length of the control field value according to the IEEE 802.2Standard.

On Alpha systems with Token Ring, if received access control(RAC) is on, the first byte of the P5 buffer contains the framecontrol (FC) field.

For FDDI, if RAC is on, the first byte of the P5 buffer containsthe FC field.

The read functions can take the following function modifier:

IO$M_NOW--Completethe read operation immediately with a received message (if no messageis currently available, return a status of SS$_ENDOFFILE in theI/O status block).

Write  

Write functions providefor the direct transfer of data from the virtual memory addressspace of the user process to the communications medium. The operatingsystem provides the following function codes:

• IO$_WRITELBLK--Write logicalblock



• IO$_WRITEVBLK--Write virtual block



• IO$_WRITEPBLK--Write physical block

Transmitted messages are copied from the buffer of the requestingprocess to a system buffer for transmission.

The write function takes the following device- or function-dependentarguments:

• P1--The starting virtual addressof the buffer containing the data to be transmitted. On OpenVMSAlpha systems, P1 can be a 64-bit address.



• P2--The size of the buffer in bytes.



• P4--The address of a quadword that pointsto a buffer that contains the DSAP and CTL field values (optional).(See Service Access Point (SAP) Use and Restrictions.) The first longwordis the buffer length; the second longword is the address of thebuffer. This argument is used only for ports with the 802 packetformat. The format of the buffer is:
  
  On OpenVMS Alpha systems, P4 can be a 64-bit address.



• P5--The address of a 6-byte buffer thatcontains the destination address (either physical or multicast). ForFDDI, if XFC is specified as zero on startup, the first byte ofthe P5 buffer contains the low-order 3 bits of the FC field to betransmitted. On OpenVMS Alpha systems, P5 can be a 64-bit address.
  
  If the device is in promiscuous mode (NMA$C_PCLI_PRM; see P2 Attributes), you must pass alarger buffer with additional information positioned after the destinationaddress. For Ethernet packet format, the buffer must be 8 byteswith the 2-byte protocol type following the destination address.For 802 packet format, the buffer must be 7 bytes with the 1-bytesource SAP following the destination address. For 802 extended packetformat, the buffer must be 11 bytes with the 5-byte protocol identifierfollowing the destination address. The individual Source SAP cannotbe a group SAP or the SNAP SAP. Write Function P5 Buffer shows the format of the P5 buffer. For FDDI with XFCspecified as zero on startup, 1 byte must be added to these sizesfor the FC field.

Figure 22  Write Function P5 Buffer

Maximum Message Sizes for CSMA/CD, FDDI, and Token Ring lists themaximum user data sizes that can be specified by P2 and receivedfor CSMA/CD, FDDI, and Token Ring protocols.

Table 37   Maximum Message Sizes for CSMA/CD, FDDI, and Token Ring

Packet Format	CSMA/CD	FDDI	Token Ring6
Ethernet formatwithout padding	1500	4470	4418
Ethernet formatwith padding	1498	4468	4416
802 formatwith 1-byte CTL field	1497	4475	4423
802 formatwith 2-byte CTL field	1496	4474	4422
802E format	1492	4470	4418

On Alpha systems, Maximum Message Sizes for LAN Emulation over ATM (Alpha Only) lists the maximum user data sizes that can be specifiedby P2 and received for LAN emulation over ATM protocol.

Table 38   Maximum Message Sizes for LAN Emulation over ATM (Alpha Only)

Packet Format	ATM ELAN size:	1516	4544	9234
Ethernet formatwithout padding		1500	4528	9218
Ethernet formatwith padding		1498	4526	9216
802 formatwith 1-byte CTL field		1497	4525	9215
802 formatwith 2-byte CTL field		1496	4524	9214
802E format		1492	4520	9210

If P2 specifies a message size larger than that allowed, thedriver returns the status SS$_IVBUFLEN in the I/O status block.

Ifthe P4 buffer is specified, it must be at least 3 bytes long. Thefirst byte is always the DSAP; the next two bytes are used to determinethe CTL field value. The DSAP value cannot be the SNAP SAP.

The CTL field value is either a 1-byte or 2-byte value. Ifthe two least significant bits of the low-order byte of the CTLfield contain the bit values 11, just the low-order byte of theCTL field is used as the CTL field value. Otherwise, both bytesof the CTL field are used as the CTL field value.

If the driver uses only the low-order byte of the CTL field,you still must pass at least a 3-byte buffer. In this case, thedriver uses the low-order byte of the CTL field and ignores thehigh-order byte.

If Class I service is enabled, only 1-byte CTL field valuescan be passed. If user-supplied service is enabled, then both 1-and 2-byte CTL field values are valid. If Class I service is enabled,the CTL field value must be one of the three command values: UI,XID, or TEST.

Regarding 802 ports, you can receive packets for the SAP enabledwith the IO$_SETMODE or IO$_SETCHAR QIOs and can transmit packetsdestined for a different SAP. This is similar to an Ethernet portreceiving packets for one protocol type and transmitting packetswith a different protocol type (which is not possible with the currentEthernet $QIO interface). It is expected that most 802 format applicationswill want to process only receive packets from a source SAP thatmatches the SAP enabled on their port. To do this, the read function(see Read) has beenenhanced to return the source SAP to you. To verify that the sourceSAP of an incoming packet matches the SAP enabled on the port, youneed only match the source SAP returned by the read function withthe SAP enabled on the port.

The write function can take the following function modifier:

IO$M_RESPONSE--Transmita response packet (sets the low-order bit in the SSAP field). Thisallows users with user-supplied service enabled to respond to certain802 format command packets. IO$M_RESPONSE can be specified onlywhen you have the 802 packet format enabled. The 802 packet formatports, with Class I service enabled, result in an error if you attemptto transmit a response message with a CTL field value of unnumberedinformation (UI).

Set Mode and Set Characteristics  

The operating system provides the following two function codes:

IO$_SETMODE

IO$_SETCHAR

Other than the privilege check, these two function codes aretreated the same by the LAN drivers. This section refers to theIO$_SETMODE function code only, even though applications can useeither function code.

The set mode function code is used to perform many differentfunctions. These different functions are distinguished by the modifiersset with the function code. The LAN drivers support the followingset mode requests:

• IO$_SETMODE!IO$M_CTRL -- Setor modify port attributes



• IO$_SETMODE!IO$M_CTRL!IO$M_STARTUP -- Setport attributes and start port



• IO$_SETMODE!IO$M_SET_MAC -- Set medium attributes



• IO$_SETMODE!IO$M_CTRL!IO$M_SHUTDOWN -- Shutdown port



• IO$_SETMODE!IO$M_ATTNAST -- Enable attentionAST

On Alpha systems, the LAN drivers also support the followingset mode requests for Token Ring:

• IO$M_SETMODE!IO$M_UPDATE_MAP -- Updatefunctional address mapping table



• IO$M_SETMODE!IO$M_ROUTE -- Update sourcerouting cache table

The following sections describe these functions in detail.

Set Controller Mode  

Once a port is created using the $ASSIGN system service, youcan set the port attributes and start the port using the requestslisted in the previous section. Note that in most cases only IO$_SETMODE!IO$M_CTRL!IO$M_STARTUPis issued because it sets the port attributes and starts the portwith one request. IO$_SETMODE!IO$M_CTRL is most often used to modifyport attributes after the port has been started.

If the function modifier IO$M_STARTUP is specified, the LANport is started.If IO$M_STARTUP is not specified, the specified characteristicsare modified.

This function takes the following device- or function-dependentargument:

P2--The addressof a quadword descriptor for an extended characteristics buffer.The first longword of the descriptor is the buffer length; the secondlongword is the address of the buffer. The P2 argument is optional.

The P2 buffer consistsof a series of 6-byte or counted string entries. The first wordof each entry contains the parameter identifier (ID) of an attribute,followed by either a longword that contains one of the(binary) values that can be associated with the parameter ID ora counted string. Counted strings consist of a word that containsthe size of the character string followed by the character string. P2 Extended Characteristics Buffer shows the format for thisbuffer.  

Figure 23  P2 Extended Characteristics Buffer

P2 Attributes is an alphabeticlisting of the parameter IDs and values that can be specified inthe P2 buffer. These parameter IDs are applicable to all LAN controllers,except where otherwise noted. The $NMADEF macro defines these values.The $NMADEF macro is included in the macro library SYS$LIBRARY:LIB.MLB. (Set Mode Parameters for Packet Formats lists the parameters thatcan be used with each of the packet formats, and indicates whichare required, which are optional, and which generate the SS$_BADPARAMerror.)

If the status SS$_BADPARAM is returned in the first word ofthe I/O status block, the second longword contains the parameterID of the parameter in error.

Table 39   P2 Attributes

Parameter ID	Meaning
NMA$C_PCLI_ACC	Protocol access mode. This optional parameterdetermines the access mode for the protocoltype. NMA$C_PCLI_ACC is valid only for ports using Ethernet packetformat. NMA$C_PCLI_ACC is valid for ports using 802Epacket format. One of the following values can be specified: NMA$C_ACC_EXC -- Exclusivemode (default) NMA$C_ACC_SHR -- Shared-default user mode NMA$C_ACC_LIM -- Shared-with-destinationmode Protocol Type Sharing provides a description of protocol type sharing. Protocol Type PID Sharing (Alpha Only) provides a descriptionof protocol type PID sharing. NMA$C_PCLI_ACC is passedas a longword value.
NMA$C_PCLI_BFN	Number of receive buffers to preallocate(default = 1). NMA$C_PCLI_BFN can have a maximum value of 255. Thisoptional parameter is specified on a per-port basis. NMA$C_PCLI_BFNis passed as a longword value. NMA$C_PCLI_BFN representsthe number of receive messages the LAN driver will hold for a portwhen the port has no read QIOs posted to the driver.
NMA$C_PCLI_BUS	Any message received for this port thatis larger than this parameter value is discarded. Maximumallowable port receive data size, that is, message length (default =512 bytes). NMA$C_PCLI_BUS can have a maximum value of 9234.Thisoptional parameter is specified on a per-port basis. It is passedas a longword value.
NMA$C_PCLI_CCA	Can change address. This optional parameterenables applications to start before DECnet starts. DECnet may attemptto set the physical address of the controller when it starts. CSMA/CDdevices support only one physical address, and so all applicationsthat are using the same device must also use the same physical address.If applications that do not use the DECnet address start beforeDECnet, DECnet is not able to start on that controller unless theother applications that have already started have all specified NMA$C_PCLI_CCAto be ON. This parameter is not applicable to FDDI becauseFDDI devices can run with more than one physical address; however,no error is returned if this parameter is supplied for FDDI devices. Theapplication receives no indication whatsoever that the physicaladdress has changed.This parameter is passed as a longword. Oneof the following values can be specified: NMA$C_STATE_ON -- Thephysical address can be changed. NMA$C_STATE_OFF -- The physical addresscannot be changed (default).
NMA$C_PCLI_CON7	Controller mode. This optional parameterdetermines whether transmit packets are to be looped back at thecontroller. One of the following values can be specified: NMA$C_LINCN_NOR -- Normal mode (default)NMA$C_LINCN_LOO -- Loopbackmode The only messages loopedback are those acceptable to the controller as receive messages,that is, those messages that possess at least one of the followingcharacteristics: Matchingphysical address (see Ethernet Addresses) Matching multicast address (see Ethernet Addresses) Promiscuous mode (NMA$C_PCLI_PRM) is in the ON state Destination address is a multicast address and allmulticasts are enabled (NMA$C_PCLI_MLT is in the ON state) NMA$C_PCLI_CONaffects all ports on a single controller. It is passed as a longwordvalue. For the DELUA, DEBNA, DEBNI, DEQTA, PMAD, DEMNA,and DESVA, the following list shows the maximum amount of user datathat can be looped: Ethernet format withoutpadding -- 18 bytes Ethernet format with padding -- 16 bytes 802 format with 1-byte CTL field -- 15 bytes 802 format with 2-byte CTL field -- 14 bytes 802 extended format--10 bytes When the DEUNA is in loopbackmode, the driver always enables echo mode (NMA$C_PCLI_EKO is inthe ON state). Notall devices support loopback mode. If normal mode is not specified,the request is completed with SS$_BADPARAM status.
NMA$C_PCLI_CRC	Cyclic redundancy check (CRC) generationstate for transmitted messages (optional). One of the followingvalues can be specified: NMA$C_STATE_ON -- Controllergenerates a CRC (default).NMA$C_STATE_OFF -- Controllerdoes not generate a CRC.NMA$C_PCLI_CRC affects all ports on a singlecontroller. There is no effect onchecking a receive message'sCRC (it is always checked). NMA$C_PCLI_CRC is passed as a longwordvalue. IfNMA$C_PCLI_CRC is turned off, all users of the controller must supply the4-byte CRC value for all messages transmitted. The CRC is passedat the end of the P1 transmit buffer; the additional 4 bytes areincluded in the size of the P1 buffer. The CRC value is not checkedfor correctness. For the DEQNA, DELQA, and Token Ringdevices, the NMA$C_PCLI_CRC parameter cannot be turned off. Forthe DEQNA, DELQA, and Token Ring devices, the NMA$C_PCLI_CRC parametercannot be turned off. Not all devices support user-suppliedCRC. If a controller-generated CRC is specified, the request iscompleted with SS$_BADPARAM status.
NMA$C_PCLI_DES	Shared protocol destination address.Passed as a counted string that consists of a modifier word (NMA$C_LINMC_SETor NMA$C_LINMC_CLR) followed by a 6-byte (48-bit) physical destination address.The size of the counted string must always be 8. NMA$C_PCLI_DESonly has meaning when protocol access (NMA$C_PCLI_ACC) is definedas shared-with-destination mode (NMA$C_ ACC_LIM). The destinationaddress specified must be a physical address--not a multicastaddress--and it must be unique among all ports sharing thesame protocol. NMA$C_PCLI_DES is required when the access mode isdefined as ''shared-with-destination.'' NMA$C_PCLI_DESshould not be specified on a port where the 802 or 802E packet formatis selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_802 or NMA$C_LINFM_802E).For 802 packet format, the concept of shared protocol type is handledby using group SAPs. NMA$C_PCLI_DES should not be specifiedon a port where the 802 packet format is selected (NMA$C_PCLI_FMTis set to NMA$C_LINFM_802). For 802 packet format, the concept ofshared protocol type is handled by using group SAPs. Protocol Type Sharing provides a descriptionof protocol type sharing. Protocol Type PID Sharing (Alpha Only) provides a description of protocol type PID sharing.
NMA$C_PCLI_EKO	Echo mode. Applicable only to the DEUNAdevice driver. If echo mode is on, transmitted messagesare returned to the sender. This optional parameter controls thecondition of the half-duplex bit in the DEUNA mode register. Oneof the following values can be specified: NMA$C_STATE_OFF -- Does not echo transmit messages(default) NMA$C_STATE_ON -- Echoes transmit messages IfNMA$C_STATE_ON is specified, the only transmitted messages echoed arethose acceptable to the DEUNA as receive messages, that is, those messagesthat have at least one of the following characteristics: Matching physical address (see Ethernet Addresses) Matching multicast address (see Ethernet Addresses) Promiscuous mode (NMA$C_PCLI_PRM) is in the ON state Destination address is a multicast address and allmulticasts are enabled (NMA$C_PCLI_MLT is in the ON state) Ifthe DEUNA is placed in loopback mode (NMA$C_LINCN_LOO is specifiedin the NMA$C_PCLI_CON parameter), the driver enables echo mode. NMA$C_PCLI_EKOaffects all ports on a single controller. It is passed as a longwordvalue.
NMA$C_PCLI_FMT	Packet format. This optional parameterspecifies the packet format as either Ethernet, IEEE 802, or 802extended. This characteristic is passed as a longword value andaffects single ports on a single controller. One of the followingvalues can be specified: NMA$C_LINFM_ETH -- Ethernetpacket format (default) NMA$C_LINFM_802 -- 802 packet format NMA$C_LINFM_802E -- 802extended packet format NMA$C_PCLI_PTY, NMA$C_PCLI_ACC,and NMA$C_PCLI_DES should only be specified on those ports wherethe Ethernet packet format (NMA$C_LINFM_ ETH) is selected. NMA$C_PCLI_SRV,NMA$C_PCLI_SAP, and NMA$C_PCLI_GSP should only be specified on thoseports where the 802 packet format (NMA$C_LINFM_802) is selected. NMA$C_PCLI_PIDshould only be specified on those ports where the 802 extended packetformat (NMA$C_LINFM_802E) is selected.
NMA$C_PCLI_GSP	Group SAP. This is an optional parameterif the 802 packet format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_802).If the Ethernet or 802 extended packet format is selected, NMA$C_PCLI_GSP cannotbe specified. Group SAPs can be shared among multiple ports on the samecontroller. If the 802 packet format is selected, NMA$C_PCLI_GSP definesup to four 802 group SAPs that are to be enabled for matching incomingpackets to complete read operations on this port. By default, no groupSAPs are enabled. NMA$C_PCLI_GSP is passed as a longwordvalue and is read as four 8-bit unsigned integers. Each integermust be either a group SAP or zero. To enable a single group SAPon a port, you need only specify the group SAP value to be enabledin one of the four integers and place a value of zero in the threeremaining integers. To disable group SAPs on the port, you need onlyplace a value of zero in all four integers and issue the QIO. Ifthis characteristic is correctly specified, any group SAPs thatwere previously enabled on the port are now replaced by the SAPsspecified by the current request.
NMA$C_PCLI_ILP	Internal loopback mode. This optionalparameter places the device in internal loopback mode (not for theDEUNA, DEQNA, or DELQA devices). One of the following values canbe specified: NMA$C_STATE_ON -- Internalloopback mode NMA$C_STATE_OFF -- Not in internal loopback mode(default) If NMA$C_STATE_ON is specified,the NMA$C_PCLI_CON parameter must be in loopback (NMA$C_LINCN_LOO)mode. When the controller is in loopback mode (generallyfor testing), it can loop packets in external loopback or internalloopback. This parameter places the controller in one of these loopbackmodes. NMA$C_PCLI_ILP is passed as a longword value and affectsall ports on the controller. Not all devices supportloopback mode. If NMA$C_STATE_OFF is not specified, the requestis completed with SS$_BADPARAM status.
NMA$C_PCLI_MCA	Multicast address (optional). Passedas a counted string that consists of a modifier word followed bya list of 6-byte (48-bit) multicast addresses. The value specifiedin the modifier word determines whether the addresses are set orcleared. If NMA$C_LINMC_CAL is specified, all multicast addresses inthe list are ignored. The following mode values canbe specified in the low byte of the modifier word: NMA$C_LINMC_SET -- Set the multicast addresses. NMA$C_LINMC_CLR -- Clear the multicast addresses. NMA$C_LINMC_CAL -- Clear all multicast addresses. The driver filters all multicastaddresses on a per-port basis; therefore, only messages receivedwith the port's physical address or the multicast addresses enabledon the port are used to complete the user's read operations. Notethat each LAN controller supports a limited number of multicast addresses.If this limit is exceeded, the LAN driver enables the "acceptall multicast" feature on the controller and all multicastpackets on the LAN must be filtered by the LAN driver. This maycause a minor performance loss. NMA$C_PCLI_MCA is specifiedon a per-port basis.
NMA$C_PCLI_MLT	Multicast addressstate. This optional parameter instructs the controller hardwarewhether to accept all multicast addresses for this port. One ofthe following values can be specified: NMA$C_STATE_ON -- Acceptall multicast addresses.NMA$C_STATE_OFF -- Do not acceptall multicast addresses (default). NMA$C_PCLI_MLT allows you toreceive all multicast address packets that also match the port'sprotocol type, SAP, or protocol identifier. Generally,you enable only your individual set of multicast addresses using theNMA$C_PCLI_MCA parameter, and leave the NMA$C_PCLI_MLT parameterin the off state. There could be a minor performanceloss when the NMA$C_PCLI_MLT parameter is in the ON state becausethe LAN driver may have to process all multicast addresses on themedium; the number of multicast addresses on the line determinesthe amount of processing required. The NMA$C_PCLI_MLTparameter is passed as a longword value.
NMA$C_PCLI_PAD	Use message size fieldon transmit and receive messages (optional). One of the followingvalues can be specified: NMA$C_STATE_ON -- Insertmessage size field (default) NMA$C_STATE_OFF -- No size field NMA$C_PCLI_PAD affects onlythe protocol type that issued the set mode request. It is passedas a longword value. On CSMA/CD, if padding is enabledon Ethernet format packets, the driver adds a 2-byte count fieldto the transmitted data. This field allows short packets (packetsfewer than 46 bytes long) to be received with the proper lengthreturned by the driver. The minimum Ethernet packet contains 46 bytesof user data. When fewer than 46 bytes are sent, the packet is padded andthe receiver always receives 46 bytes of data. When padding is enabled, themaximum message size for transmit or receive operations is 1498bytes and the minimum is zero bytes. See Ethernet Packet Format for additional information. NMA$C_PCLI_PADshould be specified only on a port where the Ethernet packet formatis selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_ETH). ForFDDI, the same 2-byte count field is added; however, because FDDI packetscan be as short as 22 bytes, FDDI transmit requests are never padded.
NMA$C_PCLI_PHA	Physical address (optional). It is passedas a counted string that consists of a modifier word followed bythe 48-bit physical address. If the request is to clear the physicaladdress or to set the physical address to the default address, thephysical address (if present) is not read. One of thefollowing mode values can be specified in the low byte of the modifierword: NMA$C_LINMC_SET -- Set thestring value. NMA$C_LINMC_CLR -- Clear the physical address. NMA$C_LINMC_SDF -- Set the physical address to thedefault address. For CSMA/CD, the default address is constructedby appending the low-order word of the system parameter SCSSYSTEMIDto the constant DECnet header (AA-00-04-00). If SCSSYSTEMID is zero,and NMA$C_LINMC_SDF is specified, the hardware address is used asthe default. If not specified for CSMA/CD,the default is the current address set by a previous set mode functionon this controller, or the hardware address if no address was definedby a previous set mode function. If not specified for FDDI, thedefault is the hardware address. The physical addressmust be passed as a 6-byte (48-bit) quantity. The first byte isthe least significant byte. A return value of -1 on a sense mode requestimplies that a physical address is not defined. TheNMA$C_PCLI_PHA parameter affects all ports on a single controller.If the address specified is already being used on the extended LAN, SS$_IVADDRis returned.
NMA$C_PCLI_PID	Protocol identifier. This parameter isrequired for, and valid only on, ports that use 802 extended formatpackets. NMA$C_PCLI_PID is passed as a counted 5-byte string, whichis the unique protocol identifier required for each 802 extendedformat user. All protocol identifiers specified on acontroller must be unique except when the PID is being shared. NMA$C_PCLI_PIDmay only be specified on a port when the 802 extended packet formatis selected; that is, NMA$C_PCLI_FMT is set to NMA$C_LINFM_802E.
NMA$C_PCLI_PRM	Promiscuous (optional). One of the followingvalues can be specified: NMA$C_STATE_ON--Promiscuousmode enabled. NMA$C_STATE_OFF--Promiscuousmode off. The NMA$C_PCLI_PRMparameter is passed as a longword value. Only one porton each controller can be active with promiscuous mode enabled.Enabling promiscuous mode requires PHY_IO privilege. THeNMA$C_PCLI_PRM parameter is passed as a longword value. HPdoes not recommend promiscuous mode for normal usage. SomeToken Ring devices do not support real promiscuous access to thering. See Promiscuous Mode for additional information.
NMA$C_PCLI_PTY	Protocol type. This value is read asa 16-bit unsigned integer and must be unique on the controller exceptwhen the protocol type is being shared. For Ethernet format ports,this is a required parameter. Valid protocol types arein the range 05-DD through FF. NMA$C_PCLI_PTY may onlybe specified on a port where the Ethernet packet format is selected(NMA$C_PCLI_FMT is set to NMA$C_LINFM_ETH). NMA$C_PCLI_PTYis passed as a longword value; however, only the low-order wordis used.
NMA$C_PCLI_RAC	(Alpha specific) Receive access control(Token Ring only). This optional parameter specifies whether theapplication receives a copy of the access control (AC) field foreach Token Ring frame received. It is passed as a longword value.It must be passed with one of the following values: NMA$C_STAT_ON -- Applicationgets a copy of the AC for each Token Ring frame received. NMA$C_STATE_OFF -- Applicationdoes not get a copy of the AC for each Token Ring frame received. TheAC is returned in the P5 buffer. The P5 buffer size for Token Ring shouldalways be a minimum of 54 bytes. This is due to the variable sizeof the Token Ring header.
NMA$C_PCLI_RES	Restart. This optional parameter allowsthe user to enable the automatic port restart feature of the LANdrivers. One of the following values can be specified: NMA$C_LINRES_DIS -- Disableautomatic restart (default) NMA$C_LINRES_ENA -- Enableautomatic restart TheLAN drivers shut down all users of a controller if there is a fatalerror on the controller or if the LAN driver determines that thecontroller has stopped functioning. All outstanding I/O operationson the LAN driver are completed with either an SS$_ABORT or SS$_TIMEOUTstatus. All ports that have the NMA$C_PCLI_RES parameterenabled (set to NMA$C_LINRES_ENA) have the port automatically restartedby the LAN driver approximately one second after it has been shutdown due to a fatal error. If the user issues read or write QIOsto the port during the time the port is shut down, the driver completesthe QIOs with an SS$_OPINCOMPL status. All ports thathave the automatic restart feature disabled must be restarted bythe application program when the port is shut down by the LAN driver. Theapplication program should wait approximately 2 seconds to allowthe LAN driver to stabilize. Once the LAN driver shuts down a port,it attempts a maximum of 30 consecutive automatic restarts. If thereare 30 consecutive failures to restart the port, the port remainsshut down. Note that it is unusual to have fatal errorson a LAN controller or to have a LAN driver detect that a LAN controllerhas stopped functioning. Having the ability to automatically restarta user's port makes the program easier to design because the programdoes not have to take into account the possibility of the LAN drivershutting down the port.
NMA$C_PCLL_RFC	Receive frame control (FDDI only). Thisoptional parameter specifies whether the application receives acopy of the Frame Control (FC) field for each FDDI frame received.It is passed as a longword value. However, only the low-order byteis used. It must be passed with one of the following values: NMA$C_STATE_ON -- Applicationgets a copy of the FC for each FDDI frame received. NMA$C_STATE_OFF -- Applicationgets a copy of the FC for each FDDI frames (default). For$QIO Read operations, the FC is passed to the application in theP5 buffer. The following are the sizes required for the P5 bufferfor various packet formats and settings of NMA$C_PCLI_RFC: Ethernet (NMA$C_LINFM_ETH) -- 14 if NMA$C_STATE_OFFis specified, 15 if NMA$C_STATE_ON is specified. 802 (NMA$C_LINFM_802) -- 16 if NMA$C_STATE_OFFis specified, 17 if NMA$C_STATE_ON is specified. 802E (NMA$C_LINKFM_802E) -- 20 if NMA$C_STATE_OFFis specified, 21 if NMA$C_STATE_ON is specified. Receiving the FC requires one additional byte of space inthe P5 buffer. The FC is the first byte in the P5 buffer, immediatelypreceding the 6-byte destination address. The size of the P5 bufferrequired does not change from the CSMA/CD sizes if NMA$C_PCLI_RFCis set to NMA$C_STATE_OFF.
NMA$C_PCLI_SAP	802 format SAP. This parameter is requiredif the 802 packet format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_802)> NMA$C_PCLI_SAPdefines an 802 SAP and is read as an 8-bit unsigned integer. Theleast significant bit of the SAP must be 0 and the SAP cannot be thenull SAP (all 8 bits equal 0) or the SNAP SAP. NMA$C_PCLI_SAP is passedas a llongwood value. However, only the low-order byte is used. TheSAP specified by NMA$C_PCLI_SAP is the SAP used to match incomingpackets to complete read requests. It is used as the source SAP (SSAP)in all transmissions (write QIOs). Because it is illegal to transmit usinga group SAP as the source SAP, the SAP specified by this NMA$C_PCLI_SAPcannot be a group SAP. NMA$C_PCLI_GSP describes how to set up groupSAPs on a port. All individual SAPs specified on a controllermust be unique on that controller; therefore, the SAP specifiedusing the NMA$C_PCLI_SAP parameter is checked for uniqueness onthe controller.
NMA$C_CPCLI_SRMODE	(Alpha specific) Sets the source routing(SR) modefor the $QIO user (Token Ring only). This optional parameterallows the application to perform the source routing discovery.It must be passed with one of the following values: NMA$C_SR_TRANSPARENT -- Applicationsource routing is transparent. This is the default when this parameteris not specified. NMA$C_SR_SELF -- Thisshuts off the automatic route discovery exploration messagefor thisuser. The $QIOs existtofurther manipulate the sourcerouting cache. HP recommends that applicationsuse the NMA$C_SR_TRANSPARENT mode.
NMA$C_PCLI_SRV	Port service. This optional parameterspecifies the service supplied by the driver for the port. It canonly be specified if the 802 packet format is selected (NMA$C_PCLI_FMTis set to NMA$C_LINFM_802). This characteristic is passed as a longwordvalue. One of the following values can be specified: NMA$C_LINSR_USR -- Usersupplied service (default) NMA$C_LINSR_CLI -- ClassI service See OpenVMS LAN Devices Requiring Configuration for a descriptionof Class I service and DW110 Token Ring for a description of user-supplied service.
NMAC$C_PCLI_XAC	(Alpha specific) Transmit access control (TokenRing only). This is an optional parameter that enables applicationsto contol the setting of the priority bits in the access control(AC) for frames being transmitted in a $QIO write operations. Whenset to a wanted value, all subsequent transmits use this AC value.
NMA$C_PCLI_XFC	Transmit frame control (FDDI) only).NMA$C_PCLI_XFC is an optional parameter that enables applicationsto control the setting of the priority bits in the FC for framesbeing transmitted in a $QIO write operation. NMA$C_PCLI_XFC is passedas a longword parameter that has many valid settings. If specifiedwith a value of 0, the application supplies an FC value on each$QIO write operation. The FC value to be used in this case is suppliedin the P5 buffer for the $QIO write operation. If the parameteris specified with a value other than 0, that value is inserted intothe FC field of every transmit by the FDDI drivers. NO FC is presentin the P5 buffer for the $QIO write in this case. If this parameteris not specified, the default setting (0) of the priority bits isused. Regardless of how the FC is supplied, the valuespecified must be valid. The allowable values for FC are between50 hexadecimal and 57 hexadecimal. If NMA$C_PCLI_XFC is specifiedwith a nonzero value outside the valid range, the application receivesa SS$_BADPARAM error. The priority bits are the three low-orderbits.

Set Mode Parameters for Packet Formats  

Set Mode Parameters for Packet Formats summarizes the use of the set mode parameters forthe Ethernet, 802, and 802 extended (802E) packet formats.

Table 40   Set Mode Parameters for Packet Formats

Parameter ID	Ethernet	IEEE 802	802E
FMT	DEF	REQ	REQ
PTY	REQ	E	E
SAP	E	REQ	E
PID	E	E	REQ
ACC	OPT	E	E
DES	OPT	E	E
PAD	OPT	E	E
SRV	E	OPT	E
GSP	E	OPT	E
BFN, BUS, CCA, CON, CRC,EKO, ILP, MCA, MLT, PHA, PRM, RAC, RES, RFC, SRMODE, XAC, XFC	OPT	OPT	OPT

Set Mode Parameter Validation  

When startinga LAN port, the LAN driver checks that the mode of the new portis compatible with the mode of the LAN ports already started. Thereare two sets of compatibility checks: one for ports running in shared modeand one for all ports.

The following parameters must match for all ports on the samecontroller:

NMA$C_PCLI_CON

NMA$C_PCLI_CRC

NMA$C_PCLI_EKO

NMA$C_PCLI_ILP

NMA$C_PCLI_PHA (need only match for CSMA/CD controllers)

On VAX systems, the following parameters must match for allshared-default and shared-with-destination users of the same protocoltype:

NMA$C_PCLI_BFN

NMA$C_PCLI_BUS

NMA$C_PCLI_CCA

NMA$C_PCLI_MLT

NMA$C_PCLI_PAD

NMA$C_PCLI_PTY

NMA$C_PCLI_RAC

NMA$C_PCLI_RES

NMA$C_PCLI_RFC

NMA$C_PCLI_XAC

NMA$C_PCLI_XFC

Once a port is started, only the following parameters canbe changed:

NMA$C_PCLI_GSP

NMA$C_PCLI_MCA

Shutdown Controller  

The shutdowncontroller function shuts down the LAN port. On completion of ashutdown request all outstanding I/O requests are completed. Thisport cannot be used again until another startup request has beenissued (see Set Controller Mode ).

The following function code is used to shut down a port:

IO$_SETMODE!IO$M_CTRL!IO$M_SHUTDOWN--Shutdown port

The shutdown controller function takes no device- or function-dependentarguments.

Enable Attention AST  

This function requeststhat an attention AST be delivered to the requesting process whena status change occurs on the assigned port. An AST is queued whena message is available and there is no waiting read request. Theenable attention AST function is legal at any time, regardless ofthe condition of the unit status bits.

The following function code and modifier is used to enablean attention AST:

• IO$_SETMODE!IO$M_ATTNAST--Enableattention AST

This function takes the following device- or function-dependentarguments:

• P1--The address of an ASTservice routine or 0 for disable



• P2--Ignored



• P3--Access mode to deliver AST

The enable attention AST function enables an attention ASTto be delivered to the requesting process once only. After the ASToccurs, it must be explicitly reenabled by the function before theAST can occur again. The function is subject to AST quotas.

The AST service routine is called with an argument list. Thefirst argument is the current value of the second longword of theI/O status block (see I/O Status Block).

IO$M_SET_MAC Functional Modifier to IO$M_SETMODE  

The IO$M_SET_MAC qualifier, when used with IO$_SETMODE, isused to set medium specific parameters. The Token Ring parametersrequire PHY_IO privilege to set. Medium Specific Parameters of IO$M_SET_MAC for Ethernet (Alpha Only) shows the parameters that may be set for Ethernet. Medium Specific Parameters of IO$M_SET_MAC for FDDI shows theparameters that may be set for FDDI. Medium Specific Parameters of IO$M_SET_MAC for Token Ring shows the parameters that may be set for Token Ring,and Medium Specific Parameters of IO$M_SET_MAC for ATM showsthe parameters that may be set for ATM.

Table 41   Medium Specific Parameters of IO$M_SET_MAC for Ethernet (Alpha Only)

Parameter ID	Meaning
MA$C_PCLI_FDE	Enables or disables fullduplex operation. The values for this parameter are NMA$C_STATE_ONor NMA$C_STATE_OFF.
NMA$C_PCLI_LINEMEDIA	Sets the connection mediatype for the Ethernet adapter. Valid values for this parameter are: NMA$C_MEDIA_AUTO NMA$C_MEDIA_AUI NMA$C_MEDIA_BNC NMA$C_MEDIA_TP
NMA$C_PCLI_LINESPEED	Sets the speed of the Ethernet adapter.Valid values for this parameter are: 0--Used to autosense the speed. 10--Sets the speed to 10 Mb/s. 100--Sets the speed to 100 Mb/s. 65636--Used to autonegotiate with a maximumspeed of 100 Mb/s. 65546--Used to autonegotiate with a maximumspeed of 10 Mb/s.

Table 42   Medium Specific Parameters of IO$M_SET_MAC for FDDI

Parameter ID	Meaning
NMA$C_PCLI_TREQ	Requested value for tokenrotation timer, ANSI MAC T_req parameter. Units are in 80 nanoseconds,the default is 8000, minimum is 4000, and maximum is 167772.
NMA$C_PCLI_TVX	Maximum time between arrivalsof a valid frame or unrestricted token, ANSI MAC TVX parameter.Units are in 80 nanoseconds, the default is 2621, minimum is 2500,and maximum is 5222.
NMA$C_PCLI_REST_TTO	Restricted token timeoutwhich limits how long a single restricted mode dialog may last beforebeing terminated. Units are in milliseconds, the default is 1000,minimum is 0, and maximum is 10000.
NMA$C_PCLI_RPE	Ring purge enable. If 1(TRUE), this link will particpate in the Ring Purger election and,if elected, perform the Ring Purger function.
NMA$C_PCLI_NIF_TARG	Neighbor information frametarget.
NMA$C_PCLI_SIF_CONF_TARG	Station information frameconfiguration target. A 6-byte string specifying the LAN addressof the target. Used only by DECnet/OSI.
NMA$C_PCLI_SIF_OP_TARG	Station information frameoperation target. A 6-byte string specifying the LAN address ofthe target. Used only by DECnet/OSI.
NMA$C_PCLI_ECHO_TARG	Echo test target. A 6-bytestring specifying the LAN address of the target. Used only by DECnet/OSI.
NMA$C_PCLI_ECHO_DAT	Data pattern to use forthe echo test. Used only by DECnet/OSI.
NMA$C_PCLI_ECHO_LEN	Length of the echo packet. Used onlyby DECnet/OSI.

Table 43   Medium Specific Parameters of IO$M_SET_MAC for Token Ring

Parameter ID	Meaning
NMA$C_PCLI_RNG_SPD	Sets the speed of the ring.This longword may be either: NMA$C_LINRNG_FOUR -- Used for 4 Mb/s rings. NMA$C_LINRNG_SIXTN -- Used for 16 Mb/s rings. Thedefault is NMA$C_LINRNG_SIXTN.
NMA$C_PCLI_LINEMEDIA	Sets the connection mediatype for the Token Ring adapter. Valid values for this longwordparameter are: NMA$C_MEDIA_STP NMA$C_MEDIA_UTP Thedefault is NMA$C_MEDIA_STP.
NMA$C_PCLI_ETR	Controls the Early Tokenrelease feature of the Token Ring hardware. This feature can greatlyimprove throughput, and is only valid on 16 Mb/s rings. The valuesfor this longword parameter are NMA$C_STATE_ON or NMA$C_STATE_OFF.The default is NMA$C_STATE_ON.
NMA$C_PCLI_MONCONTEND	Specifies whether the controllerparticipates in the monitor contention process when another adapterdetects the need for contention and initiates the process. The valuesfor this longword parameter are NMA$C_STATE_ON or NMA$C_STATE_OFF.The default is NMA$C_STATE_OFF.
NMA$C_PCLI_CACHE_ENT	The number of source routing(SR) entries to make available for caching. The default is 200,minimum is 20, and maximum is 2000. Each cache entry consumes 64bytes.
NMA$C_PCLI_ROUTEDIS	The source routing discoverytimer. This is the amount of seconds to wait after the transmissionof ring explorer packets before declaring the route of a path tobe unknown. The default is 2 seconds, minimum is 1, and maximumis 255.
NMA$C_PCLI_A_TIM	The source routing agingtimer. After traffic is neither received from nor sent to a givennode for this number of seconds, the entry is marked stale. Afterthe entry is marked stale, rediscovery is required to communicatewith the node. The default is 60 seconds, minimum is 1, and maximumis 65535.
NMA$C_PCLI_SRC_ROU	Enables and disables sourcerouting. The values for this longword parameter are NMA$C_LINSRC_ENAor NMA$C_LINSRC_DIS. The default is NMA$C_LINSRC_ENA.
NMA$C_PCLI_AUTH_PR	Specifies the highest priority that auser may transmit a frame. The priority is set within the NMA$C_PCLI_XACparameter. The default for this parameter is 3, minimum is 0, andmaximum is 6.

Table 44   Medium Specific Parameters of IO$M_SET_MAC for ATM

Parameter ID	Meaning
NMA$C_PCLI_MED	Medium. This longword parameterdefaults to and may only be set to NMA$C_LINMD_CSMACD.
NMA$C_PCLI_BUS	Buffer size. This longwordparameter specifies the requested maximum packet size of the emulatedLAN. The value may be either 1516, 4544, or 9234.
NMA$C_PCLI_ELAN_PAR	Parent device name. Thisis a 3- or 4-character string parameter that specifies the nameof the ATM device to associate with this emulated LAN.
NMA$C_PCLI_NET	ELAN name. This is a stringof up to 64 characters that specifies the name of the emulated LANto join.
NMA$C_PCLI_ELAN_DESC	ELAN description. This isa string of up to 64 characters long that provides additional descriptionof the emulated LAN for status displays.
NMA$C_PCLI_LES_HWA	LES ATM address. This isspecified as a 40-character string as the hexadecimal representationof a 20-byte ATM address.
NMA$C_PCLI_ELAN_STATE_REQ	ELAN change state requestvalue. This longword parameter directs the driver to either startor shutdown the emulated LAN. Start is specified by a value of 2.Shutdown is specified by a value of 4.
NMA$C_PCLI_EVENT_REQ	Event mask request. If setto 1, this longword parameter directs the driver to set the eventreporting mask to the value given by the event parameter.
NMA$C_PCLI_EVENT	Event mask value. This is a longwordbit mask that controls the event reporting done by the driver. Abit set in the mask enables the reporting of corresponding event(s).

IO$M_UPDATE_MAP Functional Modifier to IO$_SETMODE  

Using Token Ring only, the IO$M_UPDATE_MAP qualifier, whenused with IO$_SETMODE, manipulates the adapter's functional addressmapping table. Format of IO$M_UPDATE_MAP Setmode P2 Buffer (Alpha Only) shows the format of the P2 buffer for this operation.This QIO requires PHY_IO privilege.  

Figure 24  Format of IO$M_UPDATE_MAP Setmode P2 Buffer(Alpha Only)

The subfunction is one of the following:

• NMA$C_MAP_CHANGE -- This functionadds or changes a mapping in the functional address table. If thespecified multicast entry does not exist, an entry is created withthe specified functional address mask. If the specified multicastentry does exist, the corresponding functional address mask is changedto the specified mask. All users who currently have the multicastenabled when the functional mask is changed will automatically updatethe functional address table as part of this operation.
  
  Possible errors returned include the following:
  
  

  SS$_DEVICEFULL -- Thiserror indicates that there is insufficient space in the mappingtable to complete the request. The multicast to functional addressmapping table has 200 entries.




• NMA$C_MAP_DELETE -- This function deletesthe specified MC address in the table. For this function, the functionaladdress mask is not required to pass the P2 buffer. If the functionaladdress mask is passed, its contents are ignored.
  
  Possible errors returned include the following:
  
  

  SS$_BADPARAM -- Thiserror indicates that the specified multicast address cannot be foundin the table.

The following example maps multicast address AB-01-01-01-02-03to the functional address 03-00-00-01-00-00 for device ICA0:.

LANCP>SET DEVICE/MAP= - _LANCP>(MULTICAST=AB-01-01-01-02-03, - _LANCP>FUNCTIONAL=00-01-00-00) ICA0:

The following example deletes the mapping of the multicastaddress of AB-01-01-01-02-03 for the device ICA0:.

LANCP>SET DEVICE/NOMAP=(MULTICAST=AB-01-01-01-02-03) ICA0:

IO$M_ROUTE Functional Modifier to IO$_SETMODE  

On Alpha systems using Token Ring only, the IO$M_ROUTE qualifier,when used with IO$_SETMODE, manipulates the source routing cachetable. This command is successful only when source routing is enabled. Sourcerouting is enabled with the set mac qualified set mode QIO. Format of the IO$M_ROUTE P2 Buffer (Alpha Only) shows the formatof the P2 buffer. This QIO requires the PHY_IO privilege.  

Figure 25  Format of the IO$M_ROUTE P2 Buffer (AlphaOnly)

The subfunction is one of the following:

• NMA$C_SR_ADD -- This functionadds or changes a source routing cache entry. It enters the LAN addressinto the table with the enclosed routing information. The routinginformation string format is documented in Token Ring Source Routing Header (Alpha Only). If RI_size is passed as 0, the entry is created(or modified) to be in the EXPLORING state (this is useful for userswho are doing their own source routing). If the RC 'Lth' field is0, the LAN address is entered in the table as being in the localstate.
  
  Possible errors returned include:
  
  

  SS$_INSFMEM -- Thesource routing cache is full.

  SS$_BADPARAM -- An invalid RI string waspassed or invalid sizes were passed.

  SS$_IVMODE -- Source routing is not enabled.




• NMA$C_SR_DELETE -- This function deletesa source routing cache entry. The RI_size and the routing informationstring are not required for this QIO. If one or both of the fieldsare passed for this operation, they are ignored. The result of thiscommand is to put the entry into the deleted state. When the entry goesinto the deleted state, it is deleted within 10 minutes.
  
  Possible errors returned include the following:
  
  

  SS$_BADPARAM -- Therequested entry could not be found.

Sense Mode and Sense Characteristics  

The sense mode functionreturns the port attributes in the specified buffers. These attributesinclude the device characteristics described in LAN Device Information and, with the exceptions noted below,the attributes listed in P2 Attributes.

The following combinations of function code and modifier areprovided:

• IO$_SENSEMODE!IO$M_CTRL--Readcharacteristics



• IO$_SENSECHAR!IO$M_CTRL--Read characteristics



• IO$_SENSEMODE!IO$M_SENSE_MAC--Medium specificcharacteristics

On Alpha systems, the following combinations of function codeand modifier for Token Ring are provided:

• IO$_SENSEMODE!IO$M_SHOW_MAP--Returnscurrent functional address to multicast address mapping



• IO$_SENSEMODE!IO$M_SHOW_ROUTE--Returns currentsource routing cache table

These functions take the following device- or function-dependentarguments:

• P1--The address of a two-longwordbuffer where the device characteristics are stored. (Sense Mode P1 Characteristics Buffer shows the format for, and LAN Device Information describes the contentsof, the P1 buffer.) The P1 argument is optional.



• P2--The address of a quadword descriptorwhere the attributes buffer is stored. The first longword of the descriptoris the buffer length; the second longword is the address of thebuffer. The P2 argument is optional.
  
  The P2 buffer is not read by the LAN driver. The driver storesthe port's attributes in the buffer, which contains multiple entries.The format of each entry depends on whether a longword or a countedstring is returned, as shown in Sense Mode Attribute Buffer. Each parameter ID contains a string indicator bit (bit12) that describes whether the data item is a string or a longword.

Except for the following differences, P2 returns the sameattributes as those listed in P2 Attributes:

• All parameters that are valid forthe enabled packet format are returned (see Set Mode Parameters for Packet Formats).



• The sense-mode P2 buffer does not return the modifierword for the NMA$C_PCLI_PHA, NMA$C_PCLI_MCA, and NMA$C_PCLI_DESparameter IDs.



• The NMA$C_PCLI_DES parameter is only returned onEthernet ports whose access mode is set to "shared withdestination."



• In addition to the parameter IDs listed in P2 Attributes, the sense-mode P2buffer contains the following parameter IDs:⁸

Parameter ID	Meaning
NMA$C_PCLI_FCA	List of the currently enabledfunctional addresses (Token Ring only). Each 32-bit entry correspondsrespectively with the items returned under NMA$C_PCLI_MCA.
NMA$C_PCLI_HWA	Hardware address. Describes the value for the hardwareaddress. The hardware address is the default physical address whenno physical address has been specified and there are no active userson the controller. NMA$C_PCLI_HWA is returned in the same formatas NMA$C_PCLI_PHA.
NMA$C_PCLI_MBS	Maximum packet length. NMA$C_PCLI_MBSis a longword, read-only parameter. The value returned reflectsthe largest data packet that the application can receive for itspacket format and type of LAN, measured in bytes. The values forCSMA/CD, FDDI, and Token Ring are:

Packet Format	CSMA/CD	FDDI	Token Ring
Ethernet formatwithout padding	1500	4470	4418
Ethernet formatwith padding	1498	4468	4416
802 formatwith 1-byte CTL field	1497	4475	4423
802E format	1492	4470	4418
On Alpha systems,the values for LAN emulation over ATM are:
PacketFormat	ATM ELAN size:	1516	4544	9234
Ethernet format without padding		1500	4528'	9218
Ethernet format with padding		1498	4526	9216
802 format with 1-byte CTL field		1497	4525	9215
802E format		1492	4520	9210

Figure 26  Sense Mode P1 Characteristics Buffer

It is suggested that a size of 250 bytes be used for the P2buffer. This will allow space for additional parameters that maybe returned in future releases of OpenVMS.

All attributes that fit into the buffer specified by P2 arereturned; however, if all the attributes cannot be stored in thebuffer, the I/O status block returns the status SS$_BUFFEROVF. The secondword of the I/O status block contains the number of bytes used inthe P2 buffer (see I/O Status Block).  

Figure 27  Sense Mode Attribute Buffer

IO$M_SENSE_MAC FunctionalModifier to IO$_SENSEMODE  

The IO$M_SENSE_MAC qualifier, when used with IO$_SENSEMODE,returns the parameters specified in IO$M_SET_MAC Functional Modifier to IO$M_SETMODE. In addition to the set mac parameters, Parameters of IO$M_SENSE_MAC shows the returns ofthe following parameters:

Table 45   Parameters of IO$M_SENSE_MAC

Parameter ID	Meaning
NMA$C_PCLI_T_NEG	The negotiated value ofthe token rotation timer (ANSI MAC parameter T_neg) (FDDI only).
NMA$C_PCLI_DAT	The duplicate address testflag (FDDI only). If set, this indicates that there is another stationon the ring with the same hardware LAN address.
NMA$C_PCLI_UNA	Upstream neighbor's address(FDDI and Token Ring). This is a string parameter specifying the6-byte LAN address of the upstream neighbor. Not all devices maysupport this feature.
NMA$C_PCLI_OLD_UNA	The old (previous) upstreamneighbor address (FDDI only). Neighbor addresses change as nodesinsert and deinsert into the ring.
NMA$C_PCLI_UN_DAT	The upstream neighbor'sduplicate address test flag (FDDI only).
NMA$C_PCLI_DNA	The downstream neighbor'sLAN address (FDDI only).
NMA$C_PCLI_OLD_DNA	The old (previous) downstreamneighbor's LAN address (FDDI only).
NMA$C_PCLI_RPS	The current ring purgerstate (FDDI only). This longword parameter is one of the followingvalues: 0 -- Off 1 -- Candidate 2 -- Non-purger 3 -- Purger
NMA$C_PCLI_RER	The latest ring error reason(FDDI only). This longword parameter is one of the following values: 0 -- No Error 5 -- Ring Init initiated 6 -- Ring Init received 7 -- Ring beaconing initiated 8 -- Duplicate address detected 9 -- Duplicate token detected 10 -- Ring purger error 11 -- FCI strip error 12 -- Ring op oscillation 14 -- PC trace initiated 15 -- PC trace received
NMA$C_PCLI_NBR_PHY	Neighbor's PHY type (FDDIonly). This longword parameter is one of the following values: 0 -- A 1 -- B 2 -- S 3 -- M 4 -- Unknown
NMA$C_PCLI_RJR	Ring reject reason (FDDIonly). This longword parameter is one of the following values: 0 -- None 1 -- Local LCT 2 -- Remote LCT 3 -- LCT both sides 4 -- LEM reject 5 -- Topology error 6 -- Noise reject 7 -- Remote reject 8 -- Trace in progress 9 -- Trace received-disabled 10 -- Standby 11 -- LCT protocol error
NMA$C_PCLI_LEE	Link error estimate (FDDIonly). The longword value is a negative exponent of 10 representingthe Link error rate. For example, the value of X represents theerror rate of 10^X.
NMA$C_PCLI_RNG_NUM	The longword value contains the ringnumber that the controller is running on (Token Ring only). It isonly valid for a controller that is started, and also only validfor rings that have a ring parameter server that is configured forproviding this information.

IO$M_SHOW_MAP Functional Modifier to IO$_SENSMODE  

On Alpha systems using Token Ring only, the IO$M_SHOW_MAPqualifier, when used with IO$_SENSEMODE, returns the current settingof the mapping table. The P2 buffer is filled with the current multicastto functional address mapping information. The entries are 16 byteslong and are in the format shown in Format of IO$M_SHOW_MAP P2 Buffer. This QIO requires PHY_IO privilege.  

Figure 28  Format of IO$M_SHOW_MAP P2 Buffer

The multicast address and functional address mask are returnedin canonical format (that is, not bit-reversed). The following errorsmay occur:

• SS$_BUFFEROVF -- The passedbuffer is not large enough to hold all the data required for the operation.



• SS$_BADPARAM -- Not able to get read accessto buffer or zero length buffer passed.

IO$M_SHOW_ROUTE FunctionalModifier to IO$_SENSEMODE  

On Alpha systems with Token Ring only, the IO$M_SHOW_ROUTEqualifier, when used with IO$_SENSEMODE, returns the current valueof the source routing cache table. Each entry is 64 bytes long. Format of IO$M_SHOW_ROUTE P2 Buffer (Alpha Only) showsthe format of the returned P2 buffer.  

Figure 29  Format of IO$M_SHOW_ROUTEP2 Buffer (Alpha Only)

State of the Entry shows possiblestates of the entry.

Table 46   State of the Entry

Value	Name	Description
0	LOCAL	Address is reachable onthe attached ring.
1	STALE	Entry is stale (inactive).
2	UNKNOWN	Route to the address isunknown.
3	DELETED	Entry is marked for deletion.
4	KNOWN	Route is known and the routeis stored in the routing information string.
5	EXPLORING	Route to the address is currently beingexplored.

The LAN address is returned in canonical format (that is,not bit-reversed). The timers are recorded as seconds before expiration.The transmit and receive timers are initialized from the NMA$C_PCLI_A_TIM parameter,the discovery timer is initialized from the NMA$C_PCLI_ROUTEDISparameter, and the stale timer is initialized to 10 minutes (600seconds). The following errors may occur:

• SS$_BUFFEROVF -- The passedbuffer is not large enough to hold all the data required for the operation.



• SS$_BADPARAM -- Not able to get read accessto buffer or zero length buffer passed.

1	V= virtual,L=logical, P=physical ( There is no function difference in theseoperations.)

2	On OpenVMS Alpha, P1 and P5 support 64-bitaddresses.

3	On OpenVMS Alpha, P1, P4, and P5 support 64-bit address.

4	The P1 and P3 arguments are only for attentionAST QIOs.

5	Alpha specific.

6	Alphaspecific.

7	If the LAN controller is active and youdo not specify this parameter, the parameter defaults to currentsetting. If the LAN controller is not controller is not active,this parameter defaults to the default value indicated.

8	Alpha specific.

( Number takes you back )

LAN Device Information

I/O Status Block