### CONV

#### Synopsis

    HELP:   Simplified data conversion
    TYPE:   OBJECT
    SYNTAX: > flcl CONV(READ.{},WRITE[{}...],DIR(),LOGGING.{},MESSAGE(),INVERSE='str'/STDOUT/STDERR,NORUN)

#### Description

The CONV command converts data between various formats with an easy to use syntax. It was designed to simplify the use of the powerful Frankenstein Limes Universal Converter (FLUC). It can be used to read local or remote data sources (requires a FLIES or SSH server) of various formats, convert the data (e.g. decrypt, decompress and character conversion) and write the result to an unlimited amount of local or remote targets in different formats.

As an example, the CONV command can be used to read an encoded, encrypted and compressed text file in UTF-16 from a Windows system, generate or verify a checksum, write each line as text record into a mainframe dataset with a dedicated record format (FB, VB, ...) in EBCDIC with ASA control characters and write an additional copy of these records in UTF-8 with line delimiters as PGP file to a remote ZIP file. All these conversions are done in one step to reduce CPU and I/O utilization.

The following features are supported:

- Different kinds of remote access protocols (SSH, IP-Native, MQ-Series)
- Different kinds of data sources (Files, Streams, Tables)
- Different kinds of archive formats (ZIP, FLAMFILE, TAR)
- Different kinds of I/O methods (Binary, Character, Text, Record, FLAM)
- Different data encodings (HEX (Base16), Base32, Base64, ASCII armor)
- Different encryption methods (FLAM, PGP)
- Different compression methods (GZIP, BZIP2, XZ)
- Automatic decoding of data encodings during read operations
- Auto-detection and decoding of length fields in data blocks
- Auto-detection of character sets and language based conversion
- Auto-detection of freely defined table formats
- Powerful character conversion based on CCSIDs with
  - subset support, reporting, mapping, input assistance
  - Unicode support within EBCDIC code pages to work with 3270
- Different logical data formatting (BIN, TEXT, XML, tables (FB-CSV-VB), ...)

If the CONV command is not sufficient to meet your requirements, you can use the XCNV command which provides all full conversion capabilities of FLAM in a kind of expert mode with maximum configurability. The CONV command provides an easy to use subset of all conversion capabilities. In contrast to XCNV, the CONV command performs various types of auto detection and automated conversions to get a data representation that fits the current system and "makes sense" in the given context. To use the XCNV command, you must know what kind of data is read and can fully control how the data is written.

To get syntax information, please use:

       flcl SYNTAX CONV

To get help for a parameter, please use:

       flcl HELP CONV.parameter[.parameter[...]]

To read the manual page for a parameter, please use:

       flcl MANPAGE CONV.parameter[.parameter[...]]
          or
       flcl HELP CONV.parameter[.parameter[...]] MAN

To generate the user manual for the command, please use:

       flcl GENDOCU CONV=filename

Parameters can be defined via command line (directly or by parameter file) or via properties taken from the corresponding property file

#### Example

       flcl CONV read.text(file='ssh://<cuser>@server1/swift.txt.gz'
                             hash(algo=SHA256))
                 write.record(file='<SYSUID>.text(swift)'
                              chrmode=SUB systab=iconv usrtab=DELA
                              report='<SYSUID>.report(swift)'
                              format=VBA ccsid='IBM273')

Reads remote a binary file, calculates a SHA-256 checksum in GNU style, automatically decompresses the data (as text cannot be compressed), performs a character conversion to UTF-8 (no report required), formats the data into text records and rest elements, convert the text records to old German EBCDIC (IBM-273) with transliteration, substitution and a report file (upgrade-proof) and writea the text records to a variable blocked dataset with ASA print control characters. The user table 'DELA' ensures that only the subset of characters are valid which are available in CP1252, IBM-1141 and ISO-8859-15.

       flcl CONV read.record(file='<SYSUID>.text(swift)' ccsid='IBM273')
                 write.text(method=CRLF, ccsid='LATIN1', comp.bzib())

Reads records from a VBA dataset, does a character conversion to UTF-8, formats the data as text with carriage return and line feed as delimiter, converts the text data to Latin-1 and writes the result to BZIP file. Conversion stopped if a character is not convertible. Assuming the input file is the output of the previous example, this cannot be the case because the user table DELA used to create the file '<SYSUID>.text(swift)' prevents characters not available in Latin-1 (a.k.a. ISO-8859-1). The previous example would transliterate the EURO sign (`€`) to 'EUR' because the CCSID was IBM-273 (does not include the EURO sign). To retain the EURO sign, the CCSID IBM-1141 (=IBM273+EURO) would have to be used in the previous example and ISO-8859-15 (=LATIN1=ISO-8859-1+EURO) in this example.

       flcl CONV read.file='my.data'
                 write.record(file=stream, ccsid='IBM1141'
                              recm=cut,chrm=sub,systab=iconv)

Reads XML, text or binary data in encoded or clear form and converts the data to records which are printed to STDOUT (STREAM) in EBCDIC (IBM1141) where longer records are truncated (RECMODE=CUT), not convertible characters are transliterated (SYSTAB=ICONV) and if this not possible substituted (CHRMODE=SUB). With this command you can read any kind of file on mainframes and convert it to readable records. This command is used as part of the ISPF line command FLVIEW. It reads normal record oriented host datasets (PS, PDS(E) as VB/FB/UNDEFINED with or without ASA or machine print control character), VSAM-ESDS/RRDS/KSDS, FLAMFILEs, binary transfered text or XML files from other platforms, encoded and/or compressed text or XML files, etc.

       flcl conv read.char(file='~/myfb80.pgp' reclen=80 ccsid=IBM037
                              decrypt.pgp(fkm5()))
                   write.record(file='~.MY.DATASET' falloc(recf=FB recl=80))
                   write.text(file='ssh://user@server/my.zip'
                              method=unix ccsid=UTF-8 archive.zip())

Reads an encrypted PGP file containing a text file with fixed length records of length 80 with CCSID IBM-037 from another mainframe system and writes the records with the local CCSID (for example IBM-1141) to an FB80 dataset. A copy is written in UTF-8 (with 0x0A as record delimiter) to a ZIP archive on a remote SSH server. This example shows the exchange of fixed-length records through of block-oriented data formats.

The CONV command supports the auto detection of 4 byte length fields (read.binary()) or text delimiters (read.text()) in the data to simply exchange variable length record formats. To exchange fixed length records you can use

       read.binary(reclen=80)

or for text records

       read.char(recl=80)

READ.CHAR(), in contrast to READ.TEXT(), was designed to read text without delimiters. A fixed length dataset contains no delimiters and the internal record length table must be built after all the decoding steps, but before character conversion. The RECLENGTH parameter in READ.TEXT() is used after character conversion if no delimiters and no internal record length table are found to wrap the data blocks into records. If character conversion is done from EBCDIC to UTF-8 like in the example above, it may happen that some characters are converted to multibyte UTF-8 characters. In this case, the record length is no longer fixed. This means that splitting a block into records after character conversion will result in incorrectly wrapped UTF-8 records. To wrap a block into fixed-length records, READ.BINARY() or READ.CHAR() should be used.

       flcl INFO get.file='my.data'

Lists all determined file attributes including CCSID, delimiter, possible base encodings and (if appropriate) the member list of (concatenated) FLAMFILEs, GZIP, BZIP2, XZ files or a PGP dump.

#### Arguments

- `SWITCH: NORUN - Don't run the command only show parsed parameter`