getclientid (BPX1GCL, BPX4GCL) — Obtain the calling program's identifier
Function
The getclientid callable service obtains the calling program's identifier.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1GCL): | 31-bit |
AMODE (BPX4GCL): | 64-bit |
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 BPX1GCL,(FunctionCode,
Domain,
Clientid,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4GCL with the same parameters.
Parameters
- FunctionCode
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
Specify a 1 to have the caller's name and task identifiers returned in the Clientid parameter. Specify a 2 to have the caller's process id returned in the Clientid parameter.
- Domain
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the communications domain in which the sockets are to be given and taken. See BPXYSOCK — Map SOCKADDR structure and constants for more information about the values defined for this field.
- Clientid
- Returned parameter
- Type:
- Structure
- Length:
- Length of BPXYCID
The name of a structure that is to be returned with information that identifies the calling program.
If the FunctionCode parameter is 1, the returned Clientid is filled in as follows:- CIdDomain
- Input Domain
- CIdName
- Calling program's address space name, left-justified, and padded with blanks
- CIdTask
- Calling program's subtask identifier
- CIdReserved
- Binary zeros
If the FunctionCode parameter is not 1, the returned Clientid is filled in as follows:- CIdDomain
- Input Domain
- CIdName
- A fullword of binary zeros followed by the calling program's process id
- CIdTask
- Blanks
- CIdReserved
- Binary zeros
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getclientid service returns one of the following:0
, if the request is successful.-1
, if the request is not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getclientid service stores the return code. The getclientid service returns Return_code only if Return_value is-1
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The getclientid service can return one of the following values in the Return_code parameter:Return_code Explanation EFAULT Using the Clientid parameter as specified would result in an attempt to access storage outside the caller's address space. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword where the getclientid service stores the reason code. The getclientid service returns Reason_code only if Return_value is -
1
. Reason_code further qualifies the Return_code value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- The Clientid output of getclientid is intended to be used as the input Clientid of the givesocket and takesocket services.
- The output Clientid that is returned with an input FunctionCode of 2 provides optimal performance and integrity when used as the input Clientid on the givesocket and takesocket services. The input FunctionCode of 1 is only provided for existing applications that may have been using the output of getclientid for purposes other than as input on the givesocket or takesocket services.
Related services
Characteristics and restrictions
There are no restrictions on the use of the getclientid service.