Storing Names in a Group

There are several routines which can be used to store names in a group.

The routine GRP_PUT stores a set of names starting at a given index within a group. Any previous names with the same indices are over-written, and the group is extended as necessary. Note, an application must supply the literal names to be stored, as modification and indirection elements cannot be used with GRP_PUT. For instance, if the string ``^LIST.DAT'' was stored in a group using GRP_PUT, the ^ character would not cause names to be read from the file LIST.DAT. Instead the string would be stored in the group exactly as supplied.

The routine GRP_PUT1 is like GRP_PUT except that it stores just a single name, and so has a simpler interface.

The routine GRP_GROUP obtains a group expression from the environment using a specified parameter and expands it into a list of literal names. These names are appended to the end of a group, which must previously have been created. An existing group may be specified as the basis group for any modification elements included in the group expression. If such a group is not supplied, all elements are stored literally as names. GRP_GROUP returns the total number of names in the group, together with the number of names which it has added. It also returns a logical argument indicating if the group expression was ``flagged'' (see section ).

The routine GRP_GRPEX performs the same function as GRP_GROUP except that the group expression is supplied as an argument instead of being obtained through the parameter system. This routine can thus be used in stand-alone applications.

The following code fragment shows an example of the use of GRP_GRPEX and GRP_PUT. It is assumed that the text file FRIENDS.LIS exists and contains the single record ``FRED,BERT''.

      INTEGER IGRP, STATUS, SIZE, ADDED
      LOGICAL FLAG
      CHARACTER * ( GRP__SZNAM ) NAMES( 3 )

      ...

      CALL GRP_NEW( 'A test group', IGRP, STATUS )

      CALL GRP_GRPEX( '^FRIENDS.LIS', GRP__NOID, IGRP, SIZE, ADDED, FLAG,
     :                STATUS )

      CALL GRP_GRPEX( 'HAROLD', GRP__NOID, IGRP, SIZE, ADDED, FLAG,
     :                STATUS )
      ...

      NAMES( 1 ) = 'TOM'
      NAMES( 2 ) = 'DICK'
      NAMES( 3 ) = 'HARRY'

      ...

      CALL GRP_PUT( IGRP, 3, NAMES, 2, STATUS )

The call to GRP_NEW creates a new, empty group. The first call to GRP_GRPEX read the two names from the file FRIENDS.LIS and stores them with the following indices:

      1 - FRED
      2 - BERT

Both SIZE and ADDED are returned equal to two. The second call to GRP_GRPEX appends the name HAROLD to the group, so that the group becomes:

      1 - FRED
      2 - BERT
      3 - HAROLD

SIZE is returned equal to 3 and ADDED equal to 1. The call to GRP_PUT then stores the name TOM at index 2 (over-writing BERT), and DICK at index 3 (over-writing HAROLD). The group is then extended and HARRY is stored at index 4 so that the group becomes:

      1 - FRED
      2 - TOM
      3 - DICK
      4 - HARRY