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 ask them on Prino's talk page.

The WinRAR archive that is used to distribute Prino's Programs currently contains the following nine programs and a few additional files:

General Information

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 six 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 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 six output files will automagically be named

In other words, the input filename is prefixed with s-, l-, d-, t-, w-, and m-, 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 : due to the, on occasion even for Prino, somewhat cryptic format of the input file used by , any input data that should be processed by should first be verified by .

The default name for the input file for is "newlift.dat", but as with 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 " 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 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 , generate an output file by replacing the extension of the input file into "h-c", i.e. if the program is invoked as " -imydays.in", it will write its output to "mydays.h-c".

h-h2rtf

This program is a post-processor for . It reads the general summary, detailed summaries and tabulated trip files produced by and the columnar daily totals file produced . 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 and , 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 , a post-processor for . It reads both the original input file for and the general and detailed summary files produced by , 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 :

In other words, 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 . It can be used to extract only the data for the last trip(s) from the detailed summary 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 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 " 41" would strip all data from the detailed summary and formatted input files that is unrelated to trips 41 and 42. does not touch the general summary and daily summary 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!

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 "" and the partner data will be written to "lift-alt.dat".

However, if you have several hitchhike partners (Prino has had six until now) and/or your raw data is in a differently named file, you need to invoke the program as " -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.

Additional files

Besides the nine programs, which have a renamed extension of ".ex" rather than ".exe" due to the fact that Google does not allow uploading executable files, 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 note that the source is (currently...) only sparsely commented, but feel free to ask for any clarification, should you need it.

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 not 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, , to convert some of the output into a format that can be used on Hitchwiki and to convert the input into a very simple format that might have been useful for quick-and-dirty analysis of sorts. Further development of has been suspended due to the inflexibility of "MediaWiki" markup, and was never seriously used. Email me if you want copies of either of these two programs.

Note 2: The (z/OS) PL/I version of 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.
Free counters!