pfsctl (BPX1PCT, BPX4PCT) — Physical file system control

Function

The pfsctl callable service sends a command and argument to a physical file system (PFS). The meanings of the command and argument are specific to the PFS and are defined by the PFS.

For detailed information about the use of pfsctl, see z/OS DFSMSdfp Advanced Services.

Requirements

Parameters

File_System_type

Supplied parameter

Type:

Character string

Character set:

Printable characters

Length:

8 bytes

The name of a field that contains the 8-character file system type name. The file system type name matches the TYPE operand that was specified on the FILESYSTYPE statement, or the NAME operand of the SUBFILESYSTYPE statement that defined this physical file system in the BPXPRMxx parmlib member.

Command

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the command that is to be passed to the physical file system.

Argument_length

Supplied parameter.

Type:

Integer

Length:

Fullword

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

Argument

Parameter supplied and returned

Type:

Defined by the physical file system

Character set:

No restriction

Length:

Specified by the Argument_length parameter

Specifies the name of a buffer, of length Argument_Length, that contains the argument that is to be passed to the physical file system.

The buffer may be modified by the physical file system to return information to the caller.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pfsctl service returns -1 if the request is not successful.

Depending on the physical file system and the request involved, the length of any returned information that is placed in the Argument buffer may be returned here.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pfsctl service stores the return code. The pfsctl 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 pfsctl service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EFAULT	The Argument buffer address is not valid; or an address passed in the buffer is not valid.
EINTR	The service was interrupted by a signal.
EINVAL	A supplied parameter is incorrect. One of the following Reason_codes may accompany this Return_code: JRFilesysNotThere - The File_System_type specified does not exist. JrIOBufLengthInvalid - The Argument_length specified an incorrect value. JrInvloctlCmd - The Command value was negative.
EMVSPARM	The command or argument parameters were rejected by the physical file system. In this case the accompanying Reason_code is generated by the physical file system. Refer to its documentation to determine the exact reason the error occurred.
ENOSYS	This function is not supported by the physical file system that was specified. The following reason code can accompany this return code: JRPfsctl.
EPERM	Permission was denied by the physical file system. The calling program does not have sufficient authority for the service that was requested.
EIBMBADTCPNAME	PC#SetIbmOptCmd was used, and the name that was specified did not match any of the transports configured under Common INET. The caller did not succeed in getting affinity to a single transport, and this is probably an error for the application.
ENXIO	PC#SetIbmOptCmd was used. The name that was specified did not match a socket stack, but Common INET is not configured on this system. Because this system does not have multiple socket transports configured, there is already a natural affinity to one single stack, and this failure may not be a problem for the application.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pfsctl service stores the reason code. The pfsctl 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.

Usage notes

1. This service is provided for generic communication between a program that is running in a user process and a physical file system.

   It is similar to w_ioctl, but the command is directed to the physical file system itself, rather than to or for a particular file or device.

2. There is no restriction on the length of the argument buffer. The address and length of the argument buffer are passed to the physical file system in a UIO structure on the vfs_pfsctl operation.
3. See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
4. As an example of how a physical file system writer could make use of this function, consider the requirement to display status and performance statistics about the physical file system. You can collect this information in the physical file system, but you need a way to display it to the user.

   With pfsctl, your status utility program can easily fetch the information it needs from the physical file system. The utility needs to know the File_System_type name that the physical file system was started with, and this can be made known to it by the physical file system with the Name/token callable services. (See z/OS MVS Programming: Assembler Services Guide for information on the Name/token callable services.)

5. Command values less than X'0x40000000' are considered to be authorized commands. A check for appropriate privileges (see Authorization) is made and the results of this check are passed to the physical file system in the osi_privileged bit.
6. Command values less than zero are reserved by the system.
7. PC#SetIbmOptCmd — This pfsctl service chooses a particular sockets transport; this is similar to the setibmopt(IBMTCP_IMAGE) C function.

   The Command value for this function is X'C0000005'. You specify the desired transport with the File_System_type parameter. The Argument parameter is not used, and Argument_length should be 0, unless you are setting persistent address space affinity.

   The PC#SetIbmOptCmd function is used by programs that must connect to a specific socket transport, also known as a specific TCP/IP stack, when z/OS UNIX is configured with multiple transports for the AF_INET or AF_INET6 address families. After a transport is chosen, all subsequent socket requests for address family AF_INET or AF_INET6 create sockets that are exclusively attached to that single transport.

   This is similar to the function provided by ioctl(SIOCSETRTTD), except that ioctl(SIOCSETRTTD) detaches an existing socket from all but the specified transport, while pfsctl(PC#SetIbmOptCmd) causes future sockets to be attached to only the one transport. Using pfsctl for this function is significantly more efficient than using ioctl.

   When there is only one transport configured, all socket requests for that address family go directly to it, regardless of any prior calls to pfsctl(PC#SetIbmOptCmd). A call to pfsctl(PC#SetIbmOptCmd) is therefore not necessary in a single transport configuration, but the call will still fail if the name that is specified does not match that of a socket stack. There could be something wrong in the caller's configuration files that needs to be addressed.

   A pfsctl(PC#SetIbmOptCmd) request may be issued more than once to change the chosen transport and affect future sockets that are created. If File_System_type is all blanks, the caller's process is reset to indicate no transports chosen.

   The chosen transport is inherited over fork and preserved over exec. If this is not desired, the child process should call pfsctl(PC#SetIbmOptCmd) with a blank name to reset itself.

   If Argument_length is four and the Argument value is one, this transport affinity also becomes an address space-level transport affinity. Otherwise, only process-level affinity is established. Address-space affinity persists over job steps within a job and over UNIX process termination and re-dubbing in that address space. It applies to all UNIX processes running within that address space, so long as the MVS™ JOBID of the address space does not change. Clearing a process's affinity also clears the address space affinity if an argument value of one is passed on that call.

   Address-space-level affinity is intended for multiple job-step procedures in which one job step makes a call to pfsctl so that a program in a later job step will be restricted to the one specified transport (where that program does not have its own call to pfsctl or cannot be changed to do so). It may also be used to set affinity for a TSO address space, which affects all the programs and commands invoked afterwards.

   To minimize the performance impact of this feature, an address space is checked for address-space level affinity only once in the life of a process, and that check is only made in the socket, gethostid, and gethostname functions. Consequently, the effect of setting address space affinity when other processes are currently running in the address space, or for future programs that have their own calls to pfsctl, is unpredictable. Address-space level affinity is not, strictly speaking, inherited over fork; however, it is applied to a process the first time a call to socket, gethostid, or gethostname is made, so that if the fork occurs after one of those calls, the process's affinity is inherited by its children.

   The BPXTCAFF program supplied by IBM® may also be used to establish an address-space-level transport affinity for started procedures, submitted job streams, and the TSO CALL command. The BPXTCAFF program takes one parameter, the transport name, and makes a call to pfsctl(PC#SetIbmOptCmd), passing that name with an argument value of one, as follows:

   //STEP0 EXEC,PGM=BPXTCAFF,PARM=TPNAME

   See Using specific transports under CINET in z/OS UNIX System Services Planning for more information about transport affinity.
8. PC#SetIbmAsyIO — This pfsctl service chooses a Sockets transport that supports asynchronous I/O.

   The Command value for this function is X'C0000006'. The File_System_type and Argument parameters are not significant, and Argument_length should be 0.

   This is similar to the function provided by PC#SetIbmOptCmd, except that you do not have to know the name of the TCP/IP stack.

   Note: This function is obsolete and should not be used.

   When there is only one transport, all socket requests for that address family go directly to it, regardless of any prior calls to pfsctl(PC#SetIbmAsyIO). It is not an error to call pfsctl(PC#SetIbmAsyIO) when there is only one transport configured, therefore, programs using this function do not have to be sensitive to how an installation is configured. If the single transport does not support asynchronous I/O, attempts to call asyncio later will fail.

   The choice of an asynchronous capable transport can be reset with a call to pfsctl(PC#SetIbmOptCmd) with a File_System_type of all blanks.

   The chosen transport is inherited over fork and preserved over exec. If this is not desired, the child process should call pfsctl(PC#SetIbmOptCmd) with a blank name to reset itself.

9. PC#ErrorText — This pfsctl command retrieves error text for z/OS® UNIX return codes and reason codes and for TCP/IP and zFS reason codes. You can use this service to request the error description for a specified return code or the error description, action text, and issuing module name for a specified reason code.

   The Command value for this function is X'C000000B'.

   On entry, the Argument parameter specifies the buffer in which to pass the request type and the return code or reason code and to receive the requested text. The buffer header contains fields to pass the type of text being requested, the type of error code (return code or reason code), and the return code or reason code and is mapped as follows:

   Offset	Length	Field
   0	2	Text request type
   2	2	Error code type
   4	4	Reason code (for PC#EtReason)
   6	2	Return code (for PC#EtErrno)

   The following request types indicate the type of text to be returned:

   Text request type	Value	Text request description
   PC#EtDesc	X'0000'	Get the error description text for a return code or reason code
   PC#EtAction	X'0001'	Get the action text for a reason code
   PC#EtModname	X'0002'	Get the issuing module name for a reason code

   The following error code types indicate whether the error code you are passing is a return code or a reason code:

   Error code type	Value	Error code description
   PC#EtReason	X'0000'	Request is for a reason code
   PC#EtErrno	X'0001'	Request is for a return code

   The Argument_length includes the length of the buffer header and must be large enough to receive the requested text.

   On return, the requested text starts at the beginning of the buffer, overlaying the header. The Return_value indicates the number of bytes returned in the buffer. If the buffer is not long enough to hold all of the requested text, the service only returns the amount of data that fits in the buffer; there is no explicit indication that data was truncated.

10. PC#TDNames — This pfsctl service returns a list of the names of all the transport stacks that are configured under Common INET. These are the names specified with the NAME() parameter of the SUBFILESYSTYPE statements from the BPXPRMxx parmlib member.

    The Command value for this function is X'C000000F'.

    The output of this function is a simple array of 8-byte names that are left justified and padded with blanks. The Argument parameter, which is used for the output area, must be large enough to hold all the names. If the Argument parameter is not large enough, it is filled with the number of whole names that will fit, and no indication is given that there are more names.

    Tip: The maximum number of stacks configurable under CINET is 32, so an argument that is 256 bytes long will always be large enough.

    The Return_value indicates the number of names that have been returned. If CINET is not configured, the Return_value will be zero

    The File_System_type parameter is not used with this command.

11. PC#DirGetHost — This pfsctl service can be used to direct a BPX1HST gethostid() or gethostname() request to a particular socket transport. The PC#DirGetHost function can be used by programs that need to get the host ID or host name of a specific TCP/IP stack without setting or changing the stack affinity for a process.

    The Command value for this function is 'C0000014'x.

    You use the File_System_type parameter to pass the desired transport and the Argument parameter to pass the BPX1HST request parameters. The Argument is mapped as follows:

    Offset	Length	Field
    0	4	Input: Domain value
    4	4	Input: 0 for gethostid or Length of the Name area
    8	*	Output: Name area for gethostname

    The Argument_length is the total length of the structure that is being passed, including the space reserved for the output Name on a gethostname() request. Refer to BPX1HST for details about the parameters and the difference between the gethostid() and gethostname() requests.

    When Common Inet is not configured, the transport name is ignored and the BPX1HST request is directed to the one and only transport.

    The output from a successful call to pfsctl will be the output that would have been received from BPX1HST, as follows:

    • For gethostid() requests, the Return_value parameter contains the ID.
    • For gethostname() requests, the PC_Name field of the PC_DirGetHostArg structure contains the name.

    Refer to z/OS UNIX System Services Planning for more information about transport affinity.

12. PC#IsSrcAddr — This pfsctl service is used to validate the passed source IP address against a set of input source address selection preference flags.

    The Command value for this function is 'C0000018'x.

    In a Common Inet configuration the File_System_Type parameter can be used to direct the request to a specific TCPIP stack. This will override any process stack affinity that might be established.

    When File_System_Type is all blanks or all zeros the request is routed to the TCPIP stack specified in the scope_id of the sockaddr or to the stack that “owns” the provided source IP address. If the provided IP address is not in the home address list of any active TCPIP stack, then the request will be routed to the default TCPIP stack.

    When Common Inet is not configured the File_System_Type parameter is ignored.

    Argument value is the IsSrcAddr structure which is defined in the BPXYSOCK macro. This function can be invoked using the inet6_is_srcaddr() C function.

    Return Value	Explanation
    0	The input address does not match an address that satisfies the source address selection preference flags indicated.
    1	The IPv6 address corresponds to a valid address in the node and satisfies the given source address selection preference flags.
    -1	The IPv6 address input value does not correspond to any address in the node or the source address selection flags are not one of the valid preference flags or the PFSCTL service failed.

    This PFSCTL service is only routed to a single active IPv6 TCPIP stack and not routed by the CINET on failure.

    This service is only available for IPv6 addresses and IPv4-mapped IPv6 addresses. If an AF_INET6 NETWORK statement is not specified in the BPXPRMxx parmlib member or at least one AF_INET6 supported TCPIP stacks is not active, then the service is rejected with return code and reason codes.

Characteristics and restrictions

None.