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
|
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.