Process a Path Name Exit Program

The Process a Path Name exit program is a user-specified exit program that is called by the Qp0lProcessSubtree() function 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:

• End processing.
• Continue processing by calling the exit program again with the next object from the same directory.
• Continue processing by calling the exit program again, but not with objects from the same directory. In this case, Qp0lProcessSubtree() moves to the next directory or object that meets the specified criteria and calls the exit program with it.

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, Error value pointer, Return value pointer, or the Object name pointer when the Process a Path Name exit program is called, are destroyed or reused when Qp0lProcessSubtree() regains control.

See Qp0lProcessSubtree()--Process a Path Name for more information.

Authorities and Locks

None.

Parameters

Selection status pointer

INPUT; BINARY(4)

A pointer to an unsigned integer. This pointer indicates whether Qp0lProcessSubtree() encountered any problems in processing. Valid values follow:

0	QP0L_SELECT_OK: Indicates to that no problems were encountered during the selection of the current object. The Error value pointer parameter is set to NULL.
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 and the Error value pointer parameters are 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.

Error value pointer

INPUT; BINARY(4)

A pointer to a valid errno that describes any problems encountered by the API during the processing of the current object. Any valid errno can be passed in this field when this parameter is not NULL.

Return value pointer

OUTPUT; BINARY(4)

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.

Object name pointer

INPUT; CHAR(*)

A pointer to the path name structure that contains the fully qualified name of the object being processed by Qp0lProcessSubtree(). For more information on 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.

Function control block pointer

INPUT; CHAR(*)

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.