Function

The v_reg service registers a process as a server. A process must be registered by means of this service before it can call any other VFS callable services API.

Requirements

Parameters

Nreg_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the Nreg parameter list area.

Nreg

Supplied and returned parameter

Type:

Structure

Length:

Specified by the Nreg_length parameter

The name of an area that contains the registration parameters. The entries in this area are mapped by BPXYNREG (see BPXYNREG — Map interface block to vnode registration). The following registration parameters must be supplied:

Parameter

Description

ID

Set to Nreg#ID.

Len

Set to Nreg#Len.

Ver

Set to Nreg#Version.

Type

Set to server type:

• NRegSType#FILE — for a file server
• NRegSType#LOCK — for a lock server
• NRegSType#FEXP — for a file exporter

NameLen

Set to the length of the supplied server name.

Name

Up to 32 bytes of character string that is used as the name of this server. This name appears in DISPLAY OMVS output.

If the process is to be registered as a server-type file exporter, the following parameters must also be supplied:

ExitName

The name of the program that is to control local access to exported file systems.

InitParm

A parameter that is to be passed to the ExitName program when it is initialized.

Hotc Flag

An indication that the ExitName program should be invoked with a preinitialized C environment (HOTC).

The following registration parameters can be supplied:

No Wait Flag

An indication that server threads should not be suspended during a request that is made to a file system that is quiesced, such as for an HSM backup. The request will fail instead of waiting.

MaxVnTok

An upper bound on the number of vnode tokens and, separately, the number of open tokens that the server is to be allowed to have active at one time.

AllocDevno Flag

Requests that a file system device number, as in AttrDev, be allocated for exclusive use by the server. This number will not be used by the LFS for any mounted file system so the server can use this number as the device number for a non-UNIX file system that it is exporting. On a successful v_reg call, the device number is returned in the Devno field of the Nreg structure.

If the process is responsible for posting threads that are waiting within a specific PFS, the process can establish special recovery by specifying the PFS with:

PfsType

The name of the Physical File System that is dependent on this process for osi_post. This is the name that was specified when the PFS was defined in the BPXPRMxx parmlib member with either FILESYSTYPE TYPE() or SUBFILESYSTYPE NAME().

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

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

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the v_reg service stores the return code. The v_reg service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The v_reg service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	Parameter error; for example, the server name length that was supplied in the registration parameter list was too long; or the server type that was supplied is not a recognized value. The following reason codes can accompany this return code: JRNameTooLong, JRInvalidNReg, and JRInvalidRegType.
EPERM	The operation is not permitted. The caller of the service is not privileged; or the caller is already registered.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Usage notes

1. Registration as a server is not inherited across a fork.
2. The MaxVNTokens field in the registration parameter list is an input and output parameter. If supplied by the caller, it indicates the value that should be used for this server. If a value of 0 is supplied, or if the value that is supplied exceeds the maximum allowed value, the maximum allowed value is used and returned.
3. The main difference between the file server and file exporter types is that file exporters control all access, both local and remote, to the file systems that they export.

   Refer to DFS-style file exporters for more information about file exporters and the exit program.

4. If the exit program cannot be loaded, the Nreg abend code and abend reason code fields are filled in with the corresponding values returned by the system load service.

   If the exit program fails, v_reg also fails, and the exit's return and reason codes are returned as the corresponding values from v_reg.

5. If the server's address space is started before the z/OS UNIX address space, a v_reg that is issued during initialization fails. To account for this, an Event Notification Facility (ENF) signal is issued whenever z/OS UNIX is started. During initialization, a server can set up an ENF Listen for this event and call v_reg. If the v_reg call fails with EMVSNOTUP, the ENF signal is eventually issued, and v_reg can be called again after the server's ENF Listen exit is invoked. The ENF Qualifier Constant is defined in macro BPXYENFO. The MVS™ ENF service is documented in z/OS MVS Programming: Assembler Services Guide.
6. When a PFS is dependent on a separate address space calling osi_post to wake up threads that are in osi_wait within that PFS, recovery can be established to protect these threads from waiting forever if the separate address space terminates abnormally.

   To do this, the separate address space registers and specifies a PfsType name. This creates a process, if one did not already exist. When the registered process terminates, the system scans for and wakes up any users that are in osi_wait from within the specified PFS. The PFS's osi_wait call returns with a return code of OSI_POSTERTRM if it is posted for this reason.

   This recovery support is process-related. A process is usually the same as the address space, but if the registering task is the only task to use z/OS UNIX services, or if set_dub_default (BPX1SDD/BPX4SDD) has been called to make each task a separate process, this recovery is invoked when the registering task terminates.

   If this recovery support is the only reason the server is registering, use the server type for a file server.

7. There is no specific way to unregister. If necessary, the task can call mvsprocclp (BPX1MPC/BPX4MPC) to terminate the process, which also unregisters the server.
8. If z/OS UNIX terminates and restarts while the server address space is active, mvsprocclp (BPX1MPC) must be called on each task that has used z/OS UNIX services to remove its binding to the old instance of z/OS UNIX before V_reg can be recalled to reregister as a server.

Characteristics and restrictions

In order to register, the caller must have appropriate privileges.