osi_wait — Wait for an event to occur

Function

The osi_wait service waits for a signal to occur or for osi_post to be called.

Requirements

Operation	Environment
Authorization:	Problem or supervisor state, any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any
AMODE:	31-bit
ASC mode:	Any
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

     osi_wait(Entry_code,
              OSI_structure,
              Return_code,
             [Wait_Flags,
              Time_interval]);

Parameters

Entry_code

Supplied parameter

Type:: Integer
Length:: Fullword

The Entry_code specifies the function that is being requested for the osi_wait service.

Entry_code	Explanation
OSI_SETUP	Set up for a subsequent wait request.
OSI_SETUPSIG	Set up for a subsequent wait request with signals enabled.
OSI_SUSPEND	Wait to be posted from osi_post.
OSI_WAITX	Wait to be posted from osi_post or for a timer to expire.
OSI_INIT2	Initialize for use by an independent task. See the usage notes.

OSI_structure

Supplied and returned parameter

Type:: OSI
Length:: Specified by OSI.osi_hdr.cblen.

OSI_structure contains information that is used by the OSI operations. The PFS receives this structure on each PFS interface operation.

Refer to Interface structures for C language servers and clients for a full description of this structure.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_wait service stores the return code. The osi_wait service can return one of the following values in the Return_code parameter:

Return_code	Explanation
OSI_POSTED	Successful completion.
OSI_SIGNALRCV	A signal arrived.
OSI_SHUTDOWN	The system is being stopped.
OSI_TIMEOUT	A specified time interval expired before a post or signal.
OSI_UNMOUNTED	The file system was unmounted while LFS serialization was dropped.
OSI_POSTERTRM	The address space that is responsible for doing the osi_post has terminated.
OSI_BADPARM	Incorrect OSI_structure.
OSI_ESTAEF	Unable to establish a recovery environment.
OSI_ABEND	Abnormal end in osi_wait.
OSI_SYSTEMERR	Unable to release latches before a signal wait.

Wait_Flags

Supplied parameter (only when Entry_code is OSI_WAITX)

Type:: Integer
Length:: Fullword

Wait_flags contains flags that specify options on the wait request.

Flag	Explanation
osi_wtdroplocks	Drop LFS serialization during the wait, and reestablish it after the wait.

Refer to Interface structures for C language servers and clients for a full description of this structure.

Time_interval

Supplied parameter (only when Entry_code is OSI_WAITX)

Type:: Integer
Length:: Doubleword

The Time_interval is the time for which osi_wait will wait. The value is specified in timer units. If the high-order word is non-zero, the 8-byte value is rounded to approximate seconds. See z/Architecture® Principles of Operation for more detail on timer units. The value is added to the current time; therefore a very large time interval added to the current time could wrap to a very small number and result in an immediate timeout of osi_wait. A value of 0 indicates there is no time limit.

Usage notes

For additional information, see Waiting and posting.
The PFS must call osi_wait for setup before making the call to do the wait and before OSI_post is called to wake up the task. On the setup call, Entry_code specifies whether the PFS wants the wait to be terminated if the process receives a signal.
The order of the calls to wait and to OSI_post is not important after the setup call has been made.
If Entry_code is OSI_SUSPEND and a signal-enabled wait was set up, all LFS serialization is dropped during the wait and reestablished after the wait.
If Entry_code is OSI_WAITX, the Wait_flags specify whether LFS serialization is dropped during the wait and reestablished after the wait.

For writes on stream sockets, the default socket option of exclusive write will prevent the dropping of LFS serialization during signal-enabled waits.
Between the calls to setup and suspend, the PFS should make sure that the OSI token that is returned by setup is addressable to the program that will eventually call OSI_post. The PFS can copy the OSI token. If only the address is used, be careful using this OSI, because the storage for a task will be freed if the task terminates.
The PFS must never call OSI_post for a waiting task more than once, and should have sufficient logic and recovery to avoid calling OSI_post for a task that is no longer waiting.
The osi_thread service undoes any osi_wait setup that was done before osi_thread was called.
Osi_wait issues an MVS™ WAIT or SUSPEND, respectively, as appropriate for TCB or SRB mode callers. Osi_post invokes the corresponding MVS service to wake up osi_waiters.
When osi_wait is called from an SRB, OSI_SETUPSIG may be requested, but signals are not really enabled. This is because signals are not delivered to SRBs, therefore the wait is not interrupted by a signal.
Using OSI_SETUPSIG allows z/OS UNIX to interrupt an SRB's wait if the associated user process goes into termination. It is awakened as if a signal had been delivered.
The OSI_INIT2 Entry_code is used to initialize an OSI_Structure for use by an independent task (TCB) in an address space that is associated with the PFS. This allows the task to wait with osi_wait and be posted with osi_post. An independent task is one that was attached in that address space; it is not running from within a vnode operation.
Note: Generally an independent task would use MVS WAIT, and be posted by MVS POST. Osi_wait and osi_post take several hundred more instructions to execute than MVS WAIT/POST.
There are several restrictions on this service:
1. Only tasks (TCBs) are supported, not SRBs.
2. The task must already be dubbed a z/OS UNIX thread. If this is not the case, the task can get dubbed by calling a z/OS UNIX service such as getpid() before calling osi_wait for OSI_INIT2.
3. The only osi service that is expected to be used by this task with the OSI_structure returned is osi_wait.
Osi_wait(OSI_INIT2) needs to be called only once for the life of a TCB.

The storage for the OSI_structure is provided by the caller as input, and osi_wait(OSI_INIT2) initializes this area for use on subsequent calls for setup and suspension. This storage belongs to the caller, and is freed by the caller, usually at task termination. Calls for setup and suspension may be made with a copy of the structure that is built from this call.

Only the task that made the OSI_INIT2 call can use this OSI_structure.

The OSI_structure must be initialized with the length of the area that is being passed before osi_wait(OSI_INIT2) is called. For example, osi.osi_hdr.cblen=sizeof(OSI).
The address of the osi_wait routine is passed to the PFS in the OSIT structure when the PFS is initialized. Calls that are made from independent address spaces require their own loaded OSIT structure. Refer to Using OSI services from a non-kernel address space for details.

Related services

osi_post — Post an OSI waiter

Characteristics and restrictions

Calls that are made with the OSI_structure that was passed to the PFS on a vnode or VFS operation must be made only on the task that made the vnode or VFS call.