HP OpenVMS Systems Documentation

OpenVMS I/O User's Reference Manual

9.16.1 Read

Read functions directly transfer data from a packet received fromanother port on the Ethernet into the virtual memory address space ofthe user process. The operating system provides the following functioncodes:

IO$_READLBLK---Read logical block
IO$_READVBLK---Read virtual block
IO$_READPBLK---Read physical block

Received messages are buffered in system memory and then copied to theuser's buffer when a read operation is performed.

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

P1---The starting virtual address of 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 LAN driver returns packet header information. This is an optional argument. The information returned depends on the packet format enabled with the set mode QIO. The size of the buffer must be 14 bytes for an Ethernet format packet, 16 bytes for an IEEE 802 format packet, and 20 bytes for an 802 extended format packet. Note that the information returned is not the entire packet header but the header information less any length or size fields. The IOSB, if specified, is where the packet length information is returned. For FDDI, if received access control (RAC) is on, then 1 byte must be added to these sizes.
On Alpha systems, Token Ring requires that this buffer be at least 54 bytes long due to a possible variable length source routing header.
If NMA$C_PCLI_PRM (see Table 9-16) is enabled, the P5 buffer must be at least 20 bytes for CSMA/CD and 21 bytes for FDDI. Figure 9-21 shows the format of the three buffers. On OpenVMS Alpha systems, P5 can be a 64-bit address.

Figure 9-21 Read Function P5 Buffer

The P1 and P2 arguments must always be specified; the P5 argument isoptional. However, if P5 is not specified, you will be unable todetermine the source of the received message.

If the size of the user data in a receive message is larger than thevalue of the NMA$C_PCLI_BUS parameter, the message is not given to theuser, even if there is sufficient space in the user's receive buffer.

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

Table 9-12 lists the maximum user data sizes that can be receivedfor CSMA/CD, FDDI, and Token Ring protocols.

**Table 9-12 Maximum User Data Sizes for CSMA/CD, FDDI, and Token Ring**
Packet Format	CSMA/CD	FDDI	++Token Ring
Ethernet format without padding	1500	4470	++4418
Ethernet format with padding	1498	4468	++4416
802 format with 1-byte CTL field	1497	4475	++4423
802 format with 2-byte CTL field	1496	4474	++4422
802E format	1492	4470	++4418

++Alpha specific.

On Alpha systems, Table 9-13 lists the maximum user data sizes thatcan be received for LAN emulation over ATM protocol.

**Table 9-13 Maximum User Data Sizes for LAN Emulation over ATM (Alpha Only)**
Packet Format	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
802 format with 2-byte CTL field	1496	4524	9214
802E format	1492	4520	9210

For 802 format packets, the P5 buffer always contains the DSAP and SSAPin the bytes at offset 12 and 13. The next one or two bytes (offsets 14and 15) following the SSAP contain the control field value. For Class Iservice, the control field value is always 1 byte in length and willalways be placed in the byte at offset 14 of this buffer. Foruser-supplied service, you have to determine the length of the controlfield value according to the IEEE 802.2 Standard.

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

For FDDI, if RAC is on, the first byte of the P5 buffer contains the FCfield.

The read functions can take the following function modifier:

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

9.16.2 Write

Write functions provide for the direct transfer of data from thevirtual memory address space of the user process to the communicationsmedium. The operating system provides the following function codes:

IO$_WRITELBLK---Write logical block
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 address of the buffer containing the data to be transmitted. On OpenVMS Alpha systems, P1 can be a 64-bit address.
P2---The size of the buffer in bytes.
P4---The address of a quadword that points to a buffer that contains the DSAP and CTL field values (optional). (See Section 9.14.2.3.) The first longword is the buffer length; the second longword is the address of the buffer. This argument is used only for ports with the 802 packet format. 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 that contains the destination address (either physical or multicast). For FDDI, if XFC is specified as zero on startup, the first byte of the P5 buffer contains the low-order 3 bits of the FC field to be transmitted. On OpenVMS Alpha systems, P5 can be a 64-bit address.
If the device is in promiscuous mode (NMA$C_PCLI_PRM; see Table 9-16), you must pass a larger buffer with additional information positioned after the destination address. For Ethernet packet format, the buffer must be 8 bytes with the 2-byte protocol type following the destination address. For 802 packet format, the buffer must be 7 bytes with the 1-byte source SAP following the destination address. For 802 extended packet format, the buffer must be 11 bytes with the 5-byte protocol identifier following the destination address. The individual Source SAP cannot be a group SAP or the SNAP SAP. Figure 9-22 shows the format of the P5 buffer. For FDDI with XFC specified as zero on startup, 1 byte must be added to these sizes for the FC field.

Figure 9-22 Write Function P5 Buffer

Table 9-14 lists the maximum user data sizes that can be specifiedby P2 and received for CSMA/CD, FDDI, and Token Ring protocols.

**Table 9-14 Maximum Message Sizes for CSMA/CD, FDDI, and Token Ring**
Packet Format	CSMA/CD	FDDI	++Token Ring
Ethernet format without padding	1500	4470	++4418
Ethernet format with padding	1498	4468	++4416
802 format with 1-byte CTL field	1497	4475	++4423
802 format with 2-byte CTL field	1496	4474	++4422
802E format	1492	4470	++4418

++Alpha specific.

On Alpha systems, Table 9-15 lists the maximum user data sizes thatcan be specified by P2 and received for LAN emulation over ATMprotocol.

**Table 9-15 Maximum Message Sizes for LAN Emulation over ATM (Alpha Only)**
Packet Format	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
802 format with 2-byte CTL field	1496	4524	9214
802E format	1492	4520	9210

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

If the P4 buffer is specified, it must be at least 3 bytes long. Thefirst byte is always the DSAP; the next 2 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. If the twoleast significant bits of the low-order byte of the CTL field containthe bit values 11, just the low-order byte of the CTL field is used asthe CTL field value. Otherwise, both bytes of the CTL field are used asthe CTL field value.

If the driver uses only the low-order byte of the CTL field, you stillmust pass at least a 3-byte buffer. In this case, the driver uses thelow-order byte of the CTL field and ignores the high-order byte.

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

Regarding 802 ports, you can receive packets for the SAP enabled withthe IO$_SETMODE or IO$_SETCHAR QIOs and can transmit packets destinedfor a different SAP. This is similar to an Ethernet port receivingpackets for one protocol type and transmitting packets with a differentprotocol type (which is not possible with the current Ethernet $QIOinterface). It is expected that most 802 format applications will wantto process only receive packets from a source SAP that matches the SAPenabled on their port. To do this, the read function (seeSection 9.16.1) has been enhanced to return the source SAP to you. Toverify that the source SAP of an incoming packet matches the SAPenabled on the port, you need only match the source SAP returned by theread function with the SAP enabled on the port.

The write functions can take the following function modifier:

IO$M_RESPONSE---Transmit a response packet (sets the low-order bit in the SSAP field). This allows users with user-supplied service enabled to respond to certain 802 format command packets. IO$M_RESPONSE can be specified only when you have the 802 packet format enabled. The 802 packet format ports, with Class I service enabled, result in an error if you attempt to transmit a response message with a CTL field value of unnumbered information (UI).

9.16.3 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 are treatedthe same by the LAN drivers. This section refers to the IO$_SETMODEfunction code only, even though applications can use either functioncode.

The set mode function code is used to perform many different functions.These different functions are distinguished by the modifiers set withthe function code. The LAN drivers support the following set moderequests:

IO$_SETMODE!IO$M_CTRL---set or modify port attributes
IO$_SETMODE!IO$M_CTRL!IO$M_STARTUP---set port 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 attention AST

On Alpha systems, the LAN drivers also support the following set moderequests for Token Ring:

IO$M_SETMODE!IO$M_UPDATE_MAP---Update functional address mapping table
IO$M_SETMODE!IO$M_ROUTE--- Update source routing cache table

The following sections describe these functions in detail.

9.16.3.1 Set Controller Mode

Once a port is created using the $ASSIGN system service, you can setthe port attributes and start the port using the requests listed in theprevious section. Note that in most cases onlyIO$_SETMODE!IO$M_CTRL!IO$M_STARTUP is issued because it sets the portattributes and starts the port with one request. IO$_SETMODE!IO$M_CTRLis most often used to modify port attributes after the port has beenstarted.

If the function modifier IO$M_STARTUP is specified, the LAN port is started. If IO$M_STARTUP is not specified, the specifiedcharacteristics are modified.

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

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

The P2 buffer consists of a series of 6-byte or counted string entries.The first word of each entry contains the parameter identifier (ID) ofan attribute, followed by either a longword that contains one of the (binary) values that can be associated with theparameter ID or a counted string. Counted strings consist of a wordthat contains the size of the character string followed by thecharacter string. Figure 9-23 shows the format for this buffer.

Figure 9-23 P2 Extended Characteristics Buffer

Table 9-16 is an alphabetic listing of the parameter IDs and valuesthat can be specified in the P2 buffer. These parameter IDs areapplicable to all LAN controllers, except where otherwise noted. The$NMADEF macro defines these values. The $NMADEF macro is included inthe macro library SYS$LIBRARY:LIB.MLB. (Table 9-17 lists theparameters that can be used with each of the packet formats, andindicates which are required, which are optional, and which generatethe SS$_BADPARAM error.)

If the status SS$_BADPARAM is returned in the first word of the I/Ostatus block, the second longword contains the parameter ID of theparameter in error.

**Table 9-16 P2 Attributes**
Parameter ID	Meaning
NMA$C_PCLI_ACC	+Protocol access mode. This optional parameter determines the access mode for the protocol type. NMA$C_PCLI_ACC is valid only for ports using Ethernet packet format. ++NMA$C_PCLI_ACC is valid for ports using Ethernet and 802E. One of the following values can be specified: NMA$C_ACC_EXC --- Exclusive mode (default) NMA$C_ACC_SHR --- Shared-default user mode NMA$C_ACC_LIM --- Shared-with-destination mode +Section 9.14.1.3 provides a description of protocol type sharing. ++Section 9.14.3.1 provides a description of protocol type PID sharing. NMA$C_PCLI_ACC is passed as 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. This optional parameter is specified on a per-port basis. NMA$C_PCLI_BFN is passed as a longword value. NMA$C_PCLI_BFN represents the number of receive messages the LAN driver will hold for a port when the port has no read QIOs posted to the driver.
NMA$C_PCLI_BUS	Maximum allowable port receive data size, that is, message length (default = 512 bytes). NMA$C_PCLI_BUS can have a maximum value of 9234. This optional parameter is specified on a per-port basis. It is passed as a longword value. Any message received for this port that is larger than this parameter value is discarded.
NMA$C_PCLI_CCA	Can change address. This optional parameter enables applications to start before DECnet starts. DECnet may attempt to set the physical address of the controller when it starts. CSMA/CD devices support only one physical address, and so all applications that are using the same device must also use the same physical address. If applications that do not use the DECnet address start before DECnet, DECnet is not able to start on that controller unless the other applications that have already started have all specified NMA$C_PCLI_CCA to be ON. This parameter is not applicable to FDDI because FDDI devices can run with more than one physical address. However, no error is returned if this parameter is supplied for FDDI devices. The application receives no indication whatsoever that the physical address has changed. This parameter is passed as a longword. One of the following values can be specified: NMA$C_STATE_ON --- The physical address can be changed. NMA$C_STATE_OFF --- The physical address cannot be changed (default).
NMA$C_PCLI_CON ¹	Controller mode. This optional parameter determines whether transmit packets are to be looped back at the controller. One of the following values can be specified: NMA$C_LINCN_NOR --- Normal mode (default) NMA$C_LINCN_LOO --- Loopback mode The only messages looped back are those acceptable to the controller as receive messages, that is, those messages that possess at least one of the following characteristics: Matching physical address (see Section 9.9) Matching multicast address (see Section 9.9) Promiscuous mode (NMA$C_PCLI_PRM) is in the ON state Destination address is a multicast address and all multicasts are enabled (NMA$C_PCLI_MLT is in the ON state) NMA$C_PCLI_CON affects all ports on a single controller. It is passed as a longword value. For the DELUA, DEBNA, DEBNI, DEQTA, PMAD, DEMNA, and DESVA, the following list shows the maximum amount of user data that can be looped: Ethernet format without padding --- 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 loopback mode, the driver always enables echo mode (NMA$C_PCLI_EKO is in the ON state). Not all 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) generation state for transmitted messages (optional). One of the following values can be specified: NMA$C_STATE_ON --- Controller generates a CRC (default). NMA$C_STATE_OFF --- Controller does not generate a CRC. NMA$C_PCLI_CRC affects all ports on a single controller. There is no effect on checking a receive message's CRC (it is always checked). NMA$C_PCLI_CRC is passed as a longword value. If NMA$C_PCLI_CRC is turned off, all users of the controller must supply the 4-byte CRC value for all messages transmitted. The CRC is passed at the end of the P1 transmit buffer; the additional 4 bytes are included in the size of the P1 buffer. The CRC value is not checked for correctness. For the DEQNA, the DELQA, and the Token Ring devices, the NMA$C_PCLI_CRC parameter cannot be turned off. Not all devices support user-supplied CRC. If a controller generated CRC is specified, the request is completed 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_SET or 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_DES only has meaning when protocol access (NMA$C_PCLI_ACC) is defined as shared-with-destination mode (NMA$C_ACC_LIM). The destination address specified must be a physical address---not a multicast address---and it must be unique among all ports sharing the same protocol. NMA$C_PCLI_DES is required when the access mode is defined as "shared-with-destination." +NMA$C_PCLI_DES should not be specified on a port where the 802 or 802E packet format is 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 handled by using group SAPs. ++NMA$C_PCLI_DES should not be specified on a port where the 802 packet format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_802). For 802 packet format, the concept of shared protocol type is handled by using group SAPs. +Section 9.14.1.3 provides a description of protocol type sharing. ++Section 9.14.3.1 provides a description of protocol type PID sharing.
NMA$C_PCLI_EKO ¹	Echo mode. Applicable only to the DEUNA device driver. If echo mode is on, transmitted messages are returned to the sender. This optional parameter controls the condition of the half-duplex bit in the DEUNA mode register. One of the following values can be specified: NMA$C_STATE_ON --- Echoes transmit messages NMA$C_STATE_OFF --- Does not echo transmit messages (default) If NMA$C_STATE_ON is specified, the only transmitted messages echoed are those acceptable to the DEUNA as receive messages, that is, those messages that have at least one of the following characteristics: Matching physical address (see Section 9.9) Matching multicast address (see Section 9.9) Promiscuous mode (NMA$C_PCLI_PRM) is in the ON state Destination address is a multicast address and all multicasts are enabled (NMA$C_PCLI_MLT is in the ON state) If the DEUNA is placed in loopback mode (NMA$C_LINCN_LOO is specified in the NMA$C_PCLI_CON parameter), the driver enables echo mode. NMA$C_PCLI_EKO affects all ports on a single controller. It is passed as a longword value.
NMA$C_PCLI_FMT	Packet format. This optional parameter specifies the packet format as either Ethernet, IEEE 802, or 802 extended. This characteristic is passed as a longword value and affects single ports on a single controller. One of the following values can be specified: NMA$C_LINFM_ETH --- Ethernet packet format (default) NMA$C_LINFM_802 --- 802 packet format NMA$C_LINFM_802E --- 802 extended packet format NMA$C_PCLI_PTY, NMA$C_PCLI_ACC, and NMA$C_PCLI_DES should only be specified on those ports where the 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 those ports where the 802 packet format (NMA$C_LINFM_802) is selected. NMA$C_PCLI_PID should only be specified on those ports where the 802 extended packet format (NMA$C_LINFM_802E) is selected.
NMA$C_PCLI_GSP	Group SAP. This is an optional parameter if 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 cannot be specified. Group SAPs can be shared among multiple ports on the same controller. If the 802 packet format is selected, NMA$C_PCLI_GSP defines up to four 802 group SAPs that are to be enabled for matching incoming packets to complete read operations on this port. By default, no group SAPs are enabled. NMA$C_PCLI_GSP is passed as a longword value and is read as four 8-bit unsigned integers. Each integer must be either a group SAP or zero. To enable a single group SAP on a port, you need only specify the group SAP value to be enabled in one of the four integers and place a value of zero in the three remaining integers. To disable group SAPs on the port, you need only place a value of zero in all four integers and issue the QIO. If this characteristic is correctly specified, any group SAPs that were previously enabled on the port are now replaced by the SAPs specified by the current request.
NMA$C_PCLI_ILP ¹	Internal loopback mode. This optional parameter places the device in internal loopback mode (not for the DEUNA, DEQNA, or DELQA devices). One of the following values can be specified: NMA$C_STATE_ON --- Internal loopback 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 (generally for testing), it can loop packets in external loopback or internal loopback. This parameter places the controller in one of these loopback modes. NMA$C_PCLI_ILP is passed as a longword value and affects all ports on the controller. Not all devices support loopback mode. If NMA$C_STATE_OFF is not specified, the request is completed with SS$_BADPARAM status.
NMA$C_PCLI_MCA	Multicast address (optional). Passed as a counted string that consists of a modifier word followed by a list of 6-byte (48-bit) multicast addresses. The value specified in the modifier word determines whether the addresses are set or cleared. If NMA$C_LINMC_CAL is specified, all multicast addresses in the list are ignored. The following mode values can be 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 multicast addresses on a per-port basis. Therefore, only messages received with the port's physical address or the multicast addresses enabled on the port are used to complete the user's read operations. Note that each LAN controller supports a limited number of multicast addresses. If this limit is exceeded, the LAN driver enables the "accept all multicast" feature on the controller and all multicast packets on the LAN must be filtered by the LAN driver. This may cause a minor performance loss. NMA$C_PCLI_MCA is specified on a per-port basis.
NMA$C_PCLI_MLT	Multicast address state. This optional parameter instructs the controller hardware whether to accept all multicast addresses for this port. One of the following values can be specified: NMA$C_STATE_ON --- Accept all multicast addresses. NMA$C_STATE_OFF --- Do not accept all multicast addresses (default). NMA$C_PCLI_MLT can be enabled on more than one port. It only affects those ports on which it is enabled. NMA$C_PCLI_MLT allows you to receive all multicast address packets that also match the port's protocol type, SAP, or protocol identifier. Generally, you enable only your individual set of multicast addresses using the NMA$C_PCLI_MCA parameter, and leave the NMA$C_PCLI_MLT parameter in the off state. There could be a minor performance loss when the NMA$C_PCLI_MLT parameter is in the ON state because the LAN driver may have to process all multicast addresses on the medium; the number of multicast addresses on the line determines the amount of processing required. The NMA$C_PCLI_MLT parameter is passed as a longword value.
NMA$C_PCLI_PAD	Use message size field on transmit and receive messages (optional). One of the following values can be specified: NMA$C_STATE_ON --- Insert message size field (default) NMA$C_STATE_OFF --- No size field NMA$C_PCLI_PAD affects only the protocol type that issued the set mode request. It is passed as a longword value. On CSMA/CD, if padding is enabled on Ethernet format packets, the driver adds a 2-byte count field to the transmitted data. This field allows short packets (packets fewer than 46 bytes long) to be received with the proper length returned by the driver. The minimum Ethernet packet contains 46 bytes of user data. When fewer than 46 bytes are sent, the packet is padded and the receiver always receives 46 bytes of data. When padding is enabled, the maximum message size for transmit or receive operations is 1498 bytes and the minimum is zero bytes. See Section 9.14.1.2 for additional information. NMA$C_PCLI_PAD should be specified only on a port where the Ethernet packet format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_ETH). For FDDI, the same 2-byte count field is added. However, because FDDI packets can be as short as 22 bytes, FDDI transmit requests are never padded.
NMA$C_PCLI_PHA ¹	Physical address (optional). It is passed as a counted string that consists of a modifier word followed by the 48-bit physical address. If the request is to clear the physical address or to set the physical address to the default address, the physical address (if present) is not read. One of the following mode values can be specified in the low byte of the modifier word: NMA$C_LINMC_SET --- Set the string value. NMA$C_LINMC_CLR --- Clear the physical address. NMA$C_LINMC_SDF --- Set the physical address to the default address. For CSMA/CD, the default address is constructed by appending the low-order word of the system parameter SCSSYSTEMID to the constant DECnet header (AA-00-04-00). If SCSSYSTEMID is zero, and NMA$C_LINMC_SDF is specified, the hardware address is used as the default. For FDDI, the default address is the hardware address. If not specified for CSMA/CD, the default is the current address set by a previous set mode function on this controller, or the hardware address if no address was defined by a previous set mode function. If not specified for FDDI, the default is the hardware address. The physical address must be passed as a 6-byte (48-bit) quantity. The first byte is the least significant byte. A return value of -1 on a sense mode request implies that a physical address is not defined. The NMA$C_PCLI_PHA parameter affects all ports on a single controller. If the address specified is already being used on the extended LAN, SS$_IVADDR is returned.
NMA$C_PCLI_PID	Protocol identifier. This parameter is required for, and valid only on, ports that use 802 extended format packets. NMA$C_PCLI_PID is passed as a counted 5-byte string, which is the unique protocol identifier required for each 802 extended format user. All protocol identifiers specified on a controller must be unique except when the PID is being shared. NMA$C_PCLI_PID may only be specified on a port when the 802 extended packet format is selected; that is, NMA$C_PCLI_FMT is set to NMA$C_LINFM_802E.
NMA$C_PCLI_PRM	Promiscuous mode (optional). One of the following values can be specified: NMA$C_STATE_ON --- Promiscuous mode enabled NMA$C_STATE_OFF --- Promiscuous mode disabled (default) Only one port on each controller can be active with promiscuous mode enabled. Enabling promiscuous mode requires PHY_IO privilege. The NMA$C_PCLI_PRM parameter is passed as a longword value. Compaq does not recommend promiscuous mode for normal usage. Some Token Ring devices do not support real promiscuous access to the ring. See Section 9.18.1 for additional information.
NMA$C_PCLI_PTY	Protocol type. This value is read as a 16-bit unsigned integer and must be unique on the controller except when the protocol type is being shared. For Ethernet format ports, this is a required parameter. Valid protocol types are in the range 05-DD through FF-FF. NMA$C_PCLI_PTY may only be 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_PTY is passed as a longword value; however, only the low-order word is used.
++NMA$C_PCLI_RAC	Receive access control (Token Ring only). This optional parameter specifies whether the application receives a copy of the access control (AC) field for each Token Ring frame received. It is passed as a longword value. It must be passed with one of the following values: NMA$C_STATE_ON --- Application gets a copy of the AC for each Token Ring frame received. NMA$C_STATE_OFF --- Application does not get a copy of the AC for each Token Ring frame received. The AC is returned in the P5 buffer. The P5 buffer size for Token Ring should always be a minimum of 54 bytes. This is due to the variable size of the Token Ring header.
NMA$C_PCLI_RES	Restart. This optional parameter allows the user to enable the automatic port restart feature of the LAN drivers. One of the following values can be specified: NMA$C_LINRES_DIS --- Disable automatic restart (default) NMA$C_LINRES_ENA --- Enable automatic restart The LAN drivers shut down all users of a controller if there is a fatal error on the controller or if the LAN driver determines that the controller has stopped functioning. All outstanding I/O operations on the LAN driver are completed with either an SS$_ABORT or SS$_TIMEOUT status. All ports that have the NMA$C_PCLI_RES parameter enabled (set to NMA$C_LINRES_ENA) have the port automatically restarted by the LAN driver approximately one second after it has been shut down due to a fatal error. If the user issues read or write QIOs to the port during the time the port is shut down, the driver completes the QIOs with an SS$_OPINCOMPL status. All ports that have the automatic restart feature disabled must be restarted by the application program when the port is shut down by the LAN driver. The application program should wait approximately 2 seconds to allow the LAN driver to stabilize. Once the LAN driver shuts down a port, it attempts a maximum of 30 consecutive automatic restarts. If there are 30 consecutive failures to restart the port, the port remains shut down. Note that it is unusual to have fatal errors on a LAN controller or to have a LAN driver detect that a LAN controller has stopped functioning. Having the ability to automatically restart a user's port makes the program easier to design because the program does not have to take into account the possibility of the LAN driver shutting down the port.
NMA$C_PCLI_RFC	Receive frame control (FDDI only). This optional parameter specifies whether the application receives a copy of the Frame Control (FC) field for each FDDI frame received. It is passed as a longword value. However, only the low-order byte is used. It must be passed with one of the following values: NMA$C_STATE_ON --- Application gets a copy of the FC for each FDDI frame received. NMA$C_STATE_OFF --- Application does not get a copy of the FC for received FDDI frames (default). For $QIO Read operations, the FC is passed to the application in the P5 buffer. The following are the sizes required for the P5 buffer for various packet formats and settings of NMA$C_PCLI_RFC: Ethernet (NMA$C_LINFM_ETH) --- 14 if NMA$C_STATE_OFF is specified, 15 if NMA$C_STATE_ON is specified. 802 (NMA$C_LINFM_802) --- 16 if NMA$C_STATE_OFF is specified, 17 if NMA$C_STATE_ON is specified. 802E (NMA$C_LINKFM_802E) --- 20 if NMA$C_STATE_OFF is specified, 21 if NMA$C_STATE_ON is specified. Receiving the FC requires one additional byte of space in the P5 buffer. The FC is the first byte in the P5 buffer, immediately preceding the 6-byte destination address. The size of the P5 buffer required does not change from the CSMA/CD sizes if NMA$C_PCLI_RFC is set to NMA$C_STATE_OFF.
NMA$C_PCLI_SAP	802 format SAP. This parameter is required if the 802 packet format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_802). NMA$C_PCLI_SAP defines an 802 SAP and is read as an 8-bit unsigned integer. The least significant bit of the SAP must be zero and the SAP cannot be the null SAP (all 8 bits equal zero) or the SNAP SAP. NMA$C_PCLI_SAP is passed as a longword value. However, only the low-order byte is used. The SAP specified by NMA$C_PCLI_SAP is the SAP used to match incoming packets to complete read requests. It is used as the source SAP (SSAP) in all transmissions (write QIOs). Because it is illegal to transmit using a group SAP as the source SAP, the SAP specified by this NMA$C_PCLI_SAP cannot be a group SAP. NMA$C_PCLI_GSP describes how to set up group SAPs on a port. All individual SAPs specified on a controller must be unique on that controller. Therefore, the SAP specified using the NMA$C_PCLI_SAP parameter is checked for uniqueness on the controller.
++NMA$C_PCLI_SRMODE	Sets the source routing (SR) mode for the $QIO user (Token Ring only). This optional parameter allows the application to perform the source routing discovery. It must be passed with one of the following values: NMA$C_SR_TRANSPARENT --- Application source routing is transparent. This is the default when this parameter is not specifiied. NMA$C_SR_SELF --- This shuts off the automatic route discovery exploration messages for this user. The $QIOs exist to further manipulate the source routing cache. Compaq recommends that applications use the NMA$C_SR_TRANSPARENT mode.
NMA$C_PCLI_SRV	Port service. This optional parameter specifies the service supplied by the driver for the port. It can only be specified if the 802 packet format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_802). This characteristic is passed as a longword value. One of the following values can be specified: NMA$C_LINSR_USR --- User-supplied service (default) NMA$C_LINSR_CLI --- Class I service See Section 9.14.2.1 for a description of Class I service and Section 9.14.2.2 for a description of user-supplied service.
++NMC$C_PCLI_XAC	Transmit access control (Token Ring only). This is an optional parameter that enables applications to control the setting of the priority bits in the access control (AC) for frames being transmitted in a $QIO write operation. When set to the wamted 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 applications to control the setting of the priority bits in the FC for frames being transmitted in a $QIO write operation. NMA$C_PCLI_XFC is passed as a longword parameter that has many valid settings. If specified with a value of zero, the application supplies an FC value on each $QIO write operation. The FC value to be used in this case is supplied in the P5 buffer for the $QIO write operation. If the parameter is specified with a value other than zero, that value is inserted into the FC field of every transmit by the FDDI drivers. No FC is present in the P5 buffer for the $QIO write in this case. If this parameter is not specified, the default setting (zero) of the priority bits is used. Regardless of how the FC is supplied, the value specified must be valid. The allowable values for FC are between 50 hexadecimal and 57 hexadecimal. If NMA$C_PCLI_XFC is specified with a nonzero value outside the valid range, the application receives a SS$_BADPARAM error. The priority bits are the three low-order bits.

¹If the LAN controller is active and you do not specify thisparameter, the parameter defaults to the current setting. If the LANcontroller is not active, this parameter defaults to the default valueindicated.
++Alpha specific.
+VAX specific.

Contents

Index