JCL statements for PDUU

The JCL statements for the PDUU are:

SYSPRINT

The data set can be either SYSOUT or a sequential data set. The data set must be RECFM=FB, LRECL=134. For additional details, see Prerequisites and restrictions for PDUU.

SYSUT1

The sequential or partitioned data set to transfer to IBM®. For additional details, see Prerequisites and restrictions for PDUU.

SYSUT2

This data set is optional and can be used only when transferring partitioned data sets (PDS/PDSE). It defines a sequential unload data set for IEBCOPY output produced during the unload operation. If the SYSUT2 statement is omitted the unload data set will be allocated dynamically. This parameter can be used if you want to directly control the allocation of the unload data set, for example, to specify a particular volume or certain amount of volume space. For additional details about usage and allocation parameters of the unload data set see the topic on Unloading (Backing up) Data Sets in z/OS DFSMSdfp Utilities. See also Example 9: Using SYSUT2 to allocate an unload data set.

SYSIN

A sequential data set that uses the following control statements. The data set must be RECFM=FB, LRECL=80. For additional details, see Prerequisites and restrictions for PDUU.

PDUU is managed through the following SYSIN statements with these guidelines:

Use an asterisk (*) in the first column of each comment line to indicate comments.
Keywords must start in column one.
Use control statements that are in form VERB=OPERAND.
Mixed case verbs and operands are allowed.
The operand starts in the column after the equal sign and goes to the first blank column except TARGET_SYS, DIRECTORY, CIPHER_KEY, ACCOUNT, HTTPS_KEYFILE, HTTPS_KEYRING, HTTPS_KEYSTASH, HTTPS_PROXY, HTTPS_LOCALIPADDR, USERID, and PASSWORD, which can contain blanks.
Anything after the first blank is ignored except for any operands that can contain blanks. In those cases, do not use blanks from column one to the end of the operand.
Control statements can be coded on one or more (up to 6) consecutive records. Control statements with operands that allow blanks must not extend beyond column 71, but can continue on the following record in columns 16 through 71. Columns 1 through 15 of the continuation record must be blank. See Example 10: Using a multiple record control statement in SYSIN. Control statements with operands that do not allow blanks can occupy columns 1 through 80.
When specifying a control statement twice, the last specification is used.

USE_ATTLS

An optional parameter that when specified with a value of 'Y' indicates that PDUU use an HTTPS connection secured by the AT-TLS enabled security policy established by the installation. That is where the SSL/TLS security configuration details will come from. This eliminates the need for specifying security protocol data (HTTPS_KEYRING HTTPS_KEYFILE, SSL_4CIPHER, or TLS versions) for the PDUU file transfer. End of change

HTTPS_TLS12

An optional parameter that when specified with a value of 'Y' indicates that PDUU support TLS 1.2 encryption and cipher suites. End of change

HTTPS_TLS13

An optional parameter that when specified with a value of 'Y' indicates that PDUU support TLS 1.3 encryption and cipher suites. End of change

USE_HTTPS

An optional parameter that when specified with a value of 'Y' enables HTTPS mode and indicates that PDUU use the HTTPS protocol to transfer data to IBM.

Omitting this parameter results in PDUU using the default FTP protocol.

TARGET_SYS

The name of the TCP/IP system to transfer the files to. One through 256 characters, dotted decimal format is allowed, no default value, can not contain blanks, and it must be specified.

For FTP mode, if using a proxy server, this should be the name of the proxy server.

You can include additional FTP command parameters on the TARGET_SYS parameter by using the z/OS® UNIX specifications as shown in the topic FTP command -- Entering the FTP environment in z/OS Communications Server: IP User's Guide and Commands. For example, to trace output (-d) and use a specific ftpdata_filename (-f"//'WES.MYFTP.DATA'"):

TARGET_SYS=-d -f"//'WES.MYFTP.DATA'" testcase.boulder.ibm.com

Use the -p parameter to specify an alternate IP stack.

For HTTPS mode, does not allow for the specification of a config file or proxy information through the TARGET_SYS parameter.

USERID

The user ID on the target system that is used to send the files. One through 64 characters, no default value, does not have to be specified, and can contain imbedded blanks.

For FTP mode only, if USERID and PASSWORD are not supplied and NETRCLEVEL=2, the values from the NETRC data set is used for the FTP sessions.

If using a proxy server, this can be the full login to the remote system in the format userid@remote.system.name.

PASSWORD

The password for the USERID on the target system. One through 64 characters and the default value is blanks.

For FTP mode only, if using a proxy server, this can be the USERID and PASSWORD for the proxy server in the format userid@password.

ACCOUNT

For FTP mode, the account data that is sent when an FTP session is started. One through 64 characters with no default value.

This parameter is ignored for HTTPS mode.

TARGET_DSN

The descriptive portion for the file names for the target system. One through 50 characters, no default value, and it must be specified. It can contain alphanumeric characters and special characters allowed on the target system.

WORK_DSN

For FTP mode, the prefix for the data set names of work files on the sending system. One through 40 characters, no default value, and it must be specified. The work data sets are large format, sequential, data sets and cannot have the compaction attribute.

Note: Because work files are dynamically allocated with large format and do not support compressed format, if you specify data class for work files with the compaction attribute or N, the following message is issued for all work files:

IGD17163I COMPRESSION REQUEST NOT HONORED FOR DATA SET
work_file_dsname BECAUSE DATA SET CHARACTERISTICS 
DO NOT MEET COMPRESSION CRITERIA, ALLOCATION CONTINUES

This parameter is ignored for HTTPS mode.

CC_HTTPS | CC_FTP

The number of parallel FTP transfer sessions to use when transmitting the files. One or two decimal digits, the value must be between one and 20, and the default is two. CC_HTTPS is an alias for CC_FTP.

WORK_SIZE | WORK_DSN_SIZE

The maximum size of the work buffer in megabytes, 1–4 decimal digits. When unspecified, the default is 100. WORK_SIZE is an alias for WORK_DSN_SIZE.

For FTP mode, two DASD data sets per session (CC_FTP) are dynamically allocated with this size.

For HTTPS mode, virtual storage of the size 2 * CC_HTTPS# * WORK_SIZE# * 1 MB is requested.

When choosing values for WORK_SIZE and CC_HTTPS parameters, be aware that these buffers are allocated in 31-bit storage, and this is limited to significantly less than 2 GB.

Factors that affect the virtual storage usage include:

If you have CC_HTTPS=4 and WORK_SIZE=100, AMAPDUPL attempts to allocate 800 MB of virtual storage.
Though less impactful, the PDUU usage of the web enablement toolkit may require 2–12 MB.
Language Environment also uses virtual storage, and the default HEAP usage can double the HTTPS mode virtual storage usage when the amount of data to be transferred easily fills the work buffers allocated for PDUU. Reduce that impact by using the recommended CEEOPTS HEAP value change. It should result in only 1 additional CC_HTTPS# * WORK_SIZE# * 1 MB sized buffer being used.

Start of change When processing requires more virtual storage than is available, processing fails with return code 12 and message AMA761E. In this case, consider lowering the CC_HTTPS or WORK_SIZE parameter values, or both. End of change

KEEP_WORK

For FTP mode, the parameter to save the work data sets that are dynamically allocated for each FTP session. If you omit the KEEP_WORK parameter, the program does not save the work data sets. Y is the only value for the KEEP_WORK parameter.

Note: Only specify this parameter when debugging a problem.

This parameter is ignored for HTTPS mode.

DATACLAS

For FTP mode, the data class to use when allocating the work files on the sending system. One through eight characters with no default value.

This parameter is ignored for HTTPS mode.

MGMTCLAS

For FTP mode, the management class to use when allocating the work files on the sending system. One through eight characters with no default value.

This parameter is ignored for HTTPS mode.

STORCLAS

For FTP mode, the storage class to use when allocating the work files on the sending system. One through eight characters with no default value.

This parameter is ignored for HTTPS mode.

DIRECTORY

The directory on the target system where the files will be sent with FTP or HTTPS. One through 32 characters, with no default, can contain blanks, and you must specify the directory.

For HTTPS transfer to www.secure.ecurep.ibm.com specify the destination without any leading or trailing slashes, such as 'DIRECTORY=mvs'.

CASE

The CASE id associated with the file and problem. This field must be 11 numeric or uppercase characters. Do not specify when the PMR statement is specified. Example: TS123456789

PMR

The PMR number with which this file is associated. Do not specify when the CASE statement is specified. This field must be 13 numeric or uppercase characters, specify in the form xxxxx.yyy.zzz, and define the variables as:

Table 1. PMR number variables for PDUU
Field	Explanation	Example
XXXXX	PMR Number	`34143`
YYY	Branch office	`055`
ZZZ	IBM Country Code	`724`

CIPHER_KEY

The encryption key to use for 192-bit triple DES encryption. The 24 characters following CIPHER_KEY= are used as the key. The key can include imbedded and/or trailing blanks. For example, CIPHER_KEY=HERE IS CIPHER KEY IN 24 or CIPHER_KEY=Shortkey. If you do not specify CIPHER_KEY=, no encryption is performed. If you encrypt the data set using CIPHER_KEY, you must provide IBM with the encryption key so they can perform problem diagnosis.

Note: If CIPHER_KEY= is followed by 24 blanks, the file will be encrypted with a key of 24 blanks.

NO_FTP

A value of 'Y' specifies that PDUU compress, optionally encrypt, separate files into parts, and move the part to a local z/OS Unix Systems Services directory, without FTPing the files. PDUU uses TSO services to send data sets to USS directories. When you specify NO_FTP=Y:

TARGET_SYS, CC_FTP, USERID, and PASSWORD are not required
CC_FTP settings are ignored and set to 1
FTPCMDS DD will be ignored
The system allocates the SYSTSPRT DD to receive messages from TSO.

Once transferred, you can browse the files and extract them from the z/OS Unix Systems Service directory. The file names used depend on the PMR and TARGET_DSN input:

PMR.TARGET_DSN.Tdate.MTFTP.F00002 to ...Fnnnnn

The size and number of files you end up with depends on the WORK_DSN_SIZE SYSIN control statement and how well the input file compresses.

The date section is a random string based on the time the job is run, and PDUU creates different output file names if the same file is sent at a different time. In addition there will be a small file with suffix F001 containing the control record with information necessary to recreate the file on the receiving end.

Please package and send all generated files to IBM with the file names created. Use the NO_FTP=Y option if you have a closed data center (with no outside internet access). PDUU then prepares files you can send to IBM service on removable media as desired.

NO_FTP is ignored when USE_HTTPS is specified.

SSL_4CIPHER

An optional parameter when HTTPS_TLS12 or HTTPS_13 or both are specified. It is used to specify the 4-character cipher suite to be used. While the contents are not verified, the input must be multiples of 4 characters. See Cipher suite definitions in z/OS Cryptographic Services System SSL Programming for the values which provide the desired encryption strength.

An example value is: 13031302130100350032

HTTPS_KEYRING

Specify a SAF key ring or PKCS #11 token containing certificates necessary to connect to the HTTPS sessions. Of the form:

SAF key ring name, specified as userid/keyring
PKCS #11 token, specified as *TOKEN*/token_name

HTTPS_KEYFILE

Specifies a path and file name of the key data base file created by the System SSL gskkyman utility.

HTTPS_KEYSTASH

Specifies the path and file name of the password stash file created by the System SSL gskkyman utility. This option is required when HTTPS_KEYFILE is sepcified.

HTTPS_PORT

An optional parameter when USE_HTTPS=Y is specified indicating the remote port number to which to connect. The default value is 443.

HTTPS_IPSTACK

An optional parameter when USE_HTTPS=Y is specified indicating the local TCP/IP stack name to be used when connecting to the IBM site. 1-8 characters specifications are allowed.

HTTPS_LOCALIPADDR

An optional outgoing IP address from which the connection is to originate.

HTTPS_LOCALPORT

An optional parameter when USE_HTTPS=Y is specified indicating the outgoing port number from which the connection is to originate.

HTTPS_PROXY

An optional parameter when USE_HTTPS=Y is specified indicating the HTTP proxy to use. Must specify starting with http:// or https://. For example: http://my.proxy.com

HTTPS_PROXYPORT

An optional parameter when USE_HTTPS=Y is specified indicating the proxy port to connect to.

HTTPS_PROXYUSERNAME

An optional parameter when USE_HTTPS=Y is specified indicating the username to connect to the HTTP proxy. One through 64 characters and can contain embedded blanks. Must specify with HTTPS_PROXYPASSWORD.

HTTPS_PROXYPASSWORD

An optional parameter when USE_HTTPS=Y is specified indicating the password to connect to the HTTP proxy. One through 64 characters and can contain embedded blanks. Must specify with HTTPS_PROXYUSERNAME.

HTTPS_VERBOSE

An optional parameter when that when specified with a value of 'Y' and when USE_HTTPS=Y indicates to the web enablement toolkit to produce verbose messages for HTTPS transfers. These messages can be helpful in diagnosing connection issues and aiding in IBM problem determination. The HTTPS_VERBOSE_DD can be used to change where these messages are sent.

HTTPS_VERBOSE_DD

An optional parameter to specify a 1-8 character DD name that takes effect when the HTTPS_VERBOSE=Y parameter is used. The DD name indicates where the web enablement toolkit is to place the verbose messages. This must meet the requirements as described in HTTP/HTTPS enabler options and valuesin the HWTH_OPT_VERBOSE_OUTPUT option. The default is SYSPRINT when not specified.

CEEOPTS

Used to specify additional invocation-level runtime options for z/OS Language Environment (LE) processing.

When using the HTTPS protocol, specify the following:

HEAP(32768,32768,ANYWHERE,FREE,8192,4096)

to override the IBM-supplied default of:

HEAP(32768,32768,ANYWHERE,KEEP,8192,4096)

so that less virtual storage is used for LE buffers.

DEBUG

An optional DD statement that gathers debug information such as messages issued to the SYSPRINT data set and the FTP protocol messages. The data set must be RECFM=FB, LRECL=134.

FTPCMDS

For FTP mode, an optional DD statement that provides additional flexibility for traversing firewall or proxy servers. When this DD statement is provided, after the initial USERID and PASSWORD are sent, the specified sequential data set is read by the application and the commands contained in the data set are included as FTP commands. The data set must be RECFM=FB and LRECL=80.

This DD is ignored for HTTPS mode.

Comments and sequence numbers are not allowed. As an example, to supply a userid and password on the hostname system:

//FTPCMDS  DD *
USER 'anonymous@testcase.boulder.ibm.com proxyuser'

SYSTSPRT

An optional DD statement that shows messages from TSO operations when you have NO_FTP=Y specified. If you receive message AMA778I with a return code of X'04' and function code of X'C', add this DD statement to your JCL to receive messages and rerun if necessary to receive messages.