Using OSI services from a non-kernel address space

The osi_post, osi_selpost, and osi_wakeup services can be called from a non-kernel address space to wake up a thread that is waiting for some event to occur. Osi_ctl can be used from a non-kernel address space to communicate with a file exporter exit program. The osi_sched service can be called to initiate Part 2 of an asynchronous I/O.

For example, if a PFS establishes its own communication mechanism to another separate address space, there may be times when it needs to wait for a reply from that address space. In these cases the PFS can call osi_wait, while running on the user's thread in either the kernel or the other address space, and a program in that other address space can call osi_post to wake it up. A recovery option is available through the v_reg() function that will ensure that these waiting processes are posted if the separate address space should terminate abnormally.

Similarly, if the PFS participates in select() processing and the selected event occurs in another address space, osi_selpost can be called from that other address space.

This section does not apply to calls that are made by the PFS while in the kernel or in a colony address space. For these calls, the OSIT table address that is passed during initialization should be used.

To use the OSI services from an independent (non-cross-memory) thread in another address space, or from an end user thread that has PCed from the PFS to another address space, you must perform the following steps from an authorized program that is running in non-cross-memory mode in that other address space:

Issue an MVS™ LOAD for the module BPXVOSIT.
Branch to the address that is returned by LOAD, passing the standard return_value, return_code, and reason_code parameters with OS linkage.
The program must be authorized at the time of this branch, so that a PC (Program Call instruction) can be set up between this address space and the kernel.

If return_value is not -1, it will be the address of an OSIT in this address space.
Save the OSIT address returned from a successful LOAD and branch.
Do not DELETE the BPXVOSIT load module. All the addresses of the OSI services are within this load module.

The constants and prototype related to doing this are included in Interface structures for C language servers and clients.

From this point on, you can call the OSI services from this address space (via the saved OSIT address) from C or assembler programs the same way a PFS does. The calling program does not have to be authorized at the time of an OSI service call, unless the service specifically requires it.

The following restrictions on using the OSI services from an independent task apply:

A task in the server process can use the standard IPC message interface to communicate with a PFS that is using the osi_kmsg interface, so osi_getipc and the osi_kmsg services are not intended to be used from an independent task.
A task in the server process can use the standard kill() function to send a signal; osi_signal should not be used.
Osi_copyin, osi_copyout, and osi_uiomove should not be used to copy from or to the user address space buffers that were passed on a PFS operation.
Osi_getvnode, osi_sleep, and osi_thread may not be used. Osi_wait may be used after some special setup. Refer to the usage notes for osi_wait for details.

The effect of loading and calling BPXVOSIT is tied to the address space. BPXVOSIT cannot be called twice unless z/OS UNIX has terminated and restarted.

If z/OS UNIX terminates, new OSI service requests fail with an EMVSNOTUP return code. Calls that are in progress when z/OS UNIX terminates may receive a cross memory abend. After z/OS UNIX is restarted, BPXVOSIT must be recalled to reestablish the PC to the new kernel.

If the separate address space is started before the kernel address space, a call to BPXVOSIT that is issued during initialization fails. Generally, a PFS contacts its partner address space during z/OS UNIX initialization, and the load and call can be performed at this time. As an alternative, you can listen for the Event Notification Facility (ENF) Signal, which is issued whenever z/OS UNIX is started. During initialization, an address space can set up an ENF Listen for this event and call BPXVOSIT. If BPXVOSIT fails with EMVSNOTUP, the ENF Signal is eventually issued and BPXVOSIT can be called again after the server's ENF Listen exit is invoked. The ENF Qualifier Constant is defined in macro BPXYENFO.