Open List of Semaphores (QP0ZOLSM) API

The Open List of Semaphores (QP0ZOLSM) API lets you generate a list of description information about the semaphores within a semaphore set.

The QP0ZOLSM API places the specified number of list entries in the receiver variable. You can access additional records by using the Get List Entries (QGYGTLE) API. On successful completion of the QP0ZOLSM API, a handle is returned in the list information parameter. You may use this handle on subsequent calls to the following APIs:

• Get List Entries (QGYGTLE)
  
  
• Find Entry Number in List (QGYFNDE)
  
  
• Close List (QGYCLST)

The records returned by QP0ZOLSM include an information status field that describes the completeness and validity of the information. Be sure to check the information status field before using any other information returned.

Authorities and Locks

Job Authority

Service special authority (*SERVICE) is needed to call this API.

For additional information on this authority, see the iSeries Security Reference book.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is used to return the semaphore information that you requested.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable.

List information

OUTPUT; CHAR(80)

Information about the list of semaphores that were opened. For a description of the layout of this parameter, see Format of Open List Information.

Number of records to return

INPUT; BINARY(4)

The number of records in the list to put into the receiver variable.

Format name

INPUT; CHAR(8)

The format of the information to be returned in the receiver variable. You must use the following format name:

LSEM0100

This format is described in LSEM0100 Format.

Semaphore set identifier

INPUT; BINARY(4)

The semaphore set identifier of the semaphore set whose semaphores you would like the information about. The semaphore set identifier can be obtained from calling either the semget(), or QP0ZOLIP API.

Error code

I/O; CHAR(*)

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

LSEM0100 Format

This format name is used to return list information for the semaphores in a semaphore set. The following table shows the information returned in each record in the receiver variable for the LSEM0100 format. For a detailed description of each field, see Field Descriptions.

Field Descriptions

Displacement to wait values. The offset in characters (bytes) from the beginning of the semaphore record to the beginning of the array of wait values.

Last changed qualified job identifier. The job name, the job user profile, and the job number of the thread that last changed the value of the semaphore. The 26 characters are:

These fields will be all blanks if any of the following are true:

• No thread has changed the semaphore value.
  
  
• The process that changed the semaphore has ended.
  
  
• The process that changed the semaphore has not been initialized for signals.

Length of entry. The length of this semaphore record in the list.

Number. The semaphore number in the semaphore set.

Number of waiters. The total number of threads that are waiting for this semaphore to reach a certain value.

Process identifier The process identifier of the last thread to change the value of the semaphore. If no thread has changed the semaphore value, this field will be zero.

Reserved. An ignored field.

Size of waiting information. The size, in bytes, of the record that is used to store information about a thread that is waiting for a semaphore value.

Value. The current value of the semaphore.

Wait value. The value that a thread is waiting for the semaphore to reach. If the value is zero, the thread is waiting for the semaphore value to equal zero. If the value is a positive number, the thread is waiting for the semaphore value to be greater than or equal to this value.

Waiting for positive value. The number of threads that are currently waiting for a semaphore value to reach a positive number.

Waiting for zero. The number of threads that are currently waiting for the semaphore value to reach zero.

Waiting qualified job identifier. The job name, the job user profile, and the job number of the thread that is currently waiting for the semaphore. The 26 characters are:

Error Messages