AUTO

Synopsis

HELP:   Read binary, text or XML data record- or block-oriented
TYPE:   OBJECT
SYNTAX: AUTO(NET.{},FILE['str'/STREAM/DUMMY...],BLKSIZE=num,RECLENGTH=num,PRNCONTROL=DETACH/RETAIN/ERASE/REPLACE,RPLFFD[=num],CCSID='str'/DEFAULT/ASCII/EBCDIC/BOMUTF/BOMUCS/SYSTEM/LOCAL,CHRMODE=STOP/IGNORE/SUBSTITUTE/IDENTITY/TRANSLIT,SKIPEQUAL,USRTABLE='str'/NPAS/SEPA/DELA/DLAX,ONEMAP,COMBINED=NFD/NFC/AUTO/ON/OFF,BOM,KEEPBOM,ENL2LF,DECRYPT[{}...],REMOVE,LANG='str',PLATFORM=WIN/UNX/ZOS/USS/VSE/BS2/MAC,OWNER='str',ENVID='str',HASH(),SIGNATURE.{},CHECK,TABLE(),AVSCAN(),NOARCH,PREPROCESS[()...],POSTPROCESS/PSTPRO[()...])

Description

Read 'auto' attempts to identify the file format automatically and reads the file with the most appropriate parameters. Detection works on a best effort basis and should not be relied on.

For example, "read.auto() write.record()" can convert every supported file format to records on mainframe systems. This is utilized in the FLVIEW and FLVEDIT ISPF command.

With read.auto(), you can transparently read normal XML or text files with delimiters, encoded (BASE16/32/64), encrypted (FLAMFILE) or compressed (GZIP, BZIP2, XZ(LZMA)) files (even nested!), normal record-oriented data sets (FB(A/M)/VB(A/M)/VSAM/...), FLAMFILEs or binary data. If the data contains 4 byte length fields after I/O, decryption, decompression then a list of records is built to form one block. This allows you for example to read a file transparently from USS which was created with FILEDATA=RECORD and now allocated with FILEDATA=BINARY or a record length based format from a ZIP archive. The read.auto() function was mainly implemented to display (FLVIEW) the content of a file. The detection may fail on some files, especially for very small files.

Additionally, you can provide a list of row specifications through the table object. If the file matches a row specification, table formatting is used. If the data does not fit with the provided row specification, the normal auto processing is performed.

Generally: If you know the type of data (binary, char, text, xml, flam, charset/ccsid), it is recommended to use the corresponding read method and set the known parameters to prevent false detections. On the other side, if you know nothing about your data or you get data from different sources, read.auto() might be very helpful.

To simplify the use of the read.auto() function, the mechanisms below are implemented:

• The EBCDIC new line to ASCII line feed management is activated. This means that, for methods that support it, the ENL2LF flag is set for read methods and the ELF2NL flag is set for the write methods.
• Suppression of trailing whitespace is activated for text records.
• The print control character handling is set to erase print control characters from records.
• Subsystem specifications are not supported
• Base encodings are always decoded, if the decoding results in useful data. (i.e. text files in an a Base64 encoded Gzip file are decoded and uncompressed automatically). Optional CRC verification and verification of the trailer (if ASCII armor) is done if the CHECK switch is enabled.
• Record length format detection is enabled and used after I/O (a wrong static file allocation on z/OS was done (FILEDATA=BINARY instead of FILEDATA=RECORD) or a file with variable record length was read on Windows or UNIX platforms), after decryption (data containing record length fields were encrypted), after decompression (data with record length fields was compressed (ZIP)) and after base decoding (if data with length fields was encode).

To read ASCII text files with NEL delimiter or to use specific formatting options, please use read.text(). To keep and manage record attributes, please use read.record(). The read.auto() function is designed to be very powerful, using the procedures suited best and, at the same time, to keep it as simple as possible.

Arguments

• STRING: FILE['str'/STREAM/DUMMY...] - Name/URL of file to read [''==stdin]
  • STREAM - Read from stdin or write to stdout
  • DUMMY - Read EOF or write nothing
• NUMBER: RECLENGTH=num - Maximum record length (Host) / line length (Unix/Win) for text parsing [512]
• NUMBER: RPLFFD=num - Replace form feeds, filling rest of page with blank lines assuming n lines per page [60]
• SWITCH: SKIPEQUAL - Skip conversion if formats are equal (e.g. UTF-8 to UTF-8)
• SWITCH: KEEPBOM - Keep byte order mark for faster conversion
• SWITCH: NOARCH - Disable the attempt to read archives (prevent multiple opens to the same file) [FALSE]