This routine is used to allow multiple invocations of an application within an Starlink monolith to process a group of data files. The initialization routine LPG_START should be called prior to this routine. This routine returns a logical flag indicating if the application should be invoked again. A typical way to use this routine within a monolith is as follows:

CALL LPG_START( VERB, DELAY, DISAB, STATUS )

DO WHILE ( LPG_AGAIN( STATUS ) )

IF ( ACTION .EQ. ’ADD’ ) THEN

CALL ADD( STATUS )

ELSE IF ( ACTION .EQ. ’SUB’ ) THEN

CALL SUB( STATUS )

ELSE IF...

...

END IF

END DO

The application corresponding to the required action will always be invoked once. The applications should use the routines LPG_ASSOC, LPG_PROP, LPG_CREAT and LPG_CREP to get identifiers for NDFs, in place of their equivalent routines from the NDF library.

For catalogues, routines LPG_CATASSOC and LPG_CATCREAT should be used in place of CAT_ASSOC and CAT_CREAT.

LPG_AGAIN returns a .TRUE. value until a group of data files is exhausted, whereupon it deletes all its groups and returns a .FALSE. value.

On the first invocation of the application, groups of data files are obtained whenever one of the above LPG routines is used to get an NDF or CAT identifier, and an identifier corresponding to the first name in each group is returned to the application. On subsequent invocations, the names in the groups obtained during the first invocation are used without obtaining new parameter values from the environment. The index of the returned data file within each group is increment by 1 each time the application is invoked.

If an application is invoked more than once, all other parameters retain the values they had at the end of the first invocation. Applications that use this scheme should avoid having parameters with "VPATH=DYNAMIC" in the interace file, since the dynamic default calculated on the first invocation will then be re-used for all subsequent invocations, which may be inappropriate. A better scheme is to have "VPATH=DEFAULT", "PPATH=DYNAMIC" and "DEFAULT=!". The code should then annul any PAR__NULL status after accessing the parameter, and use the previously calculated dynamic default value for the parameter. With this scheme, the parameter value is "!" at the end of the first invocation, and so retains this value for all subsequent invocations, resulting in appropriate dynamic defaults being used.

A situation in which the above suggestion does not work is if an application sometimes sets a dynamic default, and sometimes does not. In this case, you do not want to have VPATH=DEFAULT, DEFAULT=! because this would require the application to abort in the cases where there is no dynamic default available. It is probably better in these cases to have VPATH=PROMPT,PPATH=DYNAMIC and accept the fact that the user will be prompted for a parameter that was previously defaulted.

Some applications test to see if a parameter was specified on the command line, and vary their behaviour accordingly. This is done by checking the state of the parameter before accessing it, a state of PAR__ACTIVE (or SUBPAR__ACTIVE) indicating that the parameter already has a value. This is correct on the first invocation, but not on subsequent invocations because the first invocation may have set a parameter value, resulting in subsequent invocations thinking that the parameter was given on the command line. To avoid this, applications should use LPG_STATE in place of PAR_STATE. LPG_STATE remembers the state of the parameter on the first invocation, and returns that state, rather than the current parameter state, on subsequent invocations.

RESULT = LPG_AGAIN( STATUS )

STATUS = INTEGER (Given and Returned)

LPG_AGAIN = LOGICAL