IMS/DB Data Conversion

The IMS/DB data conversion task (imsconv) splits and converts an IMS/DB DBD export file. It reads a DBD export file an produces a file for each SEGMent type contained in the source file.

Important

This is an experimental task: the task behavior is not guaranteed.

The following input file formats are supported:

Format Description
DFSRRC00 The source file is generated by standard IBM IMS/DB utility DFSRRC00
AGI The source file is generated by AGI custom utilities

Output files are created in the target repository with the following naming convention: <DBDNAME>.<SEGMENT>.dat.

The tasks takes care of converting the data encoding according to the settings of the source and target repositories/files.

The IMS/DB Conversion task is defined by the XML element imsconv 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
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

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) of the DBD segments contained in the input file. Refer to Layouts.
segments Associates the source segments with the corresponding layout(s). Refer to Segments.
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

Segments

The segments element defines one or more segment. Segments are defined by the segment elements.

Every segment contained in the input file must be defined with a corresponding segment element. If a segment on the input file has no corresponding definition, the task fails.

Segment

The segment element associate a segment with the layout(s) to be used at conversion time.

The following attributes configure the task:

Attribute Type Purpose Default
name string The segment name, as specified in the input file record headers
length integer The segment length, in bytes
layout string The default layout to use with the segment. If set to *, the layout name is assumed to be the same as the segment name. If not specified, a match script must be provided.
parent string The name of the segment's parent segment. If not specified, the segment is considered as level 1 segment

Match

In case of segments with multiple layouts, the optional element match must be used to assign a match class.

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

Example

<imsconv name="CONV1" source="CHTE" target="CHTA" 
		    dbd="BPREGDB" skipinvalid="true" count="100">
	<source recfmt="variable" reclen="27994">BPREGDB.TXT</source>
	<discarded>C:\tmp\chte\BPREGDB.TXT.DISCARDED</discarded>
	<layouts>
		<layout type="cobol" format="free">
		01  REGDB-REC.                                                           
			03  REGDBKEY.                                                        
				04  IDNO-B        PIC  X(10).                                    
			03  NAME-0E-B         PIC  X(01).  
			@ianus*type=dbcs		   
			03  NAME-B            PIC  X(78).                                    
			03  NAME-0F-B         PIC  X(01).                                    
			03  REG-ADDR-0E-B     PIC  X(01). 
			@ianus*type=dbcs		   
			03  REG-ADDR-B        PIC  X(78).                                    
			03  REG-ADDR-0F-B     PIC  X(01).                                    
			03  ZIP-B             PIC  X(05).                                    
			03  TRAN-DATE-B       PIC  9(07).                                    
			03  SYSTEM-ID-B       PIC  X(01).                                    
			03  FILLER-B          PIC  X(17).                                    
		</layout>
	</layouts>
	<segments>
		<segment name="REGAA" parent=""
			            length="200" layout="REGDB-REC" />
	</segments>
</imsconv>

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
Warnings 1 Task completed with warnings
Errors 2 Task completed with errors
Aborted 9 Task cannot be executed