VSAM on z/OS Setup Guide Private Preview

Follow these instructions to replicate your VSAM files on z/OS to your destination using Fivetran.

To connect your VSAM files to Fivetran, configure the VSAM Bridge with:

a shared authentication token
a TLS server certificate

The Fivetran connection setup form requires the VSAM Bridge connection details, the VSAM Files Directory value, a .zip file containing COBOL copybooks, and character encoding settings. Complete the following configuration before you fill in the setup form:

Ensure the prerequisites are in place
Install and configure the VSAM Bridge
Choose a connection method
Prepare your VSAM files and copybooks

Prerequisites

To connect your VSAM files on z/OS to Fivetran, you need:

A z/OS system with VSAM (Virtual Storage Access Method) data sets
The VSAM Bridge installed and running on your z/OS system
The VSAM Files Directory value, such as a data set prefix or pattern, for the VSAM data sets you want to replicate
A .zip file containing the COBOL copybook files that define the structure of your VSAM files
Network connectivity between Fivetran and your VSAM Bridge
The VSAM Bridge IP address or hostname
The VSAM Bridge TCP port, which is 4343 by default
A shared authentication token for the VSAM Bridge
A TLS server certificate configured for the VSAM Bridge
The exported public certificate that Fivetran uses to verify the VSAM Bridge

VSAM files require COBOL copybook definitions to interpret the record structure. Ensure you have a matching copybook available for each VSAM file you want to replicate.

Setup instructions

Install VSAM Bridge

The Fivetran VSAM Bridge is a compiled z/OS load module that runs as a batch job and provides secure access to your VSAM files.

Download VSAM Bridge sequential data set

Download the Fivetran VSAM Bridge binary from the Downloads page of your Fivetran dashboard. You'll find the download link in the Fivetran VSAM on z/OS section. Then, extract the VSAM Bridge from the fivetran_vsam_bridge.tar.gz file.

Allocate VSAM Bridge sequential data set

Allocate the VSAM Bridge sequential data set by submitting the following JCL script.

Replace each angle-bracketed placeholder with the corresponding value for your environment. The job name can contain up to eight characters and should begin with your TSO user ID.

The JOB statement in each script in this guide uses example values for the accounting information, job class, and message class. If your z/OS installation requires different values, change them to match your organization's standard job requirements.

//<job-name> JOB (ACCT),'FTBRIDGE ALLOC',
//             CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID,
//             MSGLEVEL=(1,1)
//ALLOC    EXEC PGM=IEFBR14
//SEQ      DD DSN=<high-level-qualifier>.FIVETRAN.FTBRIDGE.SEQ,
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200,DSORG=PS),
//            SPACE=(CYL,(5,2)),DISP=(,CATLG)
/*

The script allocates the <high-level-qualifier>.FIVETRAN.FTBRIDGE.SEQ data set.

Transfer VSAM Bridge sequential data set to z/OS

Transfer the VSAM Bridge sequential data set to your z/OS system in binary mode.

Replace <zos-host> with the hostname or IP address of your z/OS system and <high-level-qualifier> with your high-level qualifier.

You must transfer the file in binary mode.

ftp <zos-host>
ftp> binary
ftp> put FTBRIDGE.SEQ '<high-level-qualifier>.FIVETRAN.FTBRIDGE.SEQ'

The commands upload the VSAM Bridge binary to the <high-level-qualifier>.FIVETRAN.FTBRIDGE.SEQ data set.

Receive VSAM Bridge sequential data set

Restore the VSAM Bridge binary from NETDATA format into a load library by submitting the following JCL script.

Replace each angle-bracketed placeholder with the corresponding value for your environment. The job name can contain up to eight characters and should begin with your TSO user ID.

//<job-name> JOB (ACCT),'FTBRIDGE INSTALL',
//             CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID,
//             MSGLEVEL=(1,1)
//RECV     EXEC PGM=IKJEFT01,REGION=512M
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 RECEIVE INDSNAME('<high-level-qualifier>.FIVETRAN.FTBRIDGE.SEQ')
 DSNAME('<high-level-qualifier>.FIVETRAN.FTBRIDGE.LOADLIB')
/*

The script creates the <high-level-qualifier>.FIVETRAN.FTBRIDGE.LOADLIB load library containing the FTBRIDGE member.

Configure RACF security

The VSAM Bridge uses TLS to encrypt communication with Fivetran. Create a RACF key ring and TLS server certificate for the VSAM Bridge.

You need sufficient RACF authority to create and manage digital certificates and key rings and configure access to them. If you don't have the required permissions, contact your RACF administrator.

In the following commands, replace these placeholders with values from your environment:

<racf-user-id>: The RACF user ID that owns the key ring and runs the VSAM Bridge
<organization-name>: Your organization name
<country-code>: Your organization's two-letter country code, for example, US
<certificate-expiration-date>: Your chosen certificate expiration date in YYYY-MM-DD format
<bridge-ip-address>: The IP address of the z/OS system where the VSAM Bridge runs, if Fivetran will connect by IP address
<bridge-hostname>: The hostname of the z/OS system where the VSAM Bridge runs, if Fivetran will connect by hostname
<high-level-qualifier>: The high-level qualifier (HLQ) for the certificate data set. This is often the same value as <racf-user-id>, but it can be different if your site uses a different data set naming standard
<zos-host>: The hostname or IP address of the z/OS system where the VSAM Bridge runs. Use the same value as <bridge-ip-address> or <bridge-hostname>

Set the certificate's common name (CN) and subject alternative name (ALTNAME) to the hostname or IP address for the z/OS system where the VSAM Bridge runs. Later, enter the same value in the Bridge Host field of the Fivetran setup form. This ensures that TLS verification succeeds.

Create the RACF key ring:

RACDCERT ADDRING(FTRING) ID(<racf-user-id>)

Generate the TLS server certificate:

If you connect to the VSAM Bridge using an IP address, run the following command:

RACDCERT ID(<racf-user-id>) GENCERT SUBJECTSDN(CN('<bridge-ip-address>') O('<organization-name>') C('<country-code>')) SIZE(2048) NOTAFTER(DATE(<certificate-expiration-date>)) WITHLABEL('FTBRIDGE') ALTNAME(IP(<bridge-ip-address>))

If you connect to the VSAM Bridge using a hostname, run the following command:

RACDCERT ID(<racf-user-id>) GENCERT SUBJECTSDN(CN('<bridge-hostname>') O('<organization-name>') C('<country-code>')) SIZE(2048) NOTAFTER(DATE(<certificate-expiration-date>)) WITHLABEL('FTBRIDGE') ALTNAME(DOMAIN('<bridge-hostname>'))

Connect the certificate to the key ring as the DEFAULT personal certificate:

RACDCERT ID(<racf-user-id>) CONNECT(ID(<racf-user-id>) LABEL('FTBRIDGE') RING(FTRING) DEFAULT USAGE(PERSONAL))

Grant the VSAM Bridge user read access to the key ring:
```
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(<racf-user-id>) ACCESS(READ)
```
The required FACILITY profile must be configured in your RACF environment. If the IRR.DIGTCERT.LISTRING profile isn't configured, contact your RACF administrator.

Refresh the RACF classes:

SETROPTS RACLIST(DIGTCERT DIGTRING FACILITY) REFRESH

Export the public certificate to a data set:

RACDCERT EXPORT(LABEL('FTBRIDGE')) ID(<racf-user-id>) DSN('<high-level-qualifier>.FIVETRAN.CERTIF.PEM') FORMAT(CERTB64)

Download the exported certificate to your local machine:
```
ftp <zos-host>
ftp> ascii
ftp> get '<high-level-qualifier>.FIVETRAN.CERTIF.PEM' fivetran_bridge_cert.pem
```
This command downloads the public certificate as fivetran_bridge_cert.pem. You need to upload this certificate in the Fivetran connection setup form.

Create authentication token

Create a shared authentication token that Fivetran uses when connecting to the VSAM Bridge. Store the token in a sequential data set on z/OS.

The token value is case-sensitive and must match exactly in both the data set and your Fivetran dashboard.
Trailing whitespace is automatically removed from the data set. Don't use spaces as part of the token.
Use only alphanumeric characters, hyphens (-), and underscores (_). EBCDIC encoding may alter other special characters during transfer.
We recommend a minimum length of 16 characters.

Allocate the token sequential data set

Allocate the token sequential data set by submitting the following JCL script.

Replace each angle-bracketed placeholder with the corresponding value for your environment. The job name can contain up to eight characters and should begin with your TSO user ID.

//<job-name> JOB (ACCT),'FT TOKEN ALLOC',
//             CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID,
//             MSGLEVEL=(1,1)
//ALLOC    EXEC PGM=IEFBR14
//TOKEN    DD DSN=<high-level-qualifier>.FIVETRAN.TOKEN,
//            DCB=(RECFM=VB,LRECL=255,BLKSIZE=2550,DSORG=PS),
//            SPACE=(TRK,(1,1)),DISP=(,CATLG)
/*

The script allocates the <high-level-qualifier>.FIVETRAN.TOKEN data set.

Transfer the token file to z/OS

Transfer the token file to the token sequential data set.

Replace <zos-host> with the hostname or IP address of your z/OS system and <high-level-qualifier> with your high-level qualifier.

ftp <zos-host>
ftp> ascii
ftp> put token.txt '<high-level-qualifier>.FIVETRAN.TOKEN'

The token.txt file is a local file that contains your token value on a single line.

Make a note of the token value. You need to enter it in the Bridge Auth Token field of the Fivetran setup form.

Start VSAM Bridge

Start the VSAM Bridge as a long-running batch job using the following JCL script.

Replace each angle-bracketed placeholder with the corresponding value for your environment. The job name can contain up to eight characters and should begin with your TSO user ID.

//<job-name> JOB (ACCT),'FTBRIDGE RUN',
//             CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID,
//             MSGLEVEL=(1,1)
//RUN      EXEC PGM=FTBRIDGE,REGION=512M,TIME=1440
//CEEOPTS  DD *
POSIX(ON)
/*
//STEPLIB  DD DSN=<high-level-qualifier>.FIVETRAN.FTBRIDGE.LOADLIB,DISP=SHR
//         DD DSN=CEE.SCEERUN,DISP=SHR
//         DD DSN=CEE.SCEERUN2,DISP=SHR
//         DD DSN=CBC.SCLBDLL,DISP=SHR
//         DD DSN=CBC.SCLBDLL2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//SYSIN    DD *
port            4343
keyring         <racf-user-id>/FTRING
auth-token-file <high-level-qualifier>.FIVETRAN.TOKEN
/*

After the job starts, run the TSO NETSTAT SOCKETS command. Verify that the output contains a LISTEN entry for port 4343.

The VSAM Bridge runs as a long-running batch job. To stop it, cancel the job in ISPF SDSF or run the TSO CANCEL command.

Choose connection method

Choose how Fivetran connects to your VSAM Bridge.

Connect directly

Fivetran connects directly to your VSAM Bridge. To configure a direct connection:

Configure your firewall and network access controls to allow incoming TCP connections on the VSAM Bridge port, which is 4343 by default, from Fivetran's IP addresses.
Ensure that your network supports TLS 1.2 or higher.
Verify that the VSAM Bridge is accessible from outside your network.

Connect using Proxy Agent

Fivetran connects to your database through the Proxy Agent, providing secure communication between Fivetran processes and your database host. The Proxy Agent is installed in your network and creates an outbound network connection to the Fivetran-managed SaaS.

To learn more about the Proxy Agent, how to install it, and how to configure it, see our Proxy Agent documentation.

Organize VSAM files and copybooks

Make your VSAM files accessible to the VSAM Bridge, and package your COBOL copybooks in a .zip file.

Organize VSAM files: Ensure that all VSAM data sets you want to replicate share the data set prefix or match the pattern that you enter in the VSAM Files Directory field of the setup form.
Prepare copybook files: COBOL copybooks define the record structure of your VSAM files. For each VSAM file you want to replicate:
- Locate or create the corresponding COBOL copybook file.
- The copybook file name must exactly match the full VSAM data set name, without an additional file extension.
- Add the copybook files to a single .zip archive.
- Place the copybook files at the root of the .zip file, not inside nested directories.

Each VSAM file must have a corresponding copybook file that defines its record structure. Without a matching copybook, Fivetran cannot interpret the VSAM record data.

Choose COBOL code page

VSAM files on z/OS typically use EBCDIC encoding. Select a single COBOL Code Page (CCSID) that matches the CODEPAGE compiler option used to compile your COBOL programs. We use this code page for both alphanumeric and double-byte character data. The default is IBM037, the US/Canada EBCDIC code page.

If your copybooks contain DBCS fields, such as PIC G or PIC N USAGE DISPLAY-1, select a mixed SBCS/DBCS code page, for example, IBM930 for Japanese Katakana-Kanji. Selecting a single-byte-only code page for copybooks that contain DBCS fields causes the sync to fail.

Selecting a code page that doesn't match your COBOL compiler configuration may result in garbled or incorrect data.

Finish Fivetran configuration

In your Fivetran dashboard, open the connection setup form, and then follow these steps:

Enter a Destination schema prefix of your choice. This prefix applies to each replicated schema and cannot be changed once your connection is created.
(Optional) In the Destination names field, select Fivetran naming or Source naming to determine how schema, table, and column names appear in your destination. For more information, see the Schema information section.
In the Connection Method section, select the connection method you configured.
In the Bridge Host field, enter the IP address or hostname of the z/OS system that hosts the VSAM Bridge, for example, 1.2.3.4 or mainframe.yourcompany.com.
In the Bridge Port field, enter the port number your VSAM Bridge listens on for incoming connections. The default port number is 4343.
In the Bridge Auth Token field, enter the shared authentication token configured for the VSAM Bridge.
In the Bridge Public Certificate field, upload the .pem file exported from the VSAM Bridge TLS server certificate.
Verify that the configured Bridge Host matches the hostname or IP address covered by the certificate.
In the VSAM Files Directory field, enter the data set prefix or pattern for the VSAM files you want to replicate.
In the Copybooks Zip File field, upload a .zip file containing your COBOL copybook files.
Ensure that each copybook file name exactly matches the corresponding VSAM file name. Place the copybook files at the root of the .zip file. This naming convention lets Fivetran link each VSAM file to its copybook.
In the COBOL Code Page (CCSID) field, select the code page that matches your COBOL CODEPAGE compiler option.
(Hybrid Deployment only) If your destination is configured for Hybrid Deployment, the Hybrid Deployment Agent associated with your destination is pre-selected for the connection. To assign a different agent, click Replace agent, select the agent you want to use, and click Use Agent.
Click Save & Test. Fivetran validates the connection to your VSAM Bridge and verifies access to the VSAM files. After the setup tests succeed, you can sync your data.

Setup tests

Fivetran performs the following tests to ensure that we can connect to your VSAM Bridge and that it is properly configured:

The Bridge Connection Test validates that Fivetran can connect to your VSAM Bridge using the provided host, port, authentication token, and public certificate.
The VSAM Files Directory Access Test verifies that the VSAM Bridge can access the specified data set prefix or pattern and read VSAM data sets.
The Copybooks Validation Test verifies that the uploaded .zip file of COBOL copybooks can be read and contains at least one valid copybook.

If any test fails, review the error message and verify your configuration. Common issues include:

Network connectivity problems between Fivetran and the VSAM Bridge
Incorrect port
Incorrect or expired certificate
Host and certificate mismatch
Incorrect authentication token
Invalid VSAM data set prefix or pattern
Copybooks .zip file missing or incorrectly structured

The tests may take a few minutes to finish running.

Connector Overview

Schema Information

API Connector Configuration

Documentation Home

VSAM on z/OS Setup Guide Private Preview

Prerequisites

Setup instructions

Install VSAM Bridge

Download VSAM Bridge sequential data set

Allocate VSAM Bridge sequential data set

Transfer VSAM Bridge sequential data set to z/OS

Receive VSAM Bridge sequential data set

Configure RACF security

Create authentication token

Allocate the token sequential data set

Transfer the token file to z/OS

Start VSAM Bridge

Choose connection method

Organize VSAM files and copybooks

Choose COBOL code page

Finish Fivetran configuration

Setup tests

Related articles