Creating a configuration file
This topic describes how to create a configuration file.
Before you begin
Perform the procedures described in the Preparing-for-configuration topic.
To create a configuration (Config YAML) file
Use the following procedure to create a configuration file in your CI/CD tool supported repository:
Config YAML file for Universal Connector application
The config YAML file for the Universal Connector application is a YAML formatted document. The Universal Connector application contains the following two applications:
Universal Connector Common application processes are as follows:
- authentication
- fileDownload
- fileUpload
- jclExecutionUsingFile
- jclExecutionUsingFreeForm
- jclExecutionUsingPDSMember
Universal Connector application processes are as follows:
Important
- The config file must reside in your CI/CD tool supported repository.
- The config file name can be any name as long as it is YAML or yml file type.
- The version number must be specified at the top of the config YAML file.
- The minimum version for use with SQL Assurance is 2.0.0.
- All property keys must be followed by a colon and then a space.
- The stepName property key must be preceded by a dash and then a space.
For values with multiple lines, specify the pipe character (|) on the same line after the property key. On the following line, indent the values.
ExamplejobCard: |
//JOBNM JOB ($[acctno]),'COMPARE',
// CLASS=Q,MSGLEVEL=(1,1),NOTIFY=&SYSUID- For property key values with special characters [( { } , : [] & * ? | - > ' " % @ `)], it is recommended to use either single or double quotes for the values in the YAML files to avoid any unexpected error or result.
- The names for the application processes, which are defined in the configuration file, must be exact (see application process listed above). The application process name is only allowed one definition in the configuration file.
The stepName may have multiple unique definitions for each application process, except authentication.
ExamplefileDownload:
- stepName: mainframe_to_local_Test1
debugMode: false
…
- stepName: mainframe_to_local_Test2
debugMode: false- The authentication application does not have a stepName definition and allows one definition in the configuration file.
- does not support values with more than 1 hash (#) character (for example, TEST#1.OBJNM#), since this is reserved for plug-in variables.
authentication
The authentication application is the first step in the process that enables you to connect securely to the corresponding mainframe host on which z/OSMF is running.
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.
- Ensure that you enter the corresponding port number of the LPAR in the SYSPLEX on which z/OSMF is running on the mainframe.
Click here for information about this execution step
The following table lists the authentication property keys:
Property key | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
debugMode | (Optional) The debugMode property key specifies whether this step should issue additional messages in the Console Output log file. Valid values are as follows:
| ||||||||||||
hostName | (Required) The hostName property key specifies the Mainframe (host name or IP address) field as one of the two values that identify the mainframe server:
The mainframe server must be a LPAR on which the communication medium is installed. | ||||||||||||
port | (Required) The port property key specifies the port that communication medium uses on a mainframe TCP/IP network. Default port for z/OSMF=32208 but may vary at different sites. | ||||||||||||
authenticationType | (Required) The authenticationType property key specifies the type of authentication to be performed. Valid values are as follows:
| ||||||||||||
symbolicPropertiesFilePath | (Required) The symbolicPropertiesFilePath property key identifies the directory and file name where the plug-in variables file is stored. The plug-in variables file defines the variables and values that the plug-in uses. You can provide any name for the plug-in variables file, but you must use the .properties file extension. The default name of the plug-in variables file is AMI_DevOps.properties. The symbolicPropertiesFilePath property key should be the relative path of the plug-in variables file with respect to the source code repository root.
| ||||||||||||
debugModeAllSteps | (Optional) The debugModeAllSteps property key specifies whether to run all pipeline or workflow steps in debug mode. The authentication property, debugModeAllSteps: true overrides the debugMode: false property for all steps which have been configured in the pipeline or workflow. Valid values are as follows:
| ||||||||||||
executionIdentifier | (Required) The executionIdentifier property key specifies the following values in the steps of Console Output log file. where PIPELINENAME_VALUE, RUNNUMBER_VALUE, RUNBY_VALUE and RUNMODE_VALUE are placeholders defined as variables.
|
fileDownload
You can use the fileDownload application to transfer PDS members from the mainframe environment to a container workspace. This property has a list of map values.
Click here for information about this execution step
The following table lists the fileDownload property keys:
Property key | Description |
---|---|
- stepName | (Required) The stepName property key specifies a user-defined step name for the application process. This stepName is then referenced in the pipeline or workflow YAML file. |
debugMode | (Optional) The debugMode property key specifies whether this step should issue additional messages in the Console Output log file. Valid values are as follows:
|
sourcePds | (Required) The sourcePds property key specifies the partitioned data set (PDS) on the mainframe from which a member is transferred. |
sourceMember | (Required) The sourceMember property key specifies the member on the mainframe that is transferred. |
destinationDirectory | (Required) The destinationDirectory property key specifies the directory to which a file is received. This property key supports relative paths. If you do not enter any path or enter a period (.), this application considers the relative path with respect to the workspace.
|
destinationFileName | (Required) The destinationFileName property key specifies the file name to be created in the agent workspace directory. This is always saved in the agent workspace directory. |
fileUpload
You can use the fileUpload application to transfer files from a container workspace to a mainframe environment. This property has a list of map values.
Click here for information about this execution step
The following table lists the fileUpload property keys:
Property key | Description |
---|---|
- stepName | (Required) The stepName property key specifies a user-defined step name for the application process. This stepName is then referenced in the pipeline or workflow YAML file. |
debugMode | (Optional) The debugMode property key specifies whether this step should issue additional messages in the Console Output log file. Valid values are as follows:
|
sourceDirectory | (Required) The sourceDirectory property key specifies the directory on the client from which a file is transferred. $(Agent.BuildDirectory)/s |
sourceFileName | (Required) The sourceFileName property key specifies the file on the client that is transferred. For example, the sourceFileName might be the client DDL file. |
destinationPds | (Required) The destinationPds property key specifies the partitioned data set (PDS) on the mainframe to which a member is received. |
destinationMember | (Required) The destinationMember property key specifies the member on the mainframe where the file is received. |
jclExecutionUsingFile
You can use the jclExecutionUsingFile application to submit JCL from a file on the container workspace.
Click here for information about this execution step
The following table lists the jclExecutionUsingFile property keys:
Property key | Description |
---|---|
- stepName | (Required) The stepName property key specifies a user-defined step name for the application process. This stepName is then referenced in the pipeline or workflow YAML file. |
debugMode | (Optional) The debugMode property key specifies whether this step should issue additional messages in the Console Output log file. Valid values are as follows:
|
jclDirectory | (Required) The jclDirectory property key specifies the directory on which a JCL file is located. |
jclFileName | (Required) The jclFileName property key specifies the JCL file on the CI\CD agent. |
acceptableReturnCode | (Required) The acceptableReturnCode property key specifies the maximum return code value that communicates that the submitted job was successful.
Valid values are 0000 through 9999. The default value is 0004. |
maxJobWaitTime | (Required) The maxJobWaitTime property key specifies the maximum length of time in minutes that the application waits for job completion from the mainframe. If the time for the response exceeds the maximum job wait time, the application terminates the build step and stops subsequent processing. Valid values are 1 through 60. The default value is 2. |
jclExecutionUsingFreeForm
You can use the jclExecutionUsingFreeForm application to submit JCL Statements supplied for execution.
Click here for information about this execution step
The following table lists the jclExecutionUsingFreeForm property keys:
Property key | Description |
---|---|
- stepName | (Required) The stepName property key specifies a user-defined step name for the application process. This stepName is then referenced in the pipeline or workflow YAML file. |
debugMode | (Optional) The debugMode property key specifies whether this step should issue additional messages in the Console Output log file. Valid values are as follows:
|
freeFormJcl | (Required) The freeFormJcl property key specifies the entire JCL statements to generate a JCL job for submission. |
acceptableReturnCode | (Required) The acceptableReturnCode property key specifies the maximum return code value that communicates that the submitted job was successful.
Valid values are 0000 through 9999.The default value is 0004. |
maxJobWaitTime | (Required) The maxJobWaitTime property key specifies the maximum length of time in minutes that the application waits for job completion from the mainframe. If the time for the response exceeds the maximum job wait time, the application terminates the build step and stops subsequent processing. Valid values are 1 through 60. The default value is 2. |
jclExecutionUsingPDSMember
The jclExecutionUsingPDSMember application enables you to submit JCL from a data set on the mainframe.
Click here for information about this execution step
The following table lists the jclExecutionUsingPDSMember property keys:
Property key | Description |
---|---|
- stepName | (Required) The stepName property key specifies a user-defined step name for the application process. This stepName is then referenced in the pipeline or workflow YAML file. |
debugMode | (Optional) The debugMode property key specifies whether this step should issue additional messages in the Console Output log file. Valid values are as follows:
|
jclPds | (Required) The jclPds property key specifies the partitioned data set (PDS) on the mainframe where a member is located. |
jclMemberName | (Required) The jclMemberName property key specifies the PDS member on the mainframe. |
acceptableReturnCode | (Required) The acceptableReturnCode property key specifies the maximum return code value that communicates that the submitted job was successful.
Valid values are 0000 through 9999.The default value is 0004. |
maxJobWaitTime | (Required) The maxJobWaitTime property key specifies the maximum length of time in minutes that the application waits for job completion from the mainframe. If the time for the response exceeds the maximum job wait time, the application terminates the build step and stops subsequent processing. Valid values are 1 through 60. The default value is 2. |
analyzeStaticSql
The analyzeStaticSql application enables you to perform analysis on your application's static SQL statements which includes running an explain on the SQL and comparing the SQL statements to the SQL violation rules.
Click here for information about this execution step
The following table lists the analyzeStaticSql property keys:
Property key | Description |
---|---|
- stepName | (Required) The stepName property key specifies a user-defined step name for the application process. This stepName is then referenced in the pipeline or workflow YAML file. |
debugMode | (Optional) The debugMode property key specifies whether this step should issue additional messages in the Console Output log file. Valid values are as follows:
|
generateJclOnly | (Optional) The generateJclOnly property key controls whether the build step JCL is generated without running the step. Use this feature to validate the JCL from the Console Output log. Valid values are as follows:
|
ssid | (Required) The ssid property key specifies the Db2 subsystem ID where the Static SQL statements reside. |
violationResponse | (Required) The violationResponse property key specifies how the application reacts if it encounters a rule violation. Valid values are as follows:
|
explainMethod | (Required) The explainMethod property key specifies the process to be used for the SQL statement Explain. Valid values are as follows:
|
objectType | (Required) The objectType property key specifies the type of objects processed in analyzeStaticSql. Valid values are as follows:
|
objectName | (Required) The objectName property key specifies the name of the object to be explained. Use this property key for Plan and Package object types. Leave this property key blank when using an object list file. |
collectionIdPackage | (Required) The collectionIdPackage property key specifies the package collection ID for the explain. Leave this property key blank when using an object list file or objectType is Plan. |
versionPackage | (Required) The versionPackage property key specifies the package version for the explain. Leave this property key blank when using an object list file or objectType is Plan. |
useObjectListFile | (Optional) The useObjectListFile property key is used to perform the Explain process with the property key, objectListFilePath, as input, instead of the individual property keys (objectName, collectionIdPackage, versionPackage). Valid values are as follows:
|
objectListContinueOnError | (Optional) The objectListContinueOnError property key specifies the option to process records, in the object list file, up to the 100 record limit. If true is specified, this option will ignore the invalid records and records beyond the 100 record limit. If false is specified, the step will stop processing when an error for an object is encountered. Valid values are as follows:
|
objectListFilePath | (Optional) The objectListFilePath property key specifies the object list directory and file name to be used for SQL Assurance analysis when the useObjectListFile property key is set to true. The object list includes a list of all plans or packages, depending on the objectType property key specified. The object list file should be a text file with .txt extension. Click here for Object List File configuration details:
Important
|
jobCard | (Required) The jobCard property key specifies the JOB statement and additional information in the mainframe JCL. This statement provides the job name, account number, and any keyword parameters (such as CLASS, MSGCLASS, REGION, or TIME). A sample jobcard is as follows, the definition will vary based on site requirements: //COBSSQL JOB (#acctno#),'STATIC-SQL', // CLASS=A,MSGLEVEL=(1,1) //* |
sqlExplorerInputStream | (Required) The sqlExplorerInputStream property key contains the DD names and parameter values that the Explain process uses. The default values are as follows: Click here for PLAN//PSSMAIN.SYSIN DD * --NEWOBJ OBJECT=PLAN NAME="${objectName}" RULES="$[rules]" RULEDSN="$[ruledsn]" PLANTBL="${explainMethod}" CURRENCY="$[currency]" MSGLEVEL=ALL --ENDOBJ Click here for PACKAGE//PSSMAIN.SYSIN DD * --NEWOBJ OBJECT=PACKAGE NAME="${objectName}" COLLID="${collectionIdPackage}" VERSION="${versionPackage}" RULES="$[rules]" RULEDSN="$[ruledsn]" PLANTBL="${explainMethod}" CURRENCY="$[currency]" MSGLEVEL=ALL --ENDOBJ |
jcl | (Required) The jcl property key contains the statements that SQL Assurance needs to analyze the provided objects. The default value is as follows: ${jobCard} //* // JCLLIB ORDER=($[proclib]) //* //JOBLIB DD DSN=$[joblib1],DISP=SHR // DD DSN=$[joblib2],DISP=SHR // DD DSN=$[dsnexit],DISP=SHR // DD DSN=$[dsnload],DISP=SHR //*************************************************** //* // SET RTEHLQ=$[rtehlq] // SET USRHLQ=$[usrhlq] //* // EXPORT SYMLIST=(*) //* // SET SSID=${ssid} // SET PSSPLAN=$[pssplan] // SET GUDPLAN=$[gudplan] // SET GENDEBUG='${debugMode}' // SET LOGMODE='${violationResponse}' // SET RULSPACE='SPACE=(CYL,(10,10)),' // SET VTIBSZ=20 //*----------------------------------------------------------------- //* //SQLXPLOR EXEC COBPRPSS ${sqlExplorerInputStream} //RULESOUT.SYSUT2 DD &GENDEBUG //*----------------------------------------------------------------- //* //IFPSS IF (SQLXPLOR.PSSMAIN.RC EQ 4) THEN //COBLOGER EXEC COBPRLOG //LOGGER.AS$INPUT DD DSN=&&RULESOUT, // DISP=(OLD,DELETE) //IFPSSEND ENDIF //* |
maxJobWaitTime | (Required) The maxJobWaitTime property key specifies the maximum length of time in minutes that the application waits for job completion from the mainframe. If the time for the response exceeds the maximum job wait time, the application terminates the build step and stops subsequent processing. Valid values are 1 through 60. The default value is 15. |
analyzeDynamicSql
The analyzeDynamicSql application builds JCL to extract SQL statements, for a subsystem, from the Dynamic Statement Cache in the DSN_STATEMENT_CACHE_TABLE based on your Dynamic Statement Cache and SQL rules input. The product subsequently performs an Explain and compares the SQL statements to the SQL rules.
Click here for information about this execution step
The following table lists the analyzeDynamicSql property keys:
Property key | Description |
---|---|
- stepName | (Required) The stepName property key specifies a user-defined step name for the application process. This stepName is then referenced in the pipeline or workflow YAML file. |
debugMode | (Optional) The debugMode property key specifies whether this step should issue additional messages in the Console Output log file. Valid values are as follows:
|
generateJclOnly | (Optional) The generateJclOnly property key controls whether the build step JCL is generated without running the step. Use this feature to validate the JCL from the Console Output log. Valid values are as follows:
|
ssid | (Required) The ssid property key specifies the Db2 subsystem ID where the dynamic statement cache is analyzed. |
violationResponse | (Required) The violationResponse property key specifies how the application reacts if it encounters a rule violation. Valid values are as follows:
|
dsnStatementCacheTableCreator | The dsnStatementCacheTableCreator property key specifies the table creator name of the DSN_STATEMENT_CACHE_TABLE to be used in the extract of the SQL statements. If left blank, the default value is the TSO user running the application. Important The DSN_STATEMENT_CACHE_TABLE must exist for this table creator in order to use it. |
clearDsnStatementCacheTable | (Optional) The clearDsnStatementCacheTable property key specifies to remove all rows from the DSN_STATEMENT_CACHE_TABLE before the EXPLAIN STMTCACHE ALL command is performed. Valid values are as follows:
|
extractSqlFromDynamicStatementCache | (Optional) The extractSqlFromDynamicStatementCache property key copies the SQL statements from the Dynamic Statement Cache to the DSN_STATEMENT_CACHE_TABLE before the explain and SQL rules evaluation. Valid values are as follows:
|
failStepIfWhereClauseReturnsNoResultSet | (Optional) The failStepIfWhereClauseReturnsNoResultSet property key specifies to fail the application step if no data is returned from the DSN_STATEMENT_CACHE_TABLE query using the whereClauseStatement property key. Valid values are as follows:
|
whereClauseStatement | (Required) The whereClauseStatement property key specifies the WHERE clause predicates used to query the DSN_STATEMENT_CACHE_TABLE. This must be valid SQL syntax. Example - single line predicate: whereClauseStatement: PRIMAUTH = USER AND CACHED_TS > CURRENT TIMESTAMP - 1 HOUR Example - multiple line predicate: Important The multiple-line predicate must be indented and requires the pipe continuation character after the property key name. whereClauseStatement: | PRIMAUTH = USER AND CACHED_TS > CURRENT TIMESTAMP - 1 HOUR |
jobCard | (Required) The jobCard property key specifies the JOB statement and additional information in the mainframe JCL. This statement provides the job name, account number, and any keyword parameters (such as CLASS, MSGCLASS, REGION, or TIME). A sample jobcard follows, definition will vary based on site requirements: //COBDSQL JOB (#acctno#),'DYNAMIC-SQL', // CLASS=A,MSGLEVEL=(1,1) //* |
extractorInputStream | (Required) The extractorInputStream property key contains the DD names and parameter values that the Extractor and Explain processes use. //EXTRACT.PARMIN DD *,SYMBOLS=JCLONLY SSID=&SSID, PLAN=&GUDPLAN, DSNTRUNC=&DSNTRUNC, DSNEXPL=&DSNEXPL, DSNQUAL=&DSNQUAL //EXTRACT.SE$OPTS DD * ${whereClauseStatement} //EXTRACT.PSS$OPTS DD * RULES="$[rules]" RULEDSN="$[ruledsn]" CURRENCY="$[currency]" MSGLEVEL=ALL |
jcl | (Required) The jcl property key contains the statements that SQL Assurance needs to analyze the provided dynamic SQL. The default value is as follows: ${jobCard} //* // JCLLIB ORDER=($[proclib]) //* //JOBLIB DD DSN=$[joblib1],DISP=SHR // DD DSN=$[joblib2],DISP=SHR // DD DSN=$[dsnexit],DISP=SHR // DD DSN=$[dsnload],DISP=SHR //* // SET RTEHLQ=$[rtehlq] // SET USRHLQ=$[usrhlq] //* // EXPORT SYMLIST=(*) //* // SET SSID=${ssid} // SET PSSPLAN=$[pssplan] // SET GUDPLAN=$[gudplan] // SET DSNQUAL=${dsnStatementCacheTableCreator} // SET DSNTRUNC=${clearDsnStatementCacheTable} // SET DSNEXPL=${extractSqlFromDynamicStatementCache} // SET GENDEBUG='${debugMode}' // SET LOGMODE='${violationResponse}' // SET RULSPACE='SPACE=(CYL,(50,10)),' // SET VTIBSZ=20 //*----------------------------------------------------------------- //* //XTRACT EXEC COBPRXTR,PARMDD.EXTRACT=PARMIN ${extractorInputStream} //XTROUT.SYSUT2 DD &GENDEBUG //* //*----------------------------------------------------------------- //* //IFXTR IF (XTRACT.EXTRACT.RC LT 4) THEN //SQLXPLOR EXEC COBPRPSS //PSSMAIN.SYSIN DD DISP=(OLD,DELETE),DSN=&&XTROUT //RULESOUT.SYSUT2 DD &GENDEBUG //*----------------------------------------------------------------- //* //IFPSS IF (SQLXPLOR.PSSMAIN.RC EQ 4) THEN //COBLOGER EXEC COBPRLOG //LOGGER.AS$INPUT DD DSN=&&RULESOUT, // DISP=(OLD,DELETE) //IFPSSEND ENDIF //IFXTREND ENDIF |
maxJobWaitTime | (Required) The maxJobWaitTime property key specifies the maximum length of time in minutes that the application waits for job completion from the mainframe. If the time for the response exceeds the maximum job wait time, the application terminates the build step and stops subsequent processing. Valid values are 1 through 60. The default value is 15. |
-
13.1
- 12.1