| 1 | Selection status pointer | Input | BINARY(4) |
| 2 | Error value pointer | Input | BINARY(4) |
| 3 | Return value pointer | Output | BINARY(4) |
| 4 | Object name pointer | Input | CHAR(*) |
| 5 | Function control block pointer | Input | CHAR(*) |
The Process a Path Name exit program is a user-specified exit program that is called by the Qp0lProcessSubtree() API for each object in the API's search that meets the caller's selection criteria. This exit program can be either a procedure or program.
When the user exit program is given control, it can call other APIs, build lists or tables, or do other processing. Since the API passes the names of all the children objects to the user exit program before passing the name of the parent, the user exit program can also delete directories.
If the exit program encounters an error during processing, it returns a valid errno in the Return value pointer field, that Qp0lProcessSubtree() returns to its caller. When its processing is complete, the exit program return code is set to tell Qp0lProcessSubtree() to do one of the following:
If Qp0lProcessSubtree() encounters any problems in resolving to a user exit program, Qp0lProcessSubtree() ends and returns to its caller. If Qp0lProcessSubtree() encounters any errors with any other parameters, it ends and returns control to its caller, after a call to the user exit program. This call allows the exit program to perform any desired cleanup before Qp0lProcessSubtree() ends. Use the Err_recovery_action parameter of Qp0lProcessSubtree() to set other conditions for calling or not calling the user exit program.
Storage referred to by the Selection status pointer, the Error value pointer, the Return value pointer, and the Object name pointer when the Process a Path Name exit program is called, is destroyed or reused when Qp0lProcessSubtree() regains control.
See Qp0lProcessSubtree()--Process a Path Name for more information.
None.
A pointer to an unsigned integer. This pointer indicates whether Qp0lProcessSubtree() encountered any problems in processing. Valid values follow:
| 0 | QP0L_SELECT_OK: Indicates that no problems were encountered during the selection of the current object. |
| 1 | QP0L_SELECT_DONE: Indicates that the last object was processed and that this is the last call to the Process a Path Name exit program. The Object name pointer is set to NULL. |
| 2 | QP0L_SELECT_NOT_OK: Indicates that Qp0lProcessSubtree() has encountered an error but that the Process a Path Name exit program can decide if the operation should continue or end. The Error value pointer parameter points to a valid errno. |
| 3 | QP0L_SELECT_FAILED: Indicates that Qp0lProcessSubtree() has encountered an unrecoverable error and that Qp0lProcessSubtree() will return to its caller when it regains control. The Error value pointer parameter points to a valid errno. |
A pointer to a valid errno that describes any problems encountered by the Qp0lProcessSubtree() API during the processing of the current object. If no problems were encountered then the error value will be zero. Any valid errno can be passed in this field.
A pointer to a value from the Process a Path Name exit program that instructs the API to continue or to end processing. Valid values follow.
| 0 | Process a Path Name exit program was successful. |
| -1 | Process a Path Name exit program was successful. Qp0lProcessSubtree() should skip processing any remaining objects in this directory and move on to process objects in other directories. |
| > 0 (an errno) | Process a Path Name exit program was not successful. Qp0lProcessSubtree() ends. |
A pointer to the path name structure that contains the fully qualified name of the object being processed by Qp0lProcessSubtree(). For more information about this structure, see Path name format. The Path_Type flag defined in the qlg.h header file must be used to determine whether the Object name pointer contains a pointer or is a character string. This flag must also be used to determine whether the path name delimiter character is 1 or 2 characters long. Valid values follow:
| 0 | The path name is a character string, and the path name delimiter is 1 character long. |
| 1 | The path name is a pointer, and the path name delimiter character is 1 character long. |
| 2 | The path name is a character string, and the path name delimiter is 2 characters long. |
| 3 | The path name is a pointer, and the path name delimiter character is 2 characters long. |
A pointer to the data that is passed to Qp0lProcessSubtree() on its call. Qp0lProcessSubtree() does not process the data that is referred to by this pointer, but passes this pointer as a parameter when it calls the exit program.