OpenCobolIDE DocumentationRelease 2.4.0-beta

Colin Duquesnoy

July 03, 2014

Contents

1 Parts of the documentation: 31.1 What’s New? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Download & Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.3 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.4 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.5 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181.6 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2 Meta information: 19

3 Indices and tables: 21

4 Disclaimer 23

i

ii

OpenCobolIDE Documentation, Release 2.4.0-beta

OpenCobolIDE is a simple and lightweight cobol IDE based on the OpenCobol/Gnu Cobol compiler and the pyQodesource code editor widget.

Contents 1

OpenCobolIDE Documentation, Release 2.4.0-beta

2 Contents

CHAPTER 1

Parts of the documentation:

1.1 What’s New?

This page lists the most prominent milestones achieved by the OpenCobolIDE developers. For more specific detailsabout what is planned and what has been accomplished, please visit the issues page on github.

1.1.1 Next Version

We don’t have any plans for the next release. Please report bugs and share your thoughts to make OpenCobolIDEbetter!

1.1.2 Changelog

2.4.0

New features:

• add Mac OSX support

• move to PyQt5 (to support retina screens)

• add support for pyQode 2.0:

the new api is a lot more stable API and is now fully tested. The editor style and performances have beenimproved but the folding panel has been temporarely removed (for performance reason)

• new user interface:

the menu and toolbar has gone, instead there is now a compile and run button inside the editor and a dropdown button in the status bar for the most important actions.

The homepage and the preferences dialog also got redesigned.

• compiler process management has been improved:

We are now using QProcess instead of subprocess, this allow some neat improvements such as auto compilebefore run.

• better log message + log window: include information from the log window when you report bugs!

Please, read the Getting started section of this manual to get started with the new user interface!

3

OpenCobolIDE Documentation, Release 2.4.0-beta

2.3.1

• drop python 2 support (the main script must now be run by a python3 interpreter)

• fix bug with encoding error, see bug #31 on github

2.3.0

New features:

• add ability to run the compiled programe in an external terminal. This is useful if you are using theSCREEN SECTION as the embedded terminal does not support redirection.

Fixed bugs:

• fix bug with detection of submodules call if they are enclosed with single quotes instead of double quotes

2.2.0

New features:

• pic fields offsets calculator

• case converter, you can convert selected text to lower or TO UPPER using the editor context menu.

• full dark style using qdarkstyle

• new test suite for compiler and parser modules

• improved go to line dialog

• add support for _*.pco_ and _*.cpy_ files

Fixed bugs:

• fix compilation for file if path contains spaces (Linux and Windows)

• fix parser crash that prevents from compiling

• improve cobol parser to support malformed syntax

• fix ambiguous shortcut overload: F2

• fix outline not informative for cobol files that have data in column 1-6

2.1.0

New features:

• Go to definition for variables and procedures (ctrl + click on symbol)

• New debian package on ppa:open-cobol-ide/stable and ppa:open-cobol-ide/unstable

Fixed Bugs:

• code completion should not occur in comments and strings

• fix column number for navigation panel

4 Chapter 1. Parts of the documentation:

OpenCobolIDE Documentation, Release 2.4.0-beta

2.0.1

Fixed Bugs:

• removed un-needed import of pexpect which caused some issue on clean system which does not havepexepect.

2.0.0

This new release is a major update which makes the transition from PCEF to pyqode. Most of the application has beenrewritten from scratch.

Here are the major changes:

• port to pyqode 1.0

• new compiler errors panel

• interactive output console for program output

• uses pyqode.qt in place of PySide

• support for both python 2 and python 3

• on the fly syntax check, OpenCobolIDE compile your code in the background to quickly warn you about wrongsyntax.

• better integration with most linux desktop environments (use icons and colors from theme, desktop entry).Tested with KDE, Gnome, Unity and Cinnamon.

• allow user to type in lower case (https://github.com/OpenCobolIDE/OpenCobolIDE/issues/1)

1.4.2

• Update code so support pcef 0.2.2

1.4.1

Fixed Bugs:

• slow in large files: https://bugs.launchpad.net/cobcide/+bug/1179228

1.4.0

New features:

• shortcuts for dock windows (F9: log panel, F10: navigation panel)

• show fullscreen shortcut change from F12 to F11

• the application will restore its geometry and state (maximised, dock window positions)

Fixed Bugs:

• dock panel shown when switching tab: now the panel is only show when coming from the homepage orwhen compiling

• crash when editing/compiling files who have unicode characters in their path

• focus lost when opening recent files from the menu or the homepage on ubuntu 12.04 -> 13.04

1.1. What’s New? 5

OpenCobolIDE Documentation, Release 2.4.0-beta

Enhancements and fixed bugs in PCEF 0.2.0:

• improve performances in general

• support for custom word separator, allow OpenCobolIDE to remove the ‘-‘ character from word separatorswhich brings a better code completion for cobol

• dirty flag is correctly updated

• scrollbars are now correctly update when folding/unfolding code blocks

1.3.0

This release improves usability with a focus on the run and compile actions:

• detect source dependencies and compile them (if a program P requires a subprogram A who requires asubprogram B than the IDE will compile A, B and P)

• Automatically compile file when the run action is triggered

• Run the last program if the current tab is a subprogram

• Avoid compiling a file that is already compiled and up to date

1.2.1

• Fix bug: https://launchpad.net/cobcide/+milestone/1.2.1

1.2.0

Added:

• Home page with list of recent files

• A settings page to change a few options (mainly related to the editor style)

• A navigation panel to quickly browse large files (tree with div, sections, variables and paragraphs)

• A shortcut to comment/uncomment selected or active lines (ctrl+/)

• On GNU/Linux, at first start the program will ask the user if he wants to create a desktop files

Bug fixes:

• windows path not normalized

• fix bug with mingw when path contains spaces on windows

• fix bug where no extension was proposed when creating a new file

1.1.0

• better encoding detection using chardet

• cobol specific code completion model

• status bar infos (filename, encoding, cursor position)

• windows port (a windows installer is available in the download section)

6 Chapter 1. Parts of the documentation:

OpenCobolIDE Documentation, Release 2.4.0-beta

1.0.1

• fix packaging issues

1.0.0

• Initial development

1.2 Download & Install

Here you’ll find all the necessary explanations for installing OpenCobolIDE.

1.2.1 Requirements:

OpenCobolIDE depends on the following packages:

• Python 3

• PyQt5

• OpenCobol

• pyqode.core

• pygments >= 1.6

• chardet

GNU/Linux

Install pyqt5, open-cobol and pip using your package manager, then run the following commands:

sudo pip3 install OpenCobolIDE

If you are on Archlinux, you can install OpenCobolIDE and all its dependencies from the AUR:https://aur.archlinux.org/packages/open-cobol-ide/

Windows

There is a windows installer available here: https://launchpad.net/cobcide/+download

Mac OSX

There is a dmg image available here: https://launchpad.net/cobcide/+download

The only thing you have to do is:

• to install OpenCobol compiler, e.g. using homebrew:

brew install open-cobol

• run the OpenCobolIDE app

1.2. Download & Install 7

OpenCobolIDE Documentation, Release 2.4.0-beta

Note: If you installed the compiler in a non-standard path and it is not recognized, you can specify and the path tothe compiler in the preferences dialog under the Build & Run section. Just make sure to only specify the directorywhere the compiler can be found, not the full path.

1.3 Getting started

Note: All the screenshots were taken on Gnome 3 desktop. You will have different looks and feels on other OS/DE.

This is the first window you will see when running OpenCobolIDE. This is your home page.

From there you can create new files or open existing one. OpenCobolIDE is simple and lightweight IDE. It works ona single file basis (i.e. it has no concept of project):

You create/open a file, compile it then run it.

1.3.1 Create a new file

• click on New

• the following dialog should appear:

8 Chapter 1. Parts of the documentation:

OpenCobolIDE Documentation, Release 2.4.0-beta

• fill up the following information:

– Type: Specify the type of file to create. You can choose from

* program: A program is an executable. When compiled, it produces an .exe on Windows and anexecutable binary file on GNU/Linux and Mac OSX.

* module: A module or subprogram is a library, a list of procedures that can be shared amongother modules/programs. When compiled, it produces a dynamically linked library (.dll) onWindows and a shared object (.so) on GNU/Linux and Mac OSX.

* empty: create an empty file.

The type can be changed later. It used now to setup the default code skeleton, to simplify your life ;)

– Name: file name without extension (you can choose the extension in the drop down list)

– Directory: directory where the file will be created.

Warning: Modules source code must be in the same directory as the parent program source code to work properly.

1.3.2 Open a file

Simply click on Open or choose a file in the recent files list.

Note: The recent files list have a context menu that let you remove a file or clear the entire list.

1.3.3 The main window

Here is the main window of OpenCobolIDE:

1.3. Getting started 9

OpenCobolIDE Documentation, Release 2.4.0-beta

It is made up of 4 important parts:

1. the text editor tabs:

This is where you type your code.

2. the navigation panel (movable and closable):

This panel show you the structure of your code and let you navigate quickly inside your document.

3. The Log panel (movable and closable):

This panel show various log and output.

It is made up of the following tabs:

• Compilation output: textual output of the cobol compiler

• Issues: the list of issues

• Output: the program output (when you run it). The output console is interactive and acceptsstdin.

• Application log: the application log, for debugging purpose. This window is not visible whenyou start the IDE. You can show it by checking: menu -> View -> Appplication log -> Showwindow

4. the status bar:

10 Chapter 1. Parts of the documentation:

OpenCobolIDE Documentation, Release 2.4.0-beta

Since version 2.4, the status bar has become an important part of the application as it now contains the preferencesbutton and the general menu as a drop down menu button:

You can click on the button to show the preferences dialog or click on the arrow to reveal the general menu (Open,New, View, Help, ...).

1.3.4 Compile a file

To compile a file, press F8 or press the compile button (inside the editor). This will compile the current file but alsothe referenced modules.

The compiler output will automatically be shown:

1.3. Getting started 11

OpenCobolIDE Documentation, Release 2.4.0-beta

You can double click on an entry in the issues table to quickly go to the problematic line in the code editor (if the filehasn’t been open, OpenCobolIDE will gently open it for you).

To change the program type you must press the down arrow next to the compile button. Doing this will reveal a dropdown menu that let you choose the program type:

12 Chapter 1. Parts of the documentation:

OpenCobolIDE Documentation, Release 2.4.0-beta

1.3.5 Run a compiled program

Press F5 or click the run button (inside the editor) to run the file.

The program will run in the Output window which is interactive (support for stdin has been tested and works with theACCEPT keyword).

1.3. Getting started 13

OpenCobolIDE Documentation, Release 2.4.0-beta

Note: It will recompile the file and all its dependencies before running the compiled program.

1.3.6 Calculate the offset of a selected record

Since version 2.2, you can now calculate the offset of a selected record.

• select the text that contains the record you’re interested in,

• right click on the editor to open the context menu

• click Calculate PIC offsets.

• a new side panel will open and will show you a table with the offset of each selected record:

14 Chapter 1. Parts of the documentation:

OpenCobolIDE Documentation, Release 2.4.0-beta

1.3.7 Switching to a full dark style

Since version 2.2, OpenCobolIDE comes with a dark style sheet.

To activate it, open the preferences dialog (edit->preferences). Then go to the style page and click on the Dark styleradio button.

1.3. Getting started 15

OpenCobolIDE Documentation, Release 2.4.0-beta

Your IDE shoul look like that:

16 Chapter 1. Parts of the documentation:

OpenCobolIDE Documentation, Release 2.4.0-beta

1.4 FAQ

1.4.1 1) Where are the generated binaries?

The executable program or module can be found in the bin folder next to your source file

1.4.2 2) I cannot compile on Windows, the compiler freeze or I get a execution error.What can I do?

First ensure that you do not have a conflicting installation of MinGW in your PATH. If yes, remove it.

If the problem persists, do not hesitate to open an issue but OpenCobolIDE is known to work on Windows (from Xp,to 8). Chances are that the issue come from your configuration.

1.4.3 3) Cannot detect OpenCobol compiler on Mac OSX. What can I do?

If you installed the open cobol compiler in a non-standard path, you will have to tell OpenCobolIDE where to look.

1.4. FAQ 17

OpenCobolIDE Documentation, Release 2.4.0-beta

You can specify the path to the compiler in the preferences dialog (Build & Run tab).

1.4.4 4) Is it possible to install from source on Windows or Mac OSX?

Installation from source is possible on Mac and Windows:

• install all requirements (Python3, PyQt5, pyqode.core)

• run the open-cobol-ide script from the extracted archive or git repository without actually installing Open-CobolIDE. Do not run setup.py install on Windows or Mac OSX, it won’t work.

1.5 Contributing

OpenCobolIDE is an open-source project, and it needs your help to go on growing and improving.

You can contribute in many different ways:

• reports new bugs/features on the issue tracker

• fork the project and send pull requests to merge your work

If you have any question, just open an issue on the issue tracker.

1.5.1 Recommendation for submitting a bug report:

To submit a valuable bug report, the following information is required:

• Operating System

• Desktop Environment (for GNU/Linux only)

• Describe the way you installed the IDE (for GNU/Linux only): pip or apt-get or another method?

• Include the Application log output content (Menu->View->Application log->Show window)

1.5.2 Recommendation for submitting a Pull Request:

Pull Requests are great (on the dev branch)! Readme/Documentation changes are ok in the master branch.

• Fork the Repo on github.

• Push to your fork and submit a pull request to the dev branch.

The master branch is used for the stable releases, following the git workflow.

Please use PEP8 to style your code.

1.6 License

OpenCobolIDE is licensed under the GPL v3.

• What’s New? What’s new since the last release, and what is planned for the next one.• Download & Install Instructions on where and how to install pyQode.• Getting started Getting started with OpenCobolIDE• FAQ Frequently asked questions

18 Chapter 1. Parts of the documentation:

CHAPTER 2

Meta information:

• Contributing How to contribute and report bugs• License OpenCobolIDE license

19

OpenCobolIDE Documentation, Release 2.4.0-beta

20 Chapter 2. Meta information:

CHAPTER 3

Indices and tables:

• genindex

• search

21

OpenCobolIDE Documentation, Release 2.4.0-beta

22 Chapter 3. Indices and tables:

CHAPTER 4

Disclaimer

I am by no way a cobol expert, I just had to work on a cobol project at my night school with an awful IDE (NetExpresson a Windows Xp virtual machine).

As I was writing pyQode (a code editor widget for python qt applications), I thought it would be the perfect occasionto show what pyqode can do and write a simple and lightweight cobol IDE that I could run on my favorite Linuxdistribution

I’ve only learned COBOL 74 and the IDE has been designed with this standard in mind.

I have no plan on working with cobol at the moment nor to learn a new standard but if you found a missing feature,feel free to open a feature request.

I’m always looking forward to make OpenCobolIDE better. Your advice is needed and will be very appreciated!

23