SFTP Print Driver

Use this print driver to automatically transfer all types of CA Spool print files, including PDF/HTML/RTF wrapped text files, directly to a remote SFTP server for further processing.
casp14
Use this print driver to automatically transfer all types of CA Spool print files, including PDF/HTML/RTF wrapped text files, directly to a remote SFTP server for further processing.
The SFTP print driver provides support for the following:
  • Text reports stored in EBCDIC without translation and with preservation of carriage control information.
  • Text reports converted to ASCII using the translate table specified on the TRANS parameter of the NODE statement.
  • Automatic conversion of text files into PDF, HTML or RTF files while being transferred to a remote SFTP server.
You can specify SFTP report attributes and processing options as follows:
  • On the printer level using the using the 4*60=240 bytes DRIVPRM1-4 parameters.
  • On the print file level using the 4*60=240 byte OUTPUT ADDRESS parameters.
You can specify this using JCL or have it be automatically assigned using CA Spool DESTID definitions.
If you specify an SFTP print driver parameter more than once, the last specification is used.
You can automatically generate unique identifying names; that is, you can specify that the FILENAME= remote-file-name must be synthesized from userid, destination, file name, file number, date, time, job number, job name, job class, job step, proc step, DD name, and fixed text.
NETRC Data Set
The NETRC data set provides you with an alternative to specifying your userid as an SFTP Node parameter.
To use the NETRC data set, you need to activate the following DD statement in the JCL procedure for CA Spool:
//*-------------------------------------------------------------------* //* Common FTP, CA XCOM and Connect:Direct userid/password file * //*-------------------------------------------------------------------* //NETRC DD DISP=SHR,DSN=&PARMLIB(IQNETRC)
The supplied CBQ4PARM(IQNETRC) sample contains the following sample definitions:
* * Common FTP, CA XCOM and Connect:Direct userid/password file * machine ftp.com login userid1 password pass1 machine 111.222.33.44 login userid2 password pass2 machine XCOM.IPNAME.com login userid3 password pass3 machine XCOMLUx login userid4 password pass4 machine XCOMGROUPx login userid5 password pass5 machine ConnectDirect login userid6 password pass6 machine sftpnode login userid7
If no FTPUSER is specified on the SFTP Node definition or defined on the Output statement Address parameters for the file, the remote FTP machine is looked up in the NETRC data set. If the machine is found, its userid is used. Any password value is ignored by the SFTP driver.
If the NETRC data set is used, it must be secured against unauthorized read and write access.
Transfer Print Files to a Remote SFTP Server
You can transfer CA Spool print files to a remote SFTP server.
Follow these steps:
  1. Define a new CA Spool printer with TCPDRIV=SFTP.
  2. Point TCPHOST and TCPPORT to the remote SFTP server.
  3. Define PATH, FILENAME, PATHMODE, RPATH and FTPUSER values using DRIVPRMn parameters on the NODE statement or specified via OUTPUT ADDRESS parameters in the JCL of the job that creates the CA Spool file to be transferred.
External Tasks Required to Transfer Files to a Remote SFTP Server
The SFTP print driver uses IBM’s z/OS OpenSSH program product that is available starting with z/OS 2.2. The
z/OS OpenSSH User’s Guide
describes how to install and configure z/OS OpenSSH.
Host Authentication
The public/private key pair that enables host authentication on the mainframe is generated by the installer of z/OS OpenSSH during the process of implementing the SSH daemon, usually called SSHD. By default, those keys are written to /etc/ssh.
The public/private key pair that enables host authentication on the remote sftp server is generated by the install of OpenSSH on the remote server.
Perform the following tasks for host authentication:
  1. Copy a public host key from the mainframe where CA Spool is running to the remote machine and stored in the ~/.ssh/known_hosts file of all users who plan to use sftp to transfer files.
  2. Copy a public host key from the remote machine to the mainframe system where CA Spool is running and stored in the ~/.ssh/known_hosts file of all users who plan to use sftp to transfer files to that remote machine.
User Authentication
Perform the following tasks for user authentication:
  1. Generate the user’s certificate on the system running CA Spool.
    Certificates can be generated using your mainframe security software or by using the OpenSSH command ssh-keygen.
  2. When using mainframe security software to manage certificates, the next step is to add it to a keyring for the user.
    For instructions on how to generate, add and export the certificate, see the documentation for the FTP driver or the documentation for your mainframe security software.
  3. Export the user’s certificate.
  4. Copy the exported certificate to the remote SFTP server and import it into the user’s ~/.ssh/authorized_keys file.
    ssh-keygen –i –f /home/rmtuserid/zoskeyfile.pub >> /home/rmtuserid/.ssh/authorized_keys
    When mainframe security software is not in use, copy the public key generated by ssh-keygen to the remote ftp server and store it in /home/rmtuserid/.ssh/authorized_keys.
When transferring keys generated on the mainframe to a non-mainframe platform, the key must be translated from Ebcdic to Ascii.  The same is true for keys generated on a non-mainframe platform. They must be translated to Ebcdic before they are stored on the mainframe.
JCL Parameters
You can specify the following JCL parameters, separated by commas, using the file's OUTPUT ADDRESS parameters:
  • PATH
    =local USS path/filename [.PDF/.PDFL/.HTML/.RTF]
  • FILENAME
    =continued/file-name[.PDF/.PDFL/.HTML/.RTF]
    PATH and FILENAME are combined to form the complete local target directory and file name. This extends the value used to a maximum of 106 characters. 
  • RPATH
    =remote path
    RPATH defines the target directory on the remote sftp server.  The remote file name will be extracted from the combined PATH and FILENAME values.
  • FTPUSER
    = remote-userid
    FTPUSER is the userid on the remote machine where the sftp server is running.  This value can also be extracted from the file allocated on the NETRC DD statement in the CA Spool procedure. 
  • FTPDATA
    = remote-ssh_config
    FTPDATA specifies an alternative ssh_config configuration file for ssh.  This option is passed directly to ssh and has no effect on z/OS-specific configuration files.
  • PATHMODE
    =SIRUSR/,SIWUSR/,SIXUSR/,SIRWXU/,SIRGRP/,SIWGRP/,SIXGRP/
    ,SIRWXG/,SIROTH/,SIWOTH/,SIXOTH/,SIRWXO/,SISUID/,SISGID
    AM=SFTP, (or TCPDRIV=SFTP)
    PATHMODE is used to set file permissions on the local file.  The use of the
    -p
    option on the sftp put command causes these permissions to be set on the remote file at the time of the transfer.
In addition to the file defined by PATH and FILENAME, the SFTP print driver writes multiple files to the local USS path, where Fnnnnnn is the letter F followed by the CA Spool file number:
  • Fnnnnnn.batfile
  • Fnnnnnn.stdout
The batfile contains the following:
cd \sftpfolder put -p /pathname/localfilename remotefilename exit
The execution of the Fnnnnnnn.batfile files is single-threaded.
The remote directory is set to the value in the RPATH parameter, if specified. The PATH and FILENAME are combined and specify the local directory and filename specified on the NODE. The same filename is used as the remote file name. The -p option on the put command sets the permissions on the remote file to the same as the permissions on the local file. The operating system where the remote sftp server is running must support traditional UNIX permissions for the -p option to successfully set permissions.
The Fnnnnnn.stdout file is used to accumulate transfer statistics and debug information.
Unless debug options are specified with the SFTP driver, all local USS files are deleted after a successful transfer.
When the
T
option is specified, a TCPTRACE file is created for the sftp session. The TCPTRACE file contains all of the information regarding the read and write of the CA Spool file, the creation of the local USS files, the contents of the Fnnnnnn.stdout file and the deletion of the local USS files.
When the
e
option is specified, the Fnnnnnn.stdout file is kept. Extra informational messages are written to the ESFLOG. No TCPTRACE file is created.
When the
e
and
T
options are both specified, all three local USS files are kept, a TCPTRACE file is created and extra informational messages are written to the ESFLOG.
Replacement Variables
You can specify the following replacement variables anywhere in the PATH, FILENAME, and FTPUSER parameters to have appropriate unique names dynamically generated:
  • &CLS
    Print file class.
  • &DAT
    Include the current date in '
    mm
    dd
    ,
    yy
    ' format. For example, January 22, 2019.
  • &DAW
    Include the current weekday in '
    aaa
    ,
    dd
    mmm
    ,
    yyyy
    ' format. For example, Tue, 22 Jan 2019.
  • &DAY
    Current date in
    Dyymmdd
    format. For example, D190122.
  • &DDN
    DD name of the print file creator.
  • &FCB
    Print file FCB name. The file FCB name will be prefixed with FCB2 when the variable is resolved. For example, if the file FCB value is 6, the variable is resolved to FCB26.
  • &FNM
    Print file name.
  • &FNO
    Print file number.
  • &FRM
    File Form.
  • &HST
    Local Host.
  • &JID
    Job, STC or TSU ID of the print file creator.
  • &JOB
    Job name of the print file creator.
  • &JST
    Job step name of the print file creator.
  • &JUL
    Current date in Julian
    Dyyddd
    format. For example, D19022.
  • &NOD
    Print file destination name.
  • &PGN
    File Programmer’s Name.
  • &PRM
    Print file print-mode.
  • &PST
    Proc step name of the print file creator.
  • &TIM
    Current time in
    Thhmmss
    format. For example, T021734.
  • &TOD
    Current time in
    Thhmmss
    format. For example, T021734.
  • &TTL
    The file's Output Statement TITLE parameter value.
  • &UID
    User ID of the print file creator.
  • &WTR
    File Writer.
You can specify that only part of the replacement variable be used by specifying offset and length in brackets after the variable. For example, the following code specifies that only characters 2 through 5 of the file creator's name are to be used:
&UID(1,4)
If you do not specify JCL parameters, the following default JCL parameters are used:
FTPUSER=&UID FILENAME=&UID.&NOD.&FNM.&FNO
Wrapping for Text, PDF, PDFL, HTML, and RTF
If the FILENAME extension of an input text file equals PDF, PDFL, HTML or RTF, the file is automatically formatted and converted into the specified data-stream before it is transferred. PDFL generates Linearized PDF.
The formatting and paper size, orientation, and font style (family, pitch, style, and stroke weight) are controlled by the Form, Chars, channel skips, and max record length of the file. The default line spacing is 6 LPI, allowing 43 lines per page in landscape and 60 lines per page in portrait. If the lines per page in the data file is higher, LPI and lines per page are automatically adjusted.
Both of the following are supported: TCPDRIV option H - page length auto formatting, the default, and TCPDRIV option F - FCB-length based auto formatting.
If the RTF wrapper is used and FORM=A4* in the input file, the output is formatted to A4 paper size. If FORM=LET* in the input file, the output is formatted to letter paper size.
Separator pages are not supported for files that you create using CA Spool Text Wrapping support. ESFU010X is not called for files of this type.
RACF Requirements
The following requirements apply only when RACF is used as the external security package.
Program Control is required by RACF when using the SFTP print driver. All members of any loadlib in STEPLIB or LNKLIST that may be used by CA Spool must be program controlled, including the IBM C runtime loadlib and the CA Spool loadlib. This may also include loadlibs required by the Connect:Direct, SAR, XCOM and MQM print drivers if those print drivers are in use. This also includes any PDS allocated by the IMAGELIB DD statement, because CA Spool uses the load svc on any FCB used during output processing. If no IMAGELIB DD statement exists in the CA Spool proc, SYS1.IMAGELIB is used by default.
The CA Spool task userid and any user who sends files to CA Spool must have access to the programs under RACF Program Control. Additionally, READ access to BPX.SERVER and BPX.DAEMON is required.
SFTPSEC=RACF must be added to the DRIVPRMn parameters for any NODE using the SFTP print driver.
Sample
A sample SFTP printer node definition follows:
*---------------------------------------------------------------------* * TCPDRIV=SFTP * *---------------------------------------------------------------------* DEFNODE SFTP, SFTP DEFNODE SFTP-01, Device type ACQUIRE=TIME, Acquire when files to be printed FSSNPRO=3600, Retry for 3600 seconds (1 hour) * LINECNT=nnn, NOCC - max lines per page PURGE=NO, Keep files after printing RELEASE=NOWORK, Free printer when no more files SEP=0, No separator pages SETUP=NO, Printer never enters setup processing TCPDRIV=SFTPT, TCP/IP printer driver name and options TCPPORT=22 TCP/IP SFTP server port number NODE SAMPSFTP,SFTP,GROUP=1, Sample remote SFTP printer DRIVPRM1='PATH=/u/users/work,PATHMODE=SIRWXU,SIRWXG,SIRWXO', DRIVPRM2='RPATH=remote-directory,FILENAME=&UID.&FNM.PDF', DRIVPRM3='FTPUSER=remote-userid', * DRIVPRM4=’SFTPSEC=RACF’, **RACF sites only** TCPHOST=ccccccccccc, Remote TCP/IP SFTP server host TRANS=C037T19U US English EBCDIC to Latin 1 ASCII
  • DRIVPRMn parameter SFTPSEC=RACF is required when RACF is used as the external security package.
  • The printer node definition shown above is supplied in data set member CAI.CBQ4PARM(CAIQPARM).
The following sample DESTID definition automatically converts text files whose name starts with SV11 to PDF and transfers the PDF files to the remote SFTP host:
DESTID QDEST=HP6DFTP,QFNAME=SV11*, FADDRES1='RPATH=/sftpfolder/', FADDRES2='FILENAME=&UID.&FNM.PDFL'