Retrieve Synchronization Object Information (Qp0msRtvSyncObjInfo()) API


  Required Parameter Group:


  Service Program Name: QP0MSRTVSO

  Default Public Authority: *USE

  Threadsafe: Yes

The Retrieve Synchronization Object Information API (Qp0msRtvSyncObjInfo()) retrieves status information for a synchronization object.


Authorities and Locks

Job Authority
The API must be called from within the job for which the information is being retrieved, or the caller of the API must be running under a user profile that is the same as the job user identity of the job for which the information is being retrieved. Otherwise, the caller of the API must be running under a user profile that has job control (*JOBCTL) special authority.

The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work management topic collection.


Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)

The variable that is to receive the information requested. The number of synchronization object descriptions that are available may exceed the receiver variable capacity. As a result, the receiver variable structure contains only the data that the structure can hold. For example, this may mean that the number of synchronization object entries returned field in the receiver variable does not match the value in the number of synchronization object entries available field.

Length of receiver variable
INPUT; BINARY(4)

The size of the receiver variable structure. If the size provided in the length of receiver variable parameter is larger than the size of the receiver variable allocated in the user program, the results are not predictable. The minimum size is 8 bytes.

Format of receiver variable
INPUT; CHAR(8)

The format of the information returned in the receiver variable. The possible format names are:


Target identification information
INPUT; CHAR(*)

The structure that identifies target information for the specified receiver format. See Format of target identification information for details.

Format of target identification information
INPUT; CHAR(8)

The formats listed below provide job or thread identification information or synchronization object identification information to the appropriate receiver formats. The target ID format must be used with a receiver format listed under Required Receiver Formats in the table below, or the API will fail with the CPE3021 message. The possible format names are:

* The SEMA0100 receiver format is associated with more than one target ID format.


Options variable
INPUT; CHAR(*)

The options available for receiver formats. The Options variable data structure is described in Format of options variable.

Format of options variable
INPUT; CHAR(8)

The format of the information in the options variable. The options format must be used with a receiver format listed under Required Receiver Formats in the table below, or the API will fail with the CPE3021 message. The possible formats are:


Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


PMTX0100 Format - Retrieve pointer-based mutexes associated with a job or thread

This format is used to retrieve information for pointer-based mutexes associated with one or all threads of a job. The following table shows the receiver variable fields returned with the PMTX0100 format. For a detailed description of each field, see Receiver Format Field Descriptions.



PMTX0200 Format - Retrieve threads associated with a pointer-based mutex

This format is used to retrieve information for waiting threads associated with a specified pointer-based mutex. The following table shows the receiver variable fields returned with the PMTX0200 format. For a detailed description of each field, see Receiver Format Field Descriptions.



PMTX0300 Format - Retrieve threads associated with a pointer-based mutex

This format is used to retrieve information for waiting threads associated with a specified pointer-based mutex. The following table shows the receiver variable fields returned with the PMTX0300 format. For a detailed description of each field, see Receiver Format Field Descriptions.



HMTX0100 Format - Retrieve handle-based mutexes associated with a job or thread

This format is used to retrieve information for handle-based mutexes associated with one or all threads of a job. The following table shows the receiver variable fields returned with the HMTX0100 format. For a detailed description of each field, see Receiver Format Field Descriptions.



HMTX0200 Format - Retrieve threads associated with a handle-based mutex

This format is used to retrieve information for waiting threads associated with a specified handle-based mutex. The following table shows the receiver variable fields returned with the HMTX0200 format. For a detailed description of each field, see Receiver Format Field Descriptions.



HMTX0300 Format - Retrieve threads associated with a handle-based mutex

This format is used to retrieve information for waiting threads associated with a specified handle-based mutex. The following table shows the receiver variable fields returned with the HMTX0300 format. For a detailed description of each field, see Receiver Format Field Descriptions.



HCND0100 Format - Retrieve handle-based conditions associated with a job or thread

This format is used to retrieve information for handle-based conditions associated with one or all threads of a job. The following table shows the receiver variable fields returned with the HCND0100 format. For a detailed description of each field, see Receiver Format Field Descriptions.



HCND0200 Format - Retrieve threads associated with a handle-based condition

This format is used to retrieve information for waiting threads associated with a specified handle-based condition. The following table shows the receiver variable fields returned with the HCND0200 format. For a detailed description of each field, see Receiver Format Field Descriptions.



HCND0300 Format - Retrieve threads associated with a handle-based condition

This format is used to retrieve information for waiting threads associated with a specified handle-based condition. The following table shows the receiver variable fields returned with the HCND0300 format. For a detailed description of each field, see Receiver Format Field Descriptions.



STOK0100 Format - Retrieve synchronization tokens associated with a job or thread

This format is used to retrieve information for synchronization tokens associated with one or all threads of a job. The following table shows the receiver variable fields returned with the STOK0100 format. For a detailed description of each field, see Receiver Format Field Descriptions.



STOK0200 Format - Retrieve threads associated with a synchronization token

This format is used to retrieve information for waiting threads associated with a specified synchronization token. The following table shows the receiver variable fields returned with the STOK0200 format. For a detailed description of each field, see Receiver Format Field Descriptions.

STOK0300 Format - Retrieve threads associated with a synchronization token

This format is used to retrieve information for waiting threads associated with a specified synchronization token. The following table shows the receiver variable fields returned with the STOK0300 format. For a detailed description of each field, see Receiver Format Field Descriptions.



SEMA0100 Format - Retrieve semaphores associated with a job, thread, or all semaphores

This format is used to retrieve information for semaphores associated with one or all threads of a job or all semaphores on a system. The following table shows the receiver variable fields returned with the SEMA0100 format. For a detailed description of each field, see Receiver Format Field Descriptions.



SEMA0200 Format - Retrieve threads associated with a semaphore

This format is used to retrieve information for waiting threads associated with a specified semaphore. The following table shows the receiver variable fields returned with the SEMA0200 format. For a detailed description of each field, see Receiver Format Field Descriptions.



SEMA0300 Format - Retrieve threads associated with a semaphore

This format is used to retrieve information for waiting threads associated with a specified semaphore. The following table shows the receiver variable fields returned with the SEMA0300 format. For a detailed description of each field, see Receiver Format Field Descriptions.



Receiver Format Field Descriptions

Bytes available. The number (in bytes) of all data that can be returned. All available data is returned if enough space in the receiver variable is provided.

Bytes returned. The number (in bytes) of data returned in the receiver variable. Only complete descriptions are returned.

Condition creator program. The first 8 characters of the name of the program module that created the condition. This field is for debug purposes only and should not be used for building applications based on its contents.

Condition key. A unique system-wide value that is assigned to a handle-based condition for sharing between jobs. If a condition was created without a key, this field contains binary 0.

Condition reference. A replica of a handle-based condition. Additional information for the condition replica returned in this field can be retrieved using this API and the HCND0200 and HCND0300 formats.

Description of thread waiting for condition. Structure that contains a description of a thread waiting on the specified condition. This structure is repeated as needed to describe all threads waiting on the specified condition. Only complete descriptions are returned.

Description of thread waiting for mutex. Structure that contains a description of a thread waiting on the specified mutex. This structure is repeated as needed to describe all threads waiting on the specified mutex. Only complete descriptions are returned.

Description of thread waiting for semaphore. Structure that contains a description of a thread waiting on the specified semaphore. This structure is repeated as needed to describe all threads waiting on the specified semaphore. Only complete descriptions are returned.

Description of thread waiting for token. Structure that contains a description of a thread waiting on the specified token. This structure is repeated as needed to describe all threads waiting on the specified token. Only complete descriptions are returned.

Description sequence value for the thread associated with the mutex. The sequence number of a description in the range of the total number of descriptions for a thread identifier. This value can be used in the form "M of N descriptions", in which M is the description sequence value for the thread and N is the total number of descriptions for the thread.

Description sequence value for the thread associated with the token. The sequence number of a description in the range of the total number of descriptions for a thread identifier. This value can be used in the form "M of N descriptions", in which M is the description sequence value for the thread and N is the total number of descriptions for the thread.

Handle-based condition description. Contains fields that describe a handle-based condition associated with the specified job or thread. This structure is repeated as needed to include all available handle-based condition descriptions. Only complete descriptions are returned.

Handle-based mutex description. Contains fields that describe a handle-based mutex associated with the specified job or thread. This structure is repeated as needed to include all available handle-based mutex descriptions. Only complete descriptions are returned.

Is signaled flag. Indicates if the condition is in the signaled or nonsignaled state.

Keep valid flag. Indicates if the mutex was created with the keep valid option. Possible values follow:

Last condition setter job name. Job name of the job containing the last thread that performed a set or pulse operation on the condition and caused the condition to become signaled. If this field is all blanks, no job has ever performed a set operation on the condition, or the last setter job has ended and the API could not collect this information.

Last condition setter job number. Job number of the job containing the last thread that performed a set or pulse operation on the condition and caused the condition to become signaled. If this field is all blanks, no job has ever performed a set operation on the condition, or the last setter job ended and the API could not collect this information.

Last condition setter thread identifier. Job-specific thread identifier for the thread that performed a set or pulse operation on the condition and caused the condition to become signaled. If this field is binary 0, no thread has ever performed a set operation on the condition, or the last setter thread has ended and the API could not collect this information.

Last condition setter thread unique value. A system-wide unique value that identifies the specific thread that last performed a set or pulse operation on the condition and caused the condition to become signaled. If this field is binary 0, no thread has ever performed a set operation on the condition. This field cannot be used as input on any other API but may be useful for debug purposes.

Last condition setter user name. User name of the job containing the last thread that performed a set or pulse operation on the condition and caused the condition to become signaled. If this field is all blanks, no job has ever performed a set operation on the condition, or the last setter job ended and the API could not collect this information.

Last condition waiter job name. Job name of the job containing the last thread that had to wait for another thread to set the condition to a signaled state before becoming unblocked. If this field is all blanks, no job has ever waited on the condition, or the last waiter job has ended and the API could not collect this information.

Last condition waiter job number. Job number of the job containing the last thread that had to wait for another thread to set the condition to a signaled state before becoming unblocked. If this field is all blanks, no job has ever waited on the condition, or the last waiter job has ended and the API could not collect this information.

Last condition waiter thread identifier. Job-specific thread identifier for the last thread that had to wait for another thread to set the condition to a signaled state before becoming unblocked. If this field is binary 0, no thread has ever waited on the condition, or the last waiter thread has ended and the API could not collect this information.

Last condition waiter thread unique value. A system-wide unique value that identifies the specific thread that last had to wait for another thread to set the condition to a signaled state before becoming unblocked. If this field is binary 0, no thread has ever waited on the condition. This field cannot be used as input on any other API but may be useful for debug purposes.

Last condition waiter user name. User name of the job containing the last thread that had to wait for another thread to set the condition to a signaled state before becoming unblocked. If this field is all blanks, no job has ever waited on the condition, or the last waiter job has ended and the API could not collect this information.

Last mutex locker job name. Job name of the job containing the thread that last locked the mutex after waiting for another thread to unlock the mutex. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a job name for a job other than the one that last performed a lock operation on the mutex. If this field is all blanks, no job has ever locked the mutex after waiting, or the last locker job has ended and the API could not collect this information.

Last mutex locker job number. Job number of the job containing the thread that last locked the mutex after waiting for another thread to unlock the mutex. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a job number for a job other than the one that last performed a lock operation on the mutex. If this field is all blanks, no job has ever locked the mutex after waiting, or the last locker job has ended and the API could not collect this information.

Last mutex locker thread identifier. Job-specific thread identifier for the thread within the job that last locked the mutex after waiting for another thread to unlock the mutex. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a thread identifier for a thread other than the one that last performed a lock operation on the mutex. If this field is binary 0, no thread has ever locked the mutex after waiting for another thread to unlock the mutex, or the last locker thread has ended and the API could not collect this information.

Last mutex locker thread unique value. A system-wide unique value that identifies the specific thread that last locked the mutex after waiting for another thread to unlock the mutex. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a unique value for a thread other than the one that last performed a lock operation on the mutex. If this field is binary 0, no thread has ever locked the mutex after waiting for another thread to unlock the mutex. This field cannot be used as input on any other API but may be useful for debug purposes.

Last mutex locker user name. User name of the job containing the thread that last locked the mutex after waiting for another thread to unlock the mutex. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a user name for a job other than the one that last performed a lock operation on the mutex. If this field is all blanks, no job has ever locked the mutex after waiting, or the last locker job has ended and the API could not collect this information.

Last mutex unlocker job name. Job name of the job containing the thread that last unlocked the mutex while waking another thread that was waiting. A thread may perform an unlock operation and immediately unlock the mutex without waking another thread if there are no other threads waiting. As a result, this field may contain a job name for a job other than the one that last performed an unlock operation on the mutex. If this field is all blanks, no job has ever unlocked the mutex while waking another thread that was waiting, or the last unlocker job has ended and the API could not collect this information.

Last mutex unlocker job number. Job number of the job containing the thread that last unlocked the mutex while waking another thread that was waiting. A thread may perform an unlock operation and immediately unlock the mutex without waking another thread if there are no other threads waiting. As a result, this field may contain a job number for a job other than the one that last performed an unlock operation on the mutex. If this field is all blanks, no job has ever unlocked the mutex while waking another thread that was waiting, or the last unlocker job has ended and the API could not collect this information.

Last mutex unlocker thread identifier. Job-specific thread identifier for the thread within the job that last unlocked the mutex while waking another thread that was waiting. A thread may perform an unlock operation and immediately unlock the mutex without waking another thread if there are no other threads waiting. As a result, this field may contain a thread identifier for a thread other than the one that last performed an unlock operation on the mutex. If this field is binary 0, no thread has ever unlocked the mutex while waking another thread that was waiting, or the last unlocker thread has ended and the API could not collect this information.

Last mutex unlocker thread unique value. A system-wide unique value that identifies the specific thread that last unlocked the mutex while waking another thread that was waiting. A thread may perform an unlock operation and immediately unlock the mutex without waking another thread if there are no other threads waiting. As a result, this field may contain a unique value for a thread other than the one that last performed an unlock operation on the mutex. If this field is binary 0, no thread has ever unlocked the mutex while waking another thread that was waiting. This field cannot be used as input on any other API but may be useful for debug purposes.

Last mutex unlocker user name. User name of the job containing the thread that last unlocked the mutex while waking another thread that was waiting. A thread may perform an unlock operation and immediately unlock the mutex without waking another thread if there are no other threads waiting. As a result, this field may contain a user name for a job other than the one that last performed an unlock operation on the mutex. If this field is all blanks, no job has ever unlocked the mutex while waking another thread that was waiting, or the last unlocker job has ended and the API could not collect this information

Last semaphore post operation job name. The job name for the job containing the thread that last incremented the semaphore count. If this field is all blanks, the semaphore has not been successfully posted, or the thread that performed the last post operation has ended and the API could not collect this information.

Last semaphore post operation job number. The job number for the job containing the thread that last incremented the semaphore count. If this field is all blanks, the semaphore has not been successfully posted, or the thread that performed the last post operation has ended and the API could not collect this information.

Last semaphore post operation thread identifier. A job-specific thread identifier for the thread that last incremented the semaphore count. If this field is binary 0, the semaphore has not been successfully posted, or the thread that performed the last post operation has ended and the API could not collect this information.

Last semaphore post operation thread unique value. A system-wide unique value that identifies the specific thread that last incremented the semaphore count. If this field is binary 0, the semaphore has not been successfully posted. This field cannot be used as input on any other API but may be useful for debug purposes.

Last semaphore post operation user name. The user name for the job containing the thread that last incremented the semaphore count. If this field is all blanks, the semaphore has not been successfully posted, or the thread that performed the last post operation has ended and the API could not collect this information.

Last semaphore wait operation job name. The job name for the job containing the thread that last decremented the semaphore count. If this field is all blanks, the semaphore has not been successfully decremented, or the thread that performed the last wait operation has ended and the API could not collect this information.

Last semaphore wait operation job number. The job number for the job containing the thread that last decremented the semaphore count. If this field is all blanks, the semaphore has not been successfully decremented, or the thread that performed the last wait operation has ended and the API could not collect this information.

Last semaphore wait operation thread identifier. A job-specific thread identifier for the thread within the job that last decremented the semaphore count. If this field is binary 0, the semaphore has not been successfully decremented, or the thread that performed the last wait operation has ended and the API could not collect this information.

Last semaphore wait operation thread unique value. A system-wide unique value that identifies the specific thread that last decremented the semaphore count. If this field is binary 0, the semaphore has not been successfully decremented. This field cannot be used as input on any other API but may be useful for debug purposes.

Last semaphore wait operation user name. The user name for the job containing the thread that last decremented the semaphore count. If this field is all blanks, the semaphore has not been successfully decremented or the thread that performed the last wait operation has ended and the API could not collect this information.

Last token locker job name. Job name of the job containing the thread that last locked the token after waiting for another thread to unlock the token. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a job name for a job other than the one that last performed a lock operation on the token. If this field is all blanks, no job has ever locked the token after waiting, or the last locker job has ended and the API could not collect this information.

Last token locker job number. Job number of the job containing the thread that last locked the token after waiting for another thread to unlock the token. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a job number for a job other than the one that last performed a lock operation on the token. If this field is all blanks, no job has ever locked the token after waiting, or the last locker job has ended and the API could not collect this information.

Last token locker thread identifier. Job-specific thread identifier for the thread within the job that last locked the token after waiting for another thread to unlock the token. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a thread identifier for a thread other than the one that last performed a lock operation on the token. If this field is binary 0, no thread has ever locked the token after waiting for another thread to unlock the token, or the last locker thread has ended and the API could not collect this information.

Last token locker thread unique value. A system-wide unique value that identifies the specific thread that last locked the token after waiting for another thread to unlock the token. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a unique value for a thread other than the one that last performed a lock operation on the token. If this field is binary 0, no thread has ever locked the token after waiting for another thread to unlock the token. This field cannot be used as input on any other API but may be useful for debug purposes.

Last token locker user name. User name of the job containing the thread that last locked the token after waiting for another thread to unlock the token. A thread may perform a lock operation and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, this field may contain a user name for a job other than the one that last performed a lock operation on the token. If this field is all blanks, no job has ever locked the token after waiting, or the last locker job has ended and the API could not collect this information.

Last token unlocker job name. Job name of the job containing the thread that last unlocked the token while waking another thread that was waiting. A thread may perform an unlock operation and immediately unlock the token without waking another thread if there are no other threads waiting. As a result, this field may contain a job name for a job other than the one that last performed an unlock operation on the token. If this field is all blanks, no job has ever unlocked the token while waking another thread that was waiting, or the last unlocker job has ended and the API could not collect this information.

Last token unlocker job number. Job number of the job containing the thread that last unlocked the token while waking another thread that was waiting. A thread may perform a lock operation and immediately unlock the token without waking another thread if there are no other threads waiting. As a result, this field may contain a job number for a job other than the one that last performed an unlock operation on the token. If this field is all blanks, no job has ever unlocked the token while waking another thread that was waiting, or the last unlocker job has ended and the API could not collect this information.

Last token unlocker thread identifier. Job-specific thread identifier for the thread within the job that last unlocked the token while waking another thread that was waiting. A thread may perform a lock operation and immediately unlock the token without waking another thread if there are no other threads waiting. As a result, this field may contain a thread identifier for a thread other than the one that last performed an unlock operation on the token. If this field is binary 0, no thread has ever unlocked the token while waking another thread that was waiting, or the last unlocker thread has ended and the API could not collect this information.

Last token unlocker thread unique value. A system-wide unique value that identifies the specific thread that last unlocked the token while waking another thread that was waiting. A thread may perform a lock operation and immediately unlock the token without waking another thread if there are no other threads waiting. As a result, this field may contain a unique value for a thread other than the one that last performed an unlock operation on the token. If this field is binary 0, no thread has ever unlocked the token while waking another thread that was waiting. This field cannot be used as input on any other API but may be useful for debug purposes.

Last token unlocker user name. User name of the job containing the thread that last unlocked the token while waking another thread that was waiting. A thread may perform an unlock operation and immediately unlock the token without waking another thread if there are no other threads waiting. As a result, this field may contain a user name for a job other than the one that last performed an unlock operation on the token. If this field is all blanks, no job has ever unlocked the token while waking another thread that was waiting, or the last unlocker job has ended and the API could not collect this information.

Length of condition descriptions. Size (in bytes) of one condition description returned by this call. Only complete descriptions are returned.

Length of mutex descriptions. Size (in bytes) of one mutex description returned by this call. Only complete descriptions are returned.

Length of semaphore descriptions. Size (in bytes) of one semaphore description returned by this call. Only complete descriptions are returned.

Length of token descriptions. Size (in bytes) of one synchronization token description returned by this call. Only complete descriptions are returned.

Length of waiting thread descriptions. Size (in bytes) of one waiting thread description returned by this call. Only complete descriptions are returned.

Lock count. Indicates the current count for the number of times the mutex has been locked. When the mutex is created as a recursive mutex, this field may contain a value greater than one.

Mutex creator program. The first 8 characters of the name of the program module that created the mutex. This field is for debug purposes only and should not be used for building applications based on its contents.

Mutex key. A unique system-wide value that is assigned to a handle-based mutex for sharing between jobs. If a handle-based mutex was created without a key, this field contains binary 0.

Mutex owner job name. Job name associated with a job that contains the thread that holds the lock on a pointer-based or handle-based mutex. If the mutex owner job name is blanks, the mutex is not locked or the thread that holds the lock on the mutex has ended.

Mutex owner job number. Job number associated with a job that contains the thread that holds the lock on a pointer-based or handle-based mutex. If the mutex owner job number is blanks, the mutex is not locked or the thread that holds the lock on the mutex has ended.

Mutex owner thread identifier. Job-specific thread identifier for a thread that holds the lock on a pointer-based or handle-based mutex. If the mutex owner thread identifier field contains binary 0, the mutex is not locked or the thread that holds the lock on the mutex has ended.

Mutex owner thread unique value. A system-wide unique value identifying a thread owning a pointer-based or handle-based mutex. If the mutex owner thread unique value field is binary 0, the mutex is not locked. This field should be used for debug purposes only.

Mutex owner user name. User name associated with a job that contains the thread that holds the lock on a pointer-based or handle-based mutex. If the mutex owner user name is blanks, the mutex is not locked or the thread that holds the lock on the mutex has ended.

Mutex name. The field containing the mutex name may have the following formats:

  1. 16 characters, left-justified, and padded to the right with blanks.
  2. "UNNAMED_" + first 8 characters of the program that created the mutex (if the mutex is created without a name)

Mutex reference. A mutex address or a replica of a mutex. Additional information for the mutex reference returned in this field can be retrieved using this API and the PMTX0200 and PMTX0300 formats for pointer-based mutexes or the HMTX0200 and HMTX0300 formats for handle-based mutexes.

Mutex state. Indicates mutex status. Possible values follow:

Number of condition descriptions available. Total number of descriptions available to describe all conditions associated with one or more threads.

Number of condition descriptions returned. Number of condition descriptions returned by this call.

Number of mutex descriptions available. Total number of descriptions available to describe all pointer-based or handle-based mutexes associated with one or more threads.

Number of mutex descriptions returned. Number of pointer-based or handle-based mutex descriptions returned by this call.

Number of semaphore descriptions available. Total number of descriptions available to describe all semaphores of the specified type for the specified job or thread or for the entire system.

Number of semaphore descriptions returned. Number of semaphore descriptions returned by this call.

Number of thread descriptions for identified thread. Total number of descriptions available for the identified thread.

Number of threads in job. Total number of active threads in the specified job at the time of the call. This number is not applicable when information is retrieved for a single thread and contains binary 0 in this case.

Number of threads waiting on condition. The number of threads that are currently waiting for the condition to be set.

Number of threads waiting on mutex. The number of threads currently waiting for the mutex to become unlocked.

Number of threads waiting on semaphore. The number of threads that are currently waiting for the semaphore to be posted.

Number of threads waiting on token. The number of threads that are currently waiting for the token to be unlocked.

Number of token descriptions available. Total number of descriptions available to describe all synchronization tokens associated with one or more threads.

Number of token descriptions returned. Number of synchronization token descriptions returned by this call. Only complete descriptions are returned.

Number of waiting thread descriptions available. Number of descriptions available to describe all threads waiting on the associated synchronization object.

Number of waiting thread descriptions returned. Number of waiting thread descriptions returned by this call. Only complete descriptions are returned.

Offset to condition descriptions. The length (in bytes) from the start of the structure to the location of the condition descriptions. If the receiver does not contain enough space for at least one description, this field contains binary 0.

Offset to mutex descriptions. The length (in bytes) from the start of the structure to the location of the mutex descriptions. If the receiver does not contain enough space for at least one description, this field contains binary 0.

Offset to semaphore descriptions. The length (in bytes) from the start of the structure to the location of the semaphore descriptions. If the receiver does not contain enough space for at least one description, this field contains binary 0.

Offset to token descriptions. The length (in bytes) from the start of the structure to the location of the token descriptions. If the receiver does not contain enough space for at least one description, this field contains binary 0.

Offset to waiting thread descriptions. The length (in bytes) from the start of the structure to the location of the waiting thread descriptions. If the receiver does not contain enough space for at least one description, this field contains binary 0.

Original mutex. A space pointer to a mutex. If this API returns information for a mutex that is a copy of another mutex, the original mutex is the address of the mutex from which the copy was made. Copies of mutex copies are permitted; however, this field always points to the original mutex from which the first copy was made.

Original semaphore. A space pointer to a semaphore. If this API returns information for a semaphore that is a copy of another semaphore, the original semaphore is the address of the semaphore from which the copy was made. Copies of semaphore copies are permitted; however, this field always points to the original semaphore from which the first copy was made.

Pending state flag. Indicates if the mutex is currently in a state where it must be revived because the thread holding the lock on the mutex terminated. This field is only valid when the keep valid flag is set to mutex will remain valid when its owning thread is terminated. Possible values follow:

Pointer-based mutex description. Contains fields that describe a pointer-based mutex associated with a thread. This structure is repeated as needed to include all available pointer-based mutex descriptions. Only complete descriptions are returned.

Recursive flag. Indicates if the mutex was created to be a recursive mutex. Possible values follow:

Reserved. An unused field. This field contains binary 0.

Reset mode flag. Indicates the reset mode this condition was created with. If the condition is marked for cleanup, reset mode flag is set to invalid.

Semaphore associated job name. Job name associated with the identified semaphore. This field contains blanks when all semaphores are retrieved on a system.

Semaphore associated job number. Job number associated with the identified semaphore. This field contains blanks when all semaphores are retrieved on a system.

Semaphore associated user name. User name associated with the identified semaphore. This field contains blanks when all semaphores are retrieved on a system.

Semaphore count value. The current count value for the semaphore.

Semaphore creator program. The first 8 characters of the name of the program module that created the semaphore. This field is for debug purposes only and should not be used for building applications based on its contents.

Semaphore description. Contains fields that describe a semaphore associated with a thread. This structure is repeated as needed to include all available semaphore descriptions. Only complete descriptions are returned.

Semaphore key. A system-wide unique value that is assigned to name-based semaphores for sharing between jobs. The field is not applicable to pointer-based semaphores and is set to binary 0 in this case.

Semaphore maximum count. The maximum count for the semaphore specified at creation.

Semaphore reference. A replica of a semaphore. Additional information for the semaphore replica returned in this field can be retrieved using this API and the SEMA0200 and SEMA0300 formats.

Semaphore title. Semaphore description text specified during semaphore creation.

Semaphore type. Indicates the type of semaphore. Possible values follow:

Semaphore unlinked status. Indicates whether a name-based semaphore is linked or unlinked. The field does not apply to pointer-based semaphores and contains binary 0 in this case. Possible values follow:

Thread identifier associated with condition. A job-specific thread identifier that specifies a thread in a job that is associated with a handle-based condition.

Thread identifier associated with mutex. A job-specific thread identifier that specifies a thread in a job that is associated with a pointer-based or handle-based mutex.

Thread identifier associated with semaphore. A job-specific thread identifier that specifies a thread in a job that is associated with a semaphore. This field is not applicable when all semaphores on a system are retrieved and contains binary 0 for this case.

Thread identifier associated with token. A job-specific thread identifier that specifies a thread in a job that is associated with a synchronization token.

Token creator program. The first 8 characters of the name of the program module that is associated with the thread that first waited on the token. This field is for debug purposes only and should not be used for building applications based on its contents.

Token description. Contains fields that describe a synchronization token associated with a thread. This structure is repeated as needed to include all available synchronization token descriptions. Only complete descriptions are returned.

Token owner job name. Job name associated with a job that contains the thread that holds the lock on a synchronization token. If token owner job name is all blanks, the token is not locked or the thread that holds the lock on the token has ended.

Token owner job number. Job number associated with a job that contains the thread that holds the lock on a synchronization token. If token owner job number is all blanks, the token is not locked or the thread that holds the lock on the token has ended.

Token owner thread identifier. A job-specific thread identifier for a thread that holds the lock on a synchronization token. If token lock owner thread identifier is binary 0, the token is not locked or the thread that holds the lock on the token has ended.

Token owner thread unique value. A system-wide unique value identifying the thread that holds the lock on a synchronization token. If token owner unique thread value is binary 0, the token is not locked. This field should be used for debug purposes only.

Token owner user name. User name associated with a job that contains the thread that holds the lock on a synchronization token. If token owner user name is all blanks, the token is not locked or the thread that holds the lock on the token has ended.

Token reference. A synchronization token address or a replica of a synchronization token. Additional information for the synchronization token reference returned in this field can be retrieved using this API and the STOK0200 and STOK0300 formats.

Token state. Indicates synchronization token status. Possible values follow:

Token unique value. A system-wide unique value that identifies a token. This field should be used for debug purposes only.

Waiter thread job name. Job name associated with a job containing the thread waiting on a synchronization object. If waiter thread job name is all blanks, the thread waiting on the synchronization object has ended, and the API could not collect this information. This is a normal state for threads that have waited on a synchronization object successfully and ended.

Waiter thread job number. Job number associated with a job containing the thread waiting on a synchronization object. If waiter thread job number is all blanks, the thread waiting on the synchronization object has ended, and the API could not collect this information. This is a normal state for threads that have waited on a synchronization object successfully and ended.

Waiter thread identifier. A job-specific thread identifier that specifies a thread waiting on a synchronization object. If the waiter thread identifier field contains binary 0, the thread waiting on the synchronization object has ended, and the API could not collect this information. This is a normal state for threads that have waited on a synchronization object successfully and ended.

Waiter thread unique value. A system-wide unique value identifying a thread waiting on a synchronization object. This field should be used for debug purposes only.

Waiter thread user name. User name associated with a job containing the thread waiting on a synchronization object. If waiter thread user name is all blanks, the thread waiting on the synchronization object has ended, and the API could not collect this information. This is a normal state for threads that have waited on a synchronization object successfully and ended.


TIDF0100 Format - Job and Thread Identification

This format is used to identify a job or thread. A job can be identified by an Internal job identifier or the Job name, User name, and Job number fields. For a detailed description of each field, see TIDF0100 Format Field Descriptions.



TIDF0100 Format Field Descriptions

Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the Job name parameter, this parameter must contain binary 0. With this parameter, the system can locate the job more quickly than with the Job name, Job number, and User name.

Job name. A specific job name or one of the following special values:

Job number. A specific job number or binary 0 when the Job name specified is a special value.

Reserved. An unused field. This field must contain binary 0.

Thread identifier. A value that uniquely identifies a thread within a job. Because a thread identifier is job-specific, the Job name, User name, and Job Number or the Internal job identifier must also be provided to identify a thread.

Thread indicator. A value that is used to specify the thread or job for which information is to be retrieved. The following values are supported:

Note: For all supported values, the combination of the Internal job identifier, Job name, Job number, User name, and Thread identifier fields must identify the job containing the specified thread or threads.

User name. A specific user profile name or binary 0 when the Job name specified is a special value.


TIDF0200 Format - Synchronization Object Identification

This format is used to identify a synchronization object and any required job information associated with the synchronization object. For a detailed description of each field, see TIDF0200 Format Field Descriptions.



TIDF0200 Format Field Descriptions

Internal job identifier. The internal identifier for the job used with the STOK0200 and STOK0300 formats when the address of a synchronization token is indicated in the Reference specification field. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the Job name parameter, this parameter must contain binary 0. With this parameter, the system can locate the job more quickly than with the Job name, Job number, and User name. This field is not applicable to all other formats and must contain binary 0 in these cases.

Job name. A specific job name or one of the special values in the table below used with the STOK0200 and STOK0300 formats when the address of a synchronization token is indicated in the Reference specification field. This field is not applicable to all other formats and the STOK0200 and STOK0300 formats when replica addresses are provided. The field must contain binary 0 in these cases.

Job number. A specific job number used with the STOK0200 and STOK0300 formats when the address of a synchronization token is indicated in the Reference specification field. If the Job name field contains one of the special values * or *INT, this field must contain binary 0. This field is not applicable to all other formats and to the STOK0200 and STOK0300 formats when replica addresses are provided. The field must contain binary 0 in these cases.

Job specification. Specifies that a specific job will be provided for the STOK0200 and STOK0300 formats when information is to be retrieved for a synchronization token in another process. This field is not applicable to all other formats and to the STOK0200 and STOK0300 formats when replica addresses are provided. This field must contain binary 0 in these cases.

Reference address. The address of a synchronization object or the address of the replica of a synchronization object.

Reference specification. Selects address of a synchronization object or the address of a replica of a synchronization object. This field is only applicable to the STOK0200 and STOK0300 formats. The possible values of this field are:

Reserved. An unused field. This field must contain binary 0.

User name. A specific user profile name used for the STOK0200 and STOK0300 formats when the address of a synchronization object is indicated in the Reference specification field. If the Job name field contains one of the special values '* ' or '*INT ', this field must contain binary 0. This field is not applicable to all other formats and to the STOK0200 and STOK0300 formats when replica addresses are provided. The field must contain binary 0 in these cases.


OPTN0100 Format - Options for Receiver Variable

This format is used to control data retrieved in the Receiver variable. For a detailed description of each field, see OPNT0100 Format Field Descriptions.



OPTN0100 Format Field Descriptions

References. Selects addresses or replicas for the synchronization object associated with the format. If addresses are selected, only those synchronization objects that the issuing thread has addressability to can be retrieved. If replicas are selected, all synchronization objects for the specified thread or threads are retrieved. The following values are allowed:

Note: This field is used only with the PMTX0100 and STOK0100 formats. For the HMTX0100, HCND0100, and SEMA0100 formats replicas are always returned. If the field does not apply to the current request, this field must contain binary 0.

Reserved. An unused field. This field must contain binary 0.

Semaphore filter. Retrieves information for semaphores associated with a specified job or thread, all semaphores system wide, or all name-based semaphores in a job. This field is used only with the SEMA0100 format and must contain binary 0 for all other formats. The following values are allowed:

Note: For all other formats, this field must contain binary 0.

Semaphore selection. Selects type of semaphore information to be retrieved for the SEMA0100 format when Semaphore Filter is '0' or '1'. For all other formats this field must contain binary 0. The following values are allowed:

Note: This field is not applicable when the Semaphore filter field indicates that information should be retrieved for all name-based semaphores in a job. If the field does not apply to the current request, the field must contain binary 0.

Thread status. Selects status of mutexes or tokens that are retrieved. The following values are allowed:

Note: This field is used only with the PMTX0100, HMTX0100, and STOK0100 formats. If the field does not apply to the current request, the field must contain binary 0.


Error Messages



Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include "qp0msrtvso.H"
#include <qusec.h>                 /*Error code structures */
#include <string.h>
#include <stdio.h>
#include <mih/crtmtx.h>
#include <mih/lockmtx.h>
#include <mih/desmtx.h>
#include <mih/unlkmtx.h>
#include <except.h>

/*******************************************************************/
/* Description: This program creates and locks two pointer-based   */
/* mutexes. It then calls Qp0msRtvSyncObjInfo() with the PMTX0100  */
/* format to retrieve a list of consisting of the two mutexes. The */
/* program uses one of the mutex addresses as the input of         */
/* Qp0msRtvSyncObjInfo() with the PMTX0200 format to retrieve      */
/* additional information about that mutex.                        */
/*******************************************************************/

int main (int argc, char *argv[]) {

  char pmutex1[32];
  char pmutex2[32];

  char pointer[16];
  Qp0ms_TIDF0200 target2;
  memset(&target2, 0, sizeof(Qp0ms_TIDF0200));
  
  _OPENPTR address_of_mutex;  
  
  /* Creation of pointer-based mutex */
  _Mutex_Create_T pmtx_options;
  memset(&pmtx_options, 0x00, sizeof(_Mutex_Create_T));

  int result;
  result = _CRTMTX( (_Mutex_T *) pmutex1, &pmtx_options ); 
  result = _CRTMTX( (_Mutex_T *) pmutex2, &pmtx_options );

  /* Lock pointer-based mutexes */
  _Mutex_Lock_T lock_template;
  _LOCKMTX((_Mutex_T *) pmutex1, &lock_template);
  _LOCKMTX((_Mutex_T *) pmutex2, &lock_template);
    
  /**** Create Qp0msRtvSyncObjInfo parameters ****/

  // This call allocates space for 1 mutex description
  char * receiver = new char[sizeof(Qp0ms_PMTX0100_List_t) + 1*sizeof(Qp0ms_PMtxDesc_t)];
  int length = sizeof(Qp0ms_PMTX0100_List_t) + 1*sizeof(Qp0ms_PMtxDesc_t);
  Qus_EC_t err_code;

  /**** Initialize options structure ****/
  Qp0ms_OPTN0100_t options; 
  memset(&options, 0x00, sizeof(Qp0ms_OPTN0100_t) );
  options.References = '0';
  options.Thread_Status = '0';

  /**** Initialize target structure ****/
  Qp0ms_TIDF0100_t target;
  memset(&target, 0x00, sizeof(Qp0ms_TIDF0100_t) );
  target.Thread_Indicator = '1';

  /**** Initialize error code structure ****/
  memset(&err_code, 0x00, sizeof(Qus_EC_t) );
  err_code.Bytes_Provided = sizeof(Qus_EC_t);
  
  /* Call Retrieve Synchronization Object Information API */
  Qp0msRtvSyncObjInfo(receiver, &length, "PMTX0100", &target, "TIDF0100",
  &options, "OPTN0100", &err_code);

  Qp0ms_PMtxDesc_t * Mutex_Desc = (Qp0ms_PMtxDesc_t *)((char *) receiver + ((Qp0ms_PMTX0100_List_t *)
   receiver)->Desc_Offset);

  printf("********************Results of Qp0msRtvSyncObjInfo() *************\n");

  if ( err_code.Bytes_Available != 0 )
    printf("This call failed with error %7.7s\n", err_code.Exception_Id);
  else {
    printf("Bytes Returned %d\n", ((Qp0ms_PMTX0100_List *) receiver)->Bytes_Returned);
    printf("Bytes Available %d\n", ((Qp0ms_PMTX0100_List *) receiver)->Bytes_Available);
    printf("Number of Threads %d\n", ((Qp0ms_PMTX0100_List *) receiver)->Num_Threads);
    printf("Number of Descriptions Available %d\n", ((Qp0ms_PMTX0100_List *)
	 receiver)->Num_Desc_Available);
    printf("Number of Descriptions Returned %d\n", ((Qp0ms_PMTX0100_List *)
	 receiver)->Num_Desc_Returned);   
  }
  
  for ( int i = 0; i < ((Qp0ms_PMTX0100_List *) receiver)->Num_Desc_Returned; ++i) {
    if ( err_code.Bytes_Available != 0 )
      printf("This call failed with error %7.7s\n", err_code.Exception_Id);
    else{    
      printf("Mutex information %d\n", i);
      printf("Mutex state: %d\n", Mutex_Desc[i].Mutex_State);
      printf("Mutex Name: %16.16s\n", Mutex_Desc[i].Mutex_Name);

      printf("Mutex Owner Job Information\n");
      printf("Job Name: %10.10s\n", Mutex_Desc[i].Owner_Job_Name);
      printf("Job Number: %6.6s\n", Mutex_Desc[i].Owner_Job_Num);
      printf("User Name: %10.10s\n", Mutex_Desc[i].Owner_User_Name);

      int * tid = (int *) &Mutex_Desc[i].Owner_Thread_Id[0];
      printf("Mutex Owner Thread ID: %4.4x", *tid);
      printf("%4.4x\n", *(tid+1));
      int * thr_uval = (int *) &Mutex_Desc[i].Owner_Thread_Val[0];
      printf("Mutex Owner Thread Unique Value: %4.4x", *thr_uval);
      printf("%4.4x\n", *(thr_uval+1));

      printf("Number of threads waiting on this mutex: %d\n", Mutex_Desc[i].Num_Waiters);
      memcpy(&address_of_mutex, &Mutex_Desc[i].Mutex, sizeof(_OPENPTR));
      address_of_mutex = (_OPENPTR) Mutex_Desc[i].Mutex;
      void * test = Mutex_Desc[i].Mutex;
      memcpy(&test, &Mutex_Desc[i].Mutex, sizeof(void *));
      test = Mutex_Desc[i].Mutex;
      memcpy(pointer, &Mutex_Desc[i].Mutex, 16);
      memcpy(&address_of_mutex, pointer, 16);
      target2.Ref_Address = &Mutex_Desc[i].Mutex;
      if ( ((Qp0ms_PMTX0100_List_t *) receiver)->Bytes_Available > ((Qp0ms_PMTX0100_List_t *)
	   receiver)->Bytes_Returned ){
        printf("More descriptions available.\n");
      }
    }
  }
  
  delete receiver;

  /* Initialize receiver */
  receiver = new char[sizeof(Qp0ms_PMTX0200_List_t) + sizeof(Qp0ms_Waiters)];

  /* Initialize length */
  length = sizeof(Qp0ms_PMTX0200_List_t) + sizeof(Qp0ms_Waiters);

  /* Initialize error code */
  memset(&err_code, 0, sizeof(Qus_EC_t));
  err_code.Bytes_Provided = sizeof(Qus_EC_t);

  /* Call Retrieve Synchronization Object Information API */
  Qp0msRtvSyncObjInfo(receiver, &length, "PMTX0200", &target2, "TIDF0200", NULL, "OPTN0000",
   &err_code);
  
  if ( err_code.Bytes_Available != 0 )
    printf("This call failed with error %7.7s\n", err_code.Exception_Id);
  else {
    printf("Bytes Returned %d\n", ((Qp0ms_PMTX0200_List *) receiver)->Bytes_Returned);
    printf("Bytes Available %d\n", ((Qp0ms_PMTX0200_List *) receiver)->Bytes_Available);
    printf("Number of Threads %d\n", ((Qp0ms_PMTX0200_List *) receiver)->Num_Threads_Waiting);
    printf("Number of Descriptions Available %d\n", ((Qp0ms_PMTX0200_List *)
	 receiver)->Num_Desc_Available);
    printf("Number of Descriptions Returned %d\n", ((Qp0ms_PMTX0200_List *)
	 receiver)->Num_Desc_Returned);
    printf("Mutex Name: %16.16s\n", ((Qp0ms_PMTX0200_List *) receiver)->Mutex_Name);
    int * tid = (int *) &((Qp0ms_PMTX0200_List *) receiver)->Owner_Thread_Id[0];
    printf("Mutex Owner Thread ID: %4.4x", *tid);
    printf("%4.4x\n", *(tid+1));
    int * thr_uval = (int * ) &((Qp0ms_PMTX0200_List *) receiver)->Owner_Thread_Val[0];
    printf("Mutex Owner Thread Unique Value: %4.4x", *thr_uval);
    printf("%4.4x\n", *(thr_uval+1));

    printf("Owner Job Name: %10.10s\n", ((Qp0ms_PMTX0200_List *) receiver)->Owner_Job_Name);
    printf("Owner Job Number: %6.6s\n", ((Qp0ms_PMTX0200_List *) receiver)->Owner_Job_Num);
    printf("Owner User Name: %10.10s\n", ((Qp0ms_PMTX0200_List *) receiver)->Owner_User_Name);

    Qp0ms_Waiters * waiters = (Qp0ms_Waiters *) ((int) receiver + ((Qp0ms_PMTX0200_List *)
	 receiver)->Desc_Offset);
    
    for( int i = 0; i < ((Qp0ms_PMTX0200_List *) receiver)->Num_Desc_Returned; ++i) {
    int * atid = (int *) &waiters[i].Thread_Id[0];
    printf("Mutex %d, Associated Thread ID: %4.4x", i, *atid);
    printf("%4.4x\n", *(atid+1));
    int * athr_uval = waiters[i].Thread_Val;
    printf("Mutex %d Associated Thread Unique Value: %4.4x", i, *athr_uval);
    printf("%4.4x\n", *(athr_uval+1));
    printf("Mutex %d Associated Job Name\n", i, waiters[i].Job_Name);
    printf("Mutex %d Associated User Name\n", i, waiters[i].User_Name);
    printf("Mutex %d Associated Job Number\n", i, waiters[i].Job_Number);
   }
  }

  /* Clean up */
  _UNLKMTX( (_Mutex_T *) pmutex1 );
  _UNLKMTX( (_Mutex_T *) pmutex2 );
  
  _Mutex_Destroy_Opt_T destroy_opt;
  
  _DESMTX( (_Mutex_T *) pmutex1, &destroy_opt );
  _DESMTX( (_Mutex_T *) pmutex2, &destroy_opt );
  
  delete receiver;

}

Example Output

********************Results of Qp0msRtvSyncObjInfo() *************
Bytes Returned 128                                                
Bytes Available 224                                               
Number of Threads 0                                               
Number of Descriptions Available 2                                
Number of Descriptions Returned 1                                 
Mutex information 0                                               
Mutex state: 240                                                  
Mutex Name: UNNAMED_I0_EXAMP                                      
Mutex Owner Job Information                                       
Job Name: QPADEV0004                                              
Job Number: 023786                                                
User Name: USER1                                                 
Mutex Owner Thread ID: 00000060                                   
Mutex Owner Thread Unique Value: b003f000df03000                  
Number of threads waiting on this mutex: 0                        
More descriptions available.                                      
Bytes Returned 96                                                 
Bytes Available 96                              
Number of Threads 0                             
Number of Descriptions Available 0              
Number of Descriptions Returned 0               
Mutex Name: UNNAMED_I0_EXAMP                    
Mutex Owner Thread ID: 00000060                 
Mutex Owner Thread Unique Value: b003f000df03000
Owner Job Name: QPADEV0004                      
Owner Job Number: 023786                        
Owner User Name: USER1

API introduced: V5R3

[ Back to top | Work Management APIs | APIs by category ]