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