Function

The osi_ctl service passes control information to the kernel or to a file exporter exit in the kernel.

Requirements

Parameters

Command

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the command code for this operation. The allowed command codes and their associated commands are as follows:

1

OSI_GLUECALL – provides general communication between a file exporter and the exporter exit that was established during v_reg().

5

OSI_REMOUNTSAMEMODE – Enables a PFS to remount a file system without changing the mount mode.

6

OSI_QSE – Allows the PFS to issue notifications that a file system is being quieced in the PFS so that the LFS can also quiesce it in the LFS layer.

7

OSI_UQS – Allows the PFS to issue notifications that a file system is being unquiesced in the PFS so that the LFS can also unquiesce it in the LFS layer.

8

OSI_GETMNTSTATUS – Enables a PFS to obtain the LFS status of a file system.

9

OSI_DUB – Enables the PFS to dub and undub a worker task.

10

OSI_PFSSTATUS – Enables a PFS to provide PFS-specific status information to the Logical File System.

These commands are defined in BPXYPFSI. See BPXYPFSI.

Argument_length

Supplied parameter.

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the Argument.

Argument

Parameter supplied and returned

Type:

Defined by the receiver.

Length:

Specified by the Argument_length parameter

Specifies the address of a buffer, of length Argument_Length, that contains the argument of the operation. The Argument depends on the command, as follows:

• For OSI_GLUECALL, Argument is a buffer of variable length up to 256 bytes.
• For OSI_REMOUNTSAMEMODE, Argument is the osi_remnt structure in BPXYPFSI).
• For OSI_GETMNTSTATUS, Argument is the osi_getmntstat structure in BPXYPFSI.
• For OSI_DUB, Argument is a four-byte integer whose value is either osi_dubtask or osi_undubtask. These fields are defined in BPXYPFSI.
• For OSI_PFSSTATUS, Argument is the osipfsstatus structure in the BPXYPFSI, PFS interface definitions. See BPXYPFSI.
• For OSI_QSE, Argument is the Osi_Quiesce_Struct structure in BPXYPFSI, PFS interface definitions. SeeBPXYPFSI.
• For OSI_UQS, Argument is the Osi_Quiesce_Struct structure in BPXYPFSI, PFS interface definitions. See BPXYPFSI.

Specifies the name of a buffer, of length Argument_Length, that contains the argument of the operation.

The buffer can be modified to return information to the caller.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the osi_ctl service returns 0 if the request is successful, and -1 if the request is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the osi_ctl service stores the return code. The osi_ctl service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The return code may come from the exporter exit.

The osi_ctl service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	A supplied parameter is incorrect. One of the following Reason_codes can accompany this Return_code: JRNotRegisteredServer - The caller is not registered or is not a file exporter type. JRInvIoctlCmd - The command was not a supported value.
ENOENT	A matching file system was not found.
ENOMEM	A C environment cannot be obtained to invoke the exit.
EPERM	A task is already dubbed or undubbed. For OSI_DUB, if Argument is osi_dubtask and the task is already dubbed, the Return_Value is returned as -1 and the Reason_Code is JrAlreadyDubbed. If Argument is osi_undubtask and the task is already undubbed, the Return_Value is -1 and the Reason_Code is JrAlreadyUnDubbed.
ESRCH with JrPfsNotDubbed	The caller is not on a POSIX thread.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the osi_ctl service stores the reason code. The osi_ctl service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

The reason code may come from the exporter exit, in which case it would be documented with that product.

Usage notes

1. The OSI_GLUECALL command is provided for general communication between a file exporter and the exporter exit that was established during v_reg().

   The argument buffer can be modified to convey information from the exit to the caller. The exit must not write in the argument buffer beyond the amount that was passed in by the caller. The caller and the exit should agree on the size of the argument, or should use an embedded length field to limit the amount of data that is moved to the argument buffer for output.

   If the amount of data to be transferred is more than the amount that is allowed by this service, the caller should use the argument to pass the address of a buffer that contains the data. The exit can use osi_copyin and osi_copyout to move data between the caller's address space and the kernel.

   Refer to DFS-style file exporters for more information about file exporters.

2. For OSI_GETMNTSTATUS, the PFS must fill in the mt_devno in osi_getmntstat_devno. The PFS must also fill in the eyecatcher, version, buffer address, and buffer length. The buffer length must be at least as large as the length of an mnteh (header) plus the length of one mnte entry. The buffer pointed to by osi_getmntstat_bufferaddr does not need to be initialized. The length that was copied into the buffer is stored in osi_getmntstat_bufferlen as output.

   OSI_GETMNTSTATUS performs an internal getmntent (BPX1GMN), and the osi_getmntstat_bufferaddr points to a buffer that will hold the output of that getmntent call, which includes an mnteh (header) and mnte, which are described in BPXYMNTE. If a file system was found matching the input osi_getmntstat_devno, the return_value will be zero and the buffer will contain an mnteh and the mnte entry for that file system. The PFS can examine fields in the mnte to determine the status of the file system. For example, mntentfstname will contain the PFS type name and mntentfsclient will indicate if LFS function-shipping or locally-mounted to PFS. The PFS should also check the mntentstatus flags to ensure the file system is valid. If no matching file system is found, the return_value is -1 and the return_code is ENOENT.

3. For OSI_REMOUNTSAMEMODE, osi_remnt is the osi_remnt structure in BPXYPFSI. The PFS calls osi_ctl with osi_remountsamemode, passing the osi_remnt as the Argument. osi_remnt_name, osi_remnt_version, osi_remnt_devno and osi_remnt_pfsid must be filled in. The osi_remnt_devno identifies the file system. osi_remnt_pfsid is the pfsi_pfsid passed on initialization.
4. For OSI_DUB, if Argument is OSI_DUBTASK and the task is already dubbed, the return_value is returned as -1, and the return_code is EPERM with JrAlreadyDubbed. If Argument is OSI_UNDUBTASK and the task is already undubbed, the return_value is returned as -1, and the return_code is EPERM with JrAlreadyUnDubbed.
5. For OSI_PFSSTATUS, the parameter argument is specified as structure osi_pfsstatusinfo, which is documented in BPXYPFSI. osi_pfsstatus_linex contains the formatted text of 60 characters. (See BPXYPFSI.) In any part of the osi_pfsstatus_linex, if the first character is a null character, or if the entire line contains blanks, this indicates that there is no status on that line. The command D OMVS,PFS skips null or blank lines and displays only osi_pfsstatus_linex with status information.
6. For OSI_QSE, the argument is specified as structure Osi_Quiesce_Struct, which is documented in BPXYPFSI. In the structure, the PFS sets the Osi_Quiesce_Name to 'OSIQ', and Osi_Quiesce_Version to Osi_QuiesceV1. It sets Osi_Quiesce_Devno to the mt_devno identifying the file system to be quiesced. It passes the process id of the quiescing process in Osi_Quiesce_PID, and a unique quiesce instance ID in Osi_Quiesce Handle. The job name and system name of the quiesce owner is passed in Osi_Quiesce_JobName and Osi_Quiesce_SysName. The PFS passes its pfsi_pfsid in Osi_Quiesce_PfsID. The Osi_Quiesce_Flags must be set to identify the quiesce reason. The PFS must have support for a vfs_pfsctl to allow notification to the PFS to unquiesce, passing the quiesce handle and file system name. Unquiesce might be necessary under certain exceptional conditions, such as PFS termination or the quiesce owner's system leaving the sysplex.
7. For OSI_UQS, the argument is specified as structure Osi_Quiesce_Struct, which is documented in BPXYPFSI. In the structure, the PFS sets the Osi_Quiesce_Name to OSIQ, and Osi_Quiesce Version to Osi_QuiesceV1. It sets Osi_Quiesce_Devno to the mt_devno identifying the file system to be unquiesced.

The Osi_Quiesce_Handle must be passed and must match the Osi_Quiesce_Handle that was passed on the quiesce, unless it is FFFFFFFF hex, which is a force unquiesce. If the PFS wants the LFS to perform quiesce handle validation only and not proceed with the unquiesce, it should set flag Osi_Quiesce_CheckOnly.

Characteristics and restrictions

None.