Build and Promote User Exit routine requirements

If you specify a user exit option parameter, SCLM passes it to the user exit routine, followed by a string of up to eleven parameters separated by commas. The parameter list can include one list of user-specified options followed by up to ten SCLM parameters (see Table 1). The address of this input data is contained at the address stored in register 1. The first halfword of the input data is the number of characters comprising the input data string. Immediately following this halfword length is the input parameter string itself.

The user exit routine must pass back a return code value to SCLM in register 15. A return code of zero is considered to be successful and processing continues. In most situations a nonzero return code from the user exit routine causes build or promote to end with a return code 8. Whether or not processing continues after the user exit depends on the return code value passed back by the user exit routine and the exit routine being invoked. Nonzero return code values from user exit routines are handled in the following ways:

Both the Build Notify user exit (BLDNTF) and the promote purge phase user exit (PRMPURGE) can return any value as processing has already been completed at the time the exit is invoked. SCLM will, however, set a return code of 4 (in the case of BLDNTF) or 8 (in the case of PRMPURGE) for the final SCLM return code if a nonzero return code is set in the user exit.
Any nonzero value returned by the Build Initial user exit (BLDINIT) or the Promote Initial user exit (PRMINIT) causes processing to stop.
The processing that occurs after the promote verification phase user exit (PRMVFY) has been invoked depends on the promote mode in effect. In conditional mode, a return code greater than 4 causes promote processing to stop. In unconditional mode, any return code other than 20 allows promote processing to continue.
The processing that occurs after the Promote Copy user exit (PRMCOPY) has been invoked depends only on the return code value returned. Any return code other than 20 allows normal promote processing to continue.

Table 1 explains the format and description of the parameters passed from SCLM to all build and promote user exits.

Table 1. User Exit Parameters
Parameter	Description
OPTION LIST	Up to 255 characters, including delimiters (blank padding is not performed for this parameter). Parameter is specified in the FLMCNTRL macro using macro parameters BLDINIOP, BLDNTFOP, PRMINIOP, PRMVFYOP, PRMCPYOP, and PRMPRGOP. Delimit this string so that the SCLM parameters that follow can be identified by the user exit routine.
‘xxxxxxxx’	An 8-character literal value indicating the exit type (capitalized, left-aligned, blank-padded). Valid types are: BINITIAL Build Initial (BLDINIT) BUILD Build Notify (BLDNTF) PINITIAL Promote Initial (PRMINIT) PVERIFY Promote Verify (PRMVFY) PCOPY Promote Copy (PRMCOPY) PPURGE Promote Purge (PRMPURGE).
PROJECT	The 8-character name of the project (capitalized, left-aligned, blank-padded).
LIBDEF	The 8-character name of the project definition (capitalized, left-aligned, blank-padded).
USERID	The 8-character value of the user's logon ID (capitalized, left-aligned, blank-padded).
FROM GROUP	The 8-character name of the group (capitalized, left-aligned, blank-padded). The group is the "from group" for the promote and the "build group" for the build.
TYPE	The 8-character name of the type (capitalized, left-aligned, blank-padded).
MEMBER	The 8-character name of the member (capitalized, left-aligned, blank-padded).
SCOPE	The 8-character name of the scope (capitalized, left-aligned, blank-padded). Valid scopes are as follows: Build scope Limited, normal, subunit, extended. Promote scope Normal, subunit, extended.
MODE	The 13-character name of the mode (capitalized, left-aligned, blank-padded). Valid modes are as follows: Build mode Forced, conditional, unconditional, and report only. Promote mode Conditional, unconditional, and report.
TO GROUP	The 8-character name of the group (capitalized, left-aligned, blank-padded). The group is the "to-group" for the promote exit routines. This parameter is blank for the build exit routine.

Build allocates the following ddnames for internal use: BLDEXIT; BLDLIST; BLDMSGS; BLDREPT

Promote allocates the following ddnames for internal use: COPYERR; PROMEXIT; PROMMSGS; PROMREPT

Use of these names in user exit routines can cause conflicts. At the end of an exit routine, free only those ddnames explicitly allocated by the exit routine.