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 ten 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

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

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

The lift program has one hidden option, in stead of using

it is possible to use

If this mode is used with a "mydata.dat" input file, the seven output files will automagically be named

In other words, the input filename is prefixed with s-, l-, d-, t-, w-, m-, and n-, and the extension is replaced by h-h. If the default "lift.dat" is used, if is sufficient to run the program with just the "-a" parameter without filename.

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 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

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".

h-h2rtf

This program is a post-processor for lift. It reads the general summary, detailed summaries and tabulated trip files produced by lift and the columnar daily totals file produced dayform. It writes out all four of them in .rtf format, which is usable by many word-processing programs. The general summary undergoes the most extensive changes, all table-headings are bolded, and a number of large tables are split if they 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,

Like chkdat and dayform, 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

and for the output files

"trip.html" (currently) contains the following four 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:

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

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.

Additional files

Besides the ten 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.

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 suggest that you start by making your changes to the pure Pascal versions of the procedures, because

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

Subdirectory 'map'

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

Subdirectory 'batch'

Three batch files to compile all programs and a file to build the archives 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:

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 and dat2txt to convert the input into a very simple format that might have been useful for quick-and-dirty analysis of sorts. Further development of h-h2wiki has been suspended due to the inflexibility of "MediaWiki" markup, and dat2txt was never seriously used. Email me if you want copies of either of these two programs, but be aware that the last change to h-h2wiki dates back to 2016-08-15!

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 5 December 2018 with more information about the Pascal source code
Free counters!