Using the JCL_FTP Definition Type

The JCL_FTP Definition Type works with a zero footprint or agentless agent. In other words, no Redwood software needs to be installed on the mainframe. The agent that performs the submit to JES via a (remote) internal reader runs on a UNIX or Microsoft Windows system. JES2 or JES3 processes the job itself. As with all Definition Types, you must assign at least one Process Server the JCL_FTP Definition Type in order for that Process Server to perform the task and be assigned. The actual work of executing the job is done fully by the mainframe itself.

When Redwood Server submits the job it first sends it to (one of) the Platform Agent(s) that is assigned the JCL_FTP Definition Type. On that server, the job processor runs and contacts the z/OS server over TCP/IP via the FTP protocol. It switches to the JES interface instead of the normal file interface and submits the job to JES. Once the job is submitted, it polls to see if the job is finished. Once the job is finished, it attempts to retrieve the process's output datasets and puts each of them into a different Redwood Server output file. It also translates the JES job outcome into a Redwood Server process status (ERROR or COMPLETED).

Note: You must have the ProcessServerService.JCL_FTP license key to use the JCL_FTP job Definition Type.

The source of a JCL_FTP process contains either a complete job description consisting of JCL, or a single line naming a DSN containing the JCL on the mainframe. A JCL coding starts with a line beginning with //. A DSN contains just the DSN name, without any keywords.

This is an example of JCL in the Process Definition's Source field.

//EXAMPLEX JOB (ACCT#), 'JOB DEMO',CLASS=X
//STEP1 EXEC PROG=IEFBR14

This is an example of a DSN PDS naming the JCL on the mainframe.

HLQ.DEMO.CNTL(JCLDEMO)

Parameters

The JCL_FTP Definition Type supports the following built-in parameters:

The JCL_FTP Definition Type runs the Perl Net::FTP module. Options are specified as parameters named OPTION_<name>, where <name> is a valid Net::FTP module constructor option such as OPTION_Port.

Parameter Substitution

One of the advantages that most Definition Types have is that they use native parameter substitution. The Source script can use all parameters that you defined on the process, plus some built-in ones, in the native syntax of the computer language that you are writing in.

The syntax that RunMyJobs uses for parameters is:

~<parameter_name>~

For example, if you have parameters P_DSN1 varchar2(30) and P_DSN1_TRACKS number(3), you can use these in the JES source as follows:

//DSN1 DD DSN=~P_DSN1~,DISP=(NEW,CATLG),SPACE=(TRK,(~P_DSN1_TRACKS~,1))

Note: The tilde (~) character is used to start and end a parameter name because this character was not represented in earlier EBCDIC character sets, and thus not very likely to occur in normal JCL cards. However, current EBCDIC tables usually do have the tilde as code point A1, but it can only occur in '*' SYSIN cards, because JES does not allow the tilde character.

Warning: If a process reaches status Error, the Out values of parameters are not always set. You can use a Post Running action to set them if required.

JOB Card

Every job received by JES must start with a JOB card with the following format.

//jobname JOB (accounting),name,keyword-parameters

RunMyJobs automatically generates a JOB card if it sees that you have not created one at the start of your code. This default card is:

//~JES_USER~~JES_JOB_IDENTIFIER~ JOB ~JES_ACCOUNT~,'~JES_USER~'[,CLASS=~JES_CLASS~][,MSGCLASS=~JES_MSGCLASS~]]

The ,CLASS and ,MSGCLASS arguments are added only if they are filled by a process parameter.

RunMyJobs communicates with z/OS using the IBM FTP server, which has a direct link to the JES internal reader and the JES spool. If JESINTERFACELEVEL=1, you must use a job name of ~JES_USER~ followed by one character. The default JOB card does this correctly. If the FTP server is running at JESINTERFACELEVEL=2, the job name is free, and the automatic JOB card will start with J followed by at most the last 7 characters of the process ID.

Defining the User Account

The job is submitted to MVS using an FTP account. This account is also used to submit the job (unless overruled by the JOB card). The username, password, and hostname where the job is submitted are normally set via credentials. Set the Run As User field on the process to define all three parameters.

For example, to submit a job to account MYUSER with password SECRET on host ZPROD1, use the following syntax in the Run As User field (or via a {VirtualUser}: reference to a stored credential set):

MYUSER/SECRET@ZPROD1

As soon as you save the Process Definition, the password is obscured.

Prerequisites

On the z/OS or MVS server:

• z/OS (any release) or OS/390 V1R2.0 or higher, preferably V2R10 or higher to support arbitrary job names.
• TCP/IP V3R1 or higher.
• IBM FTP server enabled.

On the UNIX or Microsoft Windows server that the Platform Agent runs on:

• Perl 5.8.4 or above.
  • Perl modules Net::SSLeay, Bundle::libnet, and IO::Socket::SSL

Note: Using the latest Perl release is recommended. Customer Support may ask you to upgrade if you are experiencing problems.

Procedure

On the z/OS or MVS server:

• Recommended: Edit the TCPIP profile so that JESINTERFACELEVEL is set to 2. If this is changed, restart the FTP server.

In the RunMyJobs user interface:

1. Choose an existing Platform Agent running on UNIX or Microsoft Windows that has Perl and the required Perl modules.
2. Add the JCL_FTP Definition Type to it.

Example

The following process takes a parameter called MESSAGE and displays its content.

//*
//* A hello world program with a variable message
//*
//STEP1 EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
~MESSAGE~
/*
//SYSUT2   DD SYSOUT=*

The following is an example of a normal JCL batch, in this case a COBOL compiler call:

//*
//* Note that this process assumes there is a PDS named BPA.JES.OBJ,
//* to store the object code.
//*
//COMP     EXEC PGM=IGYCRCTL,REGION=4096K
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DSN=BPA.JES.OBJ(JCLTEST),DISP=(OLD)
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(2,2))
//SYSUT2   DD UNIT=SYSDA,SPACE=(CYL,(2,2))
//SYSUT3   DD UNIT=SYSDA,SPACE=(CYL,(2,2))
//SYSUT4   DD UNIT=SYSDA,SPACE=(CYL,(2,2))
//SYSUT5   DD UNIT=SYSDA,SPACE=(CYL,(2,2))
//SYSUT6   DD UNIT=SYSDA,SPACE=(CYL,(2,2))
//SYSUT7   DD UNIT=SYSDA,SPACE=(CYL,(2,2))
//SYSIN    DD *
       IDENTIFICATION DIVISION.
       PROGRAM-ID. JCLTEST.
       PROCEDURE DIVISION.
           STOP RUN.
/*