Function

The osi_thread service is used by a PFS to call a module on an asynchronous colony thread that is in the same colony address space that the PFS is running on. For a synchronous request, the caller's task is put into a wait while the module is running.

Requirements

Parameters

OSI_structure

Supplied parameter

Type:

Structure

Length:

Specified by the Osilen field

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.

OsitThread_Parm_structure

Supplied parameter

Type:

Structure

Length:

Specified by the Othdlen field

An area that contains the OsitThread parameters. The entries in this area are mapped by the OTHDPRM typedef.

Refer to Interface structures for C language servers and clients for a full description of this structure. The following OsitThread parameters must be supplied:

ot_modname

The name of the module that is to be fetched and called on the colony thread. The name must be a null-terminated string that is acceptable to the C fetch function.

ot_parms

The address of the parameters that is to be passed to the module specified by ot_modname. This parameter is also passed to the named exit if it is called. If any parameters are passed, the first parameter is used by the LFS to pass a state token to the named module or exit routine. The area whose address is passed in ot_parms must reserve the first word for this purpose.

The address that is specified in this parameter points to a structure, or control block, in whose first word the LFS inserts the address of the 8-byte state token. A pointer containing ot_parms is the first parameter to the module and to the exit routine.

ot_exitname

The name of the exit routine that may be called after the module completes. This routine is called for a request that specifies NOWAIT, or when the caller's wait is terminated before the module completes. The name must be a null-terminated string that is acceptable to the C fetch function.

ot_option_flags

A field in which the caller can specify:

• OSI_SIGWAIT—the caller's task is put into a signal-enabled wait until the module that is named in ot_modname completes.
• OSI_NOWAIT—the caller's task is not put into a wait; the module is run asynchronously.

  If neither OSI_SIGWAIT nor OSI_NOWAIT is specified, the caller's task is placed in a wait that is not signal-enabled.

• OSI_RELEASEMODS—the fetched module and exit routine, if called, are released when the request is complete.

  When a module is released, any state token that is associated with this module on the current osi worker thread is freed.

  IF OSI_RELEASEMODS is not specified, the named module and the exit routine, if called, remain in storage. The next request that specifies these routines does not fetch them before calling them.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the osi_thread service returns the results of the operation, as one of the following return codes:

Return_value

Meaning

-1

The operation was not successful. The resources that are associated with this request can be safely freed.

0

The operation was successful. The resources that are associated with this request can be safely freed.

+1

The named module was scheduled to be called, but might not have completed. Resources that are associated with this request should not be freed. This value is returned if the request specified OSI_NOWAIT, or if the caller's wait is terminated before the request completes.

Note: The return value indicates the results of the osi_thread service. It does not indicate the results of the named module. Some other mechanism must be used by the caller to determine these results.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the osi_thread service stores the return code. The osi_thread service can return one of the following values in the Return_code parameter only if Return_value is +1 or -1. Reason_code further qualifies the Return_code value.

Return_code	Explanation
EINTR	The service was interrupted by a signal.
EINVAL	Parameter error. Consult Reason_code to determine the exact reason that the error occurred. The following reason codes can accompany the return code: JROWaitSetupErr, JRNoClnyThreadSuppt.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the osi_thread service stores the reason code. The osi_thread service returns Reason_code only if Return_value is +1 or -1. Reason_code further qualifies the Return_code value.

Usage notes

1. The osi_thread service may be invoked only from a PFS that is running in a colony address space.
2. For more information, see Using daemon tasks within a PFS.
3. The osi_thread service is not available for use until kernel initialization is complete. The PFS can determine when kernel initialization is complete by interrogating the ot_available flag whose address is passed in the pfsi_otstatptr field.
4. The caller must not free any resources that can be used by the module that is running on the colony thread unless a return value of 0 or -1 is returned. If a return value of +1 is returned, the resources must be freed by the exit routine.
5. The osi_thread service undoes any Osi_Wait Setup that was done before this service was called.
6. The named module and the named exit routine are fetched on the colony thread using the C/370™ fetch() function. The named module must comply with any requirements of this function. See z/OS XL C/C++ Runtime Library Reference for more information.
7. The named module, and the exit routine, if it is called, remain in storage after the request completes, unless OSI_RELEASEMODS was specified.
8. The named module and the exit routine may use C/RTL or POSIX services. The writer of the PFS should remember that this thread could be used to fetch and call the specified module on another osi_thread call. Therefore, the named module should not request any services that would affect the process that is associated with this thread, such as exit or exec. Pthread services should not be requested either.
9. The named module and the exit routine must be reentrant.
10. The named module and the exit routine are invoked using OS linkage conventions.
11. The named module and the exit routine receive control in the following environment:

    Operation	Environment
    Authorization:	Problem state, PSW key 8
    Dispatchable unit mode:	Task
    Cross memory mode:	PASN=HASN=SASN
    AMODE:	31-bit
    ASC mode:	Primary
    Interrupt status:	Enabled for interrupts
    Locks:	Unlocked
    Signals:	All signals are blocked except SIGALRM

12. If any parameters are passed to the named module or exit routine, the first parameter should be the address of an 8-byte state token. The first time a named module or exit routine is invoked on a particular osi worker thread, this token is zeros. The named module or exit routine can modify this token to preserve some state information from one invocation to the next. For all subsequent invocations of this module on this particular worker thread, the token is provided unmodified by the LFS.
    When the PFS uses a parameter structure, the first word is used by the LFS to point to the state token. The input to the module and exit looks like this:

    Figure 1. Input to module and exit using a parameter structure
    When the PFS does not use a parameter structure, the input to the module and exit looks like this:

    Figure 2. Input to module and exit without using a parameter structure
13. ESTAE-like recovery is available to the module and exit routines. This saves the overhead involved in having these routines set up and take down their own ESTAEs on each entry.
    A pointer to a Recovery Block (RcvyBlk) is passed as the second parameter to these routines. The pointer is used as follows:

    1. On entry, or when recovery protection is needed, the module or exit sets the RcvyData pointer to the address of its own recovery information.

       Pertinent data can also be placed in the work area. This data will be available to the recovery routine.

       The RcvyRtn pointer is set to the address of a recovery routine.

    2. If the module or exit ends abnormally, and RcvyRtn is non-zero, the RcvyRtn routine is called from the LFS's ESTAE and passed all the parameters provided by RTM, including the pointer to RcvyBlk. An exception is that register 15 contains the address of the recovery routine (RcvyRtn), rather than the address of the LFS's permanent ESTAE exit. When the RcvyRtn routine returns, it returns directly to RTM, rather than to the LFS's permanent ESTAE exit.
    3. Under normal circumstances, before returning, or when recovery protection is no longer needed, the module or exit zeros out the RcvyRtn field.
    The recovery routine is invoked in the same way as an MVS™ ESTAE routine, not a C subroutine. The registers on entry are:

    Register

    Contents

    R0

    12, if an SDWA is not provided; otherwise, an SDWA address is provided in R1.

    R1

    SDWA address, if an SDWA is provided; otherwise, completion code.

    R2

    Pointer to RcvyBlk, with or without an SDWA. This value is also contained in SDWAPARM when an SDWA is provided.

    R13

    Address of the save area provided by RTM.

    R14

    Return address, as provided by RTM.

    R15

    Address of the recovery routine that is being called (RcvyRtn).

14. The recovery block (RcvyBlk) is mapped by OTHDCRCV in bpxypfsi.h.
15. The work area in the recovery block can be used to pass information to the recovery routine. It can also be used as a work area for the recovery routine to build dump titles or list forms of assembler macros.
16. The recovery routine is entered in problem program state, key 8.
17. The address of the osi_thread routine is passed to the PFS in the OSIT when the PFS is initialized.

Characteristics and restrictions

This routine must be used only on the task that made the vnode or VFS call.