FSIUCV

This is a character device driver that enables you to perform IUCV functions using open/close/read/write/ioctl as opposed to a network driver (AF_IUCV).

The package also contains sample programs:

1. propjr - Connects to the *MSG service
2. events - Connects to the *VMEVENT service
3. riclient - A simple client/server application

The sample programs, including source, may be found in /usr/share/fsiucv/<kernel_version>/.

Building

Builds are performed within a Docker container using podman. It will build RPMs for both AlmaLinux 8 and 9. The Dockerfile can be adapted to build for other distributions.

To build you specify on the command line which kernel targets you are building for. In this example, I am targeting the 5.14.0-587.31.1.el9_8 and 6.12.0-211.16.1.el10_2 kernels.

make -f Makefile.docker KVERS9=5.14.0 KREL9=687.31.1.el9_8 KVERS10=6.12.0 KREL10=211.16.1.el10_2

The build process results in RPMs being placed in the output/ directory:

fsiucv-5.14.0-687.31.1.el9_8.s390x.rpm
fsiucv-5.14.0-687.31.1.el9_8.src.rpm
fsiucv-debuginfo-5.14.0-687.31.1.el9_8.s390x.rpm
fsiucv-debugsource-5.14.0-687.31.1.el9_8.s390x.rpm

fsiucv-6.12.0-211.16.1.el10_2.s390x.rpm
fsiucv-6.12.0-211.16.1.el10_2.src.rpm
fsiucv-debuginfo-6.12.0-211.16.1.el10_2.s390x.rpm
fsiucv-debugsource-6.12.0-211.16.1.el10_2.s390x.rpm

Important /sys/devices/fsiucv/iucvn Files

File	Read/Write	Description
local	R/W	0=non-local connections supported; 1=only local connections supporte
msglimit	R/W	Writing to this file sets ihe maximum number of outstanding messages
parmdata	R/W	0=parmdata messages are not supported; 1=parmdata messages are supported
path	R/O	The path number in use for an active connection
priority	R/W	0=Priority messages not supported; 1=Priority messages supported
program_name	R/W	Program name associated with this device
status	R/O	Shows the status of the device - 0x80 - in use; 0x40 - Active; 0x20 - Waiting
target_node	R/W	The target node of the connection
target_user	R/W	The target user of the connection

Examples of Using

Specifying the Target User

The vmevents sample program prepares the device before use by specifying *VMEVENTS as the target.

#!/usr/bin/bash
echo "*VMEVENTS" >/sys/devices/fsiucv/iucv0/target_user
./vmevents

Specifying Program Name, Target User, and Target Node

The riclient sample program connects to a VM User on a specified node using a program name that CMSIUCV will process on the target.

#!/usr/bin/bash
echo "RISERVER" >/sys/devices/fsiucv/iucv0/program_name
echo "NEALE" >/sys/devices/fsiucv/iucv0/target_user
echo "IBMISV" >/sys/devices/fsiucv/iucv0/target_node
./riclient

When run riclient will open the iucv deivce and exchange messages with riserver running on a CMS User:

/**
 * @file riclient.c
 * @summary Sample program for use with RISERVER 
 * @description This simple program is the client half of the
 * sample program that comes with REXXIUCV package that lives
 * on the z/VM packages download page (http://www.vm.ibm.com/download).
 * It simply sends the EBCDIC '5' to the server who then returns
 * 5 lines of the RISERVER source file.
 *
 */
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <unistd.h>
#include "example.h"

int
main(int argc, char **argv) 
{
	int fd;
	int i;
    size_t j;
	char res[256];
	char out[256];
    int count = 5;
	char data[4];

	fd = open("/dev/iucv0",O_RDWR);
	if (fd < 0) {
		perror("open");
		exit(fd);
	}
    
    j = snprintf(data, sizeof(data), "%d", count);

    a2e(data,j);

    /*
     * Send the request to the server
     */ 
	if (write(fd, &data, j) <= 0) {
		perror("write");
		exit(2);
	}

    /*
     * We are expecting "data" lines back from the server
     */ 
	for (i = 0; i < count; i++) {
		j = read(fd, res, sizeof(res));
		if (j <= 0) {
			perror("read");
			exit(1);
		}

        e2a(res,j);
		res[j] = 0;
        printf("%s\n",res);
	}
	close(fd);
}

Controlling the IUCV Connection

The device driver uses the ioctl() API to modify the behaviour of the IUCV connection or to extract information about the connection.

These command codes may be found in /usr/include/fsiucv/fsiucv.h.

Command	Description
FSIUCVTCS	Set target class
FSIUCVTCG	Get target class
FSIUCVSCS	Set source class
FSIUCVSCG	Get source class
FSIUCVMTS	Set message tag
FSIUCVMTG	Get message tag
FSIUCVANS	Set answer buffer size for 2way reply
FSIUCVVMG	Get name of partner user
FSIUCVNDG	Get name of partner node