Perform NFS Options (QZNFNFSO) API
Required Parameter Group:
| 1 | NFS option operation | Input | Binary(4), Unsigned |
| 2 | Input buffer | Input | Char(*) |
| 3 | Length of input buffer | Input | Binary(4), Unsigned |
| 4 | Output buffer | Output | Char(*) |
| 5 | Length of output buffer | Input | Binary(4), Unsigned |
| 6 | Format name | Input | Char(8) |
| 10 | Error code | I/O | Char(*) |
Default Public Authority: *NONE
Threadsafe: No
The Perform NFS Options (QZNFNFSO) API retrieves and configures miscellaneous network file system options.
The API allows the administrator to set or retrieve the following options:
- The default security flavors supported by the NFS client and provide the order of preference.
These defaults will be stored in the /etc/nfs/security_default file. - The default NFS domain of the system.
The local NFS domain will be stored in the /etc/nfs/local_domain file.
Authorities and Locks
Authorities required vary for each operation:
(1) QZNF_ RETRIEVE _SECURITY_FLAVORS
- The user must have execute (*X) data authority to the /etc and /etc/nfs directory (if it exists).
- The user must have read (*R) data authority to the /etc/nfs/security_default file (if it exists).
(2) QZNF_SET_SECURITY_FLAVORS
- User must have *IOSYSCFG special authority.
- The user must have execute (*WX) data authority to the /etc and /etc/nfs directory (if it exists).
- The user must have read (*RW) data authority to the /etc/nfs/security_default file (if it exists).
(3) QZNF_ RETRIEVE _NFS_DOMAIN
- The user must have execute (*X) data authority to the /etc and /etc/nfs directory (if it exists).
- The user must have read (*R) data authority to the /etc/nfs/local_domain file (if it exists).
(4) QZNF_SET_NFS_DOMAIN
- User must have *IOSYSCFG special authority.
- The user must have execute (*WX) data authority to the /etc and /etc/nfs directory (if it exists).
- The user must have read (*RW) data authority to the /etc/nfs/local_domain file (if it exists).
(5) QZNF_ RETRIEVE _NFS_OPTIONS
- The user must have execute (*X) data authority to the /etc and /etc/nfs directory (if it exists).
- The user must have read (*R) data authority to the /etc/nfs/nfso file (if it exists).
(6) QZNF_SET_NFS_OPTIONS
- User must have *IOSYSCFG special authority.
- The user must have execute (*WX) data authority to the /etc and /etc/nfs directory (if it exists).
- The user must have read (*RW) data authority to the /etc/nfs/nfso file (if it exists).
Note: Adopted authority is not used.
Required Parameter Group
The following parameters are required.
- NFS option operation
- INPUT; BINARY(4), UNSIGNED
The required network file system options to perform.
You can specify one of the following operations:
(1) QZNFNFSO_RETRIEVE_SEC_FLAVORS
Returns information about all security flavors defined in the /etc/nfs/security_default file.
- The QZNFNFSO_RETRIEVE_SEC_FLAVORS operation requires an output buffer length of at least 8 bytes.
- If duplicate security flavor values are found in the /etc/nfs/security_default file, only the first occurrence of the flavor will only be returned in the output buffer.
- If the /etc/nfs/security_default file does not exist, the Unix style authentication flavor will be the only flavor returned.
(2) QZNFNFSO_SET_SEC_FLAVORS
Re-create the /etc/nfs/security_default file with only the entries provided. The /etc/nfs directory will be created if it does not exist.
- If 0 security flavors are provided as input to the QZNFNFSO_SET_SEC_FLAVORS operation, the /etc/nfs/security_default file is cleared. Later attempts to retrieve the security flavors with the QZNFNFSO_RETRIEVE_SEC_FLAVORS operation will return 0 security flavors.
(3) QZNFNFSO_RETRIEVE_NFS_DOMAIN
Returns information about the default NFS domain of the system defined in the /etc/nfs/local_domain file.
- The QZNFNFSO_RETRIEVE_NFS_DOMAIN operation requires an output buffer length of at least 8 bytes.
- The QZNFNFSO_RETRIEVE_NFS_DOMAIN operation will use the job CCSID to calculate the number of bytes available if an output buffer size less than 12 bytes is provided.
- The maximum length of the retrieved NFS domain name is 1024 bytes.
- If the /etc/nfs/local_domain file does not exist, the domain name will be obtained from the local TCP attributes of the system.
(4) QZNFNFSO_SET_NFS_DOMAIN
Re-create the /etc/nfs/local_domain file with the default NFS domain provided. The /etc/nfs directory will be created if it does not exist.
- The QZNFNFSO_SET_NFS_DOMAIN operation requires that the NFS domain name length be a minimum of 1 byte. No maximum is enforced, however only 1024 bytes can be retrieved through the QZNFNFSO_RETRIEVE_NFS_DOMAIN operation.
(5) QZNFNFSO_RETRIEVE_NFS_OPTIONS
Returns information about the NFS options values defined in the /etc/nfs/nfso file.
- The QZNFNFSO_RETRIEVE_NFS_OPTIONS operation requires an output buffer length of at least 8 bytes.
- If the /etc/nfs/nfso file does not exist, the default values for the NFS options will be returned.
(6) QZNFNFSO_SET_NFS_OPTIONS
Re-create the /etc/nfs/nfso file with the NFS option values provided. The /etc/nfs directory will be created if it does not exist. - Input buffer
- INPUT; CHAR(*)
Information that is required for a given network file system options operation. The input buffer parameter must be set as follows:
(1) QZNFNFSO_RETRIEVE_SEC_FLAVORS
NULL and 0 Length (no input buffer is required).
(2) QZNFNFSO_SET_SEC_FLAVORS
NFOP0100 Structure containing the list of security flavors to be set. For a detailed description of this structure, see Format of NFOP0100 Structure.
(3) QZNFNFSO_RETRIEVE_NFS_DOMAIN
NULL and 0 Length (no input buffer is required).
(4) QZNFNFSO_SET_NFS_DOMAIN
NFOP0200 Structure containing the default NFS domain to be written. For a detailed description of this structure, see Format of NFOP0200 Structure.
(5) QZNFNFSO_RETRIEVE_NFS_OPTIONS
NULL and 0 Length (no input buffer is required).
(6) QZNFNFSO_SET_NFS_OPTIONS
NFOP0300 Structure containing the NFS options entries to be set. For a detailed description of this structure, see Format of NFOP0300 Structure. - Length of input buffer
- INPUT; BINARY(4), UNSIGNED
The length of the input buffer provided. The length of the input buffer parameter may be specified up to the size of the input buffer area specified by the user program. The length of the input buffer must be 0 when the input buffer is NULL.
- Output buffer
- OUTPUT; CHAR(*)
Information that is provided by a given network file system options operation. The output buffer parameter must be set as follows:
(1) QZNFNFSO_RETRIEVE_SEC_FLAVORS
NFOP0101 structure containing the list of security flavors that are set. For a detailed description of this structure, see Format of NFOP0101 Structure
(2) QZNFNFSO_SET_SEC_FLAVORS
NULL and 0 Length (no output buffer is required).
(3) QZNFNFSO_RETRIEVE_NFS_DOMAIN
NFOP0201 structure containing the default NFS domain that is in use. For a detailed description of this structure, see Format of NFOP0201 Structure
(4) QZNFNFSO_SET_NFS_DOMAIN
NULL and 0 Length (no output buffer is required).
(5) QZNFNFSO_RETRIEVE_NFS_OPTIONS
NFOP0301 structure containing the NFS options entries to be retrieved. For a detailed description of this structure, see Format of NFOP0301 Structure
(6) QZNFNFSO_SET_NFS_OPTIONS
NULL and 0 Length (no output buffer is required). - Length of output buffer
- INPUT; BINARY(4), UNSIGNED
The length of the output buffer provided. The length of the output buffer parameter may be specified up to the size of the output buffer area specified by the user program. The length of the output buffer must be 0 when the output buffer is NULL.
- Format name
- INPUT; CHAR(8)
The content and format of the information provided or returned for the Network File System operation. The possible format names are
NFOP0100 Input Format that provides information about the NFS Security Flavors.
NFOP0101 Output Format that returns information about the NFS Security Flavors.
NFOP0200 Input Format that provides information about the NFS Domain Name.
NFOP0201 Output Format that returns information about the NFS Domain Name.
NFOP0300 Input Format that provides information about the NFS options settings.
NFOP0301 Output Format that returns information about the NFS options settings. - Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of NFOP0100 Structure
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4), UNSIGNED | Number of security flavors |
| These fields repeat for each security flavor. | BINARY(4), UNSIGNED | Security flavor | |
Format of NFOP0200 Structure
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4), UNSIGNED | CCSID of domain name |
| 4 | 4 | BINARY(4), UNSIGNED | Length of domain name |
| 8 | 8 | CHAR(*) | NFS domain name |
Format NFOP0300 Structure
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4), UNSIGNED | Maximum NFS server threads |
| 4 | 4 | BINARY(4), UNSIGNED | Client handle cache |
| 8 | 8 | BINARY(4), UNSIGNED | Utf8 validation |
Format NFOP0101 Structure
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4), UNSIGNED | Bytes returned |
| 4 | 4 | BINARY(4), UNSIGNED | Bytes available |
| 8 | 8 | BINARY(4), UNSIGNED | Number of security flavors |
| These fields repeat for each security flavor. | BINARY(4), UNSIGNED | Security flavor | |
Format NFOP0201 Structure
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4), UNSIGNED | Bytes returned |
| 4 | 4 | BINARY(4), UNSIGNED | Bytes available |
| 8 | 8 | BINARY(4), UNSIGNED | CCSID of NFS domain name |
| 12 | 0C | BINARY(4), UNSIGNED | Length of NFS domain name |
| 16 | 10 | CHAR(*) | NFS domain name |
Format NFOP0301 Structure
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4), UNSIGNED | Bytes returned |
| 4 | 4 | BINARY(4), UNSIGNED | Bytes available |
| 8 | 8 | BINARY(4), UNSIGNED | Maximum NFS server threads |
| 12 | 0C | BINARY(4), UNSIGNED | Client handle cache |
| 16 | 10 | BINARY(4), UNSIGNED | Utf8 validation |
Field Descriptions
Bytes available. The number of bytes of data available to be returned to the user in the output buffer. If all data is returned, bytes available is the same as the number of bytes returned. If the receiver variable was not large enough to contain all of the data, this value is set based on the total number of entries that could be returned.
Bytes returned. The number of bytes of data returned to the user in the output buffer.
CCSID of domain name. The CCSID of the domain name. For NFOP0201 structure a value of 0 indicates that the data is in the CCSID of the job.
Client handle cache. This option allows RPC client handle cache. The cache is enabled by default.
| Client Handle Cache Value (Hex) |
Description |
|---|---|
| 0x00000000 | Disable RPC client handle cache |
| 0x00000001 | Enable RPC client handle cache |
Length of NFS domain name. The length (in bytes) of NFS domain name used by NFSv4.
Maximum NFS server threads. Specifies the maximum number of NFS server
threads that are created to service incoming NFS requests. Default is
50. The range is from 1 to 50.
As the NFS server is multithreaded the NFS server threads are created as
demand increases for the NFS server. When the NFS server threads become
idle, they will exit. This allows the server to adapt to the needs of
the NFS clients. The Maximum NFS server threads parameter is the maximum
number of threads that can be created. In general, it does not detract
from overall system performance to have the maximum set to something
very large because the NFS server creates threads as needed. However,
this assumes that NFS file serving is the primary function of the machine.
If the desire is to share the system with other activities, then the maximum
number of threads may need to be set low.
NFS domain name. NFS domain name used by NFS v4. The NFS domain name is restricted to 255 characters and a minimum of 1.
Number of NFS security flavors. Number of NFS security flavors to be set.
Security flavor. The authentication type (flavor) required by the NFS server. Flavors are returned in the order of preference. When setting the flavors, the order in which the flavors appear in the NFOP0101 format will determine the order of preference for the supplied flavors. If a flavor does not appear in the list, that form of authentication is not allowed by the NFS version 4 client.
| Security Flavor Value (Hex) |
Security flavor | Description |
|---|---|---|
| 0x00000001 | sys | Unix style (uids, gids) |
| 0x00000002 | krb5 | Kerberos 5, with no integrity or privacy |
| 0x00000004 | krb5i | Kerberos 5, with integrity |
| 0x00000008 | krb5p | Kerberos 5, with privacy |
Utf8 validation. Enables checking of file names for the NFS version 4 client and server to ensure they conform to the UTF-8 specification. Default is 1.
| Utf8 Validation Value (Hex) |
Description |
|---|---|
| 0x00000000 | Disable Utf8 validation |
| 0x00000001 | Enable Utf8 validation |
Error Messages
The following messages may be sent from this function:
| Message ID | Error Message Text |
|---|---|
| CPFA0D4 E | File system error occurred. |
| CPE3418 E | Possible APAR condition or hardware failure. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFA0AA E | Error occurred while attempting to obtain space. |
| CPFA0AA E | CCSID conversion error occurred. |
API introduced: V6R1