Document revision date: 30 March 2001

## OpenVMS I/O User's Reference Manual

Previous | Contents | Index

#### 9.16.3.2 Set Mode Parameters for Packet Formats

Table 9-17 summarizes the use of the set mode parameters for the Ethernet, 802, and 802 extended (802E) packet formats.

Table 9-17 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

++Alpha specific.
+VAX specific. On Alpha systems, however, the ACC and DES parameters are OPT.

Legend

> DEF---Default. If not specified, this is the default parameter for this packet format.
> REQ---Required. This parameter must be specified for this packet format.
> OPT---Optional. This parameter is optional for this packet format; it may be specified.
> E---Error. This parameter cannot be specified for this packet format. If the parameter is specified, it generates an SS $ _BADPARAM error.

#### 9.16.3.3 Set Mode Parameter Validation

When starting a LAN port, the LAN driver checks that the mode of the new port is compatible with the mode of the LAN ports already started. There are two sets of compatibility checks: one for ports running in shared mode and one for all ports.

The following parameters must match for all ports on the same controller:

> 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 all shared-default and shared-with-destination users of the same protocol type:

> 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 can be changed:

> NMA$C_PCLI_GSP
> NMA$C_PCLI_MCA

#### 9.16.3.4 Shutdown Controller

The shutdown controller function shuts down the LAN port. On completion of a shutdown request all outstanding I/O requests are completed. This port cannot be used again until another startup request has been issued (see Section 9.16.3.1).

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

> IO$_SETMODE!IO$M_CTRL!IO$M_SHUTDOWN---Shut down port

The shutdown controller function takes no device- or function-dependent arguments.

#### 9.16.3.5 Enable Attention AST

This function requests that an attention AST be delivered to the requesting process when a status change occurs on the assigned port. An AST is queued when a message is available and there is no waiting read request. The enable attention AST function is legal at any time, regardless of the condition of the unit status bits.

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

- IO$_SETMODE!IO$M_ATTNAST---Enable attention AST

This function takes the following device- or function-dependent arguments:

- P1---The address of an AST service routine or 0 for disable
- P2---Ignored
- P3---Access mode to deliver AST

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

The AST service routine is called with an argument list. The first argument is the current value of the second longword of the I/O status block (see Section 9.17).

#### 9.16.3.6 IO$M_SET_MAC Functional Modifier to IO$M_SETMODE

The IO$M_SET_MAC qualifier, when used with IO$_SETMODE, is used to set medium specific parmeters. The Token Ring parameters require PHY_IO privilege to set. Table 9-18 shows the parameters that may be set for Ethernet. Table 9-19 shows the parameters that may be set for FDDI. Table 9-20 shows the parameters that may be set for Token Ring, and Table 9-21 shows the parameters that may be set for ATM.

Table 9-18 Medium Specific Parameters of IO$M_SET_MAC for Ethernet (Alpha Only)
Parameter ID | Meaning
--- | ---
MA$C_PCLI_FDE | Enables or disables full duplex operation. The values for this parameter are NMA$C_STATE_ON or NMA$C_STATE_OFF.
NMA$C_PCLI_LINEMEDIA | Sets the connection media type 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 mbits/sec. 100--Sets the speed to 100 mbits/sec. 65636--Used to autonegotiate with a maximum speed of 100 mbits/sec. 65546--Used to autonegotiate with a maximum speed of 10 mbits/sec.

Table 9-19 Medium Specific Parameters of IO$M_SET_MAC for FDDI
Parameter ID | Meaning
--- | ---
NMA$C_PCLI_TREQ | Requested value for token rotation timer, ANSI MAC T_req parameter. Units are in 80 nanoseconds, default is 8000, minimum is 4000, and maximum is 167772.
NMA$C_PCLI_TVX | Maximum time between arrivals of a valid frame or unrestricted token, ANSI MAC TVX parameter. Units are in 80 nanoseconds, default is 2621, minimum is 2500, and maximum is 5222.
NMA$C_PCLI_REST_TTO | Restricted token timeout which limits how long a single restricted mode dialog may last before being terminated. Units are in milliseconds, 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 frame target.
NMA$C_PCLI_SIF_CONF_TARG | Station information frame configuration target. A 6-byte string specifying the LAN address of the target. Used only by DECnet/OSI.
NMA$C_PCLI_SIF_OP_TARG | Station information frame operation target. A 6-byte string specifying the LAN address of the target. Used only by DECnet/OSI.
NMA$C_PCLI_ECHO_TARG | Echo test target. A 6-byte string specifying the LAN address of the target. Used only by DECnet/OSI.
NMA$C_PCLI_ECHO_DAT | Data pattern to use for the echo test. Used only by DECnet/OSI.
NMA$C_PCLI_ECHO_LEN | Length of the echo packet. Used only by DECnet/OSI.

Table 9-20 Medium Specific Parameters of IO$M_SET_MAC for Token Ring (Alpha Only)
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 Mbps rings. NMA$C_LINRNG_SIXTN---Used for 16 Mbps rings. The default is NMA$C_LINRNG_SIXTN.
NMA$C_PCLI_LINEMEDIA | Sets the connection media type for the Token Ring adapter. Valid values for this longword parameter are: NMA$C_MEDIA_STP NMA$C_MEDIA_UTP The default is NMA$C_MEDIA_STP.
NMA$C_PCLI_ETR | Controls the Early Token release feature of the Token Ring hardware. This feature can greatly improve throughput, and is only valid on 16 Mb/s rings. The values for 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 controller participates in the monitor contention process when another adapter detects the need for contention and initiates the process. The values for 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 64 bytes.
NMA$C_PCLI_ROUTEDIS | The source routing discovery timer. This is the amount of seconds to wait after the transmission of ring explorer packets before declaring the route of a path to be unknown. The default is 2 seconds, minimum is 1, and maximum is 255.
NMA$C_PCLI_A_TIM | The source routing aging timer. After traffic is neither received from nor sent to a given node for this number of seconds, the entry is marked stale. After the entry is marked stale, rediscovery is required to communicate with the node. The default is 60 seconds, minium is 1, and maximum is 65535.
NMA$C_PCLI_SRC_ROU | Enables and disables source routing. The values for this longword parameter are NMA$C_LINSRC_ENA or NMA$C_LINSRC_DIS. The default is NMA$C_LINSRC_ENA.
NMA$C_PCLI_AUTH_PR | Specifies the highest priority that a user may transmit a frame. The priority is set within the NMA$C_PCLI_XAC parameter. The default for this parameter is 3, minimum is 0, and maximum is 6.

Table 9-21 Medium Specific Parameters of IO$M_SET_MAC for ATM (Alpha Only)
Parameter ID | Meaning
--- | ---
NMA$C_PCLI_MED | Medium. This longword parameter defaults to and may only be set to NMA$C_LINMD_CSMACD.
NMA$C_PCLI_BUS | Buffer size. This longword parameter specifies the requested maximum packet size of the emulated LAN. The value may be either 1516, 4544, or 9234.
NMA$C_PCLI_ELAN_PAR | Parent device name. This is a 3 or 4 character long string parameter which specifies the name of the ATM device to associate with this emulated LAN.
NMA$C_PCLI_NET | ELAN name. This is a string up to 64 characters long which specifies the name of the emulated LAN to join.
NMA$C_PCLI_ELAN_DESC | ELAN description. This is a string up to 64 characters long which provides additional description of the eumulate LAN for status displays.
NMA$C_PCLI_LES_HWA | LES ATM address. This is specified as a 40 character string as the hexadecimal representation of a 20 byte ATM address.
NMA$C_PCLI_ELAN_STATE_REQ | ELAN change state request value. This longword parameter directs the driver to either start or 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 set to 1, this longword parameter directs the driver to set the event reporting mask to the value given by the event parameter.
NMA$C_PCLI_EVENT | Event mask value. This is a longword bit mask which controls the event reporting done by the driver. A bit set in the mask enables the reporting of corresponding event(s).

#### 9.16.3.7 IO$M_UPDATE_MAP Functional Modifier to IO$_SETMODE (Alpha Only)

Using Token Ring only, the IO$M_UPDATE_MAP qualifier, when used with IO$_SETMODE, manipulates the adapter's functional address mapping table. Figure 9-24 shows the format of the P2 buffer for this operation. This QIO requires PHY_IO privilege.

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

The subfunction is one of the following:

- NMA$C_MAP_CHANGE---This function adds or changes a mapping in the functional address table. If the specified multicast entry does not exist, an entry is created with the specified functional address mask. If the specified multicast entry does exist, the corresponding functional address mask is changed to the specified mask. All users who currently have the multicast enabled when the functional mask is changed will automatically update the functional address table as part of this operation.
  Possible errors returned include the following:

  > SS$_DEVICEFULL---This error indicates that there is insufficient space in the mapping table to complete the request. The multicast to functional address mapping table has 200 entries.

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

  > SS$_BADPARAM --- This error indicates that the specified multicast address cannot be found in the table.

The following example maps multicast address AB-01-01-01-02-03 to 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 multicast address of AB-01-01-01-02-03 for the device ICA0:.

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

#### 9.16.3.8 IO$M_ROUTE Functional Modifier to IO$_SETMODE (Alpha Only)

On Alpha systems using Token Ring only, the IO$M_ROUTE qualifier, when used with IO$_SETMODE, manipulates the source routing cache table. This command is successful only when source routing is enabled. Source routing is enabled with the set mac qualified set mode QIO. Figure 9-25 shows the format of the P2 buffer. This QIO require PHY_IO privilege.

Figure 9-25 Format of the IO$M_ROUTE P2 Buffer (Alpha Only)

The subfunction is one of the following:

- NMA$C_SR_ADD---This function adds or changes a source routing cache entry. It enters the LAN address into the table with the enclosed routing information. The routing information string format is documented in Section 9.12.6. If RI_size is passed as 0, the entry is created (or modified) to be in the EXPLORING state (this is useful for users who are doing their own source routing). If the RC 'Lth' field is zero, the LAN address is entered in the table as being in the local state.
  Possible errors returned include:

  > SS$_INSFMEM---The source routing cache is full.
  > SS$_BADPARAM---An invalid RI string was passed or invalid sizes were passed.
  > SS$_IVMODE---Source routing is not enabled.

- NMA$C_SR_DELETE---This function deletes a source routing cache entry. The RI_size and the routing information string are not required for this QIO. If one or both of the fields are passed for this operation, they are ignored. The result of this command is to put the entry into the deleted state. When the entry goes into the deleted state, it is deleted within 10 minutes.
  Possible errors returned includes the following:

  > SS$_BADPARAM---The requested entry could not be found.

### 9.16.4 Sense Mode and Sense Characteristics

The sense mode function returns the port attributes in the specified buffers. These attributes include the device characteristics described in Section 9.15 and, with the exceptions noted below, the attributes listed in Table 9-16.

The following combinations of function code and modifier are provided:

- IO$_SENSEMODE!IO$M_CTRL---Read characteristics
- IO$_SENSECHAR!IO$M_CTRL---Read characteristics
- IO$_SENSEMODE!IO$M_SENSE_MAC---Medium specific characteristics

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

- IO$_SENSEMODE!IO$M_SHOW_MAP---Returns current functional address to multicast address mapping
- IO$_SENSEMODE!IO$M_SHOW_ROUTE---Returns current source routing cache table

These functions take the following device- or function-dependent arguments:

- P1---The address of a two-longword buffer where the device characteristics are stored. (Figure 9-26 shows the format for, and Section 9.15 describes the contents of, the P1 buffer.) The P1 argument is optional.
- P2---The address of a quadword descriptor where the attributes buffer is stored. 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 is not read by the LAN driver. The driver stores the port's attributes in the buffer, which contains multiple entries. The format of each entry depends on whether a longword or a counted string is returned, as shown in Figure 9-27. Each parameter ID contains a string indicator bit (bit 12) that describes whether the data item is a string or a longword.

Except for the following differences, P2 returns the same attributes as those listed in Table 9-16:

- All parameters that are valid for the enabled packet format are returned (see Table 9-17).
- The sense-mode P2 buffer does not return the modifier word for the NMA$C_PCLI_PHA, NMA$C_PCLI_MCA, and NMA$C_PCLI_DES parameter IDs.
- The NMA$C_PCLI_DES parameter is only returned on Ethernet ports whose access mode is set to "shared with destination."
- In addition to the parameter IDs listed in Table 9-16, the sense-mode P2 buffer contains the following parameter IDs:

Parameter ID | Meaning
--- | ---
++NMA$C_PCLI_FCA | List of the currently enabled functional addresses (Token Ring only). Each 32-bit entry corresponds respectively with the items returned under NMA$C_PCLI_MCA.
NMA$C_PCLI_HWA | Hardware address. Describes the value for the hardware address. The hardware address is the default physical address when no physical address has been specified and there are no active users on the controller. NMA$C_PCLI_HWA is returned in the same format as NMA$C_PCLI_PHA.
NMA$C_PCLI_MBS | Maximum packet length. NMA$C_PCLI_MBS is a longword, read-only parameter. The value returned reflects the largest data packet that the application can receive for its packet format and type of LAN, measured in bytes. The values for CSMA/CD, FDDI, and Token Ring are:
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
802E format | 1492 | 4470 | ++4418
| On Alpha systems, the values for LAN emulation over ATM are:
Packet Format | 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
NMA$C_PCLI_MED | Type of medium to which the device is attached. Current media supported are NMA$C_LINMD_FDDI (FDDI), NMA$C_LINMD_CSMACD (Ethernet and IEEE 802.3), and NMA$C_LINMD_TR (Token Ring). This is a longword parameter.

++Alpha specific.

Figure 9-26 Sense Mode P1 Characteristics Buffer

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

All attributes that fit into the buffer specified by P2 are returned. However, if all the attributes cannot be stored in the buffer, the I/O status block returns the status SS$_BUFFEROVF. The second word of the I/O status block contains the number of bytes used in the P2 buffer (see Section 9.17).

Figure 9-27 Sense Mode Attribute Buffer

Previous | Next | Contents | Index

| privacy and legal statement |
6136PRO_033.HTML