User:Prino/pascal

From Hitchwiki

This is a short user-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:

Contents 1 General Information 2 lift 3 chkdat 4 dayform 5 h-h2rtf 6 h-h2wiki 7 newlift 8 dat2txt 9 dat2csv 10 get-aud 11 Additional files 11.1 gpl-3.0.txt 11.2 Subdirectory 'source' 11.3 Subdirectory 'map' 11.4 Subdirectory 'batch' 11.5 Subdirectory 'vpo'

General Information

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 input files are specified and/or generated.

lift

This is the main program and, unless overrides are specified, it produces the following four 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

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

chkdat

chkdat 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

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

h-h2rtf

This program 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,

• "summ.h-h", with an override of "-s<my-summary-file>"
• "lift.h-h", with an override of "-l<my-detail-file>"
• "days.h-h", with an override of "-d<my-columnar-daily-totals-file>"
• "trip.h-h", with an override of "-t<my-formatted-input-file>"

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

This program is, like h-h2rtf, a post-processor for lift. It reads both the original input file for lift and the general and detailed summary files produced by lift, and produces four (or more) files containing a mixture of "html" and "MediaWiki" markup.

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

• "trip.wiki",    with an override of "-t<viaje>"    (This file contains a sortable Wiki-table like Prino's per-trip summary)
• "country.wiki", with an override of "-c<pais>"     (This file contains a sortable Wiki-table like Prino's per-country summary)
• "month.wiki",   with an override of "-m<mes>"      (This file contains a sortable Wiki-table like Prino's per-month summary)
• "logYYYY.wiki", with an override of "-y<registro>" (These files contain the logs for every year present in the input file, like for example Prino's log for 2011)

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

Some important notes concerning h-h2wiki:

1. it expects the input file to be plain text, encoded in the rather ancient DOS code page 437. Using another single byte code page is possible, but it will require a change of the accented character to HTML-entity translation table. The program cannot handle UTF8 encoded data.
2. it is capable of translating single-byte high-ASCII characters to their corresponding HTML-entities
3. it isn't overly smart with regard to creating location links in the log-per-year files, it just brackets almost every location with [[ and ]], which is OK in probably 95% of all cases, but does not make a lot of sense for a location like M25 Junction 31, which should either be left as plain unlinked text, or possibly be converted to [[M25]] Junction 31.
4. it has a limited capability to add Wiki redirection links for links referring to Rest area's and Petrol stations

In other words, h-h2wiki will help you building log-per-year files, but a fair amount of manual post-processing is 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 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 in the detailed summary and formatted input files that is unrelated to trips 41 and 42. newlift 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

• "lift.dat", with an override of "-i<my-input-file>"
• "lift.h-h", with an override of "-l<my-detail-file>"
• "trip.h-h", with an override of "-t<my-formatted-input-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!

dat2txt

This program merely converts the input file to a simple text format, containing only basic data for every ride.

By default, the program reads "lift.dat" and writes out "lift.txt", but if it is invoked as "dat2txt mydata.text", it would write its output to "mydata.txt".

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

Additional files

Besides the nine programs, which have a renamed extension of ".ex" rather than ".exe" due to the fact that Yahoo! 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 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'

Two batch files to compile all programs.

• "ca-cmd.bat" - compile all sources with full debugging info
• "ca-opt.bat" - compile all sources with full optimisation

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.

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.