Skip to end of metadata
Go to start of metadata

IBM z/OS Connector is a plugin which lets you connect your Jenkins to z/OS.

Plugin Information

View IBM z/OS Connector on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:


Build Status

About

This plugin provides its functions via FTP connection to IBM z/OS LPAR. You can configure your SCLM project on z/OS and then check for the changes via Jenkins.

Features include:

  • Submission of user JCL job (with optional log collected upon finish)
  • Introduction of SCLM as SCM for your projects allowing to ceckout SCLM changes
    • The ability to build SCLM projects currently can be performed only via 'Submit zOS Job' build action

Version differences

Kindly back up your JCL texts before upgrading to version 2.0.0.
The 2.0 release uses text files instead of plaintext input, so old jobs will become obsolete.

Configuration

JESINTERFACELEVEL differences

Job Name must be configured accordingly to your FTP server configuration:

  • If JESINTERFACELEVEL=1 is configured, only a job named USERIDx (USERID - your z/OS user ID, x - strictly 1 character) can be processed correctly (when you are waiting for the job to end).
  • If JESINTERFACELEVEL=2 is configired, no additional considerations are required.

Change log

Version 2.2.0
  • (warning) Logout of the FTP server as soon as single request is performed.
    This will result in increased number of connect → login → logout → disconnect sequences, but should also make plugin more stable.
Version 2.1.0
  • (warning) Environment variables are once again expanded before job submission (JENKINS-55609)
Version 2.0.1
  • (error) Fix false positive error message if not waiting on job completion (JENKINS-54574)
Version 2.0.0
  • (lightbulb) Use credentials instead of username-password pair
  • (lightbulb) Use text file with JCL code instead of plaintext field (if you need to track SCLM in the same job - consider using Multiple SCMs plugin)
Version 1.2.6.1
  • (lightbulb) Option to print JES job log
Version 1.2.6
  • (lightbulb) Update failure logic for slow JES initiators
Version 1.2.5
  • (warning) Use Jenkins 2+
Version 1.2.4.1
  • (warning) Add notification about incompatibility since 1.2.4.
Version 1.2.4
  • (lightbulb) Provide different messages into the build log based on the job completion code (JENKINS-31837)
Version 1.2.3
  • (error)   JESINTERFACELEVEL=1 output changes and configuration corrections.
Version 1.2.2
  • (plus)   JESINTERFACELEVEL=1 support.
Version 1.2.1
  • Dummy release
Version 1.2.0.2
Version 1.2.0.1
  • (error)   Add error message if job is not listed while waiting for its execution to end (possible problem with JESINTERFACELEVEL=1).
Version 1.2.0
  • (plus)   Add JobName to output log file name. Change log file naming convention.
Version 1.1.1
  • (plus)   Add environment variables expansion for "Submit z/OS job" build step. Add loggers.
Version 1.1.0
  • (plus)   Add MaxCC papameter to 'Submit z/OS job' build step (JENKINS-29214)
Version 1.0.4
  • (plus)   Add support for 'RC unknown'.
Version 1.0.3

67 Comments

  1. Hello, I need to build job name dynamically based on Jenkins logged in user. ${BUILD_USER_ID} from build user var plug-in substitutes correct username as job name in JCL, however in spool it says job name XXXXX is not a valid job as its character are not alphanumerical, where XXXXX being actual user name from Jenkins which is alpha-numeral. Has anyone tried this before, is this even a correct approach. Appreciate any suggestions.

    1. Kindly check that what is used is in upper-case.

      Additionally, you can open an issue for the plugin and contact me for the debugging.

  2. We are experiencing issues where for some reason the job can't be found in the JES log. However the job is visable when logged into TSO

    Example -

    ERROR: Job [JOB63581] cannot be found in JES
    Job [JOB63581] processing failed. Reason: [JOB_NOT_FOUND_IN_JES]
    ERROR: z/OS job failed with CC JOB_NOT_FOUND_IN_JES


    From TSO -

    Any pointers on what the issue could be ?

    1. Check JESINTERFACELEVEL setting.

      1. The JESINTERFACELEVEL seems to be OK as we have 7 jobs that run OK and then on the 8th we get the above failure

        1. Set the logging for the plugin, especially, ZFTPConnector class. And JIRA issue would be nice.

          Note: this log will also log your creds - cut them out!

  3. Is there any plugin for Mainframe Deployment through Jenkins? Can this plugin be used for deployment to Mainframe. I see this plugin (Z/OS connector plugin) handles Build and Test but no to the Deployment. Please provide comment/suggestion.

  4. Is there any plugin for Mainframe Deployment through Jenkins? Can this plugin be used for deployment to Mainframe. I see this plugin (Z/OS connector plugin) handles Build and Test but no to the Deployment. Please provide comment/suggestion.

    1. No, no such functionality is supported currently.

      You can try using this + ftp upload to mimic such behaviour.

  5. Thanks Alexander for quick response. Can you suggest any plugin for that? I tried FTP=Publisher and Publish Over, both don't support upload to Mainframe.

  6. Hello Alexander,

    I'm running a 13 step job using the z/os plugin and I'm getting this error 

    JOB_NOT_FOUND_IN_JES My JESINTERFACELEVEL it set to 2 
    How do i set this

    Set the logging for the plugin, especially, ZFTPConnector class. And JIRA issue would be nice.

    Note: this log will also log your creds - cut them out!

  7. Hello Alexander,

     

    Here is what was in the log

     

    Job [J0511419] processing finished.
    
    Shared Services 17 JCL to do the RFN install 181: will expand variables
    
    Shared Services 17 JCL to do the RFN install 181: Created ZFTPConnector
    
    Shared Services 17 JCL to do the RFN install 181: FTP: connected to cw01:21
    
    Shared Services 17 JCL to do the RFN install 181: Submitted job [J0511421]
    
    Shared Services 17 JCL to do the RFN install 181: Job [J0511421] cannot be found in JES
    
    Job [J0511421] processing finished.
    1. Hi Scott,

      I've just sent you a reply e-mail.

  8. Hello, I'm trying this plugin to run simple jcl file from Windows-OS to Mainframe. I have set up setting like on the image:

     

    but when I run Jenkins it gives me IO_Error like this: 

    What should I do to solve this problem?

    1. Hello Vladik,

      The path to JCL is the relative path to the job workspace. 

      1. So, I put my jcl-file to the Jenkins workspace which I can see in the Jenkins report, like this:

        But I still have the same problem - IO_Error.

        What am I doing wrong?

        1. Let's say that you've put your file in the root of the workspace. Then you need to simply set the path to JCL as JUST the name of the file (job workspace is automatically appended before the path you specify).

          If you have a directory inside workspace and the file is in that directory - specify the path to file including this directory - just like you would've done if you were viewing the workspace directory in terminal and specified the path relative to your position.

          1. So, I put this file in the right place, in this directory: C:\Program Files (x86)\Jenkins\workspace\RunningJCL and my relative path looks like just name of the file:

            Anyway, I have tried previous version of your plugin and just write my jcl-code instead of file name. And Jenkins has given me the same error. So, I do not think that the problem is in the file path.

            Could it be that the problem is different?

            1. It might be related to RACF config for FTP JES usage (you would need to be able to submit jobs via FTP. I'd dtart by checking that you can do this manually from terminal).

              1. I have tried run JCl just by using ftp through cmd. And it has worked well, job was submitted. So, maybe I should change some settings in the Jenkins, shouldn't I?

                1. Also I found jenkins log-file, you can see its messages below:

                  Maybe it will be useful

                  1. Wow this site works weird, all my images which I uploaded here from one file, now look like last version of this file O_o

                    Sorry for that.

                  2. Check the notice about jesinterfacelevel in the description. You have to set this option and use proper job name. 

                    1. Hello again. I think I use right job name.

                      //USER**A JOB ,
                      // MSGCLASS=H,MSGLEVEL=(1,1),TIME=(,4),REGION=64M,NOTIFY=USER**

                      These are first two strings in my jcl file. So as you can see job has the name like my userID plus one character. And this configuration don't work.

                      I have tried different option in check-box, but it also hasn't worked.

                      1. IDK, you might need to check the ftp submission from terminal on the cI machine. Otherwise it seems strange.

                        1. Ok, thx, I will try to find decision.

  9. Hi Folks,

    Does that Plugin work fine with Jenkins Pipeline as well?

    If YES, somebody could send me a sample/example?

    Tks in advance!

     

     

  10. I wish you kept the JCL text box with your enhancement. I have no problem with the file, but this makes it very hard to change the 50+ jobs I have using this plugin.

    1. I had experience with lots of steps with ~300 lines of JCL each, so I decided to make config page cleaner and enforce proper configuration practices.

      Sorry that it made you revisit such lot of jobs. You might want to try autogeneration + DSL (groovy?) and pipelines with the new version, I think.

  11. When I give the JCL in PDS in the Job, Though. Its not working. Please let me know if we need to give the Job as text file and if yes where should I place the file. Below is the error im getting.

    Building remotely on docker-140d08474ab63 on BuildSwarm (docker-slave) in workspace /home/jenkins/workspace/IBM Zos conn FTP: connected to IP address Job [] processing failed. Reason: [IO_ERROR] ERROR: z/OS job failed with CC 0000 Finished: FAILURE

  12. How to place the JCL in the Jenkins work space whose path needs to be given in jobfile of the 'submit z/os job'

  13. Hello,


    When I use the following script

    step([$class: 'ZOSJobSubmitter', JESINTERFACELEVEL1: false, MaxCC: '0004', credentialsId: '**********', deleteJobFromSpool: true, jobFile: 'PKG.txt', jobLogToConsole: false, port: 21, server:****, wait: true, waitTime: 0])

    it gives the me below error

    FTP: connected to ****:21
    Job [] processing failed. Reason: [COULD_NOT_CONNECT]


    Please can you suggest what may have gone wrong

    1. Check credentials and try connecting to your LPAR from console on ci machine.

      1. Thanks! I will try doing that and let you know 

        1. we are able to use curl command and download mainframe files onto jenkins workspace but still facing below 

          FTP: connected to ****:21
          Job [] processing failed. Reason: [COULD_NOT_CONNECT]


          It looks like it established a connection but job processing failed

          1. First and foremost, you need to UPLOAD files to LPAR in order to submit job.

            Secondly, use ftp command instead of curl. Try submitting the job from some file in workspace manually (you can find a lot of instructions how to submit job to z/OS via FTP).

  14. Hi , I have installed this plugin on Jenkins. Is there any document, which can help me to start working on it?

    1. Hi Shalini,

      I tried my best to make the 'Submit z/OS Job' build step and SCLM CVM adapter as simple as possible. IDK if any additional info apart from the one present in wiki could be required for most cases.

  15. Hi Alexander,

    I am getting build log as below

    Submitted job [JOB04822]
    Job [JOB04822] processing failed. Reason: []
    Finished: SUCCESS

    although my job is getting completed successfully. Is there a way to correct the statement 

    "Job [JOB04822] processing failed."
    1. Can you share the config you're using?

      Also, could you reproduce and collect logs for 

  16. Hi Alexander, 

    Attached are the config and log file.




    1. In your run (from where the log is) did you see 'processing failed'?

  17. Below is the complete log from  " jenkins.err " file for the jobs submitted today:

    Nov 12, 2018 12:42:08 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZOSJobSubmitter perform
    INFO: Test 23: will expand variables
    Nov 12, 2018 12:42:08 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZFTPConnector log
    INFO: Test 23: Created ZFTPConnector
    Nov 12, 2018 12:42:08 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZFTPConnector log
    INFO: Test 23: FTP: connected to 10.108.92.20:21
    Nov 12, 2018 12:42:10 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZFTPConnector log
    INFO: Test 23: Submitted job [JOB04903]
    Nov 12, 2018 12:42:10 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZOSJobSubmitter perform
    INFO: Job [JOB04903] processing finished.
    Nov 12, 2018 12:42:10 AM hudson.model.Run execute
    INFO: Test #23 main build action completed: SUCCESS
    Nov 12, 2018 12:42:12 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZOSJobSubmitter perform
    INFO: Test 24: will expand variables
    Nov 12, 2018 12:42:12 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZFTPConnector log
    INFO: Test 24: Created ZFTPConnector
    Nov 12, 2018 12:42:12 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZFTPConnector log
    INFO: Test 24: FTP: connected to 10.108.92.20:21
    Nov 12, 2018 12:42:14 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZFTPConnector log
    INFO: Test 24: Submitted job [JOB04904]
    Nov 12, 2018 12:42:14 AM org.jenkinsci.plugins.IBM_zOS_Connector.ZOSJobSubmitter perform
    INFO: Job [JOB04904] processing finished.
    Nov 12, 2018 12:42:14 AM hudson.model.Run execute
    INFO: Test #24 main build action completed: SUCCESS


    There is no 'processing failed' message. i could not find the same in "jenkins.out" file. Let me know if i need to check the logs in a different file.

    1. I have created JENKINS-54574 for this. Is fixed in version 2.0.1.

      Basically, it was caused by you not using 'wait for completion'.

      1. Thank you , Alexander.

  18. Hello Alexander,

    Can interpolation of a parameter be done in the new JCL text file?

    I tried using "${PARM}" in the JCL text file but it is not working. Please advise.

    Thank you,

    MArk

    1. No, not really. Only file name itself will be expanded.

      1. Thanks for confirming Alexander.

  19. Hi, We have submitted a job from Jenkins master to Z/OS. A simple JCL routine. Its getting compile successfully but on the jobs console log we are getting following error:

    FTP: connected to x.x.x.x:21
    Submitted job [JOB07200]
    ERROR: Could not connect to server.
    FTP: connected to x.x.x.x:21
    ERROR: Could not connect to server.
    Job [JOB07200] processing failed. Reason: [FETCH_LOG_ERROR_LOGIN]

    ERROR: z/OS job failed with CC FETCH_LOG_ERROR_LOGIN
    Finished: FAILURE


    I've replaced machine IP with X for security purpose.

    1. Try new 2.2.0 version - it has updated connection logic.

      1. Hi, we tried with version 2.2.0 and this time it gave following error.


        ERROR: Failed to log out from FTP server
        FTP: connected to x.x.x.x:21
        FTP: connected to x.x.x.x:21
        FTP: connected to x.x.x.x:21
        ERROR: Failed to log out from FTP server
        Job [JOB24154] processing failed. Reason: [WAIT_ERROR]
        ERROR: z/OS job failed with CC WAIT_ERROR
        Finished: FAILURE
        1. now it seems as if the job hasn't finished yet.  (check timeout settings, you can set wait time to 0 to wait forever)

          1. Job completed successfuly on Z/OS. we set timeout to 0; but this even did not work. Each time Jenkins tried to made FTP connection. I think something need to be checked at code level.

            1. reconnects are expected with the latest version.

              As for the timeout - need more stuff to investigate, fell free to send me e-mail.

  20. Hi, I'm trying to run simple jcl file using this plugin  My setup is as follows


    the console output and log  I get is as follows

    1. Are you really not curious if the credentials you provided are correct? Why?

  21. I did double check the credentials and verified them with other FTP submit application and they work.

    1. Add ticket with problem. Attach all required logs, send me e-mail to investigate this further.

  22. Are there any future plans to support plain text input again?

    The 'version differences' states that old jobs with plain text input will become obsolete, though, re-configuring many plain text JCL(s) to version 2.0.0 is not feasible.  Have any considerations been made in this area?

    1. No, not planning to revert

  23. Hi,

    We tried with Jenkins version 2.167 and IBM Z/OS Connector version 2.2.0, I am facing below error as:

    20:10:52 Started by user Administrator
    20:10:52 Running as SYSTEM
    20:10:52 Building remotely on OS-309-SYST (syst_test)JDK installation skipped: Unknown CPU name: z/os
    20:10:52  in workspace /shared_automount/autousers/srs0168/workspace
    20:10:52 JDK installation skipped: Unknown CPU name: z/os
    20:10:52 JDK installation skipped: Unknown CPU name: z/os
    20:10:52 FTP: connected to 193.x.x.x:21
    20:10:52 Submitted job [*UNKNOWN]
    20:11:02 FTP: connected to 193.x.x.x:21
    20:11:06 ERROR: Job [*UNKNOWN] cannot be found in JES
    20:11:06 FTP: connected to 193.x.3.x:21

    ===============================================================

    I have done the configurations as given below:


    Jenkins workspace directory in Mainframe:

    Jenkins Agent

    ========

    zOS Agent Remote root directory : /shared_automount/autousers/srs0168/workspace. Under this workspace - test1


    zOS job config

    =========


    ZOS Config

    ==========

    /shared_automount/autousers/srs0168/workspace/

    cat test1

    quote SITE FILEtype=JES NOJESGETBYDSN
    GET 'PUBALL.SUBMITS.CNTL(JPH001)' 'jes.log'


    Please advise what I am missing in this case.

    1. You need to put the JCL contents into test1.

  24. Thanks for update. Tried with JCL contents but still getting same error.

    1. I've never tested this with Jenkins slave on z/OS - you don't need this for the plugin to work.

      Also, I'd look into JESINTERFACELEVEL setting on the LPAR you intend the JCL to run at.

      Additionally, this might be encoding issue?

  25.  I've never tested this with Jenkins slave on z/OS - you don't need this for the plugin to work.

    Sitansu Dash Could you please explain in more details about -  "you don't need this for the plugin to work" ?

    Also, I'd look into JESINTERFACELEVEL setting on the LPAR you intend the JCL to run at.

    Sitansu Dash  JESINTERFACELEVEL specified to 1.

    Additionally, this might be encoding issue?

    Sitansu Dash Agent JVM Options speciefied to -Dfile.encoding=utf-8 -Xnoargsconversion. Please let me know if  referring something different then this.





      1. The plugin just needs FTP access to LPAR from the machine it will be run (Jenkins slave/master) and proper configuration to be run there.
      2. See info about proper job namimg in case JESINTERFACELEVEL=1 on this wiki page.
      3. utf-8 should be fine - if the file on LPAR is in UTF-8. if it gets converted to EBCDIC - ??