Staging User Options

User options are component-level user data that is stored in 57 fields of various lengths on the component master. You enter user options on customizable panels that are displayed in build processes like stage, recompile and relink. The information stored in user options is available in file tailoring for build processing JCL.

User option settings are included in designated compile procedures, so you can lock down these fields that determine how build processing is performed. User options can be validated by exit program CMNEX025 to ensure that prohibited values are not used before a component is installed.

Using a combination of user options and custom compile procedure skeletons, you can create highly flexible build processes that fits your unique needs.

User Options Field Names

The 57 user option fields vary in length from 1 byte to 72 bytes. This table shows user option field lengths and the names of the fields at key points in component build processing:

...

Field Length	Count	Field Names on ISPF Panels	CMNEX025 Field Names	CMNEX026 Field Names	File Tailoring Variable Names	ZDDOPTS Variable Names
1	20	USROP01 to USROP20	X25$UO01 to X25$UO20	X26$OP01 to X26$OP20	USROP01 to USROP20	UserOption01 to UserOption20
1	5	CUSR011 to CUSR015	X25$0101 to X25$0105		CUSR011 to CUSR015	UserOption101 to UserOption105
2	3	CUSR021 to CUSR023	X25$0201 to X25$0203		CUSR021 to CUSR023	UserOption201 to UserOption223
3	3	CUSR031 to CUSR033	X25$0301 to X25$0303		CUSR031 to CUSR033	UserOption301 to UserOption303
4	3	CUSR041 to CUSR043	X25$0401 to X25$0403		CUSR041 to CUSR043	UserOption401 to UserOption403
8	5	CUSR081 to CUSR085	X25$0801 to X25$0805		CUSR081 to CUSR085	UserOption801 to serOption805
10	2	CUSR101 to CUSR102	X25$1001 to X25$1002		CUSR101 to CUSR102	UserOption1001 to UserOption1002
16	2	CUSR161 to CUSR162	X25$1601 to X25$1602		CUSR161 to CUSR162	UserOption1601 to UserOption1602
34	2	CUSR341 to CUSR342	X25$3401 to X25$3402		CUSR341 to CUSR342	UserOption3401 to UserOption3402
44	2	CUSR441 to CUSR442	X25$4401 to X25$4402		CUSR441 to CUSR442	UserOption4401 to UserOption4402
64	5	CUSR641 to CUSR645	X25$6401 to X25$6405		CUSR641 to CUSR645	UserOption6401 to UserOption6405
72	5	CUSR721 to CUSR725	X25$7201 to X25$7205		CUSR721 to CUSR725	UserOption7201 to UserOption7205

...

User Options Input Panels

On stage, recompile, and relink panels that have not been customized, if you select the Other options field, four User Options panels (CMNUSR01/2/3/4) are displayed in a series.

CMNUSR01             User Options Part 1
Command ===>

    Name: ACPSRCEE                                 +
    Type: SRC           Language: COBOL2

    Compile only . . . . .  IMS DLITxxx entry . . .
    CICS precompile . . .   Drop include stmts . .
    Easytrieve object . .   User option 06 . . . .
    User option 07 . . . .  User option 08 . . . .
    User option 09 . . . .  User option 10 . . . .
    User option 11 . . . .  User option 12 . . . .
    User option 13 . . . .  User option 14 . . . .
    User option 15 . . . .  User option 16 . . . .
    User option 17 . . . .  User option 18 . . . .
    User option 19 . . . .  User option 20 . . . .
Enter "/" to select option
    / Mixed Case

...

CMNUSR02            User Options Part 2
Command ===>

    Name: ACPSRCEE                               +
    Type: SRC       Language: COBOL2

    Additional build parameters:
    CUSR641
    CUSR642
    CUSR643
    CUSR644
    CUSR645
Enter "/" to select option
    / Mixed Case

...

CMNUSR03                User Options Part 3
Command ===>

        Name: ACPSRCEE                                +
        Type: SRC           Language: COBOL2

    Additional component attributes:
    CUSR011 . . . . CUSR081 . . . . CUSR021 . . . .
    CUSR012 . . . . CUSR082 . . . . CUSR022 . . . .
    CUSR013 . . . . CUSR083 . . . . CUSR023 . . . .
    CUSR014 . . . . CUSR084 . . . .
    CUSR015 . . . . CUSR085 . . . .
    CUSR031 . . . . CUSR041 . . . . CUSR101 . . . .
    CUSR032 . . . . CUSR042 . . . . CUSR102 . . . .
    CUSR033 . . . . CUSR043 . . . .
Enter "/" to select option
    / Mixed Case

...

CMNUSR04                User Options Part 4
Command ===>

        Name: ACPSRCEE                              +
        Type: SRC           Language: COBOL2

    Additional component attributes:
    CUSR161 . . . .
    CUSR162 . . . .
    CUSR341 . . . .
    CUSR342 . . . .
    CUSR441 . . . .
    CUSR442 . . . .
    CUSR721 - CUSR725
Enter "/" to select option
    / Mixed Case

...

The panels shown here are the sample CMNUSR01, CMNUSR02, CMNUSR03, and CMNUSR04 panels that are delivered on the ChangeMan ZMF installer. You can customize these panels to display and process the user options fields that you want to use.

User Options and Exits

User options variables are available in two exits.

Exit

Function

CMNEX025

Prohibit package freeze or selective refreeze of Source and Load depending on compile parameters, link edit parameters, and user options used in the last stage job.

CMNEX026

Dynamically allocate additional staging libraries based on component type, user options, and other data passed to the exit. Define relationships between library types so that when a component is deleted, components with the same name in related library types are also deleted. Prohibit delete based on library type, member name, or whether component is promoted.
Note: Only the first twenty 1-byte user options (panel field names USROP01 to USROP20) are available in this exit.

...

Implementing the User Options

Follow the steps in this section to modify user options components delivered in ChangeMan ZMF libraries so that they satisfy your needs for build processing.

Choose User Options Fields

Plan how you want user options to store information at the component level and to control build processing. Identify how you want user options to control file tailoring to create build job JCL, set build process parameters, manage target library types with CMNEX026, and any other use you can devise.
Map each user option variable to the purpose it will serve and the values that will be valid. Choose the shortest fields that will accommodate the data that you will store. See User Options Field Names for a description of the 57 available fields.
Mock up one or more prototype Stage User Options panels, and choose field tags that will fit in the available space.

Modify Sample Stage User Options Panels

Copy sample Stage User Options panels CMNUSR01-04 into your custom panels library from the CMNZMF PANELS library unloaded from the installer.
Modify the )BODY section of the panels to display field tags that identify the data users should enter in each user option field. To enhance usability, group user options that serve a similar purpose under panel subheadings.
Modify the )INIT section to initialize blank fields. Modify the .ZVARS = statement to associate panel fields with the appropriate user option field name.
Modify the )PROC section to validate information entered by the user and to perform cross field edits, if required. Set the value of variable USRPAN to the member name of the next Stage User Options panel, and set USRPAN to blank for the last panel in the chain.
Copy sample help panel CMNHMSC9 to your custom panels library from the CMNZMF PANELS library unloaded from the ZMF installer. Modify the panel to describe the user options on your custom CMNUSR01 panel. Create new help panels for the other Stage User Options panels. Code the help panel member names in the .HELP = statement in the )INIT section of each Stage User Options panel.
Verify that your customized Stage User Options panels and help panels look like you want when accessed from these panels.
- CMNCMPH2 Compile and Link Edit Options
- CMNQRY22 Query Compile and Link Edit Options
- CMNRCMP1 Recompile Job Information
- CMNRCMP3 Recompile Job Information
- CMNRLNK1 Relink Job Information
- CMNSTG04 Stage Build
- CMNSTG05 Stage Mass Build Edit

Modify Exits

User options fields in copybooks CMNEX025 and CMNEX026 are available in copybooks CMNEX025 and CMNEX026 respectively.

Copy the exit program source you want to modify to your custom source library from the CMNZMF ASMSRC library delivered on the ChangeMan ZMF installer.
Modify exit program logic to use the user options. See the User Exits for general instructions for enabling and coding ChangeMan ZMF exit programs.

Modify Build Skeletons

Copy stage process skeletons to your custom skeleton library from the CMNZMF SKELS library unloaded from the ZMF installer.
Modify those skeletons to use the user options variables.
Note

Skeleton CMN$$VAR is imbedded in every compile procedure skeleton delivered with ChangeMan ZMF. Use this skeleton to:
- Translate ChangeMan ZMF ISPF variable names into names that are meaningful to you
- Convert a value in a single user option into multiple variables
- Set one or more variables for file tailoring from combinations of user options

User Options Example

The sample CMNUSR01 panel contains five examples of user options that are fully coded in the compile procedure skeletons delivered with ChangeMan ZMF. You can change these examples to use USROP01-USROP05 for any purpose you choose.

This section describes how the first example user option is used to create stage job JCL that creates object but does not link edit the object into a load module.

User Option Panel CMNUSR01

In the )BODY section of panel CMNUSR01, the first user option (USROP01) is labeled “Compile only”. In the )PROC section, a VER command ensures that Y and N are the only acceptable values for data entered in that field otherwise message CMN132 is issued. Help panel CMNHMSC9 should be updated to describe this first user option and its purpose.

Variable Skeleton `CMN$$VAR`

In skeleton CMN$$VAR, near the top, the value of variable USROP01 is tested. If the value is Y, variable COMPONLY is set to Y. If USROP01 is N, COMPONLY is set to N.

Search skeleton CMN$$VAR for occurrences of COMPONLY to see how other variables are set for Object processing.

Compile Procedure CMNCOB2

In compile procedure CMNCOB2, variable COMPONLY is tested for value equal to Y and also for not Y (NE Y). Some skeleton code is selected when the value of COMPONLY is Y, and link edit skeletons CMN$$SSI and CMN$$LNK are only included when COMPONLY is not Y (NE Y).

HLLX exit requirements

This replaces ISPF dialog panel logic prior to display of the first panel. If you change the first user panel names from the defaults in only the ISPF panel and not the HLLX exit, the UV command will not work correctly.

Subsequent panels displays ABCUSR02, ABCUSR03 etc are done as they are today by setting USRPAN to the next panel name in the series. A simple REXX example follows, if the user is ABCD233 then change the default src and non-src names as follows:

if userid = "ABCD233" then
 do
  if userPanel = "CMNUSR01" then
  do
   userPanel = "ABCUSR01"
  end
  if userPanel = "CMNUSR11" then
  do
   userPanel = "ABCUSR11"
  end
end

...

The code must include the Boolean "if" logic about the default panel names, otherwise each time a subsequent panel is called into the exit it will be changed to ABCUSR01/11 and not display any more. In essence this is a 'what to do first time through', subsequent panels are displayed as per usual by setting the USRPAN variable on the user panel.

That is, without the first time "if" logic, if you set the panels to be ABCUSR01-04, when ABCUSR02 is processed by the exit it will be changed to ABCUSR01 again and the panel loop logic will terminate prematurely.