Dynamic map title - finally got it

[Stefanie Weykam]

I already suspected that it had to be something stupid - a transcription
error! It turned out that I tried to draw the new feature just outside the
image extent, no wonder that I didn't see a thing. The more you look the
less you see.... Now I'm happy with my map title and will resume what I've
learned (thanks Steve, Eric and Sean):

The objective was to add a dynamic title to the map, with a fixed postion
but changing text string, according to the currently displayed theme.
I started with a default inline layer (type annotation) that looks like
this:

LAYER
     NAME       "subtitESP"
     STATUS     ON
     TRANSFORM  FALSE
     TYPE       ANNOTATION
     FEATURE
        POINTS  435 10  END
        TEXT    "Merops apiaster"
     END
     CLASS
         STYLE                  # optional
             COLOR    255 0 0
             MAXSIZE  300
             SYMBOL   'star'
             SIZE     8
         END
         LABEL
              TYPE      TRUETYPE #BITMAP
              FONT      verdana-italic
              SIZE      12
              POSITION  LL
              COLOR     160 90 0
         END
     END
 END
The point coordinates are image (not map) coordinates, since I do no
TRANSFORMation.
The STYLE part isn't really necesary - usually you don't want to show the
label point - but helps to check if the labelpoint is where you expect it to
be.

I am now going to change the text string using MapScript. Apparently it is
not possible to change the properties of a feature once it has been set. So,
I comment out the FEATURE part in the map file and add a new one using this
code (here simplified):

$subtitESP=$map->getLayerByName('subtitESP');
Create 3 new objects, a pointObj, a LineObj and a shpObj.:
$p=ms_newPointObj();
$l=ms_newLineObj();
$myshpObj=ms_NewShapeObj(MS_SHAPE_POINT);

Specify the point coordinates, set the point coordinates, add the point to
the line and the line to the shape object. Line is the only feature type
that can be added to a shapeObj, but it doesn't matter its just a point.
$p->setXY(435, 10);
$l->add($p);
$myshpObj->add($l);
$myshpObj->set("text", $specname);
$specname is the variable that holds the species name, my new map title.

The shape object is now ready to be added to the title layer.
$subtitESP->addFeature($myshpObj);

I finally draw the title-layer, the map and save everything as web image.
$subtitESP->draw($img);
$img=$map->draw();
$imgURL=$img->saveWebImage();