The NetView SNMP command

To issue an SNMP request from NetView®, use the SNMP command. The SNMP command provides SNMP manager function with the NetView program to query SNMP agents for network management information.

The NetView SNMP command uses the SNMP Query Engine to issue SNMP requests to agents and to process SNMP responses returned by agents. The SNMP command supports issuance of SNMPv1 requests.

The SNMP command does not support the use of IPv6 addresses.

Note: The z/OS® Communications Server SNMP agent supports SNMPv1, SNMPv2c, and SNMPv3 requests.

Format

Getting MIB Variables:


>>-SNMP--+-Get------+--host_name--community_name---------------->
         '- GETNext '                              

   .----------.   
   V          |   
>----var_name-+------------------------------------------------><

Setting the MIB Variables:


                                        .-----------------.   
                                        V                 |   
>>-SNMP Set--host_name--community_name----var_name--value-+----><

Finding an ASN.1 Variable Name:


>>-SNMP MIBvname--asn.1 name-----------------------------------><

Forwarding Traps:


>>-SNMP TRAPson--net_mask--net_desired-------------------------><

Stop Forwarding Traps:


>>-SNMP TRAPSOFf--filter_id------------------------------------><

Pinging a Node:


>>-SNMP PING--host_name----------------------------------------><

Parameters

SNMP request types

Get: Sends a request to an SNMP agent for a specific management information base (MIB) variable.
GETNext: Sends a request to an SNMP agent for the next MIB variable that lexicographically follows the var_name specified.
Set: Sends a request to an SNMP agent to set a specific MIB variable.
MIBvname: Requests the textual name of an ASN.1 MIB object.
TRAPson: Requests that the SNMP Query Engine listen on the trap port for SNMP traps and forward them to the NetView program, which displays trap information when it occurs.
TRAPSOFf: Causes the SNMP Query Engine to stop listening on the trap port for SNMP traps and stop forwarding them to the NetView program.
PING: Obtains the minimum round-trip response time from the Query Engine to a specific node.

Variables

host_name: Specifies the destination host to which you want to send a request. The host can be specified with its name or with its IP address in dotted decimal notation.
community_name: Specifies the community name used to access the specified variables at the destination SNMP agent.
Note: Community names are case-sensitive. SNMP commands issued from the NetView console are converted to uppercase. Those issued from REXX execs are not converted to uppercase.
var_name: Specifies one or more MIB variable names to be retrieved or set. You can specify the textual names or ASN.1 notation (for example, sysDescr.0 or 1.3.6.1.2.1.1.1.0). The SNMP Query Engine can accept a maximum of 10 variables for each request.
All MIB variables that are defined as part of a sequence represent variables that can have more than one occurrence. These variables require an instance identifier appended to the end of the variable name to identify which occurrence of the variable is being requested.
value: Specifies the value to be set by the SET function. On the Set command from the NetView console, a value is enclosed in single quotation marks, not double quotation marks. From the panels, you can specify no quotation marks, single quotation marks (’), or double quotation marks (”). No quotation marks and single quotation marks work the same. If you specify double quotation marks, you get double quotation marks as part of the value.
asn.1_name: Specifies the MIB object, using its object identifier in ASN.1 notation. You can specify only one variable. Additional arguments are ignored.
net_mask: Specifies, in dotted decimal notation, the network mask to be evaluated with the IP address of incoming traps. The dotted decimal IP address is ANDed with this mask.
net_desired: Specifies the network from which you want to receive traps.
filter_id: Specifies the trap filter ID.
When you request traps using the SNMP TRAPSON command, it returns a request number or filter_id, which the SNMP Query Engine associates with the TRAPSON request. To stop receiving traps, specify this filter_id in the TRAPSOFF request.

Usage

If you start and stop NetView, you must do the same to the SNMP Query Engine.
When the SNMP command is issued from the NetView Command Facility command line, all input is translated to uppercase (standard NetView format) before it is sent to the SNMP Query Engine.
When the SNMP command is issued from a CLIST, input is passed in whatever case it was passed from the CLIST (for example, mixed case).
The textual names for the variables passed to the query engine are compared against the entries in the MIBDESC.DATA file. This comparison is not case-sensitive.
If multiple variables are specified with the GET, GETNext, or SET commands, they are all packaged in one SNMP PDU to be sent to the agent.
If multiple SNMP requests are issued, the responses might not be received in the same order the requests are issued.
The SNMP agent can receive SNMP requests over any interface.
The SNMP Query Engine treats numbers with leading zeros as octal numbers. Therefore, do not use leading zeros.
If an SNMP request is issued with the wrong community name, it could receive multiple AUTHENTICATION FAILURE traps with the same filter_id but different time stamps from the same host. This is because the SNMP Query Engine tries the request again if a response is not received from the host, and each attempt causes the host to generate an AUTHENTICATION FAILURE trap.

Return codes

The following table lists the return codes generated by SNMP.

Return code	Description
1	Error from DSIGET, cannot continue
2	Incorrect function specified
3	Missing SNMP function
4	Not enough parameters
5	Missing variable name
6	Missing variable value
7	Missing or incorrect host name
8	Missing community name
9	SNMPIUCV not active
10	Error from DSIMQS
11	Incorrect net_mask⁄desired network
12	Missing⁄Incorrect trap filter_id
1001+	Command successful — all return codes above 1000

Examples

Retrieving the MIB variable

For example, if you know:

hostname            -  anyhost
IP address          -  129.34.222.72
community name      -  public
variable name       -  sysDescr.0
asn.1 variable name -  1.3.6.1.2.1.1.1.0
variable name       -  sysObjectID.0
asn.1 variable name -  1.3.6.1.2.1.1.2.0
variable name       -  sysUpTime.0
asn.1 variable name -  1.3.6.1.2.1.1.3.0

You can issue the following SNMP GET commands:

snmp get 129.34.222.72 public 1.3.6.1.2.1.1.1.0
snmp get 129.34.222.72 public sysDescr.0
snmp get anyhost public 1.3.6.1.2.1.1.1.0
snmp get anyhost public sysDescr.0
snmp get anyhost public sysObjectID.0
snmp get anyhost public sysUpTime.0
snmp get anyhost public sysDescr.0 sysObjectID.0 sysUpTime.0

After the last SNMP GET command is completed, you get a message similar to the following one:

SNM050I SNMP Request 1001 from NETOP accepted, sent to Query Engine

When the response arrives in the NetView program (asynchronously), it displays the response as a multiline message in the following form:

Figure 1. SNMP request response

SNM040I SNMP Request 1001 from NETOP Returned the following response:
SNM042I Variable name: 1.3.6.1.2.1.1.1.0
SNM043I Variable value type: 9
SNM044I Variable value: AIX 2.2.1 SNMP Agent Version 1.0
SNM042I Variable name: 1.3.6.1.2.1.1.2.0
SNM043I Variable value type: 3
SNM044I Variable value: 1.3.6.1.4.1.2.1.1
SNM042I Variable name: 1.3.6.1.2.1.1.3.0
SNM043I Variable value type: 8
SNM044I Variable value: 98800
SNM049I SNMP Request 1001 end of response

Retrieving the next MIB variable

For example, if you know:

hostname            -  anyhost
IP address          -  129.34.222.72
community name      -  public
variable name       -  ifAdminStatus (in ifTable)
asn.1 variable name -  1.3.6.1.2.1.2.2.1.7

You can issue an SNMP GETNext command in one of the following ways:

snmp getnext 129.34.222.72 public 1.3.6.1.2.1.2.2.1.7.0
snmp getnext 129.34.222.72 public ifAdminStatus.0
snmp getnext anyhost public 1.3.6.1.2.1.2.2.1.7.0
snmp getnext anyhost public ifAdminStatus.0

The GETNext command is completed in the same manner as the GET command, and you receive an asynchronous response similar to the following one:

SNM040I SNMP Request 1001 from NETOP Returned the following response:
SNM042I Variable name: 1.3.6.1.2.1.2.2.1.7.1
SNM043I Variable value type: 1
SNM044I Variable value: 1
SNM049I SNMP Request 1001 end of response

In this example, the first instance of the variable has a status of 1 or greater (ends in 7.1).

You can then issue another GETNext command in one of the following ways:

snmp getnext 129.34.222.72 public 1.3.6.1.2.1.2.2.1.7.1
snmp getnext 129.34.222.72 public ifAdminStatus.1
snmp getnext anyhost public 1.3.6.1.2.1.2.2.1.7.1
snmp getnext anyhost public ifAdminStatus.1

The GETNext command is completed in the same manner as the GET command, and you receive an asynchronous response similar to the following one:

SNM040I SNMP Request 1002 from NETOP Returned the following response:
SNM042I Variable name: 1.3.6.1.2.1.2.2.1.7.2
SNM043I Variable value type: 1
SNM044I Variable value: 1
SNM049I SNMP Request 1002 end of response

In this example, the second instance of the variable has a status of 1 or greater (ends in 7.2).

You can then issue another GETNext command in one of the following ways:

snmp getnext 129.34.222.72 public 1.3.6.1.2.1.2.2.1.7.2
snmp getnext 129.34.222.72 public ifAdminStatus.2
snmp getnext anyhost public 1.3.6.1.2.1.2.2.1.7.2
snmp getnext anyhost public ifAdminStatus.2

The GETNext command is completed in the same manner as the GET command, and you receive an asynchronous response similar to the following one:

SNM040I SNMP Request 1003 from NETOP Returned the following response:
SNM042I Variable name: 1.3.6.1.2.1.2.2.1.8.1
SNM043I Variable value type: 1
SNM044I Variable value: 1
SNM049I SNMP Request 1003 end of response

Setting the MIB variable
For example, if you know:
```
hostname            -  anyhost
IP address          -  129.34.222.72
community name      -  publicw
variable name       -  ifAdminStatus
asn.1 variable name -  1.3.6.1.2.1.2.2.1.7.1
     (instance 1)
```
You can then issue an SNMP SET command in one of the following forms to set the administrative status of the first interface in the ifTable (first instance) to test:
```
snmp set 129.34.222.72 publicw 1.3.6.1.2.1.2.2.1.7.1 3
snmp set 129.34.222.72 publicw IfAdminStatus.1 3
snmp set anyhost publicw 1.3.6.1.2.1.2.2.1.7.1 3
snmp set anyhost publicw ifAdminStatus.1 3
```
After the command is completed, you receive a message similar to the following one:
```
SNM050I SNMP Request 1001 from NETOP accepted, sent to Query Engine
```
When the response arrives in the NetView program (asynchronously), it displays the response as a multiline message in the following form:
```
SNM040I SNMP Request 1001 from NETOP Returned the following response:
SNM042I Variable name: 1.3.6.1.2.1.2.7.1
SNM043I Variable value type: 1
SNM044I Variable value: 3
SNM049I SNMP Request 1001 end of response
```
If a SET request is attempted against an object for which the target agent or subagent does not allow SETs, you receive:
- noSuchName for SNMPv1 requests
Management Information Base (MIB) objects identifies the objects supported by the z/OS Communications Server SNMP agent and subagents and the level of access supported for each object.
Note: The variable being set must be present in the MIBDESC.DATA data set for the Query Engine to determine the syntax to use when encoding the SNMP PDU.
Receiving a trap
The SNMP TRAPSON command permits the specification of a filtering condition that enables the Query Engine to perform filtering. The SNMP TRAPSON command assigns a unique request number to each filter (also called a filter_id) and returns this number in a message and in the return code. This filter_id is the argument to an SNMP TRAPSOFF command, which is used to stop receiving traps that pass this filter.
For example, if you know:
```
IP address          -  129.34.222.72
net mask            -  255.255.255.255
```
You can issue the following SNMP TRAPSON commands:
```
snmp trapson
snmp trapson 255.255.255.255 129.34.222.72
```
The first command receives all traps (the default is a mask of 0 and a required network of 0). The second command receives traps only from the specific host 129.34.222.72.
After the command is completed, you receive a message similar to the following one:
```
SNM050I SNMP Request 1001 from NETOP accepted, sent to Query Engine
```
The number returned in the message (1001 in the previous example) is used as the filter_id. This filter_id is displayed in the header message of traps passed by this filter. The filter_id is used in the TRAPSOFF command to turn the filter off.
When the response arrives in the NetView program (asynchronously), it displays the response as a multiline message in the following form to indicate that the TRAPSON request was accepted:
```
SNM040I SNMP Request 1001 from NETOP Returned the following response:
SNM045I Major error code: 0
SNM046I Minor error code: 0
SNM047I Error index: 0
SNM048I Error text: no error
SNM049I SNMP Request 1001 end of response
```
When traps arrive, the NetView program displays each trap with a multiline message in the following form. This multiline message is sent to the NetView operator who is designated as the authorized receiver (AUTH MSGRECVR=YES in the operator profile); it might not show up on the console of the operator who issues the TRAPSON command.
```
SNM030I SNMP request 1001 received following trap:
SNM031I Agent Address: 129.34.222.34
SNM032I Generic trap type: 4
SNM033I Specific trap type: 0
SNM034I Time stamp: 472600
SNM035I Enterprise Object ID: 1.3.6.1.4.1.2.1.1
SNM039I SNMP request 1001 End of trap data
```
After the TRAPSON command has been issued, traps can start to arrive asynchronously. They can even arrive after the operator who issued the TRAPSON command has logged off. Often, a TRAPSON command is issued by a CLIST, and the received trap data triggers another CLIST to handle the trap data. Therefore, the messages in the range SNM030—SNM039 are sent to the authorized receiver. For a NetView operator to see the traps, the operator must have the following statement in the NetView Operator profile:
```
AUTH MSGRECVR=YES
```
However, only one operator receives the message. The message also goes to the log file, so you can always browse the log file to see trap data. Additionally, you can assign trap messages to go to a specific operator using the NetView ASSIGN operator command.
In the response to the SNMP TRAPSON request, not all lines need to be present, but the first line is always message SNM040I, and the last line is always message SNM049I.

For the multiline trap message, not all lines need to be present, but the first line is always message SNM030I, and the last line is always message SNM039I.

Additional messages (SNM036I—SNM038I) could be present if the trap has additional data.

If a variable value is too long, message SNM038 might not fit on an 80-character line. If this happens, the value is split and multiple SNM038 messages are displayed.

The SNMP trap data always displays the variable name in ASN.1 notation. You can use SNMP MIBVNAME to obtain the textual name for the variable.

A trap always shows the agent address in the form of an IP address in dotted decimal notation.

You can issue multiple TRAPSON requests, with either the same or a different filter. If a trap passes multiple filters, the trap is sent to the NetView program multiple times. However, in the NetView program, the header and trailer lines (messages SNM030I and SNM039I) of the duplicate trap are different, because they contain the filter_id (request number) by which the trap was forwarded. Different types of traps from different hosts can have the same filter_id, if these traps pass the same trap filter.

The SNMP Query Engine can forward only those traps that it receives. Each agent has a trap destination table, which lists all the hosts that receive that agent’s traps. The host name of your system must be in the trap destination table of all agents from which you want to receive traps.
Stop listening for traps
For example, if you know the filter_id is 1001, you can issue the following SNMP TRAPSOFF command to tell the SNMP Query Engine to quit sending traps that would pass filter 1001:
```
snmp trapsoff 1001
```
The command completes with a message similar to the following one:
```
SNM050I SNMP Request 1001 from NETOP accepted, sent to Query Engine
```
When the response arrives in the NetView program (asynchronously), it displays the response as a multiline message in the following form to indicate that the TRAPSOFF request was accepted.
```
SNM040I SNMP Request 1002 from NETOP Returned the following response:
SNM045I Major error code: 0
SNM046I Minor error code: 0
SNM047I Error index: 0
SNM048I Error text: no error
SNM049I SNMP Request 1002 end of response
```
Only one filter_id for each SNMP TRAPSOFF command can be passed. Extraneous arguments are ignored.

Finding the name of an ASN.1 variable

For example, if you have a trap that tells you:

SNM030I SNMP request 1001 received following trap:
SNM031I Agent Address: 129.34.222.34
SNM032I Generic trap type: 2
SNM033I Specific trap type: 0
SNM034I Time stamp: 472600
SNM035I Enterprise Object ID: 1.3.6.1.4.1.2.1.1
SNM036I Variable name: 1.3.6.1.2.1.2.2.1.1
SNM037I Variable value type: 1
SNM038I Variable value: 2
SNM039I SNMP request 1001 End of trap data

You can issue the following SNMP MIBVNAME command to find the textual MIB variable name:

snmp mibvname 1.3.6.1.2.1.2.2.1.1

The command completes with a message similar to the following one:

SNM050I SNMP Request 1002 from NETOP accepted, sent to Query Engine

When the response arrives in the NetView program (asynchronously), it displays the response as a multiline message in the following form:

SNM040I SNMP Request 1002 from NETOP Returned the following response:
SNM042I Variable name: 1.3.6.1.2.1.2.2.1.1
SNM043I Variable value type: 9
SNM044I Variable value: ifIndex
SNM049I SNMP Request 1002 end of response

Only one ASN.1 variable name can be passed for each SNMP MIBVNAME command. Additional parameters are ignored.

Pinging a node
For example, if you know:
```
nodename            -  anynode
IP address          -  129.34.222.72
```
You can issue the following SNMP PING commands:
```
SNMP PING ANYNODE
SNMP PING 129.34.222.72
```
The command completes with a message similar to the following one:
```
SNM050I SNMP Request 1001 from NETOP accepted, sent to Query Engine
```
When the response arrives in the NetView program (asynchronously), it displays the response as a multiline message in the following form:
```
SNM040I SNMP Request 1001 from NETOP Returned the following response:
SNM042I Variable name: 1.3.6.1.4.1.2.2.1.3.2.129.34.222.72
SNM043I Variable value type: 1
SNM044I Variable value: 26
SNM049I SNMP Request 1001 end of response
```
The Query Engine issues one PING (an ICMP echo on a raw socket) and returns the value in milliseconds in an IBM-defined SNMP variable minRTT. Because only one PING is issued, this is also the average and the maximum response time.

If the PING does not respond, the Query Engine tries again twice, once after one second and again after two seconds (Query Engine default retry mechanism). If a response is not received after all retries have been exhausted, a variable value of -1 is returned to indicate that a reply was not received.

The 129.34.222.72 in the example for the SNMP PING command represents an instance of the IBM® variable minRTT.

Only one node name can be passed for each SNMP PING command.

SNMP uses ICMP Echo to send a PING command to the remote host. No SNMP PDU exchange with the remote host occurs. Therefore, a successful SNMP PING indicates only that the remote host is active and reachable. It does not indicate that the SNMP agent at the remote host is active, or that the SNMP manager can send requests to the SNMP agent if it is active.

Usage

The SNMP response always displays the variable name in ASN.1 notation. You can use SNMP MIBVNAME to obtain the textual name for the variable.
If you issue a GET for multiple variables, messages SNM042—SNM044 are displayed for each variable.
When you issue a GET for multiple variables, they are returned in the same sequence as requested. In Figure 1, GET was issued for sysDescr.0 sysObjectID.0 sysUpTime.0. The same 3 variables are returned in the response.
If an error was detected, messages SNM042–SNM044 might not be present. You can get (in addition to other messages) error messages in the following forms (all as part of multiline message SNM040I):
```
SNM045I Major error code: n
SNM046I Minor error code: y
SNM047I Error index: z
SNM048I Error text: message text
```
If a variable value is too long, message SNM044 might not fit on an 80-character line. If this happens, the value is split and multiple SNM044 messages are displayed.
According to RFC 1157 (Simple Network Management Protocol (SNMP)), a message exchanged between SNMP entities (including version identification and community name) can be as small as 484 octets. If you specify up to 10 variables in a GET⁄GETNext command, the names could be short enough to send the GET command to the SNMP agent, but the response could be too long to fit in the message. As a result, you receive a tooBig error.
If one (or more) of the variables requested results in an error, all variables listed after the first variable in error are ignored, and data is not returned for them.
To correctly retrieve the next variable for the GETNext command, you must specify an instance identifier as part of the variable name. If the variable has only one occurrence, or if the first occurrence of a table variable is needed, use .0 as the instance identifier.
The GETNext command is used to interrogate a table (for example, the interface table) or an array. You can issue a GETNext command at the start of a table (use instance 0.0). The first element in the table is returned. The process continues in a loop, performing GETNext requests on the previously obtained variable name, until the name of the variable returned no longer has the same prefix as the one at the start of the table. This condition occurs when the GETNext request returns a variable that is in the next group.

Context

For information about the variable ibmMvsRPingResponseTime, which enables you to send remote PING commands, see SNMP remote PING.

For a list of variables supported by the z/OS Communications Server IP agent, see Management Information Base (MIB) objects.