snmpGetbulk_v3()--Retrieve Bulk MIB Objects Using SNMP Version 3
Syntax
#include <qtomeapi.h> int snmpGetbulk_v3(snmppdu_bulk * pdu_ptr, char * host_ptr, unsigned long int time_out, char * user_ptr, snmp_auth_cb * my_auth_cb_ptr snmppdu * response_pdu_ptr);
Service Program Name: QTOMEAPI
Default Public Authority: *USE
Threadsafe: No
An SNMP managing application uses the snmpGetbulk_v3() function to get the value of one or more management information base (MIB) objects from an SNMP agent or subagent on a local or remote system. The snmpGetbulk_v3() function gets the value of the object instance that is next in lexicographic order. This function uses the SNMP version 3 protocol to communicate with the local or remote agent.
Parameters
- pdu_ptr
- (Input) A pointer to a structure of the protocol data unit (PDU) get bulk type as
defined in the <qtomeapi.h> file.
This structure contains the get bulk PDU, the number of non-repeater OIDs, the maximum number of "get next" attempts for the remaining OIDs, 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 or snmpSet_v3 function. For other functions, it is returned by the API. val_len For the snmpSet or snmpSet_v3 functions, the user must set this to reflect the exact amount of data to be written to the OID. For an snmpGet, snmpGet_v3, snmpGetnext, or snmpGetnext_v3, 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.
- user_ptr
- (Input) A pointer to the character string that contains the SNMPv3 User-based Security Model (USM) user name.
The USM user name must exist in the file /QIBM/USERDATA/OS/SNMP/SNMPD.CONF. The USM user name is a NULL terminated string.
- my_auth_cb_ptr
- (Input/Output) The address of a pointer to an SNMPv3 authentication control block built by the snmpDiscover_v3() function for the host specified by the host_ptr parameter.
- response_pdu_ptr
- (Output) A pointer to an snmppdu structure that will contain the results of the get bulk request. The storage used by snmppdu structure and the associated varbinds must be provided by the caller of this API. The total number of varbind structures that must be provided can be determined with the formula T = ((V - N) * M) + N where T is the total number of varbinds to be returned, V is the number of varbinds provided by the pdu_ptr parameter, N is the number of non-repeater varbinds provided by the pdu_ptr parameter, and M is the maximum repetitions value specified by the pdu_ptr parameter. The maximum number of varbinds that this API will return is 512.
Authorities
- Service Program Authority
- *USE
Return Value
The following are the possible return codes posted by the snmpGetbulk_v3() function:
0 | API_RC_OK
snmpGetbulk_v3() 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, or the value pointer in the response PDU (str_val or int_val) is NULL. |
-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 common PDU types. |
-103 | API_RC_INVALID_IP_ADDRESS
The IP address that was specified is not valid. |
-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 either the get bulk request PDU or the response PDU varbind list is not valid. |
-113 | API_RC_INVALID_PDU_POINTER
The pointer value to the get bulk 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_HOST_POINTER
The pointer value to the host address must be non-NULL. |
-116 | API_RC_INVALID_USM_USER_PTR
The pointer value to the SNMPv3 USM user name must be non-NULL. |
-117 | API_RC_UNKNOWN_USM_USER
The USM user specified was not found in the /QIBM/USERDATA/OS/SNMP/SNMPD.CONF file. |
-118 | API_RC_INVALID_AUTH_CB_PTR
The pointer value to the authentication control block must be non-NULL. |
-119 | API_RC_INVALID_AUTH_CB
The authorization control block is not valid. |
-120 | API_RC_LOCALIZED_USM_USER
The USM user specified was found in the /QIBM/USERDATA/OS/SNMP/SNMPD.CONF file, however, it can not be used by this API because the keys have been localized with the local SNMP engine ID. |
-122 | API_RC_INVALID_RESPONSE_PDU_PTR
The pointer value to the get bulk response PDU structure must be non-NULL. |
-123 | API_RC_INVALID_GETBULK_REQUEST
The combination of values specified by the get bulk PDU for non-repeaters and maximum repetitions is not valid. Both values can not be less than 1. |
-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, or the val_len field of the varbind structure contains a value that is less than zero. |
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.
0 | API_SNMP_ERROR_noError
The function was successful. |
1 | API_SNMP_ERROR_tooBig
The agent could not fit the results of an operation into a single SNMP message. |
2 | API_SNMP_ERROR_noSuchName
The requested operation identified an unknown variable name. |
3 | API_SNMP_ERROR_badValue
The requested operation specified an incorrect syntax or value when the management application tried to modify a variable. |
5 | API_SNMP_ERROR_genErr
A nonspecific error occurred while running this operation on the SNMP agent. |
Usage Notes
The storage area (Response PDU) where the data is returned is the responsibility of the user, not the API. The user may use the MakeResponsePDUSpace routine to allocate the necessary storage (see MakeResponsePDUSpace Routine). To allocate storage for the input PDU, the user may use the AddVarbind routine (see AddVarbind Routine). To deallocate storage for both the response and input PDUs, 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 uses ASCII.
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. 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)
- snmpGet()--Retrieve MIB Objects
- snmpGetnext()--Retrieve Next MIB Object
- snmpSet()--Set MIB Objects
- snmpDiscover_v3()--SNMP Version 3 Discovery
- snmpFreeAuthCB_v3()--SNMP version 3 Free Authentication Control Block
- snmpGet_v3()--Retrieve MIB Objects Using SNMP Version 3
- snmpGetnext_v3()--Retrieve Next MIB Object Using SNMP Version 3
- snmpSet_v3()--Set MIB Objects Using SNMP Version 3
Example
For examples that pertain to the SNMP manager APIs, see Using SNMP Manager APIs--Example.
API introduced: V7R2
Top | UNIX-Type APIs | APIs by category |