IB Statements/activate

From CometWiki

ACTIVATE statement

Syntax: ACTIVATE partition, program [,DIR=directory][,EXCP=statement-label]

Discussion: The ACTIVATE statement executes a specified program in a named partition.

The partition parameter is the name of the partition from which the program you specified will be executed. This can be a string constant or a string variable, with a length of three characters. If this string is null, Comet will attempt to activate the specified program in the first available background partition (and the name of this partition is returned in the system variable named SYSPART$).

The program parameter is the name of the program to be executed in the partition you specified. Program names can have a length of up to eight characters, and can be a string constant or a string variable.

The directory parameter (optional) is the Comet directory where the specified program is located. It can be string constant or string variable, with a length of up to three characters. If a directory name is specified, only that directory is searched for the program. If a directory name is not specified, the system searches all accessed directories in accessed order until the program is found.

The ACTIVATE statement can pass up to 16K of COMMON to the program being activated.

Application notes:

When activating a background partition, pay special attention to logical unit number 0. In a background partition, there is no video device, and logical unit number 0 may be used for other purposes.

When writing programs that will be executed in a background partition (and activated from a foreground program), note that the system variable TERM$ equals three blank spaces in a background partition. This is a good way to check for foreground vs. background status of a partition.

Also see TERMINATE and KILL.

Example 1: ACTIVATE "P09","UPDATE",DIR="DSK",EXCP=9000

In this example, the program named UPDATE located on directory DSK is activated in partition P09. If an exception occurs when this statement is executed, the program will branch to statement-label 9000. If no exception occurs, the program will continue executing (and the UPDATE program will begin executing in partition P09).

Example 2:

 LENGTH 40 & COMMON DATA$
 LENGTH 8.2 & COMMON VALUE1, VALUE2, VALUE3
 .
  ACTIVATE "P16","REPORT",EXCP=9999

In this example, the program named REPORT is activated in partition P16. The COMMON data defined at the beginning of this program is passed to the activated partition. If an exception occurs when this statement is executed, the program will branch to statement-label 9999.

Example 3:

        FOR J=4 to 8
         NUMBER$=STR(J)
         PART$="P0"+NUMBER$
         ACTIVATE PART$,"UPDATE",EXCP=5000
         GOTO 6000
     5000    NEXT J
       PRINT (0) "UPDATE program not activated."
       GOTO 9000
     6000    PRINT (0) "UPDATE program activated in partition ";PART$

This example demonstrates how a specific range of partitions can be scanned for possible activation of a program. The control variable (J) in the FOR/NEXT loop starts at 4 and advances to 8, representing the partitions that will be scanned (i.e., P04 through P08).

For example, the first time through the loop, J will equal 4 and NUMBER$ will equal the string equivalent of 4. This string value is then appended to the first two characters of a partition name ("P0"), forming a complete partition named of "P04".

Next, the program attempts to activate partition P04. If the activation is successful, the program branches to statement-label 6000 and displays a success message. If the activation is unsuccessful, the program branches to statement-label 5000 (the NEXT statement).

If partitions P04, P05, P06, P07, and P08 are not able to be activated (possibly because they are already busy running other jobs), the loop terminates and displays a failure message. The program then jumps to statement-label 9000.