Workbook for SLD Offline Users - Writing Code: Prepmort

To start learning Prepmort, take a look at a simple example of a Prepmort file. We will use the file that you called from IDA when you were learning about the EXTERNAL function. Use your editor to view the file

PRODSLD:UCHKTAG.PREPMORT

The Basic Structure of PREPMORT

The Prepmort file has three basic sections: the header section, the declarations section and the executable section. We'll discuss each of these three sections. First, a few general points:

Comments in Prepmort are enclosed by a pair of double quote marks, as in
```
     " This is a Comment "
```

A comment can extend over more than one line, as in

     " This is a comment that extends
             over two lines "

Column position has no significance (the Prepmort compiler removes all of the extra spaces before it does anything else). The indentation that you see is only there to make the files easier to read.
Entirely blank lines can appear anywhere. They have no significance (the Prepmort compiler removes them).
Case has no significance (the Prepmort compiler converts everything to upper case when it turns the code into Fortran). The only exception is that strings can have mixed case (for example, you can type out a mixed case message to the console).
Every statement other than a comment must end in a semicolon, as in
```
     DELTAG = -1;
```

Statements can extend over multiple lines, as in

     DIAG = SQRT( (XVALUE1 - XVALUE2)**2 + (YVALUE1 - YVALUE2) **2
                                         + (ZVALUE1 - ZVALUE2) **2 );

Strong typing is enforced. That is, all variables must be explicitly defined before they can be used. This enables the compiler to catch many spelling mistakes in your use of variables.

The Header Section

The header section of the UCHKTAG file is everything up to but not including:

   "&COMMON/JAZELL/"

Many lines in the header section are enclosed in Prepmort comment characters. However, some of these comment lines are actually used by the Prepmort compiler and the DUCS code distribution software. So do not assume that these lines can be left out.

Many of these comment lines are read by DUCS when the file is installed for use by the rest of the SLD collaboration. The lines contain information that DUCS turns into a help file. Thus every routine that contains a properly written header will automatically generate a help file when it is installed into DUCS.

The first line is a special comment line that contains the name of the routine. This line is used by DUCS to generate the help file.
The second line is the function declaration. Almost all routines in SLD are $SLD_INTEGER_FUNCTION. The declaration includes the name and type of all of the routine's arguments. In the current example, the integer function definition extends over four lines.
The long horizontal lines are separators used by DUCS to determine how to generate the help file. All files should have the same sequence of these long horizontal lines (failure to include them will not stop the file from working, but will stop the auotmatic help file from being generated).
A once sentance description of the purpose of the routine is given.
Then there is a longer series of comments in which it is good form to explain the function of the routine and the input and output arguments.
The KEYWORDS line is another special comment line used by the automatic help system. The applications that were meant to use these keywords were never implemented, so you can actually put whatever you want on this line. Just put in a few relevant words that people searching through files might use to find this particular file.
The next two special comment lines provide information that is used by DUCS to manage the file. They tell DUCS who is responsible for maintaining the file, what DUCS section the file should be included in, and the current file name. The last of these, the current file name, is not actually used for anything. But to avoid confusion, make it the same as the actual file name and make that the same as the routine name.
Finally, version information is given. It is traditional to increment the integer part of the version number when a major new release of a routine is made. For minor changes, increment the fractional part of the version number. Some writers forget to update these version numbers, so you may find cases in which the file is much more recent than the most recent version number. In such cases, you can assume that additional changes have been made but not documented.

When the file is installed into DUCS, a help file is generated. The help can be read by issuing the help command from DCL with the appropriate library specified. Separate help libraries are maintained for each DUCS section.

Since the file UCHKTAG.PREPMORT lives in section SLD, you can view it with the command:

   HELP/LIBRARY=DUCSSLD:SLD

As another example, you could view the help library for section MFIT:

   HELP/LIBRARY=DUCSMFIT:MFIT

The Declarations Section

The declarations section of the UCHKTAG file is everything from

   "&COMMON/JAZELL/"

through

   LOGICAL FIRST / .TRUE. /;

This part of the file declares what external code is to be included, what variables are to be used and what initial values these variables are to have.

The first line tells the Prepmort pre-compiler to include the Jazelle interface. This line is read even though it is enclosed in comment characters. This line can not have any spaces before it. It is, in that sense, different from any other kind of Prepmort statement. The general rule is, statements that begin with the two characters "& can not have spaces before them.
The next line declares some Jazelle pointers. F_MA_BEL and P_MA_BEL are both declared to be pointers to the Jazelle family MA_BEL. The comma in this statement allows you to declare more than one pointer with a single statement.
The same pointers could have been set up with a pair of statements:
```
     POINTER F_MA_BEL --> MA_BEL;
     POINTER P_MA_BEL --> MA_BEL;
```
As was mentioned earlier, any statement can stretch over multiple lines. The end of the statement is determined by the semicolon. The spaces have no significane; they are only there to make the code easy to read. A statement can stretch over up to 19 lines.
The next line declares the name of a routine that will be called by the UCHKTAG routine. How you do this declaration depends on what kind of routine will be called. Some examples are as follows:
- If the routine you are calling starts with $SLD_REAL_FUNCTION, declare it with a REAL statement. For example:
```
       REAL ULMASS;
  
```
- If the routine you are calling starts with $SLD_DOUBLE PRECISION_FUNCTION, declare it with a REAL statement. For example:
```
       REAL*8 JZS8;
  
```
- If the routine you are calling starts with $SLD_CHARACTER*(*)_FUNCTION, declare it with a CHARACTER statement. The CHARACTER statement requires an additional number to tell how long the string will be. Examples are:
```
       CHARACTER*8 JZC8;
       CHARACTER*80 JZC;
  
```
The next statment declares five integer variables. The middle three of them are arrays ten long. This could instead have been written as five separate statements:
```
     INTEGER PREVTAG;
     INTEGER SEVTAG;
     INTEGER SAVCTRAC(10);
     INTEGER SAVCTRIB(10);
     INTEGER I;
```
Or it could be written:
```
     INTEGER PREVTAG, SEVTAG, SAVCTRAC(10), SAVCTRIB(10), I;
```
Or they could have been grouped many other ways. You get the idea.
There is no real reason that this integer statement could not be joined to the one that declared the routine JZBLOC. That might have looked as follows:
```
     INTEGER JZBLOC, PREVTAG, SEVTAG, SAVCTRAC(10), SAVCTRIB(10), I;
```
In general, it keeps things more clear if you separate the function declarations from the variable declarations. But this is not required.
The arrays like SEVCTRAC(10) contain elements indexed from SEVCTRAC(1) to SEVCTRAC(10).
You also have the option of specifying your start and end indexes. For example, if you want the elements of SEVCTRAC to be indexed from SEVCTRAC(0) to SEVCTRAC(9):
```
     INTEGER SAVCTRAC(0:9);
```
The last statement declares a logical variable. The part of the statement between the slashes declares an initial value for the variable. All variables can have an initial value declared.
Be careful. If no initial value is declared, the variable will initially contain whatever value happens to be in the piece of memory that the computer allocates to that variable. This could make your routine behave differently depending on what order code is loaded in or on what order you run other unrelated functions.
To repeat: the offline sortware system will not initialize the variable unless you tell it to.

Other variable types are REAL*4, REAL (same as REAL*4), CHARACTER*8, CHARACTER* some other string size.

Here are some other examples of variable declarations:

     REAL    MCST(0:7),  "cos(theta) from hits"

     Integer Nmc, Nktag, I, Nhits, Iktag, IdKtag,
             Imc, Imcs, IdMc, IdMc0, Layer, McId, Adc,
             Igain(0:7)/1,1,2,2,2,2,3,3/;

     CHARACTER*9 VALSTRG / 'VALUATOR=' /;

     REAL XARRAY(8),
          YARRAY(8);

     Real*4 bPos(3)/0.,0.,0./ ;

The Executable Section

The rest of the file is called the executable section. This is the part of the code that is executed when the routine is called.

The UCHKTAG example starts with a very common construction called the "If First Block." This construction works together with the last declarations statement. Together, they create a section of code that will only be executed the first time the routine is called:
```
     LOGICAL FIRST / .TRUE. /;

     IF FIRST
     [
       $CALL JZBLOC( 'MA_BEL', F_MA_BEL ) ERROR RETURN;
       FIRST = .FALSE.;
     ]
```
The square brackets define blocks of code. Their use is self-explanatory.
Other offline software routines are called with the construction $CALL. We will talk about this particular called routine, JZBLOC a little later when we talk about calling Jazelle from Prepmort.
The $CALL, the parentheses and the ERROR RETURN are required for all calls to other Prepmort routines. The Prepmort pre-compiler turns this construction into a standard Fortran call plus some extra code that allows informational and error messages to be handled in a sophisiticated way. We will talk about this message handling later when we discuss the Signal system.
Inside the parentheses are the arguments. JZBLOC is a routine that finds the pointer to the head of a Jazelle family.
- The input in this case is the family name, the string 'MA_BEL'. Note how strings are delimited by single quotes.
- The output in this case is the pointer F_MA_BEL. This pointer was declared in the declarations section of this routine to be a pointer to a MA_BEL bank. JZBLOC sets this pointer to point to the zero MA_BEL bank, the head of the family.

A simple conditional construction follows:

     IF INIT .EQ. 1.
     [
       PREVTAG = 0;
       DO I = 1, 10 [  SAVTAG(I) = 0; ]
     ]

IF statements allow a large number of operators. In general there are at least two ways to write any operator. In the following chart, operators on the same line do the same thing:

     .GT.    >
     .GE.    >=
     .EQ.    =
     .LE.    <=
     .LT.    <
     .NE.    <>   ^=
     .AND.   &
     .OR.    |
     .NOT.   ^

DO statements are self-explanatory. And, unlike IDA, you can use the loop index outside of the loop. Thus, after the DO statement in the example, you can expect I to be 10.
The next statement obtains the pointer to the first MA_BEL bank. It does this by setting P_MA_BEL to be one bank forward from F_MA_BEL.
```
     P_MA_BEL = F_MA_BEL%(JB$FORPT);
```
In Jazelle, each bank contains the pointer to the next bank in its family. F_MA_BEL%(JB$FORPT) is this pointer (the FORPT comes from FORwards PoinTer).
This construction may look complicated, but there are actually very few such constructions that you will need to learn. For users who are already familiar with other pointer-based languages, such as C, this construction is nothing special.
Instead of using this IF FIRST construction and the JB$FORPT pointer, we could have obtained the pointer to the first bank directly by calling a different Jazelle routine,
```
     $CALL JZBFND( 'MA_BEL', P_MA_BEL ) ERROR RETURN;
```
This would mean that every time the routine UCHKTAGis called, it has to make a call to the routine JZBFND. Since UCHKTAG might get called a very large number of times, we chose to use the faster method. We only call to a Jazelle routine, JZBLOC, the first time that UCHKTAG is called. Every other time, we get away with a single assignment statement.
The next statement demonstrates use of a Jazelle variable from Prepmort. Since we have the pointer to the first MA_BEL bank in P_MA_BEL, we can get the variable TAG by the expression
```
     P_MA_BEL%(TAG)
```
The expression starts with the pointer, then has a percent sign, then has the variable name within parentheses.
Here are some examples of other Jazelle variables:
```
     P_MA_BEL%(CONTRACT)
     P_DSPWIND%(INTERLEV)
     P_KDGHIT%(HITS(J),TOWERID)
     PHPSUM%(X(3))
     PHCHRG%(HLXPAR(1))
```

Notice the IF...ELSE structure a little bit later.

     IF P_MA_BEL%(TAG) .EQ. SAVTAG(I)
     [
       IF    P_MA_BEL%(CONTRACT) .EQ. SAVCTRAC(I)
       .AND. P_MA_BEL%(CONTRIBU) .EQ. SAVCTRIB(I)
       [
         DUPLICAT = 1;
         EXIT;
       ]
       ELSE
       [
         SPLIT = 1;
         EXIT;
       ]
     ]

There is no THEN statement in Prepmort. The block structure defined by the square brackets makes this unnecessary.

The EXIT statement exists the nearest loop.
The rest of the routine is self-explanatory. Just note that all routines end with
```
     $RETURN;
     END;
```
The $RETURN is used along with the top line, $SLD_INTEGER_FUNCTION, to tie this routine to the other routines that call it. The Prepmort pre-compiler turns the $RETURN into a standard Fortran RETURN statement plus some sophisticated error handling code.
Fortran fans, note that there is no STOP in the routine. The STOP does not belong in any user routines.

Other Basic Prepmort Not in the Example

You have just seen one Prepmort routine in detail. Here are some other common Prepmort constructions that did not happen to be in the routine we used as our example.

A DATA statement can be used to assign an initial value to a variable. This has the same affect as the method we saw earlier in which the data was just appended to the end of the variable declaration statement. So you could replace:
```
     LOGICAL FIRST / .TRUE. /;
     INTEGER COUNT / 10. /;
```
with the following:
```
     LOGICAL FIRST;
     INTEGER COUNT;
     DATA FIRST / .TRUE. /,  COUNT / 10. /;
```

A PARAMETER statement is like a DATA statement except that the variable becomes an unchangeable parameter. The value can never be changed in the routine. The syntax is a little different from DATA.

     INTEGER MAXEVT;
     PARAMETER (MAXEVT=50);

Note that the variable must have been declared before the parameter statement.

A parameter can be used in later parts of the declaration section of the routine. For example, the routine VXWRCCD PREPMORT uses a parameter this way:

     integer  i,j,k,        "counters"
              bankid,
              hiloop,
              ndead;

     parameter (ndead = 38);

     integer dead(ndead) /53,
                          65,66,67,68,69,70,71,72,
                          105,106,107,108,109,110,111,112,
                          166,
                          201,202,203,204,205,206,207,208,
                          285,286,
                          316,
                          353,354,355,356,357,358,359,360,
                          365/;

     real effic(ndead) /95.,
                        50.,50.,50.,50.,50.,50.,50.,50.,
                        0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,
                        0.0,
                        0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,
                        0.0,75.,
                        20.,
                        0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,
                        0.0/;

Executable statements can have labels. These labels can then be referred to in GOTO, NEXT and EXIT statements. With proper use of square brackets and ELSE statements, you will not need statement labels very often. But here is how they work.
Any statement can have a label. Put the label at the beginning of the statement (as always with Prepmort, exact column position does not matter). The label can be any set of up to eight characters with colons on either side. For example, :TRACK:. Then put this label name after GOTO, NEXT or EXIT.
For example:
```
     :TRACK: DO I = 1, NTRACKS
     [
        DO J = 1, NHITS
        [
          ...
          ...
          IF BAD [ NEXT :TRACK:; ]
        ]
      ]
```
All standard Prepmort code runs on both DEC VMS and IBM VM systems. Occassionally, routines need to call functions that only work on one or the other of these sytems. For example, the routines to check the current time of day have different names and formats on the two systems. To handle this situation, Prepmort contains some special commands.
Code that is enclosed by the lines GENVAX and ENDVAX will only be run on DEC VMS systems (the VM version of the Prepmort compiler comments this code out).
Code that is enclosed by the lines GENIBM and ENDIBM will only be run on IBM VM systems (the VMS version of the Prepmort compiler comments this code out).
Edit the file PRODUTIL:UGTIME:PREPMORT to see how the routine that gets the current time uses this construction.

Back to Writing Code

Joseph Perl
27 February 1995