===============================================================================
README for REXX Socket API sample:
      "How can I submit JCL jobs to MVS/JES from REXX?"
===============================================================================

   Contents:

      1.)   Abstract
      2.)   Description
      3.)   Prerequisites
      4.)   Installation instructions
      5.)   OS/390 JCL data sets
      6.)   OS/390 FTP data sets
      7.)   OS/390 FTP server: JES facility
               Entering and leaving JES mode
               Submitting a job
               Displaying the status of a job
               Specifying job IDs
               Receiving spool output
               Deleting a job and job output
      8.)   Sample
               Stack version
               File version
               RxFTP API version
      9.)   Documentation

===============================================================================
Abstract
===============================================================================

   Demonstrates how JCL jobs can be submitted to MVS/JES and how their output
   can be retrieved from REXX running on various operating systems.

===============================================================================
Description
===============================================================================

   One very comfortable way to submit jobs - which is to be shown here - is
   to use the OS/390 FTP server's JES facility. This technique is not only
   comfortable, it is also applicable for job submission from various operating
   systems (MVS, VM, VSE, OS/2, Linux, AIX, Windows, ...).

   Principially there are 3 ways to automatize an FTP client session:

   -  Placing the FTP subcommands in a file and route that file to the FTP
      clients standard input stream (on some OS there are special FTP client
      options on others input and output can be redirected using '<' and '>').

   -  QUEUE (or PUSH) the FTP subcommands on the REXX data stack. The FTP
      client checks that stack for commands to execute - this works for VM and
      MVS.

   -  Using an FTP REXX API - this solution gives the programmer the pssibility
      to work really interactively with the FTP interface, and not only execute
      some predefined commands. This solution works for the workstation plat-
      forms supported by IBM REXX (OS/2, AIX, Linux (X/86 as well as S/390),
      Windows).

===============================================================================
Prerequisites
===============================================================================

   1.) The OS where your REXX program is running must have an FTP client.

         The command to start the FTP client is always:

            ftp

   2.) The OS/390 node to which you want to submit jobs must have:

    2a)  Job Entry Subsystem running, and

    2b)  an FTP server running:

         say, the node name is XYZ, then you should get a reply from the FTP
         server when you start the FTP client on your machine using:

            ftp XYZ

         If you are not prompted to login with your user ID contact the system
         administrator for that node.

   3.) Also you'll need a user ID on that node:

    3a)  Your TSO user ID must have an OMVS segment defined or defaulted.

    3b)  To use FTP in a OS/390 UNIX environment, TSO users must be authorized
         users or have a default OS/390 UNIX unser ID:

            OS/390 UNIX user ID = TSO user ID

===============================================================================
Installation instructions
===============================================================================

   1.) Unzip the *.ZIP file on a workstation.

   2.) You should find following files:

         Readme.txt
         ftpStack.rex
         ftpFile.rex
         ftpAPI.rex
         ftpAPI.cmd
         ftp.win.in
         ftp.cms.in
         ftp.tso.in
         ftp.uss.in
         ftp.aix.in
         ftp.lin.in
         ftp.os2.in

   3.) For VM, MVS/TSO and TSO/USS copy required REXX programs and data files:

         VM:      copy:
                     ftpFile.rex    -> FTPFILE  EXEC     A
                     ftpStack.rex   -> FTPSTACK EXEC     A
                     ftp.cms.in     -> FTPIN    DATA     A
                  to your A minidisk.

         MVS:     copy:
                     ftpFile.rex
                     ftpStack.rex
                  to your REXX program dataset (allocated to DD SYSEXEC).
                  And copy:
                     ftp.tso.in
                     ftp.uss.in     (-> only needed for USS later)
                  to another PDS or to sequential files.

         USS:     copy:
                     ftpFile.rex
                     ftpStack.rex
                     ftp.uss.in
                  to your OpenMVS data area using something like:

                     OPUT CODE.REXX(FTPSTACK) 'ftpStack.rex' TEXT

                  This will copy the member '*uid*.CODE.REXX(FTPSTACK)' to
                  the file 'ftpStack.rex'. Then you need to make the file
                  executable by following call for example:

                     chmod +x ftpStack.rex

   4.) For OS/2 rename one file:

         ftpFile.rex    -> ftpFile.cmd

===============================================================================
OS/390 JCL data sets
===============================================================================

   JCL job data set:
      -  RECFM = FB,  LRECL =  80, BLKZIZE = x *  80

   JCL output data set:
      -  RECFM = VBA, LRECL = 137, BLKSIZE = x * 137

===============================================================================
OS/390 FTP data sets
===============================================================================

   DD INPUT:
      -  RECFM = FB, LRECL = 80, BLKSIZE = x * 80
      -  Specifies the data set from where the FTP subcommands to be performed
         are located.

   DD OUTPUT:
      -  RECFM = FB, LRECL = 160, BLKSIZE = x * 160
      -  Specifies the data set where FTP is to place the the client messages
         and server replies generated during the FTP session (-> messages
         exchanged via control connection).

   DD SYSPRINT:
      -  Specifies the data set where you want messages to be returned.

   *uid*.FTP.DATA:
      -  Provides a way for the user to configure the defaults for the local site
         parameters to be used for each session - such a configuration data set
         exists for the server and the client.
      -  There are lots of default parameters:
         -  data set allocation defaults (LRECL, BLKSIZE, DATACLASS, ...)
         -  data transmission defaults (ASATRANS, CCTRANS, ...)
         -  JES facility defaults (JESLRECL, JESPUTGETTO, ...)
         -  SQL facility defaults (SQLCOL, DB2, DB2PLAN, ...)
         -  some MVS/TSO specific defaults (QUOTESOVERRIDE, DIRECTORYMODE, ...)

   *uid*.NETRC:
      -  Provides an alternative for specifying user ID and password; this
         feature allows automatic logon (no need to enter uid and pwd by
         hand) to the given FTP hosts.
      -  refers to DD NETRC in JCL.

===============================================================================
OS/390 FTP server: JES facility
===============================================================================

   The FTP server's JES facility lets you:

   -  submit jobs
   -  cancel jobs
   -  inspect jobs known to JES for your user ID
   -  retrieve job output
   -  purge job output

Note: The TSO PROFILE option "PREFIX" is the name of the default directory you
      will be put into by the FTP server after successful logon.
      If PREFIX is not defined, then the user ID is taken as default directory.
      This option can be set by following TSO command:

         TSO PROFILE PREFIX(...)

-------------------------------------------------------------------------------
Entering and leaving JES mode
-------------------------------------------------------------------------------

   By issuing a SITE FTP subcommand you can alter the server's parameters used
   for and during your FTP session. The FILETYPE parameter specifies the
   current mode. Enter following command to alter the current mode:

      SITE FILETYPE=<mode>

   where <mode> is one of these:

      SEQ - transfer files    (-> standard FTP)
      JES - interface to JES  (-> JES facility)
      SQL - interface to DB2  (-> DB2 facility)

   To start JES mode enter:

      SITE FILETYPE=JES

   and to leave JES mode and return to normal FTP file transfer mode enter:

      SITE FILETYPE=SEQ

-------------------------------------------------------------------------------
Submitting a job
-------------------------------------------------------------------------------

   The JCL job that you like to submit must follow some rules:
   -  The job name must consist of you user ID plus one character.
   -  The output class for MSGCLASS and SYSOUT files contained in your JCL must
      specify a JES HOLD output class (for JES3 they also must be 'reserved for
      external writers').
   -  Maximum LRECL for the submitted job is 254, but JES scans only the first
      72 columns.

   There are 2 ways of submitting a job:
   -  PUT subcommand:

         PUT <local_file>

      -  transfer <local_file> to FTP server
      -  FTP servers submits that file as job to JES
      -  FTP servers waits for an initiator to start the job
      -  FTP servers informs client about the assigned job ID in a reply

   -  GET subcommand:

         GET <remote_file> <local_file>

      -  FTP servers submits <remote_file> (must already be on server!) as job
         to JES
      -  FTP servers retrieves the job's HELD output when the job completes
      -  Client receives that job output in <local_file>
      -  Be careful for long running jobs: Since the FTP server waits for job
         end your local session is suspended until job end or a timeout has
         been reached - the server's JESPUTGETTO parameter determines how long
         the server will keep your FTP session alive while waiting for the job
         to complete. Either
         -  change server's JESPUTGETTO parameter; for example:
               SITE JESPUTGETTO=3600
            will let the server wait for one hour (=3600 seconds), or
         -  use the PUT command and check the status of the job from time to
            time and retrieve its output manually (see further down).

-------------------------------------------------------------------------------
Displaying the status of a job
-------------------------------------------------------------------------------

   When in JES mode you can use the DIR and LS FTP subcommands to inspect
   the jobs assigned to your user ID (and whose name is your user ID + 1 char)
   that are known to JES. DIR lists status information and LS returns only the
   job names and IDs. DIR consumes more resources on the server.

   Status information:

      INPUT  -> Job was received - still waits for an initiator to start it.
      OUTPUT -> Job has finished and has output to be printed or retrieved.
                The number of spool files (JCL-, JES-, initiator- and
                terminator messages, and SYSOUT files) is also given.
      ACTIVE -> Job is currently running.

   Extra status information:

      HELD   -> the JCL specified that the job is to be put on hold

-------------------------------------------------------------------------------
Specifying job IDs
-------------------------------------------------------------------------------

   Job IDs can be obtained using the DIR subcommand or by scanning the server's
   replies (DD OUTPUT).

   A job ID of:            JOB00123
   can be abbreviated as:  J123

-------------------------------------------------------------------------------
Receiving spool output
-------------------------------------------------------------------------------

   The single spool files of one job can be retrieved either one-by-one or all
   together. Also all spool files of all your jobs can be retrieved with one
   subcommand! The FTP server must be in JES mode to retrieve job output.

      GET <job_ID>[.<spool_file_nr>] <local_file>

   If you specify a number for <spool_file_nr> then only the corresponding
   spool file is retrieved into <local_file>.
   If you specify X for <spool_file_nr> then all spool files belonging to that
   job are retrieved into <local_file>.

   Using the MGET subcommand you can retrieve all spool files for all your jobs:

      MGET xxx

   The xxx parameter is required by the MGET subcommand but not used here. For
   each job the complete spool output is retrieved into its own file (named
   after the job ID).

   When retrieving complete job outputs the single spool files are separated by
   extra separator lines:

      !! END OF JES SPOOL FILE !!

   Retrieving a job's output does not remove it from the queue - you'll have to
   use a DELETE subcommand for that.

-------------------------------------------------------------------------------
Deleting a job and job output
-------------------------------------------------------------------------------

   Jobs can be deleted (cancelled) before, during or after execution using the
   DELETE FTP subcommand:

      DELETE <job_ID>

   All spool output related to the deleted job is also purged.

===============================================================================
Sample
===============================================================================

   The following samples all do the same:
   -  submit a job to JES
   -  wait for job end and retrieve the complete output to a local file
   -  capture FTP client and server messages during FTP session

   Principially there a 2 ways to accomplish that task with FTP:
   -  automatize the local system's FTP client.
   -  use a FTP API for the programming language you use.

   The three samples demonstrate the three possible approaches:
   -  FTP client automation:
      -  FTP commands in a file
      -  FTP commands on the REXX data stack
   -  using the REXX FTP API

Note: There are differences in automatizing the different system's FTP clients:
      -  sometimes you only need "hostname", and sometimes you need
         "open hostname" to connect to the desired host.
      -  sometimes user ID and password must be given in one line separated by
         blanks.
      -  sometimes user ID and password must be given in two consecutive lines.
      -  sometimes you need extra command line parameters.

Note: There are differences in the RXFTP APIs on different platforms - AIX,
      Linux and Windows APIs should be quite the same, the OS/2 API is somewhat
      different.

-------------------------------------------------------------------------------
Stack version
-------------------------------------------------------------------------------

Invocation details:

   CMS:  ftpstack     *host* *uid* *pwd* code.jclin jcl.out.a   ftp out a
   TSO:  ftpstack     *host* *uid* *pwd* code.jclin code.jclout code.ftpout
   USS:  ftpStack.rex *host* *uid* *pwd* code.jclin jcl.out     ftp.out

   where:
   -  Remote MVS data set *uid*.CODE.JCLIN contains JCL to submit.
   -  Local file jcl.out will contain JCL output upon return.
   -  Local file ftp.out will contain FTP client and server messages.

-------------------------------------------------------------------------------
File version
-------------------------------------------------------------------------------

Note:
   -  You have to adapt the files to your needs:
      -  *host* must be a valid host where you have a user ID
      -  *uid* and *pwd* must be a valid user ID and password
   -  On VM and MVS: the FTP subcommand input file must be unnumbered.

Invocation details:

   CMS:        ftpfile     ftpin       ftpout
   TSO:        ftpfile     code.ftpin  code.ftpout
   USS:        ftpFile.rex ftp.uss.in  ftp.out
   WIN:  rexx  ftpfile     ftp.win.in  ftp.out
   OS/2:       ftpfile     ftp.os2.in  ftp.out
   LIN:  rexx  ftpFile.rex ftp.lin.in  ftp.out
   AIX:  rexx  ftpFile.rex ftp.aix.in  ftp.out

   where:
   -  Local file ftp.***.in contains FTP commands to execute.
   -  Local file ftp.out will contain FTP client and server messages.

-------------------------------------------------------------------------------
RxFTP API version
-------------------------------------------------------------------------------

Note: Of course checking the RCs of the API functions is recommended - it is
      not done in the sample for keeping it short.

Invocation details:

   WIN:  rexx ftpapi       *host* *uid* *pwd* code.jclin jcl.out ftp.out
   LIN:  rexx ftpAPI.rex   *host* *uid* *pwd* code.jclin jcl.out ftp.out
   AIX:  rexx ftpAPI.rex   *host* *uid* *pwd* code.jclin jcl.out ftp.out
   OS/2: ftpapi            *host* *uid* *pwd* code.jclin jcl.out

   where:
   -  Remote MVS data set *uid*.CODE.JCLIN contains JCL to submit.
   -  Local file jcl.out will contain JCL output upon return.
   -  Local file ftp.out will contain FTP client and server messages. Only OS/2
      has not implemented the FtpTraceLog(...) and FtpTraceLogOff() functions,
      so there is no way to capture the FTP messages.

===============================================================================
Documentation
===============================================================================

   Can be obtained via IBM BookManager BookServer Library on the internet:

      http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr/LIBRARY

   The REXX interface and the JES facility are described in the

      IP User's Guide               (GC31-8514)

   for the "OS/390 eNetwork Communications Server", also available are:

      IP Programmer's Reference     (SC31-8515)
      IP API Guide                  (SC31-8516)
      IP Configuration              (SC31-8513)
      IP Configuration Guide        (SC31-8725)
      IP Configuration Reference    (SC31-8726)

-------------------------------------------------------------------------------

   If you experience difficulties with the herein described material you can
   get help by writing an e-mail to:

      rexxhelp@vnet.ibm.com

   Also any suggestions for improvement or bug-reports are welcome.
   HAVE FUN WITH REXX!

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