pthread_tag_np (BPX1PTT, BPX4PTT) — Set, query, or both set and query the caller's thread tag data

Function

The pthread_tag_np service sets, queries, or both sets and queries the 65 bytes of thread tag data that is associated with the caller's thread.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1PTT):	31-bit
AMODE (BPX4PTT):	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 BPX1PTT,(New_Tag_Length,
              New_Tag_Ptr,
              Old_Tag_Length,
              Old_Tag_Ptr,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4PTT with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.

Parameters

New_Tag_Length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains either 0 or the length of the new tag data that is pointed to by New_Tag_Ptr. If New_Tag_Length contains 0 and New_Tag_Ptr contains a nonzero value, the caller's thread tag data is cleared. If New_Tag_Ptr contains a nonzero value, New_Tag_Length must be in the range of 0 to 65. See the usage notes for more details.

New_Tag_Ptr

Supplied parameter

Type:: Pointer
Length:: Fullword (doubleword)

The name of a fullword (doubleword) that contains either 0 or the address of a location that contains the new thread tag data. If New_Tag_Ptr contains 0, the caller's thread tag data is left unchanged. See the usage notes for more details.

Old_Tag_Length

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the pthread_tag_np service returns the length of the old (current) thread tag data that is returned to the caller.

Old_Tag_Ptr

Returned parameter

Type:: Pointer
Length:: Fullword (doubleword)

The name of a fullword (doubleword) that contains either 0 or the address of a 65-byte area in which the pthread_tag_np service returns the old (current) thread tag data. If Old_Tag_Ptr contains 0, no thread tag data is returned to the caller and Old_Tag_Length remains unchanged. See the usage notes for more details.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the pthread_tag_np service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the pthread_tag_np service stores the return code. The pthread_tag_np 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 pthread_tag_np service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EFAULT	One or more of the following conditions were detected: All or part of the location that is specified by New_Tag_Ptr and New_Tag_Length was not addressable by the caller. All or part of the 66 bytes at the location that is specified by Old_Tag_Ptr was not addressable by the caller. The following reason codes can accompany the return code: JRNewLocationErr, or JROldLocationErr.
EINVAL	New_Tag_Ptr was nonzero, but New_Tag_Length was not in the range of 0 to 65. The following reason code can accompany the return code: JRNewLenBad.

Return_code

Explanation

EFAULT

One or more of the following conditions were detected:

All or part of the location that is specified by New_Tag_Ptr and New_Tag_Length was not addressable by the caller.
All or part of the 66 bytes at the location that is specified by Old_Tag_Ptr was not addressable by the caller.

The following reason codes can accompany the return code: JRNewLocationErr, or JROldLocationErr.

EINVAL

New_Tag_Ptr was nonzero, but New_Tag_Length was not in the range of 0 to 65. The following reason code can accompany the return code: JRNewLenBad.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the pthread_tag_np service stores the reason code. The pthread_tag_np 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

If New_Tag_Ptr contains a nonzero value and New_Tag_Length contains 0, the caller's thread tag data is cleared.
If New_Tag_Ptr contains 0, the caller's thread tag data is left unchanged and the value specified by New_Tag_Length is not validity checked.
If the caller attempts to query the thread tag data and the tag data has never been set or was cleared, no data is stored at the location that is specified by Old_Tag_Ptr and Old_Tag_Length is set to 0.
If New_Tag_Ptr is nonzero, Tag_Length must be in the range of 0 to 65. If it is not within range, the tag data is left unchanged and the pthread_tag_np service is unsuccessful.
Thread tag data is displayed with the DISPLAY OMVS command when 'PID=' option is specified. The thread tag data should be printable (EBCDIC) data.
When Old_Tag_Ptr is nonzero and the caller's thread has tag data associated with it (previously set and not cleared), the pthread_tag_np service stores the tag data (left justified) at the location that is specified by the caller, and Old_Tag_Length contains the length of the data that is stored.

Related services

None.

Characteristics and restrictions

None.

Examples

For an example using this callable service, see BPX1PTT (pthread_tag_np) example.