2018-08, Stig Rosenlund

About Rapp
I am a retired Swedish non-life insurance actuary with a Ph. D. in Mathematical Statistics. For my
work I created Rapp as a tool and I also let others use it free of charge.

To understand what Rapp does, see the Rapp package here: http://www.stigrosenlund.se/rapp.htm

Rapp is a programming language for non-life insurance actuaries. The basic program is Rapp.Exe with
variations. It is written in C. It is run essentially at the Command Prompt. No Windows interfaces
with menus, drop boxes, etc. are available in Rapp.Exe. Rapp reads plain text files with, among other
things, insurance versions, claims and map coordinate data. The output is text files, Excel files in
XML (text) format and Pdf files. The latter are created by first making a PostScript file, ie in text
format, and then using ps2pdf (included with MikTeX) to convert PostScript to Pdf. The user writes
Rapp programs in plain text files with a SAS-like syntax. By virtue of having only text files as input
and output, Rapp is extremely simple in a Windows-technical sense, but mathematically very complex. I
developed Rapp.Exe both before and after my retirement during 31 years up to now. It applies actuarial
methods that I have developed and published in scientific journals and also other methods.

A shell program above Rapp.Exe is Rappmenus.Exe. It is written in Visual Basic and includes Windows
interfaces. In the technical sense it is independent of Rapp.Exe and created entirely separately from
the latter. Logically it depends on Rapp.Exe to perform the desired operations at various menu
choices. It was developed only after my retirement. Rapp.Exe works without Rappmenus.Exe. The latter
can be used without Rapp in the menu "Mbasic - edit and run Mbasic or any Rapp-program." to edit any
file, but syntax coloring requires Rapp.Exe.

Rapp and Rappmenus are made completely by me alone, but I have of course used much free code in the
public domain, such as "Numerical Recipes in C" and StackOverflow.

Rapp and Rappmenus are used by quite many actuaries worldwide. Their expectation is that Rapp as Open
Source will survive me. The minimum goal of Rapp Open Source is that considerably more people than me
should be able to compile and link Rapp and adapt it to changing technical requirements. (Apart from
the XML syntax dependency mentioned below, I cannot now see what these requirements might be. Adapting
Rapp to 64-bit Windows was a tough job, but I do not see something like it in the foreseeable future.
Someone might want to adapt it to eg Linux, and that would of course be a challenge.) That more people
than I should be able to further develop the substance of Rapp would be a bonus, but is not absolutely
necessary.

Rapp and Rappmenus as Open Source
Versioning principle
Given a version number MAJOR.MINOR.PATCH, increment the:
  MAJOR version when you make incompatible API changes,
  MINOR version when you add functionality in a backwards-compatible manner, and
  PATCH version when you make backwards-compatible bug fixes.
When MAJOR is increased set MINOR = PATCH = 0. When MINOR is increased set PATCH = 0. No leading zeros
or embedded blanks. Start with lower case letter v.

Start: v1.0.0. Different for 32-bit and 64-bit Rapp?

Tagging versions
So users know which one they are using: Since Rapp.Exe has no Windows interfaces, the best way would
be to write it on the screen at command Rapp /? before usage information. In Rappmenus.Exe simply
write it in as a label in the start menu.

Definition of API for Rapp v1.0.0 - dependencies
Windows XP or later.
Microsoft Excel xml version 1.0.
Ps2pdf or Acrobat Distiller
Microsoft .NET (needed for Rappmenus only)

Besides Windows a program for converting PostScript to Pdf is needed. Ps2pdf in MikTeX or Adobe
Acrobat Distiller can be used. For the XML files that Rapp produces to be able to open in Excel, the
XML syntax that Rapp presupposes must be correct. I have put an instruction for a limited adaption by
end-users to changed such syntax in the manual, but some work might have to be done with the Rapp
source code in the event that Microsoft changes the syntax substantially.

Installing MikTeX
The following is given in the end-user documentation. Google miktex. The Basic Installer is
sufficient. At present you can use http://miktex.org/2.9/setup">http://miktex.org/2.9/setup. Choose
64-bit for a 64-bit computer.

Getting Excel to open XML files
The default opening program for XML files might not be excel.exe. If so, search ecxel.exe with Windows
Explorer in the root, note its location, right-click an XML file for Open with, and go to excel.exe.

A possible new Rapp which would not work under this API would start with MAJOR = 2. The first such
Rapp would be v2.0.0.

Developing Rapp and Rappmenus
My editor software is SPF from CTC (Command Technology Corporation). I use it for almost everything -
C programs, Rapp programs, LaTeX, HTML, documents. The documents I paste into Word at the end, if
appropriate. It takes some time to master it. Other developers might prefer other editors. Notepad is
possible.

I do not use any graphical shell for the compilation and linking of Rapp.Exe - I do everything at the
Command Prompt. I do not find the graphical shell IDE (Integrated Developer Environment) useful for
fixing bugs, partly because I haven't taken the time to understand its debugging tools. Instead I
insert in test files diag.c in various places where a bug might show itself, such as leading to a
crash. The section between the last point that is shown by diag.c och the first point not shown
is the place to look for the cause of a crash.

For Rappmenus.Exe in Visual Basic (in Visual Studio Community 2017), I use Microsoft's menu interface.
Google Visual Studio for free download!

Download and install Microsoft Visual C++ Build package for the Command Prompt from 2017. I have tried
the Intel C compiler, but it gave slower execution of Rapp.Exe. I have been told that other compilers
also give slower execution of the things that Rapp do.

Folders
Ckod. Directly below are bat files for compiling and linking, the main-program Rapp.C and some
other examples of C main-programs. Only C, not C++ programs.
Subfolders in Ckod.
Chead. Header files. All are not needed for Rapp.
Cfuncs. Functions not main(). All are not needed for Rapp. Some files contain more than one function.
Release, Releasex, Releaset, Release32. Folders where the object modules for four
   differentfunction and Rapp compilations are added.
Rappmenus. Visual Basic project for my graphical shell Rappmenus.Exe on top of Rapp's basic program.

Add Ckod directly under the root in C.

Add Rappmenus as subfolder of the folder you are steered to at download of Visual Basic. For me it is
C:\Users\S\Documents\Visual Studio 2017\Projects. (S is my user.)

For use without modification of the bat files for compiling and linking, make an empty folder C:\Rapp
and under it C:\Rapp\Pgm.

Four different exe files for Rapp's basic program
All are created from Rapp.c and the lib files that are made with Cflalla.Bat, see below.

Rapp.Exe - the exe an end-user with a 64-bit computer shall use
Properties
64-bit. Rapp.c takes a long time to compile and link, about 8 minutes with a fast computer, but executes faster than the rest.
    Compiling the functions into CFLIB.LIB takes short time.
Associated bat programs
Cc.Bat     compiles and links main programs.
Cfl.Exe    compiles a function in Cfuncs and puts it into CFLIB.LIB. Source code Cfl.c.
Cflall.Bat executes Cfl.Exe for all functions.

Rappx.Exe - for developers' tests
Properties
64-bit. Rapp.c takes short time to compile and link, but executes more slowly than Rapp.Exe.
    Compiling the functions into CFLIBx.LIB takes longer than for CFLIB.LIB. The difference is
    noticeable for the large function files. The largest one is Cfuncs\jungfu.c. It is named after Jan
    Jung (1922-2005) who introduced the MMT method of tariff analysis in Sweden.
Associated bat programs
Ccx.Bat     compiles and links main programs.
Cflx.Exe    compiles a function in Cfuncs and puts it into CFLIBx.LIB. Source code Cflx.c.
Cflxall.Bat executes Cflx.Exe for all functions.

Rappt.Exe - for developers' leak detection
Properties
As Rappx.Exe but creates a number of files that log memory usage. Assumes that the folder C:\Ckod exists.
Associated bat programs
Cct.Bat     compiles and links main programs.
Cflt.Exe    compiles a function in Cfuncs and puts it into CFLIBt.LIB. Source code Cflt.c.
Cfltall.Bat executes Cflt.Exe for all functions.
To determine if memory leaks exist, and if so where, you use Leaktrace.Exe that youcreate from
  Leaktrace.c with Cc.Bat. Leaktr.Bat runs Leaktrace.Exe under the proviso thatlog files landed in
  C:\Ckod.

Rapp32Vc2017.Exe - the exe an end-user with a 32-bit computer shall use
Properties
32-bit. Takes a relatively long time to compile and link.
Associated bat programs
Cc32.Bat     compiles and links main programs.
Cfl32.Exe    compiles a function in Cfuncs and puts it into CFLIB32.LIB. Source code Cfl32.c.
Cfl32all.Bat executes Cfl32.Exe for all functions.

Making executables
1. The right environment
Place B.Bat and Bc.Bat in the folder you come to at entrance to the Command Prompt. In my computer it is
C:\Users\S. I added a shortcut to the Command Prompt in the start menu to avoid going through All
Programs / Accessories. At the Command Prompt, type Bc for 64-bit and Bc 32 to 32 bits.

To just get to C:\Ckod without creating a compile and link environment, use B.Bat.

2. Compile function files and create the lib files for C functions with the .bat files in Ckod
Create new lib files for all four exes with Cflalla.Bat. Object modules are intermediately stored in
the folders starting with Release. If all object modules in Release, Releasex, Releaset and Release32
exist, run with Cflalla Noc. Parameter Noc is case independent. It means no compilation. It takes a
few minutes. Without Noc all functions are compiled and the object modules are created anew. This
takes in 2015 approximately 40 minutes with my fast computer. For a slower computer, count on up to
two hours. Lib files have names that begin with CFLIB. There are no lib files in Ckod here - they must
be created new.

Create or replace an object module with
Newcfl name-excl-extent
for the files of Cfuncs. The CFLIB*.LIB are updated also. Any number of name-excl-extent's can be given.

If a function is added, enter it in Cflall.Bat, Cflxall.Bat, Cfltall.Bat and Cfl32all.Bat.

Sometimes I want to take away or give a function file a new name. Then I remove the function file name
from Cflall.Bat, Cflxall.Bat, Cfltall.Bat and Cfl32all.Bat. As a matter of order I also remove its
object module. After that I recreate the lib files anew with Cflalla Noc. Then I use Newcfl with the
new name if appropriate, after which I enter the name in Cflall.Bat, Cflxall.Bat, Cfltall.Bat and
Cfl32all.Bat. There is a way to remove object modules from a lib file, but it has given me trouble.

3. Compile and link a C program with main()
Create 64-bit executable with sometimes slow compilation but fast code:
Cc sourcename-excl-extent [executable-exe-excl-extent]

where executable-exe-excl-extent becomes the name of the executable excluding .exe. If omitted you get
executable-exe-excl-extent = sourcename-excl-extent.

Example: Creating Rapp.Exe from Rapp.c and previously compiled functions
Cc Rapp

Create Rappxx.Exe from Rapp.c with
Ccx Rapp Rappxx

For 32-bit use Cc32 like Cc.

For quick compilation but somewhat (hardly noticeable) slower finished exe there is the variant Ccx.
For leakage trace, see CCt.Bat above. For another program than Rapp, you have to insert code as in
Rapp.c. Search leak in Rapp.c and you will understand how.

I have in Newrapp.Bat collected the commands that use the above .bat files to create Rapp. The 32-bit
version then gets the name Rapp32Vc2015.Exe. It takes quite a long time, about 5-10 minutes depending
on how fast your PC is.

4. Test out functions for use in Rapp
If I, for example, develop the function matrixfu.c in Cfuncs, then I make matrixfun.c. Then I copy it
to a garbage test file Cfuncs\a1.c. (I follow the principle that files a1.*, a2* etc are for test and
always can be deleted.) Then I create z1.Exe (64-bit) with this command: 
    Trapp a1

If the compilation goes through and z1.Exe produces the desired results, then I replace matrixfu.c
with matrixfun.c. If several new functions are to be tested, then more arguments are given to Trapp,
eg Trapp a1 a2 a3. Trapp.Bat uses Cklcx.Bat, where all optimizations have been removed for very fast
compilation and linking. One can make variations of Trapp.Bat for other main-programs.

For leak detection Tratt.Bat is used in the same way.

5. Test out functions for use in any C main program
Use Sn.Bat. Syntax:
  Sn sourcefile exename [function [function ... ]]

Example:
  Sn Rapp z1 a1 a2 a3 a4
Makes C:\Ckod\z1.exe from C:\Ckod\Rapp.c with the functions in C:\Ckod\Cfuncs\a1.c,
C:\Ckod\Cfuncs\a2.c, C:\Ckod\Cfuncs\a3.c and C:\Ckod\Cfuncs\a4.c as input.

Making executables for multiprecision computing
Rapp / Proc Mbasic handles up to 306 decimal digits. To make a series of exe files with other maximums
for the number of decimal digits, execute B.bat and run C:\Ckod\Mbasicvar.bat. This takes 30-60
minutes, except for the first time when no function obj files for different maximum digits exist. The
first time will take many hours, about 3-4 on a fast computer. These other exes are only for 64 bit,
since multiprecision computing is so advanced that someone who does that can certainly be expected to
have a 64 bit computer. You can make the ordinary exe files at the same time with C:\Ckod\rappall.bat.
Special exe files Mplang*.Exe, which only run Mbasic programs, are also made with C:\Ckod\rappall.bat.
After having eg corrected a bug in some function and run Newcfl on it, run C:\Ckod\rappall.bat for all
exes.

See http://www.stigrosenlund.se/rappzip.htm for a description of these executables.

Rappmenus.Exe
It is made in Visual Basic's IDE. To help, I made some C programs with names that start with Vb. They
are run at the Command Prompt. Read the source code to understand them.

How to contribute
Developing existing features can be difficult. In contrast, it should not be that difficult to create
a new proc. Search Rapp.c for a sequence of strings that begins with "ACCTRA","ALARM","BICH". To make
a new proc, find a good name, preferably with a maximum of six characters. Add it into the string
sequence, preferably in alphabetical order. Find a place where a proc is triggered, for example, the
lines

    //*****************************************
    else if (strjfrv(procnamn,"GPDML") == 0) {
      // Format Proc Gpdml Infil() Utfil() Endproc.
      *tmp01 = *tmp02 = 0;
      dbpars(tmp01,257,strstrv(procrad," Infil("),3);
      dbpars(tmp02,257,strstrv(procrad," Utfil("),3);
      if (*tmp01 == 0 || *tmp02 == 0) {
        printf("Proc Gpdml: Infil() and Utfil() must be given!\n");
        goto FELSLUT1;
      }
      retc = gpdml(tmp01,tmp02);
      if (retc != 0) goto FELSLUT1;
    }
    //*****************************************

Study that code snippet and those of other procs. See the source code files Cfuncs\dbpars.c,
Cfuncs\strstrv.c etc how those functions allow Rapp to read the user's parameters and send it to the
appropriate functions, or sometimes perform the desired operation directly in Rapp.c. If you have a
function taking some user parameters and text files as input, I can help making the code snippet.
(This proc does maximum likelihood estimation in the Generalized Pareto model. The time to run it is
3.5 % of the time to run an algorithm for the same purpose in Python.)

When a snippet and needed new functions have been tested out, the snippet can be inserted in Rapp.c in
the right place alphabetically and the functions can be inserted into the lib files and written into
Cflall.Bat, Cflxall.Bat, Cfltall.Bat and Cfl32all.Bat. Declarations of them are put in
Chead\rappdef.h.

Notes
1. Cflalla.Bat, and the .bat files that start with New, create log files telling if all went well.
   They exit the Command Prompt when finished, so as not to create confusion about the environment in
   which you are. The initial environment does not matter to them. You can start with B.Bat. Others
   require the right environment with Bc respectively Bc 32.

2. There is a lot of documentation in Swedish in comments in the source code. Use Google translate!
   Forgive me if the translation sometimes is hard to understand, but it would take me too long to
   translate everything to English.

