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	Type	Field
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	Type	Field
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	Type	Field
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	Type	Field
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	Type	Field
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	Type	Field
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

[ Back to top | UNIX-Type APIs | APIs by category ]