%INSTANCES (C, C++, and PL/I)

Returns the maximum value of %RECURSION (the most recent recursion number) for a given block.

reference: An automatic variable or a subroutine parameter. If necessary, you can use qualification to specify the variable.

%INSTANCES can be used like a z/OS® Debugger variable.

Usage notes

z/OS Debugger does not support the %INSTANCES built-in function for Enterprise PL/I programs.

You cannot use the %INSTANCES built-in function while you replay recorded steps.

Examples

C and C++:

%INSTANCES and %RECURSION can be used together to determine the number of times a function is recursively called. They can also give you access to an automatic variable or parameter in a specific instance of a recursive procedure. Assume, for example, your program contains the following statements.
```
int RecFn(unsigned int i) {
  if (i == 0) {
    __ctest("");
```
At this point, the __ctest() call gives control to z/OS Debugger, and you are prompted for commands. Enter the following command.
```
LIST %INSTANCES(i);
```
The Log window displays the number of times that RecFn() was interactively called.
To display the value of 'i' at the first call of RecFn(), enter the following command.
```
%RECURSION(i, 1);
```
If necessary, you can use qualification to specify the parameter. For example, if the current point of execution is in %block2, and %block3 is a recursive function containing the variable x, you can write an expression using x by qualifying the variable, as shown in the example below.
```
%RECURSION(main:>%block3:>x, %INSTANCES(main:>%block3:>x, y+
```
The following example gets a line of input from stdin using the C library routine gets.
```
char line[100];
char *result;
result = gets(line);
```
The following example removes a file and checks for an error, issuing a message if an error occurs.
```
int result;
result = remove("mayfile.dat");
if (result != 0)
  perror("could not delete file");
```
z/OS Debugger performs the necessary conversions when a call to a library function is made. The cast operator can be used. In the following example, the integer 2 is converted to a double, which is the required argument type for sqrt.
```
double sqrtval;
sqrtval = sqrt(2);
```
Nested function calls can be performed, as shown in the example below.
```
printf("absolute value is %d\n", abs(-55));
```
C library variables such as errno and stdout can be used, as shown in the example below.
```
fprintf(stdout, "value of errno is %d\n", errno);
```

Refer to the following topics for more information related to the material discussed in this topic.

Related references
%RECURSION (C, C++, and PL/I)