FTP SCRIPT IBM (CMS) as an FTP 'P' end This file is available as a HELP file (named FTP) and as a script file. FTP is used to transfer files to and from other computers accessible via the SERC network; it should work with sites that support either the FTP77 or FTP80 versions of the protocol. The latter is now the default. This HELP file relates to the P-end user interface, and concentrates on defining and explaining the terminology. This is presented as a glossary in alphabetical order. For further information about specific prompts in the user dialogue, there is a separate small HELP file associated with each prompt. This can be obtained by typing HELP when the prompt appears. There is a separate HELP file covering the IBM (CMS) Q-end implementation. To obtain this, the user should type 'HELP FTPQ'. Command Format +-------------+--------------------------------------------+ | | | | FTP | [ | | | | +-------------+--------------------------------------------+ The possible values taken by are :- ? or Help - Obtain a preliminary general HELP file Monitor - Request display of the monitor record of recent transfers Cancel - Cancel the 'held' transfer whose spoolid is - Begin dialogue with user to obtain details for a transfer --------------------------------------------------------------- GLOSSARY:- Abort Transfer initiation can be abandoned at any stage in the dialogue by inputting 'QUIT'. A transfer which has been initiated by the user CMS P-END FTP (APRIL 1983) PAGE 1 FTP SCRIPT but has had to be 'held' for re-tries by the NIFTP virtual machine may be cancelled by the user if desired. See 'Cancel', 'Held', and 'Failed'. Account See 'Remote account'. Append If you want to send a file to a remote computer and the file specified on the remote computer already exists then the append option causes the new data to be appended to the existing data in the file. To append data, include 'APPEND' among the options. APPEND may be combined with MAKE. ASCII If the user wishes to specify the permissible transfer code or codes explicitly, ASCII is one of the possible codes that may be specified. Normally the user can leave the choice of transfer code to the software. See 'Transfer codes'. Banner heading If the user is sending a file to a remote device, a prompt for the banner heading will appear. If the user inputs anything except , it will be passed to the remote FTP in the FTP filename parameter for possible use in constructing a banner heading. BINARY If the user wishes to specify the permissible transfer code or codes explicitly, BINARY is one of the possible codes that may be specified. Normally the user can leave the choice of codes to the software. 'BINARY' in this context means that the file is to be transferred exactly as it stands with no character conversions at all. This is not normally appropriate, as the codes used in the remote machine are unlikely to be identical. Cancel A transfer which has been initiated by the user, but has had to be 'held' for retries due to communications problems, may be cancelled by the user if desired. To do this, input the command 'FTP' to CMS with parameters 'Cancel' and . The spoolid of the 'held' transfer is notified to the user in the mail file sent at the time of the original attempt. Example of a command to cancel file 1234: FTP CAN 1234. Codes See 'Transfer codes'. Communications CMS P-END FTP (APRIL 1983) PAGE 2 FTP SCRIPT If your transfer fails to start or cannot be completed because of a communications problem it will be retried automatically at intervals for up to 3 days. The retry strategy is 3 times at 2-minute intervals, repeated every 20 minutes. The user may cancel a 'held' transfer. See 'Held' and 'Cancel'. Computer See 'Remote computer'. Defaults Most parameters that the user can supply have default values. These are always displayed with the associated prompt. Some defaults are determined by the values that have been entered so far. Device See 'Remote device'. Device qualifier If a remote device is involved, this prompt will appear. If the user inputs anything except , it will be passed in the FTP 'device qualifier' parameter (FTP80 only) and may be of use to the remote system, for instance in connection with 'special forms'. EBCDIC If the user wishes to specify the permissible transfer code or codes explicitly, EBCDIC is one of the possible codes that may be specified. Normally the user can leave the choice of transfer code to the software. See 'Transfer codes'. Failed If a transfer cannot begin or cannot be completed for a reason other than a temporary communications problem, it is said to have 'failed'. A mail file containing further information is sent to the user, and also a message if the user is logged on. See also 'Held'. Fetch If you wish to fetch a file from the remote computer include 'FETCH' in the options. *FILE card See 'Job output' Filemode If you are sending a file from CMS the mode of the local file may be specified in the usual way. If you are fetching a file to CMS from a remote computer then the mode of the local file, if specified during the user dialogue, has no effect. The received file will be spooled to your reader and should be loaded using RECEIVE or 'DISK LOAD' ( always to your A CMS P-END FTP (APRIL 1983) PAGE 3 FTP SCRIPT mini-disk) or using 'YDISK LOAD' if you wish to load with a file id of your own choosing. Filename See 'Local file' and 'Remote file'. Filetype The filetype of the local CMS file normally has no special effect unless it is 'LISTING', in which case it is assumed that the first character of each record is a printer control character. Care should be taken when transferring files of type TEXT to ensure that any character translations involved are 'transparent'. It may be appropriate to specify 'BINARY' as the transfer code in such cases. Files whose LRECL exceeds 252 cannot be transferred. FTP77 FTP77 may be specified as an option if the remote end can only support this version of the protocol. FTP80 FTP80 is the default version. Give This is NIFTP jargon for Fetch but is not recognised as an option. Held If a transfer cannot begin or cannot be completed because of a temporary communications problem, it will be 'held' and retried at intervals. A mail file containing details, including the file's spoolid, is sent to the user at the time of the first attempt, and also a message if the user is logged on. Another mail file, and message if appropriate, is sent when the file is finally transferred or purged. See also 'Communications', 'Failed', and 'Cancel'. Internal problem If you see this message in the mail file describing a failed transfer then retry the transfer with level 2 logging and send the log to User Support for investigation. Job input A file can be sent to a remote batch system as a job for execution. If this is required, give a non-null response to the 'remote file' prompt and specify options that include SEND JOB INPUT. A file can also be fetched from a remote system and input as a job to the RAL batch system, or to any system accessible via VNET. This requires options that include FETCH JOB INPUT, CMS P-END FTP (APRIL 1983) PAGE 4 FTP SCRIPT and Local file must be appropriately specified. See 'Local file'. Job output The P-end user can manually send job output (i.e: printing) to a remote device by inputting a null response to the 'remote file' prompt. The user will then be asked to identify a remote device and device qualifier. The default is device LP and null qualifier. The user is also prompted for a 'Banner heading' (see 'Banner heading'). Ensure that the options include SEND JOB OUTPUT. The P-end user can fetch a file from a remote system and send it as printed output directly to an RAL printer, or to any destination accessible via VNET. This requires options that include FETCH JOB OUTPUT, and the Local file parameter must be appropriately specified. See 'Local file'. The P-end implementation can also automatically retrieve job output from the batch virtual machine and send it to any network destination. If this is required, the job must either have been submitted via the IBM (CMS) Q-end FTP, or it must have a Route card containing /*ROUTE PRINT NIFTP in the JCL. It must also contain one or more //* cards containing *FILE followed by FTP parameters. Further details are given in the FTPQ help file, as it is expected that most users will be submitting the jobs by that route and must set them up correctly at that stage. Listing (1) See 'Filetype' (2) See 'Printing' Local file This user dialogue prompt should normally be responded to with a CMS file identifier. For transfers from CMS the specified file is sent. For transfers to CMS, when the data is received it is spooled to your reader. On loading to your A mini-disk using RECEIVE or 'DISK LOAD', a file of the specified name is created. [Ignore any filemode reported by the 'DISK LOAD' command.] Take care that you have no existing file of the same name that you wish to keep, as this would be overwritten. The file may be loaded using 'YDISK LOAD' if you wish it to have a file id of your own choosing. If LP is input in response to the 'local file' prompt, the file will be directed to the RAL VM CMS P-END FTP (APRIL 1983) PAGE 5 FTP SCRIPT printer. If FEM is input, it will be directed to the RAL batch system as a job. If VNET/node/tag is specified, it will be directed to the VNET 'node' indicated. The 'tag' should be given as JOB if the file is to be treated as job input. Otherwise it can be omitted if not needed by VNET. If LP, FEM, or VNET/node... is specified, the options must include FETCH JOB OUTPUT or FETCH JOB INPUT. Logging The transfer process keeps a log of events that occur in the course of a transfer. This log is spooled to the user's reader on completion (whether succesful or otherwise). There are 3 levels of logging available to the user. A particular level of logging may be specified by including LOGn among the options. n should be in the range 0 to 2. The default is 0 which gives minimum logging, but this is normally adequate. It is useful to produce LOG2 evidence before consulting User Support about a problem. Mail On completion of a transfer, a file whose filetype is MAIL is spooled to your reader. These mail files can be read by issuing the command XRDR when they are at the front of your reader queue. FTP does not use the RMAIL system. The mail file contains the transfer log. Unsuccessful retries of 'held' transfers do not produce mail files. Make If you wish the data transferred from CMS to be stored in a new file on the remote computer include 'MAKE' among the options. 'MAKE' may be specified in combination with 'APPEND' or in combination with 'REPLACE' to specify the disposition of any existing file on the remote computer with the same name as the specified remote file. Messages If you are logged on when a transfer you have set up completes you will receive a message informing you of the completion of the transfer (whether successful or otherwise). Unsuccessful retries of 'held' transfers are not reported. Monitor The FTP command can be issued with the single argument 'Monitor' to determine whether the NIFTP virtual machine is active and display a list of the most recent transfers. This will not show any transfers that have yet to be CMS P-END FTP (APRIL 1983) PAGE 6 FTP SCRIPT attempted. If the FTP process is currently running and there is a free 'process' to handle it, your transfer will be processed as soon as the necessary information has been spooled to the FTP machine. If the latter is already handling the maximum number of transfers, there will be a delay. Network The network address of the remote computer should be supplied in site mnemonic form in response to the user process prompt 'remote computer'. The CMS FTP implementation makes network calls via VMNCP, which converts the site address mnemonic to an explicit network address. See 'Remote computer'. NOPFCC 'No paper-feed control'. See 'Printer control'. Null A 'null' response from the user means a line with no contents at all: e.g: input by just hitting the RETURN key. A null field is often indicated by . For instance the 'FTP' command with parameters is input simply by typing 'FTP' alone. Options When you see this user process prompt, first examine the quoted defaults: it is quite possible you will not need to supply any further options. The options available are in 6 groups :- (1) transfer direction (SEND,FETCH) (2) type of transfer (MAKE, APPEND, REPLACE, REMOVE, READ, JOB OUTPUT, JOB INPUT) (3) printer control (PFCC, NOPFCC) (4) transfer code (ASCII, EBCDIC, BINARY) (5) logging (LOG0 - LOG2) (6) protocol (FTP77,FTP80). Params faulty If you see this message at the end of a mail file reporting a failed transfer you may have made a typing error in setting up the transfer. Retry. If the problem persists retry with level 2 logging and take the log to User Support for advice. Parmfile The FTP user process operates by constructing a file of parameters specifying the requested transfer. This file of parameters is known as a 'parmfile'. After it has been constructed it is spooled to the reader of the FTP virtual machine (together with the file itself in the case of a transfer in the outwards direction). PFCC 'Paper-feed control'. See 'Printer control'. Printer control CMS P-END FTP (APRIL 1983) PAGE 7 FTP SCRIPT Under some circumstances the first character of a record of data is assumed to be a paper feed (printer control) character in accordance with ANSI Fortran conventions. If you are sending a file to a remote computer the presence of such characters is assumed if the filetype is 'LISTING'. If the filetype is not 'LISTING' and paper feed control characters are present you should specify 'PFCC' among the options. IF the filetype is 'LISTING' and paper feed control characters are not present you should specify 'NOPFCC' among the options. When fetching a remote file onto the line printer or into a CMS file of filetype LISTING, printer control characters should be present in the file. In this case the transfer will be rejected unless PFCC is used and the remote end accepts this during the FTP negotiation. Printing If you wish to print a file on a remote computer's printer you should give a null response when the user dialogue prompts for 'remote file'. You will then be prompted for 'remote device', 'device qualifier', and 'banner heading' (q.v.). The correct options will be set automatically. If you wish to print a file from the remote computer on the RAL VM printer you should respond 'LP' when the user dialogue prompts for 'local file'. (See also printer control). Printing may also be fetched to a VNET node (see 'Local file'). QUIT The user can type 'QUIT' at any time during the dialogue in order to abandon the initiation. Read If you are Fetching a file from the 'Q' end, the READ option implies read-only access at the 'Q' end (i.e: the remote file is not altered in any way in situ). If the file is a job, then JOB INPUT or JOB OUTPUT is used instead. Rejected If you see this message in the mail file describing a failed transfer then, if the cause of failure cannot be deduced from the log, retry with level 2 logging and take the log to User Support for advice. Remote account If the remote computer needs account identification it should be supplied in response to the user dialogue prompt 'remote account'. If not needed, a null response may be input. Remote computer CMS P-END FTP (APRIL 1983) PAGE 8 FTP SCRIPT This user dialogue prompt should be responded to with the site mnemonic appropriate to the remote computer. There is no default. The mnemonic is passed to the local Network Control Program (VMNCP) which converts it to an explicit network address. If VMNCP does not yet have a particular mnemonic in its table, an explicit address (if known) may be supplied directly by the user in response to 'Remote computer'. In this case, however, User Support should be asked to arrange for the new mnemonic to be inserted as soon as possible. Remote device You will only see this user dialogue prompt if you have given a null response to the 'remote file' prompt. The response is used to identify the remote device to be used. The default is the remote computer's printer (LP). Remote file This user dialogue prompt should be responded to with a file or job identification acceptable to the remote computer. A null response should be given if you want to send output to one of the remote computer's peripherals. This parameter is passed in the FTP 'filename' parameter. Remote password You will not see this user dialogue prompt if you have given a null response to the 'remote user' prompt. The response should be acceptable to the remote computer, and is passed in the FTP 'user password' parameter. Remote user This user dialogue prompt should be responded to with user identification for the remote system. It is passed in the FTP 'username' parameter. If not needed by the remote system, a null response may be input. Replace If you wish the data transferred from CMS to replace an existing file on the remote computer, include 'REPLACE' among the options. The option 'REPLACE' may be combined with the option 'MAKE'. Retry strategy See 'Communications'. Route card See 'Job output'. Send If you wish to send a file from CMS to a remote computer include 'SEND' among the options. The file will not be removed from your mini-disk (see spool) but you may then erase it if you so wish. CMS P-END FTP (APRIL 1983) PAGE 9 FTP SCRIPT Site See 'Remote computer'. Spool The user process and the NIFTP virtual machine communicate via reader and punch spool files. If you are transferring files from CMS a copy of your data file is spooled to NIFTP. If you are transferring into CMS the received file is spooled to your reader in DISK DUMP/LOAD format. A 'parmfile' specifying the transfer in detail is always spooled to the NIFTP virtual machine after completion of the user dialogue, on its own in the case of an incoming transfer or attached to the user's file in the case of an outgoing transfer. Take This is NIFTP jargon for send but is not recognised as an option. Transfer codes It is necessary to distinguish between the code in which a file is stored on a particular machine, and the code to which it may be converted for transfer purposes. The user can normally leave the choice of transfer code to the FTP software. It will use 'Blue Book' EBCDIC if this is acceptable to the remote machine; otherwise it will use ASCII (IA5). Thus the default is EBCDIC or ASCII with the former preferred where possible. Files in CMS are assumed to be stored in RAL EBCDIC (which differs very slightly from 'Blue Book' EBCDIC). If the file does not contain ordinary character data and the user wishes to ensure transparent transmission with no intervening code conversions, the BINARY option may be specified. BINARY should be chosen only if essential, however, as many remote systems do not support it. Transmission limit A limit may be imposed on the size of incoming files. This is currently 8 megabytes, including FTP protocol overheads. CMS P-END FTP (APRIL 1983) PAGE 10