A manual for Prino’s hitchhiking programs

This is a short manual for Prino’s hitchhike statistics programs. It is pretty complete, but if, after reading, you still have questions, feel free to send me an email.

The WinRAR archive that is used to distribute “Prino’s Programs” currently contains the following eleven programs and a few additional files:

General information

The archive is password encoded to allow the inclusion of .EXE files. The password is “lift”.

All programs in the above archive share a small set of common command line switches. These are

“-?”, “-h”, “--help”, to display a help screen
“-V”, “--version”, to display the version of the program

Invoking the programs with any of these switches will terminate the program with a returncode of 1 after the help or version has been displayed.

They also share the fact that they will terminate with a returncode of 16, an unrecoverable error in z/OS parlance, when duplicate output files are specified and/or generated, but detection of this condition is pretty basic and not at all fool-proof!

lift

This is the main program and, unless overrides are specified, it produces the following seven files

“summ.h-h” - a general summary
“lift.h-h” - summaries per trip, type (of driver/vehicle), country, nationality, and year
“days.h-h” - totals per day
“trip.h-h” - tabulated print of input file
“week.h-h” - distance per weekday per year file
“mnth.h-h” - distance per month per year file
“ntop.h-h” - top-n tables for distance, time and velocity, in-full, and per trip, type, country, nationality, and year

The contents of the output files is described in Keeping statistics, which also contains a description of the somewhat cryptic format of the input file.

The default name for the input file is “lift.dat”, but all input and output file names can be overridden using command line switches. To override

“lift.dat”, use “-i<my-input-file>”
“summ.h-h”, use “-s<my-summary-file>”
“lift.h-h”, use “-l<my-detail-file>”
“days.h-h”, use “-d<my-daily-totals-file>”
“trip.h-h”, use “-t<my-formatted-input-file>”
“week.h-h”, use “-w<my-per-weekday-per-year-file>”
“mnth.h-h”, use “-m<my-per-month-per-year-file>”
“ntop.h-h”, use “-n<my-top-n-file>”

But…

lift can actually generate an additional eight file, “xtra.h-h”. which currently contains two tables of “firsts”. To do so, the program must be invoked with “-x” command line switch, that may be empty, or contain an output filename override.

chkdat

This program is a pre-processor for lift: due to the, on occasion even for Prino, somewhat cryptic format of the input file used by lift, any input data that should be processed by lift should first be verified by chkdat.

The default name for the input file for chkdat is “newlift.dat”, but as with lift this can be overridden by invoking the program with a file name as the first argument. The name of the output file will be derived from the name of the input file by changing the extension into “out”, i.e. if the program is invoked as “chkdat mynewdata.in”, it will write its output to “mynewdata.out”. The latter will contain a list of most, but not (yet) all, problems encountered while verifying the input file.

dayform

This is a program to reformat the single long table contained in the totals-per-day file produced by lift into a multi-columnar format. It also sorts the original table, which is sorted on date, in three other orders, distance-per-day, time-per-day, and velocity-per-day and adds these tables to the output file.

The default name for the input file is “days.h-h”, the default name for the output file is “days.h-c”, but both names can be overridden using command line switches. To override

“days.h-h”, use “-i<my-daily-totals-file>”
“days.h-c”, use “-o<my-columnar-daily-totals-file>”

If only an override for the input is specified, the program will, like chkdat, generate an output file by replacing the extension of the input file into “h-c”, i.e. if the program is invoked as “dayform -imydays.in”, it will write its output to “mydays.h-c”.

mnthform

This is a program to post-process the totals-per-month file produced by lift. It

merges the the four split-up tables with monthly data, and
reformats the single long table into a multi-columnar format. It also sorts the original long totals-per-month table, which is sorted on date, in four other orders, days, distance-per-day, time-per-day, and velocity-per-day and adds these tables to the output file.
The table is also sorted and split in five varieties of “Per Month” tables,
1. days per month,
2. distance per month,
3. time per month,
4. velocity per month, and
5. average distance per day per month.

The default name for the input file is “mnth.h-h”, the default name for the output file is “mnth.h-c”, but both names can be overridden using command line switches. To override

“mnth.h-h”, use “-i<my-monthly-totals-file>”
“mnth.h-c”, use “-o<my-columnar-monthly-totals-file>”

If only an override for the input is specified, the program will, like dayform, generate an output file by replacing the extension of the input file into “h-c”, i.e. if the program is invoked as “mnthform -imymonths.in”, it will write its output to “mymonths.h‑c”.

h-h2rtf

This program is a post-processor for lift. It reads the general summary, detailed summaries, tabulated trip file, and top-nn files produced by lift, the columnar daily totals file produced dayform, and the merged and columnar monthly files produced by mnthform. It writes out all seven of them in .rtf format, which is usable by many word-processing programs.

The conversion “bolds” all table-headings, and, for a few tables, values in the first column. The program also splits some tables that would overflow an A4 sized page. However, pagination still needs additional work, the program is, as yet, incapable of re-paginating pages that contain two (or more) tables whose combined size overflows an A4 size page.

The default names for the files read and generated by the program, and the command line switches to override these names are,

“summ.h-h”, with an override of “-s<my-summary-file>”
“lift.h-h”, with an override of “-l<my-detail-file>”
“days.h-c”, with an override of “-d<my-columnar-daily-totals-file>”
“mnth.h-c”, with an override of “-d<my-monthly-totals-file>”
“trip.h-h”, with an override of “-t<my-formatted-input-file>”
“week.h-h”, with an override of “-w<my-weekly-file>”
“mnth.h-h”, with an override of “-m<my-monthly-file>”
“ntop.h-h”, with an override of “-n<my-top-n-file>”

Like chkdat, dayform, and mnthform,the corresponding output files are generated by replacing the extension of these files by “rtf”.

The program produces two additional files, currently using hard-coded names, “stab.rtf” and “stay.rtf”, containing the two main summary tables of totals per trip and totals per year from the general summary file, sorted in the ten possible orders that these tables can be sorted in.

h-h2html

This program is, like h-h2rtf, a post-processor for lift. It reads both the original input file for and the general and detailed summary files produced by lift, and produces three (or more) .html files, that are directly usable on your website, provided you copy the style.css file used by Prino.

The default names for the files read and generated by the program, and their command line switches to override these names are, for the input files

“lift.dat”, with an override of “-i<my-input-file> ”
“summ.h-h”, with an override of “-s<my-summary-file>”
“lift.h-h”, with an override of “-l<my-detail-file>”

and for the output files

“summary.html”, with an override of “-u<my-summary-out-file>”
“log[YYYY].html”, with an override of “-y<my-log-out-file>”

“summary.html” (currently) contains the following five sortable tables:

the “log[YYYY].html” is made up of (at least) two files, “log.html” and “logYYYY.html”:

Note that it is not necessary to add an extension, the program will always add an extension of “html” to the specified names, and the -y override will only be used as a prefix, so “-yblurb” will result in per-year logfiles named “blurbYYYY.html”.

Some important notes concerning h-h2html:

the program generates html files containing “<meta charset="UTF-8">” tags, so departure and arrival locations must be encoded in either pure ASCII, or UTF-8! Using Windows character sets for accented characters will result in oodles of useless “�” characters!
Another restriction on the departure and arrival locations is their length. At the moment the physical length of these locations is limited to 47 bytes, which means that,
“jct Thessaloniki-Yugoslavia”

to give an example of a location used several times by Prino, cannot be entered in UTF-8 in the “normal” departure or arrival locations, as its UTF-8 equivalent,
“jct Θεσσαλονίκη - Γιουγκοσλαβία”

requires 55 bytes!
Finally, when using UTF-8 encoded characters in the “normal” departure or arrival locations, the comma separating the departure and arrival locations must be located in physical(!) column 153, which means that you may temporarily have to change the encoding of the text in your editor to “ANSI” or a single-byte codepage, like 437 or 850.
the “log.html” file only contains the departure location of the first ride of a trip and the arrival location of the last ride. The above linked-to page has been manually changed to include additional intermediate data.
the program can handle breaks, such as a walk or use of public transport from one arrival location to a new departure location. To do so, use must be made of “{I x” meta-tags. The program can currently handle four specific tags,
1. “{I W”, for a walk,
 using this tag will insert a “Walk” into the “logYYYY.html” file.
2. “{I I”, for unspecified idle time,
 using this tag will insert a “Non-hitching time” into the “logYYYY.html” file.
3. “{I F”, for a departure after a ferry-crossing,
 using this tag will insert a “Ferry” into the “logYYYY.html” file.
4. “{I N {bus|train|whatever}”, for use of other transport between arrival and departure. The tag must be followed by a single blank followed by the means of transport,
 using this tag will insert a “{bus|train|whatever}” into the “logYYYY.html” file.
and one generic tag,
1. “{I * lorum ipsum…”
 where the text is literally inserted into the “logYYYY.html” file. The text can contain anything, from just a simple
 “{I * Took a break”
 to something actually containing html, like:
 “{I * Ferry - Greece (No hitching) - Ferry”
All “{I x“ meta-tags must be coded after the first line of the ride with a changed departure location!
Note: If the program detects that the departure location of $r i d e_{n + 1}$ is not equal to the arrival location of
$r i d e_{n}$ , and there is no “{I x” meta-tag coded, it inserts a “?-?-?” into the “logYYYY.html” file.

In other words, h-h2html will help you building log(-per-year) files, but a fair amount of manual post-processing might be required.

newlift

This program is another post-processor for lift. It can be used to extract only the data for the last trip(s) from the detailed summary, the file with Top-n tables, and formatted input files. If the default filenames are used, it requires a single command line argument, the number of the trip from where extraction should begin.

As an example, if the input file for lift contains the data for 42 trips, and you are only interested in printing the new data that comes from adding trips 41 and 42, the command “newlift 41” would strip all data from the detailed summary, the Top-n, and formatted input files that is unrelated to trips 41 and 42. newlift does not touch any of the other files.

The default names for the files read by the program, and their command line switches to override these names are

“lift.dat”, with an override of “-i<my-input-file>”
“lift.h-h”, with an override of “-l<my-detail-file>”
“ntop.h-h”, with an override of “-n<my-top-nn-file>”
“trip.h-h”, with an override of “-t<my-formatted-file>”

If overrides are used, it is essential that the number of the first trip to be extracted is supplied as the first command line argument!

dat2csv

This program converts the input file to a comma-separated text file, that can be loaded in most, if not all, spreadsheet programs.

By default, the program reads “lift.dat” and writes out “lift.csv”, but if it is invoked as “dat2csv tripdata.log”, it would write its output to “tripdata.csv”.

get-aud

This program allows embedding data from a second(/third/fourth/etc) hitchhiker in the input file, provided the data is a true subset of the main data. The presence of such data is indicated by special meta-data in the input file.

In the case that you always travel with the same partner and use the default “lift.dat” filename for your raw data, the invocation of the program is rather straight-forward, it’s just “get-aud” and the partner data will be written to “lift-alt.dat”.

However, if you have several hitchhike partners (Prino has had seven until now) and/or your raw data is in a differently named file, you need to invoke the program as “get-aud -iyour-input-file -xname-of-partner”. Note that “name-of-partner” must exactly match the name in the meta-data, including capitalisation! If the “-x” option is used, the output of the program will be written to a file named “name-of-partner.dat”.

box2txt

This program converts the “*.h-h” output files from lift from the original IBM PC codepage 437 (using the box character set) into pure ASCII text, replacing the box characters with “+”, “-” and “|” characters.

The program accepts one parameter, a filename, converts all box characters in this file and overwrites the input file with the changed data.

Note: To convert the box characters in, assuming default names for all files are used, ntop.h-h from codepage 437 into ASCII, the program must be invoked as “box2txt -untop.h-h” as there are UTF-8 encoded characters that might otherwise be confused with box characters!

datsplit

This program splits “lift.dat” into separate “trnnn.dat” and “yrnnnn.dat” files, that can be used to produce (more) specific per-trip and/or per-year files out of lift.

A well-kept secret, the “-a” option

Four of the above programs, lift, dayform, mnthform, and h-h2rtf have an additional command-line option that is not mentioned in the displayed help screen. That option is “-a[filename.ext]”, where “filename.ext” is the name of the input file for lift! And yes, the above means that dayform, mnthform, and h-h2rtf also need to be run with the name of the input file for lift! Prino added it to facilitate running these programs with multiple (read: separate trip(s) and/or year(s)) input files in a way that does not require long command-lines to specify the multiple in- and output files.

The result of using this option, assuming that the input file is called “hitching.dat”, is that for

lift -ahitching.dat

the seven output files will automagically be named

“s-hitching.h-h”
“l-hitching.h-h”
“d-hitching.h-h”
“t-hitching.h-h”
“w-hitching.h-h”
“m-hitching.h-h”
“n-hitching.h-h”

dayform -ahitching.dat

the input file will be assumed to be “d-hitching.h-h”
the output file will be named “d-hitching.h-c”

mnthform -ahitching.dat

the input file will be assumed to be “m-hitching.h-h”
the output file will be named “m-hitching.h-c”

h-h2rtf -ahitching.dat

the seven input files will be assumed to be

“s-hitching.h-h”
“l-hitching.h-h”
“d-hitching.h-c”
“t-hitching.h-h”
“w-hitching.h-h”
“m-hitching.h-c”
“n-hitching.h-h”

and the nine output files will automagically be named

“s-hitching.rtf”
“l-hitching.rtf”
“d-hitching.rtf”
“t-hitching.rtf”
“w-hitching.rtf”
“m-hitching.rtf”
“n-hitching.rtf”
“b-hitching.rtf”
“y-hitching.rtf”

… and the “-x” option

To use the “-x” option in combination with the “-a” option, the program(s) to which it applies must be invoked with “program -x -a”, that is the “-x” command line switch must precede the “-a” switch!

Additional files

Besides the eleven programs, the archive also contains the following (sets of) files:

gpl-3.0.txt

The text of the General Public Licence Version 3.0, all programs are released under the terms of this license, which means, in a simplified nutshell, that if you make changes to them and make them available to others, you must also make the changed sources available. (And Prino would like to have a copy of the changed versions anyway!)

Subdirectory ‘source’

A subdirectory containing the full source of the programs.

Please be aware that the source is (currently…) only sparsely commented, but feel free to ask for any clarification, should you need it. Also, if you want to start hacking it, because you do not need this, that, or any other table, I would suggest very strongly that you start by making your changes to the pure Pascal versions of the procedures, because

Virtually every procedure and function in lift (and most in the other programs) comes in two versions:

a version written in nice readable Pascal, and
a version that performs the same as the Pascal version, but has been converted into hand optimized in-line assembler, going as far as using long series of "db"’s to code instructions that require CPUs that are a few generations younger than the Pentium, the last CPU supported by Virtual Pascal. The instructions themselves are included as comments, the "db" sequences were generated by the Online x86 / x64 Assembler and Disassembler. Note that many of them will confuse the VP IDE and make Single-Stepping impossible unless you enter a breakpoint directly after them!

Subdirectory ‘map’

All .map files resulting from the compilations. Included for completeness sake.

Subdirectory ‘batch’

Two REXX execs, which implies that you will need to install Regina REXX, or, untested(!), Open Object Rexx:

“ca-opt.rex” - compile all sources with full optimisation (using inline assembler)
“ca-pas.rex” - compile all sources with full optimisation (using only Pascal)

A batch files to compile all programs with full debugging support, and a batch file to build the archives to be uploaded to Google

“ca-cmd.bat” - compile all sources with full debugging info
“make-google.bat” - build all files to be uploaded to Google

Subdirectory ‘vpo’

The .vpo (Virtual Pascal Options) files for all programs. Please note that these files do depend on the directory structure used by Prino, so it’s pretty likely that they need to be changed, the sections to look at are [Directories] and [Binaries], it’s probably best to delete all text after the latter of these two headings as it’s (virtually) impossible to edit the hexadecimal data. There are three types of .vpo files:

“xxxxx.vpo” - full debugging
“oxxxxx.vpo” - using inline assembler
“pxxxxx.vpo” - using only Pascal

Final notes

Note 1: The archive used to contain two additional programs,

h-h2wiki to convert some of the output into a format that could be used on hitchwiki.
Development of h-h2wiki has been permanently suspended since 2016-08-15 due to the inflexibility of the “MediaWiki” markup
dat2txt to convert the input into a very simple format that might have been useful for quick-and-dirty analysis of sorts. It converts the data in “lift.dat” to extremely summarised data
1. the trip number,
2. the ride number,
3. the duration of the ride,
4. the distance of the ride,
5. the velocity of thge ride,
6. the nationality of the driver,
7. the type of driver, and
8. the wait before the ride
in a fixed-format text file.

Email me if you want copies of either of these two programs, but be aware that they come without any support, dat2txt still runs OK, but h-h2wiki has not been used since Prino moved his data from some wiki in the final months of 2016, due to the unpalatable attitude of some of the (way too many for security purposes) “bureaucrat” and “administrator” types, including one who uses the site as a testbed for commercial ventures!

Note 2: The (z/OS) PL/I version of lift is no longer included in the archive as it’s unlikely to be of interest to most users. However, it is available on request, together with compile, link and run JCL.

Last updated on 27 November 2022 (Remove direct link to Google Drive)