File Copy

The file copy task (filecopy) copies a file. It can change the file format and, depending on the copy mode, convert the file encoding (EBCDIC/ASCII).

The following copy modes are supported:

Mode Description
binary Data is copied AS-IS (no conversion occur, in any case)
layout Data is copied/converted according to the provided layout(s)
text Data is copied/converted as SBCS text, depending on the encoding defined for repositories of the source and target files
mixed Data is copied/converted as Mixed data (shifted DBCS). Padding of DBCS string is driven by the attribute padmode
dbcs Data is copied/converted as DBCS data (unshifted DBCS)

During the copy the input file can be sorted using the sort element.

The file copy task is defined by the XML element filecopy whose attributes configure the execution parameters.

The following attributes configure the task:

Attribute Type Purpose Default
source string Name of the source repository
target string Name of the target repository
mode string Copy mode (see above). layout
append string If true, the target file is open in append mode false
skip integer Number of records to skip zero
count integer Number of records to display. If zero, all records are copied
skipinvalid bool If true, records with invalid data content (i.e. invalid DBCS) are skipped false
firstastext bool If true, the first record is converted as a single SBCS text field false
lastastext bool If true, the first record is converted as a single SBCS text field false
padmode string Pad mode for mixed data when converting in mixed mode. See Pad mode As defined in the environment file
validatenumeric bool If true, zoned and packed data content is validated false
ondbcserror string Defines the behavior in case of error converting DBCS. See DBCS Error Management error
warnmissingdbcs bool Warns when DBCS bytes not found in the codepage. true
warnmmalformeddbcs bool Warns when malformed DBCS sequences. true
warneverydbcserror bool If true every instance of the DBCS errors gets logged, otherwise only first gets traced true
maxwarnings integer Warnings limit. When greater than zero, the conversion stops when the specified number of warnings is detected. Zero

The following elements configure the task:

Element Purpose
source Name and attributes of the source file. Refer to Source and Target Files.
target Name and attributes of the target file. Refer to Source and Target Files.
layouts Defines the record layout(s) contained in the file, when working in layout mode. Refer to Layouts.
sort Defines the sort rules. Refer to Sort.
Note

The conversion direction (EBCDIC to ASCII or viceversa) depends on the encoding defined for the repositories of the source and target files. If both repositories use the same encoding, no conversion is performed.

Source and Target

The source and target elements define, respectively, the input and output files of the task.

The following attributes configure the file:

Attribute Type Purpose Default
recfmt string Defines the record format of the file. Refer to File Formats fixed
reclen integer Defines the maximum record length
varfmt string Defines the variable record format. Refer to Variable Record Formats If not specified, the repository default is assumed.
dd string When used with in a JCL interface, the name of the DD JCL statement referencing the file. The file characteristics are extracted from the file catalog and, therefore, the other attributes (recfmt, reclen and varfmt) are ignored.
trim bool If true, trailing spaces and NULLs (0x00) are removed from line sequential records false
encoding string Name of the text encoding to be used for Line Sequential files. Latin1
cache bool If false, file copy is refreshed (applies to cached repositories only) true
Note

The list of available encodings is listed here: https://docs.microsoft.com/it-it/dotnet/api/system.text.encoding?view=net-5.0

Note

For MARS repositories, recfmt, reclen and varfmt are ignored. The file characteristics are extracted from the MARS file catalog.

File Formats

Type Synonim Description
fixed fb Fixed Record Length
variable vb Variable Record Length
lineseq ls Line Sequential

Variable Record Formats

Type Description
ibm IBM variable record format
microfocus Micro Focus variable record format

Layouts

The layouts element defines one or more record layout to compare/convert the files as well as the match script in case of multiple layouts.

The following elements configure the layouts:

Element Purpose
layout Adds a layout definition. Refer to Layout
match Defines the match algorithm. Refer to Match

Layout

The layout element defines a one or more record layouts. Each layout must be identified by a unique name (task-wide).

By default, the layout fields are defined using XML:

  • Each layout element defines one single layout
  • Record fields are defined using field elements

But there is also the possibility to define the layout using COBOL data definition syntax:

  • Each layout element defines one or more layouts (one each level 01)
  • Record fields are defined using COBOL notation

For further information on layout definition, refer to Record Layouts

Match

The match element defines the "match class". Whenever more than on layout is provided, Ianus needs a match class to drive the selection of the correct layout for each record compared.

This class must implement the interface HPE.Ianus.Scripting.ILayoutMatch. For a detailed description of the match class please refer to the Record Layout Layout Matcher section.

The class can be provided as:

  • C# script: the code is compiled on the fly by Ianus and declared either:
    • inline, by adding the code in the element value, or
    • by reference, providing the filename of the script on the path attribute. If the script file name is not absolute, the script is searched in the same path of the job script.
  • Class library: the class can be coded in any .NET language such as C# or VB.NET but also COBOL for .NET and compiled as .NET class library. The class can be referenced either:
    • directly: providing the filename of the DLL containing the class on the assembly attribute and the full name of the class on the class attribute, or
    • by alias: providing the name of the plugin alias defined in the Plug-ins section of the Environment Configuration File.

The following attributes configure the element:

Attribute Type Purpose Default
path string Indicates to load the class script from the specified file
assembly string Indicates to load the class assembly from the specified DLL
class string Indicates the name of the class to use
plugin string Indicates to load the class from the plugin alias defined in Plug-ins

Pad Mode

When converting/comparing mixed data from EBCDIC to ASCII, Ianus replaces SOSI bytes (0x0E/0x0F) by blanks (0x20). The pad mode indicates how the replacement is done:

Mode Description
end Text is shifted left on 0x0e and 0x0f and the area (field or record) processed is padded right with blanks (0x20)
shift-out Text is shifted left on 0x0e and 0x0f and the area (field or record) processed and two blanks (0x20) area added on 0x0f

Sort

The sort element sets the sort directives and instructs Ianus to invoke the external sort engine to sort the input file before performing the copy.

Each sort processing is defined by the sort element. The following attributes configure the layout:

Attribute Type Purpose Default
side string Side where the sort directive applies: left, right or both both
collate string Collate sequence to use for the sort: native or ebcdic native
signebcdic bool When set to true, zoned fields sign is handled according to EBCDIC conventions true

The following elements configure the sort:

Element Purpose
key Adds a key to the sort operation.

Key

The key element defines a one a sort key. Keys can be definined:

  • By referencing a field previously defined in a layout by the layout element.
  • By providing offset, length and type (according to the sort engine formalism)

The following attributes configure the key:

Attribute Type Purpose Default
field string Name of the field to use as key (mandatory).
layout string Name of the layout containing the field. If omitted, the first field which name matches the provided one, is selected.
order string Sort direction: asc or desc asc
offset integer Offset (starting from 0) of the sort key
length integer Length in bytes of the sort key
type string If provided, sets/overrides the key data type, according to the sort engine key formalism (for example, with MFSORT: CH, CX, PD)

Example

  <sort side="right" collate="ebcdic">
      <key type="CH" offset="0" length="2" order="asc" />
  </sort>
  <sort side="both" collate="ebcdic">
      <key field="char01" order="desc"/>
      <key field="char02" order="desc"/>
      <key field="zoned01" order="desc"/>
      <key field="zoned02" order="desc"/>
      <key field="comp01" order="desc"/>
      <key field="comp02" order="desc"/>
      <key field="comp03" order="desc"/>
      <key field="comp04" order="desc"/>
      <key field="pack01" order="desc"/>
      <key field="pack02" order="desc"/>
  </sort>

Example

<filecopy source="REPOEBCDIC" target="TMPA" mode="convert_sbcs">
    <source recfmt="fixed" reclen="80">SOURCE.FILE.EBC</source>
    <target recfmt="ls"    reclen="80">SOURCE.FILE.TXT</target>
</filecopy>  

<filecopy name="COPYEBCSEQ" source="REPOEBCDIC" target="TMPA" mode="layout">
    <log>**** SEQ FIXED comparison - DIFFs expected ***</log>
    <source recfmt="fixed" reclen="80">IANUS.TEST.SEQ01.EBCDIC.DAT</source>
    <target recfmt="fixed" reclen="80">SORT.TEST.CONV.DAT</target>
    <layouts>
      <include>ZZREC01.xml</include>
    </layouts>
    <sort>
      <key field="CHAR01" order="desc"/>
    </sort>
  </filecopy>

Status codes

Status Status code Description
Ready -1 Task is initialized, but not yet started
Running -2 Task is running
Success 0 Task completed successfully, all records copied
Warnings 1 Task completed with warnings
Errors 2 Task completed with errors
Aborted 9 Task cannot be executed