snmpGet()--Retrieve MIB Objects

 #include <qtomeapi.h>

 int snmpGet(snmppdu  *          pdu_ptr,
             char  *             host_ptr,
             unsigned long int   time_out,
             char  *             comm_ptr,
             unsigned long int   comm_len);   

An SNMP managing application uses the snmpGet() function to get one or more management information base (MIB) objects from an SNMP agent or subagent on a local or remote system.

Parameters

pdu_ptr

(Input) A pointer to a structure of the protocol data unit (PDU) type as defined in the <qtomeapi.h> file.

This structure contains the PDU type (GET in this instance), the error status, the error index, and the pointer to the varbind structure.

The varbind structure (found in the qtomeapi.h file) consists of the following:

struct _varBind{
   struct _varBind * next;
   char   *oid;                          /* Null Terminated */
   unsigned char asn_type;
   int    val_len;
   union {
      int  * int_val;
      char * str_val;
   } val;
};

The fields for this structure are described as follows:

*next	The pointer to the next varbind. This has to be NULL if it is the last varbind in the list.
*oid	The pointer to the OID being set or retrieved (depending on the operation).
asn_type	The ASN type of the OID. This field must be set by the user only for the snmpSet function. On the snmpGet or snmpGetnext function, it is returned by the API.
val_len	For the snmpSet function, the user must set this to reflect the exact amount of data to be written to the OID. On an snmpGet or snmpGetnext, the user must use this field to indicate how much space to allocate for the value being retrieved. If the value coming back is greater than the amount of space allocated, a return code of 1 is received and a return code of API_RC_NOT_OK is returned to the API caller.
val	A union of either a pointer to the string data or a pointer to the integer data. This space is allocated by the user.

host_ptr

(Input) A pointer to the character string that contains the Internet Protocol (IP) address. The internet address may be an IPv4 or IPv6 address.

An IPv4 internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An IPv4 internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address.

An IPv6 internet address is specified in the form x:x:x:x:x:x:x:x, where x is a hexadecimal number ranging from 0 through X'FFFF'. "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address.

This parameter can also be stored in host address format, that is, mycompany.com. This parameter must contain printable characters only.

time_out

(Input) The time-out value.

This parameter is the amount of time in seconds that the management application is willing to wait for the response PDU. The minimum value is 1, and the maximum is 100.

comm_ptr

(Input) A pointer to the character string that contains the community name.

This parameter contains a variable-length field that contains printable and nonprintable values. Therefore, the user must supply the exact length of this value in another parameter. EBCDIC-to-ASCII translation will not be done, and it is the responsibility of the managing application to specify the community name in the correct notation for the SNMP agent system.

comm_len

(Input) The length of the community name.

This parameter is the exact length of the community name. The minimum value is 1, and the maximum is 255.

Authorities

Service Program Authority

*USE

Return Value

The following are the possible return codes posted by the snmpGet() function:

0	API_RC_OK snmpGet() was successful.
-4	API_RC_OUT_OF_MEMORY There was not enough storage to complete this operation.
-5	API_RC_OUT_OF_BUFFERS There were not enough internal buffers to continue.
-6	API_RC_OUT_OF_VARBINDS The maximum number of allowable varbinds was exceeded.
-7	API_RC_SNMP_OUT_OF_VARBINDS The maximum number of allowable varbinds was exceeded. This return code is equivalent to the -6 return code.
-9	API_RC_SNMP_INVALID_OID The OID specified in the varbind list is not valid. This return code is equivalent to the -112 return code.
-10	API_RC_INVALID_VALUE The specified value in the varbind is not valid.
-11	API_RC_INVALID_VALUE_REP The specified value in the varbind is incorrectly represented.
-12	API_RC_DECODE_ERROR The SNMP APIs were unable to decode the incoming PDU.
-13	API_RC_ENCODE_ERROR The SNMP APIs were unable to encode the PDU data structure.
-18	API_RC_TIMEOUT A response to this request was not received within the allotted time-out value.
-21	API_RC_INVALID_PDU_TYPE The PDU type was not recognized as one of the seven common PDU types.
-103	API_RC_INVALID_IP_ADDRESS The IP address that was specified is not valid.
-104	API_RC_INVALID_COMMUNITY_NAME _LENGTH The community name length must be greater than 0 and less than 256.
-108	API_RC_INVALID_TIMEOUT_PARM The time-out value must be greater than 0 and less than or equal to 100.
-110	API_RC_UNKNOWN_HOST The host name or IP address that is specified is not known on the network.
-112	API_RC_INVALID_OID The OID that is specified in the varbind list is not valid.
-113	API_RC_INVALID_PDU_POINTER The pointer value to the PDU structure must be non-NULL.
-114	API_RC_INVALID_HOST_POINTER The pointer value to the host address must be non-NULL.
-115	API_RC_INVALID_COMMUNITY_PTR The pointer value to the community name must be non-NULL.
-201	API_RC_SOCKET_ERROR The APIs have detected a socket error and cannot continue.
-202	API_RC_NOT_OK The APIs have detected an unknown error and cannot continue. The val_len field of the varbind structure contains a value that is not valid.
1	API_RC_VAL_LEN_LESS_THAN_RETURNED_ VAL_LEN The value being returned by the API is greater than the space allocated by the user.
241	API_RC_DOMAIN_ERROR This is equivalent to an MCH6801 error--stating object domain error.
242	API_RC_INVALID_POINTER This is equivalent to an MCH3601 error--referenced location in a space does not contain a pointer.
243	API_RC_INVALID_PTR_TYPE This is equivalent to an MCH3602 error-pointer type not valid for requested operation.

For more information, see the Simple Network Management Protocol (SNMP) Support manual.

Error Conditions

Following are the possible error statuses returned in the error status field of the PDU structure. These values are returned by the SNMP agents.

Usage Notes

The area where the data is returned is the responsibility of the user, not the API. To allocate storage, the user may use the AddVarbind routine (see AddVarbind Routine). To deallocate storage, the user may use the FreePdu routine (see FreePdu Routine).

You must use the correct PDU type on AddVarbind. It must match the operation on which you call. For example, if you build a PDU wherein AddVarbind passes a PDU type of Set and then you call the snmpGet operation using the PDU that you just created with Set, you will receive an error on the snmpGet call.

All character strings that are passed to the APIs must be null-terminated unless you explicitly provide the length, if a length field is available.

If you are building a PDU to go to a remote agent, you must remember to do correct translation of strings. The IBM i system is an EBCDIC system, whereas an SNMP agent on an AIX computer is an ASCII system. Even though IBM i is an EBCDIC system, community names default to ASCII representation. For example, if you are sending a PDU to an AIX system and the community name is public, you would enter the community name string in hexadecimal, X'7075626C6963'. See the data conversion APIs to convert data from EBCDIC to ASCII and vice versa.

These APIs are blocked, which means that on a call to the API a PDU is sent across a communications protocol to an SNMP agent on a local or remote system.jn The call returns when a response has been received from the agent or when the command times out. On the return, all returned data is placed in the appropriate locations. You need do no further action to retrieve such data.

Related Information

• The <qtomeapi.h> file (see Header Files for UNIX^®-Type Functions)
  
  
• snmpGetnext()--Retrieve Next MIB Object
  
  
• snmpSet()--Set MIB Objects

Example

For examples that pertain to the SNMP manager APIs, see Using SNMP Manager APIs--Example.