Maketags: Making a TAG extension file for the ProWesS Basic Interface

Purpose

You will need this program if you have developped your own ProWesS type, and wish it to be accessible also from Basic. Normally, you will have made a header file containing the new tags to be used for your type, which you distribute with your type so that it can be called from other programs with these tags. For obvious reasons, header files cannot be used in Basic. If you have looked at the documentation that comes with the ProWesS Basic Interface, you will note that, for the built-in types, there is a function called PW which is used to obtain the value of a tag. For example, to obtain the value for the tag PW_TYPE_LAbBEL, the function PW('TYPE_LABEL') is used, and returns the numerical value corresponding to the tag.

If you make your own type with your own tags, there would be a slight problem for the Basic Programmer, since the tags for the new types will not be included in the ProWesS Basic Interface. This in turn would mean that you could not use the PW function for the tags for this new type. In short, the type couldn't be used from Basic.

Consequently, a scheme has been devised by which extension files for the ProWesS Basic Interface can be made available. These contain further tags and are linked into the ProWesS Basic Interface. After that, the new tags can be used with the PW command just like the built-in tags. It is presumed that the author of a new type (i.e. you) will make such an extension file and include it with the type and header file.

The Maketags program is intended to help you make such an extension file. It takes your header file(s) and extracts from them all #defines starting with PW_ and makes a result file which can be linked into the ProWesS Basic Interface.

Using the Program

The program is EXEC'd normally. You will generally pass it the name of a command file as parameter, eg. EX _maketags;"commandfilename". If you give it no command filename as parameter, the program interactively queries for one.

The command file is just a list line containing filenames:

There must be one line per filename. If a file cannot be found, it is searched for first in the current DATA dirctory, then the current program directory. If the output file cannot be created, it will be created on the current data default directory.

The program works in two passes, it creates an intermediary file on ram1_, which it deletes afterwards.

Example

I have created a new type called Pbar. Here is the extract of the makefile concerning this type:



type_pbar : type_pbar_o core-dll_o
        ${LD} -ms -otype_pbar type_pbar_o  \
        core-dll_o -lpw -lpf -lsms -sxmod
        mkxmod type_pbar \"ProWesS External Type Definition\"
        dcopy $C$@|dev1_prowess_pw_$@
        maketags pbartagscmd  ------ line for maketags
type_pbar_o : pbar_h

As you can see, the Make program calls upon Maketags, and passes it the string "pbartagscmd". This is interpreted as being the file pbartagscmd on the data default directory. (The datadefault is set to "dev1_prowess_src", which is where the source files for the type reside). The file pbartagscmd is the command file, and it contains the following lines:



pbar_extns
pbar_h


The first line is the result file, which will be "dev1_prowess_src_pbar_extns". The second line contains the (single) header file, "dev1_prowess_src_pbar_h".

Restrictions

Maketags is a rather stupid program. When parsing for the tags, it will only take into account tags which start with "PW_" and are defined with "#define". It cannot handle tags containing bits shifted up or down (such as the PW_TAGINFO_SKIP tag in the Prowess_h file). It does, however, correctly handle tags composed with PW_TAGMASK_STANDARD and PW_TAGMASK_MULTIPLE.

These restrictions should not be a problem, since you will probably make two (or more?) header files, one of which contains the tags with which your type can be accessed, and which will be distributed with it.

Loading the Extension file

The user must later load the extension file before being able to use the new tags. This is achieved with the LoadPWdefn keyword, which is explained in the ProWesS Basic Interface manual. You could do this in the boot file for your type, or invite the user to do it. You might consider including a paragraph such as the following with your manual/documention of the new type:

For the Basic Programmer, a file is included, called "your filename here". This contains all the necessary tags for the new type. This file must be loaded first with the LoadPWdefn keyword, as follows:

LoadPWdefn "your filename here"

Once the file is loaded in this way, the new tags are available from Basic with the PW keywords.



Wolfgang Lenerz
6, rue Daunou
77340 Pontault-Combault
France