Dovetailed Technologies

3. Using the Co:Z SFTP server

3.1 Setting, displaying and clearing file transfer options

Unlike standard FTP, SFTP has no site command for setting platform specific options. Co:Z SFTP file transfer options are set with a special ls command request of the form: ls /+<name=value>. They can be cleared with a request of the form: ls /+NO<name>.

Multiple options can be set by separating the key=value pairs with commas. An error is returned if one or more of the options was incorrectly specified, but the remaining options are set as requested.

The options directory /+/ is a pseudo directory on the server, and it is possible to make it the working directory via the cd /+ command. From this directory, options may be set and listed without the /+ prefix.

The active options and their settings can be displayed by issuing the command ls /+.

Co:Z SFTP server file transfer options may be specified interactively or via configuration files. The active options are determined in the following priority order:

  1. The fixed: section of /etc/ssh/cozsftp_server_config (highest priority and non-modifiable)

  2. The first matching pattern (if any) from $HOME/.ssh/cozsftp_server_config

  3. The first matching pattern (if any) from /etc/ssh/cozsftp_server_config

  4. Previous interactive commands: ls /+ (described below) in the same session

  5. The environment variable SFTP_ZOS_OPTIONS

  6. The default: section of /etc/ssh/cozsftp_server_config (lowest priority)

For a list of available options, see Appendix B, Co:Z SFTP options.

For a description of the cozsftp_server_config file format, including how to specify file name patterns, see Appendix C, Session config files.

All examples in the following sections can be run by most sftp clients, either from z/OS or from other platforms (Windows, linux, etc..). Note: There are some differences in the way clients interact with the server, so the output shown in the examples below (performed with the OpenSSH sftp client) may not match your output exactly.

Example: Setting and displaying basic options

sftp> ls /+mode=text     1
/+mode=text
sftp> ls /+     2
/+/clientcp=iso8859-1             /+/error.log                      
/+/loglevel=I                     /+/mode=text                      
/+/servercp=IBM-1047              /+/trim
1

The option command ls /+mode=text is used to set the transfer mode to text. mode=binary is the default.

2

The option list command ls /+ shows the options currently in effect. In this case, the codepages clientcp and servercp are set to the defaults.

Example: Setting multiple options

sftp> ls /+lrecl=80,recfm=fb,space=trk.3.2     1
/+lrecl=80,recfm=fb,space=trk.3.2
1

Multiple options can be specified, separated by commas. Note that the SPACE parameter uses periods for commas to avoid ambiguity.

Example: Showing all options

sftp> ls /+showall      1
/+showall=true  
sftp> cd /+     2
sftp> ls     3
NOblksize             NObufno               clientcp=ISO8859-1    
conddisp=catlg        NOcopies              NOdataclas            
NOdest                NOdir                 NOdisp                
NOdsntype             NOdsorg               error.log             
estsize               NOforms               NOgdgnt               
NOhold                NOjesjobname          NOjesjobwait          
jeslrecl=80           jesowner=KIRK         jesrecfm=f            
jesstatus=*           NOlabel               NOlike                
linerule=flexible     loglevel=I            lrecl=80              
NOmaxvol              NOmgmtclas            mode=text             
NOmount               NOnorecall            NOoutdes              
overflow=wrap         NOpad                 recfm=fb              
NOrelease             replace               NOreqexits            
NOreset               NOretpd               NOsequence            
servercp=IBM-1047     showall               smf                   
space=trk.3.2         NOspin                NOstorclas            
NOsysout              trim                  NOtrtch               
NOucount              NOunit                NOvol                 
NOwriter              
sftp> ls noshowall,norecfm      4
noshowall,norecfm     
sftp> ls
clientcp=ISO8859-1    error.log             loglevel=I            
lrecl=80              mode=text             servercp=IBM-1047     
space=trk.3.2         trim
1

The option command ls /+showall is used to set the option listing mode to show all options, even those that are not active.

2

Since the options are treated as entries in a pseudo directory, the cd command can be used to make that directory the working remote directory.

3

Issuing the ls from the options directory will show all of the options. Those that are not active are prefixed with the string NO. Note that the options can be listed even if the current working directory is not the options pseudo dir with the command ls /+.

4

Active options can be de-activated by prefixing the option with the string NO. In this example, the showall option is cleared, as well as the recfm option.

3.2 Reading the error log

Most implementations of the sftp specification, including OpenSSH, do not allow for transmission of detailed information from the server to the client in the event of an error. Adding dataset transfers to the mix only increases the need for better error reporting. To help alleviate this problem, the Co:Z sftp implementation provides a comprehensive logging facility that can be enabled and tuned by each user session.

Several of the above option listing examples show error.log as one of the options. This is actually an alias for the running session's log file, which is usually written to the /tmp directory (See Chapter 2, Co:Z SFTP Configuration for more information on where this file is written). This alias can be used to easily retrieve the log at anytime and examine it from the client.

This feature makes it possible to examine detailed error information from the client without having to abandon the active sftp session. Users of graphical clients such as winSCP and gFTP see an even greater advantage in that the error.log file can be viewed simply by selecting the file and transferring it in view mode.

Example: Getting and displaying the error log

sftp> rm //user.coz.sampjcl     1
Removing //user.coz.sampjcl
Couldn't delete file: Failure     2
sftp> get /+/error.log     3
Fetching /+/error.log to error.log
/+/error.log                         100%   68     0.1KB/s   00:00    
sftp> !cat error.log     4
ZosUtil[E]: Dataset "USER.COZ.SAMPJCL" is a PDS. Use rmdir instead.
sftp>
1

This command attempts to delete a PDS with the rm which is not allowed.

2

The request fails, but the standard sftp error message is not very helpful.

3

To get better information, the error.log from the options directory is requested.

4

Using the local shell command cat to display the log gives detailed error information.

3.3 Working with Datasets

The Co:Z implementation of sftp accepts two prefix strings to identify MVS datasets as absolute paths. The first (//) is consistent with IBM's common usage. A secondary form (/-/) is also available, as not all sftp clients will allow double slash characters to be sent.

Navigating Datasets

The sftp cd command can be used to navigate around the z/OS dataset space. Using the dataset prefix // or /-/, the dataset space can be entered. Once there, traversal up and down various dataset levels can be performed similarly to hierarchical file systems.

Partitioned datasets are treated as directories as well. Once a PDS is made the current working directory, its members can be listed and retrieved like normal files.

Just as listing the entire catalog from the root is not allowed, it is not possible to make the catalog root the current working directory. As such, the command cd // will fail.

Example: Navigating the dataset space

sftp> cd //user     1
sftp> pwd     2
Remote working directory: //USER
sftp> cd coz.testjcl     3
sftp> pwd
Remote working directory: //USER.COZ.TESTJCL
sftp> cd ..     4
sftp> pwd
Remote working directory: //USER.COZ
1

Using the dataset prefix //, the high level qualifier user is specified. For cd commands, the dataset name is case insensitive.

2

The pwd command will list the current working dataset level. Note that the name is properly displayed in uppercase

3

Multiple levels can be traversed at a time. Instead of using the normal separator (.), a slash can be used: cd coz/testjcl.

4

The cd .. command will move up a level, as expected.

Transferring Datasets

The get and put commands are used to transfer datasets and PDS members. By default, the transfer mode is binary, and when storing new datasets, the DCB defaults are determined by the system and are often RECFM=U.

Any options previously set via the ls /+option=value are in effect for any given transfer.

[Note]Note

When using the put command to write datasets, the target name is used to determine the actual dataset name written. In most cases this determination is straight forward, but in certain circumstances, name determination is more involved. See Appendix D, Dataset Name Determination for complete details.

Example: Get a text sequential dataset

$ sftp user@zos.com     1
Connecting to zos.com...
user@zos.com's password:
sftp> ls /+mode=text     2
/+mode=text  
sftp> get //USER.LOG.MISC     3
Fetching //USER.LOG.MISC to USER.LOG.MISC
1

This example shows the full connection process, using keyboard-interactive password authentication.

2

The default transfer mode of binary is overridden and set to text.

3

The get command uses the dataset path prefix // (or, optionally /-/) to specify that a dataset is being requested.

Example: Get PDS members

sftp> ls /+     1
/+/clientcp=ISO8859-1     /+/mode=text     /+/servercp=IBM-1047      
sftp> get //user.ssh.jcl(sshd)     2
Fetching //user.ssh.jcl(sshd) to user.ssh.jcl(sshd)
1

If this transfer is performed after the prior example, the transfer mode will still be text. Using the ls /+ command quickly confirms the active options.

2

The get command uses the dataset path prefix // and pds member name in parentheses to identify the member to get. Note again that the dataset name for transfers is case insensitive.

Example: Get a PDS member

sftp> get //user.coz.sampjcl(cozproc) cozproc.txt          1
Fetching //user.coz.sampjcl(cozproc) to cozproc.txt

sftp> cd //user.coz.sampjcl     2
sftp> get runcoz     3
Fetching //USER.COZ.SAMPJCL/runcoz to runcoz

sftp> get *     4
Fetching //USER.COZ.SAMPJCL/@@README to @@README
Fetching //USER.COZ.SAMPJCL/BPXBATCH to BPXBATCH
Fetching //USER.COZ.SAMPJCL/BPXBATSL to BPXBATSL
Fetching //USER.COZ.SAMPJCL/COZCFGD to COZCFGD
Fetching //USER.COZ.SAMPJCL/COZPROC to COZPROC
Fetching //USER.COZ.SAMPJCL/DTLSPAWN to DTLSPAWN
Fetching //USER.COZ.SAMPJCL/GPGDSN to GPGDSN
Fetching //USER.COZ.SAMPJCL/GREPDSN to GREPDSN
Fetching //USER.COZ.SAMPJCL/GREPSED to GREPSED
Fetching //USER.COZ.SAMPJCL/OFFLDSMF to OFFLDSMF
Fetching //USER.COZ.SAMPJCL/RUNCOZ to RUNCOZ
Fetching //USER.COZ.SAMPJCL/RUNCOZ2 to RUNCOZ2
Fetching //USER.COZ.SAMPJCL/RUNCOZ3 to RUNCOZ3
Fetching //USER.COZ.SAMPJCL/RUNSPAWN to RUNSPAWN
Fetching //USER.COZ.SAMPJCL/RUNSPWN2 to RUNSPWN2
Fetching //USER.COZ.SAMPJCL/TDIRK to TDIRK
Fetching //USER.COZ.SAMPJCL/WGET2DSN to WGET2DSN
1

The get can be used to get a member from a fully qualified dataset.

2

The cd command is used to make a PDS the current working "directory".

3

The get command uses just the member name to retrieve the desired member.

4

The get * command can be used to retrieve all members at once.

Example: Put a text MVS dataset, overriding DCB attributes

...
sftp> ls /+mode=text,lrecl=80,recfm=fb     1
/+mode=text,lrecl=80,recfm=fb  
sftp> put afile.txt //USER.AFILE.TXT     2
Uploading afile.txt to //USER.AFILE.TXT
1

The option command ls /+mode=text,lrecl=80,recfm=fb is used to set the transfer mode to text, and set the DCB attributes for the new dataset USER.AFILE.TXT. This overrides the system default for new datasets. Input lines will be broken on CR, LF, or CRLF and lines longer than allowed by the dataset will be wrapped onto multiple records. The options linerule and overflowrule can be used to override those settings.

2

The put command uses the specialized path prefix // (or, optionally /-/) to specify the dataset name.

Listing datasets and PDS directories

MVS datasets can be listed using the sftp ls command. Partitioned datasets are treated as directories with their members as entries.

In order to support existing sftp clients, several considerations have to be made when listing datasets:

  • The ls lists multiple dataset levels (by default), and therefore can return a large amount of information. As such, listings that would involve searching the entire catalog, such as ls // or ls //A* are not allowed. Furthermore, because of the way sftp clients interact with the server, the following style of command is not supported: ls //USER.LVL1*. However, the same effect can be produced by either using directory notation for searching the catalog (ls //USER/LVL1*) or changing to the desired level and issuing a relative listing command:

    cd //USER
    ls LVL1*
  • Where possible, dataset names are treated as case insensitive. A get or put can specify the name in either lower or upper case and it will be found. However, any globbed (wildcard) ls command requires upper case characters. Individual datasets can be listed in either upper or lower case. To be safe, it is a good idea to use upper case on all list requests.

  • As mentioned above, partitioned datasets (PDS) are treated as directories. the long list form ls -l can be used to list member statistics, if statistics exist.

  • The ls accepts dataset names prefixed either by // or /-/. The second form should be used for the few sftp clients that do not allow a double slash to sent to the server.

Example: Listing datasets

sftp> cd //USER
sftp> ls -al     1
Volume  Referred  Ext  Tracks    Used Recfm Lrecl BlkSz Dsorg  Dsname
WORK84 2008/09/05   1       1       1  FB      80 27920  PS    USER.AFILE.TXT                              
WORK81 2008/09/08   1      30       ?  U        0  6144  PO-E  USER.COZ.LOADLIB                            
WORK81 2008/09/11   1      15       4  FB      80 27920  PO    USER.COZ.SAMPJCL                            
WORK84 2008/09/11   1       1       1  U        0  6144  PS    USER.COZ.TEST.SEQ                           
WORK81 2008/09/09   1      15       3  FB      80 27920  PO    USER.COZ.TESTJCL

sftp> cd //USER     2
sftp> ls CO*
COZ.LOADLIB/          COZ.SAMPJCL/          COZ.TEST.SEQ          COZ.TESTJCL/ 

sftp> ls //USER/CO*     3
//USER/COZ.LOADLIB/   //USER/COZ.SAMPJCL/   //USER/COZ.TEST.SEQ
//USER/COZ.TESTJCL/  

sftp> ls //USER.CO*     4
Couldn't get handle: Failure
Can't ls: "//USER.CO*" not found

sftp> ls //     5
Couldn't stat remote file: No such file or directory
Can't ls: "//" not found

sftp> cd //user
sftp> ls co*     6
Can't ls: "//USER/co*" not found
sftp>
1

The long form of the list command ls -al will list detailed information from the catalog about each dataset.

2

Relative listing requests can be performed by first navigating to the desired level, then issuing the list request without any prefix.

3

When using wildcards, the desired result can be achieved by using a slash (/ in place of the traditional level separator (.).

4

Due to existing sftp client design, this list request would require the entire catalog to be searched, then filtered with the pattern USER.CO*. It is therefore disallowed.

5

Lists that would involve the entire catalog are not supported. The openssh sftp client reports this as shown.

6

The same command with a lower case pattern will fail (as described above).

Example: Listing a PDS directory

...
sftp> cd //user.coz.sampjcl     1
sftp> ls -al     2
Name           Size  Created         Changed          ID
@@README 
BPXBATCH         13 2008/04/04 2008/04/04 17:18:09  USER   
BPXBATSL         16 2008/04/03 2008/04/03 10:36:52  USER   
COZCFGD          65 2008/03/27 2008/05/12 14:28:54  USER   
COZPROC          30 2008/03/27 2008/03/27 11:54:48  USER   
DTLSPAWN         40 2008/05/05 2008/05/05 09:31:08  USER   
GPGDSN           15 2008/05/05 2008/05/05 10:40:05  USER   
GREPDSN  
GREPSED          12 2008/05/05 2008/05/05 09:30:51  USER   
OFFLDSMF 
RUNCOZ           20 2008/03/27 2008/05/12 14:08:02  USER   
RUNCOZ2          15 2008/05/05 2008/05/05 10:02:51  USER   
RUNCOZ3           8 2008/05/05 2008/05/06 08:50:37  USER   
RUNSPAWN         54 2008/05/12 2008/05/12 14:25:37  USER   
RUNSPWN2         20 2008/05/12 2008/05/12 13:19:05  USER   
TDIRK            18 2008/04/03 2008/04/03 10:19:20  USER   
WGET2DSN
1

The cd command is used to make a PDS the current working "directory".

2

The ls -al command (long list form) is used to display the members of the PDS, including available statistics.

3.4 Working with POSIX files

This section describes how to use the Co:Z implementation of sftp with POSIX files (HFS, zFS) on z/OS. Standard sftp implementations (including z/OS OpenSSH) support only binary mode file transfers. The Co:Z implementation provides binary transfer mode by default, but also supports text mode transfers. Text mode transfers are controlled via the following options:

  • mode: when set to text causes file transfers to be text based.

  • clientcp and servercp: When text mode is active, these settings determine the codepage translation that will take place. The default client code page is ISO8859-1. The default server code page is the current z/OS locale.

  • linerule: When text mode is active, this setting determines how line separators are converted between the client and server.

Transferring Files

The get and put commands are used to transfer POSIX files (either on HFS or zFS filesystems).

The options (listed above) that have been previously set via the ls /+option=value are in effect for any given transfer. All other options (used for dataset support) are ignored for POSIX file transfers.

Example: Get a text POSIX file

sftp> ls /+mode=text,clientcp=UTF-8     1
/+mode=text,clientcp=UTF-8  
sftp> ls /+     2
/+/clientcp=UTF-8     /+/mode=text          /+/servercp=IBM-1047
sftp> get .ssh/sftp-server.rc     3
Fetching /u/user/.ssh/sftp-server.rc to sftp-server.rc
/u/user/.ssh/sftp-server.rc                100%  234     0.2KB/s   00:00    
sftp>
1

The default transfer mode of binary is overridden and set to text. Additionally, the client code page is explicitly set to UTF-8.

2

Displays the active options. Note that the server code page, if not explicitly set, defaults to the current z/OS locale.

3

The get command requests the transfer of the POSIX file using the options in effect.

Example: Put a text POSIX file

sftp> put sftp-server.rc .ssh     1
Uploading sftp-server.rc to /home/user/.ssh/sftp-server.rc
sftp-server.rc                             100%  234     0.2KB/s   00:00    
sftp>
1

The client text file sftp-server.rc is put to the remote directory .ssh under the current working remote directory. The active file transfer options are used.

3.5 Working with JES jobs and spool files

This section describes how to use Co:Z SFTP to submit jobs, query job status and access spool files on z/OS. Future releases of Co:Z SFTP will also support enhanced job cancel and purge facilities.

Note: Co:Z JES spool access supports both JES2 and JES3, but is currently limited to the primary JES subsystem.

Obtaining JES job status

To query the status of z/OS jobs, you simply list the "//-JES" pseudo-directory:

sftp> cd //-JES  1
sftp> ls  2
JOB00434  JOB00561  TSU00560  TSU00562  
sftp> ls -al  3
JOBNAME  JOBID    OWNER    STATUS   CLASS
KIRKL    JOB00434 KIRK     OUTPUT   A        RC=0000
TOMCAT   JOB00561 KIRK     ACTIVE   A        
KIRK     TSU00560 KIRK     OUTPUT   TSU      RC=0000
KIRK     TSU00562 KIRK     ACTIVE   TSU
sftp> ls /+jesjobname=kirk  4
/+jesjobname=kirk
sftp> ls -al  
JOBNAME  JOBID    OWNER    STATUS   CLASS
KIRKL    JOB00434 KIRK     OUTPUT   A        RC=0000
KIRK     TSU00560 KIRK     OUTPUT   TSU      RC=0000
KIRK     TSU00562 KIRK     ACTIVE   TSU
sftp> ls /+jesjobname=kirk.  5
/+jesjobname=kirk.
sftp> ls -al  
JOBNAME  JOBID    OWNER    STATUS   CLASS
KIRK     TSU00560 KIRK     OUTPUT   TSU      RC=0000
KIRK     TSU00562 KIRK     ACTIVE   TSU
sftp> ls /+nojesjobname  6
/+nojesjobname
sftp> ls /+jesowner=goetze  7
/+jesowner=goetze
sftp> ls -al
JOBNAME  JOBID    OWNER    STATUS   CLASS
GOETZEB  JOB00601 GOETZE   OUTPUT   A        RC=0000
GOETZE   TSU00505 GOETZE   OUTPUT   TSU      RC=0000
GOETZE   TSU00515 GOETZE   ACTIVE   TSU
sftp> ls /+jesstatus=active  8
/+jesowner=goetze
sftp> ls -al
JOBNAME  JOBID    OWNER    STATUS   CLASS
GOETZE   TSU00515 GOETZE   ACTIVE   TSU

1

Change to the //-JES pseudo-directory.

2

Listing the contents of the //-JES directory will by default display a list a job ids whose owner is the same as the current user.

3

Requesting a detailed listing of the //-JES directory produces a formatted list of the same jobs. Note here how jobs are sorted lexically by jobid - this is actually being done by the sftp client. Sorting on most sftp clients can be disabled; in the case of OpenSSH, use the -f switch on the ls command, eg: ls -alf will display the jobs in the order returned by the JES subsystem interface.

4

By default, all jobs owned by the current user are displayed. The jesjobname setting may be used to set a jobname filter.

5

Terminating the jesjobname setting with a period filters on an exact jobname match, rather than a prefix.

6

The jesjobname setting is turned off.

7

By default, the jesowner setting is set to the current userid. Here it is changed to a different userid.

8

The jesstatus setting may be used to filter job listings by one of the following categories: input, output, or active.

Co:Z SFTP uses the unauthorized "Extended Status" subsystem interface to obtain job status. This facility is only available if you are running z/OS 1.9 or later. A SAF(RACF) SECLABEL dominance check may be used by the IBM extended status subsystem interface to control access to this facility; refer to RACF or your security product documentation for more information.

Transferring JES spool files

Job spool files may be transferred using normal SFTP "get" commands from your SFTP client.

sftp> cd //-JES
sftp> ls -al 
JOBNAME  JOBID    OWNER    STATUS   CLASS
KIRKL    JOB00434 KIRK     OUTPUT   A        RC=0000
TOMCAT   JOB00561 KIRK     ACTIVE   A        
KIRK     TSU00560 KIRK     OUTPUT   TSU      RC=0000
KIRK     TSU00562 KIRK     ACTIVE   TSU
sftp> cd JOB00434  1
sftp> ls  2
102  2    3    4
sftp> ls -al  3
DSID STEPNAME PROCSTEP DDNAME   C OWNER    RECFM LRECL BYTES
 102 LOGDEF            SYSPRINT A KIRK     FBA     133 5195
   2 JES2              JESMSGLG A KIRK     FA      133 911
   3 JES2              JESJCL   A KIRK     V       136 271
   4 JES2              JESYSMSG A KIRK     VA      137 839
sftp> ls -alf  4
DSID STEPNAME PROCSTEP DDNAME   C OWNER    RECFM LRECL BYTES
   2 JES2              JESMSGLG A KIRK     FA      133 911
   3 JES2              JESJCL   A KIRK     V       136 271
   4 JES2              JESYSMSG A KIRK     VA      137 839
 102 LOGDEF            SYSPRINT A KIRK     FBA     133 5195
sftp> ls /+mode=text  5
/+mode=text  
sftp> get 102 logdef.text  6
Fetching //-JES.JOB00434/102 to logdef.text
//-JES.JOB00434/102
sftp>                              
sftp> get *  7
Fetching //-JES.JOB00434/102 to 102
//-JES.JOB00434/102                
Fetching //-JES.JOB00434/2 to 2
//-JES.JOB00434/2                  
Fetching //-JES.JOB00434/3 to 3
//-JES.JOB00434/3              
Fetching //-JES.JOB00434/4 to 4
//-JES.JOB00434/4              
sftp>  
sftp> get all concat.txt 8
Fetching //-JES.JOB00434/all to concat.txt
sftp> get jesysmsg  9
Fetching //-JES.JOB00434/jesysmsg to jesysmsg
sftp> get logdef.sysprint 
Fetching //-JES.JOB00434/logdef.sysprint to logdef.sysprint

1

Jobs are represented in Co:Z SFTP as directories under the //-JES pseudo-directory. Here we change the current directory to a specific job.

2

Job spool files are represented as file names with the numeric JES DSID identifier.

3

A detailed listing displays a formatted list of spool files.

4

Many sftp clients will sort the files lexically by name (dsid). The ls -f switch on the OpenSSH sftp client will preserve the natural ordering, which is by numerical dsid.

5

The transfer mode is set to text.

6

The sftp get command can be used to download spool files.

7

A wildcard get command can be used to download all spool files in the job directory.

8

The special ALL file name can be used to transfer all spool files to a concatenated output file. To ensure that the correct transfer options are set when using the ALL file name, it is recommended that the following pattern be defined in the system cozsftp_server_config configuration file:

pattern: //-JES.*.ALL
mode=text,jesincsysin

9

Spool files may also be referenced by [step.[procstep.]]ddname

Using the jesincsysin option (available on z/OS 1.10 or later):

sftp> ls /+jesincsysin  1
/+jesincsysin  
sftp> ls -alf
DSID STEPNAME PROCSTEP DDNAME   C OWNER    RECFM LRECL BYTES
   1                   JESJCLIN A KIRK     F        80 316
   2 JES2              JESMSGLG A KIRK     FA      133 911
   3 JES2              JESJCL   A KIRK     V       136 271
   4 JES2              JESYSMSG A KIRK     VA      137 839
 101 LOGDEF            SYSIN    A KIRK     F        80 177
 102 LOGDEF            SYSPRINT A KIRK     FBA     133 5195
 
sftp> get all concat.txt 2
Fetching //-JES.JOB00434/all to concat.txt
sftp>sftp> get jesjclin 3
Fetching //-JES.JOB00434/JESJCLIN to jesjclin
1

The jesincsysin option may be used to specify that the spool file listings and concatenated output will contain SYSIN spool files, including JESJCLIN.

2

When option jesincsysin is enabled, concatenated spool file downloads will include SYSIN spool files. In addition, the separator between spool files will be annotated with the [step.[procstep.]]ddname. This option is a convenient way to download all job input and output.

3

Regardless of how option jesincsysin is set, you can download individual SYSIN spool files. When downloading JESJCLIN as an individual spool file, the output will contain the other SYSIN spool files embedded in the orignal JCL.

Co:Z SFTP uses the unauthorized interface to the JES "Spool Browse" facility, which is only available if you are running z/OS 1.9 or later. As with IBM FTP, the SAF(RACF) JESSPOOL resource class is used to control access to spool files throuh the Spool Browse facility.

Submitting JES jobs

Jobs may be submitted to the JES internal reading using SFTP "put" commands from your SFTP client into a special pseudo-directory named "//-JES.INTRDR".

sftp> ls /+mode=text
/+mode=text
sftp> !cat jcl.txt  1
//SLEEP3  JOB (),'Kirk Wolf',MSGCLASS=H
//UNIX    EXEC PGM=COZBATCH
//STEPLIB DD DISP=SHR,DSN=KIRK.COZ.LOADLIB
//STDIN   DD *
for i in 1 2 3
do
  echo "Sleeping..."
  sleep 1
done
//
sftp> cd //-jes.intrdr  2
sftp> put jcl.txt myjob  3
Uploading jcl.txt to //-JES.INTRDR/myjob

sftp> ls -al  4
ALIAS    JOBNAME  JOBID    OWNER    STATUS   CLASS    COMPL
MYJOB    SLEEP3   JOB01941 KIRK     ACTIVE   A
        
sftp> ls -al
ALIAS    JOBNAME  JOBID    OWNER    STATUS   CLASS    COMPL
MYJOB    SLEEP3   JOB01941 KIRK     OUTPUT   A        RC=0000

sftp> cd myjob  5
sftp> ls -alf
DSID STEPNAME PROCSTEP DDNAME   C OWNER    RECFM LRECL BYTES
   2 JES2              JESMSGLG H KIRK     FA      133 1316
   3 JES2              JESJCL   H KIRK     V       136 373
   4 JES2              JESYSMSG H KIRK     VA      137 824
 102 UNIX              SYSOUT   H KIRK     FBA     121 308
 
sftp> get 2  2.txt
Fetching //-JES.INTRDR.MYJOB/2 to /tmp/2.txt

sftp> get all jobout.txt
Fetching //-JES.INTRDR.MYJOB/all to /tmp/jobout.txt

sftp> cd ..
sftp> put jcl.txt myjob2
sftp> ls -al
ALIAS    JOBNAME  JOBID    OWNER    STATUS   CLASS    COMPL
MYJOB    SLEEP3   JOB01941 KIRK     OUTPUT   A        RC=0000
MYJOB2   SLEEP3   JOB01943 KIRK     ACTIVE   A
  
sftp> ls /+jesjobwait  6
/+jesjobwait  
sftp> cd myjob2
sftp> get all jobout2.txt
Fetching //-JES.INTRDR.MYJOB2/all to /tmp/jobout2.txt

sftp> ls /+jesjobwait=10.1  7
sftp> ls /+nojesjobwait
    
1

Run the cat command on the sftp client to display a file containing JCL.

2

//-JES.INTRDR is a special pseudo-directory that contains any jobs submitted by the current session.

3

The JCL is submitted by uploading it using the sftp client's put command. The target file name MYJOB is a handle that can be used to refer to this job later in the same session.

4

Listing the //-JES.INTRDR directory displays all of the jobs that have been submitted in this session.

5

//-JES.INTRDR.MYJOB is a directory that contains all of the spool files for the job referenced by this handle.

6

The jesjobwait setting can be used to cause Co:Z SFTP server to wait until the job completes before listing or transferring the jobs spool files.

7

The default time limit to wait is 60 seconds with a polling interval of 2 seconds (60.2), but this can also be changed.

JES related options

The following table describes options that affect JES submit, status, and spool file transfer.

Table 3.1. JES related options

NameValueNotes
jesjobname<pattern>The value of this setting is used as a filter when listing jobs. If the value doesn't end in a period, then the value is used as the job prefix The default for this setting is nojesjobname, which means that jobs are not filtered by name.
jesowner<userid>This setting specifies the userid used to filter job listings by job owner. The default for this setting is the current MVS userid, but may be set to nojesowner or jesowner=* to disable filtering by owner.
jesstatusinput|output|activeThis setting is used to filter job listings by job status. The default for this setting is nojesstatus.
jesjobwaitsecs[.intvl]If enabled, this setting specifies the time in seconds to wait for a job to complete before listing or transferring its spool files. For most sftp clients, a cd to the job's spool file directory will also wait. If no value is specified, the default is 60.2, which means to wait up to 60 seconds, polling every 2 seconds. The default for this setting is nojesjobwait.
jeslrecl<numeric>This setting specifies the lrecl used when submitting jobs to the internal reader. The default for this setting is 80.
jesrecfmf|fb|v|vbThis setting specifies the record format used when submitting jobs to the JES internal reader. The default for this setting is F.
jesincsysin When enabled, listings and concatenated downloads of JES spool files will include SYSIN spool files. Available on z/OS 1.10 or later. The default for this setting is NOjesincsysin.

Copyright© 2009-2017 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.