In addition to the above description, Raincode Crossbow v6.0 (see release notes) is a technical release that includes the following:

Submit.exe is the equivalent of the mainframe’s SUBMIT command, which allows users to submit a JCL for execution. This can be achieved by starting Submit.exe on the command-line, or programmatically by calling the SubmitRunner.Execute() method.

All the coordination with the filesystem, launched processes, the interactions with the catalog, and the entire processing of a JCL is encapsulated in the call to Submit.exe. This design allows horizontal scaling by running jobs from different servers without a central coordinating server. The return code of Submit.exe is the highest return code of all the steps of the job for easy reporting and integration with schedulers. Editing the .NET configuration file for Submit.exe allows for custom configuration of various interfaces that provide extensibility.

For a complete description of the command-line options available for Submit.exe, please refer to Submit. The most straightforward way to execute Raincode JCL is to call Submit.exe by providing the JCL to execute with the -File option:

After execution, the resulting logs are stored in C:\ProgramData\Raincode\Batch\SYSOUT, as shown in the example below:

Raincode JCL’s catalog manager emulates the catalog manager of the mainframe file system. It maintains its configuration information in an XML file, which is found by default in C:\ProgramData\Raincode\Batch\Raincode.Catalog.xml(shown in the figure below).

The default volume location for data sets managed by the catalog manager is C:\ProgramData\Raincode\Batch\DefaultVolume, as illustrated in the figure below.

The catalog manager can be accessed programmatically by developers. Internally, it relies on three subsystems, namely the data file manager, the lock manager and the file system support layer.

For more information on Raincode’s approach to handling datasets, please refer to Representation of the datasets.

The JCL parser is an internal component of Raincode JCL, which is irrelevant to the day-to-day use of the tool, but which can prove very useful for programmatic interaction with the product. This parser takes the JCL and builds an internal representation, that can then be used to process and execute it. The JCL parser includes support for two levels of preprocessing (performed before actually building the internal representation), namely AutoEdit preprocessing and JCL preprocessing.

The AutoEdit preprocessing phase partially mimics a functionality provided by Control-M. It includes date processing, where calendar files can be specified in the Control-M format or programmatically through the IAutoEditCalendar interface. Variables can be set externally using an environment variable CTM_xxxx, where xxxx is the AutoEdit variable name.

In the JCL preprocessing phase, %%SET statements and &VARIABLE references are supported, similar to how they are processed on the mainframe.

The batch runtime is responsible for the different steps in executing a JCL. The basic flow of execution involves scanning, executing and cleanup, as illustrated in the figure below.

The process flows is as follows:

When the runtime looks for a program to execute, it looks successively in the paths defined by:

Programmatically, the batch runtime consists of an in-memory object model representing a JCL job and classes that facilitate the execution of steps. The parser builds up this in-memory job representation, and the Submit runner calls the Scan() and Execute() methods on the job to direct the process.

Programs compiled by Raincode’s COBOL, PL/I, HLASM and zTrieve compilers cannot be executed directly from the command-line. They require a runner, an executable program that sets up the entire environment (memory, I/O, database connection, etc.) before actually executing the program.

The default runner is %RCBIN%\rclrun.exe. In the spirit of flexibility and extensibility, Raincode JCL (and the entire Raincode toolset) allows for the definition and usage of specialized, user-defined runners, to be used instead of the default one. In practice, this means that Submit.exe and the IKJEFT01 utility go through the runner to execute a compiled module, and leverage rclrun.exe to run these DLLs.

By default, the runner will search for the RCDIR environment variable and execute from the given path. If the RCDIR environment variable is not set, it will execute in the current directory.

The default runner can may be overridden in such a way that a user-defined runner is used instead. This is done by successively trying the following steps:

When Submit.exe starts executing a program by means of a runner (the default one or a redefined version of it), the environment variable RC_LegacyRunner is set to the path of the runner that is actually used.

An example shows how the Raincode catalog emulates the mainframe file system. Refer to the following structure of datasets on the mainframe (also shown in Figure Datasets on mainframe):

On Windows, this yields the following structure (also shown in Figure Datasets on windows):

On a mainframe, a JCL can specify a concatenated dataset; multiple datasets that are presented to the program as a single concatenation, for example, as follows:

Raincode JCL has two ways to represent concatenated files: logical concatenation (the default) or concatenating into a temporary file.

There are two ways to control the choice of whether or not to use temporary files for concatenated datasets:

Further, these two approaches are explained in more detail.

This section explains migrating datasets from the mainframe to the Raincode catalog.

On the mainframe, print files are stored in FBA files using the ASA printer control character as the first character in the record. Usually, these files are produced by the report writer of COBOL programs that will use WRITE ADVANCING statements.

On the other side, windows and open system printers do not understand the ASA control char, and therefore, printing the resulting FBA requires a conversion. It is worth considering whether to use line sequential or variable line sequential files.

Below are the various aspects of handling print files.

Each step of a JCL that includes PGM=<name> requires Submit to map the name to an external program to execute. To do so, Submit performs a lookup for a filename in the form <name>.<extension>, in the order of the following table:

Submit looks for the file in the directories in the order listed in the following table.

To allow integration with an external scheduler, Submit.exe returns the return code of the job that it executes. Therefore, to integrate with a job scheduler application, follow the instructions for executing a console application and use Submit.exe as the executable.

By default, the job outputs, i.e. the contents of SYSOUT for a job, are located in the C:\ProgramData\Raincode\Batch\Sysout directory. Each job that has been executed will have a specific folder containing the SYSOUT info.

Each folder in SYSOUT will contain the following:

Submit includes the ability to build a database repository that archives several tables of the submitted JCL job, like job steps, conditions, procedures, etc. This repository can be used to analyze the portfolio and estimate the required workload for a migration effort.

Repository generation is only available when the -ScanOnly option is used along with the -DBDriver and -DBConnectionString command-line options. The DBDriver options specifies the desired type of database driver, and DBConnectionString specifies the desired connection string for the database.

The first database driver that can be used is SQLite, e.g., as follows:

When using SQLite as the database driver, the repository will be created in the same directory where Submit.exe is executed under the default repository name: RC_JCL_INVENTORY.db. However, one can specify the name of the database file through the DBConnectionString option.

Alternatively, an ODBC driver can be used, e.g., as follows:

When using the ODBC driver, the target database is an SQL Server. On the server side, one needs to create a database named: RC_JCL_INVENTORY and define the ODBC data source for the connection before executing Submit.exe. This data source needs to be passed as part of the DBConnectionString option.

The created repository includes several SQL tables giving viable information about the submitted jobs. For more details, refer to the appendix JCL JOB repository.

Raincode JCL emulates the locking mechanism of mainframe JCL on datasets using two-step lock file acquisition. Therefore, no changes must be made to the JCL batches to work with Raincode JCL. In order to prevent deadlocks, locks are obtained upfront at the beginning of the job, and taken in alphabetical order based on DSNAME.

Below are the details of the command line options of Submit.exe. These tables are automatically generated and contain the same information produced by running Submit.exe without arguments.

Below is the default configuration file (for Windows at the time of writing this document) created if the lookup fails. It consists of a top-level CatalogConfiguration element with several relevant attributes and various nested entities, all of which are described in the remainder of this chapter.

The top-level CatalogConfiguration element can have several attributes, the meaning of which is described in the table below.

The CatalogConfiguration element can have various nested entities, as described in the following table.

Raincode JCL includes support for the expansions of Autoedit variables in JCLs. In addition to the use of autoedit datasets, as on the mainframe, it looks up environment variables to find values when needed. For example, if a variable such as %%FOO could not be found in an autoedit dataset, the value of the CTM_FOO environment variable (if present) will be used instead. Additionally, the values for some variables set by Control-M , listed below, need to be specified through environment variables before they can be used in the JCLs.

Autoedit calendars are also supported. By default, they are read from the C:\ProgramData\Raincode\Batch\AutoEditCalendars path, but this behavior can be overridden by using the the autoEditCalendarFolderPath attribute in the catalog configuration.

The example configuration file below shows the expected structure of such a calendar file. The important part is the NAME= property since it maps to the calendar name that AutoEdit uses.

Alternatively, the IAutoEditCalendar interface can be implemented and registered in the submit.exe.config file to perform the supported calendar operations. The default implementation uses the XML file format from Ctrl-M. It only supports the relative type format shown above.

Bootstrapping your environment typically consists of creating one or multiple PDS libraries and importing existing JCL files into the PDS libraries created. Below is an example of such a JCL bootstrap job.

When a JOBLIB or STEPLIB is specified in the JCL, Submit first searchesthe specified libraries for executables (for more details, refer to the Resolution of PGM=xxx) . For this feature to function properly, it is necessary to define the corresponding libraries in the catalog, and load them with the program binaries (DLLs). You can create a PDS library (in this case named ENV.DEV) as shown below:

Assuming that you have a COBOL source file named HELLO.cob, which has been compiled into HELLO.dll, the compiled file must be copied to the PDS library ENV.DEV, located at <default volume>\ENV\DEV._dir\.

At this point, the library is ready to be used. You can then create a JCL to execute a program from this library. For example:

The resulting PDS library can, of course, be also used for JOBLIB.

When using the VSAMSql, VSAMLite, and VSAMOracle drivers (see chapter VSAMSql), the dataset must be defined to use the VSAMSql driver to store data in a database instead of on the file system. This mapping information is stored in the <datasetTemplate> element under <datasetSqlMapping>.

The <datasetTemplate> element contains several attributes:

<datasetTemplate> contains one or more <pattern> elements, one <parameters> element, zero or one <partitions> elements and zero or more <driverParameter> elements.

An example is below:

The different entities in the datasetTemplate entity are as follows:

Considering the contents of driverParameter: it should be a valid XML and is passed to the file driver as it is. The VSAMSql allowed elements are:

In addition to the above mentioned parameters, cache configuration parameters can also be specified, as detailed in the VSAMSql Cache configuration section.

Tables creation

Before using the VSAMSql/VSAMOracle files, tables need to be created. VSAMLite creates the tables on the fly. The driver does not do the table creation because the people executing a program usually don’t have the right to create tables; that’s why there is a program, VsamSql.DbGenerator reads the catalog configuration and generates the table creation script (see Database creation). This script needs to be executed by somebody (DBA, for example) that has the right to create tables.

If the volume (VOL-SER) is not defined in the DD statement, the dynamic distribution for files occurs as mentioned below.

The <defaultVolumeMapping> element contains the following attributes:

An example is illustrated below:

The example above explains the following:

The DSN will be stored in the defaultVolume if none of the above DSN is specified.

<DSN> refers to the dataset name that must be stored on the specified volume. It contains a <DSN> element, a regular expression (regex) representing the DSN stored in this volume.

The catalog configuration defines environment variable values that Submit will set at the beginning of each step such that the executing program can retrieve this information if needed. Below is an example.

<environmentVariables> is a list of <envvar> elements. These have one mandatory attribute: Name, which is the name of the variable, and a set of optional attributes, as defined in the table below.

The value of the environment variable is the character data inside the <envvar> element.

The definition of environment variables and their values is conditional, based on regular expressions on Program Name, StepID, and JobID. If several regular expressions are defined for one <envvar> (e.g., stepId= "0001.*" and PGM="PRG01"), all of them must match to define the environment variable.

If no regular expression is given, the environment variable is always defined.

The mainframe can define a DD card for a step not explicitly declared in the JCL. The catalog supports this through the <autoDDCardDefinitions> section containing <ddCard> elements. An example is illustrated below.

The ddCard element defines a dataset in the SYSOUT directory. It has one mandatory attribute: Name, which is the DD card name, and a set of optional attributes, as defined in the table below.

If several regular expressions are defined for one <ddCard> (e.g., stepId= "0001.*",PGM="PRG01"), all of them must match to define the DD card.

If no regular expression is defined, the DD Card is always defined.

When a program using a DB is used, it requires a connection string and a DB Type to pass to rclrun. On the mainframe, this is typically defined by a configuration that associates a Job or Program Name to a Plan Name, while in IKJEFT01, PLAN (xxx) lets a user define the Plan name that will determine the connection to the DB. This section provides insights into how this is done in Raincode JCL.

The unique job folder under the sysoutFolderPath can be configured by editing the sysoutFolderNamingPattern option in the catalog configuration. Two components have a specific meaning: ID and NAME. The ID string is replaced with the unique job ID, while the NAME string is replaced with the job name. The ID string is mandatory, whereas the NAME string is optional.

For Example:

When the job name is not yet known, such as when a job is submitted, but there are errors in parsing, the job name is set to UNKNOWN. Once the job name is known, the sysout folder will be renamed accordingly.

This directory contains different files and directories:

For each PROC/STEP, there is a directory containing the files generated by the job, e.g. SYSOUT, SYSPRINT. These files are only present if they are not empty.

Specifies the installation policy for batch jobs that must wait to enqueue the dataset (Locking). Possible values are NO, YES, 1-999999 with a default of 3600 seconds (one hour)

Specifies whether to cancel jobs that must wait to enqueue the dataset:

The Storage Management Subsystem (SMS) allows for the creation of templates with predefined data configurations by system programmers. Datasets can then be attached to such templates rather than repeating all the parameters file after file. SMS saves time and effort and, even more importantly, allows for a centralized and more abstract management of file properties.

Raincode’s JCL Emulator supports for SMS through two DD parameters, namely DATACLAS (Data Class) and STORCLAS (Storage Class). These parameters are specified in a configuration file. The default path of the configuration file is C:\ProgramData\Raincode\Batch\SMSConfig.txt.

A typical example of the contents of the configuration file:

The configuration file’s default location can be overidden using a smsConfigFilePath attribute in the Raincode.Catalog.xml.

For more details, please refer to the section Default catalog configuration. When Submit executes, it first checks for SMSConfig.txt at the location specified in the catalog. If it is not found, it checks at the default location to fetch the values for both classes.

The JCL parser supports substituting variables that start with the # @ characters (e.g., # @VAR1). The values for these variables are stored in an XML file specified in the catalog configuration attribute substitutionVariableFilePath. The format of the file is given in the example below:

Variables can also be passed through the IJCLPreprocessor interface when the UpdateSubstvarVariables method is called. It is simply a dictionary of key/value pairs.

Setting up a file share and accessing it with its UNC path means having a centralized file share location, allowing a multi-batch server environment. Each batch server will access volumes and their datasets via the respective UNC path.

To enable this, first, share the folder on the server and note the remote path to the share. Then, modify the catalog configuration file to use the new share (for sysout, volumes, etc.) using the remote path.

Units are simply a named collection of volumes. The default unit is SYSDA.

Volumes map to drives or folders on disk. They can be UNC shares or local folders.

To add new volumes to the catalog configuration, manually create a new folder on disk and add a new <Volume> element (under the <Volumes> element) with the path to the newly created folder.

The Raincode catalog (Catalog.Configuration.xml) stored on a linux machine can be accessed remotely through two common file-sharing protocols:

This section focuses on guiding you through the process of accessing the Raincode catalog on a Linux machine using the SMB protocol.

By setting up an SMB file share, the Catalog.Configuration.xml file can be accessed and managed from a Windows environment, leveraging tools like Catalog Explorer and Record Editor without direct Linux support.

Using <environmentVariables> or <programDBConnectionDefinitions> entities in the catalog configuration file may make this file large and unwieldy. So, store that information in separate files, possibly with different access permissions. This is possible since the catalog manager implements the W3C XML Inclusions (XInclude) 1.0 Recommendation for XML inclusion.

To allow this, the catalogConfiguration element needs to contain a xmlns:xi="http://www.w3.org/2003/XInclude" attribute. Inclusion of a file is then done by using an xi:include element, e.g. <xi:include href="file name" />.

Sample usage of XML Include

File: Raincode.Catalog.xml

File: envvar.xml

The file envvar.xml will be included, and the actual configuration used will be equivalent to the following:

The catalog configuration has two means to customize the calling of the legacy runner:

The former is done through the legacyRunner entity, e.g., as follows:

The latter is done through the legacyRunnerParameters entity, e.g., as follows:

Both of the above can be further fine-tuned. Following the same pattern as environment variable definitions, different runner and parameter values for specific steps or programs can be defined. For example, we can run a different runner on specific program calls or JCL steps, and enable Trace level logging whenever a certain program will be called:

IDCAMS (Integrated Data Cluster Access Method Services) is a file manipulation utility. It allows for the creation, modification, and deletion of datasets.

IEBGENER is a copy utility that copies records from a sequential dataset or converts a dataset from a sequential organization to a partitioned organization.

There are four main use cases for IEBGENER:

Raincode Sort Runner is designed for compatibility with the existing mainframe SORT utility; there is no change needed to the sort commands. It sorts, copies and merges datasets as it does on the mainframe.

The Sort Runner implements sort functionality for both SORT calls from COBOL or PL/I program and standalone SORT executions from a JCL. Its code resides in a .dll, which the Raincode runtime utilizes for all sort operations initiated from COBOL or PL/I. SORT.exe, also relies on this .dll to perform its work.

Raincode provides a bare-bone implementation of the IKJEFT01 utility. Only the following commands are partially implemented: RUN, OCOPY, and LISTCAT.

IKJEFT01 on the mainframe is often used to launch applications and connect them to the database. The Raincode implementation of IKJEFT01 relies on an underlying runner, which by default is rclrun.exe.

IKJEFT01.exe will invoke rclrun.exe and pass the required command-line arguments. To use an alternative implementation of a runner, configure it by adding an environment variable LegacyRunner and providing the full path to the executable of the alternative runner.

To provide connection strings to the utility, the user must provide an environment variable RC_DB_FILE containing the path to a file providing the connection strings. This file must be in the following format:

Supported values for DBType are SqlServer and DB2.

For more information on database connections and connection strings, refer to the section JCL connection string retrieval.

To debug a program launch by IKJEFTK01, add the parameter -DEBUG.

For example:

Raincode provides an implementation of the DSNUTILB load and unload functionality. It obtains the connection string from the environment variables RC_DB_CONNECTION and RC_DB_TYPE. Both are set up by the JCL interpreter when the DSN parameter is provided to the EXEC command. For more details on how to specify the database to be used, refer to the section JCL connection string retrieval.

By default, DSNUTILB executes the SQL queries without any modification. However, in some cases, for example, when the target DB type changes, it is desirable to rewrite the queries before executing them. For more details, refer to the Query rewriting section.

The utility understands UNLOAD commands of the following form:

And LOAD statements of the form:

To load data, DSNUTILB uses either inserts or bulk inserts, depending on the UseBulk option. Bulk inserts are supported only for the SQL Server. The number of rows sent together to the database is defined by the LoadBufferSize option.

If the SYSDISK option is enabled and an error occurs during the insertion, the tool retries with a buffer 100 times smaller. This process continues until the specific row causing the issue is identified.

Raincode provides an implementation of the DSNTIAUL utility. It obtains the connection string from the environment variables RC_DB_CONNECTION and RC_DB_TYPE. Both are set up by the JCL interpreter when the DSN parameter is provided to the EXEC command. For more details on how to specify the database to be used, refer to the section JCL connection string retrieval.

By default, DSNTIAUL executes the SQL queries without any modification. However, in some cases, for example, when the target DB type changes, it is desirable to rewrite the queries before executing them. For more details, refer to the Query rewriting section.

Raincode provides an implementation of the DSNTEP2 utility. It obtains the connection string from the environment variables RC_DB_CONNECTION and RC_DB_TYPE. Both are set up by the JCL interpreter when the DSN parameter is provided to the EXEC command. For more details on how to specify the database to be used, refer to the section JCL connection string retrieval.

By default, DSNTEP2 executes the SQL queries without any modification. However, in some cases, for example, when the target DB type changes, it is desirable to rewrite the queries before executing them. For more details, refer to the Query rewriting section.

DFSRRC00 is the utility to access IMS through a JCL. Raincode only implements a subset of the original utility:

DFSRRC00 takes only one argument: the PARM taken from the JCL. Recall that on the mainframe this PARM consists of a comma-separated list of elements. The length of the list and the meaning of the elements depend on the value of the first element of the list.

Further, this document details what subset of DFSRRC00 is implemented.

Raincode provides an implementation for the mainframe FTP functionality. It accepts both FTP and FTPS protocols. If FTPS is used, all certificates are accepted.

The connection information is read from the NETRC DD. The environment variable USERID contains the default user id that is used to find FTP.DATA

Secure File Transfer Protocol (SFTP) replaces FTP, utilising Secure Shell (SSH) protocol version 2.0 to ensure safe file transfers. While it supports the same command structure as FTP, SFTP includes extensions that enable various types of authentication methods, as mentioned below:

Authentication Methods:

Configuration Using DD Statements:

The authentication method is specified using specific DD names, as mentioned below:

Compares INFILE and OUTFILE DD. If the files are different, the return code is 16. Otherwise, it is 0.

PARM:

Example:

Raincode supports a subset of the batch capability included in BMC’s File-AID utility, which is widely used for file and data handling in mainframe systems. File-AID is offered as a program that can be executed by a job step in Batch. In that case, the SYSIN can contain multiple File-AID statements, which all consist of the following three things:

Example:

In the above example, DD01 is an instream dataset containing some dummy data. File-AID is used to copy records from DD01 to DD01O. The parameter IF limits the copied records to those that have the character A or H at the first position. Therefore, MY.TEST.FILE will contain the following:

The SMTPMAIL utility allows sending emails directly from JCL using an SMTP mail host. The utility accesses the following environment variables in order to establish a connection and send an email.

Below is a sample code snippet.

The utility processes the SMTPIN DD in the following steps:

This utility also allows you to explicitly specify the sender by using a FROM: identifier. Recipient addresses must be specified separately, either through a TO: identifier or by listing the addresses on recipient lines as shown in the examples below.

You may also use aliases for both the sender and recipient addresses, as shown in the sample code. When aliases are included, the utility uses the text inside < > to determine the actual FROM and TO email addresses.

Raincode provides a subset of the SUPERC utility, which compares datasets in the Mainframe systems similarly to diff programs. SUPERC is offered as a program that can be executed by a job step in Batch. In that case, the SYSIN can contain multiple SUPERC statements, which consist of the following four elements:

Example:

In the above example, OLDDD is a dataset compared to another NEWDD dataset. SUPERC compares these two datasets according to the options provided in the PARM field. When the LINECMP option is enabled, the datasets are compared line by line. In this example, OVSUM means that SUPERC will display comparison result in a summarised form (Overview summary) containing the types of differences (if any) between the datasets and their count. For instance, three matches and one insertion in the new dataset. This summary will be saved in FILE.OUTPUT.

If the OLDDD (FILE.INPUT2) file contains the following:

and the NEWDD (FILE.INPUT1) file contains the following:

then, FILE.OUTPUT will contain the following:

DSNTIAUL, DSNUTILB, and DSNTEP2 can be extended with a plugin that rewrites the queries. For example, to rewrite Db2 queries to SQL Server queries.

A plugin that rewrites the queries (Db2 queries into SQL Server queries) is part of the distribution. This plugin uses cobrc for rewriting process and stores the results in a SQLite cache database.

To use this plugin, the utility must be called with two additional options -PluginPath=<QueryTranslation path> -Plugin=QueryTranslation

The plugin can be parametrized using different environment variables:

The SQLite cache database, named mssql-cache.sqlite, contains a single table cache with two columns: source and target. This database is in the directory %RC_SQL_REWRITE_CACHE_DIR%, if the database does not exist, the plugin creates it.

The %RC_SQL_REWRITE_CACHE_DIR% directory can also contain a second, optional, SQLite database named mapping-rewriting.sqlite. This database also contains a table named cache.

This can be useful if the translation process does not provide the expected result. For example, the target query needs to be optimized to achieve the expected performance.

The plugin searches for the query to be translated in the source column of mapping-rewriting.sqlite (if it exists). If the query is not found, it searches for it in mssql-cache.sqlite. If it is still not found, the plugin calls cobrc to translate the query and store the result into mssql-cache.sqlite.

The IEBCOPY JCL Utility allows for the copying and merging of Partitioned Datasets (PDS) and programs. This utility takes one or several datasets as input, and performs the action specified by the user, such as COPY or COPYGROUP (see the list of implemented options below). If no specific action is mentioned, and all the other prerequisites are met, a COPY action is performed by default.

Inputs and parameters

Example 1: Performing a simple COPY operation

In this example, the PDS pointed to by SYSUT1 will be copied into the PDS pointed at by SYSUT2. This is specified in SYSIN. The COPY command takes two parameters: OUTDD, the output dataset, which is the destination of the copy operation, and INDD, the dataset to be copied.

Example 2: Performing a partial COPY operation

In this example, MY.PDS1 contains three named members: MEMBER1, MEMBER2 and MEMBER4. MY.PDS2 contains three named members as well: MEMBER3, MEMBER5 and MEMBER6. In the SYSIN statement, the user specifies that a COPY operation should be performed, from SYSUT1 to SYSUT2, but that only MEMBER1 and MEMBER4 from SYSUT1 should be copied. This means that at the end of the operation, the output SYSUT2 will contain five members: MEMBER1, MEMBER3, MEMBER4, MEMBER5 and MEMBER6.

Example 3: A compact COPY operation

In this example, SYSIN and PARM are empty. However, since SYSUT1 and SYSUT2 are provided, a COPY operation will be performed using SYSUT1 as input and SYSUT2 as output.

BPXCOPY is a JCL Utility that allows copying datasets, initially from a Mainframe-based system to a UNIX-based system. Unlike IEBCOPY, the user may manipulate the ownership of the copied dataset, for instance, the group owner and the owner of the copied dataset. This utility takes one sequential dataset or one member of a partitioned dataset (PDS) and a destination path for the copy as input.

Inputs and parameters

Unlike many other JCL Utilities, BPXCOPY exclusively relies on the PARM field for control options and statements. The options cannot be provided in SYSIN or in any additional dataset. The list of these options is available in the list of implemented options below.

Implemented options

Example 1: Performing a minimal COPY operation

In this example, the dataset pointed to by SYSUT1 will be copied to the destination path, which is the concatenation of the value of SYSUT2 and the parameter of ELEMENT. It means that MY.DATASET will be copied to the folder u/output_directory/, under the name MYCOPY.

Example 2: Performing a COPY operation and create a symbolic link

In this example, the dataset pointed to by SYSUT1 will be copied to the destination path, which is the concatenation of the value of SYSUT2 and the parameter of ELEMENT. It means that MY.DATASET will be copied to the folder u/output_directory/, under the name ACOPY. In addition, a symbolic link to this copy is created in the destination file system; its path is u/output_directory/bpxcpylink/cpylink. It means that the symbolic link called cpylink is pointing to the copied dataset located in u/output_directory/ACOPY. Creating a hard link also follows the same logic.

Example 3: Performing a COPY operation to a Windows destination system

As in the other examples, the destination path is u/output_directory. If the destination system is Windows-based, it is possible to call this program using the -WindowsRootPath= flag to set the root folder. For instance, using the following command %RCBIN%/Submit.exe -File=BPXCOPYCOPERATION.jcl -WindowsRootPath="C:\myfolder" will copy MY.DATASET to C:\myfolder\u\output_directory.

The FILEBKUP utility provides dataset backup and restore capabilities using ZIP archives. It works like mainframe JCL, making it easy to use in batch jobs.

The ZIP390 utility aims to handle and exchange datasets. Specifically, the Raincode implementation enables dataset compression and supports sending emails with or without attachments.

ZIP390 takes its arguments from SYSIN. The user must first specify which ACTION they want to perform (either ZIP for archiving a dataset, or EMAIL to send an email that may contain an attachment). Then, depending on the intended action, several other fields may be required. For instance, if the user wants to send an email, the fields HOST, FROM, and TO are required.

The four examples below illustrate the different use cases currently implemented in Raincode ZIP390

Example 1: Sending a simple email with one or several recipients

In this example, the user wants to send an email with no attachment. The fields HOST, FROM, and TO are required. If SUBJECT is omitted, the email is sent with an empty subject. The body of the email is enclosed between BODY: and END:. However, the body of the email may be omitted as well.

Each additional recipient requires an additional TO= field.

Example 2: Sending an email with one simple attachment

To add an attachment to an email, add the ATTACH field. It should contain the name of the dataset to be attached. The dataset name is prefixed by the type of the dataset. For now, Raincode supports SEQ (sequential dataset) and DSN (dataset).

Example 3: Zipping a dataset

To compress a dataset, use the ACTION ZIP instead of EMAIL. The dataset name to be archived should be provided in the IFILE field. Similar to Example 2, the dataset should be prefixed by its type (DSN or SEQ), and can be suffixed by an alternate name after a semi-colon. The name of the archive is provided in the ARCHIVE field.

Example 4: Sending an email with mixed attachments

This use case covers a more complex scenario in which an email contains multiple attachments. Some of the attachments are archived, while others are left unchanged. This use case requires the ZIP ACTION keyword, even though an email is being sent.

In a first step, the datasets to be attached are processed: SEQDD1 and ZIP390.TEST5.DATA1 are zipped together in an archive named FULL.ZIP. Then, two other datasets are attached to the email: SEQDD2 and ZIP390.TEST5.DATA2. This means the email will contain three attachments: the ZIP archive and the last two datasets.

In this case, it is not necessary to explicitly provide the HOST field. It can be inlined in the ARCHIVE field, for example ARCHIVE=EMAIL/localmail.example.com/25/FULL.ZIP.

There are two configuration settings in the Raincode Catalog that determine how character encoding is treated: defaultCodePage and codePages. The latter also determines autodetection of codepage behaviour, so it is covered here as well.