gethostid or gethostname (BPX1HST, BPX4HST) — Get ID or name information about a socket host

Function

The gethostid or gethostname callable service obtains the ID or the name of the socket host.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN = HASN
AMODE (BPX1HST):	31-bit task or SRB mode
AMODE (BPX4HST):	64-bit task mode only
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1HST,(Domain,
              Name_length,
              Name,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4HST with the same parameters.

Parameters

Domain

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the number that represents a domain. See BPXYSOCK — Map SOCKADDR structure and constants for valid Domain values.

Name_length

Supplied and returned parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the length of Name. If this field is zero, the information that is returned is the host ID. If this field is nonzero, the value that is supplied is the maximum length of the host name that is to be returned.

On return, this field contains the length of the name that is returned, including the trailing null. The size of this field should be less than 4096 bytes (4KB) in length.

Name

Returned parameter

Type:: Character
Length:: Length specified by Name_length.

The name of a field that contains the host name on successful return, if the request was gethostname. This name is terminated by a null character if there is sufficient room in the buffer.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the gethostid or gethostname service returns one of the following:

The host id, if a zero—length Name_length is supplied.
0, if a nonzero Name_length is supplied and the name is successfully returned.
-1, if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the gethostid or gethostname service stores the return code. The gethostid or gethostname service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The gethostid or gethostname service can return one of the following values in the Return_code parameter:

Return_code	Explanation
ENOENT	The domain that was specified was found to be not active. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRDomainNotSupported.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the gethostid or gethostname service stores the reason code. The gethostid or gethostname service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Characteristics and restrictions

These functions work only for AF_INET sockets, and not for AF_UNIX.

Examples

For an example using this callable service, see BPX1HST (gethostid or gethostname) example.

Usage notes

See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.