← IBM z/OS Definition TypesIBM z/OS System Tools →

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 require the ProcessServerService.JCL_FTP license key in order to be able 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.

Example of JCL in the process source

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

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:

Parameter NameDescription
JES_HOSTThe z/OS hostname where the job is submitted (not recommended; use credentials instead).
JES_USERThe z/OS user account used to submit the job (not recommended; use credentials instead).
JES_PASSWORDThe z/OS user account password used to submit the job (not recommended; use credentials instead).
JES_JOB_IDENTIFIERThe job class. If This is not set, a random letter between A and Z will be taken (only used if no job card in JCL found).
JES_DELETEDelete (cancel) the JES job after it ran?
JES_ACCOUNTThe accounting rule (only used if no job card in JCL found).
JES_ENCRYPTIONSpecifies the encryption mode, Empty (no encryption), implicit, implicitzos, or explicit
JES_PASSIVESpecifies the FTP mode, passive mode is 1 (default), set to 0 for active mode.
VERBOSEHow much logging to show on the agent side. The default = 0, but it can be set to 1 or 2 for debugging purposes.
OPTION_<perl_option>Specifies the value of the Perl Net::FTP option.

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 to set the port, for example.

Parameter substitution

One of the advantages that most definition types have is that they use native parameter substitution. The source that you type as the process source 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 Redwood Server uses for parameters is:

~<parameter_name>~

For example, you have parameters P_DSN1 varchar2(30), 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

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

note

When 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

Redwood Server 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 only added if they are filled by a process parameter.

Redwood Server communicates to z/OS using the IBM FTP server, which has a direct link to the JES internal reader and the JES spool. If the JESINTERFACELEVEL is 1 you must use a jobname of ~JES_USER~ followed by one character. The default job card does this correctly. If the FTP server is running at JESINTERFACELEVEL=2 then the job name is free, and the automatic job card will use a jobcard starting 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 will also be 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.

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

Note that as soon as you store this field the password is stored in an encrypted fashion.

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 Redwood Server UI:

  1. Choose an existing platform process server 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.
/*

See Also

← IBM z/OS Definition TypesIBM z/OS System Tools →