Configuring the project

To configure a project

Use the following procedure to configure the project to validate application SQL run against Db2 for z/OS environment. 

1. From the Dashboard in the Jenkins web user interface:
   1. Select the project you want to configure.
   2. Click Configure. 
2. Select the General tab.
   1. (Optional) Enter a project description.

   2. (Optional) To use parameters in the project:

      1. Select the This project is parameterized check box.
      2. Click Add Parameter .

      3. From the list, select the type of parameter.

         Warning

         Important

         Boolean Parameter, String Parameter, and Password Parameter are the typical parameter types for the variables you might use when working with the product.

         Information

         Examples

         • AMIDevOpsDebugOn is a Boolean Parameter.
         • MF_USER_ID is a String Parameter.
         • MF_PW is a Password Parameter. This parameter type provides encryption for passwords.
      4. For the new parameter, enter values for the following fields:

         1. Name

            Warning

            Important

            • String parameters with spaces in the name are not supported. You can include an underscore in the string parameter names.
            • A double dollar sign can be used to produce a character string starting with, or containing, a dollar sign. That is, $$ yields $.
         2. Default Value
         3. Description
3. Select the Build tab to add and configure the build steps as follows:

   1. Click Add build step.

      Warning

      Important

      SQL Assurance has two main build steps and three supporting build steps.

      The two main build steps are:

      • BMC AMI SQL Assurance for Db2 - Analyze Static SQL
      • BMC AMI SQL Assurance for Db2 - Analyze Dynamic SQL

      The three supporting build steps are:

      Success

      Best practice

      Select one of the Common - Authentication build steps based on your Jenkins configuration.

      • BMC AMI DevOps Common - Authentication
      • BMC AMI DevOps Common - Authentication (Credential Store) 
      • BMC AMI DevOps Common -  Clean Up

      We offer the BMC AMI DevOps Common - Authentication (Credential Store) build step. This build step has the Login Credentials field that provides credentials saved in Jenkins Credential Store. For more information, see BMC AMI DevOps Common - Authentication (Credential Store).

      When configuring projects, if you add one or more main build steps, you must also add the supporting build steps. You must add BMC AMI DevOps Common - Authentication or BMC AMI DevOps Common - Authentication (Credential Store) as the first build step and BMC AMI DevOps Common - Clean Up as the last build step. For more information, see Examples of how to add build steps during project configuration.

   2. Add build steps and enter values for the fields:

      Warning

      Important

      • You can run any or all build steps in Debug mode. For more information, see To run build steps in Debug mode.

      • When building the project with two main build steps, BMC AMI SQL Assurance for Db2 - Analyze Static SQL and BMC AMI SQL Assurance for Db2 - Analyze Dynamic SQL, you can disable processing for one of the build steps except:

        • BMC AMI DevOps Common - Authentication
        • BMC AMI DevOps Common - Authentication (Credential Store)
        • BMC AMI DevOps Common -  Clean Up

        For example, you can disable the BMC AMI SQL Assurance for Db2 - Analyze Dynamic SQL build step when you are performing a Static Explain on an SQL statement with BMC AMI SQL Assurance for Db2 - Analyze Static SQL build step. To enable this feature, select the Disable Build Step check box.

      • To enter your mainframe password when building the project:
        1. Select the Provide Password via Build Parameter check box.
        2. Specify a parameter-based variable as the value of the Mainframe Password via Build Parameter field. For example, specify ${MF_PW}, where MF_PW is a Password Parameter variable, as the value of this field.
      • To generate JCL but not execute it, you can select the Generate JCL Only check box available in both the BMC AMI SQL Assurance for Db2 - Analyze Static SQL and the BMC AMI SQL Assurance for Db2 - Analyze Dynamic SQL build steps. For example, you can use this feature to validate the JCL before submitting it. The generated JCL is saved to the project workspace folder. If you select this option, you must also disable the subsequent build steps.

      • For any of the following fields, if you do not enter any path or enter the relative path, SQL Assurance considers the default path of the workspace project folder.

        Build step	Field
        BMC AMI DevOps Common - Authentication	Plug-in Variables File Path
        BMC AMI SQL Assurance for Db2 - Analyze Static SQL	Object List File Path

        For more information about the default path, see Default path for Jenkins projects when the relative path is specified for a field.

      1. BMC AMI DevOpsCommon - Authentication

         Click here for information about configuring this build step

         To configure the BMC AMI DevOps Common - Authentication build step

         Enter values for the following fields:

         1. Mainframe (host name or IP address)

            Warning

            Important

            Ensure that you enter the corresponding mainframe IP address or host name of the LPAR in the SYSPLEX on which z/OSMF is running.

         2. Port Number

            Warning

            Important

            Ensure that you enter the corresponding port number of the LPAR in the SYSPLEX on which z/OSMF is running on the mainframe.

         3. Mainframe User ID
         4. Provide Password via Build Parameter
            Select this check box if you want to enter your mainframe password when building the project. If you select this check box, you must enter a parameter as the value for the the Mainframe Password via Build Parameter field.
         5. Mainframe Password
            If you do not select the Provide Password via Build Parameter check box, enter your mainframe password in this field.

         6. Plug-in Variables File Path

            Warning

            Important

            You can also enter a String Parameter variable in the Plug-in Variables File Path field. You can specify any of the following values for the variable:

            • The full plug-in variables file path, including the file name
            • Part of the plug-in variables file path
            • The plug-in variables file name

            See the following examples:

            Information

            Example 1

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARPROP
            Default Value	/var/lib/AMA_Properties/AMA_DevOps.properties
            Description	The value of this variable is the full plug-in variables file path, including the file name.

            You can then enter ${VARPROP} in the Plug-in Variables File Path field.

            Information

            Example 2

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARPATH
            Default Value	/var/lib/AMA_Properties
            Description	The value of this variable is part of the plug-in variables file path and does not include the file name.

            You can then enter ${VARPATH}/AMI_DevOps.properties in the Plug-in Variables File Path field.

            Information

            Example 3

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARFILE
            Default Value	AMI_DevOps.properties
            Description	The value of this variable is the plug-in variables file name and does not include the file path.

            You can then enter /var/lib/AMA_Properties/${VARFILE} in the Plug-in Variables File Path field.

            Warning

            Important

            AMI_DevOps.properties is the default name of the plug-in variables file. Your plug-in variables file can have any name but it must be a .properties file.

            
            

      2. BMC AMI DevOpsCommon - Authentication (Credential Store)

         Click here for information about configuring this build step

         To configure the BMC AMI DevOps Common - Authentication (Credential Store) build step

         Enter values for the following fields:

         1. Mainframe (host name or IP address)

            Warning

            Important

            Ensure that you enter the corresponding mainframe IP address or host name of the LPAR in the SYSPLEX on which z/OSMF is running.

         2. Port Number

            Warning

            Important

            Ensure that you enter the corresponding port number of the LPAR in the SYSPLEX on which z/OSMF is running on the mainframe.

         3. Login Credentials

            Warning

            Important

            In the Jenkins Credentials Provider: Jenkins >  Add Credentials, we only support the Username with Password option in the Kind field.

         4. Plug-in Variables File Path

            Warning

            Important

            You can also enter a String Parameter variable in the Plug-in Variables File Path field. You can specify any of the following values for the variable:

            • The full plug-in variables file path, including the file name
            • Part of the plug-in variables file path
            • The plug-in variables file name

            See the following examples:

            Information

            Example 1

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARPROP
            Default Value	/var/lib/AMA_Properties/AMA_DevOps.properties
            Description	The value of this variable is the full plug-in variables file path, including the file name.

            You can then enter ${VARPROP} in the Plug-in Variables File Path field.

            Information

            Example 2

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARPATH
            Default Value	/var/lib/AMA_Properties
            Description	The value of this variable is part of the plug-in variables file path and does not include the file name.

            You can then enter ${VARPATH}/AMI_DevOps.properties in the Plug-in Variables File Path field.

            Information

            Example 3

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARFILE
            Default Value	AMI_DevOps.properties
            Description	The value of this variable is the plug-in variables file name and does not include the file path.

            You can then enter /var/lib/AMA_Properties/${VARFILE} in the Plug-in Variables File Path field.

            Warning

            Important

            AMI_DevOps.properties is the default name of the plug-in variables file. Your plug-in variables file can have any name but it must be a .properties file.

            
            

      3. (BMC.DB2.SPE2404) BMC AMI DevOpsCommon - File Transmission

         Click here for information about configuring this build step

         To configure the BMC AMI DevOpsCommon - File Transmission build step

         Enter values for the following fields:

         • Direction of File Transfer 
           Select one of the following options:
           
           • Send file to mainframe
           • Receive file from mainframe
         • Source PDS or Directory Name
         • Source Member or File Name
         • Destination PDS or Directory Name
         • Destination Member or File Name

      4. BMC AMI SQL Assurance for Db2- Analyze Static SQL

         Click here for information about configuring this build step

         To configure the BMC AMI SQL Assurance for Db2 - Analyze Static SQL

         Use the following procedure:

         1. In the General Input Fields section, provide input for the following fields:
            
            1. SSID
            2. Violation Response
            3. Explain Method for SQL

            4. Object Type

               Warning

               Important

               For Object Type select one of the following options:

               • If you select Plan as your Object Type, you can only enter the Object Name.
               • If you select Package as your Object Type, you can enter any one of the following:
                 • Object Name
                 • Collection ID (Package only)
                 • Version (Package only)

               The Object Type field is required when you use an Object List File.

            5. Object Name
            6. Collection ID (Package only)
               
            7. Version (Package only)
            8. Use Object List File
            9. Object List: Continue on error

            10. Object List File path

                Warning

                Important

                If you select the Use Object List File option then the following fields are not applicable:

                • Object Name
                • Collection ID (Package only)
                • Version (Package only)

                For more information about the Object List, see Sample values for Analyze Static SQL Package Object List
                

                If you do not select the Use Object List File option, then you must enter at least one or more values for Object Name, Collection ID (Package only) or Version (Package only) dependent on the Object Type selected.

         2. In the Job Information section, enter values for the following fields:
            1. Job Card
            2. JCL

            3. Maximum Job Wait Time

               The product generates values for the SQL Explorer Input Stream field based on your input for the General Input Fields section.

      5. BMC AMI SQL Assurance for Db2- Analyze Dynamic SQL

         Click here for information about configuring this build step

         To configure the BMC AMI SQL Assurance for Db2 - Analyze Dynamic SQL

         Use the following procedure:

         1. In the General Input Fields section, provide input for the following fields:
            1. SSID
            2. Violation Response

            3. Table Creator

               Warning

               Important

               The DSN_STATEMENT_CACHE_TABLE must exist for this table creator in order to use it.

            4. Clear DSN Statement Cache Table
               
            5. Extract SQL from Dynamic Statement Cache
               
            6. Fail Step if WHERE clause returns no result set
               

            7. WHERE Clause Generation Mode

               Warning

               Important

               For WHERE Clause Generation Mode select one of the following options:

               • Auto generated WHERE clause
               • User supplied WHERE clause
            8. PRIMAUTH
               

            9. Age of Cached Statement (CACHED_TS)

               Warning

               Important

               An Auto generated WHERE clause uses the values supplied for the PRIMAUTH and the Age of Cached Statement (CACHED_TS) fields.

            10. User Supplied WHERE Clause

                Warning

                Important

                The field for User Supplied WHERE Clause allows valid SQL syntax for the predicate, with a maximum of 355 characters.

         2. In the Job Information section, enter values for the following fields:
            
            1. Job Card
            2. JCL

            3. Maximum Job Wait Time

               The product generates values for the Extractor Input Stream field based on your input for the General Input Fields section.
               

      6. (BMC.DB2.SPE2404) BMC AMI DevOpsCommon - JCL Execution

         Click here for information about configuring this build step

         To configure the BMC AMI DevOps Common - JCL Execution build step

         Enter values for the following fields:

         • (Not applicable for SQL Assurance) Run Step regardless of previous Compare results check box 
           

         • Source of JCL

           Warning

           Important

           You can select any one of the following options in the Source of JCL field:

           • (Default) Submit JCL from file or member uses the JCL defined in the following fields:
             • Execution JCL PDS or Directory Name
             • Execution JCL Member or File Name
           • Submit free-form JCL defined below uses the JCL statement defined in the Free-form JCL field.
         • Execute JCL from Mainframe PDS check box
         • Execution JCL PDS or Directory Name
         • Execution JCL Member or File Name
         • Free-form JCL
           
         • Acceptable Return Code
         • Maximum Job Wait Time
      7. BMC AMI DevOpsCommon -  Clean Up
         Add BMC AMI DevOps Common -  Clean Up as the last build step in your project to delete the workfile.properties file after processing all the other build steps.
   3. Click Apply to save the project, or Save to save and close the project.
       

Examples of how to add build steps during project configuration

The following examples illustrate how to add build steps to the project configuration.

For information about configuring the fields in each build step, see step 3 of the procedure to configure the project.

To use the configuration provided in the sample project

BMC has provided you with a ready-made sample project for your reference and convenience. The sample project folder contains the  config.xml file for the project. You can customize the configuration available in the sample project instead of configuring a new project.

Follow this procedure to use the sample project:

1. Copy the project folder to the following directory:

   Click here if you are using Jenkins on Windows

   installationDirectory\Jenkins\jobs 
   In this path, the installationDirectory variable represents the directory on the system on which Jenkins is installed.

   Click here if you are using Jenkins on Linux

   /installationDirectory/jenkins/jobs

   In this path, the installationDirectory variable represents the directory on the system on which Jenkins is installed.

2. Restart the Jenkins server and log in to Jenkins.
   The sample project appears on the Dashboard in the Jenkins web user interface.

3. Open the project for configuration.

4. Update the values of the fields based on your requirements. For more information, see To configure a project.

For the full list of sample values that you can configure for the different fields in the project, see Sample projects for Jenkins.

To run build steps in Debug mode

To view additional diagnostic information, you can run any or all the build steps in the Debug mode. To enable this feature, do one of the following:

• To run any build step in Debug mode, when configuring the build step, select the Run Step in Debug Mode check box.
• To run all the build steps in Debug mode:

  1. When configuring the project, add a Boolean parameter with the following field values:

     Field	Value	Notes
     Name	AMIDevOpsDebugOn	You must enter only this value for this field. However, this name is not case-sensitive.
     Default Value		Clear this check box.
     Description	Select this check box to run all the build steps in Debug mode.

     For more information about configuring parameters, see step 2.b of the procedure to configure a project.

  2. When building the project, select the AMIDevOpsDebugOn check box.

     Warning

     Important

     Selecting the AMIDevOpsDebugOn check box runs all the build steps in Debug mode even if you have not selected the Run Step in Debug Mode check box when configuring any of the build steps.