Common Record Editor

 

The Common Record Editor is a versatile Eclipse IDE tool that allows the user browse and maintain various types of COBOL data files. Depending on the information provided , the UI of this tool makes file record maintenance a simple task.

To launch the tool in the Eclipse IDE, make sure that you set the current perspective to  ELASTIC COBOL and then  select the "Tools / Common Record Editor" menu option as shown in the fig below.

Use the File Information area to specify the file that you wish to open using the editor.

One can either specify the datafile location or lookup the datafile using the .dcb properties file.

DataFile Name     : The name of the data file. This field usually is populated automatically upon selecting the data file location.

[LookUp DCB...]   : Opens a dialog window that allows the user to select data files using the .dcb properties file.

                        DCB LookUp

                               

The DCB LookUp dialog assists the user in selecting datafiles that are recorded in the .dcb properties file. Use the [...] browse button to specify the .dcb file. Available file entries are loaded into the table listing the file name and attributes. Note that DCB index entries for VDB Indexed files are not displayed. Select a file by either double clicking or selecting the [OK] button

 

DataFile Location: Specify the location of the data file to be opened by the editor. In case of VDB/VSQL files specify the location where the .dcb will be located even though the actual file is located in the database.

XFDXML Layout: This view allows the user to specify the various record layout xml files that may be used with a datafile.  The XFD xml file contains the information that the editor requires to split up the data file record into individual fields and display them based on the data types. An XFD file is not a requisite in order to open a data file, however it does simplify viewing and maintenance of the data file. Without the XFD file the data file record is represented as one single field and any editing is allowed only on a byte per byte basis. Also the search facility for indexed files is disabled when the XFD is not available. Refer to the Elastic COBOL manuals for more information on creating XFD files.  

The right click context menu of the view has the following options:-

• Add XFD Layout : Opens a file dialog window that allows the user to import the XFD xml file.
• Delete XFD Layout : Removes an existing XFD layout from the view.
• Delete All XFD Layouts : Removes all existing XFD layouts from the view.
• Save Layout Structure... : Allows the user to save the current layout information in the view to a .rfs file 
• Load Layout Structure... : Allows the user to load existing layout information from a .rfs file.  
• Use IBM Charset : Toggle menu item that allows the user to input conditional information in ASCII/IBM format. 

When you import a XFD xml file, the field information is extracted from the xml file and displayed as sub items to the file. The view shows all the fields as checked by default where the checked state indicates that the field should be made visible when displaying the data. 

When using multiple record layout for a single file, the user can specify the condition as to when to use the layout by clicking on the conditional expression column for the field. Multiple fields can have conditional expressions applied in order to use a particular layout. The dialog window for the conditional expression is shown below:-

Similarly the user can also specify conditional expressions for the usage of redefines structures. The dialog window allows the user to specify the field on which the conditional expression is to be applied.  

[Load File]           : Opens and loads record from the currently specified data file. Note for MicroFocus Indexed files as well as ACUCOBOL Indexed files(version 4), the recordeditor first attempts to locate the dcb information for the file. If the dcb info is not specified, then the file extracts the dcb information from the file header and saves it. This prevents the user from having to create dcb information for these file types.

[Close File]            : Closes the currently loaded file.

[DCB Editor...]                   : Opens a new dialog window that contains DCB(data control block) information for the current file. DCB information is FILE CONTROL information that the record editor uses to identify the type of data file along with information about its keys and charset usage. The DCB information for a file is stored in a ".dcb" file which is usually located in the same directory as the data file. A single ".dcb" contains information for all data files located in that directory. When the record editor loads a file it will attempt to locate the DCB information for the file. If the information is not found, a message is displayed indicating that the DCB info is missing. The user can then choose to add/edit DCB information for the current data file by clicking on the <DCB Editor...> button. The DCB dialog is shown below.

DATA CONTROL BLOCK

The individual fields of the dialog are explained below:

Orientation         : The Orientation of the file. Select from "INDEXED", "NUMBERED" etc.

Record Format : The record format type such as "FIXED" , "VARIABLE" etc.

Rec Min              : The minimum record length

Rec Max             : The maximum record length

Rec Avg             : The average record length

Key Len             : The key length for NUMBERED files

Protocol            : The protocol that applies to the data file.

Charset              : The charset in which data is stored in the data file. 

Save                   : Save the DCB information to the .dcb file.

Delete                : Deletes the currently loaded DCB information from the .dcb file. Also prompts the user for deletion of any existing associated datafiles. 

Delete Multiple  : Brings up a dialog which allows the user to delete multiple DCB's entries from the specified .dcb file. The dialog is shown below

The dialog for deleting multiple DCB entries is very similar to the DCB lookup dialog. Use the [...] button to specify the .dcb file. DCB entries from the specified file are populated into the File Selection table. The user can select multiple entries from this table to delete. To delete data files associated with the DCB entries, check the [Delete Datafiles/s] check box. Note that deletion of VDB/VSQL tables is not supported. Also deletion of a VDB INDEXED dcb entry will automatically cause the deletion of related alternate indexed dcb entries.  

 

 

Close                  : Close the dialog

 

 

Key Info

Offset        : Offset of the primary/alternate key if applicable

Length       : Length of the primary/alternate key as applicable

Duplicates: Alternate key holds duplicates values or not

Data/IndexName: VDB file base name and alternate index names

Path Name: VDB file path name

[VDB/Sql Conn...]   : Opens a dialog window that allows the user to enter VDB/VSQL connection information.

VDB/VSQL Connection Settings

This dialog allows the user to input driver information as well as connection settings required to interface databases using VDB/VSQL.

Driver Info:- At the top of the dialog is a list of currently loaded drivers for the current record editor instance. The user can load additional drivers by clicking on the [Load...] button to the right. As indicated in the dialog, drivers once loaded remain active for the instance of the record editor.

Connection Info: Use this table to manually enter the specific connection information in order to connect to various databases. Once the information has been entered, the [Apply] button can be clicked in order to set the entered connection to the system properties. The user can also import preexisting connection information from .properties files by using the (import Settings) button on the right. The [prev] and [next] buttons can be used to navigate thru multiple entries in the .properties file.  

Active Connections:- Connections that are set for the current instance of the Record Editor can be viewed in this table. To unset any or all of the connections use the buttons to the right. To modify a connection information, right click the conenction and select "Modify Connection Info".  The user can make any of these connections the "Active" connection. To toggle a connection state, either double click on the connection, or right click and select "Toggle Active Connection" or use the  button to the right. The currently active connection is displayed below the table. If the user attempts to exit without a active connection, a confirmation prompt will be displayed. The settings for the prompt can be set at Window/Preferences/Elastic COBOL/Misc

 

Validate record length to fields : Validate individual field lengths to record length

Key Order   : The key Order selection combo is applicable to indexed files. It allows the user to select the key on which data is extracted from the data file. If the XFD xml file has been supplied the combo box provides the keys by name else the offset and length is provided.

 

Navigation buttons : 

The record editor loads a fixed number of records from the data file. The default value is 15 . In order to navigate thru the data file, navigation buttons are provided.

[|<]  - Go to first page.

[<]   - Read previous record. This button is enabled for indexed/relative files that support the read previous operation.

[<<] - Read previous page of records. This button is enabled for indexed/relative files that support the read previous operation.

[>>] - Read next page of records. Loads the next set of records

[>]   - Read next record.

[>|]  - Go to last page.

 

Search Key:

The record editor allows the user to perform search operations based on key values or on String/Hex values. To bring up the search dialog click on the "Search..." button.

This will bring up the search dialog window as shown below.

The top option allows the user to search based on key for indexed files and record number for non indexed  files. This option is disabled for indexed data files that do not have a XFD XML.

The bottom option of "Search All" allows the user to perform a string/hex value search on the entire file.

Select the "ASCII/EBCIDIC" radio button to enter a string value to be searched.

Select the "HEX" radiobutton to enter a hex value to be searched. The hex value should be entered without specifying the "0x". For e.g.  e2a3 

The Limit record check option is also provided for restricting the search range.  Specify the beginning offset and length to be applied for each record.

Clicking "Find" will perform the search operation. If found the next instance can be obtained by clicking the "FIND" again

Count Records:

Select "Count Records" to count and display the total number of records in the currently loaded file.

 

The record editor loads the data file records into the main table as shown.

If the XFD xml file is available then the record is split into fields as per XFD information. The field name is set as the column name along with the offset and length of the field. For Relative and other non indexed file types the first column is used to show the Relative key/Sequence # of the record read.

To control the number of records displayed per page in the main table, right click on the main table and select "Display Rows..." menu option. This will bring up a dialog where the user can change the number of records shown per page of the main table. Refer fig below.

Record Modification: The user can edit a field by pressing the <Enter> key or double clicking on the field. This will activate the field editor. Once the modification is complete, pressing the <Enter> key or clicking on some other field will close the field editor. If a field has been modified, its foreground color changes to red to indicate that it has been modified.  In order to save the modification made to a record, right click on that record and select "Save Record".  When a record is in a modified state, moving away from that record will automatically trigger the save prompt which provides the user with the options to continue editing , save or discard the changes.  For file types other than indexed or relative, record modification is supported only for the most recent record read. This is the last visible record shown in the table. However when using the <Last Page> navigation button for such files, the last record has already been read and end of file reached, so editing the record is not possible. In such situations where one needs to modify a specific record  use the [Goto Record#>] to lookup the record and then edit the record.

When the XFD is not available there is a single column which represents the entire record. Directly editing this record as described above is not supported since we do not have the data type. Refer to Hex/Decimal/Ascii byte modification described in this document to edit in such cases.

Record Deletion: In order to delete a record right click on the record and select the "Delete Record" option. Record deletion is supported for only indexed and relative files

Record Addition: To add a new record right click anywhere on the records table and select "Add Record". A new row gets added at the end of the table and the cursor is re-positioned to that row. Save options are similar to modification.

 

The record editor allows the user to modify the record on a byte per byte basis. The user can opt to edit the byte info using the Hex , Decimal or Charset tables. The data in each of these tables represent the field selected in the main table. Note that the field gets updated with the edited byte values only when the cursor moves away from the field. Selecting a value in either of the tables automatically positions the cursor in the other tables. The offset information of the cursor within the table is specified below. One can also enter a specific offset into the field and the cursor position will be set to that position.

 

 The font on each of the tables in the UI can be customized. Use the Windows/Preferences/Elastic COBOL/ COBOL IDE Fonts to select a custom font.

 Variable Record Format: 

When displaying records of variable length, the record editor typically allows the user to navigate to the columns extending beyond the size of the record. However attempting to edit the cell value will result in a error message indicating that the column is beyond the size of the record. The user can opt to modify the size of the record by selecting a column and using the right click context menu. The menu displayed is as shown below. 

Depending on the column selected, the user is presented with the option to include /exclude the column. Excluding a column will truncate the record and reduce the record size to the previous column. Including a column will increase the record size up to the selected column. The menu options may be hidden/disabled based on whether a column is a key or falls in the min record size limit. Once the menu option has been selected and confirmed the record is immediately rewritten with the new record size.

Multiple Record Layout:  

The Common record editor allows the user to view data files that have multiple record layouts. Multiple XFD xml files can be specified as stated above along with conditional expressions that determine which layout is to be used. Note that the default behavior is to use the first layout if non of the conditionals are met. Depending upon the data type in your data file, this may cause a crash. Hence it is recommended that all possible layouts be specified. When a file with multiple layouts is loaded, the field information is shown in a separate table as rows instead of columns. The user can select an individual record in the left side table which shows the entire record as a single column. Upon selecting the record the field table to the right will display the individual fields as columns. See fig below:

 

Redefines Support:  

The Common record editor allows the user to specify redefines that should be used depending on data in the record. The redefines conditional expression should be specified using the WHEN directive at compilation time. This will make sure that the compiler includes the redefined structure in the output xfd xml. The conditional expression can be modified / removed using the record editor interface for further customization. Note that using redefines in a layout will display the table information as row instead of columns.

 

 

 

File Transformation:  

The Record Editor includes a transformation feature which allows the user to transform a file between the various supported formats. To transform a file first specify the file to be transformed by either using the DCB lookup feature or by specifying the dataset name and path. The dcb information for the file to be transformed has to be provided in order to correctly load the file. As indicated above, if the dcb information is not provided, the user will need to manually enter the information prior to the transform operation.

Click on the [Transform...] button to bring up the transform dialog as shown below:

The [Input Data Control Block] group contains the DCB information of the input file that is to be transformed. The same information is replicated for the [Output Data Control Block] group. However the user can modify the dcb information to suit the end requirements of the output file. The user should make sure that the ouput file dcb information is correctly input for the incoming data. The user can also load pre-existing DCB formats by using the [Load DCB Info...] which is similar in operation to the [LookUp DCB...] described earlier.

For ease of use the input datafile name/location is replicated for the output datafile. This should be modified as the transformation process will not allow overwrite of the input file.

The [VDB/VSQL Conn...] allows the user to enter the driver/sql connection settings required for using VDB/VSQL features. This dialog is similar to the [SQL Conn...] dialog described earlier.

The user can control the number of records to be loaded by selecting one of the options specified with [Records to Convert]. Choose between [All], [Count] or [Range].

[Append Records] Select this option if the transform process should append to the file rather than create a new file

Information about the transformation process can be logged in a output file if the user chooses by selecting the [Log file] check button and specifying the output file location.

To begin the transformation process click the [Start] button. Note when the transformation process starts, the [Start] and [Exit] button will be disabled until the process finishes. Likewise the [Stop] button gets enabled during the execution of the process. The [Stop] button can be used to interrupt a long running process.

[Save Profile...] The information that is used to transform the file can be saved as part of a ".prof" file. This can later be reused along with the command line variant of the Transform feature or loaded. 

[Load Profile...] Load the profile information saved earlier.