Parameters

hostname_p

A pointer to a null-terminated character string representing the local host name or IP address in IPv4 dotted-decimal or IPv6 colon-hexadecimal notation of the local host where the DPI-capable SNMP agent is running.

community_p

A pointer to a null-terminated character string representing the community name that is required to obtain the UNIX® path name from the SNMP agent through an SNMP GET request.

Note: For z/OS® Communications Server, the SNMP community passed by the subagent must be in ASCII only.

Return codes

• If successful, a nonnegative integer that represents the connection is returned. It is to be used as a handle in subsequent calls to DPI transport-related functions.
• If not successful, a negative integer is returned, which indicates the kind of error that occurred. See Return codes from DPI transport-related functions for a list of possible error codes.

DPI_RC_NO_PORT

Unable to obtain the UNIX path name. There are many reasons for this, for example: bad host name, bad community name, or default timeout (9 seconds) before a response from the agent.

DPI_RC_IO_ERROR

An error occurred with an underlying select(), or DPI was not able to set up a socket (might be due to an error on a socket(), bind(), connect() call, or other internal errors).

Usage

The DPIconnect_to_agent_UNIXstream() function is used at the subagent side to set up an AF_UNIX connection to the DPI-capable SNMP agent.

As part of the connection processing, the DPIconnect_to_agent_UNIXstream() function sends an SNMP GET request to the SNMP agent to retrieve the path name for the UNIX streams connection. By default, this SNMP GET request is sent to the well-known SNMP port 161. If the SNMP agent is listening on a port other than well-known port 161, the SNMP_PORT environment variable can be set to the port number of the SNMP agent prior to issuing the DPIconnect_to_agent_UNIXstream(). Use setenv() to override port 161 before using this function.

The DPIconnect_to_agent_UNIXstream() function uses a path name in the z/OS UNIX file system as the name of the socket for the connect. This path name is available at the SNMP agent through the MIB object 1.3.6.1.4.1.2.2.1.1.3, which has the name dpiPathNameForUnixStream. The SNMP agent uses the default name /var/dpi_socket if you do not supply another name in the agent startup parameter (-s) or in the OSNMPD.DATA file. Whichever name is used, the SNMP agent creates the path name as a character special file during initialization.

You must either define the subagents with superuser authority or set the read and write file access permission bits for the path name for the class associated with the user ID of the subagent before subagents can successfully connect to the agent using the path name. You can use the agent -C startup parameter to specify which permission bits should be set.

To run a user-written subagent from a non-privileged user ID, set the permission bits for the character special file to write access. Otherwise, a subagent using this function must be run from a superuser or other user with appropriate privileges.

Context

• Return codes from DPI transport-related functions
• The DPIconnect_to_agent_TCP() function