Server FTP
Available Languages
Table Of Contents
File Handling by the Server FTP
Handling a Record Which is Too Long
Using FTP to Write to Magnetic Tape
Using Wildcard Characters in FTP
JES Internal Reader Support Procedures
Truncating and Folding Records
Carriage Control and Format Effectors
File Structure with No Format Control
File Structure with Telnet Format
File Structure with ASA Format
Record Structure with No Format
Record Structure with ASA Format
Storing Structured Binary Files
Retrieving Structured Binary Files
Server FTP
This chapter describes the server program for FTP within Cisco IOS for S/390. It contains these sections:
Provides a brief overview of the Server FTP.
•
File Handling by the Server FTP
Describes how the Server FTP handles files.
Describes the Server FTP commands and includes a table with brief descriptions for quick reference.
Describes the attributes of the data sets that can be read or written by the Server FTP.
Describes the commands (STOR, APPE, and RETR) that initiate data transfer.
Describes the transformation rules for creating and retrieving character-type files.
Describes the transformation rules for creating and retrieving binary-type files.
Describes some of the changes Server FTP makes to a file that might not be able to be undone when the file is retrieved.
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.
Individual warning messages are not issued for folded records. The Server FTP counts records folded and sends that count at the end of file transfer (if it is non-zero).
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.
Note
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).
Also, the Server FTP's default formats for creating new data sets are those generally used by MVS programs. You can override these formats to obtain information-conserving storage on the mainframe. The Server FTP lists the full MVS data set attributes as well as the FTP transfer parameters when a transfer starts and reports full statistics when the transfer completes.
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().
For more information on these parameters, refer to the Cisco IOS for S/390 Customization Guide.
SITE Command Parameters
The Server FTP SITE command has parameters specifically for using FTP to transfer files to magnetic tape. These are:
•
•
•
•
•
•
•
•
These parameters are available for using FTP to transfer files to disk, but may have special significance for transferring files to magnetic tape:
•
•
•
•
•
•
FTP Server Commands APPE and RESTART are not currently supported for the FTP to Tape facility.
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.
Cataloged tape data sets are assumed to exist on standard label tapes. Use the SITE command with LABEL and DSEQ parameters when retrieving a cataloged tape data set if the tape does not have standard labels. It is recommended that you use standard label tapes whenever possible.
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
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 January 16, 2008 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. lists commands not supported by the Cisco IOS for S/390 FTP server.
Table 5-2
Commands Not Supported by the Cisco IOS for S/390 Server
The supported FTP commands are described in detail throughout the remainder of this chapter. The HELP command also provides information about the Server FTP. Read HELP for guidelines on using the HELP command.
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:
•
•
•
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.
This HELP syntax allows you to request HELP for a command_name or section_title option, but not with both. When no option is specified, general help information is given.
HELP [command_name | section_title]
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:
•
•
Table 5-3
AECF
AC or EC
STRU F
AECR
AC or EC
STRU R
AENF
AN or EN
STRU F
AENR
AN or EN
STRU R
AETF
AT or ET
STRU F
ILF
I or L
STRU F
ILR
I or L
STRU R
Using the TYPE and STRU Settings
INTRO
•
NEWS
•
PATH
•
SPACE
•
MKD
The MKD (MaKe Directory) command creates a partitioned data set (PDS).
MKD pathname
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:
•
•
•
Example
ftp> pwd257 "'MVS.'" is current prefixftp> mkd mkd.pds257-"'MVS.MKD.PDS'" partitioned dataset created with attributes:Volser ICSPK1 Unit SYSALLDA Dsorg PO Recfm FB Lrecl 80Blksize 6160 Space 5 15 Tracks Rlse Dir 46257ftp> mkd 'mvs.help.pds'521 "'MVS.HELP.PDS'" data set already exists.
Note
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.
REST restart_marker
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
sent by the Server FTP consist of twelve characters that are the ASCII representation of six bytes in the format VTTRBB.
Table 5-4 Restart Markers Sent by the Server FTP
V
Volume sequence number
TTR
Standard MVS disk block address (referred to in IBM publications as a relative track and record address)
BB
A byte offset within a TTR block
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.
RMD path_name
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.
SITE parameter [ , ]...
Syntax Description
Available parameters include the following:
ATtr (gat_name)AUTOIndexAUTOMount | NOAUTOMountAUTORecall | NOAUTORecallBLKsize(max_physical_block)BLocksBLOCKSIze(blocksize)CArds | SOurce | FOrtran | OBJect | LOadlib | PRINtCD | NOCDCHarset(table_name)CHKptint(checkpoint_interval)COmpact | NOCOmpactCONDdisp(CATLG|DELETE)CYlinderDAclass(sms_data_class)DATAClas(data_class_name)DATASetmodeDBcsset(table_name)DCBdsn(data_set_name)DCLose(data_port_close_time)DEVNullDIDle(data_port_idle_time)DIrectory(blocks)DIRECTORYMODEDOpen(data_port_open_time)DSeq(number)DUMMyExpdt(expiration_date) | RETPD(retention_period)FILEtype(SEQ|JES|VTOC)FOrtran | CArds | SOurce | OBJect | LOadlib | PRINtFULLtrk | Halftrk | VBs | VSHalftrk | FULLtrk | VBs | VSIBuf(numbuf bufsize)IRBlksize(max_physical_block)IRLrecl(logical_record_length)IRRecfm(record_format)ISPFEnq | NOISPFEnqISPFRes | NOISPFResJESLrecl(record_length)JESRecfm(record_format)LAbel(type)LIne(logical_record_length)LIStfmt(OLD | IBM | SHORT)LKEDres | NOLKedresLOadlib | CArds | SOurce | FOrtran | OBJect | PRINtLRecl(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)OBJectOBUf(numbuf bufsize)OVerwritePAD(char, char)PARallelmountPDse | NOPDsePErsist | NOPErsistPOpPREmountPRImaryPRINt | LOadlib | CArds | SOurce | FOrtran | OBJectPRIVatePUsh | POpQdisk(volume_serial_mask)RDw | NORDwRECAll(integer) | NOREcallRECFm(record_format)RESEtRESTart(integer)RETpd(retention_period) | Expdt(expiration_date)RLse | NORLseSECondarySOurce | CArds | FOrtran | OBJect | LOadlib | PRIntSPace(primary_allocation, secondary_allocation)STClass(sms_storage_class_name)STORclas(storage_class_name)STRip | NOSTRipSUbmit | NOSUbmitTABs(integer)TAPETErseTRACKsTRANopt(char_translation_mode)UCNt(unit_count)Unit(unit_name)VCNt(volume_count)VErboseVOlume(volume_name, volume_name, ...)VSEQ(volume_sequence_number)VBs | VS | FUlltrk | HalftrkVS | VBs | FUlltrk | HalftrkWRAPrecord | NOWRAPrecordrecord_format = F | FB | FBS | FBA | FBSA | V | VB | VS | VBA | VBS | U
Site Command Parameters
These parameters are described in .
Table 5-5 SITE Command Parameters
ATTR(gat_name)
Specifies any entry in the Generic Attributes table. Read Generic Attribute Names for details.
This command is not supported for the FTP to Tape Facility.
AUTOINDEX
Requests that the data set sequence number be increased by one for each subsequent file transfer.
AUTOMOUNT | NOAUTOMOUNT
AUTOMOUNT is an alias for MOUNT.
NOAUTOMOUNT is an alias for NOMOUNT.
AUTORECALL | NOAUTORECALL
AUTORECALL is an alias for RECALL.
NOAUTORECALL is an alias for NORECALL.
BLKSIZE(maximum_physical_block_length)
BLOCKSIZE(maximum_physical_block_length)
LRECL (logical_record_length)
or LINE (logical_record_length)RECFM(record_format)
Explicitly sets the DCB or format attributes of a new data set referenced by a STOR or APPE. If the data set is being created, these parameters override the defaults determined by the FTP TYPE or STRU commands. If the data set exists, these parameters must exactly match the corresponding attributes of the data set.
BLOCKSIZE is an alias for BLKSIZE.
BLOCK
Space allocation is to be in blocks.
CARDS | SOURCE| FORTRAN | OBJECT | LOADLIB | PRINT
Specifies one of the standard Generic Attribute Names supplied with Cisco IOS for S/390. Read Generic Attribute Names for details.
CD | NOCD
CD enables directory commands (CWD, PWD, CDUP). NOCD disables directory commands.
Note The CD | NOCD parameter is not reset when data transfer begins.
CHARSET (table_name)
Selects an alternate character set (translation) table for single-byte data transfer ASCII data. This table is validated for single-byte data.
CHKPTINT(checkpoint_interval)
Specifies the number of logical records between restart markers.
CONDDISP(CATLG | DELETE)
Specifies the conditional disposition for new data sets created by STOR or APPE when the file transfer fails.
COMPACT
Specifies IDRC compaction for 3480 tapes.
CYLINDER
Space allocation is to be in cylinders.
DACLASS(sms_data_class)
Alias for DATACLASS.
DATACLASS(data_class_name)
Specifies the SMS data class.
DATASETMODE
Requests the FTP server to display directory output (LIST/NLST) in data set mode. Each data set is listed individually.
DBCSSET(table_name)
Selects an alternate character set (translation) table used for double-byte data transfer ASCII data. This table will be validated for double-byte data.
DCBDSN(data_set_name)
Specifies a model data set for data set attributes.
DCLOSE(data_port_close_time)
Specifies the time, in seconds, FTP will wait to close a data port.
DEVNULL
Requests that the FTP server allocate a dummy (NULLFILE) data set for storing a data set with the STOR command.
DIDLE(data_port_idle_time)
Specifies the time, in seconds, FTP will wait on an idle data port. Minimum value = 60 seconds. Maximum value=1439 minutes.
DIR(blocks)
Integer number of 256-byte blocks to be reserved for a PDS directory. One block holds from 7 (load module) to 16 (source module) member entries. This parameter is required to create a new PDS with a STOR or APPE command.
DIRECTORYMODE
Requests that the FTP server display directory output (LIST/NLST) in directory mode. Data sets which have the same qualifier at the level immediately below the prefix level are grouped together as "pseudo-directories".
Example
The following example illustrates the use of the DIRECTORY MODE parameter.
ftp> quote site directorymode200 OK, Readyftp> dir v*125 List started OK.Volume Unit Referred Ext Used Recfm Lrecl BlkSz Dsorg DsnameICS009 3390 03/19/96 1 1 VS29389 29393 PS VSPseudo Directory V191Pseudo Directory V211Pseudo Directory V311Pseudo Directory V410250 List completed successfully.DOPEN(data_port_open_time)
Specifies the time, in seconds, FTP will wait to open a data port.
DSEQ
Specifies data set sequence number.
DUMMY
This is an alias for DEVNULL.
EXPDT | RETPD
Specifies expiration date and retention period.
EXPDT(expiration_date)—Specifies an expiration date for a new data set, in the format:
expiration_date = yyyyddd or yyyy/dddNote yyyy is a year from 1900 to 2155, ddd is a julian date from 1 to 366. You must include any leading zeroes in the ddd value.
RETPD(retention_period)—Specifies a retention period for a new data set retention_period is a number of days between 1 and 9999.
Note EXPDT and RETPD are mutually exclusive.
FILETYPE(SEQ | JES | VTOC)
Specifies the type of file the FTP server is working with:
SEQ—Sequential files. This command is the same as issuing a SITE NOSUBMIT command.
JES—JES spool. Data is written to the JES internal reader. FILETYPE=JES is the same as issuing a SITE SUBMIT command.
VTOC—DASD VTOC records. Directory commands list statistics from the Volume Table of Contents for DASD volumes.
Default: SEQ
Note You cannot do a GET of spool files or display the JES spool queue with the DIR command.
FORTRAN | CARDS | SOURCE| OBJECT | LOADLIB | PRINT
See the description for CARDS.
FULLTRK | HALFTRK | VBS | VS
Specifies general attributes for a data set.
HALFTRK | FULLTRK | VBS | VS
See the description for FULLTRK.
IBUF(numbuf bufsize)
Specifies in sublist notation the number of network input buffers (numbuf) and the buffer size (bufsize) to be used during data transfer. The maximum value for each number is 32767.
Note Your Cisco IOS for S/390 system administrator might have set restrictions on use of the IBUF parameter.
IRBLKSIZE(max_physical_block)
IRLRECL(logical_record_length)
IRRECFM(record_format)
Explicitly set the DCB or format attributes to be used to allocate the internal reader data set when SITE SUBMIT has been entered and a data transfer is performed.
ISPFENQ | NOISPFENQ
Specifies that the ISPF enqueue facility be activated (ISPFENQ) or deactivated (NOISPFENQ).
Default: NOISPFENQ
ISPFRES | NOISPFRES
Enables (ISPFRES) or disables (NOISPFRES) the RESERVE logic for the SPFEDIT ENQ, if the volume on which the PDS resides is shared by Multiple Systems (UCB shared bit ON).This assures data integrity while the PDS you are accessing is being simultaneously accessed by an ISPF user from another system.
Default: NOISPFRES
JESLRECL(record_length)
Alias for IRLRECL.
JESRECFM(record_format)
Alias for IRRECFM.
LABEL
Specifies label type.
Label options supported are: SL, NL, BLP, LTM, AL. See LABEL parameter description in the description of the GAT statement in the Cisco IOS for S/390 Customization Guide.
LKEDRES | NOLKEDRES
Enables (LKEDRES) or disables (NOLKEDRES) the RESERVE logic for the SYSIEWLP ENQ, if the volume on which the PDS resides is shared by Multiple Systems (UCB shared bit ON). This assures data integrity while the PDS you are accessing is being simultaneously accessed by the linkage editor from another system.
Default: NOLKEDRES
LINE(logical_record_length)
See BLKSIZE.
LISTFMT(OLD | IBM | SHORT)
Specifies whether output from the data set LIST command will be in the old Cisco IOS for S/390 format, in IBM-standard format, or in a shortened IBM-compatible format. The short format leaves out data set extents and tracks allocated, but improves LIST response time.
Default: SHORT
Note Certain PC-based client FTP packages expect the LIST output from a host configured as OS/MVS to be in standard IBM format.
The LIST parameter is not reset when data transfer begins.LOADLIB | CARDS | SOURCE| FORTRAN | OBJECT | PRINT
See the description for CARDS.
LRECL(logical_record_length)
See BLKSIZE.
MANAGEMENTCLASS (management_class_name)
Specifies the SMS management class.
MGMTCLASS(sms_management_class)
Alias for MANAGEMENTCLASS.
MIGRATEVOL(migration_volume_serial)
The volume serial number of migrated data sets.
MOUNT(time)
Enables tape support ability for this file transfer. The time value specifies the maximum wait time in minutes for the tape mount to complete. If the time expires, the request is aborted. MOUNT without a time value specified will use the default system wait time.
NCP(number_of_DASD_buffers)
Alias of NDAB.
NDAB(number1 number2)
Specifies the number of DASD buffers used by FTP for reading or writing disk data sets. The maximum value is 99.
Default: 4
Note Your Cisco IOS for S/390 administrator might have set restrictions on the use of the NDAB parameter.
NLSTCASE(UPPER | LOWER)
Specifies whether the output from an NLST command will be upper- or lowercase. If LOWER is specified and the data set or member list is part of the current directory, the names will be returned in lowercase.
Note NLSTCASE(LOWER) is supplied to facilitate MGET functions from FTP clients on systems that use lowercase file names.
Note This parameter is not reset when data transfer begins.OBJECT | LOADLIB | CARDS | SOURCE| FORTRAN | PRINT
See the description for CARDS.
OBUF(numbuf bufsize)
Specifies, in sublist notation, the number of network input buffers (numbuf) and the buffer size (bufsize) to be used during data transfer. The maximum value for each number is 32767.
Note Your Cisco IOS for S/390 system administrator might have set restrictions on use of the OBUF parameter.
OVERWRITE | NOOVERWRITE
This parameter is a toggle. OVERWRITE requests that the FTP server overwrite an existing data set when transferring files if a data set of the same name already exists on the target server. This parameter is necessary when the SITEOVERWRITE configuration parameter is in effect.
Note This parameter is reset after each transfer, regardless of the PERSIST option in effect.
PAD (pad_code)
Overrides the default characters that pad network records or lines to fixed-length logical records when data is stored (via STOR or APPE) or deleted from fixed-length logical records when data is retrieved (via RETR). The defaults are blanks for character types and zeros for binary types. These are the pad-codes:
Z - Pad with zeros
O - Pad with ones
B - Pad with blanks
PARALLELMOUNT
Specifies parallel mounting (mutually exclusive with UCNT).
PDSE | NOPDSE
Allocates PDSEs instead of PDSs, or vice versa.
PERSIST | NOPERSIST
Specifies whether SITE parameters will be reset following data transfer. If PERSIST is used, all SITE parameters remain in effect until explicitly changed via subsequent SITE commands, or reset with SITE RESET. If NOPERSIST is used, all SITE parameters are reset after each data transfer.
Default: NOPERSIST
PRIMARY(primary_allocation)
Specifies the primary space allocation for data sets.
PRINT | LOADLIB | CARDS | SOURCE| FORTRAN
See the description for CARDS.
PRIVATE
Requests a private volume.
PUSH | POP
PUSH causes the server FTP to save the current settings of parameters entered with previous SITE commands; POP restores those parameters.
Note PUSH and POP can be nested. Each PUSH adds an entry to a push-down stack. Each POP pulls the last entry from the stack. When there are no entries in the stack, a POP will result in an error reply.
QDISK(volume_serial_mask)
Requests the FTP server to provide volume information for the volume(s) specified in the volume_serial_mask.
Example
ftp> quote site q=ics001200- % Free Free Largest Free200- Volume Unit Free Cyls Trks Cyls-Trks Exts Address Use Attr200- ICS001 3390 1 23 102 15 14 23 420 Storage200 Site command was acceptedRDW | NORDW
Specifies whether RDWs (Record Descriptor Words) will be sent as data for RECFM=VB and RECFM=VBS files. If RDW is selected, the RDW will be sent for binary, ASCII, or EBCDIC transfers.
Default: NORDW
Note RDW will not be translated for ASCII file transfers. This parameter is ignored for data sets with carriage control (RECFM=VBA or RECFM=VBM).
RECALL(integer) | NORECALL
RECALL—Enables Hierarchical Storage Manager (HSM) recall ability for this file transfer. The integer value specifies the maximum wait time in minutes for HSM to complete the recall of the migrated file. If the time expires, the request is aborted. RECALL without an integer value specified enables HSM with the default system wait time.
NORECALL—Disables HSM recall ability for this file transfer.
RECFM(record_format)
See BLKSIZE.
RESET
Resets all previous SITE commands. Can be used if SITE PERSIST is specified.
RESTART (integer)
When a file is RETRieved in block mode, the FTP Server includes a Restart Marker in the data stream every integer data bytes. To suppress these markers entirely, specify RESTART(0). The default is RESTART(500,000). Read REST for information about Restart processing.
This command is not supported for the FTP to Tape Facility.
RETPD | EXPDT
See the description for EXPDT.
RLSE | NORLSE
RLSE—Cancels a previous SITE NORLSE. This is needed occasionally to prevent building up too many extents when many APPE operations to the same data set are performed.
NORLSE—Specifies that unused disk space not be released following a STOR or APPE.
Default = RLSE
SECONDARY(secondary_allocation)
Specifies the secondary space allocation for data sets.
SOURCE | CARDS | FORTRAN | OBJECT | LOADLIB | PRINT
See the description for CARDS.
SPACE(primary_allocation, secondary_allocation)
Specifies primary and secondary disk space allocation (the default allocation is in tracks). Only required for STOR or APPE commands.
STCLASS(sms_storage_class_name)
Alias for STORCLASS.
STORCLAS(storage_class_name)
Specifies the SMS storage class.
STRIP | NOSTRIP
Specifies whether pad characters will be stripped from fixed-length logical records when data is retrieved (using RETR).
SUBMIT | NOSUBMIT
SUBMIT—Specifies the MVS FTP Server to send the output of a file transfer to a JES internal reader for execution.
NOSUBMIT—Cancels a previous SITE SUBMIT.
TABS (integer)
Specifies the tab stop interval to be used in receiving the next file. The default is 8, and the limit is 25. TABS(0) translates tab characters (for example, ASCII x'09' is translated to EBCDIC x'05'); TABS(1) replaces each tab character with a blank.
TAPE
Specifies that attributes are to be taken from the GAT TYPE(TAPE) entry.
TERSE
Requests the FTP server to issue single-line 150 and 226 replies.
TRACKS
Requests space allocation in tracks.
TRANOPT(char_translation_mode)
Defines the character translation mode. These are the choices:
CHAR—Defines character translation mode as single-byte.
DBCS—Defines character translation mode as double-byte.
MIX—Defines character translation mode as single-byte and/or double-byte.
UCNT(unit_count)
Specifies the maximum number of generic units an output data set can require. A value of 1 to 59 can be entered.
UNIT(unit_name)
Specifies a generic unit for creating a new data set.
VBS | VS | FULLTRK | HALFTRK
See the description for FULLTRK.
VCNT(volume_count)
Specifies the maximum number of volumes an output data set can require. A value of 1 to 255 can be entered.
VERBOSE
Requests the FTP server to issue multi-line 150 and 226 replies, showing data set attributes and transfer statistics.
VOLUME(volume_name, volume_name, ...)
Specifies an explicit volume(s) for creating a new data set or referencing an old uncataloged data set. Normally not required. A total of 255 can be entered. If VOLUME is entered with no volume_name, all VOLUME information is reset.
VS | VBS | FULLTRK | HALFTRK
See the description for FULLTRK.
VSEQ(volume_sequence_number)
Specifies that processing should begin at a requested volume within a multi-volume data set. A value of 1 to 255 can be entered.
WRAPRECORD | NOWRAPRECORD
Network records which exceed LRECL will be wrapped to the next record when receiving data.
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:
SITE ATTR=gat_name
The following example illustrates the PL/I format:
SITE ATtr (gat_name)
The following example illustrates the obligatory use of parentheses when the command is entered in BAL format:
SITE VOLUME=(vol1, vol2, vol3)
STAT
The STAT command provides partial or complete status of the Server FTP.
STAT
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
STAT ?
STAT ? selector
STAT ? item_numbers
STAT path_name
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
The Server FTP rules for naming and accessing data sets described here are the same as those for TSO.
User disk data sets generally have names of the form:
defprfx.name1[.name2[.name3 .. [.namen]]]Syntax Description
Note
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:
•
•
•
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 > pwd257 "'MYID.'" is current prefix.ftp > cd level1250 "'MYID.LEVEL1.'" is current prefix.ftp > cdup200 "'MYID.'" is current prefitftp > cd level2250 "'MYID.LEVEL2.'" is current prefix.ftp > cd 'newid'250 "'NEWID.'" is current prefix.ftp > quote cwd 'nextid'250 "'NEXTID.'" is current prefix.ftp > quote cdup200 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:
•
•
•
•
•
•
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 VTOC and Catalog.
Note
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:
•
•
Note
Example
ftp> ls v*.obj200 OK, Ready125 Transfer startedV111.OBJV20.OBJV201.OBJ226 Transfer completeftp> ls v2%.obj200 OK, Ready125 Transfer startedV20.OBJ226 Transfer completeftp> cd v20.obj250 "'MVS.V20.OBJ'" partitioned data set is current directoryftp> ls ftps*200 OK, Ready125 Transfer startedFTPSFTPSFTDR226 Transfer completeftp> ls v*.obj(*)200 OK, Ready501 Wildcard characters are not permitted within a Partitioned dataset namePartitioned 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> pwd257 "'MVS.'" is the current prefixftp> cd help.pds250 "'MVS.HELP.PDS'" partitioned data set is current directoryftp> dir200 OK, Ready125 Transfer startedName VV.MM Created Changed Size Init Mod IdFTPDEFAU 04.00 12/08/93 12/09/93 6:16 98 98 0 MVSFTPINTRO 01.00 12/09/93 12/09/93 6:18 134 134 0 MVSFTPNEWS 01:00 12/09/93 12/09/93 10:30 25 25 0 MVSGREETING 01:00 12/08/93 12/09/93 6:19 12 12 0 MVS226 Transfer completeftp> get ftpnews200 OK, Ready150-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 80Blksize 3120 Rlse150226 Transfer completeIn 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, Ready125 Transfer started'MVS.HELP.PDS(FTPDEFAU)''MVS.HELP.PDS(FTPINTRO)''MVS.HELP.PDS(FTPNEWS)'226 Transfer completeIf 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 prefixVTOC 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 has a central file directory, called the catalog, that provides the volume name as a function of the dsname. TSO generally requires that all user data sets except scratch files be cataloged (in other words, listed in a system catalog). A cataloged data set name is unique on the system while an uncataloged data set name need be unique only on the disk volume where it resides. You need to give only the dsname (and member_name for a PDS), not the volume, to locate an existing cataloged data set.
This Server FTP generally does not change the catalog status of a data set operated on by a STOR, APPE, RETR, or rename operation. A data set created by an FTP STOR, APPE, or RNTO operation is cataloged. If the dsname conflicts with an existing cataloged data set, the operation is refused in the case of RNTO.
When the Server FTP performs an APPE or RETR operation on an existing uncataloged data set (using SITE VOLUME), it tries to catalog it. If the attempt fails because another data set with the same name is being cataloged or because the dsname has the wrong tree structure, a warning message is sent but the operation proceeds.
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.
Space allocation may have two parameters to the operating system: a primary space quantity, and a secondary space quantity. When an FTP STOR operation is requested, FTP first tries to allocate the primary quantity. If it succeeds, data transfer starts. Each time that space is exhausted during the STOR (or APPE) operation, FTP tries to allocate the secondary quantity. The STOR (or APPE) fails at that point if it cannot satisfy the request. Each allocation, whether primary or secondary, takes place as follows:
•
•
This allocation process continues until the total space or the extent limit is exhausted.
The default space parameters for FTP STOR are (primary, secondary) = (5,3) tracks. The maximum space that can be allocated with these parameters depends on the degree of fragmentation of the volume (assuming that enough total space exists). It ranges from 50 tracks down to 14 tracks (if the largest contiguous area is only 1 track and extents are exhausted first).
These methods obtain more space or a larger file:
•
The parameter to ALLO is a file size in (network) bytes. The Server FTP converts that value to disk tracks and uses 1.2 times that value as the initial space allocation. Therefore, if the data transfer starts, you know the initial space allocation was successful and you cannot run out of space specified by the ALLO. The 1.2 factor is intended to take care of inter-record gaps. The secondary space quantity is 0.2 times the ALLO value.
•
The disk space allocation (ALLO) is in terms of the data stored on disk, including padding. A text file normally is padded to 80 byte records, so each line is 80 bytes on disk. The primary and secondary space quantities are recorded in the data set label (DSCB) by the operating system. A subsequent APPE uses the secondary quantity determined when the data set was created unless you override it with a new ALLO or SITE SPACE before the APPE.
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.
FTP will use the greatest of the following numbers to determine how many devices and volumes to allocate to a data set:
•
•
•
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 ; the first column shows the SITE command keyword parameter(s) to set the corresponding DCB attribute:
Table 5-6 Disk Format Attributes
RECFM
Record Format (RECFM)
LRECL or LINE
Logical Record Length (LRECL)
BLKSIZE or BLOCK
Physical Block Length (BLKSIZE)
When an existing data set is retrieved, the Server FTP determines the attributes from MVS and uses them to read the disk data set correctly. However, when writing to a data set, either through a STOR or APPE operation, you may need to be concerned about setting the correct attributes. Whether Server FTP assigns attributes for an existing data set depends on whether the data set is partitioned (PDS) or sequential.
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 setAn APPE of a new PDS member is identical to a STOR. However, you cannot APPE into an existing member because the file system replaces the member. If you attempt to APPE into an existing member name, Server FTP responds with this message:
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 Default Data Set Attributes
Note
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
Generic Attribute Names
Note
These generic types create PDS libraries suitable for object modules and load modules.
Each generic attribute name includes values for RECFM, LRECL, and BLKSIZE, and optionally, UNIT, VOLUME, or SPACE, but the attributes set by a generic attribute name can be overridden by other generic or specific attribute keywords. When overriding SITE command keywords, the keywords are interpreted in left-to-right order.
In addition, other generic attribute names can be defined by your site. These names can stand for other combinations of RECFM, LRECL, BLKSIZE, UNIT, VOLUME, and SPACE. User-defined names must specify RECFM, LRECL, and BLKSIZE. They can optionally specify UNIT, VOLUME, or SPACE parameters.
The generic types SOURCE, CARDS, FORTRAN, OBJECT, LOADLIB, and PRINT can also carry UNIT, VOLUME, and SPACE parameters as defined by your site. They can be referenced by the SITE keywords SOURCE, CARDS, FORTRAN, OBJECT, LOADLIB, and PRINT. Other generic types may also have been defined by your site. They can be referenced by the SITE keyword ATTR (type).
In the preceding table, the block size is sometimes specified as rcmd, meaning a recommended value. This means the Server FTP chooses an actual default BLKSIZE that is optimum for the particular device on which the data set is allocated and less than or equal to a recommended size. The recommended size is a site-specific FTP parameter. If your site has not changed this parameter, the recommended size is 6K (6144) bytes. The choice of optimum BLKSIZE <=rcmd depends on RECFM, LRECL, and the disk device type.
Rules for Record Formats
These rules govern Server FTP support of the record format (RECFM) data set (DCB) attribute:
•
Table 5-9 Record Formats
U, F, V, VS
Unblocked
FB, FBS, VB, VBS
Blocked, nonprint format
FBA, FBSA, VBA
Blocked, print format
•
•
FA, FSA, VA, VSA, UA•
Violation of any of these rules results in a 554 illegal recfm error reply.
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•
•
•
In addition, for unblocked RECFMs the LRECL is forced to do the following:
•
•
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:
•
•
•
•
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.
Server FTP does a minimum of validity checking for internal reader file attributes. Be sure that the attributes selected are compatible with each other and are appropriate for the local Job Entry Subsystem.
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
lists options invoked by the PUT, APPE, and GET commands that initiate data transfer:
Table 5-10
STOR
saves a file on an MVS system
APPE
appends to a file stored on an MVS system
RETR
retrieves a file from an MVS system
Transfer Options
A 226-Transfer complete reply is sent only when the disk file being written has been closed successfully or when the data being retrieved and sent across your network has been fully acknowledged.
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.
Create or retrieve a raveled file with the FTP parameters STRU F and one of these:
•
•
When a raveled file is stored by the Server FTP, it is folded into maximum-sized logical records.
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:
•
•
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.
If ALLO R is specified, each network record that exceeds ALLO R is truncated.
With STRU R, a storage operation (in other words, STOR or APPE) that creates a print file (TYPE AT, TYPE AC, TYPE ET, or TYPE EC) requires the data set to be blocked. If the data set is not blocked, the operation fails with the reply
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.
A vertical tab (VT) character is always treated as data and stored in the file.
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.
Some obscure cases cannot be handled correctly in this way. In fact, to fully define the correspondence, you must compare the effects of the files on assumed printing mechanisms to achieve the same appearance. This requires that FTP define additional attributes (such as the size of a page and the effect of an overstrike).
The rules assume that at the beginning of a file, the ASA line printer is positioned on the first line. Therefore, the default carriage control character used to create the first line of an ASA print file is + (suppress space), with following lines normally using a blank (single space) before printing.
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
text...eol
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):
•
•
•
•
•
•
•
•
Retrieving Line Image Files
These rules apply to line image files being retrieved (via RETR):
•
•
•
•
Table 5-11 Retrieving Line Image Files Using Carriage Control Characters
blank
eol text
0
eol eol text
-
eol eol eol text
1
CR FF text
+ (first record)
text
+ (other)
CR text
A single logical record can result in a series of network lines, and a + CCC in the first record of the file is effectively ignored.
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):
•
•
•
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:
fe text
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:
cc text...eol
Syntax Description
cc
An ASA Carriage Control Character.
ext
A (possibly null) block of text.
eol
An end-of-line sequence (CR, LF, or NL).
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).
•
•
•
•
•
•
•
•
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):
•
•
•
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.
fe text...eor
Syntax Description
fe
A (possibly null) sequence of ASCII format effectors.
text
A (possibly null) block of text.
eor
An end-of-record sequence.
Storing Logical Records
These rules apply to files being stored (using STOR or APPE) with these parameters:
•
•
•
•
•
•
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:
•
•
•
•
Table 5-12
blank
text eor
0
eor text eor
-
eor eor text eor
1
F' text eor
+ (first)
R' text eor
+ (other)
text eor
Retrieving Logical Records Using Carriage Control Characters
Note
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.
cc text...eor
Syntax Description
Storing Print Files
These rules apply to files being stored (via STOR or APPE) with these parameters:
•
•
•
•
•
•
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:
•
•
•
•
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:
•
•
•
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:
•
•
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:
•
•
•
•
•
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:
•
•
•
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:
•
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.
•
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.
Feedback