Server FTP

This chapter describes the server program for FTP within Cisco IOS for S/390. It contains these sections:

• Introducing Server FTP

Provides a brief overview of the Server FTP.

• File Handling by the Server FTP

Describes how the Server FTP handles files.

• Server FTP Commands

Describes the Server FTP commands and includes a table with brief descriptions for quick reference.

• Data Set Attributes

Describes the attributes of the data sets that can be read or written by the Server FTP.

• Data Transfer Operations

Describes the commands (STOR, APPE, and RETR) that initiate data transfer.

• Character Type Rules

Describes the transformation rules for creating and retrieving character-type files.

• Binary-Type Rules

Describes the transformation rules for creating and retrieving binary-type files.

• Non-Invertible Retrieval

Describes some of the changes Server FTP makes to a file that might not be able to be undone when the file is retrieved.

• Other Features

Lists some other useful features of the FTP program.

Introducing Server FTP

The Server FTP supports large-scale remote computing on a large IBM (and compatible) mainframe. It includes these types of support:

The Server FTP supports creation and retrieval of a subset of the disk formats provided by the file system of MVS.

The MVS file system is record oriented. The FTP Server can translate character files between record structure locally and file structure remotely.

The Server FTP can transfer large files of binary data efficiently. The parameters required for record-structured binary files (STRU R, MODE B, and TYPE I) are implemented. Restart markers support restarts of large file transfers.

Server FTP lets data transfer to MVS be submitted as a batch job to MVS via the JES Internal Reader facility (see the section of this chapter on procedures for JES Internal Reader support).

File Handling by the Server FTP

The Server FTP can read an existing disk data set with a wide variety of disk formats and map it correctly into the specified FTP parameters for transmission across the network. The record-structured MVS file system forces you to set limits on the size of a record when a file is created. Many processors require this record limit to be a "card image" (80 characters). A source file prepared on a stream-oriented system and transferred to the mainframe can contain records that are too long, and you may want to specify a larger record size with the SITE command.

Handling a Record Which is Too Long

When the Server FTP receives a file and finds a record too long, it does not discard data; it folds it into multiple records and informs you of its action. As each source language has a different continuation convention, folding the data in this manner is unlikely to match any of these conventions. When the Server FTP preserves data in this manner, you can easily fix the error later.

You can also have the Server FTP truncate rather than fold with the ALLO R command. See ALLO and SITE for details.

Transferring Files to a Host

The FTP lets a character file be transferred to a host for one of three purposes: for printing, for storage and later retrieval, or for processing. Under MVS, each of these purposes requires a different file format that must be chosen when the file is created.

The translations the Server FTP performs for printing or processing are not exactly invertible if the file is later retrieved with FTP. If you want information to be stored for later retrieval in exactly the same form, you must override the default parameters with the SITE command.

For a detailed description of raveled and non-invertible files, see Non-Invertible Retrieval.

As an aid in setting data set attributes, canned attribute sets for the most common cases can be chosen by mnemonic name on the SITE command. For example, SITE PRINT chooses appropriate attributes for a print file.

Sophisticated File Handling

An experienced user can use additional facilities for more control over Server FTP operations. You can supply explicit Data Control Block (DCB) parameters in the SITE command to cause the FTP Server to create any reasonable sequential data set format used by MVS (the Server FTP may also create unreasonable formats).

Transferring Files To a Tape

The FTP server supports file transfer to and from magnetic tape volumes. This option can be specified dynamically with the FTP Server SITE command described in this chapter.

Configuration

To use this facility, you will need to set the parameters LABEL and MOUNT for the FTP statement in your APPCFGxx member of the PARM data set.

To provide installation defaults for tape data set allocation, the system administrator should set up a special GAT TYPE(TAPE) entry in the Generic Attributes Table (GAT) in APPCFGxx. Parameters of interest are COMPACT, LABEL(), PARALLELMOUNT, PRIVATE, and UNITCOUNT().

SITE Command Parameters

The Server FTP SITE command has parameters specifically for using FTP to transfer files to magnetic tape. These are:

For more information on these SITE parameters, read SITE.

Using FTP to Write to Magnetic Tape

Cataloging Data Sets

FTP attempts to catalog all data sets created on tape. If the data set name matches an existing name, the transfer will occur but the catalog will not be updated. This may create a problem if a retrieve is issued for the tape version. Therefore, it is recommended that all data sets--disk or tape--have unique names. Use the DELETE command to uncatalog tape data sets.

Writing Multiple Data Sets to Tape

Users who want to write several data sets to tape in one FTP session should be aware that each file to be transferred will generate a mount request, but it may be for a different tape unit. Dynamic allocation does not support RETAIN or UNIT AFFINITY. A workaround would be to arrange with Operations to hard mount a tape and then reference the unit in the SITE command.

Submitting Mount Requests

The mount request is issued by Cisco IOS for S/390, even if running client FTP in batch. This means that Operations should not terminate the mount request by cancelling the job requesting the mount. A WTOR message, ACC511A, is issued along with the mount request. A reply of NO to this message cancels the request.

Preventing Timeouts on Data Transfers

FTP will timeout a data transfer request if the remote does not complete the data connection in a certain time. If the remote is another MVS system using tapes (or recalling a data set) it will require a tape mount on the remote system before it can complete the data connection. For this reason, FTP will use the longer of MOUNT or HSM times, or 30 minutes if neither tape support nor HSM support is configured.

Using Tape Data Sets on Remote Hosts

The problem of a remote system using tape data sets should also be considered when configuring DATAIDLE time. If a remote is reading a multivolume , for example, it might have to stop the data transfer between volumes while the next tape is mounted. The DATAIDLE time could expire while this is happening.

Server FTP Commands

Table 5-1 lists the Server FTP commands. The Cisco IOS for S/390 Server FTP program supports most of the FTP commands defined in the FTP specification, RFC 959, File Transfer Protocol (FTP). Server FTP commands are accepted by the local FTP server when submitted by a remote client. The July 27, 1998 FTP server will reply or respond to the FTP commands listed here:

Not all of the commands listed in are documented in this publication. Only those which have been enhanced for Cisco IOS for S/390 are included. The others in this list conform to their descriptions in RFC 959. Table 5-2 lists commands not supported by the Cisco IOS for S/390 FTP server.

ALLO

The ALLO command allocates a specified amount of disk space for a subsequent STOR or APPE command. When an ALLO command specifies an upper limit on the size of the file as stored in the MVS file system, a STOR that starts successfully is guaranteed not to fail because of disk space.

Syntax Description

These are the allowable variations of the ALLO command syntax:

If an ALLO command is sent, the subsequent STOR or APPE commands operate with these MVS SPACE parameters in effect:

• T = floor (byte_count / track_length) (where T is the number of disk tracks needed)

• S = max(1, floor(T/5))

• SPACE = (TRK,(S+T,S),RLSE) for STOR or SPACE=(TRK,(,S),RLSE) for APPE

Default

The default, if no ALLO is given, is (5,3) tracks, unless this default has been changed by your Cisco IOS for S/390 site administrator.

Usage Guidelines

You can set the space parameters for creating a disk data set either explicitly with a SITE SPACE(..) command or implicitly with an ALLO integer command. If both commands are given, the SITE command SPACE parameter takes precedence. If the ALLO integer is given after a SITE SPACE(..) command, the reply is "200 NOTE: Ignored, overridden by site space."

ALLO R sets the LRECL value for a new data set. Once an ALLO R value has been set, a file received with a record longer than this limit is truncated rather than folded.

An ALLO R value makes sense only with a record-structured file. If the Server receives an ALLO R command when STRU F (file-structure) is specified, the ALLO command fails and returns the reply: "503 Command conflicts with previous commands."

HELP

The HELP command gives you introductory and reference information on the Server FTP. Output from the HELP command is delivered to you by the control connection; the output can be terminated by the Telnet Break facilities. Read Telnet Break.

Syntax Description

Default

Use the DEFAULT string to request information on the default data set attributes (DCB parameters) created or used by the Server FTP.

Usage Guidelines

Each MVS site supporting a Server FTP can provide additional help information beyond what is shown here. Valid section_title strings for Cisco IOS for S/390 are:

• AECF | AECR | AENF | AENR | AETF | ILF | ILR

• Use these parameters to request help about Server FTP operation with various TYPE and STRU settings. Table 5-3 shows the TYPE and STRU settings corresponding to each parameter:

MKD

The MKD (MaKe Directory) command creates a partitioned data set (PDS).

Syntax Description

Default

The special GAT TYPE(LIBRARY) statement (if present) overrides defaults for the MKD command.

Usage Guidelines

The pathname can be either a fully or a partially qualified data set name.

These are the possible PDS file attributes:

• Cisco IOS for S/390 space allocation defaults are SPACE(5,3) DIR(5);

• The DEFGAT initialization statement can provide installation defaults

• Any SITE commands entered override any of the above

Example

ftp> pwd
257 "'MVS.'" is current prefix
ftp> mkd mkd.pds
257-"'MVS.MKD.PDS'" partitioned dataset created with attributes:
Volser ICSPK1  Unit SYSALLDA  Dsorg PO  Recfm FB  Lrecl 80
Blksize 6160  Space 5 15 Tracks  Rlse  Dir 46
257
ftp> mkd 'mvs.help.pds'
521 "'MVS.HELP.PDS'" data set already exists.

REST

The REST (restart) command specifies that the data transfer command that follows immediately is to restart at a specified intermediate point in the file.

Syntax Description

Default

The default interval is every 500,000 data bytes.

Usage Guidelines

After a REST command, STOR and APPE have identical meanings (APPE is taken to mean STOR).

Data transfer must be in MODE B (block mode). The Server can send and accept restart markers in either STRU F or STRU R.

A file retrieved from the Server FTP includes restart markers at a specific interval. The SITE command RESTART option can change this interval or suppress restart markers entirely. When the count of bytes read from the disk since the last marker reaches the specified interval, a marker is sent at the next end of a complete logical record or segment of a spanned record.

Restart markers

Table 5-4 sent by the Server FTP consist of twelve characters that are the ASCII representation of six bytes in the format VTTRBB.

RMD

The RMD (ReMove Directory) command deletes an empty PDS. It will not delete a PDS that contains members. To delete a sequential file or a PDS containing members, use DELE.

Syntax Description

SITE

The SITE command supplies host-dependent parameters to the Server FTP, for MVS data management controls, for special FTP controls, and for generic data set attributes.

Syntax Description

Available parameters include the following:

ATtr (gat_name)
AUTOIndex
AUTOMount | NOAUTOMount
AUTORecall | NOAUTORecall
BLKsize(max_physical_block) 
BLocks
BLOCKSIze(blocksize)
CArds | SOurce | FOrtran | OBJect | LOadlib | PRINt
CD | NOCD
CHarset(table_name)
CHKptint(checkpoint_interval)
COmpact | NOCOmpact
CONDdisp(CATLG|DELETE)
CYlinder 
DAclass(sms_data_class)
DATAClas(data_class_name) 
DATASetmode
DBcsset(table_name) 
DCBdsn(data_set_name)
DCLose(data_port_close_time)
DEVNull
DIDle(data_port_idle_time)
DIrectory(blocks) 
DIRECTORYMODE
DOpen(data_port_open_time)
DSeq(number)
DUMMy
Expdt(expiration_date) | RETPD(retention_period)
FILEtype(SEQ|JES|VTOC)
FOrtran | CArds | SOurce | OBJect | LOadlib | PRINt
FULLtrk | Halftrk | VBs | VS
Halftrk | FULLtrk | VBs | VS
IBuf(numbuf bufsize)
IRBlksize(max_physical_block)
IRLrecl(logical_record_length)
IRRecfm(record_format)
ISPFEnq | NOISPFEnq
ISPFRes | NOISPFRes
JESLrecl(record_length)
JESRecfm(record_format)
LAbel(type)
LIne(logical_record_length) 
LIStfmt(OLD | IBM | SHORT)
LKEDres | NOLKedres
LOadlib | CArds | SOurce | FOrtran | OBJect | PRINt
LRecl(logical_record_length) 
MAnagementclas(management_class_name) 
MGmtclass(sms_management_class)
MIGratevol(migration_volume_serial)
MOunt(time)
NCP(number_of_DASD_buffers)
NDab(number1 number2)
NLstcase(UPPER | LOWER)
OBJect
OBUf(numbuf bufsize)
OVerwrite 
PAD(char, char) 
PARallelmount
PDse | NOPDse 
PErsist | NOPErsist
POp
PREmount
PRImary
PRINt | LOadlib | CArds | SOurce | FOrtran | OBJect
PRIVate
PUsh | POp
Qdisk(volume_serial_mask)
RDw | NORDw
RECAll(integer) | NOREcall
RECFm(record_format) 
RESEt
RESTart(integer) 
RETpd(retention_period) | Expdt(expiration_date)
RLse | NORLse
SECondary
SOurce | CArds | FOrtran | OBJect | LOadlib | PRInt 
SPace(primary_allocation, secondary_allocation)
STClass(sms_storage_class_name)
STORclas(storage_class_name) 
STRip | NOSTRip
SUbmit | NOSUbmit
TABs(integer) 
TAPE
TErse
TRACKs 
TRANopt(char_translation_mode)
UCNt(unit_count)
Unit(unit_name) 
VCNt(volume_count)
VErbose
VOlume(volume_name, volume_name, ...) 
VSEQ(volume_sequence_number) 
VBs | VS | FUlltrk | Halftrk 
VS | VBs | FUlltrk | Halftrk
WRAPrecord | NOWRAPrecord

Site Command Parameters

These parameters are described in Table 5-4.

Usage Guidelines

SITE command keywords are evaluated in left to right order. Successive SITE commands are cumulative. A later SITE command can add to or change attributes established by an earlier SITE command.

SITE command parameters can be entered in either PL/I or BAL formats. The examples for FTP3 are shown in PL/I format. Any SITE parameter that takes a keyword can be entered in either format.

If NOPERSIST is used, all SITE parameters are reset after each data transfer. If PERSIST is used, all SITE parameters remain in effect until explicitly changed via subsequent SITE commands, or reset with SITE RESET.

When a sub-parameter takes a list and more than one value is contained in the list, the list of values must be enclosed in parenthesis. Even if you choose to enter the command in BAL format, you must use parentheses around the list.

The SITE command verb is followed by a list of keyword parameters. Each keyword may normally be abbreviated to the minimum-length unambiguous string, as in TSO. (In the preceding list, the minimum abbreviation for each parameter is shown in upper-case.)

SITE parameters must be separated by a comma or a blank.

A single FTP command is limited to 80 characters. In the (unlikely) event that a SITE command exceeds 80 characters, it can be broken into two or more successive SITE commands.

If an error is found in parsing a SITE parameter, an error message is issued indicating the bad parameter, and the FTP server continues with the next parameter.

Examples

The following example illustrates the BAL format:

The following example illustrates the PL/I format:

The following example illustrates the obligatory use of parentheses when the command is entered in BAL format:

STAT

The STAT command provides partial or complete status of the Server FTP.

Syntax Description

Usage Guidelines

The commands STAT or STAT ? mean STAT ? FAPT.

The command STAT ? item_numbers gives only the specified item of the full STAT display. This is useful in debugging since the full display can be lengthy.

The command STAT path_name (where path_name is a valid MVS data set prefix specified in the form myuid.) gives catalog information on a specific group of data sets. STAT path_name gives the same information as LIST but sends it over the Telnet control connection instead of a data transfer connection.

The command STAT * gives the catalog list for the default (logged-in) directory.

Example

Data Set Attributes

This section describes the attributes of data sets that can be retrieved (read) or stored (written) by the Server FTP.

Units and Volumes

The Server FTP can write and retrieve only disk data sets stored on permanent-resident disk volumes.

Data Set Names

defprfx.name1[.name2[.name3 .. [.namen]]]

Syntax Description

Data set naming conventions can vary between MVS sites. Consult personnel at your site to learn naming conventions.

When the data set name is enclosed in single quotes, it is a fully qualified data set name. When the data set name is not enclosed in quotes, it is partially qualified. Under this Server FTP (and TSO), you normally specify data set names in a partially qualified fashion, allowing the system to prefix the installation's default prefix to the data set name.

Server FTP uses one of the three possible default prefixes:

• User ID

• none

• character strings.

If User ID is defined at your installation, then server FTP uses the User ID provided by the USER FTP command as the defprfx for prefixing. If no prefixing is defined, the data set is fully qualified and quotes are not required. If character string is defined, the installation selected a common qualifier for all data sets. Individuals can select their own data set prefix with the Change Working Directory (CWD) or Change to Parent Directory (CDUP) FTP commands.

Example

These are some examples of how to set your prefix. The first method shows the cd and cdup User commands; the second shows sending the cwd and cdup commands to the server using quote.

ftp > pwd
257 "'MYID.'" is current prefix.
ftp > cd level1
250 "'MYID.LEVEL1.'" is current prefix.
ftp > cdup
200 "'MYID.'" is current prefit
ftp > cd level2
250 "'MYID.LEVEL2.'" is current prefix.
ftp > cd 'newid'
250 "'NEWID.'" is current prefix.
ftp > quote cwd 'nextid'
250 "'NEXTID.'" is current prefix.
ftp > quote cdup
200 No prefix defined.

The Server FTP supports both simple sequential and partitioned data sets. A PDS contains an internal directory to a set of sub-data sets called members. All members of a PDS share the same data set name (dsname) and attributes. The fully qualified name of a PDS member is:

defprfx.name1[.name2[.name3 .. [.namen]]](member_name)

The member_name field has the same syntax as name1 through namen.

The Server FTP also supports Generation Data Group (GDG) data sets. A GDG data set has a similar format to a PDS but the member name takes the form 0, +n, or -n, where n is the relative generation number.

FTP Path Name Syntax

The data transfer commands STOR, APPE, RETR, DELE, RNFR, and RNTO have path_name as a parameter. With this Server FTP, path_name specifies a data set or PDS member in one of these forms:

• name1[.name2[.name3 ... [.namen]]]

• name1[.name2[.name3 ... [.namen]]](member_name)

• name1[.name2[.name3 ... [.namen]]](GDG_number)

• 'name1[.name2[.name3 ... [.namen]]]'

• 'name1[.name2[.name3 ... [.namen]]](member_name)'

• 'name1[.name2[.name3 ... [.namen]]](GDG_number)'

The first three forms are partially qualified data set names. An installation defined default prefix is prefixed to names in these forms. Typically, you use one of these forms to refer to your own data sets. The last three forms are fully qualified and are used as is by the FTP Server. The second and fourth forms are used for PDS libraries and the third and sixth forms are used for GDGs.

In addition, a member_name can be entered alone when the current directory is a partitioned data set. Read ../../../../../../../home/home.htm.

Using Wildcard Characters in FTP

The server commands STAT, LIST, and NLST accept a data set or member name mask as a parameter. The output from the command lists all data sets or members that match the mask criteria.

These are the rules for masking:

• An asterisk (*) represents zero or more consecutive characters

• A percent sign (%) represents a single character

Example

ftp> ls v*.obj
200 OK, Ready
125 Transfer started
V111.OBJ
V20.OBJ
V201.OBJ
226 Transfer complete
ftp> ls v2%.obj
200 OK, Ready
125 Transfer started
V20.OBJ
226 Transfer complete
ftp> cd v20.obj
250 "'MVS.V20.OBJ'" partitioned data set is current directory
ftp> ls ftps*
200 OK, Ready
125 Transfer started
FTPS
FTPSFTDR
226 Transfer complete
ftp> ls v*.obj(*)
200 OK, Ready
501 Wildcard characters are not permitted within a Partitioned dataset name

Partitioned Data Sets

When a CWD or CDUP command causes the prefix to match the data set name of a cataloged PDS, the PDS becomes the working directory. Subsequent data transfer commands STOR, RETR, DELE, RNFR, and RNTO, as well as the LIST, NLST, and STAT commands, will treat unquoted path names as PDS member names. In addition, the LIST and NLST commands without a path name cause a list of members for the PDS directory to be output.

Examples

ftp> pwd
257 "'MVS.'" is the current prefix
ftp> cd help.pds
250 "'MVS.HELP.PDS'" partitioned data set is current directory
ftp> dir
200 OK, Ready
125 Transfer started
  Name     VV.MM  Created    Changed     Size  Init  Mod  Id
FTPDEFAU   04.00  12/08/93   12/09/93    6:16   98   98  0 MVS
FTPINTRO   01.00  12/09/93   12/09/93    6:18  134  134  0 MVS
FTPNEWS    01:00  12/09/93   12/09/93   10:30   25   25  0 MVS
GREETING   01:00  12/08/93   12/09/93    6:19   12   12  0 MVS
226 Transfer complete
ftp> get ftpnews
200 OK, Ready
150-Dataset open with attributes:
Type A N Tabs 8 Stru F Mode S Path MVS.HELP.PDS(FTPNEWS)
Volser MVSVOL Unit SYSALLDA Dsorg PO Recfm FB Lrecl 80
Blksize 3120 Rlse
150
226 Transfer complete

In addition, the LIST, NLST, and STAT commands will accept member name masks as path names. The member name mask can be entered either alone (if the current directory is a PDS) or as part of a fully qualified PDS data set name.

ftp> ls 'mvs.help.pds(ftp*)'
200 OK, Ready
125 Transfer started
'MVS.HELP.PDS(FTPDEFAU)'
'MVS.HELP.PDS(FTPINTRO)'
'MVS.HELP.PDS(FTPNEWS)'
226 Transfer complete

If you want to treat a PDS data set path name as a prefix, enclose the fully-qualified name in quotes and append a period (.) at the end.

ftp> cd 'mvs.help.pds.'
250 "'MVS.HELP.PDS.'" is current prefix

VTOC and Catalog

Under MVS, each disk volume contains a file directory of the data sets on that volume called the volume table of contents (VTOC). Hence, any disk data set can be located via the logical path name: volume,dsname. The Server FTP lets you specify the volume name in the SITE command. Read SITE for details.

MVS Space Allocation

MVS allocates disk space to a data set in variable-sized pieces called extents. Each extent is a contiguous set of disk tracks. The byte capacity of a disk track depends on the disk model. For example, A 3380 holds a maximum of 47476 bytes per track. A data set used by the Server FTP is limited to a maximum of 16 extents. Therefore, if the disk space is fragmented, you might run out of extents before running out of total space. In such a situation, choice of appropriate space parameters is important.

Multivolume Data Sets

If a data set might require more space than is available on a single volume, you can specify that it may reside on multiple volumes using the SITE VOLUME, VCNT, or UCNT parameters. Enough space must exist on the first volume for the primary extent. When the space on the first volume is exhausted, extents will be allocated on the next volume. Up to 16 extents can be allocated on each volume.

Data Set Organization

FTP supports sequential (DSORG=PS) and partitioned (DSORG=PO) data sets. Direct access (DSORG=DA) data sets can be read sequentially but cannot be written by the Server FTP. ISAM and VSAM data sets are not supported.

Disk Format (DCB) Attributes

A data set under MVS has the DCB attributes listed in Table 5-6; the first column shows the SITE command keyword parameter(s) to set the corresponding DCB attribute:

Sequential Data Sets

A STOR or an APPE to a non-existent data set creates a new data set. The Server FTP assigns the attributes of the new data set. Additionally, the STOR operation assigns new attributes to an existing data set.

New attributes are set from default attributes chosen by the Server FTP based on the TYPE and STRU transfer parameters (read Default Data Set Attributes), or from explicit overrides of these defaults by SITE parameters.

Partitioned Data Sets

A STOR of a member into an existing PDS adds information to the data set (similar to an APPE). The attributes of the data set do not change. Any attributes set by the SITE command must match those of the existing PDS, or the Server FTP responds with this message:

554 SITE LRECL, BLKSIZE or RECFM do not match those of existing data set

504 Not implemented for that parameter, ignored.

If a new PDS is being created, either by STOR or APPE, new data set attributes are assigned by the rules in Sequential Data Sets.

Default Data Set Attributes

The Server FTP chooses default data set attributes for STRU based on the TYPE and chooses STRU transfer parameters as shown in Table 5-7:

Generic Attribute Names

You can explicitly provide a subset of DCB attributes and DD statement fields on a SITE command. Alternatively, the SITE command can specify one of the generic attribute names given in Table 5-8:

Rules for Record Formats

These rules govern Server FTP support of the record format (RECFM) data set (DCB) attribute:

• The Server FTP writes into a disk data set using any of the record formats (RECFM) listed in Table 5-9:

FA, FSA, VA, VSA, UA 

Data Set Attribute Errors

These conflicting data set attributes create the following error reply and prevent the operation:

501 LRECL or BLKSIZE invalid or inconsistent 

Appending to Empty Data Sets

These rules apply to append (APPE) operations performed to empty data sets.

JES Internal Reader Support Procedures

These rules apply to the Server FTP SUBMIT operation:

• Connect and log on to the host where the JCL resides.

• Connect and log on to your IBM host where Cisco IOS for S/390 is running.

• Use a QUOTE type command to send a SITE SUBMIT command to the IBM host (such as, QUOTE SITE SUBMIT).

• Issue a PUT, GET, or SEND command of the data set on the host where the JCL resides to any name on the IBM host (such as, PUT IEBPTPCH any_name). The JCL can reside in a physical sequential data set or as a member of a partitioned data set. The new name (any_name) on the IBM host is ignored and Cisco IOS for S/390 submits the job to the JES internal reader.

Defaults

The server FTP defaults to RECFM=FB,LRECL=80,BLKSIZE=20000.

The defaults can be overridden by the Cisco IOS for S/390 administrator using the special GAT TYPE(INTRDR) entry.

Usage Guidelines

The DCB attributes used by Server FTP to allocate the JES internal reader can be explicitly set by the user with the server FTP SITE IRRECFM, IRLRECL, and IRBLKSIZE commands.

Examples

The following examples show JCL streams that can be submitted using SITE SUBMIT to cause the printing of the data included in the submitted job:

//IEBPTPCH JOBCARD 
//* 
//*     IF THIS JOB STREAM RESIDES ON YOUR REMOTE HOST, YOU CAN
//*     SUBMIT THIS JOB TO THE JES INTERNAL READER OF 
//* 
//*     YOUR IBM SYSTEM BY ENTERING THE FOLLOWING COMMANDS: 
//* 
//*     FTP MVS * CONNECT TO THE IBM HOST 
//*     USERID/PSW * LOGIN TO THE IBM HOST 
//*     QUOTE SITE SUBMIT * NOTIFY SNS/TCP SFTP TO 
//*     PUT IEBPTPCH * SUBMIT JCL TO JES INTERNAL READER
//PTPCH       EXEC PGM=IEBPTPCH 
//SYSPRINT    DD SYSOUT=A 
//SYSIN       DD   *
  PRINT PREFORM=FBA 
//SYSUT2      DD SYSOUT=* 
//     *SYSUT1 CAN BE PS OR MEMBER OF A PDS THAT RESIDES ON THE
//     *MVS SYSTEM 
//     *ONE CAN INCLUDE THE PRINT FILE AS INSTREAM DATA AS 
//     *SHOWN IN THIS EXAMPLE 
//* 
//SYSUT1      DD DATA 
  (include print file here)
//IEBGENER JOBCARD 
//*     THIS JOB STREAM RESIDES ON YOUR REMOTE HOST, YOU CAN
//*     SUBMIT THIS JOB TO THE JES INTERNAL READER OF YOUR IBM
//*     SYSTEM BY ENTERING THE FOLLOWING COMMANDS: 
//* 
//*     FTP MVS  * CONNECT TO THE IBM HOST 
//*     USERID/PSW  * LOGIN TO THE IBM HOST 
//*     QUOTE SITE SUBMIT  * NOTIFY SNS/TCP SFTP TO 
//*     PUT IEBGENER  * SUBMIT JCL TO JES INTERNAL READER
//GENER       EXEC PGM=IEBGENER 
//SYSPRINT    DD SYSOUT=* 
//SYSIN       DD DUMMY 
//SYSUT2      DD SYSOUT=*
//*     SYSUT1 CAN BE PS OR MEMBER OF A PDS THAT RESIDES ON THE
//*     MVS SYSTEM. ONE CAN INCLUDE THE PRINT FILE AS INSTREAM DATA
//*     AS SHOWN IN THIS EXAMPLE 
//* 
//SYSUT1       DD DATA
  (include print file here)

Data Transfer Operations

This section describes the operation of data transfers by the Server FTP.

Transfer Commands

Table 5-10 lists options invoked by the PUT, APPE, and GET commands that initiate data transfer:

Truncating and Folding Records

The Server FTP generally folds rather than truncates a network record that exceeds LRECL (or BLKSIZE, for an unblocked data set). You can force truncation with an ALLO R command.

Raveled Files

A raveled file is a file that contains the network data concatenated into the file with no record markers. Such a file can be created and later retrieved with FTP without loss of information. However, it is not usually possible to process it with any IBM utility. The only transformation generally done on a raveled file is to translate between ASCII and EBCDIC for TYPE A.

Padding Fixed-Length Records

If the data set has a RECFM containing F (in other words, it has fixed-length logical records), and if it is not raveled, the Server FTP does these steps:

• Pads each record being written to the next LRECL.

• Removes trailing pad characters from each record read from disk.

The pad character is normally blank for character types and zero for binary types. However, the SITE command PAD option can set it to a different value. Although this is not strictly invertible, in most cases it saves transmission time and network bandwidth. The statistics at the end of a file transfer contain the number of records padded if this number is nonzero.

Translation

For the ASCII transfer (TYPE AN, TYPE AT, or TYPE AC), EBCDIC data in a disk file is translated to ASCII over the network and vice versa. The Server FTP always stores data on disk in EBCDIC.

Line Image Files

A line image file is defined by FTP parameters STRU F, one of the character types (TYPE AN, TYPE EN, TYPE AT, or TYPE ET), and a blocked disk data set (in other words, not raveled). With line image files, end-of-line (EOL) in the network data is mapped to MVS end-of-record and vice versa. Network end-of-line is normally NL (EBCDIC) or CRLF (ASCII). However, CRLF is also recognized in EBCDIC network data. Isolated CR or LF characters are not recognized as an EOL sequence.

Record Structured Files

For the FTP parameter STRU R, a network record is mapped into an MVS logical record and vice versa.

501 print type and STRU R requires blocked data set. 

Tabs

Horizontal tab characters (HT) received from the network are expanded and/or deleted in accordance with the current SITE command TABS option setting. Default is a tab every eight columns; this can be overridden by the SITE TABS command.

Carriage Control and Format Effectors

For character types with format

ple locally applied rules that do not require buffering data. These rules are invertible between storing and retrieving data with the same parameters.

Character Type Rules

This section describes the transformation rules for creating and retrieving character-type (TYPE A or TYPE E) files.

In all cases, the network data can be ASCII or EBCDIC, but a disk data set is always EBCDIC. In addition, an HT character in a received file being stored (via STOR or APPE) is always handled in accordance with the current TABS value.

File Structure with No Format Control

The STRU F command with TYPE AN or TYPE EN parameters define a file-structured (line-image) character file with no format control. Generally, with these parameters, network lines are mapped to and from logical records. The network data can be parsed into a series of lines, using the following syntax

Syntax Description

Usage Guidelines

Other format effectors, including isolated CR and LF characters, can be included in text.

Line Image Files

If the data set to be written or retrieved is blocked (RECFM includes B), the file is assumed to contain line images.

Storing Line Image Files

These rules apply to line image files being stored (via STOR or APPE):

• An ASCII file (TYPE A) is translated to EBCDIC.

• The text is scanned for the EOL sequence (CRLF or NL).

• Each line is mapped into an MVS logical record, and the EOL sequence is discarded.

• A line that exceeds the target file LRECL is folded into subsequent logical record(s) rather than being truncated.

• A null record is stored as all pad characters if the RECFM includes F, zero data bytes if the RECFM includes V, or x'00' if the RECFM is U.

• If the data set has fixed length records (RECFM includes F), each line is padded with blanks (or the PAD character specified via the SITE command) to the next logical record boundary.

• Any control characters (including format effectors but not including the EOL sequence) are left in the data stream.

• If the data set has ASA carriage control (RECFM includes A), a blank Carriage Control Character (CCC) is inserted at the beginning of each logical record.

Retrieving Line Image Files

These rules apply to line image files being retrieved (via RETR):

• Each MVS logical record is mapped into a line with an EOL sequence inserted after each line.

• If the type is ASCII (TYPE A), the data is translated from EBCDIC to ASCII.

• If the data set has fixed-length logical records (RECFM includes F), all trailing blanks (or the PAD character specified via the SITE command) are stripped off.

• If the data set has ASA carriage control (RECFM includes A), an additional transformation is applied. If the ASA CCC is the first character of the logical record and text is the rest, the data shown in Table 5-11 is sent over the network:

Raveled Files

If the data set to be written or retrieved is unblocked (RECFM does not include B), the file is assumed to be a raveled file and is treated as a single-byte string.

Storing Raveled Files

The rules in this list apply to a raveled file being stored (via STOR or APPE).

The data set stored on disk is a concatenation of the network data. That is, the network data is folded into logical records.

An ASCII file (TYPE A) is translated to EBCDIC.

Retrieving Raveled Files

These rules apply to a raveled file being retrieved (via RETR):

• The network data set is a concatenation of the retrieved logical records. That is, the logical records retrieved from disk are raveled into a single stream of bytes for transmission across the network.

• If the data set has ASA carriage control (RECFM includes A), the CCC is deleted and is not included in the network data.

• If the type is ASCII (TYPE A), the data is translated from EBCDIC to ASCII.

File Structure with Telnet Format

The STRU F command with TYPE AT or TYPE ET parameters define a file-structured character file with Telnet format effectors. Generally, with these parameters, a network line maps to/from a logical record. The network data can be parsed into a series of segments using the following format:

Syntax Description

Usage Guidelines

Data storage with these parameters follows the same rules as storage of STRU F, TYPE AN or TYPE EN, with one exception. In the line image case, if the data set being stored into (via STOR or APPE) has ASA carriage control (RECFM includes A), the CCC is not set to blank (as in the STRU F, TYPE AN or TYPE EN case) but is determined from the network data according to the table in Retrieving Line Image Files. Any format effectors not involved in this transformation are left in the data stream.

Retrieval of data using these parameters follows the same rules as retrieval of STRU F, TYPE AN or TYPE EN.

File Structure with ASA Format

The STRU F command with TYPE AC or TYPE EC parameters define a file-structured (line-image) print file containing ASA carriage control. Generally, with these parameters, a network line maps to/from a logical record. The network data consists of these parameters:

Syntax Description

Line Image Files

With these parameters, if the data set to be written or retrieved is blocked (RECFM includes B), the file is considered to be line images.

Storing Line Image Files

These rules apply to line image files being stored (via STOR or APPE).

• An ASCII file (TYPE A) is translated to EBCDIC.

• The text is scanned for the EOL sequence (CRLF or NL).

• Each line is mapped into a logical record, and the EOL sequence is discarded.

• A line that exceeds the target file LRECL is folded into subsequent logical record(s), and a warning message is issued. If the file being written has ASA carriage control, each of the subsequent logical records is stored with a blank CCC.

• A null record is stored as all pad characters if the RECFM includes F, zero data bytes if the RECFM includes V, or x'00' if the RECFM is U.

• If the data set has fixed length records (RECFM includes F), each line is padded with blanks (or the PAD character specified via the SITE command) to the next logical record boundary.

• Any control characters (including format effectors but not including the EOL sequence) are left in the data stream.

• If the data set has ASA carriage control (RECFM includes A), the ASA CCC from the network data is used as the CCC for the stored logical record. If the data set does not have ASA carriage control, the first character of the network record is not stored in the logical record.

The Server FTP writes such a print file only into a blocked data set (RECFM includes B).

Retrieving Line Image Files

When a RETR operation is performed with these TYPE and STRU parameters from a blocked data set, a new line image file is created and sent over the network. These rules apply to line image files being retrieved (via RETR):

Raveled Files

If the data set to be written or retrieved is unblocked (RECFM does not include B), the file is considered to be a raveled file and is treated as a single string of bytes.

Storing Raveled Files

The Server FTP does not write a raveled (unblocked) file with these data transfer parameters.

Retrieving Raveled Files

These rules apply to a raveled file being retrieved (via RETR):

• The network data set is a concatenation of the retrieved logical records. That is, the logical records retrieved from disk are raveled into a single stream of bytes for transmission across the network.

• If the type is ASCII (TYPE A), the data is translated from EBCDIC to ASCII.

• If the data set has ASA carriage control (RECFM includes A), the CCC of the first logical record is included in the network data. Any other carriage control is deleted. If the data set does not have carriage control, a + CCC is inserted at the beginning of the network data, and no other carriage control is inserted.

Record Structure with No Format

The STRU R command with TYPE AN, TYPE EN, TYPE AT, or TYPE ET parameters define a character file with record structure. Generally, network records are mapped to/from logical records.

Syntax Description

Storing Logical Records

These rules apply to files being stored (using STOR or APPE) with these parameters:

• An ASCII file (TYPE A) is translated to EBCDIC.

• A null record is stored as all pad characters if the RECFM includes F, zero data bytes if the RECFM includes V, or x'00' if the RECFM is U.

• A network record longer than ALLO R (if specified) is truncated, and a warning message is issued.

• If a network record (after possible ALLO R truncation) is longer than LRECL, it is folded into subsequent logical record(s) and a warning message is issued.

• If the data set has fixed length logical records (RECFM includes F), each network record is padded with blanks (or the PAD character specified via the SITE command) to the next logical record boundary.

• If the data set has ASA carriage control (RECFM includes A), the CCC is normally blank, and any embedded ASCII format effectors are treated as data. However, if the TYPE is AT or ET, the escape sequences shown in Retrieving Logical Records (F and R) are scanned for and used to set CCC if found in the network data. No scanning for the escape sequences occurs with TYPE AN or TYPE EN.

The Server FTP writes a print file with Telnet format effectors (TYPE AT or TYPE ET) only into a blocked data set (RECFM includes B).

Retrieving Logical Records

These rules apply to files being retrieved (via RETR) with these parameters:

• Each logical record (RECFM includes B) or each physical record (RECFM does not include B) is mapped into a network record. If the data set is unblocked (raveled), the network data is a concatenation of the logical records. The other transformations described in the following steps still apply.

• If the data set has fixed length logical records (RECFM includes F), all trailing blanks (or the PAD character specified via the SITE command) are stripped off before data is sent on the network. This occurs even for unblocked data sets. A completely blank (or null) record is sent as a null record with the appropriate end of record sequences based on mode.

• If the type is ASCII (TYPE A), the data is translated from EBCDIC to ASCII.

• If the data set has ASA carriage control (RECFM includes A), an additional transformation is applied. Table 5-12 shows the transformations that map the CCC in the disk data set into network data. A one-to-many relationship can occur between disk records and network records:

Record Structure with ASA Format

The STRU R command with TYPE AC or TYPE EC parameters define a record-structured print file containing ASA carriage control. Generally, with these parameters, network records map to/from logical records.

Syntax Description

Storing Print Files

These rules apply to files being stored (via STOR or APPE) with these parameters:

• An ASCII file (TYPE A) is translated to EBCDIC.

• A null record is stored as all pad characters if the RECFM includes F, zero data bytes if the RECFM includes V, or x'00' if the RECFM is U.

• A network record longer than ALLO R (if specified) is truncated, and a warning message is issued.

• If a network record (after possible ALLO R truncation) is longer than LRECL, it is folded into subsequent logical record(s) and a warning message is issued. If the file being written has ASA carriage control (RECFM includes A), each of the subsequent logical records is stored with a blank CCC.

• If the data set has fixed length logical records (RECFM includes F), each network record is padded with blanks (or the PAD character specified via the SITE command) to the next logical record boundary.

• If the data set has ASA carriage control (RECFM includes A), the ASA CCC from the network data (cc) is used as the CCC for the stored logical record. Otherwise, the first character of the network data is deleted and is not stored in the logical record.

The Server FTP writes such a print file only into a blocked data set (RECFM contains B).

Retrieving Print Files

These rules apply to files being retrieved (via RETR) with these parameters:

• Each logical record (RECFM includes B) or each physical record (RECFM does not include B) is mapped into a network record. If the data set is unblocked (raveled), the network data set is a concatenation of the logical records. The other transformations described in the following steps still apply.

• If the data set has fixed length logical records (RECFM includes F), all trailing blanks (or the PAD character specified via the SITE command) are stripped off before sending on the network. This occurs even for unblocked data sets. A completely blank (null) record is sent as a null record with the appropriate end of record sequences based on mode.

• If the type is ASCII (TYPE A), the data is translated from EBCDIC to ASCII.

• If the retrieved data set has ASA carriage control (RECFM includes A), the CCC from the logical record is passed as part of the network record. Otherwise, a blank CCC is inserted at the beginning of each network record, except for the first record, into which a + CCC is inserted.

Binary-Type Rules

This section describes the transformation rules for creating and retrieving binary-type (TYPE I or TYPE L) files. The term "image-type" is used interchangeably with "binary-type" in the information in this section.

No Record Structure

The STRU F command with TYPE I or TYPE L parameters define a binary file without record structure.

Storing Binary Files

These rules define the transformations to such a file when it is stored (via STOR or APPE) by the Server FTP:

• The received network data is folded into maximum-length logical records when stored by the Server FTP.

• If a null (zero-length) network record is received, it is ignored.

• No translation, truncation, or padding is performed on the data.

Since the contents of an image-type file are considered to be untranslatable as characters, it is assumed not to be a print file. Therefore, the Server FTP does not write image-type data into a print data set (RECFM includes A).

Retrieving Binary Files

These rules define the transformations to such a file when it is retrieved (via RETR) by the Server FTP:

• The retrieved logical records are concatenated into a single stream of network data.

• No translation, truncation, or removal of padding is performed on the retrieved data.

Since the contents of an image-type file are considered to be untranslatable as characters, it is assumed not to be a print file. Therefore, the Server FTP does not retrieve from a print data set (RECFM includes A).

Record Structure

The STRU R command with TYPE I or TYPE L parameters define a binary file with record structure.

Storing Structured Binary Files

These rules define the transformations to such a file when it is stored (via STOR or APPE) by the Server FTP:

• If a network record with zero data bytes is received, it is stored as all pad characters if RECFM includes F, zero data bytes if RECFM includes V, and x'00' if RECFM is U.

• A network record longer than ALLO R (if specified) is truncated to ALLO R, and a warning message is issued.

• If a record (possibly truncated to ALLO R) is longer than the maximum logical record length, it is folded into multiple logical records, and a warning message is issued.

• If the data set has fixed-length logical records (RECFM includes F), each network record is padded with zeros (or the PAD character specified via the SITE command) to the next logical record boundary.

• No translation is performed on the data.

Since the contents of an image-type file are considered to be untranslatable as characters, it is assumed not to be a print file. Therefore, the Server FTP does not write image-type data into a print data set (RECFM includes A).

Retrieving Structured Binary Files

These rules define the transformations performed on such a file when retrieved (via RETR) by the Server FTP:

• The retrieved logical records are mapped into network records.

• If the data set has fixed length records (RECFM includes F), all trailing zero bytes (or the PAD character specified via the SITE command) are stripped off before sending on the network.

• No translation is performed on the retrieved data.

Since the contents of an image-type file are considered to be untranslatable as characters, it is assumed not to be a print file. Therefore, the Server FTP does not retrieve from a print data set (RECFM includes A) for transmission as image-type data

Non-Invertible Retrieval

Unless a file is raveled, storing it with the Server FTP might transform the data in ways that are not strictly invertible. (That is, if the file is later retrieved using the same parameters, it might not be identical to the original file sent to this Server FTP.) The file would generally mean the same thing, but some of its byte stream is changed.

Sources of Non-Invertibility

Here are some of the sources of non-invertibility introduced when a file is stored by this Server FTP:

• All files

If the data is stored into a data set with fixed-length blocks and if a record/line ends with the pad character the Server FTP uses to pad the block, that pad character is stripped off when the file is retrieved.

• Character files

HTs might be expanded to blanks during storage and not be reintroduced when the file is retrieved.

LF and FF, which do not appear at the left margin, insert blanks to position the virtual print head correctly. On RETR, these blanks and the extra CRLF that were not in the original input are returned to the remote host.

NL is used interchangeably with CRLF in an EBCDIC file. Therefore, CRLF received in such a file is sent out as an NL.

LFs preceding an FF with no intervening data are removed.

Other Features

This section lists some other useful features of the FTP program.

Testing and Debugging

The STAT display includes the Internals section that contains a number of important control fields and pointers. This information is generally of interest only to the system programmer.

The TCP-level tracing and debugging facilities are described in the Cisco IOS for S/390 Customization Guide.

Telnet Break

The Telnet commands IP, BRK, or CONTROL-C on the control connection stops output from commands such as HELP and STATUS.