REPORTFILE

Synopsis

HELP:   Name of the report file to log substitutions
TYPE:   STRING
SYNTAX: REPORTFILE='str'/STDOUT/STDERR

Description

With the report capability, you can log every substitution (stop / ignore / substitute / translit / skip / ...) to a log file. For the report file, all rules and replacements are valid, which are described under "FILENAME HANDLING" above. For example:

   REPORT=STDERR                          ; is SYSOUT on z/OS
   REPORT='~.MYREPORT(REPORT1)'           ; PDS on z/OS
   REPORT='<SYSUID>.MYREPRT2'             ; PS dataset on z/OS
   REPORT='~/myreport3.txt'               ; Unix path name
   REPORT='<HOME>\\reports\\myreport4.txt'  ; Windows path name

A substitution report has the syntax listed below:

   report_file         -> sub_definition_list
   sub_definition_list -> sub_definition sub_definition_list
                       |  EMPTY
   sub_definition      -> SUB '(' UNIT ':' OFFSET '+' POSITION ':'
                             code_point byte_string '='
                             code_point_list byte_string ')'
                       -> XLT '(' UNIT ':' OFFSET '+' POSITION ':'
                             code_point byte_string '='
                             code_point_list byte_string ')'
                       |  IGN '(' UNIT ':' OFFSET '+' POSITION ':'
                             code_point byte_string ')'
                       |  STP '(' UNIT ':' OFFSET '+' POSITION ':'
                             code_point byte_string ')'
                       |  IDT '(' UNIT ':' OFFSET '+' POSITION ':'
                             code_point byte_string ')'
                       |  SKP '(' UNIT ':' OFFSET '+' POSITION ':'
                             code_point byte_string ')'
                       |  UKW '(' UNIT ':' OFFSET '+' POSITION ':'
                             code_point byte_string ')'
   code_point_list     -> CODEPOINT '/' code_point_list
                       |  EMPTY
   code_point          -> CODEPOINT
                       |  EMPTY
   byte_string         -> '(' BYTESTRING ')'
                       |  EMPTY

A comment behind brackets explains the reason for substitution:

'invalid character' 'incomplete character' 'incomplete character at the end of a record'

The notations STP (stop), IGN (ignore), SUB (substitute), XLT (transliteration), IDT (identical) or SKP (skip) before round brackets indicate the action taken. If the task cannot be determined then UKW (unknown) is used. A ignore of an invalid character is realized as substitution with nothing. All substitutions with a length of 0 are indicated with IGN (ignore). The position of such an abnormal/irregular character is coded inside the braces:

• UNIT number of records or blocks (depends on the data)
• OFFSET byte offset up to this unit in the complete data stream
• POSITION number of bytes inside the unit where the activity was done

All counting starts with 0. The first block or record has unit 0.

The position is relative to the data stream which was presented to the character conversion module. After conversions and formatting the position values can be far off from the input file which was read originally. For example, when reading a text file with text formatting to records, then delimiting characters are not included in the byte offset, the units are records and the position indicates which character was the issue for this log entry.

The CODEPOINTs (Unicode) are taken from the defined substitution table The BYTESTRINGs are taken from the input (read characters) and output data (written characters). BYTESTRINGs and CODEPOINTs are provided if they are known in the cases of such an irregularity. In some cases, these values can be missing.

For interpreting the report file, you must know that only the values inside round brackets are meaningful. Text before or behind round brackets are comments, but this may be subject to changes.

Selections

• STDOUT - Write output to stdout
• STDERR - Write output to stderr