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

See BPXYCID — Map the returning structure for getclientid() for more information about the format of this field.

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 complete list of possible return code values, see 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 the reason codes, see 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.